@h-ai/capacitor 0.1.0-alpha.67 → 0.1.0-alpha.68

package/README.en.md

@@ -47,7 +47,11 @@ await apiClient.init({
 })
 ```
 
-`createCapacitorTokenStorage()` persists tokens only on native Android/iOS and requires `@aparajita/capacitor-secure-storage`. On Web it does not fall back to `localStorage`: `get*()` returns `null`, and `set*()` / `clear()` are no-ops.
+`createCapacitorTokenStorage()` persists tokens only on native Android/iOS and requires `@aparajita/capacitor-secure-storage`. Its methods return promises directly: Web calls, an unavailable plugin, and failed reads, writes, or removals reject instead of pretending credentials are absent or an operation succeeded. Web entry points should select api-client cookie or memory storage.
+
+`clear()` immediately blocks both old credentials in this adapter instance and waits for all native removals before reporting the result. Failures keep them blocked; a successful write reopens only that key. Update credentials through `apiClient.auth` for serialized writes and handle rejected `setTokens()` / `clear()` calls. The UI must release its loading state, discard the logged-out identity, and display failures. Instance-local blocking does not prove persistent deletion; revocation across restarts still requires server logout/session revocation. Retry with the same instance after the plugin recovers.
+
+A failed credential write blocks both credentials, including an access token already saved before a refresh-token write failed. After failed login or registration persistence, attempt `auth.clear()` to remove partially saved data. Report cleanup failures explicitly instead of claiming device credentials were deleted.
 
 #### Device information and push notifications
 
@@ -65,6 +69,8 @@ if (reg.success) {
 }
 ```
 
+Push requires an actual native platform. The setup phase of `push.register({ signal? })` and `push.listen(callbacks, { signal? })` has a 30-second deadline including permission requests and listener attachment. Failure, timeout, cancellation and `capacitor.close()` stop callbacks and remove owned handles; late handles are removed when they arrive. Other consumers are not affected through removeAllListeners. After listen succeeds, its signal and returned cleanup can still stop it. Cleanup and close return `HaiResult<void>`; native removal failures return `PUSH_CLEANUP_FAILED` (`capacitor:032`) and retain failed handles for retry without repeating successful removals. Closing disables the module immediately, and initialization retries pending cleanup first. Controlled plugin timing tests do not replace repeated registration, permission and FCM/APNs checks on Android/iOS devices.
+
 #### Status bar
 
 ```ts
@@ -111,7 +117,7 @@ export const ssr = false
 
 ### Error handling
 
-All asynchronous APIs return `HaiResult<T>` instead of throwing directly:
+Business operations on `capacitor.*` and `safe*Preference` return `HaiResult<T>`. TokenStorage adapter methods reject their promises on platform or storage errors:
 
 ```ts
 import { capacitor, HaiCapacitorError } from '@h-ai/capacitor'
@@ -150,6 +156,8 @@ pnpm --filter @h-ai/capacitor test
 
 > Tests must mock `@capacitor/*` modules because they depend on native plugins.
 
+Public operations, internal resource scopes and types include typechecked examples; see the [JSDoc conventions (Chinese)](../../.agents/instructions/module-conventions.md#jsdoc-与示例验证). Typechecking does not prove device permissions or live FCM/APNs delivery.
+
 ## License
 
 Apache-2.0

package/README.ja.md

@@ -47,7 +47,11 @@ await apiClient.init({
 })
 ```
 
-`createCapacitorTokenStorage()` は Android/iOS のネイティブ環境でのみ Token を永続化し、`@aparajita/capacitor-secure-storage` が必要です。Web では `localStorage` に切り替わらず、`get*()` は `null` を返し、`set*()` / `clear()` は何もしません。
+`createCapacitorTokenStorage()` は Android/iOS のネイティブ環境でのみ Token を永続化し、`@aparajita/capacitor-secure-storage` が必要です。メソッドは Promise を直接返し、Web 呼び出し、プラグインの利用不可、読み書き・削除の失敗は reject されます。空の認証情報や操作成功として扱わないでください。Web では api-client の Cookie またはメモリーストレージを選びます。
+
+`clear()` は開始時にこのインスタンスの古い認証情報を読み取り不可にし、すべてのネイティブ削除が完了してから結果を返します。失敗時は読み取りを禁止したままにし、各キーへの書き込み成功時のみそのキーを再開します。書き込みを直列化する `apiClient.auth` を使い、`setTokens()` / `clear()` の失敗を処理してください。UI は loading を解除し、ログアウトしたユーザー情報を消去して失敗を表示します。この制限はインスタンス内のみで、永続データの削除を保証しません。再起動後の失効にはサーバーでのセッション撤回が必要です。プラグイン復旧後は同じインスタンスで再試行できます。
+
+認証情報の一方の書き込みが失敗すると両方を読み取り不可にするため、access token 保存後に refresh token の保存が失敗しても不完全な認証状態は公開しません。ログイン・登録時の保存失敗後は `auth.clear()` で部分保存データの削除を試み、削除も失敗した場合は端末の認証情報を削除できたと表示しないでください。
 
 #### 端末情報とプッシュ通知
 
@@ -65,6 +69,8 @@ if (reg.success) {
 }
 ```
 
+Push は実際のネイティブ環境が必要です。`push.register({ signal? })` と `push.listen(callbacks, { signal? })` の設定段階は権限要求とリスナー登録を含め30秒で終了します。失敗、タイムアウト、中止、`capacitor.close()` はコールバックを停止し、所有するハンドルを除去します。遅延したハンドルも到着時に除去し、removeAllListeners で他の利用者を巻き込みません。listen 成功後も signal と cleanup が有効です。cleanup と close は `HaiResult<void>` を返し、ネイティブ除去失敗は `PUSH_CLEANUP_FAILED`（`capacitor:032`）です。失敗したハンドルを保持して再試行し、成功済みの除去は繰り返しません。終了直後にモジュールを無効化し、再初期化前に残存ハンドルを処理します。制御したプラグイン試験は Android/iOS 実機の権限、FCM/APNs、反復登録試験を代替しません。
+
 #### ステータスバー
 
 ```ts
@@ -111,7 +117,7 @@ export const ssr = false
 
 ### エラー処理
 
-すべての非同期 API は直接 throw せず、`HaiResult<T>` を返します：
+`capacitor.*` と `safe*Preference` は `HaiResult<T>` を返します。TokenStorage のメソッドはプラットフォームや保存エラーで Promise を reject します。
 
 ```ts
 import { capacitor, HaiCapacitorError } from '@h-ai/capacitor'
@@ -150,6 +156,8 @@ pnpm --filter @h-ai/capacitor test
 
 > ネイティブプラグインへの依存があるため、テストでは `@capacitor/*` モジュールを mock する必要があります。
 
+公開操作、内部リソースと型には型検査できる例があります。[JSDoc 規約（中国語）](../../.agents/instructions/module-conventions.md#jsdoc-与示例验证) を参照してください。型検査は端末権限や FCM/APNs の実配信を保証しません。
+
 ## ライセンス
 
 Apache-2.0

package/README.md

@@ -47,7 +47,11 @@ await apiClient.init({
 })
 ```
 
-`createCapacitorTokenStorage()` 仅在 Android/iOS 原生环境中持久化 token，并要求已安装 `@aparajita/capacitor-secure-storage`。纯 Web 环境下不会退化到 `localStorage`；`get*()` 返回 `null`，`set*()` / `clear()` 为 no-op。
+`createCapacitorTokenStorage()` 仅在 Android/iOS 原生环境中持久化 token，并要求已安装 `@aparajita/capacitor-secure-storage`。适配器的方法直接返回 Promise：Web 调用、插件不可用、读写或删除失败都会拒绝 Promise，不能当作空凭据或保存/退出成功。Web 入口应选择 api-client 的 Cookie/内存存储。
+
+`clear()` 一开始就屏蔽本实例两类旧凭据，并等待所有原生删除结束后才报告结果；失败时保持屏蔽，相应 key 成功写入后才重新开放。通过 `apiClient.auth` 更新凭据以串行提交写入，并处理 `setTokens()` / `clear()` 的拒绝；界面仍须释放 loading、清理退出身份并提示失败。屏蔽只作用于当前适配器实例，不代表持久数据已删除，跨重启撤销依赖服务端退出/撤销会话。插件恢复后可以用同一实例重试，无需重建模块。
+
+任一凭据写入失败都会屏蔽整对凭据，因此 access 已保存而 refresh 保存失败时也不会留下可读的半完成会话。登录/注册保存失败后应尝试 `auth.clear()` 清理部分持久数据；清理再次失败须明确提示，不得声称设备凭据已删除。
 
 #### 设备信息与推送
 
@@ -65,6 +69,8 @@ if (reg.success) {
 }
 ```
 
+推送仅在实际原生平台调用插件。`push.register({ signal? })` 与 `push.listen(callbacks, { signal? })` 的设置阶段限时 30 秒（包含权限和监听器挂载）；失败、超时、取消及 `capacitor.close()` 都会停止回调并移除本次拥有的句柄，迟到的句柄在完成后立即移除，不调用影响其他消费者的 removeAllListeners。listen 成功后信号仍有效，也可调用返回的 cleanup。cleanup 与 close 均返回 `HaiResult<void>`；原生 remove 失败返回 `PUSH_CLEANUP_FAILED`（`capacitor:032`），失败句柄保留供再次调用重试，成功移除的句柄不重复操作。模块关闭后立即不可用；重新初始化前先重试遗留清理。自动化验证控制插件时序，不能代替 Android/iOS 真机 FCM/APNs 权限、注册与反复挂载验收。
+
 #### 状态栏
 
 ```ts
@@ -111,7 +117,7 @@ export const ssr = false
 
 ### 错误处理
 
-所有异步 API 返回 `HaiResult<T>`，不会直接 throw：
+`capacitor.*` 业务操作与 `safe*Preference` 返回 `HaiResult<T>`；TokenStorage 适配器方法以 Promise 拒绝报告平台与存储错误：
 
 ```ts
 import { capacitor, HaiCapacitorError } from '@h-ai/capacitor'
@@ -150,6 +156,8 @@ pnpm --filter @h-ai/capacitor test
 
 > 由于原生插件依赖，测试中需 mock `@capacitor/*` 模块。
 
+公开操作、内部资源作用域与类型均提供可类型检查的示例；见[模块 JSDoc 约定](../../.agents/instructions/module-conventions.md#jsdoc-与示例验证)。推送示例的类型检查不证明设备权限或 FCM/APNs 实际可用。
+
 ## 许可证
 
 Apache-2.0

package/dist/index.d.ts

@@ -2,6 +2,17 @@ import * as _h_ai_core from '@h-ai/core';
 import { HaiResult } from '@h-ai/core';
 import { TokenStorage } from '@h-ai/api-client';
 
+/**
+ * Capacitor 模块的公共错误定义；业务操作通过 HaiResult 返回。
+ * @example
+ * ```ts
+ * import { HaiCapacitorError } from '@h-ai/capacitor'
+ * import { err } from '@h-ai/core'
+ *
+ * const result = err(HaiCapacitorError.NOT_AVAILABLE, 'Native bridge required')
+ * if (!result.success) void result.error.code
+ * ```
+ */
 declare const HaiCapacitorError: {
     readonly INIT_FAILED: _h_ai_core.HaiErrorDef;
     readonly NOT_AVAILABLE: _h_ai_core.HaiErrorDef;
@@ -14,10 +25,24 @@ declare const HaiCapacitorError: {
     readonly APP_VERSION_FAILED: _h_ai_core.HaiErrorDef;
     readonly PUSH_REGISTER_FAILED: _h_ai_core.HaiErrorDef;
     readonly PUSH_LISTEN_FAILED: _h_ai_core.HaiErrorDef;
+    readonly PUSH_CLEANUP_FAILED: _h_ai_core.HaiErrorDef;
     readonly CAMERA_FAILED: _h_ai_core.HaiErrorDef;
     readonly STATUS_BAR_FAILED: _h_ai_core.HaiErrorDef;
 };
-/** 设备信息操作 */
+/**
+ * 设备信息操作
+ * @example
+ * ```ts
+ * import type { DeviceOperations } from '@h-ai/capacitor'
+ *
+ * async function use(operations: DeviceOperations) {
+ *   const result = await operations.getInfo()
+ *   if (!result.success) return result.error.message
+ *   return result.data
+ * }
+ * // 由已初始化的 capacitor.device 提供这些操作。
+ * ```
+ */
 interface DeviceOperations {
     /** 获取设备信息（平台、型号、系统版本等） */
     getInfo: () => Promise<HaiResult<DeviceInfo>>;
@@ -27,19 +52,58 @@ interface DeviceOperations {
         build: string;
     }>>;
 }
-/** 相机操作 */
+/**
+ * 相机操作
+ * @example
+ * ```ts
+ * import type { CameraOperations } from '@h-ai/capacitor'
+ *
+ * async function use(operations: CameraOperations) {
+ *   const result = await operations.takePhoto({ source: 'photos' })
+ *   if (!result.success) return result.error.message
+ *   return result.data
+ * }
+ * // 由已初始化的 capacitor.camera 提供这些操作。
+ * ```
+ */
 interface CameraOperations {
     /** 拍照或选取相册图片 */
     takePhoto: (options?: PhotoOptions) => Promise<HaiResult<PhotoResult>>;
 }
-/** 推送通知操作 */
+/**
+ * 推送通知操作
+ * @example
+ * ```ts
+ * import type { PushOperations } from '@h-ai/capacitor'
+ *
+ * async function use(operations: PushOperations) {
+ *   const result = await operations.register()
+ *   if (!result.success) return result.error.message
+ *   return result.data
+ * }
+ * // 由已初始化的 capacitor.push 提供这些操作。
+ * ```
+ */
 interface PushOperations {
-    /** 注册推送通知，返回设备 Token */
-    register: () => Promise<HaiResult<PushRegistration>>;
-    /** 监听推送通知事件，返回清理函数 */
-    listen: (callbacks: PushNotificationCallbacks) => Promise<HaiResult<() => Promise<void>>>;
+    /** 注册原生 Token；30 秒总超时，可取消，结束时回收监听器。 */
+    register: (options?: PushOptions) => Promise<HaiResult<PushRegistration>>;
+    /** 监听原生事件；设置阶段限时 30 秒，成功后由 cleanup/信号/模块关闭释放。 */
+    listen: (callbacks: PushNotificationCallbacks, options?: PushOptions) => Promise<HaiResult<PushCleanup>>;
 }
-/** 状态栏操作 */
+/**
+ * 状态栏操作
+ * @example
+ * ```ts
+ * import type { StatusBarOperations } from '@h-ai/capacitor'
+ *
+ * async function use(operations: StatusBarOperations) {
+ *   const result = await operations.configure({ style: 'dark' })
+ *   if (!result.success) return result.error.message
+ *   return result.data
+ * }
+ * // 由已初始化的 capacitor.statusBar 提供这些操作。
+ * ```
+ */
 interface StatusBarOperations {
     /** 配置状态栏（样式、背景色、沉浸式） */
     configure: (config: StatusBarConfig) => Promise<HaiResult<void>>;
@@ -48,7 +112,20 @@ interface StatusBarOperations {
     /** 隐藏状态栏 */
     hide: () => Promise<HaiResult<void>>;
 }
-/** Preferences 操作（安全读写，返回 HaiResult） */
+/**
+ * Preferences 操作（安全读写，返回 HaiResult）
+ * @example
+ * ```ts
+ * import type { PreferencesOperations } from '@h-ai/capacitor'
+ *
+ * async function use(operations: PreferencesOperations) {
+ *   const result = await operations.get('theme')
+ *   if (!result.success) return result.error.message
+ *   return result.data
+ * }
+ * // 由已初始化的 capacitor.preferences 提供这些操作。
+ * ```
+ */
 interface PreferencesOperations {
     /** 安全读取 Preference 值 */
     get: (key: string) => Promise<HaiResult<string | null>>;
@@ -57,12 +134,29 @@ interface PreferencesOperations {
     /** 安全删除 Preference 值 */
     remove: (key: string) => Promise<HaiResult<void>>;
 }
-/** Capacitor 模块服务对象接口 */
+/**
+ * Capacitor 模块服务对象接口
+ * @example
+ * ```ts
+ * import { capacitor } from '@h-ai/capacitor'
+ *
+ * const initialized = await capacitor.init()
+ * if (!initialized.success) throw new Error(initialized.error.message)
+ * try {
+ *   const result = await capacitor.device.getInfo()
+ *   if (!result.success) throw new Error(result.error.message)
+ *   void result.data
+ * } finally {
+ *   const closed = await capacitor.close()
+ *   if (!closed.success) throw new Error(closed.error.message)
+ * }
+ * ```
+ */
 interface CapacitorFunctions {
     /** 初始化 Capacitor 模块 */
     init: () => Promise<HaiResult<void>>;
-    /** 关闭模块，重置状态 */
-    close: () => Promise<void>;
+    /** 关闭模块并回收推送监听；失败时保持不可用，保留句柄供再次 close 重试。 */
+    close: () => Promise<HaiResult<void>>;
     /** 获取当前平台 */
     getPlatform: () => string;
     /** 是否运行在原生 App 中 */
@@ -80,9 +174,27 @@ interface CapacitorFunctions {
     /** Preferences 安全读写操作 */
     readonly preferences: PreferencesOperations;
 }
-/** 设备平台 */
+/**
+ * 设备平台
+ * @example
+ * ```ts
+ * import type { DevicePlatform } from '@h-ai/capacitor'
+ *
+ * const value: DevicePlatform = 'android'
+ * void value
+ * ```
+ */
 type DevicePlatform = 'ios' | 'android' | 'web';
-/** 设备信息 */
+/**
+ * 设备信息
+ * @example
+ * ```ts
+ * import type { DeviceInfo } from '@h-ai/capacitor'
+ *
+ * const value: DeviceInfo = { platform: 'android', osVersion: '15', model: 'Example device', manufacturer: 'Example', isVirtual: false }
+ * void value
+ * ```
+ */
 interface DeviceInfo {
     /** 平台（ios / android / web） */
     platform: DevicePlatform;
@@ -99,7 +211,44 @@ interface DeviceInfo {
     /** 应用 Build 号 */
     appBuild?: string;
 }
-/** 推送通知数据 */
+/**
+ * 推送流程的取消选项；listen 成功后信号仍可终止监听。
+ * @example
+ * ```ts
+ * import type { PushOptions } from '@h-ai/capacitor'
+ *
+ * const value: PushOptions = { signal: new AbortController().signal }
+ * void value
+ * ```
+ */
+interface PushOptions {
+    /** 取消当前注册或监听，不影响其他消费者拥有的句柄。 */
+    signal?: AbortSignal;
+}
+/**
+ * 幂等推送清理函数；原生 remove 失败返回错误，调用同一函数可重试。
+ * @example
+ * ```ts
+ * import type { PushCleanup } from '@h-ai/capacitor'
+ *
+ * async function release(cleanup: PushCleanup) {
+ *   const result = await cleanup()
+ *   if (!result.success) return cleanup() // 同一所有权句柄允许重试清理。
+ *   return result
+ * }
+ * ```
+ */
+type PushCleanup = () => Promise<HaiResult<void>>;
+/**
+ * 推送通知数据
+ * @example
+ * ```ts
+ * import type { PushNotification } from '@h-ai/capacitor'
+ *
+ * const value: PushNotification = { id: 'notice_1', title: 'Order ready', data: { orderId: 'order_1' } }
+ * void value
+ * ```
+ */
 interface PushNotification {
     /** 通知 ID */
     id: string;
@@ -110,21 +259,57 @@ interface PushNotification {
     /** 附加数据 */
     data?: Record<string, unknown>;
 }
-/** 推送注册结果 */
+/**
+ * 推送注册结果
+ * @example
+ * ```ts
+ * import type { PushRegistration } from '@h-ai/capacitor'
+ *
+ * const value: PushRegistration = { token: 'example-only-native-token' }
+ * void value
+ * ```
+ */
 interface PushRegistration {
     /** 设备推送 Token */
     token: string;
 }
-/** 推送通知回调 */
+/**
+ * 推送通知回调
+ * @example
+ * ```ts
+ * import type { PushNotificationCallbacks } from '@h-ai/capacitor'
+ *
+ * const value: PushNotificationCallbacks = { onReceived: notification => { document.title = notification.title ?? 'Notice' } }
+ * void value
+ * ```
+ */
 interface PushNotificationCallbacks {
     /** 收到推送时调用 */
     onReceived?: (notification: PushNotification) => void;
     /** 用户点击推送时调用 */
     onActionPerformed?: (notification: PushNotification) => void;
 }
-/** 照片来源 */
+/**
+ * 照片来源
+ * @example
+ * ```ts
+ * import type { PhotoSource } from '@h-ai/capacitor'
+ *
+ * const value: PhotoSource = 'photos'
+ * void value
+ * ```
+ */
 type PhotoSource = 'camera' | 'photos' | 'prompt';
-/** 照片选项 */
+/**
+ * 照片选项
+ * @example
+ * ```ts
+ * import type { PhotoOptions } from '@h-ai/capacitor'
+ *
+ * const value: PhotoOptions = { source: 'photos', resultType: 'uri', quality: 90, width: 1200 }
+ * void value
+ * ```
+ */
 interface PhotoOptions {
     /** 来源（默认 'prompt'） */
     source?: PhotoSource;
@@ -137,16 +322,43 @@ interface PhotoOptions {
     /** 返回格式 */
     resultType?: 'uri' | 'base64' | 'dataUrl';
 }
-/** 照片结果 */
+/**
+ * 照片结果
+ * @example
+ * ```ts
+ * import type { PhotoResult } from '@h-ai/capacitor'
+ *
+ * const value: PhotoResult = { data: 'file:///example/photo.jpeg', format: 'jpeg' }
+ * void value
+ * ```
+ */
 interface PhotoResult {
     /** 图片路径或 base64 数据 */
     data: string;
-    /** MIME 类型 */
+    /** 原生插件返回的格式扩展名（如 jpeg），不是 MIME 类型 */
     format: string;
 }
-/** 状态栏样式 */
+/**
+ * 状态栏样式
+ * @example
+ * ```ts
+ * import type { StatusBarStyle } from '@h-ai/capacitor'
+ *
+ * const value: StatusBarStyle = 'dark'
+ * void value
+ * ```
+ */
 type StatusBarStyle = 'dark' | 'light' | 'default';
-/** 状态栏配置 */
+/**
+ * 状态栏配置
+ * @example
+ * ```ts
+ * import type { StatusBarConfig } from '@h-ai/capacitor'
+ *
+ * const value: StatusBarConfig = { style: 'dark', overlay: false }
+ * void value
+ * ```
+ */
 interface StatusBarConfig {
     /** 状态栏文字样式 */
     style?: StatusBarStyle;
@@ -167,15 +379,19 @@ interface StatusBarConfig {
 
 /**
  * Capacitor 模块服务对象
- *
  * @example
  * ```ts
  * import { capacitor } from '@h-ai/capacitor'
  *
- * const result = await capacitor.init()
- * if (result.success) {
- *   const info = await capacitor.device.getInfo()
- *   await capacitor.statusBar.configure({ style: 'dark', overlay: true })
+ * const initialized = await capacitor.init()
+ * if (!initialized.success) throw new Error(initialized.error.message)
+ * try {
+ *   const result = await capacitor.device.getInfo()
+ *   if (!result.success) throw new Error(result.error.message)
+ *   void result.data
+ * } finally {
+ *   const closed = await capacitor.close()
+ *   if (!closed.success) throw new Error(closed.error.message)
  * }
  * ```
  */
@@ -194,22 +410,26 @@ declare const capacitor: CapacitorFunctions;
  * 创建基于原生安全存储的 TokenStorage
  *
  * 在原生 Android/iOS 环境下使用 `@aparajita/capacitor-secure-storage`
- * 保存 access token / refresh token；Web 环境不做不安全回退。
+ * 保存 access token / refresh token。所有方法的存储/平台错误均通过 Promise 拒绝传播，
+ * Web 调用明确失败，不做存储回退或伪成功。
+ * `clear()` 一开始即屏蔽本实例旧凭据，删除失败时仍保持屏蔽；相应 key 成功写入后恢复读取。
+ * 任一凭据写入失败也会屏蔽整对凭据，避免 access 已保存、refresh 失败时暴露半完成登录。
+ * 本实例屏蔽不代表原生持久数据已删除；跨重启撤销仍依赖服务端退出/撤销会话。
  *
  * @returns TokenStorage 实例
- *
+ * @throws 返回适配器的方法在插件不可用或原生存储失败时拒绝 Promise。
  * @example
  * ```ts
  * import { createCapacitorTokenStorage } from '@h-ai/capacitor'
- * import { apiClient } from '@h-ai/api-client'
- *
- * await apiClient.init({
- *   baseUrl: 'https://api.example.com/v1',
- *   auth: {
- *     storage: createCapacitorTokenStorage(),
- *     refreshPath: '/auth/refresh',
- *   },
- * })
+ *
+ * const storage = createCapacitorTokenStorage()
+ * try {
+ *   const token = await storage.getAccessToken()
+ *   void token // 仅原生安全存储；平台或存储失败会拒绝 Promise。
+ * } catch (cause) {
+ *   // 应阻止认证流程继续并呈现本地化错误；不回退到普通 Preferences。
+ *   void cause
+ * }
  * ```
  */
 declare function createCapacitorTokenStorage(): TokenStorage;
@@ -218,12 +438,19 @@ declare function createCapacitorTokenStorage(): TokenStorage;
  *
  * @param key - Preference Key
  * @returns HaiResult 包裹的值
- *
  * @example
  * ```ts
- * const result = await capacitor.preferences.get('my_key')
- * if (result.success) {
- *   result.data // 值或 null
+ * import { capacitor } from '@h-ai/capacitor'
+ *
+ * const initialized = await capacitor.init()
+ * if (!initialized.success) throw new Error(initialized.error.message)
+ * try {
+ *   const result = await capacitor.preferences.get('theme')
+ *   if (!result.success) throw new Error(result.error.message)
+ *   void result.data
+ * } finally {
+ *   const closed = await capacitor.close()
+ *   if (!closed.success) throw new Error(closed.error.message)
  * }
  * ```
  */
@@ -234,10 +461,20 @@ declare function safeGetPreference(key: string): Promise<HaiResult<string | null
  * @param key - Preference Key
  * @param value - 要写入的值
  * @returns HaiResult
- *
  * @example
  * ```ts
- * await capacitor.preferences.set('my_key', 'value')
+ * import { capacitor } from '@h-ai/capacitor'
+ *
+ * const initialized = await capacitor.init()
+ * if (!initialized.success) throw new Error(initialized.error.message)
+ * try {
+ *   const result = await capacitor.preferences.set('theme', 'dark')
+ *   if (!result.success) throw new Error(result.error.message)
+ *   void result.data
+ * } finally {
+ *   const closed = await capacitor.close()
+ *   if (!closed.success) throw new Error(closed.error.message)
+ * }
  * ```
  */
 declare function safeSetPreference(key: string, value: string): Promise<HaiResult<void>>;
@@ -246,12 +483,22 @@ declare function safeSetPreference(key: string, value: string): Promise<HaiResul
  *
  * @param key - Preference Key
  * @returns HaiResult
- *
  * @example
  * ```ts
- * await capacitor.preferences.remove('my_key')
+ * import { capacitor } from '@h-ai/capacitor'
+ *
+ * const initialized = await capacitor.init()
+ * if (!initialized.success) throw new Error(initialized.error.message)
+ * try {
+ *   const result = await capacitor.preferences.remove('theme')
+ *   if (!result.success) throw new Error(result.error.message)
+ *   void result.data
+ * } finally {
+ *   const closed = await capacitor.close()
+ *   if (!closed.success) throw new Error(closed.error.message)
+ * }
  * ```
  */
 declare function safeRemovePreference(key: string): Promise<HaiResult<void>>;
 
-export { type CameraOperations, type CapacitorFunctions, type DeviceInfo, type DeviceOperations, type DevicePlatform, HaiCapacitorError, type PhotoOptions, type PhotoResult, type PhotoSource, type PreferencesOperations, type PushNotification, type PushNotificationCallbacks, type PushOperations, type PushRegistration, type StatusBarConfig, type StatusBarOperations, type StatusBarStyle, capacitor, createCapacitorTokenStorage, safeGetPreference, safeRemovePreference, safeSetPreference };
+export { type CameraOperations, type CapacitorFunctions, type DeviceInfo, type DeviceOperations, type DevicePlatform, HaiCapacitorError, type PhotoOptions, type PhotoResult, type PhotoSource, type PreferencesOperations, type PushCleanup, type PushNotification, type PushNotificationCallbacks, type PushOperations, type PushOptions, type PushRegistration, type StatusBarConfig, type StatusBarOperations, type StatusBarStyle, capacitor, createCapacitorTokenStorage, safeGetPreference, safeRemovePreference, safeSetPreference };