My agentic slop goes here. Not intended for anyone else!
anil.recoil.org
1(** JMAP Identity types and operations.
2
3 This module implements the JMAP Identity data type as specified in RFC 8621
4 Section 6. Identity objects represent the user's sending identities - the
5 email addresses and associated metadata (name, signatures, etc.) that can
6 be used when composing and sending email messages.
7
8 Each Identity has an email address and optional display information like
9 name and signatures. Identities are used with EmailSubmission objects to
10 specify which sending identity should be used for a particular message.
11
12 @see <https://www.rfc-editor.org/rfc/rfc8621.html#section-6> RFC 8621, Section 6: Identity
13*)
14
15open Jmap.Error
16
17(** Complete identity object representation.
18
19 Represents a complete Identity object as returned by the server,
20 containing all identity properties including server-computed fields
21 like mayDelete.
22
23 @see <https://www.rfc-editor.org/rfc/rfc8621.html#section-6> RFC 8621, Section 6
24*)
25type t
26
27include Jmap_sigs.JSONABLE with type t := t
28
29(** Pretty printing interface *)
30include Jmap_sigs.PRINTABLE with type t := t
31
32(** JMAP object interface for property selection and object creation *)
33include Jmap_sigs.JMAP_OBJECT with type t := t and type id_type := string
34
35(** Get the server-assigned identity identifier.
36 @return Immutable unique ID (Some for all persisted identities, None only for unsaved objects) *)
37val id : t -> Jmap.Id.t option
38
39(** Get the display name for this identity.
40 @return Human-readable name, empty string if not set *)
41val name : t -> string
42
43(** Get the email address for this identity.
44 @return Immutable email address used for sending *)
45val email : t -> string
46
47(** Get the default Reply-To addresses for this identity.
48 @return List of reply-to addresses, or None if not specified *)
49val reply_to : t -> Address.t list option
50
51(** Get the default Bcc addresses for this identity.
52 @return List of addresses to always Bcc, or None if not specified *)
53val bcc : t -> Address.t list option
54
55(** Get the plain text email signature.
56 @return Text signature to append to plain text messages *)
57val text_signature : t -> string
58
59(** Get the HTML email signature.
60 @return HTML signature to append to HTML messages *)
61val html_signature : t -> string
62
63(** Check if this identity can be deleted by the user.
64 @return Server-computed permission indicating deletability *)
65val may_delete : t -> bool
66
67(** Create a new identity object.
68 @param Jmap.Id.t Server-assigned identity identifier
69 @param name Optional display name (defaults to empty string)
70 @param email Required email address for sending
71 @param reply_to Optional default Reply-To addresses
72 @param bcc Optional default Bcc addresses
73 @param text_signature Optional plain text signature
74 @param html_signature Optional HTML signature
75 @param may_delete Server permission for deletion
76 @return New identity object *)
77val v :
78 id:Jmap.Id.t ->
79 ?name:string ->
80 email:string ->
81 ?reply_to:Address.t list ->
82 ?bcc:Address.t list ->
83 ?text_signature:string ->
84 ?html_signature:string ->
85 may_delete:bool ->
86 unit -> t
87
88(** Identity creation operations.
89
90 Provides types and functions for creating new Identity objects.
91 Creation objects contain only the properties that can be set by
92 the client - server-computed properties are handled separately.
93
94 @see <https://www.rfc-editor.org/rfc/rfc8621.html#section-6.2> RFC 8621, Section 6.2
95*)
96module Create : sig
97 (** Identity creation parameters *)
98 type t
99
100 include Jmap_sigs.JSONABLE with type t := t
101
102 (** Get the display name for creation.
103 @return Optional name, None if not specified *)
104 val name : t -> string option
105
106 (** Get the email address for creation.
107 @return Required email address *)
108 val email : t -> string
109
110 (** Get the Reply-To addresses for creation.
111 @return Optional list of reply-to addresses *)
112 val reply_to : t -> Address.t list option
113
114 (** Get the Bcc addresses for creation.
115 @return Optional list of default Bcc addresses *)
116 val bcc : t -> Address.t list option
117
118 (** Get the plain text signature for creation.
119 @return Optional text signature *)
120 val text_signature : t -> string option
121
122 (** Get the HTML signature for creation.
123 @return Optional HTML signature *)
124 val html_signature : t -> string option
125
126 (** Create identity creation parameters.
127 @param name Optional display name
128 @param email Required email address
129 @param reply_to Optional Reply-To addresses
130 @param bcc Optional default Bcc addresses
131 @param text_signature Optional plain text signature
132 @param html_signature Optional HTML signature
133 @return Identity creation object *)
134 val v :
135 ?name:string ->
136 email:string ->
137 ?reply_to:Address.t list ->
138 ?bcc:Address.t list ->
139 ?text_signature:string ->
140 ?html_signature:string ->
141 unit -> t
142
143 (** Server response for successful identity creation.
144
145 Contains the server-computed properties for a newly created identity,
146 including the assigned ID and deletion permissions.
147
148 @see <https://www.rfc-editor.org/rfc/rfc8621.html#section-6.2> RFC 8621, Section 6.2
149 *)
150 module Response : sig
151 (** Identity creation response *)
152 type t
153
154 include Jmap_sigs.JSONABLE with type t := t
155
156 (** Get the server-assigned ID for the created identity.
157 @return Unique identifier assigned by the server *)
158 val id : t -> Jmap.Id.t
159
160 (** Check if the created identity may be deleted.
161 @return Server-computed permission for future deletion *)
162 val may_delete : t -> bool
163
164 (** Create an identity creation response.
165 @param Jmap.Id.t Server-assigned identity ID
166 @param may_delete Whether the identity can be deleted
167 @return Creation response object *)
168 val v :
169 id:Jmap.Id.t ->
170 may_delete:bool ->
171 unit -> t
172 end
173end
174
175(** Identity update operations.
176
177 Provides types and functions for updating existing Identity objects.
178 Update objects contain only the properties that can be modified by
179 the client - immutable and server-computed properties are handled separately.
180
181 @see <https://www.rfc-editor.org/rfc/rfc8621.html#section-6.3> RFC 8621, Section 6.3
182*)
183module Update : sig
184 (** Identity update patch object.
185
186 JSON Patch object for updating identity properties. All mutable identity
187 properties can be modified: name, replyTo, bcc, textSignature, and
188 htmlSignature. The email address and server-computed properties cannot
189 be changed.
190 *)
191 type t
192
193 include Jmap_sigs.JSONABLE with type t := t
194
195 (** Create an update that sets the display name.
196 @param name New display name (empty string to clear)
197 @return Update patch object *)
198 val set_name : string -> t
199
200 (** Create an update that sets the Reply-To addresses.
201 @param reply_to New Reply-To addresses (None to clear)
202 @return Update patch object *)
203 val set_reply_to : Address.t list option -> t
204
205 (** Create an update that sets the Bcc addresses.
206 @param bcc New default Bcc addresses (None to clear)
207 @return Update patch object *)
208 val set_bcc : Address.t list option -> t
209
210 (** Create an update that sets the plain text signature.
211 @param text_signature New text signature (empty string to clear)
212 @return Update patch object *)
213 val set_text_signature : string -> t
214
215 (** Create an update that sets the HTML signature.
216 @param html_signature New HTML signature (empty string to clear)
217 @return Update patch object *)
218 val set_html_signature : string -> t
219
220 (** Combine multiple update operations.
221 @param updates List of update patches to combine
222 @return Combined update patch object *)
223 val combine : t list -> t
224
225 (** Server response for successful identity update.
226
227 Contains any server-computed properties that may have changed as a result
228 of the update operation. For Identity objects, this is typically empty
229 unless server-side policies affect deletion permissions.
230
231 @see <https://www.rfc-editor.org/rfc/rfc8621.html#section-6.3> RFC 8621, Section 6.3
232 *)
233 module Response : sig
234 (** Identity update response (contains only changed server-set properties) *)
235 type t
236
237 include Jmap_sigs.JSONABLE with type t := t
238
239 (** Check if mayDelete permission has changed.
240 @return New deletion permission if changed, None if unchanged *)
241 val may_delete : t -> bool option
242
243 (** Create update response.
244 @param may_delete New deletion permission if changed
245 @return Update response object *)
246 val v :
247 ?may_delete:bool ->
248 unit -> t
249 end
250end
251
252(** {1 Identity Methods}
253
254 JMAP method argument and response types for Identity operations.
255 Identity objects support get, set, and changes methods but not query
256 (identities are typically small lists fetched entirely).
257*)
258
259(** Arguments for Identity/get method.
260
261 Used to retrieve Identity objects from the server. Since identities
262 are typically small lists, they are usually fetched entirely rather
263 than using specific ID lists or property filtering.
264
265 @see <https://www.rfc-editor.org/rfc/rfc8621.html#section-6.1> RFC 8621, Section 6.1
266*)
267module Get_args : sig
268 (** Identity/get arguments *)
269 type t
270
271 include Jmap_sigs.JSONABLE with type t := t
272
273 (** JMAP method arguments interface *)
274 include Jmap_sigs.METHOD_ARGS with type t := t and type account_id := string
275
276 (** Get the account ID for the operation.
277 @return Account identifier where identities will be retrieved *)
278 val account_id : t -> Jmap.Id.t
279
280 (** Validate get arguments according to JMAP method constraints.
281 @param t Get arguments to validate
282 @return Ok () if valid, Error with description if invalid *)
283 val validate : t -> (unit, string) Result.t
284
285 (** Get the method name for these arguments.
286 @return The JMAP method name "Identity/get" *)
287 val method_name : unit -> string
288
289 (** Get the specific identity IDs to retrieve.
290 @return List of identity IDs, or None to retrieve all identities *)
291 val ids : t -> Jmap.Id.t list option
292
293 (** Get the properties to include in the response.
294 @return List of property names, or None for all properties *)
295 val properties : t -> string list option
296
297 (** Create Identity/get arguments.
298 @param account_id Account where identities are located
299 @param ids Optional list of specific identity IDs to retrieve
300 @param properties Optional list of properties to include
301 @return Identity/get arguments object *)
302 val v :
303 account_id:Jmap.Id.t ->
304 ?ids:Jmap.Id.t list ->
305 ?properties:string list ->
306 unit -> t
307end
308
309(** Response for Identity/get method.
310
311 Contains the retrieved Identity objects along with standard JMAP response
312 metadata including state string for change tracking.
313
314 @see <https://www.rfc-editor.org/rfc/rfc8621.html#section-6.1> RFC 8621, Section 6.1
315*)
316module Get_response : sig
317 (** Identity type for response lists *)
318 type identity = {
319 id : Jmap.Id.t;
320 name : string;
321 email : string;
322 reply_to : Address.t list option;
323 bcc : Address.t list option;
324 text_signature : string;
325 html_signature : string;
326 may_delete : bool;
327 }
328
329 (** Identity/get response *)
330 type t
331
332 include Jmap_sigs.JSONABLE with type t := t
333
334 (** Get the account ID from the response.
335 @return Account identifier where identities were retrieved *)
336 val account_id : t -> Jmap.Id.t
337
338 (** Get the current state string for change tracking.
339 @return State string for use in Identity/changes *)
340 val state : t -> string
341
342 (** Get the list of retrieved Identity objects.
343 @return List of Identity objects that were found *)
344 val list : t -> identity list
345
346 (** Get the list of identity IDs that were not found.
347 @return List of requested IDs that don't exist *)
348 val not_found : t -> Jmap.Id.t list
349
350 (** Create Identity/get response.
351 @param account_id Account where identities were retrieved
352 @param state Current state string
353 @param list Retrieved identity objects
354 @param not_found IDs that were not found
355 @return Identity/get response object *)
356 val v :
357 account_id:Jmap.Id.t ->
358 state:string ->
359 list:identity list ->
360 not_found:Jmap.Id.t list ->
361 unit -> t
362end
363
364(** Arguments for Identity/set method.
365
366 Used to create, update, and destroy Identity objects on the server.
367
368 @see <https://www.rfc-editor.org/rfc/rfc8621.html#section-6.3> RFC 8621, Section 6.3
369*)
370module Set_args : sig
371 (** Identity/set arguments *)
372 type t
373
374 include Jmap_sigs.JSONABLE with type t := t
375
376 (** JMAP method arguments interface *)
377 include Jmap_sigs.METHOD_ARGS with type t := t and type account_id := string
378
379 (** Get the account ID for the operation.
380 @return Account identifier where identities will be modified *)
381 val account_id : t -> Jmap.Id.t
382
383 (** Validate set arguments according to JMAP method constraints.
384 @param t Set arguments to validate
385 @return Ok () if valid, Error with description if invalid *)
386 val validate : t -> (unit, string) Result.t
387
388 (** Get the method name for these arguments.
389 @return The JMAP method name "Identity/set" *)
390 val method_name : unit -> string
391
392 (** Get the if-in-state condition for the operation.
393 @return Expected state string for optimistic concurrency *)
394 val if_in_state : t -> string option
395
396 (** Get the identities to create.
397 @return Map of creation IDs to creation objects *)
398 val create : t -> (string, Create.t) Hashtbl.t option
399
400 (** Get the identities to update.
401 @return Map of identity IDs to update patch objects *)
402 val update : t -> (string, Update.t) Hashtbl.t option
403
404 (** Get the identity IDs to destroy.
405 @return List of identity IDs to delete *)
406 val destroy : t -> Jmap.Id.t list option
407
408 (** Create Identity/set arguments.
409 @param account_id Account where identities will be modified
410 @param if_in_state Optional state string for optimistic concurrency
411 @param create Optional map of identities to create
412 @param update Optional map of identities to update
413 @param destroy Optional list of identity IDs to delete
414 @return Identity/set arguments object *)
415 val v :
416 account_id:Jmap.Id.t ->
417 ?if_in_state:string ->
418 ?create:(string, Create.t) Hashtbl.t ->
419 ?update:(string, Update.t) Hashtbl.t ->
420 ?destroy:Jmap.Id.t list ->
421 unit -> t
422end
423
424(** Response for Identity/set method.
425
426 Contains the results of create, update, and destroy operations
427 along with the new state string for change tracking.
428
429 @see <https://www.rfc-editor.org/rfc/rfc8621.html#section-6.3> RFC 8621, Section 6.3
430*)
431module Set_response : sig
432 (** Identity/set response *)
433 type t
434
435 include Jmap_sigs.JSONABLE with type t := t
436
437 (** Get the account ID from the response.
438 @return Account identifier where identities were modified *)
439 val account_id : t -> Jmap.Id.t
440
441 (** Get the old state string.
442 @return State string before the operations were applied *)
443 val old_state : t -> string
444
445 (** Get the new state string.
446 @return State string after the operations were applied *)
447 val new_state : t -> string
448
449 (** Get the successfully created identities.
450 @return Map of creation IDs to creation response objects *)
451 val created : t -> (string, Create.Response.t) Hashtbl.t
452
453 (** Get the successfully updated identities.
454 @return Map of identity IDs to update response objects *)
455 val updated : t -> (string, Update.Response.t) Hashtbl.t
456
457 (** Get the successfully destroyed identity IDs.
458 @return List of identity IDs that were successfully deleted *)
459 val destroyed : t -> Jmap.Id.t list
460
461 (** Get the identities that could not be created.
462 @return Map of creation IDs to error objects *)
463 val not_created : t -> (string, Set_error.t) Hashtbl.t
464
465 (** Get the identities that could not be updated.
466 @return Map of identity IDs to error objects *)
467 val not_updated : t -> (string, Set_error.t) Hashtbl.t
468
469 (** Get the identities that could not be destroyed.
470 @return Map of identity IDs to error objects *)
471 val not_destroyed : t -> (string, Set_error.t) Hashtbl.t
472
473 (** Create Identity/set response.
474 @param account_id Account where identities were modified
475 @param old_state State string before operations
476 @param new_state State string after operations
477 @param created Successfully created identities
478 @param updated Successfully updated identities
479 @param destroyed Successfully destroyed identity IDs
480 @param not_created Identities that could not be created
481 @param not_updated Identities that could not be updated
482 @param not_destroyed Identities that could not be destroyed
483 @return Identity/set response object *)
484 val v :
485 account_id:Jmap.Id.t ->
486 old_state:string ->
487 new_state:string ->
488 ?created:(string, Create.Response.t) Hashtbl.t ->
489 ?updated:(string, Update.Response.t) Hashtbl.t ->
490 ?destroyed:Jmap.Id.t list ->
491 ?not_created:(string, Set_error.t) Hashtbl.t ->
492 ?not_updated:(string, Set_error.t) Hashtbl.t ->
493 ?not_destroyed:(string, Set_error.t) Hashtbl.t ->
494 unit -> t
495end
496
497(** Arguments for Identity/changes method.
498
499 Used to efficiently sync Identity objects by getting only the changes
500 since a previous known state.
501
502 @see <https://www.rfc-editor.org/rfc/rfc8621.html#section-6.2> RFC 8621, Section 6.2
503*)
504module Changes_args : sig
505 (** Identity/changes arguments *)
506 type t
507
508 include Jmap_sigs.JSONABLE with type t := t
509
510 (** JMAP method arguments interface *)
511 include Jmap_sigs.METHOD_ARGS with type t := t and type account_id := string
512
513 (** Get the account ID for the operation.
514 @return Account identifier where changes will be retrieved *)
515 val account_id : t -> Jmap.Id.t
516
517 (** Validate changes arguments according to JMAP method constraints.
518 @param t Changes arguments to validate
519 @return Ok () if valid, Error with description if invalid *)
520 val validate : t -> (unit, string) Result.t
521
522 (** Get the method name for these arguments.
523 @return The JMAP method name "Identity/changes" *)
524 val method_name : unit -> string
525
526 (** Get the state string to sync from.
527 @return State string from which to get changes *)
528 val since_state : t -> string
529
530 (** Get the maximum number of changes to return.
531 @return Optional limit on the number of changes *)
532 val max_changes : t -> int option
533
534 (** Create Identity/changes arguments.
535 @param account_id Account where changes will be retrieved
536 @param since_state State string to sync from
537 @param max_changes Optional limit on number of changes
538 @return Identity/changes arguments object *)
539 val v :
540 account_id:Jmap.Id.t ->
541 since_state:string ->
542 ?max_changes:int ->
543 unit -> t
544end
545
546(** Response for Identity/changes method.
547
548 Contains the list of changed and removed identity IDs along with
549 the new state string for tracking further changes.
550
551 @see <https://www.rfc-editor.org/rfc/rfc8621.html#section-6.2> RFC 8621, Section 6.2
552*)
553module Changes_response : sig
554 (** Identity/changes response *)
555 type t
556
557 include Jmap_sigs.JSONABLE with type t := t
558
559 (** Get the account ID from the response.
560 @return Account identifier where changes were retrieved *)
561 val account_id : t -> Jmap.Id.t
562
563 (** Get the old state string.
564 @return State string that was passed in since_state *)
565 val old_state : t -> string
566
567 (** Get the new state string.
568 @return Current state string for future changes calls *)
569 val new_state : t -> string
570
571 (** Check if there are more changes available.
572 @return True if there are more changes beyond max_changes limit *)
573 val has_more_changes : t -> bool
574
575 (** Get the list of created or updated identity IDs.
576 @return List of identity IDs that have been created or updated *)
577 val created : t -> Jmap.Id.t list
578
579 (** Get the list of updated identity IDs.
580 @return List of identity IDs that have been updated *)
581 val updated : t -> Jmap.Id.t list
582
583 (** Get the list of destroyed identity IDs.
584 @return List of identity IDs that have been destroyed *)
585 val destroyed : t -> Jmap.Id.t list
586
587 (** Create Identity/changes response.
588 @param account_id Account where changes were retrieved
589 @param old_state State string from the request
590 @param new_state Current state string
591 @param has_more_changes True if more changes available
592 @param created List of created/updated identity IDs
593 @param updated List of updated identity IDs
594 @param destroyed List of destroyed identity IDs
595 @return Identity/changes response object *)
596 val v :
597 account_id:Jmap.Id.t ->
598 old_state:string ->
599 new_state:string ->
600 has_more_changes:bool ->
601 ?created:Jmap.Id.t list ->
602 ?updated:Jmap.Id.t list ->
603 ?destroyed:Jmap.Id.t list ->
604 unit -> t
605end
606
607(** {1 Property System} *)
608
609(** Identity object property identifiers for selective retrieval.
610
611 Property identifiers for Identity objects as specified in RFC 8621 Section 6.
612 These identifiers are used in Identity/get requests to specify which properties
613 should be returned, enabling efficient partial object retrieval.
614
615 @see <https://www.rfc-editor.org/rfc/rfc8621.html#section-6> RFC 8621, Section 6
616*)
617module Property : sig
618 (** Identity object property identifier type.
619
620 Polymorphic variant enumeration of all standard properties available
621 on Identity objects as defined in RFC 8621.
622 *)
623 type t = [
624 | `Id (** Server-assigned unique identifier (immutable, server-set) *)
625 | `Name (** Display name for the "From" field *)
626 | `Email (** Email address for sending (immutable) *)
627 | `ReplyTo (** Default Reply-To addresses *)
628 | `Bcc (** Default Bcc addresses *)
629 | `TextSignature (** Plain text signature for messages *)
630 | `HtmlSignature (** HTML signature for messages *)
631 | `MayDelete (** Whether user can delete this identity (server-set) *)
632 ]
633
634 (** Convert a property to its JMAP protocol string representation.
635
636 @param prop The property to convert
637 @return JMAP protocol string representation *)
638 val to_string : t -> string
639
640 (** Parse a JMAP protocol string into a property variant.
641
642 @param str The protocol string to parse
643 @return Some property if valid, None if unknown *)
644 val of_string : string -> t option
645
646 (** Get all standard identity properties.
647
648 @return Complete list of all defined identity properties *)
649 val all_properties : t list
650
651 (** Convert a list of properties to their string representations.
652
653 @param properties List of property variants
654 @return List of JMAP protocol strings *)
655 val to_string_list : t list -> string list
656
657 (** Parse a list of strings into property variants.
658
659 @param strings List of JMAP protocol strings
660 @return List of parsed property variants (invalid strings ignored) *)
661 val of_string_list : string list -> t list
662
663 (** Get properties commonly needed for identity selection.
664
665 @return List of properties suitable for identity picker displays *)
666 val common_properties : t list
667
668 (** Get properties for full identity display.
669
670 @return Complete list of all properties for detailed identity views *)
671 val detailed_properties : t list
672end