@vibexnpm/talkx 3.2.2 → 4.0.1

package/package.json

@@ -1,6 +1,6 @@
 {
     "name": "@vibexnpm/talkx",
-    "version": "3.2.2",
+    "version": "4.0.1",
     "type": "module",
     "description": "TalkFlow SDK - Chat & WebRTC unified client",
     "main": "dist/talkflow-sdk.umd.js",
@@ -17,7 +17,8 @@
         "build:types": "copy types\\index.d.ts dist\\index.d.ts",
         "dev": "rollup -c -w",
         "lint": "eslint src/",
-        "test": "jest"
+        "test": "jest && npm run typecheck",
+        "typecheck": "tsc -p types/__typetests__/tsconfig.json"
     },
     "repository": {
         "type": "git",
@@ -48,6 +49,7 @@
         "@rollup/plugin-terser": "^0.4.4",
         "babel-jest": "^29.7.0",
         "jest": "^29.7.0",
-        "rollup": "^4.12.0"
+        "rollup": "^4.12.0",
+        "typescript": "^5.9.3"
     }
 }

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

@@ -1331,8 +1331,8 @@ class ChatClient extends EventEmitter {
      * 설계된다. 서버 Unique 제약 + pre-check 로 중복 저장이 차단되며, 재시도 히트 시
      * {@code duplicate: true} 로 기존 결과가 그대로 반환된다.</p>
      *
-     * <p>파일 분리 시 ({@code separateFiles: true}) 하나의 요청이 여러 메시지로 저장된다.
-     * 각 메시지는 고유한 서버 {@code messageId} 를 가지며 응답의 {@code messages} 배열로 전달된다.</p>
+     * <p><b>전송 1회 = 메시지 1건</b>: 첨부가 몇 개든 한 메시지로 저장되며 응답 {@code messages} 는 길이 1이다.
+     * {@code chatMessageType} 은 렌더러 힌트로, 첨부가 동질이면 그 카테고리, 혼재면 {@code MIXED} 다.</p>
      *
      * <p>답글: {@code data.replyToMessageId} 에 원본 메시지의 서버 {@code messageId} 를 지정.
      * 서버가 원본을 조회해서 snapshot 을 생성 후 저장하며, 응답/수신 메시지의 {@code replyTo}
@@ -1341,12 +1341,15 @@ class ChatClient extends EventEmitter {
      * @param {string} roomId - 채팅방 ID
      * @param {Object} data
      * @param {string} [data.message] - 메시지 내용 (message 또는 fileInfos 중 하나 필수)
-     * @param {Object[]} [data.fileInfos] - 파일 메타데이터 배열
-     * @param {boolean} [data.separateFiles=true] - 파일 분리 여부
+     * @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.
+     *   - {@code messages}: 저장된 메시지 배열. {@code messageId} 는 서버가 부여한 ID.
      *
      * @example
      * // 일반 메시지
@@ -1361,13 +1364,22 @@ class ChatClient extends EventEmitter {
      * });
      *
      * @example
-     * // 파일 분리 전송 — messages 배열에 텍스트 + 파일별 메시지가 모두 담김
+     * // 의사결정 카드의 선택 — 답글 하나로 나간다 (새 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: '사진 보냅니다',
-     *   fileInfos: [f0, f1, f2],
-     *   separateFiles: true
+     *   fileInfos: [f0, f1, f2]        // uploadFile 결과 (fileId 포함)
      * });
-     * // messages.length === 4 (텍스트 1 + 이미지 3)
+     * // messages.length === 1 · messages[0].chatMessageType === 'IMAGE'
+     * // messages[0].fileMetaDataList.length === 3
      */
     async sendMessage(roomId, data) {
         const messageId = this._generateMessageId();
@@ -1382,12 +1394,12 @@ class ChatClient extends EventEmitter {
      * 예측 {@code messageIds} 배열을 동기 반환한다. 호출자는 promise 가 resolve 되기 전에
      * 미리 placeholder 메시지를 UI 에 그려둘 수 있고, resolve 후 같은 ID 로 안전하게 교체할 수 있다.</p>
      *
-     * <p>{@code messageIds} 는 서버의 messageId derivation 규칙 (텍스트=base, 파일=base#N) 을
-     * SDK 가 mirror 하여 사전 계산한 값이다. 정상 케이스에서는 응답
-     * {@code messages.map(m => m.messageId)} 와 길이/순서가 정확히 일치한다.</p>
+     * <p>전송 1회 = 메시지 1건이므로 {@code messageIds} 는 <b>항상 {@code [baseMessageId]} 하나</b>다.
+     * 서버 분류 규칙을 mirror 해 여러 ID 를 예측하던 로직은 제거됐다.</p>
      *
-     * <p><b>분류 규칙 drift 방어</b>: 서버 파일 분류 규칙이 변경되어 예측이 어긋나면
-     * SDK 가 warn 로그를 남기며, 이 경우 응답의 실제 {@code messageId} 로 reconcile 해야 한다.</p>
+     * <p><b>전환 기간 주의</b>: 서버가 아직 병합 저장을 켜지 않았다면 한 요청이 여러 row 로 저장되어
+     * {@code optimistic.predictionMatched} 가 {@code false} 가 된다. 오류가 아니라 전환 기간의 정상
+     * 상태이며, 이때는 응답의 {@code actualMessageIds} 로 재구성해야 한다.</p>
      *
      * @param {string} roomId - 채팅방 ID
      * @param {Object} data - {@link #sendMessage} 와 동일한 페이로드
@@ -1407,7 +1419,8 @@ class ChatClient extends EventEmitter {
      */
     sendMessageOptimistic(roomId, data) {
         const baseMessageId = this._generateMessageId();
-        const messageIds = this._predictMessageIdsFromData(baseMessageId, data);
+        // 전송 1회 = 메시지 1건 — 예측할 것이 없다. 서버 분류 규칙을 mirror 하던 예측기는 제거됐다.
+        const messageIds = [baseMessageId];
 
         const promise = this._sendMessageWithId(roomId, baseMessageId, data)
             .then((result) => this._attachOptimisticMetadata(messageIds, result));
@@ -1430,14 +1443,18 @@ class ChatClient extends EventEmitter {
         // 메시지 전송 시 타이핑 표시 자동 중단
         this.stopTyping(roomId);
 
-        // separateFiles 는 SDK 가 명시 전송 — 서버 default 가 변경되어도 SDK 의 prediction
-        // 가정 (`undefined === true`) 과 wire 값이 어긋나지 않도록 fix.
+        // separateFiles 는 더 이상 보내지 않는다 — 전송 1회 = 메시지 1건이 계약이다.
+        // 서버는 이 필드를 병합 저장 플래그가 OFF 인 동안에만(legacy 재현용) 읽으며, 값이 없으면
+        // 기본 true 로 동작한다. 즉 OFF 서버에서는 여전히 N건이 저장되고, 그 불일치는
+        // optimistic 의 predictionMatched:false 로 드러난다(설계 §5).
         const response = await this.apiClient.post(`/api/v1/chat-messages/${roomId}/send`, {
             messageId,
             message: data.message,
             fileInfos: data.fileInfos,
-            separateFiles: data.separateFiles !== false,
-            replyToMessageId: data.replyToMessageId
+            replyToMessageId: data.replyToMessageId,
+            // 의사결정 카드의 선택. 🔴 이 줄이 없으면 호출자가 넘긴 값이 <b>조용히 유실</b>된다 —
+            // 이 payload 는 화이트리스트라 data 에 있어도 전달되지 않는다.
+            decisionResponse: data.decisionResponse
         });
 
         const result = this._unwrapSuccessResponse(response);
@@ -1542,7 +1559,6 @@ class ChatClient extends EventEmitter {
      * @param {File|Blob|Array<File|Blob>} files - 단일 파일 또는 파일 배열
      * @param {Object} [options]
      * @param {string} [options.message] - 함께 보낼 텍스트 본문
-     * @param {boolean} [options.separateFiles] - 파일별 개별 메시지 분리 여부 (서버 설정)
      * @param {string} [options.replyToMessageId] - 답글 대상 원본 메시지의 서버 {@code messageId}
      * @param {Function} [options.onUploadProgress] - {@code ({loaded,total,percent,fileIndex}) => void} — 파일별 진행률
      * @param {AbortSignal} [options.signal] - 취소 시그널 — 업로드 중에만 유효
@@ -1571,7 +1587,6 @@ class ChatClient extends EventEmitter {
         return this.sendMessage(roomId, {
             message: options.message,
             fileInfos,
-            separateFiles: options.separateFiles,
             replyToMessageId: options.replyToMessageId
         });
     }
@@ -1616,11 +1631,7 @@ class ChatClient extends EventEmitter {
         const fileArray = this._normalizeFileArray(files);
 
         const baseMessageId = this._generateMessageId();
-        const messageIds = this._predictMessageIds(
-            baseMessageId,
-            this._predictGroupCount(fileArray, options.separateFiles !== false),
-            this._hasTextMessage(options.message)
-        );
+        const messageIds = [baseMessageId];   // 전송 1회 = 메시지 1건
 
         const promise = (async () => {
             const metas = await this._uploadFiles(roomId, fileArray, options);
@@ -1628,7 +1639,6 @@ class ChatClient extends EventEmitter {
             const result = await this._sendMessageWithId(roomId, baseMessageId, {
                 message: options.message,
                 fileInfos,
-                separateFiles: options.separateFiles,
                 replyToMessageId: options.replyToMessageId
             });
             return this._attachOptimisticMetadata(messageIds, result);
@@ -1740,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 }
+        });
+    }
+
     /**
      * 메시지 삭제.
      *
@@ -1811,20 +1859,23 @@ class ChatClient extends EventEmitter {
     }
 
     /**
-     * MIME 타입 → 서버 {@code ChatMessageType} 분류 (서버 {@code FileGroupingService.classifyFileType} mirror).
-     * <p>서버 도메인 규칙과 동일해야 group count 예측이 일치한다. 서버 변경 시 본 메서드도 동기화 필요.</p>
+     * MIME 타입 → {@code ChatMessageType} 카테고리 (서버 {@code AttachmentTypeClassifier} mirror).
+     *
+     * <p><b>공개 API</b> — legacy {@code GALLERY} 메시지의 실제 카테고리를 복원하는 데 쓴다
+     * ({@link #resolveMessageCategory}). 서버 규칙이 바뀌면 본 메서드도 동기화해야 한다.</p>
      *
-     * @private
      * @param {string} mimeType
-     * @returns {string} 'IMAGE' | 'VIDEO' | 'AUDIO' | 'DOCUMENT' | 'FILE'
+     * @returns {'IMAGE'|'VIDEO'|'AUDIO'|'DOCUMENT'|'FILE'}
      */
-    _classifyFileType(mimeType) {
+    classifyFileType(mimeType) {
         const mime = this._baseMimeType(mimeType);
         if (mime.startsWith('image/')) return 'IMAGE';
         if (mime.startsWith('video/')) return 'VIDEO';
         if (mime.startsWith('audio/')) return 'AUDIO';
-        // 평문(txt/md)도 DOCUMENT — 서버가 온디맨드 번역·PM 문서 인식 대상으로 삼는 기준과 동일해야 한다
+        // 평문(txt/md)도 DOCUMENT — 서버가 온디맨드 번역·PM 문서 인식 대상으로 삼는 기준과 동일해야 한다.
+        // pre-2007 Office(.doc/.xls/.ppt)도 서버가 OLE 매직까지 검증해 DOCUMENT 로 받는다.
         if (mime.includes('pdf') || mime.includes('document')
+            || mime.includes('msword') || mime.includes('ms-excel') || mime.includes('ms-powerpoint')
             || PLAIN_TEXT_DOCUMENT_MIME_TYPES.has(mime)) {
             return 'DOCUMENT';
         }
@@ -1832,66 +1883,46 @@ class ChatClient extends EventEmitter {
     }
 
     /**
-     * 파일 그룹 수 예측 (서버 {@code FileGroupingService.groupFiles} mirror).
-     * <p>{@code separateFiles=true} 면 파일 개수, {@code false} 면 타입별 distinct 개수.
-     * File 객체 ({@code .type}) / FileMetaData 객체 ({@code .fileType}) 양쪽 입력 모두 처리.</p>
-     *
+     * 하위호환 별칭 — {@link #classifyFileType} 를 쓸 것.
      * @private
-     * @param {Array<File|Blob|Object>} fileArray
-     * @param {boolean} separateFiles
-     * @returns {number}
+     * @deprecated
      */
-    _predictGroupCount(fileArray, separateFiles) {
-        if (!fileArray || fileArray.length === 0) return 0;
-        if (separateFiles) return fileArray.length;
-
-        // 입력 순서 보존하면서 distinct 타입 카운트 (서버 LinkedHashMap 동작과 동일)
-        const typesSeen = new Set();
-        for (const file of fileArray) {
-            const mime = file && (file.type || file.fileType) || '';
-            typesSeen.add(this._classifyFileType(mime));
-        }
-        return typesSeen.size;
+    _classifyFileType(mimeType) {
+        return this.classifyFileType(mimeType);
     }
 
     /**
-     * 서버 저장 messageId 배열 예측 (서버 {@code SendMessageService} mirror).
-     * <p>규칙 ({@code SendMessageService.java:102-106, 197}):
-     * {@code expectedMessageCount = (hasMessage?1:0) + groupCount}, 1 이면 base, 2 이상이면
-     * 텍스트=base / 파일=base#0..#(N-1).</p>
+     * 메시지의 <b>렌더 카테고리</b>를 해석한다 — legacy {@code GALLERY} 복원용 공개 헬퍼.
      *
-     * @private
-     * @param {string} baseMessageId
-     * @param {number} groupCount
-     * @param {boolean} hasMessage
-     * @returns {string[]} 응답 messages 와 같은 순서
-     */
-    _predictMessageIds(baseMessageId, groupCount, hasMessage) {
-        const expectedCount = (hasMessage ? 1 : 0) + groupCount;
-        if (expectedCount === 0) return [];
-        if (expectedCount === 1) return [baseMessageId];
-
-        const ids = [];
-        if (hasMessage) ids.push(baseMessageId);
-        for (let i = 0; i < groupCount; i++) {
-            ids.push(`${baseMessageId}#${i}`);
-        }
-        return ids;
-    }
-
-    /**
-     * {@code SendMessageData} 페이로드로부터 messageIds 예측.
-     * <p>{@link #sendMessageOptimistic} 가 사용 — {@code data.fileInfos} 가 있으면 그걸로
-     * group count 예측, 없으면 텍스트 단건으로 처리.</p>
+     * <p>서버는 이제 첨부가 동질이면 그 카테고리를, 혼재면 {@code MIXED} 를 보낸다. 그러나 이 변경
+     * <b>이전에 저장된 메시지는 복수 첨부면 타입 무관 전부 {@code GALLERY}</b> 다 — 동영상 2개도, PDF 2개도
+     * {@code GALLERY} 다. 따라서 <b>{@code GALLERY} 를 {@code IMAGE} 로 매핑하면 안 된다.</b>
+     * 이 메서드가 {@code fileMetaDataList} 의 MIME 으로 실제 카테고리를 복원한다.</p>
      *
-     * @private
+     * @param {Object} message - 서버 메시지 ({@code chatMessageType} + {@code fileMetaDataList})
+     * @returns {string} 'TEXT'|'IMAGE'|'VIDEO'|'AUDIO'|'DOCUMENT'|'FILE'|'MIXED'|'SYSTEM'
+     *
+     * @example
+     * // 렌더러 선택 — GALLERY 분기를 따로 두지 않아도 된다
+     * switch (client.resolveMessageCategory(message)) {
+     *   case 'IMAGE':    return <ImageGrid files={message.fileMetaDataList} />;
+     *   case 'VIDEO':    return <VideoList files={message.fileMetaDataList} />;
+     *   case 'MIXED':    return <MixedAttachmentList files={message.fileMetaDataList} />;
+     *   default:         return <FileList files={message.fileMetaDataList} />;
+     * }
      */
-    _predictMessageIdsFromData(baseMessageId, data) {
-        const fileInfos = (data && data.fileInfos) || [];
-        const separate = !data || data.separateFiles !== false;
-        const groupCount = this._predictGroupCount(fileInfos, separate);
-        const hasMessage = this._hasTextMessage(data && data.message);
-        return this._predictMessageIds(baseMessageId, groupCount, hasMessage);
+    resolveMessageCategory(message) {
+        const type = message && message.chatMessageType;
+        const files = (message && message.fileMetaDataList) || [];
+        // GALLERY 만 복원 대상 — 나머지는 서버가 이미 정확한 카테고리를 보냈다.
+        if (type !== 'GALLERY') {
+            return type || 'TEXT';
+        }
+        if (files.length === 0) {
+            return 'FILE';
+        }
+        const categories = new Set(files.map(f => this.classifyFileType((f && f.fileType) || '')));
+        return categories.size === 1 ? categories.values().next().value : 'MIXED';
     }
 
     /**

package/src/constants.js

@@ -95,9 +95,45 @@ export const ChatMessageType = {
     FILE: 'FILE',
     VIDEO: 'VIDEO',
     AUDIO: 'AUDIO',
+    DOCUMENT: 'DOCUMENT',
+    /**
+     * 서로 다른 카테고리의 첨부가 섞인 메시지 — 예: 이미지 2 + PDF 1.
+     * <p>전송 1회 = 메시지 1건 계약에서 새로 생긴 값. 클라이언트가 모르면 렌더가 깨진다.</p>
+     */
+    MIXED: 'MIXED',
+    /**
+     * @deprecated 복수 첨부(타입 무관)를 뜻하던 <b>과거</b> 값. 신규 저장에서는 생성되지 않지만
+     * 기존 데이터에 남아 있다. 동영상·문서 복수도 전부 이 값이므로 <b>IMAGE 로 매핑하면 안 되고</b>,
+     * {@code ChatClient#resolveMessageCategory} 로 fileMetaDataList 의 MIME 에서 복원해야 한다.
+     */
+    GALLERY: 'GALLERY',
     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,9 +24,15 @@ const CHAT_DELEGATE_METHODS = [
     'sendTextMessageOptimistic',
     'sendReply',
     'sendReplyOptimistic',
+    // AI 의사결정 카드의 선택 — 답글·라벨 본문·optionId 를 한 번에 맞춰 보낸다.
+    'sendDecisionChoice',
     'uploadFile',
     'sendFileMessage',
     'sendFileMessageOptimistic',
+    // 첨부 분류 — legacy GALLERY 복원용 공개 헬퍼. 타입 선언이 최상위 클라이언트에도 있으므로
+    // 여기에 없으면 talkflow.resolveMessageCategory() 가 런타임 undefined 가 된다(타입이 거짓말).
+    'classifyFileType',
+    'resolveMessageCategory',
     'editMessage',
     'deleteMessage',
     'markAsRead',

package/types/__typetests__/singleMessageAttachment.types.ts

@@ -0,0 +1,68 @@
+/**
+ * TypeScript 소비자 컴파일 검증 — 타입 선언이 <b>실제로 컴파일되는지</b>.
+ *
+ * <p>런타임 테스트(jest)는 `.d.ts` 를 전혀 보지 않으므로, 존재하지 않는 타입을 반환 타입으로 쓰거나
+ * 값(const)을 타입 위치에 쓰는 오류를 못 잡는다. S2 에서 실제로 `resolveMessageCategory` 가
+ * 값인 `ChatMessageType` 을 반환 타입으로 선언해 소비자 컴파일이 깨졌다.</p>
+ *
+ * <p>실행: {@code npm run typecheck}</p>
+ */
+import type TalkFlowClient from '../index';
+import type {
+    ChatClient,
+    ChatMessage,
+    ChatMessageTypeValue,
+    FileMetaData,
+    SendFileInfo
+} from '../index';
+import { ChatMessageType } from '../index';
+
+declare const chat: ChatClient;
+declare const talkflow: TalkFlowClient;
+declare const message: ChatMessage;
+
+// 1) 렌더 카테고리 해석 — 반환은 값이 아니라 union 타입이어야 한다.
+const category: ChatMessageTypeValue = chat.resolveMessageCategory(message);
+const viaTopLevel: ChatMessageTypeValue = talkflow.resolveMessageCategory(message);
+
+// 2) 신규 상수가 런타임 선언에 있어야 한다.
+const mixed: 'MIXED' = ChatMessageType.MIXED;
+const gallery: 'GALLERY' = ChatMessageType.GALLERY;
+const document: 'DOCUMENT' = ChatMessageType.DOCUMENT;
+
+// 3) MIXED 를 포함한 exhaustive 분기가 성립해야 한다.
+function render(c: ChatMessageTypeValue): string {
+    switch (c) {
+        case 'TEXT': return 'text';
+        case 'IMAGE': return 'image';
+        case 'VIDEO': return 'video';
+        case 'AUDIO': return 'audio';
+        case 'DOCUMENT': return 'document';
+        case 'FILE': return 'file';
+        case 'MIXED': return 'mixed';
+        case 'GALLERY': return 'legacy';
+        case 'SYSTEM': return 'system';
+    }
+}
+
+// 4) uploadFile 결과는 fileId 를 보장하므로 그대로 전송에 넘길 수 있다.
+async function uploadThenSend(): Promise<void> {
+    const meta: SendFileInfo = await chat.uploadFile('room', new File([], 'a.png'));
+    await chat.sendMessage('room', { message: '캡션', fileInfos: [meta] });
+}
+
+// 5) optimistic 핸들 — messageIds 는 문자열 배열.
+function optimistic(): void {
+    const { baseMessageId, messageIds, promise } = chat.sendMessageOptimistic('room', { message: 'hi' });
+    void baseMessageId;
+    const ids: string[] = messageIds;
+    void ids;
+    void promise;
+}
+
+// 6) 수신 메시지의 FileMetaData 는 legacy 를 위해 fileId 가 optional 이다.
+function legacyResponseFile(f: FileMetaData): string | undefined {
+    return f.fileId;
+}
+
+export { category, viaTopLevel, mixed, gallery, document, render, uploadThenSend, optimistic, legacyResponseFile };

package/types/__typetests__/tsconfig.json

@@ -0,0 +1,12 @@
+{
+    "compilerOptions": {
+        "strict": true,
+        "noEmit": true,
+        "target": "ES2020",
+        "module": "ESNext",
+        "moduleResolution": "bundler",
+        "lib": ["ES2020", "DOM"],
+        "skipLibCheck": false
+    },
+    "include": ["./*.ts", "../index.d.ts"]
+}