@vibexnpm/talkx 3.2.1 → 4.0.0

package/package.json

@@ -1,6 +1,6 @@
 {
     "name": "@vibexnpm/talkx",
-    "version": "3.2.1",
+    "version": "4.0.0",
     "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/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,12 @@ 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 (옵션)
      * @returns {Promise<{duplicate: boolean, messages: Object[]}>}
      *   - {@code duplicate}: 멱등 재시도로 기존 결과를 반환한 경우 {@code true}
-     *   - {@code messages}: 저장된 메시지 배열 (파일 분리 시 여러 개). 각 원소의 {@code messageId} 는 서버가 부여한 고유 ID.
+     *   - {@code messages}: 저장된 메시지 배열. {@code messageId} 는 서버가 부여한 ID.
      *
      * @example
      * // 일반 메시지
@@ -1361,13 +1361,13 @@ class ChatClient extends EventEmitter {
      * });
      *
      * @example
-     * // 파일 분리 전송 — messages 배열에 텍스트 + 파일별 메시지가 모두 담김
+     * // 첨부 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 +1382,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 +1407,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,13 +1431,14 @@ 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
         });
 
@@ -1542,7 +1544,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 +1572,6 @@ class ChatClient extends EventEmitter {
         return this.sendMessage(roomId, {
             message: options.message,
             fileInfos,
-            separateFiles: options.separateFiles,
             replyToMessageId: options.replyToMessageId
         });
     }
@@ -1616,11 +1616,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 +1624,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);
@@ -1811,20 +1806,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 +1830,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,6 +95,18 @@ 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'
 };
 

package/src/push/PushManager.js

@@ -411,9 +411,20 @@ class PushManager {
 
         // 알림 권한 요청
         // - 'default' 상태: 브라우저가 권한창을 표시하고 사용자 응답을 대기
-        // - 'granted' 상태: 즉시 'granted' 반환 (창 안 뜸)
+        // - 'granted' 상태: 재요청하지 않고 즉시 통과 (아래 주의사항 참고)
         // - 'denied' 상태: 위 가드에서 이미 throw 했으므로 여기 도달 불가
-        const permission = await Notification.requestPermission();
+        //
+        // !! Safari/WebKit 주의 !!
+        //   Chromium 은 이미 granted 인 상태에서 requestPermission() 을 호출하면 창 없이 즉시
+        //   'granted' 를 반환하지만, Safari/WebKit 은 이 API 를 '사용자 제스처 안에서만' 허용한다.
+        //   따라서 연결 직후 자동 활성화처럼 제스처가 없는 경로에서는 이미 허용된 상태여도 거부로 반환되어
+        //   PERMISSION_DENIED 로 throw 되고, 그 아래의 토큰 발급/서버 등록/포그라운드 onMessage 등록까지
+        //   모두 건너뛰게 된다(iOS 홈 화면 앱에서 새로고침마다 권한 차단 배너 + 포그라운드 메시지 미수신).
+        //   이미 허용된 상태에서는 재요청 자체가 불필요하므로 호출을 건너뛴다.
+        const permission =
+            Notification.permission === 'granted'
+                ? 'granted'
+                : await Notification.requestPermission();
         if (permission !== 'granted') {
             throw new PushError(
                 PushErrorCode.PERMISSION_DENIED,

package/src/talkflow/delegates.js

@@ -27,6 +27,10 @@ const CHAT_DELEGATE_METHODS = [
     '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"]
+}