(** JMAP Core Protocol Library Interface (RFC 8620)
    
    This library provides OCaml types and function signatures for interacting
    with a JMAP server according to the core protocol specification in RFC 8620.
    
    Modules:
    - {!Jmap.Types}: Basic data types (Id, Date, etc.).
    - {!Jmap.Error}: Error types (ProblemDetails, MethodError, SetError).
    - {!Jmap.Wire}: Request and Response structures.
    - {!Jmap.Session}: Session object and discovery.
    - {!Jmap.Methods}: Standard method patterns (/get, /set, etc.) and Core/echo.
    - {!Jmap.Binary}: Binary data upload/download types.
    - {!Jmap.Push}: Push notification types (StateChange, PushSubscription).
    
    For email-specific extensions (RFC 8621), see the Jmap_email library.
    For Unix-specific implementation, see the Jmap_unix library.
    
    @see <https://www.rfc-editor.org/rfc/rfc8620.html> RFC 8620: Core JMAP
*)

(** {1 Core JMAP Types and Modules} *)

module Types = Jmap_types
module Error = Jmap_error
module Wire = Jmap_wire
module Session = Jmap_session
module Methods = Jmap_methods
module Binary = Jmap_binary
module Push = Jmap_push

(** {1 Example Usage} 

    The following example demonstrates using the Core JMAP library with the Unix implementation
    to make a simple echo request.

{[ 
  (* OCaml 5.1 required for Lwt let operators *) 
  open Lwt.Syntax 
  open Jmap 
  open Jmap.Types 
  open Jmap.Wire 
  open Jmap.Methods
  open Jmap.Unix
  
  let simple_echo_request ctx session = 
    (* Prepare an echo invocation *) 
    let echo_args = Yojson.Safe.to_basic (`Assoc [
      ("hello", `String "world");
      ("array", `List [`Int 1; `Int 2; `Int 3]);
    ]) in
    
    let echo_invocation = Invocation.v 
      ~method_name:"Core/echo"
      ~arguments:echo_args
      ~method_call_id:"echo1"
      ()
    in

    (* Prepare the JMAP request *) 
    let request = Request.v
      ~using:[capability_core]
      ~method_calls:[echo_invocation]
      ()
    in

    (* Send the request *) 
    let* response = Jmap.Unix.request ctx request in

    (* Process the response *) 
    match Wire.find_method_response response "echo1" with
    | Some (method_name, args, _) when method_name = "Core/echo" ->
        (* Echo response should contain the same arguments we sent *)
        let hello_value = match Yojson.Safe.Util.member "hello" args with
          | `String s -> s
          | _ -> "not found"
        in
        Printf.printf "Echo response received: hello=%s\n" hello_value;
        Lwt.return_unit
    | _ ->
        Printf.eprintf "Echo response not found or unexpected format\n";
        Lwt.return_unit

  let main () = 
    (* Authentication details are placeholder *) 
    let credentials = "my_auth_token" in 
    let* (ctx, session) = Jmap.Unix.connect ~host:"jmap.example.com" ~credentials in 
    let* () = simple_echo_request ctx session in 
    Jmap.Unix.close ctx 

  (* Lwt_main.run (main ()) *) 
]} 
*)

(** Capability URI for JMAP Core.
    @see <https://www.rfc-editor.org/rfc/rfc8620.html#section-2> RFC 8620, Section 2 *)
val capability_core : string

(** {1 Convenience Functions} *)

(** Check if a session supports a given capability.
    @param session The session object.
    @param capability The capability URI to check.
    @return True if supported, false otherwise.
*)
val supports_capability : Jmap_session.Session.t -> string -> bool

(** Get the primary account ID for a given capability.
    @param session The session object.
    @param capability The capability URI.
    @return The account ID or an error if not found.
*)
val get_primary_account : Jmap_session.Session.t -> string -> (Jmap_types.id, Error.error) result

(** Get the download URL for a blob.
    @param session The session object.
    @param account_id The account ID.
    @param blob_id The blob ID.
    @param ?name Optional filename for the download.
    @param ?content_type Optional content type for the download.
    @return The download URL.
*)
val get_download_url : 
  Jmap_session.Session.t -> 
  account_id:Jmap_types.id -> 
  blob_id:Jmap_types.id -> 
  ?name:string -> 
  ?content_type:string -> 
  unit ->
  Uri.t

(** Get the upload URL for a blob.
    @param session The session object.
    @param account_id The account ID.
    @return The upload URL.
*)
val get_upload_url : Jmap_session.Session.t -> account_id:Jmap_types.id -> Uri.t