@vibexnpm/talkx 3.0.8 → 3.2.0

package/dist/index.d.ts

@@ -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];
 
@@ -766,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;
@@ -851,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;
@@ -1333,6 +1362,8 @@ export interface TalkFlowClientEvents {
     /** 본인이 영구 차단당함. */
     roomListSelfBanned: RoomListUpdateEvent;
     roomListRoomUpdated: RoomListUpdateEvent;
+    /** 내가 어느 기기에서 읽든 방별 미독 절대값(+version)을 통지 — 크로스-디바이스 badge 동기화. */
+    roomListUnreadUpdated: RoomUnreadUpdatedEvent;
     retentionCleanup: RetentionCleanupPayload;
 
     // 갭 복구 — 복구된 메시지 자체는 일반 chatMessage 로 재생되므로 아래는 모두 선택 구독용.
@@ -1434,6 +1465,8 @@ export interface ChatClientEvents {
     /** 본인이 영구 차단당함. */
     roomListSelfBanned: RoomListUpdateEvent;
     roomListRoomUpdated: RoomListUpdateEvent;
+    /** 내가 어느 기기에서 읽든 방별 미독 절대값(+version)을 통지 — 크로스-디바이스 badge 동기화. */
+    roomListUnreadUpdated: RoomUnreadUpdatedEvent;
     retentionCleanup: RetentionCleanupPayload;
     messageRead: MessageReadEventPayload;
     typing: TypingEvent;
@@ -2021,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;
+}