@vibexnpm/talkx 3.0.0 → 3.0.2

package/dist/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자. */