@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.
@@ -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
  };
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "@wtfalch/chat",
3
- "version": "0.1.0",
3
+ "version": "0.2.0",
4
4
  "description": "A Matrix chat client behind the agora's token exchange.",
5
5
  "license": "MIT",
6
6
  "type": "module",