@noverachat/sdk-web 0.0.3

package/dist/index.d.ts

@@ -0,0 +1,1151 @@
+type WsInbound = WsConnected | WsAck | WsChatReceive | WsMessageUpdated | WsMessageDeleted | WsMessagesCleared | WsReactionAdded | WsReactionRemoved | WsSyncTick | WsTypingBroadcast | WsRoomEvent | WsAnnouncementEvent | WsPresence | WsPong | WsError | WsCloseNotice;
+type MessageType = "TEXT" | "FILE" | "EMOTICON" | "ADMIN" | "SYSTEM";
+type FileKind = "image" | "video" | "file";
+type FileThumbnailStatus = "pending" | "ready" | "failed" | "skipped";
+type DeleteScope = "MY" | "ALL";
+type WsOutbound = WsChatSend | WsReadWatermark | WsTypingSend | WsPing;
+interface WsConnected {
+    type: "connected";
+    session_id: string;
+    server_ts: number;
+    protocol_version: string;
+    gap_fill_url: string;
+}
+interface WsAck {
+    type: "ack";
+    temp_id: string | null;
+    message_id: string;
+    room_id: string;
+    server_ts: number;
+}
+interface WsChatReceive {
+    type: "chat_receive";
+    room_id: string;
+    /**
+     * Snowflake id as string
+     */
+    message_id: string;
+    sender_id: string | null;
+    message_type: MessageType;
+    custom_type?: string | null;
+    content?: string | null;
+    data?: {
+        [k: string]: unknown;
+    } | null;
+    meta?: {
+        [k: string]: unknown;
+    } | null;
+    file_id?: string | null;
+    file?: FileInlineWire | null;
+    files?: FileInlineWire[] | null;
+    reply_to_id?: string | null;
+    /**
+     * unix ms
+     */
+    created_at: number;
+    /**
+     * unix ms
+     */
+    server_ts: number;
+    /**
+     * server-echoed on self-echo only
+     */
+    temp_id?: string | null;
+}
+interface FileInlineWire {
+    id: string;
+    kind: FileKind;
+    mime: string;
+    size: number;
+    name?: string | null;
+    width?: number | null;
+    height?: number | null;
+    duration_sec?: number | null;
+    thumbnail_status: FileThumbnailStatus;
+    forward_blocked?: boolean;
+}
+interface WsMessageUpdated {
+    type: "message_updated";
+    room_id: string;
+    message_id: string;
+    content?: string | null;
+    data?: {
+        [k: string]: unknown;
+    } | null;
+    meta?: {
+        [k: string]: unknown;
+    } | null;
+    updated_at: number;
+}
+interface WsMessageDeleted {
+    type: "message_deleted";
+    room_id: string;
+    message_id: string;
+    scope: DeleteScope;
+    deleted_by_user_id?: string | null;
+    deleted_at: number;
+}
+interface WsMessagesCleared {
+    type: "messages_cleared";
+    room_id: string;
+    up_to_message_id: string | null;
+    cleared_by_user_id: string | null;
+    cleared_count: number;
+    cleared_at: number;
+}
+interface WsReactionAdded {
+    type: "reaction_added";
+    room_id: string;
+    message_id: string;
+    reaction_key: string;
+    user_id: string;
+    updated_at: number;
+}
+interface WsReactionRemoved {
+    type: "reaction_removed";
+    room_id: string;
+    message_id: string;
+    reaction_key: string;
+    user_id: string;
+    updated_at: number;
+}
+interface WsSyncTick {
+    type: "sync_tick";
+    room_id: string;
+    read_states: {
+        [k: string]: string;
+    };
+}
+interface WsTypingBroadcast {
+    type: "typing";
+    room_id: string;
+    user_id: string;
+    is_typing: boolean;
+}
+interface WsRoomEvent {
+    type: "room_event";
+    event: string;
+    room_id: string;
+    target_user_id: string;
+    by_user_id: string | null;
+    server_ts: number;
+}
+interface WsAnnouncementEvent {
+    type: "announcement_event";
+    event: "CREATED" | "UPDATED" | "DELETED";
+    room_id: string;
+    announcement: AnnouncementWire | null;
+    announcement_id: number;
+    by: string;
+    at: number;
+}
+interface AnnouncementWire {
+    id: number;
+    room_id: string;
+    content: string;
+    created_by: string;
+    created_at: string;
+    updated_at: string;
+}
+interface WsPresence {
+    type: "presence";
+    user_id: string;
+    online: boolean;
+    at: number;
+}
+interface WsPong {
+    type: "pong";
+    server_ts: number;
+    client_ts?: number | null;
+}
+interface WsError {
+    type: "error";
+    code: string;
+    message: string;
+    details?: {
+        [k: string]: unknown;
+    } | null;
+}
+interface WsCloseNotice {
+    type: "close_notice";
+    reason: string;
+    retry_after_ms?: number;
+}
+interface WsChatSend {
+    type: "chat_send";
+    room_id: string;
+    content?: string | null;
+    message_type: "TEXT" | "FILE" | "EMOTICON";
+    custom_type?: string | null;
+    data?: {
+        [k: string]: unknown;
+    } | null;
+    meta?: {
+        [k: string]: unknown;
+    } | null;
+    file_id?: string | null;
+    reply_to_id?: string | null;
+    forward_of_message_id?: string | null;
+    temp_id?: string | null;
+    client_ts: number;
+}
+interface WsReadWatermark {
+    type: "read_watermark";
+    room_id: string;
+    last_read_message_id: string;
+}
+interface WsTypingSend {
+    type: "typing";
+    room_id: string;
+    is_typing: boolean;
+}
+interface WsPing {
+    type: "ping";
+    client_ts: number;
+}
+
+/**
+ * Shared wire types. Must stay in lock-step with:
+ *   noverachat-backend/src/noverachat/ws/protocol.py
+ *   noverachat-backend/src/noverachat/modules/message/schemas.py
+ *
+ * NOTE on `message_id` / `reply_to_id` / `last_*_message_id`: server-side
+ * these are 63-bit Snowflake integers. On the wire they are JSON STRINGS
+ * because JS `Number` can only represent integers up to 2^53 exactly.
+ * Stringifying preserves precision; the SDK never converts them back to
+ * Number. Compare with `BigInt(a) > BigInt(b)`.
+ */
+/** 63-bit Snowflake serialized as a JSON string. Treat as opaque. */
+type MessageIdStr = string;
+
+interface SenderMini {
+    userId: string;
+    nickname?: string | null;
+    profileImageUrl?: string | null;
+}
+interface ReactionEntry {
+    key: string;
+    userIds: string[];
+    updatedAt: number;
+}
+interface MessageOut {
+    appId: string;
+    roomId: string;
+    messageId: MessageIdStr;
+    sender?: SenderMini | null;
+    senderId?: string | null;
+    messageType: MessageType;
+    customType?: string | null;
+    content?: string | null;
+    data?: Record<string, unknown> | null;
+    meta?: Record<string, unknown> | null;
+    /** Custom metadata attached by the sender (extracted from `data._customMeta`).
+     *  Null when the sender didn't attach anything. */
+    customMeta?: Record<string, unknown> | null;
+    /** Snowflake bigint (string) of the attached file, when this is a file
+     *  message. Use ``chat.getFileUrl(fileId)`` to obtain a short-lived
+     *  signed download URL, or ``chat.getFileMeta(fileId)`` for metadata
+     *  without the download. Null for text-only messages. */
+    fileId?: MessageIdStr | null;
+    /** Inline file metadata embedded by the server on chat_receive — lets
+     *  the UI render a placeholder (filename, size, dimensions, thumbnail
+     *  status) without an extra round-trip. May be null even when `fileId`
+     *  is set (e.g. for messages loaded via REST history before the inline
+     *  metadata feature shipped); call ``getFileMeta()`` in that case. */
+    file?: FileInline | null;
+    /** Multi-file bundle — set when the message references multiple files
+     *  via ``data.file_ids`` (kind = "file_group"). Each entry has the
+     *  same shape as ``file``. Null for single-file / text-only messages.
+     *  UIs should check ``files?.length > 0`` first and only fall through
+     *  to the ``file`` singleton when the bundle field is absent. */
+    files?: FileInline[] | null;
+    replyToId?: MessageIdStr | null;
+    reactions: ReactionEntry[];
+    createdAt: string;
+    createdAtMs: number;
+    updatedAt?: string | null;
+    updatedAtMs?: number | null;
+    deletedAt?: string | null;
+    deletedByUserId?: string | null;
+    deleteScope?: DeleteScope | null;
+    editedCount: number;
+}
+interface RoomUnread {
+    roomId: string;
+    unreadCount: number;
+    lastReadMessageId: MessageIdStr | null;
+    lastMessageId: MessageIdStr | null;
+}
+interface Announcement {
+    id: number;
+    roomId: string;
+    content: string;
+    createdBy: string;
+    createdAt: string;
+    updatedAt: string;
+}
+/** One-way user block — KakaoTalk-style.
+ *
+ *  A row in the caller's block list. The blocked user is NOT told they're
+ *  blocked; they keep sending messages that just don't reach the blocker.
+ *  See ``chat.blockUser`` / ``chat.unblockUser`` / ``chat.listBlocks``.
+ */
+interface Block {
+    blockedUserId: string;
+    reason: string | null;
+    /** ISO-8601 UTC. */
+    createdAt: string;
+}
+/** 방 초대 링크 (카톡 오픈채팅 URL 스타일). Minted by an OPERATOR via
+ *  ``room.createInvite()``; consumed by any user via ``chat.acceptInvite()``. */
+interface InviteToken {
+    /** URL-safe short id (~22 chars). Embed in the shareable URL as-is. */
+    token: string;
+    roomId: string;
+    createdBy: string;
+    /** ISO-8601 UTC. */
+    createdAt: string;
+    /** ISO-8601 UTC. `null` = never expires. */
+    expiresAt: string | null;
+    /** `null` = unlimited uses. */
+    maxUses: number | null;
+    /** Successful `accept` calls so far. */
+    usedCount: number;
+    /** ISO-8601 UTC. `null` = still active (assuming not expired / exhausted). */
+    revokedAt: string | null;
+}
+/** Result of `chat.acceptInvite(token)`. */
+interface AcceptInviteResult {
+    roomId: string;
+    roomName: string | null;
+    /** True when the caller was already an active member — the call is a
+     *  no-op and does NOT bump the invite's `used_count`. Useful for
+     *  deep-link flows that may be triggered on re-open. */
+    wasAlreadyMember: boolean;
+}
+/** One member shown in a channel-list avatar mosaic. */
+interface MemberPreview {
+    userId: string;
+    nickname: string | null;
+    profileImageUrl: string | null;
+    /** Cluster-wide presence dot. `null` = not resolved (endpoint didn't
+     *  include it). Consumers rendering a green/gray dot should treat
+     *  `null` and `false` differently only if they care about the
+     *  "unknown" state. */
+    isOnline: boolean | null;
+}
+interface UnreadRoomItem {
+    roomId: string;
+    name: string | null;
+    /** "ONE" | "GROUP" | "SUPER_GROUP" — lets the UI pick a 1-up vs mosaic avatar. */
+    roomType: string | null;
+    unreadCount: number;
+    lastMessageId: MessageIdStr | null;
+    /** One-line preview shown under the room name in the channel list.
+     *  TEXT/SYSTEM → first 200 chars, EMOTICON → "[이모티콘]", images/videos/
+     *  files → "[사진]" / "[동영상]" / "[파일] name". Null when the room has
+     *  no messages yet (or was just cleared). */
+    lastMessagePreview: string | null;
+    lastReadMessageId: MessageIdStr | null;
+    /** Total active (non-KICKED) members incl. the caller — the count badge. */
+    memberCount: number;
+    /** Up to 4 OTHER members (caller excluded) for the avatar mosaic. */
+    members: MemberPreview[];
+}
+interface UnreadSummary {
+    total: number;
+    rooms: UnreadRoomItem[];
+}
+interface AppPolicy {
+    appId: string;
+    /** When true, any non-KICKED room member can call
+     *  `room.deleteAllMessages()`. When false, only operators (or super-admin)
+     *  can. UIs should gate the destructive button on this. */
+    allowMemberBulkDelete: boolean;
+    /** When false, server does NOT broadcast `sync_tick` frames — hide
+     *  read-receipt badges client-side. Per-user unread counts via REST
+     *  still work (DB tracking is independent of the broadcast). */
+    readReceiptsEnabled: boolean;
+    /** When false, the server silently drops inbound `typing` frames and
+     *  no peer ever sees "alice is typing…". SDK callers should also
+     *  short-circuit `room.setTyping()` based on this flag so a disabled
+     *  app doesn't pay the WS frame cost per keystroke. */
+    typingIndicatorsEnabled: boolean;
+    /** When true, any non-KICKED room member can hard-delete another
+     *  member's message (scope=ALL). Default false — sender-or-operator
+     *  only. UIs should gate the "Delete for everyone" button on other
+     *  users' messages by this flag. */
+    deleteAnyMessageEnabled: boolean;
+}
+/** Push providers we can deliver to. Matches the backend `TokenType`. */
+type DeviceTokenType = "FCM" | "APNS" | "HUAWEI";
+/** Coarse device platform — used only for display / analytics on the
+ *  server. Matches the backend `DeviceOS`. */
+type DeviceOS = "iOS" | "Android" | "Web";
+interface RegisterDeviceParams {
+    /** Client-stable installation id. NOT the push token — tokens rotate,
+     *  this should not. Re-registering with the same deviceId just
+     *  refreshes the stored token. */
+    deviceId: string;
+    /** The FCM / APNS / HMS push token. */
+    token: string;
+    tokenType: DeviceTokenType;
+    os?: DeviceOS;
+    appVersion?: string;
+}
+interface DeviceInfo {
+    deviceId: string;
+    tokenType: DeviceTokenType;
+    /** Server returns only a short prefix of the token — it's a credential
+     *  and the caller already holds the full value. */
+    tokenPreview: string;
+    os: DeviceOS | null;
+    appVersion: string | null;
+    pushEnabled: boolean;
+    lastActiveAt: string | null;
+    createdAt: string;
+}
+interface SendParams {
+    content?: string;
+    messageType?: "TEXT" | "FILE" | "EMOTICON";
+    customType?: string;
+    data?: Record<string, unknown>;
+    meta?: Record<string, unknown>;
+    /** Attach an already-committed file (returned by ``room.sendFile()``'s
+     *  internal upload flow, or by a prior ``presignFileUpload()`` +
+     *  ``commitFileUpload()`` if you're orchestrating the upload manually).
+     *  The message_type will be auto-set to ``FILE`` when this is supplied. */
+    fileId?: MessageIdStr;
+    /** Multi-file bundle — attach N already-committed files as ONE
+     *  message. The SDK sets ``message_type = "FILE"``, ``file_id = null``,
+     *  and writes the ids into ``data.file_ids`` (with
+     *  ``data.kind = "file_group"``). Use ``room.uploadFileOnly()`` per
+     *  file to collect the ids first. Mutually exclusive with ``fileId`` —
+     *  when both are set, ``fileIds`` wins. */
+    fileIds?: MessageIdStr[];
+    /** Apply the "no-forward" flag to the whole bundle (mirrors the
+     *  per-file flag set at upload time). Written to
+     *  ``data.forward_blocked`` for the receiving client to gate its
+     *  forward-toolbar button on. */
+    forwardBlocked?: boolean;
+    replyToId?: MessageIdStr;
+    /** Set when this send is forwarding an existing message. The server
+     *  uses it to enforce the source file's ``forwardBlocked`` flag (Phase
+     *  C #7): if the source's file is no-forward AND the destination room
+     *  differs from the source room, the send is rejected with
+     *  ``NC-FILE-014``. Pass the ORIGINAL message's ``messageId``. */
+    forwardOfMessageId?: MessageIdStr;
+    /** Arbitrary custom metadata attached to the message. Stored under
+     *  `data._customMeta`. Surfaces on receiving clients as
+     *  `MessageOut.customMeta`. */
+    customMeta?: Record<string, unknown>;
+}
+/** Compact metadata embedded in chat_receive frames. The full ``FileMeta``
+ *  shape is returned by ``chat.getFileMeta(fileId)`` and matches the
+ *  ``GET /files/{id}/meta`` response — currently identical to this
+ *  inline form. */
+interface FileInline {
+    id: MessageIdStr;
+    kind: FileKind;
+    mime: string;
+    /** Bytes. */
+    size: number;
+    /** Original filename as the uploader sent it — may be null when not
+     *  known (some clients omit it). */
+    name?: string | null;
+    /** Pixel dimensions — populated for image / video after the thumbnail
+     *  worker probes the file. May be null until the worker finishes. */
+    width?: number | null;
+    height?: number | null;
+    /** Seconds — video only. */
+    durationSec?: number | null;
+    thumbnailStatus: FileThumbnailStatus;
+    /** Uploader-set "no forward" flag. When true, another user cannot
+     *  forward a message carrying this file to a different room — the
+     *  server rejects such sends with NC-FILE-014. UIs should surface a
+     *  🚫 badge and hide the forward action for these files. Downloads
+     *  and same-room views stay allowed. */
+    forwardBlocked: boolean;
+}
+/** Same shape as ``FileInline`` for now — kept distinct so future
+ *  meta-only fields (e.g. uploader info, dedupe hash) can land here
+ *  without forcing them onto every WS frame. */
+type FileMeta = FileInline;
+/** Per-call options for ``room.sendFile()``. */
+interface SendFileOptions {
+    /** Optional progress callback fired during the S3 PUT. ``loaded`` and
+     *  ``total`` are bytes; ``ratio`` is in [0, 1]. Called from an XHR
+     *  ``upload.onprogress`` listener — at minimum the final ``ratio=1``
+     *  fires when the PUT completes. */
+    onProgress?: (p: {
+        loaded: number;
+        total: number;
+        ratio: number;
+    }) => void;
+    /** Override the declared kind. Default: derived from the File's MIME
+     *  type (``image/*`` → image, ``video/*`` → video, else file). Useful
+     *  if you need to force a particular UI rendering. */
+    kind?: FileKind;
+    /** Override the declared filename. Default: ``file.name``. */
+    name?: string;
+    /** 파일 전달 제한 — when true, the uploader (this call) marks the
+     *  file as "no-forward". Other users won't be able to forward the
+     *  resulting message to a different room; the server rejects such
+     *  sends with ``NC-FILE-014``. Downloads and same-room views stay
+     *  allowed. Default false. */
+    forwardBlocked?: boolean;
+    /** Arbitrary custom metadata attached to the resulting file message.
+     *  Stored under `data._customMeta`. Surfaces on receiving clients as
+     *  `MessageOut.customMeta`. */
+    customMeta?: Record<string, unknown>;
+}
+interface ClientOptions {
+    appId: string;
+    endpoint: string;
+    wsEndpoint?: string;
+    tokenProvider: () => Promise<string>;
+    autoReconnect?: boolean;
+    pingIntervalMs?: number;
+    readWatermarkDebounceMs?: number;
+    maxReconnectDelayMs?: number;
+    /**
+     * Seed the per-room "highest-seen message_id" map at construction time.
+     * Use this to feed back values your app persisted to local storage in a
+     * previous session, so a cold page load can still drive `?since=...` on
+     * the WS handshake and surface unread messages via `chat.backfill()`.
+     *
+     * Shape: { [roomId]: lastSeenMessageId }
+     */
+    initialLastMessageIds?: Record<string, MessageIdStr>;
+    fetch?: typeof fetch;
+    WebSocketImpl?: typeof WebSocket;
+    logger?: (lvl: "debug" | "info" | "warn" | "error", msg: string, ctx?: unknown) => void;
+}
+
+interface HttpOptions {
+    baseUrl: string;
+    appId: string;
+    tokenProvider: () => Promise<string>;
+    fetch?: typeof fetch;
+    logger?: (lvl: "debug" | "info" | "warn" | "error", msg: string, ctx?: unknown) => void;
+}
+declare class HttpClient {
+    private opts;
+    constructor(opts: HttpOptions);
+    request<T>(method: string, path: string, body?: unknown, query?: Record<string, string | number | undefined>): Promise<T>;
+    private buildUrl;
+}
+
+/**
+ * Reconnecting WebSocket — state machine per docs/ws_protocol.md §6.
+ *
+ *   IDLE → CONNECTING → OPEN → RECONNECTING → CONNECTING …
+ *
+ * - Exponential backoff with jitter (500ms → 30s cap)
+ * - Refuses to reconnect on 1008/4001/4002 (policy / app-inactive / user-banned)
+ * - Emits typed events via callbacks
+ */
+
+type WsState = "idle" | "connecting" | "open" | "reconnecting" | "closed";
+interface ReconnectingWsOptions {
+    urlBuilder: () => Promise<string>;
+    onMessage: (msg: WsInbound) => void;
+    onStateChange?: (s: WsState) => void;
+    onOpen?: () => void;
+    pingIntervalMs: number;
+    maxReconnectDelayMs: number;
+    autoReconnect: boolean;
+    WebSocketImpl?: typeof WebSocket;
+    logger?: (lvl: "debug" | "info" | "warn" | "error", msg: string, ctx?: unknown) => void;
+}
+declare class ReconnectingWs {
+    private opts;
+    private ws;
+    private state;
+    private attempt;
+    private pingTimer;
+    private explicitClose;
+    private outboundQueue;
+    private static readonly OUTBOUND_QUEUE_CAP;
+    constructor(opts: ReconnectingWsOptions);
+    get currentState(): WsState;
+    connect(): Promise<void>;
+    close(): void;
+    send(msg: WsOutbound): boolean;
+    private openOnce;
+    private scheduleReconnect;
+    private startPings;
+    private stopPings;
+    private setState;
+}
+
+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;
+}
+declare class Room {
+    readonly roomId: string;
+    private http;
+    private ws;
+    private bus;
+    private pendingAcks;
+    private static readonly MAX_RATE_LIMIT_RETRIES;
+    private static readonly RATE_LIMIT_BACKOFF_MS;
+    private lastReadSent;
+    private pendingReadMid;
+    private readDebounceTimer;
+    private 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()`).
+     */
+    private mySentTempIds;
+    constructor(roomId: string, http: HttpClient, ws: ReconnectingWs, readDebounceMs: number);
+    private _sendPendingMarkRead;
+    send(params: string | SendParams): Promise<{
+        tempId: string;
+        messageId: Promise<MessageIdStr>;
+    }>;
+    /**
+     * 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.
+     */
+    sendEmoticon(item: {
+        packId: string;
+        itemId: string;
+        fileId?: string;
+        url: string;
+    }, caption?: string): Promise<{
+        tempId: string;
+        messageId: Promise<MessageIdStr>;
+    }>;
+    /**
+     * 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.
+     */
+    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;
+    }>;
+    /**
+     * 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``.
+     */
+    uploadFileOnly(file: File, opts?: SendFileOptions): Promise<MessageIdStr>;
+    /**
+     * 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.
+     */
+    listFiles(opts?: {
+        limit?: number;
+        before?: MessageIdStr;
+    }): Promise<{
+        items: Array<{
+            messageId: MessageIdStr;
+            senderId: string | null;
+            createdAtMs: number;
+            file: FileMeta;
+        }>;
+        nextCursor: MessageIdStr | null;
+        hasMore: boolean;
+    }>;
+    markRead(messageId: MessageIdStr): void;
+    /**
+     * 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;
+    setTyping(isTyping: boolean): void;
+    edit(messageId: MessageIdStr, patch: {
+        content?: string;
+        data?: Record<string, unknown>;
+        meta?: Record<string, unknown>;
+    }): Promise<MessageOut>;
+    delete(messageId: MessageIdStr, scope?: DeleteScope): Promise<void>;
+    /** 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. */
+    clearHistory(): Promise<void>;
+    /** 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. */
+    leave(): Promise<void>;
+    /**
+     * 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.
+     */
+    setPushTrigger(trigger: "ALL" | "MENTION_ONLY" | "OFF"): Promise<void>;
+    /**
+     * **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.
+     */
+    deleteAllMessages(): Promise<{
+        cleared: number;
+        upToMessageId: MessageIdStr | null;
+    }>;
+    react(messageId: MessageIdStr, key: string): Promise<void>;
+    unreact(messageId: MessageIdStr, key: string): Promise<void>;
+    listSince(sinceMessageId: MessageIdStr | number, limit?: number): Promise<{
+        items: MessageOut[];
+        nextCursor: MessageIdStr | null;
+        hasMore: boolean;
+    }>;
+    /**
+     * 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.
+     */
+    listRecent(limit?: number): Promise<{
+        items: MessageOut[];
+        nextCursor: MessageIdStr | null;
+        hasMore: boolean;
+    }>;
+    /**
+     * 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.
+     */
+    listBefore(beforeMessageId: MessageIdStr, limit?: number): Promise<{
+        items: MessageOut[];
+        nextCursor: MessageIdStr | null;
+        hasMore: boolean;
+    }>;
+    /** 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)
+     */
+    search(q: string, opts?: {
+        before?: MessageIdStr;
+        limit?: number;
+    }): Promise<{
+        items: MessageOut[];
+        nextCursor: MessageIdStr | null;
+        hasMore: boolean;
+    }>;
+    /** 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.
+     */
+    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;
+    }>>;
+    /** 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. */
+    muteMember(userId: string, durationMinutes: number | null): Promise<void>;
+    /** 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. */
+    unmuteMember(userId: string): Promise<void>;
+    /** 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. */
+    unread(): Promise<RoomUnread>;
+    /** 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. */
+    freeze(): Promise<void>;
+    /** Mirror of `freeze()` — reopens the room to chat_send. Emits a
+     *  `ROOM_UNFROZEN` roomEvent + a "방이 녹여졌습니다." SYSTEM message. */
+    unfreeze(): Promise<void>;
+    /** 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. */
+    setPublic(isPublic: boolean): Promise<void>;
+    listAnnouncements(): Promise<Announcement[]>;
+    getCurrentAnnouncement(): Promise<Announcement | null>;
+    postAnnouncement(content: string): Promise<Announcement>;
+    updateAnnouncement(id: number, content: string): Promise<Announcement>;
+    deleteAnnouncement(id: number): Promise<void>;
+    /**
+     * 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.
+     */
+    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>;
+    /** OPERATOR-only: list all invite tokens for this room (including
+     *  revoked / expired / exhausted), newest first. */
+    listInvites(): Promise<InviteToken[]>;
+    /** OPERATOR-only: revoke a token immediately. Idempotent — revoking
+     *  an already-revoked token returns 204 as well. */
+    revokeInvite(token: string): Promise<void>;
+    on<K extends keyof RoomEvents>(event: K, fn: (p: RoomEvents[K]) => void): () => void;
+    off<K extends keyof RoomEvents>(event: K, fn: (p: RoomEvents[K]) => void): void;
+    _dispatchAnnouncement(msg: WsAnnouncementEvent): void;
+    _dispatchAck(tempId: string | null, messageId: MessageIdStr): void;
+    /** True iff this room has a still-pending send with this temp_id. */
+    _hasPendingTempId(tempId: string): boolean;
+    /** 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;
+    /**
+     * 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;
+    /** 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;
+    /** Forget a self-sent temp_id once both the ack and the echo are reconciled. */
+    _forgetMySentTempId(tempId: string): void;
+    _dispatchInbound(msg: Extract<WsInbound, {
+        room_id?: string;
+    } | {
+        type: string;
+    }>): void;
+}
+
+/**
+ * NoveraChat — top-level client facade.
+ *
+ *   const chat = new NoveraChat({ appId, endpoint, tokenProvider });
+ *   await chat.connect();
+ *   const room = chat.room("room_123");
+ *   room.on("message", ...);
+ *   await room.send("hi");
+ *   chat.disconnect();
+ */
+
+/** Client-level events (not tied to a single Room facade). `roomEvent` fires
+ *  for membership / room-lifecycle changes on ANY room — including ones the
+ *  caller hasn't opened yet (e.g. being added to a brand-new room), which a
+ *  per-room `room.on(...)` listener could never catch. `presence` fires
+ *  when any user this session shares a room with transitions online or
+ *  offline (first / last live session only — multi-tab open/close stays
+ *  silent). */
+interface ClientEvents {
+    roomEvent: WsRoomEvent;
+    presence: WsPresence;
+}
+
+declare class NoveraChat {
+    private opts;
+    private http;
+    private ws;
+    private rooms;
+    private bus;
+    private readDebounceMs;
+    private logger;
+    private connectedOnce;
+    private lastMessageIdByRoom;
+    /** Most recently dispatched presence event key, `${userId}:${at}:${online}`.
+     *  Used to drop the N-1 shared-room copies of a single online/offline
+     *  transition — the server fans out one publish per room, and we don't
+     *  want the caller's listener firing N times for one UX event. */
+    private lastPresenceKey;
+    constructor(opts: ClientOptions);
+    connect(): Promise<void>;
+    disconnect(): void;
+    room(roomId: string): Room;
+    /** Subscribe to client-level events. Currently `roomEvent` — membership /
+     *  room-lifecycle changes for ANY room (added, kicked, restored, frozen,
+     *  …), including rooms the caller hasn't opened. Returns an unsubscribe fn.
+     *  Use this to refresh a channel list the instant you're added to a new
+     *  room, rather than waiting for a poll. */
+    on<K extends keyof ClientEvents>(event: K, fn: (p: ClientEvents[K]) => void): () => void;
+    off<K extends keyof ClientEvents>(event: K, fn: (p: ClientEvents[K]) => void): void;
+    /**
+     * 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.
+     */
+    backfill(): Promise<void>;
+    /** Highest `message_id` the client has seen for a given room, or null. */
+    lastSeenMessageId(roomId: string): MessageIdStr | null;
+    /**
+     * Monotonically advance the per-room "highest-seen message_id" anchor.
+     * Used by callers that learn a newer watermark from out-of-band sources —
+     * typically the server's own `last_read_message_id` (via the unread
+     * endpoint) so the next `backfill()` doesn't re-pull messages the user
+     * already marked read on another device. Never moves the value backward;
+     * a smaller `messageId` is silently ignored. Accepts either the string
+     * form (preferred) or a number (legacy / convenience).
+     */
+    setLastSeen(roomId: string, messageId: MessageIdStr | number): void;
+    /** 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. */
+    appPolicy(): Promise<AppPolicy>;
+    /**
+     * 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).
+     */
+    registerDevice(params: RegisterDeviceParams): Promise<DeviceInfo>;
+    /** List the devices registered for the authenticated user. */
+    listDevices(): Promise<DeviceInfo[]>;
+    /**
+     * 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.
+     */
+    setDevicePushEnabled(deviceId: string, enabled: boolean): Promise<void>;
+    /** Unregister a device — call on logout so the user stops receiving
+     *  push on a device they're no longer signed into. */
+    unregisterDevice(deviceId: string): Promise<void>;
+    /**
+     * 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.
+     */
+    getPushPreferences(): Promise<{
+        pushEnabled: boolean;
+    }>;
+    /**
+     * 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.
+     */
+    setPushEnabled(enabled: boolean): Promise<{
+        pushEnabled: boolean;
+    }>;
+    /**
+     * 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.
+     */
+    blockUser(userId: string, reason?: string): Promise<Block>;
+    /** Unblock a user. Idempotent — resolves either way. */
+    unblockUser(userId: string): Promise<void>;
+    /** List every user the caller has blocked, newest first. */
+    listBlocks(): Promise<Block[]>;
+    private _toDeviceInfo;
+    /**
+     * Authorization-gated URL for downloading a file attachment.
+     *
+     * The backend runs the request through the authorization gate (caller
+     * must be a non-KICKED member of some room with a non-deleted,
+     * post-cutoff message referencing this file) and then 302-redirects
+     * to a short-lived signed S3 URL. ``<img src=...>`` / ``<video
+     * src=...>`` / ``<a href=...>`` consumers transparently follow the
+     * redirect.
+     *
+     * Why the optional ``token`` argument? Browsers don't let
+     * ``<img>``/``<video>`` tags carry custom Authorization headers —
+     * so URLs destined for those elements have to embed credentials in
+     * the URL itself. The backend's ``require_user`` dep accepts
+     * ``?token=...&app_id=...`` query params as a fallback for exactly
+     * this case (it still prefers headers when present). Pass the same
+     * JWT the SDK was constructed with; ``app_id`` is filled in
+     * automatically from the client options. Omit the token when you're
+     * going to ``fetch()`` the URL yourself with the Authorization
+     * header set (e.g. server-side preview).
+     *
+     * Note: each call returns a fresh URL but the URL embeds a JWT — its
+     * lifetime is the JWT's TTL (~24h by default), not the few-seconds
+     * window of the S3 signed URL the backend redirects to. Don't log it.
+     */
+    fileUrl(fileId: MessageIdStr, token?: string): string;
+    /**
+     * Thumbnail URL for an image / video attachment. Returns 404 when
+     * the thumbnail isn't ready yet (poll ``getFileMeta`` then re-render
+     * once ``thumbnailStatus === "ready"``). Same token-in-query rule
+     * as ``fileUrl()``.
+     */
+    fileThumbnailUrl(fileId: MessageIdStr, token?: string): string;
+    /**
+     * 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.
+     */
+    getFileMeta(fileId: MessageIdStr): Promise<FileMeta>;
+    unreadSummary(): Promise<UnreadSummary>;
+    /**
+     * 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.
+     */
+    acceptInvite(token: string): Promise<AcceptInviteResult>;
+    private dispatch;
+    private highestKnownMessageId;
+    private backfillAllRooms;
+}
+
+/**
+ * Error taxonomy mirrors noverachat-backend/src/noverachat/core/errors.py.
+ * Keep the list in-sync with the server.
+ */
+declare const ErrorCode: {
+    readonly INTERNAL: "NC-GEN-001";
+    readonly NOT_FOUND: "NC-GEN-002";
+    readonly VALIDATION: "NC-GEN-003";
+    readonly FORBIDDEN: "NC-GEN-004";
+    readonly UNAUTHORIZED: "NC-AUTH-001";
+    readonly TOKEN_EXPIRED: "NC-AUTH-002";
+    readonly TOKEN_INVALID: "NC-AUTH-003";
+    readonly TOKEN_REVOKED: "NC-AUTH-004";
+    readonly APP_INACTIVE: "NC-APP-001";
+    readonly APP_NOT_FOUND: "NC-APP-002";
+    readonly USER_BANNED: "NC-USER-001";
+    readonly USER_NOT_FOUND: "NC-USER-002";
+    readonly ROOM_NOT_FOUND: "NC-ROOM-001";
+    readonly ROOM_FROZEN: "NC-ROOM-002";
+    readonly NOT_A_MEMBER: "NC-ROOM-003";
+    readonly MESSAGE_TOO_LARGE: "NC-MSG-001";
+    readonly MESSAGE_NOT_FOUND: "NC-MSG-002";
+    readonly MESSAGE_EDIT_FORBID: "NC-MSG-003";
+    readonly RATE_LIMITED: "NC-RATE-001";
+};
+type ErrorCodeValue = (typeof ErrorCode)[keyof typeof ErrorCode];
+declare class NoveraChatError extends Error {
+    readonly code: string;
+    readonly status: number;
+    readonly details?: Record<string, unknown>;
+    constructor(message: string, code?: string, status?: number, details?: Record<string, unknown>);
+    static fromResponse(status: number, body: unknown): NoveraChatError;
+}
+
+export { type AcceptInviteResult, type Announcement, type AppPolicy, type Block, type ClientOptions, type DeleteScope, ErrorCode, type ErrorCodeValue, type InviteToken, type MessageOut, type MessageType, NoveraChat, NoveraChatError, type ReactionEntry, Room, type RoomEvents, type RoomUnread, type SendParams, type SenderMini, type UnreadRoomItem, type UnreadSummary, type WsAnnouncementEvent, type WsInbound, type WsOutbound };