@vibexnpm/talkx 2.3.1

package/src/utils/ApiClient.js

@@ -0,0 +1,305 @@
+/**
+ * API Client
+ * REST API 호출을 위한 HTTP 클라이언트
+ */
+
+import { ErrorTypes, DefaultConfig } from '../constants.js';
+import Logger from './Logger.js';
+
+class ApiClient {
+    /**
+     * @param {Object} options
+     * @param {string} options.baseUrl - API 기본 URL
+     * @param {string} options.apiKey - API 키
+     * @param {string} options.projectId - 프로젝트 ID
+     * @param {string} options.jwtToken - JWT 토큰
+     * @param {number} [options.timeout] - 요청 타임아웃 (ms)
+     * @param {number} [options.logLevel] - 로그 레벨
+     */
+    constructor(options) {
+        this.baseUrl = options.baseUrl.replace(/\/$/, '');
+        this.apiKey = options.apiKey;
+        this.projectId = options.projectId;
+        this.jwtToken = options.jwtToken;
+        this.timeout = options.timeout || DefaultConfig.apiTimeout;
+
+        this.logger = new Logger(options.logLevel, 'ApiClient');
+    }
+
+    /**
+     * JWT 토큰 업데이트.
+     * logout 경로에서 토큰 제거를 위해 {@code null} 도 전달 가능.
+     * @param {string|null} token
+     */
+    setJwtToken(token) {
+        this.jwtToken = token;
+    }
+
+    /**
+     * 공통 헤더 생성
+     * @returns {Object}
+     */
+    _getHeaders() {
+        const headers = {
+            'Content-Type': 'application/json',
+            'X-API-KEY': this.apiKey,
+            'X-PROJECT-ID': this.projectId
+        };
+
+        if (this.jwtToken) {
+            headers['Authorization'] = this.jwtToken.startsWith('Bearer ')
+                ? this.jwtToken
+                : `Bearer ${this.jwtToken}`;
+        }
+
+        return headers;
+    }
+
+    /**
+     * HTTP 요청 실행
+     * @param {string} method - HTTP 메서드
+     * @param {string} path - API 경로
+     * @param {Object} [options] - 옵션
+     * @param {Object} [options.body] - 요청 본문
+     * @param {Object} [options.params] - URL 파라미터
+     * @returns {Promise<Object>}
+     */
+    async request(method, path, options = {}) {
+        const { body, params } = options;
+
+        // URL 빌드
+        let url = `${this.baseUrl}${path}`;
+        if (params) {
+            const searchParams = new URLSearchParams();
+            Object.entries(params).forEach(([key, value]) => {
+                if (value !== undefined && value !== null) {
+                    searchParams.append(key, value);
+                }
+            });
+            const queryString = searchParams.toString();
+            if (queryString) {
+                url += `?${queryString}`;
+            }
+        }
+
+        // AbortController for timeout
+        const controller = new AbortController();
+        const timeoutId = setTimeout(() => controller.abort(), this.timeout);
+
+        let response;
+        try {
+            this.logger.debug(`${method} ${url}`, body ? { body } : '');
+
+            response = await fetch(url, {
+                method,
+                headers: this._getHeaders(),
+                body: body ? JSON.stringify(body) : undefined,
+                signal: controller.signal
+            });
+        } catch (error) {
+            clearTimeout(timeoutId);
+
+            if (error.name === 'AbortError') {
+                const timeoutError = new Error('Request timeout');
+                timeoutError.code = ErrorTypes.API_TIMEOUT;
+                throw timeoutError;
+            }
+
+            this.logger.error(`API Error: ${method} ${url}`, error);
+            throw error;
+        }
+
+        clearTimeout(timeoutId);
+
+        // 응답 파싱
+        const contentType = response.headers.get('content-type');
+        let data;
+
+        if (contentType && contentType.includes('application/json')) {
+            data = await response.json();
+        } else {
+            data = await response.text();
+        }
+
+        // 에러 처리
+        if (!response.ok) {
+            const error = new Error(data?.message || `HTTP ${response.status}`);
+            error.code = ErrorTypes.API_ERROR;
+            error.status = response.status;
+            error.response = data;
+            this.logger.error(`API Error: ${method} ${url}`, error);
+            throw error;
+        }
+
+        this.logger.debug(`Response ${response.status}:`, data);
+        return data;
+    }
+
+    // HTTP 메서드 헬퍼
+
+    /**
+     * GET 요청
+     * @param {string} path - API 경로
+     * @param {Object} [params] - URL 파라미터
+     * @returns {Promise<Object>}
+     */
+    get(path, params) {
+        return this.request('GET', path, { params });
+    }
+
+    /**
+     * POST 요청
+     * @param {string} path - API 경로
+     * @param {Object} [body] - 요청 본문
+     * @param {Object} [params] - URL 파라미터
+     * @returns {Promise<Object>}
+     */
+    post(path, body, params) {
+        return this.request('POST', path, { body, params });
+    }
+
+    /**
+     * PUT 요청
+     * @param {string} path - API 경로
+     * @param {Object} [body] - 요청 본문
+     * @returns {Promise<Object>}
+     */
+    put(path, body) {
+        return this.request('PUT', path, { body });
+    }
+
+    /**
+     * PATCH 요청
+     * @param {string} path - API 경로
+     * @param {Object} [body] - 요청 본문
+     * @returns {Promise<Object>}
+     */
+    patch(path, body) {
+        return this.request('PATCH', path, { body });
+    }
+
+    /**
+     * DELETE 요청
+     * @param {string} path - API 경로
+     * @param {Object} [params] - URL 파라미터
+     * @returns {Promise<Object>}
+     */
+    delete(path, params) {
+        return this.request('DELETE', path, { params });
+    }
+
+    /**
+     * multipart/form-data 파일 업로드.
+     *
+     * <p>{@code fetch} 가 업로드 진행률을 지원하지 않아 {@code XMLHttpRequest} 사용.
+     * Content-Type 은 브라우저가 boundary 를 포함해 자동 세팅하므로 명시하지 않는다.</p>
+     *
+     * @param {string} path - API 경로 (baseUrl 뒤에 붙음)
+     * @param {File|Blob} file - 업로드할 파일
+     * @param {Object} [options]
+     * @param {string} [options.fieldName='file'] - multipart field 이름 (서버 @RequestParam 과 일치)
+     * @param {Function} [options.onProgress] - {@code ({loaded, total, percent}) => void} — 업로드 진행률 콜백
+     * @param {AbortSignal} [options.signal] - 업로드 취소용 AbortSignal
+     * @param {number} [options.timeout=600000] - 타임아웃 (ms). 기본 10분.
+     * @returns {Promise<Object>} 서버 응답 JSON (SuccessResponse 래퍼 포함)
+     */
+    upload(path, file, options = {}) {
+        const {
+            fieldName = 'file',
+            onProgress,
+            signal,
+            timeout = 600_000
+        } = options;
+
+        return new Promise((resolve, reject) => {
+            const url = `${this.baseUrl}${path}`;
+            const xhr = new XMLHttpRequest();
+            const form = new FormData();
+            form.append(fieldName, file);
+
+            xhr.open('POST', url);
+            xhr.timeout = timeout;
+
+            // Content-Type 은 XHR 이 multipart boundary 포함해 자동 세팅 — 명시 금지
+            xhr.setRequestHeader('X-API-KEY', this.apiKey);
+            xhr.setRequestHeader('X-PROJECT-ID', this.projectId);
+            if (this.jwtToken) {
+                xhr.setRequestHeader(
+                    'Authorization',
+                    this.jwtToken.startsWith('Bearer ') ? this.jwtToken : `Bearer ${this.jwtToken}`
+                );
+            }
+
+            if (typeof onProgress === 'function') {
+                xhr.upload.onprogress = (e) => {
+                    if (e.lengthComputable) {
+                        onProgress({
+                            loaded: e.loaded,
+                            total: e.total,
+                            percent: Math.round((e.loaded / e.total) * 100)
+                        });
+                    }
+                };
+            }
+
+            // 외부 AbortSignal 과 연동 (취소 지원)
+            const onAbort = () => xhr.abort();
+            if (signal) {
+                if (signal.aborted) {
+                    reject(new Error('Upload cancelled'));
+                    return;
+                }
+                signal.addEventListener('abort', onAbort);
+            }
+            const cleanupSignal = () => {
+                if (signal) signal.removeEventListener('abort', onAbort);
+            };
+
+            xhr.onload = () => {
+                cleanupSignal();
+                let parsed = xhr.responseText;
+                const contentType = xhr.getResponseHeader('content-type') || '';
+                if (contentType.includes('application/json')) {
+                    try { parsed = JSON.parse(xhr.responseText); } catch { /* keep text */ }
+                }
+                if (xhr.status >= 200 && xhr.status < 300) {
+                    this.logger.debug(`Upload ${xhr.status}:`, parsed);
+                    resolve(parsed);
+                } else {
+                    const error = new Error(parsed?.message || `HTTP ${xhr.status}`);
+                    error.code = ErrorTypes.API_ERROR;
+                    error.status = xhr.status;
+                    error.response = parsed;
+                    this.logger.error(`Upload Error: POST ${url}`, error);
+                    reject(error);
+                }
+            };
+
+            xhr.onerror = () => {
+                cleanupSignal();
+                const err = new Error('Network error during upload');
+                err.code = ErrorTypes.API_ERROR;
+                this.logger.error(`Upload Network Error: POST ${url}`, err);
+                reject(err);
+            };
+
+            xhr.ontimeout = () => {
+                cleanupSignal();
+                const err = new Error('Upload timeout');
+                err.code = ErrorTypes.API_TIMEOUT;
+                this.logger.error(`Upload Timeout: POST ${url}`, err);
+                reject(err);
+            };
+
+            xhr.onabort = () => {
+                cleanupSignal();
+                reject(new Error('Upload cancelled'));
+            };
+
+            this.logger.debug(`POST ${url} (multipart, ${file.size} bytes)`);
+            xhr.send(form);
+        });
+    }
+}
+
+export default ApiClient;

package/src/utils/EventEmitter.js

@@ -0,0 +1,113 @@
+/**
+ * EventEmitter 유틸리티
+ * 이벤트 기반 통신을 위한 간단한 구현
+ */
+
+class EventEmitter {
+    constructor() {
+        this._events = new Map();
+    }
+
+    /**
+     * 이벤트 리스너 등록
+     * @param {string} event - 이벤트 이름
+     * @param {Function} listener - 콜백 함수
+     * @returns {Function} - 구독 해제 함수
+     */
+    on(event, listener) {
+        if (!this._events.has(event)) {
+            this._events.set(event, new Set());
+        }
+        this._events.get(event).add(listener);
+
+        // 구독 해제 함수 반환
+        return () => this.off(event, listener);
+    }
+
+    /**
+     * 일회성 이벤트 리스너 등록
+     * @param {string} event - 이벤트 이름
+     * @param {Function} listener - 콜백 함수
+     * @returns {Function} - 구독 해제 함수
+     */
+    once(event, listener) {
+        const onceWrapper = (...args) => {
+            this.off(event, onceWrapper);
+            listener.apply(this, args);
+        };
+        onceWrapper._originalListener = listener;
+        return this.on(event, onceWrapper);
+    }
+
+    /**
+     * 이벤트 리스너 제거
+     * @param {string} event - 이벤트 이름
+     * @param {Function} listener - 콜백 함수
+     */
+    off(event, listener) {
+        const listeners = this._events.get(event);
+        if (listeners) {
+            // once로 등록된 리스너도 제거 가능하도록
+            for (const l of listeners) {
+                if (l === listener || l._originalListener === listener) {
+                    listeners.delete(l);
+                    break;
+                }
+            }
+            if (listeners.size === 0) {
+                this._events.delete(event);
+            }
+        }
+    }
+
+    /**
+     * 이벤트 발생.
+     * payload 가 없는 이벤트({@code loggedOut}, {@code pushEnabled} 등) 는 {@code data} 생략 가능.
+     * @param {string} event - 이벤트 이름
+     * @param {*} [data] - 이벤트 데이터 (선택)
+     */
+    emit(event, data) {
+        const listeners = this._events.get(event);
+        if (listeners) {
+            listeners.forEach(listener => {
+                try {
+                    listener(data);
+                } catch (error) {
+                    console.error(`Error in event listener for '${event}':`, error);
+                }
+            });
+        }
+    }
+
+    /**
+     * 특정 이벤트의 모든 리스너 제거 (이벤트명 생략 시 전체 제거)
+     * @param {string} [event] - 이벤트 이름 (선택)
+     */
+    removeAllListeners(event) {
+        if (event) {
+            this._events.delete(event);
+        } else {
+            this._events.clear();
+        }
+    }
+
+    /**
+     * 이벤트 리스너 수 반환
+     * @param {string} event - 이벤트 이름
+     * @returns {number}
+     */
+    listenerCount(event) {
+        const listeners = this._events.get(event);
+        return listeners ? listeners.size : 0;
+    }
+
+    /**
+     * 등록된 이벤트 이름 목록
+     * @returns {string[]}
+     */
+    eventNames() {
+        return Array.from(this._events.keys());
+    }
+}
+
+export default EventEmitter;

package/src/utils/Logger.js

@@ -0,0 +1,88 @@
+/**
+ * Logger 유틸리티
+ * 로그 레벨에 따른 콘솔 출력 관리
+ */
+
+import { LogLevel } from '../constants.js';
+
+class Logger {
+    /**
+     * @param {number} [level] - 로그 레벨
+     * @param {string} [prefix] - 로그 접두사
+     */
+    constructor(level = LogLevel.WARN, prefix = 'TalkFlow') {
+        this.level = level;
+        this.prefix = prefix;
+    }
+
+    /**
+     * 로그 레벨 설정
+     * @param {number} level - 로그 레벨
+     */
+    setLevel(level) {
+        this.level = level;
+    }
+
+    /**
+     * 로그 접두사 설정
+     * @param {string} prefix - 로그 접두사
+     */
+    setPrefix(prefix) {
+        this.prefix = prefix;
+    }
+
+    /**
+     * 로그 포맷 생성
+     * @private
+     * @param {string} level - 로그 레벨 문자열
+     * @param {...*} args - 로그 인자들
+     * @returns {Array} 포맷된 로그 배열
+     */
+    _format(level, ...args) {
+        const timestamp = new Date().toISOString();
+        return [`[${timestamp}] [${level}] [${this.prefix}]`, ...args];
+    }
+
+    /**
+     * 디버그 로그 출력
+     * @param {...*} args - 로그 인자들
+     */
+    debug(...args) {
+        if (this.level <= LogLevel.DEBUG) {
+            console.debug(...this._format('DEBUG', ...args));
+        }
+    }
+
+    /**
+     * 정보 로그 출력
+     * @param {...*} args - 로그 인자들
+     */
+    info(...args) {
+        if (this.level <= LogLevel.INFO) {
+            console.info(...this._format('INFO', ...args));
+        }
+    }
+
+    /**
+     * 경고 로그 출력
+     * @param {...*} args - 로그 인자들
+     */
+    warn(...args) {
+        if (this.level <= LogLevel.WARN) {
+            console.warn(...this._format('WARN', ...args));
+        }
+    }
+
+    /**
+     * 에러 로그 출력
+     * @param {...*} args - 로그 인자들
+     */
+    error(...args) {
+        if (this.level <= LogLevel.ERROR) {
+            console.error(...this._format('ERROR', ...args));
+        }
+    }
+}
+
+export default Logger;
+export { LogLevel };