@vibexnpm/talkx 2.3.1

package/src/core/ConnectionManager.js

@@ -0,0 +1,517 @@
+/**
+ * ConnectionManager
+ * WebSocket/STOMP 연결 관리 (Chat, WebRTC 공유)
+ */
+
+import EventEmitter from '../utils/EventEmitter.js';
+import Logger from '../utils/Logger.js';
+import { ConnectionState, ErrorTypes, WebSocketPaths, DefaultConfig, LogLevel } from '../constants.js';
+import { Client as StompClient } from '@stomp/stompjs';
+import SockJS from 'sockjs-client';
+
+// STOMP Client 가져오기 (CDN 사용 시 전역 객체 우선)
+const getStompClient = () => {
+    // noinspection JSUnresolvedReference
+    if (typeof window !== 'undefined' && window.StompJs && window.StompJs.Client) {
+        return window.StompJs.Client;
+    }
+    return StompClient;
+};
+
+// SockJS 가져오기 (CDN 사용 시 전역 객체 우선)
+const getSockJS = () => {
+    // noinspection JSUnresolvedReference
+    if (typeof window !== 'undefined' && window.SockJS) {
+        return window.SockJS;
+    }
+    return SockJS;
+};
+
+class ConnectionManager extends EventEmitter {
+    /**
+     * @param {Object} options
+     * @param {string} options.serverUrl - 서버 URL
+     * @param {string} options.jwtToken - JWT 토큰
+     * @param {string} options.apiKey - API 키
+     * @param {string} options.projectId - 프로젝트 ID
+     * @param {boolean} [options.useSockJS=true] - SockJS 사용 여부
+     * @param {number} [options.reconnectDelay] - 재연결 지연 시간
+     * @param {number} [options.maxReconnectAttempts] - 최대 재연결 시도 횟수
+     * @param {number} [options.heartbeatIncoming] - 수신 하트비트 간격
+     * @param {number} [options.heartbeatOutgoing] - 발신 하트비트 간격
+     * @param {number} [options.logLevel] - 로그 레벨
+     */
+    constructor(options) {
+        super();
+
+        this.serverUrl = options.serverUrl.replace(/\/$/, '');
+        this.jwtToken = options.jwtToken;
+        this.apiKey = options.apiKey;
+        this.projectId = options.projectId;
+        this.useSockJS = options.useSockJS !== false;
+
+        this.reconnectDelay = options.reconnectDelay || DefaultConfig.reconnectDelay;
+        this.maxReconnectAttempts = options.maxReconnectAttempts || DefaultConfig.maxReconnectAttempts;
+        this.heartbeatIncoming = options.heartbeatIncoming || DefaultConfig.heartbeatIncoming;
+        this.heartbeatOutgoing = options.heartbeatOutgoing || DefaultConfig.heartbeatOutgoing;
+
+        this.logger = new Logger(options.logLevel || LogLevel.WARN, 'ConnectionManager');
+
+        // 상태
+        this.state = ConnectionState.DISCONNECTED;
+        this.stompClient = null;
+        this.reconnectAttempts = 0;
+        this.subscriptions = new Map();
+        this.pendingSubscriptions = [];
+        this.userId = null;
+    }
+
+    /**
+     * 연결 상태 변경
+     * @private
+     */
+    _setState(state) {
+        const prevState = this.state;
+        this.state = state;
+        this.emit('stateChange', { state, prevState });
+        this.logger.info(`State changed: ${prevState} -> ${state}`);
+    }
+
+    /**
+     * WebSocket URL 생성.
+     *
+     * <p>JWT 는 STOMP connectHeaders 의 Authorization 헤더로만 전달합니다.
+     * URL query parameter 에 토큰을 넣지 않습니다 — 서버 로그, 프록시 로그,
+     * 브라우저 히스토리에 JWT 가 평문 노출되는 것을 방지.</p>
+     *
+     * @private
+     */
+    _getWebSocketUrl() {
+        const endpoint = this.useSockJS
+            ? WebSocketPaths.SOCKJS_ENDPOINT
+            : WebSocketPaths.NATIVE_ENDPOINT;
+
+        return `${this.serverUrl}${endpoint}`;
+    }
+
+    /**
+     * STOMP 클라이언트 생성
+     * @private
+     */
+    _createStompClient() {
+        const wsUrl = this._getWebSocketUrl();
+
+        const config = {
+            connectHeaders: {
+                'Authorization': this.jwtToken.startsWith('Bearer ')
+                    ? this.jwtToken
+                    : `Bearer ${this.jwtToken}`,
+                'X-API-KEY': this.apiKey,
+                'X-PROJECT-ID': this.projectId
+            },
+            heartbeatIncoming: this.heartbeatIncoming,
+            heartbeatOutgoing: this.heartbeatOutgoing,
+            reconnectDelay: this.reconnectDelay,
+            debug: (str) => {
+                if (this.logger.level <= LogLevel.DEBUG) {
+                    this.logger.debug('STOMP:', str);
+                }
+            },
+            onConnect: (frame) => this._onConnect(frame),
+            onDisconnect: (frame) => this._onDisconnect(frame),
+            onStompError: (frame) => this._onStompError(frame),
+            onWebSocketClose: (event) => this._onWebSocketClose(event),
+            onWebSocketError: (event) => this._onWebSocketError(event)
+        };
+
+        if (this.useSockJS) {
+            const SockJS = getSockJS();
+            config.webSocketFactory = () => new SockJS(wsUrl);
+        } else {
+            // Native WebSocket — 토큰은 connectHeaders 로만 전달 (URL 노출 방지)
+            const wsProtocol = this.serverUrl.startsWith('https') ? 'wss' : 'ws';
+            const wsHost = this.serverUrl.replace(/^https?:\/\//, '');
+            config.brokerURL = `${wsProtocol}://${wsHost}${WebSocketPaths.NATIVE_ENDPOINT}`;
+        }
+
+        const Client = getStompClient();
+        return new Client(config);
+    }
+
+    /**
+     * 연결
+     * @returns {Promise<void>}
+     */
+    async connect() {
+        if (this.state === ConnectionState.CONNECTED) {
+            this.logger.warn('Already connected');
+            return;
+        }
+
+        if (this.state === ConnectionState.CONNECTING) {
+            this.logger.warn('Connection in progress');
+            return;
+        }
+
+        this._setState(ConnectionState.CONNECTING);
+        this.reconnectAttempts = 0;
+
+        return new Promise((resolve, reject) => {
+            this._connectResolve = resolve;
+            this._connectReject = reject;
+
+            try {
+                this.stompClient = this._createStompClient();
+                this.stompClient.activate();
+            } catch (error) {
+                this._setState(ConnectionState.ERROR);
+                this._drainPendingSubscriptions('Connection activation failed');
+                reject(error);
+            }
+        });
+    }
+
+    /**
+     * 연결 성공 콜백
+     * @private
+     */
+    _onConnect(frame) {
+        this._setState(ConnectionState.CONNECTED);
+        this.reconnectAttempts = 0;
+        this.logger.info('Connected to server', frame);
+
+        // 기존 구독 재등록 (재연결 시)
+        this._restoreSubscriptions();
+
+        // 대기 중인 구독 처리
+        this._processPendingSubscriptions();
+
+        this.emit('connected', { frame });
+
+        if (this._connectResolve) {
+            this._connectResolve();
+            this._connectResolve = null;
+            this._connectReject = null;
+        }
+    }
+
+    /**
+     * 연결 해제 콜백
+     * @private
+     */
+    _onDisconnect(frame) {
+        this.logger.info('Disconnected from server', frame);
+        this._setState(ConnectionState.DISCONNECTED);
+        this.emit('disconnected', { frame });
+    }
+
+    /**
+     * STOMP 에러 콜백
+     * @private
+     */
+    _onStompError(frame) {
+        this.logger.error('STOMP error:', frame);
+        this._setState(ConnectionState.ERROR);
+
+        const error = {
+            type: ErrorTypes.CONNECTION_FAILED,
+            message: frame.headers?.message || 'STOMP error',
+            frame
+        };
+
+        // terminal 전이 — 대기 중 구독 Promise 가 영구 hang 되지 않도록 drain.
+        this._drainPendingSubscriptions(`STOMP error: ${error.message}`);
+
+        this.emit('error', error);
+
+        if (this._connectReject) {
+            this._connectReject(new Error(error.message));
+            this._connectResolve = null;
+            this._connectReject = null;
+        }
+    }
+
+    /**
+     * WebSocket 종료 콜백
+     * @private
+     */
+    _onWebSocketClose(event) {
+        this.logger.warn('WebSocket closed:', event);
+
+        if (this.state !== ConnectionState.DISCONNECTED) {
+            this._handleReconnect();
+        }
+    }
+
+    /**
+     * WebSocket 에러 콜백
+     * @private
+     */
+    _onWebSocketError(event) {
+        this.logger.error('WebSocket error:', event);
+
+        // 초기 연결 실패 경로 — _connectReject 가 살아있다는 건 아직 한 번도
+        // CONNECTED 된 적이 없다는 뜻. pending 구독도 함께 drain 해서 호출자 hang 방지.
+        // 이미 CONNECTED 후 일시 끊김은 _onWebSocketClose → _handleReconnect 로 흘러
+        // 재연결 성공 시 _processPendingSubscriptions 가 살린다.
+        if (this._connectReject) {
+            this._drainPendingSubscriptions('WebSocket connection failed');
+            this._connectReject(new Error('WebSocket connection failed'));
+            this._connectResolve = null;
+            this._connectReject = null;
+        }
+    }
+
+    /**
+     * 재연결 처리.
+     *
+     * <p>max 초과 시 STOMP 내부 재연결 루프(reconnectDelay) 를 차단하기 위해
+     * stompClient 를 반드시 deactivate 하고 참조를 해제한다. state 변경만으로는
+     * STOMP 자체가 소유한 타이머를 멈출 수 없음.</p>
+     *
+     * @private
+     */
+    _handleReconnect() {
+        this.reconnectAttempts++;
+
+        if (this.reconnectAttempts > this.maxReconnectAttempts) {
+            if (this.stompClient) {
+                try {
+                    this.stompClient.deactivate();
+                } catch (error) {
+                    this.logger.warn('Error deactivating stomp client on max reconnect:', error);
+                }
+                this.stompClient = null;
+            }
+
+            // terminal 전이 — 재연결 성공으로 살릴 기회가 사라졌으므로 pending 도 drain.
+            this._drainPendingSubscriptions('Max reconnection attempts exceeded');
+
+            this._setState(ConnectionState.ERROR);
+            this.emit('error', {
+                type: ErrorTypes.CONNECTION_LOST,
+                message: 'Max reconnection attempts exceeded'
+            });
+            return;
+        }
+
+        this._setState(ConnectionState.RECONNECTING);
+        this.emit('reconnecting', { attempt: this.reconnectAttempts });
+        this.logger.info(`Reconnecting... attempt ${this.reconnectAttempts}`);
+    }
+
+    /**
+     * 기존 구독 재등록 (재연결 시)
+     * @private
+     */
+    _restoreSubscriptions() {
+        if (this.subscriptions.size === 0) return;
+
+        this.logger.info(`Restoring ${this.subscriptions.size} subscriptions after reconnect`);
+
+        const previousSubscriptions = new Map(this.subscriptions);
+        this.subscriptions.clear();
+
+        previousSubscriptions.forEach(({ callback, headers }, destination) => {
+            this._subscribeInternal(destination, callback, headers);
+            this.logger.debug(`Restored subscription: ${destination}`);
+        });
+    }
+
+    /**
+     * 대기 중인 구독 처리
+     * @private
+     */
+    _processPendingSubscriptions() {
+        while (this.pendingSubscriptions.length > 0) {
+            const { destination, callback, headers, resolve } = this.pendingSubscriptions.shift();
+            const subscription = this._subscribeInternal(destination, callback, headers);
+            if (resolve) {
+                resolve(subscription);
+            }
+        }
+    }
+
+    /**
+     * 내부 구독 처리
+     * @private
+     */
+    _subscribeInternal(destination, callback, headers = {}) {
+        const subscription = this.stompClient.subscribe(destination, (message) => {
+            try {
+                const body = JSON.parse(message.body);
+                callback(body, message);
+            } catch (error) {
+                this.logger.error('Failed to parse message:', error);
+                callback(message.body, message);
+            }
+        }, headers);
+
+        // 재연결 시 복구를 위해 callback, headers도 함께 저장
+        this.subscriptions.set(destination, { subscription, callback, headers });
+        this.logger.debug(`Subscribed to: ${destination}`);
+
+        return subscription;
+    }
+
+    /**
+     * 채널 구독
+     * @param {string} destination - 구독 경로
+     * @param {Function} callback - 메시지 콜백
+     * @param {Object} [headers] - 추가 헤더
+     * @returns {Promise<Object>} - 구독 객체
+     */
+    subscribe(destination, callback, headers = {}) {
+        // 이미 구독 중이면 기존 구독 해제 후 재구독
+        if (this.subscriptions.has(destination)) {
+            this.unsubscribe(destination);
+        }
+
+        if (this.state !== ConnectionState.CONNECTED) {
+            return new Promise((resolve, reject) => {
+                this.pendingSubscriptions.push({ destination, callback, headers, resolve, reject });
+                this.logger.debug(`Queued subscription for: ${destination}`);
+            });
+        }
+
+        return Promise.resolve(this._subscribeInternal(destination, callback, headers));
+    }
+
+    /**
+     * 구독 해제
+     * @param {string} destination - 구독 경로
+     */
+    unsubscribe(destination) {
+        const entry = this.subscriptions.get(destination);
+        if (entry) {
+            entry.subscription.unsubscribe();
+            this.subscriptions.delete(destination);
+            this.logger.debug(`Unsubscribed from: ${destination}`);
+        }
+    }
+
+    /**
+     * 모든 구독 해제
+     */
+    unsubscribeAll() {
+        this.subscriptions.forEach(({ subscription }, destination) => {
+            subscription.unsubscribe();
+            this.logger.debug(`Unsubscribed from: ${destination}`);
+        });
+        this.subscriptions.clear();
+    }
+
+    /**
+     * 메시지 전송
+     * @param {string} destination - 전송 경로
+     * @param {Object} body - 메시지 본문
+     * @param {Object} [headers] - 추가 헤더
+     */
+    send(destination, body, headers = {}) {
+        if (this.state !== ConnectionState.CONNECTED) {
+            this.logger.warn('Cannot send message: not connected');
+            return false;
+        }
+
+        this.stompClient.publish({
+            destination,
+            body: JSON.stringify(body),
+            headers
+        });
+
+        this.logger.debug(`Sent to ${destination}:`, body);
+        return true;
+    }
+
+    /**
+     * JWT 토큰 업데이트
+     * @param {string} token
+     */
+    updateToken(token) {
+        this.jwtToken = token;
+
+        if (this.stompClient) {
+            this.stompClient.connectHeaders = {
+                ...this.stompClient.connectHeaders,
+                'Authorization': token.startsWith('Bearer ') ? token : `Bearer ${token}`
+            };
+        }
+    }
+
+    /**
+     * 연결 해제.
+     *
+     * <p>대기 중 구독이 남아 있으면 각 Promise 를 reject 하고 큐를 비운다.
+     * clear 만 하면 호출자 {@code await} 가 영원히 hang 된다.</p>
+     */
+    async disconnect() {
+        this._drainPendingSubscriptions('Disconnected before subscription completed');
+
+        if (this.stompClient) {
+            this.unsubscribeAll();
+            await this.stompClient.deactivate();
+            this.stompClient = null;
+        }
+
+        this._setState(ConnectionState.DISCONNECTED);
+        this.logger.info('Disconnected');
+    }
+
+    /**
+     * 대기 중 구독 Promise 일괄 reject + 큐 비움.
+     * @private
+     */
+    _drainPendingSubscriptions(reason) {
+        if (this.pendingSubscriptions.length === 0) return;
+
+        const pending = this.pendingSubscriptions;
+        this.pendingSubscriptions = [];
+
+        pending.forEach(({ destination, reject }) => {
+            if (reject) {
+                reject(new Error(`${reason}: ${destination}`));
+            }
+        });
+
+        this.logger.debug(`Drained ${pending.length} pending subscriptions: ${reason}`);
+    }
+
+    /**
+     * 연결 상태 확인
+     * @returns {boolean}
+     */
+    isConnected() {
+        return this.state === ConnectionState.CONNECTED;
+    }
+
+    /**
+     * 현재 상태 반환
+     * @returns {string}
+     */
+    getState() {
+        return this.state;
+    }
+
+    /**
+     * 로그 레벨 설정
+     * @param {number} level
+     */
+    setLogLevel(level) {
+        this.logger.setLevel(level);
+    }
+
+    /**
+     * 리소스 정리.
+     *
+     * <p>{@link #disconnect} 가 async 이므로 await 필수. 최상위 {@link TalkFlowClient#destroy}
+     * 는 별도 {@code await this.disconnect()} 선행으로 이미 완충되지만,
+     * ConnectionManager 를 직접 소유한 사용자가 destroy 만 호출하는 경로도 안전해야 함.</p>
+     */
+    async destroy() {
+        await this.disconnect();
+        this.removeAllListeners();
+        this.logger.info('ConnectionManager destroyed');
+    }
+}
+
+export default ConnectionManager;

package/src/index.js

@@ -0,0 +1,97 @@
+/**
+ * TalkFlow SDK
+ * 채팅 + WebRTC 통합 클라이언트 라이브러리
+ *
+ * <h2>인증 플로우 (중요)</h2>
+ *
+ * JWT 토큰은 반드시 고객사 backend 에서 발급받아 SDK 에 전달해야 합니다.
+ * 브라우저에서 직접 사용자를 등록/인증하는 기능은 제공하지 않습니다 (보안).
+ *
+ * 자세한 내용은 README 의 "프로덕션 인증 플로우" 섹션 참고.
+ *
+ * @example
+ * // === 빠른 시작 (개발/프로토타입) — Server Key 사용 ===
+ * import TalkFlowClient from '@talkflow/sdk';
+ *
+ * const client = new TalkFlowClient({
+ *   apiKey: 'SERVER_KEY',           // 개발용 Server Key (프로덕션에서는 쓰지 마세요)
+ *   projectId: 'your-project-id',
+ *   env: 'development'
+ * });
+ *
+ * await client.registerUser({ userId: 'user-123', nickname: '홍길동' });
+ * await client.connect();
+ * await client.chat.sendTextMessage('room-id', '안녕하세요!');
+ *
+ * @example
+ * // === 프로덕션 — Client Key + Backend JWT 발급 ===
+ * // 1단계: 고객사 backend 에서 Server Key 로 JWT 발급
+ * //   POST /api/v1/users/auth (X-API-KEY: SERVER_KEY)
+ * //   → { accessToken }
+ *
+ * // 2단계: 브라우저 SDK 는 Client Key + JWT 로 초기화
+ * const client = new TalkFlowClient({
+ *   apiKey: 'CLIENT_KEY',           // 브라우저 노출 안전 (registerUser 서버 차단)
+ *   projectId: 'your-project-id',
+ *   jwtToken: receivedJwt,          // 백엔드로부터 받은 JWT
+ *   env: 'production'
+ * });
+ *
+ * await client.connect();
+ * await client.chat.sendTextMessage('room-id', '안녕하세요!');
+ */
+
+// 메인 클라이언트
+import TalkFlowClient from './TalkFlowClient.js';
+
+// 상수
+export {
+    ConnectionState,
+    ErrorTypes,
+    SignalTypes,
+    ChatMessageType,
+    ChatRoomType,
+    AssistantMode,
+    RoomAiType,
+    EngagementIntensity,
+    PmPromptLayerScope,
+    PmPromptLayerEditorType,
+    SenderType,
+    PersonaRole,
+    SummarizeFormat,
+    RoomListEventType,
+    WebSocketPaths,
+    DefaultConfig,
+    LogLevel,
+    Environment,
+    Endpoints,
+    getServerUrl
+} from './constants.js';
+
+// 유틸리티
+export { default as EventEmitter } from './utils/EventEmitter.js';
+export { default as Logger } from './utils/Logger.js';
+export {
+    validateAndParseJWT,
+    extractUserIdFromJWT,
+    isJWTExpired,
+    getJWTRemainingTime,
+    decodeJWTPayload
+} from './utils/jwtUtils.js';
+
+// 코어
+export { default as ConnectionManager } from './core/ConnectionManager.js';
+
+// 채팅
+export { default as ChatClient } from './chat/ChatClient.js';
+
+// WebRTC
+export { default as WebRTCClient } from './webrtc/WebRTCClient.js';
+export { default as MediaStreamManager } from './webrtc/MediaStreamManager.js';
+export { default as PeerConnectionManager } from './webrtc/PeerConnectionManager.js';
+
+// Push — PushError/PushErrorCode 는 호출자가 instanceof / code 분기에 사용 가능하도록 noamed export.
+export { default as PushManager, PushError, PushErrorCode } from './push/PushManager.js';
+
+// 기본 내보내기
+export default TalkFlowClient;