My agentic slop goes here. Not intended for anyone else!
anil.recoil.org
1(** JMAP Mailbox types and operations.
2
3 This module implements the JMAP Mailbox data type as specified in RFC 8621
4 Section 2. Mailboxes represent folders or labels that contain Email objects,
5 providing hierarchical organization and access control.
6
7 Mailboxes have roles (like Inbox, Sent, Trash) that define their purpose,
8 and maintain counts of emails and threads for efficient client updates.
9 All operations support the standard JMAP methods: get, changes, query,
10 queryChanges, and set.
11
12 @see <https://www.rfc-editor.org/rfc/rfc8621.html#section-2> RFC 8621, Section 2: Mailboxes
13*)
14
15open Jmap.Methods
16
17(** Mailbox role identifiers.
18
19 Standard and extended mailbox roles as defined in RFC 8621 and related
20 specifications. Roles indicate the intended purpose of a mailbox and
21 may affect client behavior and server processing.
22
23 @see <https://www.rfc-editor.org/rfc/rfc8621.html#section-2> RFC 8621, Section 2 *)
24type role =
25 | Inbox (** Primary inbox for incoming messages *)
26 | Archive (** Long-term storage for messages no longer in inbox *)
27 | Drafts (** Draft messages being composed by the user *)
28 | Sent (** Messages that have been sent by the user *)
29 | Trash (** Messages that have been deleted (before final removal) *)
30 | Junk (** Messages classified as spam or unwanted *)
31 | Important (** Messages marked as important or high-priority *)
32 | Snoozed (** Messages temporarily hidden until a specific time *)
33 | Scheduled (** Messages scheduled for future delivery *)
34 | Memos (** Messages containing notes, reminders, or memos *)
35 | Other of string (** Server-specific or custom role identifier *)
36 | NoRole (** No specific role assigned to this mailbox *)
37
38(** Mailbox access permissions.
39
40 Defines the operations that the current user is permitted to perform
41 on a specific mailbox. Rights are determined by server-side access
42 control and may vary between users and mailboxes.
43
44 @see <https://www.rfc-editor.org/rfc/rfc8621.html#section-2> RFC 8621, Section 2 *)
45type rights = {
46 may_read_items : bool; (** Permission to read emails in this mailbox *)
47 may_add_items : bool; (** Permission to add emails to this mailbox *)
48 may_remove_items : bool; (** Permission to remove emails from this mailbox *)
49 may_set_seen : bool; (** Permission to modify the $seen keyword *)
50 may_set_keywords : bool; (** Permission to modify other keywords *)
51 may_create_child : bool; (** Permission to create child mailboxes *)
52 may_rename : bool; (** Permission to rename this mailbox *)
53 may_delete : bool; (** Permission to delete this mailbox *)
54 may_submit : bool; (** Permission to submit emails from this mailbox *)
55}
56
57(** Shared mailbox permissions for specific accounts.
58
59 Defines the operations that a specific account is permitted to perform
60 on a shared mailbox. These permissions are more coarse-grained than
61 the regular rights system.
62*)
63type sharing_rights = {
64 may_read : bool; (** Permission to read shared mailbox contents *)
65 may_write : bool; (** Permission to add/modify/remove messages *)
66 may_admin : bool; (** Administrative permissions (share, rename, delete) *)
67}
68
69(** Sharing information for a specific account.
70
71 Represents one account that this mailbox is shared with, including
72 the permissions granted to that account.
73*)
74type sharing_account = {
75 account_id : Jmap.Id.t; (** ID of account this mailbox is shared with *)
76 rights : sharing_rights; (** Permissions granted to the account *)
77}
78
79(** Main Mailbox object representation as defined in
80 {{:https://www.rfc-editor.org/rfc/rfc8621.html#section-2}RFC 8621 Section 2}.
81
82 Represents a mailbox with all its properties as returned by the server.
83 Some properties (marked as server-set) are computed by the server and
84 cannot be modified by clients. *)
85type t
86
87(** Alias for the main mailbox type for use in submodules *)
88type mailbox_t = t
89
90(** JSON serialization interface *)
91include Jmap_sigs.JSONABLE with type t := t
92
93(** Printable representation interface *)
94include Jmap_sigs.PRINTABLE with type t := t
95
96(** JMAP object interface with property selection support *)
97include Jmap_sigs.JMAP_OBJECT with type t := t and type id_type := string
98
99(** {1 Property Accessors} *)
100
101(** Get the server-assigned mailbox identifier.
102 @param mailbox The mailbox object
103 @return Immutable server-assigned identifier (always Some for valid mailboxes) *)
104val id : t -> Jmap.Id.t option
105
106(** Get the server-assigned mailbox identifier directly.
107 @param mailbox The mailbox object
108 @return Immutable server-assigned identifier (guaranteed present) *)
109val mailbox_id : t -> Jmap.Id.t
110
111(** Get the display name for the mailbox.
112 @param mailbox The mailbox object
113 @return Human-readable name for display *)
114val name : t -> string
115
116(** Get the parent mailbox ID for hierarchical organization.
117 @param mailbox The mailbox object
118 @return Parent mailbox ID (None for root level) *)
119val parent_id : t -> Jmap.Id.t option
120
121(** Get the functional role identifier for the mailbox.
122 @param mailbox The mailbox object
123 @return Functional role (None for custom mailboxes) *)
124val role : t -> role option
125
126(** Get the numeric sort order for display positioning.
127 @param mailbox The mailbox object
128 @return Display order hint (default: 0) *)
129val sort_order : t -> Jmap.UInt.t
130
131(** Get the total email count (server-computed).
132 @param mailbox The mailbox object
133 @return Total email count *)
134val total_emails : t -> Jmap.UInt.t
135
136(** Get the unread email count (server-computed).
137 @param mailbox The mailbox object
138 @return Unread email count *)
139val unread_emails : t -> Jmap.UInt.t
140
141(** Get the total thread count (server-computed).
142 @param mailbox The mailbox object
143 @return Total thread count *)
144val total_threads : t -> Jmap.UInt.t
145
146(** Get the unread thread count (server-computed).
147 @param mailbox The mailbox object
148 @return Unread thread count *)
149val unread_threads : t -> Jmap.UInt.t
150
151(** Get the user's access permissions (server-set).
152 @param mailbox The mailbox object
153 @return User's access permissions *)
154val my_rights : t -> rights
155
156(** Get the user's subscription status.
157 @param mailbox The mailbox object
158 @return Whether user is subscribed to this mailbox *)
159val is_subscribed : t -> bool
160
161(** Get the list of accounts this mailbox is shared with.
162 @param mailbox The mailbox object
163 @return List of sharing accounts, or None if not shared *)
164val shared_with : t -> sharing_account list option
165
166(** {1 Smart Constructors} *)
167
168(** Create a complete mailbox object from all required properties.
169
170 This is an extended version of the JMAP_OBJECT create function that allows
171 setting all mailbox properties including server-computed values. Used for
172 constructing complete Mailbox objects from server responses.
173
174 @param Jmap.Id.t Server-assigned identifier
175 @param name Display name
176 @param parent_id Optional parent mailbox
177 @param role Optional functional role
178 @param sort_order Display order (default: 0)
179 @param total_emails Total email count
180 @param unread_emails Unread email count
181 @param total_threads Total thread count
182 @param unread_threads Unread thread count
183 @param my_rights User access permissions
184 @param is_subscribed Subscription status
185 @param shared_with Optional list of accounts this mailbox is shared with
186 @return Ok with mailbox object, or Error with validation message *)
187val create_full :
188 id:Jmap.Id.t ->
189 name:string ->
190 ?parent_id:Jmap.Id.t ->
191 ?role:role ->
192 ?sort_order:Jmap.UInt.t ->
193 total_emails:Jmap.UInt.t ->
194 unread_emails:Jmap.UInt.t ->
195 total_threads:Jmap.UInt.t ->
196 unread_threads:Jmap.UInt.t ->
197 my_rights:rights ->
198 is_subscribed:bool ->
199 ?shared_with:sharing_account list ->
200 unit -> (t, string) result
201
202(** {1 Nested Modules} *)
203
204module Role : sig
205 (** Mailbox role identifiers.
206
207 Standard and extended mailbox roles as defined in RFC 8621 and related
208 specifications. Roles indicate the intended purpose of a mailbox and
209 may affect client behavior and server processing.
210
211 @see <https://www.rfc-editor.org/rfc/rfc8621.html#section-2> RFC 8621, Section 2 *)
212 type t = role
213
214 (** JSON serialization interface *)
215 val to_json : t -> Yojson.Safe.t
216 val of_json : Yojson.Safe.t -> (t, string) Result.t
217
218 (** Primary inbox for incoming messages *)
219 val inbox : t
220
221 (** Long-term storage for messages no longer in inbox *)
222 val archive : t
223
224 (** Draft messages being composed by the user *)
225 val drafts : t
226
227 (** Messages that have been sent by the user *)
228 val sent : t
229
230 (** Messages that have been deleted (before final removal) *)
231 val trash : t
232
233 (** Messages classified as spam or unwanted *)
234 val junk : t
235
236 (** Messages marked as important or high-priority *)
237 val important : t
238
239 (** Messages temporarily hidden until a specific time *)
240 val snoozed : t
241
242 (** Messages scheduled for future delivery *)
243 val scheduled : t
244
245 (** Messages containing notes, reminders, or memos *)
246 val memos : t
247
248 (** No specific role assigned to this mailbox *)
249 val none : t
250
251 (** Server-specific or custom role identifier
252 @param role_name Custom role identifier string *)
253 val other : string -> t
254
255 (** Convert role to JMAP protocol string.
256 @param role The role to convert
257 @return JMAP protocol string representation *)
258 val to_string : t -> string
259
260 (** Parse JMAP protocol string into role.
261 @param str The protocol string to parse
262 @return Ok with role, or Error with parse error *)
263 val of_string : string -> (t, string) result
264
265 (** Get all standard roles with their protocol strings.
266 @return List of (role, protocol string) pairs *)
267 val standard_roles : (t * string) list
268
269 (** Check if role is a standard system role.
270 @param role The role to check
271 @return true if role is one of the standard roles *)
272 val is_standard : t -> bool
273end
274
275module Rights : sig
276 (** Mailbox access permissions.
277
278 Defines the operations that the current user is permitted to perform
279 on a specific mailbox. Rights are determined by server-side access
280 control and may vary between users and mailboxes.
281
282 @see <https://www.rfc-editor.org/rfc/rfc8621.html#section-2> RFC 8621, Section 2 *)
283 type t = rights
284
285 (** JSON serialization interface *)
286 include Jmap_sigs.JSONABLE with type t := t
287
288 (** Permission to read emails in this mailbox *)
289 val may_read_items : t -> bool
290
291 (** Permission to add emails to this mailbox *)
292 val may_add_items : t -> bool
293
294 (** Permission to remove emails from this mailbox *)
295 val may_remove_items : t -> bool
296
297 (** Permission to modify the $seen keyword *)
298 val may_set_seen : t -> bool
299
300 (** Permission to modify other keywords *)
301 val may_set_keywords : t -> bool
302
303 (** Permission to create child mailboxes *)
304 val may_create_child : t -> bool
305
306 (** Permission to rename this mailbox *)
307 val may_rename : t -> bool
308
309 (** Permission to delete this mailbox *)
310 val may_delete : t -> bool
311
312 (** Permission to submit emails from this mailbox *)
313 val may_submit : t -> bool
314
315 (** Create rights object with specified permissions.
316 @param may_read_items Permission to read emails
317 @param may_add_items Permission to add emails
318 @param may_remove_items Permission to remove emails
319 @param may_set_seen Permission to modify $seen keyword
320 @param may_set_keywords Permission to modify other keywords
321 @param may_create_child Permission to create child mailboxes
322 @param may_rename Permission to rename mailbox
323 @param may_delete Permission to delete mailbox
324 @param may_submit Permission to submit emails
325 @return Rights object with specified permissions *)
326 val create :
327 may_read_items:bool ->
328 may_add_items:bool ->
329 may_remove_items:bool ->
330 may_set_seen:bool ->
331 may_set_keywords:bool ->
332 may_create_child:bool ->
333 may_rename:bool ->
334 may_delete:bool ->
335 may_submit:bool ->
336 unit -> t
337
338 (** Create rights with all permissions enabled.
339 @return Rights object with all boolean fields set to true *)
340 val full_access : unit -> t
341
342 (** Create rights with only read permissions.
343 @return Rights object with only may_read_items set to true *)
344 val read_only : unit -> t
345
346 (** Create rights with no permissions.
347 @return Rights object with all boolean fields set to false *)
348 val no_access : unit -> t
349end
350
351module Property : sig
352 (** Mailbox object property identifiers.
353
354 Enumeration of all standard properties available on Mailbox objects.
355 These identifiers are used in Mailbox/get requests to specify which
356 properties should be returned, enabling efficient partial object retrieval.
357
358 @see <https://www.rfc-editor.org/rfc/rfc8621.html#section-2> RFC 8621, Section 2 *)
359 type t
360
361 (** JSON serialization interface *)
362 include Jmap_sigs.JSONABLE with type t := t
363
364 (** Server-assigned unique identifier for the mailbox *)
365 val id : t
366
367 (** Human-readable name for display *)
368 val name : t
369
370 (** Parent mailbox ID for hierarchical organization *)
371 val parent_id : t
372
373 (** Functional role identifier for the mailbox *)
374 val role : t
375
376 (** Numeric sort order for display positioning *)
377 val sort_order : t
378
379 (** Total count of emails in the mailbox (server-set) *)
380 val total_emails : t
381
382 (** Count of unread emails in the mailbox (server-set) *)
383 val unread_emails : t
384
385 (** Total count of conversation threads (server-set) *)
386 val total_threads : t
387
388 (** Count of threads with unread emails (server-set) *)
389 val unread_threads : t
390
391 (** Access rights the current user has (server-set) *)
392 val my_rights : t
393
394 (** Whether user is subscribed to this mailbox *)
395 val is_subscribed : t
396
397 (** Server-specific extension property
398 @param name Property name string *)
399 val other : string -> t
400
401 (** Convert property to JMAP protocol string.
402 @param prop The property to convert
403 @return JMAP protocol string representation *)
404 val to_string : t -> string
405
406 (** Parse JMAP protocol string into property.
407 @param str The protocol string to parse
408 @return Ok with property, or Error with parse error *)
409 val of_string : string -> (t, string) result
410
411 (** Convert property list to string list for API use.
412 @param props List of properties
413 @return List of protocol strings *)
414 val to_string_list : t list -> string list
415
416 (** Get properties commonly needed for mailbox list display.
417 @return List of properties suitable for showing mailbox hierarchies *)
418 val common_properties : t list
419
420 (** Get all standard mailbox properties.
421 @return Complete list of all defined mailbox properties *)
422 val all_properties : t list
423
424 (** Check if a property represents a count field.
425 @param prop The property to check
426 @return true if the property is a server-computed count *)
427 val is_count_property : t -> bool
428end
429
430module Create : sig
431 (** Mailbox creation parameters.
432
433 Contains only the properties that can be set when creating a new mailbox.
434 Server-set properties (ID, counts, rights) are excluded and will be
435 computed by the server upon creation.
436
437 @see <https://www.rfc-editor.org/rfc/rfc8621.html#section-2.5> RFC 8621, Section 2.5 *)
438 type t
439
440 (** JSON serialization interface *)
441 include Jmap_sigs.JSONABLE with type t := t
442
443 (** Create mailbox creation parameters.
444 @param name Required display name for the mailbox
445 @param parent_id Optional parent mailbox for hierarchy
446 @param role Optional functional role assignment
447 @param sort_order Optional display order (default: 0)
448 @param is_subscribed Optional subscription status (default: true)
449 @return Ok with creation object, or Error with validation message *)
450 val create :
451 name:string ->
452 ?parent_id:Jmap.Id.t ->
453 ?role:role ->
454 ?sort_order:Jmap.UInt.t ->
455 ?is_subscribed:bool ->
456 unit -> (t, string) result
457
458 (** Get the display name.
459 @param create_req The creation request
460 @return Display name *)
461 val name : t -> string
462
463 (** Get the parent mailbox ID.
464 @param create_req The creation request
465 @return Optional parent mailbox *)
466 val parent_id : t -> Jmap.Id.t option
467
468 (** Get the role assignment.
469 @param create_req The creation request
470 @return Optional role *)
471 val role : t -> role option
472
473 (** Get the sort order.
474 @param create_req The creation request
475 @return Optional sort order (None means server default) *)
476 val sort_order : t -> Jmap.UInt.t option
477
478 (** Get the subscription status.
479 @param create_req The creation request
480 @return Optional subscription status (None means server default) *)
481 val is_subscribed : t -> bool option
482
483 module Response : sig
484 (** Server response for successful mailbox creation.
485
486 Contains the server-computed properties for a newly created mailbox,
487 along with any defaults that were applied during creation.
488
489 @see <https://www.rfc-editor.org/rfc/rfc8621.html#section-2.5> RFC 8621, Section 2.5 *)
490 type t
491
492 (** JSON serialization interface *)
493 include Jmap_sigs.JSONABLE with type t := t
494
495 (** Get the server-assigned mailbox ID.
496 @param response The creation response
497 @return Server-assigned mailbox ID *)
498 val id : t -> Jmap.Id.t
499
500 (** Get the role if default was applied.
501 @param response The creation response
502 @return Role if default was applied *)
503 val role : t -> role option
504
505 (** Get the sort order if default was applied.
506 @param response The creation response
507 @return Sort order if default was applied *)
508 val sort_order : t -> Jmap.UInt.t
509
510 (** Get the initial email count (typically 0).
511 @param response The creation response
512 @return Initial email count *)
513 val total_emails : t -> Jmap.UInt.t
514
515 (** Get the initial unread count (typically 0).
516 @param response The creation response
517 @return Initial unread count *)
518 val unread_emails : t -> Jmap.UInt.t
519
520 (** Get the initial thread count (typically 0).
521 @param response The creation response
522 @return Initial thread count *)
523 val total_threads : t -> Jmap.UInt.t
524
525 (** Get the initial unread thread count (typically 0).
526 @param response The creation response
527 @return Initial unread thread count *)
528 val unread_threads : t -> Jmap.UInt.t
529
530 (** Get the computed access rights for the user.
531 @param response The creation response
532 @return Computed access rights *)
533 val my_rights : t -> rights
534
535 (** Get the subscription status if default was applied.
536 @param response The creation response
537 @return Subscription status if default was applied *)
538 val is_subscribed : t -> bool
539 end
540end
541
542module Update : sig
543 (** Mailbox update patch object.
544
545 JSON Patch object for updating mailbox properties. Only mutable properties
546 can be modified: name, parentId, role, sortOrder, and isSubscribed.
547 Server-set properties cannot be changed through updates.
548
549 @see <https://www.rfc-editor.org/rfc/rfc8621.html#section-2.5> RFC 8621, Section 2.5 *)
550 type t
551
552 (** JSON serialization interface *)
553 include Jmap_sigs.JSONABLE with type t := t
554
555 (** Create mailbox update patch operations.
556 @param name New display name
557 @param parent_id New parent ID (use Some None to move to root)
558 @param role New role assignment (use Some None to clear role)
559 @param sort_order New sort order
560 @param is_subscribed New subscription status
561 @return JSON Patch operations for Mailbox/set *)
562 val create :
563 ?name:string ->
564 ?parent_id:Jmap.Id.t option ->
565 ?role:role option ->
566 ?sort_order:Jmap.UInt.t ->
567 ?is_subscribed:bool ->
568 unit -> (t, string) result
569
570 (** Create an empty update (no changes).
571 @return Empty update object *)
572 val empty : unit -> t
573
574 module Response : sig
575 (** Server response for successful mailbox update.
576
577 Contains any server-computed properties that may have changed as a result
578 of the update operation. This is typically empty unless server-side effects
579 occurred (such as permission changes affecting rights).
580
581 @see <https://www.rfc-editor.org/rfc/rfc8621.html#section-2.5> RFC 8621, Section 2.5 *)
582 type t
583
584 (** JSON serialization interface *)
585 include Jmap_sigs.JSONABLE with type t := t
586
587 (** Convert updated properties to full mailbox object.
588 @param response The update response
589 @return Full mailbox object with only changed server-set properties *)
590 val to_mailbox : t -> mailbox_t option
591 end
592end
593
594module Query_args : sig
595 (** Mailbox/query arguments as defined in
596 {{:https://www.rfc-editor.org/rfc/rfc8621.html#section-2.3}RFC 8621 Section 2.3}.
597
598 Arguments for querying mailboxes with filtering, sorting, and pagination. *)
599 type t
600
601 (** JSON serialization interface *)
602 include Jmap_sigs.JSONABLE with type t := t
603
604 (** JMAP method arguments interface *)
605 include Jmap_sigs.METHOD_ARGS with type t := t and type account_id := string
606
607 (** Create query arguments for mailboxes.
608 @param account_id Account to query in
609 @param filter Optional filter conditions
610 @param sort Optional sort criteria
611 @param position Starting position (0-based)
612 @param limit Maximum results to return
613 @param calculate_total Whether to calculate total count
614 @return Ok with query arguments, or Error with validation message *)
615 val create :
616 account_id:Jmap.Id.t ->
617 ?filter:Filter.t ->
618 ?sort:Comparator.t list ->
619 ?position:Jmap.UInt.t ->
620 ?limit:Jmap.UInt.t ->
621 ?calculate_total:bool ->
622 unit -> (t, string) result
623
624 (** Get the account ID.
625 @param args Query arguments
626 @return Account identifier where mailboxes will be queried *)
627 val account_id : t -> Jmap.Id.t
628
629 (** Validate query arguments according to JMAP method constraints.
630 @param t Query arguments to validate
631 @return Ok () if valid, Error with description if invalid *)
632 val validate : t -> (unit, string) result
633
634 (** Get the method name for these arguments.
635 @return The JMAP method name "Mailbox/query" *)
636 val method_name : unit -> string
637
638 (** Get the filter conditions.
639 @param args Query arguments
640 @return Optional filter conditions *)
641 val filter : t -> Filter.t option
642
643 (** Get the sort criteria.
644 @param args Query arguments
645 @return Optional sort criteria *)
646 val sort : t -> Comparator.t list option
647
648 (** Get the starting position.
649 @param args Query arguments
650 @return Starting position (0-based) *)
651 val position : t -> Jmap.UInt.t option
652
653 (** Get the result limit.
654 @param args Query arguments
655 @return Maximum results to return *)
656 val limit : t -> Jmap.UInt.t option
657
658 (** Check if total count should be calculated.
659 @param args Query arguments
660 @return Whether to calculate total count *)
661 val calculate_total : t -> bool option
662end
663
664module Query_response : sig
665 (** Mailbox/query response as defined in
666 {{:https://www.rfc-editor.org/rfc/rfc8621.html#section-2.3}RFC 8621 Section 2.3}.
667
668 Response from querying mailboxes containing matched IDs and metadata. *)
669 type t
670
671 (** JSON serialization interface *)
672 include Jmap_sigs.JSONABLE with type t := t
673
674 (** JMAP method response interface *)
675 include Jmap_sigs.METHOD_RESPONSE with type t := t and type account_id := string and type state := string
676
677 (** Get the account ID from the response.
678 @param response Query response
679 @return Account identifier where mailboxes were queried *)
680 val account_id : t -> Jmap.Id.t
681
682 (** Get the query state for change tracking.
683 @param response Query response
684 @return Opaque state string for detecting changes *)
685 val query_state : t -> string
686
687 (** Get the state token for synchronization (alias for query_state).
688 @param response Query response
689 @return State token for change tracking *)
690 val state : t -> string option
691
692 (** Check if this response indicates an error condition.
693 @param response Query response
694 @return false (query responses are success responses) *)
695 val is_error : t -> bool
696
697 (** Check if results can have more items.
698 @param response Query response
699 @return true if more results are available beyond the returned set *)
700 val can_calculate_changes : t -> bool
701
702 (** Get the starting position of results.
703 @param response Query response
704 @return 0-based position of the first returned result *)
705 val position : t -> Jmap.UInt.t
706
707 (** Get the total count if requested.
708 @param response Query response
709 @return Total matching results if calculateTotal was true *)
710 val total : t -> Jmap.UInt.t option
711
712 (** Get the matched mailbox IDs.
713 @param response Query response
714 @return List of mailbox IDs that matched the query *)
715 val ids : t -> Jmap.Id.t list
716end
717
718module Get_args : sig
719 (** Mailbox/get arguments as defined in
720 {{:https://www.rfc-editor.org/rfc/rfc8621.html#section-2.1}RFC 8621 Section 2.1}.
721
722 Arguments for retrieving specific mailbox objects by ID. *)
723 type t
724
725 (** JSON serialization interface *)
726 include Jmap_sigs.JSONABLE with type t := t
727
728 (** JMAP method arguments interface *)
729 include Jmap_sigs.METHOD_ARGS with type t := t and type account_id := string
730
731 (** Create get arguments for mailboxes.
732 @param account_id Account to get from
733 @param ids Optional specific IDs to retrieve (None = all mailboxes)
734 @param properties Optional properties to return (None = all properties)
735 @return Ok with get arguments, or Error with validation message *)
736 val create :
737 account_id:Jmap.Id.t ->
738 ?ids:Jmap.Id.t list ->
739 ?properties:Property.t list ->
740 unit -> (t, string) result
741
742 (** Get the account ID.
743 @param args Get arguments
744 @return Account identifier where mailboxes will be retrieved from *)
745 val account_id : t -> Jmap.Id.t
746
747 (** Validate get arguments according to JMAP method constraints.
748 @param t Get arguments to validate
749 @return Ok () if valid, Error with description if invalid *)
750 val validate : t -> (unit, string) result
751
752 (** Get the method name for these arguments.
753 @return The JMAP method name "Mailbox/get" *)
754 val method_name : unit -> string
755
756 (** Get the specific IDs to retrieve.
757 @param args Get arguments
758 @return Optional list of mailbox IDs (None = all mailboxes) *)
759 val ids : t -> Jmap.Id.t list option
760
761 (** Get the properties to return.
762 @param args Get arguments
763 @return Optional list of properties (None = all properties) *)
764 val properties : t -> Property.t list option
765end
766
767module Get_response : sig
768 (** Mailbox/get response as defined in
769 {{:https://www.rfc-editor.org/rfc/rfc8621.html#section-2.1}RFC 8621 Section 2.1}.
770
771 Response from retrieving mailbox objects. *)
772 type t
773
774 (** JSON serialization interface *)
775 include Jmap_sigs.JSONABLE with type t := t
776
777 (** JMAP method response interface *)
778 include Jmap_sigs.METHOD_RESPONSE with type t := t and type account_id := string and type state := string
779
780 (** Get the account ID from the response.
781 @param response Get response
782 @return Account identifier where mailboxes were retrieved from *)
783 val account_id : t -> Jmap.Id.t
784
785 (** Get the state for change tracking.
786 @param response Get response
787 @return Opaque state string for detecting changes *)
788 val state : t -> string
789
790 (** Check if this response indicates an error condition.
791 @param response Get response
792 @return false (get responses are success responses) *)
793 val is_error : t -> bool
794
795 (** Get the retrieved mailbox objects.
796 @param response Get response
797 @return List of mailbox objects that were found *)
798 val list : t -> mailbox_t list
799
800 (** Get the IDs that were not found.
801 @param response Get response
802 @return List of requested IDs that were not found *)
803 val not_found : t -> Jmap.Id.t list
804end
805
806module Set_args : sig
807 (** Mailbox/set arguments as defined in
808 {{:https://www.rfc-editor.org/rfc/rfc8621.html#section-2.5}RFC 8621 Section 2.5}.
809
810 Arguments for creating, updating, and destroying mailboxes. *)
811 type t
812
813 (** JSON serialization interface *)
814 include Jmap_sigs.JSONABLE with type t := t
815
816 (** JMAP method arguments interface *)
817 include Jmap_sigs.METHOD_ARGS with type t := t and type account_id := string
818
819 (** Create set arguments for mailboxes.
820 @param account_id Account to modify
821 @param if_in_state Optional state constraint
822 @param create Optional mailboxes to create
823 @param update Optional mailboxes to update
824 @param destroy Optional mailboxes to destroy
825 @return Ok with set arguments, or Error with validation message *)
826
827 (** Get the account ID.
828 @param args Set arguments
829 @return Account identifier where mailboxes will be modified *)
830 val account_id : t -> Jmap.Id.t
831
832 (** Validate set arguments according to JMAP method constraints.
833 @param t Set arguments to validate
834 @return Ok () if valid, Error with description if invalid *)
835 val validate : t -> (unit, string) result
836
837 (** Get the method name for these arguments.
838 @return The JMAP method name "Mailbox/set" *)
839 val method_name : unit -> string
840
841 (** Get the state constraint.
842 @param args Set arguments
843 @return Optional state that must match current server state *)
844 val if_in_state : t -> string option
845
846 (** Get the mailboxes to create.
847 @param args Set arguments
848 @return Map of creation IDs to creation objects *)
849 val create : t -> (string * Create.t) list
850
851 (** Get the mailboxes to update.
852 @param args Set arguments
853 @return Map of mailbox IDs to update objects *)
854 val update : t -> (Jmap.Id.t * Update.t) list
855
856 (** Get the mailboxes to destroy.
857 @param args Set arguments
858 @return List of mailbox IDs to destroy *)
859 val destroy : t -> Jmap.Id.t list
860end
861
862module Set_response : sig
863 (** Mailbox/set response as defined in
864 {{:https://www.rfc-editor.org/rfc/rfc8621.html#section-2.5}RFC 8621 Section 2.5}.
865
866 Response from modifying mailboxes. *)
867 type t
868
869 (** JSON serialization interface *)
870 include Jmap_sigs.JSONABLE with type t := t
871
872 (** JMAP method response interface *)
873 include Jmap_sigs.METHOD_RESPONSE with type t := t and type account_id := string and type state := string
874
875 (** Get the account ID from the response.
876 @param response Set response
877 @return Account identifier where mailboxes were modified *)
878 val account_id : t -> Jmap.Id.t
879
880 (** Get the old state before modifications.
881 @param response Set response
882 @return State before any changes were made *)
883 val old_state : t -> string option
884
885 (** Get the new state after modifications.
886 @param response Set response
887 @return State after all changes were applied *)
888 val new_state : t -> string
889
890 (** Get the state token for synchronization (alias for new_state).
891 @param response Set response
892 @return State token for change tracking *)
893 val state : t -> string option
894
895 (** Check if this response indicates an error condition.
896 @param response Set response
897 @return false (set responses are success responses) *)
898 val is_error : t -> bool
899
900 (** Get the successfully created mailboxes.
901 @param response Set response
902 @return Map of creation IDs to creation response objects *)
903 val created : t -> (string * Create.Response.t) list
904
905 (** Get the successfully updated mailboxes.
906 @param response Set response
907 @return Map of mailbox IDs to update response objects *)
908 val updated : t -> (Jmap.Id.t * Update.Response.t) list
909
910 (** Get the successfully destroyed mailbox IDs.
911 @param response Set response
912 @return List of mailbox IDs that were destroyed *)
913 val destroyed : t -> Jmap.Id.t list
914
915 (** Get the creation failures.
916 @param response Set response
917 @return Map of creation IDs to error objects *)
918 val not_created : t -> (string * Jmap.Error.Set_error.t) list
919
920 (** Get the update failures.
921 @param response Set response
922 @return Map of mailbox IDs to error objects *)
923 val not_updated : t -> (Jmap.Id.t * Jmap.Error.Set_error.t) list
924
925 (** Get the destruction failures.
926 @param response Set response
927 @return Map of mailbox IDs to error objects *)
928 val not_destroyed : t -> (Jmap.Id.t * Jmap.Error.Set_error.t) list
929end
930
931module Changes_args : sig
932 (** Mailbox/changes arguments as defined in
933 {{:https://www.rfc-editor.org/rfc/rfc8621.html#section-2.4}RFC 8621 Section 2.4}.
934
935 Arguments for getting changes since a previous state. *)
936 type t
937
938 (** JSON serialization interface *)
939 include Jmap_sigs.JSONABLE with type t := t
940
941 (** JMAP method arguments interface *)
942 include Jmap_sigs.METHOD_ARGS with type t := t and type account_id := string
943
944 (** Create changes arguments for mailboxes.
945 @param account_id Account to check for changes
946 @param since_state State to check changes since
947 @param max_changes Maximum number of changed IDs to return
948 @return Ok with changes arguments, or Error with validation message *)
949 val create :
950 account_id:Jmap.Id.t ->
951 since_state:string ->
952 ?max_changes:Jmap.UInt.t ->
953 unit -> (t, string) result
954
955 (** Get the account ID.
956 @param args Changes arguments
957 @return Account identifier to check for changes *)
958 val account_id : t -> Jmap.Id.t
959
960 (** Validate changes arguments according to JMAP method constraints.
961 @param t Changes arguments to validate
962 @return Ok () if valid, Error with description if invalid *)
963 val validate : t -> (unit, string) result
964
965 (** Get the method name for these arguments.
966 @return The JMAP method name "Mailbox/changes" *)
967 val method_name : unit -> string
968
969 (** Get the since state.
970 @param args Changes arguments
971 @return State to check changes since *)
972 val since_state : t -> string
973
974 (** Get the maximum changes limit.
975 @param args Changes arguments
976 @return Maximum number of changed IDs to return *)
977 val max_changes : t -> Jmap.UInt.t option
978end
979
980module Changes_response : sig
981 (** Mailbox/changes response as defined in
982 {{:https://www.rfc-editor.org/rfc/rfc8621.html#section-2.4}RFC 8621 Section 2.4}.
983
984 Response containing mailbox changes since a previous state. *)
985 type t
986
987 (** JSON serialization interface *)
988 include Jmap_sigs.JSONABLE with type t := t
989
990 (** JMAP method response interface *)
991 include Jmap_sigs.METHOD_RESPONSE with type t := t and type account_id := string and type state := string
992
993 (** Get the account ID from the response.
994 @param response Changes response
995 @return Account identifier where changes were checked *)
996 val account_id : t -> Jmap.Id.t
997
998 (** Get the old state.
999 @param response Changes response
1000 @return State that was checked for changes *)
1001 val old_state : t -> string
1002
1003 (** Get the new state.
1004 @param response Changes response
1005 @return Current state after all changes *)
1006 val new_state : t -> string
1007
1008 (** Get the state token for synchronization (alias for new_state).
1009 @param response Changes response
1010 @return State token for change tracking *)
1011 val state : t -> string option
1012
1013 (** Check if this response indicates an error condition.
1014 @param response Changes response
1015 @return false (changes responses are success responses) *)
1016 val is_error : t -> bool
1017
1018 (** Check if there are more changes beyond returned set.
1019 @param response Changes response
1020 @return true if more changes exist than were returned *)
1021 val has_more_changes : t -> bool
1022
1023 (** Get the created mailbox IDs.
1024 @param response Changes response
1025 @return List of mailbox IDs that were created *)
1026 val created : t -> Jmap.Id.t list
1027
1028 (** Get the updated mailbox IDs.
1029 @param response Changes response
1030 @return List of mailbox IDs that were updated *)
1031 val updated : t -> Jmap.Id.t list
1032
1033 (** Get the destroyed mailbox IDs.
1034 @param response Changes response
1035 @return List of mailbox IDs that were destroyed *)
1036 val destroyed : t -> Jmap.Id.t list
1037end
1038
1039(** {1 Filter Construction}
1040
1041 Helper functions for creating common Mailbox/query filter conditions.
1042 These can be combined with logical operators for complex queries. *)
1043
1044(** Create a filter to match mailboxes with a specific role.
1045 @param role The role to match
1046 @return Filter condition for Mailbox/query *)
1047val filter_has_role : role -> Filter.t
1048
1049(** Create a filter to match mailboxes with no assigned role.
1050 @return Filter condition matching mailboxes where role is null *)
1051val filter_has_no_role : unit -> Filter.t
1052
1053(** Create a filter to match child mailboxes of a specific parent.
1054 @param parent_id The parent mailbox ID to match
1055 @return Filter condition for mailboxes with the specified parent *)
1056val filter_has_parent : Jmap.Id.t -> Filter.t
1057
1058(** Create a filter to match root-level mailboxes.
1059 @return Filter condition matching mailboxes where parentId is null *)
1060val filter_is_root : unit -> Filter.t
1061
1062(** Create a filter to match subscribed mailboxes.
1063 @return Filter condition for mailboxes where isSubscribed is true *)
1064val filter_is_subscribed : unit -> Filter.t
1065
1066(** Create a filter to match unsubscribed mailboxes.
1067 @return Filter condition for mailboxes where isSubscribed is false *)
1068val filter_is_not_subscribed : unit -> Filter.t
1069
1070(** Create a filter to match mailboxes by name substring.
1071 Uses case-insensitive matching to find mailboxes whose names contain
1072 the specified text.
1073 @param text The text to search for in mailbox names
1074 @return Filter condition for name-based matching *)
1075val filter_name_contains : string -> Filter.t