@kispi/chat 0.2.3 → 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/README.en.md +46 -46
- package/README.md +43 -45
- package/dist/{chunk-5QQRM7BH.js → chunk-WSBOTTBM.js} +21 -3
- package/dist/index.cjs +63 -40
- package/dist/index.d.cts +141 -388
- package/dist/index.d.ts +141 -388
- package/dist/index.js +46 -36
- package/dist/server/index.cjs +37 -9
- package/dist/server/index.d.cts +20 -14
- package/dist/server/index.d.ts +20 -14
- package/dist/server/index.js +22 -8
- package/package.json +1 -1
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:
|
|
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
|
-
/**
|
|
32
|
-
|
|
33
|
-
|
|
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
|
-
|
|
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. `
|
|
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.
|
|
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':
|
|
230
|
-
|
|
231
|
-
'message.
|
|
232
|
-
|
|
233
|
-
'
|
|
234
|
-
|
|
235
|
-
|
|
236
|
-
|
|
237
|
-
|
|
238
|
-
'
|
|
239
|
-
'
|
|
240
|
-
|
|
241
|
-
|
|
242
|
-
|
|
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?:
|
|
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
|
-
*
|
|
678
|
-
*
|
|
679
|
-
*
|
|
680
|
-
*
|
|
681
|
-
*
|
|
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
|
-
|
|
688
|
-
unreadMentions: number;
|
|
689
|
-
roomsCapped?: boolean;
|
|
690
|
-
rooms: {
|
|
745
|
+
unread(): Promise<UnreadCounts & {
|
|
746
|
+
rooms: (UnreadCounts & {
|
|
691
747
|
roomId: string;
|
|
692
|
-
|
|
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
|
-
*
|
|
848
|
-
*
|
|
849
|
-
* # Why this is a module and not part of Room
|
|
874
|
+
* 호스팅된 엔드포인트. 하나뿐이고, 소비자가 바꾸지 않는다.
|
|
850
875
|
*
|
|
851
|
-
*
|
|
852
|
-
*
|
|
853
|
-
*
|
|
854
|
-
*
|
|
855
|
-
*
|
|
856
|
-
*
|
|
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
|
-
|
|
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
|
|
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 };
|