metadata + protocol fixes

.gitignore

···
-_build
+# OCaml build artifacts
+_build/
+*.install
+*.merlin
+
+# Third-party sources (fetch locally with opam source)
+third_party/
+
+# Editor and OS files
+.DS_Store
+*.swp
+*~
+.vscode/
+.idea/
+
+# Opam local switch
+_opam/
+
+# Environment and secrets
 .env
 .api-key
+.api-key-rw
 .api-url

.ocamlformat

···
+version=0.28.1

.tangled/workflows/build.yml

···
+when:
+  - event: ["push", "pull_request"]
+    branch: ["main"]
+
+engine: nixery
+
+dependencies:
+  nixpkgs:
+    - shell
+    - stdenv
+    - findutils
+    - binutils
+    - libunwind
+    - ncurses
+    - opam
+    - git
+    - gawk
+    - gnupatch
+    - gnum4
+    - gnumake
+    - gnutar
+    - gnused
+    - gnugrep
+    - diffutils
+    - gzip
+    - bzip2
+    - gcc
+    - ocaml
+    - pkg-config
+
+steps:
+  - name: opam
+    command: |
+       opam init --disable-sandboxing -a -y
+  - name: repo
+    command: |
+       opam repo add aoah https://tangled.org/anil.recoil.org/aoah-opam-repo.git
+  - name: switch
+    command: |
+       opam install . --confirm-level=unsafe-yes --deps-only
+  - name: build
+    command: |
+       opam exec -- dune build -p jmap
+  - name: switch-test
+    command: |
+       opam install . --confirm-level=unsafe-yes --deps-only --with-test
+  - name: test
+    command: |
+       opam exec -- dune runtest --verbose
+  - name: doc
+    command: |
+       opam install -y odoc
+       opam exec -- dune build @doc

LICENSE.md

···
+ISC License
+
+Copyright (c) 2025 Anil Madhavapeddy <[e-mail]>
+
+Permission to use, copy, modify, and distribute this software for any
+purpose with or without fee is hereby granted, provided that the above
+copyright notice and this permission notice appear in all copies.
+
+THE SOFTWARE IS PROVIDED "AS IS" AND THE AUTHOR DISCLAIMS ALL WARRANTIES
+WITH REGARD TO THIS SOFTWARE INCLUDING ALL IMPLIED WARRANTIES OF
+MERCHANTABILITY AND FITNESS. IN NO EVENT SHALL THE AUTHOR BE LIABLE FOR
+ANY SPECIAL, DIRECT, INDIRECT, OR CONSEQUENTIAL DAMAGES OR ANY DAMAGES
+WHATSOEVER RESULTING FROM LOSS OF USE, DATA OR PROFITS, WHETHER IN AN
+ACTION OF CONTRACT, NEGLIGENCE OR OTHER TORTIOUS ACTION, ARISING OUT OF
+OR IN CONNECTION WITH THE USE OR PERFORMANCE OF THIS SOFTWARE.

README.md

···
+# ocaml-jmap - JMAP Protocol Implementation for OCaml
+
+A complete implementation of the JSON Meta Application Protocol (JMAP) as specified in RFC 8620 (core) and RFC 8621 (mail).
+
+## Packages
+
+- **jmap** - Core JMAP protocol types and serialization
+- **jmap-eio** - JMAP client using Eio for async I/O
+- **jmap-brr** - JMAP client for browsers using js_of_ocaml
+
+## Key Features
+
+- Full RFC 8620 (JMAP Core) support: sessions, accounts, method calls, and error handling
+- Full RFC 8621 (JMAP Mail) support: mailboxes, emails, threads, identities, and submissions
+- Type-safe API with comprehensive type definitions
+- Multiple backends: Eio for native async, Brr for browser-based clients
+- JSON serialization via jsont
+
+## Usage
+
+```ocaml
+(* Query emails from a mailbox *)
+open Jmap
+
+let query_emails ~client ~account_id ~mailbox_id =
+  let filter = Email.Query.Filter.(in_mailbox mailbox_id) in
+  let query = Email.Query.make ~account_id ~filter () in
+  Client.call client query
+```
+
+## Installation
+
+```
+opam install jmap jmap-eio
+```
+
+For browser-based applications:
+
+```
+opam install jmap jmap-brr
+```
+
+## Documentation
+
+API documentation is available via:
+
+```
+opam install jmap
+odig doc jmap
+```
+
+## License
+
+ISC

bin/jmapq.ml

···
     let doc = "Email IDs to mark as processed" in
     Arg.(non_empty & pos_all string [] & info [] ~docv:"EMAIL_ID" ~doc)
   in
-  let run cfg email_id_strs =
+  let verbose_term =
+    let doc = "Show the raw JMAP server response" in
+    Arg.(value & flag & info ["v"; "verbose"] ~doc)
+  in
+  let run cfg verbose email_id_strs =
     Eio_main.run @@ fun env ->
     Eio.Switch.run @@ fun sw ->
     let client = Jmap_eio.Cli.create_client ~sw env cfg in
···
     Jmap_eio.Cli.debug cfg "Marking %d email(s) with '%s' keyword"
       (List.length email_ids) zulip_processed_keyword;
 
-    (* Build patch to add the zulip-processed keyword *)
+    (* Build patch to add the zulip-processed keyword and mark as read *)
     let patch =
       let open Jmap_eio.Chain in
-      json_obj [("keywords/" ^ zulip_processed_keyword, json_bool true)]
+      json_obj [
+        ("keywords/" ^ zulip_processed_keyword, json_bool true);
+        ("keywords/$seen", json_bool true);
+      ]
     in
 
     (* Build updates list: each email ID gets the same patch *)
···
         Fmt.epr "Error: %s@." (Jmap_eio.Client.error_to_string e);
         exit 1
     | Ok response ->
+        (* Print raw response if verbose *)
+        if verbose then begin
+          Fmt.pr "@[<v>%a:@," Fmt.(styled `Bold string) "Server Response";
+          (match Jsont_bytesrw.encode_string' ~format:Jsont.Indent
+                   Jmap.Proto.Response.jsont response with
+          | Ok json_str -> Fmt.pr "%s@,@]@." json_str
+          | Error e -> Fmt.epr "JSON encoding error: %s@." (Jsont.Error.to_string e))
+        end;
         (* Check for JMAP method-level errors first *)
         let call_id = Jmap_eio.Chain.call_id set_h in
         (match Jmap.Proto.Response.find_response call_id response with
···
               |> List.map (fun (id, _) -> Jmap.Proto.Id.to_string id)
             in
             if List.length updated_ids > 0 then begin
-              Fmt.pr "@[<v>%a %d email(s) with '%s':@,"
+              Fmt.pr "@[<v>%a %d email(s) as read with '%s':@,"
                 Fmt.(styled `Green string) "Marked"
                 (List.length updated_ids)
                 zulip_processed_keyword;
···
     `Pre "  jmapq zulip-timeout StrrDTS_WEa3 StrsGZ7P8Dpc StrsGuCSXJ3Z";
   ] in
   let info = Cmd.info "zulip-timeout" ~doc ~man in
-  Cmd.v info Term.(const run $ Jmap_eio.Cli.config_term $ email_ids_term)
+  Cmd.v info Term.(const run $ Jmap_eio.Cli.config_term $ verbose_term $ email_ids_term)
+
+(** {1 Zulip View Command} *)
+
+let zulip_view_cmd =
+  let json_term =
+    let doc = "Output as JSON" in
+    Arg.(value & flag & info ["json"] ~doc)
+  in
+  let limit_term =
+    let doc = "Maximum number of messages to fetch (default: all)" in
+    Arg.(value & opt (some int) None & info ["limit"; "n"] ~docv:"N" ~doc)
+  in
+  let verbose_term =
+    let doc = "Show the raw JMAP request and response" in
+    Arg.(value & flag & info ["v"; "verbose"] ~doc)
+  in
+  let run cfg json_output limit verbose =
+    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 "Searching for Zulip emails marked as processed";
+
+    (* Build filter for emails from [e-mail] with zulip-processed keyword *)
+    let cond : Jmap.Proto.Email.Filter_condition.t = {
+      in_mailbox = None; 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 = Some zulip_processed_keyword;
+      not_keyword = None;
+      has_attachment = None;
+      text = None;
+      from = Some "[e-mail]";
+      to_ = None;
+      cc = None; bcc = None; subject = None;
+      body = None; header = None;
+    } in
+    let filter = Jmap.Proto.Filter.Condition cond in
+    let sort = [Jmap.Proto.Filter.comparator ~is_ascending:false "receivedAt"] in
+
+    (* Query for processed Zulip emails *)
+    let query_limit = match limit with
+      | Some n -> Int64.of_int n
+      | None -> Int64.of_int 10000
+    in
+    let query_inv = Jmap_eio.Client.Build.email_query
+      ~call_id:"q1"
+      ~account_id
+      ~filter
+      ~sort
+      ~limit:query_limit
+      ()
+    in
+
+    let req = Jmap_eio.Client.Build.(
+      make_request
+        ~capabilities:[Jmap.Proto.Capability.core; Jmap.Proto.Capability.mail]
+        [query_inv]
+    ) in
+
+    (* Print request if verbose *)
+    if verbose then begin
+      Fmt.pr "@[<v>%a:@," Fmt.(styled `Bold string) "Request";
+      (match Jsont_bytesrw.encode_string' ~format:Jsont.Indent
+               Jmap.Proto.Request.jsont req with
+      | Ok json_str -> Fmt.pr "%s@,@]@." json_str
+      | Error e -> Fmt.epr "JSON encoding error: %s@." (Jsont.Error.to_string e))
+    end;
+
+    match Jmap_eio.Client.request client req with
+    | Error e ->
+        Fmt.epr "Error: %s@." (Jmap_eio.Client.error_to_string e);
+        exit 1
+    | Ok response ->
+        (* Print response if verbose *)
+        if verbose then begin
+          Fmt.pr "@[<v>%a:@," Fmt.(styled `Bold string) "Response";
+          (match Jsont_bytesrw.encode_string' ~format:Jsont.Indent
+                   Jmap.Proto.Response.jsont response with
+          | Ok json_str -> Fmt.pr "%s@,@]@." json_str
+          | Error e -> Fmt.epr "JSON encoding error: %s@." (Jsont.Error.to_string e))
+        end;
+        match Jmap_eio.Client.Parse.parse_email_query ~call_id:"q1" response with
+        | Error e ->
+            Fmt.epr "Parse error: %s@." (Jsont.Error.to_string e);
+            exit 1
+        | Ok query_result ->
+            let email_ids = query_result.ids in
+            Jmap_eio.Cli.debug cfg "Found %d processed Zulip email IDs" (List.length email_ids);
+
+            if List.length email_ids = 0 then (
+              if json_output then
+                Fmt.pr "[]@."
+              else
+                Fmt.pr "No Zulip emails marked as processed.@."
+            ) else (
+              (* Fetch email details *)
+              let get_inv = Jmap_eio.Client.Build.email_get
+                ~call_id:"g1"
+                ~account_id
+                ~ids:email_ids
+                ~properties:["id"; "blobId"; "threadId"; "mailboxIds"; "keywords";
+                             "size"; "receivedAt"; "subject"; "from"]
+                ()
+              in
+              let req2 = Jmap_eio.Client.Build.(
+                make_request
+                  ~capabilities:[Jmap.Proto.Capability.core; Jmap.Proto.Capability.mail]
+                  [get_inv]
+              ) in
+
+              match Jmap_eio.Client.request client req2 with
+              | Error e ->
+                  Fmt.epr "Error: %s@." (Jmap_eio.Client.error_to_string e);
+                  exit 1
+              | Ok response2 ->
+                  match Jmap_eio.Client.Parse.parse_email_get ~call_id:"g1" response2 with
+                  | Error e ->
+                      Fmt.epr "Parse error: %s@." (Jsont.Error.to_string e);
+                      exit 1
+                  | Ok get_result ->
+                      (* Parse Zulip subjects and filter successful parses *)
+                      let zulip_messages =
+                        get_result.list
+                        |> List.filter_map Zulip_message.of_email
+                      in
+
+                      Jmap_eio.Cli.debug cfg "Parsed %d Zulip messages from %d emails"
+                        (List.length zulip_messages)
+                        (List.length get_result.list);
+
+                      if json_output then (
+                        (* Output as JSON *)
+                        match Jsont_bytesrw.encode_string' ~format:Jsont.Indent Zulip_message.list_jsont zulip_messages with
+                        | Ok json_str -> Fmt.pr "%s@." json_str
+                        | Error e -> Fmt.epr "JSON encoding error: %s@." (Jsont.Error.to_string e)
+                      ) else (
+                        (* Human-readable output *)
+                        Fmt.pr "@[<v>%a (%d messages)@,@,"
+                          Fmt.(styled `Bold string) "Processed Zulip Notifications"
+                          (List.length zulip_messages);
+
+                        (* Group by server, then by channel *)
+                        let by_server = Hashtbl.create 8 in
+                        List.iter (fun (msg : Zulip_message.t) ->
+                          let existing = try Hashtbl.find by_server msg.server with Not_found -> [] in
+                          Hashtbl.replace by_server msg.server (msg :: existing)
+                        ) zulip_messages;
+
+                        Hashtbl.iter (fun server msgs ->
+                          Fmt.pr "%a [%s]@,"
+                            Fmt.(styled `Bold string) "Server:"
+                            server;
+
+                          (* Group by channel within server *)
+                          let by_channel = Hashtbl.create 8 in
+                          List.iter (fun (msg : Zulip_message.t) ->
+                            let existing = try Hashtbl.find by_channel msg.channel with Not_found -> [] in
+                            Hashtbl.replace by_channel msg.channel (msg :: existing)
+                          ) msgs;
+
+                          Hashtbl.iter (fun channel channel_msgs ->
+                            Fmt.pr "  %a #%s (%d)@,"
+                              Fmt.(styled `Cyan string) "Channel:"
+                              channel
+                              (List.length channel_msgs);
+
+                            (* Sort by date descending *)
+                            let sorted = List.sort (fun a b ->
+                              Ptime.compare b.Zulip_message.date a.Zulip_message.date
+                            ) channel_msgs in
+
+                            List.iter (fun (msg : Zulip_message.t) ->
+                              let read_marker = if msg.is_read then " " else "*" in
+                              let labels_str = match msg.labels with
+                                | [] -> ""
+                                | ls -> " [" ^ String.concat ", " ls ^ "]"
+                              in
+                              Fmt.pr "    %s %s  %a  %s%s@,"
+                                read_marker
+                                (ptime_to_string msg.date)
+                                Fmt.(styled `Yellow string) (truncate_string 40 msg.topic)
+                                (truncate_string 12 msg.id)
+                                labels_str
+                            ) sorted;
+                            Fmt.pr "@,"
+                          ) by_channel
+                        ) by_server;
+
+                        Fmt.pr "@]@."
+                      )
+            )
+  in
+  let doc = "List Zulip emails that have been marked as processed" in
+  let man = [
+    `S Manpage.s_description;
+    `P (Printf.sprintf "Lists all Zulip notification emails that have the '%s' keyword."
+        zulip_processed_keyword);
+    `S Manpage.s_examples;
+    `P "List all processed Zulip notifications:";
+    `Pre "  jmapq zulip-view";
+    `P "Output as JSON:";
+    `Pre "  jmapq zulip-view --json";
+    `P "Limit to 50 most recent:";
+    `Pre "  jmapq zulip-view -n 50";
+  ] in
+  let info = Cmd.info "zulip-view" ~doc ~man in
+  Cmd.v info Term.(const run $ Jmap_eio.Cli.config_term $ json_term $ limit_term $ verbose_term)
 
 (** {1 Main Command Group} *)
 
···
   Cmd.group info [
     zulip_list_cmd;
     zulip_timeout_cmd;
+    zulip_view_cmd;
   ]
 
 let () =

dune-project

···
 
 (generate_opam_files true)
 
-(source
- (github avsm/ocaml-jmap))
+(license ISC)
 
 (authors "Anil Madhavapeddy <[e-mail]>")
 
 (maintainers "Anil Madhavapeddy <[e-mail]>")
 
-(license ISC)
+(homepage "https://tangled.org/@anil.recoil.org/ocaml-jmap")
+
+(bug_reports "https://tangled.org/@anil.recoil.org/ocaml-jmap/issues")
 
-(documentation https://avsm.github.io/ocaml-jmap)
+(maintenance_intent "(latest)")
 
 (package
  (name jmap)

jmap-brr.opam

···
 maintainer: ["Anil Madhavapeddy <[e-mail]>"]
 authors: ["Anil Madhavapeddy <[e-mail]>"]
 license: "ISC"
-homepage: "https://github.com/avsm/ocaml-jmap"
-doc: "https://avsm.github.io/ocaml-jmap"
-bug-reports: "https://github.com/avsm/ocaml-jmap/issues"
+homepage: "https://tangled.org/@anil.recoil.org/ocaml-jmap"
+bug-reports: "https://tangled.org/@anil.recoil.org/ocaml-jmap/issues"
 depends: [
   "dune" {>= "3.20"}
   "ocaml" {>= "5.4.0"}
···
     "@doc" {with-doc}
   ]
 ]
-dev-repo: "git+https://github.com/avsm/ocaml-jmap.git"
 x-maintenance-intent: ["(latest)"]

jmap-eio.opam

···
 maintainer: ["Anil Madhavapeddy <[e-mail]>"]
 authors: ["Anil Madhavapeddy <[e-mail]>"]
 license: "ISC"
-homepage: "https://github.com/avsm/ocaml-jmap"
-doc: "https://avsm.github.io/ocaml-jmap"
-bug-reports: "https://github.com/avsm/ocaml-jmap/issues"
+homepage: "https://tangled.org/@anil.recoil.org/ocaml-jmap"
+bug-reports: "https://tangled.org/@anil.recoil.org/ocaml-jmap/issues"
 depends: [
   "dune" {>= "3.20"}
   "ocaml" {>= "5.4.0"}
···
     "@doc" {with-doc}
   ]
 ]
-dev-repo: "git+https://github.com/avsm/ocaml-jmap.git"
 x-maintenance-intent: ["(latest)"]

jmap.opam

···
 maintainer: ["Anil Madhavapeddy <[e-mail]>"]
 authors: ["Anil Madhavapeddy <[e-mail]>"]
 license: "ISC"
-homepage: "https://github.com/avsm/ocaml-jmap"
-doc: "https://avsm.github.io/ocaml-jmap"
-bug-reports: "https://github.com/avsm/ocaml-jmap/issues"
+homepage: "https://tangled.org/@anil.recoil.org/ocaml-jmap"
+bug-reports: "https://tangled.org/@anil.recoil.org/ocaml-jmap/issues"
 depends: [
   "dune" {>= "3.20"}
   "ocaml" {>= "5.4.0"}
···
     "@doc" {with-doc}
   ]
 ]
-dev-repo: "git+https://github.com/avsm/ocaml-jmap.git"
 x-maintenance-intent: ["(latest)"]

lib/proto/proto_method.ml

···
 
 let set_response_jsont (type a) (obj_jsont : a Jsont.t) : a set_response Jsont.t =
   let kind = "SetResponse" in
+  (* All map/list fields in SetResponse can be null per RFC 8620 Section 5.3 *)
+  (* opt_mem handles missing keys, Jsont.option handles explicit null values *)
+  (* Option.join flattens option option -> option *)
+  let join = Option.join in
   let make account_id old_state new_state created updated destroyed
       not_created not_updated not_destroyed =
-    { account_id; old_state; new_state; created; updated; destroyed;
-      not_created; not_updated; not_destroyed }
+    { account_id; old_state; new_state;
+      created = join created;
+      updated = join updated;
+      destroyed = join destroyed;
+      not_created = join not_created;
+      not_updated = join not_updated;
+      not_destroyed = join not_destroyed }
   in
   (* For updated values, the server may return null or an object - RFC 8620 Section 5.3 *)
   (* "Id[Foo|null]" means map values can be null, use Jsont.option to handle this *)
   let nullable_obj = Jsont.(option obj_jsont) in
+  let opt enc = Option.map Option.some enc in
   Jsont.Object.map ~kind make
   |> Jsont.Object.mem "accountId" Proto_id.jsont ~enc:(fun r -> r.account_id)
   |> Jsont.Object.opt_mem "oldState" Jsont.string ~enc:(fun r -> r.old_state)
   |> Jsont.Object.mem "newState" Jsont.string ~enc:(fun r -> r.new_state)
-  |> Jsont.Object.opt_mem "created" (Proto_json_map.of_id obj_jsont) ~enc:(fun r -> r.created)
-  |> Jsont.Object.opt_mem "updated" (Proto_json_map.of_id nullable_obj) ~enc:(fun r -> r.updated)
-  |> Jsont.Object.opt_mem "destroyed" (Jsont.list Proto_id.jsont) ~enc:(fun r -> r.destroyed)
-  |> Jsont.Object.opt_mem "notCreated" (Proto_json_map.of_id Proto_error.set_error_jsont) ~enc:(fun r -> r.not_created)
-  |> Jsont.Object.opt_mem "notUpdated" (Proto_json_map.of_id Proto_error.set_error_jsont) ~enc:(fun r -> r.not_updated)
-  |> Jsont.Object.opt_mem "notDestroyed" (Proto_json_map.of_id Proto_error.set_error_jsont) ~enc:(fun r -> r.not_destroyed)
+  |> Jsont.Object.opt_mem "created" Jsont.(option (Proto_json_map.of_id obj_jsont)) ~enc:(fun r -> opt r.created)
+  |> Jsont.Object.opt_mem "updated" Jsont.(option (Proto_json_map.of_id nullable_obj)) ~enc:(fun r -> opt r.updated)
+  |> Jsont.Object.opt_mem "destroyed" Jsont.(option (list Proto_id.jsont)) ~enc:(fun r -> opt r.destroyed)
+  |> Jsont.Object.opt_mem "notCreated" Jsont.(option (Proto_json_map.of_id Proto_error.set_error_jsont)) ~enc:(fun r -> opt r.not_created)
+  |> Jsont.Object.opt_mem "notUpdated" Jsont.(option (Proto_json_map.of_id Proto_error.set_error_jsont)) ~enc:(fun r -> opt r.not_updated)
+  |> Jsont.Object.opt_mem "notDestroyed" Jsont.(option (Proto_json_map.of_id Proto_error.set_error_jsont)) ~enc:(fun r -> opt r.not_destroyed)
   |> Jsont.Object.finish
 
 (* Foo/copy *)