@kispi/chat 0.1.2 → 0.2.1

package/dist/index.d.cts

@@ -14,6 +14,28 @@ declare class Emitter<Events extends Record<string, unknown>> {
     clear(): void;
 }
 
+/**
+ * Every failure this SDK raises, with the server's own code on it.
+ *
+ * The code matters more than the message. A consumer branches on
+ * `rate_limited` versus `moderation_denied` versus `unauthorized`, and a
+ * bare `Error` carrying prose forces them to match on strings the server
+ * is free to reword.
+ */
+declare class ChatError extends Error {
+    readonly code: string;
+    /** Present on rate limits, in milliseconds. */
+    readonly retryAfterMs?: number;
+    /** The consumer's own code, when a before_publish hook denied this. */
+    readonly appCode?: string;
+    /** The HTTP status, when this came from a REST call. */
+    status?: number;
+    constructor(code: string, message: string, extra?: {
+        retryAfterMs?: number;
+        appCode?: string;
+    });
+}
+
 /**
  * The wire shapes this SDK reads and writes.
  *
@@ -75,6 +97,11 @@ type RestOptions = {
     key: string;
     /** Returns the current user JWT, or undefined before the first connect. */
     token: () => Promise<string | undefined>;
+    /**
+     * Fetches a fresh token after a 401, or undefined when there is none to
+     * fetch. Optional so a Rest built without it behaves as before.
+     */
+    refreshToken?: () => Promise<string | undefined>;
     fetch: typeof globalThis.fetch;
 };
 declare class Rest {
@@ -86,6 +113,7 @@ declare class Rest {
     put<T>(path: string, body?: unknown): Promise<T>;
     delete<T>(path: string): Promise<T>;
     private call;
+    private callWith;
 }
 
 /** A message as the server renders it. */
@@ -160,11 +188,11 @@ type RoomEvents = {
      * socket's read loop where there is no caller to throw to -- and
      * swallowing it is what leaves a hole nothing ever fills.
      *
-     * The retry to offer is **`room.subscribe()`**. A room that emitted
-     * this is left not-subscribed on purpose, precisely so that call does
-     * something: it re-subscribes and reloads. Marking it subscribed and
-     * telling the consumer to retry would be advice that returns
-     * immediately having done nothing, which is worse than no advice.
+     * The room repairs itself: it re-subscribes with backoff (1 s doubling,
+     * up to five tries while connected), and every reconnect tries again.
+     * `room.subscribe()` is still the retry to offer a person pressing a
+     * button -- a room that emitted this is left not-subscribed on purpose,
+     * precisely so that call does something.
      */
     error: Error;
     /**
@@ -197,7 +225,12 @@ type RoomEvents = {
     'room.updated': any;
     'room.deleted': any;
     custom: any;
-    /** The room's message list changed, for any reason. */
+    /**
+     * The room's message list changed, for any reason.
+     *
+     * **A new array every time**, and one that is never mutated after it is
+     * emitted, so it can go straight into state that compares by reference.
+     */
     messages: Message[];
 };
 declare class Room extends Emitter<RoomEvents> {
@@ -241,12 +274,34 @@ declare class Room extends Emitter<RoomEvents> {
      */
     private wanted;
     private subscribing;
+    /** Self-repair: the armed retry, and how many have run since the last success. */
+    private repairTimer;
+    private repairs;
     constructor(chat: ChatClient, rest: Rest, address: {
         id?: string;
         key?: string;
     });
-    /** Everything this client knows about the room, in seq order. */
+    /** Everything this client knows about the room, in seq order. A new array whenever it changes. */
     get messages(): Message[];
+    /**
+     * Reads the page just before the oldest message held and **prepends it to
+     * `messages`**.
+     *
+     * The scroll-back call. Unlike `history()`, the rows join the room's own
+     * list, so ordering, de-duplication, deletes, reactions and reconnects
+     * apply to them like any other row, and the `messages` event fires once.
+     * A `reset` (or `reload()`) drops them with everything else; a read that
+     * lands after one is discarded rather than stitched onto the new list.
+     *
+     * `hasMore` is false once the top of the room -- or of its retention --
+     * is reached. Concurrent calls share one request.
+     */
+    loadOlder(options?: {
+        limit?: number;
+    }): Promise<{
+        messages: Message[];
+        hasMore: boolean;
+    }>;
     /**
      * Reloads recent history, discarding what is held.
      *
@@ -277,7 +332,8 @@ declare class Room extends Emitter<RoomEvents> {
      *
      * The list this room keeps is the live one; this is for a consumer
      * scrolling back, which owns its own window and does not want the
-     * bottom of the room rearranged under it.
+     * bottom of the room rearranged under it. **Scrolling the room's own
+     * list back is `loadOlder()`**, which keeps one list instead of two.
      *
      * `view` defaults to the server's, which is every message including
      * thread replies. **`view: 'main'` is a display filter, not a sync
@@ -356,7 +412,17 @@ declare class Room extends Emitter<RoomEvents> {
      * transient 500 takes a room out of the live feed for the life of the
      * page.
      */
-    resume(): Promise<void>;
+    resume(restart?: boolean): Promise<void>;
+    /**
+     * Reports a failure no caller was waiting for, and repairs.
+     *
+     * 백그라운드 실패(재접속 뒤 다시 구독, 구멍 메우기)에는 거절을 받을 호출자가
+     * 없다. 이벤트만 내고 두면 방은 다음 재접속이나 탭 복귀까지 구멍을 안고 —
+     * 구독 프레임부터 실패했다면 라이브 피드 밖에서 — 머문다. 그래서 스스로 다시
+     * 구독한다. 횟수를 묶는 것은 고칠 수 없는 실패(권한, 없어진 방)가 서버를
+     * 계속 두드리지 않게 하려는 것이고, 그 뒤는 재접속과 `subscribe()`의 몫이다.
+     */
+    failed(err: unknown): void;
     /**
      * Sends `subscribe` and recovers from the one error it has an answer
      * for.
@@ -379,6 +445,16 @@ declare class Room extends Emitter<RoomEvents> {
      * mistake.
      */
     private requireId;
+    /**
+     * The room's id, waiting for a subscribe in flight to learn it.
+     *
+     * `roomByKey(k).subscribe()`를 await하지 않고 곧바로 `send`하는 것은 자연스러운
+     * 코드이고, 그때 id는 구독 ack가 와야 생긴다. 거절(`closed`)하면 소비자는
+     * "보내도 되는 때"를 알릴 신호를 따로 찾아야 한다 — 이미 날아가고 있는
+     * 구독을 기다리면 그 신호가 필요 없다. 구독이 실패하면 그 실패가 그대로
+     * 나간다. 구독한 적이 없으면 기다릴 것이 없으니 예전처럼 거절한다.
+     */
+    private resolveId;
     /** Publishes and resolves when the server acks. */
     send(input: SendInput, options?: SendOptions): Promise<PublishAck>;
     /** Routes a frame the client decided belongs to this room. */
@@ -430,9 +506,15 @@ type ChatClientOptions = {
      * has no way to decide who anybody is on its own, and the modes that
      * pretended otherwise were removed.
      *
-     * Called again on every connect, so an expired token is replaced
-     * rather than reused. **Never sign these in the browser** -- signing
-     * needs the `sk_`, and a `sk_` in a browser is the whole app.
+     * Called again on every connect, and again when a REST call is
+     * answered 401 (the call is then retried once), so an expired token is
+     * replaced rather than reused. A throw here is retried with backoff
+     * like a dropped socket -- **unless it throws a `ChatError`**, which
+     * means "do not retry" (a ban, a session that ended): the client goes
+     * to `closed` and emits it as `error`.
+     *
+     * **Never sign these in the browser** -- signing needs the `sk_`, and
+     * a `sk_` in a browser is the whole app.
      */
     token: () => string | Promise<string>;
     /** external mode. **The server refuses this today** -- the verification half is unbuilt. */
@@ -452,6 +534,15 @@ type ChatClientEvents = {
      * SDK learns about it.
      */
     frame: Frame;
+    /**
+     * 클라이언트가 스스로 `closed`로 멈췄고, 이게 그 이유다.
+     *
+     * 멈추는 길은 셋이다: `close()`, 서버의 인증 거절, `token()`이 던진
+     * `ChatError`. 첫 connect라면 거절로도 알 수 있지만 재접속 중이나 REST의
+     * 토큰 갱신 중에는 받을 호출자가 없어서, 이것 없이는 `state`가 `closed`로
+     * 바뀌는 것만 보이고 왜인지는 사라진다. `close()`로 닫을 때는 내지 않는다.
+     */
+    error: ChatError;
 };
 declare class ChatClient extends Emitter<ChatClientEvents> {
     state: ConnectionState;
@@ -464,8 +555,11 @@ declare class ChatClient extends Emitter<ChatClientEvents> {
     private heartbeat;
     private retryTimer;
     private attempt;
-    /** Set by close(), and the only thing that stops the reconnect loop. */
-    private closedByCaller;
+    /**
+     * The reconnect loop is off: set by close(), and by a failure that
+     * retrying cannot fix (see `stop`). Cleared by connect().
+     */
+    private stopped;
     private nextFrameId;
     private opening;
     private readonly rest;
@@ -596,10 +690,30 @@ declare class ChatClient extends Emitter<ChatClientEvents> {
      * Closes for good.
      *
      * The distinction from a dropped socket is the whole point of the state
-     * machine: this is the only path that reaches `closed`, and a consumer
-     * showing "disconnected, retrying" versus "disconnected" needs it.
+     * machine: `closed` means nothing is coming back, and a consumer showing
+     * "disconnected, retrying" versus "disconnected" needs it. The other
+     * ways to reach it are refusals retrying cannot fix -- see `stop`.
      */
     close(): Promise<void>;
+    /**
+     * Stops for a reason retrying cannot fix, and says which.
+     *
+     * `close()` without the teardown of the page listeners -- a consumer
+     * that logs back in calls `connect()` on the same client -- and with an
+     * `error` event, because on a reconnect there is no caller to reject.
+     */
+    private stop;
+    /**
+     * Resolves once the connection is open. Used by `Room.subscribe`.
+     *
+     * 연결 전에 부른 `subscribe()`를 `closed`로 거절하면 소비자는 "언제 다시
+     * 부를지"를 스스로 알아내야 하고, 첫 connect가 실패했다면 그 때는 영영 오지
+     * 않는다. 붙을 때까지 기다리면 그 신호가 필요 없다. 멈춘 클라이언트(close,
+     * 인증 거절)는 붙을 일이 없으니 거절한다.
+     */
+    whenOpen(): Promise<void>;
+    private openWaiters;
+    private settleOpenWaiters;
     /** Sends a frame and resolves with its ack, or rejects with its error. */
     send(type: string, data?: unknown, timeoutMs?: number): Promise<unknown>;
     /**
@@ -639,32 +753,22 @@ declare class ChatClient extends Emitter<ChatClientEvents> {
      */
     private nextDelay;
     private authData;
+    /**
+     * REST가 401을 받았을 때 토큰을 새로 받는다.
+     *
+     * 소켓은 접속할 때 한 번 인증하고 그 뒤로는 토큰을 다시 보지 않지만, REST는
+     * 요청마다 본다. 그래서 한 시간짜리 토큰이면 한 시간 뒤 라이브는 멀쩡한데
+     * 히스토리·구멍 메우기만 401이 된다. 동시에 실패한 요청들이 `token()`을
+     * 각자 부르지 않도록 진행 중인 것 하나를 나눠 쓴다.
+     */
+    private refreshToken;
+    private refreshing;
     private failPending;
     private clearHeartbeat;
     private clearTimers;
 }
 declare function createChatClient(options: ChatClientOptions): ChatClient;
 
-/**
- * Every failure this SDK raises, with the server's own code on it.
- *
- * The code matters more than the message. A consumer branches on
- * `rate_limited` versus `moderation_denied` versus `unauthorized`, and a
- * bare `Error` carrying prose forces them to match on strings the server
- * is free to reword.
- */
-declare class ChatError extends Error {
-    readonly code: string;
-    /** Present on rate limits, in milliseconds. */
-    readonly retryAfterMs?: number;
-    /** The consumer's own code, when a before_publish hook denied this. */
-    readonly appCode?: string;
-    constructor(code: string, message: string, extra?: {
-        retryAfterMs?: number;
-        appCode?: string;
-    });
-}
-
 /**
  * The message list, in `seq` order, with its holes filled.
  *
@@ -724,7 +828,20 @@ declare class Timeline {
      * rows into the new list.
      */
     private epoch;
+    /**
+     * `items` has been handed out -- by the getter or by `onChange`.
+     *
+     * 한 번 내준 배열은 다시 건드리지 않는다. 같은 배열을 제자리에서 고쳐
+     * 다시 내주면 Svelte `$state.raw`, React `useState`, Vue `shallowRef`처럼
+     * 참조가 바뀌어야 다시 그리는 쪽은 변화를 보지 못하고 화면이 멈춘다. 그래서
+     * 내준 뒤의 첫 변경은 복사본에서 한다(copy-on-write). 행 객체도 같은 규칙이라
+     * 바뀐 행만 새 객체다.
+     */
+    private shared;
+    /** The `loadOlder` in flight, so a scroll handler firing twice asks once. */
+    private older;
     constructor(options: TimelineOptions);
+    /** A new array whenever the list changes; never mutated once returned. */
     get messages(): Message[];
     /** The highest seq this timeline holds, hole or no hole. */
     get highestSeq(): number;
@@ -807,6 +924,24 @@ declare class Timeline {
     thread(rootId: string, count: number, lastSeq?: number): void;
     /** Applies a `message.deleted`, remembering it if the row is not here. */
     remove(id: string): void;
+    /**
+     * Prepends the page just below the oldest message held.
+     *
+     * 스크롤을 올려 과거를 읽는 소비자가 `history()` 결과를 라이브 목록과 따로
+     * 들고 합치고, 중복을 걸러 내고, reset과 재접속을 따로 처리해야 했다. 같은
+     * 목록에 끼워 넣으면 그 일이 전부 이미 있는 규칙(seq 자리에 넣기, 같은 seq는
+     * 한 행, reset이면 epoch로 버리기)으로 끝난다.
+     *
+     * `hasMore`는 더 올라갈 것이 있는지다. 서버의 seq는 1부터 구멍 없이 붙으므로
+     * 맨 위가 1이거나 페이지가 덜 찼으면 끝이다(보존 기간이 지운 앞부분도 덜 찬
+     * 페이지로 드러난다). 한 번에 하나만 돈다 — 스크롤 핸들러가 두 번 불러도
+     * 요청은 하나다(진행 중인 호출과 같은 결과를 받으므로 뒤 호출의 `limit`은 쓰이지 않는다).
+     */
+    loadOlder(limit?: number): Promise<{
+        messages: Message[];
+        hasMore: boolean;
+    }>;
+    private readOlder;
     /**
      * Fetches everything between what we have and `upTo`.
      *
@@ -827,6 +962,8 @@ declare class Timeline {
     /** Inserts at the seq position, replacing an existing row with that seq. */
     private insert;
     private applyDelete;
+    /** Makes `items` safe to mutate: a copy, if the current one was handed out. */
+    private own;
     private changed;
 }
 declare function createTimeline(options: TimelineOptions): Timeline;

package/dist/index.d.ts

@@ -14,6 +14,28 @@ declare class Emitter<Events extends Record<string, unknown>> {
     clear(): void;
 }
 
+/**
+ * Every failure this SDK raises, with the server's own code on it.
+ *
+ * The code matters more than the message. A consumer branches on
+ * `rate_limited` versus `moderation_denied` versus `unauthorized`, and a
+ * bare `Error` carrying prose forces them to match on strings the server
+ * is free to reword.
+ */
+declare class ChatError extends Error {
+    readonly code: string;
+    /** Present on rate limits, in milliseconds. */
+    readonly retryAfterMs?: number;
+    /** The consumer's own code, when a before_publish hook denied this. */
+    readonly appCode?: string;
+    /** The HTTP status, when this came from a REST call. */
+    status?: number;
+    constructor(code: string, message: string, extra?: {
+        retryAfterMs?: number;
+        appCode?: string;
+    });
+}
+
 /**
  * The wire shapes this SDK reads and writes.
  *
@@ -75,6 +97,11 @@ type RestOptions = {
     key: string;
     /** Returns the current user JWT, or undefined before the first connect. */
     token: () => Promise<string | undefined>;
+    /**
+     * Fetches a fresh token after a 401, or undefined when there is none to
+     * fetch. Optional so a Rest built without it behaves as before.
+     */
+    refreshToken?: () => Promise<string | undefined>;
     fetch: typeof globalThis.fetch;
 };
 declare class Rest {
@@ -86,6 +113,7 @@ declare class Rest {
     put<T>(path: string, body?: unknown): Promise<T>;
     delete<T>(path: string): Promise<T>;
     private call;
+    private callWith;
 }
 
 /** A message as the server renders it. */
@@ -160,11 +188,11 @@ type RoomEvents = {
      * socket's read loop where there is no caller to throw to -- and
      * swallowing it is what leaves a hole nothing ever fills.
      *
-     * The retry to offer is **`room.subscribe()`**. A room that emitted
-     * this is left not-subscribed on purpose, precisely so that call does
-     * something: it re-subscribes and reloads. Marking it subscribed and
-     * telling the consumer to retry would be advice that returns
-     * immediately having done nothing, which is worse than no advice.
+     * The room repairs itself: it re-subscribes with backoff (1 s doubling,
+     * up to five tries while connected), and every reconnect tries again.
+     * `room.subscribe()` is still the retry to offer a person pressing a
+     * button -- a room that emitted this is left not-subscribed on purpose,
+     * precisely so that call does something.
      */
     error: Error;
     /**
@@ -197,7 +225,12 @@ type RoomEvents = {
     'room.updated': any;
     'room.deleted': any;
     custom: any;
-    /** The room's message list changed, for any reason. */
+    /**
+     * The room's message list changed, for any reason.
+     *
+     * **A new array every time**, and one that is never mutated after it is
+     * emitted, so it can go straight into state that compares by reference.
+     */
     messages: Message[];
 };
 declare class Room extends Emitter<RoomEvents> {
@@ -241,12 +274,34 @@ declare class Room extends Emitter<RoomEvents> {
      */
     private wanted;
     private subscribing;
+    /** Self-repair: the armed retry, and how many have run since the last success. */
+    private repairTimer;
+    private repairs;
     constructor(chat: ChatClient, rest: Rest, address: {
         id?: string;
         key?: string;
     });
-    /** Everything this client knows about the room, in seq order. */
+    /** Everything this client knows about the room, in seq order. A new array whenever it changes. */
     get messages(): Message[];
+    /**
+     * Reads the page just before the oldest message held and **prepends it to
+     * `messages`**.
+     *
+     * The scroll-back call. Unlike `history()`, the rows join the room's own
+     * list, so ordering, de-duplication, deletes, reactions and reconnects
+     * apply to them like any other row, and the `messages` event fires once.
+     * A `reset` (or `reload()`) drops them with everything else; a read that
+     * lands after one is discarded rather than stitched onto the new list.
+     *
+     * `hasMore` is false once the top of the room -- or of its retention --
+     * is reached. Concurrent calls share one request.
+     */
+    loadOlder(options?: {
+        limit?: number;
+    }): Promise<{
+        messages: Message[];
+        hasMore: boolean;
+    }>;
     /**
      * Reloads recent history, discarding what is held.
      *
@@ -277,7 +332,8 @@ declare class Room extends Emitter<RoomEvents> {
      *
      * The list this room keeps is the live one; this is for a consumer
      * scrolling back, which owns its own window and does not want the
-     * bottom of the room rearranged under it.
+     * bottom of the room rearranged under it. **Scrolling the room's own
+     * list back is `loadOlder()`**, which keeps one list instead of two.
      *
      * `view` defaults to the server's, which is every message including
      * thread replies. **`view: 'main'` is a display filter, not a sync
@@ -356,7 +412,17 @@ declare class Room extends Emitter<RoomEvents> {
      * transient 500 takes a room out of the live feed for the life of the
      * page.
      */
-    resume(): Promise<void>;
+    resume(restart?: boolean): Promise<void>;
+    /**
+     * Reports a failure no caller was waiting for, and repairs.
+     *
+     * 백그라운드 실패(재접속 뒤 다시 구독, 구멍 메우기)에는 거절을 받을 호출자가
+     * 없다. 이벤트만 내고 두면 방은 다음 재접속이나 탭 복귀까지 구멍을 안고 —
+     * 구독 프레임부터 실패했다면 라이브 피드 밖에서 — 머문다. 그래서 스스로 다시
+     * 구독한다. 횟수를 묶는 것은 고칠 수 없는 실패(권한, 없어진 방)가 서버를
+     * 계속 두드리지 않게 하려는 것이고, 그 뒤는 재접속과 `subscribe()`의 몫이다.
+     */
+    failed(err: unknown): void;
     /**
      * Sends `subscribe` and recovers from the one error it has an answer
      * for.
@@ -379,6 +445,16 @@ declare class Room extends Emitter<RoomEvents> {
      * mistake.
      */
     private requireId;
+    /**
+     * The room's id, waiting for a subscribe in flight to learn it.
+     *
+     * `roomByKey(k).subscribe()`를 await하지 않고 곧바로 `send`하는 것은 자연스러운
+     * 코드이고, 그때 id는 구독 ack가 와야 생긴다. 거절(`closed`)하면 소비자는
+     * "보내도 되는 때"를 알릴 신호를 따로 찾아야 한다 — 이미 날아가고 있는
+     * 구독을 기다리면 그 신호가 필요 없다. 구독이 실패하면 그 실패가 그대로
+     * 나간다. 구독한 적이 없으면 기다릴 것이 없으니 예전처럼 거절한다.
+     */
+    private resolveId;
     /** Publishes and resolves when the server acks. */
     send(input: SendInput, options?: SendOptions): Promise<PublishAck>;
     /** Routes a frame the client decided belongs to this room. */
@@ -430,9 +506,15 @@ type ChatClientOptions = {
      * has no way to decide who anybody is on its own, and the modes that
      * pretended otherwise were removed.
      *
-     * Called again on every connect, so an expired token is replaced
-     * rather than reused. **Never sign these in the browser** -- signing
-     * needs the `sk_`, and a `sk_` in a browser is the whole app.
+     * Called again on every connect, and again when a REST call is
+     * answered 401 (the call is then retried once), so an expired token is
+     * replaced rather than reused. A throw here is retried with backoff
+     * like a dropped socket -- **unless it throws a `ChatError`**, which
+     * means "do not retry" (a ban, a session that ended): the client goes
+     * to `closed` and emits it as `error`.
+     *
+     * **Never sign these in the browser** -- signing needs the `sk_`, and
+     * a `sk_` in a browser is the whole app.
      */
     token: () => string | Promise<string>;
     /** external mode. **The server refuses this today** -- the verification half is unbuilt. */
@@ -452,6 +534,15 @@ type ChatClientEvents = {
      * SDK learns about it.
      */
     frame: Frame;
+    /**
+     * 클라이언트가 스스로 `closed`로 멈췄고, 이게 그 이유다.
+     *
+     * 멈추는 길은 셋이다: `close()`, 서버의 인증 거절, `token()`이 던진
+     * `ChatError`. 첫 connect라면 거절로도 알 수 있지만 재접속 중이나 REST의
+     * 토큰 갱신 중에는 받을 호출자가 없어서, 이것 없이는 `state`가 `closed`로
+     * 바뀌는 것만 보이고 왜인지는 사라진다. `close()`로 닫을 때는 내지 않는다.
+     */
+    error: ChatError;
 };
 declare class ChatClient extends Emitter<ChatClientEvents> {
     state: ConnectionState;
@@ -464,8 +555,11 @@ declare class ChatClient extends Emitter<ChatClientEvents> {
     private heartbeat;
     private retryTimer;
     private attempt;
-    /** Set by close(), and the only thing that stops the reconnect loop. */
-    private closedByCaller;
+    /**
+     * The reconnect loop is off: set by close(), and by a failure that
+     * retrying cannot fix (see `stop`). Cleared by connect().
+     */
+    private stopped;
     private nextFrameId;
     private opening;
     private readonly rest;
@@ -596,10 +690,30 @@ declare class ChatClient extends Emitter<ChatClientEvents> {
      * Closes for good.
      *
      * The distinction from a dropped socket is the whole point of the state
-     * machine: this is the only path that reaches `closed`, and a consumer
-     * showing "disconnected, retrying" versus "disconnected" needs it.
+     * machine: `closed` means nothing is coming back, and a consumer showing
+     * "disconnected, retrying" versus "disconnected" needs it. The other
+     * ways to reach it are refusals retrying cannot fix -- see `stop`.
      */
     close(): Promise<void>;
+    /**
+     * Stops for a reason retrying cannot fix, and says which.
+     *
+     * `close()` without the teardown of the page listeners -- a consumer
+     * that logs back in calls `connect()` on the same client -- and with an
+     * `error` event, because on a reconnect there is no caller to reject.
+     */
+    private stop;
+    /**
+     * Resolves once the connection is open. Used by `Room.subscribe`.
+     *
+     * 연결 전에 부른 `subscribe()`를 `closed`로 거절하면 소비자는 "언제 다시
+     * 부를지"를 스스로 알아내야 하고, 첫 connect가 실패했다면 그 때는 영영 오지
+     * 않는다. 붙을 때까지 기다리면 그 신호가 필요 없다. 멈춘 클라이언트(close,
+     * 인증 거절)는 붙을 일이 없으니 거절한다.
+     */
+    whenOpen(): Promise<void>;
+    private openWaiters;
+    private settleOpenWaiters;
     /** Sends a frame and resolves with its ack, or rejects with its error. */
     send(type: string, data?: unknown, timeoutMs?: number): Promise<unknown>;
     /**
@@ -639,32 +753,22 @@ declare class ChatClient extends Emitter<ChatClientEvents> {
      */
     private nextDelay;
     private authData;
+    /**
+     * REST가 401을 받았을 때 토큰을 새로 받는다.
+     *
+     * 소켓은 접속할 때 한 번 인증하고 그 뒤로는 토큰을 다시 보지 않지만, REST는
+     * 요청마다 본다. 그래서 한 시간짜리 토큰이면 한 시간 뒤 라이브는 멀쩡한데
+     * 히스토리·구멍 메우기만 401이 된다. 동시에 실패한 요청들이 `token()`을
+     * 각자 부르지 않도록 진행 중인 것 하나를 나눠 쓴다.
+     */
+    private refreshToken;
+    private refreshing;
     private failPending;
     private clearHeartbeat;
     private clearTimers;
 }
 declare function createChatClient(options: ChatClientOptions): ChatClient;
 
-/**
- * Every failure this SDK raises, with the server's own code on it.
- *
- * The code matters more than the message. A consumer branches on
- * `rate_limited` versus `moderation_denied` versus `unauthorized`, and a
- * bare `Error` carrying prose forces them to match on strings the server
- * is free to reword.
- */
-declare class ChatError extends Error {
-    readonly code: string;
-    /** Present on rate limits, in milliseconds. */
-    readonly retryAfterMs?: number;
-    /** The consumer's own code, when a before_publish hook denied this. */
-    readonly appCode?: string;
-    constructor(code: string, message: string, extra?: {
-        retryAfterMs?: number;
-        appCode?: string;
-    });
-}
-
 /**
  * The message list, in `seq` order, with its holes filled.
  *
@@ -724,7 +828,20 @@ declare class Timeline {
      * rows into the new list.
      */
     private epoch;
+    /**
+     * `items` has been handed out -- by the getter or by `onChange`.
+     *
+     * 한 번 내준 배열은 다시 건드리지 않는다. 같은 배열을 제자리에서 고쳐
+     * 다시 내주면 Svelte `$state.raw`, React `useState`, Vue `shallowRef`처럼
+     * 참조가 바뀌어야 다시 그리는 쪽은 변화를 보지 못하고 화면이 멈춘다. 그래서
+     * 내준 뒤의 첫 변경은 복사본에서 한다(copy-on-write). 행 객체도 같은 규칙이라
+     * 바뀐 행만 새 객체다.
+     */
+    private shared;
+    /** The `loadOlder` in flight, so a scroll handler firing twice asks once. */
+    private older;
     constructor(options: TimelineOptions);
+    /** A new array whenever the list changes; never mutated once returned. */
     get messages(): Message[];
     /** The highest seq this timeline holds, hole or no hole. */
     get highestSeq(): number;
@@ -807,6 +924,24 @@ declare class Timeline {
     thread(rootId: string, count: number, lastSeq?: number): void;
     /** Applies a `message.deleted`, remembering it if the row is not here. */
     remove(id: string): void;
+    /**
+     * Prepends the page just below the oldest message held.
+     *
+     * 스크롤을 올려 과거를 읽는 소비자가 `history()` 결과를 라이브 목록과 따로
+     * 들고 합치고, 중복을 걸러 내고, reset과 재접속을 따로 처리해야 했다. 같은
+     * 목록에 끼워 넣으면 그 일이 전부 이미 있는 규칙(seq 자리에 넣기, 같은 seq는
+     * 한 행, reset이면 epoch로 버리기)으로 끝난다.
+     *
+     * `hasMore`는 더 올라갈 것이 있는지다. 서버의 seq는 1부터 구멍 없이 붙으므로
+     * 맨 위가 1이거나 페이지가 덜 찼으면 끝이다(보존 기간이 지운 앞부분도 덜 찬
+     * 페이지로 드러난다). 한 번에 하나만 돈다 — 스크롤 핸들러가 두 번 불러도
+     * 요청은 하나다(진행 중인 호출과 같은 결과를 받으므로 뒤 호출의 `limit`은 쓰이지 않는다).
+     */
+    loadOlder(limit?: number): Promise<{
+        messages: Message[];
+        hasMore: boolean;
+    }>;
+    private readOlder;
     /**
      * Fetches everything between what we have and `upTo`.
      *
@@ -827,6 +962,8 @@ declare class Timeline {
     /** Inserts at the seq position, replacing an existing row with that seq. */
     private insert;
     private applyDelete;
+    /** Makes `items` safe to mutate: a copy, if the current one was handed out. */
+    private own;
     private changed;
 }
 declare function createTimeline(options: TimelineOptions): Timeline;