@noverachat/sdk-react 0.3.0

package/package.json

@@ -0,0 +1,42 @@
+{
+  "name": "@noverachat/sdk-react",
+  "version": "0.3.0",
+  "description": "React hooks/bindings for NoveraChat — @noverachat/sdk-web 위에 얹는 얇은 래퍼",
+  "license": "MIT",
+  "type": "module",
+  "main": "./dist/index.cjs",
+  "module": "./dist/index.js",
+  "types": "./dist/index.d.ts",
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "import": "./dist/index.js",
+      "require": "./dist/index.cjs"
+    }
+  },
+  "files": [
+    "dist",
+    "src",
+    "README.md"
+  ],
+  "sideEffects": false,
+  "peerDependencies": {
+    "react": ">=18"
+  },
+  "dependencies": {
+    "@noverachat/sdk-web": "0.3.0"
+  },
+  "devDependencies": {
+    "@types/react": "^19.0.0",
+    "tsup": "^8.3.5",
+    "typescript": "^5.6.3",
+    "vitest": "^2.1.4"
+  },
+  "scripts": {
+    "build": "tsup src/index.ts --format esm,cjs --dts --clean",
+    "dev": "tsup src/index.ts --format esm,cjs --dts --watch",
+    "typecheck": "tsc --noEmit",
+    "test": "vitest run",
+    "test:watch": "vitest"
+  }
+}

package/src/chat-message.ts

@@ -0,0 +1,209 @@
+import type {
+  FileInline,
+  MessageOut,
+  ReactionEntry,
+  SenderMini,
+  WsChatReceive,
+} from "@noverachat/sdk-web";
+
+/** Delivery status of an outgoing (optimistic) message. */
+export type ChatMessageStatus = "sending" | "sent" | "failed";
+
+// Snake_case inline file shape as it rides on WS frames. Not exported from
+// the sdk-web index by name — derive it structurally from the frame type.
+type FileInlineWire = NonNullable<WsChatReceive["file"]>;
+
+/**
+ * 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.
+ */
+export 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;
+}
+
+function fileInlineFromWire(w: FileInlineWire): FileInline {
+  return {
+    id: w.id,
+    kind: w.kind,
+    mime: w.mime,
+    size: w.size,
+    name: w.name ?? null,
+    width: w.width ?? null,
+    height: w.height ?? null,
+    durationSec: w.duration_sec ?? null,
+    thumbnailStatus: w.thumbnail_status,
+    forwardBlocked: Boolean(w.forward_blocked),
+  };
+}
+
+/** Build a `ChatMessage` from server history (REST). */
+export function chatMessageFromHistory(m: MessageOut): ChatMessage {
+  return {
+    id: m.messageId,
+    senderId: m.senderId ?? null,
+    content: m.content ?? null,
+    createdAtMs: m.createdAtMs,
+    status: "sent",
+    messageType: m.messageType,
+    sender: m.sender ?? null,
+    customType: m.customType ?? null,
+    fileId: m.fileId ?? null,
+    file: m.file ?? null,
+    files: m.files ?? null,
+    replyToId: m.replyToId ?? null,
+    reactions: m.reactions ?? [],
+    customMeta: m.customMeta ?? null,
+    editedCount: m.editedCount ?? 0,
+    uploadProgress: null,
+    tempId: null,
+    isDeleted: m.deletedAt != null,
+  };
+}
+
+/** Build a `ChatMessage` from a live inbound frame (WS). */
+export function chatMessageFromLive(f: WsChatReceive): ChatMessage {
+  const data = f.data ?? null;
+  const customMeta =
+    data && typeof data === "object" && "_customMeta" in data
+      ? ((data as Record<string, unknown>)._customMeta as
+          | Record<string, unknown>
+          | null)
+      : null;
+  return {
+    id: f.message_id,
+    senderId: f.sender_id,
+    content: f.content ?? null,
+    createdAtMs: f.created_at,
+    status: "sent",
+    messageType: f.message_type,
+    sender: null,
+    customType: f.custom_type ?? null,
+    fileId: f.file_id ?? null,
+    file: f.file ? fileInlineFromWire(f.file) : null,
+    files: f.files ? f.files.map(fileInlineFromWire) : null,
+    replyToId: f.reply_to_id ?? null,
+    reactions: [],
+    customMeta,
+    editedCount: 0,
+    uploadProgress: null,
+    tempId: null,
+    isDeleted: false,
+  };
+}
+
+/** An optimistic bubble for a message we just sent, before the server acks. */
+export function pendingChatMessage(p: {
+  tempId: string;
+  content: string;
+  replyToId?: string;
+  customType?: string;
+  customMeta?: Record<string, unknown>;
+}): ChatMessage {
+  return {
+    id: p.tempId,
+    senderId: null,
+    content: p.content,
+    createdAtMs: Date.now(),
+    status: "sending",
+    messageType: "TEXT",
+    sender: null,
+    customType: p.customType ?? null,
+    fileId: null,
+    file: null,
+    files: null,
+    replyToId: p.replyToId ?? null,
+    reactions: [],
+    customMeta: p.customMeta ?? null,
+    editedCount: 0,
+    uploadProgress: null,
+    tempId: p.tempId,
+    isDeleted: false,
+  };
+}
+
+/** An optimistic bubble for a FILE message whose bytes are still uploading.
+ *  `uploadProgress` starts at 0 and is advanced by `RoomStore`. */
+export function pendingFileChatMessage(p: {
+  tempId: string;
+  name: string;
+  mime?: string;
+  size?: number;
+}): ChatMessage {
+  const mime = p.mime ?? "application/octet-stream";
+  return {
+    id: p.tempId,
+    senderId: null,
+    content: null,
+    createdAtMs: Date.now(),
+    status: "sending",
+    messageType: "FILE",
+    sender: null,
+    customType: null,
+    fileId: null,
+    file: {
+      id: "",
+      kind: mime.startsWith("image/")
+        ? "image"
+        : mime.startsWith("video/")
+          ? "video"
+          : "file",
+      mime,
+      size: p.size ?? 0,
+      name: p.name,
+      thumbnailStatus: "pending",
+      forwardBlocked: false,
+    },
+    files: null,
+    replyToId: null,
+    reactions: [],
+    customMeta: null,
+    editedCount: 0,
+    uploadProgress: 0,
+    tempId: p.tempId,
+    isDeleted: false,
+  };
+}

package/src/context.tsx

@@ -0,0 +1,72 @@
+import {
+  createContext,
+  useContext,
+  useEffect,
+  useState,
+  type ReactNode,
+} from "react";
+import { NoveraChat, type ClientOptions } from "@noverachat/sdk-web";
+
+const NoveraChatContext = createContext<NoveraChat | null>(null);
+
+export 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>
+ * ```
+ */
+export function NoveraChatProvider(props: NoveraChatProviderProps): ReactNode {
+  // useState initializer = create exactly once per mounted provider.
+  const [chat] = useState(() => new NoveraChat(props.options));
+
+  useEffect(() => {
+    void chat.connect();
+    return () => chat.disconnect();
+  }, [chat]);
+
+  return (
+    <NoveraChatContext.Provider value={chat}>
+      {props.children}
+    </NoveraChatContext.Provider>
+  );
+}
+
+/**
+ * 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");
+ * ```
+ */
+export function useNoveraChat(): NoveraChat {
+  const chat = useContext(NoveraChatContext);
+  if (!chat) {
+    throw new Error(
+      "useNoveraChat() called with no NoveraChatProvider in the tree.",
+    );
+  }
+  return chat;
+}

package/src/index.ts

@@ -0,0 +1,83 @@
+/**
+ * @noverachat/sdk-react — NoveraChat React 바인딩.
+ *
+ * `@noverachat/sdk-web`(NoveraChat/Room 파사드) 위의 얇은 훅 레이어.
+ * 채팅 로직을 재구현하지 않고, SDK 이벤트를 React 상태로 옮기고 언마운트
+ * 정리를 대신한다.
+ *
+ *   - NoveraChatProvider / useNoveraChat  클라이언트 생성 + connect/disconnect
+ *   - useRoom(roomId)                     Room 파사드 접근
+ *   - useMessages(roomId)                 메시지 리스트 + 낙관적 send (RoomStore)
+ *   - useTyping(roomId)                   "입력 중…" 표시
+ *   - useUnread()                         안읽음 뱃지
+ *   - useRoomList()                       채팅방 리스트 (채팅 탭)
+ *   - useMemberList(roomId)               멤버 목록 + presence
+ *   - useRoomFiles(roomId)                파일함·앨범 페이지네이션
+ *   - useRoomSettings(roomId)             방 설정 액션 (무음·초대·모더레이션)
+ */
+
+// Re-export the headless core so consumers get `NoveraChat`, `Room`,
+// `ClientOptions`, message/event types, etc. from a single import.
+export * from "@noverachat/sdk-web";
+
+export {
+  chatMessageFromHistory,
+  chatMessageFromLive,
+  type ChatMessage,
+  type ChatMessageStatus,
+} from "./chat-message.js";
+export {
+  NoveraChatProvider,
+  useNoveraChat,
+  type NoveraChatProviderProps,
+} from "./context.js";
+export {
+  MemberListStore,
+  type MemberListSnapshot,
+} from "./member-list-store.js";
+export {
+  RoomFilesStore,
+  type RoomFileItem,
+  type RoomFilesSnapshot,
+} from "./room-files-store.js";
+export {
+  RoomListStore,
+  type RoomListItem,
+  type RoomListSnapshot,
+  type RoomListStoreOptions,
+} from "./room-list-store.js";
+export {
+  RoomSettingsStore,
+  type RoomSettingsSnapshot,
+} from "./room-settings-store.js";
+export { RoomStore, type RoomSnapshot } from "./room-store.js";
+export {
+  useMessages,
+  type UseMessagesOptions,
+  type UseMessagesResult,
+} from "./use-messages.js";
+export {
+  useMemberList,
+  type UseMemberListResult,
+} from "./use-member-list.js";
+export { useRoom } from "./use-room.js";
+export {
+  useRoomFiles,
+  type UseRoomFilesOptions,
+  type UseRoomFilesResult,
+} from "./use-room-files.js";
+export { useRoomList, type UseRoomListResult } from "./use-room-list.js";
+export {
+  useRoomSettings,
+  type UseRoomSettingsResult,
+} from "./use-room-settings.js";
+export {
+  useTyping,
+  type UseTypingOptions,
+  type UseTypingResult,
+} from "./use-typing.js";
+export {
+  useUnread,
+  type UseUnreadOptions,
+  type UseUnreadResult,
+} from "./use-unread.js";

package/src/internal/compare-id.ts

@@ -0,0 +1,17 @@
+/**
+ * Snowflake ids are 63-bit ints as strings — compare via BigInt (numeric
+ * `>` on the string form is wrong for unequal lengths). Private copy of the
+ * core's internal helper.
+ */
+export function idGreater(
+  a: string | null | undefined,
+  b: string | null | undefined,
+): boolean {
+  if (!a || a === "0") return false;
+  if (!b || b === "0") return true;
+  try {
+    return BigInt(a) > BigInt(b);
+  } catch {
+    return a > b;
+  }
+}

package/src/member-list-store.ts

@@ -0,0 +1,116 @@
+import type { NoveraChat, RoomMemberOut, WsPresence } from "@noverachat/sdk-web";
+
+export 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.
+ */
+export class MemberListStore {
+  private readonly chat: NoveraChat;
+  readonly roomId: string;
+  private readonly listeners = new Set<() => void>();
+
+  private members: RoomMemberOut[] = [];
+  private unsubs: Array<() => void> = [];
+  private reloadTimer: ReturnType<typeof setTimeout> | null = null;
+  private snapshot: MemberListSnapshot = {
+    members: [],
+    operators: [],
+    activeMemberIds: [],
+  };
+  private attached = false;
+
+  constructor(chat: NoveraChat, roomId: string) {
+    this.chat = chat;
+    this.roomId = roomId;
+  }
+
+  attach(): void {
+    if (this.attached) return;
+    this.attached = true;
+    this.unsubs.push(
+      this.chat.on("roomEvent", (e) => {
+        if (e.room_id === this.roomId) this.scheduleReload();
+      }),
+      this.chat.on("presence", (f) => this.onPresence(f)),
+    );
+  }
+
+  dispose(): void {
+    if (!this.attached) return;
+    this.attached = false;
+    if (this.reloadTimer) clearTimeout(this.reloadTimer);
+    this.reloadTimer = null;
+    for (const u of this.unsubs.splice(0)) u();
+  }
+
+  // ── external-store contract ─────────────────────────────────────
+
+  readonly subscribe = (fn: () => void): (() => void) => {
+    this.listeners.add(fn);
+    return () => this.listeners.delete(fn);
+  };
+
+  readonly getSnapshot = (): MemberListSnapshot => this.snapshot;
+
+  private emit(): void {
+    this.snapshot = {
+      members: [...this.members],
+      operators: this.members.filter((m) => m.role === "OPERATOR"),
+      activeMemberIds: this.members
+        .filter((m) => m.role !== "KICKED")
+        .map((m) => m.userId),
+    };
+    for (const fn of this.listeners) fn();
+  }
+
+  /** Whether `userId` is an OPERATOR of this room. */
+  isOperator(userId: string): boolean {
+    return this.members.some(
+      (m) => m.userId === userId && m.role === "OPERATOR",
+    );
+  }
+
+  /** Fetch the member list. Also called automatically on membership
+   *  events. */
+  async load(): Promise<void> {
+    const list = await this.chat.room(this.roomId).listMembers();
+    if (!this.attached) return;
+    this.members = list;
+    this.emit();
+  }
+
+  // ── internals ───────────────────────────────────────────────────
+
+  private onPresence(f: WsPresence): void {
+    const i = this.members.findIndex((m) => m.userId === f.user_id);
+    if (i === -1) return;
+    this.members[i] = { ...this.members[i]!, isOnline: f.online };
+    this.emit();
+  }
+
+  private scheduleReload(): void {
+    if (this.reloadTimer) clearTimeout(this.reloadTimer);
+    this.reloadTimer = setTimeout(() => {
+      this.reloadTimer = null;
+      if (this.attached) void this.load();
+    }, 300);
+  }
+}

package/src/room-files-store.ts

@@ -0,0 +1,130 @@
+import type { FileMeta, NoveraChat } from "@noverachat/sdk-web";
+
+/** One (message, file) entry of a room's shared-file list — the same shape
+ *  `room.listFiles()` returns per item. */
+export interface RoomFileItem {
+  messageId: string;
+  senderId: string | null;
+  createdAtMs: number;
+  file: FileMeta;
+}
+
+export 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)`.
+ */
+export class RoomFilesStore {
+  private readonly chat: NoveraChat;
+  readonly roomId: string;
+  /** Page size for both `refresh` and `loadMore`. */
+  readonly pageSize: number;
+  private readonly listeners = new Set<() => void>();
+
+  private items: RoomFileItem[] = [];
+  private cursor: string | null = null;
+  private hasMore = false;
+  private loading = false;
+  private attached = false;
+  private snapshot: RoomFilesSnapshot = {
+    items: [],
+    media: [],
+    hasMore: false,
+    isLoading: false,
+  };
+
+  constructor(chat: NoveraChat, roomId: string, pageSize = 50) {
+    this.chat = chat;
+    this.roomId = roomId;
+    this.pageSize = pageSize;
+  }
+
+  /** No realtime subscriptions — kept for lifecycle symmetry with the
+   *  other stores (guards in-flight results after unmount). */
+  attach(): void {
+    this.attached = true;
+  }
+
+  dispose(): void {
+    this.attached = false;
+  }
+
+  // ── external-store contract ─────────────────────────────────────
+
+  readonly subscribe = (fn: () => void): (() => void) => {
+    this.listeners.add(fn);
+    return () => this.listeners.delete(fn);
+  };
+
+  readonly getSnapshot = (): RoomFilesSnapshot => this.snapshot;
+
+  private emit(): void {
+    this.snapshot = {
+      items: [...this.items],
+      media: this.items.filter(
+        (it) => it.file.kind === "image" || it.file.kind === "video",
+      ),
+      hasMore: this.hasMore,
+      isLoading: this.loading,
+    };
+    for (const fn of this.listeners) fn();
+  }
+
+  // ── actions ─────────────────────────────────────────────────────
+
+  /** Reload from the newest page (clears what was loaded). */
+  async refresh(): Promise<void> {
+    if (this.loading) return;
+    this.loading = true;
+    this.emit();
+    try {
+      const page = await this.chat
+        .room(this.roomId)
+        .listFiles({ limit: this.pageSize });
+      if (!this.attached) return;
+      this.items = page.items;
+      this.cursor = page.nextCursor;
+      this.hasMore = page.hasMore;
+    } finally {
+      this.loading = false;
+      if (this.attached) this.emit();
+    }
+  }
+
+  /** Fetch the next older page and append it. No-op while loading or when
+   *  `hasMore` is false. Returns the number of entries added. */
+  async loadMore(): Promise<number> {
+    const cursor = this.cursor;
+    if (this.loading || !this.hasMore || cursor == null) return 0;
+    this.loading = true;
+    this.emit();
+    try {
+      const page = await this.chat
+        .room(this.roomId)
+        .listFiles({ limit: this.pageSize, before: cursor });
+      if (!this.attached) return 0;
+      this.items = [...this.items, ...page.items];
+      this.cursor = page.nextCursor;
+      this.hasMore = page.hasMore;
+      return page.items.length;
+    } finally {
+      this.loading = false;
+      if (this.attached) this.emit();
+    }
+  }
+}