@wtfalch/chat 0.1.0 → 0.3.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/README.md CHANGED
@@ -60,6 +60,47 @@ the person reaches the newest message. `chat.connectionStatus()` (and
60
60
  `onConnectionStatusChanged`) is `'connected'`, `'catching-up'` or
61
61
  `'offline'`, for a status the UI can render.
62
62
 
63
+ **Mute** ([#5](https://github.com/wtfalch/chat/issues/5)).
64
+ `chat.muteRoom(roomId, muted)` writes (or, unmuting, removes) a room-scoped
65
+ push rule carrying the `dont_notify` action, through matrix-js-sdk's own
66
+ `setRoomMutePushRule` -- scoped `'global'`, so muting mutes every device
67
+ signed into the account, not just this one. `room.muted` is what a list
68
+ dims. Muting only ever changes that: `unreadCount` keeps climbing regardless,
69
+ because a muted room stops notifying and nothing else.
70
+
71
+ **Presence and typing** ([#7](https://github.com/wtfalch/chat/issues/7)).
72
+ Both are ephemeral and both are Matrix-native, which is why they are one
73
+ ticket: `chat.presence(userId)` reads someone's `m.presence` as `'online'`,
74
+ `'busy'`, `'away'` or `'offline'`, and `chat.onPresenceChanged(listener)`
75
+ hears about it changing. `chat.sendTyping(roomId, typing)` sends `m.typing`;
76
+ `chat.onTypingChanged(roomId, listener)` hears who else is typing in a room.
77
+ `@wtfalch/design`'s `Presence` and `Typing` components draw whatever these
78
+ return.
79
+
80
+ **Presence is off in production.** Every company's Synapse is generated by
81
+ `bootstrap/steps/chat-instance.ts:142` in `wtfalch/app-template`, which
82
+ still hardcodes it off, tracked at that project's
83
+ [#352](https://github.com/wtfalch/app-template/issues/352). Until that
84
+ lands, `presence()` reports `'offline'` for everyone, always -- not because
85
+ nobody is online, but because Synapse never says. The test stack turns it
86
+ on, so the integration suite proves all four states against a real server.
87
+ `sendTyping` and `onTypingChanged` are unaffected and work today.
88
+
89
+ **Announcing idleness** ([#20](https://github.com/wtfalch/chat/issues/20)).
90
+ `chat.announcePresence('away' | 'online')` is the only way `'away'` ever
91
+ happens. Left alone a syncing client re-asserts `'online'` on every poll,
92
+ so a tab open overnight reads as available until morning. The SDK cannot
93
+ judge this for itself -- a cron job calling `timeline()` looks exactly like
94
+ a person reading -- so the app calls it from what it alone can see: the
95
+ Page Visibility API, a locked screen, real keystrokes.
96
+
97
+ It changes the `set_presence` the sync itself carries, not only the
98
+ `PUT .../presence/status` that Synapse's next sync would undo, and it is
99
+ re-applied across this client's own restarts. `sendTyping`, by contrast,
100
+ is a single call and not a heartbeat -- Matrix auto-expires a typing state
101
+ after its own timeout, so a composer that wants "typing" to keep showing
102
+ through a long pause has to call this again itself on further keystrokes.
103
+
63
104
  **Direct messages** ([#16](https://github.com/wtfalch/messaging/issues/16)).
64
105
  `chat.people()` is everyone in the company space but the signed-in person --
65
106
  the space is where a company's membership lives, and a guest is never in it,
@@ -142,8 +183,32 @@ next reload; the reply itself is never lost.
142
183
  Both refuse a message somebody else sent, and `event.mine` is what a UI draws
143
184
  that rule from. Ownership is the whole rule: Matrix ignores an `m.replace`
144
185
  from anybody but the original sender, and the default power levels let a
145
- member redact their own event and nobody else's. Moderating other people's
146
- messages is the manage app's, later.
186
+ member redact their own event and nobody else's.
187
+
188
+ **Moderation** ([#29](https://github.com/wtfalch/chat/issues/29)). A member
189
+ reports a message with `reportMessage(roomId, eventId, reason)`. The admin SDK
190
+ reads reports with `listReports()`, removes anyone's message from a channel
191
+ with `redactMessage(roomId, eventId)`, and bans a person from a channel with
192
+ `banPerson(roomId, subject, reason?)` until `unbanPerson(roomId, subject)`.
193
+ Admins act as `@chat-admin`, and only in channels the service created.
194
+
195
+ **Pinned messages** ([#8](https://github.com/wtfalch/chat/issues/8)).
196
+ `chat.pinMessage(roomId, eventId)` and `chat.unpinMessage(roomId, eventId)` add
197
+ to and take from Matrix's own `m.room.pinned_events` state, one list the whole
198
+ room shares; `chat.pinnedMessages(roomId)` reads it back, each pinned id
199
+ reduced the same way `timeline()` reduces a message, in the order the state
200
+ lists them.
201
+
202
+ Ordinary members can call these
203
+ ([wtfalch/agora#255](https://github.com/wtfalch/agora/issues/255) overrides
204
+ the chat plan's "nobody but `@chat-admin` ... pins", for pinning only):
205
+ `apps/chat-service`'s `powerLevels()` grants `m.room.pinned_events` its own
206
+ power level, 0. That reaches only a room created after the change lands --
207
+ an existing room's power levels are never backfilled, so a member's pin in an
208
+ older channel still fails. `pinMessage` **rejects** rather than resolving
209
+ quietly when that happens: a silently-ignored pin reads as "the button does
210
+ nothing," and this package would rather a caller catch a real error than
211
+ draw a pin that never took.
147
212
 
148
213
  **Redacted text does leave the database, but not at once.** A redaction
149
214
  empties the event for every client immediately; Synapse replaces its own
@@ -228,18 +293,43 @@ id from `timeline()` before calling `retryMessage` or `cancelMessage`.
228
293
  until the upload completes. Images preview inline and all files have a named
229
294
  Download link. A failed download offers Retry download.
230
295
 
231
- Media bytes are fetched with the session bearer token from
232
- `/_matrix/client/v1/media/download/*`, including images inside formatted messages.
233
- There is no legacy unauthenticated download fallback. `loadMedia(mxcUri)` returns
234
- a blob URL or null; callers must revoke returned URLs. The React views revoke
235
- theirs on replacement and unmount, including downloads that finish after unmount.
236
- Uploads use Matrix's separate authenticated `/_matrix/media/v3/upload` endpoint.
237
- Only references on the session's own homeserver are accepted.
238
-
239
- **Known limit: files are not locked to their channels.** A person with a valid
240
- homeserver token and a media id may retrieve that file without membership in the
241
- room where it was posted. Deleting the message removes its visible reference;
242
- it does not delete the stored media. No malware scanning or file search is included.
296
+ Media bytes are fetched with the session bearer token from `apps/chat-service`'s
297
+ `GET /_chat/media/{serverName}/{mediaId}?roomId=...&eventId=...`, never from
298
+ Synapse's `/_matrix/client/v1/media/download/*` directly, including images inside
299
+ formatted messages. `loadMedia(mxcUri, roomId, eventId)` returns a blob URL or
300
+ null; every `ChatAttachment` carries the `eventId` of its message. Callers must
301
+ revoke returned URLs. The React views revoke theirs on replacement and unmount,
302
+ including downloads that finish after unmount. Uploads use Matrix's separate
303
+ authenticated `/_matrix/media/v3/upload` endpoint. Only references on the
304
+ session's own homeserver are accepted.
305
+
306
+ **Files are locked to their channels** ([#32](https://github.com/wtfalch/chat/issues/32)).
307
+ Synapse serves a file to any valid token that names its media id, whatever room
308
+ it was posted in. The media route in `apps/chat-service` (`src/media.ts`) makes
309
+ the check Synapse does not. It serves the file only when the caller is currently
310
+ joined to `roomId`, `eventId` is a message in that room that references the
311
+ file, and that message was sent by the person who uploaded it. An ex-member, or
312
+ someone who re-posts a kept media id in a room of their own, is refused. A
313
+ deleted message's file is refused too. The deleted file itself stays stored.
314
+ This only holds when the reverse proxy in front of Synapse does not route
315
+ Synapse's own media download and thumbnail paths to clients. No malware
316
+ scanning or file search is included.
317
+
318
+ **Every file in a room** ([#9](https://github.com/wtfalch/chat/issues/9)).
319
+ `chat.roomFiles(roomId, { limit, before })` lists a room's files without paging
320
+ its timeline: `GET .../messages` takes Matrix's own `contains_url` filter, and
321
+ Synapse answers with only file-bearing events no matter how much plain
322
+ conversation sits between them, confirmed live against this package's own test
323
+ Synapse. It resolves with `{ files, next }`. `files` are `ChatAttachment`s, the
324
+ same shape `event.attachment` already carries, and bytes still only ever come
325
+ through `loadMedia`. `limit` stops once that many are collected; omitted, this
326
+ walks pages until Synapse says there is nothing older.
327
+
328
+ **Loading more files** ([#33](https://github.com/wtfalch/chat/issues/33)).
329
+ `next` is the cursor for the files after these. Pass it back as `before` to load
330
+ the next page; it is `null` once there is nothing older. It resumes exactly
331
+ after the last file returned, so none is skipped or repeated. The last page can
332
+ come back empty.
243
333
 
244
334
  ## First-ship local proof
245
335
 
@@ -260,6 +350,12 @@ The React timeline calls `markRoomRead` when the visible room is at the bottom.
260
350
  Reading a thread, viewing older history, or leaving a tab in the background does
261
351
  not clear unread room messages.
262
352
 
353
+ `readBy(roomId, eventId)` names who has seen a message
354
+ ([#31](https://github.com/wtfalch/chat/issues/31)): every joined person whose
355
+ read receipt is on that message or a newer one. It leaves out the signed-in
356
+ person and the message's sender. `onTimelineChanged` fires when a receipt
357
+ moves, so a view re-reads it then. Only public read receipts count.
358
+
263
359
  ## Administration in Manage
264
360
 
265
361
  `@wtfalch/chat/admin` exports `createChatAdmin`, the typed management
@@ -274,7 +370,10 @@ const page = await admin.listChannels({ limit: 25 });
274
370
  ```
275
371
 
276
372
  It exposes channel list/details/create/update/archive/delete, private-channel
277
- invitations/removals, Chat-user deactivation and audit pagination. Redirects are
373
+ invitations/removals, moderation (`banPerson`, `unbanPerson`, `redactMessage`,
374
+ `listReports`), Chat-user deactivation, a person's Matrix sessions
375
+ (`listSessions(subject)` and `revokeSession(subject, sessionId)`,
376
+ [#30](https://github.com/wtfalch/chat/issues/30)) and audit pagination. Redirects are
278
377
  refused; tokens never appear in URLs or rendered errors. Service authorization
279
378
  still verifies the token, organisation and Chat project's admin role on every
280
379
  request. Request the Chat project audience and qualified project-role claims
@@ -42,6 +42,23 @@ export type AuditPage = {
42
42
  rows: AuditRow[];
43
43
  next_cursor: string | null;
44
44
  };
45
+ /** One Matrix session the exchange minted for a person -- one per device. */
46
+ export type PersonSession = {
47
+ session_id: string;
48
+ device_id: string | null;
49
+ created_at: string | null;
50
+ last_active_at: string | null;
51
+ };
52
+ /** A member's report of a message (#29). Never the message text. */
53
+ export type ContentReport = {
54
+ id: string;
55
+ received_at: string | null;
56
+ room_id: string | null;
57
+ event_id: string | null;
58
+ reporter: string | null;
59
+ sender: string | null;
60
+ reason: string | null;
61
+ };
45
62
  export type PageInput = {
46
63
  limit?: number;
47
64
  cursor?: string;
@@ -80,10 +97,46 @@ export declare function createChatAdmin(options: ChatAdminOptions): {
80
97
  room_id: string;
81
98
  deleted: true;
82
99
  }>;
100
+ /** Bans a person from one channel until `unbanPerson` (#29). */
101
+ banPerson: (roomId: string, subject: string, reason?: string) => Promise<{
102
+ room_id: string;
103
+ user_id: string;
104
+ banned: true;
105
+ }>;
106
+ unbanPerson: (roomId: string, subject: string) => Promise<{
107
+ room_id: string;
108
+ user_id: string;
109
+ banned: false;
110
+ }>;
111
+ /** Removes anyone's message from a channel (#29). */
112
+ redactMessage: (roomId: string, eventId: string) => Promise<{
113
+ room_id: string;
114
+ event_id: string;
115
+ redacted: true;
116
+ }>;
117
+ /** What members reported with `reportMessage`, newest first. */
118
+ listReports: (input?: PageInput) => Promise<{
119
+ reports: ContentReport[];
120
+ next_cursor: string | null;
121
+ }>;
83
122
  deactivatePerson: (subject: string) => Promise<{
84
123
  user_id: string;
85
124
  deactivated: true;
86
125
  }>;
126
+ /** Every Matrix session signed in as `subject` (#30). */
127
+ listSessions: (subject: string) => Promise<{
128
+ user_id: string;
129
+ sessions: PersonSession[];
130
+ }>;
131
+ /** Ends one of `subject`'s sessions; its Matrix token stops working at
132
+ * once. The person's next exchange on that device signs in again, so
133
+ * a stolen ZITADEL credential needs `deactivatePerson` or revoking in
134
+ * ZITADEL. */
135
+ revokeSession: (subject: string, sessionId: string) => Promise<{
136
+ user_id: string;
137
+ session_id: string;
138
+ revoked: true;
139
+ }>;
87
140
  audit: (input?: PageInput) => Promise<AuditPage>;
88
141
  };
89
142
  export type ChatAdmin = ReturnType<typeof createChatAdmin>;
@@ -106,7 +106,40 @@ export function createChatAdmin(options) {
106
106
  removePerson: (roomId, subject) => request('DELETE', `${roomPath(roomId)}/people/${identifier(subject)}`, personResult),
107
107
  archiveChannel: (roomId) => request('POST', `${roomPath(roomId)}/archive`, (data) => roomResult(data) && 'archived' in data && data.archived === true),
108
108
  deleteChannel: (roomId) => request('DELETE', roomPath(roomId), (data) => roomResult(data) && 'deleted' in data && data.deleted === true),
109
+ /** Bans a person from one channel until `unbanPerson` (#29). */
110
+ banPerson: (roomId, subject, reason) => request('POST', `${roomPath(roomId)}/bans`, (data) => personResult(data) && 'banned' in data && data.banned === true, reason === undefined ? { subject } : { subject, reason }),
111
+ unbanPerson: (roomId, subject) => request('DELETE', `${roomPath(roomId)}/bans/${identifier(subject)}`, (data) => personResult(data) && 'banned' in data && data.banned === false),
112
+ /** Removes anyone's message from a channel (#29). */
113
+ redactMessage: (roomId, eventId) => request('DELETE', `${roomPath(roomId)}/messages/${identifier(eventId)}`, (data) => roomResult(data) &&
114
+ 'event_id' in data &&
115
+ typeof data.event_id === 'string' &&
116
+ 'redacted' in data &&
117
+ data.redacted === true),
118
+ /** What members reported with `reportMessage`, newest first. */
119
+ listReports: (input) => request('GET', `/reports${pageQuery(100, input)}`, (data) => record(data) &&
120
+ Array.isArray(data.reports) &&
121
+ data.reports.every((report) => record(report) &&
122
+ typeof report.id === 'string' &&
123
+ ['received_at', 'room_id', 'event_id', 'reporter', 'sender', 'reason'].every((key) => nullableString(report[key]))) &&
124
+ nullableString(data.next_cursor)),
109
125
  deactivatePerson: (subject) => request('DELETE', `/people/${identifier(subject)}`, (data) => record(data) && typeof data.user_id === 'string' && data.deactivated === true),
126
+ /** Every Matrix session signed in as `subject` (#30). */
127
+ listSessions: (subject) => request('GET', `/people/${identifier(subject)}/sessions`, (data) => record(data) &&
128
+ typeof data.user_id === 'string' &&
129
+ Array.isArray(data.sessions) &&
130
+ data.sessions.every((entry) => record(entry) &&
131
+ typeof entry.session_id === 'string' &&
132
+ nullableString(entry.device_id) &&
133
+ nullableString(entry.created_at) &&
134
+ nullableString(entry.last_active_at))),
135
+ /** Ends one of `subject`'s sessions; its Matrix token stops working at
136
+ * once. The person's next exchange on that device signs in again, so
137
+ * a stolen ZITADEL credential needs `deactivatePerson` or revoking in
138
+ * ZITADEL. */
139
+ revokeSession: (subject, sessionId) => request('DELETE', `/people/${identifier(subject)}/sessions/${identifier(sessionId)}`, (data) => record(data) &&
140
+ typeof data.user_id === 'string' &&
141
+ typeof data.session_id === 'string' &&
142
+ data.revoked === true),
110
143
  audit: (input) => request('GET', `/audit${pageQuery(200, input)}`, (data) => record(data) &&
111
144
  Array.isArray(data.rows) &&
112
145
  data.rows.every(auditRow) &&