@kispi/chat 0.2.2 → 0.3.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
@@ -14,6 +14,19 @@ declare class Emitter<Events extends Record<string, unknown>> {
14
14
  clear(): void;
15
15
  }
16
16
 
17
+ /**
18
+ * 서버가 내는 코드와, SDK가 스스로 내는 둘.
19
+ *
20
+ * 유니온으로 적는 이유는 자동완성이 아니라 오타다. `err.code ===
21
+ * 'rate_limit'`은 영원히 거짓인 채로 통과하고, 그 분기가 비어 있다는
22
+ * 사실은 한도에 실제로 걸리는 날에야 드러난다. 목록은
23
+ * `docs/protocol.md`의 "에러 코드"가 정본이다.
24
+ */
25
+ type ChatErrorCode = 'unauthorized' | 'forbidden' | 'not_found' | 'invalid' | 'too_large' | 'rate_limited' | 'banned' | 'moderation_denied' | 'cursor_too_old' | 'internal'
26
+ /** SDK가 낸다: ack가 제 시간에 오지 않았다. */
27
+ | 'timeout'
28
+ /** SDK가 낸다: 연결이 없거나 닫혔다. */
29
+ | 'closed' | (string & {});
17
30
  /**
18
31
  * Every failure this SDK raises, with the server's own code on it.
19
32
  *
@@ -23,16 +36,23 @@ declare class Emitter<Events extends Record<string, unknown>> {
23
36
  * is free to reword.
24
37
  */
25
38
  declare class ChatError extends Error {
26
- readonly code: string;
39
+ readonly code: ChatErrorCode;
27
40
  /** Present on rate limits, in milliseconds. */
28
41
  readonly retryAfterMs?: number;
29
42
  /** The consumer's own code, when a before_publish hook denied this. */
30
43
  readonly appCode?: string;
31
- /** The HTTP status, when this came from a REST call. */
32
- status?: number;
33
- constructor(code: string, message: string, extra?: {
44
+ /**
45
+ * The HTTP status, when this came from a REST call.
46
+ *
47
+ * 읽기 전용이다. 이 값은 실패를 만든 응답의 성질이지 나중에 붙이는
48
+ * 꼬리표가 아니고, 쓸 수 있게 두면 소비자가 고쳐 쓴 상태가 SDK가
49
+ * 붙인 것과 구별되지 않는다.
50
+ */
51
+ readonly status?: number;
52
+ constructor(code: ChatErrorCode, message: string, extra?: {
34
53
  retryAfterMs?: number;
35
54
  appCode?: string;
55
+ status?: number;
36
56
  });
37
57
  }
38
58
 
@@ -54,10 +74,30 @@ type AuthUser = {
54
74
  name: string;
55
75
  avatar?: string;
56
76
  };
77
+ /**
78
+ * 안 읽은 수. `hello.unread`와 `chat.unread()`가 **같은 이름을 쓴다.**
79
+ *
80
+ * 와이어는 같은 두 숫자를 두 군데서 다르게 부르지만(hello는
81
+ * `total`/`mentions`, `/v1/me/unread`는 `unread`/`unreadMentions`),
82
+ * 배지를 그리는 쪽에게 그것은 같은 값이다. SDK가 한 이름으로 모은다.
83
+ */
84
+ type UnreadCounts = {
85
+ total: number;
86
+ mentions: number;
87
+ /** 총계가 일부만 센 값이다(방이 너무 많아 상한에서 잘렸다). */
88
+ roomsCapped?: boolean;
89
+ };
57
90
  type Hello = {
58
91
  connectionId: string;
59
92
  user: AuthUser;
60
- mode: 'token' | 'external';
93
+ /**
94
+ * 늘 `'token'`이다.
95
+ *
96
+ * 서버에는 external 모드의 검증 절반이 없어서 그 모드로 들어오는 접속을
97
+ * 무조건 거절한다. 그러니 `hello`가 다른 값을 실을 길이 없고, 유니온으로
98
+ * 두면 소비자가 영원히 도달하지 않는 분기를 쓴다.
99
+ */
100
+ mode: 'token';
61
101
  serverTime: number;
62
102
  heartbeatMs: number;
63
103
  limits: Record<string, number>;
@@ -66,13 +106,9 @@ type Hello = {
66
106
  *
67
107
  * The server drops this field when the count could not be read, and a
68
108
  * client that treats the absence as zero clears the badge of somebody
69
- * who has unread messages. `GET /me/unread` is the recovery.
109
+ * who has unread messages. `chat.unread()` is the recovery.
70
110
  */
71
- unread?: {
72
- total: number;
73
- mentions: number;
74
- roomsCapped?: boolean;
75
- };
111
+ unread?: UnreadCounts;
76
112
  warnings?: string[];
77
113
  };
78
114
  /** What `chat.on('state')` reports. */
@@ -92,7 +128,7 @@ type ConnectionState = 'connecting' | 'open' | 'reconnecting' | 'closed';
92
128
  * a token is to call it before `connect()` has fetched one.
93
129
  */
94
130
  type RestOptions = {
95
- /** `https://chat.example.com`. Derived from the socket url when absent. */
131
+ /** `https://api.chat.gravex.app`, derived from the socket url. */
96
132
  url: string;
97
133
  key: string;
98
134
  /** Returns the current user JWT, or undefined before the first connect. */
@@ -146,10 +182,15 @@ type Message = {
146
182
  * The emoji this client's user has on the message.
147
183
  *
148
184
  * Filled by history reads and kept in step by the SDK afterwards: a
149
- * `reaction.*` event whose `userId` is `chat.user.id`, and the ack of
150
- * this client's own `react()`/`unreact()`, update it. Absent on a row
151
- * the server rendered without a viewer (a live `message.created` has
152
- * none yet, which is the same as empty).
185
+ * `reaction.*` event whose `userId` is `chat.user.id` updates it, and
186
+ * this client's own `react()`/`unreact()` update it **before the frame
187
+ * goes out**, rolling back if the server refuses. Absent on a row the
188
+ * server rendered without a viewer (a live `message.created` has none
189
+ * yet, which is the same as empty).
190
+ *
191
+ * The SDK owns this field, so a consumer does not need -- and should
192
+ * not add -- an optimistic layer of its own on top of it. The count in
193
+ * `reactions` is the opposite: always the server's, never moved locally.
153
194
  */
154
195
  myReactions?: string[];
155
196
  thread?: {
@@ -190,6 +231,33 @@ type PublishAck = {
190
231
  seq: number;
191
232
  createdAt?: number;
192
233
  };
234
+ /** `presence` 이벤트가 말하는 사람. */
235
+ type PresenceUser = {
236
+ id: string;
237
+ name: string;
238
+ avatar?: string;
239
+ meta?: Record<string, unknown>;
240
+ };
241
+ /**
242
+ * 방의 presence.
243
+ *
244
+ * `joined`/`left`는 증분이고 `users`는 교체다 — 한 프레임에 같이 오지
245
+ * 않는다(`docs/protocol.md`). 100명이 넘는 방은 5초마다 `count`만 온다.
246
+ */
247
+ type PresenceEvent = {
248
+ count: number;
249
+ joined?: PresenceUser[];
250
+ left?: string[];
251
+ users?: PresenceUser[];
252
+ capped?: boolean;
253
+ };
254
+ /** `reaction.added`/`reaction.removed`. `count`는 누른 뒤의 서버 값이다. */
255
+ type ReactionEvent = {
256
+ messageId: string;
257
+ emoji: string;
258
+ count: number;
259
+ userId?: string;
260
+ };
193
261
  type RoomEvents = {
194
262
  /**
195
263
  * The room could not finish loading or catching up.
@@ -221,20 +289,51 @@ type RoomEvents = {
221
289
  * forever without ever being told.
222
290
  */
223
291
  reset: Message[];
224
- 'message.created': any;
225
- 'message.updated': any;
226
- 'message.deleted': any;
227
- 'reaction.added': any;
228
- 'reaction.removed': any;
229
- 'thread.updated': any;
230
- presence: any;
231
- typing: any;
232
- read: any;
233
- 'member.joined': any;
234
- 'member.left': any;
235
- 'room.updated': any;
236
- 'room.deleted': any;
237
- custom: any;
292
+ 'message.created': Message;
293
+ /** `message.created`와 달리 `reactions`와 `thread`가 실제 값이다. */
294
+ 'message.updated': Message;
295
+ /** `seq`는 그 메시지가 **발행될 때** 받은 값이다. tombstone은 seq를 쓰지 않는다. */
296
+ 'message.deleted': {
297
+ id: string;
298
+ seq: number;
299
+ };
300
+ 'reaction.added': ReactionEvent;
301
+ 'reaction.removed': ReactionEvent;
302
+ 'thread.updated': {
303
+ rootId: string;
304
+ count: number;
305
+ lastSeq?: number;
306
+ lastAt?: number;
307
+ };
308
+ presence: PresenceEvent;
309
+ /** **보낸 사람에게도 온다.** "X가 입력 중"을 그린다면 자기 id를 건너뛴다. */
310
+ typing: {
311
+ userId: string;
312
+ };
313
+ read: {
314
+ userId: string;
315
+ seq: number;
316
+ threadId?: string;
317
+ };
318
+ 'member.joined': {
319
+ userId: string;
320
+ role?: string;
321
+ };
322
+ 'member.left': {
323
+ userId: string;
324
+ role?: string;
325
+ };
326
+ /**
327
+ * 방 객체. 서버 REST의 방 표현 그대로라 `Message`처럼 SDK가 따로
328
+ * 적지 않는다 — 여기서 모양을 한 번 더 적으면 서버가 필드를 더할 때
329
+ * 그 필드가 타입에서만 사라진다.
330
+ */
331
+ 'room.updated': unknown;
332
+ 'room.deleted': {
333
+ roomId: string;
334
+ };
335
+ /** `rooms.custom(roomId, payload)`이 보낸 것 그대로. 서버는 해석하지 않는다. */
336
+ custom: Record<string, unknown>;
238
337
  /**
239
338
  * The room's message list changed, for any reason.
240
339
  *
@@ -249,11 +348,7 @@ declare class Room extends Emitter<RoomEvents> {
249
348
  readonly key: string | undefined;
250
349
  /** The last seq the server reported for this room. */
251
350
  lastSeq: number;
252
- presence: {
253
- count: number;
254
- users?: unknown[];
255
- capped?: boolean;
256
- } | undefined;
351
+ presence: PresenceEvent | undefined;
257
352
  private readonly chat;
258
353
  private readonly rest;
259
354
  private readonly timeline;
@@ -370,12 +465,31 @@ declare class Room extends Emitter<RoomEvents> {
370
465
  /**
371
466
  * Adds a reaction. Idempotent, like the frame.
372
467
  *
373
- * The ack updates the row's `myReactions` (not its count -- see below),
374
- * so the "I reacted" state is right even if the broadcast is missed.
468
+ * The row's `myReactions` moves **before the frame goes out** and rolls
469
+ * back if the server refuses; its count stays the server's. See
470
+ * `toggleReaction`.
375
471
  */
376
472
  react(messageId: string, emoji: string): Promise<void>;
377
- /** Removes a reaction. Idempotent; the ack clears it from `myReactions`. */
473
+ /** Removes a reaction. Idempotent, and optimistic the same way `react` is. */
378
474
  unreact(messageId: string, emoji: string): Promise<void>;
475
+ /**
476
+ * Moves `myReactions` now, sends the frame after.
477
+ *
478
+ * 누른 값은 (사용자, 이모지)로 로컬에서 정해지고 엔진은 멱등이므로 ack를
479
+ * 기다릴 이유가 없다 — 기다리면 누른 느낌이 왕복 시간만큼 늦는다. 소비자가
480
+ * 자기 낙관 계층을 덧대면 이 필드의 주인이 둘이 되므로, SDK가 한다.
481
+ * **발행은 다르다**: `before_publish` 훅이 본문을 바꿀 수 있어 미리 그릴 값이
482
+ * 로컬에 없다. 그래서 `send()`는 낙관적이지 않다.
483
+ *
484
+ * 개수는 옮기지 않는다. ack가 오기 전에 남이 같은 이모지를 누르면 로컬
485
+ * +1/-1은 서버가 보낸 수와 다른 값이 되고, 그것을 고칠 이벤트는 이미
486
+ * 지나갔다. 또 ack와 방 프레임은 다른 길로 와 순서가 없으므로, 늦게 온 내
487
+ * ack(count 1)가 앞서 온 남의 이벤트(count 2)를 되돌린다.
488
+ *
489
+ * 거절·타임아웃·끊김이면 되돌리지만, 그 사이 더 새로운 값이 자리를 차지했다면
490
+ * 두고 나온다(`Timeline.settleReaction`).
491
+ */
492
+ private toggleReaction;
379
493
  /**
380
494
  * Moves this user's read cursor.
381
495
  *
@@ -411,7 +525,7 @@ declare class Room extends Emitter<RoomEvents> {
411
525
  /** The full presence list, for rooms too large to send it in the ack. */
412
526
  presenceList(): Promise<{
413
527
  count: number;
414
- users?: unknown[];
528
+ users?: PresenceUser[];
415
529
  capped?: boolean;
416
530
  }>;
417
531
  /**
@@ -428,26 +542,6 @@ declare class Room extends Emitter<RoomEvents> {
428
542
  cursor?: string;
429
543
  limit?: number;
430
544
  }): Promise<ReactionsPage>;
431
- /**
432
- * Re-subscribes after a reconnect. Called by the client.
433
- *
434
- * The test is "was this room ever asked for", not "did the last
435
- * subscribe finish". A room whose catch-up failed is in exactly the
436
- * state that needs another try, and skipping it there is how a single
437
- * transient 500 takes a room out of the live feed for the life of the
438
- * page.
439
- */
440
- resume(restart?: boolean): Promise<void>;
441
- /**
442
- * Reports a failure no caller was waiting for, and repairs.
443
- *
444
- * 백그라운드 실패(재접속 뒤 다시 구독, 구멍 메우기)에는 거절을 받을 호출자가
445
- * 없다. 이벤트만 내고 두면 방은 다음 재접속이나 탭 복귀까지 구멍을 안고 —
446
- * 구독 프레임부터 실패했다면 라이브 피드 밖에서 — 머문다. 그래서 스스로 다시
447
- * 구독한다. 횟수를 묶는 것은 고칠 수 없는 실패(권한, 없어진 방)가 서버를
448
- * 계속 두드리지 않게 하려는 것이고, 그 뒤는 재접속과 `subscribe()`의 몫이다.
449
- */
450
- failed(err: unknown): void;
451
545
  /**
452
546
  * Sends `subscribe` and recovers from the one error it has an answer
453
547
  * for.
@@ -482,8 +576,6 @@ declare class Room extends Emitter<RoomEvents> {
482
576
  private resolveId;
483
577
  /** Publishes and resolves when the server acks. */
484
578
  send(input: SendInput, options?: SendOptions): Promise<PublishAck>;
485
- /** Routes a frame the client decided belongs to this room. */
486
- handle(type: keyof RoomEvents, data: any): void;
487
579
  /**
488
580
  * Replaces the timeline with the most recent page.
489
581
  *
@@ -512,15 +604,6 @@ type WebSocketLike = {
512
604
  };
513
605
  type WebSocketFactory = new (url: string) => WebSocketLike;
514
606
  type ChatClientOptions = {
515
- /** `wss://chat.example.com`. The `/v1/ws` path is added. */
516
- url: string;
517
- /**
518
- * Where REST lives, when it is not the same host over http(s).
519
- *
520
- * Derived from `url` by default, because a consumer configuring one
521
- * address and getting both is friendlier than asking twice.
522
- */
523
- restURL?: string;
524
607
  /** A `pk_` key. */
525
608
  key: string;
526
609
  /**
@@ -542,8 +625,6 @@ type ChatClientOptions = {
542
625
  * a `sk_` in a browser is the whole app.
543
626
  */
544
627
  token: () => string | Promise<string>;
545
- /** external mode. **The server refuses this today** -- the verification half is unbuilt. */
546
- externalToken?: () => string | Promise<string>;
547
628
  /** Defaults to the global. See WebSocketLike. */
548
629
  WebSocket?: WebSocketFactory;
549
630
  /** Defaults to the global. Used by REST calls and injectable for the same reasons. */
@@ -575,6 +656,8 @@ declare class ChatClient extends Emitter<ChatClientEvents> {
575
656
  connectionId: string | undefined;
576
657
  hello: Hello | undefined;
577
658
  private readonly options;
659
+ /** 소켓 주소. 상수이고, 테스트만 `endpoint`로 바꾼다. */
660
+ private readonly socketURL;
578
661
  private readonly makeSocket;
579
662
  private socket;
580
663
  private heartbeat;
@@ -650,24 +733,19 @@ declare class ChatClient extends Emitter<ChatClientEvents> {
650
733
  /**
651
734
  * The unread totals across every room this user is a member of.
652
735
  *
653
- * The field names are the route's own: `unread` and `unreadMentions`,
654
- * **not** the `total`/`mentions` that `hello.unread` uses for the same
655
- * two numbers. The server says it both ways and the SDK does not pick
656
- * a third; renaming here would mean a consumer reading the protocol
657
- * document finds a name that does not exist in either place.
736
+ * `{total, mentions}` — `chat.hello.unread`와 **같은 이름**이다. 와이어는
737
+ * 같은 두 숫자를 두 가지로 부르고(hello는 `total`/`mentions`, 이 라우트는
738
+ * `unread`/`unreadMentions`), 그것을 그대로 넘기면 배지 하나를 그리는
739
+ * 코드가 어디서 읽었느냐에 따라 다른 필드를 봐야 한다. 두 출처가 한 타입
740
+ * (`UnreadCounts`)이면 그 분기가 아예 없다.
658
741
  *
659
742
  * `roomsCapped` means the totals cover a subset -- this route does not
660
743
  * page, so past 500 rooms it stops counting and says so.
661
744
  */
662
- unread(): Promise<{
663
- unread: number;
664
- unreadMentions: number;
665
- roomsCapped?: boolean;
666
- rooms: {
745
+ unread(): Promise<UnreadCounts & {
746
+ rooms: (UnreadCounts & {
667
747
  roomId: string;
668
- unread: number;
669
- unreadMentions: number;
670
- }[];
748
+ })[];
671
749
  }>;
672
750
  /**
673
751
  * Updates this user's own profile.
@@ -693,22 +771,6 @@ declare class ChatClient extends Emitter<ChatClientEvents> {
693
771
  /** The same, addressed by the app's own key. Resolved on subscribe. */
694
772
  roomByKey(key: string): Room;
695
773
  private roomHandle;
696
- /**
697
- * Files a room under its id once `subscribe` has resolved one.
698
- *
699
- * A room addressed by key is filed under `key:<key>`, and every push
700
- * frame names a room by **id** -- so without this the handle is
701
- * unreachable from the read loop and a `roomByKey` room receives its
702
- * hundred messages of history and then nothing, forever. The events do
703
- * not vanish silently: they come out of `chat.on('frame')` as
704
- * unrouted, which is how this was found.
705
- *
706
- * Registering under both keys also makes `chat.room(id)` and
707
- * `chat.roomByKey(key)` return the **same** handle for the same room,
708
- * which is the property `roomHandle` exists for -- two lists of one
709
- * room drift the moment either fills a gap.
710
- */
711
- registerRoomId(roomId: string, room: Room): void;
712
774
  /** Opens the connection and resolves when `hello` arrives. */
713
775
  connect(): Promise<void>;
714
776
  /**
@@ -753,19 +815,8 @@ declare class ChatClient extends Emitter<ChatClientEvents> {
753
815
  * `error` event, because on a reconnect there is no caller to reject.
754
816
  */
755
817
  private stop;
756
- /**
757
- * Resolves once the connection is open. Used by `Room.subscribe`.
758
- *
759
- * 연결 전에 부른 `subscribe()`를 `closed`로 거절하면 소비자는 "언제 다시
760
- * 부를지"를 스스로 알아내야 하고, 첫 connect가 실패했다면 그 때는 영영 오지
761
- * 않는다. 붙을 때까지 기다리면 그 신호가 필요 없다. 멈춘 클라이언트(close,
762
- * 인증 거절)는 붙을 일이 없으니 거절한다.
763
- */
764
- whenOpen(): Promise<void>;
765
818
  private openWaiters;
766
819
  private settleOpenWaiters;
767
- /** Sends a frame and resolves with its ack, or rejects with its error. */
768
- send(type: string, data?: unknown, timeoutMs?: number): Promise<unknown>;
769
820
  /**
770
821
  * Frames waiting for an ack, by frame id.
771
822
  *
@@ -820,222 +871,15 @@ declare class ChatClient extends Emitter<ChatClientEvents> {
820
871
  declare function createChatClient(options: ChatClientOptions): ChatClient;
821
872
 
822
873
  /**
823
- * The message list, in `seq` order, with its holes filled.
824
- *
825
- * # Why this is a module and not part of Room
826
- *
827
- * Everything here is a state machine over frames: what to do when they
828
- * arrive out of order, when one is missing, when a fill lands after the
829
- * ground moved. **A real server cannot produce those inputs on demand**
830
- * -- within one connection it never reorders a room's events, its REST
831
- * answers in milliseconds so "while a fill is in flight" is not a window
832
- * you can aim at, and it has no way to be asked for a gap that is not
833
- * really there. So the tests inject frames, and that is only possible if
834
- * this thing has no socket in it.
835
- *
836
- * # What it guarantees
874
+ * 호스팅된 엔드포인트. 하나뿐이고, 소비자가 바꾸지 않는다.
837
875
  *
838
- * `messages` is sorted by `seq` and has no duplicates. Every hole the
839
- * timeline can see is either being fetched or has been fetched. A
840
- * tombstone keeps its slot, because `seq` is gap-free on the server and
841
- * a client that spliced a deleted message out would leave a hole its own
842
- * gap detection then chases forever.
876
+ * 주소가 옵션이던 동안 그것은 "우리가 운영하지 않는 엔진을 가리킬 수
877
+ * 있다"는 약속이었다. 이 서비스는 우리 호스팅 하나뿐이라 그런 엔진은
878
+ * 없고, 환경 분리는 콘솔에서 앱을 따로 만드는 일이지 SDK를 다른 주소로
879
+ * 돌리는 일이 아니다 — 스테이징 앱의 `pk_`는 운영 앱의 방을 못 본다.
880
+ * 옵션으로 남겨 두면 오타 하나가 "붙지 않는다"로만 보이고, 1.0에서
881
+ * 얼릴 표면에 우리가 지킬 수 없는 축이 하나 더 남는다.
843
882
  */
844
- /** Fetches `(after, before)` exclusive, ascending, at most `limit`. */
845
- type FetchRange = (range: {
846
- after: number;
847
- before: number;
848
- limit: number;
849
- }) => Promise<Message[]>;
850
- type TimelineOptions = {
851
- fetchRange: FetchRange;
852
- /** Called whenever the list changes. */
853
- onChange?: (messages: Message[]) => void;
854
- /** The server's page cap. Exposed so a test can make paging happen. */
855
- pageSize?: number;
856
- };
857
- declare class Timeline {
858
- private readonly options;
859
- private items;
860
- /**
861
- * Deletes for messages this client has not seen yet.
862
- *
863
- * A `message.deleted` can arrive for a seq inside a hole. If it were
864
- * dropped, the fill that follows would bring the row back **alive**,
865
- * because the history read reflects the delete only if it happened
866
- * before the read. The client would then show a message the server
867
- * considers gone, and nothing would ever correct it.
868
- */
869
- private readonly pendingDeletes;
870
- /** In-flight fills, keyed by the range they cover, to avoid duplicates. */
871
- private readonly fills;
872
- /**
873
- * Bumped by every reset.
874
- *
875
- * A fill started before a reset must not be applied after one: the
876
- * range it was asked for described a timeline that no longer exists.
877
- * Without this, a reconnect that lands mid-fill mixes the old room's
878
- * rows into the new list.
879
- */
880
- private epoch;
881
- /**
882
- * `items` has been handed out -- by the getter or by `onChange`.
883
- *
884
- * 한 번 내준 배열은 다시 건드리지 않는다. 같은 배열을 제자리에서 고쳐
885
- * 다시 내주면 Svelte `$state.raw`, React `useState`, Vue `shallowRef`처럼
886
- * 참조가 바뀌어야 다시 그리는 쪽은 변화를 보지 못하고 화면이 멈춘다. 그래서
887
- * 내준 뒤의 첫 변경은 복사본에서 한다(copy-on-write). 행 객체도 같은 규칙이라
888
- * 바뀐 행만 새 객체다.
889
- */
890
- private shared;
891
- /** The `loadOlder` in flight, so a scroll handler firing twice asks once. */
892
- private older;
893
- /**
894
- * The lowest seq the room still keeps (`minSeq` from the subscribe ack;
895
- * 1 until told). Below it there is nothing to read, whatever seq says.
896
- */
897
- private floor;
898
- /** A `loadOlder` came back short: the top of what the server keeps was reached. */
899
- private exhausted;
900
- constructor(options: TimelineOptions);
901
- /** A new array whenever the list changes; never mutated once returned. */
902
- get messages(): Message[];
903
- /**
904
- * Whether `loadOlder()` would find anything, answered without asking.
905
- *
906
- * `loadOlder()`의 `hasMore`와 같은 판정이다: 맨 위 행이 방의 보존 하한
907
- * (`minSeq`, seq는 1부터 구멍 없이 붙는다)보다 위에 있고, 앞선 `loadOlder`가
908
- * 덜 찬 페이지로 끝을 알린 적이 없으면 더 있다. 첫 `loadOlder()` 전에 "이전
909
- * 메시지 더 보기"를 그릴지 정할 수 있게 한다. 목록이 비었으면 false다.
910
- */
911
- get hasOlder(): boolean;
912
- /** Records the room's retention floor (`minSeq`). */
913
- setFloor(minSeq: number): void;
914
- /** The highest seq this timeline holds, hole or no hole. */
915
- get highestSeq(): number;
916
- /**
917
- * The highest seq with nothing missing below it.
918
- *
919
- * This is the number a resubscribe must send as `since`, and it is not
920
- * `highestSeq`. Holding 5,6,7,8,9,14 with 10..13 missing, the top of
921
- * the list is 14 and the top of what this client actually has is 9.
922
- * Sending 14 tells the server "I have everything up to 14", the
923
- * catch-up computes that there is nothing to fetch, and the hole
924
- * becomes permanent -- which is exactly the failure the whole gap
925
- * machinery exists to prevent, arriving through the number that
926
- * describes it.
927
- *
928
- * A hole below the first row held is not visible here and not this
929
- * client's business: history begins where the last load began.
930
- */
931
- get contiguousSeq(): number;
932
- /**
933
- * Forgets everything, including the pending deletes.
934
- *
935
- * Used when the server says the cursor is too old: what this timeline
936
- * holds is no longer connected to what the room holds, so carrying any
937
- * of it forward would leave a hole that nothing fills.
938
- */
939
- discard(): void;
940
- /**
941
- * Replaces the window with a recent page. Used by the initial load and
942
- * by recovery.
943
- *
944
- * Rows already held **above** the page's top survive it. A recent page
945
- * is the last N messages as of the moment the server read them, which
946
- * makes it evidence about the range it covers and no evidence at all
947
- * about anything newer. Live frames that arrived while the page was in
948
- * flight are exactly that -- newer -- and dropping them would open a
949
- * hole above the page that nothing goes looking for, because a hole is
950
- * only detected on the next arrival.
951
- *
952
- * That race is not exotic: the README points consumers at `reload()`
953
- * for the moment after a reconnect, which is the moment the missed
954
- * frames are arriving.
955
- *
956
- * A caller that wants the list genuinely emptied has `discard()`.
957
- */
958
- reset(messages: Message[]): void;
959
- /**
960
- * Takes one live message, in order or not, and fills what it reveals.
961
- *
962
- * Returns the fill promise so a caller can await settling; nothing in
963
- * the SDK does, because a consumer's UI should show what arrived and
964
- * let the rest land when it lands.
965
- */
966
- add(message: Message): Promise<void>;
967
- /**
968
- * Applies a `message.updated`.
969
- *
970
- * A row that is already a tombstone stays one. The edit and the delete
971
- * can arrive in either order -- reordering is the input this module
972
- * exists for -- and applying a late edit to a deleted row puts its body
973
- * back on screen under a `deletedAt` that says it is gone. From the
974
- * person who deleted it, that is a delete that did not work.
975
- */
976
- update(message: Message): void;
977
- /**
978
- * Applies a `reaction.added` or `reaction.removed` to the aggregate the
979
- * message carries.
980
- *
981
- * `Message.reactions` is filled by the history read and a consumer
982
- * renders from it, so leaving it alone would give them a count that is
983
- * correct at load and frozen after -- inside a live session, with the
984
- * event that should have changed it arriving on another channel.
985
- *
986
- * The server sends the new `count` with the event, so this is a
987
- * replacement rather than an increment: two clients reacting at once
988
- * cannot drift the way `+1`/`-1` would. `count` undefined leaves the
989
- * aggregate alone (the react ack path); `mine` undefined leaves
990
- * `myReactions` alone (somebody else's event).
991
- */
992
- reaction(messageId: string, emoji: string, count: number | undefined, mine?: boolean): void;
993
- /** Applies a `thread.updated` to the root message's aggregate. */
994
- thread(rootId: string, count: number, lastSeq?: number): void;
995
- /** Applies a `message.deleted`, remembering it if the row is not here. */
996
- remove(id: string): void;
997
- /**
998
- * Prepends the page just below the oldest message held.
999
- *
1000
- * 스크롤을 올려 과거를 읽는 소비자가 `history()` 결과를 라이브 목록과 따로
1001
- * 들고 합치고, 중복을 걸러 내고, reset과 재접속을 따로 처리해야 했다. 같은
1002
- * 목록에 끼워 넣으면 그 일이 전부 이미 있는 규칙(seq 자리에 넣기, 같은 seq는
1003
- * 한 행, reset이면 epoch로 버리기)으로 끝난다.
1004
- *
1005
- * `hasMore`는 더 올라갈 것이 있는지다. 서버의 seq는 1부터 구멍 없이 붙으므로
1006
- * 맨 위가 1이거나 페이지가 덜 찼으면 끝이다(보존 기간이 지운 앞부분도 덜 찬
1007
- * 페이지로 드러난다). 한 번에 하나만 돈다 — 스크롤 핸들러가 두 번 불러도
1008
- * 요청은 하나다(진행 중인 호출과 같은 결과를 받으므로 뒤 호출의 `limit`은 쓰이지 않는다).
1009
- */
1010
- loadOlder(limit?: number): Promise<{
1011
- messages: Message[];
1012
- hasMore: boolean;
1013
- }>;
1014
- private readOlder;
1015
- /**
1016
- * Fetches everything between what we have and `upTo`.
1017
- *
1018
- * Used after a reconnect, where the ack's `lastSeq` says how far the
1019
- * room got while we were away.
1020
- */
1021
- catchUp(upTo: number): Promise<void>;
1022
- /**
1023
- * Walks a range, page by page, and inserts what comes back.
1024
- *
1025
- * The loop is the point. `GET .../messages` caps `limit` at 100, so a
1026
- * client that was away while a busy room moved 250 messages gets a
1027
- * third of its gap from one call -- and a single-call implementation
1028
- * would believe the hole was filled. That failure is silent: the list
1029
- * looks continuous because the missing rows were never known about.
1030
- */
1031
- private fill;
1032
- /** Inserts at the seq position, replacing an existing row with that seq. */
1033
- private insert;
1034
- private applyDelete;
1035
- /** Makes `items` safe to mutate: a copy, if the current one was handed out. */
1036
- private own;
1037
- private changed;
1038
- }
1039
- declare function createTimeline(options: TimelineOptions): Timeline;
883
+ declare const ChatEndpoint = "wss://api.chat.gravex.app";
1040
884
 
1041
- export { type AuthUser, ChatClient, type ChatClientEvents, type ChatClientOptions, ChatError, type ConnectionState, type FetchRange, type Frame, type Hello, type Message, type PublishAck, type ReactionUser, type ReactionsPage, Room, type RoomEvents, type SendInput, type SendOptions, Timeline, type TimelineOptions, type WebSocketFactory, type WebSocketLike, createChatClient, createTimeline };
885
+ 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 };