jmap/INDEX.md at jsont · anil.recoil.org/slop

anil.recoil.org / slop
My agentic slop goes here. Not intended for anyone else!
slop / jmap / INDEX.md
at jsont 9.5 kB view raw view rendered
  1# JMAP Implementation - Quick Reference Index
  2
  3## 📚 Documentation
  4
  5| Document | Purpose | Lines |
  6|----------|---------|-------|
  7| [README.md](README.md) | User guide with examples | 450 |
  8| [DESIGN.md](DESIGN.md) | Architecture and design decisions | 800 |
  9| [IMPLEMENTATION_SUMMARY.md](IMPLEMENTATION_SUMMARY.md) | Project completion status | 350 |
 10| [PARSER_IMPLEMENTATION_GUIDE.md](PARSER_IMPLEMENTATION_GUIDE.md) | Guide for completing parsers | 500 |
 11| [INDEX.md](INDEX.md) | This file - quick reference | - |
 12
 13## 🏗️ Project Structure
 14
 15```
 16jmap/
 17├── jmap-core/          Core protocol (RFC 8620)
 18├── jmap-mail/          Mail extension (RFC 8621)
 19├── jmap-client/        HTTP client
 20├── test/               Test suite + 50 JSON files
 21└── spec/               RFC specifications
 22```
 23
 24## 📦 Packages
 25
 26| Package | Purpose | Modules | Status |
 27|---------|---------|---------|--------|
 28| jmap-core | Core JMAP (RFC 8620) | 13 | ✅ Types complete, 🚧 Parsers TODO |
 29| jmap-mail | Mail extension (RFC 8621) | 8 | ✅ Types complete, 🚧 Parsers TODO |
 30| jmap-client | HTTP client | 2 | ✅ Stubs complete |
 31| jmap-test | Test suite | 1 | ✅ Basic harness |
 32
 33## 🔧 Core Modules (jmap-core/)
 34
 35| Module | Lines | Purpose | Key Types |
 36|--------|-------|---------|-----------|
 37| jmap_error.ml | 223 | Error handling | error_level, method_error, set_error |
 38| jmap_id.ml | 47 | ID type | t (abstract) |
 39| jmap_primitives.ml | 121 | Basic types | Int53, UnsignedInt, Date, UTCDate |
 40| jmap_capability.ml | 62 | Capabilities | CoreCapability, MailCapability |
 41| jmap_filter.ml | 72 | Query filters | operator, t (recursive) |
 42| jmap_comparator.ml | 50 | Sort comparators | t |
 43| jmap_standard_methods.ml | 189 | Standard methods | Get, Changes, Set, Copy, Query, QueryChanges, Echo |
 44| jmap_invocation.ml | 159 | Type-safe dispatch | method_witness (GADT), invocation |
 45| jmap_request.ml | 54 | Request object | t |
 46| jmap_response.ml | 55 | Response object | t |
 47| jmap_session.ml | 77 | Session/Account | t, Account.t |
 48| jmap_push.ml | 79 | Push notifications | StateChange, PushSubscription |
 49| jmap_binary.ml | 42 | Binary ops | Upload, BlobCopy |
 50| jmap_parser.ml | 105 | Parser utilities | Helpers module |
 51
 52**Total**: ~1,335 lines
 53
 54## 📧 Mail Modules (jmap-mail/)
 55
 56| Module | Lines | Purpose | Key Types | Methods |
 57|--------|-------|---------|-----------|---------|
 58| jmap_mailbox.ml | 206 | Mailboxes | t, Rights, Filter | Get, Changes, Query, QueryChanges, Set |
 59| jmap_thread.ml | 84 | Thread grouping | t | Get |
 60| jmap_email.ml | 421 | Email messages | t, EmailAddress, BodyPart, BodyValue, Filter | Get, Changes, Query, QueryChanges, Set, Copy, Import, Parse |
 61| jmap_identity.ml | 126 | Identities | t | Get, Changes, Set |
 62| jmap_email_submission.ml | 322 | Email sending | t, Envelope, Address, DeliveryStatus, Filter | Get, Changes, Query, QueryChanges, Set |
 63| jmap_vacation_response.ml | 133 | Out-of-office | t (singleton) | Get, Set |
 64| jmap_search_snippet.ml | 102 | Search highlights | t | Get |
 65| jmap_mail_parser.ml | 240 | Mail parsers | N/A (parsers) | 50+ functions |
 66
 67**Total**: ~1,634 lines
 68
 69## 🌐 Client Modules (jmap-client/)
 70
 71| Module | Lines | Purpose |
 72|--------|-------|---------|
 73| jmap_client.ml | 76 | High-level client |
 74| jmap_connection.ml | 90 | Connection management |
 75
 76**Total**: ~166 lines
 77
 78## 🧪 Test Files (test/data/)
 79
 80### Core Protocol Tests (22 files)
 81
 82| Category | Files | Purpose |
 83|----------|-------|---------|
 84| Echo | 2 | Echo method testing |
 85| Get | 2 | Object retrieval |
 86| Changes | 2 | Delta synchronization |
 87| Set (Create) | 2 | Object creation |
 88| Set (Update) | 2 | Object updates with PatchObject |
 89| Set (Destroy) | 2 | Object deletion |
 90| Copy | 2 | Cross-account copy |
 91| Query | 2 | Querying with filters |
 92| QueryChanges | 2 | Query delta sync |
 93| Session | 1 | Session object |
 94| Push | 2 | Push notifications |
 95| Errors | 1 | Error responses |
 96
 97### Mail Protocol Tests (28 files)
 98
 99| Type | Files | Purpose |
100|------|-------|---------|
101| Mailbox | 6 | Mailbox hierarchy, Get/Query/Set |
102| Thread | 2 | Thread grouping |
103| Email (Basic) | 2 | Basic email properties |
104| Email (Full) | 2 | Complete MIME structure |
105| Email Query | 2 | Email search |
106| Email Set | 2 | Email creation/update |
107| Email Import | 2 | Import from blobs |
108| Email Parse | 2 | Parse without importing |
109| SearchSnippet | 2 | Search highlighting |
110| Identity | 2 | Identity management |
111| EmailSubmission | 2 | Email sending |
112| VacationResponse | 2 | Out-of-office |
113
114**Total**: 50 files, ~224KB
115
116## 🔑 Key Types Reference
117
118### Core Types
119
120```ocaml
121(* IDs and Primitives *)
122Jmap_id.t                           (* 1-255 char string *)
123Jmap_primitives.Int53.t             (* -2^53+1 to 2^53-1 *)
124Jmap_primitives.UnsignedInt.t      (* 0 to 2^53-1 *)
125Jmap_primitives.Date.t             (* RFC 3339 date-time *)
126Jmap_primitives.UTCDate.t          (* RFC 3339 with Z *)
127
128(* Protocol *)
129Jmap_request.t                      (* API request *)
130Jmap_response.t                     (* API response *)
131Jmap_session.t                      (* Session info *)
132Jmap_invocation.invocation         (* Method call *)
133
134(* Queries *)
135Jmap_filter.t                       (* AND/OR/NOT filters *)
136Jmap_comparator.t                   (* Sort comparator *)
137```
138
139### Mail Types
140
141```ocaml
142(* Objects *)
143Jmap_mailbox.t                      (* Mailbox (11 props) *)
144Jmap_thread.t                       (* Thread (2 props) *)
145Jmap_email.t                        (* Email (24 props) *)
146Jmap_identity.t                     (* Identity (8 props) *)
147Jmap_email_submission.t             (* Submission (10 props) *)
148Jmap_vacation_response.t            (* Vacation (7 props) *)
149Jmap_search_snippet.t               (* Snippet (3 props) *)
150
151(* Nested Types *)
152Jmap_mailbox.Rights.t               (* 9 permission flags *)
153Jmap_email.EmailAddress.t           (* name, email *)
154Jmap_email.BodyPart.t               (* Recursive MIME *)
155Jmap_email_submission.Envelope.t    (* SMTP envelope *)
156```
157
158### Method Types
159
160```ocaml
161(* Standard Methods *)
162'a Jmap_standard_methods.Get.request
163'a Jmap_standard_methods.Get.response
164Jmap_standard_methods.Changes.request
165Jmap_standard_methods.Changes.response
166'a Jmap_standard_methods.Set.request
167'a Jmap_standard_methods.Set.response
168'a Jmap_standard_methods.Copy.request
169'a Jmap_standard_methods.Copy.response
170'f Jmap_standard_methods.Query.request
171Jmap_standard_methods.Query.response
172'f Jmap_standard_methods.QueryChanges.request
173Jmap_standard_methods.QueryChanges.response
174Jmap_standard_methods.Echo.t
175
176(* Extended Methods *)
177Jmap_email.Import.request
178Jmap_email.Import.response
179Jmap_email.Parse.request
180Jmap_email.Parse.response
181```
182
183## 📖 RFC References
184
185| Spec | Title | Coverage |
186|------|-------|----------|
187| RFC 8620 | JMAP Core | ✅ Complete |
188| RFC 8621 | JMAP for Mail | ✅ Complete |
189| RFC 3339 | Date/Time | ✅ Date, UTCDate |
190| RFC 5322 | Email Format | ✅ Email parsing |
191| RFC 6154 | Mailbox Roles | ✅ Mailbox.Role |
192
193## 🎯 Implementation Status
194
195### ✅ Complete
196
197- Type definitions (100% complete)
198- Module structure
199- Documentation
200- Test JSON files
201- Error handling types
202- GADT method dispatch
203- Client stubs
204
205### 🚧 TODO (Marked in code)
206
207- JSON parsing (`of_json` functions)
208- JSON serialization (`to_json` functions)
209- HTTP client completion
210- Test suite expansion
211
212## 🚀 Quick Start
213
214### For Users
215
216```bash
217# Install
218opam install jmap-core jmap-mail jmap-client
219
220# Use
221open Jmap_core
222open Jmap_mail
223let client = Jmap_client.create ~session_url:"..." ()
224```
225
226### For Contributors
227
228```bash
229# Clone and build
230cd jmap
231dune build
232
233# Implement parsers (see PARSER_IMPLEMENTATION_GUIDE.md)
234# Start with: jmap-core/jmap_comparator.ml
235
236# Test
237dune test
238
239# Validate
240dune build @check
241```
242
243## 📊 Statistics
244
245| Metric | Count |
246|--------|-------|
247| Total OCaml lines | 3,500+ |
248| Modules | 23 |
249| Submodules | 45+ |
250| Type definitions | 100+ |
251| JSON test files | 50 |
252| Test data size | 224KB |
253| Documentation | 2,200+ lines |
254| RFC sections covered | 100+ |
255
256## 🔗 Links
257
258- [JMAP Website](https://jmap.io/)
259- [RFC 8620 (Core)](https://www.rfc-editor.org/rfc/rfc8620.html)
260- [RFC 8621 (Mail)](https://www.rfc-editor.org/rfc/rfc8621.html)
261- [JMAP Test Suite](https://github.com/jmapio/jmap-test-suite)
262
263## 💡 Common Tasks
264
265| Task | Command |
266|------|---------|
267| Build | `dune build` |
268| Test | `dune test` |
269| Install | `dune install` |
270| Clean | `dune clean` |
271| Format | `dune fmt` |
272| Check types | `dune build @check` |
273| Generate docs | `dune build @doc` |
274
275## 📝 Code Examples
276
277See [README.md](README.md) for:
278- Session fetching
279- Querying mailboxes
280- Searching emails
281- Creating emails
282- Complex filters
283- Uploading attachments
284
285## 🆘 Getting Help
286
2871. Check test JSON files for expected structure
2882. Read [PARSER_IMPLEMENTATION_GUIDE.md](PARSER_IMPLEMENTATION_GUIDE.md)
2893. Review existing parsers (jmap_id.ml, jmap_primitives.ml)
2904. Look at type definitions in module interfaces
2915. Use `Jmap_parser.Helpers` utilities
292
293## 🎓 Learning Path
294
2951. Read [DESIGN.md](DESIGN.md) - Understand architecture
2962. Review [README.md](README.md) - Learn usage patterns
2973. Study test files - See JSON structure
2984. Read [PARSER_IMPLEMENTATION_GUIDE.md](PARSER_IMPLEMENTATION_GUIDE.md) - Implementation details
2995. Start coding - Begin with simple parsers
300
301---
302
303**Last Updated**: 2025
304**Version**: 0.1.0
305**Status**: Types complete, parsers TODO