this repo has no description
anil.recoil.org
1(*---------------------------------------------------------------------------
2 Copyright (c) 2025 Anil Madhavapeddy. All rights reserved.
3 SPDX-License-Identifier: ISC
4 ---------------------------------------------------------------------------*)
5
6(** JMAP client for browsers using Brr.
7
8 This module provides a JMAP client that runs in web browsers using
9 the Fetch API. It can be used with js_of_ocaml to build browser-based
10 email clients.
11
12 {2 Example}
13
14 {[
15 open Fut.Syntax
16
17 let main () =
18 let* session = Jmap_brr.get_session
19 ~url:(Jstr.v "https://api.fastmail.com/jmap/session")
20 ~token:(Jstr.v "your-api-token")
21 in
22 match session with
23 | Error e -> Brr.Console.(error [str "Session error:"; e]); Fut.return ()
24 | Ok session ->
25 Brr.Console.(log [str "Connected as:"; str (Jmap.Session.username session)]);
26 Fut.return ()
27
28 let () = ignore (main ())
29 ]} *)
30
31(** {1 Connection} *)
32
33type connection
34(** A JMAP connection to a server. *)
35
36val session : connection -> Jmap.Proto.Session.t
37(** [session conn] returns the session information. *)
38
39val api_url : connection -> Jstr.t
40(** [api_url conn] returns the API URL for requests. *)
41
42(** {1 Session Establishment} *)
43
44val get_session :
45 url:Jstr.t ->
46 token:Jstr.t ->
47 (connection, Jv.Error.t) result Fut.t
48(** [get_session ~url ~token] establishes a JMAP session.
49
50 [url] is the session URL (e.g., ["https://api.fastmail.com/jmap/session"]).
51 [token] is the Bearer authentication token. *)
52
53(** {1 Making Requests} *)
54
55val request :
56 connection ->
57 Jmap.Proto.Request.t ->
58 (Jmap.Proto.Response.t, Jv.Error.t) result Fut.t
59(** [request conn req] sends a JMAP request and returns the response. *)
60
61val request_json :
62 connection ->
63 Jsont.json ->
64 (Jsont.json, Jv.Error.t) result Fut.t
65(** [request_json conn json] sends a raw JSON request and returns the
66 JSON response. Useful for debugging or custom requests. *)
67
68(** {1 JSON Encoding Utilities}
69
70 These functions help visualize how OCaml types map to JMAP JSON,
71 useful for the tutorial and debugging. *)
72
73val encode_request : Jmap.Proto.Request.t -> (Jstr.t, Jv.Error.t) result
74(** [encode_request req] encodes a request to JSON string. *)
75
76val encode_response : Jmap.Proto.Response.t -> (Jstr.t, Jv.Error.t) result
77(** [encode_response resp] encodes a response to JSON string. *)
78
79val encode_session : Jmap.Proto.Session.t -> (Jstr.t, Jv.Error.t) result
80(** [encode_session session] encodes a session to JSON string. *)
81
82val decode_json : Jstr.t -> (Jsont.json, Jv.Error.t) result
83(** [decode_json s] parses a JSON string to a Jsont.json value. *)
84
85val encode_json : Jsont.json -> (Jstr.t, Jv.Error.t) result
86(** [encode_json json] encodes a Jsont.json value to a string. *)
87
88val pp_json : Format.formatter -> Jsont.json -> unit
89(** [pp_json ppf json] pretty-prints JSON. For toplevel use. *)
90
91(** {1 Protocol Logging} *)
92
93val set_request_logger : (string -> string -> unit) -> unit
94(** [set_request_logger f] registers a callback [f label json] that will be
95 called with each outgoing JMAP request. Useful for debugging and
96 educational displays. *)
97
98val set_response_logger : (string -> string -> unit) -> unit
99(** [set_response_logger f] registers a callback [f label json] that will be
100 called with each incoming JMAP response. Useful for debugging and
101 educational displays. *)
102
103(** {1 Toplevel Support} *)
104
105val install_printers : unit -> unit
106(** [install_printers ()] installs toplevel pretty printers for JMAP types.
107 This is useful when using the OCaml console in the browser. *)