k2-im 0.1.31 → 0.1.33

package/dist/browser.d.ts

@@ -382,5 +382,27 @@ interface CreateBrowserApiProtocolClientInput extends Omit<ApiProtocolClientDepe
  */
 declare function createLazyBrowserApiProtocolClient(input: CreateBrowserApiProtocolClientInput, createClient?: (input: CreateBrowserApiProtocolClientInput) => Promise<ApiProtocolClient>): ApiProtocolClient;
 
-export { createLazyBrowserApiProtocolClient };
-export type { ApiProtocolClient };
+/** 浏览器图片复制的数据来源；消息读取由 Chat Kit 提供，页面生命周期由宿主提供。 */
+interface ImageClipboardSource {
+    /** 返回高清图片的明文 Blob。 */
+    loadOriginal: () => Promise<Blob>;
+    /** 高清读取或转码失败时，返回当前图片的缩略图。 */
+    loadThumbnail: () => Promise<Blob>;
+    /** 每个异步步骤完成后检查账号、会话及当前操作是否仍有效。 */
+    isCurrent: () => boolean;
+}
+/** 只检查 API 是否存在；浏览器权限拒绝仍由实际复制 Promise 报错。 */
+declare function canCopyImageToClipboard(): boolean;
+/**
+ * 在用户点击的同步调用栈内启动图片复制，返回最终复制的是高清图还是缩略图。
+ * 高清下载、解密或转码失败时，在同一个 ClipboardItem Promise 内尝试缩略图；两者失败则拒绝。
+ * 图片写入失败时再尝试一次缩略图；权限、安全或用户激活拒绝立即交由宿主提示。
+ * 传入非空 text 时复制高清图片和文字，图文失败改为只写文字，返回 text；失效取消不触发降级。
+ * 宿主必须直接调用，不能先 await 下载；账号切换或关闭页面应让 isCurrent 返回 false。
+ * @example
+ * await copyImageToClipboard({ loadOriginal, loadThumbnail, isCurrent });
+ */
+declare function copyImageToClipboard(source: ImageClipboardSource, text?: string): Promise<'original' | 'thumbnail' | 'text'>;
+
+export { canCopyImageToClipboard, copyImageToClipboard, createLazyBrowserApiProtocolClient };
+export type { ApiProtocolClient, ImageClipboardSource };

package/dist/browser.js

@@ -1 +1 @@
-export{B as createLazyBrowserApiProtocolClient}from'./chunk-SMWPQSGR.js';import'./chunk-CIY4WBFJ.js';import'./chunk-WOT6VMZA.js';
+export{Ta as canCopyImageToClipboard,Ua as copyImageToClipboard,B as createLazyBrowserApiProtocolClient}from'./chunk-OFXCH5DZ.js';import'./chunk-F6DQBWJW.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）；gift=礼品/刮刮卡（contentType=17）；robot=机器人卡片（contentType=18）；miniProgram=小程序分享卡（contentType=22）；redPacket=红包卡（contentType=25）；game=小游戏（contentType=27）；未知 wire 正文统一归一为 unknown。 */
-type MessageContentType = 'text' | 'system' | 'image' | 'video' | 'voice' | 'file' | 'sticker' | 'contact' | 'miniProgram' | 'game' | 'transfer' | 'gift' | 'call' | 'redPacket' | 'mediaAlbum' | 'robot' | 'unknown';
+type MessageContentType = 'text' | 'system' | 'image' | 'video' | 'voice' | 'file' | 'sticker' | 'contact' | 'miniProgram' | 'game' | 'transfer' | 'gift' | 'call' | 'redPacket' | 'mediaAlbum' | 'filesAlbum' | 'robot' | 'unknown';
 /**
  * 发送态（客户端态）：消息从本地创建到服务端确认的生命周期。
  * `uploading` 仅媒体消息使用：文件上传阶段（uploading→pending→sending→sent）；
@@ -125,6 +125,12 @@ type LastMessageSummary = {
     kind: 'voice';
     durationMs?: number;
 }
+/** 文件合集的有序文件数量与可选配文，文案由 i18n 决定。 */
+ | {
+    kind: 'filesAlbum';
+    count: number;
+    caption?: string;
+}
 /**
  * 媒体合集（contentType 28）。
  *
@@ -217,6 +223,13 @@ interface ImVideoBody {
     /** 文件加密类型：1=不加密，3=完整 TEA（BMessage.fileEncryptType；视频与图片同体系走完整 TEA）。 */
     fileEncryptType?: number;
 }
+/** 文件合集正文；接收保留所有有序文件项，首次发送每条只包含一个文件。 */
+interface ImFilesAlbumBody {
+    /** 文件下方的配文；无配文时省略。 */
+    caption?: string;
+    /** 文件元数据与独立解密参数；本地上传占位允许 URL 暂为空。 */
+    items: readonly ImFileBody[];
+}
 /**
  * 文件（附件）消息内容体（contentType==='file'）。领域友好类型（string/number），协议 BMessage 的 bytes/bigint 字段在 mapping 层互转。
  * 对齐 Android IMFileMsgBody / BMessage 文件字段（见 outputs/architecture/subagent-read-docs/研究Android文件上传实现.md）：
@@ -628,6 +641,8 @@ interface ImMessageBody {
     redPacket?: ImRedPacketBody;
     /** contentType==='mediaAlbum' 时的媒体合集正文（配文 + 1~9 个图片/视频项）。 */
     mediaAlbum?: ImMediaAlbumBody;
+    /** 文件合集（协议 29），与图片/视频合集独立。 */
+    filesAlbum?: ImFilesAlbumBody;
     /** contentType==='robot' 时的机器人卡片。 */
     robot?: ImRobotBody;
     /** contentType==='unknown' 时的稳定未知正文，不含原始 wire type。 */
@@ -664,7 +679,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' | 'media.contentTooLarge' | '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.resumeUnavailable' | 'media.cleanupUnconfirmed' | '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;
@@ -2290,6 +2305,11 @@ type ImEvent = {
     type: 'session:updated';
     session: ImSession;
     conversation: ConversationRef;
+}
+/** 已打开聊天的资料或权限变化，不代表新增会话列表项。 */
+ | {
+    type: 'conversation-context:updated';
+    conversation: ConversationRef;
 } | {
     type: 'session:removed';
     conversationId: string;
@@ -2366,6 +2386,11 @@ type ImEvent = {
 } | {
     type: 'sync:complete';
     conversations: ConversationRef[];
+}
+/** SDK 会话同步或前台内容读取的汇总状态；结束不代表所有请求成功。 */
+ | {
+    type: 'receiving:changed';
+    receiving: boolean;
 } | {
     type: 'auth:invalid';
     issue: ImAuthIssue;
@@ -3032,12 +3057,17 @@ interface ImMessageReactions {
     aggregates: readonly ImMessageReactionAggregate[];
 }
 /** 可渲染媒体正文；密钥和底层文件加密策略只允许留在 SDK/Core。 */
-interface ImMessageViewBody extends Omit<ImMessageBody, 'image' | 'video' | 'voice' | 'file' | 'sticker' | 'mediaAlbum'> {
+interface ImMessageViewBody extends Omit<ImMessageBody, 'image' | 'video' | 'voice' | 'file' | 'sticker' | 'mediaAlbum' | 'filesAlbum'> {
     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']>>;
+    /** 文件合集产品视图不包含逐项密钥，下载只接受消息引用与下标。 */
+    filesAlbum?: Readonly<{
+        caption?: string;
+        items: readonly Readonly<Omit<NonNullable<ImMessageBody['file']>, 'teaKey' | 'fileEncryptType'>>[];
+    }>;
     /** 合集的每一项都带自己的密钥材料，逐项剥离后才交给产品层；按项下载走 SDK handle，不需要这些字段。 */
     mediaAlbum?: Readonly<Omit<NonNullable<ImMessageBody['mediaAlbum']>, 'items'> & {
         items: readonly Readonly<Omit<ImMediaAlbumItem, 'teaKey' | 'fileEncryptType'>>[];
@@ -3200,10 +3230,13 @@ interface VoiceMessageMetadata {
 /**
  * 文件发送附加数据。
  *
- * @remarks 传 `Blob` 时必须提供 `fileName`；传 `File` 时默认读取其 name。当前协议无文件 caption，非空值显式 unsupported。
+ * @remarks 传 `Blob` 时必须提供 `fileName`；传 `File` 时默认读取其 name。非空 caption 使用协议 29，无配文默认保持 11。
  */
 interface FileMessageOptions {
+    /** 文件卡下方配文，最长 1024 字符。 */
     caption?: string;
+    /** 同一带配文批次的前序文件使用 29，即使自身没有配文。 */
+    filesAlbum?: boolean;
     fileName?: string;
     replyToMessageId?: string;
 }
@@ -3838,6 +3871,8 @@ interface ImLifecycleSnapshot {
     prepared: boolean;
     connectionDesired: boolean;
     authenticated: boolean;
+    /** 会话同步或前台内容读取仍在进行；不包含后台预取、媒体下载和写操作，也不代表同步成功。 */
+    receiving: boolean;
 }
 /** logout 的本地数据与在途消息策略。 */
 interface ImLogoutOptions {
@@ -4243,6 +4278,12 @@ type ConversationLastMessageSummary = {
     kind: 'voice';
     durationMs?: number;
 }
+/** 文件合集的文件数量与可选配文，供列表生成摘要。 */
+ | {
+    kind: 'filesAlbum';
+    count: number;
+    caption?: string;
+}
 /**
  * 媒体合集（一条消息内 1~9 个图片/视频 + 可选配文）。
  *
@@ -4668,6 +4709,11 @@ interface ConversationOpenOptions {
  */
 interface ConversationHandleSnapshot<TType extends ProductHandleConversationType = ProductHandleConversationType> {
     ref: ConversationRef<TType>;
+    /** 已校验的聊天标题与头像；即使尚无会话列表项，宿主也可正常展示聊天头部。 */
+    display?: Readonly<{
+        title: string;
+        avatar?: string;
+    }>;
     messages: readonly ImMessageView[];
     /** 本次打开时冻结的未读入口；只用于产品 UI 分隔线，不作为 SDK 已读真相。 */
     entryUnread: ConversationEntryUnreadSnapshot;
@@ -4930,7 +4976,8 @@ interface ChannelConversationMessageApi extends ConversationMessageApi {
      * 由社群管理员或社群主删除一条全员可见消息。
      *
      * @remarks 不受本人撤回时间窗限制；权限由 CHANNEL profile 预检并由服务端最终校验。成功后消息进入
-     * `deletedForEveryone` 终态，所有端显示“管理员删除了一条消息”。该方法不用于本机删除，也不适用于普通群。
+     * `deletedForEveryone` 终态；Chat Kit 时间线仅向社群群主和管理员显示删除提示，普通成员隐藏该项。
+     * 该方法不用于本机删除，也不适用于普通群。
      * @example
      * ```ts
      * const channel = await client.openConversation({ conversationType: 'channel', conversationId: '9001' })
@@ -5163,9 +5210,15 @@ interface ImMediaTasksApi {
     cancel: (taskId: string) => Promise<void>;
     /**
      * 重试 failed/canceled 任务；上传复用保留原文件，下载重新解析同一精确消息引用。
+     * 续传不可用或清理未确认时，必须先征得用户同意重新上传，再传 restartUpload:true。
+     * 用户取消后的重发始终重新上传尚未完成的资源；成功的合集项仍可复用。
+     * 下载取消已受理后即可创建新尝试，不复用旧取消 Promise；旧 loader 结束前仍占用并发槽，但不能覆盖新任务。
      * @throws 原文件已淘汰、任务仍在途或消息/下载 capability 不可用时显式拒绝。
      */
-    retry: (taskId: string) => Promise<void>;
+    retry: (taskId: string, options?: {
+        /** 用户已确认放弃旧进度并重新上传；仅上传任务接受，清理失败时仍停止。 */
+        restartUpload?: boolean;
+    }) => Promise<void>;
     /**
      * 下载并按消息正文合同解密，同一消息并发调用复用同一 Promise，成功返回 Blob。
      * @throws 消息不存在/非媒体/无远端 URL/未装配 capability、传输失败、取消或 teardown 均以稳定错误拒绝，不返回空 Blob。
@@ -5376,6 +5429,10 @@ interface ImProductEventMap {
     'sync:complete': Readonly<{
         conversations: readonly ConversationRef<ProductConversationListType>[];
     }>;
+    /** 当前账号仍有会话同步或前台内容读取；false 仅表示读取结束，错误仍走 error 事件。 */
+    'receiving:changed': Readonly<{
+        receiving: boolean;
+    }>;
     /** `lastLoginTime` 为服务端记录的上次登录时间（毫秒），仅被踢且走登录 ACK 的路径才有值。 */
     'auth:invalid': Readonly<{
         code: string;
@@ -6245,13 +6302,18 @@ interface AdvancedChannelsApi extends ImDirectoryApi<'channel'> {
 /** advanced 会话门面：保留兼容列表动作，同时暴露与 default 共用的背景产品能力。 */
 interface AdvancedConversationsApi extends ImConversationsApi, ImConversationBackgroundApi {
     /**
-     * 为产品 `openConversation` 完成缺失会话的本地对象/资料/访问校验并提交 DomainState 摘要。
+     * 为产品 `openConversation` 完成本地对象/资料/访问校验；打开本身不创建会话列表项。
      *
      * advanced/testing 的原始 handle 测试不得把它当成第二个宿主入口。
      *
      * @internal
      */
     ensureOpenableConversation: (ref: ConversationRef) => Promise<ConversationRef<'direct' | 'group' | 'channel' | 'robot'>>;
+    /**
+     * 读取已有会话或本次账号内已校验的目标资料；返回值不代表列表成员资格。
+     * @internal
+     */
+    getContext: (ref: ConversationRef) => ImSession | undefined;
 }
 /**
  * 普通宿主的真实 default client。
@@ -7498,7 +7560,9 @@ declare function defineImMediaStore(pinia: Pinia): pinia.StoreDefinition<"k2-im-
     start: () => void;
     reset: () => void;
     cancel: (taskId: string) => Promise<ImMediaOperationResult>;
-    retry: (taskId: string) => Promise<ImMediaOperationResult>;
+    retry: (taskId: string, options?: {
+        restartUpload?: boolean;
+    }) => Promise<ImMediaOperationResult>;
     cancelUpload: (messageId: string) => Promise<ImMediaOperationResult>;
     cancelDownload: (messageId: string, itemIndex?: number) => Promise<ImMediaOperationResult>;
     requestReplacement: (message: ImMessageView) => boolean;
@@ -7517,7 +7581,9 @@ declare function defineImMediaStore(pinia: Pinia): pinia.StoreDefinition<"k2-im-
     start: () => void;
     reset: () => void;
     cancel: (taskId: string) => Promise<ImMediaOperationResult>;
-    retry: (taskId: string) => Promise<ImMediaOperationResult>;
+    retry: (taskId: string, options?: {
+        restartUpload?: boolean;
+    }) => Promise<ImMediaOperationResult>;
     cancelUpload: (messageId: string) => Promise<ImMediaOperationResult>;
     cancelDownload: (messageId: string, itemIndex?: number) => Promise<ImMediaOperationResult>;
     requestReplacement: (message: ImMessageView) => boolean;
@@ -7536,7 +7602,9 @@ declare function defineImMediaStore(pinia: Pinia): pinia.StoreDefinition<"k2-im-
     start: () => void;
     reset: () => void;
     cancel: (taskId: string) => Promise<ImMediaOperationResult>;
-    retry: (taskId: string) => Promise<ImMediaOperationResult>;
+    retry: (taskId: string, options?: {
+        restartUpload?: boolean;
+    }) => Promise<ImMediaOperationResult>;
     cancelUpload: (messageId: string) => Promise<ImMediaOperationResult>;
     cancelDownload: (messageId: string, itemIndex?: number) => Promise<ImMediaOperationResult>;
     requestReplacement: (message: ImMessageView) => boolean;
@@ -7668,7 +7736,10 @@ interface ImMessageOperationsStoreActions {
     recall: (message: ImMessageView) => Promise<ImMessageActionResult>;
     deleteLocal: (message: ImMessageView) => Promise<ImMessageActionResult>;
     deleteForEveryone: (message: ImMessageView) => Promise<ImMessageActionResult>;
-    retry: (messageId: string) => Promise<ImMessageActionResult>;
+    /** 完整重传需由宿主先取得用户确认，普通重发不传 options。 */
+    retry: (messageId: string, options?: {
+        restartUpload?: boolean;
+    }) => Promise<ImMessageActionResult>;
     pin: (message: ImMessageView) => Promise<ImPinnedMessageActionResult>;
     unpin: () => Promise<ImPinnedMessageActionResult>;
     syncPinned: () => Promise<ImPinnedMessageActionResult>;
@@ -8184,7 +8255,10 @@ declare function defineImProfileDirectoryStore(pinia: Pinia): pinia.StoreDefinit
         forceRefresh?: boolean;
     }) => Promise<ImProfileDirectoryResult>;
     requestMembershipJoin: (ref: ConversationRef<"group" | "channel">, options?: {
+        /** 指定邀请码时走邀请码加入流程，不提交申请说明。 */
         inviteCode?: string;
+        /** 申请加入时附带给管理员的说明，原样交给对应群类型的 SDK API。 */
+        remarks?: string;
     }) => Promise<ImMembershipJoinActionResult>;
     updateChannelName: (ref: ConversationRef<"channel">, name: string) => Promise<ImChannelProfileActionResultFor<"update-name">>;
     updateChannelDescription: (ref: ConversationRef<"channel">, description: string) => Promise<ImChannelProfileActionResultFor<"update-description">>;
@@ -8358,7 +8432,10 @@ declare function defineImProfileDirectoryStore(pinia: Pinia): pinia.StoreDefinit
         forceRefresh?: boolean;
     }) => Promise<ImProfileDirectoryResult>;
     requestMembershipJoin: (ref: ConversationRef<"group" | "channel">, options?: {
+        /** 指定邀请码时走邀请码加入流程，不提交申请说明。 */
         inviteCode?: string;
+        /** 申请加入时附带给管理员的说明，原样交给对应群类型的 SDK API。 */
+        remarks?: string;
     }) => Promise<ImMembershipJoinActionResult>;
     updateChannelName: (ref: ConversationRef<"channel">, name: string) => Promise<ImChannelProfileActionResultFor<"update-name">>;
     updateChannelDescription: (ref: ConversationRef<"channel">, description: string) => Promise<ImChannelProfileActionResultFor<"update-description">>;
@@ -8532,7 +8609,10 @@ declare function defineImProfileDirectoryStore(pinia: Pinia): pinia.StoreDefinit
         forceRefresh?: boolean;
     }) => Promise<ImProfileDirectoryResult>;
     requestMembershipJoin: (ref: ConversationRef<"group" | "channel">, options?: {
+        /** 指定邀请码时走邀请码加入流程，不提交申请说明。 */
         inviteCode?: string;
+        /** 申请加入时附带给管理员的说明，原样交给对应群类型的 SDK API。 */
+        remarks?: string;
     }) => Promise<ImMembershipJoinActionResult>;
     updateChannelName: (ref: ConversationRef<"channel">, name: string) => Promise<ImChannelProfileActionResultFor<"update-name">>;
     updateChannelDescription: (ref: ConversationRef<"channel">, description: string) => Promise<ImChannelProfileActionResultFor<"update-description">>;
@@ -8895,6 +8975,8 @@ interface ApplyImSessionInput {
 interface ImSessionStore {
     readonly accountId: string;
     readonly connectionState: ImConnectionState;
+    /** SDK 正在同步会话、离线消息或读取前台会话内容；连接异常提示仍应优先展示。 */
+    readonly receiving: boolean;
     readonly generation: number;
     readonly phase: ImSessionPhase;
     readonly errorKey: string;
@@ -8911,6 +8993,7 @@ interface ImSessionStore {
 declare function defineImSessionStore(pinia: Pinia): pinia.StoreDefinition<"k2-im-session", Pick<{
     accountId: any;
     connectionState: any;
+    receiving: any;
     generation: any;
     phase: any;
     errorKey: any;
@@ -8927,6 +9010,7 @@ declare function defineImSessionStore(pinia: Pinia): pinia.StoreDefinition<"k2-i
 }, any>, Pick<{
     accountId: any;
     connectionState: any;
+    receiving: any;
     generation: any;
     phase: any;
     errorKey: any;
@@ -8943,6 +9027,7 @@ declare function defineImSessionStore(pinia: Pinia): pinia.StoreDefinition<"k2-i
 }, any>, Pick<{
     accountId: any;
     connectionState: any;
+    receiving: any;
     generation: any;
     phase: any;
     errorKey: any;
@@ -9039,6 +9124,8 @@ type ProductConversationHandle = ConversationHandle<ProductHandleConversationTyp
 /** Thread Store 中由 Pinia 管理的当前窗口投影；句柄、订阅和租约留在闭包中。 */
 interface ImThreadStoreState {
     activeRef: ConversationRef<ProductHandleConversationType> | null;
+    /** SDK 已校验的活动聊天展示资料；不依赖该聊天是否已进入会话列表。 */
+    display: ConversationHandleSnapshot['display'] | null;
     messages: readonly ImMessageView[];
     entryUnread: ConversationEntryUnreadSnapshot;
     draft: ConversationDraft | null;