easemob-websdk 5.1.3 → 5.2.0

package/message/multibody-content.d.ts

@@ -0,0 +1,35 @@
+import type { CompatibleFile, MultiBody, Message, MessageBody, MessageType } from '../types';
+declare const MULTIBODY_SEGMENT_TYPES: readonly ["text", "image", "file", "voice", "video", "location", "custom"];
+export type MultiBodySegmentType = (typeof MULTIBODY_SEGMENT_TYPES)[number];
+export declare const isMultiBodySegmentType: (type: string) => type is MultiBodySegmentType;
+/** 复合消息附件缓存 key。冒号必须保留，避免本地 id 和分段下标粘在一起。 */
+export declare const attachmentStoreKey: (msgLocalId: string, bodyIndex: number) => string;
+/** 本地文件挂在分段对象本身上。组装时按这个对象取走，复制分段会把文件丢掉。 */
+export declare const holdAttachmentFile: (body: object, file: CompatibleFile) => void;
+export declare const takeAttachmentFile: (body: object) => CompatibleFile | undefined;
+export declare const mapRestSegmentType: (type: string | undefined) => MessageType | null;
+/** REST 合并段经常写成 txt/text，并用 subType 0 或合并启发字段标识。 */
+export declare const isCombineRestSegment: (segment: Record<string, unknown>) => boolean;
+/** 多段无法合成复合消息时只留第一段，并说明原因。第一段本身解不出来则仍丢弃。 */
+export declare const keepFirstBody: <T>(segments: ReadonlyArray<T>, reason: string) => ReadonlyArray<T>;
+export declare const composeSegments: (segments: ReadonlyArray<{
+    type: MessageType;
+    body: MessageBody;
+} | null>) => {
+    type: MessageType;
+    body: MessageBody;
+} | null;
+export declare const resolvePublicMessageContent: (contents: ReadonlyArray<unknown>, decodeContent: (content: Record<string, unknown>) => {
+    type: MessageType;
+    body: MessageBody;
+} | null) => {
+    type: MessageType;
+    body: MessageBody;
+} | null;
+export declare const isDownloadableSegmentType: (type: string) => type is "image" | "voice" | "video" | "file";
+export declare const attachMultiBodyUploadDetails: (error: unknown, msgLocalId: string) => void;
+export declare const isMultiBodyMessage: (message: Pick<Message, "type" | "body">) => message is Message & {
+    type: "multi_body";
+    body: MultiBody;
+};
+export {};

package/message/translations.d.ts

@@ -0,0 +1,7 @@
+/** 消息译文的公开映射与现有消息协议数组之间的转换。 */
+export declare const toProtocolTranslations: (translations: Readonly<Record<string, string>> | undefined) => ReadonlyArray<{
+    readonly code: string;
+    readonly text: string;
+}>;
+/** 非法译文不影响原文解析；重复语言采用最后一个合法条目。 */
+export declare const readTranslations: (metaPayload: unknown) => Record<string, string> | undefined;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "easemob-websdk",
-  "version": "5.1.3",
+  "version": "5.2.0",
   "description": "High-performance, type-safe, extensible instant messaging SDK",
   "homepage": "https://www.easemob.com/",
   "type": "module",

package/platform/image/miniapp-image-processor.d.ts

@@ -4,18 +4,21 @@ interface MiniAppReadFileSuccessResult {
 }
 interface MiniAppGetFileInfoSuccessResult {
     readonly size: number;
+    readonly digest?: string;
+}
+interface MiniAppGetFileInfoOptions {
+    readonly filePath: string;
+    readonly digestAlgorithm?: 'md5';
+    readonly success: (result: MiniAppGetFileInfoSuccessResult) => void;
+    readonly fail?: (error: unknown) => void;
 }
 interface MiniAppFileSystemManagerLike {
-    readFile(options: {
+    readFile?(options: {
         readonly filePath: string;
         readonly success: (result: MiniAppReadFileSuccessResult) => void;
         readonly fail?: (error: unknown) => void;
     }): void;
-    getFileInfo?(options: {
-        readonly filePath: string;
-        readonly success: (result: MiniAppGetFileInfoSuccessResult) => void;
-        readonly fail?: (error: unknown) => void;
-    }): void;
+    getFileInfo?(options: MiniAppGetFileInfoOptions): void;
 }
 interface MiniAppImageInfoResponse {
     readonly width: number;
@@ -40,6 +43,7 @@ export interface MiniAppImageRuntimeLike {
         readonly fail?: (error: unknown) => void;
     }): void;
     getFileSystemManager?(): MiniAppFileSystemManagerLike;
+    getFileInfo?(options: MiniAppGetFileInfoOptions): void;
 }
 export declare const createMiniAppImageProcessor: (runtime: MiniAppImageRuntimeLike) => ImageProcessor;
 export {};

package/protocol/msync/codec.d.ts

@@ -149,9 +149,12 @@ export declare class MsyncCodec {
     private decodeMessage;
     private resolveMessageProfileVersionFields;
     private buildMessageMeta;
+    private buildMessageMetaFromBody;
+    private buildTranslationsMeta;
     private resolveProfileVersionTime;
     private isPublicMessageType;
     private resolveMessageIsOnline;
+    private buildContents;
     private buildContent;
     private decodeContent;
     private resolveChatType;

package/protocol/msync/message-payload-decoder.d.ts

@@ -8,7 +8,7 @@ export declare class MessagePayloadDecoder {
     private readonly useCustomAttachmentUpload;
     constructor(userId: string, useCustomAttachmentUpload?: boolean);
     decodeMetadata(body: Record<string, unknown>, conversationType: ChatConversationType, direct: Message['direct'], fallbackMeta?: unknown): Omit<Partial<Message>, 'body'>;
-    decodeContent(content: Record<string, unknown>): {
+    decodeContent(content: Record<string, unknown>, metaPayload?: unknown): {
         type: Message['type'];
         body: MessageBody;
     } | null;
@@ -24,6 +24,10 @@ export declare class MessagePayloadDecoder {
     resolveChatThreadOverview(metaPayload: unknown): ChatThreadOverview | undefined;
     resolveChatThreadOverviewLastMessage(rawLastMessage: unknown, chatThreadId: string): ChatThreadOverview['lastMessage'] | undefined;
     resolveThreadLastMessagePayload(rawLastMessage: Record<string, unknown>): Record<string, unknown> | null;
+    composeThreadBodies(bodies: ReadonlyArray<unknown>): {
+        type: Message['type'];
+        body: MessageBody;
+    } | null;
     mapThreadMessageType(rawType: string | undefined): Message['type'];
     normalizeThreadLastMessageBody(type: Message['type'], firstBody: Record<string, unknown> | null, rawLastMessage: Record<string, unknown>): MessageBody;
     readString(value: unknown): string | undefined;

package/protocol/session-list/payload-decoder.d.ts

@@ -1,6 +1,6 @@
 import type { SessionMessageSnippet } from '../../types/conversation';
 export declare const decodeSessionListPayload: (payload?: Uint8Array) => {
-    readonly body: Record<string, unknown>;
+    readonly body: Record<string, unknown> | ReadonlyArray<Record<string, unknown>>;
     readonly ext: Record<string, unknown>;
 };
 export declare const decodeSessionListPayloadRecord: (payload?: Uint8Array) => Record<string, unknown> | null;
@@ -10,4 +10,4 @@ export declare const mapSessionListPayload: (decoded: Record<string, unknown> |
     readonly from: string;
     readonly useCustomAttachmentUpload?: boolean;
 }) => Partial<SessionMessageSnippet>;
-export declare const decodeSessionListPayloadBody: (payload?: Uint8Array) => Record<string, unknown>;
+export declare const decodeSessionListPayloadBody: (payload?: Uint8Array) => Record<string, unknown> | ReadonlyArray<Record<string, unknown>>;

package/types/chat-manager.d.ts

@@ -63,7 +63,7 @@ export interface RecallMessageParams extends ConversationLocator {
 export interface UpdateMessageParams extends ConversationLocator {
     /** [zh-CN] 待编辑的消息 ID。 [en-US] ID of the message to edit. */
     messageId: string;
-    /** [zh-CN] 编辑后的消息内容。当前仅支持文本消息和自定义消息。 [en-US] Updated message content. Currently, only text messages and custom messages are supported. */
+    /** [zh-CN] 编辑后的消息内容。文本消息可修改 `content` 和 `ext`；`body.targetLanguages` 非空时先翻译再编辑，译文写入 `body.translations`，翻译失败则抛出异常且不发送编辑。自定义消息可修改 `event`、`params` 和 `ext`；图片、语音、视频、文件、位置和合并消息仅可修改 `ext`。命令消息和复合消息不支持编辑。 [en-US] Updated message content. Text messages can change `content` and `ext`. Non-empty `body.targetLanguages` are translated before the edit and stored in `body.translations`; translation failure throws without sending the edit. Custom messages can change `event`, `params`, and `ext`. Image, voice, video, file, location, and combined messages can change `ext` only. Command and multi_body messages cannot be edited. */
     message: Pick<Message, 'type' | 'body' | 'ext'>;
 }
 /**
@@ -113,7 +113,7 @@ export interface MessageHistoryPage {
  * [en-US] Parameters for downloading a message attachment.
  */
 export interface DownloadAttachmentParams {
-    /** [zh-CN] 需要下载附件的消息，通常为图片、语音、视频或文件消息。 [en-US] Message whose attachment is to be downloaded, typically an image, voice, video, or file message. */
+    /** [zh-CN] 需要下载附件的消息，通常为图片、语音、视频、文件或复合消息。复合消息会下载其中全部图片、语音、视频和文件。 [en-US] Message whose attachment is to be downloaded, typically an image, voice, video, file, or multi_body message. A multi_body message downloads every image, voice, video, and file segment. */
     message: Message;
 }
 /**

package/types/conversation.d.ts

@@ -240,8 +240,8 @@ export interface SessionMessageSnippet extends Readonly<Partial<Omit<Message, 'b
     readonly userInfoUpdateTime?: number;
     /** [zh-CN] 群成员名片的版本时间戳（秒），仅群聊会话的最后一条消息可能存在此字段。 [en-US] The version timestamp (in seconds) of the Group member name card. This field may only exist for the last message in group chat conversations. */
     readonly namecardUpdateTime?: number;
-    /** [zh-CN] 与 MessageBody 一致的消息正文，不包含 type；为兼容历史不完整摘要，保留对象类型。 [en-US] Message content matching MessageBody without type; an object type is retained for incomplete legacy snippets. */
-    readonly body: Record<string, unknown>;
+    /** [zh-CN] 与 MessageBody 一致的消息正文。复合消息时这里直接是分段数组。 [en-US] Message content matching MessageBody. For a multi_body message, this is the segment array. */
+    readonly body: Record<string, unknown> | ReadonlyArray<Record<string, unknown>>;
     /** [zh-CN] 消息扩展字段，与 onMessage 的 ext 一致；旧缓存可能缺失。 [en-US] Message extension fields, matching onMessage ext; may be absent in legacy caches. */
     readonly ext?: Message['ext'];
 }

package/types/index.d.ts

@@ -48,7 +48,7 @@ export type { Sender } from './sender';
  * [zh-CN] SDK 支持的消息类型。
  * [en-US] Message types supported by the SDK.
  */
-export type MessageType = 'text' | 'image' | 'file' | 'voice' | 'video' | 'location' | 'custom' | 'cmd' | 'combine';
+export type MessageType = 'text' | 'image' | 'file' | 'voice' | 'video' | 'location' | 'custom' | 'cmd' | 'combine' | 'multi_body';
 /**
  * [zh-CN] 图片资源类型常量。
  * [en-US] Image resource type constants.
@@ -151,9 +151,9 @@ export type CompatibleFile = File | MiniAppFile | ReactNativeFile;
 export interface TextMessageBody {
     /** [zh-CN] 消息文本内容。 [en-US] Message text content. */
     content: string;
-    /** [zh-CN] 目标翻译语言代码列表。 [en-US] Target translation language codes. */
+    /** [zh-CN] 发送前自动翻译的目标语言代码列表，不传或空数组不翻译。 [en-US] Target language codes for automatic translation before sending; omitted or empty arrays disable translation. */
     targetLanguages?: string[];
-    /** [zh-CN] 语言代码到翻译文本的映射。 [en-US] Mapping from language codes to translated text. */
+    /** [zh-CN] 语言代码到译文的映射，由自动发送翻译或接收解码填充；主动翻译 API 仅返回结果。 [en-US] Language-to-text map populated by automatic translation on send or incoming decoding; the explicit translation API only returns results. */
     translations?: Record<string, string>;
 }
 /**
@@ -307,11 +307,35 @@ export interface CombineMessageBody {
     /** [zh-CN] 当前合并消息嵌套层级。 [en-US] Current nesting level of the combined message. */
     combineLevel: number;
 }
+/**
+ * [zh-CN] 复合消息中的一段可组合内容。`type` 只出现在复合消息的分段上。
+ * [en-US] One segment inside a multi_body message. `type` exists only on these segments.
+ */
+export type MultiBodySegment = ({
+    type: 'text';
+} & TextMessageBody) | ({
+    type: 'image';
+} & ImageMessageBody) | ({
+    type: 'file';
+} & FileMessageBody) | ({
+    type: 'voice';
+} & VoiceMessageBody) | ({
+    type: 'video';
+} & VideoMessageBody) | ({
+    type: 'location';
+} & LocationMessageBody) | ({
+    type: 'custom';
+} & CustomMessageBody);
+/**
+ * [zh-CN] 复合消息正文。分段按发送顺序排列，至少 2 段。
+ * [en-US] Body of a multi_body message. Segments stay in send order and there are at least two.
+ */
+export type MultiBody = ReadonlyArray<MultiBodySegment>;
 /**
  * [zh-CN] 所有消息体的联合类型。
  * [en-US] Union of all message body types.
  */
-export type MessageBody = TextMessageBody | ImageMessageBody | FileMessageBody | VoiceMessageBody | VideoMessageBody | LocationMessageBody | CmdMessageBody | CustomMessageBody | CombineMessageBody;
+export type MessageBody = TextMessageBody | ImageMessageBody | FileMessageBody | VoiceMessageBody | VideoMessageBody | LocationMessageBody | CmdMessageBody | CustomMessageBody | CombineMessageBody | MultiBody;
 /**
  * [zh-CN] 消息对象。
  * [en-US] Message object.
@@ -339,7 +363,7 @@ export interface Message {
     ext: Record<string, unknown>;
     /** [zh-CN] 消息时间戳，单位毫秒。 [en-US] Message timestamp in milliseconds. */
     timestamp: number;
-    /** [zh-CN] 消息体。 [en-US] Message body. */
+    /** [zh-CN] 消息体。复合消息时这里直接是分段数组。 [en-US] Message body. For a multi_body message, this is the segment array. */
     body: MessageBody;
     /** [zh-CN] 消息方向。 [en-US] Message direction. */
     direct?: MessageDirect;
@@ -446,11 +470,11 @@ export interface StreamMessage extends Message {
  * [en-US] File upload progress.
  */
 export interface FileUploadProgress {
-    /** [zh-CN] 已上传字节数。 [en-US] Number of uploaded bytes. */
+    /** [zh-CN] 已上传字节数。复合消息按全部附件文件大小合计。 [en-US] Number of uploaded bytes. MultiBody messages use the combined size of all attachments. */
     loaded: number;
-    /** [zh-CN] 文件总字节数。 [en-US] Total number of bytes in the file. */
+    /** [zh-CN] 附件总字节数。复合消息是各附件文件大小之和。 [en-US] Total attachment size in bytes. MultiBody messages use the sum of every attachment file size. */
     total?: number;
-    /** [zh-CN] 上传进度百分比。 [en-US] Upload progress as a percentage. */
+    /** [zh-CN] 相对全部附件总大小的上传百分比。 [en-US] Upload percentage relative to the total size of all attachments. */
     percent?: number;
 }
 /**
@@ -498,7 +522,7 @@ export interface SendMessageOptions {
     onFileUploadComplete?: (result: FileUploadResult) => void;
     /** [zh-CN] 附件上传失败回调。 [en-US] Triggered when the attachment upload fails. */
     onFileUploadError?: (error: Error) => void;
-    /** [zh-CN] 附件上传取消回调。 [en-US]  Triggered when the attachment upload is cancelled.*/
+    /** [zh-CN] 附件上传取消回调。 [en-US] Triggered when the attachment upload is cancelled. */
     onFileUploadCanceled?: () => void;
 }
 /**

package/types/message-create.d.ts

@@ -2,7 +2,7 @@
  * [zh-CN] 创建消息方法的入参类型定义。
  * [en-US] Parameter type definitions for message creation APIs.
  */
-import type { ChatConversationType, CompatibleFile, Message, MessagePriority } from './index';
+import type { ChatConversationType, CompatibleFile, MultiBodySegment, Message, MessagePriority } from './index';
 /**
  * [zh-CN] 创建消息的通用入参。
  * [en-US] Common parameters for creating messages.
@@ -36,7 +36,7 @@ export interface CreateMessageBaseParams {
 export interface CreateTextMessageParams extends CreateMessageBaseParams {
     /** [zh-CN] 文本消息内容。 [en-US] Text message content. */
     content: string;
-    /** [zh-CN] 发送时需要翻译到的目标语言列表。 [en-US] List of target languages to translate the message into upon sending. */
+    /** [zh-CN] 发送前自动翻译的目标语言列表；不传或空数组不翻译，翻译失败不发送。 [en-US] Target languages for automatic translation before sending; omitted or empty arrays disable translation, and translation failure prevents sending. */
     targetLanguages?: string[];
 }
 /**
@@ -157,6 +157,134 @@ export interface CreateCustomMessageParams extends CreateMessageBaseParams {
     /** [zh-CN] 自定义参数。 [en-US] Custom parameters. */
     params?: Record<string, string>;
 }
+/**
+ * [zh-CN] 创建文本分段的入参。
+ * [en-US] Parameters for creating a text segment.
+ */
+export interface CreateTextMessageBodyParams {
+    /** [zh-CN] 文本内容，不能为空。 [en-US] Text content. An empty string is not allowed. */
+    content: string;
+    /** [zh-CN] 复合消息发送时不生效，这段文本不会被翻译。 [en-US] Has no effect when sending a multi_body message. This text segment is not translated. */
+    targetLanguages?: string[];
+}
+/**
+ * [zh-CN] 创建图片分段的入参。`data` 与 `originalUrl` 至少传一个。
+ * [en-US] Parameters for creating an image segment. Either `data` or `originalUrl` is required.
+ */
+export interface CreateImageMessageBodyParams {
+    /** [zh-CN] 本地图片文件。传入后必须把返回的同一个分段对象放进复合消息。 [en-US] Local image file. The returned segment object must be passed unchanged into the multi_body message. */
+    data?: CompatibleFile;
+    /** [zh-CN] 远程原图地址。 [en-US] Remote original image URL. */
+    originalUrl?: string;
+    /** [zh-CN] 文件名。传 `data` 时可由 SDK 在发送前补齐。 [en-US] File name. The SDK can fill it before sending when `data` is provided. */
+    filename?: string;
+    /** [zh-CN] 文件 MIME 类型。 [en-US] MIME type. */
+    filetype?: string;
+    /** [zh-CN] 图片宽度，单位像素。 [en-US] Image width in pixels. */
+    width?: number;
+    /** [zh-CN] 图片高度，单位像素。 [en-US] Image height in pixels. */
+    height?: number;
+    /** [zh-CN] 是否为 GIF。 [en-US] Whether the image is a GIF. */
+    isGif?: boolean;
+    /** [zh-CN] 是否按原图语义发送。 [en-US] Whether to send the original image. */
+    isOriginalImage?: boolean;
+    /** [zh-CN] 文件大小，单位字节。 [en-US] File size in bytes. */
+    fileLength?: number;
+    /** [zh-CN] 缩略图地址。 [en-US] Thumbnail URL. */
+    thumbnailUrl?: string;
+}
+/**
+ * [zh-CN] 创建文件分段的入参。`data` 与 `originalUrl` 至少传一个。
+ * [en-US] Parameters for creating a file segment. Either `data` or `originalUrl` is required.
+ */
+export interface CreateFileMessageBodyParams {
+    /** [zh-CN] 本地文件。 [en-US] Local file. */
+    data?: CompatibleFile;
+    /** [zh-CN] 远程文件地址。 [en-US] Remote file URL. */
+    originalUrl?: string;
+    /** [zh-CN] 文件名。 [en-US] File name. */
+    filename?: string;
+    /** [zh-CN] 文件 MIME 类型。 [en-US] MIME type. */
+    filetype?: string;
+    /** [zh-CN] 待发送文件大小，单位字节。 [en-US] File size in bytes. */
+    fileSize?: number;
+    /** [zh-CN] 文件长度，单位字节。 [en-US] File length in bytes. */
+    fileLength?: number;
+}
+/**
+ * [zh-CN] 创建语音分段的入参。`data` 与 `originalUrl` 至少传一个。
+ * [en-US] Parameters for creating a voice segment. Either `data` or `originalUrl` is required.
+ */
+export interface CreateVoiceMessageBodyParams {
+    /** [zh-CN] 本地语音文件。 [en-US] Local voice file. */
+    data?: CompatibleFile;
+    /** [zh-CN] 远程语音地址。 [en-US] Remote voice URL. */
+    originalUrl?: string;
+    /** [zh-CN] 文件名。 [en-US] File name. */
+    filename?: string;
+    /** [zh-CN] 文件 MIME 类型。 [en-US] MIME type. */
+    filetype?: string;
+    /** [zh-CN] 语音时长，单位秒。 [en-US] Voice duration in seconds. */
+    duration: number;
+    /** [zh-CN] 文件大小，单位字节。 [en-US] File size in bytes. */
+    fileLength?: number;
+}
+/**
+ * [zh-CN] 创建视频分段的入参。`data` 与 `originalUrl` 至少传一个。
+ * [en-US] Parameters for creating a video segment. Either `data` or `originalUrl` is required.
+ */
+export interface CreateVideoMessageBodyParams {
+    /** [zh-CN] 本地视频文件。 [en-US] Local video file. */
+    data?: CompatibleFile;
+    /** [zh-CN] 远程视频地址。 [en-US] Remote video URL. */
+    originalUrl?: string;
+    /** [zh-CN] 文件名。 [en-US] File name. */
+    filename?: string;
+    /** [zh-CN] 文件 MIME 类型。 [en-US] MIME type. */
+    filetype?: string;
+    /** [zh-CN] 视频时长，单位秒。 [en-US] Video duration in seconds. */
+    duration: number;
+    /** [zh-CN] 视频宽度，单位像素。 [en-US] Video width in pixels. */
+    width?: number;
+    /** [zh-CN] 视频高度，单位像素。 [en-US] Video height in pixels. */
+    height?: number;
+    /** [zh-CN] 文件大小，单位字节。 [en-US] File size in bytes. */
+    fileLength?: number;
+    /** [zh-CN] 视频缩略图地址。 [en-US] Video thumbnail URL. */
+    thumbnailUrl?: string;
+}
+/**
+ * [zh-CN] 创建位置分段的入参。
+ * [en-US] Parameters for creating a location segment.
+ */
+export interface CreateLocationMessageBodyParams {
+    /** [zh-CN] 纬度。 [en-US] Latitude. */
+    latitude: number;
+    /** [zh-CN] 经度。 [en-US] Longitude. */
+    longitude: number;
+    /** [zh-CN] 地址描述。 [en-US] Address description. */
+    address?: string;
+    /** [zh-CN] 建筑名称。 [en-US] Building name. */
+    buildingName?: string;
+}
+/**
+ * [zh-CN] 创建自定义分段的入参。
+ * [en-US] Parameters for creating a custom segment.
+ */
+export interface CreateCustomMessageBodyParams {
+    /** [zh-CN] 自定义事件名称。 [en-US] Custom event name. */
+    event: string;
+    /** [zh-CN] 自定义字符串参数。 [en-US] Custom string parameters. */
+    params?: Record<string, string>;
+}
+/**
+ * [zh-CN] 创建复合消息的入参。`bodies` 必须是分段工厂返回的对象，且为 2 到 20 段。
+ * [en-US] Parameters for creating a multi_body message. `bodies` must be the objects returned by segment factories and contain 2 to 20 segments.
+ */
+export interface CreateMultiBodyMessageParams extends CreateMessageBaseParams {
+    /** [zh-CN] 有序分段，2 到 20 项。不能包含命令、合并、复合消息或流式内容。 [en-US] Ordered segments, from 2 to 20. Command, combined, multi_body, and stream content is not allowed. */
+    bodies: ReadonlyArray<MultiBodySegment>;
+}
 /**
  * [zh-CN] 创建合并消息的入参。
  * [en-US] Parameters for creating a combined message.

package/upload/attachment-uploader.d.ts

@@ -11,6 +11,14 @@ export declare class AttachmentUploader {
      * 这里会串起 029 的主流程：解析本地文件、决定图片发送语义、按门槛做预检、命中则复用远端资源，未命中再进入实际上传。
      */
     prepareMessage(message: Message, options?: SendMessageOptions): Promise<Message>;
+    /**
+     * 按段串行准备复合消息的附件。文本、位置、自定义段跳过。
+     * 附件段的 msgLocalId 改成 `msgLocalId:bodyIndex`，才能取到组装时放入的文件。
+     * 任一段失败就整条不发送，已经传完的段不会单独提交。
+     */
+    private prepareMultiBodyMessage;
+    /** 失败回调补上复合消息的 msgLocalId。进度、完成和取消都不带分段序号。 */
+    private withSegmentCallbacks;
     private resolveUploadUrl;
     private hasUploadedRemoteResource;
     private prepareAttachmentUpload;

package/validators/message-create.d.ts

@@ -346,6 +346,29 @@ export declare const createCustomMessageSchema: z.ZodType<{
     isChatThread?: boolean | undefined;
     params?: Record<string, string> | undefined;
 }>;
+export declare const createMessageEnvelopeSchema: z.ZodType<{
+    conversationId: string;
+    conversationType: "singleChat" | "groupChat" | "chatRoom";
+    ext?: Record<string, unknown> | undefined;
+    timestamp?: number | undefined;
+    receiverList?: [string, ...string[]] | undefined;
+    deliverOnlineOnly?: boolean | undefined;
+    webhookEnv?: string | undefined;
+    priority?: "normal" | "high" | "low" | undefined;
+    needReadReceipt?: boolean | undefined;
+    isChatThread?: boolean | undefined;
+}, z.ZodTypeDef, {
+    conversationId: string;
+    conversationType: "singleChat" | "groupChat" | "chatRoom";
+    ext?: Record<string, unknown> | undefined;
+    timestamp?: number | undefined;
+    receiverList?: [string, ...string[]] | undefined;
+    deliverOnlineOnly?: boolean | undefined;
+    webhookEnv?: string | undefined;
+    priority?: "normal" | "high" | "low" | undefined;
+    needReadReceipt?: boolean | undefined;
+    isChatThread?: boolean | undefined;
+}>;
 export declare const createCombineMessageSchema: z.ZodType<{
     conversationId: string;
     conversationType: "singleChat" | "groupChat" | "chatRoom";
@@ -369,7 +392,7 @@ export declare const createCombineMessageSchema: z.ZodType<{
         conversationId: z.ZodString;
         conversationType: z.ZodEnum<["singleChat", "groupChat", "chatRoom"]>;
         timestamp: z.ZodNumber;
-        body: z.ZodRecord<z.ZodString, z.ZodUnknown>;
+        body: z.ZodUnion<[z.ZodRecord<z.ZodString, z.ZodUnknown>, z.ZodArray<z.ZodRecord<z.ZodString, z.ZodUnknown>, "many">]>;
         combineLevel: z.ZodOptional<z.ZodNumber>;
     }, z.ZodTypeAny, "passthrough">[];
     ext?: Record<string, unknown> | undefined;
@@ -404,7 +427,7 @@ export declare const createCombineMessageSchema: z.ZodType<{
         conversationId: z.ZodString;
         conversationType: z.ZodEnum<["singleChat", "groupChat", "chatRoom"]>;
         timestamp: z.ZodNumber;
-        body: z.ZodRecord<z.ZodString, z.ZodUnknown>;
+        body: z.ZodUnion<[z.ZodRecord<z.ZodString, z.ZodUnknown>, z.ZodArray<z.ZodRecord<z.ZodString, z.ZodUnknown>, "many">]>;
         combineLevel: z.ZodOptional<z.ZodNumber>;
     }, z.ZodTypeAny, "passthrough">[];
     ext?: Record<string, unknown> | undefined;