ocaml-jmap / lib / core / chain.mli

(*---------------------------------------------------------------------------
   Copyright (c) 2025 Anil Madhavapeddy. All rights reserved.
   SPDX-License-Identifier: ISC
  ---------------------------------------------------------------------------*)

(** JMAP method chaining with automatic result references.

    This module provides a monadic interface for building JMAP requests
    where method calls can reference results from previous calls in the
    same request. Call IDs are generated automatically.

    {2 Basic Example}

    Query for emails and fetch their details in a single request:
    {[
      let open Jmap.Chain in
      let request, emails = build ~capabilities:[core; mail] begin
        let* query = email_query ~account_id
          ~filter:(Condition { in_mailbox = Some inbox_id; _ })
          ~limit:50L ()
        in
        let* emails = email_get ~account_id
          ~ids:(from_query query)
          ~properties:["subject"; "from"; "receivedAt"]
          ()
        in
        return emails
      end in
      match Client.request client request with
      | Ok response ->
        let emails = parse emails response in
        ...
    ]}

    {2 Creation and Submission}

    Create a draft email and submit it in one request:
    {[
      let* set_h, draft_cid = email_set ~account_id
        ~create:[email_create ~mailbox_ids:[drafts_id] ~subject:"Hello" ...]
        ()
      in
      let* _ = email_submission_set ~account_id
        ~create:[submission_create
          ~email_id:(created_id draft_cid)
          ~identity_id]
        ()
      in
      return set_h
    ]}

    {2 Multi-step Chains}

    The RFC 8620 example - fetch from/date/subject for all emails in
    the first 10 threads in the inbox:
    {[
      let* q = email_query ~account_id
        ~filter:(Condition { in_mailbox = Some inbox_id; _ })
        ~sort:[comparator ~is_ascending:false "receivedAt"]
        ~collapse_threads:true ~limit:10L ()
      in
      let* e1 = email_get ~account_id
        ~ids:(from_query q)
        ~properties:["threadId"]
        ()
      in
      let* threads = thread_get ~account_id
        ~ids:(from_get_field e1 "threadId")
        ()
      in
      let* e2 = email_get ~account_id
        ~ids:(from_get_field threads "emailIds")
        ~properties:["from"; "receivedAt"; "subject"]
        ()
      in
      return e2
    ]} *)

(** {1 Handles}

    Method invocations return handles that encode both the method kind
    (for building result references) and the exact response type
    (for type-safe parsing). *)

(** Phantom type for query method handles. *)
type query

(** Phantom type for get method handles. *)
type get

(** Phantom type for changes method handles. *)
type changes

(** Phantom type for set method handles. *)
type set

(** Phantom type for query_changes method handles. *)
type query_changes

(** Phantom type for copy method handles. *)
type copy

(** Phantom type for import method handles. *)
type import

(** Phantom type for parse method handles. *)
type parse

(** A handle to a method invocation.

    The first type parameter indicates the method kind (query/get/changes/set/...),
    used for building result references. The second type parameter is the
    parsed response type, enabling type-safe parsing via {!parse}. *)
type (_, _) handle

val call_id : (_, _) handle -> string
(** [call_id h] returns the auto-generated call ID for this invocation. *)

val method_name : (_, _) handle -> string
(** [method_name h] returns the method name (e.g., "Email/query"). *)

(** {1 Creation IDs}

    When creating objects via [/set] methods, you can reference the
    server-assigned ID before the request completes using creation IDs. *)

type 'a create_id
(** A creation ID for an object of type ['a]. Used to reference
    newly created objects within the same request. *)

val created_id : _ create_id -> Jmap_proto.Id.t
(** [created_id cid] returns a placeholder ID (["#cN"]) that the server
    will substitute with the real ID. Use this to reference a created
    object in subsequent method calls within the same request. *)

val created_id_of_string : string -> Jmap_proto.Id.t
(** [created_id_of_string s] returns a placeholder ID for a string creation ID.
    For example, [created_id_of_string "draft1"] returns ["#draft1"]. *)

(** {1 ID Sources}

    Methods that accept IDs can take them either as concrete values
    or as references to results from previous method calls. *)

type id_source =
  | Ids of Jmap_proto.Id.t list
      (** Concrete list of IDs. *)
  | Ref of Jmap_proto.Invocation.result_reference
      (** Back-reference to a previous method's result. *)

val ids : Jmap_proto.Id.t list -> id_source
(** [ids lst] provides concrete IDs. *)

val id : Jmap_proto.Id.t -> id_source
(** [id x] provides a single concrete ID. *)

(** {2 References from Query} *)

val from_query : (query, _) handle -> id_source
(** [from_query h] references [/ids] from a query response. *)

(** {2 References from Get} *)

val from_get_ids : (get, _) handle -> id_source
(** [from_get_ids h] references [/list/*/id] from a get response. *)

val from_get_field : (get, _) handle -> string -> id_source
(** [from_get_field h field] references [/list/*/field] from a get response.
    Common fields: ["threadId"], ["emailIds"], ["mailboxIds"]. *)

(** {2 References from Changes} *)

val from_changes_created : (changes, _) handle -> id_source
(** [from_changes_created h] references [/created] from a changes response. *)

val from_changes_updated : (changes, _) handle -> id_source
(** [from_changes_updated h] references [/updated] from a changes response. *)

val from_changes_destroyed : (changes, _) handle -> id_source
(** [from_changes_destroyed h] references [/destroyed] from a changes response. *)

(** {2 References from Set} *)

val from_set_created : (set, _) handle -> id_source
(** [from_set_created h] references [/created/*/id] - IDs of objects created
    by a set operation. *)

val from_set_updated : (set, _) handle -> id_source
(** [from_set_updated h] references [/updated] - IDs of objects updated. *)

(** {2 References from QueryChanges} *)

val from_query_changes_removed : (query_changes, _) handle -> id_source
(** [from_query_changes_removed h] references [/removed] from queryChanges. *)

val from_query_changes_added : (query_changes, _) handle -> id_source
(** [from_query_changes_added h] references [/added/*/id] from queryChanges. *)

(** {2 References from Copy} *)

val from_copy_created : (copy, _) handle -> id_source
(** [from_copy_created h] references [/created/*/id] from copy response. *)

(** {2 References from Import} *)

val from_import_created : (import, _) handle -> id_source
(** [from_import_created h] references [/created/*/id] from import response. *)

(** {1 Chain Monad}

    A monad for building JMAP requests with automatic call ID generation
    and invocation collection. *)

type 'a t
(** A chain computation that produces ['a] (typically a handle). *)

val return : 'a -> 'a t
(** [return x] is a computation that produces [x] without adding any
    method invocations. *)

val bind : 'a t -> ('a -> 'b t) -> 'b t
(** [bind m f] sequences computations, threading the chain state. *)

val map : ('a -> 'b) -> 'a t -> 'b t
(** [map f m] applies [f] to the result of [m]. *)

val both : 'a t -> 'b t -> ('a * 'b) t
(** [both a b] runs both computations, returning their results as a pair. *)

(** {2 Syntax} *)

val ( let* ) : 'a t -> ('a -> 'b t) -> 'b t
val ( let+ ) : 'a t -> ('a -> 'b) -> 'b t
val ( and* ) : 'a t -> 'b t -> ('a * 'b) t
val ( and+ ) : 'a t -> 'b t -> ('a * 'b) t

(** {1 Building Requests} *)

val build :
  capabilities:string list ->
  'a t ->
  Jmap_proto.Request.t * 'a
(** [build ~capabilities chain] runs the chain computation, returning
    the JMAP request and the final value (typically a handle for parsing). *)

val build_request :
  capabilities:string list ->
  'a t ->
  Jmap_proto.Request.t
(** [build_request ~capabilities chain] is like {!build} but discards
    the final value. *)

(** {1 Method Builders}

    Each builder returns a handle wrapped in the chain monad.
    Call IDs are assigned automatically based on invocation order. *)

(** {2 Email Methods} *)

val email_query :
  account_id:Jmap_proto.Id.t ->
  ?filter:Jmap_proto.Mail_filter.email_filter ->
  ?sort:Jmap_proto.Filter.comparator list ->
  ?position:int64 ->
  ?anchor:Jmap_proto.Id.t ->
  ?anchor_offset:int64 ->
  ?limit:int64 ->
  ?calculate_total:bool ->
  ?collapse_threads:bool ->
  unit ->
  (query, Jmap_proto.Method.query_response) handle t

val email_get :
  account_id:Jmap_proto.Id.t ->
  ?ids:id_source ->
  ?properties:string list ->
  ?body_properties:string list ->
  ?fetch_text_body_values:bool ->
  ?fetch_html_body_values:bool ->
  ?fetch_all_body_values:bool ->
  ?max_body_value_bytes:int64 ->
  unit ->
  (get, Jmap_proto.Email.t Jmap_proto.Method.get_response) handle t

val email_changes :
  account_id:Jmap_proto.Id.t ->
  since_state:string ->
  ?max_changes:int64 ->
  unit ->
  (changes, Jmap_proto.Method.changes_response) handle t

val email_query_changes :
  account_id:Jmap_proto.Id.t ->
  since_query_state:string ->
  ?filter:Jmap_proto.Mail_filter.email_filter ->
  ?sort:Jmap_proto.Filter.comparator list ->
  ?max_changes:int64 ->
  ?up_to_id:Jmap_proto.Id.t ->
  ?calculate_total:bool ->
  unit ->
  (query_changes, Jmap_proto.Method.query_changes_response) handle t

val email_set :
  account_id:Jmap_proto.Id.t ->
  ?if_in_state:string ->
  ?create:(string * Jsont.Json.t) list ->
  ?update:(Jmap_proto.Id.t * Jsont.Json.t) list ->
  ?destroy:id_source ->
  unit ->
  (set, Jmap_proto.Email.t Jmap_proto.Method.set_response) handle t
(** Build an Email/set invocation.

    [create] is a list of [(creation_id, email_object)] pairs where
    [creation_id] is a client-chosen string (e.g., "draft1") and
    [email_object] is the JSON representation of the email to create.

    Use {!created_id_of_string} to reference created objects in later calls. *)

val email_copy :
  from_account_id:Jmap_proto.Id.t ->
  account_id:Jmap_proto.Id.t ->
  ?if_from_in_state:string ->
  ?if_in_state:string ->
  ?create:(Jmap_proto.Id.t * Jsont.Json.t) list ->
  ?on_success_destroy_original:bool ->
  ?destroy_from_if_in_state:string ->
  unit ->
  (copy, Jmap_proto.Email.t Jmap_proto.Method.copy_response) handle t
(** Build an Email/copy invocation.

    [create] maps source email IDs to override objects. The source email
    is copied to the target account with any overridden properties. *)

(** {2 Thread Methods} *)

val thread_get :
  account_id:Jmap_proto.Id.t ->
  ?ids:id_source ->
  unit ->
  (get, Jmap_proto.Thread.t Jmap_proto.Method.get_response) handle t

val thread_changes :
  account_id:Jmap_proto.Id.t ->
  since_state:string ->
  ?max_changes:int64 ->
  unit ->
  (changes, Jmap_proto.Method.changes_response) handle t

(** {2 Mailbox Methods} *)

val mailbox_query :
  account_id:Jmap_proto.Id.t ->
  ?filter:Jmap_proto.Mail_filter.mailbox_filter ->
  ?sort:Jmap_proto.Filter.comparator list ->
  ?position:int64 ->
  ?anchor:Jmap_proto.Id.t ->
  ?anchor_offset:int64 ->
  ?limit:int64 ->
  ?calculate_total:bool ->
  unit ->
  (query, Jmap_proto.Method.query_response) handle t

val mailbox_get :
  account_id:Jmap_proto.Id.t ->
  ?ids:id_source ->
  ?properties:string list ->
  unit ->
  (get, Jmap_proto.Mailbox.t Jmap_proto.Method.get_response) handle t

val mailbox_changes :
  account_id:Jmap_proto.Id.t ->
  since_state:string ->
  ?max_changes:int64 ->
  unit ->
  (changes, Jmap_proto.Method.changes_response) handle t

val mailbox_query_changes :
  account_id:Jmap_proto.Id.t ->
  since_query_state:string ->
  ?filter:Jmap_proto.Mail_filter.mailbox_filter ->
  ?sort:Jmap_proto.Filter.comparator list ->
  ?max_changes:int64 ->
  ?up_to_id:Jmap_proto.Id.t ->
  ?calculate_total:bool ->
  unit ->
  (query_changes, Jmap_proto.Method.query_changes_response) handle t

val mailbox_set :
  account_id:Jmap_proto.Id.t ->
  ?if_in_state:string ->
  ?create:(string * Jsont.Json.t) list ->
  ?update:(Jmap_proto.Id.t * Jsont.Json.t) list ->
  ?destroy:id_source ->
  ?on_destroy_remove_emails:bool ->
  unit ->
  (set, Jmap_proto.Mailbox.t Jmap_proto.Method.set_response) handle t

(** {2 Identity Methods} *)

val identity_get :
  account_id:Jmap_proto.Id.t ->
  ?ids:id_source ->
  ?properties:string list ->
  unit ->
  (get, Jmap_proto.Identity.t Jmap_proto.Method.get_response) handle t

val identity_changes :
  account_id:Jmap_proto.Id.t ->
  since_state:string ->
  ?max_changes:int64 ->
  unit ->
  (changes, Jmap_proto.Method.changes_response) handle t

val identity_set :
  account_id:Jmap_proto.Id.t ->
  ?if_in_state:string ->
  ?create:(string * Jsont.Json.t) list ->
  ?update:(Jmap_proto.Id.t * Jsont.Json.t) list ->
  ?destroy:id_source ->
  unit ->
  (set, Jmap_proto.Identity.t Jmap_proto.Method.set_response) handle t

(** {2 EmailSubmission Methods} *)

val email_submission_query :
  account_id:Jmap_proto.Id.t ->
  ?filter:Jmap_proto.Mail_filter.submission_filter ->
  ?sort:Jmap_proto.Filter.comparator list ->
  ?position:int64 ->
  ?anchor:Jmap_proto.Id.t ->
  ?anchor_offset:int64 ->
  ?limit:int64 ->
  ?calculate_total:bool ->
  unit ->
  (query, Jmap_proto.Method.query_response) handle t

val email_submission_get :
  account_id:Jmap_proto.Id.t ->
  ?ids:id_source ->
  ?properties:string list ->
  unit ->
  (get, Jmap_proto.Submission.t Jmap_proto.Method.get_response) handle t

val email_submission_changes :
  account_id:Jmap_proto.Id.t ->
  since_state:string ->
  ?max_changes:int64 ->
  unit ->
  (changes, Jmap_proto.Method.changes_response) handle t

val email_submission_query_changes :
  account_id:Jmap_proto.Id.t ->
  since_query_state:string ->
  ?filter:Jmap_proto.Mail_filter.submission_filter ->
  ?sort:Jmap_proto.Filter.comparator list ->
  ?max_changes:int64 ->
  ?up_to_id:Jmap_proto.Id.t ->
  ?calculate_total:bool ->
  unit ->
  (query_changes, Jmap_proto.Method.query_changes_response) handle t

val email_submission_set :
  account_id:Jmap_proto.Id.t ->
  ?if_in_state:string ->
  ?create:(string * Jsont.Json.t) list ->
  ?update:(Jmap_proto.Id.t * Jsont.Json.t) list ->
  ?destroy:id_source ->
  ?on_success_update_email:(string * Jsont.Json.t) list ->
  ?on_success_destroy_email:string list ->
  unit ->
  (set, Jmap_proto.Submission.t Jmap_proto.Method.set_response) handle t
(** Build an EmailSubmission/set invocation.

    [on_success_update_email] and [on_success_destroy_email] take creation IDs
    (like ["#draft1"]) or real email IDs to update/destroy the email after
    successful submission. *)

(** {2 SearchSnippet Methods} *)

val search_snippet_get :
  account_id:Jmap_proto.Id.t ->
  filter:Jmap_proto.Mail_filter.email_filter ->
  email_ids:id_source ->
  unit ->
  (get, Jmap_proto.Search_snippet.t Jmap_proto.Method.get_response) handle t
(** Build a SearchSnippet/get invocation. Note that the filter must match
    the filter used in the Email/query that produced the email IDs. *)

(** {2 VacationResponse Methods} *)

val vacation_response_get :
  account_id:Jmap_proto.Id.t ->
  ?properties:string list ->
  unit ->
  (get, Jmap_proto.Vacation.t Jmap_proto.Method.get_response) handle t

val vacation_response_set :
  account_id:Jmap_proto.Id.t ->
  ?if_in_state:string ->
  update:Jsont.Json.t ->
  unit ->
  (set, Jmap_proto.Vacation.t Jmap_proto.Method.set_response) handle t
(** VacationResponse is a singleton - you can only update "singleton". *)

(** {1 Response Parsing} *)

val parse :
  (_, 'resp) handle ->
  Jmap_proto.Response.t ->
  ('resp, Jsont.Error.t) result
(** [parse handle response] extracts and parses the response for [handle].

    The response type is determined by the handle's type parameter,
    providing compile-time type safety. *)

val parse_exn : (_, 'resp) handle -> Jmap_proto.Response.t -> 'resp
(** [parse_exn handle response] is like {!parse} but raises on error. *)

(** {1 JSON Helpers}

    Convenience functions for building JSON patch objects for /set methods. *)

val json_null : Jsont.Json.t
(** A JSON null value. Use to unset a property. *)

val json_bool : bool -> Jsont.Json.t
(** [json_bool b] creates a JSON boolean. *)

val json_string : string -> Jsont.Json.t
(** [json_string s] creates a JSON string. *)

val json_int : int64 -> Jsont.Json.t
(** [json_int n] creates a JSON number from an int64. *)

val json_obj : (string * Jsont.Json.t) list -> Jsont.Json.t
(** [json_obj fields] creates a JSON object from key-value pairs. *)

val json_array : Jsont.Json.t list -> Jsont.Json.t
(** [json_array items] creates a JSON array. *)

(** {1 Creation ID Helpers} *)

val fresh_create_id : unit -> 'a create_id t
(** [fresh_create_id ()] generates a fresh creation ID within the chain.
    The ID is unique within the request. *)

(** {1 Low-Level Access}

    For users who need direct access to the underlying invocation. *)

val raw_invocation :
  name:string ->
  arguments:Jsont.Json.t ->
  (unit, Jsont.Json.t) handle t
(** [raw_invocation ~name ~arguments] adds a raw method invocation.
    Use this for methods not yet supported by the high-level API. *)