k2-im 0.1.15 → 0.1.16

package/dist/browser.js

@@ -1 +1 @@
-export{A as createLazyBrowserApiProtocolClient}from'./chunk-HN4N3I2C.js';import'./chunk-ZPQ3HWNX.js';import'./chunk-WOT6VMZA.js';
+export{A as createLazyBrowserApiProtocolClient}from'./chunk-KBKZ27GY.js';import'./chunk-KZM3GLRL.js';import'./chunk-WOT6VMZA.js';

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

@@ -3872,22 +3872,38 @@ interface DirectConversationCapabilities {
     canUseMessageActions: CapabilityDecision;
     canManageRelationship: CapabilityDecision;
 }
+/**
+ * 普通群能力快照。
+ *
+ * 普通群只有「群主」和「普通成员」两档身份，没有管理员：`ownerId` 是唯一的身份依据。
+ * 因此这里的能力分两类：改群资料、踢人、置顶消息、转让、改入群验证只给群主；
+ * 发消息、看成员、邀请新成员、退群只要求当前账号仍在群内。
+ */
 interface GroupConversationCapabilities {
+    /** 当前账号与该群的关系；`left`/`removed`/`dismissed` 会让写动作整体不可用。 */
     membership: NonNullable<ConversationListItem['groupState']> | 'unknown';
+    /** 群主 userId；群资料尚未加载时为 undefined，此时群主专属能力是 `unknown`。 */
     ownerId?: string;
+    /** 当前账号是否为群主。 */
     isOwner: boolean;
     canSendMessages: CapabilityDecision;
     canOpenProfile: CapabilityDecision;
     canReadHistory: CapabilityDecision;
     canUseMessageActions: CapabilityDecision;
+    /** 看成员名单：在群即可，普通群没有「隐藏成员列表」开关。 */
     canViewMembers: CapabilityDecision;
+    /** 改群名称、群头像：仅群主。 */
     canEditProfile: CapabilityDecision;
+    /** 邀请新成员：在群即可，不限群主。 */
     canInviteMembers: CapabilityDecision;
+    /** 踢人等成员治理：仅群主。 */
     canManageMembers: CapabilityDecision;
     canPinMessages: CapabilityDecision;
     canUnpinMessages: CapabilityDecision;
+    /** 转让群主：仅群主。 */
     canTransferOwnership: CapabilityDecision;
     canLeave: CapabilityDecision;
+    /** 修改入群验证方式：仅群主。 */
     canUpdateVerification: CapabilityDecision;
 }
 interface ChannelConversationCapabilities {
@@ -4051,6 +4067,36 @@ interface ImExpressionsApi {
     };
 }
 
+/** 回源失败的原因与能否重试。 */
+interface MessagesByIdFailure {
+    /**
+     * 能否稍后重试。
+     *
+     * 服务端错误、网络异常和登录过期都算可以重试；无权限（已退群或已退出频道）和参数错误是终态，
+     * 再试多少次结果都一样，调用方应该停下来而不是反复打接口。
+     */
+    retryable: boolean;
+    /** 原始错误，供诊断与上报。 */
+    error: unknown;
+}
+/** 回源的汇总结果。三组 id 互不重叠，合起来覆盖调用方传入的全部有效 id。 */
+interface ImMessagesByIdResult<TMessage> {
+    /** 成功取回的消息。已经进了本地历史，后续本地查询就能命中。 */
+    readonly messages: readonly TMessage[];
+    /**
+     * 服务端确认没有这些消息：已被删除、超出保留期被清理，或对当前用户不可见。
+     * 这是终态，调用方应记下来并停止重试。
+     */
+    readonly missingMessageIds: readonly string[];
+    /**
+     * 这次没取到、但不代表不存在的消息 id（请求失败了）。
+     * 是否值得再试看 `failure.retryable`。
+     */
+    readonly unresolvedMessageIds: readonly string[];
+    /** `unresolvedMessageIds` 非空时的失败原因；全部取到或全部确认缺失时不存在。 */
+    readonly failure?: MessagesByIdFailure;
+}
+
 /**
  * 绑定单个精确会话的产品句柄与独立连续消息窗口。
  * 句柄提供历史、消息、草稿、已读和免打扰动作；SDK/DomainState 仍拥有消息真相，关闭只释放窗口和订阅。
@@ -4235,6 +4281,40 @@ interface ConversationMessageApi {
      * ```
      */
     forward: (messageIds: readonly string[], targets: readonly ConversationRef<ProductHandleConversationType>[]) => Promise<ForwardMessagesResult>;
+    /**
+     * 按 id 向服务端取回本地没有的消息，并回填进本地历史。
+     *
+     * 用途：渲染引用回复时，被引原消息可能从没拉到过本机（没翻到那一页、清过缓存、换了设备或浏览器）。
+     * 这时 `resolveMessage` 会返回 null，但服务端其实有这条消息，用本接口取回来。
+     *
+     * @remarks
+     * 和 `resolveMessage` 的分工：`resolveMessage` 只读本机、不发请求，适合先快速试一遍；本接口才发请求。
+     * 正确用法是先对每条 id 调 `resolveMessage`，把返回 null 的收集起来一次性交给本接口，不要逐条调用。
+     *
+     * 取回的消息只回填历史正文，不会改动会话列表最后一条摘要，也不会产生未读或 @我 红点，
+     * 更不会推进已读游标或影响离线消息的投递进度——为了渲染引用而调用是安全的。
+     *
+     * 超出服务端单批上限的 id 会自动分片串行请求。部分失败不影响已成功的部分：能取到的照常返回，
+     * 取不到的按「服务端确认没有」和「这次失败可重试」分开回报，调用方只需要对后者重试。
+     * 已撤回的原消息会照常取回并带撤回终态，不会被当成不存在。
+     *
+     * `supergroup` 未实现，调用即抛错，不会退化成其它会话类型的端点。
+     *
+     * @param messageIds 要取回的消息 id，通常是被引消息的 `refMessageId`；允许重复和空串，内部会清理。
+     * @returns 取回的消息、确认不存在的 id、以及本次没取到的 id 与失败原因。
+     * @example
+     * ```ts
+     * const missing: string[] = []
+     * for (const refId of referencedIds) {
+     *   if (await handle.resolveMessage(refId) === null) missing.push(refId)
+     * }
+     * const result = await handle.messages.fetchByIds(missing)
+     * result.messages.forEach(renderQuote)
+     * result.missingMessageIds.forEach(markQuoteGone)
+     * if (result.failure?.retryable === true) scheduleRetry(result.unresolvedMessageIds)
+     * ```
+     */
+    fetchByIds: (messageIds: readonly string[]) => Promise<ImMessagesByIdResult<ImMessageView>>;
 }
 /**
  * 产品层显式 Reaction 动作；协议数值枚举不会暴露给宿主。
@@ -7688,6 +7768,106 @@ type ImProfileDirectoryStore = ReturnType<ReturnType<typeof defineImProfileDirec
 /** 取得当前 Vue setup 或显式 Pinia 的资料与目录 Store；不同宿主实例的状态彼此隔离。 */
 declare function useImProfileDirectoryStore(pinia?: Pinia): ImProfileDirectoryStore;
 
+/**
+ * 为 PC 与 H5 提供同一套「引用回复原文」解析入口。
+ *
+ * 要解决的问题：一条回复消息在协议上只带被引原消息的 id，没有原文快照。原消息可能就在当前窗口里，
+ * 也可能只在本机历史深处，甚至根本没到过这台设备（没翻到那一页、清过缓存、换了浏览器）。
+ *
+ * 解析顺序固定三步，前两步不发请求：
+ *   1. 当前窗口里有就直接用，这也是唯一能拿到最新撤回/编辑状态的来源；
+ *   2. 调 SDK `resolveMessage` 查本机历史；
+ *   3. 本机确实没有，才把这一屏缺失的 id 攒成批交给 SDK 回源（`messages.fetchByIds`）。
+ *
+ * 第三步是批量的：一屏引用可能几十条，逐条打接口会给服务端制造无谓压力。回源不会改会话摘要、
+ * 不产生未读、不推进已读游标，所以为了渲染而调用是安全的。
+ *
+ * 本 Store 只保存解析状态缓存，不保存消息领域真相——消息本身由 SDK 唯一 DomainState 持有，回源
+ * 取回的消息也已经回填进本机历史。切会话、切账号或原消息发生变化时缓存会失效重读。
+ */
+
+/**
+ * 单条引用原文的解析状态。
+ *
+ * - `loading`：还在查，宿主应显示加载中占位，不要当成找不到。
+ * - `ready`：拿到原文，可以渲染摘要。
+ * - `missing`：服务端确认没有这条消息（已删除、超出保留期、对当前用户不可见）。终态，别再重试。
+ * - `failed`：这次没取到，但不代表不存在。`retryable` 为 true 时值得再试（网络或服务端错误）；
+ *   为 false 时再试结果也一样（例如已经退出这个群，服务端不再让你看它的消息）。
+ */
+type ImQuotedMessageState = Readonly<{
+    status: 'loading';
+    message: null;
+} | {
+    status: 'ready';
+    message: ImMessageView;
+} | {
+    status: 'missing';
+    message: null;
+} | {
+    status: 'failed';
+    message: null;
+    retryable: boolean;
+}>;
+/**
+ * 引用原文 Store 没有对外暴露的响应式字段。
+ *
+ * 解析状态通过 `lookup` 读取：它内部读的是 Store 的响应式缓存，所以在模板或 computed 里调用会
+ * 正常追踪依赖，解析完成后使用它的地方会自动重新渲染。
+ */
+type ImQuotedMessageStoreState = Record<string, never>;
+/** 引用原文 Store 的公共动作。 */
+interface ImQuotedMessageStoreActions {
+    /**
+     * 同步读取一条被引原消息的解析状态。
+     *
+     * 只读缓存和当前窗口，不发起任何请求，可以在渲染期放心调用。首次读到的是 `loading`，
+     * 真正的解析由 `prefetch` 触发。在模板或 computed 里调用会正常追踪依赖，解析完成后自动重新求值。
+     *
+     * 每次调用都会返回一个新的状态对象，所以不要对返回值本身做引用比较或直接 `watch`；要监听变化
+     * 请读里面的 `status` 或 `message`（同一条消息的 `message` 引用是稳定的）。
+     */
+    lookup: (messageId: string) => ImQuotedMessageState;
+    /**
+     * 声明当前这一屏需要哪些被引原消息，并按需解析尚未解析的部分。
+     *
+     * 幂等且可以高频调用：已有结论的（解析成功、确认缺失、解析失败）都不会重复查询，窗口内已有的
+     * 消息也不占用回源额度。同一时刻只允许一批解析在跑，连续翻页产生的多次调用会自动合并，
+     * 所以在消息列表变化时无脑调一次就行，不需要宿主自己做防抖。
+     *
+     * 传入顺序就是解析顺序。默认按窗口顺序传即可；如果宿主能判断用户正在看哪一段，把那段的 id 放
+     * 前面能让它们先显示出来。只想解析视口附近的引用时，直接少传一些 id 即可，本 Store 不读 DOM。
+     */
+    prefetch: (messageIds: readonly string[]) => void;
+    /**
+     * 重试指定的引用；不传则重试当前所有可重试的失败项。
+     *
+     * 只会重试 `failed` 且 `retryable` 为 true 的条目，已确认缺失的不会被重新查询。
+     *
+     * 解析失败后不会跟着翻页自己重试——否则断网期间用户每次滑动都会再打一轮接口。两种情况会重试：
+     * 连接恢复时 Store 自动调一次（覆盖最常见的断网失败），以及宿主主动调用这个动作（例如引用块上的
+     * 重试按钮）。所以宿主不接重试按钮也不会让断网后的引用永久卡住。
+     */
+    retry: (messageIds?: readonly string[]) => void;
+    /**
+     * 丢掉指定消息的解析结果，让下一次 `prefetch` 重新解析。
+     *
+     * 窗口外的原消息被编辑、撤回或管理员删除时，SDK 只把新状态写进本机历史，不会回头修改这份缓存，
+     * 需要宿主在收到消息变更事件时调用一次，否则引用块会一直显示旧正文。
+     */
+    invalidate: (messageIds: readonly string[]) => void;
+    /** 清空缓存与在途解析；切账号时使用。 */
+    reset: () => void;
+}
+/** 宿主从 `useImQuotedMessageStore` 获得的完整 Pinia Store 公共类型。 */
+type ImQuotedMessageStore = Store<'k2-im-quoted-message', ImQuotedMessageStoreState, Record<string, never>, ImQuotedMessageStoreActions>;
+/**
+ * 取得当前 Vue setup 或显式 Pinia 的引用原文 Store。
+ *
+ * 只解析被引原消息并缓存解析状态；引用块的样式、文案、点击定位和重试交互仍由宿主负责。
+ */
+declare function useImQuotedMessageStore(pinia?: Pinia): ImQuotedMessageStore;
+
 /**
  * 为 PC 与 H5 提供同一套消息 Reaction 操作入口。
  *
@@ -7966,5 +8146,5 @@ 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, useImReactionStore, useImSearchStore, 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, ImReactionOperationResult, ImReactionStore, ImReactionStoreActions, ImReactionStoreError, ImReactionStoreState, ImSearchOperationResult, ImSessionPhase, ImSessionStore, ImThreadPagingActions, ImThreadPagingState, ImThreadPagingStore, ImThreadReturnToLatestCoordinator, ImThreadStore, ImThreadStoreActions, ImThreadStoreState };
+export { applicationKey, createAndInstallImChatKit, createImChatKitContext, disposeImChatKit, ensureImChatKitSelfProfile, getImChatKitContext, installImChatKit, useImApplicationsStore, useImCapabilitiesStore, useImComposerStore, useImConversationActivationCoordinator, useImConversationDeletionCoordinator, useImConversationListStore, useImExpressionStore, useImHistoryReturnAfterSendCoordinator, useImMediaStore, useImMessageOperationsStore, useImProfileDirectoryStore, useImQuotedMessageStore, useImReactionStore, useImSearchStore, 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, ImSessionPhase, ImSessionStore, ImThreadPagingActions, ImThreadPagingState, ImThreadPagingStore, ImThreadReturnToLatestCoordinator, ImThreadStore, ImThreadStoreActions, ImThreadStoreState };