@noverachat/sdk-web 0.2.0 → 0.4.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@noverachat/sdk-web",
-  "version": "0.2.0",
+  "version": "0.4.0",
   "description": "NoveraChat browser/Node SDK — WebSocket + REST client with optimistic UI, reconnection and gap-fill",
   "license": "MIT",
   "type": "module",

package/src/cache.ts

@@ -0,0 +1,65 @@
+/**
+ * 스냅샷 캐시 — 콜드 스타트 스피너 제거용 렌더 힌트 계층.
+ * (noverachat_dart `lib/src/cache.dart`의 TS 미러 — 의미론 동일)
+ *
+ * 원칙:
+ *   1. 캐시 = 렌더 힌트, 서버가 항상 이긴다 — 시작 시 스냅샷 즉시 렌더,
+ *      API 도착 시 통째 교체(diff 병합 없음).
+ *   2. 저장소는 SDK가 정하지 않는다 — `CacheStore` 인터페이스만 정의,
+ *      구현은 앱이 주입(localStorage/IndexedDB 등).
+ *   3. 버전 스탬프 + 통째 폐기 — 키에 스키마 버전(`nc.v1.…`), 파싱 실패
+ *      시 해당 키를 드랍. 삭제 타이머 켜진 방은 캐시 대상에서 제외.
+ */
+
+/**
+ * 앱이 주입하는 key-value 스냅샷 저장소.
+ *
+ * SDK는 저장 방식에 관여하지 않는다 — 값은 불투명한 JSON 문자열이며,
+ * 앱이 localStorage·IndexedDB·파일 등 아무 곳에나 보관하면 된다.
+ * 모든 메서드는 실패해도 SDK 동작에 영향이 없다(캐시는 힌트일 뿐).
+ *
+ * ```ts
+ * const localStorageCache: CacheStore = {
+ *   async read(key) { return localStorage.getItem(key); },
+ *   async write(key, value) { localStorage.setItem(key, value); },
+ *   async remove(key) { localStorage.removeItem(key); },
+ * };
+ *
+ * const chat = new NoveraChat({
+ *   appId, endpoint, tokenProvider,
+ *   cacheStore: localStorageCache,
+ * });
+ * ```
+ */
+export interface CacheStore {
+  /** `key`의 스냅샷을 돌려준다. 없으면 null. */
+  read(key: string): Promise<string | null>;
+  /** `key`에 스냅샷을 저장한다(덮어쓰기). */
+  write(key: string, value: string): Promise<void>;
+  /** `key`의 스냅샷을 지운다. 없어도 에러 없이 통과. */
+  remove(key: string): Promise<void>;
+}
+
+/**
+ * 캐시 스냅샷과 API 응답을 어떻게 합칠지.
+ *
+ * 현재는 `"replaceByApi"`만 구현되어 있다 — `"mergeDiff"`는 서버 측
+ * 무효화 규칙(삭제 타이머 만료 통지·재입장 컷오프 등)이 확정된 뒤
+ * 병합 함수가 채워질 진입점이다.
+ */
+export type CachePolicy = "replaceByApi" | "mergeDiff";
+
+/**
+ * 캐시 키 규칙 — `nc.<스키마버전>.<대상>`.
+ *
+ * 스키마 버전이 키에 박혀 있으므로, 저장 포맷이 바뀌면 버전을 올리는
+ * 것만으로 구버전 스냅샷은 다시는 읽히지 않는다(자연 폐기).
+ */
+export const CacheKeys = {
+  /** 저장 포맷 스키마 버전. 저장되는 JSON 모양이 바뀌면 올린다. */
+  version: "v1",
+  /** 방 목록 스냅샷 (`GET /users/me/unread` 원문). */
+  rooms: "nc.v1.rooms",
+  /** 방 히스토리 최신 페이지 스냅샷 (`GET /rooms/{id}/messages` 원문). */
+  msgs: (roomId: string): string => `nc.v1.msgs.${roomId}`,
+} as const;

package/src/chat-message.ts

@@ -0,0 +1,214 @@
+/**
+ * UI 지향 메시지 뷰모델 — sdk-react에서 코어로 이동.
+ * (`MessageCollection`이 이 모양으로 상태를 소유하고, 바인딩은 재수출만 한다.
+ *  noverachat_dart `lib/src/chat_message.dart`의 TS 대응물.)
+ */
+import type {
+  FileInline,
+  MessageOut,
+  ReactionEntry,
+  SenderMini,
+  WsChatReceive,
+} from "./types.js";
+
+/** Delivery status of an outgoing (optimistic) message. */
+export type ChatMessageStatus = "sending" | "sent" | "failed";
+
+// Snake_case inline file shape as it rides on WS frames — derived
+// structurally from the frame type (not exported by name from types).
+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 — `MessageCollection` 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 `MessageCollection` 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 `MessageCollection`. */
+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/client.ts

@@ -42,6 +42,7 @@ function idGreater(a: MessageIdStr | null | undefined, b: MessageIdStr | null |
   if (!b) return true;
   try { return BigInt(a) > BigInt(b); } catch { return a > b; }
 }
+import { CacheKeys } from "./cache.js";
 import { HttpClient } from "./transport/http.js";
 import { ReconnectingWs } from "./transport/ws.js";
 import { Room } from "./features/room.js";
@@ -67,6 +68,11 @@ export class NoveraChat {
     if (!opts.appId) throw new Error("appId required");
     if (!opts.endpoint) throw new Error("endpoint required");
     if (!opts.tokenProvider) throw new Error("tokenProvider required");
+    if (opts.cachePolicy === "mergeDiff") {
+      throw new Error(
+        'CachePolicy "mergeDiff" 는 아직 미구현 — 현재 "replaceByApi"만 지원',
+      );
+    }
 
     // 400ms is the read-receipt-UX sweet spot for chat apps. Shorter and
     // we waste WS frames on every micro-scroll; longer and the "✓ read"
@@ -146,7 +152,11 @@ export class NoveraChat {
   room(roomId: string): Room {
     let r = this.rooms.get(roomId);
     if (!r) {
-      r = new Room(roomId, this.http, this.ws, this.readDebounceMs);
+      r = new Room(roomId, this.http, this.ws, this.readDebounceMs, {
+        ...(this.opts.cacheStore ? { cacheStore: this.opts.cacheStore } : {}),
+        ...(this.opts.cachePolicy ? { cachePolicy: this.opts.cachePolicy } : {}),
+        ...(this.logger ? { logger: this.logger } : {}),
+      });
       this.rooms.set(roomId, r);
     }
     return r;
@@ -409,7 +419,44 @@ export class NoveraChat {
 
   async unreadSummary(): Promise<UnreadSummary> {
     const raw = await this.http.request<unknown>("GET", "/api/v1/users/me/unread");
-    return parseUnreadSummary(raw);
+    const out = parseUnreadSummary(raw); // 파싱 성공한 응답만 캐시에 넣는다
+    void this.cacheWriteRooms(raw);
+    return out;
+  }
+
+  /**
+   * 방 목록의 캐시 스냅샷 — 마지막 `unreadSummary()` 성공 응답의 원문.
+   *
+   * 콜드 스타트 렌더 힌트 용도다: 있으면 즉시 그리고, `unreadSummary()`가
+   * 도착하면 통째로 교체할 것. 캐시가 없거나(`cacheStore` 미주입 포함)
+   * 파싱이 실패하면 `null`을 돌려주고, 깨진 스냅샷은 지운다.
+   */
+  async cachedUnreadSummary(): Promise<UnreadSummary | null> {
+    const store = this.opts.cacheStore;
+    if (!store) return null;
+    try {
+      const raw = await store.read(CacheKeys.rooms);
+      if (raw == null) return null;
+      return parseUnreadSummary(JSON.parse(raw));
+    } catch (err) {
+      this.logger?.("warn", `cache_read_failed key=${CacheKeys.rooms}`, err);
+      try {
+        await store.remove(CacheKeys.rooms);
+      } catch {
+        // 폐기 실패도 무시 — 캐시는 힌트일 뿐
+      }
+      return null;
+    }
+  }
+
+  private async cacheWriteRooms(raw: unknown): Promise<void> {
+    const store = this.opts.cacheStore;
+    if (!store) return;
+    try {
+      await store.write(CacheKeys.rooms, JSON.stringify(raw));
+    } catch (err) {
+      this.logger?.("warn", `cache_write_failed key=${CacheKeys.rooms}`, err);
+    }
   }
 
   /**