@vibexnpm/talkx 3.2.1 → 4.0.0

package/dist/index.d.ts

@@ -71,9 +71,8 @@ export const SignalTypes: {
 
 /**
  * SDK 가 런타임에 export 하는 ChatMessageType 상수.
- * <p><b>런타임 소스와 정확히 일치</b>: {@code src/constants.js} 에 정의된 6개 값만 포함.
- * {@code DOCUMENT / GALLERY} 는 SDK 상수에 없음 — 서버 응답 메시지의 {@code chatMessageType}
- * 필드로는 수신될 수 있으므로 {@link ChatMessageTypeValue} 는 해당 값을 포함한 union.</p>
+ * <p><b>{@code src/constants.js} 와 정확히 일치해야 한다</b> — 한쪽만 늘리면 소비자가 존재하는 상수를
+ * 못 쓰거나(누락) 없는 상수를 참조한다(초과).</p>
  */
 export const ChatMessageType: {
     readonly TEXT: 'TEXT';
@@ -81,17 +80,32 @@ export const ChatMessageType: {
     readonly FILE: 'FILE';
     readonly VIDEO: 'VIDEO';
     readonly AUDIO: 'AUDIO';
+    readonly DOCUMENT: 'DOCUMENT';
+    /** 서로 다른 카테고리의 첨부가 섞인 메시지 (예: 이미지 2 + PDF 1). */
+    readonly MIXED: 'MIXED';
+    /**
+     * @deprecated 복수 첨부(타입 무관)를 뜻하던 과거 값. 신규 저장에서는 생성되지 않지만 기존 데이터에 남아 있다.
+     * {@link ChatClient.resolveMessageCategory} 로 복원할 것.
+     */
+    readonly GALLERY: 'GALLERY';
     readonly SYSTEM: 'SYSTEM';
 };
 
 /**
- * 서버가 보낼 수 있는 메시지 타입 값 전체.
- * <p>SDK 상수 ({@link ChatMessageType}) 의 6개 값 + 서버에서만 쓰는 {@code DOCUMENT / GALLERY}.
- * 수신 {@link ChatMessage#chatMessageType} 비교 시 이 union 을 사용.</p>
+ * 서버가 보낼 수 있는 메시지 타입 값 전체 — {@link ChatMessageType} 상수와 같은 집합.
+ * <p>수신 {@link ChatMessage#chatMessageType} 비교 시 이 union 을 사용한다.</p>
  */
 export type ChatMessageTypeValue =
     | 'TEXT' | 'IMAGE' | 'FILE' | 'VIDEO' | 'AUDIO' | 'SYSTEM'
-    | 'DOCUMENT' | 'GALLERY';
+    | 'DOCUMENT'
+    /** 서로 다른 카테고리의 첨부가 섞인 메시지 (예: 이미지 2 + PDF 1). 전송 1회 = 메시지 1건 계약의 신규 값. */
+    | 'MIXED'
+    /**
+     * @deprecated 복수 첨부(타입 무관)를 뜻하던 과거 값. 신규 저장에서는 생성되지 않지만 기존 데이터에 남아 있다.
+     * 동영상·문서 복수도 전부 이 값이므로 `IMAGE` 로 매핑하면 안 되고,
+     * {@link ChatClient.resolveMessageCategory} 로 `fileMetaDataList` 의 MIME 에서 복원해야 한다.
+     */
+    | 'GALLERY';
 
 export const ChatRoomType: {
     readonly DIRECT: 'DIRECT';
@@ -568,6 +582,17 @@ export type FileCustomMetadata = { [key: string]: JsonValue };
 
 /** 파일 메타데이터 (이미지/영상/오디오/문서). */
 export interface FileMetaData {
+    /**
+     * 첨부 식별자 — **서버 `uploadFile` 이 발급한 UUID 를 그대로 실어야 한다**.
+     *
+     * <p>서버가 이 값을 첨부 좌표(문서 추출 캐시 키)로 쓰기 때문에, 병합 저장이 켜진 서버에서는
+     * **UUID 형식 + 메시지 내 유일**이 필수다(위반 시 400). `uploadFile` / `sendFileMessage` 경로는
+     * 서버 응답을 그대로 전달하므로 신경 쓸 것이 없다.</p>
+     *
+     * <p>⚠️ **외부 스토리지에 직접 올리고 `fileInfos` 를 손으로 조립하는 연동**은 이 필드를 반드시 채워야 한다.
+     * 값이 없거나 UUID 가 아니면 병합 저장이 켜진 뒤 전송이 거부된다. 임의 UUID v4 를 생성해 넣으면 된다.</p>
+     */
+    fileId?: string;
     fileUrl: string;
     fileName?: string;
     fileSize?: number;
@@ -1095,11 +1120,29 @@ export interface UpdateGroupRoomData {
     engagementIntensity?: EngagementIntensityValue;
 }
 
+/**
+ * **전송 요청**에 싣는 첨부 — {@code fileId} 가 <b>필수</b>다.
+ *
+ * <p>서버가 이 값을 첨부 좌표(문서 추출 캐시 키)로 쓰기 때문에, 병합 저장이 켜진 서버는 UUID 형식 +
+ * 메시지 내 유일을 강제하고 위반 시 400 을 낸다. {@link ChatClient.uploadFile} 은 서버가 발급한 UUID 를
+ * 담아 반환하므로 그대로 넘기면 된다.</p>
+ *
+ * <p>⚠️ 외부 스토리지에 직접 올리고 {@code fileInfos} 를 손으로 조립하는 연동은 {@code crypto.randomUUID()}
+ * 등으로 직접 채워야 한다. 수신 메시지의 {@link FileMetaData} 는 legacy 데이터를 위해 {@code fileId} 가
+ * optional 이므로, 그것을 그대로 재전송하려면 {@code fileId} 를 보강해야 한다.</p>
+ */
+export type SendFileInfo = FileMetaData & { fileId: string };
+
 export interface SendMessageData {
     /** @deprecated SDK 가 내부에서 UUID 를 자동 생성합니다. 지정해도 런타임에서 무시됩니다. */
     messageId?: string;
     message?: string;
-    fileInfos?: FileMetaData[];
+    /** 첨부 — {@code fileId} 필수. {@link SendFileInfo} 참고. */
+    fileInfos?: SendFileInfo[];
+    /**
+     * @deprecated 더 이상 전송되지 않습니다. 전송 1회 = 메시지 1건이 계약이며, 첨부는 한 메시지에 전량 실립니다.
+     * 지정해도 SDK 가 무시합니다.
+     */
     separateFiles?: boolean;
     replyToMessageId?: string;
 }
@@ -1110,13 +1153,17 @@ export interface SendMessageResult {
 }
 
 /**
- * Optimistic prediction 검증 메타데이터 — {@link OptimisticSendMessageResult} 에 첨부.
+ * Optimistic 검증 메타데이터 — {@link OptimisticSendMessageResult} 에 첨부.
  *
- * <p>{@code predictionMatched: false} 면 서버의 파일 분류 규칙이 SDK 와 어긋난 것이며,
- * 호출자는 placeholder 들을 제거하고 {@code actualMessageIds} 기준으로 재구성해야 한다.</p>
+ * <p>전송 1회 = 메시지 1건이므로 `predictedMessageIds` 는 항상 `[baseMessageId]` 하나다.
+ * SDK 가 서버 파일 분류 규칙을 mirror 해 여러 ID 를 예측하던 로직은 제거됐다.</p>
+ *
+ * <p>{@code predictionMatched: false} 면 서버가 아직 병합 저장을 켜지 않아 **한 요청이 여러 row 로
+ * 저장된 것**이다(전환 기간의 정상 상태). 호출자는 placeholder 를 제거하고 `actualMessageIds` 기준으로
+ * 재구성해야 한다 — 이 fallback 경로는 플래그가 켜질 때까지 실제로 발생한다.</p>
  */
 export interface OptimisticPredictionInfo {
-    /** SDK 가 호출 시점에 예측한 messageId 배열. */
+    /** SDK 가 호출 시점에 만든 messageId 배열 — 항상 길이 1(`[baseMessageId]`). */
     predictedMessageIds: string[];
     /** 서버 응답의 실제 messageId 배열 — {@code result.messages.map(m => m.messageId)} 와 동일. */
     actualMessageIds: string[];
@@ -1136,29 +1183,27 @@ export interface OptimisticSendMessageResult extends SendMessageResult {
  * Optimistic UI 핸들 — {@code sendMessageOptimistic} / {@code sendTextMessageOptimistic} /
  * {@code sendReplyOptimistic} / {@code sendFileMessageOptimistic} 의 반환 타입.
  *
- * <p>SDK 가 서버의 messageId derivation 규칙 (텍스트=base, 파일=base#N) 을 mirror 하여
- * 응답 {@code messages} 배열과 1-1 매칭되는 ID 배열을 promise 시작 전 동기 반환한다.</p>
+ * <p>전송 1회 = 메시지 1건이므로 {@code messageIds} 는 <b>항상 {@code [baseMessageId]} 하나</b>다.
+ * 첨부 개수와 무관하며, promise 시작 전 동기 반환된다. 서버의 messageId derivation 규칙
+ * (텍스트=base, 파일=base#N)을 mirror 하던 예측기는 제거됐다.</p>
  *
- * <p><b>Drift 방어</b>: 서버 파일 분류 규칙이 변경되면 prediction 이 어긋날 수 있으며,
- * 이 경우 SDK 가 warn 로그를 남기고 promise 결과의 {@code optimistic.predictionMatched: false}
- * 로 알린다. 호출자는 {@code result.optimistic.actualMessageIds} 로 fallback reconcile 한다.</p>
+ * <p><b>전환 기간 fallback</b>: 서버가 아직 병합 저장을 켜지 않았다면 한 요청이 여러 row 로 저장되어
+ * {@code optimistic.predictionMatched} 가 {@code false} 가 된다. 오류가 아니라 정상 상태이며, SDK 가
+ * warn 로그를 남긴다. 이때 호출자는 placeholder 를 제거하고
+ * {@code result.optimistic.actualMessageIds} / {@code result.messages} 로 재구성해야 한다.</p>
  */
 export interface OptimisticSendMessageHandle {
     /** SDK 가 생성한 base messageId — 서버 멱등 키. 응답 첫 메시지가 텍스트면 이 값과 동일. */
     baseMessageId: string;
     /**
-     * 예측된 전체 messageId 배열 — 응답 {@code messages} 와 같은 순서/길이.
-     * <ul>
-     *   <li>텍스트 단건: {@code [base]}</li>
-     *   <li>파일 1개 (text 없음): {@code [base]}</li>
-     *   <li>텍스트 + 파일들: {@code [base, base#0, base#1, ...]}</li>
-     *   <li>분리 다파일 (text 없음): {@code [base#0, base#1, ...]}</li>
-     * </ul>
+     * 전송할 messageId 배열 — 전송 1회 = 메시지 1건이므로 <b>항상 {@code [baseMessageId]} 하나</b>다.
+     * <p>첨부 개수와 무관하다. 서버 저장 규칙을 mirror 해 {@code base#N} 을 계산하던 예측기는 제거됐다.</p>
      */
     messageIds: string[];
     /**
      * 실제 전송 promise — 일반 결과 + {@code optimistic} 메타데이터.
-     * {@code result.optimistic.predictionMatched} 가 {@code false} 면 drift fallback 필요.
+     * {@code result.optimistic.predictionMatched} 가 {@code false} 면 서버가 아직 병합 저장을 켜지 않아
+     * N건으로 저장한 것이다 — {@code actualMessageIds} 로 재구성한다(전환 기간의 정상 상태).
      */
     promise: Promise<OptimisticSendMessageResult>;
 }
@@ -1201,7 +1246,9 @@ export interface SendFileMessageProgressEvent extends UploadProgressEvent {
 export interface SendFileMessageOptions {
     /** 함께 보낼 텍스트. */
     message?: string;
-    /** 파일별 개별 메시지 분리 여부. */
+    /**
+     * @deprecated 더 이상 전송되지 않습니다. 전송 1회 = 메시지 1건이 계약입니다.
+     */
     separateFiles?: boolean;
     /** 답글 대상 원본 메시지의 서버 messageId. */
     replyToMessageId?: string;
@@ -1220,8 +1267,8 @@ export interface SendFileMessageOptions {
      *   <li>배열: index 별 파일에 매핑. 빈 슬롯 ({@code null} / {@code undefined}) 은 해당 파일에 metadata 미부여</li>
      * </ul>
      *
-     * <p>{@code separateFiles: false} 로 묶이는 경우에도 각 파일의 {@code metadata} 는 자신의 값을 유지하므로,
-     * 그룹 메시지의 {@code fileMetaDataList[i].metadata} 가 i 별로 다를 수 있다.</p>
+     * <p>첨부가 한 메시지에 묶여도 각 파일의 {@code metadata} 는 자신의 값을 유지하므로,
+     * {@code fileMetaDataList[i].metadata} 가 i 별로 다를 수 있다.</p>
      */
     metadata?: FileCustomMetadata | Array<FileCustomMetadata | undefined | null>;
 }
@@ -1591,7 +1638,7 @@ export class ChatClient implements SdkEventEmitter<ChatClientEvents> {
     sendReply(roomId: string, message: string, replyToMessageId: string): Promise<SendMessageResult>;
     sendReplyOptimistic(roomId: string, message: string, replyToMessageId: string): OptimisticSendMessageHandle;
 
-    uploadFile(roomId: string, file: File, options?: FileUploadOptions): Promise<FileMetaData>;
+    uploadFile(roomId: string, file: File, options?: FileUploadOptions): Promise<SendFileInfo>;
     sendFileMessage(roomId: string, files: File | File[], options?: SendFileMessageOptions): Promise<SendMessageResult>;
     /**
      * 파일 메시지 Optimistic UI 버전 — 업로드 시작 전에 messageIds 를 동기 반환.
@@ -1599,6 +1646,22 @@ export class ChatClient implements SdkEventEmitter<ChatClientEvents> {
      */
     sendFileMessageOptimistic(roomId: string, files: File | File[], options?: SendFileMessageOptions): OptimisticSendMessageHandle;
 
+    /**
+     * MIME 타입 → 첨부 카테고리 (서버 분류 규칙 mirror).
+     * <p>주로 {@link ChatClient.resolveMessageCategory} 가 쓰지만, 업로드 전 미리보기 분기 등에도 쓸 수 있다.</p>
+     */
+    classifyFileType(mimeType: string): 'IMAGE' | 'VIDEO' | 'AUDIO' | 'DOCUMENT' | 'FILE';
+
+    /**
+     * 메시지의 **렌더 카테고리**를 해석한다 — legacy `GALLERY` 복원용.
+     *
+     * <p>서버는 이제 첨부가 동질이면 그 카테고리를, 혼재면 `MIXED` 를 보낸다. 그러나 이 변경 이전에 저장된
+     * 메시지는 복수 첨부면 타입 무관 전부 `GALLERY` 다 — 동영상 2개도, PDF 2개도 `GALLERY` 다.
+     * 따라서 **`GALLERY` 를 `IMAGE` 로 매핑하면 안 된다.** 이 메서드가 `fileMetaDataList` 의 MIME 으로
+     * 실제 카테고리를 복원하므로, 렌더러는 `GALLERY` 분기를 따로 둘 필요가 없다.</p>
+     */
+    resolveMessageCategory(message: Pick<ChatMessage, 'chatMessageType' | 'fileMetaDataList'>): ChatMessageTypeValue;
+
     editMessage(roomId: string, messageId: string, message: string): Promise<void>;
     deleteMessage(roomId: string, messageId: string, deleteType?: DeleteType): Promise<void>;
     /** 메시지 읽음 처리 — sync. 연결 상태 or send 결과에 따라 boolean 반환. */
@@ -1938,7 +2001,7 @@ export default class TalkFlowClient implements SdkEventEmitter<TalkFlowClientEve
     sendReply(roomId: string, message: string, replyToMessageId: string): Promise<SendMessageResult>;
     sendReplyOptimistic(roomId: string, message: string, replyToMessageId: string): OptimisticSendMessageHandle;
 
-    uploadFile(roomId: string, file: File, options?: FileUploadOptions): Promise<FileMetaData>;
+    uploadFile(roomId: string, file: File, options?: FileUploadOptions): Promise<SendFileInfo>;
     sendFileMessage(roomId: string, files: File | File[], options?: SendFileMessageOptions): Promise<SendMessageResult>;
     /**
      * 파일 메시지 Optimistic UI 버전 — 업로드 시작 전에 messageIds 를 동기 반환.
@@ -1946,6 +2009,22 @@ export default class TalkFlowClient implements SdkEventEmitter<TalkFlowClientEve
      */
     sendFileMessageOptimistic(roomId: string, files: File | File[], options?: SendFileMessageOptions): OptimisticSendMessageHandle;
 
+    /**
+     * MIME 타입 → 첨부 카테고리 (서버 분류 규칙 mirror).
+     * <p>주로 {@link ChatClient.resolveMessageCategory} 가 쓰지만, 업로드 전 미리보기 분기 등에도 쓸 수 있다.</p>
+     */
+    classifyFileType(mimeType: string): 'IMAGE' | 'VIDEO' | 'AUDIO' | 'DOCUMENT' | 'FILE';
+
+    /**
+     * 메시지의 **렌더 카테고리**를 해석한다 — legacy `GALLERY` 복원용.
+     *
+     * <p>서버는 이제 첨부가 동질이면 그 카테고리를, 혼재면 `MIXED` 를 보낸다. 그러나 이 변경 이전에 저장된
+     * 메시지는 복수 첨부면 타입 무관 전부 `GALLERY` 다 — 동영상 2개도, PDF 2개도 `GALLERY` 다.
+     * 따라서 **`GALLERY` 를 `IMAGE` 로 매핑하면 안 된다.** 이 메서드가 `fileMetaDataList` 의 MIME 으로
+     * 실제 카테고리를 복원하므로, 렌더러는 `GALLERY` 분기를 따로 둘 필요가 없다.</p>
+     */
+    resolveMessageCategory(message: Pick<ChatMessage, 'chatMessageType' | 'fileMetaDataList'>): ChatMessageTypeValue;
+
     editMessage(roomId: string, messageId: string, message: string): Promise<void>;
     deleteMessage(roomId: string, messageId: string, deleteType?: DeleteType): Promise<void>;
     /** 메시지 읽음 처리 — sync. 연결 상태 or send 결과에 따라 boolean 반환. */