@noverachat/sdk-web 0.0.3

package/src/client.ts

@@ -0,0 +1,733 @@
+/**
+ * NoveraChat — top-level client facade.
+ *
+ *   const chat = new NoveraChat({ appId, endpoint, tokenProvider });
+ *   await chat.connect();
+ *   const room = chat.room("room_123");
+ *   room.on("message", ...);
+ *   await room.send("hi");
+ *   chat.disconnect();
+ */
+
+import type {
+  AcceptInviteResult, AppPolicy, Block, ClientOptions, DeviceInfo, FileMeta,
+  MessageIdStr, RegisterDeviceParams, UnreadSummary, WsAnnouncementEvent,
+  WsInbound, WsPresence, WsRoomEvent,
+} from "./types.js";
+
+/** Client-level events (not tied to a single Room facade). `roomEvent` fires
+ *  for membership / room-lifecycle changes on ANY room — including ones the
+ *  caller hasn't opened yet (e.g. being added to a brand-new room), which a
+ *  per-room `room.on(...)` listener could never catch. `presence` fires
+ *  when any user this session shares a room with transitions online or
+ *  offline (first / last live session only — multi-tab open/close stays
+ *  silent). */
+export interface ClientEvents {
+  roomEvent: WsRoomEvent;
+  presence: WsPresence;
+}
+
+/**
+ * BigInt comparison helper. Snowflake ids are 63-bit strings on the wire
+ * (see types.ts MessageIdStr) — JS Number would lose precision, so we
+ * compare via BigInt. Empty / null / "0" sort as -∞.
+ */
+function idGreater(a: MessageIdStr | null | undefined, b: MessageIdStr | null | undefined): boolean {
+  if (!a) return false;
+  if (!b) return true;
+  try { return BigInt(a) > BigInt(b); } catch { return a > b; }
+}
+import { HttpClient } from "./transport/http.js";
+import { ReconnectingWs } from "./transport/ws.js";
+import { Room } from "./features/room.js";
+import { EventBus } from "./internal/event-bus.js";
+import { NoveraChatError } from "./errors.js";
+
+export class NoveraChat {
+  private http: HttpClient;
+  private ws: ReconnectingWs;
+  private rooms = new Map<string, Room>();
+  private bus = new EventBus<ClientEvents>();
+  private readDebounceMs: number;
+  private logger: ClientOptions["logger"];
+  private connectedOnce = false;
+  private lastMessageIdByRoom = new Map<string, MessageIdStr>();
+  /** Most recently dispatched presence event key, `${userId}:${at}:${online}`.
+   *  Used to drop the N-1 shared-room copies of a single online/offline
+   *  transition — the server fans out one publish per room, and we don't
+   *  want the caller's listener firing N times for one UX event. */
+  private lastPresenceKey: string | null = null;
+
+  constructor(private opts: ClientOptions) {
+    if (!opts.appId) throw new Error("appId required");
+    if (!opts.endpoint) throw new Error("endpoint required");
+    if (!opts.tokenProvider) throw new Error("tokenProvider required");
+
+    // 400ms is the read-receipt-UX sweet spot for chat apps. Shorter and
+    // we waste WS frames on every micro-scroll; longer and the "✓ read"
+    // indicator feels laggy. Callers can override via the constructor
+    // option for slower / battery-sensitive clients.
+    this.readDebounceMs = opts.readWatermarkDebounceMs ?? 400;
+    this.logger = opts.logger;
+
+    // Seed last-seen ids so the first WS handshake can include `?since=...`
+    // and a subsequent `chat.backfill()` knows where to start. Callers
+    // typically persist these to localStorage on each `chat_receive` and
+    // hand them back here at cold-start. Non-positive entries are ignored.
+    if (opts.initialLastMessageIds) {
+      for (const [roomId, id] of Object.entries(opts.initialLastMessageIds)) {
+        // Accept both legacy number and the new string form. Coerce number
+        // → string defensively (callers really should hand us strings now,
+        // but a freshly-migrated app might still have number-typed
+        // localStorage residue).
+        const sid = typeof id === "number" ? String(id) : id;
+        if (sid && sid !== "0") {
+          this.lastMessageIdByRoom.set(roomId, sid);
+        }
+      }
+    }
+
+    this.http = new HttpClient({
+      baseUrl: opts.endpoint,
+      appId: opts.appId,
+      tokenProvider: opts.tokenProvider,
+      ...(opts.fetch ? { fetch: opts.fetch } : {}),
+      // Same structured sink as the WS transport — the SDK is one source
+      // of truth for both pipes' traces. Debug-level lines (rest_req /
+      // rest_res) are off by default at the consumer side (e.g. the demo
+      // filters them behind a "Verbose" toggle).
+      ...(this.logger ? { logger: this.logger } : {}),
+    });
+
+    const wsBase = opts.wsEndpoint
+      ?? opts.endpoint.replace(/^http/, "ws");
+
+    this.ws = new ReconnectingWs({
+      urlBuilder: async () => {
+        const token = await opts.tokenProvider();
+        const since = this.highestKnownMessageId();
+        const u = new URL(wsBase.replace(/\/+$/, "") + `/ws/${opts.appId}`);
+        u.searchParams.set("token", token);
+        if (since) u.searchParams.set("since", since);
+        return u.toString();
+      },
+      onMessage: (msg) => this.dispatch(msg),
+      onOpen: () => {
+        if (this.connectedOnce) {
+          // reconnect path — ask for any gap since the highest seen id
+          void this.backfillAllRooms();
+        } else {
+          this.connectedOnce = true;
+        }
+      },
+      onStateChange: (s) => this.logger?.("info", `ws_state=${s}`),
+      autoReconnect: opts.autoReconnect ?? true,
+      pingIntervalMs: opts.pingIntervalMs ?? 20_000,
+      maxReconnectDelayMs: opts.maxReconnectDelayMs ?? 30_000,
+      ...(opts.WebSocketImpl ? { WebSocketImpl: opts.WebSocketImpl } : {}),
+      ...(opts.logger ? { logger: opts.logger } : {}),
+    });
+  }
+
+  async connect(): Promise<void> {
+    await this.ws.connect();
+  }
+
+  disconnect(): void {
+    this.ws.close();
+    this.rooms.clear();
+  }
+
+  room(roomId: string): Room {
+    let r = this.rooms.get(roomId);
+    if (!r) {
+      r = new Room(roomId, this.http, this.ws, this.readDebounceMs);
+      this.rooms.set(roomId, r);
+    }
+    return r;
+  }
+
+  /** Subscribe to client-level events. Currently `roomEvent` — membership /
+   *  room-lifecycle changes for ANY room (added, kicked, restored, frozen,
+   *  …), including rooms the caller hasn't opened. Returns an unsubscribe fn.
+   *  Use this to refresh a channel list the instant you're added to a new
+   *  room, rather than waiting for a poll. */
+  on<K extends keyof ClientEvents>(event: K, fn: (p: ClientEvents[K]) => void): () => void {
+    return this.bus.on(event, fn);
+  }
+
+  off<K extends keyof ClientEvents>(event: K, fn: (p: ClientEvents[K]) => void): void {
+    this.bus.off(event, fn);
+  }
+
+  /**
+   * Manually fetch all messages newer than the highest known `message_id`
+   * for each room and surface them as regular `room.on("message", ...)`
+   * events. Useful at cold start (after `chat.connect()`) to pull the
+   * "unread since last session" tail — the WS reconnect path calls this
+   * automatically, but the first connect does not.
+   *
+   * No-op for rooms with no seeded id.
+   */
+  async backfill(): Promise<void> {
+    await this.backfillAllRooms();
+  }
+
+  /** Highest `message_id` the client has seen for a given room, or null. */
+  lastSeenMessageId(roomId: string): MessageIdStr | null {
+    return this.lastMessageIdByRoom.get(roomId) ?? null;
+  }
+
+  /**
+   * Monotonically advance the per-room "highest-seen message_id" anchor.
+   * Used by callers that learn a newer watermark from out-of-band sources —
+   * typically the server's own `last_read_message_id` (via the unread
+   * endpoint) so the next `backfill()` doesn't re-pull messages the user
+   * already marked read on another device. Never moves the value backward;
+   * a smaller `messageId` is silently ignored. Accepts either the string
+   * form (preferred) or a number (legacy / convenience).
+   */
+  setLastSeen(roomId: string, messageId: MessageIdStr | number): void {
+    const sid = typeof messageId === "number" ? String(messageId) : messageId;
+    if (!sid || sid === "0") return;
+    const cur = this.lastMessageIdByRoom.get(roomId);
+    if (idGreater(sid, cur)) this.lastMessageIdByRoom.set(roomId, sid);
+  }
+
+  /** Server-side aggregate unread state: total count + per-room breakdown
+   *  for the authenticated user. Single REST call; cheap enough to poll
+   *  every few seconds for a badge, or just refresh on focus + after
+   *  receiving new messages. */
+  /** Client-facing feature flags for the caller's app. Cheap (one row
+   *  read on the server) — fetch once on connect to decide which
+   *  destructive buttons to expose. */
+  async appPolicy(): Promise<AppPolicy> {
+    const raw = await this.http.request<{
+      app_id: string;
+      allow_member_bulk_delete: boolean;
+      read_receipts_enabled: boolean;
+      typing_indicators_enabled: boolean;
+      allow_member_delete_any_message: boolean;
+    }>("GET", "/api/v1/app/policy");
+    return {
+      appId: raw.app_id,
+      allowMemberBulkDelete: raw.allow_member_bulk_delete,
+      readReceiptsEnabled: raw.read_receipts_enabled ?? true,
+      typingIndicatorsEnabled: raw.typing_indicators_enabled ?? true,
+      deleteAnyMessageEnabled: raw.allow_member_delete_any_message ?? false,
+    };
+  }
+
+  // ---- device tokens (push) ----
+
+  /**
+   * Register (or refresh) this device's push token. Call after login and
+   * whenever the platform hands you a rotated FCM/APNS token. Idempotent
+   * on `deviceId` — the server upserts, so re-registering is cheap and
+   * safe. Returns the stored device record (token shown only as a prefix).
+   */
+  async registerDevice(params: RegisterDeviceParams): Promise<DeviceInfo> {
+    const raw = await this.http.request<{
+      device_id: string;
+      token_type: DeviceInfo["tokenType"];
+      token_preview: string;
+      os: DeviceInfo["os"];
+      app_version: string | null;
+      push_enabled: boolean;
+      last_active_at: string | null;
+      created_at: string;
+    }>("POST", "/api/v1/users/me/devices", {
+      device_id: params.deviceId,
+      token: params.token,
+      token_type: params.tokenType,
+      os: params.os ?? null,
+      app_version: params.appVersion ?? null,
+    });
+    return this._toDeviceInfo(raw);
+  }
+
+  /** List the devices registered for the authenticated user. */
+  async listDevices(): Promise<DeviceInfo[]> {
+    const raw = await this.http.request<{
+      items: Array<Parameters<NoveraChat["_toDeviceInfo"]>[0]>;
+      total: number;
+    }>("GET", "/api/v1/users/me/devices");
+    return raw.items.map((d) => this._toDeviceInfo(d));
+  }
+
+  /**
+   * Turn push delivery on/off for one device without unregistering it —
+   * the token stays stored, the push pipeline just skips it. Use for an
+   * in-app "notifications" toggle.
+   */
+  async setDevicePushEnabled(deviceId: string, enabled: boolean): Promise<void> {
+    await this.http.request<void>(
+      "PATCH", `/api/v1/users/me/devices/${encodeURIComponent(deviceId)}`,
+      { push_enabled: enabled },
+    );
+  }
+
+  /** Unregister a device — call on logout so the user stops receiving
+   *  push on a device they're no longer signed into. */
+  async unregisterDevice(deviceId: string): Promise<void> {
+    await this.http.request<void>(
+      "DELETE", `/api/v1/users/me/devices/${encodeURIComponent(deviceId)}`,
+    );
+  }
+
+  // ---- global push preference (user-level kill switch) ----
+
+  /**
+   * Read the caller's GLOBAL push preference. When `pushEnabled` is
+   * false the push worker skips this user entirely — every per-room
+   * `push_trigger` setting is ignored. Fail-open: an unknown user
+   * comes back as `pushEnabled: true`.
+   *
+   * Two levels of push control:
+   *   1. **Per-room** — `room.setPushTrigger("ALL" | "MENTION_ONLY" | "OFF")`.
+   *   2. **Global (this)** — overrides all rooms when off.
+   */
+  async getPushPreferences(): Promise<{ pushEnabled: boolean }> {
+    const raw = await this.http.request<{ push_enabled: boolean }>(
+      "GET", "/api/v1/users/me/push-preferences",
+    );
+    return { pushEnabled: Boolean(raw.push_enabled) };
+  }
+
+  /**
+   * Flip the caller's global push kill switch. Pass `false` to mute
+   * every push notification for this user across every room; pass
+   * `true` to restore normal delivery. Idempotent.
+   */
+  async setPushEnabled(enabled: boolean): Promise<{ pushEnabled: boolean }> {
+    const raw = await this.http.request<{ push_enabled: boolean }>(
+      "PATCH", "/api/v1/users/me/push-preferences",
+      { push_enabled: enabled },
+    );
+    return { pushEnabled: Boolean(raw.push_enabled) };
+  }
+
+  // -------------------------------------------------------------------------
+  // User blocks — KakaoTalk-style one-way block.
+  //
+  // The block is directional: `chat.blockUser(otherId)` stops `otherId`'s
+  // messages from reaching the caller. The blocked side is NEVER notified;
+  // their sends still ack. There's no admin escape hatch or "who blocked
+  // me" query — that's the whole point of a one-way block.
+  // -------------------------------------------------------------------------
+
+  /**
+   * Block a user (one-way). Idempotent — repeated calls return the
+   * existing row without changing `createdAt` or `reason`.
+   *
+   * @param userId  The user to block. `chat.blockUser(myUserId)` throws
+   *                a validation error server-side.
+   * @param reason  Optional local note ≤500 chars.
+   */
+  async blockUser(userId: string, reason?: string): Promise<Block> {
+    const raw = await this.http.request<{
+      blocked_user_id: string;
+      reason: string | null;
+      created_at: string;
+    }>(
+      "POST", `/api/v1/users/me/blocks/${encodeURIComponent(userId)}`,
+      { reason: reason ?? null },
+    );
+    return {
+      blockedUserId: raw.blocked_user_id,
+      reason: raw.reason,
+      createdAt: raw.created_at,
+    };
+  }
+
+  /** Unblock a user. Idempotent — resolves either way. */
+  async unblockUser(userId: string): Promise<void> {
+    await this.http.request<void>(
+      "DELETE", `/api/v1/users/me/blocks/${encodeURIComponent(userId)}`,
+    );
+  }
+
+  /** List every user the caller has blocked, newest first. */
+  async listBlocks(): Promise<Block[]> {
+    const raw = await this.http.request<Array<{
+      blocked_user_id: string;
+      reason: string | null;
+      created_at: string;
+    }>>("GET", "/api/v1/users/me/blocks");
+    return raw.map((r) => ({
+      blockedUserId: r.blocked_user_id,
+      reason: r.reason,
+      createdAt: r.created_at,
+    }));
+  }
+
+  private _toDeviceInfo(raw: {
+    device_id: string;
+    token_type: DeviceInfo["tokenType"];
+    token_preview: string;
+    os: DeviceInfo["os"];
+    app_version: string | null;
+    push_enabled: boolean;
+    last_active_at: string | null;
+    created_at: string;
+  }): DeviceInfo {
+    return {
+      deviceId: raw.device_id,
+      tokenType: raw.token_type,
+      tokenPreview: raw.token_preview,
+      os: raw.os,
+      appVersion: raw.app_version,
+      pushEnabled: raw.push_enabled,
+      lastActiveAt: raw.last_active_at,
+      createdAt: raw.created_at,
+    };
+  }
+
+  /**
+   * Authorization-gated URL for downloading a file attachment.
+   *
+   * The backend runs the request through the authorization gate (caller
+   * must be a non-KICKED member of some room with a non-deleted,
+   * post-cutoff message referencing this file) and then 302-redirects
+   * to a short-lived signed S3 URL. ``<img src=...>`` / ``<video
+   * src=...>`` / ``<a href=...>`` consumers transparently follow the
+   * redirect.
+   *
+   * Why the optional ``token`` argument? Browsers don't let
+   * ``<img>``/``<video>`` tags carry custom Authorization headers —
+   * so URLs destined for those elements have to embed credentials in
+   * the URL itself. The backend's ``require_user`` dep accepts
+   * ``?token=...&app_id=...`` query params as a fallback for exactly
+   * this case (it still prefers headers when present). Pass the same
+   * JWT the SDK was constructed with; ``app_id`` is filled in
+   * automatically from the client options. Omit the token when you're
+   * going to ``fetch()`` the URL yourself with the Authorization
+   * header set (e.g. server-side preview).
+   *
+   * Note: each call returns a fresh URL but the URL embeds a JWT — its
+   * lifetime is the JWT's TTL (~24h by default), not the few-seconds
+   * window of the S3 signed URL the backend redirects to. Don't log it.
+   */
+  fileUrl(fileId: MessageIdStr, token?: string): string {
+    const base = this.opts.endpoint.replace(/\/+$/, "");
+    const u = new URL(`${base}/api/v1/files/${encodeURIComponent(fileId)}`);
+    if (token) {
+      u.searchParams.set("token", token);
+      u.searchParams.set("app_id", this.opts.appId);
+    }
+    return u.toString();
+  }
+
+  /**
+   * Thumbnail URL for an image / video attachment. Returns 404 when
+   * the thumbnail isn't ready yet (poll ``getFileMeta`` then re-render
+   * once ``thumbnailStatus === "ready"``). Same token-in-query rule
+   * as ``fileUrl()``.
+   */
+  fileThumbnailUrl(fileId: MessageIdStr, token?: string): string {
+    const base = this.opts.endpoint.replace(/\/+$/, "");
+    const u = new URL(`${base}/api/v1/files/${encodeURIComponent(fileId)}/thumbnail`);
+    if (token) {
+      u.searchParams.set("token", token);
+      u.searchParams.set("app_id", this.opts.appId);
+    }
+    return u.toString();
+  }
+
+  /**
+   * Fetch a file's metadata without committing to a download. Useful
+   * when ``Message.file`` (the inline copy) is missing — e.g. for
+   * messages loaded from REST history that predate the inline-meta
+   * shipping date.
+   */
+  async getFileMeta(fileId: MessageIdStr): Promise<FileMeta> {
+    // Wire shape mirrors backend ``FileOut`` (Pydantic v2). The ``id``
+    // field comes through with its alias name, not the model attribute
+    // ``file_id`` — easy mistake to make when looking at the SQLAlchemy
+    // model. ``original_name`` was renamed to ``name`` in the inline
+    // shape but the standalone meta still uses ``original_name``.
+    const raw = await this.http.request<{
+      id: MessageIdStr;
+      kind: "image" | "video" | "file";
+      mime: string;
+      size_bytes: number;
+      original_name: string | null;
+      width: number | null;
+      height: number | null;
+      duration_sec: number | null;
+      thumbnail_status: "pending" | "ready" | "failed" | "skipped";
+      forward_blocked?: boolean;
+    }>("GET", `/api/v1/files/${encodeURIComponent(fileId)}/meta`);
+    return {
+      id: raw.id,
+      kind: raw.kind,
+      mime: raw.mime,
+      size: raw.size_bytes,
+      name: raw.original_name ?? null,
+      width: raw.width ?? null,
+      height: raw.height ?? null,
+      durationSec: raw.duration_sec ?? null,
+      thumbnailStatus: raw.thumbnail_status,
+      forwardBlocked: Boolean(raw.forward_blocked),
+    };
+  }
+
+  async unreadSummary(): Promise<UnreadSummary> {
+    const raw = await this.http.request<{
+      total: number;
+      rooms: Array<{
+        room_id: string;
+        name: string | null;
+        room_type: string | null;
+        unread_count: number;
+        last_message_id: string | null;
+        last_message_preview: string | null;
+        last_read_message_id: string | null;
+        member_count: number;
+        members_preview: Array<{
+          user_id: string;
+          nickname: string | null;
+          profile_image_url: string | null;
+          is_online: boolean | null;
+        }>;
+      }>;
+    }>("GET", "/api/v1/users/me/unread");
+    return {
+      total: raw.total,
+      rooms: raw.rooms.map((r) => ({
+        roomId: r.room_id,
+        name: r.name,
+        roomType: r.room_type ?? null,
+        unreadCount: r.unread_count,
+        lastMessageId: r.last_message_id,
+        lastMessagePreview: r.last_message_preview ?? null,
+        lastReadMessageId: r.last_read_message_id,
+        memberCount: r.member_count ?? 0,
+        members: (r.members_preview ?? []).map((m) => ({
+          userId: m.user_id,
+          nickname: m.nickname ?? null,
+          profileImageUrl: m.profile_image_url ?? null,
+          isOnline: m.is_online ?? null,
+        })),
+      })),
+    };
+  }
+
+  /**
+   * Accept an invite link — call this in flows where you receive a
+   * shareable URL (e.g. after parsing a deep link like
+   * `#invite/<token>`). Consumes one use of the token and joins the
+   * caller to the target room; peers already in the room receive a
+   * `MEMBER_JOINED` roomEvent and a SYSTEM chat message.
+   *
+   * Idempotent: if the caller is already an active member the call
+   * succeeds with `wasAlreadyMember: true` and does NOT decrement the
+   * token's remaining uses — safe to call again on every app open.
+   *
+   * Throws (via HttpClient's `NoveraChatError`) when the token is
+   * invalid, expired, revoked, exhausted, or when the caller has been
+   * kicked from the target room.
+   */
+  async acceptInvite(token: string): Promise<AcceptInviteResult> {
+    const raw = await this.http.request<{
+      room_id: string;
+      room_name: string | null;
+      was_already_member: boolean;
+    }>("POST", `/api/v1/invites/${encodeURIComponent(token)}/accept`);
+    return {
+      roomId: raw.room_id,
+      roomName: raw.room_name,
+      wasAlreadyMember: raw.was_already_member,
+    };
+  }
+
+  // ---- internal ----
+
+  private dispatch(msg: WsInbound): void {
+    switch (msg.type) {
+      case "connected":
+        return;
+      case "pong":
+        return;
+      case "error": {
+        this.logger?.("warn", "ws_error_frame", msg);
+        // Server echoes the offending frame's temp_id back in `details`
+        // (e.g. NC-RATE-001 from a rate-limit reject) so we can correlate
+        // it back to the pending send. Without this we'd wait 15s for the
+        // ack timeout to fire — terrible UX for an instantly-knowable
+        // failure.
+        const tempId = (msg.details && typeof msg.details === "object")
+          ? (msg.details as { temp_id?: unknown }).temp_id
+          : undefined;
+        if (typeof tempId === "string" && tempId.length > 0) {
+          // Find the owning room first (temp_ids are globally unique per
+          // session but mapping is per-room).
+          let target: import("./features/room.js").Room | null = null;
+          for (const room of this.rooms.values()) {
+            if (room._hasPendingTempId(tempId)) { target = room; break; }
+          }
+          if (target) {
+            // Rate-limit is the one error class where transparent retry is
+            // safe and almost always succeeds: the token bucket refills
+            // every second, and chat_send is naturally idempotent on
+            // temp_id (server self-echo dedupes). For every other code
+            // (auth, payload too large, frozen room, etc.) the failure
+            // is deterministic — retrying buys nothing.
+            const code = msg.code || "WS_ERROR";
+            if (code === "NC-RATE-001" && target._retryPending(tempId)) {
+              this.logger?.("info", "ws_send_retry_scheduled", {
+                temp_id: tempId, code,
+              });
+              return;
+            }
+            const details = (msg.details ?? undefined) as
+              | Record<string, unknown>
+              | undefined;
+            const err = details !== undefined
+              ? new NoveraChatError(
+                  msg.message || "server rejected frame",
+                  code, 0, details,
+                )
+              : new NoveraChatError(
+                  msg.message || "server rejected frame",
+                  code,
+                );
+            target._rejectPending(tempId, err);
+          }
+        }
+        return;
+      }
+      case "close_notice":
+        this.logger?.("warn", "ws_close_notice", msg);
+        return;
+      case "room_event": {
+        // Membership / room-lifecycle change. Surface at the CLIENT level so
+        // callers can react even for rooms with no Room facade yet (e.g. being
+        // added to a brand-new room) — the `default` case below would drop it
+        // (`this.rooms.get(roomId)` is undefined). Also forward to the room's
+        // facade if one exists, so room-scoped listeners can observe it later.
+        this.bus.emit("roomEvent", msg);
+        return;
+      }
+      case "presence": {
+        // Presence transition (online / offline boundary). The server
+        // publishes one copy per room the peer is a member of, so a
+        // receiver who shares N rooms with the peer sees the same event
+        // N times. Dedupe by (userId, at, online): the server stamps a
+        // single `at` for the whole fan-out, so any repeat with the same
+        // key is a shared-room duplicate we can drop.
+        const key = `${msg.user_id}:${msg.at}:${msg.online ? 1 : 0}`;
+        if (this.lastPresenceKey === key) return;
+        this.lastPresenceKey = key;
+        this.bus.emit("presence", msg);
+        return;
+      }
+      case "ack": {
+        // Treat our own send-and-acked id as "seen" — most servers don't
+        // echo a sender's message back as `chat_receive`, so without this
+        // bookkeeping the sender's own ids would be missing from the
+        // reconnect `?since=` watermark and trigger redundant backfill.
+        if (idGreater(msg.message_id, this.lastMessageIdByRoom.get(msg.room_id))) {
+          this.lastMessageIdByRoom.set(msg.room_id, msg.message_id);
+        }
+        const room = this.rooms.get(msg.room_id);
+        room?._dispatchAck(msg.temp_id, msg.message_id);
+        return;
+      }
+      case "announcement_event": {
+        const room = this.rooms.get(msg.room_id);
+        room?._dispatchAnnouncement(msg);
+        return;
+      }
+      default: {
+        const roomId = "room_id" in msg ? msg.room_id : undefined;
+        if (!roomId) return;
+        const room = this.rooms.get(roomId);
+        if (!room) return;
+        if (msg.type === "chat_receive" && idGreater(msg.message_id, this.lastMessageIdByRoom.get(roomId))) {
+          this.lastMessageIdByRoom.set(roomId, msg.message_id);
+        }
+        // Self-echo dedup. The server fans this room's traffic back to the
+        // sender's own session too, so we'd render the message twice
+        // (once optimistically, once on this frame). When `temp_id` is set
+        // and matches one of our outgoing sends, treat the frame like an
+        // ack — bind the optimistic bubble to the server id — and skip
+        // the regular `message` emit so the UI doesn't see a duplicate.
+        if (msg.type === "chat_receive") {
+          const tid = msg.temp_id ?? null;
+          if (tid && room._isMySentTempId(tid)) {
+            // ack may arrive before or after this frame; whichever comes
+            // first does the swap, the other is a no-op (pendingAcks
+            // entry already cleared).
+            room._dispatchAck(tid, msg.message_id);
+            room._forgetMySentTempId(tid);
+            return;
+          }
+        }
+        room._dispatchInbound(msg);
+      }
+    }
+  }
+
+  private highestKnownMessageId(): MessageIdStr | null {
+    let max: MessageIdStr | null = null;
+    for (const v of this.lastMessageIdByRoom.values()) {
+      if (idGreater(v, max)) max = v;
+    }
+    return max;
+  }
+
+  private async backfillAllRooms(): Promise<void> {
+    for (const [roomId, lastSeen] of this.lastMessageIdByRoom) {
+      try {
+        const room = this.rooms.get(roomId);
+        if (!room) continue;
+        const { items } = await room.listSince(lastSeen, 200);
+        for (const m of items) {
+          // Surface as regular chat_receive so UIs don't need a second code path
+          room._dispatchInbound({
+            type: "chat_receive",
+            room_id: roomId,
+            message_id: m.messageId,
+            sender_id: m.senderId ?? null,
+            message_type: m.messageType,
+            custom_type: m.customType ?? null,
+            content: m.content ?? null,
+            data: m.data ?? null,
+            meta: m.meta ?? null,
+            file_id: m.fileId ?? null,
+            // Inline file metadata loaded via REST has the same shape as
+            // the WS frame's `file` field — pass through if the history
+            // entry carries it; otherwise null and the UI calls
+            // ``chat.getFileMeta(fileId)`` to fetch on demand.
+            file: m.file
+              ? {
+                  id: m.file.id,
+                  kind: m.file.kind,
+                  mime: m.file.mime,
+                  size: m.file.size,
+                  name: m.file.name ?? null,
+                  width: m.file.width ?? null,
+                  height: m.file.height ?? null,
+                  duration_sec: m.file.durationSec ?? null,
+                  thumbnail_status: m.file.thumbnailStatus,
+                }
+              : null,
+            reply_to_id: m.replyToId ?? null,
+            created_at: m.createdAtMs,
+            server_ts: Date.now(),
+          });
+          if (idGreater(m.messageId, this.lastMessageIdByRoom.get(roomId))) {
+            this.lastMessageIdByRoom.set(roomId, m.messageId);
+          }
+        }
+      } catch (err) {
+        if (err instanceof NoveraChatError) {
+          this.logger?.("warn", `backfill_failed room=${roomId}`, err);
+        } else {
+          throw err;
+        }
+      }
+    }
+  }
+}