@vibexnpm/talkx 3.0.1 → 3.0.3

package/package.json

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

package/src/chat/ChatClient.js

@@ -477,30 +477,41 @@ class ChatClient extends EventEmitter {
      * Rolling 누적 요약 갱신 트리거 (비동기).
      *
      * <p>방의 <b>누적 대화 요약</b>을 갱신한다 — {@link #summarizeWithAssistant}(페르소나가 최근 N개를 방에
-     * 어시스턴트 메시지로 발행)와 달리, 방당 1개의 통합 요약본(rollup)을 마지막 요약 지점 이후 <b>새 대화만
-     * 증분</b> 반영한다. 실제 요약은 서버 워커가 비동기로 수행하며, 완료/실패는 {@code summaryUpdate} 이벤트로
-     * 통지된다. 확정 내용은 {@link #getSummary} 로 조회한다(알림 payload 에는 내용이 없다).</p>
+     * 어시스턴트 메시지로 발행)와 달리, <b>포맷×언어별</b> 통합 요약본(rollup)을 마지막 요약 지점 이후 <b>새 대화만
+     * 증분</b> 반영한다(같은 방을 여러 포맷·언어로 보관). 실제 요약은 서버 워커가 비동기로 수행하며, 완료/실패는
+     * {@code summaryUpdate} 이벤트로 통지된다. 확정 내용은 {@link #getSummary} 로 조회한다(알림 payload 에는 내용이 없다).</p>
+     *
+     * <p><b>언어</b>: {@code lang} 미지정 시 서버가 요청자 언어(방 설정 ?? 사용자 선호)로 해소한다 — 자동번역으로
+     * 원문이 섞여도 그 언어로만 통합된다. {@code 'OFF'} 는 원문 유지. 응답에 해소된 {@code format}/{@code language} 가
+     * 담긴다.</p>
      *
      * <p>전체 히스토리를 보는 방(예: TEAM) 대상 기능이며, AI capability {@code TOOL_SUMMARIZE} 가 필요하다.</p>
      *
      * @param {string} roomId - 채팅방 ID
      * @param {Object} [options]
      * @param {string} [options.format] - 요약 포맷 ({@link SummarizeFormat}). 미지정/알 수 없는 값이면 서버가 {@code SHORT} 적용.
-     * @returns {Promise<{status: string}>} {@code status}: {@code 'STARTED'}(워커 시작 — {@code summaryUpdate} 대기) |
-     *   {@code 'ALREADY_RUNNING'}(이미 진행 중 — 재요청하지 말 것) | {@code 'NO_CHANGE'}(새 대화 없음 — 알림 발생 안 함)
+     * @param {string} [options.lang] - 출력 언어(BCP-47 예 {@code 'ko'}/{@code 'en'}, 또는 {@code 'OFF'}=원문). 미지정 시 요청자 언어로 해소.
+     * @returns {Promise<{status: string, format?: string, language?: string}>} {@code status}: {@code 'STARTED'}(워커 시작 —
+     *   {@code summaryUpdate} 대기) | {@code 'ALREADY_RUNNING'}(방에서 <b>다른</b> 요약이 진행 중일 수 있음 — 응답의
+     *   {@code format}/{@code language} 로 내 키인지 확인) | {@code 'NO_CHANGE'}(새 대화 없음 — 알림 발생 안 함).
+     *   {@code format}/{@code language}=이번 요청이 해소한 키(방 단위 경합 식별용).
      *
-     * @fires summaryUpdate - 완료/실패 시 { roomId, status: 'READY'|'NO_CHANGE'|'FAILED', format, updatedAt }
+     * @fires summaryUpdate - 완료/실패 시 { roomId, status: 'READY'|'NO_CHANGE'|'FAILED', format, language, updatedAt }
      *
      * @example
-     * const { status } = await chat.refreshSummary(roomId, { format: SummarizeFormat.MINUTES });
-     * if (status === 'STARTED' || status === 'ALREADY_RUNNING') showSpinner(); // summaryUpdate 를 기다린다
-     * else if (status === 'NO_CHANGE') toast('변경 사항이 없습니다');
+     * const { status, format, language } = await chat.refreshSummary(roomId, { format: SummarizeFormat.MINUTES, lang: 'ko' });
+     * if (status === 'STARTED') showSpinner();          // 내 키 진행 시작 — summaryUpdate 대기
+     * else if (status === 'ALREADY_RUNNING') {
+     *   // 방에서 다른 키가 도는 중일 수 있다. summaryUpdate 의 format+language 가 { minutes, ko } 가 아니면
+     *   // 그때 다시 refreshSummary 로 내 키를 요청한다(재요청 금지가 아니라 "내 키가 아니면 재요청").
+     *   showSpinner();
+     * } else if (status === 'NO_CHANGE') toast('변경 사항이 없습니다');
      */
     async refreshSummary(roomId, options = {}) {
-        const { format } = options;
+        const { format, lang } = options;
         const response = await this.apiClient.post(
             `/api/v1/rooms/${roomId}/summary/refresh`,
-            { format }
+            { format, lang }
         );
         return this._unwrapSuccessResponse(response);
     }
@@ -512,23 +523,32 @@ class ChatClient extends EventEmitter {
      * transient(저장 안 됨)라 유실될 수 있으므로 GET 으로 동기화한다. 아직 한 번도 요약된 적 없으면 {@code rollup}
      * 이 {@code null} 이다. segment 는 {@code afterSeq}/{@code size} 로 페이지네이션한다({@code hasNext}/{@code nextSeq}).</p>
      *
+     * <p>같은 방을 여러 포맷×언어로 보관하므로 {@code options.format}/{@code options.lang} 으로 골라 조회한다.
+     * {@code lang} 미지정 시 서버가 요청자 언어로 해소하고, 응답 {@code language} 로 <b>어느 언어 기준</b>인지
+     * 알려준다. {@code availableFormats} 는 <b>그 언어에 존재하는</b> 포맷만 담는다(타 언어로 fallback 하지 않음).
+     * 요청 포맷이 그 언어에 아직 없으면 {@code rollup=null}(refreshSummary 로 생성). {@code rollup.stale} 이
+     * {@code true} 면 그 키가 최신 대화를 아직 반영 안 함(refresh 로 최신화).</p>
+     *
      * @param {string} roomId - 채팅방 ID
      * @param {Object} [options]
+     * @param {string} [options.format] - 조회할 포맷({@link SummarizeFormat}). 미지정 시 그 언어의 기본(SHORT 우선). 미보유면 rollup=null.
+     * @param {string} [options.lang] - 조회할 언어(BCP-47 예 {@code 'ko'}, 또는 {@code 'OFF'}=원문). 미지정 시 요청자 언어로 해소(응답 {@code language}).
      * @param {number} [options.afterSeq] - segment 페이지 커서(exclusive). 미지정 시 처음부터.
      * @param {number} [options.size=50] - segment 페이지 크기(서버 상한 50).
-     * @returns {Promise<RoomSummaryView>} { rollup: { content, format, status, ... } | null, segments: [...], hasNext, nextSeq }
+     * @returns {Promise<RoomSummaryView>} { language, rollup | null, availableFormats, segments, hasNext, nextSeq }
      *
      * @example
-     * const view = await chat.getSummary(roomId);
-     * if (!view.rollup) return renderEmpty();          // 아직 요약 없음
-     * renderRollup(view.rollup);                        // rollup.status: 'IDLE' | 'RUNNING' | 'FAILED'
-     * renderSegments(view.segments, view.hasNext, view.nextSeq);
+     * const view = await chat.getSummary(roomId, { format: 'timeline', lang: 'ko' });
+     * console.log(view.language);                       // 'ko' (미지정 조회였다면 서버가 해소한 언어)
+     * if (!view.rollup) return renderEmpty();           // 그 포맷×언어 아직 없음 (availableFormats 로 탭 렌더)
+     * renderRollup(view.rollup, view.rollup.stale);     // stale 이면 "최신화" 유도
+     * renderTabs(view.availableFormats);                // 이 언어에 보유한 포맷 탭
      */
     async getSummary(roomId, options = {}) {
-        const { afterSeq, size } = options;
+        const { format, lang, afterSeq, size } = options;
         const response = await this.apiClient.get(
             `/api/v1/rooms/${roomId}/summary`,
-            { afterSeq, size }
+            { format, lang, afterSeq, size }
         );
         return this._unwrapSuccessResponse(response);
     }
@@ -2345,10 +2365,14 @@ class ChatClient extends EventEmitter {
     /**
      * Rolling 누적 요약 완료 알림(summary 채널) 수신 처리 — status 를 그대로 {@code summaryUpdate} 로 emit.
      *
-     * <p>서버 {@code SummaryStreamEvent}: {@code { status: 'READY'|'NO_CHANGE'|'FAILED', roomId, format?, updatedAt? }}.
+     * <p>서버 {@code SummaryStreamEvent}: {@code { status: 'READY'|'NO_CHANGE'|'FAILED', roomId, format?, language?, updatedAt? }}.
      * assistant-stream 과 달리 단계/토큰 누적이 없어 상태 관리 없이 그대로 통지한다. transient(저장 안 됨)라 UI 는
      * 이벤트를 신호로만 쓰고 확정 내용은 {@link #getSummary} 로 읽는다. {@code READY}=요약 갱신됨(→ getSummary),
      * {@code FAILED}=실패(재시도 가능), {@code NO_CHANGE}=변경 없음(대개 refreshSummary 응답에서 동기로 이미 받음).</p>
+     *
+     * <p><b>키 식별(format+language)</b>: 방 단위로 한 번에 한 요약만 도므로, 여러 포맷·언어를 요청했다면 이 이벤트의
+     * {@code format}+{@code language} 로 <b>어느 키</b>가 완료/실패했는지 가려 내 키가 아니면 다시 refreshSummary 한다.
+     * {@code READY}·{@code FAILED} 모두 키를 싣는다({@code NO_CHANGE} 는 없음).</p>
      * @private
      */
     _handleSummaryEvent(roomId, event) {
@@ -2356,7 +2380,8 @@ class ChatClient extends EventEmitter {
         this.emit('summaryUpdate', {
             roomId,
             status: event.status,                 // 'READY' | 'NO_CHANGE' | 'FAILED'
-            format: event.format || null,         // READY 만 포함(그 외 null)
+            format: event.format || null,         // READY/FAILED 포함(NO_CHANGE 는 null)
+            language: event.language || null,     // READY/FAILED 포함(NO_CHANGE 는 null) — 키 식별용
             updatedAt: event.updatedAt || null
         });
     }

package/types/index.d.ts

@@ -288,6 +288,8 @@ export interface TranslateToolRequest {
 export interface RefreshSummaryOptions {
     /** 요약 포맷 ({@link SummarizeFormat}). 미지정/알 수 없는 값이면 서버가 {@code SHORT} 적용. */
     format?: SummarizeFormatValue;
+    /** 출력 언어(BCP-47 예 {@code 'ko'}/{@code 'en'}, 또는 {@code 'OFF'}=원문). 미지정 시 서버가 요청자 언어로 해소. */
+    lang?: string;
 }
 
 /**
@@ -298,15 +300,24 @@ export interface RefreshSummaryResult {
     /**
      * <ul>
      *   <li>{@code 'STARTED'} — 요약 워커 시작됨({@code summaryUpdate} 대기).</li>
-     *   <li>{@code 'ALREADY_RUNNING'} — 이미 진행 중(중복 트리거 — 재요청하지 말 것).</li>
+     *   <li>{@code 'ALREADY_RUNNING'} — 방에서 요약이 진행 중(<b>다른</b> 포맷·언어일 수 있음). {@code format}/{@code language}
+     *       로 내 키인지 확인하고, {@code summaryUpdate} 가 내 키가 아니면 그때 다시 요청한다(무조건 재요청 금지 아님).</li>
      *   <li>{@code 'NO_CHANGE'} — 새 대화 없음(알림 발생 안 함; 직전 실패가 있었다면 자동 복구됨).</li>
      * </ul>
      */
     status: 'STARTED' | 'ALREADY_RUNNING' | 'NO_CHANGE';
+    /** 이번 요청이 해소한 포맷({@link SummarizeFormat} 소문자). 방 단위 경합 식별용. */
+    format?: string;
+    /** 이번 요청이 해소한 언어(소문자 BCP-47 / {@code 'OFF'}=원문). 방 단위 경합 식별용. */
+    language?: string;
 }
 
 /** {@link ChatClient.getSummary} 옵션. */
 export interface GetSummaryOptions {
+    /** 조회할 포맷({@link SummarizeFormat}). 미지정 시 그 언어의 기본(SHORT 우선). 미보유 포맷이면 rollup=null. */
+    format?: SummarizeFormatValue;
+    /** 조회할 언어(BCP-47 예 {@code 'ko'}, 또는 {@code 'OFF'}=원문). 미지정 시 요청자 언어로 해소(응답 {@code language}). */
+    lang?: string;
     /** segment 페이지 커서(exclusive). 미지정 시 처음부터. */
     afterSeq?: number;
     /** segment 페이지 크기(서버 상한 50). */
@@ -315,18 +326,20 @@ export interface GetSummaryOptions {
 
 /** Rolling 누적 요약 통합본 — {@link RoomSummaryView.rollup}. */
 export interface RoomSummaryRollup {
-    /** 요약 본문 ({@code format} 적용됨). */
+    /** 요약 본문 ({@code format} 적용 + {@code language} 로 통합됨). */
     content: string;
     /** 적용된 포맷 ({@link SummarizeFormat} 소문자). */
     format: string;
+    /** 이 rollup 의 언어(소문자 BCP-47 / {@code 'OFF'}=원문). {@link RoomSummaryView.language} 와 동일. */
+    language: string;
     /** rollup 이 커버하는 가장 오래된 지점. */
     coverStartAt: string | null;
     /** 마지막으로 요약된 지점. */
     watermarkAt: string | null;
     /** 전체 segment 수(페이지 총량 힌트). */
     segmentCount: number;
-    /** 진행 상태. {@code 'IDLE'}(완료/대기) | {@code 'RUNNING'}(요약 중) | {@code 'FAILED'}(실패). */
-    status: 'IDLE' | 'RUNNING' | 'FAILED';
+    /** 이 키(포맷×언어)가 최신 대화를 아직 반영 안 함(reducedSegmentCount < segmentCount) — refreshSummary 로 최신화 가능. */
+    stale: boolean;
     /** 마지막 갱신 시각. */
     updatedAt: string;
 }
@@ -352,9 +365,23 @@ export interface RoomSummarySegment {
  * 아직 한 번도 요약되지 않았으면 {@code rollup} 이 {@code null} 이고 {@code segments} 는 빈 배열이다.
  */
 export interface RoomSummaryView {
-    /** 통합 요약본. 최초 요약 전이면 null. */
+    /**
+     * 이 응답의 기준 언어(소문자 BCP-47 / {@code 'OFF'}=원문). {@code lang} 미지정 조회면 서버가 해소한 값이다 —
+     * {@code rollup}·{@code availableFormats} 가 이 언어 기준이다. 요약 이력이 없어도 서버가 요청자 언어로 해소해
+     * <b>항상</b> 채운다(never null).
+     */
+    language: string;
+    /**
+     * 방 전체 요약 프로세스 상태 — {@code 'IDLE'}(대기) | {@code 'RUNNING'}(요약 중) | {@code 'FAILED'}(실패).
+     * <b>방 단위(키별 아님)</b>: 방은 한 번에 한 키만 요약하므로, 지금 다른 포맷·언어를 요약 중이어도 {@code 'RUNNING'} 이다.
+     * 특정 rollup 의 최신 여부는 {@code rollup.stale} 로 판단한다(rollup 자체는 완료된 데이터). 요약 이력이 없으면 null.
+     */
+    roomStatus: 'IDLE' | 'RUNNING' | 'FAILED' | null;
+    /** 요청/기본 포맷의 통합 요약본. 그 포맷×언어로 아직 요약 안 됐으면 null(availableFormats 로 같은 언어의 다른 포맷 확인). */
     rollup: RoomSummaryRollup | null;
-    /** 구간 부분요약 페이지. */
+    /** 이 방이 <b>이 언어로</b> 보유한 포맷 목록(short/timeline/… — 탭 렌더용). 타 언어는 포함하지 않는다. */
+    availableFormats: string[];
+    /** 구간 부분요약 페이지(포맷 무관 공유). */
     segments: RoomSummarySegment[];
     /** 다음 segment 페이지 존재 여부. */
     hasNext: boolean;
@@ -370,8 +397,10 @@ export interface SummaryUpdateEvent {
     roomId: string;
     /** {@code 'READY'}(갱신됨 → getSummary) | {@code 'FAILED'}(실패 → 재시도 가능) | {@code 'NO_CHANGE'}(변경 없음). */
     status: 'READY' | 'NO_CHANGE' | 'FAILED';
-    /** 적용된 포맷. {@code READY} 만 포함, 그 외 null. */
+    /** 완료/실패한 포맷. {@code READY}·{@code FAILED} 포함, {@code NO_CHANGE} 는 null. */
     format: string | null;
+    /** 완료/실패한 언어(소문자 BCP-47 / {@code 'OFF'}). {@code READY}·{@code FAILED} 포함, {@code NO_CHANGE} 는 null — format 과 함께 키 식별. */
+    language: string | null;
     /** 갱신 시각. {@code READY} 만 포함, 그 외 null. */
     updatedAt: string | null;
 }