@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.
- package/LICENSE +21 -0
- package/README.md +293 -0
- package/dist/chat/admin/admin.css +78 -0
- package/dist/chat/admin/index.d.ts +92 -0
- package/dist/chat/admin/index.js +124 -0
- package/dist/chat/admin/react.d.ts +40 -0
- package/dist/chat/admin/react.js +169 -0
- package/dist/chat/chat.css +1003 -0
- package/dist/chat/client.d.ts +30 -0
- package/dist/chat/client.js +1300 -0
- package/dist/chat/exchange.d.ts +9 -0
- package/dist/chat/exchange.js +31 -0
- package/dist/chat/fake/index.d.ts +27 -0
- package/dist/chat/fake/index.js +48 -0
- package/dist/chat/fake/intercept.d.ts +21 -0
- package/dist/chat/fake/intercept.js +57 -0
- package/dist/chat/fake/sample.d.ts +4 -0
- package/dist/chat/fake/sample.js +6 -0
- package/dist/chat/fake/server.d.ts +168 -0
- package/dist/chat/fake/server.js +811 -0
- package/dist/chat/fake/xhr.d.ts +3 -0
- package/dist/chat/fake/xhr.js +104 -0
- package/dist/chat/index.d.ts +10 -0
- package/dist/chat/index.js +9 -0
- package/dist/chat/markdown.d.ts +29 -0
- package/dist/chat/markdown.js +161 -0
- package/dist/chat/react/Attachment.d.ts +39 -0
- package/dist/chat/react/Attachment.js +113 -0
- package/dist/chat/react/Chat.d.ts +48 -0
- package/dist/chat/react/Chat.js +139 -0
- package/dist/chat/react/Composer.d.ts +25 -0
- package/dist/chat/react/Composer.js +157 -0
- package/dist/chat/react/MessageRow.d.ts +21 -0
- package/dist/chat/react/MessageRow.js +114 -0
- package/dist/chat/react/NewDirectMessage.d.ts +23 -0
- package/dist/chat/react/NewDirectMessage.js +47 -0
- package/dist/chat/react/ThreadPanel.d.ts +25 -0
- package/dist/chat/react/ThreadPanel.js +17 -0
- package/dist/chat/react/Timeline.d.ts +27 -0
- package/dist/chat/react/Timeline.js +120 -0
- package/dist/chat/react/index.d.ts +7 -0
- package/dist/chat/react/index.js +6 -0
- package/dist/chat/react/mentions.d.ts +34 -0
- package/dist/chat/react/mentions.js +70 -0
- package/dist/chat/react/scroll.d.ts +26 -0
- package/dist/chat/react/scroll.js +27 -0
- package/dist/chat/react/timelineLayout.d.ts +26 -0
- package/dist/chat/react/timelineLayout.js +47 -0
- package/dist/chat/sanitize.d.ts +49 -0
- package/dist/chat/sanitize.js +264 -0
- package/dist/chat/store.d.ts +16 -0
- package/dist/chat/store.js +25 -0
- package/dist/chat/types.d.ts +340 -0
- package/dist/chat/types.js +1 -0
- 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 {};
|