@vibexnpm/talkx 3.0.6 → 3.0.7

package/dist/index.d.ts

@@ -926,10 +926,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 +1254,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 +1265,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 +1327,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;
     /**