@wtfalch/chat 0.1.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (55) hide show
  1. package/LICENSE +21 -0
  2. package/README.md +293 -0
  3. package/dist/chat/admin/admin.css +78 -0
  4. package/dist/chat/admin/index.d.ts +92 -0
  5. package/dist/chat/admin/index.js +124 -0
  6. package/dist/chat/admin/react.d.ts +40 -0
  7. package/dist/chat/admin/react.js +169 -0
  8. package/dist/chat/chat.css +1003 -0
  9. package/dist/chat/client.d.ts +30 -0
  10. package/dist/chat/client.js +1300 -0
  11. package/dist/chat/exchange.d.ts +9 -0
  12. package/dist/chat/exchange.js +31 -0
  13. package/dist/chat/fake/index.d.ts +27 -0
  14. package/dist/chat/fake/index.js +48 -0
  15. package/dist/chat/fake/intercept.d.ts +21 -0
  16. package/dist/chat/fake/intercept.js +57 -0
  17. package/dist/chat/fake/sample.d.ts +4 -0
  18. package/dist/chat/fake/sample.js +6 -0
  19. package/dist/chat/fake/server.d.ts +168 -0
  20. package/dist/chat/fake/server.js +811 -0
  21. package/dist/chat/fake/xhr.d.ts +3 -0
  22. package/dist/chat/fake/xhr.js +104 -0
  23. package/dist/chat/index.d.ts +10 -0
  24. package/dist/chat/index.js +9 -0
  25. package/dist/chat/markdown.d.ts +29 -0
  26. package/dist/chat/markdown.js +161 -0
  27. package/dist/chat/react/Attachment.d.ts +39 -0
  28. package/dist/chat/react/Attachment.js +113 -0
  29. package/dist/chat/react/Chat.d.ts +48 -0
  30. package/dist/chat/react/Chat.js +139 -0
  31. package/dist/chat/react/Composer.d.ts +25 -0
  32. package/dist/chat/react/Composer.js +157 -0
  33. package/dist/chat/react/MessageRow.d.ts +21 -0
  34. package/dist/chat/react/MessageRow.js +114 -0
  35. package/dist/chat/react/NewDirectMessage.d.ts +23 -0
  36. package/dist/chat/react/NewDirectMessage.js +47 -0
  37. package/dist/chat/react/ThreadPanel.d.ts +25 -0
  38. package/dist/chat/react/ThreadPanel.js +17 -0
  39. package/dist/chat/react/Timeline.d.ts +27 -0
  40. package/dist/chat/react/Timeline.js +120 -0
  41. package/dist/chat/react/index.d.ts +7 -0
  42. package/dist/chat/react/index.js +6 -0
  43. package/dist/chat/react/mentions.d.ts +34 -0
  44. package/dist/chat/react/mentions.js +70 -0
  45. package/dist/chat/react/scroll.d.ts +26 -0
  46. package/dist/chat/react/scroll.js +27 -0
  47. package/dist/chat/react/timelineLayout.d.ts +26 -0
  48. package/dist/chat/react/timelineLayout.js +47 -0
  49. package/dist/chat/sanitize.d.ts +49 -0
  50. package/dist/chat/sanitize.js +264 -0
  51. package/dist/chat/store.d.ts +16 -0
  52. package/dist/chat/store.js +25 -0
  53. package/dist/chat/types.d.ts +340 -0
  54. package/dist/chat/types.js +1 -0
  55. package/package.json +88 -0
@@ -0,0 +1,264 @@
1
+ /**
2
+ * A `formatted_body` from a stranger, made fit to set as a page's HTML
3
+ * (chat plan section 9, ticket #15).
4
+ *
5
+ * **The same technique `@wtfalch/email`'s `sanitise.ts` uses**: an allow-list
6
+ * walked over a document `DOMParser` built with no browsing context, so
7
+ * nothing in the markup loads or runs while it is being cleaned. Elements
8
+ * not on the list are unwrapped, so their text survives; attributes are
9
+ * kept by name, never removed by name, so one this has not heard of is gone
10
+ * rather than let through.
11
+ *
12
+ * **Narrower than mail's, and drawn straight into the page.** A message
13
+ * body is not a stranger's whole document -- there is no `<style>`, no
14
+ * `<meta>`, nothing that repoints the page -- so this keeps to the tags
15
+ * Matrix's own client-server spec recommends a client render, and drops
16
+ * everything else, its content included where the tag itself is the
17
+ * problem (`script`, `iframe`, `form` and the like).
18
+ *
19
+ * **A link's scheme is checked, not merely present.** `href` is parsed with
20
+ * `URL`, which resolves the escapes a pattern would miss, and only
21
+ * `http:`, `https:` and `mailto:` survive -- never `javascript:`, never
22
+ * `data:`.
23
+ *
24
+ * **An image is never a request to somewhere else.** `formatted_body`'s
25
+ * `img[src]` is only ever meaningful as a Matrix `mxc://` reference in the
26
+ * first place; this refuses anything that is not one, asks `allowMedia`
27
+ * whether the reference is one this session may load -- ordinarily the
28
+ * session's own `client.canLoadMedia`, which says no to any server but its
29
+ * own -- and then writes the reference back as `data-mxc`, never as a
30
+ * `src`. There is no `src` to write: Synapse serves media only to a
31
+ * request carrying the token, so the bytes are fetched by the renderer
32
+ * (`client.loadMedia`) and shown as an object URL (ticket #13).
33
+ *
34
+ * **Depth and size are capped.** A message nested or repeated past what a
35
+ * person would ever type by hand is truncated rather than walked in full --
36
+ * the "cannot lock the browser up" half of the safety requirement, since an
37
+ * allow-list alone says nothing about *how much* of the allowed shape a
38
+ * document may contain.
39
+ */
40
+ const HTML_NS = 'http://www.w3.org/1999/xhtml';
41
+ /** Matrix's own recommended tag list (client-server spec, "HTML
42
+ * sanitisation"), kept with their attributes filtered. */
43
+ const KEEP = new Set([
44
+ 'font',
45
+ 'del',
46
+ 'h1',
47
+ 'h2',
48
+ 'h3',
49
+ 'h4',
50
+ 'h5',
51
+ 'h6',
52
+ 'blockquote',
53
+ 'p',
54
+ 'a',
55
+ 'ul',
56
+ 'ol',
57
+ 'sup',
58
+ 'sub',
59
+ 'li',
60
+ 'b',
61
+ 'i',
62
+ 'u',
63
+ 'strong',
64
+ 'em',
65
+ 'strike',
66
+ 's',
67
+ 'code',
68
+ 'hr',
69
+ 'br',
70
+ 'div',
71
+ 'table',
72
+ 'thead',
73
+ 'tbody',
74
+ 'tr',
75
+ 'th',
76
+ 'td',
77
+ 'caption',
78
+ 'pre',
79
+ 'span',
80
+ 'img',
81
+ 'details',
82
+ 'summary',
83
+ ]);
84
+ /** Removed with everything inside them -- the same reasoning as `@wtfalch/email`'s
85
+ * `DISCARD`: a script's source as text is harmless, but a `<noscript>` or
86
+ * `<xmp>` body parses as markup the second time it is read. */
87
+ const DISCARD = new Set([
88
+ 'script',
89
+ 'style',
90
+ 'iframe',
91
+ 'frame',
92
+ 'frameset',
93
+ 'object',
94
+ 'embed',
95
+ 'applet',
96
+ 'form',
97
+ 'input',
98
+ 'button',
99
+ 'select',
100
+ 'option',
101
+ 'optgroup',
102
+ 'textarea',
103
+ 'label',
104
+ 'svg',
105
+ 'math',
106
+ 'template',
107
+ 'noscript',
108
+ 'canvas',
109
+ 'audio',
110
+ 'video',
111
+ 'source',
112
+ 'track',
113
+ 'base',
114
+ 'link',
115
+ 'meta',
116
+ 'head',
117
+ 'title',
118
+ 'dialog',
119
+ 'portal',
120
+ 'slot',
121
+ 'noembed',
122
+ 'noframes',
123
+ 'xmp',
124
+ 'plaintext',
125
+ 'datalist',
126
+ 'map',
127
+ 'area',
128
+ ]);
129
+ /** Presentational and descriptive, kept on every tag that carries them.
130
+ * `href` (on `a`), `src`/`alt` (on `img`) and `class` (on `code`, and only
131
+ * a `language-*` token) are handled on their own below, never through this
132
+ * set -- each needs a check this generic allow-list cannot express. */
133
+ const ATTRIBUTES = new Set(['title', 'colspan', 'rowspan', 'start']);
134
+ /** How far into the document, and how much of it, this will walk. Past
135
+ * either, the rest is dropped rather than processed -- nested or repeated
136
+ * content no person would type by hand is the shape a browser lockup
137
+ * takes, not a tag this has not heard of. */
138
+ const MAX_DEPTH = 32;
139
+ const MAX_NODES = 4000;
140
+ /** `http:`/`https:`/`mailto:` only. See `markdown.ts`'s own `safeLinkHref`;
141
+ * the two are the same rule, written twice because sending and rendering
142
+ * are different modules with different jobs, not because the rule
143
+ * differs. */
144
+ function safeLinkHref(raw) {
145
+ let url;
146
+ try {
147
+ url = new URL(raw.trim());
148
+ }
149
+ catch {
150
+ return null;
151
+ }
152
+ return url.protocol === 'https:' || url.protocol === 'http:' || url.protocol === 'mailto:'
153
+ ? url.href
154
+ : null;
155
+ }
156
+ function cleanAttributes(element) {
157
+ const name = element.localName;
158
+ for (const attribute of Array.from(element.attributes)) {
159
+ const key = attribute.name.toLowerCase();
160
+ if (name === 'a' && key === 'href') {
161
+ const href = safeLinkHref(attribute.value);
162
+ if (href)
163
+ element.setAttribute('href', href);
164
+ else
165
+ element.removeAttribute(attribute.name);
166
+ continue;
167
+ }
168
+ if (name === 'code' && key === 'class') {
169
+ if (!/^language-[\w-]+$/.test(attribute.value))
170
+ element.removeAttribute(attribute.name);
171
+ continue;
172
+ }
173
+ if (!ATTRIBUTES.has(key) && !key.startsWith('aria-'))
174
+ element.removeAttribute(attribute.name);
175
+ }
176
+ if (name === 'a') {
177
+ // Every link leaves the page for a tab of its own, and takes nothing
178
+ // with it: not a handle back to this window.
179
+ element.setAttribute('target', '_blank');
180
+ element.setAttribute('rel', 'noopener noreferrer');
181
+ }
182
+ }
183
+ /** `img` is handled on its own rather than through `cleanAttributes`: a
184
+ * disallowed source drops the whole element, where every other tag here
185
+ * only ever loses an attribute.
186
+ *
187
+ * What survives carries `data-mxc` and no `src` at all, so the element
188
+ * this returns can never make a request on its own -- not to another
189
+ * server, and not to this one's unauthenticated endpoints. The renderer
190
+ * fills the `src` in with an object URL it fetched with the token. */
191
+ function cleanImage(element, options) {
192
+ const rawSrc = element.getAttribute('src');
193
+ const allowed = !!rawSrc && /^mxc:\/\//i.test(rawSrc) && options.allowMedia(rawSrc);
194
+ if (!allowed)
195
+ return false;
196
+ const alt = element.getAttribute('alt');
197
+ const title = element.getAttribute('title');
198
+ for (const attribute of Array.from(element.attributes))
199
+ element.removeAttribute(attribute.name);
200
+ element.setAttribute('data-mxc', rawSrc);
201
+ if (alt)
202
+ element.setAttribute('alt', alt);
203
+ if (title)
204
+ element.setAttribute('title', title);
205
+ return true;
206
+ }
207
+ /** The walk. Iterative rather than recursive, with a node budget and a
208
+ * depth cap, both enforced as the queue is drained rather than after the
209
+ * fact -- a document past either is never fully built up in memory. */
210
+ function sweep(root, options) {
211
+ let budget = MAX_NODES;
212
+ const queue = Array.from(root.childNodes, (node) => ({
213
+ node,
214
+ depth: 1,
215
+ }));
216
+ while (queue.length > 0) {
217
+ const next = queue.pop();
218
+ if (!next)
219
+ break;
220
+ const { node, depth } = next;
221
+ budget -= 1;
222
+ if (budget <= 0 || depth > MAX_DEPTH) {
223
+ node.parentNode?.removeChild(node);
224
+ continue;
225
+ }
226
+ if (node.nodeType === 3)
227
+ continue; // text
228
+ if (node.nodeType !== 1) {
229
+ node.parentNode?.removeChild(node);
230
+ continue;
231
+ }
232
+ const element = node;
233
+ const name = element.localName;
234
+ if (element.namespaceURI !== HTML_NS || DISCARD.has(name)) {
235
+ element.remove();
236
+ continue;
237
+ }
238
+ if (!KEEP.has(name)) {
239
+ const children = Array.from(element.childNodes);
240
+ element.replaceWith(...children);
241
+ for (const child of children)
242
+ queue.push({ node: child, depth });
243
+ continue;
244
+ }
245
+ if (name === 'img') {
246
+ if (!cleanImage(element, options))
247
+ element.remove();
248
+ continue; // img is void: nothing under it to walk
249
+ }
250
+ cleanAttributes(element);
251
+ for (const child of Array.from(element.childNodes))
252
+ queue.push({ node: child, depth: depth + 1 });
253
+ }
254
+ }
255
+ /** A `formatted_body`, cleaned to what may be drawn as HTML. Browser only:
256
+ * it needs `DOMParser`. */
257
+ export function sanitizeHtml(html, options) {
258
+ if (typeof DOMParser === 'undefined')
259
+ return '';
260
+ const parsed = new DOMParser().parseFromString(html, 'text/html');
261
+ const body = parsed.body?.localName === 'body' ? parsed.body : parsed.createElement('body');
262
+ sweep(body, options);
263
+ return body.innerHTML;
264
+ }
@@ -0,0 +1,16 @@
1
+ import { IndexedDBStore } from 'matrix-js-sdk';
2
+ /** The `dbName` this package hands `IndexedDBStore` for a given
3
+ * `storeName`. Its own function so a test can assert on it directly,
4
+ * without starting a client. matrix-js-sdk prefixes this again with
5
+ * `matrix-js-sdk:` for the real IndexedDB database name
6
+ * (`indexeddb-local-backend.ts`) -- an internal of its own, not this
7
+ * package's to name. */
8
+ export declare function storeDbName(storeName: string): string;
9
+ /**
10
+ * A local store named from `storeName`, so two companies open in the same
11
+ * browser -- or two fakes in the same test process -- never share one.
12
+ *
13
+ * `indexedDB` is read at call time rather than imported, so this works both
14
+ * in a real browser and under vitest with `fake-indexeddb/auto` installed.
15
+ */
16
+ export declare function createChatStore(storeName: string): IndexedDBStore;
@@ -0,0 +1,25 @@
1
+ import { IndexedDBStore } from 'matrix-js-sdk';
2
+ /** The `dbName` this package hands `IndexedDBStore` for a given
3
+ * `storeName`. Its own function so a test can assert on it directly,
4
+ * without starting a client. matrix-js-sdk prefixes this again with
5
+ * `matrix-js-sdk:` for the real IndexedDB database name
6
+ * (`indexeddb-local-backend.ts`) -- an internal of its own, not this
7
+ * package's to name. */
8
+ export function storeDbName(storeName) {
9
+ return `wtfalch-messaging-${storeName}`;
10
+ }
11
+ /**
12
+ * A local store named from `storeName`, so two companies open in the same
13
+ * browser -- or two fakes in the same test process -- never share one.
14
+ *
15
+ * `indexedDB` is read at call time rather than imported, so this works both
16
+ * in a real browser and under vitest with `fake-indexeddb/auto` installed.
17
+ */
18
+ export function createChatStore(storeName) {
19
+ const dbName = storeDbName(storeName);
20
+ return new IndexedDBStore({
21
+ indexedDB: globalThis.indexedDB,
22
+ dbName,
23
+ localStorage: globalThis.localStorage,
24
+ });
25
+ }
@@ -0,0 +1,340 @@
1
+ /**
2
+ * The exchange contract, as `apps/chat-service`'s README and
3
+ * `src/exchange.ts` define it: `POST <exchangeUrl>` with a ZITADEL bearer
4
+ * token and a device id, back a Matrix personal session.
5
+ */
6
+ export type ExchangeBody = {
7
+ homeserver: string;
8
+ user_id: string;
9
+ device_id: string;
10
+ access_token: string;
11
+ expires_at: string;
12
+ };
13
+ /** A joined room or invitation, reduced to what a chat list needs to draw
14
+ * itself. Nothing here is a Matrix type: a UI built on this package never
15
+ * imports matrix-js-sdk. */
16
+ export type ChatRoomSummary = {
17
+ readonly id: string;
18
+ readonly name: string;
19
+ /** Whether this is a direct message or group DM, from the
20
+ * account's `m.direct` data (or an invitation's `is_direct` flag) --
21
+ * rather than guessing from membership counts. */
22
+ readonly isDirect: boolean;
23
+ /** Invited rooms need an answer before their timeline can be opened. */
24
+ readonly membership: 'join' | 'invite';
25
+ /** Matrix's own total notification count for this room (`unread_
26
+ * notifications.notification_count` from `/sync`), zeroed the moment
27
+ * `markRoomRead` sends a receipt for the newest event. An unanswered
28
+ * invitation contributes one until answered or withdrawn. */
29
+ readonly unreadCount: number;
30
+ };
31
+ /** Someone this person can start a direct message with: a member of the
32
+ * company space. Guests are never in the space (chat plan section 5), so
33
+ * a guest can never appear here -- which is how "the UI does not offer it"
34
+ * is kept true without this package knowing what a guest is. */
35
+ export type ChatPerson = {
36
+ readonly userId: string;
37
+ /** Their display name in the company space, falling back to `userId`. */
38
+ readonly name: string;
39
+ };
40
+ /** Where a `m.room.message` event stands with the homeserver, for the
41
+ * composer's optimistic send (chat plan section 9, ticket #15). `'sent'`
42
+ * covers both "accepted by the server" and "confirmed by sync" -- a UI
43
+ * never needs to tell those apart, only pending/sent/failed. */
44
+ export type ChatMessageStatus = 'sent' | 'pending' | 'failed';
45
+ /** One key people have reacted to a message with -- an emoji, usually,
46
+ * but Matrix allows any string and a client must not assume otherwise. */
47
+ export type ChatReaction = {
48
+ /** The reaction's own text, exactly as it was sent. */
49
+ readonly key: string;
50
+ readonly count: number;
51
+ /** Whether the signed-in person is one of them. */
52
+ readonly mine: boolean;
53
+ /** Who reacted, by display name, each once. */
54
+ readonly people: readonly string[];
55
+ };
56
+ /** What a thread hangs off its root message: how many replies, and who
57
+ * wrote them. `null` on a message that has started no thread.
58
+ *
59
+ * Matrix threads are one level deep -- a reply inside a thread relates to
60
+ * the *root*, never to another reply -- so a thread summary never appears
61
+ * on an event that is itself inside a thread. */
62
+ export type ChatThreadSummary = {
63
+ readonly replyCount: number;
64
+ /** Everyone with a message in the thread, by display name, first to
65
+ * last, each once. The root's own sender included: they started it. */
66
+ readonly participants: readonly string[];
67
+ };
68
+ /** A file hanging off a message, from its `m.file`/`m.image` content.
69
+ *
70
+ * `mxcUri` is a Matrix reference, never a URL, and deliberately so:
71
+ * reading it needs this session's own token, which is `loadMedia`'s job.
72
+ * Handing a UI something it could put straight in an `<img src>` is how a
73
+ * client ends up on the legacy unauthenticated endpoint (ticket #13). */
74
+ export type ChatAttachment = {
75
+ readonly name: string;
76
+ readonly mimeType: string;
77
+ /** Bytes, as the sender reported them. `0` when the sender sent none. */
78
+ readonly size: number;
79
+ readonly mxcUri: string;
80
+ /** Whether this package will preview it inline. An image, and only ever
81
+ * by the `mimeType` the sender declared -- which is why the preview is
82
+ * still fetched through `loadMedia` rather than pointed at. */
83
+ readonly isImage: boolean;
84
+ };
85
+ /** A file still going up, as `timeline()` shows it: a message that is not
86
+ * a message yet. `total` is the file's own size, so a caller draws a
87
+ * proportion without knowing anything about chunks. */
88
+ export type ChatUploadProgress = {
89
+ readonly loaded: number;
90
+ readonly total: number;
91
+ };
92
+ /** A `m.room.message` event, reduced to what the timeline draws. Nothing
93
+ * here is a Matrix type -- a UI built on this package never imports
94
+ * matrix-js-sdk. A cancelled send is removed rather than represented: it
95
+ * never appears here once `cancelMessage` has been called. */
96
+ export type ChatTimelineEvent = {
97
+ readonly id: string;
98
+ readonly senderId: string;
99
+ /** The room member's display name, falling back to `senderId` when none
100
+ * is set. */
101
+ readonly senderName: string;
102
+ readonly ts: number;
103
+ readonly body: string;
104
+ /** The event's raw `formatted_body`, `null` when it carried none or its
105
+ * `format` was not `org.matrix.custom.html`. A stranger's HTML: a caller
106
+ * sanitises it (`@wtfalch/chat/react`'s `MessageRow` does)
107
+ * before ever setting it as a page's HTML. */
108
+ readonly formattedBody: string | null;
109
+ readonly status: ChatMessageStatus;
110
+ /** The thread this message started, or `null` for a message with no
111
+ * replies -- and always `null` for a message read out of a thread's own
112
+ * timeline, because a thread cannot hold another (ticket #17). */
113
+ readonly thread: ChatThreadSummary | null;
114
+ /** What people have reacted with, most-reacted first and then by key, so
115
+ * the order is the same for everyone looking at it. Empty for a message
116
+ * nobody has reacted to. */
117
+ readonly reactions: readonly ChatReaction[];
118
+ /** Whether this message mentions the signed-in person, from its own
119
+ * `m.mentions.user_ids`. */
120
+ readonly mentionsMe: boolean;
121
+ /** Whether the sender has since replaced this message's text with an
122
+ * `m.replace`. `body` and `formattedBody` are already the new text --
123
+ * this only says that the reader is not looking at what was first
124
+ * written (ticket #19). */
125
+ readonly edited: boolean;
126
+ /** Whether this message has been redacted. `body` and `formattedBody`
127
+ * are empty, because a redaction takes the content away: a renderer
128
+ * draws a tombstone in its place rather than dropping the row, which
129
+ * would move everything under a reader's eyes mid-scroll. */
130
+ readonly deleted: boolean;
131
+ /** The file this message carries, or `null` for a plain one. */
132
+ readonly attachment: ChatAttachment | null;
133
+ /** Set only while a file is still going up: this row is this client's
134
+ * own, has no event id on the server yet, and `status` is `'pending'`
135
+ * or `'failed'`. `null` on every message that is really a message. */
136
+ readonly upload: ChatUploadProgress | null;
137
+ /** Whether the signed-in person sent this. What decides whether editing
138
+ * and deleting are offered at all: Matrix ignores an `m.replace` from
139
+ * anybody but the original sender, and moderating other people's
140
+ * messages is the manage app's (ticket #19's "not in this ticket"). */
141
+ readonly mine: boolean;
142
+ };
143
+ /** The rest of what a send can carry, beyond the text itself. */
144
+ export type ChatSendOptions = {
145
+ /** The message that started the thread this goes into. Omit it and the
146
+ * message goes to the room (ticket #17). */
147
+ threadId?: string | null;
148
+ /** Who this message mentions, by Matrix user id. Sent as
149
+ * `m.mentions.user_ids`, which is what decides whose notification this
150
+ * is -- the text alone never does (ticket #18). */
151
+ mentions?: readonly string[];
152
+ };
153
+ /** A room's currently-known timeline, oldest first. */
154
+ export type ChatTimelinePage = {
155
+ readonly events: readonly ChatTimelineEvent[];
156
+ /** Whether `paginate` might still have older history to fetch. Starts
157
+ * `true` and only `paginate` itself ever turns it `false`, once a page
158
+ * comes back with nothing more behind it. */
159
+ readonly hasMore: boolean;
160
+ };
161
+ /** Whether the sync loop is caught up, working to catch up (after a
162
+ * network drop, or recovering from a refused sync position with a fresh
163
+ * full sync), or not connected at all. */
164
+ export type ChatConnectionStatus = 'connected' | 'catching-up' | 'offline';
165
+ export type CreateChatClientOptions = {
166
+ /** `POST` here exchanges the agora's current ZITADEL token for a Matrix
167
+ * one. See `apps/chat-service/README.md`. */
168
+ exchangeUrl: string;
169
+ /** A current ZITADEL access token, fetched fresh on every call -- this
170
+ * package never caches or refreshes it itself. Called once to start, and
171
+ * again on every refresh (near expiry, or after `M_UNKNOWN_TOKEN`). */
172
+ getAccessToken: () => string | Promise<string>;
173
+ /** The id this agora, on this device, made once for the exchange -- see the
174
+ * chat plan section 4. Stable across sign-ins so MAS keeps one Matrix
175
+ * device for its whole life. */
176
+ deviceId: string;
177
+ /** Names this client's local store, so two companies open in one browser
178
+ * never share one. Typically the company/project id. */
179
+ storeName: string;
180
+ };
181
+ /**
182
+ * What a UI needs from a signed-in chat session: whether it is running, the
183
+ * rooms the person is in, and a way to hear about changes. No timeline, no
184
+ * sending -- that is a later ticket (#15).
185
+ */
186
+ export type ChatClient = {
187
+ /** Exchanges for a Matrix session and starts syncing. Resolves once the
188
+ * first sync has landed, so `rooms()` is meaningful right after. Calling
189
+ * it again while already started is a no-op. */
190
+ start: () => Promise<void>;
191
+ /** Stops syncing and releases the underlying Matrix client. Safe to call
192
+ * more than once, and before `start()` ever resolves. */
193
+ stop: () => void;
194
+ /** The rooms the person is currently in. Empty before `start()` resolves. */
195
+ rooms: () => ChatRoomSummary[];
196
+ /** Called with the current room list whenever it changes. Returns a
197
+ * function that stops listening. */
198
+ onRoomsChanged: (listener: (rooms: ChatRoomSummary[]) => void) => () => void;
199
+ /** The signed-in Matrix user id, or `null` before `start()` resolves. */
200
+ userId: () => string | null;
201
+ /** A room's currently-known timeline, or -- given `threadId`, the id of
202
+ * the message that started one -- that thread's own, root first. Empty,
203
+ * with `hasMore: true`, for a room `start()` has not caught up to yet.
204
+ *
205
+ * A thread's replies are never in the room's own timeline: they live in
206
+ * the thread and nowhere else, which is what keeps the room readable. */
207
+ timeline: (roomId: string, threadId?: string | null) => ChatTimelinePage;
208
+ /** Called whenever anything in `roomId` changes -- a new event, an
209
+ * optimistic send's status settling, an older page landing, or a reply
210
+ * in one of its threads. Returns a function that stops listening.
211
+ *
212
+ * No thread id: a reply changes both the thread it is in *and* the reply
213
+ * count on its root in the room, so a caller reading either has to hear
214
+ * about it. One subscription per room says that once. */
215
+ onTimelineChanged: (roomId: string, listener: () => void) => () => void;
216
+ /** Fetches one older page of history and prepends it, in the room or in
217
+ * one of its threads. Resolves once `timeline()` reflects it; a caller
218
+ * reads `hasMore` off that, not off this promise. A no-op, resolved
219
+ * promise for a room not joined. */
220
+ paginate: (roomId: string, threadId?: string | null) => Promise<void>;
221
+ /** Everyone joined to `roomId`, by name, the signed-in person included --
222
+ * who a message in this room can mention. A room's own membership, not
223
+ * the company's: mentioning somebody who is not here would notify
224
+ * nobody. Empty for a room this client does not know. */
225
+ roomMembers: (roomId: string) => ChatPerson[];
226
+ /** Adds the signed-in person's reaction to `eventId`, or takes it away
227
+ * if it is already theirs -- one call for both, because that is the one
228
+ * thing a person ever means by pressing a reaction.
229
+ *
230
+ * Concurrent toggles converge because Matrix does the converging: each
231
+ * reaction is its own event and removing one is a redaction of that
232
+ * event, so two clients pressing at once end up with both events, or
233
+ * neither, and never with a count nobody can explain. */
234
+ toggleReaction: (roomId: string, eventId: string, key: string) => Promise<void>;
235
+ /** Sends `text` as `m.room.message`, converting Markdown shortcuts to
236
+ * `formatted_body` (`@wtfalch/chat`'s own conversion, not
237
+ * matrix-js-sdk's). Given `threadId`, sends it into that thread instead
238
+ * of the room. Returns the local id the optimistic event appears under
239
+ * in `timeline()` at once, before the network round-trip settles it --
240
+ * see `ChatMessageStatus`. */
241
+ sendMessage: (roomId: string, text: string, options?: ChatSendOptions) => string;
242
+ /** Replaces the text of the signed-in person's own message, as Matrix's
243
+ * `m.replace`: a new event carrying `m.new_content`, related to the
244
+ * original. The original event stays where it is, keeping its place in
245
+ * the timeline and its own id -- which is why an edit never reorders a
246
+ * conversation and never breaks a thread hanging off it.
247
+ *
248
+ * A no-op for a message somebody else sent, one already deleted, or an
249
+ * event this client does not have: Matrix would ignore such an edit
250
+ * anyway, and refusing here keeps the UI's rule and the client's rule
251
+ * the same one. */
252
+ editMessage: (roomId: string, eventId: string, text: string) => Promise<void>;
253
+ /** Deletes the signed-in person's own message, as a redaction. Synapse
254
+ * empties the event's content at once and replaces the stored copy with
255
+ * its redacted form after `redaction_retention_period` (7 days by
256
+ * default), so the text eventually leaves the database too.
257
+ *
258
+ * The event itself stays in the timeline, and `deleted` says so: a
259
+ * thread hanging off a deleted message keeps every reply, and a reader
260
+ * scrolling past does not have the page move under them. */
261
+ deleteMessage: (roomId: string, eventId: string) => Promise<void>;
262
+ /** Retries a `'failed'` send with the same content. A no-op if `localId`
263
+ * is no longer in the room's pending events (already retried, already
264
+ * settled). */
265
+ retryMessage: (roomId: string, localId: string) => void;
266
+ /** Cancels an in-progress upload or withdraws a failed send. */
267
+ cancelMessage: (roomId: string, localId: string) => void;
268
+ /** The event id the signed-in person has read up to in `roomId`, or
269
+ * `null` with nothing read or no such room. For the timeline's unread
270
+ * separator -- read once when a room is opened, not tracked live, so the
271
+ * marker does not move while someone is reading past it. */
272
+ readUpToEventId: (roomId: string) => string | null;
273
+ /** Whether this session may load `mxcUri` at all: a well-formed
274
+ * `mxc://` on *this* homeserver. `false` for anything else, a reference
275
+ * to another server included.
276
+ *
277
+ * A predicate rather than a URL, because there is no URL a renderer
278
+ * could use: Synapse serves media only to a request carrying the token
279
+ * (`enable_authenticated_media`), so the bytes come through
280
+ * `loadMedia`. This is what the sanitiser asks before it keeps an
281
+ * `img` at all. */
282
+ canLoadMedia: (mxcUri: string) => boolean;
283
+ /** Fetches `mxcUri` from `/_matrix/client/v1/media/download` with this
284
+ * session's token and resolves with an object URL for the bytes, or
285
+ * `null` if this session may not load it or the fetch failed.
286
+ *
287
+ * **The caller owns the URL and must `URL.revokeObjectURL` it**, or the
288
+ * blob is held for the life of the document. The React components in
289
+ * `@wtfalch/chat/react` do that on unmount. */
290
+ loadMedia: (mxcUri: string) => Promise<string | null>;
291
+ /** Sends `file` to `roomId` as `m.image` (an image) or `m.file`, and
292
+ * returns the id its row carries in `timeline()` at once -- before a
293
+ * byte has gone up. That row is `'pending'` with `upload` counting, and
294
+ * `'failed'` if the upload fails. Once uploaded, the Matrix local echo
295
+ * replaces it with its own event id. Use the current timeline row's id
296
+ * for `retryMessage` and `cancelMessage`.
297
+ *
298
+ * Throws for a file over `MAX_UPLOAD_BYTES`, before anything is read or
299
+ * sent: Synapse would refuse it after the whole upload, which is a long
300
+ * wait to be told no. */
301
+ sendFile: (roomId: string, file: File, options?: ChatSendOptions) => string;
302
+ /** The sum of every room's `unreadCount` -- the agora's badge. */
303
+ totalUnreadCount: () => number;
304
+ /** Sends an `m.read` receipt for the newest event in `roomId` and clears
305
+ * its unread count right away, rather than waiting on the server to
306
+ * echo it back. Call this when a room is opened, and again when the
307
+ * person scrolls to the newest message. A no-op if the room is unknown
308
+ * or has no events yet. */
309
+ markRoomRead: (roomId: string) => Promise<void>;
310
+ /** Everyone in the company space except the signed-in person, by name.
311
+ * Empty before `start()` resolves, and empty for a session whose
312
+ * account is in no space. */
313
+ people: () => ChatPerson[];
314
+ /** Opens the direct room with exactly `userIds` and resolves with its id.
315
+ *
316
+ * Reopens rather than duplicates: an existing room is found through the
317
+ * account's own `m.direct` data, the same signal every Matrix client
318
+ * uses, and a hidden one is unhidden. A different set of people is a
319
+ * different DM, so changing a group's people starts a new room. The new
320
+ * room is created `is_direct` with no name and no initial state, which
321
+ * is the only shape the Synapse gate lets a member create at all (chat
322
+ * plan section 5).
323
+ *
324
+ * Resolves once the room has actually arrived through sync, so a caller
325
+ * can navigate straight to it. */
326
+ startDirectMessage: (userIds: readonly string[]) => Promise<string>;
327
+ /** Takes a direct room out of `rooms()` without leaving it, so its
328
+ * history is untouched and the next `startDirectMessage` with the same
329
+ * people brings it straight back. A no-op for a room that is not
330
+ * direct. */
331
+ hideDirectMessage: (roomId: string) => Promise<void>;
332
+ /** Answer an invitation. Matrix sync updates every client of this account. */
333
+ acceptInvitation: (roomId: string) => Promise<void>;
334
+ declineInvitation: (roomId: string) => Promise<void>;
335
+ /** connected, catching up, or offline -- see `ChatConnectionStatus`. */
336
+ connectionStatus: () => ChatConnectionStatus;
337
+ /** Called with the current status whenever it changes. Returns a
338
+ * function that stops listening. */
339
+ onConnectionStatusChanged: (listener: (status: ChatConnectionStatus) => void) => () => void;
340
+ };
@@ -0,0 +1 @@
1
+ export {};