@h-ai/api-client 0.1.0-alpha.66 → 0.1.0-alpha.68

package/dist/index.d.ts

@@ -11,13 +11,22 @@ import * as zod_v4_core from 'zod/v4/core';
 import * as zod from 'zod';
 
 /**
- * API client 标准错误集合（遵循 `@h-ai/core` 错误码规范）。
+ * 客户端标准错误集合；包含稳定 code/httpStatus 与构造错误的方法，业务调用先检查 success。
+ * 传输失败在 procedure 代理中映射；服务端 HaiResult 的业务错误保持原契约。
  *
  * @example
  * ```ts
- * if (!result.success && result.error.code === HaiApiClientError.UNAUTHORIZED.code) {
- *   redirectToLogin()
+ * import { apiClient, HaiApiClientError } from '@h-ai/api-client'
+ * const initialized = await apiClient.init({ baseUrl: 'https://api.example.com/api/v1' })
+ * if (!initialized.success) throw new Error(initialized.error.message)
+ * try {
+ *   const result = await apiClient.iam.auth.currentUser()
+ *   if (!result.success && result.error.code === HaiApiClientError.UNAUTHORIZED.code) {
+ *     // 由应用切换到登录页面；不输出 Token。
+ *     const message = result.error.message
+ *   }
  * }
+ * finally { await apiClient.close() }
  * ```
  */
 declare const HaiApiClientError: {
@@ -33,7 +42,17 @@ declare const HaiApiClientError: {
     readonly CONFIG_ERROR: _h_ai_core.HaiErrorDef;
     readonly UNKNOWN: _h_ai_core.HaiErrorDef;
 };
-/** Token 对（与 `@h-ai/iam` 的 TokenPair 对齐）。 */
+/**
+ * 短期 access token、可选 refresh token 与有效期；HTTP 头使用 Bearer。
+ * Cookie 模式的 refresh token 由服务端管理，不能要求浏览器读取或持久化它。
+ *
+ * @example
+ * ```ts
+ * import type { TokenPair } from '@h-ai/api-client'
+ * const tokens: TokenPair = { accessToken: 'test-access', expiresIn: 3600, tokenType: 'Bearer' }
+ * // 示例为测试凭据；生产 Token 只能来自可信服务端认证响应。
+ * ```
+ */
 interface TokenPair {
     /** 短期访问凭证，请求时作为 `Authorization: Bearer ...`。 */
     readonly accessToken: string;
@@ -45,30 +64,110 @@ interface TokenPair {
     readonly tokenType: 'Bearer';
 }
 /**
- * Token 存储适配器。
+ * 异步安全凭据存储契约；null 仅表示无可用凭据，读写故障须拒绝 Promise。
+ * 浏览器使用内存 access token/httpOnly refresh Cookie，原生端注入平台安全存储，禁止敏感 Token 放入 localStorage。
+ * 已绑定客户端的身份切换通过 client.auth，避免绕过刷新代际与串行写入；部分写入失败须执行清理并报告清理失败。
  *
  * 内置实现：
  * - `apiClient.tokenStorage.httpOnlyCookie()` — **默认**；浏览器端推荐，refresh token 由服务端管理，防 XSS。
  * - `apiClient.tokenStorage.memory()` — Node.js 测试 / SSR（需显式传入）。
- * - `apiClient.tokenStorage.localStorage()` — 浏览器 SPA / PWA（有 XSS 风险，生产不推荐）。
  *
  * Capacitor / 小程序场景请由对应模块提供（例如 `@h-ai/capacitor`）。
+ *
+ * @example
+ * ```ts
+ * import { apiClient, type TokenStorage } from '@h-ai/api-client'
+ * const storage: TokenStorage = apiClient.tokenStorage.memory()
+ * await storage.setAccessToken('test-access')
+ * const accessToken = await storage.getAccessToken()
+ * await storage.clear()
+ * ```
  */
 interface TokenStorage {
+    /**
+     * 读取本适配器可用 access token；无凭据返回 null，存储故障拒绝。
+     * @returns Token 或 null；不能把读取失败当成不存在。
+     *
+     * @example
+     * ```ts
+     * import { apiClient } from '@h-ai/api-client'
+     * const storage = apiClient.tokenStorage.memory()
+     * const accessToken = await storage.getAccessToken()
+     * ```
+     */
     readonly getAccessToken: () => Promise<string | null>;
+    /**
+     * 保存 access token；已绑定客户端应通过 auth.setTokens 维护代际。
+     * @param token - 可信服务端认证返回的 access token。
+     * @returns 写入完成；底层故障须拒绝。
+     *
+     * @example
+     * ```ts
+     * import { apiClient } from '@h-ai/api-client'
+     * const storage = apiClient.tokenStorage.memory()
+     * await storage.setAccessToken('test-access')
+     * await storage.clear()
+     * ```
+     */
     readonly setAccessToken: (token: string) => Promise<void>;
+    /**
+     * 读取 refresh token 或 Cookie 模式内部哨兵；null 仅表示没有凭据。
+     * @returns Token、模式哨兵或 null，不是对 httpOnly Cookie 内容的脚本读取。
+     *
+     * @example
+     * ```ts
+     * import { apiClient } from '@h-ai/api-client'
+     * const storage = apiClient.tokenStorage.memory()
+     * const refreshToken = await storage.getRefreshToken()
+     * // 内存适配器初始为空；Cookie 适配器由管理器识别模式哨兵。
+     * ```
+     */
     readonly getRefreshToken: () => Promise<string | null>;
+    /**
+     * 保存 refresh token；Cookie 实现不通过脚本修改服务端 Cookie。
+     * @param token - 服务端返回的刷新凭据；禁止写入 Web Storage。
+     * @returns 写入完成；原生安全存储故障须拒绝。
+     *
+     * @example
+     * ```ts
+     * import { apiClient } from '@h-ai/api-client'
+     * const storage = apiClient.tokenStorage.memory()
+     * await storage.setRefreshToken('test-refresh')
+     * await storage.clear()
+     * ```
+     */
     readonly setRefreshToken: (token: string) => Promise<void>;
+    /**
+     * 清空适配器可管理的凭据；Cookie 实现只能清内存 access token。
+     * @returns 清理完成；失败须拒绝，服务端 Cookie/会话另由退出接口撤销。
+     *
+     * @example
+     * ```ts
+     * import { apiClient } from '@h-ai/api-client'
+     * const storage = apiClient.tokenStorage.memory()
+     * await storage.clear()
+     * const remaining = await storage.getAccessToken()
+     * ```
+     */
     readonly clear: () => Promise<void>;
 }
-/** Token 自动刷新配置。 */
+/**
+ * 启用 Token 注入与自动刷新；默认 Cookie 适配器，refreshPath 相对 baseUrl。
+ * 网络/超时/5xx 为暂时失败，保留凭据；明确失效才清理并通知。回调不应抛出或记录 Token。
+ *
+ * @example
+ * ```ts
+ * import { apiClient, type AuthConfig } from '@h-ai/api-client'
+ * const auth: AuthConfig = { storage: apiClient.tokenStorage.memory(), refreshPath: '/auth/refresh', refreshTimeoutMs: 5000, onTokenRefreshed: tokens => { const lifetime = tokens.expiresIn } }
+ * // Node/SSR 选择独立内存存储；浏览器通常直接配置 auth: {}。
+ * ```
+ */
 interface AuthConfig {
     /**
      * Token 存储适配器；默认 `apiClient.tokenStorage.httpOnlyCookie()`（refresh token 由服务端管理，防 XSS）。
      *
      * - SSR / Node.js 测试场景请显式传入 `apiClient.tokenStorage.memory()`。
-     * - 浏览器 SPA 如确需持久化，可显式传 `apiClient.tokenStorage.localStorage()`，
-     *   但请先评估 XSS 风险。
+     * - 浏览器刷新后通过 httpOnly Cookie 恢复会话，不将 Token 持久化到 Web Storage。
      * - Capacitor / 小程序请使用对应平台的安全存储适配器（如 `@h-ai/capacitor`）。
      */
     readonly storage?: TokenStorage;
@@ -85,7 +184,20 @@ interface AuthConfig {
     /** 刷新失败回调（如 refresh token 已失效），通常用于跳转登录页。 */
     readonly onRefreshFailed?: () => void;
 }
-/** API client 初始化配置。 */
+/**
+ * 客户端初始化配置；baseUrl 包含 API 前缀，headers/fetch 用于平台适配。
+ * auth 缺省时不创建 TokenManager；timeout 是底层请求中断期限，不代表服务端已取消副作用。
+ * transport 需要已初始化 crypto，首次业务请求前协商会话；客户端不接收服务端私钥。
+ *
+ * @example
+ * ```ts
+ * import { apiClient, type ApiClientConfig } from '@h-ai/api-client'
+ * const config: ApiClientConfig = { baseUrl: 'https://api.example.com/api/v1', auth: { storage: apiClient.tokenStorage.memory() }, timeout: 15000, clientName: 'orders-web', headers: () => ({ 'x-app-channel': 'web' }) }
+ * const initialized = await apiClient.init(config)
+ * if (!initialized.success) throw new Error(initialized.error.message)
+ * await apiClient.close()
+ * ```
+ */
 interface ApiClientConfig {
     /** API service 完整 baseUrl，通常含 `apiPrefix`，例如 `https://api.example.com/api/v1`。 */
     readonly baseUrl: string;
@@ -112,16 +224,38 @@ interface ApiClientConfig {
      * import { apiClient } from '@h-ai/api-client'
      * import { crypto } from '@h-ai/crypto'
      *
-     * await crypto.init()
-     * await apiClient.init({
-     *   baseUrl: 'https://api.example.com/api/v1',
-     *   transport: { crypto },
-     * })
+     * const cryptography = await crypto.init()
+     * if (!cryptography.success) throw new Error(cryptography.error.message)
+     * try {
+     *   const initialized = await apiClient.init({ baseUrl: 'https://api.example.com/api/v1', transport: { crypto } })
+     *   if (!initialized.success) throw new Error(initialized.error.message)
+     *   await apiClient.close()
+     * }
+     * finally { await crypto.close() }
      * ```
      */
     readonly transport?: ApiClientTransportConfig;
 }
-/** {@link ApiClientConfig.transport} 的配置项。 */
+/**
+ * 可选加密会话配置；密钥协商路径相对 baseUrl，并与服务端配置匹配。
+ * crypto 必须先初始化；服务器版本公钥通过受保护的 TLS 握手取得，不配置服务端私钥。
+ * 传输防重放不能代替业务幂等性，失败后不要自动重放非幂等操作。
+ *
+ * @example
+ * ```ts
+ * import { apiClient, type ApiClientTransportConfig } from '@h-ai/api-client'
+ * import { crypto } from '@h-ai/crypto'
+ * const cryptography = await crypto.init()
+ * if (!cryptography.success) throw new Error(cryptography.error.message)
+ * try {
+ *   const transport: ApiClientTransportConfig = { crypto, keyExchangePath: '/_hai/key-exchange' }
+ *   const initialized = await apiClient.init({ baseUrl: 'https://api.example.com/api/v1', transport })
+ *   if (!initialized.success) throw new Error(initialized.error.message)
+ *   await apiClient.close()
+ * }
+ * finally { await crypto.close() }
+ * ```
+ */
 interface ApiClientTransportConfig {
     /**
      * crypto 服务实例（通常直接传入 `@h-ai/crypto` 的 `crypto`）。
@@ -135,31 +269,141 @@ interface ApiClientTransportConfig {
      */
     readonly keyExchangePath?: string;
 }
-/** Token 辅助操作。 */
+/**
+ * 当前客户端的凭据辅助操作；仅 init 启用 auth 时建立实际管理器。
+ * setTokens/clear 撤销旧刷新代际并等待串行存储变更；故障拒绝 Promise，调用方处理失败。
+ * clear 不能撤销服务端会话或删除 httpOnly Cookie，退出仍需服务端接口成功。
+ *
+ * @example
+ * ```ts
+ * import { apiClient, type ApiClientAuth } from '@h-ai/api-client'
+ * const initialized = await apiClient.init({ baseUrl: 'https://api.example.com/api/v1', auth: {} })
+ * if (!initialized.success) throw new Error(initialized.error.message)
+ * try {
+ *   const auth: ApiClientAuth = apiClient.auth
+ *   const off = auth.onTokenRefreshed(tokens => { const lifetime = tokens.expiresIn })
+ *   off()
+ *   await auth.clear()
+ * }
+ * finally { await apiClient.close() }
+ * ```
+ */
 interface ApiClientAuth {
-    /** 手动写入 Token（例如登录成功后）。 */
+    /**
+     * 替换整对凭据并同步废弃旧刷新代际；缺省 refreshToken 时清除旧值。
+     * @param tokens - 服务端成功认证返回的真实 TokenPair。
+     * @returns 写入完成；安全存储失败拒绝 Promise，调用方应清理部分凭据并报告清理失败。
+     *
+     * @example
+     * ```ts
+     * import { apiClient } from '@h-ai/api-client'
+     * const initialized = await apiClient.init({ baseUrl: 'https://api.example.com/api/v1', auth: {} })
+     * if (!initialized.success) throw new Error(initialized.error.message)
+     * try {
+     *   const form = { identifier: 'alice', password: 'test-password' }
+     *   const login = await apiClient.iam.auth.login(form)
+     *   if (!login.success) throw new Error(login.error.message)
+     *   try { await apiClient.auth.setTokens(login.data.tokens) }
+     *   catch (writeError) {
+     *     try { await apiClient.auth.clear() }
+     *     catch (cleanupError) { throw new AggregateError([writeError, cleanupError], 'Credential persistence and cleanup failed') }
+     *     throw writeError
+     *   }
+     * }
+     * finally { await apiClient.close() }
+     * ```
+     */
     readonly setTokens: (tokens: TokenPair) => Promise<void>;
-    /** 清空存储的 Token（登出）。 */
+    /**
+     * 同步废弃旧刷新代际并等待存储清理；失败拒绝 Promise，不声称已持久删除。
+     * 服务端会话与 httpOnly Cookie 仍需服务端退出撤销；本操作不能替代退出接口。
+     * @returns 本地清理完成，不返回 HaiResult。
+     *
+     * @example
+     * ```ts
+     * import { apiClient } from '@h-ai/api-client'
+     * const initialized = await apiClient.init({ baseUrl: 'https://api.example.com/api/v1', auth: {} })
+     * if (!initialized.success) throw new Error(initialized.error.message)
+     * try {
+     *   const logout = await apiClient.iam.auth.logout({})
+     *   await apiClient.auth.clear()
+     *   if (!logout.success) throw new Error(logout.error.message)
+     *   // 只有服务端退出和本地清理都成功，才能确认两侧均已处理。
+     * }
+     * finally { await apiClient.close() }
+     * ```
+     */
     readonly clear: () => Promise<void>;
-    /** 订阅 Token 刷新成功事件，返回取消订阅函数。 */
+    /**
+     * 订阅当前管理器刷新成功事件；回调在写入后同步调用，避免抛错或输出 Token。
+     * @param callback - 接收 TokenPair 的同步回调。
+     * @returns 取消订阅函数；未启用 auth 时返回空操作。
+     *
+     * @example
+     * ```ts
+     * import { apiClient } from '@h-ai/api-client'
+     * const initialized = await apiClient.init({ baseUrl: 'https://api.example.com/api/v1', auth: {} })
+     * if (!initialized.success) throw new Error(initialized.error.message)
+     * try {
+     *   const off = apiClient.auth.onTokenRefreshed(tokens => { const expiresIn = tokens.expiresIn })
+     *   off()
+     * }
+     * finally { await apiClient.close() }
+     * ```
+     */
     readonly onTokenRefreshed: (callback: (tokens: TokenPair) => void) => () => void;
 }
-/** API client 生命周期能力。 */
+/**
+ * 客户端生命周期与认证辅助能力；init 的 HaiResult 必须先检查 success。
+ * 同一实例并发 init 共享在途初始化，已初始化后再 init 返回 CONFIG_ERROR；切换配置先 close。
+ * config 为脱敏快照；close 清理运行状态/加密会话，不等于服务端退出或凭据存储清理。
+ *
+ * @example
+ * ```ts
+ * import { apiClient, type ApiClientLifecycle } from '@h-ai/api-client'
+ * const client: ApiClientLifecycle = apiClient
+ * const initialized = await client.init({ baseUrl: 'https://api.example.com/api/v1' })
+ * if (!initialized.success) throw new Error(initialized.error.message)
+ * const active = client.isInitialized
+ * const snapshot = client.config
+ * await client.close()
+ * ```
+ */
 interface ApiClientLifecycle {
     /**
-     * 初始化 client；必须在调用任何 procedure 前完成。
+     * 构造并提交客户端运行状态；初始化失败返回 CONFIG_ERROR，未提交半初始化对象。
+     * 并发 init 共享同一初始化；已初始化再调用会失败，切换配置先 close。
+     * @param config - baseUrl、认证、fetch 与可选加密配置。
+     * @returns HaiResult；必须先判断 success，再发起 procedure。
      *
      * @example
      * ```ts
-     * await client.init({
-     *   baseUrl: 'https://api.example.com/api/v1',
-     *   auth: { refreshPath: '/auth/refresh' },
-     *   timeout: 15_000,
-     * })
+     * import { apiClient } from '@h-ai/api-client'
+     * const initialized = await apiClient.init({ baseUrl: 'https://api.example.com/api/v1', auth: {} })
+     * if (!initialized.success) throw new Error(initialized.error.message)
+     * try {
+     *   const result = await apiClient.iam.auth.publicConfig()
+     *   if (!result.success) throw new Error(result.error.message)
+     * }
+     * finally { await apiClient.close() }
      * ```
      */
     readonly init: (config: ApiClientConfig) => Promise<HaiResult<void>>;
-    /** 释放资源并允许重新 `init`。 */
+    /**
+     * 销毁当前加密会话并清除运行状态，允许重新 init；不发送服务端退出、不清空外置存储。
+     * @returns 资源清理完成；不是 HaiResult，不应读取 success。
+     *
+     * @example
+     * ```ts
+     * import { apiClient } from '@h-ai/api-client'
+     * const initialized = await apiClient.init({ baseUrl: 'https://api.example.com/api/v1', auth: {} })
+     * if (!initialized.success) throw new Error(initialized.error.message)
+     * await apiClient.close()
+     * const reinitialized = await apiClient.init({ baseUrl: 'https://api.example.com/api/v1', auth: {} })
+     * if (!reinitialized.success) throw new Error(reinitialized.error.message)
+     * await apiClient.close()
+     * ```
+     */
     readonly close: () => Promise<void>;
     /** 当前脱敏后的运行配置快照；未初始化时为 `null`。 */
     readonly config: ApiClientConfig | null;
@@ -168,15 +412,66 @@ interface ApiClientLifecycle {
     /** Token 辅助操作。 */
     readonly auth: ApiClientAuth;
 }
-/** 根据 oRPC contract 推导出的 typed API client（生命周期 + procedure 调用）。 */
+/**
+ * 由 oRPC 契约推导的 JSON typed client，与生命周期组合；procedure 的输入/输出由契约决定。
+ * 调用先检查初始化和业务 HaiResult；自定义契约不能覆盖 init/close/config/isInitialized/auth 顶层成员。
+ *
+ * @example
+ * ```ts
+ * import { apiClient, type ApiClient } from '@h-ai/api-client'
+ * import { apiContract } from '@h-ai/api-contract'
+ * const contract = apiContract.create({ iam: apiContract.iam })
+ * const client: ApiClient<typeof contract> = apiClient.create(contract)
+ * const initialized = await client.init({ baseUrl: 'https://api.example.com/api/v1', auth: {} })
+ * if (!initialized.success) throw new Error(initialized.error.message)
+ * try {
+ *   const result = await client.iam.auth.currentUser()
+ *   if (!result.success) throw new Error(result.error.message)
+ *   const userId = result.data.id
+ * }
+ * finally { await client.close() }
+ * ```
+ */
 type ApiClient<TContract extends AnyContractRouter> = ApiClientLifecycle & JsonifiedClient<ContractRouterClient<TContract>>;
 
-/** 与认证场景表单对齐的登录输入。 */
+/**
+ * 认证表单登录输入；默认 password，ldap 使用 identifier/password，email/sms 使用 identifier/code。
+ * method/code 为客户端表单辅助字段，按所选方式映射到标准 IAM procedure。
+ *
+ * @example
+ * ```ts
+ * import type { IamAuthLoginInput } from '@h-ai/api-client'
+ * const input: IamAuthLoginInput = { identifier: 'alice@example.com', password: '', method: 'email', code: '123456' }
+ * ```
+ */
 type IamAuthLoginInput = IamLoginInput & {
     method?: 'password' | 'ldap' | 'email' | 'sms';
     code?: string;
 };
-/** 绑定任意包含标准 iam contract 的客户端；成功时自动保存 Token。 */
+/**
+ * 将含标准 IAM 契约的客户端绑定为认证表单动作；包用户通过 apiClient.createAuthActions 调用。
+ * 登录/注册成功后等待 client.auth.setTokens，失败 HaiResult 原样返回；存储失败拒绝 Promise，不能据服务端成功就显示已登录。
+ * 调用方必须先 init 并启用 auth；未启用 auth 时客户端 setTokens 不会建立 Token 管理器。
+ * @param client - 具有标准 IAM procedure 与 setTokens 能力的已初始化客户端。
+ * @param client.iam - 标准 IAM 契约的领域分组。
+ * @param client.iam.auth - 公开配置、登录、注册、验证码和密码重置 procedure。
+ * @param client.auth - 认证成功后的凭据写入能力（setTokens）。
+ * @returns publicConfig、按方式登录、注册、验证码和密码重置动作。
+ *
+ * @example
+ * ```ts
+ * import { apiClient } from '@h-ai/api-client'
+ * const initialized = await apiClient.init({ baseUrl: 'https://api.example.com/api/v1', auth: {} })
+ * if (!initialized.success) throw new Error(initialized.error.message)
+ * try {
+ *   const actions = apiClient.createAuthActions(apiClient)
+ *   // 运行时凭据来自已验证的表单；此处只请求公开配置，不提交示例密码。
+ *   const config = await actions.publicConfig()
+ *   if (!config.success) throw new Error(config.error.message)
+ * }
+ * finally { await apiClient.close() }
+ * ```
+ */
 declare function createIamAuthActions(client: {
     iam: {
         auth: Pick<ApiClient<{
@@ -382,17 +677,19 @@ declare function createIamAuthActions(client: {
 /**
  * @h-ai/api-client — Token 存储与刷新管理
  *
- * 提供两个内置 Token 存储适配器（localStorage / 内存）和一个 Token 管理器
+ * 提供两个内置 Token 存储适配器（httpOnly Cookie / 内存）和一个 Token 管理器
  * （封装存储读写、自动刷新、并发去重、回调通知）。
  *
  * @example 浏览器 SPA
  * ```ts
  * import { apiClient } from '@h-ai/api-client'
  *
- * await apiClient.init({
+ * const initialized = await apiClient.init({
  *   baseUrl: 'https://api.example.com/api/v1',
- *   auth: { storage: apiClient.tokenStorage.localStorage() },
+ *   auth: { storage: apiClient.tokenStorage.httpOnlyCookie() },
  * })
+ * if (!initialized.success) throw new Error(initialized.error.message)
+ * await apiClient.close()
  * ```
  *
  * @example Node.js 测试
@@ -400,122 +697,80 @@ declare function createIamAuthActions(client: {
  * import { apiClient } from '@h-ai/api-client'
  *
  * const storage = apiClient.tokenStorage.memory()
- * await storage.setAccessToken('abc')
+ * await storage.setAccessToken('test-access')
+ * await storage.clear()
  * ```
  *
  * @module api-client-auth
  */
 
 /**
- * 创建基于 `localStorage` 的 Token 存储（浏览器 SPA / PWA）。
- *
- * ⚠️ 安全提示（XSS 风险）：
- * - `localStorage` 对同源脚本可读，任意 XSS 漏洞都可以偷取 Token。
- * - 生产环境应优先使用 httpOnly cookie + SameSite 或 BFF 主机代理。
- * - 本适配器仅适用于内部工具、Demo、或者已接受 XSS 风险的浏览器场景，
- *   并且在调用方明确选择使用。`apiClient.create` 默认不会使用本适配器，
- *   需调用方显式传入 `auth.storage = apiClient.tokenStorage.localStorage()`。
- *
- * @example
- * ```ts
- * await apiClient.init({
- *   baseUrl: 'https://api.example.com/api/v1',
- *   auth: { storage: apiClient.tokenStorage.localStorage() },
- * })
- * ```
- */
-declare function createLocalStorageTokenStorage(): TokenStorage;
-/**
- * 创建内存 Token 存储（Node.js 测试 / SSR / 短生命周期场景）。
- * 页面刷新后丢失。
+ * 创建仅属于本适配器实例的内存凭据存储，页面刷新或进程结束后丢失。
+ * SSR 应为每个请求创建客户端和存储实例，避免不同用户共享默认单例。
+ * 通过 client.auth 更新已绑定的存储，才能撤销旧代际刷新；直接存储写入不提供这种保证。
+ * @returns 两个初始为空的 Token 槽位及清理操作。
  *
  * @example
  * ```ts
+ * import { apiClient } from '@h-ai/api-client'
  * const storage = apiClient.tokenStorage.memory()
- * await storage.setAccessToken('abc')
+ * await storage.setAccessToken('test-access')
+ * const saved = await storage.getAccessToken()
+ * await storage.clear()
+ * // saved 为本实例的测试值；不把 Token 写入 Web Storage。
  * ```
  */
 declare function createMemoryTokenStorage(): TokenStorage;
 /**
- * 创建基于 httpOnly cookie 的 Token 存储（生产环境推荐方案）。
- *
- * **安全模型：**
- * - `accessToken` 保存在**内存**中：JS 可读写，用于注入 `Authorization: Bearer`；
- *   页面刷新后丢失，由 refresh 流程自动补充。
- * - `refreshToken` 保存在服务端设置的 **httpOnly cookie** 中：
- *   - JS 不可读写，XSS 脚本无法直接盗取。
- *   - 结合 `SameSite=Strict` 可阻止 CSRF 攻击。
- *   - 浏览器在每次请求时自动携带，无需客户端显式传递。
- *
- * **服务端配套要求：**
- * 1. 登录端点在响应中设置：
- *    ```
- *    Set-Cookie: refresh_token=<token>; HttpOnly; SameSite=Strict; Secure;
- *               Path=/api/v1/auth/refresh; Max-Age=<seconds>
- *    ```
- *    `Path` 限定为 refresh 端点，减少 Cookie 暴露面。
- * 2. Refresh 端点从 Cookie 读取 refresh token（忽略请求体中的 `refreshToken` 字段）。
- * 3. Logout 端点清除 Cookie：
- *    ```
- *    Set-Cookie: refresh_token=; HttpOnly; SameSite=Strict; Secure;
- *               Path=/api/v1/auth/refresh; Max-Age=0
- *    ```
- *
- * **跨域注意事项：**
- * 若 API 与前端不同源，服务端还需设置：
- * `Access-Control-Allow-Origin: <前端域名>` 和 `Access-Control-Allow-Credentials: true`。
- * 调用方不需要做额外配置，`apiClient.create` 会自动识别并设置 `credentials: 'include'`。
+ * 创建浏览器使用的内存 access token 与服务端 httpOnly refresh Cookie 适配器。
+ * refresh getter 返回内部哨兵，setter 不修改 Cookie；clear 只清除内存 access token。
+ * 刷新请求使用 credentials: include；服务端须实际设置/撤销 Cookie，配置适当的 Secure、SameSite、Path 与跨域凭据策略。
+ * HttpOnly 限制脚本直接读取 Cookie，不能阻止已执行的恶意脚本代用户发请求；服务端仍须授权和防护 CSRF。
+ * @returns 独立内存 access token 与 Cookie 模式标记；不接触 localStorage。
  *
  * @example
  * ```ts
- * await apiClient.init({
- *   baseUrl: 'https://api.example.com/api/v1',
- *   auth: { storage: apiClient.tokenStorage.httpOnlyCookie() },
- * })
+ * import { apiClient } from '@h-ai/api-client'
+ * const initialized = await apiClient.init({ baseUrl: 'https://api.example.com/api/v1', auth: { storage: apiClient.tokenStorage.httpOnlyCookie() } })
+ * if (!initialized.success) throw new Error(initialized.error.message)
+ * try {
+ *   const me = await apiClient.iam.auth.currentUser()
+ *   if (!me.success) throw new Error(me.error.message)
+ *   const userId = me.data.id
+ * }
+ * finally { await apiClient.close() }
  * ```
  */
 declare function createHttpOnlyCookieTokenStorage(): TokenStorage;
 
-/** Token 存储方案集合：内存 / 浏览器 localStorage / httpOnly Cookie。 */
+/** Token 存储方案集合：内存 / httpOnly Cookie。 */
 declare const tokenStorage: {
     /** 内存存储——SSR / Node 测试或一次性会话使用。 */
     readonly memory: typeof createMemoryTokenStorage;
-    /** 浏览器 `localStorage` 存储——单页应用便捷选项；注意 XSS 风险。 */
-    readonly localStorage: typeof createLocalStorageTokenStorage;
     /** httpOnly Cookie 存储——浏览器场景推荐方案。 */
     readonly httpOnlyCookie: typeof createHttpOnlyCookieTokenStorage;
 };
 /**
- * 根据 oRPC contract 创建 typed API client。
- *
- * 返回对象同时具备：
- * - **生命周期能力**：`init` / `close` / `config` / `isInitialized` / `auth`
- * - **contract procedure**：按 contract 嵌套结构调用，例如 `client.iam.auth.login(input)`
+ * 按真实 oRPC 契约创建独立 typed client；公开调用入口为 apiClient.create(contract)。
+ * init 返回 HaiResult，成功后才调用 procedure；已初始化实例必须先 close 再换配置。
+ * procedure 将传输异常转换为 HaiResult；auth.setTokens/clear 的安全存储失败仍会拒绝 Promise。
+ * SSR 应为每个请求创建客户端和内存存储；不共享默认单例中的用户凭据。
+ * @param contract - 已定义的嵌套 oRPC contract；顶层命名不能与生命周期成员冲突。
+ * @returns 生命周期、认证辅助操作与契约推导出的 procedure 代理。
  *
- * @example 基础用法
+ * @example
  * ```ts
  * import { apiClient } from '@h-ai/api-client'
  * import { apiContract } from '@h-ai/api-contract'
- *
  * const client = apiClient.create(apiContract.create({ iam: apiContract.iam }))
- * await client.init({ baseUrl: 'https://api.example.com/api/v1' })
- *
- * const result = await client.iam.auth.login({ identifier: 'alice', password: 'secret' })
- * if (result.success) {
- *   await client.auth.setTokens(result.data.tokens)
+ * const initialized = await client.init({ baseUrl: 'https://api.example.com/api/v1', auth: { storage: apiClient.tokenStorage.memory() }, timeout: 10000 })
+ * if (!initialized.success) throw new Error(initialized.error.message)
+ * try {
+ *   const result = await client.iam.auth.currentUser()
+ *   if (!result.success) throw new Error(result.error.message)
+ *   const userId = result.data.id
  * }
- *
- * await client.close()
- * ```
- *
- * @example 自定义 fetch / 超时
- * ```ts
- * const client = apiClient.create(contract)
- * await client.init({
- *   baseUrl: 'https://api.example.com/api/v1',
- *   fetch: customFetch,
- *   timeout: 10_000,
- * })
+ * finally { await client.close() }
  * ```
  */
 declare function createApiClient<const TContract extends AnyContractRouter>(contract: TContract): ApiClient<TContract>;
@@ -528,12 +783,16 @@ declare function createApiClient<const TContract extends AnyContractRouter>(cont
  * ```ts
  * import { apiClient } from '@h-ai/api-client'
  *
- * await apiClient.init({
+ * const initialized = await apiClient.init({
  *   baseUrl: 'http://localhost:3000/api/v1',
  *   auth: { refreshPath: '/auth/refresh' },
  * })
- * const result = await apiClient.iam.auth.login({ identifier: 'alice', password: 'secret' })
- * await apiClient.close()
+ * if (!initialized.success) throw new Error(initialized.error.message)
+ * try {
+ *   const result = await apiClient.iam.auth.currentUser()
+ *   if (!result.success) throw new Error(result.error.message)
+ * }
+ * finally { await apiClient.close() }
  * ```
  */
 declare const defaultApiContract: _h_ai_api_contract.CreatedApiContract<{
@@ -699,7 +958,6 @@ declare const defaultApiContract: _h_ai_api_contract.CreatedApiContract<{
             login: _orpc_contract.ContractProcedureBuilderWithInputOutput<zod.ZodObject<{
                 identifier: zod.ZodString;
                 password: zod.ZodString;
-                rememberMe: zod.ZodOptional<zod.ZodBoolean>;
             }, zod_v4_core.$strip>, zod.ZodDiscriminatedUnion<[zod.ZodObject<{
                 success: zod.ZodLiteral<true>;
                 data: zod.ZodObject<{
@@ -1466,7 +1724,7 @@ declare const defaultApiContract: _h_ai_api_contract.CreatedApiContract<{
             createDownload: _orpc_contract.ContractProcedureBuilderWithInputOutput<zod.ZodObject<{
                 key: zod.ZodString;
                 expiresIn: zod.ZodOptional<zod.ZodNumber>;
-            }, zod_v4_core.$strip>, zod.ZodDiscriminatedUnion<[zod.ZodObject<{
+            }, zod_v4_core.$strict>, zod.ZodDiscriminatedUnion<[zod.ZodObject<{
                 success: zod.ZodLiteral<true>;
                 data: zod.ZodObject<{
                     url: zod.ZodString;
@@ -1489,9 +1747,8 @@ declare const defaultApiContract: _h_ai_api_contract.CreatedApiContract<{
             createUpload: _orpc_contract.ContractProcedureBuilderWithInputOutput<zod.ZodObject<{
                 key: zod.ZodString;
                 contentType: zod.ZodOptional<zod.ZodString>;
-                contentLength: zod.ZodOptional<zod.ZodNumber>;
                 expiresIn: zod.ZodOptional<zod.ZodNumber>;
-            }, zod_v4_core.$strip>, zod.ZodDiscriminatedUnion<[zod.ZodObject<{
+            }, zod_v4_core.$strict>, zod.ZodDiscriminatedUnion<[zod.ZodObject<{
                 success: zod.ZodLiteral<true>;
                 data: zod.ZodObject<{
                     url: zod.ZodString;
@@ -1593,7 +1850,19 @@ declare const defaultApiContract: _h_ai_api_contract.CreatedApiContract<{
                 keys: zod.ZodArray<zod.ZodString>;
             }, zod_v4_core.$strip>, zod.ZodDiscriminatedUnion<[zod.ZodObject<{
                 success: zod.ZodLiteral<true>;
-                data: zod.ZodVoid;
+                data: zod.ZodObject<{
+                    deletedKeys: zod.ZodArray<zod.ZodString>;
+                    failures: zod.ZodArray<zod.ZodObject<{
+                        key: zod.ZodString;
+                        code: zod.ZodString;
+                        retryable: zod.ZodBoolean;
+                        outcome: zod.ZodEnum<{
+                            unknown: "unknown";
+                            failed: "failed";
+                            notAttempted: "notAttempted";
+                        }>;
+                    }, zod_v4_core.$strip>>;
+                }, zod_v4_core.$strip>;
             }, zod_v4_core.$strip>, zod.ZodObject<{
                 success: zod.ZodLiteral<false>;
                 error: zod.ZodObject<{
@@ -1604,7 +1873,21 @@ declare const defaultApiContract: _h_ai_api_contract.CreatedApiContract<{
                     module: zod.ZodOptional<zod.ZodString>;
                     cause: zod.ZodOptional<zod.ZodUnknown>;
                     suggestion: zod.ZodOptional<zod.ZodString>;
-                    ext: zod.ZodOptional<zod.ZodRecord<zod.ZodString, zod.ZodUnknown>>;
+                    ext: zod.ZodOptional<zod.ZodObject<{
+                        deleteMany: zod.ZodOptional<zod.ZodObject<{
+                            deletedKeys: zod.ZodArray<zod.ZodString>;
+                            failures: zod.ZodArray<zod.ZodObject<{
+                                key: zod.ZodString;
+                                code: zod.ZodString;
+                                retryable: zod.ZodBoolean;
+                                outcome: zod.ZodEnum<{
+                                    unknown: "unknown";
+                                    failed: "failed";
+                                    notAttempted: "notAttempted";
+                                }>;
+                            }, zod_v4_core.$strip>>;
+                        }, zod_v4_core.$strip>>;
+                    }, zod_v4_core.$catchall<zod.ZodUnknown>>>;
                 }, zod_v4_core.$strip>;
             }, zod_v4_core.$strip>], "success">, Record<never, never>, Record<never, never>>;
         };
@@ -1612,18 +1895,22 @@ declare const defaultApiContract: _h_ai_api_contract.CreatedApiContract<{
     readonly ai: {
         chats: {
             createCompletion: _orpc_contract.ContractProcedureBuilderWithInputOutput<zod.ZodObject<{
+                objectId: zod.ZodOptional<zod.ZodString>;
+                sessionId: zod.ZodOptional<zod.ZodString>;
                 model: zod.ZodOptional<zod.ZodString>;
-                messages: zod.ZodArray<zod.ZodObject<{
-                    role: zod.ZodEnum<{
-                        system: "system";
-                        user: "user";
-                        assistant: "assistant";
-                        tool: "tool";
-                    }>;
-                    content: zod.ZodOptional<zod.ZodUnion<readonly [zod.ZodString, zod.ZodArray<zod.ZodUnion<readonly [zod.ZodObject<{
+                messages: zod.ZodArray<zod.ZodDiscriminatedUnion<[zod.ZodObject<{
+                    role: zod.ZodLiteral<"system">;
+                    content: zod.ZodUnion<readonly [zod.ZodString, zod.ZodArray<zod.ZodObject<{
                         type: zod.ZodLiteral<"text">;
                         text: zod.ZodString;
-                    }, zod_v4_core.$strip>, zod.ZodObject<{
+                    }, zod_v4_core.$strict>>]>;
+                    name: zod.ZodOptional<zod.ZodString>;
+                }, zod_v4_core.$strict>, zod.ZodObject<{
+                    role: zod.ZodLiteral<"user">;
+                    content: zod.ZodUnion<readonly [zod.ZodString, zod.ZodArray<zod.ZodUnion<readonly [zod.ZodObject<{
+                        type: zod.ZodLiteral<"text">;
+                        text: zod.ZodString;
+                    }, zod_v4_core.$strict>, zod.ZodObject<{
                         type: zod.ZodLiteral<"image_url">;
                         image_url: zod.ZodObject<{
                             url: zod.ZodString;
@@ -1632,8 +1919,15 @@ declare const defaultApiContract: _h_ai_api_contract.CreatedApiContract<{
                                 low: "low";
                                 high: "high";
                             }>>;
-                        }, zod_v4_core.$strip>;
-                    }, zod_v4_core.$strip>]>>]>>;
+                        }, zod_v4_core.$strict>;
+                    }, zod_v4_core.$strict>]>>]>;
+                    name: zod.ZodOptional<zod.ZodString>;
+                }, zod_v4_core.$strict>, zod.ZodObject<{
+                    role: zod.ZodLiteral<"assistant">;
+                    content: zod.ZodOptional<zod.ZodNullable<zod.ZodUnion<readonly [zod.ZodString, zod.ZodArray<zod.ZodObject<{
+                        type: zod.ZodLiteral<"text">;
+                        text: zod.ZodString;
+                    }, zod_v4_core.$strict>>]>>>;
                     name: zod.ZodOptional<zod.ZodString>;
                     tool_calls: zod.ZodOptional<zod.ZodArray<zod.ZodObject<{
                         id: zod.ZodString;
@@ -1641,37 +1935,35 @@ declare const defaultApiContract: _h_ai_api_contract.CreatedApiContract<{
                         function: zod.ZodObject<{
                             name: zod.ZodString;
                             arguments: zod.ZodString;
-                        }, zod_v4_core.$strip>;
-                    }, zod_v4_core.$strip>>>;
-                    tool_call_id: zod.ZodOptional<zod.ZodString>;
-                }, zod_v4_core.$strip>>;
+                        }, zod_v4_core.$strict>;
+                    }, zod_v4_core.$strict>>>;
+                }, zod_v4_core.$strict>, zod.ZodObject<{
+                    role: zod.ZodLiteral<"tool">;
+                    content: zod.ZodUnion<readonly [zod.ZodString, zod.ZodArray<zod.ZodObject<{
+                        type: zod.ZodLiteral<"text">;
+                        text: zod.ZodString;
+                    }, zod_v4_core.$strict>>]>;
+                    tool_call_id: zod.ZodString;
+                }, zod_v4_core.$strict>], "role">>;
                 temperature: zod.ZodOptional<zod.ZodNumber>;
                 top_p: zod.ZodOptional<zod.ZodNumber>;
                 max_tokens: zod.ZodOptional<zod.ZodNumber>;
-                stream: zod.ZodOptional<zod.ZodBoolean>;
                 tools: zod.ZodOptional<zod.ZodArray<zod.ZodObject<{
                     type: zod.ZodLiteral<"function">;
                     function: zod.ZodObject<{
                         name: zod.ZodString;
                         description: zod.ZodOptional<zod.ZodString>;
-                        parameters: zod.ZodOptional<zod.ZodObject<{
-                            type: zod.ZodLiteral<"object">;
-                            properties: zod.ZodOptional<zod.ZodRecord<zod.ZodString, zod.ZodObject<{
-                                type: zod.ZodString;
-                                description: zod.ZodOptional<zod.ZodString>;
-                                enum: zod.ZodOptional<zod.ZodArray<zod.ZodString>>;
-                            }, zod_v4_core.$strip>>>;
-                            required: zod.ZodOptional<zod.ZodArray<zod.ZodString>>;
-                        }, zod_v4_core.$strip>>;
-                    }, zod_v4_core.$strip>;
-                }, zod_v4_core.$strip>>>;
-                tool_choice: zod.ZodOptional<zod.ZodUnion<readonly [zod.ZodLiteral<"auto">, zod.ZodLiteral<"none">, zod.ZodObject<{
+                        parameters: zod.ZodOptional<zod.ZodRecord<zod.ZodString, zod.ZodJSONSchema>>;
+                        strict: zod.ZodOptional<zod.ZodNullable<zod.ZodBoolean>>;
+                    }, zod_v4_core.$strict>;
+                }, zod_v4_core.$strict>>>;
+                tool_choice: zod.ZodOptional<zod.ZodUnion<readonly [zod.ZodLiteral<"auto">, zod.ZodLiteral<"none">, zod.ZodLiteral<"required">, zod.ZodObject<{
                     type: zod.ZodLiteral<"function">;
                     function: zod.ZodObject<{
                         name: zod.ZodString;
-                    }, zod_v4_core.$strip>;
-                }, zod_v4_core.$strip>]>>;
-            }, zod_v4_core.$strip>, zod.ZodDiscriminatedUnion<[zod.ZodObject<{
+                    }, zod_v4_core.$strict>;
+                }, zod_v4_core.$strict>]>>;
+            }, zod_v4_core.$strict>, zod.ZodDiscriminatedUnion<[zod.ZodObject<{
                 success: zod.ZodLiteral<true>;
                 data: zod.ZodObject<{
                     id: zod.ZodString;
@@ -1689,8 +1981,8 @@ declare const defaultApiContract: _h_ai_api_contract.CreatedApiContract<{
                                 function: zod.ZodObject<{
                                     name: zod.ZodString;
                                     arguments: zod.ZodString;
-                                }, zod_v4_core.$strip>;
-                            }, zod_v4_core.$strip>>>;
+                                }, zod_v4_core.$strict>;
+                            }, zod_v4_core.$strict>>>;
                         }, zod_v4_core.$strip>;
                         finish_reason: zod.ZodEnum<{
                             length: "length";
@@ -1719,6 +2011,8 @@ declare const defaultApiContract: _h_ai_api_contract.CreatedApiContract<{
                 }, zod_v4_core.$strip>;
             }, zod_v4_core.$strip>], "success">, Record<never, never>, Record<never, never>>;
             sendMessage: _orpc_contract.ContractProcedureBuilderWithInputOutput<zod.ZodObject<{
+                objectId: zod.ZodOptional<zod.ZodString>;
+                sessionId: zod.ZodOptional<zod.ZodString>;
                 message: zod.ZodString;
                 systemPrompt: zod.ZodOptional<zod.ZodString>;
                 model: zod.ZodOptional<zod.ZodString>;
@@ -1748,7 +2042,7 @@ declare const defaultApiContract: _h_ai_api_contract.CreatedApiContract<{
                 }, zod_v4_core.$strip>;
             }, zod_v4_core.$strip>], "success">, Record<never, never>, Record<never, never>>;
             listHistory: _orpc_contract.ContractProcedureBuilderWithInputOutput<zod.ZodObject<{
-                objectId: zod.ZodString;
+                objectId: zod.ZodOptional<zod.ZodString>;
                 sessionId: zod.ZodString;
                 limit: zod.ZodOptional<zod.ZodNumber>;
                 order: zod.ZodOptional<zod.ZodEnum<{
@@ -1764,17 +2058,19 @@ declare const defaultApiContract: _h_ai_api_contract.CreatedApiContract<{
                         sessionId: zod.ZodString;
                         request: zod.ZodObject<{
                             model: zod.ZodString;
-                            messages: zod.ZodArray<zod.ZodObject<{
-                                role: zod.ZodEnum<{
-                                    system: "system";
-                                    user: "user";
-                                    assistant: "assistant";
-                                    tool: "tool";
-                                }>;
-                                content: zod.ZodOptional<zod.ZodUnion<readonly [zod.ZodString, zod.ZodArray<zod.ZodUnion<readonly [zod.ZodObject<{
+                            messages: zod.ZodArray<zod.ZodDiscriminatedUnion<[zod.ZodObject<{
+                                role: zod.ZodLiteral<"system">;
+                                content: zod.ZodUnion<readonly [zod.ZodString, zod.ZodArray<zod.ZodObject<{
                                     type: zod.ZodLiteral<"text">;
                                     text: zod.ZodString;
-                                }, zod_v4_core.$strip>, zod.ZodObject<{
+                                }, zod_v4_core.$strict>>]>;
+                                name: zod.ZodOptional<zod.ZodString>;
+                            }, zod_v4_core.$strict>, zod.ZodObject<{
+                                role: zod.ZodLiteral<"user">;
+                                content: zod.ZodUnion<readonly [zod.ZodString, zod.ZodArray<zod.ZodUnion<readonly [zod.ZodObject<{
+                                    type: zod.ZodLiteral<"text">;
+                                    text: zod.ZodString;
+                                }, zod_v4_core.$strict>, zod.ZodObject<{
                                     type: zod.ZodLiteral<"image_url">;
                                     image_url: zod.ZodObject<{
                                         url: zod.ZodString;
@@ -1783,8 +2079,15 @@ declare const defaultApiContract: _h_ai_api_contract.CreatedApiContract<{
                                             low: "low";
                                             high: "high";
                                         }>>;
-                                    }, zod_v4_core.$strip>;
-                                }, zod_v4_core.$strip>]>>]>>;
+                                    }, zod_v4_core.$strict>;
+                                }, zod_v4_core.$strict>]>>]>;
+                                name: zod.ZodOptional<zod.ZodString>;
+                            }, zod_v4_core.$strict>, zod.ZodObject<{
+                                role: zod.ZodLiteral<"assistant">;
+                                content: zod.ZodOptional<zod.ZodNullable<zod.ZodUnion<readonly [zod.ZodString, zod.ZodArray<zod.ZodObject<{
+                                    type: zod.ZodLiteral<"text">;
+                                    text: zod.ZodString;
+                                }, zod_v4_core.$strict>>]>>>;
                                 name: zod.ZodOptional<zod.ZodString>;
                                 tool_calls: zod.ZodOptional<zod.ZodArray<zod.ZodObject<{
                                     id: zod.ZodString;
@@ -1792,10 +2095,16 @@ declare const defaultApiContract: _h_ai_api_contract.CreatedApiContract<{
                                     function: zod.ZodObject<{
                                         name: zod.ZodString;
                                         arguments: zod.ZodString;
-                                    }, zod_v4_core.$strip>;
-                                }, zod_v4_core.$strip>>>;
-                                tool_call_id: zod.ZodOptional<zod.ZodString>;
-                            }, zod_v4_core.$strip>>;
+                                    }, zod_v4_core.$strict>;
+                                }, zod_v4_core.$strict>>>;
+                            }, zod_v4_core.$strict>, zod.ZodObject<{
+                                role: zod.ZodLiteral<"tool">;
+                                content: zod.ZodUnion<readonly [zod.ZodString, zod.ZodArray<zod.ZodObject<{
+                                    type: zod.ZodLiteral<"text">;
+                                    text: zod.ZodString;
+                                }, zod_v4_core.$strict>>]>;
+                                tool_call_id: zod.ZodString;
+                            }, zod_v4_core.$strict>], "role">>;
                         }, zod_v4_core.$strip>;
                         response: zod.ZodObject<{
                             content: zod.ZodString;
@@ -1805,8 +2114,8 @@ declare const defaultApiContract: _h_ai_api_contract.CreatedApiContract<{
                                 function: zod.ZodObject<{
                                     name: zod.ZodString;
                                     arguments: zod.ZodString;
-                                }, zod_v4_core.$strip>;
-                            }, zod_v4_core.$strip>>>;
+                                }, zod_v4_core.$strict>;
+                            }, zod_v4_core.$strict>>>;
                             finishReason: zod.ZodString;
                             usage: zod.ZodObject<{
                                 prompt_tokens: zod.ZodNumber;
@@ -1928,7 +2237,7 @@ declare const defaultApiContract: _h_ai_api_contract.CreatedApiContract<{
         };
         sessions: {
             list: _orpc_contract.ContractProcedureBuilderWithInputOutput<zod.ZodObject<{
-                objectId: zod.ZodString;
+                objectId: zod.ZodOptional<zod.ZodString>;
             }, zod_v4_core.$strip>, zod.ZodDiscriminatedUnion<[zod.ZodObject<{
                 success: zod.ZodLiteral<true>;
                 data: zod.ZodObject<{
@@ -1956,13 +2265,43 @@ declare const defaultApiContract: _h_ai_api_contract.CreatedApiContract<{
         };
     };
 }>;
-/** `apiClient` 默认单例 + 工厂命名空间的统一对外类型。 */
+/**
+ * 默认 iam/storage/ai typed client 与 create、tokenStorage、createAuthActions 命名空间的交叉类型。
+ * 具体项目契约使用 apiClient.create 的返回类型，不给默认单例附加未知 procedure。
+ *
+ * @example
+ * ```ts
+ * import { apiClient, type DefaultApiClient } from '@h-ai/api-client'
+ * const client: DefaultApiClient = apiClient
+ * const initialized = await client.init({ baseUrl: 'https://api.example.com/api/v1', auth: {} })
+ * if (!initialized.success) throw new Error(initialized.error.message)
+ * try { const actions = client.createAuthActions(client); const result = await actions.publicConfig(); if (!result.success) throw new Error(result.error.message) }
+ * finally { await client.close() }
+ * ```
+ */
 type DefaultApiClient = ApiClient<typeof defaultApiContract> & {
     readonly create: typeof createApiClient;
     readonly tokenStorage: typeof tokenStorage;
     readonly createAuthActions: typeof createIamAuthActions;
 };
-/** hai-framework API client 统一入口（默认单例 + `create` + `tokenStorage`）。 */
+/**
+ * API Client 公开入口：默认 iam/storage/ai 单例，以及独立实例、安全存储和认证动作工厂。
+ * 未启用 auth 时不注入或刷新 Token；浏览器 auth: {} 使用 httpOnly Cookie 方案。
+ * close 释放客户端运行状态/加密会话，不能替代服务端退出或 auth.clear。
+ *
+ * @example
+ * ```ts
+ * import { apiClient } from '@h-ai/api-client'
+ * const initialized = await apiClient.init({ baseUrl: 'https://api.example.com/api/v1', auth: {} })
+ * if (!initialized.success) throw new Error(initialized.error.message)
+ * try {
+ *   const result = await apiClient.iam.auth.currentUser()
+ *   if (!result.success) throw new Error(result.error.message)
+ *   const permissions = result.data.permissions
+ * }
+ * finally { await apiClient.close() }
+ * ```
+ */
 declare const apiClient: DefaultApiClient;
 
 export { type ApiClient, type ApiClientAuth, type ApiClientConfig, type ApiClientLifecycle, type ApiClientTransportConfig, type AuthConfig, type DefaultApiClient, HaiApiClientError, type IamAuthLoginInput, type TokenPair, type TokenStorage, apiClient };