@kispi/chat 0.1.0

package/dist/index.d.ts

@@ -0,0 +1,806 @@
+/**
+ * The smallest event emitter that types its listeners.
+ *
+ * Not `EventTarget`: it exists in browsers and in Node 22, but its
+ * listeners take an `Event` and the payload has to be smuggled through
+ * `CustomEvent.detail`, which types badly and reads worse at the call
+ * site. Not Node's `EventEmitter` either -- that is not in browsers.
+ */
+type Listener<T> = (value: T) => void;
+declare class Emitter<Events extends Record<string, unknown>> {
+    private readonly listeners;
+    on<K extends keyof Events>(event: K, fn: Listener<Events[K]>): () => void;
+    emit<K extends keyof Events>(event: K, value: Events[K]): void;
+    clear(): void;
+}
+
+/**
+ * The wire shapes this SDK reads and writes.
+ *
+ * These mirror `docs/protocol.md`, and the names are the wire's own. When
+ * the server grows a field, the change here is additive and nothing has
+ * to be renamed on the way through -- which is the whole reason the
+ * public API uses the wire's event names too.
+ */
+type Frame = {
+    type: string;
+    id?: string;
+    data?: unknown;
+};
+type AuthUser = {
+    id: string;
+    name: string;
+    avatar?: string;
+};
+type Hello = {
+    connectionId: string;
+    user: AuthUser;
+    mode: 'token' | 'external';
+    serverTime: number;
+    heartbeatMs: number;
+    limits: Record<string, number>;
+    /**
+     * Absent is not zero.
+     *
+     * The server drops this field when the count could not be read, and a
+     * client that treats the absence as zero clears the badge of somebody
+     * who has unread messages. `GET /me/unread` is the recovery.
+     */
+    unread?: {
+        total: number;
+        mentions: number;
+        roomsCapped?: boolean;
+    };
+    warnings?: string[];
+};
+/** What `chat.on('state')` reports. */
+type ConnectionState = 'connecting' | 'open' | 'reconnecting' | 'closed';
+
+/**
+ * The REST half of the client.
+ *
+ * The socket carries everything live; this carries everything a client
+ * has to *ask* for -- history, the gap after a reconnect, unread counts,
+ * the reaction list. Both halves are needed and neither replaces the
+ * other: `subscribe` does not replay, and REST does not push.
+ *
+ * **It authenticates only in token mode.** A user JWT plus the `pk_` is
+ * the one REST credential a client has (`internal/auth/rest.go`). That is
+ * every connection this SDK makes, so the only way to reach this without
+ * a token is to call it before `connect()` has fetched one.
+ */
+type RestOptions = {
+    /** `https://chat.example.com`. Derived from the socket url when absent. */
+    url: string;
+    key: string;
+    /** Returns the current user JWT, or undefined before the first connect. */
+    token: () => Promise<string | undefined>;
+    fetch: typeof globalThis.fetch;
+};
+declare class Rest {
+    private readonly options;
+    constructor(options: RestOptions);
+    get<T>(path: string, query?: Record<string, string | number | undefined>): Promise<T>;
+    post<T>(path: string, body?: unknown): Promise<T>;
+    patch<T>(path: string, body?: unknown): Promise<T>;
+    put<T>(path: string, body?: unknown): Promise<T>;
+    delete<T>(path: string): Promise<T>;
+    private call;
+}
+
+/** A message as the server renders it. */
+type Message = {
+    id: string;
+    seq: number;
+    sender?: {
+        id: string;
+        name: string;
+        avatar?: string;
+    };
+    kind?: string;
+    body?: {
+        text?: string;
+        entities?: unknown[];
+        attachments?: unknown[];
+    };
+    meta?: Record<string, unknown>;
+    appMeta?: Record<string, unknown>;
+    createdAt?: number;
+    editedAt?: number;
+    deletedAt?: number;
+    replyTo?: string;
+    threadId?: string;
+    reactions?: {
+        emoji: string;
+        count: number;
+    }[];
+    thread?: {
+        count: number;
+        lastSeq?: number;
+    };
+};
+type SendInput = {
+    text?: string;
+    attachments?: unknown[];
+    entities?: unknown[];
+    replyTo?: string;
+    threadId?: string;
+    meta?: Record<string, unknown>;
+};
+type SendOptions = {
+    /**
+     * Overrides the generated dedup key.
+     *
+     * The SDK makes one per call, and a caller that retries at its own
+     * layer has to pass the **same** one back -- a fresh id turns one slow
+     * network into two messages.
+     */
+    clientMessageId?: string;
+};
+type PublishAck = {
+    messageId: string;
+    seq: number;
+    createdAt?: number;
+};
+type RoomEvents = {
+    /**
+     * The room could not finish loading or catching up.
+     *
+     * Emitted rather than thrown, because the failure happens on the
+     * 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.
+     */
+    error: Error;
+    /**
+     * The timeline was thrown away and rebuilt, because the server said
+     * this client's cursor was older than the room's retention.
+     *
+     * A consumer holding rendered messages has to drop them: the list is
+     * new, and quietly appending to the old one leaves a gap that no fill
+     * will ever close.
+     *
+     * Expect this more often than the retention window alone suggests. A
+     * resubscribe reports the top of the **contiguous** run, not the top
+     * of the list, so a client that has been carrying an unfilled hole
+     * asks from further back and crosses the retention line sooner. That
+     * is the honest outcome: the alternative is a hole the client keeps
+     * forever without ever being told.
+     */
+    reset: Message[];
+    'message.created': any;
+    'message.updated': any;
+    'message.deleted': any;
+    'reaction.added': any;
+    'reaction.removed': any;
+    'thread.updated': any;
+    presence: any;
+    typing: any;
+    read: any;
+    'member.joined': any;
+    'member.left': any;
+    'room.updated': any;
+    'room.deleted': any;
+    custom: any;
+    /** The room's message list changed, for any reason. */
+    messages: Message[];
+};
+declare class Room extends Emitter<RoomEvents> {
+    /** Resolved on subscribe when the room was addressed by key. */
+    id: string | undefined;
+    readonly key: string | undefined;
+    /** The last seq the server reported for this room. */
+    lastSeq: number;
+    presence: {
+        count: number;
+        users?: unknown[];
+        capped?: boolean;
+    } | undefined;
+    private readonly chat;
+    private readonly rest;
+    private readonly timeline;
+    /** The live feed is on and history is loaded. */
+    private subscribed;
+    /**
+     * Invalidates work in flight.
+     *
+     * A subscribe is several awaits long -- the frame, then a history read
+     * -- and the socket can die in the middle of it. The promise that was
+     * in flight then completes against a **dead socket's** ack and marks
+     * the room subscribed, while the new socket has never heard of it. The
+     * room is then live nowhere and believes it is live, and no public
+     * call fixes that because every entry point short-circuits on the flag
+     * it just set.
+     *
+     * Each attempt carries the generation it started in and applies
+     * nothing once that has moved.
+     */
+    private generation;
+    /**
+     * A subscribe was asked for at least once, whether or not it finished.
+     *
+     * `subscribed` cannot carry this. A catch-up that fails leaves a room
+     * that is *not* subscribed, and if that were the only flag a reconnect
+     * would skip it -- the room drops out of the live feed permanently and
+     * silently, which is worse than the failure that started it.
+     */
+    private wanted;
+    private subscribing;
+    constructor(chat: ChatClient, rest: Rest, address: {
+        id?: string;
+        key?: string;
+    });
+    /** Everything this client knows about the room, in seq order. */
+    get messages(): Message[];
+    /**
+     * Reloads recent history, discarding what is held.
+     *
+     * A reconnect recovers the **message timeline** and nothing else: the
+     * only history route is `GET .../messages`, and reactions, thread
+     * counts, read cursors, membership and room metadata ride along only
+     * for the rows that page happens to contain. So a reaction added to an
+     * older message while this client was away is never seen, and no
+     * amount of gap filling will find it.
+     *
+     * The SDK does not hide that behind a background refresh, because the
+     * refresh would have to be either wasteful or wrong. It gives the
+     * consumer the one honest tool -- ask again -- and says when to use it.
+     */
+    reload(): Promise<void>;
+    /**
+     * Starts the live feed and loads recent history.
+     *
+     * Both halves, because neither is enough: `subscribe` does not replay
+     * anything that already happened, and a history read has no way to
+     * learn about what happens next. A room that only did the first looks
+     * empty until somebody speaks.
+     */
+    subscribe(): Promise<void>;
+    private doSubscribe;
+    /**
+     * Reads a page of history directly, without touching `messages`.
+     *
+     * 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.
+     *
+     * `view` defaults to the server's, which is every message including
+     * thread replies. **`view: 'main'` is a display filter, not a sync
+     * cursor** -- its last seq skips replies, so feeding it back as
+     * `since` would ask the server to resend every reply since.
+     */
+    history(options?: {
+        before?: number;
+        after?: number;
+        limit?: number;
+        view?: 'main' | 'all' | {
+            thread: string;
+        };
+    }): Promise<Message[]>;
+    /** Adds a reaction. Idempotent, like the frame. */
+    react(messageId: string, emoji: string): Promise<void>;
+    unreact(messageId: string, emoji: string): Promise<void>;
+    /**
+     * Moves this user's read cursor.
+     *
+     * The cursor only moves forward: the server ignores a lower value and
+     * **does not call that an error**, so the ack's `advanced` is the only
+     * way to know what happened. It is returned rather than swallowed.
+     */
+    markRead(seq: number, options?: {
+        threadId?: string;
+    }): Promise<{
+        seq: number;
+        advanced: boolean;
+    }>;
+    /**
+     * Says this user is typing.
+     *
+     * Fire and forget: the frame is ephemeral, the server throttles it,
+     * and a caller awaiting an ack on every keystroke would be doing the
+     * one thing this event is designed to avoid.
+     *
+     * **The event comes back to the sender too.** The server broadcasts it
+     * to the room without excluding whoever sent it, so a consumer drawing
+     * "X is typing" has to skip its own `userId` -- the SDK does not
+     * filter it out, because a room view that shows every typist and one
+     * that shows everyone else are both legitimate and only the consumer
+     * knows which it is drawing.
+     */
+    typing(): void;
+    /** Joins a public or channel room. Idempotent. */
+    join(): Promise<void>;
+    /** Leaves. Idempotent from the caller's side. */
+    leave(): Promise<void>;
+    /** The full presence list, for rooms too large to send it in the ack. */
+    presenceList(): Promise<{
+        count: number;
+        users?: unknown[];
+        capped?: boolean;
+    }>;
+    /**
+     * Who reacted, one row per (user, emoji) pair.
+     *
+     * A person who put three emoji on one message is three rows, and the
+     * cursor pages over pairs for that reason: keyed on the user alone, a
+     * page boundary falling inside someone's set would drop the rest of
+     * their emoji from every page. `limit` is 50 by default and 100 at
+     * most, and a full page still carries a cursor when more follows.
+     */
+    reactionsOf(messageId: string, options?: {
+        emoji?: string;
+        cursor?: string;
+        limit?: number;
+    }): Promise<unknown>;
+    /**
+     * Re-subscribes after a reconnect. Called by the client.
+     *
+     * The test is "was this room ever asked for", not "did the last
+     * subscribe finish". A room whose catch-up failed is in exactly the
+     * state that needs another try, and skipping it there is how a single
+     * transient 500 takes a room out of the live feed for the life of the
+     * page.
+     */
+    resume(): Promise<void>;
+    /**
+     * Sends `subscribe` and recovers from the one error it has an answer
+     * for.
+     *
+     * `cursor_too_old` means the room's retention has passed the point
+     * this client last saw: the server cannot bridge the gap and neither
+     * can we. The only honest response is to drop what we hold and start
+     * from recent history -- and to **say so**, because a consumer that
+     * quietly appends onto its old list keeps a hole forever.
+     */
+    private subscribeFrame;
+    unsubscribe(): Promise<void>;
+    /**
+     * The room's id, or a refusal.
+     *
+     * A room addressed by key has no id until it subscribes, and every
+     * route below builds a path out of it. Without this the path is
+     * `/v1/rooms/undefined/...` and the frame carries `roomId: undefined`
+     * -- a 404 or a validation error that says nothing about the actual
+     * mistake.
+     */
+    private requireId;
+    /** Publishes and resolves when the server acks. */
+    send(input: SendInput, options?: SendOptions): Promise<PublishAck>;
+    /** Routes a frame the client decided belongs to this room. */
+    handle(type: keyof RoomEvents, data: any): void;
+    /**
+     * Replaces the timeline with the most recent page.
+     *
+     * `stillCurrent` guards the write, not the read. This is a replacement
+     * -- the whole point of it -- so a page fetched for a socket that has
+     * since died would throw away everything the socket that replaced it
+     * has already loaded. Marking the room subscribed is guarded for the
+     * same reason one step later; both are the same await, and the guard
+     * has to cover the part that touches shared state.
+     */
+    private loadRecent;
+}
+
+/**
+ * A WebSocket constructor. Injectable because the tests need one that can
+ * be made to misbehave -- an open socket that never answers, a close at a
+ * chosen moment -- and because a consumer behind a proxy or with their
+ * own instrumentation has the same need.
+ */
+type WebSocketLike = {
+    readonly readyState: number;
+    send: (data: string) => void;
+    close: (code?: number, reason?: string) => void;
+    addEventListener: (type: string, fn: (ev: any) => void) => void;
+    removeEventListener: (type: string, fn: (ev: any) => void) => void;
+};
+type WebSocketFactory = new (url: string) => WebSocketLike;
+type ChatClientOptions = {
+    /** `wss://chat.example.com`. The `/v1/ws` path is added. */
+    url: string;
+    /**
+     * Where REST lives, when it is not the same host over http(s).
+     *
+     * Derived from `url` by default, because a consumer configuring one
+     * address and getting both is friendlier than asking twice.
+     */
+    restURL?: string;
+    /** A `pk_` key. */
+    key: string;
+    /**
+     * The user's token, from your backend.
+     *
+     * Required, and there is no mode that does without it. The server
+     * verifies a signature and takes the `sub` inside at face value; it
+     * 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.
+     */
+    token: () => string | Promise<string>;
+    /** external mode. **The server refuses this today** -- the verification half is unbuilt. */
+    externalToken?: () => string | Promise<string>;
+    /** Defaults to the global. See WebSocketLike. */
+    WebSocket?: WebSocketFactory;
+    /** Defaults to the global. Used by REST calls and injectable for the same reasons. */
+    fetch?: typeof globalThis.fetch;
+};
+type ChatClientEvents = {
+    state: ConnectionState;
+    notification: unknown;
+    'user.presence': unknown;
+    /**
+     * A frame the SDK did not route anywhere. Emitted rather than dropped
+     * so a server that grows an event is visible to a consumer before the
+     * SDK learns about it.
+     */
+    frame: Frame;
+};
+declare class ChatClient extends Emitter<ChatClientEvents> {
+    state: ConnectionState;
+    user: AuthUser | undefined;
+    connectionId: string | undefined;
+    hello: Hello | undefined;
+    private readonly options;
+    private readonly makeSocket;
+    private socket;
+    private heartbeat;
+    private retryTimer;
+    private attempt;
+    /** Set by close(), and the only thing that stops the reconnect loop. */
+    private closedByCaller;
+    private nextFrameId;
+    private opening;
+    private readonly rest;
+    /**
+     * Room handles this client has handed out, keyed by how they were
+     * asked for. Nothing is ever removed: a handle a consumer holds has to
+     * keep being resumed after a reconnect.
+     */
+    private readonly handles;
+    /**
+     * Which handle a push frame for a given room id goes to.
+     *
+     * Separate from `handles` because the two questions are different.
+     * Filing a resolved id **into** `handles` meant a second handle for
+     * the same room evicted the first -- and an evicted handle is not just
+     * unrouted, it stops being resumed at all, which is worse than the
+     * problem the eviction was solving.
+     */
+    private readonly routes;
+    /** The token most recently sent, so REST can present the same one. */
+    private lastToken;
+    /** True once a socket has reached `hello`, so the next one is a return. */
+    private everOpened;
+    constructor(options: ChatClientOptions);
+    /** The account-level routes: the rooms this user is in, and unread. */
+    get rooms(): {
+        list: (options?: {
+            cursor?: string;
+            limit?: number;
+        }) => Promise<unknown>;
+        discover: (options?: {
+            type?: 'public' | 'channel';
+            cursor?: string;
+            limit?: number;
+        }) => Promise<unknown>;
+        members: (roomId: string) => {
+            list: (options?: {
+                cursor?: string;
+                limit?: number;
+            }) => Promise<unknown>;
+            add: (userId: string, role?: string) => Promise<void>;
+            remove: (userId: string) => Promise<void>;
+        };
+    };
+    /**
+     * The unread totals across every room this user is a member of.
+     *
+     * The field names are the route's own: `unread` and `unreadMentions`,
+     * **not** the `total`/`mentions` that `hello.unread` uses for the same
+     * two numbers. The server says it both ways and the SDK does not pick
+     * a third; renaming here would mean a consumer reading the protocol
+     * document finds a name that does not exist in either place.
+     *
+     * `roomsCapped` means the totals cover a subset -- this route does not
+     * page, so past 500 rooms it stops counting and says so.
+     */
+    unread(): Promise<{
+        unread: number;
+        unreadMentions: number;
+        roomsCapped?: boolean;
+        rooms: {
+            roomId: string;
+            unread: number;
+            unreadMentions: number;
+        }[];
+    }>;
+    /**
+     * Updates this user's own profile.
+     *
+     * **`meta` only.** The spec's example is `me.update({ name })`, and the
+     * server answers 400 to `name` and `avatar` on this route: a name comes
+     * from the token the consumer's backend signs, or from `PUT
+     * /users/{id}` with an `sk_`. A signature that always fails is not an
+     * API, it is a trap, so it is not offered.
+     *
+     * The merge is one level deep and a `null` deletes its key -- a nested
+     * object is **replaced**, not merged into.
+     */
+    updateMe(meta: Record<string, unknown>): Promise<unknown>;
+    /**
+     * A handle on a room by id.
+     *
+     * Handles are cached, so two callers asking for the same room get the
+     * same object and the same message list -- two lists of one room would
+     * drift the moment one of them filled a gap.
+     */
+    room(roomId: string): Room;
+    /** The same, addressed by the app's own key. Resolved on subscribe. */
+    roomByKey(key: string): Room;
+    private roomHandle;
+    /**
+     * Files a room under its id once `subscribe` has resolved one.
+     *
+     * A room addressed by key is filed under `key:<key>`, and every push
+     * frame names a room by **id** -- so without this the handle is
+     * unreachable from the read loop and a `roomByKey` room receives its
+     * hundred messages of history and then nothing, forever. The events do
+     * not vanish silently: they come out of `chat.on('frame')` as
+     * unrouted, which is how this was found.
+     *
+     * Registering under both keys also makes `chat.room(id)` and
+     * `chat.roomByKey(key)` return the **same** handle for the same room,
+     * which is the property `roomHandle` exists for -- two lists of one
+     * room drift the moment either fills a gap.
+     */
+    registerRoomId(roomId: string, room: Room): void;
+    /** Opens the connection and resolves when `hello` arrives. */
+    connect(): Promise<void>;
+    /**
+     * 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.
+     */
+    close(): Promise<void>;
+    /** Sends a frame and resolves with its ack, or rejects with its error. */
+    send(type: string, data?: unknown, timeoutMs?: number): Promise<unknown>;
+    /**
+     * Frames waiting for an ack, by frame id.
+     *
+     * A table rather than "the next reply is mine": the protocol lets a
+     * client have several frames in flight, and the server answers each
+     * with the id it was given. Assuming order would pair a publish's ack
+     * with a react's.
+     */
+    private readonly pending;
+    private setState;
+    private openOnce;
+    private onHello;
+    private onFrame;
+    /**
+     * Unwraps a `push` frame and gives it to whoever it is about.
+     *
+     * Every server-initiated event arrives inside one envelope --
+     * `{type:"push", data:{roomId?, event, data}}` -- rather than as a
+     * frame type of its own. That is deliberate on the server's side: the
+     * event name lives in the payload, so a message body containing
+     * `"type":"control"` can never be mistaken for a control frame. The
+     * cost is this hop, and the SDK pays it once here so a consumer never
+     * sees the envelope.
+     */
+    private onPush;
+    private plannedDelayMs;
+    private startHeartbeat;
+    private scheduleReconnect;
+    /**
+     * Exponential with full jitter, or whatever the server asked for.
+     *
+     * Jitter is not decoration. A node shutting down drops every socket it
+     * holds at the same instant, and a fixed schedule brings all of them
+     * back at the same instant too -- onto the node that is still up.
+     */
+    private nextDelay;
+    private authData;
+    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.
+ *
+ * # Why this is a module and not part of Room
+ *
+ * Everything here is a state machine over frames: what to do when they
+ * arrive out of order, when one is missing, when a fill lands after the
+ * ground moved. **A real server cannot produce those inputs on demand**
+ * -- within one connection it never reorders a room's events, its REST
+ * answers in milliseconds so "while a fill is in flight" is not a window
+ * you can aim at, and it has no way to be asked for a gap that is not
+ * really there. So the tests inject frames, and that is only possible if
+ * this thing has no socket in it.
+ *
+ * # What it guarantees
+ *
+ * `messages` is sorted by `seq` and has no duplicates. Every hole the
+ * timeline can see is either being fetched or has been fetched. A
+ * tombstone keeps its slot, because `seq` is gap-free on the server and
+ * a client that spliced a deleted message out would leave a hole its own
+ * gap detection then chases forever.
+ */
+/** Fetches `(after, before)` exclusive, ascending, at most `limit`. */
+type FetchRange = (range: {
+    after: number;
+    before: number;
+    limit: number;
+}) => Promise<Message[]>;
+type TimelineOptions = {
+    fetchRange: FetchRange;
+    /** Called whenever the list changes. */
+    onChange?: (messages: Message[]) => void;
+    /** The server's page cap. Exposed so a test can make paging happen. */
+    pageSize?: number;
+};
+declare class Timeline {
+    private readonly options;
+    private items;
+    /**
+     * Deletes for messages this client has not seen yet.
+     *
+     * A `message.deleted` can arrive for a seq inside a hole. If it were
+     * dropped, the fill that follows would bring the row back **alive**,
+     * because the history read reflects the delete only if it happened
+     * before the read. The client would then show a message the server
+     * considers gone, and nothing would ever correct it.
+     */
+    private readonly pendingDeletes;
+    /** In-flight fills, keyed by the range they cover, to avoid duplicates. */
+    private readonly fills;
+    /**
+     * Bumped by every reset.
+     *
+     * A fill started before a reset must not be applied after one: the
+     * range it was asked for described a timeline that no longer exists.
+     * Without this, a reconnect that lands mid-fill mixes the old room's
+     * rows into the new list.
+     */
+    private epoch;
+    constructor(options: TimelineOptions);
+    get messages(): Message[];
+    /** The highest seq this timeline holds, hole or no hole. */
+    get highestSeq(): number;
+    /**
+     * The highest seq with nothing missing below it.
+     *
+     * This is the number a resubscribe must send as `since`, and it is not
+     * `highestSeq`. Holding 5,6,7,8,9,14 with 10..13 missing, the top of
+     * the list is 14 and the top of what this client actually has is 9.
+     * Sending 14 tells the server "I have everything up to 14", the
+     * catch-up computes that there is nothing to fetch, and the hole
+     * becomes permanent -- which is exactly the failure the whole gap
+     * machinery exists to prevent, arriving through the number that
+     * describes it.
+     *
+     * A hole below the first row held is not visible here and not this
+     * client's business: history begins where the last load began.
+     */
+    get contiguousSeq(): number;
+    /**
+     * Forgets everything, including the pending deletes.
+     *
+     * Used when the server says the cursor is too old: what this timeline
+     * holds is no longer connected to what the room holds, so carrying any
+     * of it forward would leave a hole that nothing fills.
+     */
+    discard(): void;
+    /**
+     * Replaces the window with a recent page. Used by the initial load and
+     * by recovery.
+     *
+     * Rows already held **above** the page's top survive it. A recent page
+     * is the last N messages as of the moment the server read them, which
+     * makes it evidence about the range it covers and no evidence at all
+     * about anything newer. Live frames that arrived while the page was in
+     * flight are exactly that -- newer -- and dropping them would open a
+     * hole above the page that nothing goes looking for, because a hole is
+     * only detected on the next arrival.
+     *
+     * That race is not exotic: the README points consumers at `reload()`
+     * for the moment after a reconnect, which is the moment the missed
+     * frames are arriving.
+     *
+     * A caller that wants the list genuinely emptied has `discard()`.
+     */
+    reset(messages: Message[]): void;
+    /**
+     * Takes one live message, in order or not, and fills what it reveals.
+     *
+     * Returns the fill promise so a caller can await settling; nothing in
+     * the SDK does, because a consumer's UI should show what arrived and
+     * let the rest land when it lands.
+     */
+    add(message: Message): Promise<void>;
+    /**
+     * Applies a `message.updated`.
+     *
+     * A row that is already a tombstone stays one. The edit and the delete
+     * can arrive in either order -- reordering is the input this module
+     * exists for -- and applying a late edit to a deleted row puts its body
+     * back on screen under a `deletedAt` that says it is gone. From the
+     * person who deleted it, that is a delete that did not work.
+     */
+    update(message: Message): void;
+    /**
+     * Applies a `reaction.added` or `reaction.removed` to the aggregate the
+     * message carries.
+     *
+     * `Message.reactions` is filled by the history read and a consumer
+     * renders from it, so leaving it alone would give them a count that is
+     * correct at load and frozen after -- inside a live session, with the
+     * event that should have changed it arriving on another channel.
+     *
+     * 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.
+     */
+    reaction(messageId: string, emoji: string, count: number): void;
+    /** 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. */
+    remove(id: string): void;
+    /**
+     * Fetches everything between what we have and `upTo`.
+     *
+     * Used after a reconnect, where the ack's `lastSeq` says how far the
+     * room got while we were away.
+     */
+    catchUp(upTo: number): Promise<void>;
+    /**
+     * Walks a range, page by page, and inserts what comes back.
+     *
+     * The loop is the point. `GET .../messages` caps `limit` at 100, so a
+     * client that was away while a busy room moved 250 messages gets a
+     * third of its gap from one call -- and a single-call implementation
+     * would believe the hole was filled. That failure is silent: the list
+     * looks continuous because the missing rows were never known about.
+     */
+    private fill;
+    /** Inserts at the seq position, replacing an existing row with that seq. */
+    private insert;
+    private applyDelete;
+    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, Room, type RoomEvents, type SendInput, type SendOptions, Timeline, type TimelineOptions, type WebSocketFactory, type WebSocketLike, createChatClient, createTimeline };