@vibexnpm/talkx 3.0.7 → 3.1.0

package/package.json

@@ -1,6 +1,6 @@
 {
     "name": "@vibexnpm/talkx",
-    "version": "3.0.7",
+    "version": "3.1.0",
     "type": "module",
     "description": "TalkFlow SDK - Chat & WebRTC unified client",
     "main": "dist/talkflow-sdk.umd.js",

package/src/chat/ChatClient.js

@@ -2451,6 +2451,15 @@ class ChatClient extends EventEmitter {
                     cutoffTime: event.cutoffTime
                 });
                 break;
+            case RoomListEventType.ROOM_UNREAD_UPDATED:
+                // 다른(또는 이) 기기에서 내가 읽어 방 미독이 바뀜 → badge 를 절대값으로 세팅.
+                // roomUnreadCount 는 delta 가 아니라 절대값, unreadVersion 은 순서 역전 판별용.
+                this.emit('roomListUnreadUpdated', {
+                    roomId: event.roomId,
+                    roomUnreadCount: event.roomUnreadCount,
+                    unreadVersion: event.unreadVersion
+                });
+                break;
             default:
                 this.logger.warn('Unknown room list event type:', event.eventType);
         }

package/src/chat/RoomUnreadReconciler.js

@@ -0,0 +1,125 @@
+/**
+ * 방별 미독 카운트 계산기 (READ_SYNC_DESIGN v2.1 §6).
+ *
+ * <p>SDK 는 방 목록 상태를 소유하지 않는다(페이징·필터·프레임워크 상태와 충돌). 대신 순서 역전에
+ * 안전한 "카운트 계산"만 이 헬퍼로 제공하고, 앱이 결과를 자신의 room store 에 반영한다.</p>
+ *
+ * <p><b>왜 단순 절대값 세팅이 안 되나</b>: 서로 다른 발신 흐름에서 나온 이벤트는 도착 순서가 논리적
+ * 발생 순서와 다를 수 있다. 예컨대 내가 방을 읽어 나간 {@code ROOM_UNREAD_UPDATED(count=0, v=13)} 이
+ * 신규 {@code MESSAGE_RECEIVED(+1, v=12)} 보다 먼저 도착할 수 있다. 단순히 절대값을 덮으면 뒤늦게 온
+ * v12 delta 가 badge 를 1 로 되돌린다. 그래서 방마다 스냅샷(마지막 절대값)과 그 이후의 delta 를 분리
+ * 보관하고, version 으로 이미 반영된 delta 를 정리한다.</p>
+ *
+ * <p><b>방별 상태</b>: {@code snapshotCount}/{@code snapshotVersion}(마지막 절대값) +
+ * {@code pendingDeltas}(messageId → {version, delta}). 표시값 = snapshotCount + Σ pending.delta.</p>
+ *
+ * <p><b>버전 전제</b>: 순서 정합성은 서버가 이벤트/응답에 {@code version} 을 실어줄 때만 보장된다.
+ * version 이 아예 없는 구서버 구간에서는 순서 역전을 판별할 수 없다 — 이 경우 이미 versioned baseline 이
+ * 있으면 비교 불가한 legacy 스냅샷을 무시해 최신 pair 를 지키고, 최종 정합은 REST 재조회에 의존한다.</p>
+ *
+ * @example
+ * const reconciler = new RoomUnreadReconciler(client.userId); // JWT 에서 SDK 가 추출한 내 userId
+ * // 초기 REST 페이지를 baseline 으로 투입
+ * rooms.forEach(r => reconciler.applySnapshot(r.id, r.unreadCount, r.unreadVersion));
+ * client.on('roomListMessage',      e => { reconciler.applyMessageReceived(e); render(e.roomId); });
+ * client.on('roomListUnreadUpdated', e => { reconciler.applySnapshot(e.roomId, e.roomUnreadCount, e.unreadVersion); render(e.roomId); });
+ * function render(roomId) { store.setBadge(roomId, reconciler.getCount(roomId)); } // null 이면 REST 로 표시
+ */
+export class RoomUnreadReconciler {
+    /**
+     * @param {string} currentUserId - 내 사용자 ID. SDK 가 JWT 에서 추출한 값을 {@code client.userId} 로
+     *   얻는다(별도 관리 불필요). 내가 보낸 메시지의 MESSAGE_RECEIVED 가 내 badge 를 올리지 않도록 걸러내는
+     *   데만 쓰는 <b>표시용 값</b>이라 보안 결정에 관여하지 않는다. (서버도 발신자를 unread 대상에서 제외하지만,
+     *   방 리스트 이벤트는 발신자에게도 전달되므로 클라에서 한 번 더 거른다.)
+     */
+    constructor(currentUserId) {
+        this._currentUserId = currentUserId;
+        /** @type {Map<string, {snapshotCount: (number|null), snapshotVersion: (number|null), pendingDeltas: Map<string, {version: (number|null), delta: number}>}>} */
+        this._rooms = new Map();
+    }
+
+    _room(roomId) {
+        let state = this._rooms.get(roomId);
+        if (!state) {
+            state = { snapshotCount: null, snapshotVersion: null, pendingDeltas: new Map() };
+            this._rooms.set(roomId, state);
+        }
+        return state;
+    }
+
+    /**
+     * MESSAGE_RECEIVED(delta +1) 반영.
+     * @param {{roomId: string, messageId: string, actorId?: string, unreadVersion?: (number|null)}} event
+     */
+    applyMessageReceived(event) {
+        if (!event || !event.roomId || !event.messageId) return;
+        // 발신자 본인 메시지 → 내 badge 증가 금지.
+        if (event.actorId != null && event.actorId === this._currentUserId) return;
+
+        const state = this._room(event.roomId);
+        // 같은 메시지 중복 수신(서버측 멱등 race 복구 등) → 한 번만.
+        if (state.pendingDeltas.has(event.messageId)) return;
+
+        const version = event.unreadVersion == null ? null : event.unreadVersion;
+        // 이미 baseline 에 반영된 delta(스냅샷 version 이하) → 무시.
+        if (state.snapshotVersion != null && version != null && version <= state.snapshotVersion) return;
+
+        state.pendingDeltas.set(event.messageId, { version, delta: 1 });
+    }
+
+    /**
+     * 절대값 스냅샷 반영 — REST 응답 또는 ROOM_UNREAD_UPDATED.
+     * @param {string} roomId
+     * @param {(number|null|undefined)} count   방별 내 미독 절대값. null/undefined 면 무시(미계산 방).
+     * @param {(number|null|undefined)} version 그 카운트가 확정된 방 version.
+     */
+    applySnapshot(roomId, count, version) {
+        if (!roomId || count == null) return;
+        const v = version == null ? null : version;
+        const state = this._room(roomId);
+
+        // 이미 versioned baseline 이 있는데 version 없는(구서버) 스냅샷이 오면 비교 불가 → 무시.
+        // 그대로 count 를 덮으면 snapshotVersion 은 최신인데 count 는 옛 값인 (옛 count, 최신 version) 조합이
+        // 되어, 백엔드가 원자 read 로 막은 순서 훼손이 SDK 에서 재현된다.
+        if (state.snapshotVersion != null && v == null) return;
+
+        // 더 오래된 스냅샷은 무시(stale).
+        if (state.snapshotVersion != null && v != null && v < state.snapshotVersion) return;
+
+        state.snapshotCount = count;
+        if (v != null) state.snapshotVersion = v;
+
+        // 이 스냅샷에 이미 반영된 pending 제거, 더 최신 pending 은 보존(v13 유실 방지).
+        // version 이 있을 때만 정리 가능 — version 없는 스냅샷(구서버)은 pending 을 건드리지 않는다.
+        if (v != null) {
+            for (const [messageId, d] of state.pendingDeltas) {
+                if (d.version == null || d.version <= v) {
+                    state.pendingDeltas.delete(messageId);
+                }
+            }
+        }
+    }
+
+    /**
+     * 방의 현재 표시 카운트.
+     * @param {string} roomId
+     * @returns {(number|null)} baseline(스냅샷)이 아직 없으면 null — 앱은 REST 조회 결과로 표시한다.
+     */
+    getCount(roomId) {
+        const state = this._rooms.get(roomId);
+        if (!state || state.snapshotCount == null) return null;
+        let sum = state.snapshotCount;
+        for (const d of state.pendingDeltas.values()) sum += d.delta;
+        return sum;
+    }
+
+    /** 방을 상태에서 제거(퇴장/추방 등). */
+    removeRoom(roomId) {
+        this._rooms.delete(roomId);
+    }
+
+    /** 전체 초기화(로그아웃/재연결 리셋 등). */
+    clear() {
+        this._rooms.clear();
+    }
+}

package/src/constants.js

@@ -298,7 +298,14 @@ export const RoomListEventType = {
     /** 방장에 의한 추방 + 영구 차단 → payload 는 ROOM_KICKED 와 동일, 재입장 거부됨. */
     ROOM_BANNED: 'ROOM_BANNED',
     /** 메시지 보관 기간 정리 → cutoffTime 이전 메시지를 UI에서 제거. */
-    MESSAGE_RETENTION_CLEANUP: 'MESSAGE_RETENTION_CLEANUP'
+    MESSAGE_RETENTION_CLEANUP: 'MESSAGE_RETENTION_CLEANUP',
+    /**
+     * 내 unread 가 변경됨 → 방 리스트 badge 를 roomUnreadCount 절대값으로 세팅(delta 아님).
+     * 내가 어느 기기에서 읽든 같은 사용자의 다른 세션에 전달돼 크로스-디바이스로 badge 를 맞춘다.
+     * unreadVersion 으로 순서 역전(읽음 0 이 신규 메시지보다 먼저 도착)을 방어한다.
+     * SDK 는 이를 roomListUnreadUpdated 이벤트로 emit 한다.
+     */
+    ROOM_UNREAD_UPDATED: 'ROOM_UNREAD_UPDATED'
 };
 
 /**

package/src/index.js

@@ -84,6 +84,8 @@ export { default as ConnectionManager } from './core/ConnectionManager.js';
 
 // 채팅
 export { default as ChatClient } from './chat/ChatClient.js';
+// 방 미독 계산기 — ROOM_UNREAD_UPDATED / MESSAGE_RECEIVED 를 순서 역전에 안전하게 합산(READ_SYNC_DESIGN §6).
+export { RoomUnreadReconciler } from './chat/RoomUnreadReconciler.js';
 
 // WebRTC
 export { default as WebRTCClient } from './webrtc/WebRTCClient.js';

package/src/talkflow/eventForwarding.js

@@ -42,6 +42,7 @@ const CHAT_EVENT_MAP = [
     ['roomListBanned', 'roomListBanned'],
     ['roomListSelfBanned', 'roomListSelfBanned'],
     ['roomListRoomUpdated', 'roomListRoomUpdated'],
+    ['roomListUnreadUpdated', 'roomListUnreadUpdated'],
     ['retentionCleanup', 'retentionCleanup']
 ];
 

package/types/index.d.ts

@@ -332,16 +332,16 @@ export interface RoomSummaryRollup {
     format: string;
     /** 이 rollup 의 언어(소문자 BCP-47 / {@code 'OFF'}=원문). {@link RoomSummaryView.language} 와 동일. */
     language: string;
-    /** rollup 이 커버하는 가장 오래된 지점. */
-    coverStartAt: string | null;
-    /** 마지막으로 요약된 지점. */
-    watermarkAt: string | null;
+    /** rollup 이 커버하는 가장 오래된 지점(epoch millis). */
+    coverStartAt: number | null;
+    /** 마지막으로 요약된 지점(epoch millis). */
+    watermarkAt: number | null;
     /** 전체 segment 수(페이지 총량 힌트). */
     segmentCount: number;
     /** 이 키(포맷×언어)가 최신 대화를 아직 반영 안 함(reducedSegmentCount < segmentCount) — refreshSummary 로 최신화 가능. */
     stale: boolean;
-    /** 마지막 갱신 시각. */
-    updatedAt: string;
+    /** 마지막 갱신 시각(epoch millis). */
+    updatedAt: number;
 }
 
 /** Rolling 누적 요약 구간 부분요약 — {@link RoomSummaryView.segments} 항목. 항상 {@code contentFormat==='neutral'}. */
@@ -352,9 +352,9 @@ export interface RoomSummarySegment {
     content: string;
     /** 항상 {@code 'neutral'}(format 미적용). */
     contentFormat: string;
-    fromSentAt: string | null;
+    fromSentAt: number | null;
     fromMessageId: string | null;
-    toSentAt: string | null;
+    toSentAt: number | null;
     toMessageId: string | null;
     /** 이 구간이 담은 메시지 수. */
     messageCount: number;
@@ -407,8 +407,8 @@ export interface SummaryUpdateEvent {
      * 그 외 null. 각 사용자는 자기 언어가 이 목록에 있으면 {@code getSummary({ format, lang })} 로 읽는다(§S1).
      */
     languages: string[] | null;
-    /** 갱신 시각. {@code READY} 만 포함, 그 외 null. */
-    updatedAt: string | null;
+    /** 갱신 시각(epoch millis). {@code READY} 만 포함, 그 외 null. */
+    updatedAt: number | null;
 }
 
 /**
@@ -484,6 +484,7 @@ export const RoomListEventType: {
     readonly ROOM_KICKED: 'ROOM_KICKED';
     readonly ROOM_BANNED: 'ROOM_BANNED';
     readonly MESSAGE_RETENTION_CLEANUP: 'MESSAGE_RETENTION_CLEANUP';
+    readonly ROOM_UNREAD_UPDATED: 'ROOM_UNREAD_UPDATED';
 };
 export type RoomListEventTypeValue = typeof RoomListEventType[keyof typeof RoomListEventType];
 
@@ -723,7 +724,8 @@ export interface ParticipantResponse {
      * 과도기 동안 {@code ADMIN} 생성자가 보일 수 있으나 권한은 동일.</p>
      */
     role: 'OWNER' | 'ADMIN' | 'MEMBER' | 'ASSISTANT';
-    joinedAt: string;
+    /** 참가 시각(epoch millis). */
+    joinedAt: number;
 }
 
 /** 채팅방 last message preview. */
@@ -734,7 +736,8 @@ export interface LastMessageResponse {
     senderProfileUrl?: string | null;
     content: string;
     messageType: string;
-    sentAt: string;
+    /** 마지막 메시지 시각(epoch millis). */
+    sentAt: number;
     /**
      * 파일 메시지일 때 첫 파일의 사용자 metadata (opaque pass-through).
      * <p>고객사가 파일 업로드 시 함께 보낸 데이터 (스티커 ID 등) 가 채팅방 리스트에서도 식별 가능하도록 보존.
@@ -764,6 +767,11 @@ export interface ChatRoomResponse {
     description?: string;
     creatorId: string;
     unreadCount?: number | null;
+    /**
+     * unreadCount 가 확정된 방 version — {@link RoomUnreadReconciler} 의 baseline.
+     * 미참여 방 등 unread 미계산 응답 또는 구버전 서버에서는 없을 수 있음.
+     */
+    unreadVersion?: number | null;
     isParticipating?: boolean | null;
     activeParticipantCount: number;
     messageRetentionHours?: number | null;
@@ -771,8 +779,10 @@ export interface ChatRoomResponse {
     pinnedMessageId?: string | null;
     participants?: ParticipantResponse[];
     lastMessage?: LastMessageResponse | null;
-    lastMessageAt?: string | null;
-    createdAt: string;
+    /** 마지막 메시지 시각(epoch millis) — 방 목록 정렬용. */
+    lastMessageAt?: number | null;
+    /** 방 생성 시각(epoch millis). */
+    createdAt: number;
 }
 
 /** 커서 페이지네이션 응답. */
@@ -825,6 +835,10 @@ export interface RoomListUpdateEvent {
     eventType: RoomListEventTypeValue;
     roomId: string;
     actorId?: string;
+    /** {@code MESSAGE_*} 이벤트의 방 마지막 메시지 시각(epoch millis). 그 외 이벤트에서는 undefined. */
+    lastMessageAt?: number | null;
+    /** 이벤트 발행 시각(epoch millis). */
+    timestamp?: number;
     cutoffTime?: number;
     /** {@code ROOM_UPDATED} 전용 — 저장된 최신 메타 snapshot. 다른 eventType 에서는 undefined. */
     room?: RoomMeta;
@@ -843,9 +857,32 @@ export interface RoomListUpdateEvent {
      * SDK 내부에서 같은 메시지의 중복 수신 (서버측 멱등 race 복구 등) dedup 용도. 다른 eventType 에서는 undefined.
      */
     messageId?: string;
+    /**
+     * {@code ROOM_UNREAD_UPDATED} 전용 — 방별 내 미독 메시지 수 <b>절대값</b>(delta 아님).
+     * 다른 eventType 에서는 undefined. 전용 이벤트 {@link RoomUnreadUpdatedEvent} 로도 받을 수 있다.
+     */
+    roomUnreadCount?: number;
+    /**
+     * unread 를 바꾼 원자 연산이 확정한 방 단위 version. {@code MESSAGE_RECEIVED} 와
+     * {@code ROOM_UNREAD_UPDATED} 에 실려, 순서 역전을 {@link RoomUnreadReconciler} 가 판별한다.
+     */
+    unreadVersion?: number;
     [extra: string]: unknown;
 }
 
+/**
+ * `roomListUnreadUpdated` 이벤트 payload — 내가 어느 기기에서 읽든 같은 사용자의 다른 세션에 전달된다.
+ *
+ * <p>{@link RoomUnreadReconciler.applySnapshot} 에 그대로 넣으면 순서 역전에 안전하게 badge 를 계산할 수 있다.</p>
+ */
+export interface RoomUnreadUpdatedEvent {
+    roomId: string;
+    /** 방별 내 미독 메시지 수 절대값. */
+    roomUnreadCount: number;
+    /** 그 카운트가 확정된 방 version. */
+    unreadVersion: number;
+}
+
 /** 포그라운드 푸시 알림 payload. */
 export interface PushNotificationPayload {
     title: string;
@@ -1325,6 +1362,8 @@ export interface TalkFlowClientEvents {
     /** 본인이 영구 차단당함. */
     roomListSelfBanned: RoomListUpdateEvent;
     roomListRoomUpdated: RoomListUpdateEvent;
+    /** 내가 어느 기기에서 읽든 방별 미독 절대값(+version)을 통지 — 크로스-디바이스 badge 동기화. */
+    roomListUnreadUpdated: RoomUnreadUpdatedEvent;
     retentionCleanup: RetentionCleanupPayload;
 
     // 갭 복구 — 복구된 메시지 자체는 일반 chatMessage 로 재생되므로 아래는 모두 선택 구독용.
@@ -1426,6 +1465,8 @@ export interface ChatClientEvents {
     /** 본인이 영구 차단당함. */
     roomListSelfBanned: RoomListUpdateEvent;
     roomListRoomUpdated: RoomListUpdateEvent;
+    /** 내가 어느 기기에서 읽든 방별 미독 절대값(+version)을 통지 — 크로스-디바이스 badge 동기화. */
+    roomListUnreadUpdated: RoomUnreadUpdatedEvent;
     retentionCleanup: RetentionCleanupPayload;
     messageRead: MessageReadEventPayload;
     typing: TypingEvent;
@@ -2013,3 +2054,32 @@ export class Logger {
 export class ConnectionManager {}
 export class MediaStreamManager {}
 export class PeerConnectionManager {}
+
+/**
+ * 방 미독 카운트 계산기 (READ_SYNC_DESIGN §6).
+ *
+ * <p>SDK 는 방 목록 상태를 소유하지 않는다 — 순서 역전에 안전한 카운트 계산만 제공하고 앱이 결과를
+ * 자신의 room store 에 반영한다. 방마다 마지막 절대값 스냅샷과 그 이후 delta 를 분리 보관해,
+ * 서로 다른 발신 흐름의 이벤트가 도착 순서가 뒤바뀌어도 서버 진실과 수렴한다.</p>
+ *
+ * @example
+ * const reconciler = new RoomUnreadReconciler(client.userId); // JWT 에서 SDK 가 추출한 내 userId
+ * rooms.forEach(r => reconciler.applySnapshot(r.id, r.unreadCount, r.unreadVersion)); // REST baseline
+ * client.on('roomListMessage',       e => { reconciler.applyMessageReceived(e); render(e.roomId); });
+ * client.on('roomListUnreadUpdated', e => { reconciler.applySnapshot(e.roomId, e.roomUnreadCount, e.unreadVersion); render(e.roomId); });
+ * // render: const c = reconciler.getCount(roomId); c == null ? useRestValue() : store.setBadge(roomId, c);
+ */
+export class RoomUnreadReconciler {
+    /** @param currentUserId 내 사용자 ID — 내가 보낸 메시지의 delta 를 걸러내는 데 쓴다. */
+    constructor(currentUserId: string);
+    /** MESSAGE_RECEIVED(delta +1) 반영. 발신자 본인 · 중복 messageId · 이미 반영된 version 은 무시. */
+    applyMessageReceived(event: { roomId: string; messageId: string; actorId?: string; unreadVersion?: number | null }): void;
+    /** 절대값 스냅샷(REST 또는 ROOM_UNREAD_UPDATED) 반영. stale version 은 무시, 반영된 pending 은 정리. */
+    applySnapshot(roomId: string, count: number | null | undefined, version: number | null | undefined): void;
+    /** 방의 현재 표시 카운트. baseline 이 아직 없으면 null(앱은 REST 값으로 표시). */
+    getCount(roomId: string): number | null;
+    /** 방을 상태에서 제거. */
+    removeRoom(roomId: string): void;
+    /** 전체 초기화. */
+    clear(): void;
+}