@vibexnpm/talkx 5.1.0 → 5.3.0

package/package.json

@@ -1,6 +1,6 @@
 {
     "name": "@vibexnpm/talkx",
-    "version": "5.1.0",
+    "version": "5.3.0",
     "type": "module",
     "description": "TalkFlow SDK - Chat & WebRTC unified client",
     "main": "dist/talkflow-sdk.umd.js",

package/src/chat/ChatClient.js

@@ -320,6 +320,21 @@ class ChatClient extends EventEmitter {
         // 1) WebSocket 구독을 먼저 — 이후 서버 read 이벤트 유실 방지
         if (!wasAlreadySubscribed) {
             await this.subscribeRoom(roomId);
+        } else if (this.assistantStreamReplay) {
+            // ⭐ <b>이미 구독 중인 방으로 재입장</b> — 구독을 유지한 채 방 화면만 나갔다 들어오는 흐름이다
+            // (목록 화면에서 unread 를 받으려면 구독을 끊지 않는 것이 정상 구현이다). 이때 subscribeRoom 이
+            // 통째로 건너뛰어져 <b>스냅샷 트리거가 하나도 돌지 않는다</b> — 재개 경로는 여기와 재연결
+            // (`resumeAssistantStreams`) 둘뿐이기 때문이다.
+            //
+            // 진행 표시는 transient 이벤트라 화면이 언마운트되면 프론트에서 사라지는데, SDK 슬롯에만 남은
+            // 그 상태를 다시 그려줄 신호가 없다 → 다음 PHASE 가 올 때까지(워커 heartbeat 간격 15초) 배지가
+            // 안 뜬다. 스냅샷을 다시 받아 그 공백을 없앤다.
+            //
+            // await 하지 않는다 — 구독은 살아 있으므로 그 사이 도착분은 보류함에 쌓였다가 병합 후 순서대로
+            // 풀린다(§6.1). 실패해도 보류분은 반드시 풀리므로 라이브만으로 계속 동작한다.
+            const generation = this._armAssistantSnapshot(roomId);
+            this._loadAssistantSnapshot(roomId, generation)
+                .catch((error) => this.logger.warn(`Assistant snapshot on re-enter failed: room=${roomId}`, error));
         }
         // 2) 자동 읽음 처리 활성 방 지정
         this.setActiveRoom(roomId);
@@ -1017,6 +1032,222 @@ class ChatClient extends EventEmitter {
         return this.apiClient.post(`/api/v1/rooms/group/${roomId}/unpin`);
     }
 
+    // ── 투표 ────────────────────────────────────────────────────────────────
+    //
+    // 투표 서버는 클러스터 내부에만 있어 클라이언트가 직접 부를 수 없다. 모든 호출은 채팅 서버를 거치고,
+    // 신원(userId/projectId)은 채팅 서버가 인증 결과로 채워 넣는다.
+    //
+    // 🔴 실패는 서버가 투표 서버의 code 를 <b>그대로</b> 내려준다 — {@code error.response.code} 로 분기한다
+    //    (VOTE_ALREADY_CLOSED / VOTE_NOT_EDITABLE / VOTE_MODIFY_FORBIDDEN / CONFLICT ...).
+    //    409 는 세 종류이고 대응이 다르다: ALREADY_CLOSED·NOT_EDITABLE 은 재시도해도 같고,
+    //    CONFLICT 만 <b>재조회 후</b> 재전송하면 성공한다.
+    //
+    // 🔴 결과 마스킹은 <b>호출자마다</b> 계산된다. 목록에는 집계가 없고, 단건 조회/접수 응답에만 있다.
+    //    같은 투표라도 다른 사용자가 보면 가려지므로 응답을 공유 캐시에 넣으면 안 된다.
+
+    /**
+     * 투표 생성.
+     *
+     * <p>🔴 <b>{@code idempotencyKey} 는 필수다.</b> SDK 가 대신 만들지 않는다 — 만들면 그 값이 호출자에게
+     * 남지 않아, 응답만 유실된 타임아웃에서 <b>복구가 불가능</b>하다(다음 호출이 새 키를 만들어 투표가
+     * 두 개 생긴다). 호출자가 키를 소유하고, 같은 시도의 재시도에는 <b>같은 키</b>를 넘긴다 —
+     * 그러면 서버가 기존 투표를 돌려준다(응답도 201, {@code voteId} 도 같다).</p>
+     *
+     * @param {string} roomId - 채팅방 ID
+     * @param {Object} vote - 투표 폼
+     * @param {string} vote.question - 질문 (최대 500자)
+     * @param {'SINGLE'|'MULTIPLE'} vote.type
+     * @param {number} vote.maxSelections - 양수. {@code SINGLE} 이면 1
+     * @param {'TEXT'|'TEXT_WITH_IMAGE'} vote.optionType - {@code 'IMAGE'} 라는 값은 없다
+     * @param {number} vote.closeAt - 마감 시각 (epoch millis). 과거·현재 불가 · 최대 30일 뒤
+     * @param {Array<{id: string, content: string, order: number, imageUrl?: string}>} vote.options - 2~10개.
+     *   {@code imageUrl} 은 {@link #uploadVoteImage} 가 돌려준 값을 <b>가공 없이</b> 넣는다
+     * @param {Object} options
+     * @param {string} options.idempotencyKey - <b>필수.</b> 재시도에는 반드시 같은 값을 넘긴다
+     * @returns {Promise<Object>} 생성된 투표 (집계 포함)
+     * @throws {Error} {@code idempotencyKey} 가 없으면 서버를 호출하지 않고 즉시 실패한다
+     * @example
+     * const key = crypto.randomUUID();
+     * const vote = await chat.createVote(roomId, {
+     *   question: '점심 뭐 먹지', type: 'SINGLE', optionType: 'TEXT', maxSelections: 1,
+     *   closeAt: Date.now() + 86_400_000,
+     *   options: [{ id: 'opt-1', content: '삼겹살', order: 0 }, { id: 'opt-2', content: '국밥', order: 1 }]
+     * }, { idempotencyKey: key });
+     */
+    async createVote(roomId, vote, options = {}) {
+        if (!roomId) {
+            throw new Error('roomId is required');
+        }
+        const { idempotencyKey } = options;
+        if (!idempotencyKey) {
+            // SDK 가 만들어 주면 호출자는 그 값을 볼 수 없다 — 타임아웃으로 응답만 유실됐을 때
+            // 같은 키로 재시도할 방법이 사라지고, 다음 호출이 투표를 하나 더 만든다.
+            throw new Error(
+                'createVote: options.idempotencyKey is required — '
+                + 'generate it once per vote and reuse the same value on retry '
+                + '(재시도에 같은 키를 넘겨야 투표가 중복 생성되지 않는다).'
+            );
+        }
+        const response = await this.apiClient.post(
+            `/api/v1/rooms/${roomId}/votes`,
+            vote,
+            undefined,
+            { 'X-Idempotency-Key': idempotencyKey }
+        );
+        return this._unwrapSuccessResponse(response);
+    }
+
+    /**
+     * 방의 투표 목록 (최신순).
+     *
+     * <p>목록 항목에는 선택지별 집계도 내 선택도 없다 — 참여자 수({@code responseCount})만 있다.
+     * 결과를 보려면 {@link #getVote} 를 쓴다.</p>
+     *
+     * @param {string} roomId - 채팅방 ID
+     * @param {Object} [options]
+     * @param {string} [options.cursor] - 이전 응답의 {@code nextCursor} 를 <b>그대로</b>. 불투명 문자열이라 파싱하지 않는다
+     * @param {number} [options.limit=20] - 최대 100. 초과분은 서버가 조용히 100 으로 보정한다(에러 아님)
+     * @returns {Promise<{items: Array<Object>, nextCursor: ?string}>} {@code items} 가 비면 끝
+     */
+    async getVotes(roomId, options = {}) {
+        const { cursor, limit } = options;
+        const response = await this.apiClient.get(`/api/v1/rooms/${roomId}/votes`, { cursor, limit });
+        return this._unwrapSuccessResponse(response);
+    }
+
+    /**
+     * 투표 단건 + 집계.
+     *
+     * <p>{@code revealed: false} 일 때의 {@code count}/{@code ratio} 0 은 「참여자가 없다」가 아니라
+     * <b>서버가 가린 값</b>이다. 결과 공개 조건은 「내가 응답했다」 또는 「마감됐다」. 비공개 상태에서도
+     * {@code myOptionIds} 는 채워진다(재투표 화면용).</p>
+     *
+     * <p>{@code ratio} 의 분모는 응답자 수이지 총 선택 수가 아니다 — 복수 선택에서 <b>합이 100을 넘는 것이
+     * 정상</b>이고 화면이 「복수 응답」임을 표기해야 한다.</p>
+     *
+     * <p>마감 여부는 {@code status} 만으로 정해지지 않는다. 서버 자동 마감이 미구현이라
+     * {@code status: 'OPEN'} 인데 {@code closeAt} 이 지난 투표가 있고 그건 마감된 것으로 동작한다 —
+     * <b>{@code status} 와 {@code closeAt} 을 함께</b> 봐야 한다.</p>
+     *
+     * @param {string} roomId - 채팅방 ID
+     * @param {string} voteId - 투표 ID
+     * @returns {Promise<Object>}
+     */
+    async getVote(roomId, voteId) {
+        const response = await this.apiClient.get(`/api/v1/rooms/${roomId}/votes/${voteId}`);
+        return this._unwrapSuccessResponse(response);
+    }
+
+    /**
+     * 투표 수정 — <b>부분 수정이 아니다.</b> 등록 폼 전체를 보낸다({@link #createVote} 와 같은 타입).
+     *
+     * <p>{@code maxSelections}↔{@code type}, {@code optionType}↔{@code imageUrl} 이 서로 묶여 있어
+     * 한쪽만 바꾸면 판독 불가능한 투표가 만들어지기 때문이다.</p>
+     *
+     * <p>조건 둘: <b>개설자만</b> · <b>참여자가 0명일 때만</b>. 표가 들어오면
+     * {@code VOTE_NOT_EDITABLE}(409), 개설자가 아니면 {@code VOTE_MODIFY_FORBIDDEN}(403).
+     * 선택지 {@code id} 를 이전 값과 맞출 필요는 없다 — 참여자가 0명이라 어긋날 응답이 없다.</p>
+     *
+     * @param {string} roomId - 채팅방 ID
+     * @param {string} voteId - 투표 ID
+     * @param {Object} vote - 투표 폼 (생성과 동일)
+     * @returns {Promise<Object>}
+     */
+    async updateVote(roomId, voteId, vote) {
+        const response = await this.apiClient.patch(`/api/v1/rooms/${roomId}/votes/${voteId}`, vote);
+        return this._unwrapSuccessResponse(response);
+    }
+
+    /**
+     * 투표 삭제 — 개설자면 된다. 마감 여부도 참여자 유무도 보지 않는다.
+     *
+     * <p>채팅에 이미 게시된 투표 카드는 <b>그대로 남는다</b>(서버가 발행된 메시지를 고칠 수 없다).
+     * 원본 카드를 누르면 404 가 오고, 이 404 를 「취소된 투표」로 표시하는 것은 화면 몫이다.
+     * 삭제 사실은 별도의 취소 카드 메시지로도 방에 발행된다.</p>
+     *
+     * @param {string} roomId - 채팅방 ID
+     * @param {string} voteId - 투표 ID
+     * @returns {Promise<void>} 본문 없음 (204)
+     */
+    async deleteVote(roomId, voteId) {
+        await this.apiClient.delete(`/api/v1/rooms/${roomId}/votes/${voteId}`);
+    }
+
+    /**
+     * 수동 마감 (개설자만).
+     *
+     * <p>본문이 없으므로 마감 후 결과를 보려면 {@link #getVote} 를 다시 호출한다.
+     * 이미 마감이면 {@code VOTE_ALREADY_CLOSED}(409), 개설자가 아니면 {@code VOTE_CLOSE_FORBIDDEN}(403)
+     * — 수정의 403 과 code 가 다르다.</p>
+     *
+     * @param {string} roomId - 채팅방 ID
+     * @param {string} voteId - 투표 ID
+     * @returns {Promise<void>} 본문 없음 (204)
+     */
+    async closeVote(roomId, voteId) {
+        await this.apiClient.patch(`/api/v1/rooms/${roomId}/votes/${voteId}/close`);
+    }
+
+    /**
+     * 투표 접수 · 재투표 — <b>같은 메서드</b>다.
+     *
+     * <p>재투표는 새 자원을 만들지 않고 기존 응답을 덮어쓴다. 클라이언트가 최초/재투표를 구분해 보낼 필요가
+     * 없고, 같은 값을 여러 번 보내도 결과가 같다. 응답에 <b>갱신된 집계가 함께</b> 오므로 별도 폴링이 필요 없다.</p>
+     *
+     * <p>빈 배열은 「투표 취소」로 해석되지 않는다 — 투표를 취소하는 경로는 없다(400).</p>
+     *
+     * <p>여러 규칙을 동시에 위반해도 서버는 <b>먼저 걸린 하나만</b> 응답한다. 하나를 고쳐 재시도하면
+     * 다음 위반이 드러날 수 있어, 모든 오류를 한 번에 수집하는 화면은 성립하지 않는다.</p>
+     *
+     * @param {string} roomId - 채팅방 ID
+     * @param {string} voteId - 투표 ID
+     * @param {string[]} optionIds - 고른 선택지. 빈 배열 불가
+     * @returns {Promise<Object>} 갱신된 투표 (집계 포함)
+     */
+    async submitVote(roomId, voteId, optionIds) {
+        const response = await this.apiClient.put(
+            `/api/v1/rooms/${roomId}/votes/${voteId}/responses`,
+            { optionIds }
+        );
+        return this._unwrapSuccessResponse(response);
+    }
+
+    /**
+     * 선택지 이미지 업로드.
+     *
+     * <p>돌려받은 {@code imageUrl} 을 <b>가공 없이 그대로</b> 생성·수정 본문의 {@code options[].imageUrl} 에
+     * 넣는다 — 서버가 문자열로 비교하고, 이 API 가 발급한 URL 만 통과한다. <b>채팅 첨부 URL 은 쓸 수 없다</b>
+     * (같은 버킷이라도 거절된다).</p>
+     *
+     * <p>형식은 매직넘버로 판정한다(PNG · JPEG · GIF · WEBP) — 신고된 Content-Type 과 확장자는 쓰이지 않으므로
+     * {@code .png} 로 이름 붙인 텍스트 파일은 거절된다. 10MB 를 넘으면 {@code VOTE_IMAGE_TOO_LARGE}.</p>
+     *
+     * <p>{@code optionType: 'TEXT_WITH_IMAGE'} 는 「이미지를 쓸 수 있다」는 상한이지 「모두 이미지다」가 아니다 —
+     * 이미지가 있는 선택지와 없는 선택지를 섞어도 되고 하나도 없어도 된다. 다만 {@code imageUrl} 이
+     * <b>빈 문자열</b>이면 거절된다(없으면 키를 아예 빼거나 {@code null}).</p>
+     *
+     * @param {string} roomId - 채팅방 ID
+     * @param {File|Blob} file - 이미지 파일
+     * @param {Object} [options]
+     * @param {Function} [options.onProgress] - {@code ({loaded, total, percent}) => void}
+     * @param {AbortSignal} [options.signal] - 취소용
+     * @returns {Promise<{imageUrl: string}>}
+     */
+    async uploadVoteImage(roomId, file, options = {}) {
+        if (!roomId) {
+            throw new Error('roomId is required');
+        }
+        if (!file) {
+            throw new Error('file is required');
+        }
+        const response = await this.apiClient.upload(
+            `/api/v1/rooms/${roomId}/votes/images`,
+            file,
+            { onProgress: options.onProgress, signal: options.signal }
+        );
+        return this._unwrapSuccessResponse(response);
+    }
+
     /**
      * 이모지 리액션 토글.
      * <p>한 사용자는 메시지당 하나의 이모지만 보유.
@@ -3274,17 +3505,29 @@ class ChatClient extends EventEmitter {
      * @private
      */
     _emitAssistantRoomProgress(roomId) {
+        // 이벤트 계약은 종전 그대로 둔다 — stream 목록은 getter 전용(이벤트로 매 틱 배열을 실어 보내면
+        // DELTA 마다 방 전체 스트림을 다시 만들어 흘리는 셈이다).
+        const { streams, ...event } = this._assistantRoomProgressPayload(roomId);
+        this.emit('assistantRoomProgress', event);
+    }
+
+    /**
+     * 방 단위 집계 payload 생성 — {@link #_emitAssistantRoomProgress} 와 {@link #getAssistantProgress} 의
+     * <b>공통 SSOT</b>. 두 곳에서 각자 조립하면 "이벤트로 본 상태"와 "물어봐서 본 상태"가 갈린다.
+     * @private
+     */
+    _assistantRoomProgressPayload(roomId) {
         const slots = this._assistantProgress.get(roomId);
         const alive = slots ? Array.from(slots.entries()) : [];
         if (alive.length === 0) {
-            this.emit('assistantRoomProgress', {
+            return {
                 roomId, active: false, streamCount: 0,
-                streamId: null, personaId: null, phase: null, label: null, text: null, textAvailable: true
-            });
-            return;
+                streamId: null, personaId: null, phase: null, label: null, text: null, textAvailable: true,
+                streams: []
+            };
         }
         const [streamId, slot] = alive.reduce((a, b) => (b[1].order > a[1].order ? b : a));
-        this.emit('assistantRoomProgress', {
+        return {
             roomId,
             active: true,
             streamCount: alive.length,
@@ -3293,8 +3536,43 @@ class ChatClient extends EventEmitter {
             phase: slot.phase,
             label: slot.phase ? (this._assistantPhaseLabels[slot.phase] || null) : null,
             text: slot.textAvailable ? (slot.text || null) : null,
-            textAvailable: slot.textAvailable
-        });
+            textAvailable: slot.textAvailable,
+            // stream 단위 UI(권장 (B))가 마운트 즉시 버블을 복원할 수 있도록 전부 싣는다.
+            // 도착 순서(order)대로 — 소비자가 "가장 최근"을 다시 계산하지 않아도 되게 한다.
+            streams: alive
+                .sort((a, b) => a[1].order - b[1].order)
+                .map(([id, s]) => ({
+                    streamId: id,
+                    personaId: s.personaId,
+                    phase: s.phase,
+                    label: s.phase ? (this._assistantPhaseLabels[s.phase] || null) : null,
+                    text: s.textAvailable ? (s.text || null) : null,
+                    textAvailable: s.textAvailable,
+                    resumed: s.resumed === true
+                }))
+        };
+    }
+
+    /**
+     * 방의 <b>현재</b> AI 진행 상태를 즉시 반환 (네트워크 호출 없음).
+     *
+     * <p>{@code assistantProgress} / {@code assistantRoomProgress} 는 transient 이벤트라, 방 화면을 나갔다
+     * 들어오면 프론트 상태가 비어 있는데 <b>이미 지나간 이벤트는 다시 오지 않는다</b>. 마운트 시점에 이걸
+     * 한 번 읽으면 다음 이벤트를 기다리지 않고 바로 그릴 수 있다 — 재입장 스냅샷(1 RTT)보다도 빠르다.</p>
+     *
+     * <p>반환 형태는 {@code assistantRoomProgress} 이벤트와 동일하고, stream 단위 UI 를 위해 {@code streams}
+     * 배열이 추가된다. 진행 중인 것이 없으면 {@code active:false} + 빈 배열.</p>
+     *
+     * @param {string} roomId - 채팅방 ID
+     * @returns {Object} { roomId, active, streamCount, streamId, personaId, phase, label, text, textAvailable, streams[] }
+     *
+     * @example
+     * // 방 화면 마운트 시 — 이벤트를 기다리지 않고 즉시 복원
+     * const p = client.chat.getAssistantProgress(roomId);
+     * if (p.active) renderBubble(p);
+     */
+    getAssistantProgress(roomId) {
+        return this._assistantRoomProgressPayload(roomId);
     }
 
     /**

package/src/talkflow/delegates.js

@@ -52,6 +52,10 @@ const CHAT_DELEGATE_METHODS = [
     'isSubscribed',
     'startTyping',
     'stopTyping',
+    // AI 진행 표시 — 마운트 즉시 복원용 동기 조회 + 수동 재개. 여기 없으면 최상위 클라이언트에서
+    // 런타임 undefined 가 된다(타입 선언만 있고 배선이 없으면 타입이 거짓말을 한다).
+    'getAssistantProgress',
+    'resumeAssistantStreams',
     'getAssistants',
     'getRoomAiMeta',
     'rateAssistantMessage',
@@ -65,7 +69,16 @@ const CHAT_DELEGATE_METHODS = [
     'deactivateRoomPmPrompt',
     'getRoomPmPromptVersions',
     'activateRoomPmPromptVersion',
-    'previewRoomPmPrompt'
+    'previewRoomPmPrompt',
+    // 투표 — 투표 서버는 클러스터 내부에만 있어 클라이언트가 직접 부를 수 없다. 전부 채팅 서버 경유.
+    'createVote',
+    'getVotes',
+    'getVote',
+    'updateVote',
+    'deleteVote',
+    'closeVote',
+    'submitVote',
+    'uploadVoteImage'
 ];
 
 const WEBRTC_DELEGATE_METHODS = [

package/src/utils/ApiClient.js

@@ -62,10 +62,12 @@ class ApiClient {
      * @param {Object} [options] - 옵션
      * @param {Object} [options.body] - 요청 본문
      * @param {Object} [options.params] - URL 파라미터
+     * @param {Object} [options.headers] - 이 요청에만 얹는 추가 헤더. 기본 헤더(Authorization 등)와 병합된다.
+     *   같은 이름이면 이 값이 이긴다 — 인증 헤더를 덮어쓰지 않도록 호출자가 주의한다.
      * @returns {Promise<Object>}
      */
     async request(method, path, options = {}) {
-        const { body, params } = options;
+        const { body, params, headers } = options;
 
         // URL 빌드
         let url = `${this.baseUrl}${path}`;
@@ -92,7 +94,7 @@ class ApiClient {
 
             response = await fetch(url, {
                 method,
-                headers: this._getHeaders(),
+                headers: headers ? { ...this._getHeaders(), ...headers } : this._getHeaders(),
                 body: body ? JSON.stringify(body) : undefined,
                 signal: controller.signal
             });
@@ -152,10 +154,12 @@ class ApiClient {
      * @param {string} path - API 경로
      * @param {Object} [body] - 요청 본문
      * @param {Object} [params] - URL 파라미터
+     * @param {Object} [headers] - 이 요청에만 얹는 추가 헤더 (예: {@code X-Idempotency-Key}).
+     *   기존 호출자는 인자를 넘기지 않으므로 동작이 바뀌지 않는다.
      * @returns {Promise<Object>}
      */
-    post(path, body, params) {
-        return this.request('POST', path, { body, params });
+    post(path, body, params, headers) {
+        return this.request('POST', path, { body, params, headers });
     }
 
     /**