@vibexnpm/talkx 8.2.0 → 8.5.0

package/package.json

@@ -1,6 +1,6 @@
 {
     "name": "@vibexnpm/talkx",
-    "version": "8.2.0",
+    "version": "8.5.0",
     "type": "module",
     "description": "TalkFlow SDK - Chat & WebRTC unified client",
     "main": "dist/talkflow-sdk.umd.js",

package/src/chat/ChatClient.js

@@ -49,6 +49,9 @@ class ChatClient extends EventEmitter {
         // 채팅방 리스트 구독 상태 (카톡 스타일 리스트 실시간 업데이트)
         this.roomListSubscribed = false;
 
+        // Gmail 메일함 변화 구독 상태 — 자동 구독하지 않는다(Gmail 을 연결한 화면에서 subscribeMail()).
+        this.mailSubscribed = false;
+
         // 현재 보고 있는 채팅방 ID (이 방에서만 자동 읽음 처리)
         this._activeRoomId = null;
 
@@ -143,6 +146,7 @@ class ChatClient extends EventEmitter {
             SEARCHING: '검색 중…',
             PLANNING: '기획 중…',
             DOCUMENT_ANALYSIS: '문서 분석 중…',
+            VIDEO_ANALYSIS: '영상 분석 중…',
             WRITING: '작성 중…'
         };
         // PHASE 의 expiresAt 누락/이상 시 fallback TTL (ms) — 서버 ttl(최소 30s) 보다 약간 길게.
@@ -595,6 +599,50 @@ class ChatClient extends EventEmitter {
         return this._unwrapSuccessResponse(response);
     }
 
+    /** 영상 분석용 비공개 업로드. 반환한 assetId를 analyzeVideo에 전달한다. */
+    async uploadVideoAsset(file, options = {}) {
+        if (!file) throw new Error('file is required');
+        return this._unwrapSuccessResponse(await this.apiClient.upload('/api/v1/video-assets', file, {
+            onProgress: options.onProgress, signal: options.signal
+        }));
+    }
+
+    /** 비공개 분석 접수. 네트워크 재시도에는 같은 idempotencyKey를 사용한다. */
+    async analyzeVideo(analysis, options = {}) {
+        if (typeof options.idempotencyKey !== 'string' || !options.idempotencyKey.trim()) {
+            throw new Error('idempotencyKey is required for video analysis');
+        }
+        return this._unwrapSuccessResponse(await this.apiClient.post('/api/v1/video-analyses', analysis,
+            undefined, { 'Idempotency-Key': options.idempotencyKey }));
+    }
+
+    /** 같은 분석 코어를 호출하고 결과를 지정한 방에 게시한다. */
+    async analyzeVideoWithAssistant(roomId, request, options = {}) {
+        if (!roomId || !request?.personaId || !request?.triggerMessageId) {
+            throw new Error('roomId, personaId and triggerMessageId are required');
+        }
+        if (typeof options.idempotencyKey !== 'string' || !options.idempotencyKey.trim()) {
+            throw new Error('idempotencyKey is required for video analysis');
+        }
+        return this._unwrapSuccessResponse(await this.apiClient.post(
+            `/api/v1/rooms/${encodeURIComponent(roomId)}/assistant/tools/analyze-video`, request,
+            undefined, { 'Idempotency-Key': options.idempotencyKey }));
+    }
+
+    async getVideoAnalysis(jobId) {
+        if (!jobId) throw new Error('jobId is required');
+        return this._unwrapSuccessResponse(await this.apiClient.get(`/api/v1/video-analyses/${encodeURIComponent(jobId)}`));
+    }
+
+    async cancelVideoAnalysis(jobId) {
+        if (!jobId) throw new Error('jobId is required');
+        return this._unwrapSuccessResponse(await this.apiClient.post(`/api/v1/video-analyses/${encodeURIComponent(jobId)}/cancel`));
+    }
+
+    async getVideoAnalysisCapabilities() {
+        return this._unwrapSuccessResponse(await this.apiClient.get('/api/v1/video-analyses/capabilities'));
+    }
+
     /**
      * 특정 메시지 온디맨드 번역 (버튼 진입점, 동기).
      *
@@ -868,12 +916,84 @@ class ChatClient extends EventEmitter {
     }
 
     /**
-     * 채팅방 나가기 (구독도 자동 해제됨)
+     * 채팅방 나가기 (구독도 자동 해제됨).
+     *
+     * <p>일반 참가자는 {@code leaveRoom(roomId)} 그대로. <b>방장</b>은 그냥 나갈 수 없다 — 나가면 방에 관리자가
+     * 0명이 되기 때문이다. 방장은 둘 중 하나를 고른다:</p>
+     * <ul>
+     *   <li>위임 후 나가기 — {@code leaveRoom(roomId, { newOwnerId })}</li>
+     *   <li>방 삭제 — {@link #deleteRoom}</li>
+     * </ul>
+     *
+     * <p>서버 응답:</p>
+     * <ul>
+     *   <li>409 {@code ROOM_OWNER_CANNOT_LEAVE} — 방장이 newOwnerId 없이 나가려 함 (선택 화면을 띄울 신호)</li>
+     *   <li>403 {@code NOT_ROOM_ADMIN} — 방장이 아닌데 newOwnerId 를 보냄</li>
+     *   <li>400 {@code CANNOT_TRANSFER_OWNERSHIP_TO_SELF} / {@code INVALID_OWNERSHIP_TARGET}, 404 {@code USER_NOT_IN_ROOM}
+     *       — 위임 대상 오류 ({@link #transferOwnership} 와 같다). 이때는 나가지도 않는다.</li>
+     * </ul>
+     *
      * @param {string} roomId - 채팅방 ID
+     * @param {Object} [options]
+     * @param {string} [options.newOwnerId] - 방장이 나갈 때 방장을 넘겨받을 사람 (방의 활성 사람 참가자 · 활성 계정)
+     * @returns {Promise<Object>}
+     *
+     * @example
+     * try {
+     *   await chat.leaveRoom(roomId);
+     * } catch (e) {
+     *   // 서버 코드는 e.response.code — 방장이면 «위임 후 나가기 / 방 삭제» 선택 화면
+     *   if (e.response?.code === 'ROOM_OWNER_CANNOT_LEAVE') openOwnerExitDialog(roomId);
+     * }
+     * // 위임 후 나가기
+     * await chat.leaveRoom(roomId, { newOwnerId: 'user-2' });
+     */
+    async leaveRoom(roomId, options = {}) {
+        const body = options.newOwnerId ? { newOwnerId: options.newOwnerId } : undefined;
+        const result = await this.apiClient.post(`/api/v1/rooms/${roomId}/leave`, body);
+        this.unsubscribeRoom(roomId);
+        return result;
+    }
+
+    /**
+     * 방장 위임 — 방장은 방에 남고 MEMBER 가 된다. 방장(OWNER) 전용.
+     *
+     * <p>나가면서 넘기려면 {@code leaveRoom(roomId, { newOwnerId })}. 방 참가자 전원에게
+     * {@code roomListOwnerChanged} 가 간다(actorId = 이전 방장, members[0] = 새 방장).</p>
+     *
+     * <p>서버 응답:</p>
+     * <ul>
+     *   <li>403 {@code NOT_ROOM_ADMIN} — 방장 아님 (DIRECT 방은 방장이 없다)</li>
+     *   <li>400 {@code CANNOT_TRANSFER_OWNERSHIP_TO_SELF} — 자기 자신에게 위임</li>
+     *   <li>404 {@code USER_NOT_IN_ROOM} — 대상이 현재 참가자가 아님</li>
+     *   <li>400 {@code INVALID_OWNERSHIP_TARGET} — 대상이 어시스턴트이거나 퇴사·차단 계정</li>
+     * </ul>
+     *
+     * @param {string} roomId
+     * @param {string} newOwnerId - 새 방장 userId
+     * @returns {Promise<Object>} 갱신된 방 상세 (participants[].role 반영 — 봉투를 벗긴 data)
+     */
+    async transferOwnership(roomId, newOwnerId) {
+        const response = await this.apiClient.put(`/api/v1/rooms/${roomId}/owner`, { newOwnerId });
+        return response && typeof response === 'object' && 'data' in response
+            ? response.data
+            : response;
+    }
+
+    /**
+     * 방 삭제 — 방장(OWNER) 전용. 참가자 전원이 나가게 되고 방은 목록에서 사라진다.
+     * 이후 enterRoom·getRoomInfo 는 403(ACCESS_FORBIDDEN — 더는 참가자가 아님), joinGroupRoom 은 404(CHAT_ROOM_NOT_FOUND).
+     *
+     * <p>참가자 전원(방장 포함)에게 {@code roomListDeleted} 가 간다. 본인 구독은 자동 해제된다.
+     * 메시지·첨부는 서버에 보존된다(소프트 삭제) — 되살리는 API 는 없다.</p>
+     *
+     * <p>서버 응답: 403 {@code NOT_ROOM_ADMIN} — 방장 아님.</p>
+     *
+     * @param {string} roomId
      * @returns {Promise<Object>}
      */
-    async leaveRoom(roomId) {
-        const result = await this.apiClient.post(`/api/v1/rooms/${roomId}/leave`);
+    async deleteRoom(roomId) {
+        const result = await this.apiClient.delete(`/api/v1/rooms/${roomId}`);
         this.unsubscribeRoom(roomId);
         return result;
     }
@@ -2551,6 +2671,8 @@ class ChatClient extends EventEmitter {
      *  - roomListJoined — 방 입장 (ROOM_JOINED)
      *  - roomListLeft — 방 퇴장 (ROOM_LEFT)
      *  - roomListSelfLeft — 본인이 나간 경우 (리스트에서 제거 신호)
+     *  - roomListOwnerChanged — 방장 위임 (ROOM_OWNER_CHANGED, members[0] = 새 방장)
+     *  - roomListDeleted — 방장이 방을 삭제 (ROOM_DELETED, 리스트 제거 + 방 화면 닫기)
      *
      * @returns {Promise<void>}
      *
@@ -2613,6 +2735,61 @@ class ChatClient extends EventEmitter {
         return this.roomListSubscribed;
     }
 
+    /**
+     * Gmail 메일함 변화 구독 — {@code /user/queue/mail}. 받은 이벤트를 {@code mailChanged} 로 그대로 낸다.
+     *
+     * <p>새 메일 알림은 최상위 클라이언트의 {@code newMail} 을 쓴다 — 웹소켓 이벤트의 미리보기와 포그라운드 FCM 메일 푸시를
+     * 합쳐 메일마다 한 번만 낸다. 재연결 때는 연결 관리자가 구독을 되살린다(이벤트는 최대 한 번 전달이라 재연결·창 포커스 때
+     * 안읽은 수와 목록을 다시 읽는다).</p>
+     */
+    async subscribeMail() {
+        if (this.mailSubscribed) {
+            this.logger.debug('Already subscribed to mail');
+            return;
+        }
+
+        await this.connectionManager.subscribe(WebSocketPaths.MAIL_USER_DESTINATION, (event) => {
+            this._handleMailEvent(event);
+        });
+
+        this.mailSubscribed = true;
+        this.logger.info('Subscribed to mail');
+        this.emit('mailSubscribed', {});
+    }
+
+    /**
+     * Gmail 메일함 변화 구독 해제.
+     */
+    unsubscribeMail() {
+        if (!this.mailSubscribed) {
+            return;
+        }
+
+        this.connectionManager.unsubscribe(WebSocketPaths.MAIL_USER_DESTINATION);
+        this.mailSubscribed = false;
+
+        this.logger.info('Unsubscribed from mail');
+        this.emit('mailUnsubscribed', {});
+    }
+
+    /**
+     * Gmail 메일함 변화 구독 여부.
+     * @returns {boolean}
+     */
+    isMailSubscribed() {
+        return this.mailSubscribed;
+    }
+
+    /** 메일 이벤트 — 보낸 사람·제목이 실리므로 내용은 로그에 남기지 않는다(연결 ID·건수만). */
+    _handleMailEvent(event) {
+        if (!event || event.eventType !== 'MAIL_CHANGED') {
+            return;
+        }
+        this.logger.debug('Mail changed:', event.connectionId,
+            Array.isArray(event.messages) ? event.messages.length : 0);
+        this.emit('mailChanged', event);
+    }
+
     /**
      * 메시지 읽음 처리
      * @param {string} roomId - 채팅방 ID
@@ -2819,6 +2996,19 @@ class ChatClient extends EventEmitter {
                     this.emit('roomListSelfKicked', event);
                 }
                 break;
+            case RoomListEventType.ROOM_OWNER_CHANGED:
+                // 방장 위임 — actorId=이전 방장, members[0]=새 방장. 방장 표시·관리 메뉴를 갱신한다.
+                this.emit('roomListOwnerChanged', event);
+                break;
+            case RoomListEventType.ROOM_DELETED:
+                // 방장이 방을 삭제 — 모든 참가자가 리스트에서 제거하고 열린 방 화면을 닫는다.
+                // 🔴 그 방 구독은 SDK 가 «먼저» 푼다. 남겨 두면 아무것도 못 받으면서 재연결 때마다 되살아나 서버에
+                //    거부된다 — 그 거부로 연결을 끊던 서버 버전에서는 «재연결 → 거부 → 끊김» 이 반복돼 다른 방 실시간까지 멈췄다.
+                if (this.subscribedRooms.has(event.roomId)) {
+                    this.unsubscribeRoom(event.roomId);
+                }
+                this.emit('roomListDeleted', event);
+                break;
             case RoomListEventType.ROOM_BANNED:
                 this.emit('roomListBanned', event);
                 // 본인이 영구 차단당한 경우 편의 이벤트 — "영구 차단되었습니다" 표시 + 리스트 제거

package/src/constants.js

@@ -333,6 +333,18 @@ export const RoomListEventType = {
     ROOM_KICKED: 'ROOM_KICKED',
     /** 방장에 의한 추방 + 영구 차단 → payload 는 ROOM_KICKED 와 동일, 재입장 거부됨. */
     ROOM_BANNED: 'ROOM_BANNED',
+    /**
+     * 방장 위임 → actorId 는 이전 방장, members[0] 이 새 방장. 방장 표시·관리 권한을 갱신한다.
+     * «위임 후 나가기» 면 이어서 같은 이전 방장의 ROOM_LEFT 가 온다.
+     * SDK 는 이를 roomListOwnerChanged 이벤트로 emit 한다.
+     */
+    ROOM_OWNER_CHANGED: 'ROOM_OWNER_CHANGED',
+    /**
+     * 방장이 방을 삭제 → 리스트에서 제거 + 열린 방 화면 닫기. actorId 는 삭제한 방장.
+     * 이후 enterRoom·getRoomInfo 는 403(ACCESS_FORBIDDEN — 더는 참가자가 아님), joinGroupRoom 은 404.
+     * SDK 는 이를 roomListDeleted 이벤트로 emit 한다.
+     */
+    ROOM_DELETED: 'ROOM_DELETED',
     /** 메시지 보관 기간 정리 → cutoffTime 이전 메시지를 UI에서 제거. */
     MESSAGE_RETENTION_CLEANUP: 'MESSAGE_RETENTION_CLEANUP',
     /**
@@ -372,6 +384,10 @@ export const WebSocketPaths = {
     // 클라이언트는 "/user/queue/rooms" 구독 (Spring STOMP 가 세션별 자동 격리)
     ROOM_LIST_USER_DESTINATION: '/user/queue/rooms',
 
+    // Gmail 메일함 변화 (서버 GMAIL_MAILBOX_FEATURES_DESIGN.md §6-6·§6-7)
+    // 서버가 convertAndSendToUser(userId, "/queue/mail", MAIL_CHANGED) 로 전송 — 새 메일이면 messages[] 미리보기 포함
+    MAIL_USER_DESTINATION: '/user/queue/mail',
+
     // WebRTC destinations
     getWebRTCDestination: (roomId) => `/topic/webrtc/${roomId}`,
     getWebRTCUserDestination: () => `/user/queue/webrtc`,

package/src/push/PushManager.js

@@ -68,6 +68,10 @@ const PENDING_NAVIGATION_STORE_NAME = 'pendingNavigation';
 // SW 와 동일한 key 규칙 사용 — 멀티테넌트에서 다른 projectId 의 pending 을 건드리지 않도록 한다.
 const PENDING_NAVIGATION_KEY_PREFIX = 'pending-room';
 const PENDING_NAVIGATION_LEGACY_KEY = 'pending-room';
+// Gmail 메일 알림 클릭 — 방과 다른 key 라 consumePendingRoom 과 섞이지 않는다. 프로젝트별로만 저장한다(레거시 전역 key 없음).
+const PENDING_MAIL_KEY_PREFIX = 'pending-mail';
+// 앱이 이 시간 안에 꺼내지 않은 메일 이동은 버린다 — 며칠 뒤 앱을 열 때 엉뚱하게 메일 화면으로 가지 않게.
+const PENDING_MAIL_MAX_AGE_MS = 10 * 60 * 1000;
 
 // deviceId 저장 — 같은 IndexedDB 의 별도 store 사용 (XSS 방어 + 기존 인프라 재사용).
 // DB 버전은 2 로 bump — v1 에서 pendingNavigation 만 있던 상태에서 deviceInfo store 추가.
@@ -175,6 +179,54 @@ function generateDeviceId() {
     return 'web-' + random;
 }
 
+/**
+ * SW 가 저장한 메일 이동(알림 클릭 → 열린 창 없음)을 꺼내고 지운다. 같은 프로젝트·10분 안의 것만.
+ *
+ * @returns {Promise<{connectionId: string, messageId: (string|null)}|null>}
+ */
+async function consumePendingMailFromIndexedDB(projectId) {
+    if (!projectId || typeof projectId !== 'string' || projectId.trim() === '') {
+        return null;
+    }
+    const db = await openPendingNavigationDb();
+    if (!db) {
+        return null;
+    }
+    const key = PENDING_MAIL_KEY_PREFIX + ':' + projectId;
+    return new Promise((resolve, reject) => {
+        const transaction = db.transaction(PENDING_NAVIGATION_STORE_NAME, 'readwrite');
+        const store = transaction.objectStore(PENDING_NAVIGATION_STORE_NAME);
+        let pending = null;
+        const request = store.get(key);
+        request.onsuccess = () => {
+            const record = request.result;
+            if (!record) {
+                return;
+            }
+            store.delete(key);
+            const fresh = typeof record.savedAt === 'number' && Date.now() - record.savedAt <= PENDING_MAIL_MAX_AGE_MS;
+            if (fresh && record.projectId === projectId && record.connectionId) {
+                pending = { connectionId: record.connectionId, messageId: record.messageId || null };
+            }
+        };
+        request.onerror = () => {
+            reject(request.error || new Error('IndexedDB read failed'));
+        };
+        transaction.oncomplete = () => {
+            db.close();
+            resolve(pending);
+        };
+        transaction.onerror = () => {
+            db.close();
+            reject(transaction.error || new Error('IndexedDB transaction failed'));
+        };
+        transaction.onabort = () => {
+            db.close();
+            reject(transaction.error || new Error('IndexedDB transaction aborted'));
+        };
+    });
+}
+
 async function consumePendingRoomFromIndexedDB(projectId) {
     const db = await openPendingNavigationDb();
     if (!db) {
@@ -302,6 +354,17 @@ class PushManager {
         return consumePendingRoomFromIndexedDB(projectId);
     }
 
+    /**
+     * 서비스 워커가 cold start 시 저장한 메일 이동(Gmail 메일 알림 클릭)을 꺼내고 지운다.
+     * 앱 부팅 때 호출해 메일 화면으로 라우팅한다 — {@code messageId} 가 있으면 그 메일 상세, 없으면(묶음 알림) 받은메일함.
+     *
+     * @param {string} projectId
+     * @returns {Promise<{connectionId: string, messageId: (string|null)}|null>}
+     */
+    static async consumePendingMail(projectId) {
+        return consumePendingMailFromIndexedDB(projectId);
+    }
+
     /**
      * 현재 브라우저의 푸시 권한 상태를 조회한다.
      *
@@ -669,6 +732,15 @@ class PushManager {
         return PushManager.consumePendingRoom(this.projectId);
     }
 
+    /**
+     * 서비스 워커가 cold start 시 저장한 메일 이동을 꺼내고 지운다 — {@link PushManager.consumePendingMail}.
+     *
+     * @returns {Promise<{connectionId: string, messageId: (string|null)}|null>}
+     */
+    async consumePendingMail() {
+        return PushManager.consumePendingMail(this.projectId);
+    }
+
     /**
      * 현재 푸시 상태를 정리한다.
      * 로그아웃 또는 다른 사용자로 전환할 때 foreground listener 와 활성화 상태를 초기화한다.

package/src/talkflow/delegates.js

@@ -7,6 +7,9 @@ const CHAT_DELEGATE_METHODS = [
     'createGroupRoom',
     'joinGroupRoom',
     'leaveRoom',
+    // 방장 위임(방에 남음) · 방 삭제 — 방장의 «위임 후 나가기» 는 leaveRoom(roomId, { newOwnerId }).
+    'transferOwnership',
+    'deleteRoom',
     'updateGroupRoom',
     'inviteToGroupRoom',
     'kickMember',
@@ -48,6 +51,9 @@ const CHAT_DELEGATE_METHODS = [
     'subscribeRoomList',
     'unsubscribeRoomList',
     'isRoomListSubscribed',
+    'subscribeMail',
+    'unsubscribeMail',
+    'isMailSubscribed',
     'getSubscribedRooms',
     'isSubscribed',
     'startTyping',
@@ -61,6 +67,12 @@ const CHAT_DELEGATE_METHODS = [
     'rateAssistantMessage',
     'summarizeWithAssistant',
     'translateWithAssistant',
+    'uploadVideoAsset',
+    'analyzeVideo',
+    'analyzeVideoWithAssistant',
+    'getVideoAnalysis',
+    'cancelVideoAnalysis',
+    'getVideoAnalysisCapabilities',
     'refreshSummary',
     'getSummary',
     'getRoomPmPrompt',

package/src/talkflow/eventForwarding.js

@@ -1,3 +1,5 @@
+import { emitNewMailFromSocket } from './mailNotifications.js';
+
 const CONNECTION_EVENT_MAP = [
     ['connected', 'connected'],
     ['disconnected', 'disconnected'],
@@ -34,6 +36,8 @@ const CHAT_EVENT_MAP = [
     ['roomListUnsubscribed', 'roomListUnsubscribed'],
     ['roomListUpdate', 'roomListUpdate'],
     ['roomListMessage', 'roomListMessage'],
+    ['roomListMessageDeleted', 'roomListMessageDeleted'],
+    ['roomListMessageUpdated', 'roomListMessageUpdated'],
     ['roomListCreated', 'roomListCreated'],
     ['roomListJoined', 'roomListJoined'],
     ['roomListLeft', 'roomListLeft'],
@@ -42,8 +46,15 @@ const CHAT_EVENT_MAP = [
     ['roomListSelfKicked', 'roomListSelfKicked'],
     ['roomListBanned', 'roomListBanned'],
     ['roomListSelfBanned', 'roomListSelfBanned'],
+    // 방장 위임 · 방 삭제 — 타입에 선언한 이벤트는 여기 없으면 최상위 client.on 에서 안 울린다.
+    ['roomListOwnerChanged', 'roomListOwnerChanged'],
+    ['roomListDeleted', 'roomListDeleted'],
     ['roomListRoomUpdated', 'roomListRoomUpdated'],
     ['roomListUnreadUpdated', 'roomListUnreadUpdated'],
+    // Gmail 메일함 — mailChanged 는 받은 그대로. 새 메일 알림(newMail)은 아래에서 푸시와 합쳐 따로 낸다.
+    ['mailSubscribed', 'mailSubscribed'],
+    ['mailUnsubscribed', 'mailUnsubscribed'],
+    ['mailChanged', 'mailChanged'],
     ['retentionCleanup', 'retentionCleanup']
 ];
 
@@ -97,6 +108,7 @@ export function setupEventForwarding(client) {
 
     if (client.chat) {
         forwardMappedEvents(client.chat, client, CHAT_EVENT_MAP);
+        client.chat.on('mailChanged', (event) => emitNewMailFromSocket(client, event));
     }
 
     if (client.webrtc) {

package/src/talkflow/mailNotifications.js

@@ -0,0 +1,154 @@
+/**
+ * Gmail 새 메일 알림 — 웹소켓 {@code MAIL_CHANGED} 의 미리보기와 포그라운드 FCM 메일 푸시를 합쳐 메일마다 한 번만
+ * {@code newMail} 을 낸다 (서버 GMAIL_MAILBOX_FEATURES_DESIGN.md §6-7).
+ *
+ * <p>같은 메일이 두 길로 온다: 서버는 앱 접속 여부와 상관없이 FCM 을 보내고(채팅과 같음), 화면이 떠 있으면 웹소켓
+ * 이벤트도 받는다. 중복 판정 키는 {@code projectId:connectionId:messageId} — 어느 쪽이 먼저 와도 두 번째는 버린다.
+ * 묶음 푸시({@code kind=SUMMARY})도 묶은 메시지 ID({@code data.messageIds})로 같은 판정을 하고, 처음 보는 메일이 있을 때만
+ * 그 수로 {@code newMailSummary} 를 낸다(같은 묶음이 다시 와도, 개별 알림을 이미 받았어도 다시 띄우지 않는다).</p>
+ *
+ * <p>보낸 사람·제목은 로그에 남기지 않는다.</p>
+ */
+
+/** 같은 메일을 다시 보지 않는 시간 — 서버 푸시 수명(수신 후 30분)보다 길게. */
+const DEDUP_TTL_MS = 60 * 60 * 1000;
+/** 기억하는 메일 수 상한 — 넘으면 오래된 것부터 잊는다. */
+const DEDUP_MAX = 1000;
+
+export function createMailNotificationDeduper({ ttlMs = DEDUP_TTL_MS, max = DEDUP_MAX, now = () => Date.now() } = {}) {
+    const seen = new Map();
+    return {
+        /** 처음 보는 키면 true(그리고 기억), 이미 본 키면 false. */
+        accept(key) {
+            const at = now();
+            for (const [seenKey, seenAt] of seen) {
+                if (at - seenAt < ttlMs) {
+                    break; // Map 은 넣은 순서 — 첫 살아 있는 항목부터는 다 살아 있다
+                }
+                seen.delete(seenKey);
+            }
+            if (seen.has(key)) {
+                return false;
+            }
+            seen.set(key, at);
+            while (seen.size > max) {
+                seen.delete(seen.keys().next().value);
+            }
+            return true;
+        },
+        size() {
+            return seen.size;
+        }
+    };
+}
+
+function deduperOf(client) {
+    if (!client._mailNotificationDeduper) {
+        client._mailNotificationDeduper = createMailNotificationDeduper();
+    }
+    return client._mailNotificationDeduper;
+}
+
+function projectIdOf(client) {
+    return (client.options && client.options.projectId) || null;
+}
+
+function keyOf(projectId, connectionId, messageId) {
+    return `${projectId || ''}:${connectionId}:${messageId}`;
+}
+
+function senderOf(from) {
+    if (!from || typeof from !== 'object') {
+        return null;
+    }
+    return (typeof from.name === 'string' && from.name.trim() !== '') ? from.name : (from.email || null);
+}
+
+/**
+ * 웹소켓 {@code MAIL_CHANGED} → 새 메일마다 {@code newMail}. 읽음·보관 같은 변화(미리보기 없음)는 아무것도 내지 않는다.
+ */
+export function emitNewMailFromSocket(client, event) {
+    if (!event || event.eventType !== 'MAIL_CHANGED' || !Array.isArray(event.messages) || !event.connectionId) {
+        return;
+    }
+    const projectId = projectIdOf(client);
+    const deduper = deduperOf(client);
+    for (const preview of event.messages) {
+        if (!preview || !preview.messageId) {
+            continue;
+        }
+        if (!deduper.accept(keyOf(projectId, event.connectionId, preview.messageId))) {
+            continue;
+        }
+        client.emit('newMail', {
+            projectId,
+            connectionId: event.connectionId,
+            messageId: preview.messageId,
+            threadId: preview.threadId || null,
+            sender: senderOf(preview.from),
+            from: preview.from || null,
+            subject: preview.subject || null,
+            receivedAt: preview.receivedAt || null,
+            source: 'socket'
+        });
+    }
+}
+
+/**
+ * 포그라운드 FCM 메일 푸시({@code data.target === 'MAIL'}) → {@code newMail}(한 통) 또는 {@code newMailSummary}(묶음).
+ * 메일 푸시면 {@code true} — 호출자는 {@code pushNotification} 을 내지 않는다(같은 알림을 두 번 띄우지 않게).
+ */
+export function handleMailPush(client, payload) {
+    const data = (payload && payload.data) || {};
+    if (data.target !== 'MAIL') {
+        return false;
+    }
+    const projectId = projectIdOf(client);
+    if (!data.connectionId) {
+        return true;
+    }
+    if (data.kind === 'SUMMARY') {
+        const ids = typeof data.messageIds === 'string'
+            ? data.messageIds.split(',').map((id) => id.trim()).filter(Boolean)
+            : [];
+        if (ids.length === 0) {
+            // 메시지 ID 없는 묶음(구버전 서버) — 거를 기준이 없어 건수 그대로 낸다.
+            const count = Number.parseInt(data.count, 10);
+            client.emit('newMailSummary', {
+                projectId,
+                connectionId: data.connectionId,
+                count: Number.isFinite(count) ? count : null,
+                messageIds: [],
+                source: 'push'
+            });
+            return true;
+        }
+        const deduper = deduperOf(client);
+        const unseen = ids.filter((id) => deduper.accept(keyOf(projectId, data.connectionId, id)));
+        if (unseen.length > 0) {
+            client.emit('newMailSummary', {
+                projectId,
+                connectionId: data.connectionId,
+                count: unseen.length,
+                messageIds: unseen,
+                source: 'push'
+            });
+        }
+        return true;
+    }
+    if (!data.messageId || !deduperOf(client).accept(keyOf(projectId, data.connectionId, data.messageId))) {
+        return true;
+    }
+    client.emit('newMail', {
+        projectId,
+        connectionId: data.connectionId,
+        messageId: data.messageId,
+        threadId: data.threadId || null,
+        sender: (payload.notification && payload.notification.title) || data.title || null,
+        from: null,
+        subject: (payload.notification && payload.notification.body) || data.body || null,
+        receivedAt: null,
+        source: 'push'
+    });
+    return true;
+}

package/src/talkflow/session.js

@@ -3,6 +3,7 @@ import ConnectionManager from '../core/ConnectionManager.js';
 import ChatClient from '../chat/ChatClient.js';
 import WebRTCClient from '../webrtc/WebRTCClient.js';
 import PushManager from '../push/PushManager.js';
+import { handleMailPush } from './mailNotifications.js';
 
 export function initializeSubClients(client) {
     if (client.connectionManager) {
@@ -127,6 +128,7 @@ export function applySessionMethods(TalkFlowClient) {
         if (this.chat) {
             this.chat.unsubscribeAllRooms();
             this.chat.unsubscribeRoomList();
+            this.chat.unsubscribeMail();
         }
 
         await this.connectionManager.disconnect();
@@ -217,6 +219,11 @@ export function applySessionMethods(TalkFlowClient) {
                     return;
                 }
 
+                // Gmail 메일 푸시 — 웹소켓 미리보기와 합쳐 newMail/newMailSummary 로만 낸다(pushNotification 아님).
+                if (handleMailPush(this, payload)) {
+                    return;
+                }
+
                 const activeRoomId = this.chat?.getActiveRoom();
 
                 if (activeRoomId && activeRoomId === data.roomId) {
@@ -291,6 +298,10 @@ export function applySessionMethods(TalkFlowClient) {
         return PushManager.consumePendingRoom(this.options.projectId);
     };
 
+    TalkFlowClient.prototype.consumePendingMail = async function consumePendingMail() {
+        return PushManager.consumePendingMail(this.options.projectId);
+    };
+
     TalkFlowClient.prototype.setCurrentDeviceEnabled = function setCurrentDeviceEnabled(enabled) {
         return this.pushManager?.setCurrentDeviceEnabled(enabled);
     };