@wtfalch/chat 0.1.0 → 0.2.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 +71 -0
- package/dist/chat/client.js +509 -20
- package/dist/chat/fake/server.d.ts +61 -0
- package/dist/chat/fake/server.js +249 -15
- package/dist/chat/types.d.ts +228 -1
- package/package.json +1 -1
package/dist/chat/types.d.ts
CHANGED
|
@@ -25,8 +25,22 @@ export type ChatRoomSummary = {
|
|
|
25
25
|
/** Matrix's own total notification count for this room (`unread_
|
|
26
26
|
* notifications.notification_count` from `/sync`), zeroed the moment
|
|
27
27
|
* `markRoomRead` sends a receipt for the newest event. An unanswered
|
|
28
|
-
* invitation contributes one until answered or withdrawn.
|
|
28
|
+
* invitation contributes one until answered or withdrawn.
|
|
29
|
+
*
|
|
30
|
+
* A muted room is the one exception, and by necessity: confirmed live,
|
|
31
|
+
* Synapse's own notification count is itself gated by the room-scoped
|
|
32
|
+
* `dont_notify` rule `muteRoom` writes, so reading it there would
|
|
33
|
+
* report zero forever. A muted room counts itself instead -- every
|
|
34
|
+
* message after the local read-up-to marker, sent by somebody else --
|
|
35
|
+
* which is what keeps this field climbing while `muted` stops the
|
|
36
|
+
* bell. */
|
|
29
37
|
readonly unreadCount: number;
|
|
38
|
+
/** Whether `muteRoom` has muted this room: a room-scoped push rule with
|
|
39
|
+
* the `dont_notify` action, which is what a list dims. Independent of
|
|
40
|
+
* `unreadCount` -- muting stops a room from notifying, never from
|
|
41
|
+
* counting, so a muted room keeps climbing exactly as an unmuted one
|
|
42
|
+
* would. */
|
|
43
|
+
readonly muted: boolean;
|
|
30
44
|
};
|
|
31
45
|
/** Someone this person can start a direct message with: a member of the
|
|
32
46
|
* company space. Guests are never in the space (chat plan section 5), so
|
|
@@ -162,6 +176,16 @@ export type ChatTimelinePage = {
|
|
|
162
176
|
* network drop, or recovering from a refused sync position with a fresh
|
|
163
177
|
* full sync), or not connected at all. */
|
|
164
178
|
export type ChatConnectionStatus = 'connected' | 'catching-up' | 'offline';
|
|
179
|
+
/** Someone's `m.presence`, reduced to the four states `@wtfalch/design`'s
|
|
180
|
+
* `Presence` dot draws. Matrix itself only ever reports three --
|
|
181
|
+
* `'online'`, `'unavailable'` (this package's `'away'`) and `'offline'` --
|
|
182
|
+
* plus MSC3026's unstable `'busy'` (`org.matrix.msc3026.busy` on the
|
|
183
|
+
* wire), which some clients send and Synapse merely relays without
|
|
184
|
+
* understanding. Anything else this package has never seen, including no
|
|
185
|
+
* presence at all, reads as `'offline'` -- the same state a person who is
|
|
186
|
+
* genuinely offline has, which is the honest answer when the only
|
|
187
|
+
* difference is that nobody has said otherwise (see `ChatClient.presence`). */
|
|
188
|
+
export type Presence = 'online' | 'busy' | 'away' | 'offline';
|
|
165
189
|
export type CreateChatClientOptions = {
|
|
166
190
|
/** `POST` here exchanges the agora's current ZITADEL token for a Matrix
|
|
167
191
|
* one. See `apps/chat-service/README.md`. */
|
|
@@ -218,6 +242,57 @@ export type ChatClient = {
|
|
|
218
242
|
* reads `hasMore` off that, not off this promise. A no-op, resolved
|
|
219
243
|
* promise for a room not joined. */
|
|
220
244
|
paginate: (roomId: string, threadId?: string | null) => Promise<void>;
|
|
245
|
+
/** Every file shared in `roomId`, most recently sent first, without the
|
|
246
|
+
* caller ever paging the room's timeline to find them -- see
|
|
247
|
+
* `ChatAttachment` for what counts as a file. `options.limit` stops
|
|
248
|
+
* once that many have been collected; omitted, this keeps going until
|
|
249
|
+
* Synapse says there is nothing older. `options.before` continues a
|
|
250
|
+
* walk this method already started: Synapse's own opaque `/messages`
|
|
251
|
+
* pagination token (its `end` field) -- not a `ChatTimelineEvent.id`.
|
|
252
|
+
* This method does not hand one back yet, so nothing here can produce a
|
|
253
|
+
* value for a caller to pass in; see the ticket's own report for why
|
|
254
|
+
* that is left for whoever needs it next rather than reshaping the
|
|
255
|
+
* return type now.
|
|
256
|
+
*
|
|
257
|
+
* Filtered server-side, not paged client-side: `GET .../messages`
|
|
258
|
+
* takes Matrix's own `contains_url` filter, and Synapse answers it with
|
|
259
|
+
* only file-bearing events, no matter how much plain conversation sits
|
|
260
|
+
* between them -- confirmed live against this package's own test
|
|
261
|
+
* Synapse (v1.161.0): a single filtered request found a file sent
|
|
262
|
+
* before 50 plain messages that a caller's already-synced timeline and
|
|
263
|
+
* one `paginate()` page (38 events between them) could not have
|
|
264
|
+
* reached. matrix-js-sdk's `TimelineWindow` and `relations` both
|
|
265
|
+
* assume a timeline or an event already in hand; neither expresses
|
|
266
|
+
* "every event of this shape, anywhere in history", so this goes
|
|
267
|
+
* through matrix-js-sdk's own `createMessagesRequest` (oddly marked
|
|
268
|
+
* private, but exported and used exactly this way elsewhere in the
|
|
269
|
+
* SDK) rather than a hand-rolled HTTP call.
|
|
270
|
+
*
|
|
271
|
+
* **Spans the room's threads too, unlike `timeline()`.** `timeline()`
|
|
272
|
+
* deliberately excludes a thread's replies -- they "live in the thread
|
|
273
|
+
* and nowhere else, which is what keeps the room readable" (see above).
|
|
274
|
+
* This does not: `/messages` carries no thread-vs-room distinction at
|
|
275
|
+
* all, so a file shared inside a thread comes back exactly like one
|
|
276
|
+
* shared in the room -- confirmed live against Synapse. Deliberately
|
|
277
|
+
* kept, not just left over: a Files panel asking "every file shared
|
|
278
|
+
* here" means the threads too, and a caller who wants only the room's
|
|
279
|
+
* own files can still get them by asking each thread's `timeline()`
|
|
280
|
+
* what it excludes.
|
|
281
|
+
*
|
|
282
|
+
* **An encrypted room's files never appear.** `m.room.encrypted` has no
|
|
283
|
+
* top-level `url` for `contains_url` to match, so this returns `[]` for
|
|
284
|
+
* a room full of files exactly as it would for one with none -- an
|
|
285
|
+
* empty list from such a room means "cannot see", not "none". Not a bug
|
|
286
|
+
* to fix here: this package never calls `initRustCrypto()` (see the
|
|
287
|
+
* module comment), so an encrypted room's whole timeline is already
|
|
288
|
+
* unusable, not just this method.
|
|
289
|
+
*
|
|
290
|
+
* Empty before `start()` resolves, or for a room this client does not
|
|
291
|
+
* know. */
|
|
292
|
+
roomFiles: (roomId: string, options?: {
|
|
293
|
+
limit?: number;
|
|
294
|
+
before?: string;
|
|
295
|
+
}) => Promise<readonly ChatAttachment[]>;
|
|
221
296
|
/** Everyone joined to `roomId`, by name, the signed-in person included --
|
|
222
297
|
* who a message in this room can mention. A room's own membership, not
|
|
223
298
|
* the company's: mentioning somebody who is not here would notify
|
|
@@ -307,6 +382,20 @@ export type ChatClient = {
|
|
|
307
382
|
* person scrolls to the newest message. A no-op if the room is unknown
|
|
308
383
|
* or has no events yet. */
|
|
309
384
|
markRoomRead: (roomId: string) => Promise<void>;
|
|
385
|
+
/** Stops `roomId` from notifying, without stopping it from counting
|
|
386
|
+
* unread: `muted` and `unreadCount` are two different fields on
|
|
387
|
+
* `ChatRoomSummary`, and this only ever changes one of them -- a person
|
|
388
|
+
* who mutes a noisy room still watches it climb, and still knows to
|
|
389
|
+
* look.
|
|
390
|
+
*
|
|
391
|
+
* Writes (or, unmuting, deletes) a room-scoped push rule carrying the
|
|
392
|
+
* `dont_notify` action, through matrix-js-sdk's own
|
|
393
|
+
* `setRoomMutePushRule` -- scoped `'global'`, an account-wide ruleset
|
|
394
|
+
* rather than a device-specific one, so muting here mutes every device
|
|
395
|
+
* signed into this person's account, not just this session.
|
|
396
|
+
*
|
|
397
|
+
* A no-op for a room this client does not know. */
|
|
398
|
+
muteRoom: (roomId: string, muted: boolean) => Promise<void>;
|
|
310
399
|
/** Everyone in the company space except the signed-in person, by name.
|
|
311
400
|
* Empty before `start()` resolves, and empty for a session whose
|
|
312
401
|
* account is in no space. */
|
|
@@ -337,4 +426,142 @@ export type ChatClient = {
|
|
|
337
426
|
/** Called with the current status whenever it changes. Returns a
|
|
338
427
|
* function that stops listening. */
|
|
339
428
|
onConnectionStatusChanged: (listener: (status: ChatConnectionStatus) => void) => () => void;
|
|
429
|
+
/** Adds `eventId` to `roomId`'s pinned messages -- Matrix's own
|
|
430
|
+
* `m.room.pinned_events` state, one list the whole room shares rather
|
|
431
|
+
* than a per-person bookmark. A no-op, already resolved, if it is
|
|
432
|
+
* already pinned.
|
|
433
|
+
*
|
|
434
|
+
* Ordinary members can call this (ticket #8, settled on
|
|
435
|
+
* wtfalch/agora#255): `apps/chat-service`'s `powerLevels()` grants
|
|
436
|
+
* `m.room.pinned_events` its own power level, 0, overriding the chat
|
|
437
|
+
* plan's "nobody but `@chat-admin` ... pins" on this one point. That
|
|
438
|
+
* reaches only a room created after the change landed -- an existing
|
|
439
|
+
* room's power levels are never backfilled -- so this **rejects**
|
|
440
|
+
* rather than resolving quietly when Synapse refuses it. A caller in an
|
|
441
|
+
* older channel sees the promise reject, not a pin that silently did
|
|
442
|
+
* nothing.
|
|
443
|
+
*
|
|
444
|
+
* **Safe to call twice in a row from one client** --
|
|
445
|
+
* `await pinMessage(a); await pinMessage(b);`, or neither awaited
|
|
446
|
+
* first -- and have both survive: each call is queued behind this
|
|
447
|
+
* client's own last write for the room rather than built on a read of
|
|
448
|
+
* `roomId`'s local state, which a resolved `sendStateEvent` does not
|
|
449
|
+
* prove has caught up yet (confirmed live: it had not, even after a
|
|
450
|
+
* full `await`).
|
|
451
|
+
*
|
|
452
|
+
* **Not safe across two `ChatClient`s** -- two accounts, or two
|
|
453
|
+
* devices of one account -- pinning in the same room at once. Nothing
|
|
454
|
+
* sequences *between* clients, and Matrix gives `m.room.pinned_events`
|
|
455
|
+
* no compare-and-swap: it is one state value, replaced whole, so a
|
|
456
|
+
* genuine race is decided by Synapse's own state resolution, never
|
|
457
|
+
* merged, and can still silently drop one side's pin. This is a limit
|
|
458
|
+
* the protocol imposes, not a gap this method leaves open by
|
|
459
|
+
* accident. */
|
|
460
|
+
pinMessage: (roomId: string, eventId: string) => Promise<void>;
|
|
461
|
+
/** Takes `eventId` back out of `roomId`'s pinned messages. A no-op,
|
|
462
|
+
* already resolved, if it is not pinned. Needs the same power level as
|
|
463
|
+
* `pinMessage`, rejects the same way in a room whose power levels
|
|
464
|
+
* predate ticket #8, and carries the same two guarantees: safe to
|
|
465
|
+
* chain with `pinMessage`/`unpinMessage` calls from this client, not
|
|
466
|
+
* safe against another client writing to the same room's pinned list
|
|
467
|
+
* at once. */
|
|
468
|
+
unpinMessage: (roomId: string, eventId: string) => Promise<void>;
|
|
469
|
+
/** `roomId`'s currently pinned messages, in the order `m.room.pinned_
|
|
470
|
+
* events` lists them, each reduced the same way `timeline()` reduces a
|
|
471
|
+
* message. A pinned id this client cannot find an event for -- paginated
|
|
472
|
+
* away, or never loaded -- is left out rather than drawn as a gap.
|
|
473
|
+
* Empty for a room with nothing pinned, or one this client does not
|
|
474
|
+
* know. */
|
|
475
|
+
pinnedMessages: (roomId: string) => readonly ChatTimelineEvent[];
|
|
476
|
+
/** Somebody's presence, read off matrix-js-sdk's own `User` object --
|
|
477
|
+
* never fetched, and never kept up to date by this call itself, only by
|
|
478
|
+
* whatever `m.presence` Matrix has already delivered through sync. A
|
|
479
|
+
* user this session has not seen a presence event for, the signed-in
|
|
480
|
+
* person's own id included, reads as `'offline'`.
|
|
481
|
+
*
|
|
482
|
+
* **Every company's Synapse ships with presence off** (ticket #7's own
|
|
483
|
+
* finding, tracked at `wtfalch/app-template#352`, `bootstrap/steps/
|
|
484
|
+
* chat-instance.ts:142`): until that lands, Synapse never emits an
|
|
485
|
+
* `m.presence` event at all, so this method is honest and returns
|
|
486
|
+
* `'offline'` for everyone, always, in production -- not because nobody
|
|
487
|
+
* is online, but because the server never says. Typing is unaffected.
|
|
488
|
+
*
|
|
489
|
+
* **`'away'` only happens if somebody announces it.** Left alone, a
|
|
490
|
+
* syncing client re-asserts `'online'` on every poll, so a person with
|
|
491
|
+
* a tab open all night reads as available forever. `announcePresence`
|
|
492
|
+
* is what breaks that, and nothing else in this package does -- see its
|
|
493
|
+
* own comment for why. `'busy'` still comes only from some *other*
|
|
494
|
+
* Matrix client (MSC3026, unstable, and off unless a homeserver opts in
|
|
495
|
+
* with `msc3026_enabled`). */
|
|
496
|
+
presence: (userId: string) => Presence;
|
|
497
|
+
/** Says whether the signed-in person is at their machine. This is the
|
|
498
|
+
* only way `'away'` is ever reachable, and a caller that never calls it
|
|
499
|
+
* leaves everyone reading `'online'` for as long as a tab stays open.
|
|
500
|
+
*
|
|
501
|
+
* **The SDK cannot decide this for itself.** A library sees method
|
|
502
|
+
* calls, and a cron job calling `timeline()` looks exactly like a person
|
|
503
|
+
* reading. Only the app knows about the Page Visibility API, a locked
|
|
504
|
+
* screen, and real keystrokes, so the app is what calls this --
|
|
505
|
+
* `'away'` when it stops seeing activity, `'online'` on the next real
|
|
506
|
+
* input. That half is Agora's, and is not built yet.
|
|
507
|
+
*
|
|
508
|
+
* **Why it takes two requests.** Confirmed live against Synapse
|
|
509
|
+
* v1.161.0: every `/sync` carries an implicit `set_presence`, so a plain
|
|
510
|
+
* `PUT .../presence/status` is undone by this session's own next poll
|
|
511
|
+
* seconds later (`handlers/presence.py`'s `user_syncing` ->
|
|
512
|
+
* `set_state(is_sync=True)`, which exempts only `'busy'`). Announcing
|
|
513
|
+
* changes the sync parameter itself, which is what makes it stick, and
|
|
514
|
+
* also sends the `PUT` so the change lands now rather than whenever the
|
|
515
|
+
* current long poll happens to return.
|
|
516
|
+
*
|
|
517
|
+
* **Remembered, not just sent.** An announcement survives this client's
|
|
518
|
+
* own restarts -- a dead token, a refused sync position, a `stop()` and
|
|
519
|
+
* `start()` -- because each of those builds a fresh sync loop that would
|
|
520
|
+
* otherwise default the person back to `'online'`. Announcing before
|
|
521
|
+
* `start()` sends nothing, and applies to the session that follows.
|
|
522
|
+
*
|
|
523
|
+
* **Never rejects, and never needs retrying.** Synapse allows one
|
|
524
|
+
* presence change per ten seconds and refuses the rest, so flipping
|
|
525
|
+
* idle and back quickly means the `PUT` is turned away -- but the
|
|
526
|
+
* announcement still stands, because what carries it is the sync, and
|
|
527
|
+
* the state catches up within a poll. Call it as often as real activity
|
|
528
|
+
* suggests; it is a statement of the current truth, not a queued
|
|
529
|
+
* command. */
|
|
530
|
+
announcePresence: (presence: 'online' | 'away') => Promise<void>;
|
|
531
|
+
/** Called whenever somebody's presence changes, with just the people who
|
|
532
|
+
* changed -- one entry, almost always, since Matrix delivers `m.presence`
|
|
533
|
+
* one person at a time. Returns a function that stops listening.
|
|
534
|
+
*
|
|
535
|
+
* Nothing is replayed on subscribing: a caller that wants a room's
|
|
536
|
+
* current presence has to read `presence(userId)` for each member first
|
|
537
|
+
* and use this only to hear about what changes after. */
|
|
538
|
+
onPresenceChanged: (listener: (changed: ReadonlyMap<string, Presence>) => void) => () => void;
|
|
539
|
+
/** Tells `roomId` the signed-in person has started, or stopped, typing --
|
|
540
|
+
* `m.typing`, which is not an event: nothing lands in `timeline()`, and
|
|
541
|
+
* nothing is retried if this fails, the same as any other presence-like
|
|
542
|
+
* signal nobody is meant to notice going missing once.
|
|
543
|
+
*
|
|
544
|
+
* **Not a heartbeat.** Matrix expires a typing state on its own after a
|
|
545
|
+
* server-side timeout (this sends the SDK's own default, 20 seconds) --
|
|
546
|
+
* so a composer that wants the other side to keep seeing "typing" while
|
|
547
|
+
* a person keeps composing has to call this again itself, on further
|
|
548
|
+
* keystrokes, rather than once at the start. Sending `false` (a blurred
|
|
549
|
+
* composer, a sent message) clears it at once rather than waiting that
|
|
550
|
+
* out. */
|
|
551
|
+
sendTyping: (roomId: string, typing: boolean) => void;
|
|
552
|
+
/** Called with everyone currently typing in `roomId`, other than the
|
|
553
|
+
* signed-in person -- Matrix's own `m.typing` lists every typing member
|
|
554
|
+
* including this session, and a person is never told they are typing.
|
|
555
|
+
* Returns a function that stops listening. A no-op subscription, never
|
|
556
|
+
* called, for a room this client does not know: `m.typing` is scoped to
|
|
557
|
+
* a room this client has joined, so one it has not is simply silent,
|
|
558
|
+
* the same as `onTimelineChanged` on an unknown room.
|
|
559
|
+
*
|
|
560
|
+
* **Matrix never says "stopped" for a room you left.** `m.typing` is
|
|
561
|
+
* ephemeral, resent by the server as the complete current list on every
|
|
562
|
+
* change -- but a room you have left sends nothing further at all, so a
|
|
563
|
+
* list this call last reported for it can go stale forever rather than
|
|
564
|
+
* clearing to empty. A caller that cares should stop listening itself
|
|
565
|
+
* once the room is gone from `rooms()`. */
|
|
566
|
+
onTypingChanged: (roomId: string, listener: (userIds: readonly string[]) => void) => () => void;
|
|
340
567
|
};
|