@noverachat/sdk-react 0.3.0

package/src/room-store.ts

@@ -0,0 +1,475 @@
+import type {
+  DeleteScope,
+  NoveraChat,
+  ReactionEntry,
+  Room,
+  SendFileOptions,
+  WsChatReceive,
+  WsMessageDeleted,
+  WsMessagesCleared,
+  WsMessageUpdated,
+  WsReactionAdded,
+  WsReactionRemoved,
+  WsSyncTick,
+} from "@noverachat/sdk-web";
+
+import {
+  chatMessageFromHistory,
+  chatMessageFromLive,
+  pendingChatMessage,
+  pendingFileChatMessage,
+  type ChatMessage,
+} from "./chat-message.js";
+import { idGreater } from "./internal/compare-id.js";
+
+/** Immutable snapshot handed to React via `useSyncExternalStore`. A new
+ *  object (new array/record identities) is produced on every change. */
+export 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>>;
+}
+
+let uploadSeq = 0;
+
+/**
+ * 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");
+ * ```
+ */
+export class RoomStore {
+  private readonly chat: NoveraChat;
+  readonly roomId: string;
+  private readonly listeners = new Set<() => void>();
+  private readonly unsubs: Array<() => void> = [];
+
+  private messages: ChatMessage[] = [];
+  private readWatermarks: Record<string, string> = {};
+  private hasMore = false;
+  private oldestCursor: string | null = null;
+  private loadingMore = false;
+  private historyRequested = false;
+  private snapshot: RoomSnapshot;
+  private attached = false;
+  private readonly onPageHide = () => this.room.flushMarkRead();
+
+  constructor(chat: NoveraChat, roomId: string) {
+    this.chat = chat;
+    this.roomId = roomId;
+    this.snapshot = {
+      messages: [],
+      hasMore: false,
+      readWatermarks: {},
+    };
+  }
+
+  /** 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(): 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
+   *  mount → cleanup → mount effect cycle. */
+  attach(): void {
+    if (this.attached) return;
+    this.attached = true;
+    const room = this.room; // resolve once — all subs must share one facade
+    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)),
+    );
+    // Flush the pending read watermark when the tab goes to the background,
+    // so the last-read position isn't lost to the debounce window.
+    if (typeof document !== "undefined") {
+      document.addEventListener("visibilitychange", this.onVisibilityChange);
+    }
+    if (typeof window !== "undefined") {
+      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. */
+  dispose(): void {
+    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);
+    }
+    if (typeof window !== "undefined") {
+      window.removeEventListener("pagehide", this.onPageHide);
+    }
+  }
+
+  // ── external-store contract ─────────────────────────────────────
+
+  /** `useSyncExternalStore`-compatible subscribe. Returns an unsubscribe fn. */
+  readonly subscribe = (fn: () => void): (() => void) => {
+    this.listeners.add(fn);
+    return () => this.listeners.delete(fn);
+  };
+
+  readonly getSnapshot = (): RoomSnapshot => this.snapshot;
+
+  private emit(): void {
+    this.snapshot = {
+      messages: [...this.messages],
+      hasMore: this.hasMore,
+      readWatermarks: { ...this.readWatermarks },
+    };
+    for (const fn of this.listeners) fn();
+  }
+
+  // ── read receipts ───────────────────────────────────────────────
+
+  /** Whether `userId` has read `messageId` according to the latest watermark. */
+  isReadBy(userId: string, messageId: string): boolean {
+    const w = this.readWatermarks[userId];
+    if (!w) return false;
+    return !idGreater(messageId, w);
+  }
+
+  /** 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 {
+    let n = 0;
+    for (const u of userIds) if (this.isReadBy(u, messageId)) n++;
+    return n;
+  }
+
+  // ── 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. */
+  async loadHistory(limit = 50): Promise<void> {
+    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();
+  }
+
+  /** 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): Promise<number> {
+    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;
+    }
+  }
+
+  // ── outgoing ────────────────────────────────────────────────────
+
+  /** 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 {
+    void (async () => {
+      let tempId: string;
+      let ackPromise: Promise<string>;
+      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 {
+        // WS not open — surface a failed bubble rather than throwing into
+        // the void (send() is fire-and-forget).
+        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);
+    })();
+  }
+
+  /** 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: File, opts?: SendFileOptions): Promise<void> {
+    // Local temp id for the optimistic bubble — the real WS temp id only
+    // exists after the upload commits (sendFile resolves then).
+    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);
+        },
+      });
+      // Upload committed — bind the bubble to the real file id and ack.
+      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,
+      }));
+    }
+  }
+
+  /** Edit a message's content (server-side; peers get `message_updated`).
+   *  The local copy updates optimistically. */
+  async edit(messageId: string, content: string): Promise<void> {
+    await this.room.edit(messageId, { content });
+    this.mutateById(messageId, (m) => ({
+      ...m,
+      content,
+      editedCount: m.editedCount + 1,
+    }));
+  }
+
+  /** 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: string, scope: DeleteScope = "ALL"): Promise<void> {
+    await this.room.delete(messageId, scope);
+    this.mutateById(messageId, (m) => ({ ...m, isDeleted: true }));
+  }
+
+  /** 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: string,
+    key: string,
+    myUserId: string,
+  ): Promise<void> {
+    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);
+    }
+  }
+
+  /** Search this room's messages (server-side, content substring match).
+   *  Returns view models without touching the message list. */
+  async search(q: string, limit = 30): Promise<ChatMessage[]> {
+    const page = await this.room.search(q, { limit });
+    return page.items.map(chatMessageFromHistory);
+  }
+
+  /** Mark `messageId` read (debounced inside the SDK). */
+  markRead(messageId: string): void {
+    this.room.markRead(messageId);
+  }
+
+  // ── event handlers ──────────────────────────────────────────────
+
+  private onIncoming(f: WsChatReceive): void {
+    this.messages.push(chatMessageFromLive(f));
+    this.emit();
+  }
+
+  private onUpdated(f: WsMessageUpdated): void {
+    this.mutateById(f.message_id, (m) => ({
+      ...m,
+      content: f.content ?? m.content,
+      editedCount: m.editedCount + 1,
+    }));
+  }
+
+  private onDeleted(f: WsMessageDeleted): void {
+    this.mutateById(f.message_id, (m) => ({ ...m, isDeleted: true }));
+  }
+
+  private onCleared(f: WsMessagesCleared): void {
+    // Operator wipe up to (and including) up_to_message_id — flip local
+    // copies. A null cutoff means the whole room was wiped.
+    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();
+  }
+
+  private onReactionAdded(f: WsReactionAdded): void {
+    this.mutateById(f.message_id, (m) => {
+      const next: ReactionEntry[] = m.reactions.map((r) =>
+        r.key === f.reaction_key
+          ? {
+              key: r.key,
+              userIds: [...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 };
+    });
+  }
+
+  private onReactionRemoved(f: WsReactionRemoved): void {
+    this.mutateById(f.message_id, (m) => {
+      const next: ReactionEntry[] = [];
+      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 };
+    });
+  }
+
+  private onSyncTick(f: WsSyncTick): void {
+    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();
+  }
+
+  private onVisibilityChange = (): void => {
+    if (typeof document !== "undefined" && document.visibilityState === "hidden") {
+      this.room.flushMarkRead();
+    }
+  };
+
+  // ── helpers ─────────────────────────────────────────────────────
+
+  private bindAck(tempId: string, messageId: Promise<string>): void {
+    messageId
+      .then((realId) => {
+        this.mutateByTempId(tempId, (m) => ({
+          ...m,
+          id: realId,
+          status: "sent",
+        }));
+      })
+      .catch(() => {
+        this.mutateByTempId(tempId, (m) => ({ ...m, status: "failed" }));
+      });
+  }
+
+  private mutateById(id: string, f: (m: ChatMessage) => ChatMessage): void {
+    const i = this.messages.findIndex((m) => m.id === id);
+    if (i === -1) return;
+    this.messages[i] = f(this.messages[i]!);
+    this.emit();
+  }
+
+  private mutateByTempId(
+    tempId: string,
+    f: (m: ChatMessage) => ChatMessage,
+  ): void {
+    const i = this.messages.findIndex((m) => m.tempId === tempId);
+    if (i === -1) return;
+    this.messages[i] = f(this.messages[i]!);
+    this.emit();
+  }
+}

package/src/use-member-list.ts

@@ -0,0 +1,46 @@
+import { useEffect, useMemo, useSyncExternalStore } from "react";
+
+import { useNoveraChat } from "./context.js";
+import {
+  MemberListStore,
+  type MemberListSnapshot,
+} from "./member-list-store.js";
+
+export 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");
+ * ```
+ */
+export function useMemberList(roomId: string): UseMemberListResult {
+  const chat = useNoveraChat();
+  const store = useMemo(
+    () => new MemberListStore(chat, roomId),
+    [chat, roomId],
+  );
+
+  useEffect(() => {
+    store.attach();
+    void store.load();
+    return () => store.dispose();
+  }, [store]);
+
+  const snapshot = useSyncExternalStore(
+    store.subscribe,
+    store.getSnapshot,
+    store.getSnapshot,
+  );
+
+  return { ...snapshot, store };
+}

package/src/use-messages.ts

@@ -0,0 +1,62 @@
+import { useEffect, useMemo, useSyncExternalStore } from "react";
+
+import { useNoveraChat } from "./context.js";
+import { RoomStore, type RoomSnapshot } from "./room-store.js";
+
+export interface UseMessagesOptions {
+  /** Page size for the initial history load (and a sensible default for
+   *  scrollback pages). Default 50. */
+  historyLimit?: number;
+}
+
+export 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)} />
+ * ```
+ */
+export function useMessages(
+  roomId: string,
+  opts?: UseMessagesOptions,
+): UseMessagesResult {
+  const chat = useNoveraChat();
+  const historyLimit = opts?.historyLimit ?? 50;
+
+  // Construction is side-effect free — subscriptions happen in attach(),
+  // so a StrictMode double-render leaking an extra never-attached store
+  // is harmless.
+  const store = useMemo(() => new RoomStore(chat, roomId), [chat, roomId]);
+
+  useEffect(() => {
+    store.attach();
+    void store.loadHistory(historyLimit);
+    return () => store.dispose();
+    // historyLimit is intentionally not a dep — it only matters for the
+    // first load; changing it later shouldn't reset the room.
+    // eslint-disable-next-line react-hooks/exhaustive-deps
+  }, [store]);
+
+  const snapshot = useSyncExternalStore(
+    store.subscribe,
+    store.getSnapshot,
+    store.getSnapshot,
+  );
+
+  return { ...snapshot, store };
+}

package/src/use-room-files.ts

@@ -0,0 +1,53 @@
+import { useEffect, useMemo, useSyncExternalStore } from "react";
+
+import { useNoveraChat } from "./context.js";
+import {
+  RoomFilesStore,
+  type RoomFilesSnapshot,
+} from "./room-files-store.js";
+
+export interface UseRoomFilesOptions {
+  /** Page size for both the initial load and `loadMore`. Default 50. */
+  pageSize?: number;
+}
+
+export 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");
+ * ```
+ */
+export function useRoomFiles(
+  roomId: string,
+  opts?: UseRoomFilesOptions,
+): UseRoomFilesResult {
+  const chat = useNoveraChat();
+  const pageSize = opts?.pageSize ?? 50;
+  const store = useMemo(
+    () => new RoomFilesStore(chat, roomId, pageSize),
+    [chat, roomId, pageSize],
+  );
+
+  useEffect(() => {
+    store.attach();
+    void store.refresh();
+    return () => store.dispose();
+  }, [store]);
+
+  const snapshot = useSyncExternalStore(
+    store.subscribe,
+    store.getSnapshot,
+    store.getSnapshot,
+  );
+
+  return { ...snapshot, store };
+}

package/src/use-room-list.ts

@@ -0,0 +1,57 @@
+import { useEffect, useMemo, useRef, useSyncExternalStore } from "react";
+
+import { useNoveraChat } from "./context.js";
+import {
+  RoomListStore,
+  type RoomListSnapshot,
+  type RoomListStoreOptions,
+} from "./room-list-store.js";
+
+export 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>
+ * ))}
+ * ```
+ */
+export function useRoomList(opts?: RoomListStoreOptions): UseRoomListResult {
+  const chat = useNoveraChat();
+  // Options are captured once — they're behavior callbacks, not reactive
+  // inputs; recreating the store per render would drop the live list.
+  const optsRef = useRef(opts);
+  const store = useMemo(
+    () => new RoomListStore(chat, optsRef.current ?? {}),
+    [chat],
+  );
+
+  useEffect(() => {
+    store.attach();
+    void store.load();
+    return () => store.dispose();
+  }, [store]);
+
+  const snapshot = useSyncExternalStore(
+    store.subscribe,
+    store.getSnapshot,
+    store.getSnapshot,
+  );
+
+  return { ...snapshot, store };
+}