@h-ai/capacitor 0.1.0-alpha8 → 1.0.0-beta.1

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;
@@ -11,12 +22,27 @@ declare const HaiCapacitorError: {
     readonly PREFERENCES_SET_FAILED: _h_ai_core.HaiErrorDef;
     readonly PREFERENCES_REMOVE_FAILED: _h_ai_core.HaiErrorDef;
     readonly DEVICE_INFO_FAILED: _h_ai_core.HaiErrorDef;
+    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>>;
@@ -26,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>>;
@@ -47,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>>;
@@ -56,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 中 */
@@ -79,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;
@@ -98,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;
@@ -109,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;
@@ -136,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;
@@ -166,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)
  * }
  * ```
  */
@@ -183,33 +400,36 @@ declare const capacitor: CapacitorFunctions;
 /**
  * @h-ai/capacitor — Token 存储
  *
- * 基于 Capacitor Preferences 的 TokenStorage 实现，
- * 比浏览器 localStorage 更安全，适用于原生 App 场景。
+ * 基于原生安全存储插件的 TokenStorage 实现。
+ * 仅在 Capacitor 原生环境启用，拒绝回退到不安全的 Web 存储。
  *
  * @module capacitor-token-storage
  */
 
 /**
- * 创建基于 Capacitor Preferences 的 TokenStorage
+ * 创建基于原生安全存储的 TokenStorage
  *
- * 使用 `@capacitor/preferences` 插件进行持久化存储，
- * 在 Android 使用 SharedPreferences，iOS 使用 UserDefaults，
- * 比 localStorage 有更好的安全性。
+ * 在原生 Android/iOS 环境下使用 `@aparajita/capacitor-secure-storage`
+ * 保存 access token / refresh token。所有方法的存储/平台错误均通过 Promise 拒绝传播，
+ * Web 调用明确失败，不做存储回退或伪成功。
+ * `clear()` 一开始即屏蔽本实例旧凭据，删除失败时仍保持屏蔽；相应 key 成功写入后恢复读取。
+ * 任一凭据写入失败也会屏蔽整对凭据，避免 access 已保存、refresh 失败时暴露半完成登录。
+ * 本实例屏蔽不代表原生持久数据已删除；跨重启撤销仍依赖服务端退出/撤销会话。
  *
  * @returns TokenStorage 实例
- *
+ * @throws 返回适配器的方法在插件不可用或原生存储失败时拒绝 Promise。
  * @example
  * ```ts
  * import { createCapacitorTokenStorage } from '@h-ai/capacitor'
- * import { api } from '@h-ai/api-client'
- *
- * await api.init({
- *   baseUrl: 'https://api.example.com/v1',
- *   auth: {
- *     storage: createCapacitorTokenStorage(),
- *     refreshUrl: '/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 };