@vibexnpm/talkx 4.0.0 → 4.0.1

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;
 }
 
 /** 채팅방 참가자. */
@@ -1145,6 +1195,11 @@ export interface SendMessageData {
      */
     separateFiles?: boolean;
     replyToMessageId?: string;
+    /**
+     * 의사결정 카드의 선택 — 카드 버튼을 눌렀을 때만. {@link ChatClient#sendDecisionChoice} 가
+     * {@code replyToMessageId}/{@code message}/{@code optionId} 셋을 한 번에 맞춰 준다.
+     */
+    decisionResponse?: DecisionResponse;
 }
 
 export interface SendMessageResult {
@@ -1637,6 +1692,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 +2060,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>;