My agentic slop goes here. Not intended for anyone else!
anil.recoil.org
1# JMAP OCaml Module Structure
2
3## Overview
4
5The JMAP libraries use proper OCaml module wrapping with module aliases for re-export. This provides a clean namespace while allowing both qualified and unqualified access to submodules.
6
7## Library Structure
8
9### jmap-core
10
11**Top-level module:** `Jmap_core`
12
13**Submodules (re-exported):**
14- `Jmap_core.Jmap_error` - Error types and exceptions
15- `Jmap_core.Jmap_id` - JMAP ID type
16- `Jmap_core.Jmap_primitives` - Primitive types (Int53, UnsignedInt, Date, UTCDate)
17- `Jmap_core.Jmap_capability` - Server capabilities
18- `Jmap_core.Jmap_filter` - Generic filter combinators
19- `Jmap_core.Jmap_comparator` - Sort comparators
20- `Jmap_core.Jmap_standard_methods` - Standard JMAP methods (Get, Set, Query, etc.)
21- `Jmap_core.Jmap_invocation` - Type-safe method invocations (GADT-based)
22- `Jmap_core.Jmap_request` - JMAP request wrapper
23- `Jmap_core.Jmap_response` - JMAP response wrapper
24- `Jmap_core.Jmap_session` - Session discovery
25- `Jmap_core.Jmap_push` - Push notifications
26- `Jmap_core.Jmap_binary` - Binary data operations
27- `Jmap_core.Jmap_parser` - JSON parsing helpers
28
29### jmap-mail
30
31**Top-level module:** `Jmap_mail`
32
33**Submodules (re-exported):**
34- `Jmap_mail.Jmap_mailbox` - Mailbox type and operations
35- `Jmap_mail.Jmap_thread` - Thread type and operations
36- `Jmap_mail.Jmap_email` - Email type and operations
37- `Jmap_mail.Jmap_identity` - Identity type and operations
38- `Jmap_mail.Jmap_email_submission` - Email submission type and operations
39- `Jmap_mail.Jmap_vacation_response` - Vacation response type and operations
40- `Jmap_mail.Jmap_search_snippet` - Search snippet type and operations
41- `Jmap_mail.Jmap_mail_parser` - Mail-specific JSON parsing
42
43### jmap-client
44
45**Top-level module:** `Jmap_client`
46
47**Files:**
48- `Jmap_client` - HTTP client (stub implementation)
49- `Jmap_connection` - Connection management (stub implementation)
50
51## Usage Patterns
52
53### Pattern 1: Qualified Access
54
55```ocaml
56let id = Jmap_core.Jmap_id.of_string "abc123"
57let mailbox = Jmap_mail.Jmap_mailbox.v
58 ~id ~name:"Inbox"
59 ~sort_order:(Jmap_core.Jmap_primitives.UnsignedInt.of_int 0)
60 ...
61```
62
63### Pattern 2: Open for Direct Access
64
65```ocaml
66open Jmap_core
67open Jmap_mail
68
69let id = Jmap_id.of_string "abc123"
70let mailbox = Jmap_mailbox.v
71 ~id ~name:"Inbox"
72 ~sort_order:(Jmap_primitives.UnsignedInt.of_int 0)
73 ...
74```
75
76### Pattern 3: Mixed (Recommended)
77
78```ocaml
79(* Open Jmap_core for common types *)
80open Jmap_core
81
82(* Use qualified names for specific modules *)
83let mailbox = Jmap_mail.Jmap_mailbox.v
84 ~id:(Jmap_id.of_string "inbox")
85 ~name:"Inbox"
86 ...
87```
88
89## Benefits of This Structure
90
911. **Namespace Control**: All modules are under `Jmap_core` or `Jmap_mail`, avoiding name collisions
922. **Flexible Access**: Use qualified or unqualified names as needed
933. **Clear Dependencies**: Module hierarchy reflects the protocol structure
944. **Standard Practice**: Follows OCaml best practices for library design
955. **Tool Compatibility**: Works well with merlin, ocamllsp, and other OCaml tools
96
97## Building
98
99```bash
100dune build
101```
102
103## Testing
104
105```bash
106dune test
107```
108
109## Installation
110
111```bash
112dune install
113```
114
115This will install three packages:
116- `jmap-core` - Core JMAP protocol (RFC 8620)
117- `jmap-mail` - Mail extension (RFC 8621)
118- `jmap-client` - HTTP client (stub)