@vibexnpm/talkx 5.2.0 → 5.4.0

package/README.md

@@ -75,6 +75,7 @@ await client.connect(jwtToken, { enablePush: true });
 | [chat.md](docs/chat.md) | 채팅방 관리, 메시지 전송, 파일 업로드, 답글, 리액션, 핀, 타이핑, 채팅방 리스트 실시간 갱신, **AI 어시스턴트 페르소나 (멘션 응답)** |
 | [push.md](docs/push.md) | **웹 푸시 알림.** 권한 lifecycle, 활성화 패턴 (자동 vs 사용자 액션), 디바이스 토글, 알림 클릭 라우팅 |
 | [webrtc.md](docs/webrtc.md) | 1:1 / 그룹 통화, 미디어 제어, 디바이스 관리, TURN 서버 |
+| [vote.md](docs/vote.md) | **투표.** 생성(멱등키 필수) · 투표/재투표 · 결과 마스킹 · 이미지 선택지 · 채팅 카드 렌더링 |
 | [events.md](docs/events.md) | 모든 이벤트 레퍼런스. 채팅 이벤트 처리 패턴 (`eventType` 분기 vs 상태 필드 렌더) |
 | [errors.md](docs/errors.md) | 에러 분류 (`PushErrorReason`, `ErrorTypes`), HTTP 상태 코드, 입력 제약 |
 

package/dist/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. */
@@ -1260,6 +1271,29 @@ export interface AssistantRoomProgressEvent {
     textAvailable?: boolean;
 }
 
+/** {@link ChatClient.getAssistantProgress} 가 돌려주는 stream 1건. */
+export interface AssistantProgressStreamSnapshot {
+    streamId: string;
+    personaId: string | null;
+    phase: 'THINKING' | 'SEARCHING' | 'PLANNING' | 'WRITING' | null;
+    label: string | null;
+    text: string | null;
+    textAvailable: boolean;
+    /** 서버 스냅샷으로 복원된 진행분이면 true. */
+    resumed: boolean;
+}
+
+/**
+ * 방의 **현재** AI 진행 상태 (v5.3.0 — {@link ChatClient.getAssistantProgress} 반환).
+ *
+ * <p>{@link AssistantRoomProgressEvent} 와 같은 형태에 stream 단위 UI 를 위한 `streams` 가 더해진다.
+ * 이벤트는 transient 라 화면을 나갔다 들어오면 다시 오지 않는다 — 마운트 시 이걸 한 번 읽는다.</p>
+ */
+export interface AssistantProgressSnapshot extends AssistantRoomProgressEvent {
+    /** 살아 있는 stream 전체 (도착 순서). 없으면 빈 배열. */
+    streams: AssistantProgressStreamSnapshot[];
+}
+
 // ============================================================================
 // Options — constructor & method
 // ============================================================================
@@ -2017,6 +2051,17 @@ export class ChatClient implements SdkEventEmitter<ChatClientEvents> {
 
     startTyping(roomId: string): void;
     stopTyping(roomId: string): void;
+
+    /**
+     * 방의 현재 AI 진행 상태를 즉시 반환 (네트워크 호출 없음, v5.3.0).
+     * 진행 표시 이벤트는 transient 라 방 화면 마운트 시 이걸 읽어 버블을 복원한다.
+     */
+    getAssistantProgress(roomId: string): AssistantProgressSnapshot;
+    /**
+     * 구독 중인 모든 방의 진행 스트림 스냅샷을 서버에서 다시 받는다 (v5.1.0).
+     * 재연결·탭 복귀 때 SDK 가 자동 호출하므로 보통은 직접 부를 일이 없다.
+     */
+    resumeAssistantStreams(reason?: string): Promise<void>;
 }
 
 export class WebRTCClient implements SdkEventEmitter<WebRTCClientEvents> {
@@ -2400,6 +2445,17 @@ export default class TalkFlowClient implements SdkEventEmitter<TalkFlowClientEve
     startTyping(roomId: string): void;
     stopTyping(roomId: string): void;
 
+    /**
+     * 방의 현재 AI 진행 상태를 즉시 반환 (네트워크 호출 없음, v5.3.0).
+     * 진행 표시 이벤트는 transient 라 방 화면 마운트 시 이걸 읽어 버블을 복원한다.
+     */
+    getAssistantProgress(roomId: string): AssistantProgressSnapshot;
+    /**
+     * 구독 중인 모든 방의 진행 스트림 스냅샷을 서버에서 다시 받는다 (v5.1.0).
+     * 재연결·탭 복귀 때 SDK 가 자동 호출하므로 보통은 직접 부를 일이 없다.
+     */
+    resumeAssistantStreams(reason?: string): Promise<void>;
+
     // WebRTC delegations
     initializeIceServers(): Promise<RTCIceServer[]>;
     getTurnCredentials(): Promise<{ iceServers: RTCIceServer[] }>;