@vibexnpm/talkx 8.4.1 → 8.6.0

package/types/index.d.ts

@@ -577,6 +577,7 @@ export const DefaultConfig: {
     readonly environment: EnvironmentValue;
     readonly reconnectDelay: number;
     readonly maxReconnectAttempts: number;
+    readonly reconnectRecoveryDelay: number;
     readonly heartbeatIncoming: number;
     readonly heartbeatOutgoing: number;
     readonly apiTimeout: number;
@@ -1340,6 +1341,71 @@ export interface RoomUnreadUpdatedEvent {
     unreadVersion: number;
 }
 
+/** Gmail 새 메일 미리보기 — 서버 `MAIL_CHANGED.messages[]` 원소. 본문은 없다. */
+export interface MailPreview {
+    messageId: string;
+    threadId?: string | null;
+    from?: { name?: string | null; email: string } | null;
+    subject?: string | null;
+    /** ISO-8601 UTC. */
+    receivedAt?: string | null;
+}
+
+/**
+ * `mailChanged` 이벤트 — 서버 `/user/queue/mail` 그대로. 받으면 열려 있는 메일 목록·안읽은 수를 다시 읽는다.
+ * 읽음·보관 같은 변화면 `messages` 가 비어 있다(새 메일 알림을 띄우지 않는다).
+ */
+export interface MailChangedEvent {
+    eventType: 'MAIL_CHANGED';
+    connectionId: string;
+    /** 받은메일함 안읽은 수, 모르면 -1. */
+    inboxUnread: number;
+    newMessages: number;
+    /** true 면 놓친 변화가 있을 수 있다 — 목록을 첫 쪽부터 다시 읽는다. */
+    resync: boolean;
+    timestamp: string;
+    messages: MailPreview[];
+}
+
+/**
+ * `newMail` 이벤트 — 새 메일 한 통. 웹소켓 미리보기(`source: 'socket'`)와 포그라운드 FCM 메일 푸시(`source: 'push'`)를
+ * `(projectId, connectionId, messageId)` 로 합쳐 메일마다 한 번만 온다.
+ */
+export interface NewMailEvent {
+    projectId: string | null;
+    connectionId: string;
+    messageId: string;
+    threadId: string | null;
+    /** 보낸 사람 표시(이름, 없으면 주소). */
+    sender: string | null;
+    /** 웹소켓으로 왔을 때만. */
+    from: { name?: string | null; email: string } | null;
+    subject: string | null;
+    /** 웹소켓으로 왔을 때만(ISO-8601 UTC). */
+    receivedAt: string | null;
+    source: 'socket' | 'push';
+}
+
+/**
+ * `newMailSummary` 이벤트 — 한 번에 4통 이상 온 묶음 푸시(포그라운드). 받은메일함을 다시 읽는다.
+ * 묶은 메일 중 아직 `newMail` 로 알리지 않은 것만 센다 — 전부 알린 메일이면 오지 않는다.
+ */
+export interface NewMailSummaryEvent {
+    projectId: string | null;
+    connectionId: string;
+    /** 처음 알리는 메일 수(구버전 서버의 묶음이면 서버가 준 건수). */
+    count: number | null;
+    /** 처음 알리는 메일 ID(구버전 서버의 묶음이면 빈 배열). */
+    messageIds: string[];
+    source: 'push';
+}
+
+/** 알림 클릭으로 열린 앱이 꺼내는 메일 이동 — `messageId` 가 없으면(묶음 알림) 받은메일함으로. */
+export interface PendingMail {
+    connectionId: string;
+    messageId: string | null;
+}
+
 /** 포그라운드 푸시 알림 payload. */
 export interface PushNotificationPayload {
     title: string;
@@ -1544,6 +1610,8 @@ export interface TalkFlowClientOptions {
     maxReconnectDelay?: number;
     /** 최대 재연결 시도. 기본 10. */
     maxReconnectAttempts?: number;
+    /** 기존 연결의 재시도 소진 후 자동 복구 대기(ms, 기본 60000, ±20% 지터). 0이면 비활성화. */
+    reconnectRecoveryDelay?: number;
     /** 수신 하트비트 간격 (ms). 기본 10000. */
     heartbeatIncoming?: number;
     /** 발신 하트비트 간격 (ms). 기본 10000. */
@@ -1980,6 +2048,9 @@ export interface TalkFlowClientEvents {
     roomListRoomUpdated: RoomListUpdateEvent;
     /** 내가 어느 기기에서 읽든 방별 미독 절대값(+version)을 통지 — 크로스-디바이스 badge 동기화. */
     roomListUnreadUpdated: RoomUnreadUpdatedEvent;
+    mailSubscribed: Record<string, unknown>;
+    mailUnsubscribed: Record<string, unknown>;
+    mailChanged: MailChangedEvent;
     retentionCleanup: RetentionCleanupPayload;
 
     // 갭 복구 — 복구된 메시지 자체는 일반 chatMessage 로 재생되므로 아래는 모두 선택 구독용.
@@ -2010,6 +2081,10 @@ export interface TalkFlowClientEvents {
      */
     pushFailed: PushFailedPayload;
     pushNotification: PushNotificationPayload;
+    /** Gmail 새 메일 한 통 — 웹소켓·포그라운드 푸시를 합쳐 메일마다 한 번. 메일 푸시는 pushNotification 으로 오지 않는다. */
+    newMail: NewMailEvent;
+    /** Gmail 묶음 푸시(4통 이상) — 포그라운드. */
+    newMailSummary: NewMailSummaryEvent;
 
     // WebRTC (re-emit from WebRTCClient)
     localStreamStarted: unknown;
@@ -2021,6 +2096,8 @@ export interface TalkFlowClientEvents {
     mediaStateChanged: unknown;
     callStarted: unknown;
     callEnded: unknown;
+    /** 그룹 통화 재참가가 불가능해 로컬 통화를 종료한 경우. */
+    callRecoveryFailed: { roomId: string; error: unknown };
     callRequested: unknown;
     callAccepted: unknown;
     callRejected: unknown;
@@ -2087,6 +2164,9 @@ export interface ChatClientEvents {
     roomListRoomUpdated: RoomListUpdateEvent;
     /** 내가 어느 기기에서 읽든 방별 미독 절대값(+version)을 통지 — 크로스-디바이스 badge 동기화. */
     roomListUnreadUpdated: RoomUnreadUpdatedEvent;
+    mailSubscribed: Record<string, unknown>;
+    mailUnsubscribed: Record<string, unknown>;
+    mailChanged: MailChangedEvent;
     retentionCleanup: RetentionCleanupPayload;
     messageRead: MessageReadEventPayload;
     typing: TypingEvent;
@@ -2111,6 +2191,8 @@ export interface WebRTCClientEvents {
     error: unknown;
     callStarted: unknown;
     callEnded: unknown;
+    /** 그룹 통화 재참가가 불가능해 로컬 통화를 종료한 경우. */
+    callRecoveryFailed: { roomId: string; error: unknown };
     callRequested: unknown;
     callAccepted: unknown;
     callRejected: unknown;
@@ -2297,6 +2379,10 @@ export class ChatClient implements SdkEventEmitter<ChatClientEvents> {
     subscribeRoomList(): Promise<void>;
     unsubscribeRoomList(): void;
     isRoomListSubscribed(): boolean;
+    /** Gmail 메일함 변화 구독(`/user/queue/mail`) — 자동 구독하지 않는다. */
+    subscribeMail(): Promise<void>;
+    unsubscribeMail(): void;
+    isMailSubscribed(): boolean;
     getSubscribedRooms(): string[];
     isSubscribed(roomId: string): boolean;
 
@@ -2315,6 +2401,13 @@ export class ChatClient implements SdkEventEmitter<ChatClientEvents> {
     resumeAssistantStreams(reason?: string): Promise<void>;
 }
 
+/** POST /api/v1/webrtc/rooms 요청. 생략한 값은 서버 기본값을 사용합니다. */
+export interface CreateCallRoomRequest {
+    invitedUsers?: string[];
+    title?: string;
+    maxParticipants?: number;
+}
+
 export class WebRTCClient implements SdkEventEmitter<WebRTCClientEvents> {
     on<K extends keyof WebRTCClientEvents>(event: K, listener: (payload: WebRTCClientEvents[K]) => void): () => void;
     once<K extends keyof WebRTCClientEvents>(event: K, listener: (payload: WebRTCClientEvents[K]) => void): () => void;
@@ -2326,7 +2419,7 @@ export class WebRTCClient implements SdkEventEmitter<WebRTCClientEvents> {
     initializeIceServers(): Promise<RTCIceServer[]>;
     getTurnCredentials(): Promise<{ iceServers: RTCIceServer[] }>;
 
-    createCallRoom(data: unknown): Promise<unknown>;
+    createCallRoom(data: CreateCallRoomRequest): Promise<unknown>;
     getCallRoom(roomId: string): Promise<unknown>;
     joinCallRoomApi(roomId: string): Promise<unknown>;
     leaveCallRoomApi(roomId: string): Promise<unknown>;
@@ -2447,6 +2540,8 @@ export const PushErrorCode: {
 
 export class PushManager {
     consumePendingRoom(): Promise<string | null>;
+    /** 알림 클릭(cold start)으로 저장된 Gmail 메일 이동을 꺼내고 지운다 — 10분 안의 것만. */
+    consumePendingMail(): Promise<PendingMail | null>;
     reset(): void;
     getToken(): string | null;
     isEnabled(): boolean;
@@ -2457,6 +2552,7 @@ export class PushManager {
     /** 현재 디바이스의 푸시 수신 여부 토글. */
     setCurrentDeviceEnabled(enabled: boolean): Promise<void>;
     static consumePendingRoom(projectId?: string): Promise<string | null>;
+    static consumePendingMail(projectId?: string): Promise<PendingMail | null>;
     /**
      * 현재 브라우저의 푸시 권한 상태. 인스턴스 없이도 호출 가능.
      */
@@ -2549,6 +2645,10 @@ export default class TalkFlowClient implements SdkEventEmitter<TalkFlowClientEve
     changeMyPassword(params: { currentPassword: string; newPassword: string }): Promise<unknown>;
 
     // Connection lifecycle
+    /**
+     * 연결 완료까지 기다립니다. 이전 연결의 자동 복구가 이어지는 동안 재시도 한도 소진으로 reject하지 않습니다.
+     * 복구 연결 시 resolve하며, 명시적 disconnect·인증 종료·최초 연결 실패 시 reject합니다.
+     */
     connect(jwt?: string, options?: ConnectOptions): Promise<void>;
     disconnect(): Promise<void>;
     logout(): Promise<void>;
@@ -2588,6 +2688,8 @@ export default class TalkFlowClient implements SdkEventEmitter<TalkFlowClientEve
     /** 푸시 상태 초기화 — 로그아웃 또는 사용자 전환 시 호출. logout() 내부에서 자동 호출됨. */
     resetPush(): void;
     consumePendingRoom(): Promise<string | null>;
+    /** 알림 클릭(cold start)으로 저장된 Gmail 메일 이동을 꺼내고 지운다 — 앱 부팅 때 한 번. */
+    consumePendingMail(): Promise<PendingMail | null>;
     /** 현재 디바이스의 푸시 수신 여부 토글. enable 선행 안 됐으면 undefined 반환. */
     setCurrentDeviceEnabled(enabled: boolean): Promise<void> | undefined;
     /** 특정 디바이스 토글 (관리 UI 용). enable 선행 안 됐으면 undefined 반환. */
@@ -2750,6 +2852,10 @@ export default class TalkFlowClient implements SdkEventEmitter<TalkFlowClientEve
     subscribeRoomList(): Promise<void>;
     unsubscribeRoomList(): void;
     isRoomListSubscribed(): boolean;
+    /** Gmail 메일함 변화 구독(`/user/queue/mail`) — 자동 구독하지 않는다. */
+    subscribeMail(): Promise<void>;
+    unsubscribeMail(): void;
+    isMailSubscribed(): boolean;
     getSubscribedRooms(): string[];
     isSubscribed(roomId: string): boolean;
 
@@ -2771,7 +2877,7 @@ export default class TalkFlowClient implements SdkEventEmitter<TalkFlowClientEve
     initializeIceServers(): Promise<RTCIceServer[]>;
     getTurnCredentials(): Promise<{ iceServers: RTCIceServer[] }>;
 
-    createCallRoom(data: unknown): Promise<unknown>;
+    createCallRoom(data: CreateCallRoomRequest): Promise<unknown>;
     getCallRoom(roomId: string): Promise<unknown>;
     joinCallRoomApi(roomId: string): Promise<unknown>;
     leaveCallRoomApi(roomId: string): Promise<unknown>;