@noverachat/sdk-react 0.3.0 → 0.5.0

package/README.ko.md

@@ -4,6 +4,8 @@
 
 NoveraChat용 React 훅/바인딩 — [`@noverachat/sdk-web`](../sdk-web)(헤드리스 `NoveraChat` / `Room` 코어) 위의 얇은 레이어. 채팅 로직을 재구현하지 않고 채팅 UI도 제공하지 않는다 — 이 패키지는 글루만 담당한다: 라이프사이클을 관리하는 프로바이더와, SDK 이벤트를 React 상태로 옮기는 훅들.
 
+> 팁: 클라이언트 옵션에 [`cacheStore`](../sdk-web/docs/core/caching.ko.md)만 주입하면 `useMessages`가 콜드 스타트에서 마지막 히스토리를 즉시 렌더한다(스냅샷 캐시) — 화면 코드 변경 없음.
+
 ## 설치
 
 ```sh

package/README.md

@@ -4,6 +4,8 @@
 
 React hooks/bindings for NoveraChat — a thin layer over [`@noverachat/sdk-web`](../sdk-web) (the headless `NoveraChat` / `Room` core). It does NOT reimplement chat logic and it does NOT ship chat UI — this package is only the glue: a lifecycle-managed provider and hooks that turn the SDK's events into React state.
 
+> Tip: inject a [`cacheStore`](../sdk-web/docs/core/caching.md) in the client options and `useMessages` renders the last known history instantly on cold start (snapshot cache) — zero screen-code changes.
+
 ## Install
 
 ```sh

package/dist/index.cjs

@@ -27,8 +27,8 @@ __export(index_exports, {
   RoomListStore: () => RoomListStore,
   RoomSettingsStore: () => RoomSettingsStore,
   RoomStore: () => RoomStore,
-  chatMessageFromHistory: () => chatMessageFromHistory,
-  chatMessageFromLive: () => chatMessageFromLive,
+  chatMessageFromHistory: () => import_sdk_web.chatMessageFromHistory,
+  chatMessageFromLive: () => import_sdk_web.chatMessageFromLive,
   useMemberList: () => useMemberList,
   useMessages: () => useMessages,
   useNoveraChat: () => useNoveraChat,
@@ -43,127 +43,15 @@ module.exports = __toCommonJS(index_exports);
 __reExport(index_exports, require("@noverachat/sdk-web"), module.exports);
 
 // src/chat-message.ts
-function fileInlineFromWire(w) {
-  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)
-  };
-}
-function chatMessageFromHistory(m) {
-  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
-  };
-}
-function chatMessageFromLive(f) {
-  const data = f.data ?? null;
-  const customMeta = data && typeof data === "object" && "_customMeta" in data ? data._customMeta : 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
-  };
-}
-function pendingChatMessage(p) {
-  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
-  };
-}
-function pendingFileChatMessage(p) {
-  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
-  };
-}
+var import_sdk_web = require("@noverachat/sdk-web");
 
 // src/context.tsx
 var import_react = require("react");
-var import_sdk_web = require("@noverachat/sdk-web");
+var import_sdk_web2 = require("@noverachat/sdk-web");
 var import_jsx_runtime = require("react/jsx-runtime");
 var NoveraChatContext = (0, import_react.createContext)(null);
 function NoveraChatProvider(props) {
-  const [chat] = (0, import_react.useState)(() => new import_sdk_web.NoveraChat(props.options));
+  const [chat] = (0, import_react.useState)(() => new import_sdk_web2.NoveraChat(props.options));
   (0, import_react.useEffect)(() => {
     void chat.connect();
     return () => chat.disconnect();
@@ -357,7 +245,7 @@ function itemFromUnread(r) {
     lastMessagePreview: r.lastMessagePreview ?? null,
     memberCount: r.memberCount ?? 0,
     members,
-    lastMessageAtMs: null,
+    lastMessageAtMs: r.lastMessageAt ?? null,
     anyMemberOnline: members.some((m) => m.isOnline === true)
   };
 }
@@ -626,29 +514,13 @@ var RoomSettingsStore = class {
   }
 };
 
-// src/internal/compare-id.ts
-function idGreater(a, b) {
-  if (!a || a === "0") return false;
-  if (!b || b === "0") return true;
-  try {
-    return BigInt(a) > BigInt(b);
-  } catch {
-    return a > b;
-  }
-}
-
 // src/room-store.ts
-var uploadSeq = 0;
 var RoomStore = class {
   chat;
   roomId;
   listeners = /* @__PURE__ */ new Set();
-  unsubs = [];
-  messages = [];
-  readWatermarks = {};
-  hasMore = false;
-  oldestCursor = null;
-  loadingMore = false;
+  col = null;
+  colUnsub = null;
   historyRequested = false;
   snapshot;
   attached = false;
@@ -667,22 +539,25 @@ var RoomStore = class {
   get room() {
     return this.chat.room(this.roomId);
   }
-  /** Subscribe to WS events + page lifecycle. Safe to call repeatedly
-   *  (no-op while attached) — matches React 18/19 StrictMode's
+  /** The backing collection, bound to the CURRENT facade. Recreated when
+   *  the facade was dropped (post-`chat.disconnect()`) — the old one would
+   *  never receive dispatches again. */
+  collection() {
+    const facade = this.room;
+    if (this.col && this.col.room === facade) return this.col;
+    this.colUnsub?.();
+    this.col = facade.collection();
+    this.colUnsub = this.col.on("change", () => this.rebuild());
+    this.rebuild();
+    return this.col;
+  }
+  /** Subscribe page lifecycle + ensure the collection is live. Safe to call
+   *  repeatedly (no-op while attached) — matches React 18/19 StrictMode's
    *  mount → cleanup → mount effect cycle. */
   attach() {
     if (this.attached) return;
     this.attached = true;
-    const room = this.room;
-    this.unsubs.push(
-      room.on("message", (f) => this.onIncoming(f)),
-      room.on("messageUpdated", (f) => this.onUpdated(f)),
-      room.on("messageDeleted", (f) => this.onDeleted(f)),
-      room.on("messagesCleared", (f) => this.onCleared(f)),
-      room.on("reactionAdded", (f) => this.onReactionAdded(f)),
-      room.on("reactionRemoved", (f) => this.onReactionRemoved(f)),
-      room.on("syncTick", (f) => this.onSyncTick(f))
-    );
+    this.collection();
     if (typeof document !== "undefined") {
       document.addEventListener("visibilitychange", this.onVisibilityChange);
     }
@@ -690,13 +565,13 @@ var RoomStore = class {
       window.addEventListener("pagehide", this.onPageHide);
     }
   }
-  /** Unsubscribe everything and flush the pending read watermark. The store
-   *  keeps its message state, so a later `attach()` resumes cleanly. */
+  /** Detach page listeners and flush the pending read watermark. The
+   *  collection (and its state) survives, so a later `attach()` resumes
+   *  cleanly — StrictMode's mount → cleanup → mount cycle keeps messages. */
   dispose() {
     if (!this.attached) return;
     this.attached = false;
     this.room.flushMarkRead();
-    for (const u of this.unsubs.splice(0)) u();
     if (typeof document !== "undefined") {
       document.removeEventListener("visibilitychange", this.onVisibilityChange);
     }
@@ -711,59 +586,42 @@ var RoomStore = class {
     return () => this.listeners.delete(fn);
   };
   getSnapshot = () => this.snapshot;
-  emit() {
+  rebuild() {
+    const col = this.col;
+    if (!col) return;
     this.snapshot = {
-      messages: [...this.messages],
-      hasMore: this.hasMore,
-      readWatermarks: { ...this.readWatermarks }
+      messages: [...col.messages],
+      hasMore: col.hasMore,
+      readWatermarks: { ...col.readWatermarks }
     };
     for (const fn of this.listeners) fn();
   }
   // ── read receipts ───────────────────────────────────────────────
   /** Whether `userId` has read `messageId` according to the latest watermark. */
   isReadBy(userId, messageId) {
-    const w = this.readWatermarks[userId];
-    if (!w) return false;
-    return !idGreater(messageId, w);
+    return this.collection().isReadBy(userId, messageId);
   }
   /** 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, userIds) {
-    let n = 0;
-    for (const u of userIds) if (this.isReadBy(u, messageId)) n++;
-    return n;
+    return this.collection().readCount(messageId, userIds);
   }
   // ── history ─────────────────────────────────────────────────────
-  /** Load the most recent page of history and prepend it. No-op after the
-   *  first call (StrictMode double-mount safe) — use `loadMore` for
-   *  scrollback. */
+  /** Load the most recent page of history. No-op after the first call
+   *  (StrictMode double-mount safe) — use `loadMore` for scrollback.
+   *  캐시(`ClientOptions.cacheStore`)가 켜져 있으면 스냅샷 즉시 렌더 →
+   *  API 도착 시 통째 교체가 컬렉션 안에서 일어난다. */
   async loadHistory(limit = 50) {
     if (this.historyRequested) return;
     this.historyRequested = true;
-    const page = await this.room.listRecent(limit);
-    this.messages.unshift(...page.items.map(chatMessageFromHistory));
-    this.oldestCursor = page.nextCursor;
-    this.hasMore = page.hasMore;
-    this.emit();
+    await this.collection().load(limit);
   }
   /** 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. */
-  async loadMore(limit = 50) {
-    const cursor = this.oldestCursor;
-    if (this.loadingMore || !this.hasMore || cursor == null) return 0;
-    this.loadingMore = true;
-    try {
-      const page = await this.room.listBefore(cursor, limit);
-      this.messages.unshift(...page.items.map(chatMessageFromHistory));
-      this.oldestCursor = page.nextCursor;
-      this.hasMore = page.hasMore;
-      this.emit();
-      return page.items.length;
-    } finally {
-      this.loadingMore = false;
-    }
+  loadMore(limit = 50) {
+    return this.collection().loadMore(limit);
   }
   // ── outgoing ────────────────────────────────────────────────────
   /** Send `text` optimistically: a `sending` bubble appears immediately,
@@ -772,221 +630,45 @@ var RoomStore = class {
    *  Optional extras ride along: `replyToId` for replies, `customType` /
    *  `customMeta` for app-defined conventions (e.g. message priority). */
   send(text, opts) {
-    void (async () => {
-      let tempId;
-      let ackPromise;
-      try {
-        const sent = await this.room.send({
-          content: text,
-          ...opts?.replyToId ? { replyToId: opts.replyToId } : {},
-          ...opts?.customType ? { customType: opts.customType } : {},
-          ...opts?.customMeta ? { customMeta: opts.customMeta } : {}
-        });
-        tempId = sent.tempId;
-        ackPromise = sent.messageId;
-      } catch {
-        const localId = `failed_${Date.now()}_${uploadSeq++}`;
-        this.messages.push({
-          ...pendingChatMessage({ tempId: localId, content: text, ...opts }),
-          status: "failed"
-        });
-        this.emit();
-        return;
-      }
-      this.messages.push(
-        pendingChatMessage({ tempId, content: text, ...opts })
-      );
-      this.emit();
-      this.bindAck(tempId, ackPromise);
-    })();
+    this.collection().send(text, opts);
   }
   /** 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`). */
-  async sendFile(file, opts) {
-    const localId = `upload_${Date.now()}_${uploadSeq++}`;
-    this.messages.push(
-      pendingFileChatMessage({
-        tempId: localId,
-        name: opts?.name ?? file.name,
-        mime: file.type,
-        size: file.size
-      })
-    );
-    this.emit();
-    try {
-      const sent = await this.room.sendFile(file, {
-        ...opts ?? {},
-        onProgress: (p) => {
-          this.mutateByTempId(localId, (m) => ({
-            ...m,
-            uploadProgress: p.ratio
-          }));
-          opts?.onProgress?.(p);
-        }
-      });
-      this.mutateByTempId(localId, (m) => ({
-        ...m,
-        fileId: sent.fileId,
-        file: m.file ? { ...m.file, id: sent.fileId } : m.file,
-        uploadProgress: null
-      }));
-      const realId = await sent.messageId;
-      this.mutateByTempId(localId, (m) => ({
-        ...m,
-        id: realId,
-        status: "sent"
-      }));
-    } catch {
-      this.mutateByTempId(localId, (m) => ({
-        ...m,
-        status: "failed",
-        uploadProgress: null
-      }));
-    }
+  sendFile(file, opts) {
+    return this.collection().sendFile(file, opts);
   }
   /** Edit a message's content (server-side; peers get `message_updated`).
    *  The local copy updates optimistically. */
-  async edit(messageId, content) {
-    await this.room.edit(messageId, { content });
-    this.mutateById(messageId, (m) => ({
-      ...m,
-      content,
-      editedCount: m.editedCount + 1
-    }));
+  edit(messageId, content) {
+    return this.collection().edit(messageId, content);
   }
   /** Delete a message. `scope: "ALL"` (default) removes it for everyone;
    *  `"MY"` hides it only for the caller. Local copy flips to deleted. */
-  async delete(messageId, scope = "ALL") {
-    await this.room.delete(messageId, scope);
-    this.mutateById(messageId, (m) => ({ ...m, isDeleted: true }));
+  delete(messageId, scope = "ALL") {
+    return this.collection().delete(messageId, scope);
   }
   /** 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. */
-  async toggleReaction(messageId, key, myUserId) {
-    const m = this.messages.find((x) => x.id === messageId);
-    const mine = m?.reactions.some(
-      (r) => r.key === key && r.userIds.includes(myUserId)
-    ) ?? false;
-    if (mine) {
-      await this.room.unreact(messageId, key);
-    } else {
-      await this.room.react(messageId, key);
-    }
+  toggleReaction(messageId, key, myUserId) {
+    return this.collection().toggleReaction(messageId, key, myUserId);
   }
   /** Search this room's messages (server-side, content substring match).
    *  Returns view models without touching the message list. */
   async search(q, limit = 30) {
     const page = await this.room.search(q, { limit });
-    return page.items.map(chatMessageFromHistory);
+    return page.items.map(import_sdk_web.chatMessageFromHistory);
   }
   /** Mark `messageId` read (debounced inside the SDK). */
   markRead(messageId) {
-    this.room.markRead(messageId);
-  }
-  // ── event handlers ──────────────────────────────────────────────
-  onIncoming(f) {
-    this.messages.push(chatMessageFromLive(f));
-    this.emit();
-  }
-  onUpdated(f) {
-    this.mutateById(f.message_id, (m) => ({
-      ...m,
-      content: f.content ?? m.content,
-      editedCount: m.editedCount + 1
-    }));
-  }
-  onDeleted(f) {
-    this.mutateById(f.message_id, (m) => ({ ...m, isDeleted: true }));
-  }
-  onCleared(f) {
-    const upTo = f.up_to_message_id;
-    let changed = false;
-    this.messages = this.messages.map((m) => {
-      if (!m.isDeleted && (upTo == null || !idGreater(m.id, upTo))) {
-        changed = true;
-        return { ...m, isDeleted: true };
-      }
-      return m;
-    });
-    if (changed) this.emit();
-  }
-  onReactionAdded(f) {
-    this.mutateById(f.message_id, (m) => {
-      const next = m.reactions.map(
-        (r) => r.key === f.reaction_key ? {
-          key: r.key,
-          userIds: [.../* @__PURE__ */ new Set([...r.userIds, f.user_id])],
-          updatedAt: f.updated_at
-        } : r
-      );
-      if (!next.some((r) => r.key === f.reaction_key)) {
-        next.push({
-          key: f.reaction_key,
-          userIds: [f.user_id],
-          updatedAt: f.updated_at
-        });
-      }
-      return { ...m, reactions: next };
-    });
-  }
-  onReactionRemoved(f) {
-    this.mutateById(f.message_id, (m) => {
-      const next = [];
-      for (const r of m.reactions) {
-        if (r.key !== f.reaction_key) {
-          next.push(r);
-          continue;
-        }
-        const users = r.userIds.filter((u) => u !== f.user_id);
-        if (users.length > 0) {
-          next.push({ key: r.key, userIds: users, updatedAt: f.updated_at });
-        }
-      }
-      return { ...m, reactions: next };
-    });
-  }
-  onSyncTick(f) {
-    let changed = false;
-    for (const [userId, mid] of Object.entries(f.read_states)) {
-      const cur = this.readWatermarks[userId];
-      if (!cur || idGreater(mid, cur)) {
-        this.readWatermarks[userId] = mid;
-        changed = true;
-      }
-    }
-    if (changed) this.emit();
+    this.collection().markRead(messageId);
   }
   onVisibilityChange = () => {
     if (typeof document !== "undefined" && document.visibilityState === "hidden") {
       this.room.flushMarkRead();
     }
   };
-  // ── helpers ─────────────────────────────────────────────────────
-  bindAck(tempId, messageId) {
-    messageId.then((realId) => {
-      this.mutateByTempId(tempId, (m) => ({
-        ...m,
-        id: realId,
-        status: "sent"
-      }));
-    }).catch(() => {
-      this.mutateByTempId(tempId, (m) => ({ ...m, status: "failed" }));
-    });
-  }
-  mutateById(id, f) {
-    const i = this.messages.findIndex((m) => m.id === id);
-    if (i === -1) return;
-    this.messages[i] = f(this.messages[i]);
-    this.emit();
-  }
-  mutateByTempId(tempId, f) {
-    const i = this.messages.findIndex((m) => m.tempId === tempId);
-    if (i === -1) return;
-    this.messages[i] = f(this.messages[i]);
-    this.emit();
-  }
 };
 
 // src/use-messages.ts