@noverachat/sdk-web 0.0.3 → 0.2.0

package/dist/index.d.cts

@@ -204,34 +204,49 @@ interface WsPing {
     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 {
+/** Client-facing feature flags for the caller's app. */
+interface AppPolicy {
+    appId: string;
+    allowMemberBulkDelete: boolean;
+    readReceiptsEnabled: boolean;
+    typingIndicatorsEnabled: boolean;
+    allowMemberDeleteAnyMessage: boolean;
+}
+/** Aggregate unread state across every room the calling user is in. */
+interface UnreadSummary {
+    total: number;
+    rooms: UnreadRoomItem[];
+}
+interface UnreadRoomItem {
+    roomId: string;
+    name: string | null;
+    roomType?: string | null;
+    unreadCount: number;
+    lastMessageId?: string | null;
+    lastReadMessageId?: string | null;
+    lastMessagePreview?: string | null;
+    memberCount?: number;
+    membersPreview?: MemberPreview[];
+}
+/** A single member shown in a channel-list avatar mosaic. */
+interface MemberPreview {
     userId: string;
     nickname?: string | null;
     profileImageUrl?: string | null;
+    isOnline?: boolean | null;
 }
-interface ReactionEntry {
-    key: string;
-    userIds: string[];
-    updatedAt: number;
+/** Per-room unread state for the calling user. */
+interface RoomUnread {
+    roomId: string;
+    unreadCount: number;
+    lastReadMessageId?: string | null;
+    lastMessageId?: string | null;
 }
-interface MessageOut {
+/** Canonical NoveraChat message response.  Bemily clients hit the compat adapter which translates this into Sendbird wire-format (channelUrl, data as JSON string, etc.). */
+interface MessageOut$1 {
     appId: string;
     roomId: string;
-    messageId: MessageIdStr;
+    messageId: string;
     sender?: SenderMini | null;
     senderId?: string | null;
     messageType: MessageType;
@@ -239,44 +254,22 @@ interface MessageOut {
     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[];
+    fileId?: string | null;
+    file?: Record<string, unknown> | null;
+    files?: Record<string, unknown>[] | null;
+    replyToId?: string | 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;
+    deleteScope?: string | null;
+    editedCount?: number;
+    createdAtMs: number;
+    updatedAtMs: number | null;
 }
-interface Announcement {
+/** 공지사항 (KakaoTalk 스타일) — 방마다 다수. `deleted_at` 이 세팅되면 소프트 삭제된 것으로 리스트/current 조회에서 제외된다. */
+interface AnnouncementOut {
     id: number;
     roomId: string;
     content: string;
@@ -284,98 +277,120 @@ interface Announcement {
     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. */
+/** 방 초대 링크 (카톡 오픈채팅 URL 스타일). */
+interface InviteTokenOut {
     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 {
+/** `POST /invites/{token}/accept` 성공 응답. 가입한 방 정보. */
+interface InviteAcceptResponse {
     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 {
+interface DeviceOut {
+    deviceId: string;
+    tokenType: string;
+    tokenPreview: string;
+    os: string | null;
+    appVersion: string | null;
+    pushEnabled: boolean;
+    lastActiveAt: string | null;
+    createdAt: string;
+}
+/** One row from ``user_blocks`` for the caller.  We DON'T echo ``blocker_user_id`` — it's always the caller, and including it in every list entry would just add noise. ``model_config`` lets the router return ORM instances directly via ``response_model``. */
+interface BlockOut {
+    blockedUserId: string;
+    reason: string | null;
+    createdAt: string;
+}
+interface RoomMemberOut {
     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;
+    nickname?: string | null;
+    role: MemberRole;
+    pushTrigger: PushTrigger;
+    lastReadMessageId?: string | null;
+    joinedAt: string;
+    isOnline?: boolean | null;
+    mutedUntil?: string | 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 JoinRequestOut {
+    userId: string;
+    status: "PENDING" | "APPROVED" | "REJECTED" | "CANCELLED";
+    reason: string | null;
+    requestedAt: string;
+    processedAt: string | null;
+    processedByUserId: string | null;
 }
-interface UnreadSummary {
+interface JoinRequestListResponse {
+    items: JoinRequestOut[];
     total: number;
-    rooms: UnreadRoomItem[];
+    limit: number;
+    offset: number;
 }
-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;
+/** Synchronous response after `POST /join-request`.  `status="joined"`   — OPEN room, user was immediately added. `status="pending"`  — APPROVAL_REQUIRED, request is pending. `status="already_member"` — caller is already an active member; no-op. */
+interface JoinRequestCreateResponse {
+    status: "joined" | "pending" | "already_member";
+    roomId: string;
+}
+/** Minimal sender identity — no friend/block/profile-url fluff. */
+interface SenderMini {
+    userId: string;
+    nickname?: string | null;
+    profileImageUrl?: string | null;
+}
+interface ReactionEntry {
+    key: string;
+    userIds: string[];
+    updatedAt: number;
+}
+type MemberRole = "OPERATOR" | "MEMBER" | "KICKED";
+type PushTrigger = "ALL" | "MENTION_ONLY" | "OFF";
+
+/**
+ * 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;
+
+/**
+ * Canonical message shape surfaced to SDK callers. Structurally the
+ * GENERATED REST `MessageOut` PLUS two client-side enhancements the server
+ * doesn't send verbatim:
+ *   - `file` / `files` parsed into the camelCase `FileInline` shape (the
+ *     generated model leaves them free-form since the OpenAPI schema does),
+ *   - `customMeta` lifted out of `data._customMeta`.
+ * Built by `toMessageOut` in features/room.ts.
+ */
+interface MessageOut extends Omit<MessageOut$1, "file" | "files" | "reactions"> {
+    /** Inline file metadata embedded by the server on chat_receive / REST
+     *  history — lets the UI render a placeholder (filename, size, dims,
+     *  thumbnail status) without an extra round-trip. May be null even when
+     *  `fileId` is set (older history predating inline meta); call
+     *  ``getFileMeta()`` in that case. */
+    file?: FileInline | null;
+    /** Multi-file bundle (kind = "file_group"). Null for single-file /
+     *  text-only messages. Check ``files?.length`` first, then fall back to
+     *  the ``file`` singleton. */
+    files?: FileInline[] | null;
+    reactions: ReactionEntry[];
+    /** Custom metadata attached by the sender (extracted from
+     *  `data._customMeta`). Null when the sender didn't attach anything. */
+    customMeta?: Record<string, unknown> | null;
 }
 /** Push providers we can deliver to. Matches the backend `TokenType`. */
 type DeviceTokenType = "FCM" | "APNS" | "HUAWEI";
@@ -393,18 +408,6 @@ interface RegisterDeviceParams {
     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";
@@ -735,8 +738,31 @@ declare class Room {
      *  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>;
+     *  an operator add; for ONE, re-creating the 1:1 rejoins with history kept.
+     *
+     *  Optional `deleteMessages` — atomically clean up chat history as part
+     *  of leaving.  Default is `"none"` (messages survive so the room's
+     *  history keeps making sense to remaining members).
+     *    - `"none"` — leave only.
+     *    - `"mine"` — soft-delete every message YOU sent, then leave.  Other
+     *                 members' messages are untouched.  Broadcasts
+     *                 `messages_cleared_by_sender` so connected clients hide
+     *                 them locally.
+     *    - `"all"`  — wipe every message in the room, then leave.  Subject to
+     *                 the app's `allow_member_bulk_delete` gate and per-room
+     *                 OPERATOR check — a plain member gets 403 back. */
+    leave(options?: {
+        deleteMessages?: "none" | "mine" | "all";
+    }): Promise<void>;
+    /** Delete every message YOU sent in this room.  Standalone version of
+     *  `leave({ deleteMessages: "mine" })` — useful when a user wants to
+     *  scrub their history without actually leaving.  Other members'
+     *  messages are untouched; broadcasts `messages_cleared_by_sender`
+     *  so connected clients hide the vanished ones locally.
+     *  No OPERATOR gate — you own your messages. */
+    deleteMyMessages(): Promise<{
+        cleared: number;
+    }>;
     /**
      * Set the caller's per-room push preference — like long-pressing a
      * chat and tapping "notifications off".
@@ -811,20 +837,7 @@ declare class Room {
      *  `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;
-    }>>;
+    listMembers(): Promise<RoomMemberOut[]>;
     /** 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)
@@ -853,10 +866,10 @@ declare class Room {
      *  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>;
+    listAnnouncements(): Promise<AnnouncementOut[]>;
+    getCurrentAnnouncement(): Promise<AnnouncementOut | null>;
+    postAnnouncement(content: string): Promise<AnnouncementOut>;
+    updateAnnouncement(id: number, content: string): Promise<AnnouncementOut>;
     deleteAnnouncement(id: number): Promise<void>;
     /**
      * OPERATOR-only: mint a new invite link for this room. Default:
@@ -874,13 +887,44 @@ declare class Room {
         /** Max successful `acceptInvite` calls before the link
          *  auto-exhausts. Default null (unlimited). */
         maxUses?: number | null;
-    }): Promise<InviteToken>;
+    }): Promise<InviteTokenOut>;
     /** OPERATOR-only: list all invite tokens for this room (including
      *  revoked / expired / exhausted), newest first. */
-    listInvites(): Promise<InviteToken[]>;
+    listInvites(): Promise<InviteTokenOut[]>;
     /** OPERATOR-only: revoke a token immediately. Idempotent — revoking
      *  an already-revoked token returns 204 as well. */
     revokeInvite(token: string): Promise<void>;
+    /**
+     * Ask to join this room (self). Behavior depends on the room's
+     * `joinPolicy`:
+     *   - `OPEN` → the caller is added immediately (`status: "joined"`);
+     *   - `APPROVAL_REQUIRED` → the request lands in the operators' inbox
+     *     (`status: "pending"`) until [`approveJoinRequest`] / reject.
+     * Idempotent for members (`status: "already_member"`).
+     *
+     * @param reason Optional note shown to operators ("하은이 반 친구 엄마예요").
+     */
+    requestJoin(reason?: string): Promise<JoinRequestCreateResponse>;
+    /** Cancel the caller's own pending join request. */
+    cancelJoinRequest(): Promise<void>;
+    /** OPERATOR-only: list join requests for this room (the approval inbox).
+     *  Defaults to pending only — pass a status to see processed history. */
+    listJoinRequests(opts?: {
+        status?: "PENDING" | "APPROVED" | "REJECTED" | "CANCELLED";
+        limit?: number;
+        offset?: number;
+    }): Promise<JoinRequestListResponse>;
+    /** OPERATOR-only: approve a pending join request — the requester becomes
+     *  a MEMBER. [reason] is echoed back to them in later list calls. */
+    approveJoinRequest(userId: string, reason?: string): Promise<void>;
+    /** OPERATOR-only: reject a pending join request. */
+    rejectJoinRequest(userId: string, reason?: string): Promise<void>;
+    /** Hide this room from the caller's own room list (self, reversible —
+     *  the KakaoTalk "숨기기"). The room typically reappears via [unhide]
+     *  or on new activity, per server policy. Messages are untouched. */
+    hide(): Promise<void>;
+    /** Undo [hide] — the room shows up in the caller's list again. */
+    unhide(): 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;
@@ -1005,9 +1049,9 @@ declare class NoveraChat {
      * 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>;
+    registerDevice(params: RegisterDeviceParams): Promise<DeviceOut>;
     /** List the devices registered for the authenticated user. */
-    listDevices(): Promise<DeviceInfo[]>;
+    listDevices(): Promise<DeviceOut[]>;
     /**
      * Turn push delivery on/off for one device without unregistering it —
      * the token stays stored, the push pipeline just skips it. Use for an
@@ -1046,12 +1090,11 @@ declare class NoveraChat {
      *                a validation error server-side.
      * @param reason  Optional local note ≤500 chars.
      */
-    blockUser(userId: string, reason?: string): Promise<Block>;
+    blockUser(userId: string, reason?: string): Promise<BlockOut>;
     /** 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;
+    listBlocks(): Promise<BlockOut[]>;
     /**
      * Authorization-gated URL for downloading a file attachment.
      *
@@ -1108,7 +1151,7 @@ declare class NoveraChat {
      * invalid, expired, revoked, exhausted, or when the caller has been
      * kicked from the target room.
      */
-    acceptInvite(token: string): Promise<AcceptInviteResult>;
+    acceptInvite(token: string): Promise<InviteAcceptResponse>;
     private dispatch;
     private highestKnownMessageId;
     private backfillAllRooms;
@@ -1148,4 +1191,4 @@ declare class NoveraChatError extends Error {
     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 };
+export { type InviteAcceptResponse as AcceptInviteResult, type AnnouncementOut as Announcement, type AppPolicy, type BlockOut as Block, type ClientOptions, type DeleteScope, ErrorCode, type ErrorCodeValue, type InviteTokenOut as InviteToken, type JoinRequestCreateResponse, type JoinRequestListResponse, type JoinRequestOut, type MessageOut, type MessageType, NoveraChat, NoveraChatError, type ReactionEntry, Room, type RoomEvents, type RoomMemberOut, type RoomUnread, type SendParams, type SenderMini, type UnreadRoomItem, type UnreadSummary, type WsAnnouncementEvent, type WsInbound, type WsOutbound };