@vibexnpm/talkx 8.4.1 → 8.5.0

package/package.json

@@ -1,6 +1,6 @@
 {
     "name": "@vibexnpm/talkx",
-    "version": "8.4.1",
+    "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;
 
@@ -2732,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

package/src/constants.js

@@ -384,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

@@ -51,6 +51,9 @@ const CHAT_DELEGATE_METHODS = [
     'subscribeRoomList',
     'unsubscribeRoomList',
     'isRoomListSubscribed',
+    'subscribeMail',
+    'unsubscribeMail',
+    'isMailSubscribed',
     'getSubscribedRooms',
     'isSubscribed',
     'startTyping',

package/src/talkflow/eventForwarding.js

@@ -1,3 +1,5 @@
+import { emitNewMailFromSocket } from './mailNotifications.js';
+
 const CONNECTION_EVENT_MAP = [
     ['connected', 'connected'],
     ['disconnected', 'disconnected'],
@@ -49,6 +51,10 @@ const CHAT_EVENT_MAP = [
     ['roomListDeleted', 'roomListDeleted'],
     ['roomListRoomUpdated', 'roomListRoomUpdated'],
     ['roomListUnreadUpdated', 'roomListUnreadUpdated'],
+    // Gmail 메일함 — mailChanged 는 받은 그대로. 새 메일 알림(newMail)은 아래에서 푸시와 합쳐 따로 낸다.
+    ['mailSubscribed', 'mailSubscribed'],
+    ['mailUnsubscribed', 'mailUnsubscribed'],
+    ['mailChanged', 'mailChanged'],
     ['retentionCleanup', 'retentionCleanup']
 ];
 
@@ -102,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);
     };

package/types/index.d.ts

@@ -1340,6 +1340,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;
@@ -1980,6 +2045,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 +2078,10 @@ export interface TalkFlowClientEvents {
      */
     pushFailed: PushFailedPayload;
     pushNotification: PushNotificationPayload;
+    /** Gmail 새 메일 한 통 — 웹소켓·포그라운드 푸시를 합쳐 메일마다 한 번. 메일 푸시는 pushNotification 으로 오지 않는다. */
+    newMail: NewMailEvent;
+    /** Gmail 묶음 푸시(4통 이상) — 포그라운드. */
+    newMailSummary: NewMailSummaryEvent;
 
     // WebRTC (re-emit from WebRTCClient)
     localStreamStarted: unknown;
@@ -2087,6 +2159,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;
@@ -2297,6 +2372,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;
 
@@ -2447,6 +2526,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 +2538,7 @@ export class PushManager {
     /** 현재 디바이스의 푸시 수신 여부 토글. */
     setCurrentDeviceEnabled(enabled: boolean): Promise<void>;
     static consumePendingRoom(projectId?: string): Promise<string | null>;
+    static consumePendingMail(projectId?: string): Promise<PendingMail | null>;
     /**
      * 현재 브라우저의 푸시 권한 상태. 인스턴스 없이도 호출 가능.
      */
@@ -2588,6 +2670,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 +2834,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;