k2-im 0.1.37 → 0.1.38

package/dist/browser.js

@@ -1 +1 @@
-export{Ta as canCopyImageToClipboard,Ua as copyImageToClipboard,B as createLazyBrowserApiProtocolClient}from'./chunk-HUSCO5JM.js';import'./chunk-75GNCLQQ.js';import'./chunk-WOT6VMZA.js';
+export{Ta as canCopyImageToClipboard,Ua as copyImageToClipboard,B as createLazyBrowserApiProtocolClient}from'./chunk-ZERTVCH2.js';import'./chunk-4I23ADH2.js';import'./chunk-WOT6VMZA.js';

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

@@ -713,7 +713,7 @@ interface MediaTaskUpdate {
      * upload 任务子阶段。
      *
      * `waiting-upload-slot` 与 `state: 'queued'` 同时出现，表示还没开始传字节（在生成缩略图或在等上传槽位），
-     * 此时 percent 恒为 0；`transferring` 正在传字节；`finalizing` 是等待远端 URL 最终确认。
+     * 首发 percent 为 0，断点恢复时保留已有进度；`transferring` 正在传字节；`finalizing` 是等待远端 URL 最终确认。
      */
     phase?: 'waiting-upload-slot' | 'waiting-retry' | 'transferring' | 'finalizing';
     /** 当前发送意图的尝试序号与总上限。 */
@@ -722,6 +722,18 @@ interface MediaTaskUpdate {
     /** 已传与总字节数，供共享展示层估算速度。 */
     bytesTransferred?: number;
     bytesTotal?: number;
+    /** 上传合集的逐项真实字节快照；整组发送仍由外层任务控制，不为每格创建独立发送。 */
+    items?: readonly Readonly<{
+        /** 从零开始的合集位置。 */
+        itemIndex: number;
+        /** 本项实际上传字节与源文件总字节。 */
+        bytesTransferred: number;
+        bytesTotal: number;
+        /** 远端资源确认完成前最多 99%。 */
+        percent: number;
+        /** 本项状态；已完成项不随兄弟项取消或失败回退。 */
+        state: 'queued' | 'running' | 'completed' | 'failed' | 'canceled';
+    }>[];
     /** 跨刷新恢复可用性；缺省尚未建立恢复记录。 */
     recovery?: 'available' | 'session-only';
     recoveryReason?: string;
@@ -1860,6 +1872,8 @@ interface MediaAssetCacheStrategy {
     softMaxBytes: number;
     maxEntries: number;
     maxEntryBytes: number;
+    /** 完整媒体副本允许连续未访问的最长毫秒数；省略时不按时间过期，仍执行容量限制。 */
+    maxIdleMs?: number;
 }
 /** 精确按 kind 解析策略；未注册返回 undefined，不提供默认策略。 */
 interface MediaAssetCacheStrategyRegistry {
@@ -1873,8 +1887,12 @@ interface MediaAssetCacheStrategyRegistry {
  */
 interface MediaAssetCachePort {
     get: (key: MediaAssetCacheKey) => Promise<MediaAssetCacheEntry | null>;
+    /** 按输入顺序检查完整资源是否存在且未过期；不读取 Blob、不延长闲置期限，存储故障必须抛出。 */
+    hasMany?: (keys: readonly MediaAssetCacheKey[]) => Promise<readonly boolean[]>;
     put: (entry: MediaAssetCacheEntry) => Promise<'stored' | 'skipped'>;
     clear: () => Promise<void>;
+    /** 删除超过闲置期限的完整持久副本；不撤销已经返回的 Blob 或宿主持有的播放地址。 */
+    prune?: () => Promise<void>;
 }
 
 interface ImProfilePort {
@@ -2978,8 +2996,8 @@ interface IndexedDbStorageAdapterOptions {
         maxPendingWriteBytes?: number;
     };
 }
-/** 官方浏览器 adapter 始终提供背景和最近历史缓存；可选只存在于通用 `ImStoragePort` 兼容边界。 */
-type IndexedDbStorageAdapter = ImStoragePort & MediaAssetCachePort & Required<Pick<ImStoragePort, 'getConversationBackground' | 'recentHistoryCache' | 'saveConversationBackground' | 'deleteConversationBackground' | 'getDefaultConversationBackground' | 'saveDefaultConversationBackground' | 'deleteDefaultConversationBackground'>>;
+/** 官方浏览器 adapter 始终提供背景、最近历史和媒体缓存维护；通用端口为其它实现保留可选能力。 */
+type IndexedDbStorageAdapter = ImStoragePort & MediaAssetCachePort & Required<Pick<MediaAssetCachePort, 'prune' | 'hasMany'>> & Required<Pick<ImStoragePort, 'getConversationBackground' | 'recentHistoryCache' | 'saveConversationBackground' | 'deleteConversationBackground' | 'getDefaultConversationBackground' | 'saveDefaultConversationBackground' | 'deleteDefaultConversationBackground'>>;
 /**
  * 创建 IndexedDB 存储 adapter（实现 ImStoragePort）。
  * 生命周期：先 `open({ namespace })`（幂等，跑 schema 迁移），再读写；`close()` 释放句柄。
@@ -5079,9 +5097,9 @@ interface ConversationHandle<TType extends ProductHandleConversationType = Produ
         /**
          * 按稳定消息 id 打开目标附近的连续历史窗口。
          *
-         * @remarks 冷启动时允许使用同一复合会话的完整置顶预览或短期搜索结果作为只读锚点；二者都不会因此写入
-         * 普通消息 Store，partial 置顶、过期搜索结果仍因缺少可信排序信息而明确拒绝定位。
-         * @throws 目标不在本机历史或不属于当前复合会话时，抛出稳定 `IM_SDK_MESSAGE_NOT_FOUND`
+         * @remarks GROUP 完整置顶预览可按消息时间定位；CHANNEL 置顶未缓存时先按 ID 取回正式历史记录，
+         * 以服务端游标继续双向分页。短期搜索结果只作为只读锚点；partial 置顶和过期搜索结果明确拒绝定位。
+         * @throws 没有可用锚点、远端确认缺失或目标不属于当前复合会话时，抛出稳定 `IM_SDK_MESSAGE_NOT_FOUND`
          * （`category: 'state'`、`retryable: false`、`details.messageId`）。这是常见产品结果而非链路异常，
          * 调用方应据此与真正的存储/协议失败区分反馈，不要解析错误文案。
          */
@@ -5217,6 +5235,8 @@ interface ImMediaTask {
      * 上传任务不带下标：一条合集整体只有一条上传进度（所有项都传完才算这条消息发出去）。
      */
     itemIndex?: number;
+    /** 合集各项的真实上传快照；控制动作仍作用于整条消息，不包含资源或传输凭据。 */
+    items?: MediaTaskUpdate['items'];
     /** upload 来自发送链路，download 来自本产品 API。 */
     direction: 'upload' | 'download';
     /** 终态 completed/failed/canceled 不会被同一尝试的迟到 progress 回退。 */
@@ -5262,6 +5282,20 @@ interface ImMediaTask {
  * ```
  */
 interface ImMediaTasksApi {
+    /** 清除当前账号完整媒体缓存及下载断点；保留消息、草稿、上传源和已交付的播放资源，在途下载仍可完成。 */
+    clearCache: () => Promise<void>;
+    /**
+     * 按输入顺序查询完整本机媒体是否可用；不下载、不读取 Blob、不续缓存期限或创建任务。
+     * 仅支持图片/视频（含媒体合集）；未配置持久缓存时只检查内存。
+     * @throws 不支持轻量查询或存储读取失败时明确拒绝，不伪装成未命中。
+     * @example const [available] = await client.media.probeCached([messageRef])
+     */
+    probeCached: (messages: readonly ImMessageRef[]) => Promise<readonly boolean[]>;
+    /**
+     * 缓存写入、清理或过期后通知消费者重新查询；账号销毁后自动退订。
+     * @example const stop = client.media.subscribeCacheChanges(() => refreshVisibleMedia())
+     */
+    subscribeCacheChanges: (listener: () => void) => () => void;
     /**
      * 返回当前账号全部活跃任务与近期终态任务的冻结快照；总量超过 128 时只淘汰终态，极端并发活跃可暂时超过上限。
      * @throws runtime 已 logout/dispose 时抛 `IM_SDK_MEDIA_RUNTIME_INACTIVE`。
@@ -5276,7 +5310,10 @@ interface ImMediaTasksApi {
      * 取消 queued/running 任务；上传委托 core，下载中止当前 AbortController。
      * @throws 未知任务、非法状态或底层未受理时以稳定 `IM_SDK_MEDIA_TASK_*` 错误拒绝。
      */
-    cancel: (taskId: string) => Promise<void>;
+    cancel: (taskId: string, options?: {
+        /** 取消发送但保留已确认上传分片与原文件，只有用户显式重试才继续。默认取消仍清理。 */
+        retainCheckpoint?: boolean;
+    }) => Promise<void>;
     /** 暂停上传，等待请求收尾后返回；下载不支持暂停。 */
     pause: (taskId: string) => Promise<void>;
     /** 恢复已暂停上传，复用同一原文件与消息。 */
@@ -5294,19 +5331,28 @@ interface ImMediaTasksApi {
     /**
      * 重试 failed/canceled 任务；上传复用保留原文件，下载重新解析同一精确消息引用。
      * 续传不可用或清理未确认时，必须先征得用户同意重新上传，再传 restartUpload:true。
-     * 用户取消后的重发始终重新上传尚未完成的资源；成功的合集项仍可复用。
+     * 保留式取消后的重发复用已确认分片和原密钥；默认清理式取消不保证保有原文件。
      * 下载取消已受理后即可创建新尝试，不复用旧取消 Promise；旧 loader 结束前仍占用并发槽，但不能覆盖新任务。
      * @throws 原文件已淘汰、任务仍在途或消息/下载 capability 不可用时显式拒绝。
      */
     retry: (taskId: string, options?: {
         /** 用户已确认放弃旧进度并重新上传；仅上传任务接受，清理失败时仍停止。 */
         restartUpload?: boolean;
+        /** 下载断点已失效或超出缓存预算时，用户确认从头下载。 */
+        restartDownload?: boolean;
     }) => Promise<void>;
     /**
      * 下载并按消息正文合同解密，同一消息并发调用复用同一 Promise，成功返回 Blob。
      * @throws 消息不存在/非媒体/无远端 URL/未装配 capability、传输失败、取消或 teardown 均以稳定错误拒绝，不返回空 Blob。
      */
     download: (message: ImMessageRef) => Promise<Blob>;
+    /**
+     * 将最近预览的精确媒体项设为最高下载优先级，不新建或取消任务。
+     * 下一空闲任务/分片请求名额优先给该项；已发请求不中断，关闭播放器不撤销优先级。
+     * 后续调用替换上一个目标；账号退出后不可调用。
+     * @example client.media.prioritizeDownload({ conversation, messageId, itemIndex: 1 })
+     */
+    prioritizeDownload: (message: ImMessageRef) => void;
     /**
      * 仅读取当前账号内存或持久媒体资产缓存；命中返回 Blob，未缓存或类型未注册返回 `null`。
      *
@@ -6097,6 +6143,7 @@ interface ImClientOptions {
     /** 显式开启视频/文件跨刷新续传。最多 3 条、24 小时，保存加密密钥但不保存文件副本；注销清除。 */
     uploadRecovery?: {
         enabled: boolean;
+        retainFailedUploads?: boolean;
     };
 }
 /**
@@ -6713,6 +6760,7 @@ interface ChatRuntimeHostDeps {
     /** 显式启用账号隔离的跨刷新恢复记录；保存密钥、不保存原文件，注销清除。 */
     uploadRecovery?: {
         enabled: boolean;
+        retainFailedUploads?: boolean;
     };
     /** 获取 GIF provider 配置；API key 只留在宿主闭包与 SDK adapter，不进入共享 Store。 */
     getExpressionOptions?: () => ImExpressionOptions | undefined;
@@ -6990,7 +7038,11 @@ interface ChatRuntime {
     resolveMediaPreviewToRemote: (ref: ChatMediaMessageRef, contentType: 'image' | 'video' | 'sticker', byteSize?: number) => void;
     /** 为指定消息取得本地媒体播放租约；没有本地缓存时返回 `undefined`，调用方应改用远端资源。 */
     acquireMediaBlob: (ref: ChatMediaMessageRef) => MediaObjectUrlLease | undefined;
+    /** 只读检查完整本地媒体是否可用，不取得租约、不改变缓存淘汰顺序。 */
+    hasMediaBlob: (ref: ChatMediaMessageRef) => boolean;
     /** 撤销当前账号创建的全部媒体预览地址并释放 Blob 内存，切账号、退出或销毁时调用。 */
+    /** 清理当前账号完整媒体缓存和下载断点；上传源保留，正在使用的播放地址在释放后才撤销。 */
+    clearMediaCache: () => Promise<void>;
     cleanupLocalMediaBlobs: () => void;
     /** 删除会话时释放该会话绑定的本地媒体预览/播放缓存。 */
     cleanupConversationMediaBlobs: (conversation: ConversationRef<'direct' | 'group' | 'channel' | 'robot'>) => void;
@@ -7655,11 +7707,18 @@ declare function defineImMediaStore(pinia: Pinia): pinia.StoreDefinition<"k2-im-
     uploadWaiting: any;
     uploadFinalizing: any;
     replacementRequest: any;
+    cacheAvailability: any;
+    cachedAvailability: (message: ImMessageView, itemIndex?: number) => boolean | undefined;
+    cacheProbePending: any;
+    cacheAvailabilityPending: (message: ImMessageView, itemIndex?: number) => boolean;
     start: () => void;
     reset: () => void;
-    cancel: (taskId: string) => Promise<ImMediaOperationResult>;
+    cancel: (taskId: string, options?: {
+        retainCheckpoint?: boolean;
+    }) => Promise<ImMediaOperationResult>;
     retry: (taskId: string, options?: {
         restartUpload?: boolean;
+        restartDownload?: boolean;
     }) => Promise<ImMediaOperationResult>;
     pause: (taskId: string) => Promise<ImMediaOperationResult>;
     resume: (taskId: string) => Promise<ImMediaOperationResult>;
@@ -7671,7 +7730,9 @@ declare function defineImMediaStore(pinia: Pinia): pinia.StoreDefinition<"k2-im-
     resumeUpload: (message: ImMessageRef, input: {
         file: Blob;
     }) => Promise<ImMediaOperationResult>;
-    cancelUpload: (messageId: string) => Promise<ImMediaOperationResult>;
+    cancelUpload: (messageId: string, options?: {
+        retainCheckpoint?: boolean;
+    }) => Promise<ImMediaOperationResult>;
     cancelDownload: (message: string | ImMessageRef, itemIndex?: number) => Promise<ImMediaOperationResult>;
     requestReplacement: (message: ImMessageView) => boolean;
     takeReplacementRequest: () => ImMediaReplacementRequest | null;
@@ -7687,11 +7748,18 @@ declare function defineImMediaStore(pinia: Pinia): pinia.StoreDefinition<"k2-im-
     uploadWaiting: any;
     uploadFinalizing: any;
     replacementRequest: any;
+    cacheAvailability: any;
+    cachedAvailability: (message: ImMessageView, itemIndex?: number) => boolean | undefined;
+    cacheProbePending: any;
+    cacheAvailabilityPending: (message: ImMessageView, itemIndex?: number) => boolean;
     start: () => void;
     reset: () => void;
-    cancel: (taskId: string) => Promise<ImMediaOperationResult>;
+    cancel: (taskId: string, options?: {
+        retainCheckpoint?: boolean;
+    }) => Promise<ImMediaOperationResult>;
     retry: (taskId: string, options?: {
         restartUpload?: boolean;
+        restartDownload?: boolean;
     }) => Promise<ImMediaOperationResult>;
     pause: (taskId: string) => Promise<ImMediaOperationResult>;
     resume: (taskId: string) => Promise<ImMediaOperationResult>;
@@ -7703,7 +7771,9 @@ declare function defineImMediaStore(pinia: Pinia): pinia.StoreDefinition<"k2-im-
     resumeUpload: (message: ImMessageRef, input: {
         file: Blob;
     }) => Promise<ImMediaOperationResult>;
-    cancelUpload: (messageId: string) => Promise<ImMediaOperationResult>;
+    cancelUpload: (messageId: string, options?: {
+        retainCheckpoint?: boolean;
+    }) => Promise<ImMediaOperationResult>;
     cancelDownload: (message: string | ImMessageRef, itemIndex?: number) => Promise<ImMediaOperationResult>;
     requestReplacement: (message: ImMessageView) => boolean;
     takeReplacementRequest: () => ImMediaReplacementRequest | null;
@@ -7719,11 +7789,18 @@ declare function defineImMediaStore(pinia: Pinia): pinia.StoreDefinition<"k2-im-
     uploadWaiting: any;
     uploadFinalizing: any;
     replacementRequest: any;
+    cacheAvailability: any;
+    cachedAvailability: (message: ImMessageView, itemIndex?: number) => boolean | undefined;
+    cacheProbePending: any;
+    cacheAvailabilityPending: (message: ImMessageView, itemIndex?: number) => boolean;
     start: () => void;
     reset: () => void;
-    cancel: (taskId: string) => Promise<ImMediaOperationResult>;
+    cancel: (taskId: string, options?: {
+        retainCheckpoint?: boolean;
+    }) => Promise<ImMediaOperationResult>;
     retry: (taskId: string, options?: {
         restartUpload?: boolean;
+        restartDownload?: boolean;
     }) => Promise<ImMediaOperationResult>;
     pause: (taskId: string) => Promise<ImMediaOperationResult>;
     resume: (taskId: string) => Promise<ImMediaOperationResult>;
@@ -7735,7 +7812,9 @@ declare function defineImMediaStore(pinia: Pinia): pinia.StoreDefinition<"k2-im-
     resumeUpload: (message: ImMessageRef, input: {
         file: Blob;
     }) => Promise<ImMediaOperationResult>;
-    cancelUpload: (messageId: string) => Promise<ImMediaOperationResult>;
+    cancelUpload: (messageId: string, options?: {
+        retainCheckpoint?: boolean;
+    }) => Promise<ImMediaOperationResult>;
     cancelDownload: (message: string | ImMessageRef, itemIndex?: number) => Promise<ImMediaOperationResult>;
     requestReplacement: (message: ImMessageView) => boolean;
     takeReplacementRequest: () => ImMediaReplacementRequest | null;
@@ -8881,7 +8960,7 @@ interface ImQuotedMessageStoreActions {
      * 声明当前这一屏需要哪些被引原消息，并按需解析尚未解析的部分。
      *
      * 幂等且可以高频调用：已有结论的（解析成功、确认缺失、解析失败）都不会重复查询，窗口内已有的
-     * 消息也不占用回源额度。同一时刻只允许一批解析在跑，连续翻页产生的多次调用会自动合并，
+     * 消息也不占用回源额度。同一活动线程只允许一批解析在跑，连续翻页产生的多次调用会自动合并，
      * 所以在消息列表变化时无脑调一次就行，不需要宿主自己做防抖。
      *
      * 传入顺序就是解析顺序。默认按窗口顺序传即可；如果宿主能判断用户正在看哪一段，把那段的 id 放