(** Unix-specific JMAP client implementation interface.

    This module provides functions to interact with a JMAP server using
    Unix sockets for network communication.
    
    @see <https://www.rfc-editor.org/rfc/rfc8620.html#section-4> RFC 8620, Section 4
*)

(** Configuration options for a JMAP client context *)
type client_config = {
  connect_timeout : float option;        (** Connection timeout in seconds *)
  request_timeout : float option;        (** Request timeout in seconds *)
  max_concurrent_requests : int option;  (** Maximum concurrent requests *)
  max_request_size : int option;         (** Maximum request size in bytes *)
  user_agent : string option;            (** User-Agent header value *)
  authentication_header : string option; (** Custom Authentication header name *)
}

(** Authentication method options *)
type auth_method = 
  | Basic of string * string                  (** Basic auth with username and password *)
  | Bearer of string                          (** Bearer token auth *)
  | Custom of (string * string)               (** Custom header name and value *)
  | Session_cookie of (string * string)       (** Session cookie name and value *)
  | No_auth                                   (** No authentication *)

(** Represents an active JMAP connection context. Opaque type. *)
type context

(** Represents an active EventSource connection. Opaque type. *)
type event_source_connection

(** A request builder for constructing and sending JMAP requests *)
type request_builder

(** Create default configuration options *)
val default_config : unit -> client_config

(** Create a client context with the specified configuration
    @return The context object used for JMAP API calls
*)
val create_client : 
  ?config:client_config -> 
  unit -> 
  context

(** Connect to a JMAP server and retrieve the session.
    This handles discovery (if needed) and authentication.
    @param ctx The client context.
    @param ?session_url Optional direct URL to the Session resource.
    @param ?username Optional username (e.g., email address) for discovery.
    @param ?auth_method Authentication method to use (default Basic).
    @param credentials Authentication credentials.
    @return A result with either (context, session) or an error.
*)
val connect : 
  context ->
  ?session_url:Uri.t ->
  ?username:string ->
  host:string -> 
  ?port:int -> 
  ?auth_method:auth_method ->
  unit -> 
  (context * Jmap.Session.Session.t) Jmap.Error.result

(** Create a request builder for constructing a JMAP request.
    @param ctx The client context.
    @return A request builder object.
*)
val build : context -> request_builder

(** Set the using capabilities for a request.
    @param builder The request builder.
    @param capabilities List of capability URIs to use.
    @return The updated request builder.
*)
val using : request_builder -> string list -> request_builder

(** Add a method call to a request builder.
    @param builder The request builder.
    @param name Method name (e.g., "Email/get").
    @param args Method arguments.
    @param id Method call ID.
    @return The updated request builder.
*)
val add_method_call : 
  request_builder -> 
  string -> 
  Yojson.Safe.t -> 
  string -> 
  request_builder

(** Create a reference to a previous method call result.
    @param result_of Method call ID to reference.
    @param name Path in the response.
    @return A ResultReference to use in another method call.
*)
val create_reference : string -> string -> Jmap.Wire.Result_reference.t

(** Execute a request and return the response.
    @param builder The request builder to execute.
    @return The JMAP response from the server.
*)
val execute : request_builder -> Jmap.Wire.Response.t Jmap.Error.result 

(** Perform a JMAP API request.
    @param ctx The connection context.
    @param request The JMAP request object.
    @return The JMAP response from the server.
*)
val request : context -> Jmap.Wire.Request.t -> Jmap.Wire.Response.t Jmap.Error.result

(** Upload binary data.
    @param ctx The connection context.
    @param account_id The target account ID.
    @param content_type The MIME type of the data.
    @param data_stream A stream providing the binary data chunks.
    @return A result with either an upload response or an error.
*)
val upload : 
  context -> 
  account_id:Jmap.Types.id -> 
  content_type:string -> 
  data_stream:string Seq.t -> 
  Jmap.Binary.Upload_response.t Jmap.Error.result

(** Download binary data.
    @param ctx The connection context.
    @param account_id The account ID.
    @param blob_id The blob ID to download.
    @param ?content_type The desired Content-Type for the download response.
    @param ?name The desired filename for the download response.
    @return A result with either a stream of data chunks or an error.
*)
val download : 
  context -> 
  account_id:Jmap.Types.id -> 
  blob_id:Jmap.Types.id -> 
  ?content_type:string -> 
  ?name:string -> 
  (string Seq.t) Jmap.Error.result

(** Copy blobs between accounts.
    @param ctx The connection context.
    @param from_account_id Source account ID.
    @param account_id Destination account ID.
    @param blob_ids List of blob IDs to copy.
    @return A result with either the copy response or an error.
*)
val copy_blobs :
  context ->
  from_account_id:Jmap.Types.id ->
  account_id:Jmap.Types.id ->
  blob_ids:Jmap.Types.id list ->
  Jmap.Binary.Blob_copy_response.t Jmap.Error.result

(** Connect to the EventSource for push notifications.
    @param ctx The connection context.
    @param ?types List of types to subscribe to (default "*").
    @param ?close_after Request server to close after first state event.
    @param ?ping Request ping interval in seconds (default 0).
    @return A result with either a tuple of connection handle and event stream, or an error.
    @see <https://www.rfc-editor.org/rfc/rfc8620.html#section-7.3> RFC 8620, Section 7.3 *)
val connect_event_source : 
  context -> 
  ?types:string list -> 
  ?close_after:[`State | `No] -> 
  ?ping:Jmap.Types.uint ->
  (event_source_connection * 
   ([`State of Jmap.Push.State_change.t | `Ping of Jmap.Push.Event_source_ping_data.t ] Seq.t)) Jmap.Error.result

(** Create a websocket connection for JMAP over WebSocket.
    @param ctx The connection context.
    @return A result with either a websocket connection or an error.
    @see <https://www.rfc-editor.org/rfc/rfc8887.html> RFC 8887 *)
val connect_websocket :
  context ->
  event_source_connection Jmap.Error.result

(** Send a message over a websocket connection.
    @param conn The websocket connection.
    @param request The JMAP request to send.
    @return A result with either the response or an error.
*)
val websocket_send :
  event_source_connection ->
  Jmap.Wire.Request.t ->
  Jmap.Wire.Response.t Jmap.Error.result

(** Close an EventSource or WebSocket connection.
    @param conn The connection handle.
    @return A result with either unit or an error.
*)
val close_connection : event_source_connection -> unit Jmap.Error.result

(** Close the JMAP connection context. 
    @return A result with either unit or an error.
*)
val close : context -> unit Jmap.Error.result

(** {2 Helper Methods for Common Tasks} *)

(** Helper to get a single object by ID.
    @param ctx The context.
    @param method_name The get method (e.g., "Email/get").
    @param account_id The account ID.
    @param object_id The ID of the object to get.
    @param ?properties Optional list of properties to fetch.
    @return A result with either the object as JSON or an error.
*)
val get_object :
  context ->
  method_name:string ->
  account_id:Jmap.Types.id ->
  object_id:Jmap.Types.id ->
  ?properties:string list ->
  Yojson.Safe.t Jmap.Error.result

(** Helper to set up the connection with minimal options.
    @param host The JMAP server hostname.
    @param username Username for basic auth.
    @param password Password for basic auth.
    @return A result with either (context, session) or an error.
*)
val quick_connect :
  host:string ->
  username:string ->
  password:string ->
  (context * Jmap.Session.Session.t) Jmap.Error.result

(** Perform a Core/echo request to test connectivity.
    @param ctx The JMAP connection context.
    @param ?data Optional data to echo back.
    @return A result with either the response or an error.
*)
val echo : 
  context -> 
  ?data:Yojson.Safe.t -> 
  unit -> 
  Yojson.Safe.t Jmap.Error.result

(** {2 Email Operations} *)

(** High-level email operations that map to JMAP email methods *)
module Email : sig
  open Jmap_email.Types
  
  (** Get an email by ID 
      @param ctx The JMAP client context
      @param account_id The account ID
      @param email_id The email ID to fetch
      @param ?properties Optional list of properties to fetch
      @return The email object or an error
  *)
  val get_email : 
    context -> 
    account_id:Jmap.Types.id -> 
    email_id:Jmap.Types.id -> 
    ?properties:string list -> 
    unit -> 
    Email.t Jmap.Error.result
  
  (** Search for emails using a filter
      @param ctx The JMAP client context
      @param account_id The account ID
      @param filter The search filter
      @param ?sort Optional sort criteria (default received date newest first)
      @param ?limit Optional maximum number of results
      @param ?properties Optional properties to fetch for the matching emails
      @return The list of matching email IDs and optionally the email objects
  *)
  val search_emails :
    context ->
    account_id:Jmap.Types.id ->
    filter:Jmap.Methods.Filter.t ->
    ?sort:Jmap.Methods.Comparator.t list ->
    ?limit:Jmap.Types.uint ->
    ?position:int ->
    ?properties:string list ->
    unit ->
    (Jmap.Types.id list * Email.t list option) Jmap.Error.result
    
  (** Mark multiple emails with a keyword
      @param ctx The JMAP client context
      @param account_id The account ID
      @param email_ids List of email IDs to update
      @param keyword The keyword to add
      @return The result of the operation
  *)
  val mark_emails :
    context ->
    account_id:Jmap.Types.id ->
    email_ids:Jmap.Types.id list ->
    keyword:Keywords.keyword ->
    unit ->
    unit Jmap.Error.result
    
  (** Mark emails as seen/read
      @param ctx The JMAP client context
      @param account_id The account ID
      @param email_ids List of email IDs to mark
      @return The result of the operation
  *)
  val mark_as_seen :
    context ->
    account_id:Jmap.Types.id ->
    email_ids:Jmap.Types.id list ->
    unit ->
    unit Jmap.Error.result
    
  (** Mark emails as unseen/unread
      @param ctx The JMAP client context
      @param account_id The account ID
      @param email_ids List of email IDs to mark
      @return The result of the operation
  *)
  val mark_as_unseen :
    context ->
    account_id:Jmap.Types.id ->
    email_ids:Jmap.Types.id list ->
    unit ->
    unit Jmap.Error.result
  
  (** Move emails to a different mailbox
      @param ctx The JMAP client context
      @param account_id The account ID
      @param email_ids List of email IDs to move
      @param mailbox_id Destination mailbox ID
      @param ?remove_from_mailboxes Optional list of source mailbox IDs to remove from
      @return The result of the operation
  *)
  val move_emails :
    context ->
    account_id:Jmap.Types.id ->
    email_ids:Jmap.Types.id list ->
    mailbox_id:Jmap.Types.id ->
    ?remove_from_mailboxes:Jmap.Types.id list ->
    unit ->
    unit Jmap.Error.result
  
  (** Import an RFC822 message
      @param ctx The JMAP client context
      @param account_id The account ID
      @param rfc822 Raw message content
      @param mailbox_ids Mailboxes to add the message to
      @param ?keywords Optional keywords to set
      @param ?received_at Optional received timestamp
      @return The ID of the imported email
  *)
  val import_email :
    context ->
    account_id:Jmap.Types.id ->
    rfc822:string ->
    mailbox_ids:Jmap.Types.id list ->
    ?keywords:Keywords.t ->
    ?received_at:Jmap.Types.date ->
    unit ->
    Jmap.Types.id Jmap.Error.result
end