@vibexnpm/talkx 5.3.0 → 5.4.0

package/package.json

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

package/src/chat/ChatClient.js

@@ -648,23 +648,24 @@ class ChatClient extends EventEmitter {
      * @param {Object} [options]
      * @param {string} [options.format] - 요약 포맷 ({@link SummarizeFormat}). 미지정/알 수 없는 값이면 서버가 {@code SHORT} 적용.
      * @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'|'INVALIDATED', format, languages, updatedAt }.
+     * @returns {Promise<{status: string, format?: string, language?: string}>} {@code status}: {@code 'QUEUED'} —
+     *   방 단위 durable work item 에 저장·병합됐다. local worker 포화여도 요청은 버려지지 않으며
+     *   최종 {@code READY|NO_CHANGE|NO_MESSAGES|FAILED} {@code summaryUpdate} 를 기다린다.
+     *   {@code format}/{@code language}=이번 호출이 work item 에 병합한 키.
+     *   ⚠️ 닫힌 목록이 아니다 — 분기에는 default 를 두고, 모르는 값에 스피너를 띄우지 마라.
+     * @throws {Error} HTTP 503 {@code SUMMARY_REFRESH_UNAVAILABLE} — durable 저장 자체가 실패했다.
+     *   간격을 두고 재시도하고 사용자에게는 일시 오류로 알린다.
+     *   {@code err.status}=503, {@code err.response.code}={@code 'SUMMARY_REFRESH_UNAVAILABLE'}.
+     *
+     * @fires summaryUpdate - { roomId, status: 'READY'|'NO_CHANGE'|'NO_MESSAGES'|'FAILED'|'INVALIDATED'|string, format, languages, updatedAt }.
      *   fan-out 으로 여러 언어를 한 번에 생성하므로 {@code languages} 는 배열(§S1). {@code INVALIDATED} 는 refreshSummary 가
      *   아니라 방 원문 삭제/편집으로 발생(요약이 통째로 폐기됨).
      *
      * @example
      * const { status } = await chat.refreshSummary(roomId, { format: SummarizeFormat.MINUTES, lang: 'ko' });
-     * if (status === 'STARTED') showSpinner();          // fan-out 진행 시작 — summaryUpdate 대기
-     * else if (status === 'ALREADY_RUNNING') {
-     *   // 방에서 다른 요약이 도는 중일 수 있다. 완료 이벤트 summaryUpdate 의 languages 에 내 언어가 없으면
-     *   // 그때 다시 refreshSummary 로 내 언어를 요청한다(재요청 금지가 아니라 "내 언어가 없으면 재요청").
-     *   showSpinner();
-     * } else if (status === 'NO_CHANGE') toast('변경 사항이 없습니다');
+     * if (status === 'QUEUED') showQueuedProgress();    // durable 접수 — summaryUpdate 대기
+     * else showUnknownSummaryState(status);             // 미래 서버 값은 추측하지 않는다
+     * // 503(SUMMARY_REFRESH_UNAVAILABLE)은 durable 접수 실패 — try/catch로 받고 간격을 두고 재시도.
      */
     async refreshSummary(roomId, options = {}) {
         const { format, lang } = options;
@@ -678,9 +679,10 @@ class ChatClient extends EventEmitter {
     /**
      * 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>terminal {@code summaryUpdate} 수신 후, 화면 진입/재접속 시, 그리고 {@code QUEUED} 뒤 앱이 정한 완료
+     * timeout에 <b>한 번</b> 호출한다 — 알림은 transient(저장 안 됨)라 유실될 수 있으므로 GET 으로 동기화한다.
+     * 주기적 polling은 하지 않는다. 아직 한 번도 요약된 적 없으면 {@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>인지
@@ -694,7 +696,7 @@ class ChatClient extends EventEmitter {
      * @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>} { language, rollup | null, availableFormats, segments, hasNext, nextSeq }
+     * @returns {Promise<RoomSummaryView>} { language, roomStatus, rollup | null, availableFormats, segments, hasNext, nextSeq }
      *
      * @example
      * const view = await chat.getSummary(roomId, { format: 'timeline', lang: 'ko' });
@@ -3392,24 +3394,27 @@ class ChatClient extends EventEmitter {
     /**
      * Rolling 누적 요약 완료 알림(summary 채널) 수신 처리 — status 를 그대로 {@code summaryUpdate} 로 emit.
      *
-     * <p>서버 {@code SummaryStreamEvent}: {@code { status: 'READY'|'NO_CHANGE'|'FAILED'|'INVALIDATED', roomId, format?, languages?, updatedAt? }}.
+     * <p>서버 {@code SummaryStreamEvent}: {@code { status: 'READY'|'NO_CHANGE'|'NO_MESSAGES'|'FAILED'|'INVALIDATED'|string, roomId, format?, languages?, updatedAt? }}.
      * assistant-stream 과 달리 단계/토큰 누적이 없어 상태 관리 없이 그대로 통지한다. transient(저장 안 됨)라 UI 는
      * 이벤트를 신호로만 쓰고 확정 내용은 {@link #getSummary} 로 읽는다. {@code READY}=요약 갱신됨(→ getSummary),
-     * {@code FAILED}=실패(재시도 가능), {@code NO_CHANGE}=변경 없음(대개 refreshSummary 응답에서 동기로 이미 받음),
+     * {@code FAILED}=실패(재시도 가능), {@code NO_CHANGE}=durable 작업이 변경 없이 완료,
+     * {@code NO_MESSAGES}=해당 키에 요약할 대화 없음,
      * {@code INVALIDATED}=방 원문 삭제/편집으로 요약이 통째로 버려짐(→ 요약 화면을 즉시 비우고, 필요 시 refreshSummary 로 재생성).</p>
      *
      * <p><b>키 식별(format+languages)</b>: 한 refresh 가 방 활성 언어들을 fan-out 으로 한 번에 생성하므로(§S1), 완료
-     * 이벤트의 {@code languages} 에 내 언어가 있으면 {@code getSummary({ format, lang })} 로 읽는다. {@code READY}·
-     * {@code FAILED} 모두 언어 목록을 싣는다({@code NO_CHANGE}·{@code INVALIDATED} 는 없음).</p>
+     * 이벤트의 {@code languages} 에 내 언어가 있으면 {@code getSummary({ format, lang })} 로 읽는다.
+     * {@code READY}·{@code NO_CHANGE}·{@code NO_MESSAGES}·{@code FAILED} 모두 언어 목록을 싣는다
+     * ({@code INVALIDATED} 만 없음). 알 수 없는 미래 status도 그대로 전달하므로 소비자는 default 분기와
+     * one-shot {@code getSummary} 재동기화를 둔다.</p>
      * @private
      */
     _handleSummaryEvent(roomId, event) {
         if (!event || !event.status) return;
         this.emit('summaryUpdate', {
             roomId,
-            status: event.status,                 // 'READY' | 'NO_CHANGE' | 'FAILED' | 'INVALIDATED'
-            format: event.format || null,         // READY/FAILED 포함(NO_CHANGE·INVALIDATED 는 null)
-            languages: event.languages || null,   // fan-out 으로 생성/최신화된 언어 목록(READY/FAILED). 그 외 null
+            status: event.status,                 // known status + future server values (pass-through)
+            format: event.format || null,         // READY/NO_CHANGE/NO_MESSAGES/FAILED 포함
+            languages: event.languages || null,   // READY/NO_CHANGE/NO_MESSAGES/FAILED 처리 언어 목록
             updatedAt: event.updatedAt || null
         });
     }

package/src/constants.js

@@ -364,7 +364,7 @@ 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 의 비동기 완료 통지 채널.
+    // Rolling 누적 요약 종결 알림(READY/NO_CHANGE/NO_MESSAGES/FAILED) — refreshSummary 비동기 완료 채널.
     getChatSummaryDestination: (roomId) => `/topic/chat/${roomId}/summary`,
 
     // Room list (카톡 스타일 리스트 실시간 업데이트)

package/types/__typetests__/singleMessageAttachment.types.ts

@@ -13,6 +13,7 @@ import type {
     ChatMessage,
     ChatMessageTypeValue,
     FileMetaData,
+    RoomSummaryView,
     SendFileInfo
 } from '../index';
 import { ChatMessageType } from '../index';
@@ -65,4 +66,24 @@ function legacyResponseFile(f: FileMetaData): string | undefined {
     return f.fileId;
 }
 
-export { category, viaTopLevel, mixed, gallery, document, render, uploadThenSend, optimistic, legacyResponseFile };
+// 7) 서버 rolling 배포를 견디도록 summary 상태는 열린 문자열 union이어야 한다.
+function renderSummaryStatus(status: NonNullable<RoomSummaryView['roomStatus']>): string {
+    switch (status) {
+        case 'QUEUED': return 'queued';
+        case 'IDLE': return 'idle';
+        case 'RUNNING': return 'running';
+        case 'FAILED': return 'failed';
+        case 'NO_MESSAGES': return 'empty';
+        default: {
+            // @ts-expect-error 열린 union이므로 알려진 값만 처리해도 exhaustive never가 될 수 없다.
+            const futureServerStatus: never = status;
+            void futureServerStatus;
+            return 'unknown';
+        }
+    }
+}
+
+const futureSummaryStatus: NonNullable<RoomSummaryView['roomStatus']> = 'FUTURE_SERVER_STATUS';
+
+export { category, viaTopLevel, mixed, gallery, document, render, uploadThenSend, optimistic, legacyResponseFile,
+    renderSummaryStatus, futureSummaryStatus };

package/types/index.d.ts

@@ -327,16 +327,20 @@ export interface RefreshSummaryOptions {
 export interface RefreshSummaryResult {
     /**
      * <ul>
-     *   <li>{@code 'STARTED'} — 요약 워커 시작됨({@code summaryUpdate} 대기).</li>
-     *   <li>{@code 'ALREADY_RUNNING'} — 방에서 요약이 진행 중(<b>다른</b> 포맷·언어일 수 있음). {@code format}/{@code language}
-     *       로 내 키인지 확인하고, {@code summaryUpdate} 가 내 키가 아니면 그때 다시 요청한다(무조건 재요청 금지 아님).</li>
-     *   <li>{@code 'NO_CHANGE'} — 새 대화 없음(알림 발생 안 함; 직전 실패가 있었다면 자동 복구됨).</li>
+     *   <li>{@code 'QUEUED'} — 방 단위 durable work item 에 저장·병합됐다. pod 실행 슬롯이 포화여도
+     *       요청은 버려지지 않으며, 최종 {@code READY|NO_CHANGE|NO_MESSAGES|FAILED} {@code summaryUpdate} 를 기다린다.</li>
      * </ul>
+     *
+     * <p>durable 저장 자체가 실패하면 성공 결과가 아니라 <b>HTTP 503</b>
+     * ({@code SUMMARY_REFRESH_UNAVAILABLE})으로 오며, {@link ChatClient.refreshSummary} 가 reject 한다.</p>
+     *
+     * <p>⚠️ <b>닫힌 union 이 아니다</b>: 서버가 값을 추가할 수 있으므로 분기에는 반드시 default 를 둔다.
+     * 모르는 값을 {@code QUEUED} 로 가정하지 말고 별도 상태 확인 UI를 표시한다.</p>
      */
-    status: 'STARTED' | 'ALREADY_RUNNING' | 'NO_CHANGE';
-    /** 이번 요청이 해소한 포맷({@link SummarizeFormat} 소문자). 방 단위 경합 식별용. */
+    status: 'QUEUED' | (string & {});
+    /** durable work item 에 병합한 포맷({@link SummarizeFormat} 소문자). */
     format?: string;
-    /** 이번 요청이 해소한 언어(소문자 BCP-47 / {@code 'OFF'}=원문). 방 단위 경합 식별용. */
+    /** durable work item 에 병합한 요청자 언어(소문자 BCP-47 / {@code 'OFF'}=원문). */
     language?: string;
 }
 
@@ -400,11 +404,15 @@ export interface RoomSummaryView {
      */
     language: string;
     /**
-     * 방 전체 요약 프로세스 상태 — {@code 'IDLE'}(대기) | {@code 'RUNNING'}(요약 중) | {@code 'FAILED'}(실패).
-     * <b>방 단위(키별 아님)</b>: 방은 한 번에 한 키만 요약하므로, 지금 다른 포맷·언어를 요약 중이어도 {@code 'RUNNING'} 이다.
-     * 특정 rollup 의 최신 여부는 {@code rollup.stale} 로 판단한다(rollup 자체는 완료된 데이터). 요약 이력이 없으면 null.
+     * 실행 상태 — {@code 'QUEUED'}(durable 대기) | {@code 'IDLE'}(유휴) |
+     * {@code 'RUNNING'}(요약 중) | {@code 'FAILED'}(선택 키 실패) |
+     * {@code 'NO_MESSAGES'}(선택 키에 요약할 대화 없음).
+     * 대기/실행은 방 단위이고 terminal 결과는 조회한 포맷×언어 키 기준이다. 특정 rollup 의 최신 여부는
+     * {@code rollup.stale} 로 판단한다. 요약 이력이 없어도 durable job 상태가 있으면 null이 아닐 수 있다.
+     * 닫힌 union이 아니므로 분기에는 default를 둔다.
      */
-    roomStatus: 'IDLE' | 'RUNNING' | 'FAILED' | null;
+    /** durable execution-plane 상태에서 합성되므로 재접속 뒤에도 복원된다. */
+    roomStatus: 'QUEUED' | 'IDLE' | 'RUNNING' | 'FAILED' | 'NO_MESSAGES' | (string & {}) | null;
     /** 요청/기본 포맷의 통합 요약본. 그 포맷×언어로 아직 요약 안 됐으면 null(availableFormats 로 같은 언어의 다른 포맷 확인). */
     rollup: RoomSummaryRollup | null;
     /** 이 방이 <b>이 언어로</b> 보유한 포맷 목록(short/timeline/… — 탭 렌더용). 타 언어는 포함하지 않는다. */
@@ -424,15 +432,18 @@ export interface RoomSummaryView {
 export interface SummaryUpdateEvent {
     roomId: string;
     /**
-     * {@code 'READY'}(갱신됨 → getSummary) | {@code 'FAILED'}(실패 → 재시도 가능) | {@code 'NO_CHANGE'}(변경 없음) |
+     * {@code 'READY'}(갱신됨 → getSummary) | {@code 'FAILED'}(실패 → 재시도 가능) |
+     * {@code 'NO_CHANGE'}(변경 없이 durable 작업 종결 → getSummary로 최종 동기화) |
+     * {@code 'NO_MESSAGES'}(선택 키에 요약할 대화 없음) |
      * {@code 'INVALIDATED'}(방 원문 삭제/편집으로 요약이 통째로 버려짐 → 화면을 비우고 필요 시 refreshSummary 로 재생성).
+     * 닫힌 union이 아니므로 모르는 값은 추측하지 말고 one-shot getSummary로 재동기화한다.
      */
-    status: 'READY' | 'NO_CHANGE' | 'FAILED' | 'INVALIDATED';
-    /** 완료/실패한 포맷. {@code READY}·{@code FAILED} 포함, {@code NO_CHANGE}·{@code INVALIDATED} 는 null. */
+    status: 'READY' | 'NO_CHANGE' | 'NO_MESSAGES' | 'FAILED' | 'INVALIDATED' | (string & {});
+    /** 완료 포맷. {@code READY}·{@code NO_CHANGE}·{@code NO_MESSAGES}·{@code FAILED} 포함, {@code INVALIDATED} 는 null. */
     format: string | null;
     /**
-     * fan-out 으로 한 번에 생성/최신화된 언어 목록(소문자 BCP-47 / {@code 'OFF'}). {@code READY}·{@code FAILED} 포함,
-     * 그 외 null. 각 사용자는 자기 언어가 이 목록에 있으면 {@code getSummary({ format, lang })} 로 읽는다(§S1).
+     * fan-out 으로 한 번에 처리한 언어 목록(소문자 BCP-47 / {@code 'OFF'}).
+     * {@code READY}·{@code NO_CHANGE}·{@code NO_MESSAGES}·{@code FAILED} 포함, {@code INVALIDATED} 만 null.
      */
     languages: string[] | null;
     /** 갱신 시각(epoch millis). {@code READY} 만 포함, 그 외 null. */