@vibexnpm/talkx 3.0.7 → 3.1.0

package/dist/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;
+}