@vibexnpm/talkx 2.3.1

package/package.json

@@ -0,0 +1,51 @@
+{
+    "name": "@vibexnpm/talkx",
+    "version": "2.3.1",
+    "type": "module",
+    "description": "TalkFlow SDK - Chat & WebRTC unified client",
+    "main": "dist/talkflow-sdk.umd.js",
+    "module": "dist/talkflow-sdk.esm.js",
+    "browser": "dist/talkflow-sdk.standalone.js",
+    "types": "types/index.d.ts",
+    "files": [
+        "dist",
+        "src",
+        "types"
+    ],
+    "scripts": {
+        "build": "rollup -c && npm run build:types",
+        "build:types": "copy types\\index.d.ts dist\\index.d.ts",
+        "dev": "rollup -c -w",
+        "lint": "eslint src/",
+        "test": "jest"
+    },
+    "repository": {
+        "type": "git",
+        "url": "https://github.com/talkflow/talkflow-sdk.git"
+    },
+    "keywords": [
+        "talkflow",
+        "chat",
+        "webrtc",
+        "websocket",
+        "stomp",
+        "realtime"
+    ],
+    "author": "vibexnpm",
+    "license": "MIT",
+    "dependencies": {
+        "@stomp/stompjs": "^7.0.0",
+        "firebase": "^11.8.1",
+        "sockjs-client": "^1.6.0"
+    },
+    "devDependencies": {
+        "@babel/core": "^7.24.0",
+        "@babel/preset-env": "^7.24.0",
+        "@rollup/plugin-babel": "^6.0.4",
+        "@rollup/plugin-commonjs": "^29.0.0",
+        "@rollup/plugin-node-resolve": "^16.0.3",
+        "@rollup/plugin-replace": "^6.0.3",
+        "@rollup/plugin-terser": "^0.4.4",
+        "rollup": "^4.12.0"
+    }
+}

package/src/TalkFlowClient.js

@@ -0,0 +1,481 @@
+/**
+ * TalkFlowClient
+ * 채팅 + WebRTC 통합 클라이언트
+ */
+
+import EventEmitter from './utils/EventEmitter.js';
+import Logger from './utils/Logger.js';
+import ApiClient from './utils/ApiClient.js';
+import { extractUserIdFromJWT } from './utils/jwtUtils.js';
+import { ConnectionState, ErrorTypes, DefaultConfig, LogLevel, Environment, getServerUrl } from './constants.js';
+import { initializeSubClients, applySessionMethods } from './talkflow/session.js';
+import { setupEventForwarding } from './talkflow/eventForwarding.js';
+import { applyDelegatedMethods } from './talkflow/delegates.js';
+
+// noinspection JSUnresolvedReference
+class TalkFlowClient extends EventEmitter {
+    /**
+     * TalkFlowClient 생성
+     *
+     * <p>JWT 토큰은 고객사 backend 에서 발급받아서 SDK 에 전달해야 합니다.
+     * 브라우저에서 직접 JWT 를 발급하는 기능은 제공하지 않습니다 (보안상).
+     * 자세한 내용은 README "프로덕션 인증 플로우" 섹션 참고.</p>
+     *
+     * @param {Object} options - 설정 옵션
+     * @param {string} options.apiKey - Client API 키 (필수, 브라우저 노출 안전)
+     * @param {string} options.projectId - 프로젝트 ID (필수)
+     * @param {string} options.jwtToken - JWT 토큰 (필수, 고객사 backend 에서 발급)
+     * @param {string} [options.env='production'] - 환경 ('development' | 'staging' | 'production')
+     * @param {string} [options.serverUrl] - 서버 URL (직접 지정 시 env 무시)
+     * @param {boolean} [options.useSockJS=true] - SockJS 사용 여부
+     * @param {number} [options.reconnectDelay=5000] - 재연결 지연 (ms)
+     * @param {number} [options.maxReconnectAttempts=10] - 최대 재연결 시도
+     * @param {Object[]} [options.iceServers] - ICE 서버 설정
+     * @param {boolean} [options.autoSubscribeRoomList=true] - connect() 시 채팅방 리스트 자동 구독 여부 (카톡 스타일)
+     * @param {number} [options.logLevel=LogLevel.WARN] - 로그 레벨
+     *
+     * @example
+     * // 1단계: 고객사 backend 가 talkflow JWT 를 발급받음 (Server API Key 사용)
+     * //   POST https://chat.apiorbit.net/api/v1/users/auth
+     * //   Headers: X-API-KEY: <SERVER_KEY>, X-PROJECT-ID: <project-id>
+     * //   Body: { userId: 'user-123', nickname: '홍길동' }
+     * //   Response: { accessToken, refreshToken }
+     *
+     * // 2단계: 고객사 backend 가 최종 사용자 브라우저에 JWT 전달 (자사 API 응답 등)
+     *
+     * // 3단계: 브라우저에서 SDK 초기화
+     * const client = new TalkFlowClient({
+     *     apiKey: 'CLIENT_KEY',          // 브라우저에 노출되는 Client Key
+     *     projectId: 'your-project-id',
+     *     jwtToken: receivedJwt,          // 고객사 backend 로부터 받은 JWT
+     *     env: 'production'
+     * });
+     *
+     * await client.connect();
+     */
+    constructor(options) {
+        super();
+
+        // 필수 옵션 검증
+        this._validateOptions(options);
+
+        // 환경에 따른 서버 URL 결정
+        // serverUrl이 직접 지정되면 우선 사용, 아니면 env에 따라 자동 결정
+        const env = options.env || DefaultConfig.environment;
+        const serverUrl = (options.serverUrl || getServerUrl(env)).replace(/\/$/, '');
+
+        this.options = {
+            serverUrl,
+            env,
+            apiKey: options.apiKey,
+            projectId: options.projectId,
+            jwtToken: options.jwtToken || null,
+            useSockJS: options.useSockJS !== false,
+            reconnectDelay: options.reconnectDelay || DefaultConfig.reconnectDelay,
+            maxReconnectAttempts: options.maxReconnectAttempts || DefaultConfig.maxReconnectAttempts,
+            iceServers: options.iceServers || DefaultConfig.iceServers,
+            // connect() 시 채팅방 리스트 자동 구독 여부 (카톡 스타일).
+            // 기본 true — 앱 어디서든 리스트 이벤트를 놓치지 않음 (배지/알림 등).
+            // false 로 설정 시 수동으로 client.chat.subscribeRoomList() 호출 필요.
+            autoSubscribeRoomList: options.autoSubscribeRoomList !== false,
+            logLevel: options.logLevel !== undefined ? options.logLevel : LogLevel.WARN
+        };
+
+        // 로거 초기화
+        this.logger = new Logger(this.options.logLevel, 'TalkFlowClient');
+
+        // 상태
+        this._initialized = false;
+        this._state = ConnectionState.DISCONNECTED;
+
+        // public 읽기 전용 surface 의 backing field.
+        // types/index.d.ts 는 chat/webrtc/pushManager/userId 를 readonly 로 선언 —
+        // 외부 계약(readonly) 과 내부 재할당 필요성을 동시에 만족시키기 위해 private
+        // backing field 에 저장하고 동명 getter 로 공개한다.
+        this._userId = null;
+
+        // JWT가 있으면 userId 추출
+        if (this.options.jwtToken) {
+            this._userId = extractUserIdFromJWT(this.options.jwtToken);
+        }
+
+        // API 클라이언트 초기화 (JWT 없이도 동작)
+        this.apiClient = new ApiClient({
+            baseUrl: this.options.serverUrl,
+            apiKey: this.options.apiKey,
+            projectId: this.options.projectId,
+            jwtToken: this.options.jwtToken,
+            logLevel: this.options.logLevel
+        });
+
+        // ConnectionManager, ChatClient, WebRTCClient는 지연 초기화
+        this.connectionManager = null;
+        this._chat = null;
+        this._webrtc = null;
+        this._pushManager = null;
+        this._pushEnablePromise = null;
+
+        // JWT가 있으면 즉시 서브 클라이언트 초기화
+        if (this.options.jwtToken && this._userId) {
+            this._initializeSubClients();
+        }
+
+        this._initialized = true;
+        this.logger.info('TalkFlowClient initialized', {
+            userId: this._userId,
+            hasToken: !!this.options.jwtToken
+        });
+    }
+
+    // ==================== Public readonly surface (getter) ====================
+
+    /** @returns {ChatClient|null} */
+    get chat() { return this._chat; }
+
+    /** @returns {WebRTCClient|null} */
+    get webrtc() { return this._webrtc; }
+
+    /** @returns {PushManager|null} */
+    get pushManager() { return this._pushManager; }
+
+    /** @returns {string|null} */
+    get userId() { return this._userId; }
+
+    /**
+     * 옵션 검증
+     * @private
+     * @param {Object} options - 설정 옵션
+     * @throws {Error} 필수 옵션이 없는 경우
+     */
+    _validateOptions(options) {
+        if (!options) {
+            throw new Error('Options are required');
+        }
+        if (!options.apiKey) {
+            throw new Error('apiKey is required');
+        }
+        if (!options.projectId) {
+            throw new Error('projectId is required');
+        }
+
+        // Server Key (sk-) 브라우저 사용 경고
+        // - development: 경고만 (registerUser 빠른 테스트 허용)
+        // - staging/production: 경고 + 강력 안내
+        if (options.apiKey.startsWith('sk-')) {
+            const env = options.env || 'production';
+            if (env === 'development') {
+                console.warn(
+                    '⚠️ [TalkFlow] Server Key (sk-) 를 개발 모드에서 사용 중입니다. ' +
+                    '프로덕션 배포 전에 반드시 Client Key (ck-) 로 교체하세요.'
+                );
+            } else {
+                console.error(
+                    '🚨 [TalkFlow] Server Key (sk-) 가 비개발 환경 (' + env + ') 에서 감지되었습니다. ' +
+                    '보안 위험: Server Key 를 브라우저에 포함하면 공격자가 임의 사용자로 JWT 를 발급받을 수 있습니다. ' +
+                    '반드시 Client Key (ck-) 로 교체하세요. ' +
+                    '서버에서도 프로덕션 모드에서 Server Key 의 브라우저 호출을 차단합니다.'
+                );
+            }
+        }
+    }
+
+    /**
+     * 서브 클라이언트 초기화
+     * @private
+     */
+    _initializeSubClients() {
+        initializeSubClients(this);
+    }
+
+    /**
+     * 이벤트 포워딩 설정
+     * @private
+     */
+    _setupEventForwarding() {
+        setupEventForwarding(this);
+    }
+
+    /**
+     * 연결 상태 확인
+     * @returns {boolean}
+     */
+    isConnected() {
+        return this.connectionManager ? this.connectionManager.isConnected() : false;
+    }
+
+    /**
+     * 현재 연결 상태
+     * @returns {string}
+     */
+    getState() {
+        return this._state;
+    }
+
+    /**
+     * 토큰 보유 여부
+     * @returns {boolean}
+     */
+    hasToken() {
+        return !!this.options.jwtToken;
+    }
+
+    // ==================== 사용자 API ====================
+
+    /**
+     * 사용자 인증 (등록/로그인).
+     * 인증 성공 시 반환된 JWT 토큰을 자동으로 설정합니다.
+     *
+     * <h3>⚠️ Server API Key 전용</h3>
+     * <p>이 메서드는 JWT 를 발급하는 엔드포인트 ({@code POST /api/v1/users/auth}) 를 호출합니다.
+     * <strong>프로덕션 환경에서는 Client API Key 로 이 메서드를 호출하면 서버가 403 을 반환합니다.</strong></p>
+     *
+     * <ul>
+     *   <li><strong>개발/프로토타입</strong>: Server Key 로 SDK 를 초기화한 뒤 이 메서드를 사용하면 빠르게 테스트 가능</li>
+     *   <li><strong>프로덕션</strong>: 고객사 backend 에서 Server Key 로 직접 {@code POST /api/v1/users/auth} 를 호출 →
+     *       JWT 를 받아 SDK 에 {@code setToken(jwt)} 으로 전달. 이 메서드를 브라우저에서 쓰지 마세요.</li>
+     * </ul>
+     *
+     * <p>자세한 내용은 README 의 "프로덕션 인증 플로우" 섹션 참고.</p>
+     *
+     * @param {Object} userData
+     * @param {string} userData.userId - 사용자 ID (필수, 고객사 회원 ID)
+     * @param {string} userData.nickname - 닉네임 (필수, max 100자)
+     * @param {string} [userData.profileImageUrl] - 프로필 이미지 URL (max 500자)
+     * @param {Object} [userData.metadata] - 추가 메타데이터
+     * @returns {Promise<Object>} 인증 결과 (토큰 포함)
+     *
+     * @example
+     * // 개발 환경 — Server Key 로 빠른 테스트
+     * const client = new TalkFlowClient({
+     *     apiKey: 'SERVER_KEY',
+     *     projectId: 'your-project-id',
+     *     env: 'development'
+     * });
+     * await client.registerUser({ userId: 'user-123', nickname: '홍길동' });
+     * await client.connect();
+     */
+    async registerUser(userData) {
+        // 다국어: navigator.language 자동 시드 — 호출자가 preferredLanguage 를 명시하지 않은 경우에만.
+        // 서버 /users/auth 는 seed-if-absent (기존 값 비클로버) 라 매 인증마다 덮어쓰지 않아 안전.
+        const payload = { ...userData };
+        if (payload.preferredLanguage === undefined) {
+            const detected = TalkFlowClient.detectBrowserLanguage();
+            if (detected) {
+                payload.preferredLanguage = detected;
+            }
+        }
+
+        const response = await this.apiClient.post('/api/v1/users/auth', payload);
+
+        if (response.data && response.data.accessToken) {
+            await this.setToken(response.data.accessToken);
+            this.logger.info('User authenticated, token auto-set');
+        }
+
+        return response;
+    }
+
+    /**
+     * 사용자 정보 수정
+     * @param {Object} userData
+     * @param {string} [userData.nickname] - 닉네임 (max 100자)
+     * @param {string} [userData.profileImageUrl] - 프로필 이미지 URL (max 500자)
+     * @param {Object} [userData.metadata] - 메타데이터 (전체 교체)
+     * @param {string|null} [userData.preferredLanguage] - 기본 선호 언어 (BCP-47 / 'OFF'(원문) / null). 다국어.
+     * @returns {Promise<Object>}
+     */
+    async updateMyInfo(userData) {
+        this._checkToken();
+        return this.apiClient.put('/api/v1/users/update', userData);
+    }
+
+    /**
+     * 내 기본 선호 언어 설정 (전 방 공통, 다국어). 명시 변경 — 방별 오버라이드는 {@link #setMyRoomLanguage}.
+     * @param {string|null} language - BCP-47 코드(예 'ko','en') / 'OFF'(원문) / null·''(미설정)
+     * @returns {Promise<Object>}
+     */
+    async setPreferredLanguage(language) {
+        return this.updateMyInfo({ preferredLanguage: language });
+    }
+
+    /**
+     * 브라우저 locale 감지 — {@code navigator.language} 를 BCP-47 소문자로 정규화. 비브라우저/미가용 시 null.
+     * <p>{@link #registerUser} 자동 시드에 사용되며, 고객사 BFF 의 {@code /users/auth} 시드에도 쓸 수 있다.</p>
+     * @returns {string|null}
+     */
+    static detectBrowserLanguage() {
+        if (typeof navigator === 'undefined' || !navigator.language) {
+            return null;
+        }
+        return navigator.language.trim().toLowerCase() || null;
+    }
+
+    /**
+     * 표시 텍스트 헬퍼 (다국어) — 내 언어 번역이 있으면 그것, 없으면 원문.
+     * <p>{@code myLang} 은 내 effectiveLanguage (방 participant.language ?? user.preferredLanguage).
+     * {@code messageTranslated} 이벤트로 갱신된 message 에 적용.</p>
+     * @param {Object} message - 메시지 (translations 맵 포함 가능)
+     * @param {string} [myLang] - 내 언어 코드
+     * @returns {string|null}
+     */
+    static displayText(message, myLang) {
+        if (message && message.translations && myLang && message.translations[myLang]) {
+            return message.translations[myLang];
+        }
+        return message ? message.content : null;
+    }
+
+    /**
+     * 사용자 존재 여부 확인
+     * @param {string} projectUserId - 프로젝트 사용자 ID
+     * @returns {Promise<Object>}
+     */
+    async checkUserExists(projectUserId) {
+        return this.apiClient.get(`/api/v1/users/${projectUserId}/exists`);
+    }
+
+    /**
+     * 사용자 목록 조회
+     * @param {Object} [params]
+     * @param {number} [params.size=50] - 페이지 크기 (1-100)
+     * @param {string} [params.lastId] - 마지막 사용자 ID
+     * @param {number} [params.lastSortValue] - 마지막 정렬값
+     * @returns {Promise<Object>}
+     */
+    async getUsers(params = {}) {
+        this._checkToken();
+        const { size = 50, lastId, lastSortValue } = params;
+        return this.apiClient.get('/api/v1/users', { size, lastId, lastSortValue });
+    }
+
+    /**
+     * 사용자 검색
+     * @param {Object} params
+     * @param {string} params.keyword - 검색 키워드 (필수, max 50자)
+     * @param {number} [params.limit=20] - 결과 수 (1-50)
+     * @returns {Promise<Object>}
+     */
+    async searchUsers(params) {
+        this._checkToken();
+        const { keyword, limit = 20 } = params;
+        return this.apiClient.get('/api/v1/users/search', { keyword, limit });
+    }
+
+    /**
+     * 토큰 필요 여부 확인
+     * @private
+     * @throws {Error} 토큰이 없는 경우
+     */
+    _checkToken() {
+        if (!this.options.jwtToken) {
+            throw new Error(
+                'JWT token is required for this operation. Obtain it from your backend ' +
+                '(POST /api/v1/users/auth with Server API Key) and pass it via setToken(). ' +
+                'See README "프로덕션 인증 플로우".'
+            );
+        }
+    }
+
+    // ==================== 유틸리티 ====================
+
+    /**
+     * 현재 사용자 ID
+     * @returns {string|null}
+     */
+    getUserId() {
+        return this.userId;
+    }
+
+    /**
+     * 초기화 상태 확인
+     * @returns {boolean}
+     */
+    isInitialized() {
+        return this._initialized;
+    }
+
+    /**
+     * 서브 클라이언트 초기화 상태 확인
+     * @returns {boolean}
+     */
+    isReady() {
+        return this._initialized && !!this.connectionManager;
+    }
+
+    /**
+     * 로그 레벨 설정
+     * @param {number} level - LogLevel 값
+     */
+    setLogLevel(level) {
+        this.options.logLevel = level;
+        this.logger.setLevel(level);
+        this.apiClient.logger?.setLevel(level);
+
+        if (this.connectionManager) {
+            this.connectionManager.setLogLevel(level);
+        }
+        if (this.chat) {
+            this.chat.setLogLevel(level);
+        }
+        if (this.webrtc) {
+            this.webrtc.setLogLevel(level);
+        }
+    }
+
+    /**
+     * 전체 상태 요약
+     * @returns {Object}
+     */
+    getStatus() {
+        return {
+            initialized: this._initialized,
+            ready: this.isReady(),
+            hasToken: this.hasToken(),
+            connectionState: this._state,
+            isConnected: this.isConnected(),
+            userId: this.userId,
+            chat: this.chat ? {
+                subscribedRooms: this.chat.getSubscribedRooms()
+            } : null,
+            webrtc: this.webrtc ? {
+                isInCall: this.webrtc.isInCall(),
+                currentRoom: this.webrtc.getCurrentRoom(),
+                participants: this.webrtc.getParticipants(),
+                mediaState: this.webrtc.getMediaState()
+            } : null
+        };
+    }
+
+    /**
+     * 리소스 정리
+     */
+    async destroy() {
+        await this.disconnect();
+
+        if (this.chat) {
+            this.chat.destroy();
+        }
+        if (this.webrtc) {
+            this.webrtc.destroy();
+        }
+        if (this.connectionManager) {
+            await this.connectionManager.destroy();
+        }
+
+        this.removeAllListeners();
+
+        this._initialized = false;
+        this.logger.info('TalkFlowClient destroyed');
+    }
+}
+
+// 정적 속성으로 상수 노출
+TalkFlowClient.ConnectionState = ConnectionState;
+TalkFlowClient.ErrorTypes = ErrorTypes;
+TalkFlowClient.LogLevel = LogLevel;
+TalkFlowClient.Environment = Environment;
+
+applySessionMethods(TalkFlowClient);
+applyDelegatedMethods(TalkFlowClient);
+
+export default TalkFlowClient;