@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/README.en.md +74 -48
- package/README.md +70 -47
- package/dist/{chunk-5QQRM7BH.js → chunk-WSBOTTBM.js} +21 -3
- package/dist/index.cjs +183 -46
- package/dist/index.d.cts +172 -328
- package/dist/index.d.ts +172 -328
- package/dist/index.js +166 -42
- 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. */
|
|
@@ -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
|
|
150
|
-
* this client's own `react()`/`unreact()
|
|
151
|
-
* the server
|
|
152
|
-
*
|
|
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':
|
|
225
|
-
|
|
226
|
-
'message.
|
|
227
|
-
|
|
228
|
-
'
|
|
229
|
-
|
|
230
|
-
|
|
231
|
-
|
|
232
|
-
|
|
233
|
-
'
|
|
234
|
-
'
|
|
235
|
-
|
|
236
|
-
|
|
237
|
-
|
|
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
|
|
374
|
-
*
|
|
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
|
|
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?:
|
|
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
|
-
*
|
|
654
|
-
*
|
|
655
|
-
*
|
|
656
|
-
*
|
|
657
|
-
*
|
|
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
|
-
|
|
664
|
-
unreadMentions: number;
|
|
665
|
-
roomsCapped?: boolean;
|
|
666
|
-
rooms: {
|
|
745
|
+
unread(): Promise<UnreadCounts & {
|
|
746
|
+
rooms: (UnreadCounts & {
|
|
667
747
|
roomId: string;
|
|
668
|
-
|
|
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
|
-
*
|
|
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
|
-
*
|
|
839
|
-
*
|
|
840
|
-
*
|
|
841
|
-
*
|
|
842
|
-
*
|
|
876
|
+
* 주소가 옵션이던 동안 그것은 "우리가 운영하지 않는 엔진을 가리킬 수
|
|
877
|
+
* 있다"는 약속이었다. 이 서비스는 우리 호스팅 하나뿐이라 그런 엔진은
|
|
878
|
+
* 없고, 환경 분리는 콘솔에서 앱을 따로 만드는 일이지 SDK를 다른 주소로
|
|
879
|
+
* 돌리는 일이 아니다 — 스테이징 앱의 `pk_`는 운영 앱의 방을 못 본다.
|
|
880
|
+
* 옵션으로 남겨 두면 오타 하나가 "붙지 않는다"로만 보이고, 1.0에서
|
|
881
|
+
* 얼릴 표면에 우리가 지킬 수 없는 축이 하나 더 남는다.
|
|
843
882
|
*/
|
|
844
|
-
|
|
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
|
|
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 };
|