@kispi/chat 0.7.4 → 0.8.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/dist/index.d.ts CHANGED
@@ -93,6 +93,18 @@ type UnreadCounts = {
93
93
  /** 총계가 일부만 센 값이다(방이 너무 많아 상한에서 잘렸다). */
94
94
  roomsCapped?: boolean;
95
95
  };
96
+ /**
97
+ * `notification.typing`의 data. 방 `typing`과 같은 뜻에 방 id를 붙인 것이다
98
+ * (유저 채널의 프레임에는 방 봉투가 없다).
99
+ *
100
+ * `userId`는 입력 중인 사람의 외부 id이고, `threadId`는 **루트** id다 —
101
+ * 본 타임라인이면 없다(`typing.changed`의 `threadId`와 같다).
102
+ */
103
+ type NotificationTyping = {
104
+ roomId: string;
105
+ userId: string;
106
+ threadId?: string;
107
+ };
96
108
  type Hello = {
97
109
  connectionId: string;
98
110
  user: AuthUser;
@@ -158,6 +170,77 @@ declare class Rest {
158
170
  private callWith;
159
171
  }
160
172
 
173
+ type ThreadEvents = {
174
+ /** The replies changed. A new array every time, never mutated after it is emitted. */
175
+ messages: Message[];
176
+ /** `thread.root` changed: a reaction, an edit, a delete or a new reply count on the root. */
177
+ root: Message | undefined;
178
+ /** A background read failed (the refresh after a reconnect). The thread stays open. */
179
+ error: Error;
180
+ };
181
+ /**
182
+ * One thread's replies, kept current -- what a thread panel draws.
183
+ *
184
+ * `room.thread(rootId)`이 준다. 답글은 방 스트림의 일부라 seq가 이어지지 않고,
185
+ * 오래된 답글은 방의 `messages`에 없다. 그래서 이 핸들은 스레드 뷰
186
+ * (`view=thread:<rootId>`)로 읽은 답글을 따로 들고, 방이 받는 이벤트(새 답글·
187
+ * 리액션·수정·삭제)를 그 행들에도 똑같이 적용한다. 리액션 낙관 처리(`myReactions`)도
188
+ * 방 목록과 같은 규칙이다 — `room.react()`가 두 목록을 함께 누른다.
189
+ *
190
+ * **방을 구독해야 살아 있다.** 이벤트는 방 구독으로만 오므로, 구독하지 않은 방의
191
+ * 스레드는 `load()`로 읽은 그대로 멈춰 있다.
192
+ */
193
+ declare class Thread extends Emitter<ThreadEvents> {
194
+ readonly rootId: string;
195
+ /** The newest page has been read at least once (`load()`). */
196
+ loaded: boolean;
197
+ private readonly room;
198
+ private lastRoot;
199
+ private markedSeq;
200
+ private closed;
201
+ /** Moves on `load()` and on `close()`; a read from before is dropped. */
202
+ private generation;
203
+ private readonly offRoom;
204
+ private readonly onClose;
205
+ /** The replies held, in seq order. Tombstones keep their place, as in `room.messages`. */
206
+ get messages(): Message[];
207
+ /**
208
+ * The root message: the room's own row when it holds it, or the copy passed
209
+ * to `room.thread(rootId, { root })`. Undefined when neither has it.
210
+ */
211
+ get root(): Message | undefined;
212
+ /** Whether `loadOlder()` would find more replies. False until `load()` and after a short page. */
213
+ get hasOlder(): boolean;
214
+ /**
215
+ * Reads the newest page of replies and replaces what is held (replies that
216
+ * arrived live while it was in flight survive). Call it when the panel opens.
217
+ */
218
+ load(options?: {
219
+ limit?: number;
220
+ }): Promise<void>;
221
+ /** Reads the page just above the oldest reply held and prepends it. Concurrent calls share one request. */
222
+ loadOlder(options?: {
223
+ limit?: number;
224
+ }): Promise<{
225
+ messages: Message[];
226
+ hasMore: boolean;
227
+ }>;
228
+ /**
229
+ * Moves this user's read cursor for the thread to `seq` -- by default the
230
+ * newest reply held. Skips the frame when this handle already marked that
231
+ * far, so it can be called on every `messages` event.
232
+ */
233
+ markRead(seq?: number): Promise<{
234
+ seq: number;
235
+ advanced: boolean;
236
+ }>;
237
+ /** Stops following the thread. `room.thread(rootId)` afterwards gives a new handle. */
238
+ close(): void;
239
+ private reloadPending;
240
+ private dropRows;
241
+ private checkRoot;
242
+ }
243
+
161
244
  /** A message as the server renders it. */
162
245
  type Message = {
163
246
  id: string;
@@ -229,6 +312,16 @@ type SendInput = {
229
312
  threadId?: string;
230
313
  meta?: Record<string, unknown>;
231
314
  };
315
+ /**
316
+ * What `room.edit()` replaces. The body is replaced as a whole, like the
317
+ * route: a field left out is removed, not kept -- pass the attachments back
318
+ * to keep them.
319
+ */
320
+ type EditInput = {
321
+ text?: string;
322
+ attachments?: unknown[];
323
+ entities?: unknown[];
324
+ };
232
325
  type SendOptions = {
233
326
  /**
234
327
  * Overrides the generated dedup key.
@@ -284,6 +377,11 @@ type RoomEvents = {
284
377
  * `room.subscribe()` is still the retry to offer a person pressing a
285
378
  * button -- a room that emitted this is left not-subscribed on purpose,
286
379
  * precisely so that call does something.
380
+ *
381
+ * The one exception is the refresh of held rows after a reconnect
382
+ * (`refreshHeld`): the live feed and the list are fine, so it emits this
383
+ * and leaves the room subscribed with no repair; the next reconnect
384
+ * tries again.
287
385
  */
288
386
  error: Error;
289
387
  /**
@@ -305,9 +403,15 @@ type RoomEvents = {
305
403
  */
306
404
  reset: Message[];
307
405
  'message.created': Message;
308
- /** `message.created`와 달리 `reactions`와 `thread`가 실제 값이다. */
406
+ /**
407
+ * `message.created`와 달리 `reactions`와 `thread`가 실제 값이다.
408
+ * 재접속 뒤에는 끊긴 사이 바뀐 행(리액션·스레드 수·수정)에도 이 이벤트가 온다.
409
+ */
309
410
  'message.updated': Message;
310
- /** `seq`는 그 메시지가 **발행될 때** 받은 값이다. tombstone은 seq를 쓰지 않는다. */
411
+ /**
412
+ * `seq`는 그 메시지가 **발행될 때** 받은 값이다. tombstone은 seq를 쓰지 않는다.
413
+ * 재접속 뒤에는 끊긴 사이 지워진 행에도 온다.
414
+ */
311
415
  'message.deleted': {
312
416
  id: string;
313
417
  seq: number;
@@ -329,6 +433,16 @@ type RoomEvents = {
329
433
  userId: string;
330
434
  threadId?: string;
331
435
  };
436
+ /**
437
+ * Who is typing in one place changed -- someone started, sent, or went
438
+ * quiet for five seconds. `threadId` is the thread's root, absent for the
439
+ * main timeline; `userIds` is `room.typists({ threadId })` at that moment,
440
+ * **without this client's own user**.
441
+ */
442
+ 'typing.changed': {
443
+ threadId?: string;
444
+ userIds: string[];
445
+ };
332
446
  read: {
333
447
  userId: string;
334
448
  seq: number;
@@ -408,12 +522,27 @@ declare class Room extends Emitter<RoomEvents> {
408
522
  private wanted;
409
523
  /** 신원이 바뀌어 버린 목록을 다음 구독이 다시 채우고 `reset`으로 알려야 한다. */
410
524
  private rebuildPending;
525
+ /**
526
+ * The next successful catch-up follows a real reconnect, so the held rows
527
+ * get re-read (`refreshHeld`).
528
+ *
529
+ * Set by a restarting `resume`, cleared once the refresh was started or
530
+ * the timeline was rebuilt anyway, and **kept across a failed
531
+ * attempt**: the self-repair `subscribe()` that finally succeeds is still
532
+ * the one that follows the reconnect.
533
+ */
534
+ private refreshPending;
411
535
  /** When `typing()` last tried to send (a closed socket still spends the window). See TypingSendIntervalMs. */
412
536
  private typingSentAt;
413
537
  private subscribing;
414
538
  /** Self-repair: the armed retry, and how many have run since the last success. */
415
539
  private repairTimer;
416
540
  private repairs;
541
+ /** Open thread handles by root id (`thread()`). */
542
+ private readonly threads;
543
+ /** Who is typing, by `<threadId>|<userId>` (empty threadId: the main timeline). */
544
+ private readonly typers;
545
+ private typingTimer;
417
546
  constructor(chat: ChatClient, rest: Rest, address: {
418
547
  id?: string;
419
548
  key?: string;
@@ -429,6 +558,46 @@ declare class Room extends Emitter<RoomEvents> {
429
558
  get hasOlder(): boolean;
430
559
  /** Everything this client knows about the room, in seq order. A new array whenever it changes. */
431
560
  get messages(): Message[];
561
+ /**
562
+ * A handle on one thread's replies -- what a thread panel draws.
563
+ *
564
+ * Cached per root id until `thread.close()`. Call `thread.load()` to read
565
+ * the newest replies; from then on new replies, reactions (including this
566
+ * client's optimistic `myReactions`), edits and deletes reach its rows like
567
+ * they reach `room.messages`, and a reconnect re-reads its newest page.
568
+ *
569
+ * `root` seeds `thread.root` for a root the room's list does not hold (an
570
+ * old message opened from search or a link). Without it `thread.root` is the
571
+ * room's own row, or undefined.
572
+ */
573
+ thread(rootId: string, options?: {
574
+ root?: Message;
575
+ }): Thread;
576
+ /**
577
+ * Who is typing right now in one place: the main timeline, or the thread
578
+ * whose root is `threadId`. User ids, oldest signal first, **without this
579
+ * client's own user**. Someone drops out five seconds after their last
580
+ * signal, or as soon as their message arrives. `typing.changed` fires
581
+ * whenever this changes.
582
+ */
583
+ typists(options?: {
584
+ threadId?: string;
585
+ }): string[];
586
+ /**
587
+ * Edits one of this user's own messages. The server allows only the
588
+ * sender, within the app's edit window, and answers `forbidden` otherwise.
589
+ *
590
+ * The body is **replaced**: pass `attachments` (and `entities`) back to keep
591
+ * them. The returned row is applied to `messages` (and an open thread) right
592
+ * away; the `message.updated` broadcast that follows changes nothing more.
593
+ */
594
+ edit(messageId: string, input: EditInput): Promise<Message>;
595
+ /**
596
+ * Deletes a message: this user's own, or anyone's for the room's owner and
597
+ * admins. Idempotent. The row becomes a tombstone in `messages` (and an
598
+ * open thread) right away.
599
+ */
600
+ delete(messageId: string): Promise<void>;
432
601
  /**
433
602
  * Reads the page just before the oldest message held and **prepends it to
434
603
  * `messages`**.
@@ -449,18 +618,22 @@ declare class Room extends Emitter<RoomEvents> {
449
618
  hasMore: boolean;
450
619
  }>;
451
620
  /**
452
- * Reloads recent history, discarding what is held.
453
- *
454
- * A reconnect recovers the **message timeline** and nothing else: the
455
- * only history route is `GET .../messages`, and reactions, thread
456
- * counts, read cursors, membership and room metadata ride along only
457
- * for the rows that page happens to contain. So a reaction added to an
458
- * older message while this client was away is never seen, and no
459
- * amount of gap filling will find it.
460
- *
461
- * The SDK does not hide that behind a background refresh, because the
462
- * refresh would have to be either wasteful or wrong. It gives the
463
- * consumer the one honest tool -- ask again -- and says when to use it.
621
+ * Reloads recent history, replacing what is held.
622
+ *
623
+ * A reconnect already brings the held rows up to date by itself: after
624
+ * the catch-up it re-reads the newest page (one `GET .../messages`,
625
+ * `limit=100`) and **merges** it into the rows it holds -- reactions,
626
+ * `myReactions`, thread counts, edits and deletes that happened while
627
+ * the socket was away -- see `refreshHeld`. Reactions, thread counts and
628
+ * the like ride on history rows only, and no event replays them, so
629
+ * without that read nothing would ever show them. Rows **older than the
630
+ * newest page** are not re-read; they stay as they were until
631
+ * `reload()`/`loadOlder()` or the next event for them.
632
+ *
633
+ * `reload()` is the manual version and a stronger one: it **replaces**
634
+ * the list with the newest page (rows newer than the page survive) and
635
+ * drops older pages loaded with `loadOlder()`. Use it for "refresh"
636
+ * buttons, or after anything the reconnect refresh does not cover.
464
637
  */
465
638
  reload(): Promise<void>;
466
639
  /**
@@ -473,6 +646,30 @@ declare class Room extends Emitter<RoomEvents> {
473
646
  */
474
647
  subscribe(): Promise<void>;
475
648
  private doSubscribe;
649
+ /**
650
+ * Re-reads the newest page and merges it into the rows already held.
651
+ *
652
+ * What a reconnect's catch-up cannot bring: it fetches rows this client
653
+ * does not have, and a reaction, a thread count, an edit or a delete that
654
+ * happened to a row it **does** have rides on no event it will see. One
655
+ * `GET .../messages?limit=100` per reconnect, so the newest 100 rows of
656
+ * the room are refreshed and anything older is not -- that is the bound
657
+ * on the cost, and it is the part of the room people are looking at.
658
+ * Thread replies live in the same timeline, so they and their roots come
659
+ * along.
660
+ *
661
+ * It is a merge (`Timeline.applyRefresh`): no `reset`, no rows dropped,
662
+ * older pages from `loadOlder()` untouched, and a row a live frame or a
663
+ * press changed after the read began is left to that newer value. A row
664
+ * that changed raises `message.updated`, a row now deleted raises
665
+ * `message.deleted`, as the live frames would.
666
+ *
667
+ * **Failure is background and local**: an `error` event, no repair loop
668
+ * (the live feed is fine and the next reconnect tries again), and the
669
+ * room stays subscribed. A refresh from before another reconnect, a
670
+ * reset or an unsubscribe is discarded (`stillCurrent`, the generation).
671
+ */
672
+ private refreshHeld;
476
673
  /**
477
674
  * Reads a page of history directly, without touching `messages`.
478
675
  *
@@ -522,6 +719,8 @@ declare class Room extends Emitter<RoomEvents> {
522
719
  * 두고 나온다(`Timeline.settleReaction`).
523
720
  */
524
721
  private toggleReaction;
722
+ /** The lists open threads hold beside the room's own: their replies and root copies. */
723
+ private sideLines;
525
724
  /**
526
725
  * Moves this user's read cursor.
527
726
  *
@@ -661,6 +860,12 @@ declare class Room extends Emitter<RoomEvents> {
661
860
  private resolveId;
662
861
  /** Publishes and resolves when the server acks. */
663
862
  send(input: SendInput, options?: SendOptions): Promise<PublishAck>;
863
+ private noteTyping;
864
+ private dropTypist;
865
+ private emitTypists;
866
+ /** One timer for the earliest expiry; re-armed after it fires. */
867
+ private armTypingTimer;
868
+ private clearTypists;
664
869
  /**
665
870
  * Replaces the timeline with the most recent page.
666
871
  *
@@ -674,6 +879,120 @@ declare class Room extends Emitter<RoomEvents> {
674
879
  private loadRecent;
675
880
  }
676
881
 
882
+ /**
883
+ * A room as the server renders it (`GET /v1/rooms/{id}`, `room.updated`).
884
+ *
885
+ * The fields every room has are typed; the index signature keeps whatever
886
+ * the server adds later instead of dropping it from the type.
887
+ */
888
+ type RoomInfo = {
889
+ id: string;
890
+ appId?: string;
891
+ key?: string;
892
+ type: 'public' | 'private' | 'channel' | 'dm' | (string & {});
893
+ name?: string;
894
+ meta?: Record<string, unknown>;
895
+ lastSeq?: number;
896
+ minSeq?: number;
897
+ createdAt?: number;
898
+ updatedAt?: number;
899
+ [field: string]: unknown;
900
+ };
901
+ /** One row of `chat.rooms.list()` (`GET /v1/me/rooms`): a room this user is in, with its unread. */
902
+ type MyRoom = {
903
+ room: RoomInfo;
904
+ lastSeq: number;
905
+ /** This user's main-timeline read cursor. */
906
+ readSeq: number;
907
+ /** Main timeline, not this user's own, not deleted. */
908
+ unread: number;
909
+ unreadMentions: number;
910
+ unreadCapped?: boolean;
911
+ lastMessage?: {
912
+ id: string;
913
+ seq: number;
914
+ sender: {
915
+ id: string;
916
+ name: string;
917
+ avatar?: string;
918
+ };
919
+ kind?: string;
920
+ body?: {
921
+ text?: string;
922
+ attachments?: unknown[];
923
+ };
924
+ createdAt?: number;
925
+ };
926
+ };
927
+ /** One row of `members.list()`. A withdrawn identity keeps its row with no `userId`. */
928
+ type MemberRow = {
929
+ userId?: string;
930
+ name?: string;
931
+ role: 'owner' | 'admin' | 'member' | (string & {});
932
+ joinedAt?: number;
933
+ withdrawn?: boolean;
934
+ };
935
+ /** A room in the live list (`chat.roomList()`). */
936
+ type RoomSummary = {
937
+ id: string;
938
+ /** The room object, kept current by `room.updated`. */
939
+ room: RoomInfo;
940
+ lastSeq: number;
941
+ readSeq: number;
942
+ unread: number;
943
+ mentions: number;
944
+ /** The counts stopped at the server's cap. */
945
+ unreadCapped?: boolean;
946
+ lastMessage?: MyRoom['lastMessage'];
947
+ };
948
+ type RoomListEvents = {
949
+ /** The list changed. A new array every time, never mutated after it is emitted. */
950
+ rooms: RoomSummary[];
951
+ /** A load failed. The list keeps what it had. */
952
+ error: Error;
953
+ };
954
+ /**
955
+ * The rooms this user is in, with unread counts kept current -- a channel
956
+ * sidebar.
957
+ *
958
+ * `chat.roomList()` gives one per client. `load()` reads `GET /v1/me/rooms`
959
+ * (up to a thousand rooms); after that the SDK keeps it current:
960
+ *
961
+ * - `notification` (a message in a room this client has not subscribed):
962
+ * the server's `unread`/`unreadMentions` for that room, and `lastSeq`. A
963
+ * room the list does not know -- this user was just added -- reloads it.
964
+ * - A message in a subscribed room moves its `lastSeq`; this client's own
965
+ * `room.markRead()` on the main timeline moves `readSeq` and, once it
966
+ * reaches `lastSeq`, zeroes the counts.
967
+ * - `room.updated` replaces the room object, `room.deleted` and this user's
968
+ * own `member.left` drop the room (both arrive only for subscribed rooms).
969
+ * - A reconnect or a return to the tab (`resumed`) reloads it: counts that
970
+ * moved while the socket was away ride on no event.
971
+ *
972
+ * Order is the server's (latest activity first) for rooms from a load;
973
+ * sorting and grouping are the screen's.
974
+ */
975
+ declare class RoomList extends Emitter<RoomListEvents> {
976
+ /** At least one `load()` finished. */
977
+ loaded: boolean;
978
+ private list;
979
+ private readonly pager;
980
+ private loading;
981
+ private again;
982
+ /** The rooms, as of the last change. A new array whenever it changes. */
983
+ get rooms(): RoomSummary[];
984
+ get(roomId: string): RoomSummary | undefined;
985
+ /**
986
+ * Reads the list from the server and replaces what is held. A call while
987
+ * one is in flight runs once more after it, so the last answer is never
988
+ * older than the last call.
989
+ */
990
+ load(): Promise<void>;
991
+ private readAll;
992
+ private patch;
993
+ private set;
994
+ }
995
+
677
996
  /**
678
997
  * A WebSocket constructor. Injectable because the tests need one that can
679
998
  * be made to misbehave -- an open socket that never answers, a close at a
@@ -718,7 +1037,40 @@ type ChatClientOptions = {
718
1037
  type ChatClientEvents = {
719
1038
  state: ConnectionState;
720
1039
  notification: unknown;
1040
+ /**
1041
+ * Someone is typing in a room you are a member of but have not subscribed,
1042
+ * for a chat list's "typing..." beside that conversation.
1043
+ *
1044
+ * It comes only for small rooms (the engine sends it to rooms of about ten
1045
+ * members or fewer -- a bigger room never gets one, so do not read silence
1046
+ * as "nobody is typing"), never for your own typing, and never for a room
1047
+ * you have subscribed: that room's typing arrives through `room.typists()`
1048
+ * and `typing.changed`, so a screen that shows both reads the open room
1049
+ * from the room and every other row from here.
1050
+ *
1051
+ * There is no "stopped typing" event. Show it for **five seconds or
1052
+ * more** after the last one (the sender's signal comes about every three
1053
+ * seconds) and let it lapse, and clear it when that user's message
1054
+ * arrives -- `notification`'s `preview.sender.id`, or the room's
1055
+ * `message.created`. Not replayed after a reconnect.
1056
+ */
1057
+ 'notification.typing': NotificationTyping;
721
1058
  'user.presence': unknown;
1059
+ /**
1060
+ * The client came back: a reconnect reached `hello` again, or `resume()`
1061
+ * (tab visible, network back, a page restored from the back/forward cache)
1062
+ * found the socket alive and resubscribed every room.
1063
+ *
1064
+ * Rooms catch themselves up -- new messages, and the held rows' reactions,
1065
+ * thread counts, edits and deletes. This is for what the SDK does not hold:
1066
+ * a screen's own lists fetched over REST (an activity feed, a search). The
1067
+ * live room list (`roomList()`) already reloads on it.
1068
+ *
1069
+ * `reconnected` is false when the old socket was still alive.
1070
+ */
1071
+ resumed: {
1072
+ reconnected: boolean;
1073
+ };
722
1074
  /**
723
1075
  * A frame the SDK did not route anywhere. Emitted rather than dropped
724
1076
  * so a server that grows an event is visible to a consumer before the
@@ -803,6 +1155,8 @@ declare class ChatClient extends Emitter<ChatClientEvents> {
803
1155
  resume(): Promise<void>;
804
1156
  private resuming;
805
1157
  private resumeOnce;
1158
+ /** `resumed`, after the rooms were told. The live room list reloads first. */
1159
+ private cameBack;
806
1160
  /**
807
1161
  * Pings `socket` and resolves whether any frame came back within
808
1162
  * `ResumeProbeMs`. The server's `pong` carries no id, so "any frame on
@@ -814,20 +1168,33 @@ declare class ChatClient extends Emitter<ChatClientEvents> {
814
1168
  private settleProbes;
815
1169
  /** The account-level routes: the rooms this user is in, and unread. */
816
1170
  get rooms(): {
1171
+ /** One page of the rooms this user is in, latest activity first. `cursor` is `''` on the last page. */
817
1172
  list: (options?: {
818
1173
  cursor?: string;
819
1174
  limit?: number;
820
- }) => Promise<unknown>;
1175
+ }) => Promise<{
1176
+ rooms: MyRoom[];
1177
+ cursor: string;
1178
+ }>;
821
1179
  discover: (options?: {
822
1180
  type?: 'public' | 'channel';
823
1181
  cursor?: string;
824
1182
  limit?: number;
825
1183
  }) => Promise<unknown>;
1184
+ update: (roomId: string, patch: {
1185
+ name?: string;
1186
+ meta?: Record<string, unknown>;
1187
+ }) => Promise<RoomInfo>;
1188
+ /** Soft-deletes the room. The owner only (`forbidden` otherwise); subscribers get `room.deleted`. */
1189
+ delete: (roomId: string) => Promise<void>;
826
1190
  members: (roomId: string) => {
827
1191
  list: (options?: {
828
1192
  cursor?: string;
829
1193
  limit?: number;
830
- }) => Promise<unknown>;
1194
+ }) => Promise<{
1195
+ members: MemberRow[];
1196
+ cursor: string;
1197
+ }>;
831
1198
  add: (userId: string, role?: string) => Promise<void>;
832
1199
  remove: (userId: string) => Promise<void>;
833
1200
  };
@@ -862,6 +1229,12 @@ declare class ChatClient extends Emitter<ChatClientEvents> {
862
1229
  * object is **replaced**, not merged into.
863
1230
  */
864
1231
  updateMe(meta: Record<string, unknown>): Promise<unknown>;
1232
+ /**
1233
+ * The rooms this user is in, with unread counts the SDK keeps current --
1234
+ * see `RoomList`. One per client; call `load()` once to fill it.
1235
+ */
1236
+ roomList(): RoomList;
1237
+ private list;
865
1238
  /**
866
1239
  * A handle on a room by id.
867
1240
  *
@@ -997,4 +1370,64 @@ declare function createChatClient(options: ChatClientOptions): ChatClient;
997
1370
  */
998
1371
  declare const ChatEndpoint = "wss://api.chat.gravex.app";
999
1372
 
1000
- export { type AuthUser, ChatClient, type ChatClientEvents, type ChatClientOptions, ChatEndpoint, ChatError, type ChatErrorCode, type ConnectionState, type Frame, type Hello, type Message, type PresenceEvent, type PresenceUser, type PublishAck, type ReactionEvent, type ReactionUser, type ReactionsPage, Room, type RoomEvents, type SendInput, type SendOptions, type UnreadCounts, type WebSocketFactory, type WebSocketLike, createChatClient };
1373
+ /**
1374
+ * @멘션을 `body.entities`로 싣고, 받은 것을 믿을 수 있는 조각으로 읽는 도우미.
1375
+ *
1376
+ * 엔진의 멘션은 글자가 아니라 entity다: `{type: 'mention', userId, offset, length}`
1377
+ * — `userId`는 앱의 외부 id, `offset`·`length`는 `body.text`의 JS(UTF-16) 인덱스이고
1378
+ * `@이름` 전체를 덮는다. 엔진은 `userId`만 풀어 `unreadMentions`·푸시에 쓰고
1379
+ * `offset`·`length`는 **검증하지 않는다**(docs/protocol.md `publish`). 그래서 보내는 쪽은
1380
+ * 최종 글에서 자리를 세어야 하고(`buildMentions`), 그리는 쪽은 받은 값을 검증해야 한다
1381
+ * (`mentionSpans`).
1382
+ */
1383
+ /** One mention as the engine stores it in `body.entities`. */
1384
+ type MentionEntity = {
1385
+ type: 'mention';
1386
+ userId: string;
1387
+ offset: number;
1388
+ length: number;
1389
+ };
1390
+ /** A mention that checked out against the text: `text.slice(start, end)` is `@name`. */
1391
+ type MentionSpan = {
1392
+ start: number;
1393
+ end: number;
1394
+ userId: string;
1395
+ };
1396
+ /**
1397
+ * Finds `@name` for each of `people` in the **final** text and returns the
1398
+ * entities to send with it.
1399
+ *
1400
+ * Count on the text being sent, not on what the input box remembered: a
1401
+ * mention typed and then edited away simply is not found, and the offsets
1402
+ * are right after any rewrite (a long text replaced by a preview, a trim).
1403
+ *
1404
+ * - `@` must start the text or follow a character that is not a letter,
1405
+ * digit, `_`, `.` or `@` -- `a@b.com` is not a mention.
1406
+ * - The name must end the text or be followed by a non-name character, so
1407
+ * `@Ann` does not match the start of `@Anna`; the longer name is tried
1408
+ * first.
1409
+ * - Inside markdown code -- a fenced block or an inline span in backticks --
1410
+ * nothing is a mention, unless `skipCode: false`.
1411
+ * - Two people with the same name are given out in the order they appear in
1412
+ * `people`, one per occurrence; past that the name is left alone (whose
1413
+ * it is cannot be known).
1414
+ * - At most 100, the engine's cap.
1415
+ */
1416
+ declare function buildMentions(text: string, people: readonly {
1417
+ id: string;
1418
+ name: string;
1419
+ }[], options?: {
1420
+ skipCode?: boolean;
1421
+ }): MentionEntity[];
1422
+ /**
1423
+ * The mentions in a received message that agree with its text, in order.
1424
+ *
1425
+ * Somebody else's client wrote these, and the engine does not check the
1426
+ * offsets, so each is kept only if it is a mention with a `userId`, its
1427
+ * range lies inside the text on one line and starts at an `@`, and it does
1428
+ * not overlap an earlier one. Anything else is dropped rather than drawn in
1429
+ * the wrong place.
1430
+ */
1431
+ declare function mentionSpans(text: string, entities: unknown): MentionSpan[];
1432
+
1433
+ export { type AuthUser, ChatClient, type ChatClientEvents, type ChatClientOptions, ChatEndpoint, ChatError, type ChatErrorCode, type ConnectionState, type EditInput, type Frame, type Hello, type MemberRow, type MentionEntity, type MentionSpan, type Message, type MyRoom, type NotificationTyping, type PresenceEvent, type PresenceUser, type PublishAck, type ReactionEvent, type ReactionUser, type ReactionsPage, Room, type RoomEvents, type RoomInfo, RoomList, type RoomListEvents, type RoomSummary, type SendInput, type SendOptions, Thread, type ThreadEvents, type UnreadCounts, type WebSocketFactory, type WebSocketLike, buildMentions, createChatClient, mentionSpans };