@kispi/chat 0.1.0

package/dist/index.cjs

@@ -0,0 +1,1175 @@
+"use strict";
+var __defProp = Object.defineProperty;
+var __getOwnPropDesc = Object.getOwnPropertyDescriptor;
+var __getOwnPropNames = Object.getOwnPropertyNames;
+var __hasOwnProp = Object.prototype.hasOwnProperty;
+var __export = (target, all) => {
+  for (var name in all)
+    __defProp(target, name, { get: all[name], enumerable: true });
+};
+var __copyProps = (to, from, except, desc) => {
+  if (from && typeof from === "object" || typeof from === "function") {
+    for (let key of __getOwnPropNames(from))
+      if (!__hasOwnProp.call(to, key) && key !== except)
+        __defProp(to, key, { get: () => from[key], enumerable: !(desc = __getOwnPropDesc(from, key)) || desc.enumerable });
+  }
+  return to;
+};
+var __toCommonJS = (mod) => __copyProps(__defProp({}, "__esModule", { value: true }), mod);
+
+// src/index.ts
+var src_exports = {};
+__export(src_exports, {
+  ChatClient: () => ChatClient,
+  ChatError: () => ChatError,
+  Room: () => Room,
+  Timeline: () => Timeline,
+  createChatClient: () => createChatClient,
+  createTimeline: () => createTimeline
+});
+module.exports = __toCommonJS(src_exports);
+
+// src/emitter.ts
+var Emitter = class {
+  listeners = /* @__PURE__ */ new Map();
+  on(event, fn) {
+    let set = this.listeners.get(event);
+    if (set === void 0) {
+      set = /* @__PURE__ */ new Set();
+      this.listeners.set(event, set);
+    }
+    set.add(fn);
+    return () => void set.delete(fn);
+  }
+  emit(event, value) {
+    const set = this.listeners.get(event);
+    if (set === void 0) return;
+    for (const fn of [...set]) {
+      try {
+        ;
+        fn(value);
+      } catch (err) {
+        queueMicrotask(() => {
+          throw err;
+        });
+      }
+    }
+  }
+  clear() {
+    this.listeners.clear();
+  }
+};
+
+// src/errors.ts
+var ChatError = class extends Error {
+  code;
+  /** Present on rate limits, in milliseconds. */
+  retryAfterMs;
+  /** The consumer's own code, when a before_publish hook denied this. */
+  appCode;
+  constructor(code, message, extra) {
+    super(message);
+    this.name = "ChatError";
+    this.code = code;
+    if (extra?.retryAfterMs !== void 0) this.retryAfterMs = extra.retryAfterMs;
+    if (extra?.appCode !== void 0) this.appCode = extra.appCode;
+  }
+};
+function errorFrom(data, fallback = "the server refused the request") {
+  if (typeof data === "object" && data !== null) {
+    const d = data;
+    const inner = d["error"] ?? d;
+    const code = typeof inner["code"] === "string" ? inner["code"] : "internal";
+    const message = typeof inner["message"] === "string" ? inner["message"] : fallback;
+    const extra = {};
+    if (typeof inner["retryAfterMs"] === "number") extra.retryAfterMs = inner["retryAfterMs"];
+    if (typeof inner["appCode"] === "string") extra.appCode = inner["appCode"];
+    return new ChatError(code, message, extra);
+  }
+  return new ChatError("internal", fallback);
+}
+
+// src/rest.ts
+var Rest = class {
+  options;
+  constructor(options) {
+    this.options = options;
+  }
+  async get(path, query) {
+    return this.call("GET", path + queryString(query));
+  }
+  async post(path, body) {
+    return this.call("POST", path, body);
+  }
+  async patch(path, body) {
+    return this.call("PATCH", path, body);
+  }
+  async put(path, body) {
+    return this.call("PUT", path, body);
+  }
+  async delete(path) {
+    return this.call("DELETE", path);
+  }
+  async call(method, path, body) {
+    const token = await this.options.token();
+    if (token === void 0) {
+      throw new ChatError(
+        "unauthorized",
+        "no user token yet: connect() fetches one, and REST calls before that have nothing to present"
+      );
+    }
+    const headers = {
+      Authorization: `Bearer ${token}`,
+      "X-Chat-Key": this.options.key
+    };
+    if (body !== void 0) headers["Content-Type"] = "application/json";
+    const res = await this.options.fetch(`${this.options.url}${path}`, {
+      method,
+      headers,
+      ...body === void 0 ? {} : { body: JSON.stringify(body) }
+    });
+    if (res.status === 204) return void 0;
+    const text = await res.text();
+    const parsed = text === "" ? void 0 : JSON.parse(text);
+    if (!res.ok) {
+      const err = errorFrom(parsed, `${method} ${path} failed with ${res.status}`);
+      throw err;
+    }
+    return parsed;
+  }
+};
+function queryString(query) {
+  if (query === void 0) return "";
+  const params = new URLSearchParams();
+  for (const [k, v] of Object.entries(query)) {
+    if (v !== void 0) params.set(k, String(v));
+  }
+  const s = params.toString();
+  return s === "" ? "" : `?${s}`;
+}
+function restURLFrom(socketURL) {
+  if (socketURL.startsWith("wss://")) return `https://${socketURL.slice("wss://".length)}`;
+  if (socketURL.startsWith("ws://")) return `http://${socketURL.slice("ws://".length)}`;
+  return socketURL;
+}
+
+// src/timeline.ts
+var MaxPageSize = 100;
+var Timeline = class {
+  options;
+  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.
+   */
+  pendingDeletes = /* @__PURE__ */ new Set();
+  /** In-flight fills, keyed by the range they cover, to avoid duplicates. */
+  fills = /* @__PURE__ */ new Map();
+  /**
+   * 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.
+   */
+  epoch = 0;
+  constructor(options) {
+    this.options = options;
+  }
+  get messages() {
+    return this.items;
+  }
+  /** The highest seq this timeline holds, hole or no hole. */
+  get highestSeq() {
+    return this.items.at(-1)?.seq ?? 0;
+  }
+  /**
+   * 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() {
+    const first = this.items[0];
+    if (first === void 0) return 0;
+    let last = first.seq;
+    for (const item of this.items) {
+      if (item.seq === last || item.seq === last + 1) {
+        last = item.seq;
+        continue;
+      }
+      break;
+    }
+    return last;
+  }
+  /**
+   * 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() {
+    this.epoch++;
+    this.fills.clear();
+    this.pendingDeletes.clear();
+    this.items = [];
+    this.changed();
+  }
+  /**
+   * 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) {
+    this.epoch++;
+    this.fills.clear();
+    const page = [...messages].sort((a, b) => a.seq - b.seq);
+    const top = page.at(-1)?.seq ?? 0;
+    this.items = [...page, ...this.items.filter((m) => m.seq > top)];
+    for (const m of this.items) {
+      if (this.pendingDeletes.has(m.id)) this.applyDelete(m.id);
+    }
+    this.changed();
+  }
+  /**
+   * 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) {
+    const gapFrom = this.highestSeq;
+    this.insert(message);
+    if (gapFrom > 0 && message.seq > gapFrom + 1) {
+      return this.fill(gapFrom, message.seq);
+    }
+    return Promise.resolve();
+  }
+  /**
+   * 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) {
+    const at = this.items.findIndex((m) => m.id === message.id);
+    if (at === -1) return;
+    const current = this.items[at];
+    if (current.deletedAt !== void 0) return;
+    this.items[at] = { ...current, ...message };
+    this.changed();
+  }
+  /**
+   * 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, emoji, count) {
+    const at = this.items.findIndex((m) => m.id === messageId);
+    if (at === -1) return;
+    const current = this.items[at];
+    const existing = current.reactions ?? [];
+    const slot = existing.findIndex((r) => r.emoji === emoji);
+    let next;
+    if (count <= 0) next = existing.filter((r) => r.emoji !== emoji);
+    else if (slot === -1) next = [...existing, { emoji, count }];
+    else next = existing.map((r, i) => i === slot ? { emoji, count } : r);
+    this.items[at] = { ...current, reactions: next };
+    this.changed();
+  }
+  /** Applies a `thread.updated` to the root message's aggregate. */
+  thread(rootId, count, lastSeq) {
+    const at = this.items.findIndex((m) => m.id === rootId);
+    if (at === -1) return;
+    const current = this.items[at];
+    this.items[at] = { ...current, thread: lastSeq === void 0 ? { count } : { count, lastSeq } };
+    this.changed();
+  }
+  /** Applies a `message.deleted`, remembering it if the row is not here. */
+  remove(id) {
+    if (!this.applyDelete(id)) this.pendingDeletes.add(id);
+  }
+  /**
+   * 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.
+   */
+  async catchUp(upTo) {
+    const from = this.contiguousSeq;
+    if (upTo <= from) return;
+    await this.fill(from, upTo + 1);
+  }
+  /**
+   * 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.
+   */
+  fill(after, before) {
+    const key = `${after}:${before}`;
+    const existing = this.fills.get(key);
+    if (existing !== void 0) return existing;
+    const epoch = this.epoch;
+    const pageSize = this.options.pageSize ?? MaxPageSize;
+    const run = (async () => {
+      let cursor = after;
+      while (cursor < before - 1) {
+        const page = await this.options.fetchRange({ after: cursor, before, limit: pageSize });
+        if (this.epoch !== epoch) return;
+        if (page.length === 0) return;
+        for (const m of page) this.insert(m);
+        const highest = page.at(-1)?.seq ?? cursor;
+        if (highest <= cursor) return;
+        cursor = highest;
+      }
+    })().finally(() => {
+      if (this.fills.get(key) === run) this.fills.delete(key);
+    });
+    this.fills.set(key, run);
+    return run;
+  }
+  /** Inserts at the seq position, replacing an existing row with that seq. */
+  insert(message) {
+    const pending = this.pendingDeletes.has(message.id);
+    if (pending) this.pendingDeletes.delete(message.id);
+    const withDelete = pending ? emptied(message) : message;
+    const at = this.items.findIndex((m) => m.seq >= withDelete.seq);
+    if (at === -1) {
+      this.items.push(withDelete);
+    } else if (this.items[at]?.seq === withDelete.seq) {
+      const current = this.items[at];
+      this.items[at] = current.deletedAt !== void 0 ? current : withDelete;
+    } else {
+      this.items.splice(at, 0, withDelete);
+    }
+    this.changed();
+  }
+  applyDelete(id) {
+    const at = this.items.findIndex((m) => m.id === id);
+    if (at === -1) return false;
+    this.pendingDeletes.delete(id);
+    this.items[at] = emptied(this.items[at]);
+    this.changed();
+    return true;
+  }
+  changed() {
+    this.options.onChange?.(this.items);
+  }
+};
+function emptied(message) {
+  return { ...message, body: {}, deletedAt: message.deletedAt ?? Date.now() };
+}
+function createTimeline(options) {
+  return new Timeline(options);
+}
+
+// src/room.ts
+var HistoryPageSize = 100;
+var Room = class extends Emitter {
+  /** Resolved on subscribe when the room was addressed by key. */
+  id;
+  key;
+  /** The last seq the server reported for this room. */
+  lastSeq = 0;
+  presence;
+  chat;
+  rest;
+  timeline;
+  /** The live feed is on and history is loaded. */
+  subscribed = false;
+  /**
+   * 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.
+   */
+  generation = 0;
+  /**
+   * 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.
+   */
+  wanted = false;
+  subscribing;
+  constructor(chat, rest, address) {
+    super();
+    this.chat = chat;
+    this.rest = rest;
+    this.id = address.id;
+    this.key = address.key;
+    this.timeline = createTimeline({
+      fetchRange: ({ after, before, limit }) => this.rest.get(`/v1/rooms/${this.id}/messages`, {
+        after,
+        before,
+        limit
+      }).then((page) => page.messages),
+      onChange: (messages) => this.emit("messages", messages)
+    });
+  }
+  /** Everything this client knows about the room, in seq order. */
+  get messages() {
+    return this.timeline.messages;
+  }
+  /**
+   * 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.
+   */
+  async reload() {
+    const gen = this.generation;
+    await this.loadRecent(() => gen === this.generation);
+  }
+  /**
+   * 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.
+   */
+  async subscribe() {
+    this.wanted = true;
+    if (this.subscribing !== void 0) return this.subscribing;
+    if (this.subscribed) return;
+    const attempt = this.doSubscribe().finally(() => {
+      if (this.subscribing === attempt) this.subscribing = void 0;
+    });
+    this.subscribing = attempt;
+    return attempt;
+  }
+  async doSubscribe() {
+    const gen = this.generation;
+    const current = () => gen === this.generation;
+    const data = this.id !== void 0 ? { roomId: this.id } : { key: this.key };
+    const since = this.timeline.contiguousSeq;
+    if (since > 0) data["since"] = since;
+    const attempt = await this.subscribeFrame(data);
+    const ack = attempt.ack;
+    if (!current()) return;
+    this.id = ack.roomId;
+    this.chat.registerRoomId(ack.roomId, this);
+    this.lastSeq = ack.lastSeq;
+    if (ack.presence !== void 0) this.presence = ack.presence;
+    if (attempt.wasReset) {
+      await this.loadRecent(current);
+      if (!current()) return;
+      this.subscribed = true;
+      this.emit("reset", this.timeline.messages);
+      return;
+    }
+    if (since > 0) {
+      await this.timeline.catchUp(ack.lastSeq);
+      if (!current()) return;
+      this.subscribed = true;
+      return;
+    }
+    if (ack.lastSeq > 0) {
+      await this.loadRecent(current);
+    }
+    if (!current()) return;
+    this.subscribed = true;
+  }
+  /**
+   * 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.
+   */
+  async history(options = {}) {
+    const view = options.view === void 0 ? void 0 : typeof options.view === "string" ? options.view : `thread:${options.view.thread}`;
+    const page = await this.rest.get(`/v1/rooms/${this.requireId("reading history")}/messages`, {
+      before: options.before,
+      after: options.after,
+      limit: options.limit,
+      view
+    });
+    return page.messages;
+  }
+  /** Adds a reaction. Idempotent, like the frame. */
+  async react(messageId, emoji) {
+    await this.chat.send("react", { roomId: this.requireId("reacting"), messageId, emoji, op: "add" });
+  }
+  async unreact(messageId, emoji) {
+    await this.chat.send("react", { roomId: this.requireId("reacting"), messageId, emoji, op: "remove" });
+  }
+  /**
+   * 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.
+   */
+  async markRead(seq, options = {}) {
+    const data = { roomId: this.requireId("marking read"), seq };
+    if (options.threadId !== void 0) data["threadId"] = options.threadId;
+    return await this.chat.send("read", data);
+  }
+  /**
+   * 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() {
+    try {
+      void this.chat.send("typing", { roomId: this.requireId("typing") }).catch(() => {
+      });
+    } catch {
+    }
+  }
+  /** Joins a public or channel room. Idempotent. */
+  async join() {
+    await this.rest.post(`/v1/rooms/${this.requireId("joining")}/join`);
+  }
+  /** Leaves. Idempotent from the caller's side. */
+  async leave() {
+    await this.rest.delete(`/v1/rooms/${this.requireId("leaving")}/members/me`);
+  }
+  /** The full presence list, for rooms too large to send it in the ack. */
+  async presenceList() {
+    return this.rest.get(`/v1/rooms/${this.requireId("reading presence")}/presence`, { full: "true" });
+  }
+  /**
+   * 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.
+   */
+  async reactionsOf(messageId, options = {}) {
+    return this.rest.get(`/v1/rooms/${this.requireId("reading reactions")}/messages/${messageId}/reactions`, {
+      emoji: options.emoji,
+      cursor: options.cursor,
+      limit: options.limit
+    });
+  }
+  /**
+   * 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.
+   */
+  async resume() {
+    if (!this.wanted) return;
+    this.generation++;
+    this.subscribing = void 0;
+    this.subscribed = false;
+    await this.subscribe();
+  }
+  /**
+   * 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.
+   */
+  async subscribeFrame(data) {
+    try {
+      return { ack: await this.chat.send("subscribe", data), wasReset: false };
+    } catch (err) {
+      if (err.code !== "cursor_too_old") throw err;
+      this.timeline.discard();
+      const retry = { ...data };
+      delete retry["since"];
+      return { ack: await this.chat.send("subscribe", retry), wasReset: true };
+    }
+  }
+  async unsubscribe() {
+    if (this.id === void 0) return;
+    this.wanted = false;
+    this.subscribed = false;
+    this.generation++;
+    this.subscribing = void 0;
+    await this.chat.send("unsubscribe", { roomId: this.id });
+  }
+  /**
+   * 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.
+   */
+  requireId(what) {
+    if (this.id === void 0) {
+      throw new ChatError("closed", `subscribe to the room before ${what}: its id is not known yet`);
+    }
+    return this.id;
+  }
+  /** Publishes and resolves when the server acks. */
+  async send(input, options = {}) {
+    const roomId = this.requireId("sending");
+    const body = {};
+    if (input.text !== void 0) body["text"] = input.text;
+    if (input.entities !== void 0) body["entities"] = input.entities;
+    if (input.attachments !== void 0) body["attachments"] = input.attachments;
+    const frame = {
+      roomId,
+      clientMessageId: options.clientMessageId ?? newClientMessageId(),
+      body
+    };
+    if (input.replyTo !== void 0) frame["replyTo"] = input.replyTo;
+    if (input.threadId !== void 0) frame["threadId"] = input.threadId;
+    if (input.meta !== void 0) frame["meta"] = input.meta;
+    return await this.chat.send("publish", frame);
+  }
+  /** Routes a frame the client decided belongs to this room. */
+  handle(type, data) {
+    switch (type) {
+      case "message.created":
+        if (data.seq > this.lastSeq) this.lastSeq = data.seq;
+        this.timeline.add(data).catch((err) => {
+          this.subscribed = false;
+          this.emit("error", err instanceof Error ? err : new Error(String(err)));
+        });
+        break;
+      case "message.updated":
+        this.timeline.update(data);
+        break;
+      case "message.deleted": {
+        const deleted = data;
+        if (deleted.seq !== void 0 && deleted.seq > this.lastSeq) this.lastSeq = deleted.seq;
+        this.timeline.remove(deleted.id);
+        break;
+      }
+      case "reaction.added":
+      case "reaction.removed": {
+        const r = data;
+        this.timeline.reaction(r.messageId, r.emoji, r.count);
+        break;
+      }
+      case "thread.updated": {
+        const t = data;
+        this.timeline.thread(t.rootId, t.count, t.lastSeq);
+        break;
+      }
+      case "presence":
+        this.presence = data;
+        break;
+      default:
+        break;
+    }
+    this.emit(type, data);
+  }
+  /**
+   * 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.
+   */
+  async loadRecent(stillCurrent) {
+    const page = await this.rest.get(`/v1/rooms/${this.requireId("reading history")}/messages`, {
+      limit: HistoryPageSize
+    });
+    if (!stillCurrent()) return;
+    this.timeline.reset(page.messages);
+  }
+};
+function newClientMessageId() {
+  const c = globalThis.crypto;
+  if (c?.randomUUID !== void 0) return `cm-${c.randomUUID()}`;
+  return `cm-${Date.now().toString(36)}-${Math.random().toString(36).slice(2, 10)}`;
+}
+
+// src/client.ts
+var MinBackoffMs = 500;
+var MaxBackoffMs = 3e4;
+var ChatClient = class extends Emitter {
+  state = "closed";
+  user;
+  connectionId;
+  hello;
+  options;
+  makeSocket;
+  socket;
+  heartbeat;
+  retryTimer;
+  attempt = 0;
+  /** Set by close(), and the only thing that stops the reconnect loop. */
+  closedByCaller = false;
+  nextFrameId = 0;
+  opening;
+  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.
+   */
+  handles = /* @__PURE__ */ new Map();
+  /**
+   * 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.
+   */
+  routes = /* @__PURE__ */ new Map();
+  /** The token most recently sent, so REST can present the same one. */
+  lastToken;
+  /** True once a socket has reached `hello`, so the next one is a return. */
+  everOpened = false;
+  constructor(options) {
+    super();
+    this.options = options;
+    const ctor = options.WebSocket ?? globalThis.WebSocket;
+    if (ctor === void 0) {
+      throw new TypeError(
+        "no WebSocket available: pass one as options.WebSocket (Node 22 and every current browser have a global)"
+      );
+    }
+    this.makeSocket = ctor;
+    this.rest = new Rest({
+      url: options.restURL ?? restURLFrom(options.url),
+      key: options.key,
+      token: async () => this.lastToken,
+      fetch: options.fetch ?? globalThis.fetch.bind(globalThis)
+    });
+  }
+  /** The account-level routes: the rooms this user is in, and unread. */
+  get rooms() {
+    return {
+      list: (options) => this.rest.get("/v1/me/rooms", { cursor: options?.cursor, limit: options?.limit }),
+      discover: (options) => this.rest.get("/v1/rooms", { type: options?.type, cursor: options?.cursor, limit: options?.limit }),
+      members: (roomId) => ({
+        list: (options) => this.rest.get(`/v1/rooms/${roomId}/members`, { cursor: options?.cursor, limit: options?.limit }),
+        add: async (userId, role) => {
+          await this.rest.put(`/v1/rooms/${roomId}/members/${userId}`, role === void 0 ? {} : { role });
+        },
+        remove: async (userId) => {
+          await this.rest.delete(`/v1/rooms/${roomId}/members/${userId}`);
+        }
+      })
+    };
+  }
+  /**
+   * 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.
+   */
+  async unread() {
+    return this.rest.get("/v1/me/unread");
+  }
+  /**
+   * 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.
+   */
+  async updateMe(meta) {
+    return this.rest.patch("/v1/me", { meta });
+  }
+  /**
+   * 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) {
+    const routed = this.routes.get(roomId);
+    if (routed !== void 0) return routed;
+    return this.roomHandle(roomId, { id: roomId });
+  }
+  /** The same, addressed by the app's own key. Resolved on subscribe. */
+  roomByKey(key) {
+    return this.roomHandle(`key:${key}`, { key });
+  }
+  roomHandle(cacheKey, address) {
+    const existing = this.handles.get(cacheKey);
+    if (existing !== void 0) return existing;
+    const room = new Room(this, this.rest, address);
+    this.handles.set(cacheKey, room);
+    return room;
+  }
+  /**
+   * 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, room) {
+    this.routes.set(roomId, room);
+  }
+  /** Opens the connection and resolves when `hello` arrives. */
+  async connect() {
+    this.closedByCaller = false;
+    if (this.opening !== void 0) return this.opening;
+    if (this.state === "open" && this.socket !== void 0) return;
+    this.clearTimers();
+    this.opening = this.openOnce().finally(() => {
+      this.opening = void 0;
+    });
+    return this.opening;
+  }
+  /**
+   * 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.
+   */
+  async close() {
+    this.closedByCaller = true;
+    this.clearTimers();
+    const socket = this.socket;
+    this.socket = void 0;
+    if (socket !== void 0) {
+      try {
+        socket.close(1e3, "client closed");
+      } catch {
+      }
+    }
+    this.setState("closed");
+  }
+  /** Sends a frame and resolves with its ack, or rejects with its error. */
+  send(type, data, timeoutMs = 15e3) {
+    const socket = this.socket;
+    if (socket === void 0 || this.state !== "open") {
+      return Promise.reject(new ChatError("closed", `cannot send ${type}: the connection is ${this.state}`));
+    }
+    const id = `c${++this.nextFrameId}`;
+    return new Promise((resolve, reject) => {
+      const timer = setTimeout(() => {
+        this.pending.delete(id);
+        reject(new ChatError("timeout", `no ack for ${type} within ${timeoutMs}ms`));
+      }, timeoutMs);
+      this.pending.set(id, {
+        resolve: (value) => {
+          clearTimeout(timer);
+          resolve(value);
+        },
+        reject: (err) => {
+          clearTimeout(timer);
+          reject(err);
+        }
+      });
+      socket.send(JSON.stringify({ type, id, data }));
+    });
+  }
+  /**
+   * 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.
+   */
+  pending = /* @__PURE__ */ new Map();
+  setState(next) {
+    if (this.state === next) return;
+    this.state = next;
+    this.emit("state", next);
+  }
+  async openOnce() {
+    this.setState(this.attempt === 0 ? "connecting" : "reconnecting");
+    const authData = await this.authData();
+    if (this.closedByCaller) {
+      throw new ChatError("closed", "the client was closed while connecting");
+    }
+    const socket = new this.makeSocket(`${this.options.url}/v1/ws?v=1`);
+    this.socket = socket;
+    return new Promise((resolve, reject) => {
+      let settled = false;
+      const finish = (err) => {
+        if (settled) return;
+        settled = true;
+        if (err === void 0) resolve();
+        else reject(err);
+      };
+      socket.addEventListener("message", (ev) => {
+        const frame = JSON.parse(String(ev.data));
+        if (frame.type === "hello") {
+          this.onHello(frame.data);
+          finish();
+          return;
+        }
+        if (frame.type === "error" && !settled) {
+          this.closedByCaller = true;
+          this.setState("closed");
+          finish(errorFrom(frame.data));
+          return;
+        }
+        this.onFrame(frame);
+      });
+      socket.addEventListener("close", () => {
+        if (this.socket !== void 0 && this.socket !== socket) return;
+        this.clearTimers();
+        this.socket = void 0;
+        this.failPending(new ChatError("closed", "the connection closed"));
+        if (settled) {
+          this.scheduleReconnect();
+        } else {
+          finish(new ChatError("closed", "the connection closed before hello"));
+          this.scheduleReconnect();
+        }
+      });
+      socket.addEventListener("error", () => {
+      });
+      socket.addEventListener("open", () => {
+        socket.send(JSON.stringify({ type: "auth", id: "auth", data: authData }));
+      });
+    });
+  }
+  onHello(hello) {
+    this.hello = hello;
+    this.user = hello.user;
+    this.connectionId = hello.connectionId;
+    this.attempt = 0;
+    this.startHeartbeat(hello.heartbeatMs);
+    const reconnected = this.everOpened;
+    this.everOpened = true;
+    this.setState("open");
+    if (reconnected) {
+      for (const room of this.handles.values()) {
+        void room.resume().catch((err) => {
+          room.emit("error", err instanceof Error ? err : new Error(String(err)));
+        });
+      }
+    }
+  }
+  onFrame(frame) {
+    if (frame.id !== void 0) {
+      const waiter = this.pending.get(frame.id);
+      if (waiter !== void 0) {
+        this.pending.delete(frame.id);
+        if (frame.type === "error") waiter.reject(errorFrom(frame.data));
+        else waiter.resolve(frame.data);
+        return;
+      }
+    }
+    switch (frame.type) {
+      case "push":
+        this.onPush(frame);
+        return;
+      case "pong":
+        return;
+      case "reconnect":
+        this.plannedDelayMs = frame.data?.delayMs;
+        return;
+      default:
+        this.emit("frame", frame);
+    }
+  }
+  /**
+   * 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.
+   */
+  onPush(frame) {
+    const push = frame.data;
+    const event = push?.event;
+    if (event === void 0) {
+      this.emit("frame", frame);
+      return;
+    }
+    if (event === "notification.message") {
+      this.emit("notification", push?.data);
+      return;
+    }
+    if (event === "user.presence") {
+      this.emit("user.presence", push?.data);
+      return;
+    }
+    const room = push?.roomId === void 0 ? void 0 : this.routes.get(push.roomId);
+    if (room === void 0) {
+      this.emit("frame", frame);
+      return;
+    }
+    room.handle(event, push?.data);
+  }
+  plannedDelayMs;
+  startHeartbeat(intervalMs) {
+    this.clearHeartbeat();
+    this.heartbeat = setInterval(() => {
+      try {
+        this.socket?.send(JSON.stringify({ type: "ping", id: `p${++this.nextFrameId}` }));
+      } catch {
+      }
+    }, Math.max(1e3, intervalMs));
+  }
+  scheduleReconnect() {
+    if (this.closedByCaller) return;
+    this.setState("reconnecting");
+    const delay = this.nextDelay();
+    this.retryTimer = setTimeout(() => {
+      this.opening = this.openOnce().finally(() => {
+        this.opening = void 0;
+      });
+      void this.opening.catch(() => {
+      });
+    }, delay);
+  }
+  /**
+   * 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.
+   */
+  nextDelay() {
+    const planned = this.plannedDelayMs;
+    this.plannedDelayMs = void 0;
+    if (planned !== void 0) return planned;
+    const ceiling = Math.min(MaxBackoffMs, MinBackoffMs * 2 ** this.attempt);
+    this.attempt++;
+    return MinBackoffMs + Math.random() * (ceiling - MinBackoffMs);
+  }
+  async authData() {
+    const data = { key: this.options.key };
+    if (this.options.externalToken !== void 0) {
+      data["externalToken"] = await this.options.externalToken();
+      return data;
+    }
+    const token = await this.options.token();
+    this.lastToken = token;
+    data["token"] = token;
+    return data;
+  }
+  failPending(err) {
+    for (const [, waiter] of this.pending) waiter.reject(err);
+    this.pending.clear();
+  }
+  clearHeartbeat() {
+    if (this.heartbeat !== void 0) clearInterval(this.heartbeat);
+    this.heartbeat = void 0;
+  }
+  clearTimers() {
+    this.clearHeartbeat();
+    if (this.retryTimer !== void 0) clearTimeout(this.retryTimer);
+    this.retryTimer = void 0;
+  }
+};
+function createChatClient(options) {
+  return new ChatClient(options);
+}
+// Annotate the CommonJS export names for ESM import in node:
+0 && (module.exports = {
+  ChatClient,
+  ChatError,
+  Room,
+  Timeline,
+  createChatClient,
+  createTimeline
+});