k2-im 0.1.0 → 0.1.2

package/dist/browser.d.ts

@@ -0,0 +1,365 @@
+/**
+ * 后端协议的目标服务命名。
+ *
+ * `core`、`wallet`、`bi` 沿用当前 H5/BFF 已接入的服务分组；`im` 用于后续 IM
+ * HTTP 业务接口直连。调用方应优先通过 `target` 切换服务，而不是在业务代码里手动拼接
+ * baseURL 或 prefix，这样未来从 BFF 迁移到客户端直连时可以只调整运行时配置。
+ */
+type ApiProtocolTarget = 'core' | 'wallet' | 'bi' | 'im';
+/**
+ * 单个目标服务的直连地址配置。
+ *
+ * `baseUrl` 通常来自 Nuxt public runtime config 或客户端构建配置；`prefix` 是该服务在后端
+ * 网关下的默认业务前缀，例如核心业务的 `/api/h5`。单次请求可以通过 request options 覆盖它们。
+ */
+interface ApiProtocolTargetConfig {
+    baseUrl: string;
+    prefix?: string;
+}
+/**
+ * 客户端直连协议所需的公开运行时配置。
+ *
+ * 这份配置只包含允许公开给浏览器的协议字段。签名和 AES 规则由 `@k2/crypto` wasm 提供，
+ * 不要求调用方传入额外密钥。
+ */
+interface ApiProtocolRuntimeConfig {
+    /** 应用版本，同时写入 `app_version` 和加密版本请求头。 */
+    appVersion: string;
+    /** 品牌 ID，对应现有 H5/BFF 协议里的 `brand-id`。 */
+    brandId: string;
+    /** 商户 ID，对应协议请求头 `mch-id`。 */
+    merchantId: string;
+    /** 默认渠道 ID；单次请求可通过 `channelId` 覆盖。 */
+    channelId: string;
+    /** 签名算法需要的环境标识，例如 `prod`、`dev` 等。 */
+    envType: string;
+    /** 所有可请求目标的 baseURL/prefix 映射。 */
+    targets: Record<ApiProtocolTarget, ApiProtocolTargetConfig>;
+}
+/**
+ * 与 `@k2/crypto` wasm 实现对齐的协议加解密能力。
+ *
+ * 通过依赖注入而不是在核心 request 中直接加载 wasm，可以让 Node 测试、浏览器插件、
+ * Nuxt client plugin 或未来客户端容器按自己的生命周期加载 crypto。
+ */
+interface ApiProtocolCryptoDriver {
+    /** 计算普通 MD5，主要用于兼容 BI feedback 签名。 */
+    cryptMd5: (input: string) => string;
+    /**
+     * 生成后端协议签名。
+     *
+     * @param signType 当前业务请求固定为 `api`。
+     * @param envType 运行环境标识，来自 `ApiProtocolRuntimeConfig.envType`。
+     * @param businessParams 已合并公共参数且完成字符串化的业务请求参数。
+     * @param eTag 本次请求头中的 `Content-ETag`，缺省时按 crypto 实现约定处理。
+     */
+    generateSign: (signType: string, envType: string, businessParams: Record<string, string>, eTag?: string | null) => string;
+    /** 将 UTF-8 JSON bytes 加密为后端要求的二进制请求体。 */
+    encryptAes: (payload: Uint8Array) => Uint8Array;
+    /** 将后端返回的二进制响应体解密为 UTF-8 JSON bytes。 */
+    decryptAes: (payload: Uint8Array) => Uint8Array;
+}
+/**
+ * 协议请求头需要的浏览器/设备信息。
+ *
+ * Web 端默认从 userAgent 和本地随机设备号派生；原生客户端或桌面容器可以注入更稳定的设备信息。
+ */
+interface ApiProtocolBrowserInfo {
+    deviceBrand: string;
+    deviceInfo: string;
+    deviceNumber: string;
+    deviceToken: string;
+}
+/**
+ * 上传进度事件的协议层抽象。
+ *
+ * 默认 axios transport 会从 AxiosProgressEvent 映射到该结构；如果未来接入原生容器网络层，
+ * 也只需要按相同字段回调业务层即可。
+ */
+interface ApiProtocolUploadProgress {
+    /** 已上传字节数。 */
+    loaded: number;
+    /** 总字节数；部分运行时无法拿到时为空。 */
+    total?: number;
+    /** 0 到 1 之间的上传比例；无法计算时为空。 */
+    progress?: number;
+    /** 底层 transport 的原始进度事件，供调试或特殊场景读取。 */
+    event?: unknown;
+}
+/**
+ * 单次协议请求的可覆盖项。
+ *
+ * 默认请求会按当前 H5/BFF 协议自动补公共参数、签名、AES 加密、token、语言和设备头。
+ * 只有上传、特殊回调或兼容接口这类非标准请求，才需要显式传 `body`、关闭 `encrypt/sign`
+ * 或使用 `customUrl`。
+ */
+interface ApiProtocolRequestOptions {
+    /** HTTP method，默认 `POST`；`GET` 请求会把协议参数拼到 query。 */
+    method?: string;
+    /** 目标后端服务，默认 `core`。IM 业务请求应传 `im`。 */
+    target?: ApiProtocolTarget;
+    /** 业务参数。数字会按现有协议转换为字符串，避免大整数在 JSON 中丢精度。 */
+    data?: Record<string, unknown>;
+    /** 自定义请求体。传入后默认不做协议加密/签名，适合 FormData 或已编码内容。 */
+    body?: BodyInit | null;
+    /** 追加或覆盖请求头；需要特殊端类型等场景可覆盖公共协议头。 */
+    headers?: HeadersInit;
+    /** 覆盖目标服务默认 prefix。 */
+    prefix?: string;
+    /** 覆盖目标服务默认 baseURL，常用于灰度环境或临时调试。 */
+    baseUrl?: string;
+    /** 覆盖默认渠道 ID。 */
+    channelId?: string;
+    /** 是否对普通请求体执行 AES 加密；默认在无自定义 body 时开启。 */
+    encrypt?: boolean;
+    /** 是否生成协议签名；默认在无自定义 body 时开启。 */
+    sign?: boolean;
+    /** 客户端超时时间，默认 60 秒。 */
+    timeoutMs?: number;
+    /** 覆盖依赖注入中的 token 读取结果；传空字符串可主动发起未登录请求。 */
+    token?: string | null;
+    /** 覆盖依赖注入中的 locale 读取结果。 */
+    locale?: string | null;
+    /** 覆盖浏览器 userAgent 派生逻辑，主要用于测试或容器环境。 */
+    userAgent?: string | null;
+    /** `true` 时 `path` 被视为完整 URL，不再拼接 target baseURL/prefix。 */
+    customUrl?: boolean;
+    /** 外部取消信号，会和内部 timeout 信号合并。 */
+    signal?: AbortSignal;
+    /** 上传进度回调；默认浏览器客户端的 axios transport 支持该能力。 */
+    onUploadProgress?: (progress: ApiProtocolUploadProgress) => void;
+    /**
+     * 响应解析模式。
+     * - `'json'`（默认）：按 content-type 走 JSON / 文本 / AES-JSON 解析，返回业务响应对象。
+     * - `'raw'`：原样返回响应字节（`data` 为 `Uint8Array`），不做 JSON / 文本解析；用于
+     *   protobuf 等二进制接口（如 IM CM 离线消息）。通常与二进制 `body` 搭配使用。
+     */
+    responseMode?: 'json' | 'raw';
+}
+/**
+ * 后端业务响应体。
+ *
+ * @template T 业务数据 `data` 的类型；当接口无数据或失败时，`data` 可能为空。
+ */
+interface ApiProtocolResponse<T = unknown> {
+    code: number;
+    data?: T | null;
+    msg?: string;
+    time?: number;
+    [key: string]: unknown;
+}
+/**
+ * transport 层收到的标准化请求。
+ *
+ * 核心协议只关心“发送一个 HTTP 请求并返回原始响应”，axios、fetch 或原生容器网络栈都可以适配成
+ * 这个形状，从而避免业务协议绑定具体 HTTP 库。
+ */
+interface ApiProtocolTransportRequest {
+    url: string;
+    method: string;
+    headers: Record<string, string>;
+    body?: BodyInit;
+    signal?: AbortSignal;
+    timeoutMs?: number;
+    onUploadProgress?: (progress: ApiProtocolUploadProgress) => void;
+}
+/**
+ * transport 层返回的原始 HTTP 响应。
+ *
+ * `data` 应尽量保持未解析形态，例如 ArrayBuffer 或二进制 bytes；协议层会根据 content-type
+ * 决定是否 JSON 解析、文本解析或 AES 解密。
+ */
+interface ApiProtocolTransportResponse {
+    status: number;
+    statusText: string;
+    headers?: Headers | Record<string, unknown>;
+    data?: unknown;
+}
+/**
+ * HTTP 发送适配器。
+ *
+ * @example
+ * ```ts
+ * const transport: ApiProtocolTransport = async request => ({
+ *   status: 200,
+ *   statusText: 'OK',
+ *   headers: { 'content-type': 'application/json' },
+ *   data: '{"code":0,"data":null}',
+ * });
+ * ```
+ */
+type ApiProtocolTransport = (request: ApiProtocolTransportRequest) => Promise<ApiProtocolTransportResponse>;
+/**
+ * 业务响应副作用回调的上下文。
+ *
+ * 这里故意不暴露 BFF 层曾经用于调试的 `meta`，因为客户端调用方只应关心业务响应和本次请求的
+ * 基础定位信息。登录态失效、全局 toast、埋点等副作用可以通过该上下文判断来源。
+ */
+interface ApiProtocolBusinessResponseContext {
+    request: {
+        path: string;
+        method: string;
+        target: ApiProtocolTarget;
+        url: string;
+    };
+    options: ApiProtocolRequestOptions;
+}
+/**
+ * 业务响应统一处理器。
+ *
+ * 典型用途是沿用当前全局登录态处理：例如 `401`、`501` 时清理 token 并跳转登录。
+ */
+type ApiProtocolBusinessResponseHandler = (response: ApiProtocolResponse<unknown>, context: ApiProtocolBusinessResponseContext) => void | Promise<void>;
+/**
+ * 协议客户端内部调试事件。
+ *
+ * 事件只通过可选 debug hook 暴露给开发工具，不会混入公开业务响应。它刻意包含加密前请求参数、
+ * 解密后的响应体和真实请求/响应头，方便类似 Network 面板的插件还原协议请求。
+ *
+ * @template T 当前请求业务响应 `data` 的类型。
+ */
+interface ApiProtocolDebugEvent<T = unknown> {
+    requestId: string;
+    eTag: string;
+    method: string;
+    upstreamUrl: string;
+    requestHeaders?: Record<string, string>;
+    /** 协议层自动补齐并参与签名/发送的公共参数，例如 app_id、timestamp、nonce、sign。 */
+    requestCommonParams?: unknown;
+    /** 调用方通过 `options.data` 显式传入并归一化后的业务参数。 */
+    requestBusinessParams?: unknown;
+    /** 加密、签名或拼 query 前的最终请求参数；通常等于公共参数与业务参数的合并结果。 */
+    requestParams?: unknown;
+    transportStatus: 'success' | 'http_error' | 'network_error' | 'invalid_response';
+    httpStatus?: number;
+    contentType?: string | null;
+    responseHeaders?: Record<string, string>;
+    rawBody?: unknown;
+    timings: {
+        totalMs: number;
+        upstreamMs: number;
+        parseMs?: number;
+        decryptMs?: number;
+    };
+    response: ApiProtocolResponse<T>;
+    error?: {
+        name?: string;
+        message: string;
+    };
+}
+/** 接收协议调试事件的可选回调，用于应用内调试面板或测试环境观测。 */
+type ApiProtocolDebugHandler = (event: ApiProtocolDebugEvent) => void | Promise<void>;
+/**
+ * 创建协议客户端所需的依赖集合。
+ *
+ * 所有与具体运行时相关的读取行为都放在这里：token/locale/设备信息/随机数/时间/transport。
+ * 这样核心 request 可以在浏览器、H5、PC、单元测试或未来原生客户端中复用。
+ */
+interface ApiProtocolClientDependencies {
+    /** 公开协议配置。 */
+    config: ApiProtocolRuntimeConfig;
+    /** 协议签名和 AES 加解密能力。 */
+    crypto: ApiProtocolCryptoDriver;
+    /** HTTP 发送适配器。 */
+    transport: ApiProtocolTransport;
+    /** 每次请求前读取最新 token，避免客户端登录态刷新后 request 持有旧值。 */
+    getToken?: () => string | null | undefined | Promise<string | null | undefined>;
+    /** 每次请求前读取当前语言，并由协议层转换为后端短码。 */
+    getLocale?: () => string | null | undefined;
+    /** 覆盖默认浏览器设备信息推导。 */
+    getBrowserInfo?: () => ApiProtocolBrowserInfo;
+    /** 注入时间源，方便测试签名与时间戳。 */
+    now?: () => Date;
+    /** 注入 nonce，方便测试或兼容特定容器随机数实现。 */
+    randomNonce?: () => string;
+    /** 注入请求 ID 生成器。 */
+    randomRequestId?: () => string;
+    /** 注入 ETag 生成器，参与签名和请求头。 */
+    randomETag?: () => string;
+    /** 业务响应统一副作用处理器。 */
+    onBusinessResponse?: ApiProtocolBusinessResponseHandler;
+    /** 可选调试事件回调。只用于开发/测试面板，不改变公开 API 返回值。 */
+    onDebugRecord?: ApiProtocolDebugHandler;
+}
+/**
+ * 协议客户端函数。
+ *
+ * @template T 业务响应 `data` 类型。
+ * @example
+ * ```ts
+ * const response = await client<{ nickname: string }>('/v1/user/profile', {
+ *   target: 'im',
+ *   data: { userId: '10001' },
+ * });
+ * ```
+ */
+type ApiProtocolClient = <T = unknown>(path: string, options?: ApiProtocolRequestOptions) => Promise<ApiProtocolResponse<T>>;
+
+/**
+ * 创建运行时协议配置的输入。
+ *
+ * 这里同时支持扁平的 `coreBaseUrl/imBaseUrl` 和完整的 `targets` 覆盖，方便 Nuxt public runtime
+ * config 使用简单字段，也方便未来客户端容器一次性传入完整服务映射。
+ */
+interface CreateApiProtocolRuntimeConfigInput {
+    /** 应用版本，会进入公共参数和加密版本请求头。 */
+    appVersion?: string;
+    /** 品牌 ID。 */
+    brandId?: string;
+    /** 商户 ID。 */
+    merchantId?: string;
+    /** 默认渠道 ID。 */
+    channelId?: string;
+    /** 签名环境标识。 */
+    envType?: string;
+    /** core 服务 baseURL。 */
+    coreBaseUrl?: string;
+    /** wallet 服务 baseURL。 */
+    walletBaseUrl?: string;
+    /** BI 服务 baseURL。 */
+    biBaseUrl?: string;
+    /** IM 服务 baseURL。 */
+    imBaseUrl?: string;
+    /** 更细粒度的 target 覆盖，优先级高于上面的扁平 baseURL 字段。 */
+    targets?: Partial<Record<ApiProtocolTarget, Partial<ApiProtocolTargetConfig>>>;
+}
+
+/**
+ * 浏览器便捷客户端的创建参数。
+ *
+ * 与底层 `createApiProtocolClient` 相比，这里默认补齐 wasm crypto 和 axios transport。
+ * Nuxt/React/Vue 等应用只需要注入运行时配置、token/locale 读取器和业务响应处理器。
+ */
+interface CreateBrowserApiProtocolClientInput extends Omit<ApiProtocolClientDependencies, 'config' | 'crypto' | 'transport'> {
+    /** 允许传入不完整配置，内部会通过 `createApiProtocolRuntimeConfig` 补齐默认 prefix。 */
+    config?: CreateApiProtocolRuntimeConfigInput;
+    /** 覆盖默认 axios transport，例如测试、埋点代理或客户端容器网络层。 */
+    transport?: ApiProtocolTransport;
+}
+
+/**
+ * 延迟创建并复用浏览器 API 协议客户端的账号运行时 helper。
+ * 初始化失败会清除 rejected 缓存允许重试；凭据始终从当前调用方读取，不固化旧账号闭包。
+ */
+
+/**
+ * 创建按首次请求初始化的浏览器协议客户端。
+ *
+ * @remarks
+ * SDK client 的构造必须保持同步，wasm crypto 与 axios transport 则只能异步初始化。本代理把初始化推迟到
+ * 第一次 core JSON 请求，并复用同一个 client；每次业务请求仍由底层 client 调用动态 `getToken`，不会捕获
+ * 创建时的账号凭据。初始化失败会清除缓存，允许宿主修复运行环境后重试。
+ *
+ * @example
+ * ```ts
+ * const client = createLazyBrowserApiProtocolClient({
+ *   config: { coreBaseUrl: 'https://core.example.com' },
+ *   getToken: async () => auth.getToken(),
+ * })
+ * await client('/user/info/other', { target: 'core', data: { user_id: '42' } })
+ * ```
+ */
+declare function createLazyBrowserApiProtocolClient(input: CreateBrowserApiProtocolClientInput, createClient?: (input: CreateBrowserApiProtocolClientInput) => Promise<ApiProtocolClient>): ApiProtocolClient;
+
+export { createLazyBrowserApiProtocolClient };
+export type { ApiProtocolClient };

package/dist/browser.js

@@ -0,0 +1 @@
+export{A as createLazyBrowserApiProtocolClient}from'./chunk-FO2MMPPT.js';import'./chunk-VSMNRAAM.js';import'./chunk-WOT6VMZA.js';

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

@@ -2083,7 +2083,7 @@ type ImEvent = {
     createdAt: number;
     expired: boolean;
 }
-/** 对端应答 0x4008；accept 后仍须等 `call:peer-audio-begin` 才算接通。 */
+/** 对端应答 0x4008；accept 后仍须等匹配的首帧事件才算接通。 */
  | {
     type: 'call:answered';
     conversation: ConversationRef<'direct'>;
@@ -2099,13 +2099,20 @@ type ImEvent = {
     peerId: string;
     outcome: ImCallOutcome;
 }
-/** 对端 PEER_AUDIO_BEGIN(5)；对齐 Android TrackSubscribed 后的接通点。 */
+/** 对端 PEER_AUDIO_BEGIN(5)。Android TrackSubscribed 后发送；iOS LiveKit 不发此包。收到才算语音接通，不把 accept 当成接通。 */
  | {
     type: 'call:peer-audio-begin';
     conversation: ConversationRef<'direct'>;
     callId: string;
     peerId: string;
 }
+/** 对端 PEER_VIDEO_BEGIN(6)。Android TrackSubscribed 后发送；iOS LiveKit 不发此包。收到才算视频接通，不把 accept 当成接通。 */
+ | {
+    type: 'call:peer-video-begin';
+    conversation: ConversationRef<'direct'>;
+    callId: string;
+    peerId: string;
+}
 /** 主叫 invite ACK 失败（对端离线等）；本机已写入 cancelled 记录。 */
  | {
     type: 'call:failed';
@@ -3379,7 +3386,7 @@ interface ImApplicationsApi {
 }
 
 /**
- * 单聊 1v1 语音信令产品门面。
+ * 单聊 1v1 音视频信令产品门面。
  *
  * 宿主先完成 LiveKit Connected，再 `invite`；来电订阅 `call:incoming`。
  * SDK 不持有 getUserMedia / LiveKit；token 与进房留在宿主。
@@ -3388,6 +3395,8 @@ interface ImApplicationsApi {
 interface ImDirectCallInviteInput {
     peerId: string;
     callId: string;
+    /** 默认 audio。视频发信令 callType=0。接通仍等对端首帧事件，不把 accept 当成接通。 */
+    callKind?: ImCallKind;
 }
 interface ImDirectCallTargetInput {
     peerId: string;
@@ -3402,13 +3411,13 @@ interface ImDirectCallNotifyAudioInput extends ImDirectCallTargetInput {
 interface ImDirectCallsApi {
     /**
      * 主叫在 LiveKit Connected 之后发送 0x4001。
-     * 当前只接受语音；视频 fail-fast。
+     * `callKind` 默认 audio；video 发 callType=0。
      */
     invite: (input: ImDirectCallInviteInput) => {
         callId: string;
         conversation: ConversationRef<'direct'>;
     };
-    /** 被叫同意：发 0x4005 NON_ERR。接通仍等 `call:peer-audio-begin`。 */
+    /** 被叫同意：发 0x4005 NON_ERR。接通仍等匹配的首帧事件。 */
     accept: (input: ImDirectCallTargetInput) => void;
     /** 被叫拒绝：发 0x4005 0x8400，并插入 rejected 记录。 */
     reject: (input: ImDirectCallTargetInput) => void;
@@ -3417,10 +3426,17 @@ interface ImDirectCallsApi {
     /** 挂断：发 0x400d，并插入通话记录（msgId=callId）。 */
     hangup: (input: ImDirectCallHangupInput) => void;
     /**
-     * 本地 TrackSubscribed 后通知对端 PEER_AUDIO_BEGIN(5)。
+     * 语音 TrackSubscribed 后通知对端 PEER_AUDIO_BEGIN(5)。
      * `role` 映射 Android notifyValue：caller=1 / callee=2。
+     * iOS LiveKit 现行不发此包；宿主不得因对端是 iOS 而改发或不发。
      */
     notifyPeerAudioBegin: (input: ImDirectCallNotifyAudioInput) => void;
+    /**
+     * 视频 TrackSubscribed 后通知对端 PEER_VIDEO_BEGIN(6)。
+     * `role` 映射与语音相同。当前通话不是视频时 fail-fast。
+     * iOS LiveKit 现行不发此包。
+     */
+    notifyPeerVideoBegin: (input: ImDirectCallNotifyAudioInput) => void;
 }
 
 /**
@@ -4579,6 +4595,11 @@ interface ImProductEventMap {
         callId: string;
         peerId: string;
     }>;
+    'call:peer-video-begin': Readonly<{
+        ref: ConversationRef<'direct'>;
+        callId: string;
+        peerId: string;
+    }>;
     'call:failed': Readonly<{
         ref: ConversationRef<'direct'>;
         callId: string;
@@ -5259,7 +5280,7 @@ interface ImProductClient {
  * 普通宿主只使用 `ImProductClient`；官方 Chat Kit 和受控诊断从 internal 子入口取得 `ImAdvancedClient`。
  */
 interface ImClient extends Omit<ImProductClient, 'capabilities' | 'channels' | 'contacts' | 'conversations' | 'groups'> {
-    /** internal/testing 与高级宿主使用的单聊语音信令；稳定 default 产品门面不暴露此能力。 */
+    /** internal/testing 与高级宿主使用的单聊音视频信令；稳定 default 产品门面不暴露此能力。 */
     readonly calls: ImDirectCallsApi;
     /**
      * 打开一个拥有独立连续窗口与生命周期的 direct、GROUP 或 CHANNEL 会话句柄。