@vibexnpm/talkx 4.0.0 → 5.1.0

package/dist/index.d.ts

@@ -91,6 +91,20 @@ export const ChatMessageType: {
     readonly SYSTEM: 'SYSTEM';
 };
 
+/**
+ * AI 의사결정 카드 렌더 상한 — 서버가 강제하는 값의 사본(참고용, 클라 검증 불필요).
+ *
+ * <p>🔴 카드는 <b>새 {@code chatMessageType} 이 아니다</b> — 타입은 {@code TEXT} 이고 선택 요청은
+ * {@link ChatMessage#decisionRequest} 필드로 온다. 모르는 렌더러는 텍스트로 그리면 되고 그게 정상이다.
+ * 카드를 그린다면 {@code content} 를 다시 그리지 마라(같은 내용이 두 번 보인다).</p>
+ */
+export const DecisionCardLimits: {
+    readonly MIN_OPTIONS: 2;
+    readonly MAX_OPTIONS: 5;
+    readonly LABEL_MAX_LENGTH: 80;
+    readonly QUESTION_MAX_LENGTH: 200;
+};
+
 /**
  * 서버가 보낼 수 있는 메시지 타입 값 전체 — {@link ChatMessageType} 상수와 같은 집합.
  * <p>수신 {@link ChatMessage#chatMessageType} 비교 시 이 union 을 사용한다.</p>
@@ -728,6 +742,42 @@ export interface ChatMessage {
     translations?: Record<string, string> | null;
     /** 번역 당시 content 해시 — stale 판별용 (내부). */
     translationsOf?: string | null;
+    /**
+     * AI 의 구조화 선택 요청(카드). 어시스턴트 메시지에만 존재하고, 일반 메시지에는 부재.
+     *
+     * <p><b>모르면 그냥 텍스트로 그려라 — 그게 정상 동작이다.</b> {@code content} 에 질문과 후보가
+     * 사람이 읽는 형태로 들어 있어 카드를 못 그려도 대화가 그대로 읽힌다.</p>
+     *
+     * <p>🔴 반대로 카드를 그린다면 {@code content} 를 <b>다시 그리지 마라</b> — 질문과 후보가 두 번 보인다.</p>
+     */
+    decisionRequest?: DecisionRequest | null;
+    /** 사용자의 선택. 어느 카드인지는 {@code replyTo} 가 특정한다. */
+    decisionResponse?: DecisionResponse | null;
+}
+
+/**
+ * AI 가 낸 선택 요청 — 질문 + 후보 2~5개.
+ *
+ * <p>후보는 <b>서버가 방의 실제 첨부에서</b> 만든다(클라가 만들거나 편집하지 않는다).</p>
+ */
+export interface DecisionRequest {
+    /** 사용자에게 보일 질문 — 최대 200자. */
+    question: string;
+    /** 선택지 2~5개. 라벨은 이 카드 안에서 유일하다. */
+    options: DecisionOption[];
+}
+
+export interface DecisionOption {
+    /** 불투명 식별자 — 선택 전송 시 {@code decisionResponse.optionId} 로 <b>그대로</b> 돌려보낸다. */
+    id: string;
+    /** 버튼에 보일 이름 — 최대 80자(초과분은 서버가 말줄임). */
+    label: string;
+    /** 보조 설명(업로드 시각 등). 없을 수 있다. */
+    hint?: string | null;
+}
+
+export interface DecisionResponse {
+    optionId: string;
 }
 
 /** 채팅방 참가자. */
@@ -940,35 +990,103 @@ export interface TypingEvent {
  *
  * typing 과 별개의 가산 UX 레이어(설계 ASSISTANT_PROGRESS_STREAMING_DESIGN.md). 서버가 typing 도 이중발행하므로
  * 구버전 SDK 는 본 이벤트를 못 받아도 기존 typing 으로 정상 동작한다. UI 는 `active:true` 면 `label`(또는 `phase`)
- * 로 단계를 표시하고, `active:false`(DONE·어시 메시지 도착·TTL 만료) 면 해제한다.
+ * 로 단계를 표시하고, `active:false`(DONE·TTL 만료) 면 해제한다.
+ *
+ * ⚠️ **v5.0.0 breaking — 이 이벤트는 `streamId` 단위다.** 한 방에 동시 스트림이 실재하므로(PM 방에서 트리거가
+ * 겹치면 각각 streamId 를 받는다) `active:false` 는 **그 stream 하나**를 뜻한다. 방마다 버블 하나를 그리는
+ * 기존 코드에 그대로 물리면 **같은 방의 다른 살아 있는 버블까지 숨긴다**. 둘 중 하나를 택한다.
+ *
+ * - (권장) `roomId + streamId` 를 키로 버블을 관리한다 — 최종 목표 형태.
+ * - (이행용 다리) {@link AssistantRoomProgressEvent} 를 대신 구독한다. 리스너 이름만 바꾸면 기존 단일 버블
+ *   렌더가 그대로 동작한다.
  *
  * 현재는 PM_BACKSTAGE(방당 단일 PM) 만 phase 를 발행 — 멘션/버튼/14인 경로는 본 이벤트 없이 typing 만.
  */
 export interface AssistantProgressEvent {
     /** 채팅방 ID. */
     roomId: string;
-    /** 어시 응답 1회분 식별(멀티 응답/중복 dedup). 일부 종료 emit 에선 null. */
-    streamId: string | null;
+    /**
+     * 어시 응답 1회분 식별 — **v5.0.0 부터 항상 non-null**.
+     *
+     * UI 는 `roomId + streamId` 로 버블을 키잉한다. SDK 는 `streamId` 없는 서버 이벤트를 아예 버리므로
+     * 이 값이 비어 오는 emit 은 없다(v4.x 는 일부 종료 emit 에서 null 이 올 수 있었다).
+     */
+    streamId: string;
     /** 진행 주체 페르소나 ID. */
     personaId: string | null;
     /** 진행 단계 — `active:true` 일 때. 종료 시 null. */
     phase: 'THINKING' | 'SEARCHING' | 'PLANNING' | 'WRITING' | null;
     /** phase 의 기본 표시 라벨(예: "생각 중…"). SDK 매핑 — 커스텀하려면 `phase` 사용. 종료 시 null. */
     label: string | null;
-    /** true=진행중(PHASE/DELTA) / false=종료(DONE·메시지 도착·TTL). */
+    /** true=진행중(PHASE/DELTA) / false=종료(DONE·TTL). */
     active: boolean;
-    /** 토큰 스트림 누적 텍스트(B) — DELTA 수신 시 지금까지 모인 전체. 버블에 그대로 렌더. PHASE-only/종료 시 null. */
+    /**
+     * 토큰 스트림 누적 텍스트(B) — DELTA 수신 시 지금까지 모인 전체. 버블에 그대로 렌더.
+     * PHASE-only/종료 시 null. **`textAvailable:false` 면 항상 null** — 그 땐 `label` 을 그린다.
+     */
     text?: string | null;
-    /** 이번 토큰 청크(B) — append 렌더를 선호할 때. DELTA 수신 시만. */
+    /** 이번 토큰 청크(B) — append 렌더를 선호할 때. DELTA 수신 시만. `textAvailable:false` 면 null. */
     delta?: string | null;
     /** 토큰 청크 순서/누락 감지(B) — DELTA 수신 시만. */
     seq?: number | null;
+    /**
+     * 본문을 신뢰할 수 있는가 (v4.2.0 추가).
+     *
+     * `false` = 앞부분을 받은 적이 없다 — 스트리밍 도중 재입장/새로고침(late join)했거나 WS 순단으로 `seq` 에
+     * 구멍이 났다는 뜻. 이때 `text`/`delta` 는 null 로 오고 **이후 청크도 누적되지 않는다**.
+     * UI 는 본문 대신 `label`(예: "작성 중…")을 표시하고 최종 메시지를 기다리면 된다.
+     *
+     * 예전 동작은 이 경우에도 받은 조각을 누적본처럼 넘겨서 **잘린 답변**이 화면에 그려졌다.
+     */
+    textAvailable?: boolean;
     /** 종료(DONE) 결과 — DONE 수신 시만. */
     status?: 'SUCCEEDED' | 'FAILED' | 'CANCELLED' | 'TIMEOUT' | null;
     /** 종료(DONE, SUCCEEDED) 시 영속된 최종 메시지 ID. */
     messageId?: string | null;
-    /** 종료 사유 — 'message'(어시 메시지 도착) / 'timeout'(TTL). DONE 수신 해제엔 없음. */
-    reason?: 'message' | 'timeout' | null;
+    /**
+     * 종료 사유 — 'timeout'(TTL 만료). DONE 수신 해제엔 없음.
+     *
+     * v4.2.0 부터 `'message'` 는 emit 되지 않았고(어시 메시지 도착은 진행 표시를 끄지 않는다 —
+     * 종료 SSOT = DONE + TTL), **v5.0.0 에서 유니온에서도 제거**했다.
+     */
+    reason?: 'timeout' | null;
+    /** 이 stream 의 마지막 seq — 스냅샷 병합 커서(v5.0.0). DELTA 0건이면 -1. */
+    lastSeq?: number;
+    /**
+     * `true` = 서버 스냅샷으로 **복원된** 진행분(v5.1.0).
+     *
+     * 스트리밍 도중 재입장했거나 새로 들어와서, 구독 전에 이미 발행된 앞부분을 REST 스냅샷으로 받아온
+     * 경우다. UI 가 "이어보는 중" 같은 표시를 하고 싶을 때만 쓰면 되고, 렌더 로직은 평소와 같다.
+     */
+    resumed?: boolean;
+}
+
+/**
+ * 방 단위 AI 진행 표시 집계 (v5.0.0 신설).
+ *
+ * <p>{@link AssistantProgressEvent} 가 `streamId` 단위로 바뀌면서, **방마다 임시 버블 하나**를 그리는 기존
+ * UI 를 위한 이행용 다리로 제공한다. 리스너 이름만 `assistantProgress` → `assistantRoomProgress` 로 바꾸면
+ * 기존 렌더 코드가 그대로 동작한다.</p>
+ *
+ * <p>`active` 는 방에 살아 있는 stream 이 **하나라도** 있으면 true 다. 그래서 동시 응답 중 하나가 끝나도
+ * 버블이 사라지지 않는다. 표시 내용(`text`/`label`/`phase`)은 **가장 최근에 갱신된** stream 을 따른다.</p>
+ */
+export interface AssistantRoomProgressEvent {
+    /** 채팅방 ID. */
+    roomId: string;
+    /** 방에 살아 있는 stream 이 하나라도 있으면 true. */
+    active: boolean;
+    /** 살아 있는 stream 개수. 2 이상이면 동시 응답 중이다. */
+    streamCount: number;
+    /** 표시 기준이 된 stream (가장 최근 갱신). 없으면 null. */
+    streamId: string | null;
+    personaId: string | null;
+    phase: 'THINKING' | 'SEARCHING' | 'PLANNING' | 'WRITING' | null;
+    label: string | null;
+    /** 표시 기준 stream 의 누적 본문. `textAvailable:false` 거나 진행 중이 아니면 null. */
+    text?: string | null;
+    /** 표시 기준 stream 의 본문 신뢰 여부 — false 면 `label` 을 그린다. */
+    textAvailable?: boolean;
 }
 
 // ============================================================================
@@ -1011,6 +1129,13 @@ export interface TalkFlowClientOptions {
      * <p>복구된 메시지는 일반 `chatMessage` 이벤트로 재생되므로 수신 코드를 바꿀 필요가 없다.</p>
      */
     syncOnReconnect?: boolean;
+    /**
+     * 방 구독·재연결 시 진행 중 AI 스트림을 서버 스냅샷으로 이어받을지. 기본 true (v5.1.0).
+     *
+     * <p>스트림은 Pub/Sub 라 구독 시점 이후만 오므로, 스트리밍 도중 재입장하면 앞부분을 받을 방법이
+     * 스냅샷뿐이다. `syncOnReconnect`(메시지 갭 복구)와 <b>별개 경로</b>다 — 그쪽을 꺼도 이건 돈다.</p>
+     */
+    assistantStreamReplay?: boolean;
     /** 갭 복구 첫 페이지에만 적용되는 되감기 폭 (ms). 기본 3000. 서버가 상한 clamp 후 1회 차감. */
     rewindMillis?: number;
     /** 갭 복구 페이지 상한. 기본 5. 초과 시 최신 페이지 재로드로 전환하고 `gapTruncated` 를 발행. */
@@ -1145,6 +1270,11 @@ export interface SendMessageData {
      */
     separateFiles?: boolean;
     replyToMessageId?: string;
+    /**
+     * 의사결정 카드의 선택 — 카드 버튼을 눌렀을 때만. {@link ChatClient#sendDecisionChoice} 가
+     * {@code replyToMessageId}/{@code message}/{@code optionId} 셋을 한 번에 맞춰 준다.
+     */
+    decisionResponse?: DecisionResponse;
 }
 
 export interface SendMessageResult {
@@ -1383,6 +1513,7 @@ export interface TalkFlowClientEvents {
     messageRead: MessageReadEventPayload;
     typing: TypingEvent;
     assistantProgress: AssistantProgressEvent;
+    assistantRoomProgress: AssistantRoomProgressEvent;
     /** Rolling 누적 요약 완료/실패 통지 (transient) — refreshSummary 후. */
     summaryUpdate: SummaryUpdateEvent;
     memberJoined: MemberChangePayload;
@@ -1518,6 +1649,7 @@ export interface ChatClientEvents {
     messageRead: MessageReadEventPayload;
     typing: TypingEvent;
     assistantProgress: AssistantProgressEvent;
+    assistantRoomProgress: AssistantRoomProgressEvent;
     /** Rolling 누적 요약 완료/실패 통지 (transient) — refreshSummary 후. */
     summaryUpdate: SummaryUpdateEvent;
 }
@@ -1637,6 +1769,11 @@ export class ChatClient implements SdkEventEmitter<ChatClientEvents> {
     sendTextMessageOptimistic(roomId: string, message: string): OptimisticSendMessageHandle;
     sendReply(roomId: string, message: string, replyToMessageId: string): Promise<SendMessageResult>;
     sendReplyOptimistic(roomId: string, message: string, replyToMessageId: string): OptimisticSendMessageHandle;
+    /**
+     * 의사결정 카드의 선택 전송 — 답글 + 라벨 본문 + optionId 를 한 번에 맞춰 보낸다.
+     * 직접 조립하지 말고 이 메서드를 쓰는 편이 안전하다(셋 중 하나만 빠져도 계약이 깨진다).
+     */
+    sendDecisionChoice(roomId: string, card: ChatMessage, option: DecisionOption): Promise<SendMessageResult>;
 
     uploadFile(roomId: string, file: File, options?: FileUploadOptions): Promise<SendFileInfo>;
     sendFileMessage(roomId: string, files: File | File[], options?: SendFileMessageOptions): Promise<SendMessageResult>;
@@ -2000,6 +2137,11 @@ export default class TalkFlowClient implements SdkEventEmitter<TalkFlowClientEve
     sendTextMessageOptimistic(roomId: string, message: string): OptimisticSendMessageHandle;
     sendReply(roomId: string, message: string, replyToMessageId: string): Promise<SendMessageResult>;
     sendReplyOptimistic(roomId: string, message: string, replyToMessageId: string): OptimisticSendMessageHandle;
+    /**
+     * 의사결정 카드의 선택 전송 — 답글 + 라벨 본문 + optionId 를 한 번에 맞춰 보낸다.
+     * 직접 조립하지 말고 이 메서드를 쓰는 편이 안전하다(셋 중 하나만 빠져도 계약이 깨진다).
+     */
+    sendDecisionChoice(roomId: string, card: ChatMessage, option: DecisionOption): Promise<SendMessageResult>;
 
     uploadFile(roomId: string, file: File, options?: FileUploadOptions): Promise<SendFileInfo>;
     sendFileMessage(roomId: string, files: File | File[], options?: SendFileMessageOptions): Promise<SendMessageResult>;