@vibexnpm/talkx 3.0.6 → 3.0.8

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;
 }
 
 /**
@@ -723,7 +723,8 @@ export interface ParticipantResponse {
      * 과도기 동안 {@code ADMIN} 생성자가 보일 수 있으나 권한은 동일.</p>
      */
     role: 'OWNER' | 'ADMIN' | 'MEMBER' | 'ASSISTANT';
-    joinedAt: string;
+    /** 참가 시각(epoch millis). */
+    joinedAt: number;
 }
 
 /** 채팅방 last message preview. */
@@ -734,7 +735,8 @@ export interface LastMessageResponse {
     senderProfileUrl?: string | null;
     content: string;
     messageType: string;
-    sentAt: string;
+    /** 마지막 메시지 시각(epoch millis). */
+    sentAt: number;
     /**
      * 파일 메시지일 때 첫 파일의 사용자 metadata (opaque pass-through).
      * <p>고객사가 파일 업로드 시 함께 보낸 데이터 (스티커 ID 등) 가 채팅방 리스트에서도 식별 가능하도록 보존.
@@ -771,8 +773,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 +829,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;
@@ -926,10 +934,35 @@ export interface TalkFlowClientOptions {
     serverUrl?: string;
     /** SockJS 사용 여부. 기본 true. */
     useSockJS?: boolean;
-    /** 재연결 지연 (ms). 기본 5000. */
+    /** 최초 재연결 지연 (ms). 기본 5000. 이후 지수적으로 증가한다. */
     reconnectDelay?: number;
+    /** 지수 백오프 상한 (ms). 기본 30000. */
+    maxReconnectDelay?: number;
     /** 최대 재연결 시도. 기본 10. */
     maxReconnectAttempts?: number;
+    /** 수신 하트비트 간격 (ms). 기본 10000. */
+    heartbeatIncoming?: number;
+    /** 발신 하트비트 간격 (ms). 기본 10000. */
+    heartbeatOutgoing?: number;
+    /**
+     * 탭 복귀(visibilitychange/pageshow) · 네트워크 복구(online) 시 자동 재연결. 기본 true.
+     *
+     * <p>재시도 횟수를 소진해 죽은 연결도 되살린다. 단 {@code connect()} 를 한 번도 호출하지 않았거나
+     * {@code disconnect()} 로 명시적으로 끊은 경우에는 동작하지 않는다.</p>
+     */
+    resumeOnVisibility?: boolean;
+    /**
+     * 재연결/복귀 후 끊긴 구간의 메시지를 자동으로 다시 불러올지. 기본 true.
+     *
+     * <p>복구된 메시지는 일반 `chatMessage` 이벤트로 재생되므로 수신 코드를 바꿀 필요가 없다.</p>
+     */
+    syncOnReconnect?: boolean;
+    /** 갭 복구 첫 페이지에만 적용되는 되감기 폭 (ms). 기본 3000. 서버가 상한 clamp 후 1회 차감. */
+    rewindMillis?: number;
+    /** 갭 복구 페이지 상한. 기본 5. 초과 시 최신 페이지 재로드로 전환하고 `gapTruncated` 를 발행. */
+    maxSyncPages?: number;
+    /** 갭 복구 페이지 크기. 기본 100. */
+    syncPageSize?: number;
     /** WebRTC ICE 서버. */
     iceServers?: RTCIceServer[];
     /** connect() 시 채팅방 리스트 자동 구독. 기본 true. */
@@ -1229,7 +1262,7 @@ export interface RetentionCleanupPayload {
 /**
  * TalkFlowClient 이벤트 맵 — 런타임 {@code TalkFlowClient.js} 의 {@code this.emit(...)} 호출 기반.
  *
- * <p><b>Connection 관련</b>: stateChange, connected, disconnected, reconnecting, connectionError, tokenSet, loggedOut</p>
+ * <p><b>Connection 관련</b>: stateChange, connected, disconnected, reconnecting, reconnected, resumed, connectionError, tokenSet, loggedOut</p>
  * <p><b>Chat 관련 (ChatClient 이벤트를 이 이름으로 re-emit)</b>: chatMessage, newChatMessage, messageUpdated, messageDeleted, reactionChanged, linkPreviewAttached, messageRead, typing, assistantProgress, memberJoined, memberLeft, roomSubscribed, roomUnsubscribed, roomListSubscribed, roomListUnsubscribed, roomListUpdate, roomListMessage, roomListCreated, roomListJoined, roomListLeft, roomListSelfLeft, roomListRoomUpdated, retentionCleanup</p>
  * <p><b>Push 관련</b>: pushEnabled, pushFailed, pushNotification</p>
  * <p><b>WebRTC 관련</b>: localStreamStarted, localStreamStopped, remoteTrack, screenShareStarted, screenShareEnded, deviceChange, mediaStateChanged, callStarted, callEnded, callRequested, callAccepted, callRejected, callCancelled, callInvitation, callBusy, incomingCall, incomingCallWhileBusy, userJoined, userLeft, participantLeft, participantMediaState, peerConnected, peerDisconnected, peerClosed, webrtcError</p>
@@ -1240,6 +1273,20 @@ export interface TalkFlowClientEvents {
     connected: unknown;
     disconnected: unknown;
     reconnecting: { attempt: number };
+    /**
+     * 재연결 **성공**. 최초 연결에는 발행되지 않는다.
+     *
+     * <p>{@link TalkFlowClientEvents.resumed} 와 상호 배타적 — 재동기화 시점을 모두 잡으려면 둘 다 구독한다.</p>
+     */
+    reconnected: { attempts: number };
+    /**
+     * 탭 복귀 / 네트워크 복구 감지 — **연결이 살아 있어 재연결이 불필요했던** 경우에만 발행된다.
+     *
+     * <p>백그라운드 동안 프레임을 놓쳤을 수 있으므로 소비자는 이 시점에도 재동기화해야 한다.
+     * 복귀가 재연결을 유발한 경우에는 이 이벤트 대신 {@link TalkFlowClientEvents.reconnected} 가
+     * 발행된다(두 이벤트가 겹치지 않아 재동기화가 중복 실행되지 않는다).</p>
+     */
+    resumed: { reason: 'visibilitychange' | 'pageshow' | 'online' };
     connectionError: unknown;
     tokenSet: { userId: string };
     loggedOut: void;
@@ -1288,6 +1335,21 @@ export interface TalkFlowClientEvents {
     roomListRoomUpdated: RoomListUpdateEvent;
     retentionCleanup: RetentionCleanupPayload;
 
+    // 갭 복구 — 복구된 메시지 자체는 일반 chatMessage 로 재생되므로 아래는 모두 선택 구독용.
+    /** 갭 복구 시작 (전 방 1회). */
+    syncStarted: { roomIds: string[]; reason: string };
+    /** 갭 복구 완료 (전 방 1회). */
+    syncCompleted: {
+        rooms: Array<{ roomId: string; recovered: number; truncated: boolean; durationMs: number }>;
+        totalRecovered: number;
+        durationMs: number;
+        reason: string;
+    };
+    /** 갭이 `maxSyncPages` 를 넘거나 커서가 만료돼 최신 페이지 재로드로 전환됨 (방 단위). */
+    gapTruncated: { roomId: string; fetched: number; reason?: 'cursorExpired' };
+    /** 재연결 시 방 목록 전체 스냅샷. delta 계약인 `roomListUpdate` 와 별개. */
+    roomListSynced: { rooms: ChatRoomResponse[]; reason: string };
+
     // Push
     pushEnabled: void;
     /**