anil.recoil.org
Matrix protocol in OCaml, Eio specialised
1(** Matrix client type and lifecycle. *)
2
3(** Client configuration. *)
4type config = {
5 homeserver : Uri.t;
6 (** Homeserver URL (e.g., https://matrix.org) *)
7 user_agent : string option;
8 (** Optional custom User-Agent header *)
9}
10
11(** Session information after login. *)
12type session = {
13 user_id : Matrix_proto.Id.User_id.t;
14 access_token : string;
15 device_id : Matrix_proto.Id.Device_id.t;
16 refresh_token : string option;
17}
18
19(** Matrix client. *)
20type t
21
22(** Create a new client.
23
24 The client is not logged in initially. Use {!Auth.login_password} or
25 {!with_session} to authenticate.
26
27 The environment must provide network and clock capabilities. *)
28val create :
29 sw:Eio.Switch.t ->
30 config:config ->
31 < net : _ Eio.Net.t ; clock : _ Eio.Time.clock ; fs : Eio.Fs.dir_ty Eio.Path.t ; .. > ->
32 t
33
34(** Restore a client from a saved session.
35
36 Returns a new client with the session set. The original client is unchanged. *)
37val with_session : t -> session -> t
38
39(** Get current session if logged in. *)
40val session : t -> session option
41
42(** Get the homeserver URL. *)
43val homeserver : t -> Uri.t
44
45(** Check if client is logged in. *)
46val is_logged_in : t -> bool
47
48(** Get the access token if logged in. *)
49val access_token : t -> string option
50
51(** Get the user ID if logged in. *)
52val user_id : t -> Matrix_proto.Id.User_id.t option
53
54(** Get the device ID if logged in. *)
55val device_id : t -> Matrix_proto.Id.Device_id.t option
56
57(** {1 Internal HTTP helpers}
58
59 These are used by the API modules. *)
60
61(** Make a GET request. *)
62val get :
63 t ->
64 path:string ->
65 ?query:(string * string) list ->
66 unit ->
67 (string, Error.t) result
68
69(** Make a POST request with JSON body. *)
70val post :
71 t ->
72 path:string ->
73 ?query:(string * string) list ->
74 body:string ->
75 unit ->
76 (string, Error.t) result
77
78(** Make a PUT request with JSON body. *)
79val put :
80 t ->
81 path:string ->
82 ?query:(string * string) list ->
83 body:string ->
84 unit ->
85 (string, Error.t) result
86
87(** Make a DELETE request. *)
88val delete :
89 t ->
90 path:string ->
91 ?query:(string * string) list ->
92 ?body:string ->
93 unit ->
94 (string, Error.t) result
95
96(** Make a POST request without authentication (for login/register). *)
97val post_unauthenticated :
98 t ->
99 path:string ->
100 ?query:(string * string) list ->
101 body:string ->
102 unit ->
103 (string, Error.t) result
104
105(** Decode a JSON response using a jsont codec. *)
106val decode_response : 'a Jsont.t -> string -> ('a, Error.t) result
107
108(** Encode a value to JSON string using a jsont codec.
109 Returns Error if encoding fails. *)
110val encode_body : 'a Jsont.t -> 'a -> (string, Error.t) result