jon.recoil.org
forked from
anil.recoil.org/ocaml-jmap
this repo has no description
1(*---------------------------------------------------------------------------
2 Copyright (c) 2025 Anil Madhavapeddy. All rights reserved.
3 SPDX-License-Identifier: ISC
4 ---------------------------------------------------------------------------*)
5
6(** Mailbox type as defined in RFC 8621 Section 2
7
8 @canonical Jmap.Proto.Mailbox *)
9
10(** {1 Mailbox Properties}
11
12 Polymorphic variants for type-safe property selection in Mailbox/get requests.
13 These correspond to the properties defined in RFC 8621 Section 2. *)
14
15(** All Mailbox properties that can be requested. *)
16type property = [
17 | `Id
18 | `Name
19 | `Parent_id
20 | `Role
21 | `Sort_order
22 | `Total_emails
23 | `Unread_emails
24 | `Total_threads
25 | `Unread_threads
26 | `My_rights
27 | `Is_subscribed
28]
29
30val property_to_string : [< property ] -> string
31(** Convert a property to its wire name (e.g., [`Parent_id] -> "parentId"). *)
32
33val property_of_string : string -> property option
34(** Parse a property name, case-sensitive. *)
35
36(** {1 Mailbox Rights} *)
37
38(** Rights the user has on a mailbox. *)
39module Rights : sig
40 type t = {
41 may_read_items : bool;
42 may_add_items : bool;
43 may_remove_items : bool;
44 may_set_seen : bool;
45 may_set_keywords : bool;
46 may_create_child : bool;
47 may_rename : bool;
48 may_delete : bool;
49 may_submit : bool;
50 }
51
52 val may_read_items : t -> bool
53 val may_add_items : t -> bool
54 val may_remove_items : t -> bool
55 val may_set_seen : t -> bool
56 val may_set_keywords : t -> bool
57 val may_create_child : t -> bool
58 val may_rename : t -> bool
59 val may_delete : t -> bool
60 val may_submit : t -> bool
61
62 val jsont : t Jsont.t
63end
64
65(** {1 Standard Roles} *)
66
67(** Standard mailbox roles per RFC 8621 Section 2 and draft-ietf-mailmaint. *)
68type role = [
69 | `All
70 | `Archive
71 | `Drafts
72 | `Flagged
73 | `Important
74 | `Inbox
75 | `Junk
76 | `Sent
77 | `Subscribed
78 | `Trash
79 | `Snoozed (** draft-ietf-mailmaint: Messages snoozed until a later time. *)
80 | `Scheduled (** draft-ietf-mailmaint: Messages scheduled to send. *)
81 | `Memos (** draft-ietf-mailmaint: Messages with the $memo keyword. *)
82 | `Other of string
83]
84
85val role_to_string : role -> string
86val role_of_string : string -> role
87val role_jsont : role Jsont.t
88
89(** {2 Conversion to/from mail-flag} *)
90
91val role_of_special_use : Mail_flag.Mailbox_attr.special_use -> role
92(** [role_of_special_use su] converts a mail-flag special-use attribute to a JMAP role. *)
93
94val special_use_of_role : role -> Mail_flag.Mailbox_attr.special_use option
95(** [special_use_of_role r] converts a JMAP role to a mail-flag special-use attribute.
96 Returns [None] for [`Other _] roles that don't correspond to standard special-use values. *)
97
98(** {1 Mailbox} *)
99
100type t = {
101 id : Proto_id.t option;
102 (** Server-assigned mailbox id. *)
103 name : string option;
104 (** User-visible name (UTF-8). *)
105 parent_id : Proto_id.t option;
106 (** Id of parent mailbox, or [None] for root. Note: [None] can mean
107 either "not requested" or "top-level mailbox". *)
108 role : role option;
109 (** Standard role, if any. Note: [None] can mean either "not requested"
110 or "no role assigned". *)
111 sort_order : int64 option;
112 (** Sort order hint (lower = displayed first). *)
113 total_emails : int64 option;
114 (** Total number of emails in mailbox. *)
115 unread_emails : int64 option;
116 (** Number of unread emails. *)
117 total_threads : int64 option;
118 (** Total number of threads. *)
119 unread_threads : int64 option;
120 (** Number of threads with unread emails. *)
121 my_rights : Rights.t option;
122 (** User's rights on this mailbox. *)
123 is_subscribed : bool option;
124 (** Whether user is subscribed to this mailbox. *)
125}
126
127val id : t -> Proto_id.t option
128val name : t -> string option
129val parent_id : t -> Proto_id.t option
130val role : t -> role option
131val sort_order : t -> int64 option
132val total_emails : t -> int64 option
133val unread_emails : t -> int64 option
134val total_threads : t -> int64 option
135val unread_threads : t -> int64 option
136val my_rights : t -> Rights.t option
137val is_subscribed : t -> bool option
138
139val jsont : t Jsont.t
140
141(** {1 Mailbox Filter Conditions} *)
142
143(** Filter conditions for Mailbox/query. *)
144module Filter_condition : sig
145 type t = {
146 parent_id : Proto_id.t option option;
147 (** Filter by parent. [Some None] = top-level only. *)
148 name : string option;
149 (** Filter by exact name match. *)
150 role : role option option;
151 (** Filter by role. [Some None] = no role. *)
152 has_any_role : bool option;
153 (** Filter by whether mailbox has any role. *)
154 is_subscribed : bool option;
155 (** Filter by subscription status. *)
156 }
157
158 val jsont : t Jsont.t
159end