@kispi/chat 0.2.3 → 0.3.1

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. */
@@ -195,6 +231,33 @@ type PublishAck = {
195
231
  seq: number;
196
232
  createdAt?: number;
197
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
+ };
198
261
  type RoomEvents = {
199
262
  /**
200
263
  * The room could not finish loading or catching up.
@@ -226,20 +289,51 @@ type RoomEvents = {
226
289
  * forever without ever being told.
227
290
  */
228
291
  reset: Message[];
229
- 'message.created': any;
230
- 'message.updated': any;
231
- 'message.deleted': any;
232
- 'reaction.added': any;
233
- 'reaction.removed': any;
234
- 'thread.updated': any;
235
- presence: any;
236
- typing: any;
237
- read: any;
238
- 'member.joined': any;
239
- 'member.left': any;
240
- 'room.updated': any;
241
- 'room.deleted': any;
242
- 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>;
243
337
  /**
244
338
  * The room's message list changed, for any reason.
245
339
  *
@@ -254,11 +348,7 @@ declare class Room extends Emitter<RoomEvents> {
254
348
  readonly key: string | undefined;
255
349
  /** The last seq the server reported for this room. */
256
350
  lastSeq: number;
257
- presence: {
258
- count: number;
259
- users?: unknown[];
260
- capped?: boolean;
261
- } | undefined;
351
+ presence: PresenceEvent | undefined;
262
352
  private readonly chat;
263
353
  private readonly rest;
264
354
  private readonly timeline;
@@ -435,7 +525,7 @@ declare class Room extends Emitter<RoomEvents> {
435
525
  /** The full presence list, for rooms too large to send it in the ack. */
436
526
  presenceList(): Promise<{
437
527
  count: number;
438
- users?: unknown[];
528
+ users?: PresenceUser[];
439
529
  capped?: boolean;
440
530
  }>;
441
531
  /**
@@ -452,26 +542,6 @@ declare class Room extends Emitter<RoomEvents> {
452
542
  cursor?: string;
453
543
  limit?: number;
454
544
  }): Promise<ReactionsPage>;
455
- /**
456
- * Re-subscribes after a reconnect. Called by the client.
457
- *
458
- * The test is "was this room ever asked for", not "did the last
459
- * subscribe finish". A room whose catch-up failed is in exactly the
460
- * state that needs another try, and skipping it there is how a single
461
- * transient 500 takes a room out of the live feed for the life of the
462
- * page.
463
- */
464
- resume(restart?: boolean): Promise<void>;
465
- /**
466
- * Reports a failure no caller was waiting for, and repairs.
467
- *
468
- * 백그라운드 실패(재접속 뒤 다시 구독, 구멍 메우기)에는 거절을 받을 호출자가
469
- * 없다. 이벤트만 내고 두면 방은 다음 재접속이나 탭 복귀까지 구멍을 안고 —
470
- * 구독 프레임부터 실패했다면 라이브 피드 밖에서 — 머문다. 그래서 스스로 다시
471
- * 구독한다. 횟수를 묶는 것은 고칠 수 없는 실패(권한, 없어진 방)가 서버를
472
- * 계속 두드리지 않게 하려는 것이고, 그 뒤는 재접속과 `subscribe()`의 몫이다.
473
- */
474
- failed(err: unknown): void;
475
545
  /**
476
546
  * Sends `subscribe` and recovers from the one error it has an answer
477
547
  * for.
@@ -506,8 +576,6 @@ declare class Room extends Emitter<RoomEvents> {
506
576
  private resolveId;
507
577
  /** Publishes and resolves when the server acks. */
508
578
  send(input: SendInput, options?: SendOptions): Promise<PublishAck>;
509
- /** Routes a frame the client decided belongs to this room. */
510
- handle(type: keyof RoomEvents, data: any): void;
511
579
  /**
512
580
  * Replaces the timeline with the most recent page.
513
581
  *
@@ -536,15 +604,6 @@ type WebSocketLike = {
536
604
  };
537
605
  type WebSocketFactory = new (url: string) => WebSocketLike;
538
606
  type ChatClientOptions = {
539
- /** `wss://chat.example.com`. The `/v1/ws` path is added. */
540
- url: string;
541
- /**
542
- * Where REST lives, when it is not the same host over http(s).
543
- *
544
- * Derived from `url` by default, because a consumer configuring one
545
- * address and getting both is friendlier than asking twice.
546
- */
547
- restURL?: string;
548
607
  /** A `pk_` key. */
549
608
  key: string;
550
609
  /**
@@ -566,8 +625,6 @@ type ChatClientOptions = {
566
625
  * a `sk_` in a browser is the whole app.
567
626
  */
568
627
  token: () => string | Promise<string>;
569
- /** external mode. **The server refuses this today** -- the verification half is unbuilt. */
570
- externalToken?: () => string | Promise<string>;
571
628
  /** Defaults to the global. See WebSocketLike. */
572
629
  WebSocket?: WebSocketFactory;
573
630
  /** Defaults to the global. Used by REST calls and injectable for the same reasons. */
@@ -599,6 +656,8 @@ declare class ChatClient extends Emitter<ChatClientEvents> {
599
656
  connectionId: string | undefined;
600
657
  hello: Hello | undefined;
601
658
  private readonly options;
659
+ /** 소켓 주소. 상수이고, 테스트만 `endpoint`로 바꾼다. */
660
+ private readonly socketURL;
602
661
  private readonly makeSocket;
603
662
  private socket;
604
663
  private heartbeat;
@@ -674,24 +733,19 @@ declare class ChatClient extends Emitter<ChatClientEvents> {
674
733
  /**
675
734
  * The unread totals across every room this user is a member of.
676
735
  *
677
- * The field names are the route's own: `unread` and `unreadMentions`,
678
- * **not** the `total`/`mentions` that `hello.unread` uses for the same
679
- * two numbers. The server says it both ways and the SDK does not pick
680
- * a third; renaming here would mean a consumer reading the protocol
681
- * 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`)이면 그 분기가 아예 없다.
682
741
  *
683
742
  * `roomsCapped` means the totals cover a subset -- this route does not
684
743
  * page, so past 500 rooms it stops counting and says so.
685
744
  */
686
- unread(): Promise<{
687
- unread: number;
688
- unreadMentions: number;
689
- roomsCapped?: boolean;
690
- rooms: {
745
+ unread(): Promise<UnreadCounts & {
746
+ rooms: (UnreadCounts & {
691
747
  roomId: string;
692
- unread: number;
693
- unreadMentions: number;
694
- }[];
748
+ })[];
695
749
  }>;
696
750
  /**
697
751
  * Updates this user's own profile.
@@ -717,22 +771,6 @@ declare class ChatClient extends Emitter<ChatClientEvents> {
717
771
  /** The same, addressed by the app's own key. Resolved on subscribe. */
718
772
  roomByKey(key: string): Room;
719
773
  private roomHandle;
720
- /**
721
- * Files a room under its id once `subscribe` has resolved one.
722
- *
723
- * A room addressed by key is filed under `key:<key>`, and every push
724
- * frame names a room by **id** -- so without this the handle is
725
- * unreachable from the read loop and a `roomByKey` room receives its
726
- * hundred messages of history and then nothing, forever. The events do
727
- * not vanish silently: they come out of `chat.on('frame')` as
728
- * unrouted, which is how this was found.
729
- *
730
- * Registering under both keys also makes `chat.room(id)` and
731
- * `chat.roomByKey(key)` return the **same** handle for the same room,
732
- * which is the property `roomHandle` exists for -- two lists of one
733
- * room drift the moment either fills a gap.
734
- */
735
- registerRoomId(roomId: string, room: Room): void;
736
774
  /** Opens the connection and resolves when `hello` arrives. */
737
775
  connect(): Promise<void>;
738
776
  /**
@@ -777,19 +815,8 @@ declare class ChatClient extends Emitter<ChatClientEvents> {
777
815
  * `error` event, because on a reconnect there is no caller to reject.
778
816
  */
779
817
  private stop;
780
- /**
781
- * Resolves once the connection is open. Used by `Room.subscribe`.
782
- *
783
- * 연결 전에 부른 `subscribe()`를 `closed`로 거절하면 소비자는 "언제 다시
784
- * 부를지"를 스스로 알아내야 하고, 첫 connect가 실패했다면 그 때는 영영 오지
785
- * 않는다. 붙을 때까지 기다리면 그 신호가 필요 없다. 멈춘 클라이언트(close,
786
- * 인증 거절)는 붙을 일이 없으니 거절한다.
787
- */
788
- whenOpen(): Promise<void>;
789
818
  private openWaiters;
790
819
  private settleOpenWaiters;
791
- /** Sends a frame and resolves with its ack, or rejects with its error. */
792
- send(type: string, data?: unknown, timeoutMs?: number): Promise<unknown>;
793
820
  /**
794
821
  * Frames waiting for an ack, by frame id.
795
822
  *
@@ -844,289 +871,15 @@ declare class ChatClient extends Emitter<ChatClientEvents> {
844
871
  declare function createChatClient(options: ChatClientOptions): ChatClient;
845
872
 
846
873
  /**
847
- * The message list, in `seq` order, with its holes filled.
848
- *
849
- * # Why this is a module and not part of Room
874
+ * 호스팅된 엔드포인트. 하나뿐이고, 소비자가 바꾸지 않는다.
850
875
  *
851
- * Everything here is a state machine over frames: what to do when they
852
- * arrive out of order, when one is missing, when a fill lands after the
853
- * ground moved. **A real server cannot produce those inputs on demand**
854
- * -- within one connection it never reorders a room's events, its REST
855
- * answers in milliseconds so "while a fill is in flight" is not a window
856
- * you can aim at, and it has no way to be asked for a gap that is not
857
- * really there. So the tests inject frames, and that is only possible if
858
- * this thing has no socket in it.
859
- *
860
- * # What it guarantees
861
- *
862
- * `messages` is sorted by `seq` and has no duplicates. Every hole the
863
- * timeline can see is either being fetched or has been fetched. A
864
- * tombstone keeps its slot, because `seq` is gap-free on the server and
865
- * a client that spliced a deleted message out would leave a hole its own
866
- * gap detection then chases forever.
867
- */
868
- /** Fetches `(after, before)` exclusive, ascending, at most `limit`. */
869
- type FetchRange = (range: {
870
- after: number;
871
- before: number;
872
- limit: number;
873
- }) => Promise<Message[]>;
874
- /**
875
- * A press of this client's own that the server has not answered yet.
876
- *
877
- * Carries its own sequence number, which is the whole point: by the time
878
- * an answer comes back the (message, emoji) pair may belong to a newer
879
- * press, and settling this one then would put a value nobody is showing
880
- * any more back on screen.
876
+ * 주소가 옵션이던 동안 그것은 "우리가 운영하지 않는 엔진을 가리킬 수
877
+ * 있다"는 약속이었다. 이 서비스는 우리 호스팅 하나뿐이라 그런 엔진은
878
+ * 없고, 환경 분리는 콘솔에서 앱을 따로 만드는 일이지 SDK를 다른 주소로
879
+ * 돌리는 일이 아니다 — 스테이징 앱의 `pk_`는 운영 앱의 방을 못 본다.
880
+ * 옵션으로 남겨 두면 오타 하나가 "붙지 않는다"로만 보이고, 1.0에서
881
+ * 얼릴 표면에 우리가 지킬 수 없는 축이 하나 더 남는다.
881
882
  */
882
- type PendingReaction = {
883
- messageId: string;
884
- emoji: string;
885
- /** What the press asked for: in `myReactions`, or out of it. */
886
- mine: boolean;
887
- seq: number;
888
- };
889
- type TimelineOptions = {
890
- fetchRange: FetchRange;
891
- /** Called whenever the list changes. */
892
- onChange?: (messages: Message[]) => void;
893
- /** The server's page cap. Exposed so a test can make paging happen. */
894
- pageSize?: number;
895
- };
896
- declare class Timeline {
897
- private readonly options;
898
- private items;
899
- /**
900
- * Deletes for messages this client has not seen yet.
901
- *
902
- * A `message.deleted` can arrive for a seq inside a hole. If it were
903
- * dropped, the fill that follows would bring the row back **alive**,
904
- * because the history read reflects the delete only if it happened
905
- * before the read. The client would then show a message the server
906
- * considers gone, and nothing would ever correct it.
907
- */
908
- private readonly pendingDeletes;
909
- /** In-flight fills, keyed by the range they cover, to avoid duplicates. */
910
- private readonly fills;
911
- /**
912
- * Bumped by every reset.
913
- *
914
- * A fill started before a reset must not be applied after one: the
915
- * range it was asked for described a timeline that no longer exists.
916
- * Without this, a reconnect that lands mid-fill mixes the old room's
917
- * rows into the new list.
918
- */
919
- private epoch;
920
- /**
921
- * `items` has been handed out -- by the getter or by `onChange`.
922
- *
923
- * 한 번 내준 배열은 다시 건드리지 않는다. 같은 배열을 제자리에서 고쳐
924
- * 다시 내주면 Svelte `$state.raw`, React `useState`, Vue `shallowRef`처럼
925
- * 참조가 바뀌어야 다시 그리는 쪽은 변화를 보지 못하고 화면이 멈춘다. 그래서
926
- * 내준 뒤의 첫 변경은 복사본에서 한다(copy-on-write). 행 객체도 같은 규칙이라
927
- * 바뀐 행만 새 객체다.
928
- */
929
- private shared;
930
- /** The `loadOlder` in flight, so a scroll handler firing twice asks once. */
931
- private older;
932
- /**
933
- * The lowest seq the room still keeps (`minSeq` from the subscribe ack;
934
- * 1 until told). Below it there is nothing to read, whatever seq says.
935
- */
936
- private floor;
937
- /** A `loadOlder` came back short: the top of what the server keeps was reached. */
938
- private exhausted;
939
- /**
940
- * Presses this client has made and the server has not answered yet, one
941
- * entry per (message, emoji) pair, each remembering the last value the
942
- * **server** gave for that pair.
943
- *
944
- * 되돌릴 자리로 "누르기 직전 화면값"을 쓰면 안 된다. 눌렀다 곧바로 취소하고
945
- * 두 거절이 차례로 오면, 두 번째 거절이 첫 번째의 낙관값 — 서버가 한 번도
946
- * 가진 적 없는 값 — 을 화면에 되살린다. 마지막으로 서버가 말한 값만이
947
- * 되돌릴 자리다.
948
- */
949
- private readonly presses;
950
- private pressSeq;
951
- constructor(options: TimelineOptions);
952
- /** A new array whenever the list changes; never mutated once returned. */
953
- get messages(): Message[];
954
- /**
955
- * Whether `loadOlder()` would find anything, answered without asking.
956
- *
957
- * `loadOlder()`의 `hasMore`와 같은 판정이다: 맨 위 행이 방의 보존 하한
958
- * (`minSeq`, seq는 1부터 구멍 없이 붙는다)보다 위에 있고, 앞선 `loadOlder`가
959
- * 덜 찬 페이지로 끝을 알린 적이 없으면 더 있다. 첫 `loadOlder()` 전에 "이전
960
- * 메시지 더 보기"를 그릴지 정할 수 있게 한다. 목록이 비었으면 false다.
961
- */
962
- get hasOlder(): boolean;
963
- /** Records the room's retention floor (`minSeq`). */
964
- setFloor(minSeq: number): void;
965
- /** The highest seq this timeline holds, hole or no hole. */
966
- get highestSeq(): number;
967
- /**
968
- * The highest seq with nothing missing below it.
969
- *
970
- * This is the number a resubscribe must send as `since`, and it is not
971
- * `highestSeq`. Holding 5,6,7,8,9,14 with 10..13 missing, the top of
972
- * the list is 14 and the top of what this client actually has is 9.
973
- * Sending 14 tells the server "I have everything up to 14", the
974
- * catch-up computes that there is nothing to fetch, and the hole
975
- * becomes permanent -- which is exactly the failure the whole gap
976
- * machinery exists to prevent, arriving through the number that
977
- * describes it.
978
- *
979
- * A hole below the first row held is not visible here and not this
980
- * client's business: history begins where the last load began.
981
- */
982
- get contiguousSeq(): number;
983
- /**
984
- * Forgets everything, including the pending deletes.
985
- *
986
- * Used when the server says the cursor is too old: what this timeline
987
- * holds is no longer connected to what the room holds, so carrying any
988
- * of it forward would leave a hole that nothing fills.
989
- */
990
- discard(): void;
991
- /**
992
- * Replaces the window with a recent page. Used by the initial load and
993
- * by recovery.
994
- *
995
- * Rows already held **above** the page's top survive it. A recent page
996
- * is the last N messages as of the moment the server read them, which
997
- * makes it evidence about the range it covers and no evidence at all
998
- * about anything newer. Live frames that arrived while the page was in
999
- * flight are exactly that -- newer -- and dropping them would open a
1000
- * hole above the page that nothing goes looking for, because a hole is
1001
- * only detected on the next arrival.
1002
- *
1003
- * That race is not exotic: the README points consumers at `reload()`
1004
- * for the moment after a reconnect, which is the moment the missed
1005
- * frames are arriving.
1006
- *
1007
- * A caller that wants the list genuinely emptied has `discard()`.
1008
- */
1009
- reset(messages: Message[]): void;
1010
- /**
1011
- * Takes one live message, in order or not, and fills what it reveals.
1012
- *
1013
- * Returns the fill promise so a caller can await settling; nothing in
1014
- * the SDK does, because a consumer's UI should show what arrived and
1015
- * let the rest land when it lands.
1016
- */
1017
- add(message: Message): Promise<void>;
1018
- /**
1019
- * Applies a `message.updated`.
1020
- *
1021
- * A row that is already a tombstone stays one. The edit and the delete
1022
- * can arrive in either order -- reordering is the input this module
1023
- * exists for -- and applying a late edit to a deleted row puts its body
1024
- * back on screen under a `deletedAt` that says it is gone. From the
1025
- * person who deleted it, that is a delete that did not work.
1026
- */
1027
- update(message: Message): void;
1028
- /**
1029
- * Applies a `reaction.added` or `reaction.removed` to the aggregate the
1030
- * message carries.
1031
- *
1032
- * `Message.reactions` is filled by the history read and a consumer
1033
- * renders from it, so leaving it alone would give them a count that is
1034
- * correct at load and frozen after -- inside a live session, with the
1035
- * event that should have changed it arriving on another channel.
1036
- *
1037
- * The server sends the new `count` with the event, so this is a
1038
- * replacement rather than an increment: two clients reacting at once
1039
- * cannot drift the way `+1`/`-1` would. `count` undefined leaves the
1040
- * aggregate alone (the react ack path); `mine` undefined leaves
1041
- * `myReactions` alone (somebody else's event).
1042
- *
1043
- * This is the **authoritative** entry point: a value the server sent.
1044
- * So a press still waiting on an answer for the same pair is finished
1045
- * here -- a refusal landing afterwards must not push this value back
1046
- * to the older one it was going to restore.
1047
- */
1048
- reaction(messageId: string, emoji: string, count: number | undefined, mine?: boolean): void;
1049
- /**
1050
- * Applies this client's own react/unreact to `myReactions` **before the
1051
- * frame goes out**, and returns the press so its answer can settle it.
1052
- *
1053
- * 누른 값은 (사용자, 이모지)로 로컬에서 정해지고 엔진은 멱등이므로, 미리
1054
- * 적용해도 ack가 새로 알려 줄 것이 없다. `count`는 일부러 건드리지 않는다 —
1055
- * 그 사이 남이 같은 이모지를 누르면 로컬 +1/-1은 서버가 보낼 수와 다르고,
1056
- * 그 차이를 고칠 이벤트는 이미 지나갔다.
1057
- *
1058
- * Undefined when the row is not held: there is nothing to show now and
1059
- * nothing to put back later.
1060
- */
1061
- pressReaction(messageId: string, emoji: string, mine: boolean): PendingReaction | undefined;
1062
- /**
1063
- * Settles a press with what the server said.
1064
- *
1065
- * `accepted` re-asserts the value the press asked for; a refusal puts
1066
- * the last server-given value back. Either way it does nothing once
1067
- * this press no longer owns the pair -- a newer press took it over
1068
- * (and that one's answer decides), or something authoritative already
1069
- * landed on it (a `reaction.*` event carrying this user's id, a
1070
- * `reload()`, a reconnect's catch-up page). Reverting there would
1071
- * resurrect a value older than what is on screen.
1072
- */
1073
- settleReaction(press: PendingReaction, accepted: boolean): void;
1074
- private applyReaction;
1075
- /** Applies a `thread.updated` to the root message's aggregate. */
1076
- thread(rootId: string, count: number, lastSeq?: number): void;
1077
- /** Applies a `message.deleted`, remembering it if the row is not here. */
1078
- remove(id: string): void;
1079
- /**
1080
- * Prepends the page just below the oldest message held.
1081
- *
1082
- * 스크롤을 올려 과거를 읽는 소비자가 `history()` 결과를 라이브 목록과 따로
1083
- * 들고 합치고, 중복을 걸러 내고, reset과 재접속을 따로 처리해야 했다. 같은
1084
- * 목록에 끼워 넣으면 그 일이 전부 이미 있는 규칙(seq 자리에 넣기, 같은 seq는
1085
- * 한 행, reset이면 epoch로 버리기)으로 끝난다.
1086
- *
1087
- * `hasMore`는 더 올라갈 것이 있는지다. 서버의 seq는 1부터 구멍 없이 붙으므로
1088
- * 맨 위가 1이거나 페이지가 덜 찼으면 끝이다(보존 기간이 지운 앞부분도 덜 찬
1089
- * 페이지로 드러난다). 한 번에 하나만 돈다 — 스크롤 핸들러가 두 번 불러도
1090
- * 요청은 하나다(진행 중인 호출과 같은 결과를 받으므로 뒤 호출의 `limit`은 쓰이지 않는다).
1091
- */
1092
- loadOlder(limit?: number): Promise<{
1093
- messages: Message[];
1094
- hasMore: boolean;
1095
- }>;
1096
- private readOlder;
1097
- /**
1098
- * Fetches everything between what we have and `upTo`.
1099
- *
1100
- * Used after a reconnect, where the ack's `lastSeq` says how far the
1101
- * room got while we were away.
1102
- */
1103
- catchUp(upTo: number): Promise<void>;
1104
- /**
1105
- * Walks a range, page by page, and inserts what comes back.
1106
- *
1107
- * The loop is the point. `GET .../messages` caps `limit` at 100, so a
1108
- * client that was away while a busy room moved 250 messages gets a
1109
- * third of its gap from one call -- and a single-call implementation
1110
- * would believe the hole was filled. That failure is silent: the list
1111
- * looks continuous because the missing rows were never known about.
1112
- */
1113
- private fill;
1114
- /** Inserts at the seq position, replacing an existing row with that seq. */
1115
- private insert;
1116
- private applyDelete;
1117
- /**
1118
- * Forgets the presses on a row the server has just re-rendered.
1119
- *
1120
- * 히스토리 응답의 행은 뷰어별 `myReactions`를 싣고 오므로 그 값이 서버의
1121
- * 값이다. 누름을 남겨 두면 그 뒤에 온 거절이 더 새로운 진실 위에 옛 값을
1122
- * 덮어쓴다. 행 전체 단위인 것은 페이지가 그 행의 이모지 전부를 다시 그려
1123
- * 주기 때문이다.
1124
- */
1125
- private serverRendered;
1126
- /** Makes `items` safe to mutate: a copy, if the current one was handed out. */
1127
- private own;
1128
- private changed;
1129
- }
1130
- declare function createTimeline(options: TimelineOptions): Timeline;
883
+ declare const ChatEndpoint = "wss://api.chat.gravex.app";
1131
884
 
1132
- export { type AuthUser, ChatClient, type ChatClientEvents, type ChatClientOptions, ChatError, type ConnectionState, type FetchRange, type Frame, type Hello, type Message, type PendingReaction, 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 };