@noverachat/sdk-web 0.3.0 → 0.5.0

package/src/features/room.ts

@@ -12,6 +12,7 @@ import type { HttpClient } from "../transport/http.js";
 import type { ReconnectingWs } from "../transport/ws.js";
 import type {
   Announcement,
+  ClientOptions,
   DeleteScope,
   FileKind,
   FileMeta,
@@ -20,6 +21,7 @@ import type {
   MessageIdStr,
   MessageOut,
   RoomMemberOut,
+  RoomOut,
   RoomUnread,
   SendFileOptions,
   SendParams,
@@ -33,8 +35,10 @@ import type {
   WsSyncTick,
   WsTypingBroadcast,
 } from "../types.js";
+import { CacheKeys, type CachePolicy, type CacheStore } from "../cache.js";
 import { EventBus } from "../internal/event-bus.js";
 import { tempId as newTempId } from "../internal/temp-id.js";
+import { MessageCollection } from "./message-collection.js";
 import {
   parseAnnouncementOut,
   parseBulkDeleteBySenderResult,
@@ -46,6 +50,7 @@ import {
   parseJoinRequestListResponse,
   parseMessageOut,
   parseRoomMemberOut,
+  parseRoomOut,
   parseRoomUnread,
 } from "../generated/rest.js";
 import type {
@@ -89,7 +94,7 @@ function toFileInline(f: {
 // Enhance the GENERATED `parseMessageOut` with the two client-side
 // extras it can't derive from the OpenAPI schema: parse `file`/`files`
 // into the camelCase `FileInline` shape, and lift sender-attached
-// `_customMeta` out of `data` (Phase D #11). Everything else — key
+// `_customMeta` out of `data`. Everything else — key
 // renames, nested sender/reactions — comes straight from the codegen.
 function toMessageOut(j: unknown): MessageOut {
   const base = parseMessageOut(j);
@@ -196,13 +201,43 @@ export class Room {
    */
   private mySentTempIds = new Set<string>();
 
+  // ── 스냅샷 캐시 협력자 (클라이언트 옵션에서 흘러듦) ──────────────
+  private readonly cacheStore: CacheStore | null;
+  private readonly cachePolicy: CachePolicy;
+  private readonly logger: ClientOptions["logger"];
   constructor(
     public readonly roomId: string,
     private http: HttpClient,
     private ws: ReconnectingWs,
     readDebounceMs: number,
+    opts?: {
+      cacheStore?: CacheStore;
+      cachePolicy?: CachePolicy;
+      logger?: ClientOptions["logger"];
+    },
   ) {
     this.readDebounceMs = readDebounceMs;
+    this.cacheStore = opts?.cacheStore ?? null;
+    this.cachePolicy = opts?.cachePolicy ?? "replaceByApi";
+    this.logger = opts?.logger;
+  }
+
+  /**
+   * 이 방의 메시지 상태를 소유하는 `MessageCollection`을 만든다.
+   *
+   * 컬렉션이 이벤트 반영·낙관적 전송·캐시 hydrate→교체를 전부 담당하므로,
+   * 리스트 화면은 컬렉션 하나만 물면 된다. 여러 개 만들 수 있고 각자
+   * `dispose()`로 정리한다.
+   *
+   * ```ts
+   * const col = chat.room("room_123").collection();
+   * const unsub = col.on("change", () => render(col.messages));
+   * await col.load();
+   * col.send("hello");
+   * ```
+   */
+  collection(policy?: CachePolicy): MessageCollection {
+    return new MessageCollection(this, policy ?? this.cachePolicy);
   }
 
   private _sendPendingMarkRead(): void {
@@ -260,7 +295,7 @@ export class Room {
           forward_blocked: Boolean(p.forwardBlocked),
         }
       : (p.data ?? null);
-    // Phase D #11 — merge client-supplied custom metadata under a reserved
+    // Merge client-supplied custom metadata under a reserved
     // `_customMeta` key in `data`. Backend passes the whole `data` blob
     // through untouched, so receiving clients read it back via
     // `MessageOut.customMeta` (see `toMessageOut`).
@@ -788,15 +823,87 @@ export class Room {
     items: MessageOut[];
     nextCursor: MessageIdStr | null;
     hasMore: boolean;
+    /** 히스토리 하한(unix ms). null=컷 없음 — 재입장 컷·대화 지우기가 수렴. */
+    historyFrom: number | null;
   }> {
     const raw = await this.http.request<{
       items: unknown[]; next_cursor: string | null; has_more: boolean;
+      history_from?: number | null;
     }>("GET", `/api/v1/rooms/${this.roomId}/messages`, undefined, { limit });
-    return {
-      items: raw.items.map(toMessageOut),
+    const page = {
+      items: raw.items.map(toMessageOut), // 파싱 성공한 응답만 캐시에 넣는다
       nextCursor: raw.next_cursor,
       hasMore: raw.has_more,
+      historyFrom: raw.history_from ?? null,
     };
+    void this.cacheWriteRecent(raw);
+    return page;
+  }
+
+  /** 이 방의 상세 정보 (`GET /rooms/{id}`) — 이름·멤버 수·삭제 타이머 등. */
+  async detail(): Promise<RoomOut> {
+    const raw = await this.http.request<unknown>(
+      "GET", `/api/v1/rooms/${this.roomId}`,
+    );
+    return parseRoomOut(raw);
+  }
+
+  /**
+   * 히스토리 최신 페이지의 캐시 스냅샷 — 마지막 `listRecent()` 성공 응답의
+   * 원문. 콜드 스타트 렌더 힌트 용도다: 있으면 즉시 그리고, `listRecent()`가
+   * 도착하면 통째로 교체할 것. 캐시가 없거나(`cacheStore` 미주입 포함)
+   * 파싱이 실패하면 `null`을 돌려주고, 깨진 스냅샷은 지운다.
+   *
+   * 스냅샷의 `nextCursor`/`hasMore`는 시점이 지난 값이므로 스크롤백
+   * 커서로 쓰지 말 것 — API 응답이 도착한 뒤의 값만 신뢰한다.
+   */
+  async cachedRecent(): Promise<{
+    items: MessageOut[];
+    nextCursor: MessageIdStr | null;
+    hasMore: boolean;
+    historyFrom: number | null;
+  } | null> {
+    const store = this.cacheStore;
+    if (!store) return null;
+    const key = CacheKeys.msgs(this.roomId);
+    try {
+      const raw = await store.read(key);
+      if (raw == null) return null;
+      const j = JSON.parse(raw) as {
+        items: unknown[]; next_cursor: string | null; has_more: boolean;
+        history_from?: number | null;
+      };
+      return {
+        items: j.items.map(toMessageOut),
+        nextCursor: j.next_cursor,
+        hasMore: j.has_more,
+        historyFrom: j.history_from ?? null,
+      };
+    } catch (err) {
+      this.logger?.("warn", `cache_read_failed key=${key}`, err);
+      try {
+        await store.remove(key);
+      } catch {
+        // 폐기 실패도 무시 — 캐시는 힌트일 뿐
+      }
+      return null;
+    }
+  }
+
+  /**
+   * 최신 페이지 스냅샷 저장. 삭제 타이머 방도 저장한다 — 서버가 만료를
+   * 일반 `message_deleted` 프레임으로 브로드캐스트하고 히스토리에서도
+   * 즉시 제외하므로, 만료분은 라이브 이벤트/`history_from` diff로 정리된다.
+   */
+  private async cacheWriteRecent(raw: unknown): Promise<void> {
+    const store = this.cacheStore;
+    if (!store) return;
+    const key = CacheKeys.msgs(this.roomId);
+    try {
+      await store.write(key, JSON.stringify(raw));
+    } catch (err) {
+      this.logger?.("warn", `cache_write_failed key=${key}`, err);
+    }
   }
 
   /**
@@ -822,7 +929,7 @@ export class Room {
     };
   }
 
-  /** Phase D #2 — 방 내 메시지 검색.
+  /** 방 내 메시지 검색.
    *
    * ``content`` 필드에 대한 대소문자 무시 부분 문자열 매칭 (ILIKE). 삭제된
    * 메시지는 제외. 결과는 최신순 (message_id DESC) 으로 반환되고, ``before``

package/src/generated/rest.ts

@@ -44,6 +44,7 @@ export interface UnreadRoomItem {
   lastMessageId?: string | null;
   lastReadMessageId?: string | null;
   lastMessagePreview?: string | null;
+  lastMessageAt?: number | null;
   memberCount?: number;
   membersPreview?: MemberPreview[];
 }
@@ -57,6 +58,7 @@ export function parseUnreadRoomItem(j: any): UnreadRoomItem {
     lastMessageId: j["last_message_id"],
     lastReadMessageId: j["last_read_message_id"],
     lastMessagePreview: j["last_message_preview"],
+    lastMessageAt: j["last_message_at"],
     memberCount: j["member_count"],
     membersPreview: j["members_preview"] == null ? undefined : (j["members_preview"] as unknown[]).map((e: any) => parseMemberPreview(e)),
   } as UnreadRoomItem;
@@ -155,6 +157,7 @@ export interface MessageListResponse {
   items: MessageOut[];
   nextCursor?: string | null;
   hasMore: boolean;
+  historyFrom?: number | null;
 }
 
 export function parseMessageListResponse(j: any): MessageListResponse {
@@ -162,6 +165,7 @@ export function parseMessageListResponse(j: any): MessageListResponse {
     items: (j["items"] as unknown[]).map((e: any) => parseMessageOut(e)),
     nextCursor: j["next_cursor"],
     hasMore: j["has_more"],
+    historyFrom: j["history_from"],
   } as MessageListResponse;
 }
 
@@ -489,6 +493,20 @@ export function parseJoinRequestCreateResponse(j: any): JoinRequestCreateRespons
   } as JoinRequestCreateResponse;
 }
 
+export interface RoomFilesResponse {
+  items: RoomFileItem[];
+  nextCursor?: string | null;
+  hasMore?: boolean;
+}
+
+export function parseRoomFilesResponse(j: any): RoomFilesResponse {
+  return {
+    items: (j["items"] as unknown[]).map((e: any) => parseRoomFileItem(e)),
+    nextCursor: j["next_cursor"],
+    hasMore: j["has_more"],
+  } as RoomFilesResponse;
+}
+
 /** Minimal sender identity — no friend/block/profile-url fluff. */
 export interface SenderMini {
   userId: string;
@@ -527,3 +545,49 @@ export type JoinPolicy = "OPEN" | "APPROVAL_REQUIRED";
 export type MemberRole = "OPERATOR" | "MEMBER" | "KICKED";
 
 export type PushTrigger = "ALL" | "MENTION_ONLY" | "OFF";
+
+/** 방에서 공유된 파일 1건 — 전달(forward)이면 메시지마다 한 번씩. */
+export interface RoomFileItem {
+  messageId: string;
+  senderId: string;
+  createdAtMs: number;
+  file: RoomFileInfo;
+}
+
+export function parseRoomFileItem(j: any): RoomFileItem {
+  return {
+    messageId: j["message_id"],
+    senderId: j["sender_id"],
+    createdAtMs: j["created_at_ms"],
+    file: parseRoomFileInfo(j["file"]),
+  } as RoomFileItem;
+}
+
+/** 한 파일의 메타 (rooms/{id}/files 항목의 file 필드). */
+export interface RoomFileInfo {
+  id: string;
+  kind: string;
+  mime?: string | null;
+  sizeBytes?: number | null;
+  originalName?: string | null;
+  width?: number | null;
+  height?: number | null;
+  durationSec?: number | null;
+  thumbnailStatus?: string | null;
+  forwardBlocked?: boolean;
+}
+
+export function parseRoomFileInfo(j: any): RoomFileInfo {
+  return {
+    id: j["id"],
+    kind: j["kind"],
+    mime: j["mime"],
+    sizeBytes: j["size_bytes"],
+    originalName: j["original_name"],
+    width: j["width"],
+    height: j["height"],
+    durationSec: j["duration_sec"],
+    thumbnailStatus: j["thumbnail_status"],
+    forwardBlocked: j["forward_blocked"],
+  } as RoomFileInfo;
+}

package/src/index.ts

@@ -1,5 +1,23 @@
 export { NoveraChat } from "./client.js";
 export { Room, type RoomEvents } from "./features/room.js";
+
+// 스냅샷 캐시 — 앱 주입 저장소 인터페이스 + 정책 + 키 규칙
+export { CacheKeys, type CachePolicy, type CacheStore } from "./cache.js";
+
+// 코어 소유 메시지 상태 + 뷰모델 (sdk-react에서 이동)
+export {
+  MessageCollection,
+  type CollectionChange,
+  type CollectionChangeKind,
+} from "./features/message-collection.js";
+export {
+  chatMessageFromHistory,
+  chatMessageFromLive,
+  pendingChatMessage,
+  pendingFileChatMessage,
+  type ChatMessage,
+  type ChatMessageStatus,
+} from "./chat-message.js";
 export {
   ErrorCode,
   NoveraChatError,
@@ -20,6 +38,7 @@ export type {
   MessageType,
   ReactionEntry,
   RoomMemberOut,
+  RoomOut,
   RoomUnread,
   SendParams,
   SenderMini,

package/src/internal/compare-id.ts

@@ -0,0 +1,17 @@
+/**
+ * Snowflake id 비교 — 63비트 정수가 문자열로 오므로 BigInt로 비교한다
+ * (길이가 다르면 사전순 `>`는 틀린다: "9" > "10"). null/빈 문자열/"0"은
+ * "id 없음 = -∞"로 취급.
+ */
+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/types.ts

@@ -152,8 +152,7 @@ export interface SendParams {
   forwardBlocked?: boolean;
   replyToId?: MessageIdStr;
   /** Set when this send is forwarding an existing message. The server
-   *  uses it to enforce the source file's ``forwardBlocked`` flag (Phase
-   *  C #7): if the source's file is no-forward AND the destination room
+   *  uses it to enforce the source file's ``forwardBlocked`` flag: if the source's file is no-forward AND the destination room
    *  differs from the source room, the send is rejected with
    *  ``NC-FILE-014``. Pass the ORIGINAL message's ``messageId``. */
   forwardOfMessageId?: MessageIdStr;
@@ -238,11 +237,23 @@ export interface FilePresignResponse {
 
 // (wire frame types are generated — see re-export block near the top)
 
+import type { CachePolicy, CacheStore } from "./cache.js";
+
 export interface ClientOptions {
   appId: string;
   endpoint: string;                // e.g. "https://chat.example.com"
   wsEndpoint?: string;             // defaults to endpoint with ws(s)://
   tokenProvider: () => Promise<string>;
+  /**
+   * 스냅샷 캐시 저장소 — 생략(기본)하면 캐시 기능이 전부 꺼진다.
+   * 주입하면 방 목록·방 히스토리 최신 페이지가 REST 원문 그대로 저장되고,
+   * `cachedUnreadSummary()` / `room.cachedRecent()` 로 콜드 스타트 즉시
+   * 렌더에 쓸 수 있다. 자세한 건 `CacheStore` 문서 참조.
+   */
+  cacheStore?: CacheStore;
+  /** 캐시 스냅샷과 API 응답의 합성 방식. 기본 `"replaceByApi"`(통째 교체),
+   *  `"mergeDiff"`는 옵트인 — 옛 캐시 메시지를 보존·병합. */
+  cachePolicy?: CachePolicy;
   autoReconnect?: boolean;         // default true
   pingIntervalMs?: number;         // default 20_000
   readWatermarkDebounceMs?: number;// default 1500