@kispi/chat 0.2.1 → 0.2.3

package/dist/index.d.cts

@@ -142,6 +142,21 @@ type Message = {
         emoji: string;
         count: number;
     }[];
+    /**
+     * The emoji this client's user has on the message.
+     *
+     * Filled by history reads and kept in step by the SDK afterwards: a
+     * `reaction.*` event whose `userId` is `chat.user.id` updates it, and
+     * this client's own `react()`/`unreact()` update it **before the frame
+     * goes out**, rolling back if the server refuses. Absent on a row the
+     * server rendered without a viewer (a live `message.created` has none
+     * yet, which is the same as empty).
+     *
+     * The SDK owns this field, so a consumer does not need -- and should
+     * not add -- an optimistic layer of its own on top of it. The count in
+     * `reactions` is the opposite: always the server's, never moved locally.
+     */
+    myReactions?: string[];
     thread?: {
         count: number;
         lastSeq?: number;
@@ -281,6 +296,15 @@ declare class Room extends Emitter<RoomEvents> {
         id?: string;
         key?: string;
     });
+    /**
+     * Whether older history exists above the first message held -- what
+     * `loadOlder()` would report as `hasMore`, known before calling it.
+     *
+     * Derived from the first row's seq against the room's retention floor
+     * (the subscribe ack's `minSeq`), and false once a `loadOlder()` came
+     * back short. False while nothing is loaded. Re-read it on `messages`.
+     */
+    get hasOlder(): boolean;
     /** Everything this client knows about the room, in seq order. A new array whenever it changes. */
     get messages(): Message[];
     /**
@@ -348,9 +372,34 @@ declare class Room extends Emitter<RoomEvents> {
             thread: string;
         };
     }): Promise<Message[]>;
-    /** Adds a reaction. Idempotent, like the frame. */
+    /**
+     * Adds a reaction. Idempotent, like the frame.
+     *
+     * The row's `myReactions` moves **before the frame goes out** and rolls
+     * back if the server refuses; its count stays the server's. See
+     * `toggleReaction`.
+     */
     react(messageId: string, emoji: string): Promise<void>;
+    /** Removes a reaction. Idempotent, and optimistic the same way `react` is. */
     unreact(messageId: string, emoji: string): Promise<void>;
+    /**
+     * Moves `myReactions` now, sends the frame after.
+     *
+     * 누른 값은 (사용자, 이모지)로 로컬에서 정해지고 엔진은 멱등이므로 ack를
+     * 기다릴 이유가 없다 — 기다리면 누른 느낌이 왕복 시간만큼 늦는다. 소비자가
+     * 자기 낙관 계층을 덧대면 이 필드의 주인이 둘이 되므로, SDK가 한다.
+     * **발행은 다르다**: `before_publish` 훅이 본문을 바꿀 수 있어 미리 그릴 값이
+     * 로컬에 없다. 그래서 `send()`는 낙관적이지 않다.
+     *
+     * 개수는 옮기지 않는다. ack가 오기 전에 남이 같은 이모지를 누르면 로컬
+     * +1/-1은 서버가 보낸 수와 다른 값이 되고, 그것을 고칠 이벤트는 이미
+     * 지나갔다. 또 ack와 방 프레임은 다른 길로 와 순서가 없으므로, 늦게 온 내
+     * ack(count 1)가 앞서 온 남의 이벤트(count 2)를 되돌린다.
+     *
+     * 거절·타임아웃·끊김이면 되돌리지만, 그 사이 더 새로운 값이 자리를 차지했다면
+     * 두고 나온다(`Timeline.settleReaction`).
+     */
+    private toggleReaction;
     /**
      * Moves this user's read cursor.
      *
@@ -686,6 +735,31 @@ declare class ChatClient extends Emitter<ChatClientEvents> {
     registerRoomId(roomId: string, room: Room): void;
     /** Opens the connection and resolves when `hello` arrives. */
     connect(): Promise<void>;
+    /**
+     * Re-authenticates: calls `token()` again and replaces the socket, keeping
+     * every room handle and every subscription.
+     *
+     * For when the identity the server holds has to change mid-session --
+     * a nickname change, a new avatar, fresh claims. The server reads the
+     * token once, at `auth`, so `sender.name` on the next message is the old
+     * one until the connection is re-authenticated. `close()` + `connect()`
+     * does that too, but passes through `closed` (a consumer's "you are
+     * offline" screen) and tears down the page listeners.
+     *
+     * States: `open` → `reconnecting` → `open`, never `closed`. Rooms
+     * resubscribe from what they hold and catch up the gap, as after any
+     * drop; `messages` is kept. Frames awaiting an ack on the old socket are
+     * rejected with `closed`. `chat.user` is the new identity once this
+     * resolves. If `token()` fails the client keeps retrying in the
+     * background like any reconnect (and this rejects); a `ChatError` from
+     * `token()` stops it at `closed`, as on connect.
+     *
+     * On a client that is not connected (never connected, or `close()`d) it
+     * is `connect()`.
+     */
+    reconnect(): Promise<void>;
+    /** Sockets `reconnect()` replaced: their late events are not this client's any more. */
+    private readonly retired;
     /**
      * Closes for good.
      *
@@ -797,6 +871,21 @@ type FetchRange = (range: {
     before: number;
     limit: number;
 }) => Promise<Message[]>;
+/**
+ * A press of this client's own that the server has not answered yet.
+ *
+ * Carries its own sequence number, which is the whole point: by the time
+ * an answer comes back the (message, emoji) pair may belong to a newer
+ * press, and settling this one then would put a value nobody is showing
+ * any more back on screen.
+ */
+type PendingReaction = {
+    messageId: string;
+    emoji: string;
+    /** What the press asked for: in `myReactions`, or out of it. */
+    mine: boolean;
+    seq: number;
+};
 type TimelineOptions = {
     fetchRange: FetchRange;
     /** Called whenever the list changes. */
@@ -840,9 +929,39 @@ declare class Timeline {
     private shared;
     /** The `loadOlder` in flight, so a scroll handler firing twice asks once. */
     private older;
+    /**
+     * The lowest seq the room still keeps (`minSeq` from the subscribe ack;
+     * 1 until told). Below it there is nothing to read, whatever seq says.
+     */
+    private floor;
+    /** A `loadOlder` came back short: the top of what the server keeps was reached. */
+    private exhausted;
+    /**
+     * Presses this client has made and the server has not answered yet, one
+     * entry per (message, emoji) pair, each remembering the last value the
+     * **server** gave for that pair.
+     *
+     * 되돌릴 자리로 "누르기 직전 화면값"을 쓰면 안 된다. 눌렀다 곧바로 취소하고
+     * 두 거절이 차례로 오면, 두 번째 거절이 첫 번째의 낙관값 — 서버가 한 번도
+     * 가진 적 없는 값 — 을 화면에 되살린다. 마지막으로 서버가 말한 값만이
+     * 되돌릴 자리다.
+     */
+    private readonly presses;
+    private pressSeq;
     constructor(options: TimelineOptions);
     /** A new array whenever the list changes; never mutated once returned. */
     get messages(): Message[];
+    /**
+     * Whether `loadOlder()` would find anything, answered without asking.
+     *
+     * `loadOlder()`의 `hasMore`와 같은 판정이다: 맨 위 행이 방의 보존 하한
+     * (`minSeq`, seq는 1부터 구멍 없이 붙는다)보다 위에 있고, 앞선 `loadOlder`가
+     * 덜 찬 페이지로 끝을 알린 적이 없으면 더 있다. 첫 `loadOlder()` 전에 "이전
+     * 메시지 더 보기"를 그릴지 정할 수 있게 한다. 목록이 비었으면 false다.
+     */
+    get hasOlder(): boolean;
+    /** Records the room's retention floor (`minSeq`). */
+    setFloor(minSeq: number): void;
     /** The highest seq this timeline holds, hole or no hole. */
     get highestSeq(): number;
     /**
@@ -917,9 +1036,42 @@ declare class Timeline {
      *
      * The server sends the new `count` with the event, so this is a
      * replacement rather than an increment: two clients reacting at once
-     * cannot drift the way `+1`/`-1` would.
+     * cannot drift the way `+1`/`-1` would. `count` undefined leaves the
+     * aggregate alone (the react ack path); `mine` undefined leaves
+     * `myReactions` alone (somebody else's event).
+     *
+     * This is the **authoritative** entry point: a value the server sent.
+     * So a press still waiting on an answer for the same pair is finished
+     * here -- a refusal landing afterwards must not push this value back
+     * to the older one it was going to restore.
      */
-    reaction(messageId: string, emoji: string, count: number): void;
+    reaction(messageId: string, emoji: string, count: number | undefined, mine?: boolean): void;
+    /**
+     * Applies this client's own react/unreact to `myReactions` **before the
+     * frame goes out**, and returns the press so its answer can settle it.
+     *
+     * 누른 값은 (사용자, 이모지)로 로컬에서 정해지고 엔진은 멱등이므로, 미리
+     * 적용해도 ack가 새로 알려 줄 것이 없다. `count`는 일부러 건드리지 않는다 —
+     * 그 사이 남이 같은 이모지를 누르면 로컬 +1/-1은 서버가 보낼 수와 다르고,
+     * 그 차이를 고칠 이벤트는 이미 지나갔다.
+     *
+     * Undefined when the row is not held: there is nothing to show now and
+     * nothing to put back later.
+     */
+    pressReaction(messageId: string, emoji: string, mine: boolean): PendingReaction | undefined;
+    /**
+     * Settles a press with what the server said.
+     *
+     * `accepted` re-asserts the value the press asked for; a refusal puts
+     * the last server-given value back. Either way it does nothing once
+     * this press no longer owns the pair -- a newer press took it over
+     * (and that one's answer decides), or something authoritative already
+     * landed on it (a `reaction.*` event carrying this user's id, a
+     * `reload()`, a reconnect's catch-up page). Reverting there would
+     * resurrect a value older than what is on screen.
+     */
+    settleReaction(press: PendingReaction, accepted: boolean): void;
+    private applyReaction;
     /** Applies a `thread.updated` to the root message's aggregate. */
     thread(rootId: string, count: number, lastSeq?: number): void;
     /** Applies a `message.deleted`, remembering it if the row is not here. */
@@ -962,10 +1114,19 @@ declare class Timeline {
     /** Inserts at the seq position, replacing an existing row with that seq. */
     private insert;
     private applyDelete;
+    /**
+     * Forgets the presses on a row the server has just re-rendered.
+     *
+     * 히스토리 응답의 행은 뷰어별 `myReactions`를 싣고 오므로 그 값이 서버의
+     * 값이다. 누름을 남겨 두면 그 뒤에 온 거절이 더 새로운 진실 위에 옛 값을
+     * 덮어쓴다. 행 전체 단위인 것은 페이지가 그 행의 이모지 전부를 다시 그려
+     * 주기 때문이다.
+     */
+    private serverRendered;
     /** Makes `items` safe to mutate: a copy, if the current one was handed out. */
     private own;
     private changed;
 }
 declare function createTimeline(options: TimelineOptions): Timeline;
 
-export { type AuthUser, ChatClient, type ChatClientEvents, type ChatClientOptions, ChatError, type ConnectionState, type FetchRange, type Frame, type Hello, type Message, type PublishAck, type ReactionUser, type ReactionsPage, Room, type RoomEvents, type SendInput, type SendOptions, Timeline, type TimelineOptions, type WebSocketFactory, type WebSocketLike, createChatClient, createTimeline };
+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 };

package/dist/index.d.ts

@@ -142,6 +142,21 @@ type Message = {
         emoji: string;
         count: number;
     }[];
+    /**
+     * The emoji this client's user has on the message.
+     *
+     * Filled by history reads and kept in step by the SDK afterwards: a
+     * `reaction.*` event whose `userId` is `chat.user.id` updates it, and
+     * this client's own `react()`/`unreact()` update it **before the frame
+     * goes out**, rolling back if the server refuses. Absent on a row the
+     * server rendered without a viewer (a live `message.created` has none
+     * yet, which is the same as empty).
+     *
+     * The SDK owns this field, so a consumer does not need -- and should
+     * not add -- an optimistic layer of its own on top of it. The count in
+     * `reactions` is the opposite: always the server's, never moved locally.
+     */
+    myReactions?: string[];
     thread?: {
         count: number;
         lastSeq?: number;
@@ -281,6 +296,15 @@ declare class Room extends Emitter<RoomEvents> {
         id?: string;
         key?: string;
     });
+    /**
+     * Whether older history exists above the first message held -- what
+     * `loadOlder()` would report as `hasMore`, known before calling it.
+     *
+     * Derived from the first row's seq against the room's retention floor
+     * (the subscribe ack's `minSeq`), and false once a `loadOlder()` came
+     * back short. False while nothing is loaded. Re-read it on `messages`.
+     */
+    get hasOlder(): boolean;
     /** Everything this client knows about the room, in seq order. A new array whenever it changes. */
     get messages(): Message[];
     /**
@@ -348,9 +372,34 @@ declare class Room extends Emitter<RoomEvents> {
             thread: string;
         };
     }): Promise<Message[]>;
-    /** Adds a reaction. Idempotent, like the frame. */
+    /**
+     * Adds a reaction. Idempotent, like the frame.
+     *
+     * The row's `myReactions` moves **before the frame goes out** and rolls
+     * back if the server refuses; its count stays the server's. See
+     * `toggleReaction`.
+     */
     react(messageId: string, emoji: string): Promise<void>;
+    /** Removes a reaction. Idempotent, and optimistic the same way `react` is. */
     unreact(messageId: string, emoji: string): Promise<void>;
+    /**
+     * Moves `myReactions` now, sends the frame after.
+     *
+     * 누른 값은 (사용자, 이모지)로 로컬에서 정해지고 엔진은 멱등이므로 ack를
+     * 기다릴 이유가 없다 — 기다리면 누른 느낌이 왕복 시간만큼 늦는다. 소비자가
+     * 자기 낙관 계층을 덧대면 이 필드의 주인이 둘이 되므로, SDK가 한다.
+     * **발행은 다르다**: `before_publish` 훅이 본문을 바꿀 수 있어 미리 그릴 값이
+     * 로컬에 없다. 그래서 `send()`는 낙관적이지 않다.
+     *
+     * 개수는 옮기지 않는다. ack가 오기 전에 남이 같은 이모지를 누르면 로컬
+     * +1/-1은 서버가 보낸 수와 다른 값이 되고, 그것을 고칠 이벤트는 이미
+     * 지나갔다. 또 ack와 방 프레임은 다른 길로 와 순서가 없으므로, 늦게 온 내
+     * ack(count 1)가 앞서 온 남의 이벤트(count 2)를 되돌린다.
+     *
+     * 거절·타임아웃·끊김이면 되돌리지만, 그 사이 더 새로운 값이 자리를 차지했다면
+     * 두고 나온다(`Timeline.settleReaction`).
+     */
+    private toggleReaction;
     /**
      * Moves this user's read cursor.
      *
@@ -686,6 +735,31 @@ declare class ChatClient extends Emitter<ChatClientEvents> {
     registerRoomId(roomId: string, room: Room): void;
     /** Opens the connection and resolves when `hello` arrives. */
     connect(): Promise<void>;
+    /**
+     * Re-authenticates: calls `token()` again and replaces the socket, keeping
+     * every room handle and every subscription.
+     *
+     * For when the identity the server holds has to change mid-session --
+     * a nickname change, a new avatar, fresh claims. The server reads the
+     * token once, at `auth`, so `sender.name` on the next message is the old
+     * one until the connection is re-authenticated. `close()` + `connect()`
+     * does that too, but passes through `closed` (a consumer's "you are
+     * offline" screen) and tears down the page listeners.
+     *
+     * States: `open` → `reconnecting` → `open`, never `closed`. Rooms
+     * resubscribe from what they hold and catch up the gap, as after any
+     * drop; `messages` is kept. Frames awaiting an ack on the old socket are
+     * rejected with `closed`. `chat.user` is the new identity once this
+     * resolves. If `token()` fails the client keeps retrying in the
+     * background like any reconnect (and this rejects); a `ChatError` from
+     * `token()` stops it at `closed`, as on connect.
+     *
+     * On a client that is not connected (never connected, or `close()`d) it
+     * is `connect()`.
+     */
+    reconnect(): Promise<void>;
+    /** Sockets `reconnect()` replaced: their late events are not this client's any more. */
+    private readonly retired;
     /**
      * Closes for good.
      *
@@ -797,6 +871,21 @@ type FetchRange = (range: {
     before: number;
     limit: number;
 }) => Promise<Message[]>;
+/**
+ * A press of this client's own that the server has not answered yet.
+ *
+ * Carries its own sequence number, which is the whole point: by the time
+ * an answer comes back the (message, emoji) pair may belong to a newer
+ * press, and settling this one then would put a value nobody is showing
+ * any more back on screen.
+ */
+type PendingReaction = {
+    messageId: string;
+    emoji: string;
+    /** What the press asked for: in `myReactions`, or out of it. */
+    mine: boolean;
+    seq: number;
+};
 type TimelineOptions = {
     fetchRange: FetchRange;
     /** Called whenever the list changes. */
@@ -840,9 +929,39 @@ declare class Timeline {
     private shared;
     /** The `loadOlder` in flight, so a scroll handler firing twice asks once. */
     private older;
+    /**
+     * The lowest seq the room still keeps (`minSeq` from the subscribe ack;
+     * 1 until told). Below it there is nothing to read, whatever seq says.
+     */
+    private floor;
+    /** A `loadOlder` came back short: the top of what the server keeps was reached. */
+    private exhausted;
+    /**
+     * Presses this client has made and the server has not answered yet, one
+     * entry per (message, emoji) pair, each remembering the last value the
+     * **server** gave for that pair.
+     *
+     * 되돌릴 자리로 "누르기 직전 화면값"을 쓰면 안 된다. 눌렀다 곧바로 취소하고
+     * 두 거절이 차례로 오면, 두 번째 거절이 첫 번째의 낙관값 — 서버가 한 번도
+     * 가진 적 없는 값 — 을 화면에 되살린다. 마지막으로 서버가 말한 값만이
+     * 되돌릴 자리다.
+     */
+    private readonly presses;
+    private pressSeq;
     constructor(options: TimelineOptions);
     /** A new array whenever the list changes; never mutated once returned. */
     get messages(): Message[];
+    /**
+     * Whether `loadOlder()` would find anything, answered without asking.
+     *
+     * `loadOlder()`의 `hasMore`와 같은 판정이다: 맨 위 행이 방의 보존 하한
+     * (`minSeq`, seq는 1부터 구멍 없이 붙는다)보다 위에 있고, 앞선 `loadOlder`가
+     * 덜 찬 페이지로 끝을 알린 적이 없으면 더 있다. 첫 `loadOlder()` 전에 "이전
+     * 메시지 더 보기"를 그릴지 정할 수 있게 한다. 목록이 비었으면 false다.
+     */
+    get hasOlder(): boolean;
+    /** Records the room's retention floor (`minSeq`). */
+    setFloor(minSeq: number): void;
     /** The highest seq this timeline holds, hole or no hole. */
     get highestSeq(): number;
     /**
@@ -917,9 +1036,42 @@ declare class Timeline {
      *
      * The server sends the new `count` with the event, so this is a
      * replacement rather than an increment: two clients reacting at once
-     * cannot drift the way `+1`/`-1` would.
+     * cannot drift the way `+1`/`-1` would. `count` undefined leaves the
+     * aggregate alone (the react ack path); `mine` undefined leaves
+     * `myReactions` alone (somebody else's event).
+     *
+     * This is the **authoritative** entry point: a value the server sent.
+     * So a press still waiting on an answer for the same pair is finished
+     * here -- a refusal landing afterwards must not push this value back
+     * to the older one it was going to restore.
      */
-    reaction(messageId: string, emoji: string, count: number): void;
+    reaction(messageId: string, emoji: string, count: number | undefined, mine?: boolean): void;
+    /**
+     * Applies this client's own react/unreact to `myReactions` **before the
+     * frame goes out**, and returns the press so its answer can settle it.
+     *
+     * 누른 값은 (사용자, 이모지)로 로컬에서 정해지고 엔진은 멱등이므로, 미리
+     * 적용해도 ack가 새로 알려 줄 것이 없다. `count`는 일부러 건드리지 않는다 —
+     * 그 사이 남이 같은 이모지를 누르면 로컬 +1/-1은 서버가 보낼 수와 다르고,
+     * 그 차이를 고칠 이벤트는 이미 지나갔다.
+     *
+     * Undefined when the row is not held: there is nothing to show now and
+     * nothing to put back later.
+     */
+    pressReaction(messageId: string, emoji: string, mine: boolean): PendingReaction | undefined;
+    /**
+     * Settles a press with what the server said.
+     *
+     * `accepted` re-asserts the value the press asked for; a refusal puts
+     * the last server-given value back. Either way it does nothing once
+     * this press no longer owns the pair -- a newer press took it over
+     * (and that one's answer decides), or something authoritative already
+     * landed on it (a `reaction.*` event carrying this user's id, a
+     * `reload()`, a reconnect's catch-up page). Reverting there would
+     * resurrect a value older than what is on screen.
+     */
+    settleReaction(press: PendingReaction, accepted: boolean): void;
+    private applyReaction;
     /** Applies a `thread.updated` to the root message's aggregate. */
     thread(rootId: string, count: number, lastSeq?: number): void;
     /** Applies a `message.deleted`, remembering it if the row is not here. */
@@ -962,10 +1114,19 @@ declare class Timeline {
     /** Inserts at the seq position, replacing an existing row with that seq. */
     private insert;
     private applyDelete;
+    /**
+     * Forgets the presses on a row the server has just re-rendered.
+     *
+     * 히스토리 응답의 행은 뷰어별 `myReactions`를 싣고 오므로 그 값이 서버의
+     * 값이다. 누름을 남겨 두면 그 뒤에 온 거절이 더 새로운 진실 위에 옛 값을
+     * 덮어쓴다. 행 전체 단위인 것은 페이지가 그 행의 이모지 전부를 다시 그려
+     * 주기 때문이다.
+     */
+    private serverRendered;
     /** Makes `items` safe to mutate: a copy, if the current one was handed out. */
     private own;
     private changed;
 }
 declare function createTimeline(options: TimelineOptions): Timeline;
 
-export { type AuthUser, ChatClient, type ChatClientEvents, type ChatClientOptions, ChatError, type ConnectionState, type FetchRange, type Frame, type Hello, type Message, type PublishAck, type ReactionUser, type ReactionsPage, Room, type RoomEvents, type SendInput, type SendOptions, Timeline, type TimelineOptions, type WebSocketFactory, type WebSocketLike, createChatClient, createTimeline };
+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 };