@kispi/chat 0.7.4 → 0.7.5

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
@@ -158,6 +158,77 @@ declare class Rest {
158
158
  private callWith;
159
159
  }
160
160
 
161
+ type ThreadEvents = {
162
+ /** The replies changed. A new array every time, never mutated after it is emitted. */
163
+ messages: Message[];
164
+ /** `thread.root` changed: a reaction, an edit, a delete or a new reply count on the root. */
165
+ root: Message | undefined;
166
+ /** A background read failed (the refresh after a reconnect). The thread stays open. */
167
+ error: Error;
168
+ };
169
+ /**
170
+ * One thread's replies, kept current -- what a thread panel draws.
171
+ *
172
+ * `room.thread(rootId)`이 준다. 답글은 방 스트림의 일부라 seq가 이어지지 않고,
173
+ * 오래된 답글은 방의 `messages`에 없다. 그래서 이 핸들은 스레드 뷰
174
+ * (`view=thread:<rootId>`)로 읽은 답글을 따로 들고, 방이 받는 이벤트(새 답글·
175
+ * 리액션·수정·삭제)를 그 행들에도 똑같이 적용한다. 리액션 낙관 처리(`myReactions`)도
176
+ * 방 목록과 같은 규칙이다 — `room.react()`가 두 목록을 함께 누른다.
177
+ *
178
+ * **방을 구독해야 살아 있다.** 이벤트는 방 구독으로만 오므로, 구독하지 않은 방의
179
+ * 스레드는 `load()`로 읽은 그대로 멈춰 있다.
180
+ */
181
+ declare class Thread extends Emitter<ThreadEvents> {
182
+ readonly rootId: string;
183
+ /** The newest page has been read at least once (`load()`). */
184
+ loaded: boolean;
185
+ private readonly room;
186
+ private lastRoot;
187
+ private markedSeq;
188
+ private closed;
189
+ /** Moves on `load()` and on `close()`; a read from before is dropped. */
190
+ private generation;
191
+ private readonly offRoom;
192
+ private readonly onClose;
193
+ /** The replies held, in seq order. Tombstones keep their place, as in `room.messages`. */
194
+ get messages(): Message[];
195
+ /**
196
+ * The root message: the room's own row when it holds it, or the copy passed
197
+ * to `room.thread(rootId, { root })`. Undefined when neither has it.
198
+ */
199
+ get root(): Message | undefined;
200
+ /** Whether `loadOlder()` would find more replies. False until `load()` and after a short page. */
201
+ get hasOlder(): boolean;
202
+ /**
203
+ * Reads the newest page of replies and replaces what is held (replies that
204
+ * arrived live while it was in flight survive). Call it when the panel opens.
205
+ */
206
+ load(options?: {
207
+ limit?: number;
208
+ }): Promise<void>;
209
+ /** Reads the page just above the oldest reply held and prepends it. Concurrent calls share one request. */
210
+ loadOlder(options?: {
211
+ limit?: number;
212
+ }): Promise<{
213
+ messages: Message[];
214
+ hasMore: boolean;
215
+ }>;
216
+ /**
217
+ * Moves this user's read cursor for the thread to `seq` -- by default the
218
+ * newest reply held. Skips the frame when this handle already marked that
219
+ * far, so it can be called on every `messages` event.
220
+ */
221
+ markRead(seq?: number): Promise<{
222
+ seq: number;
223
+ advanced: boolean;
224
+ }>;
225
+ /** Stops following the thread. `room.thread(rootId)` afterwards gives a new handle. */
226
+ close(): void;
227
+ private reloadPending;
228
+ private dropRows;
229
+ private checkRoot;
230
+ }
231
+
161
232
  /** A message as the server renders it. */
162
233
  type Message = {
163
234
  id: string;
@@ -229,6 +300,16 @@ type SendInput = {
229
300
  threadId?: string;
230
301
  meta?: Record<string, unknown>;
231
302
  };
303
+ /**
304
+ * What `room.edit()` replaces. The body is replaced as a whole, like the
305
+ * route: a field left out is removed, not kept -- pass the attachments back
306
+ * to keep them.
307
+ */
308
+ type EditInput = {
309
+ text?: string;
310
+ attachments?: unknown[];
311
+ entities?: unknown[];
312
+ };
232
313
  type SendOptions = {
233
314
  /**
234
315
  * Overrides the generated dedup key.
@@ -284,6 +365,11 @@ type RoomEvents = {
284
365
  * `room.subscribe()` is still the retry to offer a person pressing a
285
366
  * button -- a room that emitted this is left not-subscribed on purpose,
286
367
  * precisely so that call does something.
368
+ *
369
+ * The one exception is the refresh of held rows after a reconnect
370
+ * (`refreshHeld`): the live feed and the list are fine, so it emits this
371
+ * and leaves the room subscribed with no repair; the next reconnect
372
+ * tries again.
287
373
  */
288
374
  error: Error;
289
375
  /**
@@ -305,9 +391,15 @@ type RoomEvents = {
305
391
  */
306
392
  reset: Message[];
307
393
  'message.created': Message;
308
- /** `message.created`와 달리 `reactions`와 `thread`가 실제 값이다. */
394
+ /**
395
+ * `message.created`와 달리 `reactions`와 `thread`가 실제 값이다.
396
+ * 재접속 뒤에는 끊긴 사이 바뀐 행(리액션·스레드 수·수정)에도 이 이벤트가 온다.
397
+ */
309
398
  'message.updated': Message;
310
- /** `seq`는 그 메시지가 **발행될 때** 받은 값이다. tombstone은 seq를 쓰지 않는다. */
399
+ /**
400
+ * `seq`는 그 메시지가 **발행될 때** 받은 값이다. tombstone은 seq를 쓰지 않는다.
401
+ * 재접속 뒤에는 끊긴 사이 지워진 행에도 온다.
402
+ */
311
403
  'message.deleted': {
312
404
  id: string;
313
405
  seq: number;
@@ -329,6 +421,16 @@ type RoomEvents = {
329
421
  userId: string;
330
422
  threadId?: string;
331
423
  };
424
+ /**
425
+ * Who is typing in one place changed -- someone started, sent, or went
426
+ * quiet for five seconds. `threadId` is the thread's root, absent for the
427
+ * main timeline; `userIds` is `room.typists({ threadId })` at that moment,
428
+ * **without this client's own user**.
429
+ */
430
+ 'typing.changed': {
431
+ threadId?: string;
432
+ userIds: string[];
433
+ };
332
434
  read: {
333
435
  userId: string;
334
436
  seq: number;
@@ -408,12 +510,27 @@ declare class Room extends Emitter<RoomEvents> {
408
510
  private wanted;
409
511
  /** 신원이 바뀌어 버린 목록을 다음 구독이 다시 채우고 `reset`으로 알려야 한다. */
410
512
  private rebuildPending;
513
+ /**
514
+ * The next successful catch-up follows a real reconnect, so the held rows
515
+ * get re-read (`refreshHeld`).
516
+ *
517
+ * Set by a restarting `resume`, cleared once the refresh was started or
518
+ * the timeline was rebuilt anyway, and **kept across a failed
519
+ * attempt**: the self-repair `subscribe()` that finally succeeds is still
520
+ * the one that follows the reconnect.
521
+ */
522
+ private refreshPending;
411
523
  /** When `typing()` last tried to send (a closed socket still spends the window). See TypingSendIntervalMs. */
412
524
  private typingSentAt;
413
525
  private subscribing;
414
526
  /** Self-repair: the armed retry, and how many have run since the last success. */
415
527
  private repairTimer;
416
528
  private repairs;
529
+ /** Open thread handles by root id (`thread()`). */
530
+ private readonly threads;
531
+ /** Who is typing, by `<threadId>|<userId>` (empty threadId: the main timeline). */
532
+ private readonly typers;
533
+ private typingTimer;
417
534
  constructor(chat: ChatClient, rest: Rest, address: {
418
535
  id?: string;
419
536
  key?: string;
@@ -429,6 +546,46 @@ declare class Room extends Emitter<RoomEvents> {
429
546
  get hasOlder(): boolean;
430
547
  /** Everything this client knows about the room, in seq order. A new array whenever it changes. */
431
548
  get messages(): Message[];
549
+ /**
550
+ * A handle on one thread's replies -- what a thread panel draws.
551
+ *
552
+ * Cached per root id until `thread.close()`. Call `thread.load()` to read
553
+ * the newest replies; from then on new replies, reactions (including this
554
+ * client's optimistic `myReactions`), edits and deletes reach its rows like
555
+ * they reach `room.messages`, and a reconnect re-reads its newest page.
556
+ *
557
+ * `root` seeds `thread.root` for a root the room's list does not hold (an
558
+ * old message opened from search or a link). Without it `thread.root` is the
559
+ * room's own row, or undefined.
560
+ */
561
+ thread(rootId: string, options?: {
562
+ root?: Message;
563
+ }): Thread;
564
+ /**
565
+ * Who is typing right now in one place: the main timeline, or the thread
566
+ * whose root is `threadId`. User ids, oldest signal first, **without this
567
+ * client's own user**. Someone drops out five seconds after their last
568
+ * signal, or as soon as their message arrives. `typing.changed` fires
569
+ * whenever this changes.
570
+ */
571
+ typists(options?: {
572
+ threadId?: string;
573
+ }): string[];
574
+ /**
575
+ * Edits one of this user's own messages. The server allows only the
576
+ * sender, within the app's edit window, and answers `forbidden` otherwise.
577
+ *
578
+ * The body is **replaced**: pass `attachments` (and `entities`) back to keep
579
+ * them. The returned row is applied to `messages` (and an open thread) right
580
+ * away; the `message.updated` broadcast that follows changes nothing more.
581
+ */
582
+ edit(messageId: string, input: EditInput): Promise<Message>;
583
+ /**
584
+ * Deletes a message: this user's own, or anyone's for the room's owner and
585
+ * admins. Idempotent. The row becomes a tombstone in `messages` (and an
586
+ * open thread) right away.
587
+ */
588
+ delete(messageId: string): Promise<void>;
432
589
  /**
433
590
  * Reads the page just before the oldest message held and **prepends it to
434
591
  * `messages`**.
@@ -449,18 +606,22 @@ declare class Room extends Emitter<RoomEvents> {
449
606
  hasMore: boolean;
450
607
  }>;
451
608
  /**
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.
609
+ * Reloads recent history, replacing what is held.
610
+ *
611
+ * A reconnect already brings the held rows up to date by itself: after
612
+ * the catch-up it re-reads the newest page (one `GET .../messages`,
613
+ * `limit=100`) and **merges** it into the rows it holds -- reactions,
614
+ * `myReactions`, thread counts, edits and deletes that happened while
615
+ * the socket was away -- see `refreshHeld`. Reactions, thread counts and
616
+ * the like ride on history rows only, and no event replays them, so
617
+ * without that read nothing would ever show them. Rows **older than the
618
+ * newest page** are not re-read; they stay as they were until
619
+ * `reload()`/`loadOlder()` or the next event for them.
620
+ *
621
+ * `reload()` is the manual version and a stronger one: it **replaces**
622
+ * the list with the newest page (rows newer than the page survive) and
623
+ * drops older pages loaded with `loadOlder()`. Use it for "refresh"
624
+ * buttons, or after anything the reconnect refresh does not cover.
464
625
  */
465
626
  reload(): Promise<void>;
466
627
  /**
@@ -473,6 +634,30 @@ declare class Room extends Emitter<RoomEvents> {
473
634
  */
474
635
  subscribe(): Promise<void>;
475
636
  private doSubscribe;
637
+ /**
638
+ * Re-reads the newest page and merges it into the rows already held.
639
+ *
640
+ * What a reconnect's catch-up cannot bring: it fetches rows this client
641
+ * does not have, and a reaction, a thread count, an edit or a delete that
642
+ * happened to a row it **does** have rides on no event it will see. One
643
+ * `GET .../messages?limit=100` per reconnect, so the newest 100 rows of
644
+ * the room are refreshed and anything older is not -- that is the bound
645
+ * on the cost, and it is the part of the room people are looking at.
646
+ * Thread replies live in the same timeline, so they and their roots come
647
+ * along.
648
+ *
649
+ * It is a merge (`Timeline.applyRefresh`): no `reset`, no rows dropped,
650
+ * older pages from `loadOlder()` untouched, and a row a live frame or a
651
+ * press changed after the read began is left to that newer value. A row
652
+ * that changed raises `message.updated`, a row now deleted raises
653
+ * `message.deleted`, as the live frames would.
654
+ *
655
+ * **Failure is background and local**: an `error` event, no repair loop
656
+ * (the live feed is fine and the next reconnect tries again), and the
657
+ * room stays subscribed. A refresh from before another reconnect, a
658
+ * reset or an unsubscribe is discarded (`stillCurrent`, the generation).
659
+ */
660
+ private refreshHeld;
476
661
  /**
477
662
  * Reads a page of history directly, without touching `messages`.
478
663
  *
@@ -522,6 +707,8 @@ declare class Room extends Emitter<RoomEvents> {
522
707
  * 두고 나온다(`Timeline.settleReaction`).
523
708
  */
524
709
  private toggleReaction;
710
+ /** The lists open threads hold beside the room's own: their replies and root copies. */
711
+ private sideLines;
525
712
  /**
526
713
  * Moves this user's read cursor.
527
714
  *
@@ -661,6 +848,12 @@ declare class Room extends Emitter<RoomEvents> {
661
848
  private resolveId;
662
849
  /** Publishes and resolves when the server acks. */
663
850
  send(input: SendInput, options?: SendOptions): Promise<PublishAck>;
851
+ private noteTyping;
852
+ private dropTypist;
853
+ private emitTypists;
854
+ /** One timer for the earliest expiry; re-armed after it fires. */
855
+ private armTypingTimer;
856
+ private clearTypists;
664
857
  /**
665
858
  * Replaces the timeline with the most recent page.
666
859
  *
@@ -674,6 +867,120 @@ declare class Room extends Emitter<RoomEvents> {
674
867
  private loadRecent;
675
868
  }
676
869
 
870
+ /**
871
+ * A room as the server renders it (`GET /v1/rooms/{id}`, `room.updated`).
872
+ *
873
+ * The fields every room has are typed; the index signature keeps whatever
874
+ * the server adds later instead of dropping it from the type.
875
+ */
876
+ type RoomInfo = {
877
+ id: string;
878
+ appId?: string;
879
+ key?: string;
880
+ type: 'public' | 'private' | 'channel' | 'dm' | (string & {});
881
+ name?: string;
882
+ meta?: Record<string, unknown>;
883
+ lastSeq?: number;
884
+ minSeq?: number;
885
+ createdAt?: number;
886
+ updatedAt?: number;
887
+ [field: string]: unknown;
888
+ };
889
+ /** One row of `chat.rooms.list()` (`GET /v1/me/rooms`): a room this user is in, with its unread. */
890
+ type MyRoom = {
891
+ room: RoomInfo;
892
+ lastSeq: number;
893
+ /** This user's main-timeline read cursor. */
894
+ readSeq: number;
895
+ /** Main timeline, not this user's own, not deleted. */
896
+ unread: number;
897
+ unreadMentions: number;
898
+ unreadCapped?: boolean;
899
+ lastMessage?: {
900
+ id: string;
901
+ seq: number;
902
+ sender: {
903
+ id: string;
904
+ name: string;
905
+ avatar?: string;
906
+ };
907
+ kind?: string;
908
+ body?: {
909
+ text?: string;
910
+ attachments?: unknown[];
911
+ };
912
+ createdAt?: number;
913
+ };
914
+ };
915
+ /** One row of `members.list()`. A withdrawn identity keeps its row with no `userId`. */
916
+ type MemberRow = {
917
+ userId?: string;
918
+ name?: string;
919
+ role: 'owner' | 'admin' | 'member' | (string & {});
920
+ joinedAt?: number;
921
+ withdrawn?: boolean;
922
+ };
923
+ /** A room in the live list (`chat.roomList()`). */
924
+ type RoomSummary = {
925
+ id: string;
926
+ /** The room object, kept current by `room.updated`. */
927
+ room: RoomInfo;
928
+ lastSeq: number;
929
+ readSeq: number;
930
+ unread: number;
931
+ mentions: number;
932
+ /** The counts stopped at the server's cap. */
933
+ unreadCapped?: boolean;
934
+ lastMessage?: MyRoom['lastMessage'];
935
+ };
936
+ type RoomListEvents = {
937
+ /** The list changed. A new array every time, never mutated after it is emitted. */
938
+ rooms: RoomSummary[];
939
+ /** A load failed. The list keeps what it had. */
940
+ error: Error;
941
+ };
942
+ /**
943
+ * The rooms this user is in, with unread counts kept current -- a channel
944
+ * sidebar.
945
+ *
946
+ * `chat.roomList()` gives one per client. `load()` reads `GET /v1/me/rooms`
947
+ * (up to a thousand rooms); after that the SDK keeps it current:
948
+ *
949
+ * - `notification` (a message in a room this client has not subscribed):
950
+ * the server's `unread`/`unreadMentions` for that room, and `lastSeq`. A
951
+ * room the list does not know -- this user was just added -- reloads it.
952
+ * - A message in a subscribed room moves its `lastSeq`; this client's own
953
+ * `room.markRead()` on the main timeline moves `readSeq` and, once it
954
+ * reaches `lastSeq`, zeroes the counts.
955
+ * - `room.updated` replaces the room object, `room.deleted` and this user's
956
+ * own `member.left` drop the room (both arrive only for subscribed rooms).
957
+ * - A reconnect or a return to the tab (`resumed`) reloads it: counts that
958
+ * moved while the socket was away ride on no event.
959
+ *
960
+ * Order is the server's (latest activity first) for rooms from a load;
961
+ * sorting and grouping are the screen's.
962
+ */
963
+ declare class RoomList extends Emitter<RoomListEvents> {
964
+ /** At least one `load()` finished. */
965
+ loaded: boolean;
966
+ private list;
967
+ private readonly pager;
968
+ private loading;
969
+ private again;
970
+ /** The rooms, as of the last change. A new array whenever it changes. */
971
+ get rooms(): RoomSummary[];
972
+ get(roomId: string): RoomSummary | undefined;
973
+ /**
974
+ * Reads the list from the server and replaces what is held. A call while
975
+ * one is in flight runs once more after it, so the last answer is never
976
+ * older than the last call.
977
+ */
978
+ load(): Promise<void>;
979
+ private readAll;
980
+ private patch;
981
+ private set;
982
+ }
983
+
677
984
  /**
678
985
  * A WebSocket constructor. Injectable because the tests need one that can
679
986
  * be made to misbehave -- an open socket that never answers, a close at a
@@ -719,6 +1026,21 @@ type ChatClientEvents = {
719
1026
  state: ConnectionState;
720
1027
  notification: unknown;
721
1028
  'user.presence': unknown;
1029
+ /**
1030
+ * The client came back: a reconnect reached `hello` again, or `resume()`
1031
+ * (tab visible, network back, a page restored from the back/forward cache)
1032
+ * found the socket alive and resubscribed every room.
1033
+ *
1034
+ * Rooms catch themselves up -- new messages, and the held rows' reactions,
1035
+ * thread counts, edits and deletes. This is for what the SDK does not hold:
1036
+ * a screen's own lists fetched over REST (an activity feed, a search). The
1037
+ * live room list (`roomList()`) already reloads on it.
1038
+ *
1039
+ * `reconnected` is false when the old socket was still alive.
1040
+ */
1041
+ resumed: {
1042
+ reconnected: boolean;
1043
+ };
722
1044
  /**
723
1045
  * A frame the SDK did not route anywhere. Emitted rather than dropped
724
1046
  * so a server that grows an event is visible to a consumer before the
@@ -803,6 +1125,8 @@ declare class ChatClient extends Emitter<ChatClientEvents> {
803
1125
  resume(): Promise<void>;
804
1126
  private resuming;
805
1127
  private resumeOnce;
1128
+ /** `resumed`, after the rooms were told. The live room list reloads first. */
1129
+ private cameBack;
806
1130
  /**
807
1131
  * Pings `socket` and resolves whether any frame came back within
808
1132
  * `ResumeProbeMs`. The server's `pong` carries no id, so "any frame on
@@ -814,20 +1138,33 @@ declare class ChatClient extends Emitter<ChatClientEvents> {
814
1138
  private settleProbes;
815
1139
  /** The account-level routes: the rooms this user is in, and unread. */
816
1140
  get rooms(): {
1141
+ /** One page of the rooms this user is in, latest activity first. `cursor` is `''` on the last page. */
817
1142
  list: (options?: {
818
1143
  cursor?: string;
819
1144
  limit?: number;
820
- }) => Promise<unknown>;
1145
+ }) => Promise<{
1146
+ rooms: MyRoom[];
1147
+ cursor: string;
1148
+ }>;
821
1149
  discover: (options?: {
822
1150
  type?: 'public' | 'channel';
823
1151
  cursor?: string;
824
1152
  limit?: number;
825
1153
  }) => Promise<unknown>;
1154
+ update: (roomId: string, patch: {
1155
+ name?: string;
1156
+ meta?: Record<string, unknown>;
1157
+ }) => Promise<RoomInfo>;
1158
+ /** Soft-deletes the room. The owner only (`forbidden` otherwise); subscribers get `room.deleted`. */
1159
+ delete: (roomId: string) => Promise<void>;
826
1160
  members: (roomId: string) => {
827
1161
  list: (options?: {
828
1162
  cursor?: string;
829
1163
  limit?: number;
830
- }) => Promise<unknown>;
1164
+ }) => Promise<{
1165
+ members: MemberRow[];
1166
+ cursor: string;
1167
+ }>;
831
1168
  add: (userId: string, role?: string) => Promise<void>;
832
1169
  remove: (userId: string) => Promise<void>;
833
1170
  };
@@ -862,6 +1199,12 @@ declare class ChatClient extends Emitter<ChatClientEvents> {
862
1199
  * object is **replaced**, not merged into.
863
1200
  */
864
1201
  updateMe(meta: Record<string, unknown>): Promise<unknown>;
1202
+ /**
1203
+ * The rooms this user is in, with unread counts the SDK keeps current --
1204
+ * see `RoomList`. One per client; call `load()` once to fill it.
1205
+ */
1206
+ roomList(): RoomList;
1207
+ private list;
865
1208
  /**
866
1209
  * A handle on a room by id.
867
1210
  *
@@ -997,4 +1340,64 @@ declare function createChatClient(options: ChatClientOptions): ChatClient;
997
1340
  */
998
1341
  declare const ChatEndpoint = "wss://api.chat.gravex.app";
999
1342
 
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 };
1343
+ /**
1344
+ * @멘션을 `body.entities`로 싣고, 받은 것을 믿을 수 있는 조각으로 읽는 도우미.
1345
+ *
1346
+ * 엔진의 멘션은 글자가 아니라 entity다: `{type: 'mention', userId, offset, length}`
1347
+ * — `userId`는 앱의 외부 id, `offset`·`length`는 `body.text`의 JS(UTF-16) 인덱스이고
1348
+ * `@이름` 전체를 덮는다. 엔진은 `userId`만 풀어 `unreadMentions`·푸시에 쓰고
1349
+ * `offset`·`length`는 **검증하지 않는다**(docs/protocol.md `publish`). 그래서 보내는 쪽은
1350
+ * 최종 글에서 자리를 세어야 하고(`buildMentions`), 그리는 쪽은 받은 값을 검증해야 한다
1351
+ * (`mentionSpans`).
1352
+ */
1353
+ /** One mention as the engine stores it in `body.entities`. */
1354
+ type MentionEntity = {
1355
+ type: 'mention';
1356
+ userId: string;
1357
+ offset: number;
1358
+ length: number;
1359
+ };
1360
+ /** A mention that checked out against the text: `text.slice(start, end)` is `@name`. */
1361
+ type MentionSpan = {
1362
+ start: number;
1363
+ end: number;
1364
+ userId: string;
1365
+ };
1366
+ /**
1367
+ * Finds `@name` for each of `people` in the **final** text and returns the
1368
+ * entities to send with it.
1369
+ *
1370
+ * Count on the text being sent, not on what the input box remembered: a
1371
+ * mention typed and then edited away simply is not found, and the offsets
1372
+ * are right after any rewrite (a long text replaced by a preview, a trim).
1373
+ *
1374
+ * - `@` must start the text or follow a character that is not a letter,
1375
+ * digit, `_`, `.` or `@` -- `a@b.com` is not a mention.
1376
+ * - The name must end the text or be followed by a non-name character, so
1377
+ * `@Ann` does not match the start of `@Anna`; the longer name is tried
1378
+ * first.
1379
+ * - Inside markdown code -- a fenced block or an inline span in backticks --
1380
+ * nothing is a mention, unless `skipCode: false`.
1381
+ * - Two people with the same name are given out in the order they appear in
1382
+ * `people`, one per occurrence; past that the name is left alone (whose
1383
+ * it is cannot be known).
1384
+ * - At most 100, the engine's cap.
1385
+ */
1386
+ declare function buildMentions(text: string, people: readonly {
1387
+ id: string;
1388
+ name: string;
1389
+ }[], options?: {
1390
+ skipCode?: boolean;
1391
+ }): MentionEntity[];
1392
+ /**
1393
+ * The mentions in a received message that agree with its text, in order.
1394
+ *
1395
+ * Somebody else's client wrote these, and the engine does not check the
1396
+ * offsets, so each is kept only if it is a mention with a `userId`, its
1397
+ * range lies inside the text on one line and starts at an `@`, and it does
1398
+ * not overlap an earlier one. Anything else is dropped rather than drawn in
1399
+ * the wrong place.
1400
+ */
1401
+ declare function mentionSpans(text: string, entities: unknown): MentionSpan[];
1402
+
1403
+ 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 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 };