@noverachat/sdk-react 0.3.0

package/dist/index.d.cts

@@ -0,0 +1,675 @@
+import { SenderMini, FileInline, ReactionEntry, MessageOut, WsChatReceive, ClientOptions, NoveraChat, RoomMemberOut, FileMeta, MemberPreview, InviteToken, JoinRequestOut, PushTrigger, SendFileOptions, DeleteScope, Room, UnreadSummary } from '@noverachat/sdk-web';
+export * from '@noverachat/sdk-web';
+import { ReactNode } from 'react';
+
+/** Delivery status of an outgoing (optimistic) message. */
+type ChatMessageStatus = "sending" | "sent" | "failed";
+/**
+ * A single message as the UI wants it — one uniform shape over the SDK's
+ * three sources: `MessageOut` (history/REST), `WsChatReceive` (live/WS), and
+ * an optimistic bubble we just sent.
+ *
+ * Treat instances as immutable — `RoomStore` evolves them by replacement,
+ * never mutation.
+ */
+interface ChatMessage {
+    /** The server message id, or the `tempId` while still `sending`. */
+    id: string;
+    /** Author user id. `null` means the current user (an optimistic bubble). */
+    senderId: string | null;
+    content: string | null;
+    /** Creation time in unix milliseconds. */
+    createdAtMs: number | null;
+    status: ChatMessageStatus;
+    /** `TEXT | FILE | EMOTICON | ADMIN | SYSTEM` — UIs use this to render
+     *  system/admin lines (centered notices) differently from chat bubbles. */
+    messageType: string;
+    /** Sender identity (nickname / profile image) when the server included it.
+     *  Null for optimistic bubbles and live frames (which carry only
+     *  `senderId`) — UIs typically resolve the profile from their member list. */
+    sender: SenderMini | null;
+    /** App-defined subtype (e.g. a message-priority convention). */
+    customType: string | null;
+    /** Snowflake id (string) of the attached file, when this is a file message. */
+    fileId: string | null;
+    /** Inline metadata of the attached file — enough to render a placeholder
+     *  without a round-trip. May be null even when `fileId` is set; fetch via
+     *  `chat.getFileMeta` then. */
+    file: FileInline | null;
+    /** Multi-file bundle (`file_group`). Null for single-file / text messages.
+     *  Check `files?.length` first and fall back to the `file` singleton. */
+    files: FileInline[] | null;
+    /** Id of the message this one replies to, if any. */
+    replyToId: string | null;
+    /** Emoji reactions grouped by key. Kept live by `RoomStore` from the
+     *  reaction WS events. */
+    reactions: ReactionEntry[];
+    /** Sender-attached custom metadata (`data._customMeta`). */
+    customMeta: Record<string, unknown> | null;
+    /** How many times the message was edited. `> 0` → show an "edited" mark. */
+    editedCount: number;
+    /** Upload progress in [0, 1] while an optimistic FILE message's bytes are
+     *  still going up to S3. Null once committed (or for non-file messages). */
+    uploadProgress: number | null;
+    /** The optimistic temp id, kept for ack reconciliation. Null once confirmed. */
+    tempId: string | null;
+    isDeleted: boolean;
+}
+/** Build a `ChatMessage` from server history (REST). */
+declare function chatMessageFromHistory(m: MessageOut): ChatMessage;
+/** Build a `ChatMessage` from a live inbound frame (WS). */
+declare function chatMessageFromLive(f: WsChatReceive): ChatMessage;
+
+interface NoveraChatProviderProps {
+    /** Options for the `NoveraChat` this provider creates. Read **once**, when
+     *  the provider first mounts — to connect with different options, give the
+     *  provider a new `key` so it remounts. */
+    options: ClientOptions;
+    children: ReactNode;
+}
+/**
+ * Provides a connected `NoveraChat` to the component subtree.
+ *
+ * Mount it once near the top of your app. It creates the client, calls
+ * `connect()` on mount and `disconnect()` on unmount. Descendants read the
+ * client with `useNoveraChat()`.
+ *
+ * ```tsx
+ * <NoveraChatProvider
+ *   options={{
+ *     appId: "app_9f8k2x",
+ *     endpoint: "https://chat.example.com",
+ *     tokenProvider: async () => fetchJwt(),
+ *   }}
+ * >
+ *   <ChatScreen />
+ * </NoveraChatProvider>
+ * ```
+ */
+declare function NoveraChatProvider(props: NoveraChatProviderProps): ReactNode;
+/**
+ * The `NoveraChat` from the nearest enclosing `NoveraChatProvider`.
+ * Throws when there is no provider above in the tree.
+ *
+ * ```tsx
+ * const chat = useNoveraChat();
+ * const room = chat.room("room_123");
+ * ```
+ */
+declare function useNoveraChat(): NoveraChat;
+
+interface MemberListSnapshot {
+    /** Current members (server order). Empty until `load` completes. */
+    members: RoomMemberOut[];
+    /** Members with the OPERATOR role — e.g. to show a crown badge or gate
+     *  operator-only actions client-side. */
+    operators: RoomMemberOut[];
+    /** Active (non-KICKED) member ids — handy as the `userIds` argument of
+     *  `RoomStore.readCount` for read-receipt math. */
+    activeMemberIds: string[];
+}
+/**
+ * Live member list of one room — roles, presence dots, mute state. Backs a
+ * room-settings member section or an operator panel.
+ *
+ * Loads via `room.listMembers()` and keeps itself fresh:
+ *   - membership / lifecycle `roomEvent`s for this room trigger a
+ *     debounced reload (member joined / left / kicked / role changed /
+ *     muted …);
+ *   - `presence` transitions flip the member's `isOnline` in place, no
+ *     round-trip.
+ */
+declare class MemberListStore {
+    private readonly chat;
+    readonly roomId: string;
+    private readonly listeners;
+    private members;
+    private unsubs;
+    private reloadTimer;
+    private snapshot;
+    private attached;
+    constructor(chat: NoveraChat, roomId: string);
+    attach(): void;
+    dispose(): void;
+    readonly subscribe: (fn: () => void) => (() => void);
+    readonly getSnapshot: () => MemberListSnapshot;
+    private emit;
+    /** Whether `userId` is an OPERATOR of this room. */
+    isOperator(userId: string): boolean;
+    /** Fetch the member list. Also called automatically on membership
+     *  events. */
+    load(): Promise<void>;
+    private onPresence;
+    private scheduleReload;
+}
+
+/** One (message, file) entry of a room's shared-file list — the same shape
+ *  `room.listFiles()` returns per item. */
+interface RoomFileItem {
+    messageId: string;
+    senderId: string | null;
+    createdAtMs: number;
+    file: FileMeta;
+}
+interface RoomFilesSnapshot {
+    /** Loaded entries, newest first. One entry per (message, file). */
+    items: RoomFileItem[];
+    /** Only image/video entries — for a photo-album grid that skips plain
+     *  files. */
+    media: RoomFileItem[];
+    /** True when older pages remain — call `loadMore` from the grid's tail. */
+    hasMore: boolean;
+    /** True while a `refresh` / `loadMore` request is in flight. */
+    isLoading: boolean;
+}
+/**
+ * Paginated media/file grid of one room — backs a "파일" section in room
+ * settings or an album-style photo grid.
+ *
+ * Wraps `room.listFiles()` (newest first) with cursor bookkeeping. New
+ * uploads land at the head on `refresh`; older pages append via `loadMore`.
+ * Render thumbnails with `chat.fileThumbnailUrl(item.file.id, token)`.
+ */
+declare class RoomFilesStore {
+    private readonly chat;
+    readonly roomId: string;
+    /** Page size for both `refresh` and `loadMore`. */
+    readonly pageSize: number;
+    private readonly listeners;
+    private items;
+    private cursor;
+    private hasMore;
+    private loading;
+    private attached;
+    private snapshot;
+    constructor(chat: NoveraChat, roomId: string, pageSize?: number);
+    /** No realtime subscriptions — kept for lifecycle symmetry with the
+     *  other stores (guards in-flight results after unmount). */
+    attach(): void;
+    dispose(): void;
+    readonly subscribe: (fn: () => void) => (() => void);
+    readonly getSnapshot: () => RoomFilesSnapshot;
+    private emit;
+    /** Reload from the newest page (clears what was loaded). */
+    refresh(): Promise<void>;
+    /** Fetch the next older page and append it. No-op while loading or when
+     *  `hasMore` is false. Returns the number of entries added. */
+    loadMore(): Promise<number>;
+}
+
+/**
+ * One row of a chat-room list screen.
+ *
+ * A live-updatable view over `UnreadRoomItem`: same fields, plus
+ * `lastMessageAtMs` which is filled from realtime messages as they arrive
+ * (the initial REST load doesn't carry a timestamp yet) and
+ * `anyMemberOnline` for the green presence dot.
+ */
+interface RoomListItem {
+    roomId: string;
+    name: string | null;
+    roomType: string | null;
+    unreadCount: number;
+    lastMessageId: string | null;
+    lastMessagePreview: string | null;
+    memberCount: number;
+    members: MemberPreview[];
+    /** unix ms of the last message — filled from realtime frames onward. */
+    lastMessageAtMs: number | null;
+    /** Green dot — true when any preview member is online (as of the last
+     *  list load). */
+    anyMemberOnline: boolean;
+}
+interface RoomListSnapshot {
+    /** Rooms, most-recently-active first. */
+    rooms: RoomListItem[];
+    /** Sum of every room's unread badge (for a bottom-tab badge). */
+    totalUnread: number;
+}
+interface RoomListStoreOptions {
+    /** Incoming message → list preview string. Default: `content`, or "📎"
+     *  for file messages. */
+    previewBuilder?: (m: WsChatReceive) => string;
+    /** Return true while the user is looking at the given room, so its new
+     *  messages don't bump the badge (the room screen's `markRead` owns the
+     *  read state then). */
+    isRoomVisible?: (roomId: string) => boolean;
+}
+/**
+ * Chat-room list state — the data behind a KakaoTalk-style "채팅" tab.
+ *
+ * Loads the room list from `chat.unreadSummary()` (rooms come back
+ * most-recently-active first) and keeps it live:
+ *   - a new message in any room bumps that room to the top, replaces its
+ *     preview, and (unless `isRoomVisible` says the user is looking at it)
+ *     increments its unread badge;
+ *   - room membership events and cross-device read syncs trigger a
+ *     debounced reload.
+ *
+ * When coming back from a room screen, call `markRead(roomId)` to clear
+ * the badge. Previews of the user's own sends are picked up by the reload
+ * on return (`load()` is idempotent-safe to call again).
+ */
+declare class RoomListStore {
+    private readonly chat;
+    private readonly opts;
+    private readonly listeners;
+    private rooms;
+    private index;
+    private roomSubs;
+    private clientSub;
+    private reloadTimer;
+    private snapshot;
+    private attached;
+    constructor(chat: NoveraChat, opts?: RoomListStoreOptions);
+    /** Subscribe to client-level room events. Idempotent. */
+    attach(): void;
+    /** Unsubscribe everything (list state is kept for a later `attach`). */
+    dispose(): void;
+    readonly subscribe: (fn: () => void) => (() => void);
+    readonly getSnapshot: () => RoomListSnapshot;
+    private emit;
+    /** Reload the room list and re-hook the realtime subscriptions. */
+    load(): Promise<void>;
+    /** Hide a room (카톡 "숨기기") — optimistically remove it from the list
+     *  and send `hide` to the server. On failure the next `load` brings it
+     *  back; new activity may re-surface it per server policy (arrives via
+     *  roomEvent → reload). */
+    hideRoom(roomId: string): Promise<void>;
+    /** Undo `hideRoom` — send `unhide` and reload the list. */
+    unhideRoom(roomId: string): Promise<void>;
+    /** Mark a room read — drop its badge to 0 and advance the client's
+     *  last-seen watermark. */
+    markRead(roomId: string): void;
+    private reindex;
+    private resubscribe;
+    private onIncoming;
+    private scheduleReload;
+}
+
+interface RoomSettingsSnapshot {
+    /** Invite tokens minted for this room (operator view), newest first.
+     *  Empty until `loadInvites`. */
+    invites: InviteToken[];
+    /** Pending join requests (operator inbox). Empty until
+     *  `loadJoinRequests`. */
+    joinRequests: JoinRequestOut[];
+}
+/**
+ * Actions and state behind a room-settings screen (대화방 설정): per-room
+ * mute, invite links, join-request inbox, leave / clear-history, and
+ * operator moderation.
+ *
+ * Mostly a thin, typed facade over `Room`'s one-shot REST calls — the only
+ * held state is the invite / join-request lists. Read the caller's
+ * *current* push trigger from their own row in `MemberListStore` (the
+ * server has no standalone "get my settings" endpoint).
+ */
+declare class RoomSettingsStore {
+    private readonly chat;
+    readonly roomId: string;
+    private readonly listeners;
+    private invites;
+    private joinRequests;
+    private attached;
+    private snapshot;
+    constructor(chat: NoveraChat, roomId: string);
+    private get room();
+    /** No realtime subscriptions — kept for lifecycle symmetry with the
+     *  other stores (guards in-flight results after unmount). */
+    attach(): void;
+    dispose(): void;
+    readonly subscribe: (fn: () => void) => (() => void);
+    readonly getSnapshot: () => RoomSettingsSnapshot;
+    private emit;
+    /** Convenience mute toggle: `true` → `OFF`, `false` → `ALL`. */
+    setMuted(muted: boolean): Promise<void>;
+    /** Fine-grained per-room push trigger: `ALL` | `MENTION_ONLY` | `OFF`. */
+    setPushTrigger(trigger: PushTrigger): Promise<void>;
+    /** Fetch the invite list (operator-only server-side). */
+    loadInvites(): Promise<void>;
+    /** Mint a new invite link and prepend it to `invites`. */
+    createInvite(opts?: {
+        expiresInHours?: number | null;
+        maxUses?: number | null;
+    }): Promise<InviteToken>;
+    /** Revoke a token and drop it from `invites`. */
+    revokeInvite(token: string): Promise<void>;
+    /** Fetch pending join requests (operator-only server-side). */
+    loadJoinRequests(): Promise<void>;
+    /** Approve a pending request and drop it from `joinRequests`. */
+    approveJoinRequest(userId: string, reason?: string): Promise<void>;
+    /** Reject a pending request and drop it from `joinRequests`. */
+    rejectJoinRequest(userId: string, reason?: string): Promise<void>;
+    /** Per-user "clear chat" — hides existing messages for the caller only. */
+    clearHistory(): Promise<void>;
+    /** Leave the room. `deleteMessages`: `"none"` (default) | `"mine"` |
+     *  `"all"` — see `Room.leave`. */
+    leave(options?: {
+        deleteMessages?: "none" | "mine" | "all";
+    }): Promise<void>;
+    /** Delete every message the caller sent (without leaving). Returns the
+     *  cleared count. */
+    deleteMyMessages(): Promise<number>;
+    /** **Destructive, operator-only** — wipe every message in the room. */
+    deleteAllMessages(): Promise<{
+        cleared: number;
+        upToMessageId: string | null;
+    }>;
+    /** Operator: block non-operator sends (`ROOM_FROZEN` server-side). */
+    freeze(): Promise<void>;
+    /** Operator: reopen the room to sends. */
+    unfreeze(): Promise<void>;
+    /** Operator: toggle open-chat visibility. */
+    setPublic(isPublic: boolean): Promise<void>;
+    /** Operator: mute a member (`durationMinutes` null → indefinite). */
+    muteMember(userId: string, durationMinutes: number | null): Promise<void>;
+    /** Operator: clear a member's mute. */
+    unmuteMember(userId: string): Promise<void>;
+}
+
+/** Immutable snapshot handed to React via `useSyncExternalStore`. A new
+ *  object (new array/record identities) is produced on every change. */
+interface RoomSnapshot {
+    /** The current messages, oldest first. */
+    messages: ChatMessage[];
+    /** True when older history remains — show a "load more" affordance. */
+    hasMore: boolean;
+    /** Per-user read watermarks (`userId` → last read `messageId`), kept live
+     *  from `sync_tick` frames. */
+    readWatermarks: Readonly<Record<string, string>>;
+}
+/**
+ * Turns a `Room`'s events into an externally-subscribable message list and
+ * drives optimistic sends. Framework-agnostic on purpose so it can also be
+ * used outside hooks (tests, non-React glue).
+ *
+ * Lifecycle: construct → `attach()` (subscribe WS events; idempotent) →
+ * `dispose()` (flush read watermark + unsubscribe). `useMessages` does all
+ * three for you.
+ *
+ * Holds `(chat, roomId)` rather than a `Room` instance and re-resolves the
+ * live facade on every use — `chat.disconnect()` drops its Room facades, so
+ * a remounted provider (React StrictMode simulates this) would otherwise
+ * leave the store subscribed to an orphaned Room that no longer receives
+ * dispatches.
+ *
+ * ```ts
+ * const store = new RoomStore(chat, "room_123");
+ * store.attach();
+ * const unsub = store.subscribe(() => render(store.getSnapshot()));
+ * await store.loadHistory();
+ * store.send("hello");
+ * ```
+ */
+declare class RoomStore {
+    private readonly chat;
+    readonly roomId: string;
+    private readonly listeners;
+    private readonly unsubs;
+    private messages;
+    private readWatermarks;
+    private hasMore;
+    private oldestCursor;
+    private loadingMore;
+    private historyRequested;
+    private snapshot;
+    private attached;
+    private readonly onPageHide;
+    constructor(chat: NoveraChat, roomId: string);
+    /** The live `Room` facade — resolved from the client on every access
+     *  (get-or-create in a map, cheap) so we never act on an orphan. */
+    private get room();
+    /** Subscribe to WS events + page lifecycle. Safe to call repeatedly
+     *  (no-op while attached) — matches React 18/19 StrictMode's
+     *  mount → cleanup → mount effect cycle. */
+    attach(): void;
+    /** Unsubscribe everything and flush the pending read watermark. The store
+     *  keeps its message state, so a later `attach()` resumes cleanly. */
+    dispose(): void;
+    /** `useSyncExternalStore`-compatible subscribe. Returns an unsubscribe fn. */
+    readonly subscribe: (fn: () => void) => (() => void);
+    readonly getSnapshot: () => RoomSnapshot;
+    private emit;
+    /** Whether `userId` has read `messageId` according to the latest watermark. */
+    isReadBy(userId: string, messageId: string): boolean;
+    /** How many of the given users have read `messageId`. Pass the room's
+     *  member ids (minus the sender) to get a KakaoTalk-style unread count:
+     *  `members.length - readCount(...)`. */
+    readCount(messageId: string, userIds: Iterable<string>): number;
+    /** Load the most recent page of history and prepend it. No-op after the
+     *  first call (StrictMode double-mount safe) — use `loadMore` for
+     *  scrollback. */
+    loadHistory(limit?: number): Promise<void>;
+    /** Scrollback: load the page of messages older than what's on screen and
+     *  prepend it. No-op while a previous call is in flight or when `hasMore`
+     *  is false. Returns the number of messages added. */
+    loadMore(limit?: number): Promise<number>;
+    /** Send `text` optimistically: a `sending` bubble appears immediately,
+     *  then flips to `sent` (with the real id) on ack, or `failed` on error.
+     *
+     *  Optional extras ride along: `replyToId` for replies, `customType` /
+     *  `customMeta` for app-defined conventions (e.g. message priority). */
+    send(text: string, opts?: {
+        replyToId?: string;
+        customType?: string;
+        customMeta?: Record<string, unknown>;
+    }): void;
+    /** Send a file optimistically. A FILE bubble with `uploadProgress`
+     *  appears immediately; progress advances during the S3 upload, then the
+     *  bubble flips to `sent` on ack (or `failed`). */
+    sendFile(file: File, opts?: SendFileOptions): Promise<void>;
+    /** Edit a message's content (server-side; peers get `message_updated`).
+     *  The local copy updates optimistically. */
+    edit(messageId: string, content: string): Promise<void>;
+    /** Delete a message. `scope: "ALL"` (default) removes it for everyone;
+     *  `"MY"` hides it only for the caller. Local copy flips to deleted. */
+    delete(messageId: string, scope?: DeleteScope): Promise<void>;
+    /** Add/remove the caller's reaction. Pass `myUserId` so the toggle can
+     *  tell whether the caller already reacted with `key`. The authoritative
+     *  state arrives back via the reaction WS events. */
+    toggleReaction(messageId: string, key: string, myUserId: string): Promise<void>;
+    /** Search this room's messages (server-side, content substring match).
+     *  Returns view models without touching the message list. */
+    search(q: string, limit?: number): Promise<ChatMessage[]>;
+    /** Mark `messageId` read (debounced inside the SDK). */
+    markRead(messageId: string): void;
+    private onIncoming;
+    private onUpdated;
+    private onDeleted;
+    private onCleared;
+    private onReactionAdded;
+    private onReactionRemoved;
+    private onSyncTick;
+    private onVisibilityChange;
+    private bindAck;
+    private mutateById;
+    private mutateByTempId;
+}
+
+interface UseMessagesOptions {
+    /** Page size for the initial history load (and a sensible default for
+     *  scrollback pages). Default 50. */
+    historyLimit?: number;
+}
+interface UseMessagesResult extends RoomSnapshot {
+    /** The backing store — exposes `send`, `sendFile`, `edit`, `delete`,
+     *  `toggleReaction`, `markRead`, `loadMore`, `search`, `isReadBy`,
+     *  `readCount`. Stable identity for the lifetime of `(client, roomId)`. */
+    store: RoomStore;
+}
+/**
+ * The live message list of a room, plus the store that drives it.
+ *
+ * Subscribes to the room's WS events, loads the first history page on
+ * mount, and re-renders on every change — new/edited/deleted messages,
+ * reactions, read watermarks, optimistic send state.
+ *
+ * ```tsx
+ * const { messages, hasMore, store } = useMessages("room_123");
+ * // ...
+ * <button onClick={() => store.loadMore()} disabled={!hasMore}>more</button>
+ * {messages.map((m) => <Bubble key={m.id} message={m} />)}
+ * <input onKeyDown={(e) => e.key === "Enter" && store.send(draft)} />
+ * ```
+ */
+declare function useMessages(roomId: string, opts?: UseMessagesOptions): UseMessagesResult;
+
+interface UseMemberListResult extends MemberListSnapshot {
+    /** The backing store — `load`, `isOperator`. */
+    store: MemberListStore;
+}
+/**
+ * Live member list of a room — roles, presence dots, mute state. Reloads
+ * on membership events; presence transitions update in place.
+ *
+ * Combine with `useMessages` for read receipts:
+ * `activeMemberIds.length - 1 - store.readCount(messageId, activeMemberIds)`
+ * gives a KakaoTalk-style "unread N" per message.
+ *
+ * ```tsx
+ * const { members, operators } = useMemberList("room_123");
+ * ```
+ */
+declare function useMemberList(roomId: string): UseMemberListResult;
+
+/**
+ * The `Room` facade for `roomId`, from the nearest `NoveraChatProvider`'s
+ * client. Use it for direct SDK calls the hooks don't cover (members,
+ * announcements, invites, moderation, …).
+ *
+ * Deliberately NOT memoized: `chat.room()` is a get-or-create map lookup,
+ * and re-resolving each render guarantees the facade is never an orphan
+ * after the provider reconnects.
+ *
+ * ```tsx
+ * const room = useRoom("room_123");
+ * const members = await room.listMembers();
+ * ```
+ */
+declare function useRoom(roomId: string): Room;
+
+interface UseRoomFilesOptions {
+    /** Page size for both the initial load and `loadMore`. Default 50. */
+    pageSize?: number;
+}
+interface UseRoomFilesResult extends RoomFilesSnapshot {
+    /** The backing store — `refresh`, `loadMore`. */
+    store: RoomFilesStore;
+}
+/**
+ * Paginated media/file grid of a room (파일함·앨범). Newest first; call
+ * `store.loadMore()` from the grid's tail while `hasMore`, and
+ * `store.refresh()` after an upload to surface it at the head. Render
+ * thumbnails with `chat.fileThumbnailUrl(item.file.id, token)`.
+ *
+ * ```tsx
+ * const { media, hasMore, store } = useRoomFiles("room_123");
+ * ```
+ */
+declare function useRoomFiles(roomId: string, opts?: UseRoomFilesOptions): UseRoomFilesResult;
+
+interface UseRoomListResult extends RoomListSnapshot {
+    /** The backing store — `load`, `markRead`, `hideRoom`, `unhideRoom`. */
+    store: RoomListStore;
+}
+/**
+ * Live chat-room list (채팅 탭): previews, unread badges and
+ * most-recent-first ordering, kept fresh from WS streams.
+ *
+ * `opts.previewBuilder` / `opts.isRoomVisible` are read once (first
+ * render). Call `store.markRead(roomId)` when returning from a room screen
+ * to clear its badge.
+ *
+ * ```tsx
+ * const { rooms, totalUnread, store } = useRoomList();
+ * // ...
+ * {rooms.map((r) => (
+ *   <li key={r.roomId} onClick={() => openRoom(r.roomId)}>
+ *     {r.name} — {r.lastMessagePreview}
+ *     {r.unreadCount > 0 && <b>{r.unreadCount}</b>}
+ *   </li>
+ * ))}
+ * ```
+ */
+declare function useRoomList(opts?: RoomListStoreOptions): UseRoomListResult;
+
+interface UseRoomSettingsResult extends RoomSettingsSnapshot {
+    /** The backing store — `setMuted`, `setPushTrigger`, invite CRUD,
+     *  join-request inbox, `leave` / `clearHistory` / `deleteMyMessages`,
+     *  and operator moderation (`freeze`, `setPublic`, `muteMember`, …). */
+    store: RoomSettingsStore;
+}
+/**
+ * State + actions behind a room-settings screen (대화방 설정). Lists are
+ * lazy — call `store.loadInvites()` / `store.loadJoinRequests()` when the
+ * relevant section opens (both are operator-only server-side).
+ *
+ * ```tsx
+ * const { invites, joinRequests, store } = useRoomSettings("room_123");
+ * // ...
+ * <Switch onChange={(on) => store.setMuted(on)} />
+ * <button onClick={() => store.leave({ deleteMessages: "mine" })}>나가기</button>
+ * ```
+ */
+declare function useRoomSettings(roomId: string): UseRoomSettingsResult;
+
+interface UseTypingOptions {
+    /** How long (ms) a user stays "typing" without a fresh event before
+     *  auto-removal. Default 5000. */
+    timeoutMs?: number;
+}
+interface UseTypingResult {
+    /** User ids currently typing. */
+    typingUserIds: readonly string[];
+    isAnyoneTyping: boolean;
+    /** Broadcast the local user's typing state to the room (throttle it
+     *  yourself — one `true` per keystroke burst, `false` on blur/send). */
+    setTyping: (isTyping: boolean) => void;
+}
+/**
+ * Who is currently typing in a room, for a "… is typing" indicator.
+ *
+ * The server sends a `typing: true` event when someone starts, but a
+ * "stopped" event isn't guaranteed to arrive. To avoid a stuck indicator,
+ * each user is auto-removed after `timeoutMs` unless a fresh typing event
+ * resets their timer.
+ *
+ * ```tsx
+ * const { isAnyoneTyping, setTyping } = useTyping("room_123");
+ * // ...
+ * <span>{isAnyoneTyping ? "typing…" : ""}</span>
+ * <input onChange={() => setTyping(true)} onBlur={() => setTyping(false)} />
+ * ```
+ */
+declare function useTyping(roomId: string, opts?: UseTypingOptions): UseTypingResult;
+
+interface UseUnreadOptions {
+    /** Poll `chat.unreadSummary()` every N ms. Off by default (pull model —
+     *  call `refresh()` on focus / after reading a room). The endpoint is a
+     *  single cheap REST call, so a few seconds is a fine badge cadence. */
+    refreshIntervalMs?: number;
+}
+interface UseUnreadResult {
+    /** Total unread across all rooms. 0 until the first fetch resolves. */
+    total: number;
+    /** The full last-fetched summary (per-room breakdown in `rooms`),
+     *  or null before the first fetch. */
+    summary: UnreadSummary | null;
+    /** Fetch the latest unread summary now. */
+    refresh: () => Promise<void>;
+}
+/**
+ * The account-wide unread summary, for a badge. Fetches once on mount;
+ * refresh manually via `refresh()` or periodically via
+ * `refreshIntervalMs`.
+ *
+ * ```tsx
+ * const { total, refresh } = useUnread({ refreshIntervalMs: 15_000 });
+ * // ...
+ * <Badge count={total} />
+ * ```
+ */
+declare function useUnread(opts?: UseUnreadOptions): UseUnreadResult;
+
+export { type ChatMessage, type ChatMessageStatus, type MemberListSnapshot, MemberListStore, NoveraChatProvider, type NoveraChatProviderProps, type RoomFileItem, type RoomFilesSnapshot, RoomFilesStore, type RoomListItem, type RoomListSnapshot, RoomListStore, type RoomListStoreOptions, type RoomSettingsSnapshot, RoomSettingsStore, type RoomSnapshot, RoomStore, type UseMemberListResult, type UseMessagesOptions, type UseMessagesResult, type UseRoomFilesOptions, type UseRoomFilesResult, type UseRoomListResult, type UseRoomSettingsResult, type UseTypingOptions, type UseTypingResult, type UseUnreadOptions, type UseUnreadResult, chatMessageFromHistory, chatMessageFromLive, useMemberList, useMessages, useNoveraChat, useRoom, useRoomFiles, useRoomList, useRoomSettings, useTyping, useUnread };