k2-im 0.2.16 → 0.2.17

package/dist/sdk.d.ts

@@ -2553,13 +2553,13 @@ interface MediaTransferAdapterConfig {
     useAccelerateEndpoint?: boolean;
     /**
      * 统一允许 S3 分片上传和 Range 分段下载，默认 false（单次 PUT / 普通 GET）。
-     * 显式 true 后仍按 16MiB 阈值及已确认下载大小选择策略，小资源不分片。
+     * 显式 true 后，上传对象达到 8 MiB 使用 Multipart；上传片长与下载段长均为 16 MiB。
      * 开启前各桶须支持分片请求方法，并暴露上传 ETag、下载 Content-Range 与强 ETag。
      * @example { multipartTransfer: true } 同时允许大资源分片上传、下载。
      */
     multipartTransfer?: boolean;
     /**
-     * 总开关开启后，是否允许超过分片阈值（16MiB）的上传使用 S3 分片上传。
+     * 总开关开启后，是否允许达到分片阈值（8 MiB）的上传使用 S3 分片上传。
      *
      * 分片相比单次 PUT 需要各物理桶的 CORS 额外放行 POST（Create/CompleteMultipartUpload）、
      * DELETE（AbortMultipartUpload）并 `ExposeHeaders: ETag`；未配齐时分片会直接失败。
@@ -2575,8 +2575,8 @@ interface MediaTransferAdapterConfig {
     /**
      * 媒体发送阶段的并发上限；由 im-core 消费，限制媒体任务数而非分片请求数。
      *
-     * 并发按媒体体积分两档：不超过分片阈值（16 MiB）的非视频媒体走小文件档，
-     * 缺省 5；视频与超过阈值（或字节数未知）的内容走大文件档，缺省 3。
+     * 并发按媒体体积分两档：小于分片阈值（8 MiB）的非视频媒体走小文件档，
+     * 缺省 5；视频与达到阈值（或字节数未知）的内容走大文件档，缺省 3。
      * 分档只限制媒体任务数；实际 PUT/UploadPart 另受 adapter 的六路数据请求限制。
      * 两档都只接受 1-6 的整数，超出范围由 core 显式报错。
      * - 传一个数字：所有媒体共用这一个并发数，与分档前的语义一致。
@@ -2603,11 +2603,12 @@ interface MediaTransferAdapterConfig {
  * - `multipart-etag-missing`：分片响应读不到 ETag，**桶 CORS 缺 `ExposeHeaders: ETag`**，不是网络问题。
  * - `multipart-abort-failed`：分片失败后的 `AbortMultipartUpload` 清理本身失败，已上传分片可能残留并计费。
  * - `multipart-upload-failed`：分片上传因其它原因失败；`cause` 保留原始错误，消息列出分片对 CORS 的额外要求。
+ * - `download-timeout`：下载连续 30 秒无新数据，或单次 GET 超过 30 分钟。
  * - `download-range-invalid`：分段状态、范围、长度或可读响应头不符合合同。
  * - `download-object-changed`：分段之间的强 ETag 或总长度改变，拒绝混合不同文件版本。
  * - `download-range-failed`：下载返回非成功 HTTP 状态。
  */
-type MediaTransferErrorCode = 'upload-timeout' | 'bucket-unconfigured' | 'credentials-provider-missing' | 'credentials-request-failed' | 'credentials-invalid' | 'upload-source-invalid' | 'upload-size-exceeded' | 'upload-resume-unavailable' | 'multipart-etag-missing' | 'multipart-abort-failed' | 'multipart-upload-failed' | 'download-range-invalid' | 'download-object-changed' | 'download-range-failed';
+type MediaTransferErrorCode = 'upload-timeout' | 'bucket-unconfigured' | 'credentials-provider-missing' | 'credentials-request-failed' | 'credentials-invalid' | 'upload-source-invalid' | 'upload-size-exceeded' | 'upload-resume-unavailable' | 'multipart-etag-missing' | 'multipart-abort-failed' | 'multipart-upload-failed' | 'download-timeout' | 'download-range-invalid' | 'download-object-changed' | 'download-range-failed';
 /** 媒体传输统一错误：携带稳定业务码 + 可选底层 cause（诊断用，永不携带凭证明文）。 */
 declare class MediaTransferError extends Error {
     readonly code: MediaTransferErrorCode;
@@ -5304,16 +5305,26 @@ interface ImMediaTasksApi {
         includeDisplayPoster?: boolean;
     }) => Promise<(TKind extends 'video' ? LocalVideoPreviewMetadata : ImagePreviewMetadata) | null>;
     /**
-     * 从本地视频提取仅供页面展示的高清 JPEG 封面，不上传、不下载、不写缓存。
+     * 从本地视频或已有截图生成气泡封面；传入消息身份时复用独立持久缓存，不下载或上传。
      *
      * 长边最多 960px 且不放大原视频；与发送预读共用同一解码执行器。返回 Blob 由宿主创建和释放
      * object URL，不能作为 localPreviewMetadata 发进消息正文。读取失败返回 null 并记录诊断；
      * 宿主取消抛 AbortError，运行时失效或未装配能力时抛与 prepareLocalPreview 相同的明确错误。
-     * @param input.file 本地或已解密的完整视频 Blob。
+     * @param input.file 本地或已解密的完整视频 Blob；已有 poster 时可以不传。
+     * @param input.poster 发送前已经提取的截图，避免重新加载视频抽帧。
+     * @param input.message 可选消息身份，用于持久保存封面。
+     * @param input.expectedResourceUrl 取得源文件前的资源地址，防止换图后的旧结果污染缓存。
      * @param input.signal 页面卸载、换源或切会话时取消这次抽帧。
      */
     prepareLocalVideoPoster: (input: {
-        file: Blob;
+        file?: Blob;
+        poster?: Blob;
+        message?: ImMessageRef;
+        expectedResourceUrl?: string;
+        signal?: AbortSignal;
+    }) => Promise<Blob | null>;
+    /** 只读视频气泡封面缓存；不下载、不抽帧，未命中返回 null。 */
+    getCachedVideoPoster: (message: ImMessageRef, options?: {
         signal?: AbortSignal;
     }) => Promise<Blob | null>;
     /**
@@ -5329,6 +5340,34 @@ interface ImMediaTasksApi {
         file: Blob;
         signal?: AbortSignal;
     }) => Promise<Blob | null>;
+    /**
+     * 从本机原图生成独立的静态显示图，供 PC/H5 气泡使用；不下载、不上传、不改原图与消息尺寸。
+     * 传入消息引用时先查独立的显示图缓存；稳定远端资源的结果可持久保存，本地待上传资源只生成。
+     * 所有浏览器可解码格式均处理；最长边不超过 maxSize 且不放大，透明图优先保留透明度。
+     * WebP 质量 0.85，最低 0.82，目标 256 KiB、最多 512 KiB；超过字节预算时可继续缩小，失败返回 null 并记录诊断。
+     * 取消、账号失效、能力缺失和非法参数明确拒绝；返回 Blob 的 object URL 由宿主管理。
+     * @param input.file 原始或已解密的完整图片 Blob，不会被修改。
+     * @param input.maxSize 显示图最长边上限，必须是 1 到 2048 的整数。
+     * @param input.signal 页面退出、资源失效时取消准备。
+     * @param input.message 可选的精确消息引用，用于按消息、合集项、资源版本和尺寸隔离显示图缓存。
+     * @param input.expectedResourceUrl 取得 file 前记录的消息资源地址；与 message 配合使用，不匹配时返回 null，防止旧文件写入新资源缓存。
+     * @example const display = await client.media.prepareLocalImageDisplay({ file: original, maxSize: 1440 })
+     */
+    prepareLocalImageDisplay: (input: {
+        file: Blob;
+        maxSize: number;
+        message?: ImMessageRef;
+        expectedResourceUrl?: string;
+        signal?: AbortSignal;
+    }) => Promise<Blob | null>;
+    /**
+     * 仅读取指定消息和尺寸的持久显示图，不下载原图、不编码；未命中或读取期间资源失效返回 null。
+     * maxSize 必须是 1 到 2048 的整数；取消、账号失效、存储读取失败明确拒绝。
+     */
+    getCachedImageDisplay: (message: ImMessageRef, options: {
+        maxSize: number;
+        signal?: AbortSignal;
+    }) => Promise<Blob | null>;
 }
 
 /**
@@ -6032,7 +6071,7 @@ declare function resolveImEmojiToken(token: string): ImEmojiCatalogEntry | undef
  * 1 小时、按服务端过期时间提前 5 分钟失效）、同桶并发请求复用和失败后重新签发由 SDK 负责，宿主只需提供「打一次接口」的纯函数。
  *
  * 默认单次 PUT/GET；仅 multipartTransfer=true 才允许大资源分片上传、下载。
- * 各 bucket 需在对象存储侧配置 CORS 允许本站 origin 的 PUT + GET；开启分片后，超过 16MiB 的上传另需放行
+ * 各 bucket 需在对象存储侧配置 CORS 允许本站 origin 的 PUT + GET；开启分片后，达到 8 MiB 的上传另需放行
  * POST（Create/CompleteMultipartUpload）、DELETE（AbortMultipartUpload）并 ExposeHeaders: ETag。CORS 未配齐时
  * 下载还需暴露 Content-Range 与强 ETag；multipartTransfer=false 统一关闭分片上传和下载。
  * ⚠ 并发字段只由 SDK core 的媒体编排消费；adapter 会忽略该字段。高内存设备可设置 5-6，低内存设备建议 2-3。
@@ -6641,7 +6680,7 @@ interface ImResourceUploadResult {
 /** 独立资源上传器；不创建消息、Outbox 项或 client.media 任务。 */
 interface ImResourceUploader {
     /**
-     * 上传原始文件。默认单次 PUT；multipartTransfer=true 且 >16 MiB 才允许分片，沿用既有凭证刷新策略。
+     * 上传原始文件。默认单次 PUT；multipartTransfer=true 且 ≥8 MiB 才允许分片，沿用既有凭证刷新策略。
      * 失败会清理未完成分片并保留错误，显式重试须再次调用 upload；不会退回旧 HTTP 上传接口。
      * @throws 取消为 AbortError；若取消后的分片清理失败，仍报告 multipart-abort-failed。
      * 配置、凭证、S3 或清理失败直接拒绝；dispose 后不可再使用。

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "k2-im",
   "type": "module",
-  "version": "0.2.16",
+  "version": "0.2.17",
   "browserslist": {
     "js": [
       "chrome >= 93",