move chain

bin/jmap.ml

···
   let info = Cmd.info "identities" ~doc in
   Cmd.v info Term.(const run $ Jmap_eio.Cli.config_term)
 
+(** {1 Chained Commands - Using the Chain monad} *)
+
+(** Inbox command - demonstrates simple query+get chain *)
+let inbox_cmd =
+  let limit_term =
+    let doc = "Maximum number of emails to show" in
+    Arg.(value & opt int 20 & info ["limit"; "n"] ~docv:"N" ~doc)
+  in
+  let run cfg limit =
+    Eio_main.run @@ fun env ->
+    Eio.Switch.run @@ fun sw ->
+    let client = Jmap_eio.Cli.create_client ~sw env cfg in
+    let account_id = Jmap_eio.Cli.get_account_id cfg client in
+
+    Jmap_eio.Cli.debug cfg "Fetching inbox emails using Chain API";
+
+    (* Find inbox mailbox first *)
+    let mbox_req = Jmap_eio.Client.Build.(
+      make_request
+        ~capabilities:[Jmap.Proto.Capability.core; Jmap.Proto.Capability.mail]
+        [mailbox_get ~call_id:"m1" ~account_id ()]
+    ) in
+
+    match Jmap_eio.Client.request client mbox_req with
+    | Error e ->
+        Fmt.epr "Error: %s@." (Jmap_eio.Client.error_to_string e);
+        exit 1
+    | Ok mbox_response ->
+        match Jmap_eio.Client.Parse.parse_mailbox_get ~call_id:"m1" mbox_response with
+        | Error e ->
+            Fmt.epr "Parse error: %s@." (Jsont.Error.to_string e);
+            exit 1
+        | Ok mbox_result ->
+            (* Find inbox *)
+            let inbox =
+              List.find_opt (fun (m : Jmap.Proto.Mailbox.t) ->
+                m.role = Some Jmap.Proto.Mailbox.Inbox
+              ) mbox_result.list
+            in
+            match inbox with
+            | None ->
+                Fmt.epr "No inbox found@.";
+                exit 1
+            | Some inbox ->
+                Jmap_eio.Cli.debug cfg "Found inbox: %s" (Jmap.Proto.Id.to_string inbox.id);
+
+                (* Now use Chain API to query and get emails in one request *)
+                let open Jmap_eio.Chain in
+                let filter_cond : Jmap.Proto.Email.Filter_condition.t = {
+                  in_mailbox = Some inbox.id;
+                  in_mailbox_other_than = None;
+                  before = None; after = None;
+                  min_size = None; max_size = None;
+                  all_in_thread_have_keyword = None;
+                  some_in_thread_have_keyword = None;
+                  none_in_thread_have_keyword = None;
+                  has_keyword = None; not_keyword = None;
+                  has_attachment = None;
+                  text = None; from = None; to_ = None;
+                  cc = None; bcc = None; subject = None;
+                  body = None; header = None;
+                } in
+                let sort = [Jmap.Proto.Filter.comparator ~is_ascending:false "receivedAt"] in
+
+                let request, email_handle = build
+                  ~capabilities:[Jmap.Proto.Capability.core; Jmap.Proto.Capability.mail]
+                begin
+                  let* query = email_query ~account_id
+                    ~filter:(Jmap.Proto.Filter.Condition filter_cond)
+                    ~sort
+                    ~limit:(Int64.of_int limit)
+                    ()
+                  in
+                  let* emails = email_get ~account_id
+                    ~ids:(from_query query)
+                    ~properties:["id"; "blobId"; "threadId"; "mailboxIds"; "size"; "receivedAt"; "subject"; "from"; "preview"; "keywords"]
+                    ()
+                  in
+                  return emails
+                end in
+
+                Jmap_eio.Cli.debug cfg "Sending chained request (query + get in one round trip)";
+
+                match Jmap_eio.Client.request client request with
+                | Error e ->
+                    Fmt.epr "Error: %s@." (Jmap_eio.Client.error_to_string e);
+                    exit 1
+                | Ok response ->
+                    match parse email_handle response with
+                    | Error e ->
+                        Fmt.epr "Parse error: %s@." (Jsont.Error.to_string e);
+                        exit 1
+                    | Ok result ->
+                        Fmt.pr "@[<v>%a (%d emails in inbox)@,@,"
+                          Fmt.(styled `Bold string) "Inbox"
+                          (List.length result.list);
+                        List.iter (fun (email : Jmap.Proto.Email.t) ->
+                          let from_str = match email.from with
+                            | Some (addr :: _) ->
+                                Option.value addr.name ~default:addr.email
+                            | _ -> "?"
+                          in
+                          let subject = Option.value email.subject ~default:"(no subject)" in
+                          let flags = format_keywords email.keywords in
+                          Fmt.pr "  %a %s@,"
+                            Fmt.(styled `Cyan string) (Jmap.Proto.Id.to_string email.id)
+                            (ptime_to_string email.received_at);
+                          Fmt.pr "    From: %s@," (truncate_string 40 from_str);
+                          Fmt.pr "    Subject: %a%s@,"
+                            Fmt.(styled `White string) (truncate_string 50 subject)
+                            (if flags = "" then "" else " [" ^ flags ^ "]");
+                          Fmt.pr "@,"
+                        ) result.list;
+                        Fmt.pr "@]@."
+  in
+  let doc = "List inbox emails (uses Chain API for query+get in single request)" in
+  let info = Cmd.info "inbox" ~doc in
+  Cmd.v info Term.(const run $ Jmap_eio.Cli.config_term $ limit_term)
+
+(** Thread-view command - demonstrates multi-step chaining (RFC 8620 example) *)
+let thread_view_cmd =
+  let limit_term =
+    let doc = "Number of threads to show" in
+    Arg.(value & opt int 10 & info ["limit"; "n"] ~docv:"N" ~doc)
+  in
+  let run cfg limit =
+    Eio_main.run @@ fun env ->
+    Eio.Switch.run @@ fun sw ->
+    let client = Jmap_eio.Cli.create_client ~sw env cfg in
+    let account_id = Jmap_eio.Cli.get_account_id cfg client in
+
+    Jmap_eio.Cli.debug cfg "Fetching threaded view using multi-step Chain API";
+
+    (*
+       This implements the RFC 8620 example:
+       1. Email/query with collapseThreads to get one email per thread
+       2. Email/get to fetch threadId for each
+       3. Thread/get to fetch all emailIds in each thread
+       4. Email/get to fetch details for all emails in those threads
+    *)
+    let open Jmap_eio.Chain in
+    let sort = [Jmap.Proto.Filter.comparator ~is_ascending:false "receivedAt"] in
+
+    let request, (query_h, final_emails_h) = build
+      ~capabilities:[Jmap.Proto.Capability.core; Jmap.Proto.Capability.mail]
+    begin
+      (* Step 1: Query for recent emails, collapsing threads *)
+      let* query = email_query ~account_id
+        ~sort
+        ~collapse_threads:true
+        ~limit:(Int64.of_int limit)
+        ()
+      in
+      (* Step 2: Get just threadId for those emails *)
+      let* emails1 = email_get ~account_id
+        ~ids:(from_query query)
+        ~properties:["id"; "blobId"; "threadId"; "mailboxIds"; "size"; "receivedAt"]
+        ()
+      in
+      (* Step 3: Get threads using threadIds from step 2 *)
+      let* threads = thread_get ~account_id
+        ~ids:(from_get_field emails1 "threadId")
+        ()
+      in
+      (* Step 4: Get all emails in those threads *)
+      let* emails2 = email_get ~account_id
+        ~ids:(from_get_field threads "emailIds")
+        ~properties:["id"; "blobId"; "threadId"; "mailboxIds"; "size"; "receivedAt"; "subject"; "from"; "preview"]
+        ()
+      in
+      return (query, emails2)
+    end in
+
+    Jmap_eio.Cli.debug cfg "Sending 4-step chained request in single round trip";
+
+    match Jmap_eio.Client.request client request with
+    | Error e ->
+        Fmt.epr "Error: %s@." (Jmap_eio.Client.error_to_string e);
+        exit 1
+    | Ok response ->
+        let query_result = parse_exn query_h response in
+        let emails_result = parse_exn final_emails_h response in
+
+        (* Group emails by thread *)
+        let threads_map = Hashtbl.create 16 in
+        List.iter (fun (email : Jmap.Proto.Email.t) ->
+          let tid = Jmap.Proto.Id.to_string email.thread_id in
+          let existing = try Hashtbl.find threads_map tid with Not_found -> [] in
+          Hashtbl.replace threads_map tid (email :: existing)
+        ) emails_result.list;
+
+        Fmt.pr "@[<v>%a (%d threads, %d total emails)@,@,"
+          Fmt.(styled `Bold string) "Threaded View"
+          (Hashtbl.length threads_map)
+          (List.length emails_result.list);
+        Fmt.pr "Query found %s total matching emails@,@,"
+          (match query_result.total with Some n -> Int64.to_string n | None -> "?");
+
+        (* Print threads *)
+        Hashtbl.iter (fun _tid emails ->
+          let emails = List.sort (fun (a : Jmap.Proto.Email.t) (b : Jmap.Proto.Email.t) ->
+            Ptime.compare a.received_at b.received_at
+          ) emails in
+          let first_email = List.hd emails in
+          let subject = Option.value first_email.subject ~default:"(no subject)" in
+          Fmt.pr "  %a Thread: %s (%d emails)@,"
+            Fmt.(styled `Bold string) "▸"
+            (truncate_string 50 subject)
+            (List.length emails);
+          List.iter (fun (email : Jmap.Proto.Email.t) ->
+            let from_str = match email.from with
+              | Some (addr :: _) -> Option.value addr.name ~default:addr.email
+              | _ -> "?"
+            in
+            Fmt.pr "      %s  %s  %s@,"
+              (Jmap.Proto.Id.to_string email.id |> truncate_string 12)
+              (ptime_to_string email.received_at)
+              (truncate_string 30 from_str)
+          ) emails;
+          Fmt.pr "@,"
+        ) threads_map;
+        Fmt.pr "@]@."
+  in
+  let doc = "Show threaded view (demonstrates RFC 8620 multi-step chain)" in
+  let info = Cmd.info "thread-view" ~doc in
+  Cmd.v info Term.(const run $ Jmap_eio.Cli.config_term $ limit_term)
+
+(** Mark-read command - demonstrates email_set for updating keywords *)
+let mark_read_cmd =
+  let email_id_term =
+    let doc = "Email ID to mark as read" in
+    Arg.(required & pos 0 (some string) None & info [] ~docv:"EMAIL_ID" ~doc)
+  in
+  let unread_term =
+    let doc = "Mark as unread instead of read" in
+    Arg.(value & flag & info ["unread"; "u"] ~doc)
+  in
+  let run cfg email_id_str unread =
+    Eio_main.run @@ fun env ->
+    Eio.Switch.run @@ fun sw ->
+    let client = Jmap_eio.Cli.create_client ~sw env cfg in
+    let account_id = Jmap_eio.Cli.get_account_id cfg client in
+    let email_id = Jmap.Proto.Id.of_string_exn email_id_str in
+
+    Jmap_eio.Cli.debug cfg "%s email %s"
+      (if unread then "Marking as unread" else "Marking as read")
+      email_id_str;
+
+    (* Build the patch object - set or unset $seen keyword *)
+    let patch =
+      let open Jmap_eio.Chain in
+      if unread then
+        json_obj [("keywords/$seen", json_null)]
+      else
+        json_obj [("keywords/$seen", json_bool true)]
+    in
+
+    let open Jmap_eio.Chain in
+    let request, set_h = build
+      ~capabilities:[Jmap.Proto.Capability.core; Jmap.Proto.Capability.mail]
+    begin
+      email_set ~account_id
+        ~update:[(email_id, patch)]
+        ()
+    end in
+
+    match Jmap_eio.Client.request client request with
+    | Error e ->
+        Fmt.epr "Error: %s@." (Jmap_eio.Client.error_to_string e);
+        exit 1
+    | Ok response ->
+        match parse set_h response with
+        | Error e ->
+            Fmt.epr "Parse error: %s@." (Jsont.Error.to_string e);
+            exit 1
+        | Ok result ->
+            (* Check if update succeeded *)
+            let updated_ids =
+              result.updated
+              |> Option.value ~default:[]
+              |> List.map (fun (id, _) -> Jmap.Proto.Id.to_string id)
+            in
+            if List.mem email_id_str updated_ids then
+              Fmt.pr "Email %s marked as %s@."
+                email_id_str
+                (if unread then "unread" else "read")
+            else (
+              Fmt.epr "Failed to update email. ";
+              let not_updated = Option.value ~default:[] result.not_updated in
+              (match List.find_opt (fun (id, _) -> Jmap.Proto.Id.to_string id = email_id_str) not_updated with
+               | Some (_, err) ->
+                   let open Jmap.Proto.Error in
+                   let err_type = set_error_type_to_string err.type_ in
+                   let err_desc = Option.value ~default:"" err.description in
+                   Fmt.epr "Error: %s (%s)@." err_type err_desc
+               | None ->
+                   Fmt.epr "Unknown error@.");
+              exit 1
+            )
+  in
+  let doc = "Mark an email as read/unread (demonstrates Email/set)" in
+  let info = Cmd.info "mark-read" ~doc in
+  Cmd.v info Term.(const run $ Jmap_eio.Cli.config_term $ email_id_term $ unread_term)
+
+(** Delete email command - demonstrates email_set destroy *)
+let delete_email_cmd =
+  let email_ids_term =
+    let doc = "Email IDs to delete" in
+    Arg.(non_empty & pos_all string [] & info [] ~docv:"EMAIL_ID" ~doc)
+  in
+  let run cfg email_id_strs =
+    Eio_main.run @@ fun env ->
+    Eio.Switch.run @@ fun sw ->
+    let client = Jmap_eio.Cli.create_client ~sw env cfg in
+    let account_id = Jmap_eio.Cli.get_account_id cfg client in
+    let email_ids = List.map Jmap.Proto.Id.of_string_exn email_id_strs in
+
+    Jmap_eio.Cli.debug cfg "Deleting %d email(s)" (List.length email_ids);
+
+    let open Jmap_eio.Chain in
+    let request, set_h = build
+      ~capabilities:[Jmap.Proto.Capability.core; Jmap.Proto.Capability.mail]
+    begin
+      email_set ~account_id
+        ~destroy:(ids email_ids)
+        ()
+    end in
+
+    match Jmap_eio.Client.request client request with
+    | Error e ->
+        Fmt.epr "Error: %s@." (Jmap_eio.Client.error_to_string e);
+        exit 1
+    | Ok response ->
+        match parse set_h response with
+        | Error e ->
+            Fmt.epr "Parse error: %s@." (Jsont.Error.to_string e);
+            exit 1
+        | Ok result ->
+            let destroyed = Option.value ~default:[] result.destroyed in
+            let destroyed_ids = List.map Jmap.Proto.Id.to_string destroyed in
+            Fmt.pr "Deleted %d email(s):@." (List.length destroyed_ids);
+            List.iter (fun id -> Fmt.pr "  %s@." id) destroyed_ids;
+            (* Report any failures *)
+            let not_destroyed = Option.value ~default:[] result.not_destroyed in
+            if not_destroyed <> [] then begin
+              Fmt.epr "Failed to delete %d email(s):@." (List.length not_destroyed);
+              List.iter (fun (id, err) ->
+                let open Jmap.Proto.Error in
+                let err_type = set_error_type_to_string err.type_ in
+                Fmt.epr "  %s: %s@."
+                  (Jmap.Proto.Id.to_string id)
+                  err_type
+              ) not_destroyed
+            end
+  in
+  let doc = "Delete emails (demonstrates Email/set destroy)" in
+  let info = Cmd.info "delete" ~doc in
+  Cmd.v info Term.(const run $ Jmap_eio.Cli.config_term $ email_ids_term)
+
+(** Changes command - demonstrates email_changes for sync *)
+let changes_cmd =
+  let state_term =
+    let doc = "State to get changes since (use 'current' to just show current state)" in
+    Arg.(required & pos 0 (some string) None & info [] ~docv:"STATE" ~doc)
+  in
+  let run cfg state_str =
+    Eio_main.run @@ fun env ->
+    Eio.Switch.run @@ fun sw ->
+    let client = Jmap_eio.Cli.create_client ~sw env cfg in
+    let account_id = Jmap_eio.Cli.get_account_id cfg client in
+
+    if state_str = "current" then (
+      (* Just get current state by doing a minimal query *)
+      let open Jmap_eio.Chain in
+      let request, get_h = build
+        ~capabilities:[Jmap.Proto.Capability.core; Jmap.Proto.Capability.mail]
+      begin
+        (* Get empty list just to see state *)
+        email_get ~account_id ~ids:(ids []) ()
+      end in
+
+      match Jmap_eio.Client.request client request with
+      | Error e ->
+          Fmt.epr "Error: %s@." (Jmap_eio.Client.error_to_string e);
+          exit 1
+      | Ok response ->
+          match parse get_h response with
+          | Error e ->
+              Fmt.epr "Parse error: %s@." (Jsont.Error.to_string e);
+              exit 1
+          | Ok result ->
+              Fmt.pr "Current email state: %a@."
+                Fmt.(styled `Cyan string) result.state
+    ) else (
+      Jmap_eio.Cli.debug cfg "Getting changes since state: %s" state_str;
+
+      let open Jmap_eio.Chain in
+      let request, changes_h = build
+        ~capabilities:[Jmap.Proto.Capability.core; Jmap.Proto.Capability.mail]
+      begin
+        email_changes ~account_id ~since_state:state_str ()
+      end in
+
+      match Jmap_eio.Client.request client request with
+      | Error e ->
+          Fmt.epr "Error: %s@." (Jmap_eio.Client.error_to_string e);
+          exit 1
+      | Ok response ->
+          match parse changes_h response with
+          | Error e ->
+              Fmt.epr "Parse error: %s@." (Jsont.Error.to_string e);
+              exit 1
+          | Ok result ->
+              Fmt.pr "@[<v>%a@,@,"
+                Fmt.(styled `Bold string) "Email Changes";
+              Fmt.pr "Old state: %s@," result.old_state;
+              Fmt.pr "New state: %a@," Fmt.(styled `Cyan string) result.new_state;
+              Fmt.pr "Has more changes: %b@,@," result.has_more_changes;
+              Fmt.pr "Created: %d email(s)@," (List.length result.created);
+              List.iter (fun id ->
+                Fmt.pr "  + %s@," (Jmap.Proto.Id.to_string id)
+              ) result.created;
+              Fmt.pr "Updated: %d email(s)@," (List.length result.updated);
+              List.iter (fun id ->
+                Fmt.pr "  ~ %s@," (Jmap.Proto.Id.to_string id)
+              ) result.updated;
+              Fmt.pr "Destroyed: %d email(s)@," (List.length result.destroyed);
+              List.iter (fun id ->
+                Fmt.pr "  - %s@," (Jmap.Proto.Id.to_string id)
+              ) result.destroyed;
+              Fmt.pr "@]@."
+    )
+  in
+  let doc = "Show email changes since a state (demonstrates Email/changes)" in
+  let info = Cmd.info "changes" ~doc in
+  Cmd.v info Term.(const run $ Jmap_eio.Cli.config_term $ state_term)
+
+(** Sync command - demonstrates changes + get pattern for incremental sync *)
+let sync_cmd =
+  let state_term =
+    let doc = "State to sync from" in
+    Arg.(required & pos 0 (some string) None & info [] ~docv:"STATE" ~doc)
+  in
+  let run cfg state_str =
+    Eio_main.run @@ fun env ->
+    Eio.Switch.run @@ fun sw ->
+    let client = Jmap_eio.Cli.create_client ~sw env cfg in
+    let account_id = Jmap_eio.Cli.get_account_id cfg client in
+
+    Jmap_eio.Cli.debug cfg "Syncing from state: %s" state_str;
+
+    (* Chain: changes → get created → get updated *)
+    let open Jmap_eio.Chain in
+    let request, (changes_h, created_h, updated_h) = build
+      ~capabilities:[Jmap.Proto.Capability.core; Jmap.Proto.Capability.mail]
+    begin
+      let* changes = email_changes ~account_id ~since_state:state_str () in
+      let* created = email_get ~account_id
+        ~ids:(from_changes_created changes)
+        ~properties:["id"; "blobId"; "threadId"; "mailboxIds"; "size"; "receivedAt"; "subject"; "from"; "preview"]
+        ()
+      in
+      let* updated = email_get ~account_id
+        ~ids:(from_changes_updated changes)
+        ~properties:["id"; "blobId"; "threadId"; "mailboxIds"; "size"; "receivedAt"; "subject"; "from"; "keywords"]
+        ()
+      in
+      return (changes, created, updated)
+    end in
+
+    Jmap_eio.Cli.debug cfg "Sending chained sync request";
+
+    match Jmap_eio.Client.request client request with
+    | Error e ->
+        Fmt.epr "Error: %s@." (Jmap_eio.Client.error_to_string e);
+        exit 1
+    | Ok response ->
+        let changes_result = parse_exn changes_h response in
+        let created_result = parse_exn created_h response in
+        let updated_result = parse_exn updated_h response in
+
+        Fmt.pr "@[<v>%a (state: %s → %s)@,@,"
+          Fmt.(styled `Bold string) "Sync Results"
+          changes_result.old_state
+          changes_result.new_state;
+
+        if List.length created_result.list > 0 then begin
+          Fmt.pr "%a (%d)@,"
+            Fmt.(styled `Green string) "New emails"
+            (List.length created_result.list);
+          List.iter (fun (email : Jmap.Proto.Email.t) ->
+            let from_str = match email.from with
+              | Some (addr :: _) -> Option.value addr.name ~default:addr.email
+              | _ -> "?"
+            in
+            let subject = Option.value email.subject ~default:"(no subject)" in
+            Fmt.pr "  + %s  %s  %s@,"
+              (Jmap.Proto.Id.to_string email.id |> truncate_string 12)
+              (truncate_string 20 from_str)
+              (truncate_string 40 subject)
+          ) created_result.list;
+          Fmt.pr "@,"
+        end;
+
+        if List.length updated_result.list > 0 then begin
+          Fmt.pr "%a (%d)@,"
+            Fmt.(styled `Yellow string) "Updated emails"
+            (List.length updated_result.list);
+          List.iter (fun (email : Jmap.Proto.Email.t) ->
+            let flags = format_keywords email.keywords in
+            Fmt.pr "  ~ %s  [%s]@,"
+              (Jmap.Proto.Id.to_string email.id |> truncate_string 12)
+              flags
+          ) updated_result.list;
+          Fmt.pr "@,"
+        end;
+
+        if List.length changes_result.destroyed > 0 then begin
+          Fmt.pr "%a (%d)@,"
+            Fmt.(styled `Red string) "Deleted emails"
+            (List.length changes_result.destroyed);
+          List.iter (fun id ->
+            Fmt.pr "  - %s@," (Jmap.Proto.Id.to_string id)
+          ) changes_result.destroyed;
+          Fmt.pr "@,"
+        end;
+
+        if changes_result.has_more_changes then
+          Fmt.pr "%a - call sync again with state %s@,"
+            Fmt.(styled `Bold string) "More changes available"
+            changes_result.new_state;
+
+        Fmt.pr "@]@."
+  in
+  let doc = "Incremental sync (demonstrates changes + get chain)" in
+  let info = Cmd.info "sync" ~doc in
+  Cmd.v info Term.(const run $ Jmap_eio.Cli.config_term $ state_term)
+
 (** {1 Main Command Group} *)
 
 let main_cmd =
···
     recent_cmd;
     threads_cmd;
     identities_cmd;
+    (* Chain API examples *)
+    inbox_cmd;
+    thread_view_cmd;
+    mark_read_cmd;
+    delete_email_cmd;
+    changes_cmd;
+    sync_cmd;
   ]
 
 let () =

eio/jmap_eio.ml

···
 module Codec = Codec
 module Client = Client
 module Cli = Cli
+module Chain = Jmap.Chain

eio/jmap_eio.mli

···
 
 (** CLI configuration and cmdliner terms for JMAP tools. *)
 module Cli = Cli
+
+(** Method chaining with automatic result references.
+
+    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. *)
+module Chain = Jmap.Chain

lib/core/chain.ml

···
+(*---------------------------------------------------------------------------
+   Copyright (c) 2025 Anil Madhavapeddy. All rights reserved.
+   SPDX-License-Identifier: ISC
+  ---------------------------------------------------------------------------*)
+
+open Jmap_proto
+
+(* Phantom types for handle kinds *)
+type query
+type get
+type changes
+type set
+type query_changes
+type copy
+type import
+type parse
+
+(* Internal handle representation with GADT for response type *)
+type (_, _) handle =
+  | Query_handle : {
+      call_id : string;
+      method_name : string;
+    } -> (query, Method.query_response) handle
+  | Query_changes_handle : {
+      call_id : string;
+      method_name : string;
+    } -> (query_changes, Method.query_changes_response) handle
+  | Email_get_handle : {
+      call_id : string;
+      method_name : string;
+    } -> (get, Email.t Method.get_response) handle
+  | Thread_get_handle : {
+      call_id : string;
+      method_name : string;
+    } -> (get, Thread.t Method.get_response) handle
+  | Mailbox_get_handle : {
+      call_id : string;
+      method_name : string;
+    } -> (get, Mailbox.t Method.get_response) handle
+  | Identity_get_handle : {
+      call_id : string;
+      method_name : string;
+    } -> (get, Identity.t Method.get_response) handle
+  | Submission_get_handle : {
+      call_id : string;
+      method_name : string;
+    } -> (get, Submission.t Method.get_response) handle
+  | Search_snippet_get_handle : {
+      call_id : string;
+      method_name : string;
+    } -> (get, Search_snippet.t Method.get_response) handle
+  | Vacation_get_handle : {
+      call_id : string;
+      method_name : string;
+    } -> (get, Vacation.t Method.get_response) handle
+  | Changes_handle : {
+      call_id : string;
+      method_name : string;
+    } -> (changes, Method.changes_response) handle
+  | Email_set_handle : {
+      call_id : string;
+      method_name : string;
+    } -> (set, Email.t Method.set_response) handle
+  | Mailbox_set_handle : {
+      call_id : string;
+      method_name : string;
+    } -> (set, Mailbox.t Method.set_response) handle
+  | Identity_set_handle : {
+      call_id : string;
+      method_name : string;
+    } -> (set, Identity.t Method.set_response) handle
+  | Submission_set_handle : {
+      call_id : string;
+      method_name : string;
+    } -> (set, Submission.t Method.set_response) handle
+  | Vacation_set_handle : {
+      call_id : string;
+      method_name : string;
+    } -> (set, Vacation.t Method.set_response) handle
+  | Email_copy_handle : {
+      call_id : string;
+      method_name : string;
+    } -> (copy, Email.t Method.copy_response) handle
+  | Raw_handle : {
+      call_id : string;
+      method_name : string;
+    } -> (unit, Jsont.Json.t) handle
+
+let call_id : type k r. (k, r) handle -> string = function
+  | Query_handle h -> h.call_id
+  | Query_changes_handle h -> h.call_id
+  | Email_get_handle h -> h.call_id
+  | Thread_get_handle h -> h.call_id
+  | Mailbox_get_handle h -> h.call_id
+  | Identity_get_handle h -> h.call_id
+  | Submission_get_handle h -> h.call_id
+  | Search_snippet_get_handle h -> h.call_id
+  | Vacation_get_handle h -> h.call_id
+  | Changes_handle h -> h.call_id
+  | Email_set_handle h -> h.call_id
+  | Mailbox_set_handle h -> h.call_id
+  | Identity_set_handle h -> h.call_id
+  | Submission_set_handle h -> h.call_id
+  | Vacation_set_handle h -> h.call_id
+  | Email_copy_handle h -> h.call_id
+  | Raw_handle h -> h.call_id
+
+let method_name : type k r. (k, r) handle -> string = function
+  | Query_handle h -> h.method_name
+  | Query_changes_handle h -> h.method_name
+  | Email_get_handle h -> h.method_name
+  | Thread_get_handle h -> h.method_name
+  | Mailbox_get_handle h -> h.method_name
+  | Identity_get_handle h -> h.method_name
+  | Submission_get_handle h -> h.method_name
+  | Search_snippet_get_handle h -> h.method_name
+  | Vacation_get_handle h -> h.method_name
+  | Changes_handle h -> h.method_name
+  | Email_set_handle h -> h.method_name
+  | Mailbox_set_handle h -> h.method_name
+  | Identity_set_handle h -> h.method_name
+  | Submission_set_handle h -> h.method_name
+  | Vacation_set_handle h -> h.method_name
+  | Email_copy_handle h -> h.method_name
+  | Raw_handle h -> h.method_name
+
+(* Creation IDs *)
+type 'a create_id = string
+
+let created_id cid = Id.of_string_exn ("#" ^ cid)
+let created_id_of_string s = Id.of_string_exn ("#" ^ s)
+
+(* ID sources *)
+type id_source =
+  | Ids of Id.t list
+  | Ref of Invocation.result_reference
+
+let ids lst = Ids lst
+let id x = Ids [x]
+
+let make_ref ~call_id ~method_name ~path =
+  Ref (Invocation.result_reference_of_strings
+         ~result_of:call_id
+         ~name:method_name
+         ~path)
+
+let from_query : type r. (query, r) handle -> id_source = fun h ->
+  make_ref ~call_id:(call_id h) ~method_name:(method_name h) ~path:"/ids"
+
+let from_get_ids : type r. (get, r) handle -> id_source = fun h ->
+  make_ref ~call_id:(call_id h) ~method_name:(method_name h) ~path:"/list/*/id"
+
+let from_get_field : type r. (get, r) handle -> string -> id_source = fun h field ->
+  make_ref ~call_id:(call_id h) ~method_name:(method_name h)
+    ~path:(Printf.sprintf "/list/*/%s" field)
+
+let from_changes_created : type r. (changes, r) handle -> id_source = fun h ->
+  make_ref ~call_id:(call_id h) ~method_name:(method_name h) ~path:"/created"
+
+let from_changes_updated : type r. (changes, r) handle -> id_source = fun h ->
+  make_ref ~call_id:(call_id h) ~method_name:(method_name h) ~path:"/updated"
+
+let from_changes_destroyed : type r. (changes, r) handle -> id_source = fun h ->
+  make_ref ~call_id:(call_id h) ~method_name:(method_name h) ~path:"/destroyed"
+
+let from_set_created : type r. (set, r) handle -> id_source = fun h ->
+  make_ref ~call_id:(call_id h) ~method_name:(method_name h) ~path:"/created/*/id"
+
+let from_set_updated : type r. (set, r) handle -> id_source = fun h ->
+  make_ref ~call_id:(call_id h) ~method_name:(method_name h) ~path:"/updated"
+
+let from_query_changes_removed : type r. (query_changes, r) handle -> id_source = fun h ->
+  make_ref ~call_id:(call_id h) ~method_name:(method_name h) ~path:"/removed"
+
+let from_query_changes_added : type r. (query_changes, r) handle -> id_source = fun h ->
+  make_ref ~call_id:(call_id h) ~method_name:(method_name h) ~path:"/added/*/id"
+
+let from_copy_created : type r. (copy, r) handle -> id_source = fun h ->
+  make_ref ~call_id:(call_id h) ~method_name:(method_name h) ~path:"/created/*/id"
+
+let from_import_created : type r. (import, r) handle -> id_source = fun h ->
+  make_ref ~call_id:(call_id h) ~method_name:(method_name h) ~path:"/created/*/id"
+
+(* Chain state *)
+type state = {
+  mutable next_id : int;
+  mutable next_create_id : int;
+  mutable invocations : Invocation.t list;
+}
+
+(* Chain monad *)
+type 'a t = state -> 'a
+
+let return x _state = x
+
+let bind m f state =
+  let a = m state in
+  f a state
+
+let map f m state =
+  f (m state)
+
+let both a b state =
+  let x = a state in
+  let y = b state in
+  (x, y)
+
+let ( let* ) = bind
+let ( let+ ) m f = map f m
+let ( and* ) = both
+let ( and+ ) = both
+
+(* Building *)
+let fresh_call_id state =
+  let id = Printf.sprintf "c%d" state.next_id in
+  state.next_id <- state.next_id + 1;
+  id
+
+let fresh_create_id () state =
+  let id = Printf.sprintf "k%d" state.next_create_id in
+  state.next_create_id <- state.next_create_id + 1;
+  id
+
+let record_invocation inv state =
+  state.invocations <- inv :: state.invocations
+
+let build ~capabilities chain =
+  let state = { next_id = 0; next_create_id = 0; invocations = [] } in
+  let result = chain state in
+  let request = Request.create
+    ~using:capabilities
+    ~method_calls:(List.rev state.invocations)
+    ()
+  in
+  (request, result)
+
+let build_request ~capabilities chain =
+  fst (build ~capabilities chain)
+
+(* JSON helpers - exported *)
+let json_null = Jsont.Null ((), Jsont.Meta.none)
+
+let json_bool b = Jsont.Bool (b, Jsont.Meta.none)
+
+let json_string s = Jsont.String (s, Jsont.Meta.none)
+
+let json_int n = Jsont.Number (Int64.to_float n, Jsont.Meta.none)
+
+let json_name s = (s, Jsont.Meta.none)
+
+let json_obj fields =
+  let fields' = List.map (fun (k, v) -> (json_name k, v)) fields in
+  Jsont.Object (fields', Jsont.Meta.none)
+
+let json_array items = Jsont.Array (items, Jsont.Meta.none)
+
+(* JSON helpers - internal *)
+let json_of_id id =
+  Jsont.String (Id.to_string id, Jsont.Meta.none)
+
+let json_of_id_list ids =
+  let items = List.map json_of_id ids in
+  Jsont.Array (items, Jsont.Meta.none)
+
+let json_of_string_list strs =
+  let items = List.map json_string strs in
+  Jsont.Array (items, Jsont.Meta.none)
+
+let json_map pairs =
+  let fields' = List.map (fun (k, v) -> (json_name k, v)) pairs in
+  Jsont.Object (fields', Jsont.Meta.none)
+
+let encode_to_json jsont value =
+  match Jsont.Json.encode' jsont value with
+  | Ok j -> j
+  | Error _ -> json_obj []
+
+let encode_list_to_json jsont values =
+  match Jsont.Json.encode' (Jsont.list jsont) values with
+  | Ok j -> j
+  | Error _ -> Jsont.Array ([], Jsont.Meta.none)
+
+(* Add id_source to args *)
+let add_ids_arg args = function
+  | None -> args
+  | Some (Ids ids) ->
+      ("ids", json_of_id_list ids) :: args
+  | Some (Ref ref_) ->
+      let ref_json = encode_to_json Invocation.result_reference_jsont ref_ in
+      ("#ids", ref_json) :: args
+
+let add_destroy_arg args = function
+  | None -> args
+  | Some (Ids ids) ->
+      ("destroy", json_of_id_list ids) :: args
+  | Some (Ref ref_) ->
+      let ref_json = encode_to_json Invocation.result_reference_jsont ref_ in
+      ("#destroy", ref_json) :: args
+
+(* Query builder helper *)
+let build_query_args ~account_id ?filter ?filter_jsont ?sort ?position ?anchor
+    ?anchor_offset ?limit ?calculate_total () =
+  let args = [ ("accountId", json_of_id account_id) ] in
+  let args = match filter, filter_jsont with
+    | Some f, Some jsont -> ("filter", encode_to_json jsont f) :: args
+    | _ -> args
+  in
+  let args = match sort with
+    | None -> args
+    | Some comparators -> ("sort", encode_list_to_json Filter.comparator_jsont comparators) :: args
+  in
+  let args = match position with
+    | None -> args
+    | Some n -> ("position", json_int n) :: args
+  in
+  let args = match anchor with
+    | None -> args
+    | Some id -> ("anchor", json_of_id id) :: args
+  in
+  let args = match anchor_offset with
+    | None -> args
+    | Some n -> ("anchorOffset", json_int n) :: args
+  in
+  let args = match limit with
+    | None -> args
+    | Some n -> ("limit", json_int n) :: args
+  in
+  let args = match calculate_total with
+    | None -> args
+    | Some b -> ("calculateTotal", json_bool b) :: args
+  in
+  args
+
+(* Changes builder helper *)
+let build_changes_args ~account_id ~since_state ?max_changes () =
+  let args = [
+    ("accountId", json_of_id account_id);
+    ("sinceState", json_string since_state);
+  ] in
+  let args = match max_changes with
+    | None -> args
+    | Some n -> ("maxChanges", json_int n) :: args
+  in
+  args
+
+(* QueryChanges builder helper *)
+let build_query_changes_args ~account_id ~since_query_state ?filter ?filter_jsont
+    ?sort ?max_changes ?up_to_id ?calculate_total () =
+  let args = [
+    ("accountId", json_of_id account_id);
+    ("sinceQueryState", json_string since_query_state);
+  ] in
+  let args = match filter, filter_jsont with
+    | Some f, Some jsont -> ("filter", encode_to_json jsont f) :: args
+    | _ -> args
+  in
+  let args = match sort with
+    | None -> args
+    | Some comparators -> ("sort", encode_list_to_json Filter.comparator_jsont comparators) :: args
+  in
+  let args = match max_changes with
+    | None -> args
+    | Some n -> ("maxChanges", json_int n) :: args
+  in
+  let args = match up_to_id with
+    | None -> args
+    | Some id -> ("upToId", json_of_id id) :: args
+  in
+  let args = match calculate_total with
+    | None -> args
+    | Some b -> ("calculateTotal", json_bool b) :: args
+  in
+  args
+
+(* Set builder helper *)
+let build_set_args ~account_id ?if_in_state ?create ?update ?destroy () =
+  let args = [ ("accountId", json_of_id account_id) ] in
+  let args = match if_in_state with
+    | None -> args
+    | Some s -> ("ifInState", json_string s) :: args
+  in
+  let args = match create with
+    | None | Some [] -> args
+    | Some items ->
+        let create_map = json_map (List.map (fun (cid, obj) -> (cid, obj)) items) in
+        ("create", create_map) :: args
+  in
+  let args = match update with
+    | None | Some [] -> args
+    | Some items ->
+        let update_map = json_map (List.map (fun (id, patch) -> (Id.to_string id, patch)) items) in
+        ("update", update_map) :: args
+  in
+  let args = add_destroy_arg args destroy in
+  args
+
+(* Method builders *)
+
+let email_query ~account_id ?filter ?sort ?position ?anchor ?anchor_offset
+    ?limit ?calculate_total ?collapse_threads () state =
+  let call_id = fresh_call_id state in
+  let args = build_query_args ~account_id ?filter
+    ~filter_jsont:Mail_filter.email_filter_jsont
+    ?sort ?position ?anchor ?anchor_offset ?limit ?calculate_total () in
+  let args = match collapse_threads with
+    | None -> args
+    | Some b -> ("collapseThreads", json_bool b) :: args
+  in
+  let inv = Invocation.create
+    ~name:"Email/query"
+    ~arguments:(json_obj args)
+    ~method_call_id:call_id
+  in
+  record_invocation inv state;
+  Query_handle { call_id; method_name = "Email/query" }
+
+let email_get ~account_id ?ids ?properties ?body_properties
+    ?fetch_text_body_values ?fetch_html_body_values ?fetch_all_body_values
+    ?max_body_value_bytes () state =
+  let call_id = fresh_call_id state in
+  let args = [ ("accountId", json_of_id account_id) ] in
+  let args = add_ids_arg args ids in
+  let args = match properties with
+    | None -> args
+    | Some props -> ("properties", json_of_string_list props) :: args
+  in
+  let args = match body_properties with
+    | None -> args
+    | Some props -> ("bodyProperties", json_of_string_list props) :: args
+  in
+  let args = match fetch_text_body_values with
+    | None -> args
+    | Some b -> ("fetchTextBodyValues", json_bool b) :: args
+  in
+  let args = match fetch_html_body_values with
+    | None -> args
+    | Some b -> ("fetchHTMLBodyValues", json_bool b) :: args
+  in
+  let args = match fetch_all_body_values with
+    | None -> args
+    | Some b -> ("fetchAllBodyValues", json_bool b) :: args
+  in
+  let args = match max_body_value_bytes with
+    | None -> args
+    | Some n -> ("maxBodyValueBytes", json_int n) :: args
+  in
+  let inv = Invocation.create
+    ~name:"Email/get"
+    ~arguments:(json_obj args)
+    ~method_call_id:call_id
+  in
+  record_invocation inv state;
+  Email_get_handle { call_id; method_name = "Email/get" }
+
+let email_changes ~account_id ~since_state ?max_changes () state =
+  let call_id = fresh_call_id state in
+  let args = build_changes_args ~account_id ~since_state ?max_changes () in
+  let inv = Invocation.create
+    ~name:"Email/changes"
+    ~arguments:(json_obj args)
+    ~method_call_id:call_id
+  in
+  record_invocation inv state;
+  Changes_handle { call_id; method_name = "Email/changes" }
+
+let email_query_changes ~account_id ~since_query_state ?filter ?sort
+    ?max_changes ?up_to_id ?calculate_total () state =
+  let call_id = fresh_call_id state in
+  let args = build_query_changes_args ~account_id ~since_query_state
+    ?filter ~filter_jsont:Mail_filter.email_filter_jsont
+    ?sort ?max_changes ?up_to_id ?calculate_total () in
+  let inv = Invocation.create
+    ~name:"Email/queryChanges"
+    ~arguments:(json_obj args)
+    ~method_call_id:call_id
+  in
+  record_invocation inv state;
+  Query_changes_handle { call_id; method_name = "Email/queryChanges" }
+
+let email_set ~account_id ?if_in_state ?create ?update ?destroy () state =
+  let call_id = fresh_call_id state in
+  let args = build_set_args ~account_id ?if_in_state ?create ?update ?destroy () in
+  let inv = Invocation.create
+    ~name:"Email/set"
+    ~arguments:(json_obj args)
+    ~method_call_id:call_id
+  in
+  record_invocation inv state;
+  Email_set_handle { call_id; method_name = "Email/set" }
+
+let email_copy ~from_account_id ~account_id ?if_from_in_state ?if_in_state
+    ?create ?on_success_destroy_original ?destroy_from_if_in_state () state =
+  let call_id = fresh_call_id state in
+  let args = [
+    ("fromAccountId", json_of_id from_account_id);
+    ("accountId", json_of_id account_id);
+  ] in
+  let args = match if_from_in_state with
+    | None -> args
+    | Some s -> ("ifFromInState", json_string s) :: args
+  in
+  let args = match if_in_state with
+    | None -> args
+    | Some s -> ("ifInState", json_string s) :: args
+  in
+  let args = match create with
+    | None | Some [] -> args
+    | Some items ->
+        let create_map = json_map (List.map (fun (id, obj) -> (Id.to_string id, obj)) items) in
+        ("create", create_map) :: args
+  in
+  let args = match on_success_destroy_original with
+    | None -> args
+    | Some b -> ("onSuccessDestroyOriginal", json_bool b) :: args
+  in
+  let args = match destroy_from_if_in_state with
+    | None -> args
+    | Some s -> ("destroyFromIfInState", json_string s) :: args
+  in
+  let inv = Invocation.create
+    ~name:"Email/copy"
+    ~arguments:(json_obj args)
+    ~method_call_id:call_id
+  in
+  record_invocation inv state;
+  Email_copy_handle { call_id; method_name = "Email/copy" }
+
+let thread_get ~account_id ?ids () state =
+  let call_id = fresh_call_id state in
+  let args = [ ("accountId", json_of_id account_id) ] in
+  let args = add_ids_arg args ids in
+  let inv = Invocation.create
+    ~name:"Thread/get"
+    ~arguments:(json_obj args)
+    ~method_call_id:call_id
+  in
+  record_invocation inv state;
+  Thread_get_handle { call_id; method_name = "Thread/get" }
+
+let thread_changes ~account_id ~since_state ?max_changes () state =
+  let call_id = fresh_call_id state in
+  let args = build_changes_args ~account_id ~since_state ?max_changes () in
+  let inv = Invocation.create
+    ~name:"Thread/changes"
+    ~arguments:(json_obj args)
+    ~method_call_id:call_id
+  in
+  record_invocation inv state;
+  Changes_handle { call_id; method_name = "Thread/changes" }
+
+let mailbox_query ~account_id ?filter ?sort ?position ?anchor ?anchor_offset
+    ?limit ?calculate_total () state =
+  let call_id = fresh_call_id state in
+  let args = build_query_args ~account_id ?filter
+    ~filter_jsont:Mail_filter.mailbox_filter_jsont
+    ?sort ?position ?anchor ?anchor_offset ?limit ?calculate_total () in
+  let inv = Invocation.create
+    ~name:"Mailbox/query"
+    ~arguments:(json_obj args)
+    ~method_call_id:call_id
+  in
+  record_invocation inv state;
+  Query_handle { call_id; method_name = "Mailbox/query" }
+
+let mailbox_get ~account_id ?ids ?properties () state =
+  let call_id = fresh_call_id state in
+  let args = [ ("accountId", json_of_id account_id) ] in
+  let args = add_ids_arg args ids in
+  let args = match properties with
+    | None -> args
+    | Some props -> ("properties", json_of_string_list props) :: args
+  in
+  let inv = Invocation.create
+    ~name:"Mailbox/get"
+    ~arguments:(json_obj args)
+    ~method_call_id:call_id
+  in
+  record_invocation inv state;
+  Mailbox_get_handle { call_id; method_name = "Mailbox/get" }
+
+let mailbox_changes ~account_id ~since_state ?max_changes () state =
+  let call_id = fresh_call_id state in
+  let args = build_changes_args ~account_id ~since_state ?max_changes () in
+  let inv = Invocation.create
+    ~name:"Mailbox/changes"
+    ~arguments:(json_obj args)
+    ~method_call_id:call_id
+  in
+  record_invocation inv state;
+  Changes_handle { call_id; method_name = "Mailbox/changes" }
+
+let mailbox_query_changes ~account_id ~since_query_state ?filter ?sort
+    ?max_changes ?up_to_id ?calculate_total () state =
+  let call_id = fresh_call_id state in
+  let args = build_query_changes_args ~account_id ~since_query_state
+    ?filter ~filter_jsont:Mail_filter.mailbox_filter_jsont
+    ?sort ?max_changes ?up_to_id ?calculate_total () in
+  let inv = Invocation.create
+    ~name:"Mailbox/queryChanges"
+    ~arguments:(json_obj args)
+    ~method_call_id:call_id
+  in
+  record_invocation inv state;
+  Query_changes_handle { call_id; method_name = "Mailbox/queryChanges" }
+
+let mailbox_set ~account_id ?if_in_state ?create ?update ?destroy
+    ?on_destroy_remove_emails () state =
+  let call_id = fresh_call_id state in
+  let args = build_set_args ~account_id ?if_in_state ?create ?update ?destroy () in
+  let args = match on_destroy_remove_emails with
+    | None -> args
+    | Some b -> ("onDestroyRemoveEmails", json_bool b) :: args
+  in
+  let inv = Invocation.create
+    ~name:"Mailbox/set"
+    ~arguments:(json_obj args)
+    ~method_call_id:call_id
+  in
+  record_invocation inv state;
+  Mailbox_set_handle { call_id; method_name = "Mailbox/set" }
+
+let identity_get ~account_id ?ids ?properties () state =
+  let call_id = fresh_call_id state in
+  let args = [ ("accountId", json_of_id account_id) ] in
+  let args = add_ids_arg args ids in
+  let args = match properties with
+    | None -> args
+    | Some props -> ("properties", json_of_string_list props) :: args
+  in
+  let inv = Invocation.create
+    ~name:"Identity/get"
+    ~arguments:(json_obj args)
+    ~method_call_id:call_id
+  in
+  record_invocation inv state;
+  Identity_get_handle { call_id; method_name = "Identity/get" }
+
+let identity_changes ~account_id ~since_state ?max_changes () state =
+  let call_id = fresh_call_id state in
+  let args = build_changes_args ~account_id ~since_state ?max_changes () in
+  let inv = Invocation.create
+    ~name:"Identity/changes"
+    ~arguments:(json_obj args)
+    ~method_call_id:call_id
+  in
+  record_invocation inv state;
+  Changes_handle { call_id; method_name = "Identity/changes" }
+
+let identity_set ~account_id ?if_in_state ?create ?update ?destroy () state =
+  let call_id = fresh_call_id state in
+  let args = build_set_args ~account_id ?if_in_state ?create ?update ?destroy () in
+  let inv = Invocation.create
+    ~name:"Identity/set"
+    ~arguments:(json_obj args)
+    ~method_call_id:call_id
+  in
+  record_invocation inv state;
+  Identity_set_handle { call_id; method_name = "Identity/set" }
+
+let email_submission_query ~account_id ?filter ?sort ?position ?anchor
+    ?anchor_offset ?limit ?calculate_total () state =
+  let call_id = fresh_call_id state in
+  let args = build_query_args ~account_id ?filter
+    ~filter_jsont:Mail_filter.submission_filter_jsont
+    ?sort ?position ?anchor ?anchor_offset ?limit ?calculate_total () in
+  let inv = Invocation.create
+    ~name:"EmailSubmission/query"
+    ~arguments:(json_obj args)
+    ~method_call_id:call_id
+  in
+  record_invocation inv state;
+  Query_handle { call_id; method_name = "EmailSubmission/query" }
+
+let email_submission_get ~account_id ?ids ?properties () state =
+  let call_id = fresh_call_id state in
+  let args = [ ("accountId", json_of_id account_id) ] in
+  let args = add_ids_arg args ids in
+  let args = match properties with
+    | None -> args
+    | Some props -> ("properties", json_of_string_list props) :: args
+  in
+  let inv = Invocation.create
+    ~name:"EmailSubmission/get"
+    ~arguments:(json_obj args)
+    ~method_call_id:call_id
+  in
+  record_invocation inv state;
+  Submission_get_handle { call_id; method_name = "EmailSubmission/get" }
+
+let email_submission_changes ~account_id ~since_state ?max_changes () state =
+  let call_id = fresh_call_id state in
+  let args = build_changes_args ~account_id ~since_state ?max_changes () in
+  let inv = Invocation.create
+    ~name:"EmailSubmission/changes"
+    ~arguments:(json_obj args)
+    ~method_call_id:call_id
+  in
+  record_invocation inv state;
+  Changes_handle { call_id; method_name = "EmailSubmission/changes" }
+
+let email_submission_query_changes ~account_id ~since_query_state ?filter ?sort
+    ?max_changes ?up_to_id ?calculate_total () state =
+  let call_id = fresh_call_id state in
+  let args = build_query_changes_args ~account_id ~since_query_state
+    ?filter ~filter_jsont:Mail_filter.submission_filter_jsont
+    ?sort ?max_changes ?up_to_id ?calculate_total () in
+  let inv = Invocation.create
+    ~name:"EmailSubmission/queryChanges"
+    ~arguments:(json_obj args)
+    ~method_call_id:call_id
+  in
+  record_invocation inv state;
+  Query_changes_handle { call_id; method_name = "EmailSubmission/queryChanges" }
+
+let email_submission_set ~account_id ?if_in_state ?create ?update ?destroy
+    ?on_success_update_email ?on_success_destroy_email () state =
+  let call_id = fresh_call_id state in
+  let args = build_set_args ~account_id ?if_in_state ?create ?update ?destroy () in
+  let args = match on_success_update_email with
+    | None | Some [] -> args
+    | Some items ->
+        let update_map = json_map items in
+        ("onSuccessUpdateEmail", update_map) :: args
+  in
+  let args = match on_success_destroy_email with
+    | None | Some [] -> args
+    | Some ids ->
+        ("onSuccessDestroyEmail", json_of_string_list ids) :: args
+  in
+  let inv = Invocation.create
+    ~name:"EmailSubmission/set"
+    ~arguments:(json_obj args)
+    ~method_call_id:call_id
+  in
+  record_invocation inv state;
+  Submission_set_handle { call_id; method_name = "EmailSubmission/set" }
+
+let search_snippet_get ~account_id ~filter ~email_ids () state =
+  let call_id = fresh_call_id state in
+  let args = [ ("accountId", json_of_id account_id) ] in
+  let args = ("filter", encode_to_json Mail_filter.email_filter_jsont filter) :: args in
+  let args = match email_ids with
+    | Ids ids -> ("emailIds", json_of_id_list ids) :: args
+    | Ref ref_ ->
+        let ref_json = encode_to_json Invocation.result_reference_jsont ref_ in
+        ("#emailIds", ref_json) :: args
+  in
+  let inv = Invocation.create
+    ~name:"SearchSnippet/get"
+    ~arguments:(json_obj args)
+    ~method_call_id:call_id
+  in
+  record_invocation inv state;
+  Search_snippet_get_handle { call_id; method_name = "SearchSnippet/get" }
+
+let vacation_response_get ~account_id ?properties () state =
+  let call_id = fresh_call_id state in
+  let args = [ ("accountId", json_of_id account_id) ] in
+  let args = match properties with
+    | None -> args
+    | Some props -> ("properties", json_of_string_list props) :: args
+  in
+  let inv = Invocation.create
+    ~name:"VacationResponse/get"
+    ~arguments:(json_obj args)
+    ~method_call_id:call_id
+  in
+  record_invocation inv state;
+  Vacation_get_handle { call_id; method_name = "VacationResponse/get" }
+
+let vacation_response_set ~account_id ?if_in_state ~update () state =
+  let call_id = fresh_call_id state in
+  let args = [ ("accountId", json_of_id account_id) ] in
+  let args = match if_in_state with
+    | None -> args
+    | Some s -> ("ifInState", json_string s) :: args
+  in
+  let args = ("update", json_map [("singleton", update)]) :: args in
+  let inv = Invocation.create
+    ~name:"VacationResponse/set"
+    ~arguments:(json_obj args)
+    ~method_call_id:call_id
+  in
+  record_invocation inv state;
+  Vacation_set_handle { call_id; method_name = "VacationResponse/set" }
+
+let raw_invocation ~name ~arguments state =
+  let call_id = fresh_call_id state in
+  let inv = Invocation.create
+    ~name
+    ~arguments
+    ~method_call_id:call_id
+  in
+  record_invocation inv state;
+  Raw_handle { call_id; method_name = name }
+
+(* Response parsing *)
+
+let find_invocation ~call_id response =
+  List.find_opt
+    (fun inv -> Invocation.method_call_id inv = call_id)
+    (Response.method_responses response)
+
+let parse : type k r. (k, r) handle -> Response.t -> (r, Jsont.Error.t) result =
+  fun handle response ->
+    let cid = call_id handle in
+    match find_invocation ~call_id:cid response with
+    | None ->
+        Error (Jsont.Error.msgf Jsont.Meta.none "No response found for call_id: %s" cid)
+    | Some inv ->
+        let args = Invocation.arguments inv in
+        match handle with
+        | Query_handle _ ->
+            Jsont.Json.decode' Method.query_response_jsont args
+        | Query_changes_handle _ ->
+            Jsont.Json.decode' Method.query_changes_response_jsont args
+        | Email_get_handle _ ->
+            Jsont.Json.decode' (Method.get_response_jsont Email.jsont) args
+        | Thread_get_handle _ ->
+            Jsont.Json.decode' (Method.get_response_jsont Thread.jsont) args
+        | Mailbox_get_handle _ ->
+            Jsont.Json.decode' (Method.get_response_jsont Mailbox.jsont) args
+        | Identity_get_handle _ ->
+            Jsont.Json.decode' (Method.get_response_jsont Identity.jsont) args
+        | Submission_get_handle _ ->
+            Jsont.Json.decode' (Method.get_response_jsont Submission.jsont) args
+        | Search_snippet_get_handle _ ->
+            Jsont.Json.decode' (Method.get_response_jsont Search_snippet.jsont) args
+        | Vacation_get_handle _ ->
+            Jsont.Json.decode' (Method.get_response_jsont Vacation.jsont) args
+        | Changes_handle _ ->
+            Jsont.Json.decode' Method.changes_response_jsont args
+        | Email_set_handle _ ->
+            Jsont.Json.decode' (Method.set_response_jsont Email.jsont) args
+        | Mailbox_set_handle _ ->
+            Jsont.Json.decode' (Method.set_response_jsont Mailbox.jsont) args
+        | Identity_set_handle _ ->
+            Jsont.Json.decode' (Method.set_response_jsont Identity.jsont) args
+        | Submission_set_handle _ ->
+            Jsont.Json.decode' (Method.set_response_jsont Submission.jsont) args
+        | Vacation_set_handle _ ->
+            Jsont.Json.decode' (Method.set_response_jsont Vacation.jsont) args
+        | Email_copy_handle _ ->
+            Jsont.Json.decode' (Method.copy_response_jsont Email.jsont) args
+        | Raw_handle _ ->
+            Ok args
+
+let parse_exn handle response =
+  match parse handle response with
+  | Ok r -> r
+  | Error e -> failwith (Jsont.Error.to_string e)

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. *)

lib/core/jmap.ml

···
   val to_string : t -> (string, Error.t) result
 end
 
-(** {1 Private Interface} *)
+(** {1 Request Chaining} *)
 
-(** Private module for internal use by Jmap_eio.
+(** JMAP method chaining with automatic result references.
 
-    This exposes the underlying Jsont codecs for serialization. *)
-module Private = struct
-  module Session = struct
-    let jsont = Proto.Session.jsont
-  end
-
-  module Request = struct
-    let jsont = Proto.Request.jsont
-  end
-
-  module Response = struct
-    let jsont = Proto.Response.jsont
-  end
-
-  module Mailbox = struct
-    let jsont = Proto.Mailbox.jsont
-  end
-
-  module Email = struct
-    let jsont = Proto.Email.jsont
-  end
-
-  module Thread = struct
-    let jsont = Proto.Thread.jsont
-  end
-
-  module Identity = struct
-    let jsont = Proto.Identity.jsont
-  end
-
-  module Submission = struct
-    let jsont = Proto.Submission.jsont
-  end
-
-  module Vacation = struct
-    let jsont = Proto.Vacation.jsont
-  end
-
-  module Blob = struct
-    let upload_response_jsont = Proto.Blob.upload_response_jsont
-  end
-
-  module Method = struct
-    let get_response_jsont = Proto.Method.get_response_jsont
-    let query_response_jsont = Proto.Method.query_response_jsont
-    let changes_response_jsont = Proto.Method.changes_response_jsont
-    let set_response_jsont = Proto.Method.set_response_jsont
-  end
-
-  module Mail_filter = struct
-    let email_filter_jsont = Proto.Mail_filter.email_filter_jsont
-    let mailbox_filter_jsont = Proto.Mail_filter.mailbox_filter_jsont
-    let submission_filter_jsont = Proto.Mail_filter.submission_filter_jsont
-  end
-
-  module Filter = struct
-    let comparator_jsont = Proto.Filter.comparator_jsont
-  end
-end
+    See {!Chain} for the full interface. *)
+module Chain = Chain

lib/core/jmap.mli

···
   val to_string : t -> (string, Error.t) result
 end
 
-(** {1 Private Interface} *)
-
-(** Private module for internal use by Jmap_eio.
-
-    This exposes the underlying Jsont codecs for serialization. *)
-module Private : sig
-  module Session : sig
-    val jsont : Proto.Session.t Jsont.t
-  end
-
-  module Request : sig
-    val jsont : Proto.Request.t Jsont.t
-  end
-
-  module Response : sig
-    val jsont : Proto.Response.t Jsont.t
-  end
-
-  module Mailbox : sig
-    val jsont : Proto.Mailbox.t Jsont.t
-  end
-
-  module Email : sig
-    val jsont : Proto.Email.t Jsont.t
-  end
-
-  module Thread : sig
-    val jsont : Proto.Thread.t Jsont.t
-  end
-
-  module Identity : sig
-    val jsont : Proto.Identity.t Jsont.t
-  end
+(** {1 Request Chaining} *)
 
-  module Submission : sig
-    val jsont : Proto.Submission.t Jsont.t
-  end
+(** JMAP method chaining with automatic result references.
 
-  module Vacation : sig
-    val jsont : Proto.Vacation.t Jsont.t
-  end
-
-  module Blob : sig
-    val upload_response_jsont : Proto.Blob.upload_response Jsont.t
-  end
-
-  module Method : sig
-    val get_response_jsont : 'a Jsont.t -> 'a Proto.Method.get_response Jsont.t
-    val query_response_jsont : Proto.Method.query_response Jsont.t
-    val changes_response_jsont : Proto.Method.changes_response Jsont.t
-    val set_response_jsont : 'a Jsont.t -> 'a Proto.Method.set_response Jsont.t
-  end
-
-  module Mail_filter : sig
-    val email_filter_jsont : Proto.Mail_filter.email_filter Jsont.t
-    val mailbox_filter_jsont : Proto.Mail_filter.mailbox_filter Jsont.t
-    val submission_filter_jsont : Proto.Mail_filter.submission_filter Jsont.t
-  end
-
-  module Filter : sig
-    val comparator_jsont : Proto.Filter.comparator Jsont.t
-  end
-end
+    This module provides a monadic interface for building JMAP requests
+    where method calls can reference results from previous calls. *)
+module Chain = Chain

lib/dune

···
   ; Core unified interface
   jmap
   jmap_types
+  chain
   ; Protocol layer wrapper (combines core + mail)
   jmap_proto
   ; Core protocol modules