this repo has no description
anil.recoil.org
1(** JMAP Core Protocol Library Interface (RFC 8620)
2
3 This library provides OCaml types and function signatures for interacting
4 with a JMAP server according to the core protocol specification in RFC 8620.
5
6 Modules:
7 - {!Jmap.Types}: Basic data types (Id, Date, etc.).
8 - {!Jmap.Error}: Error types (ProblemDetails, MethodError, SetError).
9 - {!Jmap.Wire}: Request and Response structures.
10 - {!Jmap.Session}: Session object and discovery.
11 - {!Jmap.Methods}: Standard method patterns (/get, /set, etc.) and Core/echo.
12 - {!Jmap.Binary}: Binary data upload/download types.
13 - {!Jmap.Push}: Push notification types (StateChange, PushSubscription).
14
15 For email-specific extensions (RFC 8621), see the Jmap_email library.
16 For Unix-specific implementation, see the Jmap_unix library.
17
18 @see <https://www.rfc-editor.org/rfc/rfc8620.html> RFC 8620: Core JMAP
19*)
20
21(** {1 Core JMAP Types and Modules} *)
22
23module Types = Jmap_types
24module Error = Jmap_error
25module Wire = Jmap_wire
26module Session = Jmap_session
27module Methods = Jmap_methods
28module Binary = Jmap_binary
29module Push = Jmap_push
30
31(** {1 Example Usage}
32
33 The following example demonstrates using the Core JMAP library with the Unix implementation
34 to make a simple echo request.
35
36{[
37 (* OCaml 5.1 required for Lwt let operators *)
38 open Lwt.Syntax
39 open Jmap
40 open Jmap.Types
41 open Jmap.Wire
42 open Jmap.Methods
43 open Jmap.Unix
44
45 let simple_echo_request ctx session =
46 (* Prepare an echo invocation *)
47 let echo_args = Yojson.Safe.to_basic (`Assoc [
48 ("hello", `String "world");
49 ("array", `List [`Int 1; `Int 2; `Int 3]);
50 ]) in
51
52 let echo_invocation = Invocation.v
53 ~method_name:"Core/echo"
54 ~arguments:echo_args
55 ~method_call_id:"echo1"
56 ()
57 in
58
59 (* Prepare the JMAP request *)
60 let request = Request.v
61 ~using:[capability_core]
62 ~method_calls:[echo_invocation]
63 ()
64 in
65
66 (* Send the request *)
67 let* response = Jmap.Unix.request ctx request in
68
69 (* Process the response *)
70 match Wire.find_method_response response "echo1" with
71 | Some (method_name, args, _) when method_name = "Core/echo" ->
72 (* Echo response should contain the same arguments we sent *)
73 let hello_value = match Yojson.Safe.Util.member "hello" args with
74 | `String s -> s
75 | _ -> "not found"
76 in
77 Printf.printf "Echo response received: hello=%s\n" hello_value;
78 Lwt.return_unit
79 | _ ->
80 Printf.eprintf "Echo response not found or unexpected format\n";
81 Lwt.return_unit
82
83 let main () =
84 (* Authentication details are placeholder *)
85 let credentials = "my_auth_token" in
86 let* (ctx, session) = Jmap.Unix.connect ~host:"jmap.example.com" ~credentials in
87 let* () = simple_echo_request ctx session in
88 Jmap.Unix.close ctx
89
90 (* Lwt_main.run (main ()) *)
91]}
92*)
93
94(** Capability URI for JMAP Core.
95 @see <https://www.rfc-editor.org/rfc/rfc8620.html#section-2> RFC 8620, Section 2 *)
96val capability_core : string
97
98(** {1 Convenience Functions} *)
99
100(** Check if a session supports a given capability.
101 @param session The session object.
102 @param capability The capability URI to check.
103 @return True if supported, false otherwise.
104*)
105val supports_capability : Jmap_session.Session.t -> string -> bool
106
107(** Get the primary account ID for a given capability.
108 @param session The session object.
109 @param capability The capability URI.
110 @return The account ID or an error if not found.
111*)
112val get_primary_account : Jmap_session.Session.t -> string -> (Jmap_types.id, Error.error) result
113
114(** Get the download URL for a blob.
115 @param session The session object.
116 @param account_id The account ID.
117 @param blob_id The blob ID.
118 @param ?name Optional filename for the download.
119 @param ?content_type Optional content type for the download.
120 @return The download URL.
121*)
122val get_download_url :
123 Jmap_session.Session.t ->
124 account_id:Jmap_types.id ->
125 blob_id:Jmap_types.id ->
126 ?name:string ->
127 ?content_type:string ->
128 unit ->
129 Uri.t
130
131(** Get the upload URL for a blob.
132 @param session The session object.
133 @param account_id The account ID.
134 @return The upload URL.
135*)
136val get_upload_url : Jmap_session.Session.t -> account_id:Jmap_types.id -> Uri.t