My agentic slop goes here. Not intended for anyone else!
anil.recoil.org
1(** JMAP Vacation Response types and operations.
2
3 This module implements the JMAP VacationResponse data type as specified in
4 RFC 8621 Section 8. VacationResponse objects represent automatic email
5 reply systems (out-of-office messages) that can be enabled and configured
6 by users.
7
8 VacationResponse is a singleton object (only one per account) with the
9 fixed ID "singleton". It supports get and set operations but not create,
10 destroy, query, or changes methods.
11
12 @see <https://www.rfc-editor.org/rfc/rfc8621.html#section-8> RFC 8621, Section 8: VacationResponse
13*)
14
15open Jmap.Error
16
17(** Complete VacationResponse object representation.
18
19 Represents the user's vacation/out-of-office auto-reply configuration.
20 This is a singleton object with the fixed ID "singleton" - there is
21 exactly one VacationResponse per account.
22
23 The vacation response can be enabled/disabled and configured with
24 Date.t ranges, custom subject, and message content in both text and HTML.
25
26 @see <https://www.rfc-editor.org/rfc/rfc8621.html#section-8> RFC 8621, Section 8
27*)
28type t
29
30(** Type alias for VacationResponse objects used in submodules *)
31type vacation_response = t
32
33(** JSON serialization interface *)
34include Jmap_sigs.JSONABLE with type t := t
35
36(** Printable formatting interface *)
37include Jmap_sigs.PRINTABLE with type t := t
38
39(** JMAP object interface for property-based operations *)
40include Jmap_sigs.JMAP_OBJECT with type t := t and type id_type := string
41
42(** Get the vacation response ID.
43 @return Always returns "singleton" for VacationResponse objects *)
44val id : t -> Jmap.Id.t option
45
46(** Check if the vacation response is currently enabled.
47 @return true if auto-replies are active *)
48val is_enabled : t -> bool
49
50(** Get the start Date.t for the vacation period.
51 @return Optional start Date.t, None means no start constraint *)
52val from_date : t -> Jmap.Date.t option
53
54(** Get the end Date.t for the vacation period.
55 @return Optional end Date.t, None means no end constraint *)
56val to_date : t -> Jmap.Date.t option
57
58(** Get the custom subject line for vacation replies.
59 @return Optional subject override, None uses default subject *)
60val subject : t -> string option
61
62(** Get the plain text vacation message body.
63 @return Optional text message content *)
64val text_body : t -> string option
65
66(** Get the HTML vacation message body.
67 @return Optional HTML message content *)
68val html_body : t -> string option
69
70(** Create a VacationResponse object.
71 @param Jmap.Id.t Must be "singleton" for VacationResponse objects
72 @param is_enabled Whether vacation replies are active
73 @param from_date Optional start Date.t for vacation period
74 @param to_date Optional end Date.t for vacation period
75 @param subject Optional custom subject line
76 @param text_body Optional plain text message content
77 @param html_body Optional HTML message content
78 @return New VacationResponse object *)
79val v :
80 id:Jmap.Id.t ->
81 is_enabled:bool ->
82 ?from_date:Jmap.Date.t ->
83 ?to_date:Jmap.Date.t ->
84 ?subject:string ->
85 ?text_body:string ->
86 ?html_body:string ->
87 unit ->
88 t
89
90(** VacationResponse update operations.
91
92 Provides types and functions for updating VacationResponse objects.
93 Update objects contain patches for mutable properties: isEnabled,
94 fromDate, toDate, subject, textBody, and htmlBody.
95
96 @see <https://www.rfc-editor.org/rfc/rfc8621.html#section-8.2> RFC 8621, Section 8.2
97*)
98module Update : sig
99 (** VacationResponse update parameters *)
100 type t
101
102 (** JSON serialization interface *)
103 val to_json : t -> Yojson.Safe.t
104 val of_json : Yojson.Safe.t -> (t, string) Result.t
105
106 (** Check if the vacation response should be enabled.
107 @return Optional enabled flag for update *)
108 val is_enabled : t -> bool option
109
110 (** Get the start Date.t update.
111 @return Optional start Date.t change *)
112 val from_date : t -> Jmap.Date.t option option
113
114 (** Get the end Date.t update.
115 @return Optional end Date.t change *)
116 val to_date : t -> Jmap.Date.t option option
117
118 (** Get the subject line update.
119 @return Optional subject change *)
120 val subject : t -> string option option
121
122 (** Get the plain text message body update.
123 @return Optional text body change *)
124 val text_body : t -> string option option
125
126 (** Get the HTML message body update.
127 @return Optional HTML body change *)
128 val html_body : t -> string option option
129
130 (** Create VacationResponse update parameters.
131 @param is_enabled Optional enabled flag update
132 @param from_date Optional start Date.t update
133 @param to_date Optional end Date.t update
134 @param subject Optional subject update
135 @param text_body Optional text body update
136 @param html_body Optional HTML body update
137 @return Update parameters *)
138 val v :
139 ?is_enabled:bool ->
140 ?from_date:Jmap.Date.t option ->
141 ?to_date:Jmap.Date.t option ->
142 ?subject:string option ->
143 ?text_body:string option ->
144 ?html_body:string option ->
145 unit -> t
146
147 (** Create an update to enable vacation responses.
148 @param from_date Optional start Date.t for vacation period
149 @param to_date Optional end Date.t for vacation period
150 @param subject Optional custom subject line
151 @param text_body Optional text message content
152 @param html_body Optional HTML message content
153 @return Update to enable vacation with specified settings *)
154 val enable :
155 ?from_date:Jmap.Date.t ->
156 ?to_date:Jmap.Date.t ->
157 ?subject:string ->
158 ?text_body:string ->
159 ?html_body:string ->
160 unit -> t
161
162 (** Create an update to disable vacation responses.
163 @return Update to disable vacation responses *)
164 val disable : unit -> t
165end
166
167(** {1 VacationResponse Methods}
168
169 JMAP method argument and response types for VacationResponse operations.
170 VacationResponse supports get and set methods but not create, destroy,
171 query, or changes (it's a singleton object with fixed ID "singleton").
172*)
173
174(** Arguments for VacationResponse/get method.
175
176 Used to retrieve the VacationResponse singleton object. Since VacationResponse
177 is a singleton, the ids parameter should contain ["singleton"] or be omitted
178 to retrieve the single VacationResponse object.
179
180 @see <https://www.rfc-editor.org/rfc/rfc8621.html#section-8.1> RFC 8621, Section 8.1
181*)
182module Get_args : sig
183 (** VacationResponse/get arguments *)
184 type t
185
186 include Jmap_sigs.JSONABLE with type t := t
187
188 (** Get the account ID for the operation.
189 @return Account identifier where vacation response will be retrieved *)
190 val account_id : t -> Jmap.Id.t
191
192 (** Get the specific vacation response IDs to retrieve.
193 @return List should be ["singleton"] or None for the singleton object *)
194 val ids : t -> Jmap.Id.t list option
195
196 (** Get the properties to include in the response.
197 @return List of property names, or None for all properties *)
198 val properties : t -> string list option
199
200 (** Create VacationResponse/get arguments.
201 @param account_id Account where vacation response is configured
202 @param ids Should be ["singleton"] or omitted for VacationResponse
203 @param properties Optional list of properties to retrieve
204 @return VacationResponse/get arguments *)
205 val v :
206 account_id:Jmap.Id.t ->
207 ?ids:Jmap.Id.t list ->
208 ?properties:string list ->
209 unit -> t
210
211 (** Create get arguments for the singleton vacation response.
212 @param account_id Account where vacation response is configured
213 @param properties Optional list of properties to retrieve
214 @return Arguments configured for singleton retrieval *)
215 val singleton :
216 account_id:Jmap.Id.t ->
217 ?properties:string list ->
218 unit -> t
219end
220
221(** Response for VacationResponse/get method.
222
223 Contains the retrieved VacationResponse singleton object along with
224 standard JMAP response metadata. The list should contain at most one
225 VacationResponse object (the singleton).
226
227 @see <https://www.rfc-editor.org/rfc/rfc8621.html#section-8.1> RFC 8621, Section 8.1
228*)
229module Get_response : sig
230 (** VacationResponse/get response *)
231 type t
232
233 include Jmap_sigs.JSONABLE with type t := t
234
235 (** Get the account ID from the response.
236 @return Account identifier where vacation response was retrieved *)
237 val account_id : t -> Jmap.Id.t
238
239 (** Get the current state string for change tracking.
240 @return State string for use in VacationResponse/set *)
241 val state : t -> string
242
243 (** Get the list of retrieved VacationResponse objects.
244 @return List containing the singleton VacationResponse (or empty) *)
245 val list : t -> vacation_response list
246
247 (** Get the list of vacation response IDs that were not found.
248 @return List of requested IDs that don't exist *)
249 val not_found : t -> Jmap.Id.t list
250
251 (** Create VacationResponse/get response.
252 @param account_id Account where vacation response was retrieved
253 @param state Current state string for change tracking
254 @param list List containing the singleton VacationResponse (or empty)
255 @param not_found List of requested IDs that were not found
256 @return VacationResponse/get response *)
257 val v :
258 account_id:Jmap.Id.t ->
259 state:string ->
260 list:vacation_response list ->
261 not_found:Jmap.Id.t list ->
262 unit -> t
263
264 (** Get the singleton vacation response if present.
265 @return The vacation response object or None if not found *)
266 val singleton : t -> vacation_response option
267end
268
269(** Arguments for VacationResponse/set method.
270
271 Specialized version of the standard JMAP set arguments. Only supports
272 update operations (not create or destroy) and the target ID must be
273 "singleton" since VacationResponse is a singleton object.
274
275 @see <https://www.rfc-editor.org/rfc/rfc8621.html#section-8.2> RFC 8621, Section 8.2
276*)
277module Set_args : sig
278 (** VacationResponse/set arguments *)
279 type t
280
281 include Jmap_sigs.JSONABLE with type t := t
282
283 (** Get the account ID for the set operation.
284 @return Account where vacation response will be updated *)
285 val account_id : t -> Jmap.Id.t
286
287 (** Get the conditional state for the update.
288 @return Optional state string for conditional updates *)
289 val if_in_state : t -> string option
290
291 (** Get the update operations to perform.
292 @return Map of "singleton" to update patch object *)
293 val update : t -> (string, Update.t) Hashtbl.t option
294
295 (** Create VacationResponse/set arguments.
296 @param account_id Account where vacation response will be updated
297 @param if_in_state Optional state for conditional updates
298 @param update Map containing "singleton" -> update object
299 @return VacationResponse/set arguments *)
300 val v :
301 account_id:Jmap.Id.t ->
302 ?if_in_state:string ->
303 ?update:(string, Update.t) Hashtbl.t ->
304 unit ->
305 t
306
307 (** Create set arguments for updating the singleton vacation response.
308 @param account_id Account where vacation response will be updated
309 @param if_in_state Optional state for conditional updates
310 @param update Update parameters for the singleton
311 @return Arguments configured for singleton update *)
312 val singleton :
313 account_id:Jmap.Id.t ->
314 ?if_in_state:string ->
315 update:Update.t ->
316 unit -> t
317end
318
319(** Response for VacationResponse/set method.
320
321 Contains the result of updating the VacationResponse singleton object.
322 Since only updates are supported, the created and destroyed fields are
323 not used - only updated and not_updated are relevant.
324
325 @see <https://www.rfc-editor.org/rfc/rfc8621.html#section-8.2> RFC 8621, Section 8.2
326*)
327module Set_response : sig
328 (** VacationResponse/set response *)
329 type t
330
331 include Jmap_sigs.JSONABLE with type t := t
332
333 (** Get the account ID from the response.
334 @return Account where vacation response was updated *)
335 val account_id : t -> Jmap.Id.t
336
337 (** Get the old state string.
338 @return Previous state if available *)
339 val old_state : t -> string option
340
341 (** Get the new current state string.
342 @return Updated state for future operations *)
343 val new_state : t -> string
344
345 (** Get the successfully updated VacationResponse objects.
346 @return Map of "singleton" to updated VacationResponse (if successful) *)
347 val updated : t -> (string, vacation_response option) Hashtbl.t option
348
349 (** Get the vacation responses that failed to update.
350 @return Map of IDs to error information for failed updates *)
351 val not_updated : t -> (string, Set_error.t) Hashtbl.t option
352
353 (** Create VacationResponse/set response.
354 @param account_id Account where vacation response was updated
355 @param old_state Previous state string
356 @param new_state Current state string
357 @param updated Map of successfully updated objects
358 @param not_updated Map of failed updates with errors
359 @return VacationResponse/set response *)
360 val v :
361 account_id:Jmap.Id.t ->
362 ?old_state:string ->
363 new_state:string ->
364 ?updated:(string, vacation_response option) Hashtbl.t ->
365 ?not_updated:(string, Set_error.t) Hashtbl.t ->
366 unit ->
367 t
368
369 (** Check if the singleton vacation response was successfully updated.
370 @return The updated vacation response or None if update failed *)
371 val singleton_updated : t -> vacation_response option
372
373 (** Get the error for singleton update failure.
374 @return Update error or None if update succeeded *)
375 val singleton_error : t -> Set_error.t option
376end
377
378(** {1 Property System} *)
379
380(** VacationResponse object property identifiers for selective retrieval.
381
382 Property identifiers for VacationResponse objects as specified in RFC 8621 Section 8.
383 These identifiers are used in VacationResponse/get requests to specify which properties
384 should be returned, enabling efficient partial object retrieval.
385
386 @see <https://www.rfc-editor.org/rfc/rfc8621.html#section-8> RFC 8621, Section 8
387*)
388module Property : sig
389 (** VacationResponse object property identifier type.
390
391 Polymorphic variant enumeration of all standard properties available
392 on VacationResponse objects as defined in RFC 8621.
393 *)
394 type t = [
395 | `Id (** Server-assigned unique identifier (always "singleton") (immutable, server-set) *)
396 | `IsEnabled (** Whether vacation response is currently active *)
397 | `FromDate (** Start Date.t for vacation response activation *)
398 | `ToDate (** End Date.t for vacation response activation *)
399 | `Subject (** Subject line for vacation response messages *)
400 | `TextBody (** Plain text body for vacation responses *)
401 | `HtmlBody (** HTML body for vacation responses *)
402 ]
403
404 (** Convert a property to its JMAP protocol string representation.
405
406 @param prop The property to convert
407 @return JMAP protocol string representation *)
408 val to_string : t -> string
409
410 (** Parse a JMAP protocol string into a property variant.
411
412 @param str The protocol string to parse
413 @return Some property if valid, None if unknown *)
414 val of_string : string -> t option
415
416 (** Get all standard VacationResponse properties.
417
418 @return Complete list of all defined VacationResponse properties *)
419 val all_properties : t list
420
421 (** Convert a list of properties to their string representations.
422
423 @param properties List of property variants
424 @return List of JMAP protocol strings *)
425 val to_string_list : t list -> string list
426
427 (** Parse a list of strings into property variants.
428
429 @param strings List of JMAP protocol strings
430 @return List of parsed property variants (invalid strings ignored) *)
431 val of_string_list : string list -> t list
432
433 (** Get properties commonly needed for vacation response status.
434
435 @return List of properties suitable for vacation status displays *)
436 val common_properties : t list
437
438 (** Get properties for detailed vacation response configuration.
439
440 @return Complete list of all properties for vacation response setup *)
441 val detailed_properties : t list
442end