anil.recoil.org
Matrix protocol in OCaml, Eio specialised
1(** Message sending and retrieval. *)
2
3(** {1 Sending Messages} *)
4
5(** Response from sending an event. *)
6type send_response = {
7 event_id : Matrix_proto.Id.Event_id.t;
8}
9
10(** JSON codec for send_response. *)
11val send_response_jsont : send_response Jsont.t
12
13(** Send a text message.
14
15 @param format Optional format (e.g., "org.matrix.custom.html").
16 @param formatted_body HTML body when format is set. *)
17val send_text :
18 Client.t ->
19 room_id:Matrix_proto.Id.Room_id.t ->
20 body:string ->
21 ?format:string ->
22 ?formatted_body:string ->
23 unit ->
24 (Matrix_proto.Id.Event_id.t, Error.t) result
25
26(** Send an emote message (like /me in IRC). *)
27val send_emote :
28 Client.t ->
29 room_id:Matrix_proto.Id.Room_id.t ->
30 body:string ->
31 unit ->
32 (Matrix_proto.Id.Event_id.t, Error.t) result
33
34(** Send a notice message (bot/automated messages). *)
35val send_notice :
36 Client.t ->
37 room_id:Matrix_proto.Id.Room_id.t ->
38 body:string ->
39 unit ->
40 (Matrix_proto.Id.Event_id.t, Error.t) result
41
42(** Send an image message.
43
44 @param url The mxc:// URL of the uploaded image.
45 @param info Optional image info (width, height, size, mimetype). *)
46val send_image :
47 Client.t ->
48 room_id:Matrix_proto.Id.Room_id.t ->
49 body:string ->
50 url:string ->
51 ?info:Jsont.json ->
52 unit ->
53 (Matrix_proto.Id.Event_id.t, Error.t) result
54
55(** Send a file message.
56
57 @param url The mxc:// URL of the uploaded file. *)
58val send_file :
59 Client.t ->
60 room_id:Matrix_proto.Id.Room_id.t ->
61 body:string ->
62 url:string ->
63 ?info:Jsont.json ->
64 unit ->
65 (Matrix_proto.Id.Event_id.t, Error.t) result
66
67(** Send a generic room event.
68
69 @param event_type The event type (e.g., "m.room.message").
70 @param content The event content as JSON. *)
71val send_event :
72 Client.t ->
73 room_id:Matrix_proto.Id.Room_id.t ->
74 event_type:string ->
75 content:Jsont.json ->
76 (Matrix_proto.Id.Event_id.t, Error.t) result
77
78(** {1 Redaction} *)
79
80(** Redact an event.
81
82 @param reason Optional reason for the redaction. *)
83val redact :
84 Client.t ->
85 room_id:Matrix_proto.Id.Room_id.t ->
86 event_id:Matrix_proto.Id.Event_id.t ->
87 ?reason:string ->
88 unit ->
89 (Matrix_proto.Id.Event_id.t, Error.t) result
90
91(** {1 Retrieving Messages} *)
92
93(** Direction for message retrieval. *)
94type direction = Forward | Backward
95
96(** Messages response. *)
97type messages_response = {
98 start : string;
99 end_ : string option;
100 chunk : Matrix_proto.Event.Raw_event.t list;
101 state : Matrix_proto.Event.Raw_event.t list;
102}
103
104(** Get messages from a room.
105
106 @param from Pagination token to start from.
107 @param dir Direction to paginate.
108 @param limit Maximum number of events to return.
109 @param filter Event filter (as filter ID or JSON). *)
110val get_messages :
111 Client.t ->
112 room_id:Matrix_proto.Id.Room_id.t ->
113 from:string ->
114 dir:direction ->
115 ?limit:int ->
116 ?filter:string ->
117 unit ->
118 (messages_response, Error.t) result
119
120(** Get a single event by ID. *)
121val get_event :
122 Client.t ->
123 room_id:Matrix_proto.Id.Room_id.t ->
124 event_id:Matrix_proto.Id.Event_id.t ->
125 (Matrix_proto.Event.Raw_event.t, Error.t) result
126
127(** Context around an event. *)
128type context = {
129 start : string;
130 end_ : string;
131 event : Matrix_proto.Event.Raw_event.t;
132 events_before : Matrix_proto.Event.Raw_event.t list;
133 events_after : Matrix_proto.Event.Raw_event.t list;
134 state : Matrix_proto.Event.Raw_event.t list;
135}
136
137(** Get context around an event.
138
139 @param limit Number of events to return before and after. *)
140val get_context :
141 Client.t ->
142 room_id:Matrix_proto.Id.Room_id.t ->
143 event_id:Matrix_proto.Id.Event_id.t ->
144 ?limit:int ->
145 unit ->
146 (context, Error.t) result