this repo has no description
anil.recoil.org
1(**
2 * JMAP protocol implementation based on RFC8620
3 * https://datatracker.ietf.org/doc/html/rfc8620
4 *
5 * This module implements the core JMAP protocol as defined in RFC8620, providing
6 * types and functions for making JMAP API requests and handling responses.
7 *)
8
9(** Initialize and configure logging for JMAP
10 @param level Optional logging level (higher means more verbose)
11 @param enable_logs Whether to enable logging at all (default true)
12 @param redact_sensitive Whether to redact sensitive information like tokens (default true)
13 *)
14val init_logging : ?level:int -> ?enable_logs:bool -> ?redact_sensitive:bool -> unit -> unit
15
16(** Redact sensitive data like authentication tokens from logs
17 @param redact Whether to perform redaction (default true)
18 @param token The token string to redact
19 @return A redacted version of the token (with characters replaced by '*')
20 *)
21val redact_token : ?redact:bool -> string -> string
22
23(** Module for managing JMAP capability URIs and other constants
24 as defined in RFC8620 Section 1.8
25 @see <https://datatracker.ietf.org/doc/html/rfc8620#section-1.8> RFC8620 Section 1.8
26*)
27module Capability : sig
28 (** JMAP core capability URI as specified in RFC8620 Section 2
29 @see <https://datatracker.ietf.org/doc/html/rfc8620#section-2> RFC8620 Section 2
30 *)
31 val core_uri : string
32
33 (** All JMAP capability types as described in RFC8620 Section 1.8
34 @see <https://datatracker.ietf.org/doc/html/rfc8620#section-1.8> RFC8620 Section 1.8
35 *)
36 type t =
37 | Core (** Core JMAP capability *)
38 | Extension of string (** Extension capabilities with custom URIs *)
39
40 (** Convert capability to URI string
41 @param capability The capability to convert
42 @return The full URI string for the capability
43 *)
44 val to_string : t -> string
45
46 (** Parse a string to a capability, returns Extension for non-core capabilities
47 @param uri The capability URI string to parse
48 @return The parsed capability type
49 *)
50 val of_string : string -> t
51
52 (** Check if a capability matches the core capability
53 @param capability The capability to check
54 @return True if the capability is the core JMAP capability
55 @see <https://datatracker.ietf.org/doc/html/rfc8620#section-2>
56 *)
57 val is_core : t -> bool
58
59 (** Check if a capability string is the core capability URI
60 @param uri The capability URI string to check
61 @return True if the string represents the core JMAP capability
62 @see <https://datatracker.ietf.org/doc/html/rfc8620#section-2>
63 *)
64 val is_core_string : string -> bool
65
66 (** Create a list of capability URI strings
67 @param capabilities List of capability types
68 @return List of capability URI strings
69 *)
70 val strings_of_capabilities : t list -> string list
71end
72
73(** {1 Types}
74 Core types as defined in RFC8620
75 @see <https://datatracker.ietf.org/doc/html/rfc8620> RFC8620
76*)
77
78module Types : sig
79 (** Id string as defined in RFC8620 Section 1.2.
80 A string of at least 1 and maximum 255 octets, case-sensitive,
81 and does not begin with the '#' character.
82 @see <https://datatracker.ietf.org/doc/html/rfc8620#section-1.2>
83 *)
84 type id = string
85
86 (** Int type bounded within the range -2^53+1 to 2^53-1 as defined in RFC8620 Section 1.3.
87 Represented as JSON number where the value MUST be an integer and in the range.
88 @see <https://datatracker.ietf.org/doc/html/rfc8620#section-1.3>
89 *)
90 type int_t = int
91
92 (** UnsignedInt bounded within the range 0 to 2^53-1 as defined in RFC8620 Section 1.3.
93 Represented as JSON number where the value MUST be a non-negative integer and in the range.
94 @see <https://datatracker.ietf.org/doc/html/rfc8620#section-1.3>
95 *)
96 type unsigned_int = int
97
98 (** Date string in RFC3339 format as defined in RFC8620 Section 1.4.
99 Includes date, time and time zone offset information or UTC.
100 @see <https://datatracker.ietf.org/doc/html/rfc8620#section-1.4>
101 *)
102 type date = string
103
104 (** UTCDate is a Date with 'Z' time zone (UTC) as defined in RFC8620 Section 1.4.
105 Same format as Date type but always with UTC time zone (Z).
106 @see <https://datatracker.ietf.org/doc/html/rfc8620#section-1.4>
107 *)
108 type utc_date = string
109
110 (** Error object as defined in RFC8620 Section 3.6.2.
111 Used to represent standard error conditions in method responses.
112 @see <https://datatracker.ietf.org/doc/html/rfc8620#section-3.6.2>
113 *)
114 type error = {
115 type_: string; (** The type of error, e.g., "serverFail" *)
116 description: string option; (** Optional human-readable description of the error *)
117 }
118
119 (** Set error object as defined in RFC8620 Section 5.3.
120 Used for reporting errors in set operations.
121 @see <https://datatracker.ietf.org/doc/html/rfc8620#section-5.3>
122 *)
123 type set_error = {
124 type_: string; (** The type of error, e.g., "notFound" *)
125 description: string option; (** Optional human-readable description of the error *)
126 properties: string list option; (** Properties causing the error, if applicable *)
127 existing_id: id option; (** For "alreadyExists" error, the ID of the existing object *)
128 }
129
130 (** Invocation object as defined in RFC8620 Section 3.2.
131 Represents a method call in the JMAP protocol.
132 @see <https://datatracker.ietf.org/doc/html/rfc8620#section-3.2>
133 *)
134 type 'a invocation = {
135 name: string; (** The name of the method to call, e.g., "Mailbox/get" *)
136 arguments: 'a; (** The arguments for the method, type varies by method *)
137 method_call_id: string; (** Client-specified ID for referencing this call *)
138 }
139
140 (** ResultReference object as defined in RFC8620 Section 3.7.
141 Used to reference results from previous method calls.
142 @see <https://datatracker.ietf.org/doc/html/rfc8620#section-3.7>
143 *)
144 type result_reference = {
145 result_of: string; (** The method_call_id of the method to reference *)
146 name: string; (** Name of the response in the referenced result *)
147 path: string; (** JSON pointer path to the value being referenced *)
148 }
149
150 (** FilterOperator, FilterCondition and Filter as defined in RFC8620 Section 5.5.
151 Used for complex filtering in query methods.
152 @see <https://datatracker.ietf.org/doc/html/rfc8620#section-5.5>
153 *)
154 type filter_operator = {
155 operator: string; (** The operator: "AND", "OR", "NOT" *)
156 conditions: filter list; (** The conditions to apply the operator to *)
157 }
158
159 (** Property/value pairs for filtering *)
160 and filter_condition =
161 (string * Ezjsonm.value) list
162
163 and filter =
164 | Operator of filter_operator (** Logical operator combining conditions *)
165 | Condition of filter_condition (** Simple property-based condition *)
166
167 (** Comparator object for sorting as defined in RFC8620 Section 5.5.
168 Specifies how to sort query results.
169 @see <https://datatracker.ietf.org/doc/html/rfc8620#section-5.5>
170 *)
171 type comparator = {
172 property: string; (** The property to sort by *)
173 is_ascending: bool option; (** Sort order (true for ascending, false for descending) *)
174 collation: string option; (** Collation algorithm for string comparison *)
175 }
176
177 (** PatchObject as defined in RFC8620 Section 5.3.
178 Used to represent a set of updates to apply to an object.
179 @see <https://datatracker.ietf.org/doc/html/rfc8620#section-5.3>
180 *)
181 type patch_object = (string * Ezjsonm.value) list (** List of property/value pairs to update *)
182
183 (** AddedItem structure as defined in RFC8620 Section 5.6.
184 Represents an item added to a query result.
185 @see <https://datatracker.ietf.org/doc/html/rfc8620#section-5.6>
186 *)
187 type added_item = {
188 id: id; (** The ID of the added item *)
189 index: unsigned_int; (** The index in the result list where the item appears *)
190 }
191
192 (** Account object as defined in RFC8620 Section 1.6.2.
193 Represents a user account in JMAP.
194 @see <https://datatracker.ietf.org/doc/html/rfc8620#section-1.6.2>
195 *)
196 type account = {
197 name: string; (** User-friendly account name, e.g. "john@example.com" *)
198 is_personal: bool; (** Whether this account belongs to the authenticated user *)
199 is_read_only: bool; (** Whether this account can be modified *)
200 account_capabilities: (string * Ezjsonm.value) list; (** Capabilities available for this account *)
201 }
202
203 (** Core capability object as defined in RFC8620 Section 2.
204 Describes limits and features of the JMAP server.
205 @see <https://datatracker.ietf.org/doc/html/rfc8620#section-2>
206 *)
207 type core_capability = {
208 max_size_upload: unsigned_int; (** Maximum file size in octets for uploads *)
209 max_concurrent_upload: unsigned_int; (** Maximum number of concurrent uploads *)
210 max_size_request: unsigned_int; (** Maximum size in octets for a request *)
211 max_concurrent_requests: unsigned_int; (** Maximum number of concurrent requests *)
212 max_calls_in_request: unsigned_int; (** Maximum number of method calls in a request *)
213 max_objects_in_get: unsigned_int; (** Maximum number of objects in a get request *)
214 max_objects_in_set: unsigned_int; (** Maximum number of objects in a set request *)
215 collation_algorithms: string list; (** Supported string collation algorithms *)
216 }
217
218 (** PushSubscription keys object as defined in RFC8620 Section 7.2.
219 Contains encryption keys for web push subscriptions.
220 @see <https://datatracker.ietf.org/doc/html/rfc8620#section-7.2>
221 *)
222 type push_keys = {
223 p256dh: string; (** User agent public key (Base64url-encoded) *)
224 auth: string; (** Authentication secret (Base64url-encoded) *)
225 }
226
227 (** Session object as defined in RFC8620 Section 2.
228 Contains information about the server and user's accounts.
229 @see <https://datatracker.ietf.org/doc/html/rfc8620#section-2>
230 *)
231 type session = {
232 capabilities: (string * Ezjsonm.value) list; (** Server capabilities with their properties *)
233 accounts: (id * account) list; (** Map of account IDs to account objects *)
234 primary_accounts: (string * id) list; (** Map of capability URIs to primary account IDs *)
235 username: string; (** Username associated with this session *)
236 api_url: string; (** URL to use for JMAP API requests *)
237 download_url: string; (** URL endpoint to download files *)
238 upload_url: string; (** URL endpoint to upload files *)
239 event_source_url: string option; (** URL for Server-Sent Events notifications *)
240 state: string; (** String representing the state on the server *)
241 }
242
243 (** TypeState for state changes as defined in RFC8620 Section 7.1.
244 Maps data type names to the state string for that type.
245 @see <https://datatracker.ietf.org/doc/html/rfc8620#section-7.1>
246 *)
247 type type_state = (string * string) list (** (data type name, state string) pairs *)
248
249 (** StateChange object as defined in RFC8620 Section 7.1.
250 Represents changes to data types for different accounts.
251 @see <https://datatracker.ietf.org/doc/html/rfc8620#section-7.1>
252 *)
253 type state_change = {
254 changed: (id * type_state) list; (** Map of account IDs to type state changes *)
255 }
256
257 (** PushVerification object as defined in RFC8620 Section 7.2.2.
258 Used for verifying push subscription ownership.
259 @see <https://datatracker.ietf.org/doc/html/rfc8620#section-7.2.2>
260 *)
261 type push_verification = {
262 push_subscription_id: id; (** ID of the push subscription being verified *)
263 verification_code: string; (** Code the client must submit to verify ownership *)
264 }
265
266 (** PushSubscription object as defined in RFC8620 Section 7.2.
267 Represents a subscription for push notifications.
268 @see <https://datatracker.ietf.org/doc/html/rfc8620#section-7.2>
269 *)
270 type push_subscription = {
271 id: id; (** Server-assigned ID for the subscription *)
272 device_client_id: string; (** ID representing the client/device *)
273 url: string; (** URL to which events are pushed *)
274 keys: push_keys option; (** Encryption keys for web push, if any *)
275 verification_code: string option; (** Verification code if not yet verified *)
276 expires: utc_date option; (** When the subscription expires, if applicable *)
277 types: string list option; (** Types of changes to push, null means all *)
278 }
279
280 (** Request object as defined in RFC8620 Section 3.3.
281 Represents a JMAP request from client to server.
282 @see <https://datatracker.ietf.org/doc/html/rfc8620#section-3.3>
283 *)
284 type request = {
285 using: string list; (** Capabilities required for this request *)
286 method_calls: Ezjsonm.value invocation list; (** List of method calls to process *)
287 created_ids: (id * id) list option; (** Map of client-created IDs to server IDs *)
288 }
289
290 (** Response object as defined in RFC8620 Section 3.4.
291 Represents a JMAP response from server to client.
292 @see <https://datatracker.ietf.org/doc/html/rfc8620#section-3.4>
293 *)
294 type response = {
295 method_responses: Ezjsonm.value invocation list; (** List of method responses *)
296 created_ids: (id * id) list option; (** Map of client-created IDs to server IDs *)
297 session_state: string; (** Current session state on the server *)
298 }
299
300 (** {2 Standard method arguments and responses}
301 Standard method patterns defined in RFC8620 Section 5
302 @see <https://datatracker.ietf.org/doc/html/rfc8620#section-5>
303 *)
304
305 (** Arguments for Foo/get method as defined in RFC8620 Section 5.1.
306 Generic template for retrieving objects by ID.
307 @see <https://datatracker.ietf.org/doc/html/rfc8620#section-5.1>
308 *)
309 type 'a get_arguments = {
310 account_id: id; (** The account ID to operate on *)
311 ids: id list option; (** IDs to fetch, null means all *)
312 properties: string list option; (** Properties to return, null means all *)
313 }
314
315 (** Response for Foo/get method as defined in RFC8620 Section 5.1.
316 Generic template for returning requested objects.
317 @see <https://datatracker.ietf.org/doc/html/rfc8620#section-5.1>
318 *)
319 type 'a get_response = {
320 account_id: id; (** The account ID that was operated on *)
321 state: string; (** Server state for the type at the time of processing *)
322 list: 'a list; (** The list of requested objects *)
323 not_found: id list; (** IDs that could not be found *)
324 }
325
326 (** Arguments for Foo/changes method as defined in RFC8620 Section 5.2.
327 Generic template for getting state changes.
328 @see <https://datatracker.ietf.org/doc/html/rfc8620#section-5.2>
329 *)
330 type changes_arguments = {
331 account_id: id; (** The account ID to operate on *)
332 since_state: string; (** The last state seen by the client *)
333 max_changes: unsigned_int option; (** Maximum number of changes to return *)
334 }
335
336 (** Response for Foo/changes method as defined in RFC8620 Section 5.2.
337 Generic template for returning object changes.
338 @see <https://datatracker.ietf.org/doc/html/rfc8620#section-5.2>
339 *)
340 type changes_response = {
341 account_id: id; (** The account ID that was operated on *)
342 old_state: string; (** The state provided in the request *)
343 new_state: string; (** The current server state *)
344 has_more_changes: bool; (** True if more changes are available *)
345 created: id list; (** IDs of objects created since old_state *)
346 updated: id list; (** IDs of objects updated since old_state *)
347 destroyed: id list; (** IDs of objects destroyed since old_state *)
348 }
349
350 (** Arguments for Foo/set method as defined in RFC8620 Section 5.3.
351 Generic template for creating, updating, and destroying objects.
352 @see <https://datatracker.ietf.org/doc/html/rfc8620#section-5.3>
353 *)
354 type 'a set_arguments = {
355 account_id: id; (** The account ID to operate on *)
356 if_in_state: string option; (** Only apply changes if in this state *)
357 create: (id * 'a) list option; (** Map of creation IDs to objects to create *)
358 update: (id * patch_object) list option; (** Map of IDs to patches to apply *)
359 destroy: id list option; (** List of IDs to destroy *)
360 }
361
362 (** Response for Foo/set method as defined in RFC8620 Section 5.3.
363 Generic template for reporting create/update/destroy status.
364 @see <https://datatracker.ietf.org/doc/html/rfc8620#section-5.3>
365 *)
366 type 'a set_response = {
367 account_id: id; (** The account ID that was operated on *)
368 old_state: string option; (** The state before processing, if changed *)
369 new_state: string; (** The current server state *)
370 created: (id * 'a) list option; (** Map of creation IDs to created objects *)
371 updated: (id * 'a option) list option; (** Map of IDs to updated objects *)
372 destroyed: id list option; (** List of IDs successfully destroyed *)
373 not_created: (id * set_error) list option; (** Map of IDs to errors for failed creates *)
374 not_updated: (id * set_error) list option; (** Map of IDs to errors for failed updates *)
375 not_destroyed: (id * set_error) list option; (** Map of IDs to errors for failed destroys *)
376 }
377
378 (** Arguments for Foo/copy method as defined in RFC8620 Section 5.4.
379 Generic template for copying objects between accounts.
380 @see <https://datatracker.ietf.org/doc/html/rfc8620#section-5.4>
381 *)
382 type 'a copy_arguments = {
383 from_account_id: id; (** The account ID to copy from *)
384 if_from_in_state: string option; (** Only copy if source account in this state *)
385 account_id: id; (** The account ID to copy to *)
386 if_in_state: string option; (** Only copy if destination account in this state *)
387 create: (id * 'a) list; (** Map of creation IDs to objects to copy *)
388 on_success_destroy_original: bool option; (** Whether to destroy the original after copying *)
389 destroy_from_if_in_state: string option; (** Only destroy originals if in this state *)
390 }
391
392 (** Response for Foo/copy method as defined in RFC8620 Section 5.4.
393 Generic template for reporting copy operation status.
394 @see <https://datatracker.ietf.org/doc/html/rfc8620#section-5.4>
395 *)
396 type 'a copy_response = {
397 from_account_id: id; (** The account ID that was copied from *)
398 account_id: id; (** The account ID that was copied to *)
399 old_state: string option; (** The state before processing, if changed *)
400 new_state: string; (** The current server state *)
401 created: (id * 'a) list option; (** Map of creation IDs to created objects *)
402 not_created: (id * set_error) list option; (** Map of IDs to errors for failed copies *)
403 }
404
405 (** Arguments for Foo/query method as defined in RFC8620 Section 5.5.
406 Generic template for querying objects.
407 @see <https://datatracker.ietf.org/doc/html/rfc8620#section-5.5>
408 *)
409 type query_arguments = {
410 account_id: id; (** The account ID to operate on *)
411 filter: filter option; (** Filter to determine which objects are returned *)
412 sort: comparator list option; (** Sort order for returned objects *)
413 position: int_t option; (** Zero-based index of first result to return *)
414 anchor: id option; (** ID of object to use as reference point *)
415 anchor_offset: int_t option; (** Offset from anchor to start returning results *)
416 limit: unsigned_int option; (** Maximum number of results to return *)
417 calculate_total: bool option; (** Whether to calculate the total number of matching objects *)
418 }
419
420 (** Response for Foo/query method as defined in RFC8620 Section 5.5.
421 Generic template for returning query results.
422 @see <https://datatracker.ietf.org/doc/html/rfc8620#section-5.5>
423 *)
424 type query_response = {
425 account_id: id; (** The account ID that was operated on *)
426 query_state: string; (** State string for the query results *)
427 can_calculate_changes: bool; (** Whether queryChanges can be used with these results *)
428 position: unsigned_int; (** Zero-based index of the first result *)
429 ids: id list; (** The list of IDs for objects matching the query *)
430 total: unsigned_int option; (** Total number of matching objects, if calculated *)
431 limit: unsigned_int option; (** Limit enforced on the results, if requested *)
432 }
433
434 (** Arguments for Foo/queryChanges method as defined in RFC8620 Section 5.6.
435 Generic template for getting query result changes.
436 @see <https://datatracker.ietf.org/doc/html/rfc8620#section-5.6>
437 *)
438 type query_changes_arguments = {
439 account_id: id; (** The account ID to operate on *)
440 filter: filter option; (** Same filter as used in the original query *)
441 sort: comparator list option; (** Same sort as used in the original query *)
442 since_query_state: string; (** The query_state from previous results *)
443 max_changes: unsigned_int option; (** Maximum number of changes to return *)
444 up_to_id: id option; (** Only calculate changes until this ID is encountered *)
445 calculate_total: bool option; (** Whether to recalculate the total matches *)
446 }
447
448 (** Response for Foo/queryChanges method as defined in RFC8620 Section 5.6.
449 Generic template for returning query result changes.
450 @see <https://datatracker.ietf.org/doc/html/rfc8620#section-5.6>
451 *)
452 type query_changes_response = {
453 account_id: id; (** The account ID that was operated on *)
454 old_query_state: string; (** The query_state from the request *)
455 new_query_state: string; (** The current query_state on the server *)
456 total: unsigned_int option; (** Updated total number of matches, if calculated *)
457 removed: id list; (** IDs that were in the old results but not in the new *)
458 added: added_item list option; (** IDs that are in the new results but not the old *)
459 }
460
461 (** Arguments for Blob/copy method as defined in RFC8620 Section 6.3.
462 Used for copying binary data between accounts.
463 @see <https://datatracker.ietf.org/doc/html/rfc8620#section-6.3>
464 *)
465 type blob_copy_arguments = {
466 from_account_id: id; (** The account ID to copy blobs from *)
467 account_id: id; (** The account ID to copy blobs to *)
468 blob_ids: id list; (** IDs of blobs to copy *)
469 }
470
471 (** Response for Blob/copy method as defined in RFC8620 Section 6.3.
472 Reports the results of copying binary data.
473 @see <https://datatracker.ietf.org/doc/html/rfc8620#section-6.3>
474 *)
475 type blob_copy_response = {
476 from_account_id: id; (** The account ID that was copied from *)
477 account_id: id; (** The account ID that was copied to *)
478 copied: (id * id) list option; (** Map of source IDs to destination IDs *)
479 not_copied: (id * set_error) list option; (** Map of IDs to errors for failed copies *)
480 }
481
482 (** Upload response as defined in RFC8620 Section 6.1.
483 Contains information about an uploaded binary blob.
484 @see <https://datatracker.ietf.org/doc/html/rfc8620#section-6.1>
485 *)
486 type upload_response = {
487 account_id: id; (** The account ID the blob was uploaded to *)
488 blob_id: id; (** The ID for the uploaded blob *)
489 type_: string; (** Media type of the blob *)
490 size: unsigned_int; (** Size of the blob in octets *)
491 }
492
493 (** Problem details object as defined in RFC8620 Section 3.6.1 and RFC7807.
494 Used for HTTP error responses in the JMAP protocol.
495 @see <https://datatracker.ietf.org/doc/html/rfc8620#section-3.6.1>
496 @see <https://datatracker.ietf.org/doc/html/rfc7807>
497 *)
498 type problem_details = {
499 type_: string; (** URI that identifies the problem type *)
500 status: int option; (** HTTP status code for this problem *)
501 detail: string option; (** Human-readable explanation of the problem *)
502 limit: string option; (** For "limit" errors, which limit was exceeded *)
503 }
504end
505
506(** {1 API Client}
507 Modules for interacting with JMAP servers
508*)
509
510(** Module for working with ResultReferences as described in Section 3.7 of RFC8620.
511 Provides utilities to create and compose results from previous methods.
512 @see <https://datatracker.ietf.org/doc/html/rfc8620#section-3.7>
513*)
514module ResultReference : sig
515 (** Create a reference to a previous method result
516 @param result_of The methodCallId of the method call to reference
517 @param name The name in the response to reference (e.g., "list")
518 @param path JSON pointer path to the value being referenced
519 @return A result_reference object
520 @see <https://datatracker.ietf.org/doc/html/rfc8620#section-3.7>
521 *)
522 val create :
523 result_of:string ->
524 name:string ->
525 path:string ->
526 Types.result_reference
527
528 (** Create a JSON pointer path to access a specific property
529 @param property The property name to access
530 @return A JSON pointer path string
531 *)
532 val property_path : string -> string
533
534 (** Create a JSON pointer path to access all items in an array with a specific property
535 @param property Optional property to access within each array item
536 @param array_name The name of the array to access
537 @return A JSON pointer path string that references all items in the array
538 *)
539 val array_items_path : ?property:string -> string -> string
540
541 (** Create argument with result reference.
542 @param arg_name The name of the argument
543 @param reference The result reference to use
544 @return A tuple of string key (with # prefix) and ResultReference JSON value
545 *)
546 val reference_arg : string -> Types.result_reference -> string * Ezjsonm.value
547
548 (** Create a reference to all IDs returned by a query method
549 @param result_of The methodCallId of the query method call
550 @return A result_reference to the IDs returned by the query
551 *)
552 val query_ids :
553 result_of:string ->
554 Types.result_reference
555
556 (** Create a reference to properties of objects returned by a get method
557 @param result_of The methodCallId of the get method call
558 @param property The property to reference in the returned objects
559 @return A result_reference to the specified property in the get results
560 *)
561 val get_property :
562 result_of:string ->
563 property:string ->
564 Types.result_reference
565end
566
567(** Module for making JMAP API requests over HTTP.
568 Provides functionality to interact with JMAP servers according to RFC8620.
569 @see <https://datatracker.ietf.org/doc/html/rfc8620>
570*)
571module Api : sig
572 (** Error that may occur during API requests *)
573 type error =
574 | Connection_error of string (** Network-related errors *)
575 | HTTP_error of int * string (** HTTP errors with status code and message *)
576 | Parse_error of string (** JSON parsing errors *)
577 | Authentication_error (** Authentication failures *)
578
579 (** Result type for API operations *)
580 type 'a result = ('a, error) Stdlib.result
581
582 (** Configuration for a JMAP API client as defined in RFC8620 Section 3.1
583 @see <https://datatracker.ietf.org/doc/html/rfc8620#section-3.1>
584 *)
585 type config = {
586 api_uri: Uri.t; (** The JMAP API endpoint URI *)
587 username: string; (** The username for authentication *)
588 authentication_token: string; (** The token for authentication *)
589 }
590
591 (** Make a raw JMAP API request as defined in RFC8620 Section 3.3
592 @param config The API client configuration
593 @param request The JMAP request to send
594 @return A result containing the JMAP response or an error
595 @see <https://datatracker.ietf.org/doc/html/rfc8620#section-3.3>
596 *)
597 val make_request :
598 config ->
599 Types.request ->
600 Types.response result Lwt.t
601
602 (** Fetch a Session object from a JMAP server as defined in RFC8620 Section 2
603 Can authenticate with either username/password or API token.
604 @param uri The URI of the JMAP session resource
605 @param username Optional username for authentication
606 @param authentication_token Optional password or token for authentication
607 @param api_token Optional API token for Bearer authentication
608 @return A result containing the session object or an error
609 @see <https://datatracker.ietf.org/doc/html/rfc8620#section-2>
610 *)
611 val get_session :
612 Uri.t ->
613 ?username:string ->
614 ?authentication_token:string ->
615 ?api_token:string ->
616 unit ->
617 Types.session result Lwt.t
618
619 (** Upload a binary blob to the server as defined in RFC8620 Section 6.1
620 @param config The API client configuration
621 @param account_id The account ID to upload to
622 @param content_type The MIME type of the blob
623 @param data The blob data as a string
624 @return A result containing the upload response or an error
625 @see <https://datatracker.ietf.org/doc/html/rfc8620#section-6.1>
626 *)
627 val upload_blob :
628 config ->
629 account_id:Types.id ->
630 content_type:string ->
631 string ->
632 Types.upload_response result Lwt.t
633
634 (** Download a binary blob from the server as defined in RFC8620 Section 6.2
635 @param config The API client configuration
636 @param account_id The account ID that contains the blob
637 @param blob_id The ID of the blob to download
638 @param type_ Optional MIME type to require for the blob
639 @param name Optional name for the downloaded blob
640 @return A result containing the blob data as a string or an error
641 @see <https://datatracker.ietf.org/doc/html/rfc8620#section-6.2>
642 *)
643 val download_blob :
644 config ->
645 account_id:Types.id ->
646 blob_id:Types.id ->
647 ?type_:string ->
648 ?name:string ->
649 unit ->
650 string result Lwt.t
651end