this repo has no description
anil.recoil.org
1(** Unix-specific JMAP client implementation interface.
2
3 This module provides functions to interact with a JMAP server using
4 Unix sockets for network communication.
5
6 @see <https://www.rfc-editor.org/rfc/rfc8620.html#section-4> RFC 8620, Section 4
7*)
8
9(** Configuration options for a JMAP client context *)
10type client_config = {
11 connect_timeout : float option; (** Connection timeout in seconds *)
12 request_timeout : float option; (** Request timeout in seconds *)
13 max_concurrent_requests : int option; (** Maximum concurrent requests *)
14 max_request_size : int option; (** Maximum request size in bytes *)
15 user_agent : string option; (** User-Agent header value *)
16 authentication_header : string option; (** Custom Authentication header name *)
17}
18
19(** Authentication method options *)
20type auth_method =
21 | Basic of string * string (** Basic auth with username and password *)
22 | Bearer of string (** Bearer token auth *)
23 | Custom of (string * string) (** Custom header name and value *)
24 | Session_cookie of (string * string) (** Session cookie name and value *)
25 | No_auth (** No authentication *)
26
27(** Represents an active JMAP connection context. Opaque type. *)
28type context
29
30(** Represents an active EventSource connection. Opaque type. *)
31type event_source_connection
32
33(** A request builder for constructing and sending JMAP requests *)
34type request_builder
35
36(** Create default configuration options *)
37val default_config : unit -> client_config
38
39(** Create a client context with the specified configuration
40 @return The context object used for JMAP API calls
41*)
42val create_client :
43 ?config:client_config ->
44 unit ->
45 context
46
47(** Connect to a JMAP server and retrieve the session.
48 This handles discovery (if needed) and authentication.
49 @param ctx The client context.
50 @param ?session_url Optional direct URL to the Session resource.
51 @param ?username Optional username (e.g., email address) for discovery.
52 @param ?auth_method Authentication method to use (default Basic).
53 @param credentials Authentication credentials.
54 @return A result with either (context, session) or an error.
55*)
56val connect :
57 context ->
58 ?session_url:Uri.t ->
59 ?username:string ->
60 host:string ->
61 ?port:int ->
62 ?auth_method:auth_method ->
63 unit ->
64 (context * Jmap.Session.Session.t) Jmap.Error.result
65
66(** Create a request builder for constructing a JMAP request.
67 @param ctx The client context.
68 @return A request builder object.
69*)
70val build : context -> request_builder
71
72(** Set the using capabilities for a request.
73 @param builder The request builder.
74 @param capabilities List of capability URIs to use.
75 @return The updated request builder.
76*)
77val using : request_builder -> string list -> request_builder
78
79(** Add a method call to a request builder.
80 @param builder The request builder.
81 @param name Method name (e.g., "Email/get").
82 @param args Method arguments.
83 @param id Method call ID.
84 @return The updated request builder.
85*)
86val add_method_call :
87 request_builder ->
88 string ->
89 Yojson.Safe.t ->
90 string ->
91 request_builder
92
93(** Create a reference to a previous method call result.
94 @param result_of Method call ID to reference.
95 @param name Path in the response.
96 @return A ResultReference to use in another method call.
97*)
98val create_reference : string -> string -> Jmap.Wire.Result_reference.t
99
100(** Execute a request and return the response.
101 @param builder The request builder to execute.
102 @return The JMAP response from the server.
103*)
104val execute : request_builder -> Jmap.Wire.Response.t Jmap.Error.result
105
106(** Perform a JMAP API request.
107 @param ctx The connection context.
108 @param request The JMAP request object.
109 @return The JMAP response from the server.
110*)
111val request : context -> Jmap.Wire.Request.t -> Jmap.Wire.Response.t Jmap.Error.result
112
113(** Upload binary data.
114 @param ctx The connection context.
115 @param account_id The target account ID.
116 @param content_type The MIME type of the data.
117 @param data_stream A stream providing the binary data chunks.
118 @return A result with either an upload response or an error.
119*)
120val upload :
121 context ->
122 account_id:Jmap.Types.id ->
123 content_type:string ->
124 data_stream:string Seq.t ->
125 Jmap.Binary.Upload_response.t Jmap.Error.result
126
127(** Download binary data.
128 @param ctx The connection context.
129 @param account_id The account ID.
130 @param blob_id The blob ID to download.
131 @param ?content_type The desired Content-Type for the download response.
132 @param ?name The desired filename for the download response.
133 @return A result with either a stream of data chunks or an error.
134*)
135val download :
136 context ->
137 account_id:Jmap.Types.id ->
138 blob_id:Jmap.Types.id ->
139 ?content_type:string ->
140 ?name:string ->
141 (string Seq.t) Jmap.Error.result
142
143(** Copy blobs between accounts.
144 @param ctx The connection context.
145 @param from_account_id Source account ID.
146 @param account_id Destination account ID.
147 @param blob_ids List of blob IDs to copy.
148 @return A result with either the copy response or an error.
149*)
150val copy_blobs :
151 context ->
152 from_account_id:Jmap.Types.id ->
153 account_id:Jmap.Types.id ->
154 blob_ids:Jmap.Types.id list ->
155 Jmap.Binary.Blob_copy_response.t Jmap.Error.result
156
157(** Connect to the EventSource for push notifications.
158 @param ctx The connection context.
159 @param ?types List of types to subscribe to (default "*").
160 @param ?close_after Request server to close after first state event.
161 @param ?ping Request ping interval in seconds (default 0).
162 @return A result with either a tuple of connection handle and event stream, or an error.
163 @see <https://www.rfc-editor.org/rfc/rfc8620.html#section-7.3> RFC 8620, Section 7.3 *)
164val connect_event_source :
165 context ->
166 ?types:string list ->
167 ?close_after:[`State | `No] ->
168 ?ping:Jmap.Types.uint ->
169 (event_source_connection *
170 ([`State of Jmap.Push.State_change.t | `Ping of Jmap.Push.Event_source_ping_data.t ] Seq.t)) Jmap.Error.result
171
172(** Create a websocket connection for JMAP over WebSocket.
173 @param ctx The connection context.
174 @return A result with either a websocket connection or an error.
175 @see <https://www.rfc-editor.org/rfc/rfc8887.html> RFC 8887 *)
176val connect_websocket :
177 context ->
178 event_source_connection Jmap.Error.result
179
180(** Send a message over a websocket connection.
181 @param conn The websocket connection.
182 @param request The JMAP request to send.
183 @return A result with either the response or an error.
184*)
185val websocket_send :
186 event_source_connection ->
187 Jmap.Wire.Request.t ->
188 Jmap.Wire.Response.t Jmap.Error.result
189
190(** Close an EventSource or WebSocket connection.
191 @param conn The connection handle.
192 @return A result with either unit or an error.
193*)
194val close_connection : event_source_connection -> unit Jmap.Error.result
195
196(** Close the JMAP connection context.
197 @return A result with either unit or an error.
198*)
199val close : context -> unit Jmap.Error.result
200
201(** {2 Helper Methods for Common Tasks} *)
202
203(** Helper to get a single object by ID.
204 @param ctx The context.
205 @param method_name The get method (e.g., "Email/get").
206 @param account_id The account ID.
207 @param object_id The ID of the object to get.
208 @param ?properties Optional list of properties to fetch.
209 @return A result with either the object as JSON or an error.
210*)
211val get_object :
212 context ->
213 method_name:string ->
214 account_id:Jmap.Types.id ->
215 object_id:Jmap.Types.id ->
216 ?properties:string list ->
217 Yojson.Safe.t Jmap.Error.result
218
219(** Helper to set up the connection with minimal options.
220 @param host The JMAP server hostname.
221 @param username Username for basic auth.
222 @param password Password for basic auth.
223 @return A result with either (context, session) or an error.
224*)
225val quick_connect :
226 host:string ->
227 username:string ->
228 password:string ->
229 (context * Jmap.Session.Session.t) Jmap.Error.result
230
231(** Perform a Core/echo request to test connectivity.
232 @param ctx The JMAP connection context.
233 @param ?data Optional data to echo back.
234 @return A result with either the response or an error.
235*)
236val echo :
237 context ->
238 ?data:Yojson.Safe.t ->
239 unit ->
240 Yojson.Safe.t Jmap.Error.result
241
242(** {2 Email Operations} *)
243
244(** High-level email operations that map to JMAP email methods *)
245module Email : sig
246 open Jmap_email.Types
247
248 (** Get an email by ID
249 @param ctx The JMAP client context
250 @param account_id The account ID
251 @param email_id The email ID to fetch
252 @param ?properties Optional list of properties to fetch
253 @return The email object or an error
254 *)
255 val get_email :
256 context ->
257 account_id:Jmap.Types.id ->
258 email_id:Jmap.Types.id ->
259 ?properties:string list ->
260 unit ->
261 Email.t Jmap.Error.result
262
263 (** Search for emails using a filter
264 @param ctx The JMAP client context
265 @param account_id The account ID
266 @param filter The search filter
267 @param ?sort Optional sort criteria (default received date newest first)
268 @param ?limit Optional maximum number of results
269 @param ?properties Optional properties to fetch for the matching emails
270 @return The list of matching email IDs and optionally the email objects
271 *)
272 val search_emails :
273 context ->
274 account_id:Jmap.Types.id ->
275 filter:Jmap.Methods.Filter.t ->
276 ?sort:Jmap.Methods.Comparator.t list ->
277 ?limit:Jmap.Types.uint ->
278 ?position:int ->
279 ?properties:string list ->
280 unit ->
281 (Jmap.Types.id list * Email.t list option) Jmap.Error.result
282
283 (** Mark multiple emails with a keyword
284 @param ctx The JMAP client context
285 @param account_id The account ID
286 @param email_ids List of email IDs to update
287 @param keyword The keyword to add
288 @return The result of the operation
289 *)
290 val mark_emails :
291 context ->
292 account_id:Jmap.Types.id ->
293 email_ids:Jmap.Types.id list ->
294 keyword:Keywords.keyword ->
295 unit ->
296 unit Jmap.Error.result
297
298 (** Mark emails as seen/read
299 @param ctx The JMAP client context
300 @param account_id The account ID
301 @param email_ids List of email IDs to mark
302 @return The result of the operation
303 *)
304 val mark_as_seen :
305 context ->
306 account_id:Jmap.Types.id ->
307 email_ids:Jmap.Types.id list ->
308 unit ->
309 unit Jmap.Error.result
310
311 (** Mark emails as unseen/unread
312 @param ctx The JMAP client context
313 @param account_id The account ID
314 @param email_ids List of email IDs to mark
315 @return The result of the operation
316 *)
317 val mark_as_unseen :
318 context ->
319 account_id:Jmap.Types.id ->
320 email_ids:Jmap.Types.id list ->
321 unit ->
322 unit Jmap.Error.result
323
324 (** Move emails to a different mailbox
325 @param ctx The JMAP client context
326 @param account_id The account ID
327 @param email_ids List of email IDs to move
328 @param mailbox_id Destination mailbox ID
329 @param ?remove_from_mailboxes Optional list of source mailbox IDs to remove from
330 @return The result of the operation
331 *)
332 val move_emails :
333 context ->
334 account_id:Jmap.Types.id ->
335 email_ids:Jmap.Types.id list ->
336 mailbox_id:Jmap.Types.id ->
337 ?remove_from_mailboxes:Jmap.Types.id list ->
338 unit ->
339 unit Jmap.Error.result
340
341 (** Import an RFC822 message
342 @param ctx The JMAP client context
343 @param account_id The account ID
344 @param rfc822 Raw message content
345 @param mailbox_ids Mailboxes to add the message to
346 @param ?keywords Optional keywords to set
347 @param ?received_at Optional received timestamp
348 @return The ID of the imported email
349 *)
350 val import_email :
351 context ->
352 account_id:Jmap.Types.id ->
353 rfc822:string ->
354 mailbox_ids:Jmap.Types.id list ->
355 ?keywords:Keywords.t ->
356 ?received_at:Jmap.Types.date ->
357 unit ->
358 Jmap.Types.id Jmap.Error.result
359end