@vibexnpm/talkx 2.5.0 → 3.0.1

package/package.json

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

package/src/chat/ChatClient.js

@@ -438,40 +438,97 @@ class ChatClient extends EventEmitter {
     }
 
     /**
-     * 어시스턴트로 특정 메시지 번역 (버튼 진입점, 동기).
+     * 특정 메시지 온디맨드 번역 (버튼 진입점, 동기).
      *
-     * <p>지정한 페르소나가 {@code sourceMessageId} 메시지를 {@code targetLang} 으로 번역해
-     * 방에 어시스턴트 메시지로 broadcast 한다. 생성된 메시지는 일반 {@code chatMessage}
-     * 이벤트로도 수신된다.</p>
+     * <p>{@code sourceMessageId} 메시지(텍스트/이미지/문서)를 {@code targetLang} 으로 번역해 요청자에게만
+     * 반환한다. 이미지는 이미지 속 텍스트를, 문서(PDF/DOCX/XLSX/PPTX 등)는 파일 안의 텍스트를 서버가 추출해
+     * 번역한다. 방에 메시지를 저장하거나 {@code chatMessage} 이벤트를 broadcast 하지 않는다. 읽을 텍스트가
+     * 없거나 문서가 너무 크면 에러를 반환한다.</p>
      *
      * @param {string} roomId - 채팅방 ID
      * @param {Object} options
-     * @param {string} options.personaId - 번역을 수행할 어시스턴트 ID ({@link #getAssistants} 의 {@code id}). 필수.
-     * @param {string} options.sourceMessageId - 번역 대상 메시지의 {@code messageId}. 필수.
-     * @param {string} [options.targetLang] - 목표 언어 (예: {@code 'en'}, {@code '日本語'}). 미지정 시 서버 정책.
-     * @returns {Promise<{outcome: string, messageId: (string|null), detail: (string|null)}>}
-     *   {@code outcome}: {@code 'EMITTED'} (생성됨, {@code messageId} 존재) |
-     *   {@code 'SKIPPED'} / {@code 'FAILED'} ({@code detail} 에 사유).
+     * @param {string} options.sourceMessageId - 번역 대상 메시지의 {@code messageId} (텍스트/이미지/문서). 필수.
+     * @param {string} options.targetLang - 목표 언어 (예: {@code 'en'}, {@code '日本語'}). 필수.
+     * @returns {Promise<{translatedText: string, sourceMessageId: string, targetLang: string}>}
      *
      * @example
      * const result = await chat.translateWithAssistant(roomId, {
-     *   personaId,
      *   sourceMessageId: msg.messageId,
      *   targetLang: 'en'
      * });
      */
     async translateWithAssistant(roomId, options = {}) {
-        const { personaId, targetLang, sourceMessageId } = options;
-        if (!personaId) {
-            throw new Error('translateWithAssistant requires options.personaId');
-        }
+        const { targetLang, sourceMessageId } = options;
         if (!sourceMessageId) {
             throw new Error('translateWithAssistant requires options.sourceMessageId');
         }
+        if (!targetLang) {
+            throw new Error('translateWithAssistant requires options.targetLang');
+        }
 
         const response = await this.apiClient.post(
             `/api/v1/rooms/${roomId}/assistant/tools/translate`,
-            { personaId, targetLang, sourceMessageId }
+            { targetLang, sourceMessageId }
+        );
+        return this._unwrapSuccessResponse(response);
+    }
+
+    /**
+     * Rolling 누적 요약 갱신 트리거 (비동기).
+     *
+     * <p>방의 <b>누적 대화 요약</b>을 갱신한다 — {@link #summarizeWithAssistant}(페르소나가 최근 N개를 방에
+     * 어시스턴트 메시지로 발행)와 달리, 방당 1개의 통합 요약본(rollup)을 마지막 요약 지점 이후 <b>새 대화만
+     * 증분</b> 반영한다. 실제 요약은 서버 워커가 비동기로 수행하며, 완료/실패는 {@code summaryUpdate} 이벤트로
+     * 통지된다. 확정 내용은 {@link #getSummary} 로 조회한다(알림 payload 에는 내용이 없다).</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'}(새 대화 없음 — 알림 발생 안 함)
+     *
+     * @fires summaryUpdate - 완료/실패 시 { roomId, status: 'READY'|'NO_CHANGE'|'FAILED', format, 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('변경 사항이 없습니다');
+     */
+    async refreshSummary(roomId, options = {}) {
+        const { format } = options;
+        const response = await this.apiClient.post(
+            `/api/v1/rooms/${roomId}/summary/refresh`,
+            { format }
+        );
+        return this._unwrapSuccessResponse(response);
+    }
+
+    /**
+     * Rolling 누적 요약 조회 — 통합본(rollup) + 구간 부분요약(segments) 페이지. 저장된 요약의 단일 진실 소스.
+     *
+     * <p>{@code summaryUpdate}({@code status:'READY'}) 수신 후, 그리고 화면 진입/재접속 시 호출한다 — 알림은
+     * transient(저장 안 됨)라 유실될 수 있으므로 GET 으로 동기화한다. 아직 한 번도 요약된 적 없으면 {@code rollup}
+     * 이 {@code null} 이다. segment 는 {@code afterSeq}/{@code size} 로 페이지네이션한다({@code hasNext}/{@code nextSeq}).</p>
+     *
+     * @param {string} roomId - 채팅방 ID
+     * @param {Object} [options]
+     * @param {number} [options.afterSeq] - segment 페이지 커서(exclusive). 미지정 시 처음부터.
+     * @param {number} [options.size=50] - segment 페이지 크기(서버 상한 50).
+     * @returns {Promise<RoomSummaryView>} { rollup: { content, format, status, ... } | null, 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);
+     */
+    async getSummary(roomId, options = {}) {
+        const { afterSeq, size } = options;
+        const response = await this.apiClient.get(
+            `/api/v1/rooms/${roomId}/summary`,
+            { afterSeq, size }
         );
         return this._unwrapSuccessResponse(response);
     }
@@ -1601,6 +1658,12 @@ class ChatClient extends EventEmitter {
             this._handleAssistantStreamEvent(roomId, event);
         });
 
+        // Rolling 누적 요약 완료 알림 구독 — refreshSummary 완료/실패를 summaryUpdate 이벤트로 통지(transient).
+        const summaryDestination = WebSocketPaths.getChatSummaryDestination(roomId);
+        await this.connectionManager.subscribe(summaryDestination, (event) => {
+            this._handleSummaryEvent(roomId, event);
+        });
+
         // 멤버 변경 이벤트 — roomList 이벤트를 방 수준으로 변환하여 자동 emit
         // 서버가 members 배열(입장/퇴장 사용자들) + participantCount(정확한 인원수) 포함
         const memberJoinedHandler = (event) => {
@@ -1631,6 +1694,7 @@ class ChatClient extends EventEmitter {
             readDestination,
             typingDestination,
             assistantStreamDestination,
+            summaryDestination,
             memberJoinedHandler,
             memberLeftHandler,
             subscribedAt: new Date()
@@ -1659,6 +1723,9 @@ class ChatClient extends EventEmitter {
         if (subscription.assistantStreamDestination) {
             this.connectionManager.unsubscribe(subscription.assistantStreamDestination);
         }
+        if (subscription.summaryDestination) {
+            this.connectionManager.unsubscribe(subscription.summaryDestination);
+        }
 
         // 멤버 변경 리스너 해제
         if (subscription.memberJoinedHandler) {
@@ -2275,6 +2342,25 @@ class ChatClient extends EventEmitter {
         // 그 외 미지 type 은 무시(forward-compat).
     }
 
+    /**
+     * Rolling 누적 요약 완료 알림(summary 채널) 수신 처리 — status 를 그대로 {@code summaryUpdate} 로 emit.
+     *
+     * <p>서버 {@code SummaryStreamEvent}: {@code { status: 'READY'|'NO_CHANGE'|'FAILED', roomId, format?, updatedAt? }}.
+     * assistant-stream 과 달리 단계/토큰 누적이 없어 상태 관리 없이 그대로 통지한다. transient(저장 안 됨)라 UI 는
+     * 이벤트를 신호로만 쓰고 확정 내용은 {@link #getSummary} 로 읽는다. {@code READY}=요약 갱신됨(→ getSummary),
+     * {@code FAILED}=실패(재시도 가능), {@code NO_CHANGE}=변경 없음(대개 refreshSummary 응답에서 동기로 이미 받음).</p>
+     * @private
+     */
+    _handleSummaryEvent(roomId, event) {
+        if (!event || !event.status) return;
+        this.emit('summaryUpdate', {
+            roomId,
+            status: event.status,                 // 'READY' | 'NO_CHANGE' | 'FAILED'
+            format: event.format || null,         // READY 만 포함(그 외 null)
+            updatedAt: event.updatedAt || null
+        });
+    }
+
     /**
      * AI 진행 상태 갱신 + TTL 타이머 재무장 — {@code expiresAt}(epochMillis) 기반, 누락/이상 시 fallback.
      * {@code fields}={phase, text}(PHASE/DELTA 가 해소해 전달 — DELTA 는 직전 phase 유지 + 누적 text).

package/src/constants.js

@@ -321,6 +321,8 @@ export const WebSocketPaths = {
     getChatTypingDestination: (roomId) => `/topic/chat/${roomId}/typing`,
     // AI 진행 표시(생각중/검색중/작성중) + 토큰 스트리밍 — typing 과 별개 채널(가산 UX 레이어).
     getChatAssistantStreamDestination: (roomId) => `/topic/chat/${roomId}/assistant-stream`,
+    // Rolling 누적 요약 완료 알림(READY/NO_CHANGE/FAILED) — refreshSummary 의 비동기 완료 통지 채널.
+    getChatSummaryDestination: (roomId) => `/topic/chat/${roomId}/summary`,
 
     // Room list (카톡 스타일 리스트 실시간 업데이트)
     // 서버가 convertAndSendToUser(userId, "/queue/rooms", event) 로 전송

package/src/talkflow/delegates.js

@@ -51,6 +51,8 @@ const CHAT_DELEGATE_METHODS = [
     'rateAssistantMessage',
     'summarizeWithAssistant',
     'translateWithAssistant',
+    'refreshSummary',
+    'getSummary',
     'getRoomPmPrompt',
     'upsertRoomPmPrompt',
     'activateRoomPmPrompt',

package/src/talkflow/eventForwarding.js

@@ -16,6 +16,7 @@ const CHAT_EVENT_MAP = [
     ['messageRead', 'messageRead'],
     ['typing', 'typing'],
     ['assistantProgress', 'assistantProgress'],
+    ['summaryUpdate', 'summaryUpdate'],
     ['memberJoined', 'memberJoined'],
     ['memberLeft', 'memberLeft'],
     ['roomSubscribed', 'roomSubscribed'],

package/types/index.d.ts

@@ -236,7 +236,7 @@ export interface AssistantPersonaResponse {
 
 /**
  * 어시스턴트 도구 실행 결과 — 서버 {@code AssistantToolResult}.
- * {@link ChatClient.summarizeWithAssistant} / {@link ChatClient.translateWithAssistant} 반환.
+ * {@link ChatClient.summarizeWithAssistant} 반환.
  */
 export interface AssistantToolResult {
     /**
@@ -254,6 +254,16 @@ export interface AssistantToolResult {
     detail: string | null;
 }
 
+/** {@link ChatClient.translateWithAssistant} 반환 — 요청자 전용 온디맨드 번역 응답. */
+export interface OnDemandTranslationResponse {
+    /** 번역된 텍스트. */
+    translatedText: string;
+    /** 번역 대상 원본 메시지의 {@code messageId}. */
+    sourceMessageId: string;
+    /** 요청한 목표 언어. */
+    targetLang: string;
+}
+
 /** {@link ChatClient.summarizeWithAssistant} 옵션 — 서버 {@code SummarizeToolRequest}. */
 export interface SummarizeToolRequest {
     /** 요약을 수행할 어시스턴트 ID ({@link AssistantPersonaResponse.id}). 필수. */
@@ -266,12 +276,104 @@ export interface SummarizeToolRequest {
 
 /** {@link ChatClient.translateWithAssistant} 옵션 — 서버 {@code TranslateToolRequest}. */
 export interface TranslateToolRequest {
-    /** 번역을 수행할 어시스턴트 ID ({@link AssistantPersonaResponse.id}). 필수. */
-    personaId: string;
     /** 번역 대상 메시지의 {@code messageId}. 필수. */
     sourceMessageId: string;
-    /** 목표 언어 (예: {@code 'en'}). 미지정 시 서버 정책. */
-    targetLang?: string;
+    /** 목표 언어 (예: {@code 'en'}). 필수. */
+    targetLang: string;
+}
+
+// ── Rolling 누적 요약 (refreshSummary / getSummary / summaryUpdate) ──
+
+/** {@link ChatClient.refreshSummary} 옵션. */
+export interface RefreshSummaryOptions {
+    /** 요약 포맷 ({@link SummarizeFormat}). 미지정/알 수 없는 값이면 서버가 {@code SHORT} 적용. */
+    format?: SummarizeFormatValue;
+}
+
+/**
+ * {@link ChatClient.refreshSummary} 반환 — 비동기 접수 결과(서버 {@code SummaryRefreshResult}).
+ * 실제 완료는 {@code summaryUpdate} 이벤트 + {@link ChatClient.getSummary} 로 확인한다.
+ */
+export interface RefreshSummaryResult {
+    /**
+     * <ul>
+     *   <li>{@code 'STARTED'} — 요약 워커 시작됨({@code summaryUpdate} 대기).</li>
+     *   <li>{@code 'ALREADY_RUNNING'} — 이미 진행 중(중복 트리거 — 재요청하지 말 것).</li>
+     *   <li>{@code 'NO_CHANGE'} — 새 대화 없음(알림 발생 안 함; 직전 실패가 있었다면 자동 복구됨).</li>
+     * </ul>
+     */
+    status: 'STARTED' | 'ALREADY_RUNNING' | 'NO_CHANGE';
+}
+
+/** {@link ChatClient.getSummary} 옵션. */
+export interface GetSummaryOptions {
+    /** segment 페이지 커서(exclusive). 미지정 시 처음부터. */
+    afterSeq?: number;
+    /** segment 페이지 크기(서버 상한 50). */
+    size?: number;
+}
+
+/** Rolling 누적 요약 통합본 — {@link RoomSummaryView.rollup}. */
+export interface RoomSummaryRollup {
+    /** 요약 본문 ({@code format} 적용됨). */
+    content: string;
+    /** 적용된 포맷 ({@link SummarizeFormat} 소문자). */
+    format: string;
+    /** rollup 이 커버하는 가장 오래된 지점. */
+    coverStartAt: string | null;
+    /** 마지막으로 요약된 지점. */
+    watermarkAt: string | null;
+    /** 전체 segment 수(페이지 총량 힌트). */
+    segmentCount: number;
+    /** 진행 상태. {@code 'IDLE'}(완료/대기) | {@code 'RUNNING'}(요약 중) | {@code 'FAILED'}(실패). */
+    status: 'IDLE' | 'RUNNING' | 'FAILED';
+    /** 마지막 갱신 시각. */
+    updatedAt: string;
+}
+
+/** Rolling 누적 요약 구간 부분요약 — {@link RoomSummaryView.segments} 항목. 항상 {@code contentFormat==='neutral'}. */
+export interface RoomSummarySegment {
+    /** segment 순번(0부터). 페이지 커서. */
+    seq: number;
+    /** 구간 부분요약 본문. */
+    content: string;
+    /** 항상 {@code 'neutral'}(format 미적용). */
+    contentFormat: string;
+    fromSentAt: string | null;
+    fromMessageId: string | null;
+    toSentAt: string | null;
+    toMessageId: string | null;
+    /** 이 구간이 담은 메시지 수. */
+    messageCount: number;
+}
+
+/**
+ * {@link ChatClient.getSummary} 반환 — 서버 {@code RoomSummaryView}.
+ * 아직 한 번도 요약되지 않았으면 {@code rollup} 이 {@code null} 이고 {@code segments} 는 빈 배열이다.
+ */
+export interface RoomSummaryView {
+    /** 통합 요약본. 최초 요약 전이면 null. */
+    rollup: RoomSummaryRollup | null;
+    /** 구간 부분요약 페이지. */
+    segments: RoomSummarySegment[];
+    /** 다음 segment 페이지 존재 여부. */
+    hasNext: boolean;
+    /** 다음 페이지 커서({@code getSummary} 의 {@code afterSeq} 로 사용). {@code hasNext === false} 면 null. */
+    nextSeq: number | null;
+}
+
+/**
+ * {@code summaryUpdate} 이벤트 payload — Rolling 요약 완료/실패 통지(서버 {@code SummaryStreamEvent}).
+ * transient(저장 안 됨) — 확정 내용은 {@link ChatClient.getSummary} 로 읽는다.
+ */
+export interface SummaryUpdateEvent {
+    roomId: string;
+    /** {@code 'READY'}(갱신됨 → getSummary) | {@code 'FAILED'}(실패 → 재시도 가능) | {@code 'NO_CHANGE'}(변경 없음). */
+    status: 'READY' | 'NO_CHANGE' | 'FAILED';
+    /** 적용된 포맷. {@code READY} 만 포함, 그 외 null. */
+    format: string | null;
+    /** 갱신 시각. {@code READY} 만 포함, 그 외 null. */
+    updatedAt: string | null;
 }
 
 /**
@@ -1123,6 +1225,8 @@ export interface TalkFlowClientEvents {
     messageRead: MessageReadEventPayload;
     typing: TypingEvent;
     assistantProgress: AssistantProgressEvent;
+    /** Rolling 누적 요약 완료/실패 통지 (transient) — refreshSummary 후. */
+    summaryUpdate: SummaryUpdateEvent;
     memberJoined: MemberChangePayload;
     memberLeft: MemberChangePayload;
     roomSubscribed: { roomId: string };
@@ -1237,6 +1341,8 @@ export interface ChatClientEvents {
     messageRead: MessageReadEventPayload;
     typing: TypingEvent;
     assistantProgress: AssistantProgressEvent;
+    /** Rolling 누적 요약 완료/실패 통지 (transient) — refreshSummary 후. */
+    summaryUpdate: SummaryUpdateEvent;
 }
 
 /**
@@ -1300,8 +1406,12 @@ export class ChatClient implements SdkEventEmitter<ChatClientEvents> {
     rateAssistantMessage(roomId: string, messageId: string, rating: number, comment?: string): Promise<void>;
     /** 어시스턴트로 대화 요약 (버튼 진입점, 동기). */
     summarizeWithAssistant(roomId: string, options: SummarizeToolRequest): Promise<AssistantToolResult>;
-    /** 어시스턴트로 특정 메시지 번역 (버튼 진입점, 동기). */
-    translateWithAssistant(roomId: string, options: TranslateToolRequest): Promise<AssistantToolResult>;
+    /** 특정 메시지 온디맨드 번역 (버튼 진입점, 동기, 요청자 전용 응답). */
+    translateWithAssistant(roomId: string, options: TranslateToolRequest): Promise<OnDemandTranslationResponse>;
+    /** Rolling 누적 요약 갱신 트리거 (비동기). 완료는 {@code summaryUpdate} 이벤트 + {@link getSummary} 로 확인. */
+    refreshSummary(roomId: string, options?: RefreshSummaryOptions): Promise<RefreshSummaryResult>;
+    /** Rolling 누적 요약 조회 — rollup + segment 페이지. 저장된 요약의 단일 진실 소스. */
+    getSummary(roomId: string, options?: GetSummaryOptions): Promise<RoomSummaryView>;
     /** 방 PM 프롬프트 레이어 조회 — PM_BACKSTAGE 방 전용, 참여자 전체. 미등록 시 404. */
     getRoomPmPrompt(roomId: string): Promise<PmPromptLayerResponse>;
     /** 방 PM 프롬프트 레이어 등록/수정 (upsert, 새 버전 자동 기록) — 방 주인(OWNER) 전용. content 1~2,000자. */
@@ -1641,8 +1751,12 @@ export default class TalkFlowClient implements SdkEventEmitter<TalkFlowClientEve
     rateAssistantMessage(roomId: string, messageId: string, rating: number, comment?: string): Promise<void>;
     /** 어시스턴트로 대화 요약 (버튼 진입점, 동기). */
     summarizeWithAssistant(roomId: string, options: SummarizeToolRequest): Promise<AssistantToolResult>;
-    /** 어시스턴트로 특정 메시지 번역 (버튼 진입점, 동기). */
-    translateWithAssistant(roomId: string, options: TranslateToolRequest): Promise<AssistantToolResult>;
+    /** 특정 메시지 온디맨드 번역 (버튼 진입점, 동기, 요청자 전용 응답). */
+    translateWithAssistant(roomId: string, options: TranslateToolRequest): Promise<OnDemandTranslationResponse>;
+    /** Rolling 누적 요약 갱신 트리거 (비동기). 완료는 {@code summaryUpdate} 이벤트 + {@link getSummary} 로 확인. */
+    refreshSummary(roomId: string, options?: RefreshSummaryOptions): Promise<RefreshSummaryResult>;
+    /** Rolling 누적 요약 조회 — rollup + segment 페이지. 저장된 요약의 단일 진실 소스. */
+    getSummary(roomId: string, options?: GetSummaryOptions): Promise<RoomSummaryView>;
     /** 방 PM 프롬프트 레이어 조회 — PM_BACKSTAGE 방 전용, 참여자 전체. 미등록 시 404. */
     getRoomPmPrompt(roomId: string): Promise<PmPromptLayerResponse>;
     /** 방 PM 프롬프트 레이어 등록/수정 (upsert, 새 버전 자동 기록) — 방 주인(OWNER) 전용. content 1~2,000자. */