@vibexnpm/talkx 3.0.0 → 3.0.2

package/package.json

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

package/src/chat/ChatClient.js

@@ -473,6 +473,71 @@ class ChatClient extends EventEmitter {
         return this._unwrapSuccessResponse(response);
     }
 
+    /**
+     * Rolling 누적 요약 갱신 트리거 (비동기).
+     *
+     * <p>방의 <b>누적 대화 요약</b>을 갱신한다 — {@link #summarizeWithAssistant}(페르소나가 최근 N개를 방에
+     * 어시스턴트 메시지로 발행)와 달리, <b>포맷별</b> 통합 요약본(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>
+     *
+     * <p>같은 방을 여러 포맷으로 보관하므로 {@code options.format} 으로 골라 조회한다. 미지정 시 기본(SHORT 우선),
+     * 요청 포맷이 아직 없으면 {@code rollup=null}(이때 {@code availableFormats} 로 보유 포맷 확인 또는 refreshSummary
+     * 로 생성). {@code rollup.stale} 이 {@code true} 면 그 포맷이 최신 대화를 아직 반영 안 함(refresh 로 최신화).</p>
+     *
+     * @param {string} roomId - 채팅방 ID
+     * @param {Object} [options]
+     * @param {string} [options.format] - 조회할 포맷({@link SummarizeFormat}). 미지정 시 기본. 미보유 포맷이면 rollup=null.
+     * @param {number} [options.afterSeq] - segment 페이지 커서(exclusive). 미지정 시 처음부터.
+     * @param {number} [options.size=50] - segment 페이지 크기(서버 상한 50).
+     * @returns {Promise<RoomSummaryView>} { rollup | null, availableFormats, segments, hasNext, nextSeq }
+     *
+     * @example
+     * const view = await chat.getSummary(roomId, { format: 'timeline' });
+     * if (!view.rollup) return renderEmpty();          // 그 포맷 아직 없음 (availableFormats 로 탭 렌더)
+     * renderRollup(view.rollup, view.rollup.stale);     // stale 이면 "최신화" 유도
+     * renderTabs(view.availableFormats);                // 보유 포맷 탭
+     */
+    async getSummary(roomId, options = {}) {
+        const { format, afterSeq, size } = options;
+        const response = await this.apiClient.get(
+            `/api/v1/rooms/${roomId}/summary`,
+            { format, afterSeq, size }
+        );
+        return this._unwrapSuccessResponse(response);
+    }
+
     /**
      * 방 PM 프롬프트 레이어 조회 — PM_BACKSTAGE 방 전용.
      *
@@ -1598,6 +1663,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) => {
@@ -1628,6 +1699,7 @@ class ChatClient extends EventEmitter {
             readDestination,
             typingDestination,
             assistantStreamDestination,
+            summaryDestination,
             memberJoinedHandler,
             memberLeftHandler,
             subscribedAt: new Date()
@@ -1656,6 +1728,9 @@ class ChatClient extends EventEmitter {
         if (subscription.assistantStreamDestination) {
             this.connectionManager.unsubscribe(subscription.assistantStreamDestination);
         }
+        if (subscription.summaryDestination) {
+            this.connectionManager.unsubscribe(subscription.summaryDestination);
+        }
 
         // 멤버 변경 리스너 해제
         if (subscription.memberJoinedHandler) {
@@ -2272,6 +2347,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

@@ -282,6 +282,106 @@ export interface TranslateToolRequest {
     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 {
+    /** 조회할 포맷({@link SummarizeFormat}). 미지정 시 기본(SHORT 우선). 미보유 포맷이면 rollup=null. */
+    format?: SummarizeFormatValue;
+    /** 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;
+    /** 이 포맷이 최신 대화를 아직 반영 안 함(reducedSegmentCount < segmentCount) — refreshSummary 로 최신화 가능. */
+    stale: boolean;
+    /** 진행 상태. {@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(availableFormats 로 다른 포맷 확인). */
+    rollup: RoomSummaryRollup | null;
+    /** 이 방이 보유한 포맷 목록(short/timeline/… — 탭 렌더용). */
+    availableFormats: string[];
+    /** 구간 부분요약 페이지(포맷 무관 공유). */
+    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;
+}
+
 /**
  * PM 프롬프트 레이어 — 서버 {@code PmPromptLayerResponse}.
  *
@@ -1131,6 +1231,8 @@ export interface TalkFlowClientEvents {
     messageRead: MessageReadEventPayload;
     typing: TypingEvent;
     assistantProgress: AssistantProgressEvent;
+    /** Rolling 누적 요약 완료/실패 통지 (transient) — refreshSummary 후. */
+    summaryUpdate: SummaryUpdateEvent;
     memberJoined: MemberChangePayload;
     memberLeft: MemberChangePayload;
     roomSubscribed: { roomId: string };
@@ -1245,6 +1347,8 @@ export interface ChatClientEvents {
     messageRead: MessageReadEventPayload;
     typing: TypingEvent;
     assistantProgress: AssistantProgressEvent;
+    /** Rolling 누적 요약 완료/실패 통지 (transient) — refreshSummary 후. */
+    summaryUpdate: SummaryUpdateEvent;
 }
 
 /**
@@ -1310,6 +1414,10 @@ export class ChatClient implements SdkEventEmitter<ChatClientEvents> {
     summarizeWithAssistant(roomId: string, options: SummarizeToolRequest): 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자. */
@@ -1651,6 +1759,10 @@ export default class TalkFlowClient implements SdkEventEmitter<TalkFlowClientEve
     summarizeWithAssistant(roomId: string, options: SummarizeToolRequest): 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자. */