@noverachat/sdk-web 0.0.3

package/src/features/room.ts

@@ -0,0 +1,1292 @@
+/**
+ * Room — feature-level facade bound to a single room_id.
+ *
+ * Responsibilities:
+ *  - Optimistic send with temp_id swap on ack
+ *  - Read-watermark debouncing
+ *  - Typed emit of server events filtered to this room
+ *  - Gap-fill on demand via REST
+ */
+
+import type { HttpClient } from "../transport/http.js";
+import type { ReconnectingWs } from "../transport/ws.js";
+import type {
+  Announcement,
+  DeleteScope,
+  FileKind,
+  FileMeta,
+  FilePresignResponse,
+  InviteToken,
+  MessageIdStr,
+  MessageOut,
+  RoomUnread,
+  SendFileOptions,
+  SendParams,
+  WsAnnouncementEvent,
+  WsChatReceive,
+  WsMessageDeleted,
+  WsMessagesCleared,
+  WsMessageUpdated,
+  WsReactionAdded,
+  WsReactionRemoved,
+  WsSyncTick,
+  WsTypingBroadcast,
+} from "../types.js";
+import { EventBus } from "../internal/event-bus.js";
+import { tempId as newTempId } from "../internal/temp-id.js";
+// Note: previously used `utils/debounce`, replaced with a hand-rolled
+// timer in Room so we can also expose `flushMarkRead()` — the util has
+// no flush primitive.
+
+// Shape coming off the wire from /api/v1/rooms/{id}/messages — backend is
+// Pydantic v2 with snake_case AND serializes 63-bit ids as JSON strings
+// (see `MsgId` on the server). Kept private to this module; callers see
+// the camelCase MessageOut exported from types.ts with string ids.
+interface RawMessageOut {
+  app_id: string;
+  room_id: string;
+  message_id: string;
+  sender: { user_id: string; nickname?: string | null; profile_image_url?: string | null } | null;
+  sender_id: string | null;
+  message_type: MessageOut["messageType"];
+  custom_type?: string | null;
+  content?: string | null;
+  data?: Record<string, unknown> | null;
+  meta?: Record<string, unknown> | null;
+  file_id?: string | null;
+  file?: {
+    id: string;
+    kind: "image" | "video" | "file";
+    mime: string;
+    size: number;
+    name?: string | null;
+    width?: number | null;
+    height?: number | null;
+    duration_sec?: number | null;
+    thumbnail_status: "pending" | "ready" | "failed" | "skipped";
+    forward_blocked?: boolean;
+  } | null;
+  files?: Array<{
+    id: string;
+    kind: "image" | "video" | "file";
+    mime: string;
+    size: number;
+    name?: string | null;
+    width?: number | null;
+    height?: number | null;
+    duration_sec?: number | null;
+    thumbnail_status: "pending" | "ready" | "failed" | "skipped";
+    forward_blocked?: boolean;
+  }> | null;
+  reply_to_id?: string | null;
+  reactions?: Array<{ key: string; user_ids: string[]; updated_at: number }>;
+  created_at: string;
+  created_at_ms: number;
+  updated_at?: string | null;
+  updated_at_ms?: number | null;
+  deleted_at?: string | null;
+  deleted_by_user_id?: string | null;
+  delete_scope?: MessageOut["deleteScope"] | null;
+  edited_count?: number;
+}
+
+function toMessageOut(r: RawMessageOut): MessageOut {
+  // Phase D #11 — extract sender-attached `_customMeta` from `data`.
+  // Backend stores the whole `data` blob untouched, so both self-sent
+  // and received messages surface `customMeta` here for the caller.
+  const dataObj = r.data ?? null;
+  const customMeta =
+    dataObj && typeof dataObj === "object" && "_customMeta" in dataObj
+      ? ((dataObj as Record<string, unknown>)._customMeta as
+          | Record<string, unknown>
+          | null)
+      : 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,
+  };
+}
+
+// On-wire shape of an outbound chat_send. Kept private to this module —
+// callers use `Room.send({...})` which builds this for them. We store the
+// built payload in pendingAcks so an auto-retry on NC-RATE-001 can reuse
+// the exact same frame (same temp_id, same client_ts) without the caller
+// having to provide it again.
+interface ChatSendPayload {
+  type: "chat_send";
+  room_id: string;
+  message_type: "TEXT" | "FILE" | "EMOTICON";
+  content: string | null;
+  custom_type: string | null;
+  data: Record<string, unknown> | null;
+  meta: Record<string, unknown> | null;
+  file_id: MessageIdStr | null;
+  reply_to_id: MessageIdStr | null;
+  forward_of_message_id: MessageIdStr | null;
+  temp_id: string;
+  client_ts: number;
+}
+
+export interface RoomEvents {
+  message: WsChatReceive;
+  messageUpdated: WsMessageUpdated;
+  messageDeleted: WsMessageDeleted;
+  /** Operator (or super-admin) wiped the room. Hide every locally-rendered
+   *  message with `message_id <= up_to_message_id`. */
+  messagesCleared: WsMessagesCleared;
+  reactionAdded: WsReactionAdded;
+  reactionRemoved: WsReactionRemoved;
+  syncTick: WsSyncTick;
+  typing: WsTypingBroadcast;
+  ack: { tempId: string; messageId: MessageIdStr };
+  announcement: WsAnnouncementEvent;
+}
+
+export class Room {
+  private bus = new EventBus<RoomEvents>();
+  // 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.
+  private pendingAcks = new Map<string, {
+    resolve: (messageId: MessageIdStr) => void;
+    reject: (err: Error) => void;
+    payload: ChatSendPayload;
+    retries: number;
+    timer: ReturnType<typeof setTimeout>;  // 15s ack-timeout handle
+  }>();
+  // 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.
+  private static readonly MAX_RATE_LIMIT_RETRIES = 1;
+  private static readonly 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.
+  private lastReadSent: MessageIdStr | null = null;
+  // Pending read_watermark — set by markRead, flushed after readDebounceMs
+  // OR immediately on flushMarkRead().
+  private pendingReadMid: MessageIdStr | null = null;
+  private readDebounceTimer: ReturnType<typeof setTimeout> | null = null;
+  private readDebounceMs: number;
+  /**
+   * 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()`).
+   */
+  private mySentTempIds = new Set<string>();
+
+  constructor(
+    public readonly roomId: string,
+    private http: HttpClient,
+    private ws: ReconnectingWs,
+    readDebounceMs: number,
+  ) {
+    this.readDebounceMs = readDebounceMs;
+  }
+
+  private _sendPendingMarkRead(): void {
+    const mid = this.pendingReadMid;
+    if (!mid) return;
+    // BigInt monotonic guard — `lastReadSent` may be a 19-digit string,
+    // numeric `>` is wrong (lexicographic for unequal lengths).
+    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: string | SendParams,
+  ): Promise<{ tempId: string; messageId: Promise<MessageIdStr> }> {
+    const p: SendParams = typeof params === "string" ? { content: params } : params;
+    const tempId = newTempId();
+    // Multi-file bundle path — encode the list of file ids inside
+    // ``data.file_ids`` (with ``kind = "file_group"``) so the whole
+    // send stays ONE message. Auto-promotes messageType to FILE. When
+    // both ``fileIds`` and ``fileId`` are provided the bundle wins.
+    const hasBundle = Array.isArray(p.fileIds) && p.fileIds.length > 0;
+    // Auto-promote to FILE message type when a fileId or bundle is
+    // attached — the caller no longer has to remember the messageType.
+    const messageType: "TEXT" | "FILE" | "EMOTICON" =
+      p.messageType ?? (hasBundle || p.fileId ? "FILE" : "TEXT");
+    const baseData: Record<string, unknown> =
+      (p.data as Record<string, unknown> | undefined) ?? {};
+    let outData: Record<string, unknown> | null = hasBundle
+      ? {
+          ...baseData,
+          kind: "file_group",
+          file_ids: p.fileIds as MessageIdStr[],
+          forward_blocked: Boolean(p.forwardBlocked),
+        }
+      : (p.data ?? null);
+    // Phase D #11 — merge client-supplied custom metadata under a reserved
+    // `_customMeta` key in `data`. Backend passes the whole `data` blob
+    // through untouched, so receiving clients read it back via
+    // `MessageOut.customMeta` (see `toMessageOut`).
+    if (p.customMeta) {
+      outData = { ...(outData ?? {}), _customMeta: p.customMeta };
+    }
+    const payload = {
+      type: "chat_send" as const,
+      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: tempId,
+      client_ts: Date.now(),
+    };
+    this.mySentTempIds.add(tempId);
+    const messageId = new Promise<MessageIdStr>((resolve, reject) => {
+      const timer = setTimeout(() => {
+        this.pendingAcks.delete(tempId);
+        this.mySentTempIds.delete(tempId);
+        reject(new Error("ack timeout"));
+      }, 15_000);
+      this.pendingAcks.set(tempId, {
+        resolve: (id: MessageIdStr) => {
+          clearTimeout(timer);
+          resolve(id);
+        },
+        reject: (err: Error) => {
+          clearTimeout(timer);
+          reject(err);
+        },
+        payload,
+        retries: 0,
+        timer,
+      });
+    });
+    const sent = this.ws.send(payload);
+    if (!sent) {
+      this.pendingAcks.delete(tempId);
+      this.mySentTempIds.delete(tempId);
+      throw new Error("ws not open");
+    }
+    return { tempId, 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: {
+      packId:  string;
+      itemId:  string;
+      fileId?: string;
+      url:     string;
+    },
+    caption?: string,
+  ): Promise<{ tempId: string; messageId: Promise<MessageIdStr> }> {
+    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: File,
+    opts: SendFileOptions = {},
+  ): Promise<{
+    tempId: string;
+    messageId: Promise<MessageIdStr>;
+    /** Snowflake id of the just-committed file row. Useful when the
+     *  caller renders an optimistic bubble with a placeholder and
+     *  wants to swap in the real thumbnail / download URL as soon as
+     *  the upload finishes (without waiting for the chat_receive
+     *  echo, which the SDK suppresses for self-sent messages). */
+    fileId: MessageIdStr;
+  }> {
+    // Derive kind from MIME if the caller didn't pin one. Anything that
+    // isn't recognisably image/video falls into the generic "file"
+    // bucket — the server-side allowlist is what actually enforces
+    // what's renderable.
+    const kind: FileKind =
+      opts.kind
+      ?? (file.type.startsWith("image/")
+        ? "image"
+        : file.type.startsWith("video/")
+        ? "video"
+        : "file");
+    const name = opts.name ?? file.name;
+
+    // Step 1 — presign. The backend assigns the file_id and the S3 key
+    // and returns the URL we should PUT to. ``Content-Type`` is bound
+    // into the signature, so the PUT must echo it.
+    const presign = await this.http.request<{
+      file_id: MessageIdStr;
+      upload_url: string;
+      headers: Record<string, string>;
+      expires_at_ms: number;
+    }>("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: FilePresignResponse = {
+      fileId: presign.file_id,
+      uploadUrl: presign.upload_url,
+      headers: presign.headers,
+      expiresAtMs: presign.expires_at_ms,
+    };
+
+    // Step 2 — S3 PUT via XHR so the caller can show a progress bar.
+    // We deliberately don't go through HttpClient here: that one
+    // injects ``Authorization`` and ``X-Noverachat-App-Id``, which S3
+    // would reject as unsigned headers.
+    await new Promise<void>((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) {
+          // Synthesise a final ratio=1 tick so progress UIs reach 100%
+          // even when the upload finishes between two progress events.
+          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);
+    });
+
+    // Step 3 — commit. The server HEADs S3 to verify size/existence
+    // before flipping the row. After this returns the file is safe to
+    // reference from a chat_send.
+    await this.http.request<FileMeta>(
+      "POST", `/api/v1/files/${presigned.fileId}/commit`, {},
+    );
+
+    // Step 4 — send the chat message carrying just the file_id. Server
+    // joins the files row and embeds inline metadata for receivers.
+    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: File,
+    opts: SendFileOptions = {},
+  ): Promise<MessageIdStr> {
+    const kind: FileKind =
+      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<{
+      file_id: MessageIdStr;
+      upload_url: string;
+      headers: Record<string, string>;
+      expires_at_ms: number;
+    }>("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<void>((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<FileMeta>(
+      "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: { limit?: number; before?: MessageIdStr } = {},
+  ): Promise<{
+    items: Array<{
+      messageId: MessageIdStr;
+      senderId: string | null;
+      createdAtMs: number;
+      file: FileMeta;
+    }>;
+    nextCursor: MessageIdStr | null;
+    hasMore: boolean;
+  }> {
+    const raw = await this.http.request<{
+      items: Array<{
+        message_id: MessageIdStr;
+        sender_id: string | null;
+        created_at_ms: number;
+        file: {
+          id: MessageIdStr;
+          kind: FileKind;
+          mime: string;
+          size_bytes: number;
+          original_name: string | null;
+          width: number | null;
+          height: number | null;
+          duration_sec: number | null;
+          thumbnail_status: FileMeta["thumbnailStatus"];
+          forward_blocked?: boolean;
+        };
+      }>;
+      next_cursor: MessageIdStr | null;
+      has_more: boolean;
+    }>(
+      "GET",
+      `/api/v1/rooms/${encodeURIComponent(this.roomId)}/files`,
+      undefined,
+      {
+        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: MessageIdStr): void {
+    // Monotonic: keep only the highest pending mid.
+    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;  // already scheduled
+    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(): void {
+    if (this.readDebounceTimer) {
+      clearTimeout(this.readDebounceTimer);
+      this.readDebounceTimer = null;
+    }
+    this._sendPendingMarkRead();
+  }
+
+  setTyping(isTyping: boolean): void {
+    this.ws.send({ type: "typing", room_id: this.roomId, is_typing: isTyping });
+  }
+
+  async edit(
+    messageId: MessageIdStr,
+    patch: { content?: string; data?: Record<string, unknown>; meta?: Record<string, unknown> },
+  ): Promise<MessageOut> {
+    return this.http.request<MessageOut>(
+      "PUT", `/api/v1/rooms/${this.roomId}/messages/${messageId}`, patch,
+    );
+  }
+
+  async delete(messageId: MessageIdStr, scope: DeleteScope = "ALL"): Promise<void> {
+    await this.http.request<void>(
+      "DELETE", `/api/v1/rooms/${this.roomId}/messages/${messageId}`,
+      undefined, { 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(): Promise<void> {
+    await this.http.request<void>(
+      "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(): Promise<void> {
+    await this.http.request<void>(
+      "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: "ALL" | "MENTION_ONLY" | "OFF",
+  ): Promise<void> {
+    await this.http.request<void>(
+      "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(): Promise<{
+    cleared: number;
+    upToMessageId: MessageIdStr | null;
+  }> {
+    const raw = await this.http.request<{
+      cleared: number;
+      up_to_message_id: string | null;
+    }>("DELETE", `/api/v1/rooms/${this.roomId}/messages`);
+    return {
+      cleared: raw.cleared,
+      upToMessageId: raw.up_to_message_id,
+    };
+  }
+
+  async react(messageId: MessageIdStr, key: string): Promise<void> {
+    await this.http.request<void>(
+      "POST", `/api/v1/rooms/${this.roomId}/messages/${messageId}/reactions`,
+      { key },
+    );
+  }
+
+  async unreact(messageId: MessageIdStr, key: string): Promise<void> {
+    await this.http.request<void>(
+      "DELETE", `/api/v1/rooms/${this.roomId}/messages/${messageId}/reactions/${encodeURIComponent(key)}`,
+    );
+  }
+
+  async listSince(sinceMessageId: MessageIdStr | number, limit = 100): Promise<{
+    items: MessageOut[];
+    nextCursor: MessageIdStr | null;
+    hasMore: boolean;
+  }> {
+    // Backend response is snake_case Pydantic — convert to the SDK's
+    // camelCase contract here so callers (and the demo's renderMessage)
+    // don't see `undefined` on `messageId` / `senderId` / etc.
+    const raw = await this.http.request<{
+      items: RawMessageOut[]; next_cursor: string | null; has_more: boolean;
+    }>("GET", `/api/v1/rooms/${this.roomId}/messages`, undefined, {
+      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): Promise<{
+    items: MessageOut[];
+    nextCursor: MessageIdStr | null;
+    hasMore: boolean;
+  }> {
+    const raw = await this.http.request<{
+      items: RawMessageOut[]; next_cursor: string | null; has_more: boolean;
+    }>("GET", `/api/v1/rooms/${this.roomId}/messages`, undefined, { 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: MessageIdStr, limit = 50): Promise<{
+    items: MessageOut[];
+    nextCursor: MessageIdStr | null;
+    hasMore: boolean;
+  }> {
+    const raw = await this.http.request<{
+      items: RawMessageOut[]; next_cursor: string | null; has_more: boolean;
+    }>("GET", `/api/v1/rooms/${this.roomId}/messages`, undefined, {
+      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: string,
+    opts?: { before?: MessageIdStr; limit?: number },
+  ): Promise<{
+    items: MessageOut[];
+    nextCursor: MessageIdStr | null;
+    hasMore: boolean;
+  }> {
+    const params: Record<string, string | number> = {
+      q,
+      limit: opts?.limit ?? 30,
+    };
+    if (opts?.before) params.before = opts.before;
+    const raw = await this.http.request<{
+      items: RawMessageOut[]; next_cursor: string | null; has_more: boolean;
+    }>("GET", `/api/v1/rooms/${this.roomId}/messages/search`, undefined, 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(): Promise<Array<{
+    userId: string;
+    nickname: string | null;
+    role: "OPERATOR" | "MEMBER" | "KICKED";
+    pushTrigger: "ALL" | "MENTION" | "OFF";
+    lastReadMessageId: MessageIdStr | null;
+    joinedAt: string;
+    /** Cluster-wide presence dot. `null` when the server didn't resolve it. */
+    isOnline: boolean | null;
+    /** Per-room mute expiry. `null` = not muted. A far-future sentinel
+     *  (year 9999) means the operator picked "indefinite" — clients
+     *  should render that as "무기한" instead of a real timestamp. */
+    mutedUntil: string | null;
+  }>> {
+    const raw = await this.http.request<Array<{
+      user_id: string;
+      nickname?: string | null;
+      role: "OPERATOR" | "MEMBER" | "KICKED";
+      push_trigger: "ALL" | "MENTION" | "OFF";
+      last_read_message_id: string | null;
+      joined_at: string;
+      is_online?: boolean | null;
+      muted_until?: string | null;
+    }>>("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: string, durationMinutes: number | null): Promise<void> {
+    await this.http.request<void>(
+      "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: string): Promise<void> {
+    await this.http.request<void>(
+      "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(): Promise<RoomUnread> {
+    const raw = await this.http.request<{
+      room_id: string;
+      unread_count: number;
+      last_read_message_id: string | null;
+      last_message_id: string | null;
+    }>("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(): Promise<void> {
+    await this.http.request<void>(
+      "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(): Promise<void> {
+    await this.http.request<void>(
+      "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: boolean): Promise<void> {
+    await this.http.request<void>(
+      "PATCH", `/api/v1/rooms/${this.roomId}/visibility`,
+      { is_public: isPublic },
+    );
+  }
+
+  // -------- announcements --------
+
+  async listAnnouncements(): Promise<Announcement[]> {
+    const raw = await this.http.request<Array<{
+      id: number;
+      room_id: string;
+      content: string;
+      created_by: string;
+      created_at: string;
+      updated_at: string;
+    }>>("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(): Promise<Announcement | null> {
+    const raw = await this.http.request<{
+      id: number;
+      room_id: string;
+      content: string;
+      created_by: string;
+      created_at: string;
+      updated_at: string;
+    } | null>("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: string): Promise<Announcement> {
+    const raw = await this.http.request<{
+      id: number;
+      room_id: string;
+      content: string;
+      created_by: string;
+      created_at: string;
+      updated_at: string;
+    }>("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: number, content: string): Promise<Announcement> {
+    const raw = await this.http.request<{
+      id: number;
+      room_id: string;
+      content: string;
+      created_by: string;
+      created_at: string;
+      updated_at: string;
+    }>("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: number): Promise<void> {
+    await this.http.request<void>(
+      "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?: {
+    /** Hours until the link stops working. Default 168 (7 days). Pass
+     *  `null` for no expiry. */
+    expiresInHours?: number | null;
+    /** Max successful `acceptInvite` calls before the link
+     *  auto-exhausts. Default null (unlimited). */
+    maxUses?: number | null;
+  }): Promise<InviteToken> {
+    const body: Record<string, unknown> = {};
+    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<{
+      token: string;
+      room_id: string;
+      created_by: string;
+      created_at: string;
+      expires_at: string | null;
+      max_uses: number | null;
+      used_count: number;
+      revoked_at: string | null;
+    }>("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(): Promise<InviteToken[]> {
+    const raw = await this.http.request<Array<{
+      token: string;
+      room_id: string;
+      created_by: string;
+      created_at: string;
+      expires_at: string | null;
+      max_uses: number | null;
+      used_count: number;
+      revoked_at: string | null;
+    }>>("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: string): Promise<void> {
+    await this.http.request<void>(
+      "DELETE",
+      `/api/v1/rooms/${this.roomId}/invites/${encodeURIComponent(token)}`,
+    );
+  }
+
+  // -------- internal dispatch --------
+
+  on<K extends keyof RoomEvents>(event: K, fn: (p: RoomEvents[K]) => void): () => void {
+    return this.bus.on(event, fn);
+  }
+
+  off<K extends keyof RoomEvents>(event: K, fn: (p: RoomEvents[K]) => void): void {
+    this.bus.off(event, fn);
+  }
+
+  _dispatchAnnouncement(msg: WsAnnouncementEvent): void {
+    this.bus.emit("announcement", msg);
+  }
+
+  _dispatchAck(tempId: string | null, messageId: MessageIdStr): void {
+    if (!tempId) return;
+    const entry = this.pendingAcks.get(tempId);
+    if (entry) {
+      entry.resolve(messageId);
+      this.pendingAcks.delete(tempId);
+      this.mySentTempIds.delete(tempId);
+      this.bus.emit("ack", { tempId, messageId });
+    }
+  }
+
+  /** True iff this room has a still-pending send with this temp_id. */
+  _hasPendingTempId(tempId: string): boolean {
+    return this.pendingAcks.has(tempId);
+  }
+
+  /** 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(tempId: string, err: Error): void {
+    const entry = this.pendingAcks.get(tempId);
+    if (!entry) return;
+    entry.reject(err);
+    this.pendingAcks.delete(tempId);
+    this.mySentTempIds.delete(tempId);
+  }
+
+  /**
+   * 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(tempId: string): boolean {
+    const entry = this.pendingAcks.get(tempId);
+    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(() => {
+      // The entry may have been resolved/rejected in the meantime (ack
+      // arrived late, or an explicit disconnect cleared the map). Bail
+      // if so — the resend would create a frame the server can't pair
+      // to any outbound promise.
+      if (!this.pendingAcks.has(tempId)) return;
+      const ok = this.ws.send(entry.payload);
+      if (!ok) {
+        // ws.send already buffered to outboundQueue if appropriate; only
+        // returns false on explicit close. Treat as terminal failure.
+        this._rejectPending(tempId, 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(tempId: string): boolean {
+    return this.mySentTempIds.has(tempId);
+  }
+
+  /** Forget a self-sent temp_id once both the ack and the echo are reconciled. */
+  _forgetMySentTempId(tempId: string): void {
+    this.mySentTempIds.delete(tempId);
+  }
+
+  _dispatchInbound(msg: Extract<
+    import("../types.js").WsInbound,
+    { room_id?: string } | { type: string }
+  >): void {
+    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;
+    }
+  }
+}