@vibexnpm/talkx 2.3.1

package/src/push/PushManager.js

@@ -0,0 +1,893 @@
+/**
+ * PushManager
+ * FCM 웹 푸시 알림 관리 (Firebase 초기화, 서비스 워커, 권한, 토큰)
+ */
+
+import Logger from '../utils/Logger.js';
+import { LogLevel } from '../constants.js';
+
+/**
+ * 푸시 활성화 실패 사유 분류.
+ *
+ * <p>호출자가 {@code error.message} 문자열 매칭 대신 {@code error.code} 로 분기할 수 있도록
+ * 표준화된 enum 값을 제공한다.</p>
+ *
+ * <ul>
+ *   <li>{@code UNSUPPORTED_BROWSER} — Notification / Service Worker 미지원 환경</li>
+ *   <li>{@code FIREBASE_NOT_INSTALLED} — firebase 패키지 동적 import 실패</li>
+ *   <li>{@code SW_REGISTER_FAILED} — 서비스 워커 등록 실패 (firebase-messaging-sw.js 누락 등)</li>
+ *   <li>{@code PERMISSION_DENIED} — 브라우저 알림 권한 거부 (이미 거부 상태 또는 이번 요청에서 거부)</li>
+ *   <li>{@code TOKEN_FAILED} — FCM 토큰 발급 실패</li>
+ *   <li>{@code SERVER_REGISTER_FAILED} — TalkFlow 서버에 디바이스 토큰 등록 실패</li>
+ * </ul>
+ */
+export const PushErrorCode = Object.freeze({
+    UNSUPPORTED_BROWSER: 'UNSUPPORTED_BROWSER',
+    FIREBASE_NOT_INSTALLED: 'FIREBASE_NOT_INSTALLED',
+    SW_REGISTER_FAILED: 'SW_REGISTER_FAILED',
+    PERMISSION_DENIED: 'PERMISSION_DENIED',
+    TOKEN_FAILED: 'TOKEN_FAILED',
+    SERVER_REGISTER_FAILED: 'SERVER_REGISTER_FAILED'
+});
+
+/**
+ * 푸시 활성화 과정에서 발생한 분류된 에러.
+ *
+ * <p>일반 {@link Error} 와 달리 {@code code} 필드로 분류되어 있어
+ * 호출자가 사유별로 다른 UX (권한 거부 → 설정 가이드, 토큰 실패 → 재시도 등) 를 적용할 수 있다.</p>
+ */
+export class PushError extends Error {
+    /**
+     * @param {string} code - {@link PushErrorCode} 값 중 하나
+     * @param {string} message - 사람이 읽는 메시지
+     * @param {Error} [cause] - 원인 에러 (네트워크 실패 등)
+     */
+    constructor(code, message, cause) {
+        super(message);
+        this.name = 'PushError';
+        this.code = code;
+        if (cause !== undefined) {
+            this.cause = cause;
+        }
+    }
+}
+
+// TalkFlow 기본 Firebase 설정 (고객별 분리 시 서버에서 내려받는 구조로 확장 가능)
+const DEFAULT_FIREBASE_CONFIG = {
+    apiKey: "AIzaSyB8VhRg6rSvUI7K3Ua7h6sBpLvaQGmIkRc",
+    authDomain: "chatting-c3e5d.firebaseapp.com",
+    projectId: "chatting-c3e5d",
+    storageBucket: "chatting-c3e5d.firebasestorage.app",
+    messagingSenderId: "1020496565673",
+    appId: "1:1020496565673:web:5039167257fd83f5ce20b8"
+};
+
+const DEFAULT_VAPID_KEY = 'BGP8qaSm1ntjWd4n9pc0lX_rw4BmMxm9u4pvRIANCitbmYaV0iy-gn05suTKBo88kUBejxdxM8sb6x2nt3avu8c';
+const PENDING_NAVIGATION_DB_NAME = 'talkflowPush';
+const PENDING_NAVIGATION_STORE_NAME = 'pendingNavigation';
+// SW 와 동일한 key 규칙 사용 — 멀티테넌트에서 다른 projectId 의 pending 을 건드리지 않도록 한다.
+const PENDING_NAVIGATION_KEY_PREFIX = 'pending-room';
+const PENDING_NAVIGATION_LEGACY_KEY = 'pending-room';
+
+// deviceId 저장 — 같은 IndexedDB 의 별도 store 사용 (XSS 방어 + 기존 인프라 재사용).
+// DB 버전은 2 로 bump — v1 에서 pendingNavigation 만 있던 상태에서 deviceInfo store 추가.
+const DEVICE_STORE_NAME = 'deviceInfo';
+const DEVICE_ID_KEY = 'device-id';
+const DEVICE_ID_DB_VERSION = 2;
+// 기존 localStorage 에 저장된 deviceId 를 IndexedDB 로 옮긴 뒤 제거하기 위한 legacy key.
+const LEGACY_LOCAL_STORAGE_DEVICE_ID_KEY = 'talkflow_device_id';
+
+function buildPendingNavigationKey(projectId) {
+    if (projectId && typeof projectId === 'string' && projectId.trim() !== '') {
+        return PENDING_NAVIGATION_KEY_PREFIX + ':' + projectId;
+    }
+    return PENDING_NAVIGATION_LEGACY_KEY;
+}
+
+function openPendingNavigationDb() {
+    if (typeof indexedDB === 'undefined') {
+        return Promise.resolve(null);
+    }
+
+    return new Promise((resolve, reject) => {
+        const request = indexedDB.open(PENDING_NAVIGATION_DB_NAME, DEVICE_ID_DB_VERSION);
+
+        request.onupgradeneeded = () => {
+            const db = request.result;
+            // v1 → v2: deviceInfo store 추가.
+            // 기존 pendingNavigation store 는 그대로 유지 (contains 체크로 멱등).
+            if (!db.objectStoreNames.contains(PENDING_NAVIGATION_STORE_NAME)) {
+                db.createObjectStore(PENDING_NAVIGATION_STORE_NAME, { keyPath: 'id' });
+            }
+            if (!db.objectStoreNames.contains(DEVICE_STORE_NAME)) {
+                db.createObjectStore(DEVICE_STORE_NAME, { keyPath: 'id' });
+            }
+        };
+
+        request.onsuccess = () => resolve(request.result);
+        request.onerror = () => reject(request.error || new Error('IndexedDB open failed'));
+    });
+}
+
+/**
+ * IndexedDB 에서 deviceId 를 읽는다.
+ * @returns {Promise<string|null>} 저장된 deviceId, 없으면 null. IndexedDB 사용 불가 시 null.
+ */
+function readDeviceIdFromIndexedDb() {
+    return openPendingNavigationDb().then(db => {
+        if (!db) return null;
+        return new Promise((resolve, reject) => {
+            const tx = db.transaction(DEVICE_STORE_NAME, 'readonly');
+            const store = tx.objectStore(DEVICE_STORE_NAME);
+            const request = store.get(DEVICE_ID_KEY);
+            request.onsuccess = () => {
+                const record = request.result;
+                resolve(record && record.value ? record.value : null);
+            };
+            request.onerror = () => reject(request.error || new Error('IndexedDB read failed'));
+            tx.oncomplete = () => db.close();
+            tx.onerror = () => db.close();
+            tx.onabort = () => db.close();
+        });
+    });
+}
+
+/**
+ * IndexedDB 에 deviceId 를 저장한다.
+ *
+ * <p><b>반환값 의미</b>:</p>
+ * <ul>
+ *   <li>{@code true} — transaction 이 complete 까지 성공적으로 완료됨.</li>
+ *   <li>{@code false} — open / transaction 실패, IDB 사용 불가, 기타 예외.</li>
+ * </ul>
+ *
+ * <p>호출자는 반환값이 {@code true} 일 때만 "영속성 확보" 로 간주해야 한다.
+ * 특히 legacy localStorage 정리는 read-back 검증까지 거친 뒤 수행.</p>
+ *
+ * @param {string} deviceId
+ * @returns {Promise<boolean>}
+ */
+function writeDeviceIdToIndexedDb(deviceId) {
+    return openPendingNavigationDb().then(db => {
+        if (!db) return false;
+        return new Promise(resolve => {
+            try {
+                const tx = db.transaction(DEVICE_STORE_NAME, 'readwrite');
+                tx.objectStore(DEVICE_STORE_NAME).put({ id: DEVICE_ID_KEY, value: deviceId });
+                tx.oncomplete = () => { db.close(); resolve(true); };
+                tx.onerror = () => { db.close(); resolve(false); };
+                tx.onabort = () => { db.close(); resolve(false); };
+            } catch (e) {
+                try { db.close(); } catch (_) { /* ignore */ }
+                resolve(false);
+            }
+        });
+    }).catch(() => false);
+}
+
+/**
+ * 신규 deviceId 생성.
+ */
+function generateDeviceId() {
+    const random = (typeof crypto !== 'undefined' && crypto.randomUUID)
+        ? crypto.randomUUID()
+        : Date.now().toString(36) + Math.random().toString(36).substring(2);
+    return 'web-' + random;
+}
+
+async function consumePendingRoomFromIndexedDB(projectId) {
+    const db = await openPendingNavigationDb();
+    if (!db) {
+        return null;
+    }
+
+    // 1차: projectId 별 key 를 조회한다.
+    // 2차 (mixed rollout 호환): projectId 가 있지만 1차 miss 인 경우,
+    //     legacy 전역 key 도 fallback 으로 조회한다. 서버 배포 전 또는 구버전 SW 에서 발생한
+    //     projectId 없는 payload 는 legacy key (pending-room) 에 저장되어 있을 수 있다.
+    //     legacy record 는 반드시 record.projectId 가 비어있어야 안전하게 소비한다 —
+    //     다른 프로젝트의 값이 섞일 여지를 원천 차단.
+    const primaryKey = buildPendingNavigationKey(projectId);
+    const shouldTryLegacyFallback = !!projectId && primaryKey !== PENDING_NAVIGATION_LEGACY_KEY;
+
+    return new Promise((resolve, reject) => {
+        const transaction = db.transaction(PENDING_NAVIGATION_STORE_NAME, 'readwrite');
+        const store = transaction.objectStore(PENDING_NAVIGATION_STORE_NAME);
+
+        let pendingRoomId = null;
+        let finalizedKey = null;
+
+        const primaryRequest = store.get(primaryKey);
+
+        primaryRequest.onsuccess = () => {
+            const record = primaryRequest.result;
+            // 저장된 record 의 projectId 와 요청한 projectId 가 일치할 때만 소비.
+            // key 분리가 정상 작동하면 이 체크는 리던던트이지만, 레거시 전역 key 로 저장된
+            // 레코드를 다른 프로젝트가 실수로 소비하는 것을 막기 위한 방어.
+            if (record && record.roomId) {
+                const recordProjectId = record.projectId || null;
+                const requestedProjectId = projectId || null;
+                if (recordProjectId === requestedProjectId) {
+                    pendingRoomId = record.roomId;
+                    finalizedKey = primaryKey;
+                    store.delete(primaryKey);
+                    return;
+                }
+            }
+
+            // 1차 miss — legacy fallback 시도 (mixed rollout 호환 경로).
+            if (!shouldTryLegacyFallback) {
+                return;
+            }
+
+            const legacyRequest = store.get(PENDING_NAVIGATION_LEGACY_KEY);
+            legacyRequest.onsuccess = () => {
+                const legacyRecord = legacyRequest.result;
+                // legacy record 는 projectId 가 null/undefined 인 경우에만 안전하게 소비.
+                // SW v1 또는 구버전 서버가 projectId 없이 저장한 경우에 해당한다.
+                if (
+                    legacyRecord &&
+                    legacyRecord.roomId &&
+                    !legacyRecord.projectId
+                ) {
+                    pendingRoomId = legacyRecord.roomId;
+                    finalizedKey = PENDING_NAVIGATION_LEGACY_KEY;
+                    store.delete(PENDING_NAVIGATION_LEGACY_KEY);
+                }
+            };
+            // legacyRequest.onerror 는 별도 처리하지 않는다 — primary 가 성공했다면 transaction 은
+            // 이미 유효하고, 실패하면 transaction.onerror 로 넘어간다.
+        };
+
+        primaryRequest.onerror = () => {
+            reject(primaryRequest.error || new Error('IndexedDB read failed'));
+        };
+
+        transaction.oncomplete = () => {
+            db.close();
+            // finalizedKey 를 쓰진 않지만, 추후 디버깅/로그 확장 시 어느 key 를 소비했는지 구분 가능.
+            void finalizedKey;
+            resolve(pendingRoomId);
+        };
+
+        transaction.onerror = () => {
+            db.close();
+            reject(transaction.error || new Error('IndexedDB transaction failed'));
+        };
+
+        transaction.onabort = () => {
+            db.close();
+            reject(transaction.error || new Error('IndexedDB transaction aborted'));
+        };
+    });
+}
+
+class PushManager {
+    /**
+     * @param {Object} options
+     * @param {Object} options.apiClient - ApiClient 인스턴스
+     * @param {string} [options.projectId] - 프로젝트 ID (멀티테넌트 환경에서 알림 라우팅 격리용)
+     * @param {Object} [options.firebaseConfig] - Firebase 설정 (기본: TalkFlow 설정)
+     * @param {string} [options.vapidKey] - VAPID Key (기본: TalkFlow 키)
+     * @param {string} [options.serviceWorkerPath] - 서비스 워커 경로 (기본: '/firebase-messaging-sw.js')
+     * @param {number} [options.logLevel] - 로그 레벨
+     */
+    constructor(options) {
+        this.apiClient = options.apiClient;
+        this.projectId = options.projectId || null;
+        this.firebaseConfig = options.firebaseConfig || DEFAULT_FIREBASE_CONFIG;
+        this.vapidKey = options.vapidKey || DEFAULT_VAPID_KEY;
+        this.serviceWorkerPath = options.serviceWorkerPath || '/firebase-messaging-sw.js';
+        this.logger = new Logger(options.logLevel || LogLevel.WARN, 'PushManager');
+
+        this._messaging = null;
+        this._currentToken = null;
+        this._enabled = false;
+        this._enablePromise = null;
+        this._foregroundMessageUnsubscribe = null;
+        this._swRegistration = null;
+        this._projectRegisteredToSW = false;
+        this._visibilityHandler = null;
+        this._deviceIdCache = null;  // IndexedDB 조회 결과 메모리 캐시 (세션 단위)
+    }
+
+    /**
+     * 저장된 pending roomId 를 소비한다.
+     *
+     * @param {string} [projectId] - 소비할 projectId. 지정 시 해당 projectId 로 저장된 pending 만 소비.
+     *                               미지정 시 레거시 전역 key 만 조회 (구버전 호환).
+     * @returns {Promise<string|null>}
+     */
+    static async consumePendingRoom(projectId) {
+        return consumePendingRoomFromIndexedDB(projectId);
+    }
+
+    /**
+     * 현재 브라우저의 푸시 권한 상태를 조회한다.
+     *
+     * <p>{@link PushManager} 인스턴스가 없어도 (즉, {@code enablePushNotifications()} 호출 전) 호출 가능하다.
+     * 호출자가 enable 호출 <b>전에</b> UI 분기를 결정할 때 사용한다.</p>
+     *
+     * <p>반환값:</p>
+     * <ul>
+     *   <li>{@code 'granted'} — 이미 허용. enable 호출 시 권한창 안 뜨고 토큰 발급으로 즉시 진행.</li>
+     *   <li>{@code 'default'} — 아직 묻지 않음. enable 호출 시 권한창 표시.</li>
+     *   <li>{@code 'denied'} — 거부됨. enable 호출 시 즉시 PERMISSION_DENIED 로 실패 (브라우저 정책상 권한창 안 뜸).</li>
+     *   <li>{@code 'unsupported'} — Notification 또는 Service Worker 미지원 환경 (Safari iOS 등).</li>
+     * </ul>
+     *
+     * @returns {'granted'|'denied'|'default'|'unsupported'}
+     */
+    static getPermissionState() {
+        if (typeof window === 'undefined' || typeof Notification === 'undefined') {
+            return 'unsupported';
+        }
+        if (typeof navigator === 'undefined' || !('serviceWorker' in navigator)) {
+            return 'unsupported';
+        }
+        return Notification.permission; // 'granted' | 'denied' | 'default'
+    }
+
+    /**
+     * 푸시 알림 활성화.
+     * Firebase 초기화 → 서비스 워커 등록 → 권한 요청 → 토큰 획득 → 서버 등록.
+     *
+     * <p>토큰은 SDK 내부에서만 관리되므로 호출자는 반환값을 받을 필요가 없습니다.
+     * 상태 확인은 {@link #isEnabled} 로, 에러는 throw 로 전달됩니다.</p>
+     *
+     * @returns {Promise<void>}
+     * @throws {Error} 브라우저 미지원, 권한 거부, Firebase 미설치 등
+     */
+    async enable() {
+        if (this._enabled) {
+            this.logger.debug('푸시 알림이 이미 활성화되어 있습니다.');
+            return;
+        }
+
+        if (this._enablePromise) {
+            this.logger.debug('푸시 알림 활성화가 이미 진행 중입니다.');
+            return this._enablePromise;
+        }
+
+        this._enablePromise = this._enableInternal();
+
+        try {
+            return await this._enablePromise;
+        } finally {
+            this._enablePromise = null;
+        }
+    }
+
+    async _enableInternal() {
+        // 브라우저 환경 체크
+        if (typeof window === 'undefined' || !('Notification' in window)) {
+            throw new PushError(
+                PushErrorCode.UNSUPPORTED_BROWSER,
+                '푸시 알림은 브라우저 환경에서만 사용 가능합니다'
+            );
+        }
+
+        if (!('serviceWorker' in navigator)) {
+            throw new PushError(
+                PushErrorCode.UNSUPPORTED_BROWSER,
+                '이 브라우저는 서비스 워커를 지원하지 않습니다'
+            );
+        }
+
+        // 권한이 이미 거부된 상태면 requestPermission() 은 즉시 'denied' 를 반환하고
+        // 권한창은 뜨지 않는다. 명확한 분류 에러로 즉시 throw 하여 호출자가
+        // "브라우저 설정에서 풀어달라" 가이드를 띄울 수 있도록 한다.
+        if (Notification.permission === 'denied') {
+            throw new PushError(
+                PushErrorCode.PERMISSION_DENIED,
+                '알림 권한이 이미 거부되어 있습니다. 브라우저 사이트 설정에서 허용해주세요.'
+            );
+        }
+
+        // Firebase 동적 로드
+        let firebaseApp, firebaseMessaging;
+        try {
+            firebaseApp = await import('firebase/app');
+            firebaseMessaging = await import('firebase/messaging');
+        } catch (e) {
+            throw new PushError(
+                PushErrorCode.FIREBASE_NOT_INSTALLED,
+                'firebase 패키지가 설치되지 않았습니다. npm install firebase 를 실행하세요.',
+                e
+            );
+        }
+
+        // Firebase 초기화 (이미 초기화된 경우 기존 앱 사용)
+        // 고객 앱의 기존 Firebase와 충돌 방지 — named app으로 분리
+        let app;
+        try {
+            app = firebaseApp.getApp('talkflow');
+        } catch {
+            app = firebaseApp.initializeApp(this.firebaseConfig, 'talkflow');
+        }
+
+        // 서비스 워커 등록
+        const registration = await this._registerServiceWorker();
+
+        // 알림 권한 요청
+        // - 'default' 상태: 브라우저가 권한창을 표시하고 사용자 응답을 대기
+        // - 'granted' 상태: 즉시 'granted' 반환 (창 안 뜸)
+        // - 'denied' 상태: 위 가드에서 이미 throw 했으므로 여기 도달 불가
+        const permission = await Notification.requestPermission();
+        if (permission !== 'granted') {
+            throw new PushError(
+                PushErrorCode.PERMISSION_DENIED,
+                '알림 권한이 거부되었습니다. 브라우저 설정에서 허용해주세요.'
+            );
+        }
+
+        // FCM 토큰 획득
+        this._messaging = firebaseMessaging.getMessaging(app);
+
+        const tokenOptions = { serviceWorkerRegistration: registration };
+        if (this.vapidKey) {
+            tokenOptions.vapidKey = this.vapidKey;
+        }
+
+        try {
+            this._currentToken = await firebaseMessaging.getToken(this._messaging, tokenOptions);
+        } catch (e) {
+            throw new PushError(
+                PushErrorCode.TOKEN_FAILED,
+                'FCM 토큰 획득 중 오류 발생: ' + (e?.message || e),
+                e
+            );
+        }
+
+        if (!this._currentToken) {
+            throw new PushError(
+                PushErrorCode.TOKEN_FAILED,
+                'FCM 토큰 획득 실패 (응답이 비어있음)'
+            );
+        }
+
+        // 서버에 토큰 등록
+        await this._registerTokenToServer(this._currentToken);
+
+        // 포그라운드 메시지 수신 핸들러
+        if (this._foregroundMessageUnsubscribe) {
+            this._foregroundMessageUnsubscribe();
+        }
+
+        this._foregroundMessageUnsubscribe = firebaseMessaging.onMessage(this._messaging, (payload) => {
+            this.logger.debug('포그라운드 푸시 수신:', payload);
+            this._onForegroundMessage(payload);
+        });
+
+        // SW 등록 객체를 보관 — 이후 projectId 재등록에 사용한다.
+        this._swRegistration = registration;
+
+        // SW 에 projectId 등록.
+        // 멀티테넌트 환경에서 notificationclick 시 SW 가 "어느 창이 어느 project 인지"를 알아야
+        // 다른 프로젝트 창에 NAVIGATE_TO_ROOM 을 보내지 않는다.
+        await this._registerProjectToSW();
+
+        // SW terminate 로 Map 이 소실될 수 있으므로 visibility 복귀 시 재등록.
+        this._installVisibilityReRegister();
+
+        // SW 업데이트 체크 (CDN handler 갱신 전파)
+        try {
+            await registration.update();
+        } catch (e) {
+            this.logger.debug('SW 업데이트 체크 실패 (무시):', e.message);
+        }
+
+        // SW 버전 감지 — 구버전 경고 용도로만 사용.
+        // 이 값으로 서버/SDK 가 기능 분기(image 지원 여부 등)를 판단하면 안 된다.
+        const swVersion = await this._getSWVersion(registration);
+        if (!swVersion) {
+            this.logger.warn(
+                '[TalkFlow] 서비스 워커가 구버전(v1)입니다. ' +
+                '이미지 미리보기 등 리치 알림 기능을 사용하려면 firebase-messaging-sw.js 를 ' +
+                'v2 로 업데이트하세요. 가이드: https://docs.talkflow.ai/push/sw-upgrade'
+            );
+        } else {
+            this.logger.debug('SW 버전:', swVersion);
+        }
+
+        this._enabled = true;
+        this.logger.info('푸시 알림 활성화 완료');
+    }
+
+    /**
+     * 서비스 워커 등록.
+     * updateViaCache: 'none' 으로 등록하여 registration.update() 시
+     * importScripts 로 로드하는 CDN handler 까지 캐시 없이 갱신되도록 한다.
+     * https://developer.mozilla.org/en-US/docs/Web/API/ServiceWorkerContainer/register
+     * @private
+     */
+    async _registerServiceWorker() {
+        try {
+            const registration = await navigator.serviceWorker.register(
+                this.serviceWorkerPath,
+                { updateViaCache: 'none' }
+            );
+            this.logger.debug('서비스 워커 등록 완료:', this.serviceWorkerPath);
+            return registration;
+        } catch (error) {
+            throw new PushError(
+                PushErrorCode.SW_REGISTER_FAILED,
+                `서비스 워커 등록 실패: ${this.serviceWorkerPath}\n` +
+                '프로젝트 public 폴더에 firebase-messaging-sw.js 파일을 배치하세요.',
+                error
+            );
+        }
+    }
+
+    /**
+     * 서버에 디바이스 토큰 등록
+     * @private
+     */
+    async _registerTokenToServer(token) {
+        try {
+            const deviceId = await this._getDeviceId();
+            await this.apiClient.post('/api/v1/push/devices', {
+                deviceToken: token,
+                deviceType: 'WEB',
+                deviceId
+            });
+            this.logger.info('디바이스 토큰 서버 등록 완료');
+        } catch (error) {
+            this.logger.error('디바이스 토큰 서버 등록 실패:', error);
+            // PushError 가 아닌 경우 (네트워크 / 서버 5xx 등) SERVER_REGISTER_FAILED 로 wrap.
+            // 이미 PushError 면 그대로 전파 (분류 보존).
+            if (error instanceof PushError) {
+                throw error;
+            }
+            throw new PushError(
+                PushErrorCode.SERVER_REGISTER_FAILED,
+                '디바이스 토큰 서버 등록 실패: ' + (error?.message || error),
+                error
+            );
+        }
+    }
+
+    /**
+     * 브라우저 고유 식별자 조회/생성 (IndexedDB 기반).
+     *
+     * <p>순서:</p>
+     * <ol>
+     *   <li>IndexedDB 에서 기존 deviceId 조회</li>
+     *   <li>없으면 localStorage 에 있는 legacy 값 있는지 확인 (기존 SDK 버전 설치 이력)</li>
+     *   <li>legacy 있으면 IndexedDB 로 이관 + localStorage 키 제거</li>
+     *   <li>둘 다 없으면 신규 생성 + IndexedDB 저장</li>
+     * </ol>
+     *
+     * <p>IndexedDB 사용 불가 환경 (private mode 등) 에서는 in-memory fallback — 세션 단위
+     * 새 deviceId 사용. 완벽한 영속성은 없지만 기본 기능은 유지.</p>
+     *
+     * @private
+     * @returns {Promise<string>}
+     */
+    async _getDeviceId() {
+        // 메모리 캐시 — 동일 세션 내 반복 호출 방지.
+        if (this._deviceIdCache) {
+            return this._deviceIdCache;
+        }
+
+        try {
+            // 1) IndexedDB 에서 조회
+            let deviceId = await readDeviceIdFromIndexedDb();
+
+            // 2) 없으면 localStorage legacy 값 확인 + 이관
+            if (!deviceId && typeof localStorage !== 'undefined') {
+                const legacy = localStorage.getItem(LEGACY_LOCAL_STORAGE_DEVICE_ID_KEY);
+                if (legacy) {
+                    deviceId = legacy;
+                    // IDB 저장 성공 + read-back 검증 둘 다 통과한 경우에만 localStorage 정리.
+                    // 실패하거나 검증 miss 면 legacy 값 보존해 다음 방문에 재시도 가능.
+                    const saved = await writeDeviceIdToIndexedDb(deviceId);
+                    if (saved) {
+                        const readBack = await readDeviceIdFromIndexedDb();
+                        if (readBack === deviceId) {
+                            try {
+                                localStorage.removeItem(LEGACY_LOCAL_STORAGE_DEVICE_ID_KEY);
+                                this.logger.debug('deviceId migrated from localStorage to IndexedDB');
+                            } catch (_) { /* quota/private mode 예외 무시 — legacy 남아도 다음에 재이관 시도 */ }
+                        } else {
+                            // 저장 tx 는 complete 됐는데 read-back 은 다르게 나오는 극단 케이스.
+                            // localStorage 보존 — 다음 방문에 재시도.
+                            this.logger.warn('deviceId IDB read-back 불일치, localStorage 보존');
+                        }
+                    } else {
+                        this.logger.warn('deviceId IDB 저장 실패 (private mode / quota 등), localStorage 보존');
+                    }
+                }
+            }
+
+            // 3) 그래도 없으면 신규 생성 + 저장 시도.
+            //    저장 실패해도 in-memory 캐시로 세션 단위 유효하므로 푸시 등록은 진행됨.
+            //    (영속화 실패는 다음 방문에 새 deviceId 생성 → 서버 쪽 device 매핑 갱신은 불가피)
+            if (!deviceId) {
+                deviceId = generateDeviceId();
+                const saved = await writeDeviceIdToIndexedDb(deviceId);
+                if (!saved) {
+                    this.logger.warn('신규 deviceId IDB 저장 실패, 이번 세션만 유효');
+                }
+            }
+
+            this._deviceIdCache = deviceId;
+            return deviceId;
+        } catch (error) {
+            // IndexedDB 장애 (open / read / transaction throw 등) 시 fallback.
+            // IDB 가 현재 실패하므로 localStorage 를 삭제하지 않는다 — 다음 방문에 IDB 회복되면
+            // try 블록의 이관 경로가 다시 시도됨.
+            this.logger.warn('IndexedDB deviceId 조회/저장 실패, fallback:', error);
+            if (!this._deviceIdCache) {
+                // 1) localStorage legacy 우선 확인 — 기존 사용자 device 연속성 유지.
+                //    IDB 가 실패해도 localStorage 가 읽히면 기존 deviceId 재사용.
+                let fallbackId = null;
+                if (typeof localStorage !== 'undefined') {
+                    try {
+                        fallbackId = localStorage.getItem(LEGACY_LOCAL_STORAGE_DEVICE_ID_KEY);
+                    } catch (_) { /* private mode 등 — localStorage 도 접근 불가 */ }
+                }
+                // 2) legacy 도 없으면 신규 생성 (in-memory 단일 세션).
+                this._deviceIdCache = fallbackId || generateDeviceId();
+            }
+            return this._deviceIdCache;
+        }
+    }
+
+    /**
+     * 포그라운드 메시지 수신 콜백.
+     * TalkFlowClient에서 오버라이드하여 activeRoom 기반 suppress 처리.
+     * @param {Object} payload - FCM 메시지 페이로드
+     */
+    _onForegroundMessage(payload) {
+        // TalkFlowClient에서 오버라이드
+    }
+
+    /**
+     * 서비스 워커가 cold start 시 저장한 pending roomId 를 소비하고 삭제한다.
+     * 앱 부팅 시 호출하여 알림 클릭으로 열려야 할 방으로 라우팅할 때 사용한다.
+     *
+     * <p>내부 projectId 가 설정되어 있으면 해당 프로젝트의 pending 만 소비한다.
+     * 다른 프로젝트의 pending 은 건드리지 않아 그 프로젝트가 나중에 꺼낼 수 있다.</p>
+     *
+     * @returns {Promise<string|null>} pending roomId 또는 null
+     */
+    async consumePendingRoom() {
+        return PushManager.consumePendingRoom(this.projectId);
+    }
+
+    /**
+     * 현재 푸시 상태를 정리한다.
+     * 로그아웃 또는 다른 사용자로 전환할 때 foreground listener 와 활성화 상태를 초기화한다.
+     * SW 에 등록된 projectId 도 해제한다.
+     */
+    reset() {
+        if (this._foregroundMessageUnsubscribe) {
+            try {
+                this._foregroundMessageUnsubscribe();
+            } catch (error) {
+                this.logger.debug('포그라운드 푸시 리스너 해제 실패 (무시):', error?.message || error);
+            }
+        }
+
+        // visibility 재등록 핸들러 제거 — reset 이후 새 enable 전까지 자동 재등록이 일어나지 않도록.
+        this._uninstallVisibilityReRegister();
+
+        // SW 의 projectId 등록도 해제 (best-effort).
+        this._unregisterProjectFromSW();
+
+        this._foregroundMessageUnsubscribe = null;
+        this._enablePromise = null;
+        this._messaging = null;
+        this._currentToken = null;
+        this._enabled = false;
+        this._swRegistration = null;
+        this._projectRegisteredToSW = false;
+    }
+
+    /**
+     * 활성 SW 에 현재 projectId 를 등록한다.
+     * SW 는 Client.id → projectId Map 을 유지해 notificationclick 시 올바른 창을 선택한다.
+     * @private
+     */
+    async _registerProjectToSW() {
+        if (!this.projectId) {
+            return;
+        }
+        try {
+            const readyRegistration = await navigator.serviceWorker.ready;
+            const sw =
+                readyRegistration.active ||
+                (this._swRegistration && this._swRegistration.active);
+            if (!sw) {
+                this.logger.debug('SW active worker 없음 — projectId 등록 스킵');
+                return;
+            }
+            sw.postMessage({ type: 'TALKFLOW_REGISTER_PROJECT', projectId: this.projectId });
+            this._projectRegisteredToSW = true;
+        } catch (error) {
+            this.logger.debug('SW projectId 등록 실패 (무시):', error?.message || error);
+        }
+    }
+
+    /**
+     * SW 에 등록된 projectId 해제 (best-effort).
+     * reset 시 호출되며, navigator.serviceWorker 접근이 실패해도 예외를 삼킨다.
+     * @private
+     */
+    _unregisterProjectFromSW() {
+        if (!this._projectRegisteredToSW) {
+            return;
+        }
+        try {
+            if (typeof navigator === 'undefined' || !navigator.serviceWorker) {
+                return;
+            }
+            const controller = navigator.serviceWorker.controller;
+            if (!controller) {
+                return;
+            }
+            controller.postMessage({ type: 'TALKFLOW_UNREGISTER_PROJECT' });
+        } catch (error) {
+            this.logger.debug('SW projectId 해제 실패 (무시):', error?.message || error);
+        }
+    }
+
+    /**
+     * visibility 복귀 시 SW 에 projectId 를 재등록한다.
+     * SW 는 idle 시 terminate 되며 이때 clientProjectMap 이 소실되므로,
+     * 창이 다시 visible 상태가 될 때 방어적으로 재등록한다.
+     * @private
+     */
+    _installVisibilityReRegister() {
+        if (typeof document === 'undefined' || this._visibilityHandler) {
+            return;
+        }
+        this._visibilityHandler = () => {
+            if (document.visibilityState === 'visible' && this._enabled && this.projectId) {
+                // best-effort — 재등록 실패는 다음 visibility 이벤트에 다시 시도된다.
+                this._registerProjectToSW().catch(() => {});
+            }
+        };
+        document.addEventListener('visibilitychange', this._visibilityHandler);
+    }
+
+    /**
+     * @private
+     */
+    _uninstallVisibilityReRegister() {
+        if (typeof document === 'undefined' || !this._visibilityHandler) {
+            return;
+        }
+        try {
+            document.removeEventListener('visibilitychange', this._visibilityHandler);
+        } catch (error) {
+            // 무시
+        }
+        this._visibilityHandler = null;
+    }
+
+    // noinspection JSUnusedGlobalSymbols
+    /**
+     * 현재 FCM 토큰
+     * @returns {string|null}
+     */
+    getToken() {
+        return this._currentToken;
+    }
+
+    /**
+     * 푸시 활성화 여부
+     * @returns {boolean}
+     */
+    isEnabled() {
+        return this._enabled;
+    }
+
+    /**
+     * 현재 사용자의 등록된 디바이스 목록 조회 (푸시 on/off UI 용).
+     *
+     * <p>서버가 내려주는 필드: {@code deviceId}, {@code deviceType}, {@code enabled}, {@code createdAt}.
+     * {@code deviceToken} 은 보안상 응답에 포함되지 않는다.</p>
+     *
+     * @returns {Promise<Array<{deviceId: string, deviceType: string, enabled: boolean, createdAt: string}>>}
+     */
+    async getMyDevices() {
+        const response = await this.apiClient.get('/api/v1/push/devices/me');
+        return response && typeof response === 'object' && 'data' in response
+            ? response.data
+            : response;
+    }
+
+    /**
+     * 특정 디바이스의 푸시 수신 여부 토글.
+     *
+     * <p>본인 소유 디바이스만 수정 가능 (서버가 {@code (projectId, userId, deviceId)} 조합으로 검증).
+     * 소유자 불일치 또는 미등록 디바이스 시 서버가 404 로 응답 → 호출자에 throw.</p>
+     *
+     * @param {string} deviceId - 대상 디바이스 ID (현재 디바이스면 {@link #setCurrentDeviceEnabled} 사용 권장)
+     * @param {boolean} enabled - true 면 수신, false 면 수신 중단
+     * @returns {Promise<void>}
+     */
+    async setDeviceEnabled(deviceId, enabled) {
+        await this.apiClient.patch('/api/v1/push/devices/me/enabled', {
+            deviceId,
+            enabled
+        });
+        this.logger.info(`디바이스 푸시 enabled=${enabled}: deviceId=${deviceId}`);
+    }
+
+    /**
+     * 현재 디바이스의 푸시 수신 여부 토글 (편의 메서드).
+     *
+     * <p>SDK 가 관리하는 현재 브라우저의 deviceId 로 {@link #setDeviceEnabled} 를 호출한다.
+     * {@link #enable} 이 선행되지 않아도 호출 가능 — 서버에 디바이스가 등록돼 있으면 동작.</p>
+     *
+     * @param {boolean} enabled
+     * @returns {Promise<void>}
+     */
+    async setCurrentDeviceEnabled(enabled) {
+        const deviceId = await this._getDeviceId();
+        await this.setDeviceEnabled(deviceId, enabled);
+    }
+
+    /**
+     * 등록된 서비스 워커의 TalkFlow 버전을 조회.
+     *
+     * navigator.serviceWorker.ready 를 기다려 active worker 가 보장된 상태에서,
+     * readyRegistration → register() 반환 registration 양쪽의
+     * waiting → installing → active 순으로 SW 를 찾는다.
+     * v1→v2 교체 직후 새 SW 가 waiting/installing 상태에 있을 때
+     * 구 active(v1) 대신 신규(v2)를 우선 감지하여 거짓 경고를 방지한다.
+     * 같은 scope 에서는 두 객체가 동일 참조이지만, 타이밍 차이에 대한 방어 코드.
+     *
+     * v1(구버전) SW 는 메시지 핸들러가 없으므로 2초 timeout 후 null 반환.
+     *
+     * @param {ServiceWorkerRegistration} registration - register() 가 반환한 등록 객체
+     * @returns {Promise<string|null>} 버전 문자열 또는 null (구버전/미응답)
+     * @private
+     */
+    async _getSWVersion(registration) {
+        try {
+            const readyRegistration = await navigator.serviceWorker.ready;
+
+            const sw =
+                readyRegistration.waiting ||
+                readyRegistration.installing ||
+                readyRegistration.active ||
+                registration.waiting ||
+                registration.installing ||
+                registration.active;
+            if (!sw) return null;
+
+            return new Promise((resolve) => {
+                const timeout = setTimeout(() => resolve(null), 2000);
+
+                const channel = new MessageChannel();
+                channel.port1.onmessage = (event) => {
+                    clearTimeout(timeout);
+                    resolve(event.data?.version || null);
+                };
+
+                try {
+                    sw.postMessage({ type: 'TALKFLOW_SW_VERSION' }, [channel.port2]);
+                } catch (e) {
+                    clearTimeout(timeout);
+                    resolve(null);
+                }
+            });
+        } catch {
+            return null;
+        }
+    }
+
+    /**
+     * 로그 레벨 설정
+     * @param {number} level
+     */
+    setLogLevel(level) {
+        this.logger.setLevel(level);
+    }
+}
+
+export default PushManager;