@wtfalch/chat 0.5.1 → 0.6.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.
@@ -1,16 +1,54 @@
1
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,
2
+ /** The `dbName` this package hands `IndexedDBStore` for a workspace,
3
+ * authenticated homeserver and user. Its own function so a test can assert on it directly,
4
4
  * without starting a client. matrix-js-sdk prefixes this again with
5
5
  * `matrix-js-sdk:` for the real IndexedDB database name
6
6
  * (`indexeddb-local-backend.ts`) -- an internal of its own, not this
7
7
  * package's to name. */
8
- export declare function storeDbName(storeName: string): string;
8
+ export declare function storeDbName(storeName: string, homeserver: string, userId: string): string;
9
+ /** The `cryptoDatabasePrefix` this package hands `initRustCrypto()`, bound
10
+ * to the exchanged identity the same tuple `storeDbName` is -- its own
11
+ * function for the same reason: a test can assert on it without starting
12
+ * a client. Without this, matrix-js-sdk's own default
13
+ * (`RUST_SDK_STORE_PREFIX`, a fixed constant) names the same IndexedDB
14
+ * database for every client in the browser, defeating the one thing
15
+ * `storeName` exists for -- two companies, or two accounts under one
16
+ * `storeName`, open at once would either fail to start (the Rust store
17
+ * refusing a user/device id it does not recognise) or, for the very first
18
+ * account on a fresh store, succeed and then reject the next account that
19
+ * tries (chat#71 review). Binding to `userId` as well as `storeName`, not
20
+ * just the latter, is what turns a stale account's crypto store into an
21
+ * unrelated empty one rather than a rejected mismatch. matrix-js-sdk
22
+ * suffixes this again with `::matrix-sdk-crypto` and
23
+ * `::matrix-sdk-crypto-meta` for the real database names -- internals of
24
+ * its own, not this package's to name, same as `storeDbName`'s `matrix-
25
+ * js-sdk:` prefix.
26
+ *
27
+ * The user and device ids are part of the name because the Rust store
28
+ * binds to one account: the same `storeName` with a new device (a fresh
29
+ * sign-in) would make `initRustCrypto` fail with "the account in the store
30
+ * doesn't match the account in the constructor". Not `homeserver`, unlike
31
+ * `storeDbName`: `OlmMachine.initFromStore` validates `userId`/`deviceId`
32
+ * alone, never a homeserver, and a Matrix user id already carries its
33
+ * homeserver as the part after the colon. Stale crypto stores left behind
34
+ * by a device or account change are not purged the way
35
+ * `purgeStaleChatStores` purges the sync store -- a known gap, not a
36
+ * correctness bug: a mismatch now opens a fresh, empty crypto store rather
37
+ * than being rejected. */
38
+ export declare function cryptoStoreDbPrefix(storeName: string, userId: string, deviceId: string): string;
9
39
  /**
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.
40
+ * A local store bound to the exchanged identity as well as `storeName`, so
41
+ * companies, homeservers and accounts in the same browser never share one.
12
42
  *
13
43
  * `indexedDB` is read at call time rather than imported, so this works both
14
44
  * in a real browser and under vitest with `fake-indexeddb/auto` installed.
15
45
  */
16
- export declare function createChatStore(storeName: string): IndexedDBStore;
46
+ export declare function createChatStore(storeName: string, homeserver: string, userId: string): IndexedDBStore;
47
+ /**
48
+ * Deletes this workspace's databases that do not belong to the exchanged
49
+ * identity: the legacy unbound one (`wtfalch-messaging-<storeName>`, which
50
+ * holds the previous account's joined history) and the `v2` ones for other
51
+ * homeservers or users. Other workspaces' databases are left alone.
52
+ * Best effort: a failure here must not stop the client from starting.
53
+ */
54
+ export declare function purgeStaleChatStores(storeName: string, homeserver: string, userId: string): Promise<void>;
@@ -1,25 +1,105 @@
1
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,
2
+ /** The `dbName` this package hands `IndexedDBStore` for a workspace,
3
+ * authenticated homeserver and user. Its own function so a test can assert on it directly,
4
4
  * without starting a client. matrix-js-sdk prefixes this again with
5
5
  * `matrix-js-sdk:` for the real IndexedDB database name
6
6
  * (`indexeddb-local-backend.ts`) -- an internal of its own, not this
7
7
  * package's to name. */
8
- export function storeDbName(storeName) {
9
- return `wtfalch-messaging-${storeName}`;
8
+ export function storeDbName(storeName, homeserver, userId) {
9
+ // A tuple prevents delimiter collisions. The versioned prefix leaves legacy, unbound
10
+ // caches behind: their contents cannot be attributed safely to the current account.
11
+ return `wtfalch-messaging-v2-${JSON.stringify([storeName, homeserver, userId])}`;
12
+ }
13
+ /** The `cryptoDatabasePrefix` this package hands `initRustCrypto()`, bound
14
+ * to the exchanged identity the same tuple `storeDbName` is -- its own
15
+ * function for the same reason: a test can assert on it without starting
16
+ * a client. Without this, matrix-js-sdk's own default
17
+ * (`RUST_SDK_STORE_PREFIX`, a fixed constant) names the same IndexedDB
18
+ * database for every client in the browser, defeating the one thing
19
+ * `storeName` exists for -- two companies, or two accounts under one
20
+ * `storeName`, open at once would either fail to start (the Rust store
21
+ * refusing a user/device id it does not recognise) or, for the very first
22
+ * account on a fresh store, succeed and then reject the next account that
23
+ * tries (chat#71 review). Binding to `userId` as well as `storeName`, not
24
+ * just the latter, is what turns a stale account's crypto store into an
25
+ * unrelated empty one rather than a rejected mismatch. matrix-js-sdk
26
+ * suffixes this again with `::matrix-sdk-crypto` and
27
+ * `::matrix-sdk-crypto-meta` for the real database names -- internals of
28
+ * its own, not this package's to name, same as `storeDbName`'s `matrix-
29
+ * js-sdk:` prefix.
30
+ *
31
+ * The user and device ids are part of the name because the Rust store
32
+ * binds to one account: the same `storeName` with a new device (a fresh
33
+ * sign-in) would make `initRustCrypto` fail with "the account in the store
34
+ * doesn't match the account in the constructor". Not `homeserver`, unlike
35
+ * `storeDbName`: `OlmMachine.initFromStore` validates `userId`/`deviceId`
36
+ * alone, never a homeserver, and a Matrix user id already carries its
37
+ * homeserver as the part after the colon. Stale crypto stores left behind
38
+ * by a device or account change are not purged the way
39
+ * `purgeStaleChatStores` purges the sync store -- a known gap, not a
40
+ * correctness bug: a mismatch now opens a fresh, empty crypto store rather
41
+ * than being rejected. */
42
+ export function cryptoStoreDbPrefix(storeName, userId, deviceId) {
43
+ return `wtfalch-messaging-crypto-${storeName}-${userId}-${deviceId}`;
10
44
  }
11
45
  /**
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.
46
+ * A local store bound to the exchanged identity as well as `storeName`, so
47
+ * companies, homeservers and accounts in the same browser never share one.
14
48
  *
15
49
  * `indexedDB` is read at call time rather than imported, so this works both
16
50
  * in a real browser and under vitest with `fake-indexeddb/auto` installed.
17
51
  */
18
- export function createChatStore(storeName) {
19
- const dbName = storeDbName(storeName);
52
+ export function createChatStore(storeName, homeserver, userId) {
53
+ const dbName = storeDbName(storeName, homeserver, userId);
20
54
  return new IndexedDBStore({
21
55
  indexedDB: globalThis.indexedDB,
22
56
  dbName,
23
57
  localStorage: globalThis.localStorage,
24
58
  });
25
59
  }
60
+ const SDK_PREFIX = 'matrix-js-sdk:';
61
+ const LEGACY_PREFIX = 'wtfalch-messaging-';
62
+ const V2_PREFIX = 'wtfalch-messaging-v2-';
63
+ function deleteDatabase(indexedDB, name) {
64
+ return new Promise((resolve) => {
65
+ const request = indexedDB.deleteDatabase(name);
66
+ // A blocked delete (another tab holds it open) completes once that tab
67
+ // closes; waiting on it would stall start-up, so it is not awaited.
68
+ request.onsuccess = () => resolve();
69
+ request.onerror = () => resolve();
70
+ request.onblocked = () => resolve();
71
+ });
72
+ }
73
+ /**
74
+ * Deletes this workspace's databases that do not belong to the exchanged
75
+ * identity: the legacy unbound one (`wtfalch-messaging-<storeName>`, which
76
+ * holds the previous account's joined history) and the `v2` ones for other
77
+ * homeservers or users. Other workspaces' databases are left alone.
78
+ * Best effort: a failure here must not stop the client from starting.
79
+ */
80
+ export async function purgeStaleChatStores(storeName, homeserver, userId) {
81
+ const indexedDB = globalThis.indexedDB;
82
+ if (!indexedDB)
83
+ return;
84
+ const keep = SDK_PREFIX + storeDbName(storeName, homeserver, userId);
85
+ const legacy = SDK_PREFIX + LEGACY_PREFIX + storeName;
86
+ const stale = new Set([legacy]);
87
+ try {
88
+ for (const { name } of (await indexedDB.databases?.()) ?? []) {
89
+ if (!name || name === keep || !name.startsWith(SDK_PREFIX + V2_PREFIX))
90
+ continue;
91
+ try {
92
+ const tuple = JSON.parse(name.slice(SDK_PREFIX.length + V2_PREFIX.length));
93
+ if (Array.isArray(tuple) && tuple[0] === storeName)
94
+ stale.add(name);
95
+ }
96
+ catch {
97
+ // Not one of ours.
98
+ }
99
+ }
100
+ }
101
+ catch {
102
+ // Listing is unsupported or failed; the legacy name is still deleted.
103
+ }
104
+ await Promise.all([...stale].map((name) => deleteDatabase(indexedDB, name)));
105
+ }
@@ -1,3 +1,4 @@
1
+ import type { CryptoApi } from 'matrix-js-sdk/lib/crypto-api';
1
2
  /**
2
3
  * The exchange contract, as `apps/chat-service`'s README and
3
4
  * `src/exchange.ts` define it: `POST <exchangeUrl>` with a ZITADEL bearer
@@ -61,21 +62,72 @@ export type ChatRoomSummary = {
61
62
  * which is what keeps this field climbing while `muted` stops the
62
63
  * bell. */
63
64
  readonly unreadCount: number;
65
+ /** The subset of `unreadCount` that mentions this person by name, by
66
+ * display name, or through a room-wide `@room` -- Matrix's own
67
+ * `unread_notifications.highlight_count` from `/sync`, read the same
68
+ * way `unreadCount` reads `notification_count`. `unreadCount >=
69
+ * mentionCount` always holds, so a list needs no third field: weight
70
+ * (bold) on `unreadCount > 0`, a badge on `mentionCount > 0` -- the
71
+ * distinction every other chat client draws and this one could not
72
+ * (wtfalch/chat#45).
73
+ *
74
+ * Ships as the server figure alone, with the same gap `unreadCount`'s
75
+ * own docs would have if it only read Synapse: a muted room's
76
+ * `highlight_count` is gated by the same room-scoped `dont_notify` rule
77
+ * `muteRoom` writes, so it reads `0` there regardless of whether a
78
+ * message actually named this person. `unreadCount` solves this for
79
+ * itself with a local timeline walk (`unreadTimelineCount`); the same
80
+ * walk for highlights needs push-rule evaluation (display name,
81
+ * `@room`, `.m.rule.contains_user_name`) that is not built yet. A
82
+ * muted room is exactly the case this field exists for -- muting a
83
+ * channel and staying reachable by name is most of why people are
84
+ * willing to mute it at all -- so treat `mentionCount === 0` in a muted
85
+ * room as unproven, not as "nobody mentioned you", until that walk
86
+ * exists. */
87
+ readonly mentionCount: number;
64
88
  /** Whether `muteRoom` has muted this room: a room-scoped push rule with
65
89
  * the `dont_notify` action, which is what a list dims. Independent of
66
90
  * `unreadCount` -- muting stops a room from notifying, never from
67
91
  * counting, so a muted room keeps climbing exactly as an unmuted one
68
92
  * would. */
69
93
  readonly muted: boolean;
94
+ /** Whether this room carries MSC2867's marked-unread flag: room-scoped
95
+ * account data under `m.marked_unread`, or the pre-merge
96
+ * `com.famedly.marked_unread` key some clients still write -- both are
97
+ * what `markRoomUnread` writes, and what `markRoomRead` clears. Not
98
+ * derived from `unreadCount`: unlike `muted`, which only ever changes
99
+ * whether a room notifies, marking a room unread is a person's own
100
+ * signal on top of whatever `unreadCount` already says, the same way a
101
+ * read room can still be flagged unread by hand in any Matrix client. */
102
+ readonly markedUnread: boolean;
103
+ /** Whether this room's `m.room.power_levels` has locked member writes
104
+ * (`events_default >= 100`) -- the same test `admin/index.ts`'s
105
+ * `AdminChannel.archived` reads, mirrored here so a member's client has
106
+ * something to show a refused write against (agora#32). */
107
+ readonly archived: boolean;
108
+ /** Whether `starRoom` has starred this room: the Matrix spec's own
109
+ * `m.favourite` room tag, synced across every device on the account
110
+ * the same way `hideDirectMessage`'s tag is (agora#27). */
111
+ readonly starred: boolean;
70
112
  };
71
113
  /** Someone this person can start a direct message with: a member of the
72
- * company space. Guests are never in the space (chat plan section 5), so
73
- * a guest can never appear here -- which is how "the UI does not offer it"
74
- * is kept true without this package knowing what a guest is. */
114
+ * company space, or a guest sharing a room with them (docs/guests.md,
115
+ * "What the SDK shows"). Guests are never in the space (chat plan section
116
+ * 5), so `guest` is what keeps "the UI does not offer it" true for anyone
117
+ * outside a shared room -- without this package knowing what a guest *is*.
118
+ * It displays what the service marks on a room member and enforces
119
+ * nothing of its own. */
75
120
  export type ChatPerson = {
76
121
  readonly userId: string;
77
- /** Their display name in the company space, falling back to `userId`. */
122
+ /** Their display name, falling back to `userId`. */
78
123
  readonly name: string;
124
+ /** Set when the service has marked this room member a guest, with when
125
+ * their access ends. A safety line on their messages, not decoration --
126
+ * it is how somebody knows not to paste the numbers in front of them.
127
+ * `undefined` for an ordinary member. */
128
+ readonly guest?: {
129
+ readonly until: string;
130
+ };
79
131
  };
80
132
  /** Where a `m.room.message` event stands with the homeserver, for the
81
133
  * composer's optimistic send (chat plan section 9, ticket #15). `'sent'`
@@ -240,6 +292,21 @@ export type ChatConnectionStatus = 'connected' | 'catching-up' | 'offline';
240
292
  * genuinely offline has, which is the honest answer when the only
241
293
  * difference is that nobody has said otherwise (see `ChatClient.presence`). */
242
294
  export type Presence = 'online' | 'busy' | 'away' | 'offline';
295
+ /** What a person has told us, durably -- distinct from `Presence`, which is
296
+ * ephemeral and dies with the sync loop (`docs/status.md`). Presence
297
+ * answers "is this person's app open right now"; status answers "should I
298
+ * expect a reply". They compose rather than one replacing the other:
299
+ * somebody can be `offline` and `vacation` until Monday, or `online` and
300
+ * `meeting`. See `ChatClient.status`. */
301
+ export type ChatStatus = {
302
+ readonly kind: 'here' | 'busy' | 'meeting' | 'vacation' | 'sick';
303
+ /** ISO 8601. When this status ends, if the person said. */
304
+ readonly until?: string;
305
+ /** What actually redirects the person who was about to write --
306
+ * `docs/status.md`'s own point: "on vacation" helps a little, "back on
307
+ * the 6th, ask Marcus for anything urgent" is the thing that works. */
308
+ readonly message?: string;
309
+ };
243
310
  export type CreateChatClientOptions = {
244
311
  /** `POST` here exchanges the agora's current ZITADEL token for a Matrix
245
312
  * one. See `apps/chat-service/README.md`. */
@@ -252,9 +319,15 @@ export type CreateChatClientOptions = {
252
319
  * chat plan section 4. Stable across sign-ins so MAS keeps one Matrix
253
320
  * device for its whole life. */
254
321
  deviceId: string;
255
- /** Names this client's local store, so two companies open in one browser
256
- * never share one. Typically the company/project id. */
322
+ /** Workspace namespace for this client's local store, typically the company/project id.
323
+ * The SDK also binds the cache to the exchanged homeserver and Matrix user id. */
257
324
  storeName: string;
325
+ /** Turns on matrix-js-sdk's Rust crypto layer (`initRustCrypto()`) before
326
+ * the first sync -- see `createChatClient`'s own comment for what that
327
+ * gates. `false`/omitted keeps crypto off exactly as this package always
328
+ * has: the WASM module is never even loaded. Key backup, recovery key
329
+ * and device verification (chat#67-69) all need this on first. */
330
+ encryptionEnabled?: boolean;
258
331
  };
259
332
  /**
260
333
  * What a UI needs from a signed-in chat session: whether it is running, the
@@ -276,6 +349,15 @@ export type ChatClient = {
276
349
  onRoomsChanged: (listener: (rooms: ChatRoomSummary[]) => void) => () => void;
277
350
  /** The signed-in Matrix user id, or `null` before `start()` resolves. */
278
351
  userId: () => string | null;
352
+ /** matrix-js-sdk's own crypto surface -- key backup, secret storage,
353
+ * device verification -- once `encryptionEnabled: true` has turned it on
354
+ * and `start()` has created the underlying `MatrixClient`. `undefined`
355
+ * otherwise, for the whole life of a client started with crypto off,
356
+ * the same as `MatrixClient.getCrypto()` itself. The one door
357
+ * chat#67-69's key-backup, recovery-key and device-verification methods
358
+ * reach matrix-js-sdk's `CryptoApi` through, rather than each holding
359
+ * its own closed-over `MatrixClient`. */
360
+ getCrypto: () => CryptoApi | undefined;
279
361
  /** A room's currently-known timeline, or -- given `threadId`, the id of
280
362
  * the message that started one -- that thread's own, root first. Empty,
281
363
  * with `hasMore: true`, for a room `start()` has not caught up to yet.
@@ -338,9 +420,12 @@ export type ChatClient = {
338
420
  * top-level `url` for `contains_url` to match, so this returns `[]` for
339
421
  * a room full of files exactly as it would for one with none -- an
340
422
  * empty list from such a room means "cannot see", not "none". Not a bug
341
- * to fix here: this package never calls `initRustCrypto()` (see the
342
- * module comment), so an encrypted room's whole timeline is already
343
- * unusable, not just this method.
423
+ * to fix here: crypto stays off by default (see `createChatClient`'s own
424
+ * comment), so an encrypted room's whole timeline is already unusable in
425
+ * that case, not just this method -- and turning `encryptionEnabled` on
426
+ * is only the crypto bootstrap (chat#66), not the key backup, recovery
427
+ * or device verification (chat#67-69) an encrypted room's history
428
+ * actually needs to decrypt.
344
429
  *
345
430
  * No files and a `null` cursor before `start()` resolves, or for a room
346
431
  * this client does not know. */
@@ -430,6 +515,44 @@ export type ChatClient = {
430
515
  * separator -- read once when a room is opened, not tracked live, so the
431
516
  * marker does not move while someone is reading past it. */
432
517
  readUpToEventId: (roomId: string) => string | null;
518
+ /** This session's own current draft for `roomId` -- unsent composer text
519
+ * that would otherwise not survive navigating away, a reconnect, or
520
+ * opening the room on a second device (agora#25). `''` for a room with
521
+ * no draft, or one this client does not know.
522
+ *
523
+ * Reads this client's own running knowledge of the draft, not
524
+ * matrix-js-sdk's account data directly: a write's promise resolves on
525
+ * the server's HTTP response, before its echo has come back through
526
+ * `/sync` and landed in the room's account data (the same gap
527
+ * `ChatClient.pinMessage`'s own comment documents for state events), so
528
+ * a caller reading right after an awaited `setDraft` would otherwise
529
+ * see the old value. */
530
+ getDraft: (roomId: string) => string;
531
+ /** Saves `text` as `roomId`'s draft, replacing whatever was there.
532
+ * Visible to this client at once; another device sees it once its own
533
+ * `/sync` next delivers the account data. A no-op for a room this
534
+ * client does not know, or before `start()`. */
535
+ setDraft: (roomId: string, text: string) => Promise<void>;
536
+ /** Empties `roomId`'s draft -- call this once a message actually sends,
537
+ * so the composer does not reoffer text already delivered. Same
538
+ * visibility and no-op rules as `setDraft`. */
539
+ clearDraft: (roomId: string) => Promise<void>;
540
+ /** Whether the signed-in person follows the thread `threadId` (the
541
+ * message that started it) in `roomId`. A person follows a thread by
542
+ * posting in it or being mentioned in it, until they unfollow; then only
543
+ * `followThread` follows it again. Activity tells them about replies in
544
+ * the threads they follow. Rejects when the chat service refuses or
545
+ * cannot be reached. */
546
+ threadFollowing: (roomId: string, threadId: string) => Promise<boolean>;
547
+ /** Follows the thread, including after an earlier unfollow. */
548
+ followThread: (roomId: string, threadId: string) => Promise<void>;
549
+ /** Unfollows the thread. It stays unfollowed: a later post or mention of
550
+ * the person in it does not follow it again. */
551
+ unfollowThread: (roomId: string, threadId: string) => Promise<void>;
552
+ /** Calls `listener` with whether the person follows the thread each time
553
+ * this session's own post in it has followed it (or found it
554
+ * unfollowed). Returns the unsubscribe. */
555
+ onThreadFollowChanged: (roomId: string, threadId: string, listener: (following: boolean) => void) => () => void;
433
556
  /** Whether this session may load `mxcUri` at all: a well-formed
434
557
  * `mxc://` on *this* homeserver. `false` for anything else, a reference
435
558
  * to another server included.
@@ -485,9 +608,37 @@ export type ChatClient = {
485
608
  *
486
609
  * A no-op for a room this client does not know. */
487
610
  muteRoom: (roomId: string, muted: boolean) => Promise<void>;
488
- /** Everyone in the company space except the signed-in person, by name.
489
- * Empty before `start()` resolves, and empty for a session whose
490
- * account is in no space. */
611
+ /** Sets or clears MSC2867's marked-unread flag on `roomId`: room-scoped
612
+ * account data under `m.marked_unread`, and, for clients that still read
613
+ * the pre-merge key, `com.famedly.marked_unread` alongside it -- both
614
+ * with the same content. Independent of `unreadCount` and `muted`, the
615
+ * same way `muted` is independent of `unreadCount`: this is a person's
616
+ * own flag, not a count.
617
+ *
618
+ * Account data lands through the next `/sync`, the same way a room tag
619
+ * does (`hideDirectMessage`) -- there is no local echo, and no separate
620
+ * push-rule refetch to piggyback on the way `muteRoom` does.
621
+ *
622
+ * `markRoomRead` clears this flag itself when it is set, so opening a
623
+ * room a person had marked unread also un-marks it -- a marked-unread
624
+ * room a real read left flagged would be a room no read ever un-reads.
625
+ *
626
+ * A no-op for a room this client does not know. */
627
+ markRoomUnread: (roomId: string, unread: boolean) => Promise<void>;
628
+ /** Stars or unstars `roomId`: the Matrix spec's own `m.favourite` room
629
+ * tag, the same `setRoomTag`/`deleteRoomTag` pair `hideDirectMessage`
630
+ * uses for its own tag. Room tags are account data, so starring here
631
+ * is visible on every device signed into this person's account, not
632
+ * just this session (agora#27).
633
+ *
634
+ * A no-op for a room this client does not know. */
635
+ starRoom: (roomId: string, starred: boolean) => Promise<void>;
636
+ /** Everyone in the company space except the signed-in person, plus every
637
+ * guest sharing a joined room with them (see `ChatPerson.guest`) --
638
+ * someone invited for a purpose has to be reachable by the people they
639
+ * were invited to work with. Empty before `start()` resolves, and empty
640
+ * for a session whose account is in no space and shares no room with a
641
+ * guest. */
491
642
  people: () => ChatPerson[];
492
643
  /** Opens the direct room with exactly `userIds` and resolves with its id.
493
644
  *
@@ -625,6 +776,41 @@ export type ChatClient = {
625
776
  * current presence has to read `presence(userId)` for each member first
626
777
  * and use this only to hear about what changes after. */
627
778
  onPresenceChanged: (listener: (changed: ReadonlyMap<string, Presence>) => void) => () => void;
779
+ /** Somebody's durable status -- see `ChatStatus` and `docs/status.md`.
780
+ * Stored as a Matrix custom profile field (MSC4133 extended profiles),
781
+ * so it survives the person closing their laptop entirely, unlike
782
+ * `presence`. `null` for a person with nothing set, or whose
783
+ * homeserver does not support extended profiles yet
784
+ * (`experimental_features.msc4133_enabled`, off until
785
+ * wtfalch/foundry#41 turns it on).
786
+ *
787
+ * Reads a local cache and never blocks: the first call for a given
788
+ * `userId` starts a fetch in the background and returns `null` until it
789
+ * resolves, the same lazy-then-cached shape most of this package uses
790
+ * for anything that has to reach the network. Call `onStatusChanged` to
791
+ * hear the fetch land, rather than polling this. */
792
+ status: (userId: string) => ChatStatus | null;
793
+ /** Sets, or (`null`) clears, the signed-in person's own status
794
+ * (`docs/status.md`). Writes through to the local cache and notifies
795
+ * `onStatusChanged` immediately, before the request resolves -- but
796
+ * unlike `starRoom`/`muteRoom`'s optimism, a rejection rolls the cache
797
+ * back to what it held before: this write fails for an ordinary reason
798
+ * in production today (MSC4133 off until wtfalch/foundry#41 turns it
799
+ * on), so `status(myOwnId)` reporting a status that was never actually
800
+ * saved would be a common bug here, not a rare one. Rejects rather
801
+ * than silently doing nothing when it fails.
802
+ *
803
+ * Durable by construction once it succeeds: this is what makes
804
+ * wtfalch/chat#24's own done-check true -- a colleague who reads
805
+ * `status` after this session has gone offline entirely still gets it,
806
+ * because it lives on the Matrix profile, not in this client's
807
+ * memory. */
808
+ setOwnStatus: (status: ChatStatus | null) => Promise<void>;
809
+ /** Called whenever a status fetch or `setOwnStatus` lands, with just the
810
+ * people who changed. Nothing is replayed on subscribing, the same as
811
+ * `onPresenceChanged`: read `status(userId)` for anyone already of
812
+ * interest before relying on this for what changes next. */
813
+ onStatusChanged: (listener: (changed: ReadonlyMap<string, ChatStatus | null>) => void) => () => void;
628
814
  /** Tells `roomId` the signed-in person has started, or stopped, typing --
629
815
  * `m.typing`, which is not an event: nothing lands in `timeline()`, and
630
816
  * nothing is retried if this fails, the same as any other presence-like
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "@wtfalch/chat",
3
- "version": "0.5.1",
3
+ "version": "0.6.0",
4
4
  "description": "A Matrix chat client behind the agora's token exchange.",
5
5
  "license": "MIT",
6
6
  "type": "module",
@@ -69,7 +69,7 @@
69
69
  "@types/node": "22.20.2",
70
70
  "@types/react": "19.3.0",
71
71
  "@types/react-dom": "19.3.0",
72
- "@wtfalch/design": "0.16.0",
72
+ "@wtfalch/design": "0.30.0",
73
73
  "fake-indexeddb": "6.2.5",
74
74
  "jsdom": "30.0.1",
75
75
  "react": "19.2.4",