@vibexnpm/talkx 4.0.0 → 4.0.1

package/package.json

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

package/src/TalkFlowClient.js

@@ -289,7 +289,15 @@ class TalkFlowClient extends EventEmitter {
     }
 
     /**
-     * 사용자 정보 수정
+     * 사용자 정보 수정.
+     *
+     * 서버는 갱신된 프로필이 담긴 **새 JWT** 를 응답에 함께 실어 준다(`/auth` 와 같은 계약).
+     * 이걸 채택하지 않으면 옛 토큰의 name/profileUrl 클레임이 계속 나가, 서버가 그 클레임을 읽는
+     * 경로에서 낡은 값이 최대 7일(토큰 TTL) 동안 보인다.
+     *
+     * 같은 사용자의 토큰 교체라 `setToken` 은 재연결을 일으키지 않는다 — userId 가 바뀔 때만
+     * 재초기화하고, 여기서는 STOMP connectHeaders 만 갱신된다.
+     *
      * @param {Object} userData
      * @param {string} [userData.nickname] - 닉네임 (max 100자)
      * @param {string} [userData.profileImageUrl] - 프로필 이미지 URL (max 500자)
@@ -299,7 +307,20 @@ class TalkFlowClient extends EventEmitter {
      */
     async updateMyInfo(userData) {
         this._checkToken();
-        return this.apiClient.put('/api/v1/users/update', userData);
+        const response = await this.apiClient.put('/api/v1/users/update', userData);
+
+        if (response?.data?.accessToken) {
+            // 토큰 교체 실패로 수정 자체를 실패시키지 않는다 — 서버 반영은 이미 끝났고,
+            // 옛 토큰도 유효(낡았을 뿐)하므로 여기서 throw 하면 호출자가 이미 적용된 수정을
+            // 다시 시도하게 된다. authenticate() 는 토큰이 없으면 아무것도 못 하므로 계약이 다르다.
+            try {
+                await this.setToken(response.data.accessToken);
+            } catch (error) {
+                this.logger.warn('Profile updated but token refresh failed; keeping the old token', error);
+            }
+        }
+
+        return response;
     }
 
     /**

package/src/chat/ChatClient.js

@@ -1344,6 +1344,9 @@ class ChatClient extends EventEmitter {
      * @param {Object[]} [data.fileInfos] - 파일 메타데이터 배열. 각 원소는 <b>UUID {@code fileId} 필수</b>
      *   ({@link #uploadFile} 반환값은 이미 포함). 외부 스토리지 직접 업로드 연동은 직접 채워야 한다.
      * @param {string} [data.replyToMessageId] - 답글 대상 원본 메시지 ID (옵션)
+     * @param {Object} [data.decisionResponse] - 의사결정 카드의 선택 — {@code { optionId }} (옵션).
+     *   카드 버튼을 누르면 <b>평범한 답글</b>로 보낸다: {@code replyToMessageId} = 카드의 messageId,
+     *   {@code message} = 고른 선택지의 {@code label}, 여기에 {@code optionId}. 전용 endpoint 는 없다.
      * @returns {Promise<{duplicate: boolean, messages: Object[]}>}
      *   - {@code duplicate}: 멱등 재시도로 기존 결과를 반환한 경우 {@code true}
      *   - {@code messages}: 저장된 메시지 배열. {@code messageId} 는 서버가 부여한 ID.
@@ -1361,6 +1364,15 @@ class ChatClient extends EventEmitter {
      * });
      *
      * @example
+     * // 의사결정 카드의 선택 — 답글 하나로 나간다 (새 API 없음)
+     * const option = card.decisionRequest.options[0];
+     * await chat.sendMessage('room-id', {
+     *   message: option.label,               // 폴백 가독성 — 카드를 못 그리는 화면에서도 대화가 읽힌다
+     *   replyToMessageId: card.messageId,
+     *   decisionResponse: { optionId: option.id }
+     * });
+     *
+     * @example
      * // 첨부 3장 + 캡션 — 메시지 1건
      * const { messages } = await chat.sendMessage('room-id', {
      *   message: '사진 보냅니다',
@@ -1439,7 +1451,10 @@ class ChatClient extends EventEmitter {
             messageId,
             message: data.message,
             fileInfos: data.fileInfos,
-            replyToMessageId: data.replyToMessageId
+            replyToMessageId: data.replyToMessageId,
+            // 의사결정 카드의 선택. 🔴 이 줄이 없으면 호출자가 넘긴 값이 <b>조용히 유실</b>된다 —
+            // 이 payload 는 화이트리스트라 data 에 있어도 전달되지 않는다.
+            decisionResponse: data.decisionResponse
         });
 
         const result = this._unwrapSuccessResponse(response);
@@ -1735,6 +1750,44 @@ class ChatClient extends EventEmitter {
         return this.sendMessageOptimistic(roomId, { message, replyToMessageId });
     }
 
+    /**
+     * 의사결정 카드의 선택 전송 (간편 버전).
+     *
+     * <p>세 가지를 <b>한 번에 맞춰</b> 보낸다 — 셋 중 하나만 빠져도 계약이 깨지므로 직접 조립하기보다
+     * 이 메서드를 쓰는 편이 안전하다:</p>
+     * <ul>
+     *   <li>{@code replyToMessageId} = 카드 messageId — 어느 질문에 답한 것인지</li>
+     *   <li>{@code message} = 고른 선택지의 {@code label} — <b>가독 폴백</b>. 빈 본문이면 대화에
+     *       빈 칸이 남아 나중에 읽을 때 무엇을 골랐는지 알 수 없다</li>
+     *   <li>{@code decisionResponse.optionId} — 서버가 보는 <b>권위</b> 값</li>
+     * </ul>
+     *
+     * <p>전용 endpoint 가 아니라 <b>평범한 답글</b>이다. 그래서 선택이 대화에 메시지로 남고, 카드를
+     * 못 그리는 화면에서도 흐름이 읽힌다.</p>
+     *
+     * @param {string} roomId - 채팅방 ID
+     * @param {Object} card - 카드 메시지 ({@code decisionRequest} 를 가진 그 메시지)
+     * @param {Object} option - 사용자가 고른 {@code card.decisionRequest.options[i]}
+     * @returns {Promise<{duplicate: boolean, messages: Object[]}>}
+     *
+     * @example
+     * const card = messages.find(m => m.decisionRequest);
+     * await chat.sendDecisionChoice('room-id', card, card.decisionRequest.options[1]);
+     */
+    async sendDecisionChoice(roomId, card, option) {
+        if (!card || !card.messageId) {
+            throw new Error('sendDecisionChoice: card with messageId is required');
+        }
+        if (!option || !option.id) {
+            throw new Error('sendDecisionChoice: option with id is required');
+        }
+        return this.sendMessage(roomId, {
+            message: option.label,
+            replyToMessageId: card.messageId,
+            decisionResponse: { optionId: option.id }
+        });
+    }
+
     /**
      * 메시지 삭제.
      *

package/src/constants.js

@@ -110,6 +110,30 @@ export const ChatMessageType = {
     SYSTEM: 'SYSTEM'
 };
 
+/**
+ * AI 의사결정 카드({@code message.decisionRequest}) 렌더 상한 — 서버가 강제하는 값의 사본.
+ *
+ * <p>🔴 <b>카드는 새 {@code chatMessageType} 이 아니다.</b> 카드 메시지의 타입은 그냥 {@code TEXT} 이고,
+ * 선택 요청은 {@code decisionRequest} <b>필드</b>로 온다. 그래서 필드를 모르는 렌더러는 <b>평범한 텍스트
+ * 메시지로 그리면 되고 그게 정상 동작</b>이다 — {@code content} 에 질문과 후보가 사람이 읽는 형태로
+ * 들어 있다.</p>
+ *
+ * <p>🔴 반대로 카드를 그린다면 {@code content} 를 <b>다시 그리지 마라</b> — 버튼과 본문에 같은 질문·후보가
+ * 두 번 보인다. 둘 중 하나만 그린다.</p>
+ *
+ * <p>클라가 이 값으로 <b>검증할 필요는 없다</b>(서버가 이미 강제한다). 레이아웃 계산용 참고값이다.</p>
+ */
+export const DecisionCardLimits = {
+    /** 선택지 최소 개수 — 1개면 물을 이유가 없어 서버가 카드를 만들지 않는다. */
+    MIN_OPTIONS: 2,
+    /** 선택지 최대 개수 — 그 이상은 선택이 아니라 목록이다. */
+    MAX_OPTIONS: 5,
+    /** 라벨 표시 길이(초과분은 서버가 말줄임 처리해서 보낸다). */
+    LABEL_MAX_LENGTH: 80,
+    /** 질문 표시 길이. */
+    QUESTION_MAX_LENGTH: 200
+};
+
 /**
  * 메시지 발신자 타입 — 서버 {@code SenderType} 과 일치.
  *

package/src/index.js

@@ -50,6 +50,7 @@ export {
     ErrorTypes,
     SignalTypes,
     ChatMessageType,
+    DecisionCardLimits,
     ChatRoomType,
     AssistantMode,
     RoomAiType,

package/src/talkflow/delegates.js

@@ -24,6 +24,8 @@ const CHAT_DELEGATE_METHODS = [
     'sendTextMessageOptimistic',
     'sendReply',
     'sendReplyOptimistic',
+    // AI 의사결정 카드의 선택 — 답글·라벨 본문·optionId 를 한 번에 맞춰 보낸다.
+    'sendDecisionChoice',
     'uploadFile',
     'sendFileMessage',
     'sendFileMessageOptimistic',

package/types/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>;