k2-im 0.1.18 → 0.1.20

package/README.md

@@ -79,3 +79,39 @@ import { createImClient } from '@k2/im/sdk';
 import { createImI18n } from '@k2/im/i18n';
 import { createChatRuntime } from '@k2/im/chat-kit';
 ```
+
+### Web Push 绑定
+
+`client.push` 负责当前设备订阅上报、ACK 确认与连接恢复后的同步。浏览器授权、
+`ServiceWorkerRegistration`、`PushManager`、系统通知展示和点击路由由宿主负责。
+共享消息提醒规则可从 `chat-kit` 或已加载的 `chat-kit/pinia` 入口导入
+`resolveMessageNotificationDecision`，输入事实由宿主提供。
+
+```ts
+const stop = client.push.subscribe((snapshot) => {
+  // 只有 synced 表示服务端确认，浏览器创建订阅不等于绑定成功。
+  renderPushStatus(snapshot)
+})
+client.push.setWebSubscription({ userId, subscription: subscription.toJSON() })
+// 注销、关闭通知或切换账号：先停止上报，再解除浏览器订阅。
+client.push.clear()
+await subscription.unsubscribe()
+stop()
+```
+
+绑定数据只在当前账号 runtime 的内存中保存，不持久化登录凭据或订阅密钥。
+账号 logout 会销毁旧 push 对象，新账号需要重新提供浏览器真实订阅。
+`clear()` 不代表服务端解绑，不能用它替代浏览器 `unsubscribe()`。
+
+协议使用已有 `CM_PUSHTOKENSYNC` / `CM_PUSHTOKENSYNC_ACK`、Web Push 类型 20、
+普通 token 类型 0。SDK 按后端回显的帧 MsgSeq 配对，只有正确账号和 `NON_ERR` 才视为绑定成功。
+旧后端默认 0 回复进入 `unconfirmed`，其它错误码显示失败；超时或解析失败后等待正常重连，
+不会为了推送主动重连。
+
+目前未确认关闭页面时可用的后端 HTTP 续订及解绑合同。Worker 可以续订并通知打开的宿主，
+没有页面时需等下次启动由 SDK 上报；这不等于已经实现关闭期间的可靠后台同步。
+
+Web Push 绑定通过 `client.push` 同步浏览器订阅。`synced` 只表示收到账号与 MsgSeq 匹配的成功 ACK；
+`unconfirmed` 表示旧后端已回复默认错误码，绑定结果不能确认，宿主可保留浏览器订阅并显示本机已授权、
+服务端未确认。SDK 不把默认 0 当成功，也不因该旧回复自动反复上报相同订阅；正常重连会重新同步。
+后端当前每账号只有一个 Web 槽，不保证多浏览器独立收推送，`clear()` 也不代表服务端解绑。

package/dist/browser.js

@@ -1 +1 @@
-export{A as createLazyBrowserApiProtocolClient}from'./chunk-DFJWOEGQ.js';import'./chunk-RKZTPXBQ.js';import'./chunk-WOT6VMZA.js';
+export{A as createLazyBrowserApiProtocolClient}from'./chunk-4RG5NHIL.js';import'./chunk-ZDD7A2BS.js';import'./chunk-WOT6VMZA.js';

package/dist/chat-kit-pinia.d.ts

@@ -43,7 +43,7 @@ interface ConversationDraft$1 {
     updatedAt: number;
 }
 /** 消息内容类型。sticker=表情/贴图（BMessage contentType=7）；call=单聊通话记录（contentType=10）；transfer=转账（contentType=16）；miniProgram=小程序分享卡（contentType=22）；redPacket=红包卡（contentType=25）；game=小游戏（contentType=27）；未知 wire 正文统一归一为 unknown。 */
-type MessageContentType = 'text' | 'system' | 'image' | 'video' | 'voice' | 'file' | 'sticker' | 'contact' | 'miniProgram' | 'game' | 'transfer' | 'call' | 'redPacket' | 'unknown';
+type MessageContentType = 'text' | 'system' | 'image' | 'video' | 'voice' | 'file' | 'sticker' | 'contact' | 'miniProgram' | 'game' | 'transfer' | 'call' | 'redPacket' | 'mediaAlbum' | 'unknown';
 /**
  * 发送态（客户端态）：消息从本地创建到服务端确认的生命周期。
  * `uploading` 仅媒体消息使用：文件上传阶段（uploading→pending→sending→sent）；
@@ -53,7 +53,7 @@ type MessageSendStatus = 'pending' | 'uploading' | 'sending' | 'sent' | 'failed'
 /** 送达/已读态（服务端态）：消息在对端的回执状态。 */
 type MessageReceipt = 'unread' | 'delivered' | 'read';
 /** 群系统提示事件类型（结构化语义；UI/i18n 层据此渲染文案，**不在 mapper 写死中文**）。 */
-type ImSystemEventType = 'direct_contact_established' | 'direct_contact_required' | 'direct_message_refused' | 'group_info_changed' | 'group_activated' | 'group_member_joined' | 'group_member_invited' | 'group_member_left' | 'group_member_removed' | 'group_master_changed' | 'group_dismissed' | 'group_member_renamed' | 'group_message_pinned' | 'group_message_unpinned' | 'channel_name_changed' | 'channel_avatar_changed' | 'channel_announcement_changed' | 'channel_member_joined' | 'channel_member_invited' | 'channel_member_left' | 'channel_member_removed' | 'channel_owner_transferred' | 'channel_admin_added' | 'channel_admin_removed' | 'channel_dismissed' | 'channel_all_muted' | 'channel_all_unmuted' | 'channel_created' | 'channel_private_chat_disabled' | 'channel_private_chat_enabled' | 'channel_member_renamed' | 'channel_member_muted' | 'channel_member_unmuted' | 'channel_message_pinned' | 'channel_message_unpinned' | 'channel_unknown' | 'red_packet_claimed' | 'red_packet_claimed_thunder' | 'unknown';
+type ImSystemEventType = 'direct_contact_established' | 'direct_contact_required' | 'direct_message_refused' | 'group_info_changed' | 'group_activated' | 'group_member_joined' | 'group_member_invited' | 'group_member_left' | 'group_member_removed' | 'group_master_changed' | 'group_dismissed' | 'group_member_renamed' | 'group_message_pinned' | 'group_message_unpinned' | 'group_call_started' | 'group_call_ended' | 'group_call_missed' | 'channel_name_changed' | 'channel_avatar_changed' | 'channel_announcement_changed' | 'channel_member_joined' | 'channel_member_invited' | 'channel_member_left' | 'channel_member_removed' | 'channel_owner_transferred' | 'channel_admin_added' | 'channel_admin_removed' | 'channel_dismissed' | 'channel_all_muted' | 'channel_all_unmuted' | 'channel_created' | 'channel_private_chat_disabled' | 'channel_private_chat_enabled' | 'channel_member_renamed' | 'channel_member_muted' | 'channel_member_unmuted' | 'channel_message_pinned' | 'channel_message_unpinned' | 'channel_unknown' | 'red_packet_claimed' | 'red_packet_claimed_thunder' | 'unknown';
 /** 系统提示结构化内容（contentType==='system'）：存语义，不把最终中文句子当主数据源（UI/composable 据 eventType + 资料生成文案）。 */
 interface ImSystemMessageBody {
     eventType: ImSystemEventType;
@@ -120,6 +120,18 @@ type LastMessageSummary = {
 } | {
     kind: 'voice';
     durationMs?: number;
+}
+/**
+ * 媒体合集（contentType 28）。
+ *
+ * 只给结构化计数与配文，**不在这里拼「2 张照片, 1 个视频」这种文案**——中英文的量词、复数与
+ * 连接符各不相同，必须由 im-i18n 按 locale 组装。`caption` 非空时宿主优先显示配文（对齐三端）。
+ */
+ | {
+    kind: 'mediaAlbum';
+    imageCount: number;
+    videoCount: number;
+    caption?: string;
 } | {
     kind: 'encrypted';
 } | {
@@ -422,6 +434,59 @@ interface UnknownMessageBody {
     reason: 'unsupported-content-type' | 'malformed-content';
 }
 /** 按 contentType 的结构化内容体。 */
+/**
+ * 媒体合集单项：一张图片或一个视频。
+ *
+ * 对应协议 `content` JSON 里 `items[]` 的一个元素（wire `mediaType` 1=图片 2=视频）。
+ * 与 `ImImageBody` / `ImVideoBody` 的区别是它**不是**独立的一条消息——同一条合集消息里的
+ * 若干项共享消息级的撤回、已读、引用与转发语义。
+ */
+interface ImMediaAlbumItem {
+    /** 该项是图片还是视频；由协议 `mediaType` 归一而来，未知取值的项在解析阶段已被丢弃。 */
+    kind: 'image' | 'video';
+    /** 远端地址。加密项也是这个地址，解密用本项自己的 `teaKey`。 */
+    url: string;
+    /** 原始像素宽。宫格按它判定朝向，为 0 时宿主用兜底几何。 */
+    width: number;
+    /** 原始像素高。 */
+    height: number;
+    /**
+     * 视频时长，**毫秒**。
+     *
+     * 协议 `items[].duration` 本身就是毫秒，这里不做换算——注意这与单视频消息
+     * `ImVideoBody.duration`（秒）单位不同，所以刻意用 `durationMs` 命名区分。图片项没有此字段。
+     */
+    durationMs?: number;
+    /** 远端缩略图地址；可能缺省，此时只能用 `thumbData`。 */
+    thumbUrl?: string;
+    /** 内嵌缩略图/封面 JPEG 字节。加密消息服务端出不了封面，宫格首屏只能靠它。 */
+    thumbData?: Uint8Array;
+    /** 原文件 MD5。 */
+    md5?: string;
+    /** 原文件大小（字节）。 */
+    size?: number;
+    /** 本项的文件解密 TEA key；`fileEncryptType` 为 0/2/3 时必有。 */
+    teaKey?: Uint8Array;
+    /** 文件加密类型：0=跟随消息 1=不加密 2=前 32 字节 TEA 3=完整 TEA。 */
+    fileEncryptType?: number;
+    /** 发送方勾选了「原图」。仅作展示角标，不影响下载与解密。 */
+    hd?: boolean;
+}
+/**
+ * 媒体合集正文（`contentType === 'mediaAlbum'`，协议 28）。
+ *
+ * 一条消息同时承载一段可选配文和 1–9 个图片/视频项。产品上的「图文消息」就是
+ * `items.length === 1 && caption` 非空的情形，所以**分档判断一律看 `items.length`，不要看 contentType**。
+ *
+ * `items` 为空数组只会出现在入站解析残缺时（所有项的 `mediaType` 都不认识，或都无法解密）；
+ * 这种正文不可出站——出站编码会显式拒绝，避免把坏消息转发出去。
+ */
+interface ImMediaAlbumBody {
+    /** 配文；缺省与空串等价，出站不写空串。 */
+    caption?: string;
+    /** 媒体项，顺序即用户选择顺序（决定宫格 index 与首项朝向）。 */
+    items: readonly ImMediaAlbumItem[];
+}
 interface ImMessageBody {
     /** P0 文本内容（明文，解密后的结果）。 */
     text?: string;
@@ -449,6 +514,8 @@ interface ImMessageBody {
     call?: ImCallRecordBody;
     /** contentType==='redPacket' 时的红包卡片。 */
     redPacket?: ImRedPacketBody;
+    /** contentType==='mediaAlbum' 时的媒体合集正文（配文 + 1~9 个图片/视频项）。 */
+    mediaAlbum?: ImMediaAlbumBody;
     /** contentType==='unknown' 时的稳定未知正文，不含原始 wire type。 */
     unknown?: UnknownMessageBody;
 }
@@ -483,7 +550,7 @@ type ImMessageFailureReason = 'timeout' | 'rejected' | 'encrypt_failed' | 'netwo
  * 失败**展示语义**码（强类型枚举，非裸串）：供 im-i18n 按 locale 渲染失败气泡文案。
  * 由 `reason` / `SendMediaFailReason` / ACK errcode 穷尽映射而来，与 im-i18n failure catalog 键一一对应（media.* 带 mediaKind 参数）。
  */
-type ImFailureDisplayCode = 'media.empty' | 'media.noCrypto' | 'media.previewFailed' | 'media.encryptFailed' | 'media.uploadFailed' | 'media.cancelled' | 'media.invalidDuration' | 'media.uploadInterrupted' | 'contactRequired' | 'messageRefused' | 'forbiddenOrLeft' | 'contentRejected' | 'groupDismissed' | 'groupUnavailable' | 'channelDismissed' | 'channelMuted' | 'channelNotMember' | 'channelAdminRequired' | 'conversationUnsupported' | 'sendCanceled' | 'sessionLoggedOut' | 'timeout' | 'network' | 'unknown';
+type ImFailureDisplayCode = 'media.empty' | 'media.noCrypto' | 'media.previewFailed' | 'media.encryptFailed' | 'media.uploadFailed' | 'media.cancelled' | 'media.invalidDuration' | 'media.uploadInterrupted' | 'media.contentTooLarge' | 'contactRequired' | 'messageRefused' | 'forbiddenOrLeft' | 'contentRejected' | 'groupDismissed' | 'groupUnavailable' | 'channelDismissed' | 'channelMuted' | 'channelNotMember' | 'channelAdminRequired' | 'conversationUnsupported' | 'sendCanceled' | 'sessionLoggedOut' | 'timeout' | 'network' | 'unknown';
 interface ImMessageFailure {
     /** 归一后的错误码（来自 MESChatAck.errcode 或本地失败码，本地码用负值）。 */
     code: number;
@@ -511,7 +578,12 @@ interface MediaTaskUpdate {
     direction: 'upload' | 'download';
     state: 'queued' | 'running' | 'completed' | 'failed' | 'canceled';
     percent: number;
-    /** upload 任务子阶段；finalizing 是等待远端 URL 最终确认。 */
+    /**
+     * upload 任务子阶段。
+     *
+     * `waiting-upload-slot` 与 `state: 'queued'` 同时出现，表示还没开始传字节（在生成缩略图或在等上传槽位），
+     * 此时 percent 恒为 0；`transferring` 正在传字节；`finalizing` 是等待远端 URL 最终确认。
+     */
     phase?: 'waiting-upload-slot' | 'transferring' | 'finalizing';
     failure?: ImMessageFailure;
 }
@@ -1612,9 +1684,23 @@ interface MediaAssetCacheKey {
     messageId: string;
     resourceVersion: string;
 }
-/** 已解密的真实媒体资产；字节可结构化克隆并可在未来作为 Worker transferable。 */
+/**
+ * 已解密的真实媒体资产。
+ *
+ * 内容用 `Blob` 承载而不是 `Uint8Array`：图片、尤其视频可达上百 MB，读成 `Uint8Array` 就等于把整份
+ * 媒体搬进 JS 堆；`Blob` 的字节由浏览器自己托管，写缓存、读缓存和交给 `<img>` / `<video>` 全程都不需要
+ * 整读一遍。字段名从 `bytes` 改成 `blob` 是刻意的——改名让编译器强制每个读写点重新被检查，也不会留下
+ * 「有时是字节、有时是 Blob」两条内存表现完全不同的路径。
+ *
+ * `Blob` 可结构化克隆，因此 IndexedDB 能直接存，未来跨 Worker 传递也不需要改形状。
+ */
 interface MediaAssetCacheEntry extends MediaAssetCacheKey {
-    bytes: Uint8Array;
+    /** 解密后的真实媒体内容；字节量一律按 `blob.size` 核算（LRU、单条上限、诊断都用它）。 */
+    blob: Blob;
+    /**
+     * 消息体声明的 MIME。保留该字段而不是依赖 `blob.type`：解密产物的 Blob 可能没有类型，也可能带的是
+     * 下载响应的类型，与消息声明不一定一致；读缓存时要以消息声明为准。
+     */
     mimeType?: string;
 }
 /** 单种媒体的 sibling 缓存策略。 */
@@ -1632,7 +1718,7 @@ interface MediaAssetCacheStrategyRegistry {
 /**
  * 明文媒体资产缓存 Port。
  *
- * Core/SDK 只通过该端口读写真实媒体字节；IndexedDB、配额与 LRU 由浏览器实现负责。
+ * Core/SDK 只通过该端口读写真实媒体内容（以 Blob 承载）；IndexedDB、配额与 LRU 由浏览器实现负责。
  */
 interface MediaAssetCachePort {
     get: (key: MediaAssetCacheKey) => Promise<MediaAssetCacheEntry | null>;
@@ -1652,8 +1738,14 @@ interface ImProfilePort {
     clearCache?: () => void;
 }
 
-/** 会话收藏可展示的内容类型；与 iOS `isSupportCollectionMsgType` 对齐。 */
-type ImSessionFavoriteKind = 'text' | 'image' | 'video' | 'voice' | 'location' | 'file';
+/**
+ * 会话收藏可展示的内容类型；与 iOS `isSupportCollectionMsgType` 对齐。
+ *
+ * @remarks 这些值与收藏接口的 `content_type` 数值一一对应，而那个数值就是消息自己的 contentType
+ * （1=文本 2=图片 3=视频 4=语音 5=位置 11=文件 **28=媒体合集**），不是另一套收藏专用枚举。
+ * Android `MessageCollectExecute` 直接写 `message.getContentType()`，iOS 写 `msg.msgType`，两端一致。
+ */
+type ImSessionFavoriteKind = 'text' | 'image' | 'video' | 'voice' | 'location' | 'file' | 'mediaAlbum';
 /** 服务端一条会话收藏快照；列表以 HTTP 为准，不回写原消息。 */
 interface ImSessionFavoriteItem$1 {
     readonly collectId: string;
@@ -2325,6 +2417,38 @@ type EditFailReason = 'not-found' | 'not-own' | 'not-sent' | 'recalled' | 'delet
 
 type RecallFailReason = 'not-found' | 'not-own' | 'not-sent' | 'expired' | 'unsupported' | 'timeout' | 'server-expired' | 'failed' | 'disconnected';
 
+/** 浏览器 PushSubscription.toJSON() 的可移植数据；不依赖 DOM 或浏览器全局。 */
+interface ImWebPushSubscription {
+    endpoint?: string;
+    expirationTime?: number | null;
+    keys?: Record<string, string>;
+}
+/** 状态不包含 endpoint、加密密钥或登录凭据，可安全用于设置页。 */
+interface ImPushSnapshot {
+    status: 'idle' | 'pending' | 'syncing' | 'synced' | 'unconfirmed' | 'error' | 'disposed';
+    error?: 'timeout' | 'invalid-ack' | 'server-rejected' | 'send-failed';
+    /** unconfirmed 表示已收到旧后端默认错误码 ACK，不能据此证明绑定成功或失败。 */
+    serverCode?: number;
+    /** 超时等失败后等下一条连接恢复；不主动反复重报或制造重连。 */
+    requiresReconnect?: boolean;
+}
+/**
+ * 当前账号的推送绑定。浏览器授权、订阅和取消订阅由宿主拥有。
+ * setWebSubscription 只提交同步意图；只有 snapshot.status === 'synced' 表示收到服务端成功 ACK。
+ */
+interface ImPushApi {
+    /** 必须携带创建订阅时的账号，防止异步结果被交给另一个账号。离线时保留最新意图。 */
+    setWebSubscription: (input: {
+        userId: string;
+        subscription: ImWebPushSubscription;
+    }) => void;
+    /** 停止本地同步并释放订阅数据；不宣称服务端解绑，宿主仍须调用 PushSubscription.unsubscribe()。 */
+    clear: () => void;
+    snapshot: () => ImPushSnapshot;
+    /** 立即提供快照，返回退订函数；监听器的异常经宿主错误端口报告。 */
+    subscribe: (listener: (snapshot: ImPushSnapshot) => void) => () => void;
+}
+
 /**
  * 后端协议的目标服务命名。
  *
@@ -2555,11 +2679,27 @@ interface MediaTransferAdapterConfig {
      * 部署可置 false 立即退回全量单次 PutObject（大文件回到单连接与整包内存的旧行为），无需发版。
      */
     multipartUpload?: boolean;
+    /**
+     * 大于 16MiB 的明文/simple 文件是否尝试 Range 并发下载（默认 true）。
+     * 需要下载域名支持 Range，并暴露 Content-Range 与强 ETag；返回 200 时消费完整响应并记录诊断。
+     * 置 false 使用单次 GET。此开关不改变上传或整文件 TEA 的行为。
+     */
+    rangeDownload?: boolean;
     /**
      * 媒体发送阶段的并发上限；由 im-core 消费，adapter 本身仍只负责单个上传任务。
-     * 缺省为 4，允许 1-6；高并发会提高吞吐，也会增加文件加密的内存峰值。
+     *
+     * 并发按媒体体积分两档：图片与不超过分片阈值（16 MiB）的小文件走单次 PutObject、不占分片缓冲，
+     * 缺省 5；视频与超过阈值（或字节数未知）的文件走分片，每路各带分片缓冲，缺省 3。
+     * 两档都只接受 1-6 的整数，超出范围由 core 显式报错。
+     * - 传一个数字：所有媒体共用这一个并发数，与分档前的语义一致。
+     * - 传 `{ total, largeFiles }`：显式分档，`largeFiles` 不得超过 `total`。
      */
-    maxConcurrentUploads?: number;
+    maxConcurrentUploads?: number | {
+        /** 在途上传总数上限（两档合计）；缺省 5。 */
+        total?: number;
+        /** 其中大文件档的上限（视频、超过分片阈值或字节数未知的内容）；缺省 min(3, total)。 */
+        largeFiles?: number;
+    };
 }
 
 interface NetworkEventTarget {
@@ -2705,12 +2845,16 @@ interface ImMessageReactions {
     aggregates: readonly ImMessageReactionAggregate[];
 }
 /** 可渲染媒体正文；密钥和底层文件加密策略只允许留在 SDK/Core。 */
-interface ImMessageViewBody extends Omit<ImMessageBody, 'image' | 'video' | 'voice' | 'file' | 'sticker'> {
+interface ImMessageViewBody extends Omit<ImMessageBody, 'image' | 'video' | 'voice' | 'file' | 'sticker' | 'mediaAlbum'> {
     image?: Readonly<Omit<NonNullable<ImMessageBody['image']>, 'teaKey' | 'fileEncryptType'>>;
     video?: Readonly<Omit<NonNullable<ImMessageBody['video']>, 'teaKey' | 'fileEncryptType'>>;
     voice?: Readonly<Omit<NonNullable<ImMessageBody['voice']>, 'teaKey' | 'fileEncryptType'>>;
     file?: Readonly<Omit<NonNullable<ImMessageBody['file']>, 'teaKey' | 'fileEncryptType'>>;
     sticker?: Readonly<NonNullable<ImMessageBody['sticker']>>;
+    /** 合集的每一项都带自己的密钥材料，逐项剥离后才交给产品层；按项下载走 SDK handle，不需要这些字段。 */
+    mediaAlbum?: Readonly<Omit<NonNullable<ImMessageBody['mediaAlbum']>, 'items'> & {
+        items: readonly Readonly<Omit<ImMediaAlbumItem, 'teaKey' | 'fileEncryptType'>>[];
+    }>;
 }
 /**
  * 官方 Chat Kit 与宿主消息线程使用的完整稳定消息 DTO。
@@ -2786,6 +2930,44 @@ interface MiniProgramMessageOptions {
 interface TransferMessageOptions {
     replyToMessageId?: string;
 }
+/**
+ * 媒体合集里的一项：一张图片或一个视频。
+ *
+ * @remarks `kind` 由**调用方**按 MIME 分类，SDK 不嗅探文件内容——宿主的文件选择器本来就要按类型分流
+ * （GIF 得走 `sendGif`），再让 SDK 猜一次只会多一处口径不一致。
+ */
+interface MediaAlbumItemInput {
+    /** 这一项是图片还是视频。 */
+    kind: 'image' | 'video';
+    /** 原文件；`File` 可直接传，`Blob` 需调用方保证 `type` 可判定。 */
+    file: File | Blob;
+    /** 宿主创建的本地 object URL，仅供上传中的宫格显示这一格；URL 释放由宿主生命周期负责。 */
+    localPreviewUrl?: string;
+    /**
+     * 这一项的本地宽高（视频再带时长与首帧）。
+     *
+     * 不传时 SDK 会自己读一次（与单图/单视频同一条预览路径）。宫格的格子几何按原始宽高算，
+     * 缺了它整条消息的格子比例会在上传完成时跳变。
+     */
+    localPreviewMetadata?: ImagePreviewMetadata | VideoPreviewMetadata;
+}
+/**
+ * 媒体合集发送选项。
+ *
+ * @remarks 恰好 1 项且没有配文时，SDK 内部会回落成普通图片/视频消息（与 Android / iOS / 旧 H5 一致），
+ * 此时返回的仍是同样的 `SendMessageResult`，调用方不需要区分。
+ */
+interface MediaAlbumMessageOptions {
+    /** 配文，最长 1024 字符；纯空白等同于没有配文。超长由 SDK 明确拒绝，**不静默截断**。 */
+    caption?: string;
+    replyToMessageId?: string;
+    /**
+     * 发送方勾选了「原图」，写进每一项的 `hd` 标记。
+     *
+     * 本期不做任何图片/视频压缩，勾与不勾都发原文件，这个字段只让接收端显示「原图」角标。
+     */
+    hd?: boolean;
+}
 /**
  * 本地视频的固有尺寸、时长与首帧封面。
  *
@@ -3848,6 +4030,18 @@ type ConversationLastMessageSummary = {
 } | {
     kind: 'voice';
     durationMs?: number;
+}
+/**
+ * 媒体合集（一条消息内 1~9 个图片/视频 + 可选配文）。
+ *
+ * 只给计数与配文，数量文案由宿主经 im-i18n 按 locale 组装；有配文时优先显示配文。
+ * 两个计数都为 0 表示入站正文残缺（所有项都无法解析），宿主应按未知正文处理。
+ */
+ | {
+    kind: 'mediaAlbum';
+    imageCount: number;
+    videoCount: number;
+    caption?: string;
 } | {
     kind: 'encrypted';
 } | {
@@ -4300,6 +4494,16 @@ interface ConversationMessageApi {
     sendFile: (file: File | Blob, options?: FileMessageOptions) => Promise<SendMessageResult>;
     /** 发送 GIF 贴图；原文件明文上传 sticker bucket，消息固定 EXPRESSION/LINK/GIF。 */
     sendGif: (file: File | Blob, options?: GifMessageOptions) => Promise<SendMessageResult>;
+    /**
+     * 发送媒体合集：1~9 个图片/视频合成**一条**消息，可带一段配文。
+     *
+     * @remarks 全部项上传成功才发出；任一项失败整条失败，不发半条消息。恰好 1 项且没有配文时
+     * SDK 内部回落成普通图片/视频消息（三端一致）。**校验是整条的**——某一项超限会拒绝整条，
+     * 因为协议上它就是一条消息，没有「发一半」这种状态。
+     *
+     * GIF 不能进合集（三端一致），调用方要先按 MIME 把它拆出去走 `sendGif`。
+     */
+    sendMediaAlbum: (items: readonly MediaAlbumItemInput[], options?: MediaAlbumMessageOptions) => Promise<SendMessageResult>;
     /** 发送已经托管在远端的静态贴图；资源和贴图包身份均为必填合同。 */
     sendSticker: (asset: ImStickerAssetInput, options?: ExpressionMessageOptions) => Promise<SendMessageResult>;
     /** 发送已经托管在远端的 GIF；Giphy 没有 package identity，输入不得提供 packageId。 */
@@ -4380,6 +4584,43 @@ interface ConversationMessageApi {
      * ```
      */
     forward: (messageIds: readonly string[], targets: readonly ConversationRef<ProductHandleConversationType>[]) => Promise<ForwardMessagesResult>;
+    /**
+     * 把媒体合集里的第 `itemIndex` 项，当成**一条独立的图片或视频消息**转发到多个目标会话。
+     *
+     * 用途：全屏预览里点转发时，用户要转的是当前正在看的这一格，而不是整条合集。
+     *
+     * @remarks
+     * 与 `forward` 的区别是产出的消息类型变了（合集 → 图片/视频），所以是独立方法而不是给 `forward`
+     * 放宽入参。与 `forward` 相同的是：复用该项已有的远端地址与解密 key，**不重新上传**；目标会话仍由
+     * direct/GROUP/CHANNEL 各自的 SendStrategy 组帧入 Outbox。
+     *
+     * 视频项在合集里的时长是毫秒，转成单视频消息时 SDK 会换算成协议要求的秒，调用方不需要处理。
+     * 合集项上的「原图」角标与远端缩略图地址不会带到单媒体消息上——单图/单视频正文没有这两个字段。
+     *
+     * 三种情况进 `failed`：源消息不是媒体合集（`IM_SDK_FORWARD_CONTENT_UNSUPPORTED`）、
+     * `itemIndex` 越界或该项已不存在（`IM_SDK_MEDIA_ALBUM_ITEM_INVALID`）、该项还没有可复用的远端地址
+     * （还在上传或入站残缺，`IM_SDK_FORWARD_MEDIA_NOT_READY`，可重试）。
+     *
+     * **还有一类结果三个数组会全空**：源消息已撤回、已被双删、解密失败、在本地已经查不到，
+     * 或它的类型本身就不可转发时，这条消息在预检阶段就被剔除，只出现在 `skippedSourceMessageIds` 里。
+     * 这与 `forward` 的批量语义一致（批量转发本来就要把不可转的源剔掉再发其余的），
+     * 但单条调用时它意味着**什么都没发出去**。所以调用方判成功要看 `sent`，
+     * 不要只判 `failed.length > 0`——那样在「预览期间原消息被撤回」这种竞态下会既不发送也不提示。
+     *
+     * @param messageId 当前 handle 中的合集消息 id。
+     * @param itemIndex 宫格里的项下标，从 0 起；必须是非负整数。
+     * @param targets 目标会话，最多 9 个。
+     * @example
+     * ```ts
+     * const result = await handle.messages.forwardMediaAlbumItem('message-42', 2, [
+     *   { conversationType: 'direct', conversationId: '1001' },
+     * ])
+     * // 一条都没发出去就要提示：失败原因在 failed 里，源消息被剔除时 failed 也是空的。
+     * if (result.sent.length === 0)
+     *   showError(result.failed[0]?.error.code ?? 'IM_SDK_FORWARD_CONTENT_UNSUPPORTED')
+     * ```
+     */
+    forwardMediaAlbumItem: (messageId: string, itemIndex: number, targets: readonly ConversationRef<ProductHandleConversationType>[]) => Promise<ForwardMessagesResult>;
     /**
      * 按 id 向服务端取回本地没有的消息，并回填进本地历史。
      *
@@ -4589,6 +4830,14 @@ interface ImMessageRef {
     conversation: ConversationRef<ProductHandleConversationType>;
     /** 当前会话内的稳定消息 id。 */
     messageId: string;
+    /**
+     * 媒体合集里的第几项（从 0 起）。
+     *
+     * **只有合集消息需要它，也只有合集消息接受它**：一条合集是一条消息、多个文件，光靠 messageId
+     * 指不到具体某一项。给单媒体消息传这个字段会被显式拒绝，而不是忽略——忽略的话调用方以为自己
+     * 在下载第 3 项，实际拿到的是整条消息的唯一媒体。
+     */
+    itemIndex?: number;
 }
 /**
  * 可观察媒体上传/下载任务的只读产品投影。
@@ -4603,13 +4852,27 @@ interface ImMediaTask {
     messageId: string;
     /** 关联消息的精确会话 sibling。 */
     ref: ConversationRef<ProductHandleConversationType>;
+    /**
+     * 媒体合集的项下标；单媒体消息与全部上传任务为 undefined。
+     *
+     * 一条合集的多项共用同一个 messageId，各自是独立的下载任务。调用方按 messageId 找任务时
+     * 必须连这个字段一起比，否则并发下载两项时会把另一项的进度读成自己的。
+     * 上传任务不带下标：一条合集整体只有一条上传进度（所有项都传完才算这条消息发出去）。
+     */
+    itemIndex?: number;
     /** upload 来自发送链路，download 来自本产品 API。 */
     direction: 'upload' | 'download';
     /** 终态 completed/failed/canceled 不会被同一尝试的迟到 progress 回退。 */
     state: 'queued' | 'running' | 'completed' | 'failed' | 'canceled';
     /** 0-100 的归一化整数。 */
     percent: number;
-    /** upload 子阶段；finalizing 为等待对象存储确认。 */
+    /**
+     * upload 子阶段。
+     *
+     * `waiting-upload-slot` 与 `state: 'queued'` 同时出现，表示这条媒体还没开始传字节（在生成缩略图或在
+     * 等上传槽位），此时 `percent` 恒为 0——宿主应显示「等待中」而不是把 0 当成停住的进度。
+     * `transferring` 是正在传字节，`finalizing` 是字节已传完、在等对象存储确认。
+     */
     phase?: 'waiting-upload-slot' | 'transferring' | 'finalizing';
     /** 可供产品按 code/category 决策的稳定错误；不含底层 URL、密钥或响应正文。 */
     error?: ImSdkErrorShape;
@@ -5632,6 +5895,8 @@ interface AdvancedConversationsApi extends ImConversationsApi, ImConversationBac
  * ```
  */
 interface ImProductClient {
+    /** 当前设备推送订阅的服务端绑定与同步状态。 */
+    readonly push: ImPushApi;
     readonly session: ImSessionApi;
     readonly capabilities: ImConversationCapabilitiesApi;
     readonly conversations: ImConversationListApi;
@@ -5837,7 +6102,7 @@ declare function useImApplicationsStore(pinia?: Pinia): ImApplicationsStore;
  * 二期收敛：kit 框架无关层不再直接产中文，改产本联合里的码 + 参数（如 {reason}/{label}/{size}），由宿主经 im-i18n 渲染。
  * 动态原始报错（error.message）作为 `{reason}` 参数拼接，不入 catalog（属诊断，不翻译）。
  */
-type ImServiceTextKey = 'common.notConnected' | 'common.selectOrOpenConversation' | 'common.conversationTypeNotReady' | 'common.conversationNotReady' | `recall.${RecallFailReason}` | `edit.${EditFailReason}` | 'localDelete.done' | 'localDelete.notFound' | 'localDelete.inFlight' | 'localDelete.failed' | 'channelDelete.notFound' | 'channelDelete.unsupported' | 'channelDelete.notSent' | 'channelDelete.unavailable' | 'channelDelete.forbidden' | 'channelDelete.timeout' | 'channelDelete.failed' | 'channelDelete.disconnected' | 'directBlock.contactRequired' | 'groupBlock.left' | 'groupBlock.removed' | 'groupBlock.dismissed' | 'groupBlock.unknownRestricted' | 'channelBlock.guest' | 'channelBlock.left' | 'channelBlock.removed' | 'channelBlock.dismissed' | 'channelBlock.muted' | 'channelBlock.allMembersMuted' | 'channelBlock.currentUserMuted' | 'channelBlock.blacklisted' | 'channelBlock.unknownRestricted' | 'channelProfile.loadFailed' | 'channelProfile.notFound' | 'channelProfile.retryAction' | 'channelMembers.title' | 'channelMembers.searchPlaceholder' | 'channelMembers.loading' | 'channelMembers.loadFailed' | 'channelMembers.retryAction' | 'channelMembers.empty' | 'channelMembers.loadingMore' | 'channelMembers.loadMoreFailed' | 'channelMembers.exhausted' | 'channelMembers.loadMoreAction' | 'label.image' | 'label.video' | 'label.file' | 'label.sticker' | 'send.failed' | 'send.retryFailed' | 'send.cancelFailed' | 'send.mediaFailed' | 'send.mediaEmpty' | 'send.mediaCancelled' | 'send.mediaCountLimit' | 'send.mediaTooLarge' | 'send.videoTooLong' | 'send.videoDurationUnavailable' | 'send.voiceEmpty' | 'send.voiceStorageNotConfigured' | 'send.voiceCancelled' | 'send.voiceFailed' | 'media.voiceNotReady' | 'media.voiceLoadEmpty' | 'media.voiceLoadFailed' | 'media.videoOpenEmpty' | 'media.videoLoadFailed' | 'media.imageInvalid' | 'media.imageLoadFailed' | 'media.fileDownloadEmpty' | 'media.fileDownloadFailed' | 'conversation.muteEnableFailed' | 'conversation.muteDisableFailed' | 'read.markReadFailed' | 'pinned.forbidden' | 'pinned.network' | 'pinned.contract' | 'pinned.unsupported' | 'pinned.failed' | 'pinned.previewUnavailable' | 'pinned.locateFailed' | 'pinned.recalled' | 'pinned.deleted' | 'pinned.protected' | 'pinned.pinAction' | 'pinned.unpinAction' | 'pinned.unpinConfirm' | 'pinned.cancelAction' | 'lifecycle.missingLoginState' | 'lifecycle.prepareFailed' | 'lifecycle.missingConnectParams' | 'lifecycle.connectFailed' | 'lifecycle.disposed' | 'forward.emptyInput' | 'forward.allSkipped' | 'forward.partialSkipped' | 'forward.done' | 'forward.failed';
+type ImServiceTextKey = 'common.notConnected' | 'common.selectOrOpenConversation' | 'common.conversationTypeNotReady' | 'common.conversationNotReady' | `recall.${RecallFailReason}` | `edit.${EditFailReason}` | 'localDelete.done' | 'localDelete.notFound' | 'localDelete.inFlight' | 'localDelete.failed' | 'channelDelete.notFound' | 'channelDelete.unsupported' | 'channelDelete.notSent' | 'channelDelete.unavailable' | 'channelDelete.forbidden' | 'channelDelete.timeout' | 'channelDelete.failed' | 'channelDelete.disconnected' | 'directBlock.contactRequired' | 'groupBlock.left' | 'groupBlock.removed' | 'groupBlock.dismissed' | 'groupBlock.unknownRestricted' | 'channelBlock.guest' | 'channelBlock.left' | 'channelBlock.removed' | 'channelBlock.dismissed' | 'channelBlock.muted' | 'channelBlock.allMembersMuted' | 'channelBlock.currentUserMuted' | 'channelBlock.blacklisted' | 'channelBlock.unknownRestricted' | 'channelProfile.loadFailed' | 'channelProfile.notFound' | 'channelProfile.retryAction' | 'channelMembers.title' | 'channelMembers.searchPlaceholder' | 'channelMembers.loading' | 'channelMembers.loadFailed' | 'channelMembers.retryAction' | 'channelMembers.empty' | 'channelMembers.loadingMore' | 'channelMembers.loadMoreFailed' | 'channelMembers.exhausted' | 'channelMembers.loadMoreAction' | 'label.image' | 'label.video' | 'label.file' | 'label.sticker' | 'send.failed' | 'send.retryFailed' | 'send.cancelFailed' | 'send.mediaFailed' | 'send.mediaEmpty' | 'send.mediaCancelled' | 'send.mediaCountLimit' | 'send.mediaTooLarge' | 'send.mediaFormatMismatch' | 'send.videoTooLong' | 'send.videoDurationUnavailable' | 'send.voiceEmpty' | 'send.voiceStorageNotConfigured' | 'send.voiceCancelled' | 'send.voiceFailed' | 'media.uploadWaiting' | 'media.voiceNotReady' | 'media.voiceLoadEmpty' | 'media.voiceLoadFailed' | 'media.videoOpenEmpty' | 'media.videoLoadFailed' | 'media.imageInvalid' | 'media.imageLoadFailed' | 'media.fileDownloadEmpty' | 'media.fileDownloadFailed' | 'conversation.muteEnableFailed' | 'conversation.muteDisableFailed' | 'conversation.backgroundLoadFailed' | 'read.markReadFailed' | 'storage.failed' | 'sync.failed' | 'draft.saveFailed' | 'history.returnLatestFailed' | 'pinned.forbidden' | 'pinned.network' | 'pinned.contract' | 'pinned.unsupported' | 'pinned.failed' | 'pinned.previewUnavailable' | 'pinned.locateFailed' | 'pinned.recalled' | 'pinned.deleted' | 'pinned.protected' | 'pinned.pinAction' | 'pinned.unpinAction' | 'pinned.unpinConfirm' | 'pinned.cancelAction' | 'lifecycle.missingLoginState' | 'lifecycle.prepareFailed' | 'lifecycle.missingConnectParams' | 'lifecycle.connectFailed' | 'lifecycle.disposed' | 'forward.emptyInput' | 'forward.allSkipped' | 'forward.partialSkipped' | 'forward.done' | 'forward.failed';
 
 /**
  * 本文件管理图片和视频本地预览地址的完整生命周期。
@@ -5993,6 +6258,13 @@ interface ChatMediaMessageRef {
     conversationId: string;
     /** 需要查找本地媒体预览的消息 ID。 */
     messageId: string;
+    /**
+     * 媒体合集的项下标（第几格）。
+     *
+     * 一条合集的 9 格共用同一个 messageId，各自是独立资源；不带下标会让它们落到同一个注册表键上，
+     * 后绑定的一格把先绑定的挤掉并撤销其地址。单媒体消息不传这个字段。
+     */
+    itemIndex?: number;
 }
 /**
  * Chat Kit 提供给共享 Store 和业务 Service 的账号运行接口。
@@ -6796,8 +7068,8 @@ declare function useImHistoryReturnAfterSendCoordinator(pinia?: Pinia): ImHistor
  * 为页面展示当前账号的媒体上传/下载进度，并提供取消、重试和重新选择原文件入口。
  *
  * 【状态从哪里来】
- * Store 订阅 SDK 的完整媒体任务列表，向页面提供任务、当前线程每条消息的上传百分比、是否正在完成
- * 最后处理以及稳定错误。传输、任务状态、消息状态、取消和重试都由 SDK 维护；Store 不模拟进度，也不
+ * Store 订阅 SDK 的完整媒体任务列表，向页面提供任务、当前线程每条消息的上传百分比、是否还在排队等
+ * 上传槽位、是否正在完成最后处理以及稳定错误。传输、任务状态、消息状态、取消和重试都由 SDK 维护；Store 不模拟进度，也不
  * 创建第二套上传队列。
  *
  * 【提供的能力】
@@ -6839,6 +7111,14 @@ type ImMediaOperationResult = Readonly<{
     reason: 'not-ready' | 'not-found' | 'failed' | 'stale';
     error?: ImMediaStoreError;
 }>;
+/**
+ * 下载任务在 `downloadTasks` / `downloadProgress` 里的键。
+ *
+ * 一条媒体合集的每一项是各自独立的下载任务，却共用同一个 messageId；只用 messageId 做键的话
+ * 后一项会把前一项整条覆盖掉，宿主读到的进度属于另一格。单媒体消息不带下标，键与历史保持一致，
+ * 宿主既有的 `downloadProgress[message.id]` 读法不受影响。
+ */
+declare function imMediaDownloadKey(messageId: string, itemIndex?: number): string;
 /** 取得当前 Vue setup 或显式 Pinia 的媒体任务 Store；不会隐式创建 Runtime。 */
 declare function useImMediaStore(pinia?: Pinia): any;
 
@@ -8320,5 +8600,25 @@ type ImThreadStore = Store<'k2-im-thread', ImThreadStoreState, Record<string, ne
 /** 取得当前 Vue setup 或显式 Pinia 的消息线程 Store；每个实例只管理一个当前会话。 */
 declare function useImThreadStore(pinia?: Pinia): ImThreadStore;
 
-export { applicationKey, createAndInstallImChatKit, createImChatKitContext, disposeImChatKit, ensureImChatKitSelfProfile, getImChatKitContext, installImChatKit, useImApplicationsStore, useImCapabilitiesStore, useImComposerStore, useImConversationActivationCoordinator, useImConversationDeletionCoordinator, useImConversationListStore, useImExpressionStore, useImHistoryReturnAfterSendCoordinator, useImMediaStore, useImMessageOperationsStore, useImProfileDirectoryStore, useImQuotedMessageStore, useImReactionStore, useImSearchStore, useImSessionFavoritesStore, useImSessionStore, useImThreadPagingStore, useImThreadReturnToLatestCoordinator, useImThreadStore };
+/** 新消息提醒所需的领域与宿主事实；本模块不读取浏览器、路由或全局设置。 */
+interface MessageNotificationInput {
+    source: 'live' | 'offline';
+    senderId: string;
+    accountId: string;
+    contentType: string;
+    muted: boolean;
+    globallyEnabled: boolean;
+    visibilityState: 'visible' | 'hidden';
+    permission: 'default' | 'denied' | 'granted' | null;
+}
+type MessageNotificationDecision = {
+    show: true;
+} | {
+    show: false;
+    reason: 'not-live' | 'unsupported' | 'permission-denied' | 'page-visible' | 'self-message' | 'system-message' | 'conversation-muted' | 'globally-disabled';
+};
+/** PC/H5 共用的实时消息提醒规则；离线历史回放不逐条弹通知。 */
+declare function resolveMessageNotificationDecision(input: MessageNotificationInput): MessageNotificationDecision;
+
+export { applicationKey, createAndInstallImChatKit, createImChatKitContext, disposeImChatKit, ensureImChatKitSelfProfile, getImChatKitContext, imMediaDownloadKey, installImChatKit, resolveMessageNotificationDecision, useImApplicationsStore, useImCapabilitiesStore, useImComposerStore, useImConversationActivationCoordinator, useImConversationDeletionCoordinator, useImConversationListStore, useImExpressionStore, useImHistoryReturnAfterSendCoordinator, useImMediaStore, useImMessageOperationsStore, useImProfileDirectoryStore, useImQuotedMessageStore, useImReactionStore, useImSearchStore, useImSessionFavoritesStore, useImSessionStore, useImThreadPagingStore, useImThreadReturnToLatestCoordinator, useImThreadStore };
 export type { ApplyImSessionInput, ChatRuntimeFactories, ChatRuntimeHostDeps, ImApplicationDomainCounts, ImApplicationReviewOperation, ImApplicationReviewResult, ImApplicationsReloadResult, ImApplicationsStoreError, ImCapabilitiesStore, ImChannelManagementMemberTarget, ImChannelMemberManagementOperation, ImChannelMemberManagementResult, ImChannelMemberManagementResultFor, ImChannelProfileActionResult, ImChannelProfileActionResultFor, ImChannelProfileOperation, ImChatKitContext, ImChatKitInstallation, ImComposerStore, ImComposerStoreActions, ImComposerStoreState, ImComposerSubmitResult, ImConversationActivationCoordinator, ImConversationActivationError, ImConversationActivationResult, ImConversationDeletionCoordinator, ImConversationDeletionError, ImConversationDeletionResult, ImConversationListActionError, ImConversationListMutationOperation, ImConversationListMutationResult, ImConversationListRefreshResult, ImConversationListStore, ImDirectContactActionResult, ImDirectContactActionResultFor, ImDirectContactOperation, ImDirectoryState, ImEmojiPanelRecentEntry, ImEmojiRecentEntry, ImExpressionLoadStatus, ImExpressionOperation, ImExpressionOperationResult, ImExpressionRecentPersistencePort, ImExpressionRecentPersistenceSnapshot, ImExpressionRecentViewItem, ImExpressionResetOptions, ImExpressionSendResult, ImExpressionStore, ImExpressionStoreActions, ImExpressionStoreError, ImExpressionStoreGetters, ImExpressionStoreState, ImForwardPreparationResult, ImGameRecentEntry, ImGroupMemberManagementOperation, ImGroupMemberManagementResult, ImGroupMemberManagementResultFor, ImGroupProfileActionResult, ImGroupProfileActionResultFor, ImGroupProfileOperation, ImHistoryReturnAfterSendCoordinator, ImHistoryReturnError, ImHistoryReturnExecution, ImHistoryReturnResult, ImMediaOperationResult, ImMediaReplacementRequest, ImMediaStoreError, ImMediaTaskPresentation, ImMembershipJoinActionResult, ImMembershipJoinOperation, ImMessageOperationsStore, ImMessageOperationsStoreActions, ImMessageOperationsStoreState, ImMessageSelectionResult, ImPersistedEmojiPanelRecentEntry, ImPersistedEmojiRecentEntry, ImPersistedExpressionAssetRecentEntry, ImPersistedGameRecentEntry, ImProfileAccessDestination, ImProfileAccessResult, ImProfileDirectoryResult, ImQuotedMessageState, ImQuotedMessageStore, ImQuotedMessageStoreActions, ImQuotedMessageStoreState, ImReactionOperationResult, ImReactionStore, ImReactionStoreActions, ImReactionStoreError, ImReactionStoreState, ImSearchOperationResult, ImSessionFavoritesReloadResult, ImSessionFavoritesStoreError, ImSessionFavoritesWriteResult, ImSessionPhase, ImSessionStore, ImThreadPagingActions, ImThreadPagingState, ImThreadPagingStore, ImThreadReturnToLatestCoordinator, ImThreadStore, ImThreadStoreActions, ImThreadStoreState };