@noverachat/sdk-web 0.0.3

package/dist/index.cjs

@@ -0,0 +1,1737 @@
+"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 index_exports = {};
+__export(index_exports, {
+  ErrorCode: () => ErrorCode,
+  NoveraChat: () => NoveraChat,
+  NoveraChatError: () => NoveraChatError,
+  Room: () => Room
+});
+module.exports = __toCommonJS(index_exports);
+
+// src/errors.ts
+var ErrorCode = {
+  INTERNAL: "NC-GEN-001",
+  NOT_FOUND: "NC-GEN-002",
+  VALIDATION: "NC-GEN-003",
+  FORBIDDEN: "NC-GEN-004",
+  UNAUTHORIZED: "NC-AUTH-001",
+  TOKEN_EXPIRED: "NC-AUTH-002",
+  TOKEN_INVALID: "NC-AUTH-003",
+  TOKEN_REVOKED: "NC-AUTH-004",
+  APP_INACTIVE: "NC-APP-001",
+  APP_NOT_FOUND: "NC-APP-002",
+  USER_BANNED: "NC-USER-001",
+  USER_NOT_FOUND: "NC-USER-002",
+  ROOM_NOT_FOUND: "NC-ROOM-001",
+  ROOM_FROZEN: "NC-ROOM-002",
+  NOT_A_MEMBER: "NC-ROOM-003",
+  MESSAGE_TOO_LARGE: "NC-MSG-001",
+  MESSAGE_NOT_FOUND: "NC-MSG-002",
+  MESSAGE_EDIT_FORBID: "NC-MSG-003",
+  RATE_LIMITED: "NC-RATE-001"
+};
+var NoveraChatError = class _NoveraChatError extends Error {
+  code;
+  status;
+  details;
+  constructor(message, code = ErrorCode.INTERNAL, status = 0, details) {
+    super(message);
+    this.name = "NoveraChatError";
+    this.code = code;
+    this.status = status;
+    if (details !== void 0) this.details = details;
+  }
+  static fromResponse(status, body) {
+    const rec = body;
+    const code = rec?.error?.code ?? ErrorCode.INTERNAL;
+    const msg = rec?.error?.message ?? `HTTP ${status}`;
+    const details = rec?.error?.details;
+    return details !== void 0 ? new _NoveraChatError(msg, code, status, details) : new _NoveraChatError(msg, code, status);
+  }
+};
+
+// src/transport/http.ts
+var HttpClient = class {
+  constructor(opts) {
+    this.opts = opts;
+  }
+  opts;
+  async request(method, path, body, query) {
+    const token = await this.opts.tokenProvider();
+    const url = this.buildUrl(path, query);
+    const init = {
+      method,
+      headers: {
+        "Authorization": `Bearer ${token}`,
+        "X-Noverachat-App-Id": this.opts.appId,
+        ...body != null ? { "Content-Type": "application/json" } : {}
+      }
+    };
+    if (body != null) init.body = JSON.stringify(body);
+    const fetchFn = this.opts.fetch ?? globalThis.fetch;
+    this.opts.logger?.(
+      "debug",
+      `rest_req ${method} ${path}`,
+      body != null ? { body, query } : { query }
+    );
+    const startedAt = Date.now();
+    const res = await fetchFn(url, init);
+    const elapsedMs = Date.now() - startedAt;
+    if (res.status === 204) {
+      this.opts.logger?.(
+        "debug",
+        `rest_res ${method} ${path} 204 ${elapsedMs}ms`
+      );
+      return void 0;
+    }
+    const text = await res.text();
+    const parsed = text ? JSON.parse(text) : null;
+    this.opts.logger?.(
+      "debug",
+      `rest_res ${method} ${path} ${res.status} ${elapsedMs}ms`,
+      parsed
+    );
+    if (!res.ok) {
+      throw NoveraChatError.fromResponse(res.status, parsed);
+    }
+    return parsed;
+  }
+  buildUrl(path, query) {
+    const base = this.opts.baseUrl.replace(/\/+$/, "");
+    const url = new URL(base + path);
+    if (query) {
+      for (const [k, v] of Object.entries(query)) {
+        if (v !== void 0 && v !== null) url.searchParams.set(k, String(v));
+      }
+    }
+    return url.toString();
+  }
+};
+
+// src/transport/ws.ts
+var NO_RECONNECT = /* @__PURE__ */ new Set([1008, 4001, 4002, 4003]);
+var ReconnectingWs = class _ReconnectingWs {
+  constructor(opts) {
+    this.opts = opts;
+  }
+  opts;
+  ws = null;
+  state = "idle";
+  attempt = 0;
+  pingTimer = null;
+  explicitClose = false;
+  // Outbound buffer used while the socket is transiently down (reconnect
+  // window between a server-side close and the next successful open). FIFO.
+  // Capped to avoid an unbounded queue if the server is hard-down — chat_send
+  // bursts past the cap are dropped (caller sees `send -> false` the usual
+  // way). Pings and typing frames are NOT queued: pings are stateless
+  // heartbeats and a stale typing event is worse than no event.
+  outboundQueue = [];
+  static OUTBOUND_QUEUE_CAP = 200;
+  get currentState() {
+    return this.state;
+  }
+  async connect() {
+    this.explicitClose = false;
+    await this.openOnce();
+  }
+  close() {
+    this.explicitClose = true;
+    this.setState("closed");
+    if (this.pingTimer) clearInterval(this.pingTimer);
+    this.pingTimer = null;
+    this.outboundQueue = [];
+    this.ws?.close(1e3, "client close");
+    this.ws = null;
+  }
+  send(msg) {
+    if (this.ws && this.ws.readyState === 1) {
+      this.ws.send(JSON.stringify(msg));
+      this.opts.logger?.("debug", `ws_send ${msg.type}`, msg);
+      return true;
+    }
+    if (msg.type === "ping" || msg.type === "typing") return false;
+    if (this.explicitClose || this.state === "closed") return false;
+    if (this.outboundQueue.length >= _ReconnectingWs.OUTBOUND_QUEUE_CAP) {
+      this.opts.logger?.(
+        "warn",
+        "ws_outbound_queue_full",
+        { cap: _ReconnectingWs.OUTBOUND_QUEUE_CAP, dropping: msg.type }
+      );
+      return false;
+    }
+    this.outboundQueue.push(msg);
+    this.opts.logger?.(
+      "debug",
+      `ws_send_queued ${msg.type}`,
+      { queueLen: this.outboundQueue.length }
+    );
+    return true;
+  }
+  async openOnce() {
+    this.setState(this.attempt === 0 ? "connecting" : "reconnecting");
+    const WSImpl = this.opts.WebSocketImpl ?? globalThis.WebSocket;
+    if (!WSImpl) throw new Error("No WebSocket implementation available");
+    let url;
+    try {
+      url = await this.opts.urlBuilder();
+    } catch (err) {
+      this.opts.logger?.("error", "url_builder_failed", err);
+      this.scheduleReconnect();
+      return;
+    }
+    const ws = new WSImpl(url);
+    this.ws = ws;
+    ws.onopen = () => {
+      this.attempt = 0;
+      this.setState("open");
+      this.startPings();
+      if (this.outboundQueue.length > 0) {
+        const drained = this.outboundQueue;
+        this.outboundQueue = [];
+        this.opts.logger?.("info", "ws_outbound_drained", { count: drained.length });
+        for (const m of drained) {
+          try {
+            ws.send(JSON.stringify(m));
+          } catch (err) {
+            this.opts.logger?.("warn", "ws_outbound_drain_failed", err);
+          }
+        }
+      }
+      this.opts.onOpen?.();
+    };
+    ws.onmessage = (ev) => {
+      try {
+        const data = typeof ev.data === "string" ? ev.data : ev.data.toString();
+        const parsed = JSON.parse(data);
+        this.opts.logger?.(
+          "debug",
+          `ws_recv ${parsed.type ?? "?"}`,
+          parsed
+        );
+        this.opts.onMessage(parsed);
+      } catch (err) {
+        this.opts.logger?.("warn", "ws_parse_failed", err);
+      }
+    };
+    ws.onerror = (ev) => {
+      this.opts.logger?.("warn", "ws_error", ev);
+    };
+    ws.onclose = (ev) => {
+      this.stopPings();
+      this.ws = null;
+      if (this.explicitClose) {
+        this.setState("closed");
+        return;
+      }
+      if (NO_RECONNECT.has(ev.code)) {
+        this.opts.logger?.("warn", "ws_fatal_close", { code: ev.code, reason: ev.reason });
+        this.setState("closed");
+        return;
+      }
+      if (this.opts.autoReconnect) this.scheduleReconnect();
+      else this.setState("closed");
+    };
+  }
+  scheduleReconnect() {
+    this.attempt += 1;
+    const base = 500;
+    const cap = this.opts.maxReconnectDelayMs;
+    const exp = Math.min(cap, base * 2 ** (this.attempt - 1));
+    const jitter = Math.floor(Math.random() * base);
+    const delay = exp + jitter;
+    this.opts.logger?.("info", "ws_reconnect_scheduled", { attempt: this.attempt, delay });
+    this.setState("reconnecting");
+    setTimeout(() => {
+      void this.openOnce();
+    }, delay);
+  }
+  startPings() {
+    this.stopPings();
+    this.pingTimer = setInterval(() => {
+      this.send({ type: "ping", client_ts: Date.now() });
+    }, this.opts.pingIntervalMs);
+  }
+  stopPings() {
+    if (this.pingTimer) clearInterval(this.pingTimer);
+    this.pingTimer = null;
+  }
+  setState(s) {
+    if (s === this.state) return;
+    this.state = s;
+    this.opts.onStateChange?.(s);
+  }
+};
+
+// src/internal/event-bus.ts
+var EventBus = class {
+  handlers = {};
+  on(event, fn) {
+    let set = this.handlers[event];
+    if (!set) {
+      set = /* @__PURE__ */ new Set();
+      this.handlers[event] = set;
+    }
+    set.add(fn);
+    return () => this.off(event, fn);
+  }
+  off(event, fn) {
+    this.handlers[event]?.delete(fn);
+  }
+  emit(event, payload) {
+    const set = this.handlers[event];
+    if (!set) return;
+    for (const h of set) {
+      try {
+        h(payload);
+      } catch {
+      }
+    }
+  }
+  removeAll() {
+    this.handlers = {};
+  }
+};
+
+// src/internal/temp-id.ts
+function tempId() {
+  if (typeof crypto !== "undefined" && "randomUUID" in crypto) {
+    return `tmp_${crypto.randomUUID()}`;
+  }
+  const bytes = Array.from({ length: 16 }, () => Math.floor(Math.random() * 256));
+  return "tmp_" + bytes.map((b) => b.toString(16).padStart(2, "0")).join("");
+}
+
+// src/features/room.ts
+function toMessageOut(r) {
+  const dataObj = r.data ?? null;
+  const customMeta = dataObj && typeof dataObj === "object" && "_customMeta" in dataObj ? dataObj._customMeta : null;
+  return {
+    appId: r.app_id,
+    roomId: r.room_id,
+    messageId: r.message_id,
+    sender: r.sender ? {
+      userId: r.sender.user_id,
+      nickname: r.sender.nickname ?? null,
+      profileImageUrl: r.sender.profile_image_url ?? null
+    } : null,
+    senderId: r.sender_id ?? null,
+    messageType: r.message_type,
+    customType: r.custom_type ?? null,
+    content: r.content ?? null,
+    data: dataObj,
+    meta: r.meta ?? null,
+    customMeta,
+    fileId: r.file_id ?? null,
+    file: r.file ? {
+      id: r.file.id,
+      kind: r.file.kind,
+      mime: r.file.mime,
+      size: r.file.size,
+      name: r.file.name ?? null,
+      width: r.file.width ?? null,
+      height: r.file.height ?? null,
+      durationSec: r.file.duration_sec ?? null,
+      thumbnailStatus: r.file.thumbnail_status,
+      forwardBlocked: Boolean(r.file.forward_blocked)
+    } : null,
+    files: r.files && r.files.length > 0 ? r.files.map((f) => ({
+      id: f.id,
+      kind: f.kind,
+      mime: f.mime,
+      size: f.size,
+      name: f.name ?? null,
+      width: f.width ?? null,
+      height: f.height ?? null,
+      durationSec: f.duration_sec ?? null,
+      thumbnailStatus: f.thumbnail_status,
+      forwardBlocked: Boolean(f.forward_blocked)
+    })) : null,
+    replyToId: r.reply_to_id ?? null,
+    reactions: (r.reactions ?? []).map((x) => ({
+      key: x.key,
+      userIds: x.user_ids,
+      updatedAt: x.updated_at
+    })),
+    createdAt: r.created_at,
+    createdAtMs: r.created_at_ms,
+    updatedAt: r.updated_at ?? null,
+    updatedAtMs: r.updated_at_ms ?? null,
+    deletedAt: r.deleted_at ?? null,
+    deletedByUserId: r.deleted_by_user_id ?? null,
+    deleteScope: r.delete_scope ?? null,
+    editedCount: r.edited_count ?? 0
+  };
+}
+var Room = class _Room {
+  constructor(roomId, http, ws, readDebounceMs) {
+    this.roomId = roomId;
+    this.http = http;
+    this.ws = ws;
+    this.readDebounceMs = readDebounceMs;
+  }
+  roomId;
+  http;
+  ws;
+  bus = new EventBus();
+  // tempId → resolver pair. We keep `reject` alongside `resolve` so an
+  // incoming `error` frame carrying the offending temp_id (e.g.
+  // NC-RATE-001) can fail the send immediately rather than letting the
+  // 15s ack timeout fire — without correlation, a user hitting the
+  // per-tenant rate limit sees the chat hang on "PENDING…" forever.
+  //
+  // `payload` and `retries` enable transparent auto-retry of rate-limited
+  // sends: client.ts re-fires the same WS frame (same temp_id) with
+  // exponential backoff up to `MAX_RETRIES` instead of immediately failing
+  // the user's promise. Same temp_id keeps self-echo dedup correct in
+  // case the server actually processed the first attempt.
+  pendingAcks = /* @__PURE__ */ new Map();
+  // Retry policy for rate-limited (NC-RATE-001) sends. We cap at 1
+  // automatic retry — enough to swallow the normal jitter-induced spillover
+  // at the per-second token bucket boundary, but anything beyond that is
+  // a sustained rate-limit problem that the SDK shouldn't silently paper
+  // over. Subsequent failures bubble up to the caller so the UI can offer
+  // an explicit "Retry" button — manual retry is the right UX once we
+  // know the auto path didn't fix it.
+  // Backoff: ~300ms — long enough to land in a fresh 1s token bucket.
+  static MAX_RATE_LIMIT_RETRIES = 1;
+  static RATE_LIMIT_BACKOFF_MS = [300];
+  // Highest id we've sent via `read_watermark`. Used to drop redundant
+  // frames inside the debounce window. Compared via BigInt.
+  lastReadSent = null;
+  // Pending read_watermark — set by markRead, flushed after readDebounceMs
+  // OR immediately on flushMarkRead().
+  pendingReadMid = null;
+  readDebounceTimer = null;
+  readDebounceMs;
+  /**
+   * Every temp_id we've sent this session. The server echoes the same
+   * temp_id back on `chat_receive` for the sender's own sessions, so the
+   * client can dedup against its optimistic bubble regardless of whether
+   * the `ack` or the `chat_receive` arrives first. Unbounded growth is
+   * fine in practice (small strings, cleared on `chat.disconnect()`).
+   */
+  mySentTempIds = /* @__PURE__ */ new Set();
+  _sendPendingMarkRead() {
+    const mid = this.pendingReadMid;
+    if (!mid) return;
+    if (this.lastReadSent !== null) {
+      try {
+        if (BigInt(mid) <= BigInt(this.lastReadSent)) {
+          this.pendingReadMid = null;
+          return;
+        }
+      } catch {
+        if (mid <= this.lastReadSent) {
+          this.pendingReadMid = null;
+          return;
+        }
+      }
+    }
+    const ok = this.ws.send({
+      type: "read_watermark",
+      room_id: this.roomId,
+      last_read_message_id: mid
+    });
+    if (ok) {
+      this.lastReadSent = mid;
+      this.pendingReadMid = null;
+    }
+  }
+  // -------- outgoing --------
+  async send(params) {
+    const p = typeof params === "string" ? { content: params } : params;
+    const tempId2 = tempId();
+    const hasBundle = Array.isArray(p.fileIds) && p.fileIds.length > 0;
+    const messageType = p.messageType ?? (hasBundle || p.fileId ? "FILE" : "TEXT");
+    const baseData = p.data ?? {};
+    let outData = hasBundle ? {
+      ...baseData,
+      kind: "file_group",
+      file_ids: p.fileIds,
+      forward_blocked: Boolean(p.forwardBlocked)
+    } : p.data ?? null;
+    if (p.customMeta) {
+      outData = { ...outData ?? {}, _customMeta: p.customMeta };
+    }
+    const payload = {
+      type: "chat_send",
+      room_id: this.roomId,
+      message_type: messageType,
+      content: p.content ?? null,
+      custom_type: p.customType ?? null,
+      data: outData,
+      meta: p.meta ?? null,
+      // Bundle path sends file_id=null; the ids live in data.file_ids.
+      file_id: hasBundle ? null : p.fileId ?? null,
+      reply_to_id: p.replyToId ?? null,
+      forward_of_message_id: p.forwardOfMessageId ?? null,
+      temp_id: tempId2,
+      client_ts: Date.now()
+    };
+    this.mySentTempIds.add(tempId2);
+    const messageId = new Promise((resolve, reject) => {
+      const timer = setTimeout(() => {
+        this.pendingAcks.delete(tempId2);
+        this.mySentTempIds.delete(tempId2);
+        reject(new Error("ack timeout"));
+      }, 15e3);
+      this.pendingAcks.set(tempId2, {
+        resolve: (id) => {
+          clearTimeout(timer);
+          resolve(id);
+        },
+        reject: (err) => {
+          clearTimeout(timer);
+          reject(err);
+        },
+        payload,
+        retries: 0,
+        timer
+      });
+    });
+    const sent = this.ws.send(payload);
+    if (!sent) {
+      this.pendingAcks.delete(tempId2);
+      this.mySentTempIds.delete(tempId2);
+      throw new Error("ws not open");
+    }
+    return { tempId: tempId2, messageId };
+  }
+  /**
+   * Send an admin-uploaded emoticon as a STICKER-like message.
+   *
+   * Thin wrapper over ``send()``: stamps ``messageType: "EMOTICON"`` and
+   * fills ``data`` with the pack / item identifiers + a stable URL so the
+   * receiving client can render the bubble without a separate fetch.
+   *
+   * Pass either an ``EmoticonItem``-shaped object (matching the response
+   * of ``GET /v1/emoticon-packs``) or the raw ids + url. ``caption`` is
+   * optional — KakaoTalk-style sticker bubbles render fine without one.
+   */
+  async sendEmoticon(item, caption) {
+    return this.send({
+      content: caption ?? "",
+      messageType: "EMOTICON",
+      data: {
+        source: "emoticon",
+        pack_id: item.packId,
+        item_id: item.itemId,
+        file_id: item.fileId ?? "",
+        url: item.url
+      }
+    });
+  }
+  /**
+   * Send a file as a message. Wraps the three-step file pipeline:
+   *
+   *   1. ``POST /files`` to presign an S3 PUT
+   *   2. ``PUT`` the bytes direct to S3 (XHR — so we can report
+   *      progress; ``fetch`` has no upload progress event)
+   *   3. ``POST /files/{id}/commit`` to flip the row to ``committed``
+   *      and enqueue the thumbnail worker
+   *   4. ``room.send({ fileId, messageType: "FILE" })`` to broadcast
+   *      the message to the room
+   *
+   * Returns the same ``{ tempId, messageId }`` shape as ``send()`` —
+   * callers reconcile the optimistic bubble against the eventual ack
+   * the same way text messages do.
+   *
+   * On any error before the final ``send()`` (upload aborted, S3
+   * rejected, commit failed) the row in ``files`` stays at
+   * ``upload_status=pending`` and the background cleanup worker
+   * reclaims it within ``FILE_PENDING_UPLOAD_TTL_SEC`` (24h default)
+   * — no client-side cleanup needed.
+   */
+  async sendFile(file, opts = {}) {
+    const kind = opts.kind ?? (file.type.startsWith("image/") ? "image" : file.type.startsWith("video/") ? "video" : "file");
+    const name = opts.name ?? file.name;
+    const presign = await this.http.request("POST", "/api/v1/files", {
+      kind,
+      mime: file.type || "application/octet-stream",
+      size: file.size,
+      original_name: name,
+      // 파일 전달 제한 — uploader-set at presign time. When true,
+      // other users can't forward this file to a different room.
+      forward_blocked: Boolean(opts.forwardBlocked)
+    });
+    const presigned = {
+      fileId: presign.file_id,
+      uploadUrl: presign.upload_url,
+      headers: presign.headers,
+      expiresAtMs: presign.expires_at_ms
+    };
+    await new Promise((resolve, reject) => {
+      const xhr = new XMLHttpRequest();
+      xhr.open("PUT", presigned.uploadUrl);
+      for (const [k, v] of Object.entries(presigned.headers)) {
+        xhr.setRequestHeader(k, v);
+      }
+      if (opts.onProgress) {
+        xhr.upload.addEventListener("progress", (e) => {
+          if (!e.lengthComputable) return;
+          opts.onProgress({
+            loaded: e.loaded,
+            total: e.total,
+            ratio: e.total > 0 ? e.loaded / e.total : 0
+          });
+        });
+      }
+      xhr.onload = () => {
+        if (xhr.status >= 200 && xhr.status < 300) {
+          opts.onProgress?.({ loaded: file.size, total: file.size, ratio: 1 });
+          resolve();
+        } else {
+          reject(new Error(`S3 PUT failed: ${xhr.status} ${xhr.statusText}`));
+        }
+      };
+      xhr.onerror = () => reject(new Error("S3 PUT network error"));
+      xhr.onabort = () => reject(new Error("S3 PUT aborted"));
+      xhr.send(file);
+    });
+    await this.http.request(
+      "POST",
+      `/api/v1/files/${presigned.fileId}/commit`,
+      {}
+    );
+    const sendResult = await this.send({
+      fileId: presigned.fileId,
+      messageType: "FILE",
+      ...opts.customMeta ? { customMeta: opts.customMeta } : {}
+    });
+    return { ...sendResult, fileId: presigned.fileId };
+  }
+  /**
+   * Upload a file (presign → S3 PUT → commit) WITHOUT emitting a chat
+   * message. Returns the committed ``file_id`` so callers can gather
+   * several ids and bundle them into ONE ``room.send({ fileIds: [...] })``
+   * for the multi-file "file_group" message pattern.
+   *
+   * Same 3-step pipeline as ``sendFile()`` minus step 4. Errors before
+   * commit leave the file at ``upload_status=pending`` — the cleanup
+   * worker reclaims it within ``FILE_PENDING_UPLOAD_TTL_SEC``.
+   */
+  async uploadFileOnly(file, opts = {}) {
+    const kind = opts.kind ?? (file.type.startsWith("image/") ? "image" : file.type.startsWith("video/") ? "video" : "file");
+    const name = opts.name ?? file.name;
+    const presign = await this.http.request("POST", "/api/v1/files", {
+      kind,
+      mime: file.type || "application/octet-stream",
+      size: file.size,
+      original_name: name,
+      forward_blocked: Boolean(opts.forwardBlocked)
+    });
+    await new Promise((resolve, reject) => {
+      const xhr = new XMLHttpRequest();
+      xhr.open("PUT", presign.upload_url);
+      for (const [k, v] of Object.entries(presign.headers)) {
+        xhr.setRequestHeader(k, v);
+      }
+      if (opts.onProgress) {
+        xhr.upload.addEventListener("progress", (e) => {
+          if (!e.lengthComputable) return;
+          opts.onProgress({
+            loaded: e.loaded,
+            total: e.total,
+            ratio: e.total > 0 ? e.loaded / e.total : 0
+          });
+        });
+      }
+      xhr.onload = () => {
+        if (xhr.status >= 200 && xhr.status < 300) {
+          opts.onProgress?.({ loaded: file.size, total: file.size, ratio: 1 });
+          resolve();
+        } else {
+          reject(new Error(`S3 PUT failed: ${xhr.status} ${xhr.statusText}`));
+        }
+      };
+      xhr.onerror = () => reject(new Error("S3 PUT network error"));
+      xhr.onabort = () => reject(new Error("S3 PUT aborted"));
+      xhr.send(file);
+    });
+    await this.http.request(
+      "POST",
+      `/api/v1/files/${presign.file_id}/commit`,
+      {}
+    );
+    return presign.file_id;
+  }
+  /**
+   * List files shared in this room — newest-first, paginated.
+   *
+   * One entry per non-deleted message that carries a ``file_id`` —
+   * forwarded files (same file_id, multiple messages) appear once
+   * per occurrence. The history-visibility floor is applied so files
+   * attached to messages older than the caller's ``last_cleared_at``
+   * (or the post-rejoin cutoff for grouprooms) are filtered out.
+   *
+   * Use ``before`` with the smallest ``messageId`` of the previous
+   * page to paginate.
+   */
+  async listFiles(opts = {}) {
+    const raw = await this.http.request(
+      "GET",
+      `/api/v1/rooms/${encodeURIComponent(this.roomId)}/files`,
+      void 0,
+      {
+        limit: opts.limit ?? 50,
+        ...opts.before ? { before: opts.before } : {}
+      }
+    );
+    return {
+      items: raw.items.map((r) => ({
+        messageId: r.message_id,
+        senderId: r.sender_id,
+        createdAtMs: r.created_at_ms,
+        file: {
+          id: r.file.id,
+          kind: r.file.kind,
+          mime: r.file.mime,
+          size: r.file.size_bytes,
+          name: r.file.original_name ?? null,
+          width: r.file.width ?? null,
+          height: r.file.height ?? null,
+          durationSec: r.file.duration_sec ?? null,
+          thumbnailStatus: r.file.thumbnail_status,
+          forwardBlocked: Boolean(r.file.forward_blocked)
+        }
+      })),
+      nextCursor: raw.next_cursor,
+      hasMore: raw.has_more
+    };
+  }
+  markRead(messageId) {
+    if (this.pendingReadMid !== null) {
+      try {
+        if (BigInt(messageId) <= BigInt(this.pendingReadMid)) return;
+      } catch {
+        if (messageId <= this.pendingReadMid) return;
+      }
+    }
+    this.pendingReadMid = messageId;
+    if (this.readDebounceTimer) return;
+    this.readDebounceTimer = setTimeout(() => {
+      this.readDebounceTimer = null;
+      this._sendPendingMarkRead();
+    }, this.readDebounceMs);
+  }
+  /**
+   * Bypass the read_watermark debounce and send the pending watermark
+   * immediately. Use on critical UX boundaries (user leaves room,
+   * client disconnects, page unload) so the server's per-user unread
+   * count is correct by the time any other device / admin / push
+   * service queries it. No-op when nothing is pending.
+   */
+  flushMarkRead() {
+    if (this.readDebounceTimer) {
+      clearTimeout(this.readDebounceTimer);
+      this.readDebounceTimer = null;
+    }
+    this._sendPendingMarkRead();
+  }
+  setTyping(isTyping) {
+    this.ws.send({ type: "typing", room_id: this.roomId, is_typing: isTyping });
+  }
+  async edit(messageId, patch) {
+    return this.http.request(
+      "PUT",
+      `/api/v1/rooms/${this.roomId}/messages/${messageId}`,
+      patch
+    );
+  }
+  async delete(messageId, scope = "ALL") {
+    await this.http.request(
+      "DELETE",
+      `/api/v1/rooms/${this.roomId}/messages/${messageId}`,
+      void 0,
+      { scope }
+    );
+  }
+  /** Per-user "Clear chat". Hides every existing message in this room
+   *  from the calling user (via `room_members.last_cleared_at = now()`).
+   *  Other members are unaffected — this is local history hiding, not
+   *  a destructive bulk delete. Irreversible from the caller's side. */
+  async clearHistory() {
+    await this.http.request(
+      "POST",
+      `/api/v1/rooms/${this.roomId}/clear`
+    );
+  }
+  /** Leave this room (self). Deletes the caller's membership row — the room
+   *  drops out of `unreadSummary()` and they stop receiving its messages.
+   *  Other members get a `MEMBER_LEFT` [`roomEvent`](../reference/noverachat.md#events).
+   *  Idempotent if already a non-member; throws 409 if the caller was KICKED
+   *  (ask an operator to restore first). For GROUP/SUPER_GROUP, re-entry needs
+   *  an operator add; for ONE, re-creating the 1:1 rejoins with history kept. */
+  async leave() {
+    await this.http.request(
+      "POST",
+      `/api/v1/rooms/${this.roomId}/leave`
+    );
+  }
+  /**
+   * Set the caller's per-room push preference — like long-pressing a
+   * chat and tapping "notifications off".
+   *   "ALL"          — push for every message (default)
+   *   "MENTION_ONLY" — push only when the message @-mentions the caller
+   *   "OFF"          — mute this room's push entirely
+   * Scoped to the calling user; throws if they're not a room member.
+   */
+  async setPushTrigger(trigger) {
+    await this.http.request(
+      "PATCH",
+      `/api/v1/rooms/${this.roomId}/push-trigger`,
+      { push_trigger: trigger }
+    );
+  }
+  /**
+   * **DESTRUCTIVE, operator-only.** Soft-deletes every currently-undeleted
+   * message in the room — visible to all members instantly via a
+   * `messagesCleared` event (subscribe via `room.on("messagesCleared", ...)`).
+   * Server enforces the operator check; throws 403 for regular members.
+   * Returns the cleared count plus the cutoff `message_id` so callers can
+   * hide rendered messages up to (and including) that id.
+   */
+  async deleteAllMessages() {
+    const raw = await this.http.request("DELETE", `/api/v1/rooms/${this.roomId}/messages`);
+    return {
+      cleared: raw.cleared,
+      upToMessageId: raw.up_to_message_id
+    };
+  }
+  async react(messageId, key) {
+    await this.http.request(
+      "POST",
+      `/api/v1/rooms/${this.roomId}/messages/${messageId}/reactions`,
+      { key }
+    );
+  }
+  async unreact(messageId, key) {
+    await this.http.request(
+      "DELETE",
+      `/api/v1/rooms/${this.roomId}/messages/${messageId}/reactions/${encodeURIComponent(key)}`
+    );
+  }
+  async listSince(sinceMessageId, limit = 100) {
+    const raw = await this.http.request("GET", `/api/v1/rooms/${this.roomId}/messages`, void 0, {
+      since: String(sinceMessageId),
+      limit
+    });
+    return {
+      items: raw.items.map(toMessageOut),
+      nextCursor: raw.next_cursor,
+      hasMore: raw.has_more
+    };
+  }
+  /**
+   * Load the latest `limit` messages of the room — what to render when the
+   * user just opens the chat. Returns ASC (oldest → newest within the
+   * page) so callers don't need to reverse. Use `room.listBefore(cursor)`
+   * to paginate further back.
+   */
+  async listRecent(limit = 50) {
+    const raw = await this.http.request("GET", `/api/v1/rooms/${this.roomId}/messages`, void 0, { limit });
+    return {
+      items: raw.items.map(toMessageOut),
+      nextCursor: raw.next_cursor,
+      hasMore: raw.has_more
+    };
+  }
+  /**
+   * Scrollback. Fetches the page of `limit` messages immediately preceding
+   * `beforeMessageId` (exclusive), in ASC order. The returned
+   * `nextCursor` is the oldest id in this page — feed it back to keep
+   * scrolling up.
+   */
+  async listBefore(beforeMessageId, limit = 50) {
+    const raw = await this.http.request("GET", `/api/v1/rooms/${this.roomId}/messages`, void 0, {
+      before: beforeMessageId,
+      limit
+    });
+    return {
+      items: raw.items.map(toMessageOut),
+      nextCursor: raw.next_cursor,
+      hasMore: raw.has_more
+    };
+  }
+  /** Phase D #2 — 방 내 메시지 검색.
+   *
+   * ``content`` 필드에 대한 대소문자 무시 부분 문자열 매칭 (ILIKE). 삭제된
+   * 메시지는 제외. 결과는 최신순 (message_id DESC) 으로 반환되고, ``before``
+   * 커서로 뒤로 페이지네이션. 스티커/파일/이모티콘 등 ``content`` 가 없는
+   * 메시지는 검색 대상 X.
+   *
+   * @param q 검색어 (필수, 1~200자, whitespace-only 는 서버가 빈 결과 반환)
+   * @param opts.before 이전 페이지 마지막 message_id (다음 페이지 커서)
+   * @param opts.limit 페이지 크기 (기본 30, 최대 100)
+   */
+  async search(q, opts) {
+    const params = {
+      q,
+      limit: opts?.limit ?? 30
+    };
+    if (opts?.before) params.before = opts.before;
+    const raw = await this.http.request("GET", `/api/v1/rooms/${this.roomId}/messages/search`, void 0, params);
+    return {
+      items: raw.items.map(toMessageOut),
+      nextCursor: raw.next_cursor,
+      hasMore: raw.has_more
+    };
+  }
+  /** List this room's members (with each one's role). Handy for UIs that
+   *  want to conditionally enable destructive operator-only actions like
+   *  `room.deleteAllMessages()`. Server gates by membership for non-public
+   *  rooms, so the caller must already be a member to read this.
+   */
+  async listMembers() {
+    const raw = await this.http.request("GET", `/api/v1/rooms/${this.roomId}/members`);
+    return raw.map((m) => ({
+      userId: m.user_id,
+      nickname: m.nickname ?? null,
+      role: m.role,
+      pushTrigger: m.push_trigger,
+      lastReadMessageId: m.last_read_message_id,
+      joinedAt: m.joined_at,
+      isOnline: m.is_online ?? null,
+      mutedUntil: m.muted_until ?? null
+    }));
+  }
+  // -------- mute --------
+  /** OPERATOR-only: mute a member so they can't send messages in this
+   *  room. `durationMinutes=null` → indefinite (until an explicit unmute).
+   *  Emits a `MEMBER_MUTED` [`roomEvent`](../reference/noverachat.md#events)
+   *  + a SYSTEM chat message. Non-operator callers get 403. Server also
+   *  refuses self-mute and muting another OPERATOR. */
+  async muteMember(userId, durationMinutes) {
+    await this.http.request(
+      "POST",
+      `/api/v1/rooms/${this.roomId}/members/${encodeURIComponent(userId)}/mute`,
+      { duration_minutes: durationMinutes }
+    );
+  }
+  /** OPERATOR-only: clear a member's mute. Idempotent — no-op + no
+   *  broadcast when the target wasn't muted. Emits a `MEMBER_UNMUTED`
+   *  roomEvent + SYSTEM chat message otherwise. */
+  async unmuteMember(userId) {
+    await this.http.request(
+      "POST",
+      `/api/v1/rooms/${this.roomId}/members/${encodeURIComponent(userId)}/unmute`
+    );
+  }
+  /** Server-side unread state for this room: exact COUNT(*) of messages
+   *  newer than the caller's `read_watermark`, plus the room's
+   *  `last_message_id` so the UI can show a "•" dot regardless of count. */
+  async unread() {
+    const raw = await this.http.request("GET", `/api/v1/rooms/${this.roomId}/unread`);
+    return {
+      roomId: raw.room_id,
+      unreadCount: raw.unread_count,
+      lastReadMessageId: raw.last_read_message_id,
+      lastMessageId: raw.last_message_id
+    };
+  }
+  // -------- freeze --------
+  /** OPERATOR-only moderation: freeze this room. Non-admin messages are
+   *  blocked server-side with NC-ROOM-FROZEN while frozen. All members'
+   *  clients receive a `roomEvent` with `event: "ROOM_FROZEN"` in real
+   *  time, plus a SYSTEM chat message "방이 얼려졌습니다."
+   *  Idempotent — no-op if already frozen. Non-operator callers get 403. */
+  async freeze() {
+    await this.http.request(
+      "POST",
+      `/api/v1/rooms/${this.roomId}/freeze`
+    );
+  }
+  /** Mirror of `freeze()` — reopens the room to chat_send. Emits a
+   *  `ROOM_UNFROZEN` roomEvent + a "방이 녹여졌습니다." SYSTEM message. */
+  async unfreeze() {
+    await this.http.request(
+      "POST",
+      `/api/v1/rooms/${this.roomId}/unfreeze`
+    );
+  }
+  /** OPERATOR-only: toggle room visibility. `true` → 공개방 (open chat,
+   *  anyone can join). `false` → 비공개방 (invite-only, join requires
+   *  approval). Auto-inserts a SYSTEM chat message and broadcasts a
+   *  `ROOM_VISIBILITY_CHANGED` roomEvent so peers update in real time. */
+  async setPublic(isPublic) {
+    await this.http.request(
+      "PATCH",
+      `/api/v1/rooms/${this.roomId}/visibility`,
+      { is_public: isPublic }
+    );
+  }
+  // -------- announcements --------
+  async listAnnouncements() {
+    const raw = await this.http.request("GET", `/api/v1/rooms/${this.roomId}/announcements`);
+    return raw.map((a) => ({
+      id: a.id,
+      roomId: a.room_id,
+      content: a.content,
+      createdBy: a.created_by,
+      createdAt: a.created_at,
+      updatedAt: a.updated_at
+    }));
+  }
+  async getCurrentAnnouncement() {
+    const raw = await this.http.request("GET", `/api/v1/rooms/${this.roomId}/announcements/current`);
+    if (!raw) return null;
+    return {
+      id: raw.id,
+      roomId: raw.room_id,
+      content: raw.content,
+      createdBy: raw.created_by,
+      createdAt: raw.created_at,
+      updatedAt: raw.updated_at
+    };
+  }
+  async postAnnouncement(content) {
+    const raw = await this.http.request("POST", `/api/v1/rooms/${this.roomId}/announcements`, { content });
+    return {
+      id: raw.id,
+      roomId: raw.room_id,
+      content: raw.content,
+      createdBy: raw.created_by,
+      createdAt: raw.created_at,
+      updatedAt: raw.updated_at
+    };
+  }
+  async updateAnnouncement(id, content) {
+    const raw = await this.http.request("PATCH", `/api/v1/rooms/${this.roomId}/announcements/${id}`, { content });
+    return {
+      id: raw.id,
+      roomId: raw.room_id,
+      content: raw.content,
+      createdBy: raw.created_by,
+      createdAt: raw.created_at,
+      updatedAt: raw.updated_at
+    };
+  }
+  async deleteAnnouncement(id) {
+    await this.http.request(
+      "DELETE",
+      `/api/v1/rooms/${this.roomId}/announcements/${id}`
+    );
+  }
+  // -------- invite links --------
+  /**
+   * OPERATOR-only: mint a new invite link for this room. Default:
+   * expires in 7 days, unlimited uses. Pass `expiresInHours: null`
+   * for a link that never expires, or `maxUses: 1` for a one-shot.
+   *
+   * Returns the raw `InviteToken` — build the shareable URL yourself
+   * (e.g. `${location.origin}/#invite/${token.token}`) so you control
+   * the format your app uses to consume it.
+   */
+  async createInvite(opts) {
+    const body = {};
+    if (opts && "expiresInHours" in opts) body.expires_in_hours = opts.expiresInHours;
+    if (opts && "maxUses" in opts) body.max_uses = opts.maxUses;
+    const raw = await this.http.request("POST", `/api/v1/rooms/${this.roomId}/invites`, body);
+    return {
+      token: raw.token,
+      roomId: raw.room_id,
+      createdBy: raw.created_by,
+      createdAt: raw.created_at,
+      expiresAt: raw.expires_at,
+      maxUses: raw.max_uses,
+      usedCount: raw.used_count,
+      revokedAt: raw.revoked_at
+    };
+  }
+  /** OPERATOR-only: list all invite tokens for this room (including
+   *  revoked / expired / exhausted), newest first. */
+  async listInvites() {
+    const raw = await this.http.request("GET", `/api/v1/rooms/${this.roomId}/invites`);
+    return raw.map((r) => ({
+      token: r.token,
+      roomId: r.room_id,
+      createdBy: r.created_by,
+      createdAt: r.created_at,
+      expiresAt: r.expires_at,
+      maxUses: r.max_uses,
+      usedCount: r.used_count,
+      revokedAt: r.revoked_at
+    }));
+  }
+  /** OPERATOR-only: revoke a token immediately. Idempotent — revoking
+   *  an already-revoked token returns 204 as well. */
+  async revokeInvite(token) {
+    await this.http.request(
+      "DELETE",
+      `/api/v1/rooms/${this.roomId}/invites/${encodeURIComponent(token)}`
+    );
+  }
+  // -------- internal dispatch --------
+  on(event, fn) {
+    return this.bus.on(event, fn);
+  }
+  off(event, fn) {
+    this.bus.off(event, fn);
+  }
+  _dispatchAnnouncement(msg) {
+    this.bus.emit("announcement", msg);
+  }
+  _dispatchAck(tempId2, messageId) {
+    if (!tempId2) return;
+    const entry = this.pendingAcks.get(tempId2);
+    if (entry) {
+      entry.resolve(messageId);
+      this.pendingAcks.delete(tempId2);
+      this.mySentTempIds.delete(tempId2);
+      this.bus.emit("ack", { tempId: tempId2, messageId });
+    }
+  }
+  /** True iff this room has a still-pending send with this temp_id. */
+  _hasPendingTempId(tempId2) {
+    return this.pendingAcks.has(tempId2);
+  }
+  /** Reject the pending send for tempId with the given error. Used by the
+   *  client when a server `error` frame echoes back our temp_id so we can
+   *  fail the matching outbound promise immediately instead of waiting
+   *  for the 15s ack timeout. */
+  _rejectPending(tempId2, err) {
+    const entry = this.pendingAcks.get(tempId2);
+    if (!entry) return;
+    entry.reject(err);
+    this.pendingAcks.delete(tempId2);
+    this.mySentTempIds.delete(tempId2);
+  }
+  /**
+   * Try to re-send a pending frame after a transient server reject
+   * (currently only NC-RATE-001 — the tenant's per-second token bucket
+   * spilled). Reuses the same temp_id so:
+   *   1. ack matching on success still works,
+   *   2. self-echo dedup still recognizes the frame as ours,
+   *   3. *if* the server's first attempt secretly succeeded (we got an
+   *      error frame but the message was already persisted) the second
+   *      attempt's `chat_receive` self-echo collapses cleanly.
+   *
+   * Returns true if a retry was scheduled; false if we've already used
+   * up the retry budget and the caller should fall back to rejecting
+   * the promise.
+   */
+  _retryPending(tempId2) {
+    const entry = this.pendingAcks.get(tempId2);
+    if (!entry) return false;
+    if (entry.retries >= _Room.MAX_RATE_LIMIT_RETRIES) return false;
+    const idx = entry.retries;
+    entry.retries += 1;
+    const delay = _Room.RATE_LIMIT_BACKOFF_MS[idx] ?? 1200;
+    setTimeout(() => {
+      if (!this.pendingAcks.has(tempId2)) return;
+      const ok = this.ws.send(entry.payload);
+      if (!ok) {
+        this._rejectPending(tempId2, new Error("ws closed during retry"));
+      }
+    }, delay);
+    return true;
+  }
+  /** True if this room originated a `chat_send` with the given temp_id
+   *  during the current session. Used by the client dispatcher to detect
+   *  self-echo chat_receive frames. */
+  _isMySentTempId(tempId2) {
+    return this.mySentTempIds.has(tempId2);
+  }
+  /** Forget a self-sent temp_id once both the ack and the echo are reconciled. */
+  _forgetMySentTempId(tempId2) {
+    this.mySentTempIds.delete(tempId2);
+  }
+  _dispatchInbound(msg) {
+    switch (msg.type) {
+      case "chat_receive":
+        this.bus.emit("message", msg);
+        return;
+      case "message_updated":
+        this.bus.emit("messageUpdated", msg);
+        return;
+      case "message_deleted":
+        this.bus.emit("messageDeleted", msg);
+        return;
+      case "messages_cleared":
+        this.bus.emit("messagesCleared", msg);
+        return;
+      case "reaction_added":
+        this.bus.emit("reactionAdded", msg);
+        return;
+      case "reaction_removed":
+        this.bus.emit("reactionRemoved", msg);
+        return;
+      case "sync_tick":
+        this.bus.emit("syncTick", msg);
+        return;
+      case "typing":
+        this.bus.emit("typing", msg);
+        return;
+    }
+  }
+};
+
+// src/client.ts
+function idGreater(a, b) {
+  if (!a) return false;
+  if (!b) return true;
+  try {
+    return BigInt(a) > BigInt(b);
+  } catch {
+    return a > b;
+  }
+}
+var NoveraChat = class {
+  constructor(opts) {
+    this.opts = opts;
+    if (!opts.appId) throw new Error("appId required");
+    if (!opts.endpoint) throw new Error("endpoint required");
+    if (!opts.tokenProvider) throw new Error("tokenProvider required");
+    this.readDebounceMs = opts.readWatermarkDebounceMs ?? 400;
+    this.logger = opts.logger;
+    if (opts.initialLastMessageIds) {
+      for (const [roomId, id] of Object.entries(opts.initialLastMessageIds)) {
+        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) {
+          void this.backfillAllRooms();
+        } else {
+          this.connectedOnce = true;
+        }
+      },
+      onStateChange: (s) => this.logger?.("info", `ws_state=${s}`),
+      autoReconnect: opts.autoReconnect ?? true,
+      pingIntervalMs: opts.pingIntervalMs ?? 2e4,
+      maxReconnectDelayMs: opts.maxReconnectDelayMs ?? 3e4,
+      ...opts.WebSocketImpl ? { WebSocketImpl: opts.WebSocketImpl } : {},
+      ...opts.logger ? { logger: opts.logger } : {}
+    });
+  }
+  opts;
+  http;
+  ws;
+  rooms = /* @__PURE__ */ new Map();
+  bus = new EventBus();
+  readDebounceMs;
+  logger;
+  connectedOnce = false;
+  lastMessageIdByRoom = /* @__PURE__ */ new Map();
+  /** 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. */
+  lastPresenceKey = null;
+  async connect() {
+    await this.ws.connect();
+  }
+  disconnect() {
+    this.ws.close();
+    this.rooms.clear();
+  }
+  room(roomId) {
+    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(event, fn) {
+    return this.bus.on(event, fn);
+  }
+  off(event, fn) {
+    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() {
+    await this.backfillAllRooms();
+  }
+  /** Highest `message_id` the client has seen for a given room, or null. */
+  lastSeenMessageId(roomId) {
+    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, messageId) {
+    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() {
+    const raw = await this.http.request("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) {
+    const raw = await this.http.request("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() {
+    const raw = await this.http.request("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, enabled) {
+    await this.http.request(
+      "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) {
+    await this.http.request(
+      "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() {
+    const raw = await this.http.request(
+      "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) {
+    const raw = await this.http.request(
+      "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, reason) {
+    const raw = await this.http.request(
+      "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) {
+    await this.http.request(
+      "DELETE",
+      `/api/v1/users/me/blocks/${encodeURIComponent(userId)}`
+    );
+  }
+  /** List every user the caller has blocked, newest first. */
+  async listBlocks() {
+    const raw = await this.http.request("GET", "/api/v1/users/me/blocks");
+    return raw.map((r) => ({
+      blockedUserId: r.blocked_user_id,
+      reason: r.reason,
+      createdAt: r.created_at
+    }));
+  }
+  _toDeviceInfo(raw) {
+    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, token) {
+    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, token) {
+    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) {
+    const raw = await this.http.request("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() {
+    const raw = await this.http.request("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) {
+    const raw = await this.http.request("POST", `/api/v1/invites/${encodeURIComponent(token)}/accept`);
+    return {
+      roomId: raw.room_id,
+      roomName: raw.room_name,
+      wasAlreadyMember: raw.was_already_member
+    };
+  }
+  // ---- internal ----
+  dispatch(msg) {
+    switch (msg.type) {
+      case "connected":
+        return;
+      case "pong":
+        return;
+      case "error": {
+        this.logger?.("warn", "ws_error_frame", msg);
+        const tempId2 = msg.details && typeof msg.details === "object" ? msg.details.temp_id : void 0;
+        if (typeof tempId2 === "string" && tempId2.length > 0) {
+          let target = null;
+          for (const room of this.rooms.values()) {
+            if (room._hasPendingTempId(tempId2)) {
+              target = room;
+              break;
+            }
+          }
+          if (target) {
+            const code = msg.code || "WS_ERROR";
+            if (code === "NC-RATE-001" && target._retryPending(tempId2)) {
+              this.logger?.("info", "ws_send_retry_scheduled", {
+                temp_id: tempId2,
+                code
+              });
+              return;
+            }
+            const details = msg.details ?? void 0;
+            const err = details !== void 0 ? new NoveraChatError(
+              msg.message || "server rejected frame",
+              code,
+              0,
+              details
+            ) : new NoveraChatError(
+              msg.message || "server rejected frame",
+              code
+            );
+            target._rejectPending(tempId2, err);
+          }
+        }
+        return;
+      }
+      case "close_notice":
+        this.logger?.("warn", "ws_close_notice", msg);
+        return;
+      case "room_event": {
+        this.bus.emit("roomEvent", msg);
+        return;
+      }
+      case "presence": {
+        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": {
+        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 : void 0;
+        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);
+        }
+        if (msg.type === "chat_receive") {
+          const tid = msg.temp_id ?? null;
+          if (tid && room._isMySentTempId(tid)) {
+            room._dispatchAck(tid, msg.message_id);
+            room._forgetMySentTempId(tid);
+            return;
+          }
+        }
+        room._dispatchInbound(msg);
+      }
+    }
+  }
+  highestKnownMessageId() {
+    let max = null;
+    for (const v of this.lastMessageIdByRoom.values()) {
+      if (idGreater(v, max)) max = v;
+    }
+    return max;
+  }
+  async backfillAllRooms() {
+    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) {
+          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;
+        }
+      }
+    }
+  }
+};
+// Annotate the CommonJS export names for ESM import in node:
+0 && (module.exports = {
+  ErrorCode,
+  NoveraChat,
+  NoveraChatError,
+  Room
+});