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

package/README.en.md

@@ -4,9 +4,11 @@
 
 [Framework home](../../README.en.md) · Related modules: [@h-ai/api-client](../api-client/README.en.md) · [@h-ai/core](../core/README.en.md)
 
+## Introduction
+
 A Capacitor native bridge for hai Framework mobile apps, with a unified API for secure token storage, device information, push notifications, camera, and status bar access.
 
-## Capabilities
+## Core features
 
 - **Token storage**: `@aparajita/capacitor-secure-storage` (required on native platforms). Android uses KeyStore + encrypted SharedPreferences; iOS uses Keychain. No Web fallback.
 - **Preferences**: `@capacitor/preferences` (required). General preferences storage for nonsensitive settings, not authentication tokens.
@@ -16,7 +18,9 @@ A Capacitor native bridge for hai Framework mobile apps, with a unified API for
 - **Camera/gallery**: `@capacitor/camera` (optional). Capture photos or select gallery images.
 - **Status bar**: `@capacitor/status-bar` (optional). Immersive mode, background color, and style settings.
 
-## Quick start
+## Getting started
+
+### Quick start
 
 ```ts
 import { capacitor } from '@h-ai/capacitor'
@@ -28,7 +32,7 @@ if (!result.success) {
 }
 ```
 
-### Secure token storage with api-client
+#### Secure token storage with api-client
 
 ```ts
 import { apiClient } from '@h-ai/api-client'
@@ -43,9 +47,13 @@ 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.
 
-### Device information and push notifications
+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
 
 ```ts
 import { capacitor } from '@h-ai/capacitor'
@@ -61,7 +69,9 @@ if (reg.success) {
 }
 ```
 
-### Status bar
+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
 import { capacitor } from '@h-ai/capacitor'
@@ -73,7 +83,7 @@ await capacitor.statusBar.configure({
 })
 ```
 
-### Camera
+#### Camera
 
 ```ts
 const photo = await capacitor.camera.takePhoto({
@@ -83,7 +93,7 @@ const photo = await capacitor.camera.takePhoto({
 })
 ```
 
-### Preferences
+#### Preferences
 
 ```ts
 await capacitor.preferences.set('my_key', 'value')
@@ -93,7 +103,7 @@ await capacitor.preferences.remove('my_key')
 
 `capacitor.preferences` is for general preferences such as language, theme, and drafts. Use `createCapacitorTokenStorage()` for authentication tokens.
 
-## Configuration
+### Configuration
 
 This module has no configuration file. `capacitor.init()` only checks whether the Capacitor runtime is available.
 
@@ -105,9 +115,9 @@ export const prerender = true
 export const ssr = false
 ```
 
-## Error handling
+### 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'
@@ -138,7 +148,7 @@ Common error codes:
 | `HaiCapacitorError.CAMERA_FAILED`             | `hai:capacitor:040` | Camera operation failed             |
 | `HaiCapacitorError.STATUS_BAR_FAILED`         | `hai:capacitor:050` | Status bar operation failed         |
 
-## Tests
+## Development and testing
 
 ```bash
 pnpm --filter @h-ai/capacitor test
@@ -146,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

@@ -4,6 +4,8 @@
 
 [フレームワークのホーム](../../README.ja.md) · 関連モジュール：[@h-ai/api-client](../api-client/README.ja.md) · [@h-ai/core](../core/README.ja.md)
 
+## 概要
+
 hai Framework のモバイルアプリ向け Capacitor ネイティブブリッジ。安全な Token ストレージ、端末情報、プッシュ通知、カメラ、ステータスバーを共通 API で提供します。
 
 ## 主な機能
@@ -16,7 +18,9 @@ hai Framework のモバイルアプリ向け Capacitor ネイティブブリッ
 - **カメラ/アルバム**：`@capacitor/camera`（任意）。撮影とアルバム画像の選択。
 - **ステータスバー**：`@capacitor/status-bar`（任意）。没入型表示、背景色、スタイルの設定。
 
-## クイックスタート
+## 使い始める
+
+### クイックスタート
 
 ```ts
 import { capacitor } from '@h-ai/capacitor'
@@ -28,7 +32,7 @@ if (!result.success) {
 }
 ```
 
-### api-client と連携する安全な Token ストレージ
+#### api-client と連携する安全な Token ストレージ
 
 ```ts
 import { apiClient } from '@h-ai/api-client'
@@ -43,9 +47,13 @@ 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()` で部分保存データの削除を試み、削除も失敗した場合は端末の認証情報を削除できたと表示しないでください。
+
+#### 端末情報とプッシュ通知
 
 ```ts
 import { capacitor } from '@h-ai/capacitor'
@@ -61,7 +69,9 @@ 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
 import { capacitor } from '@h-ai/capacitor'
@@ -73,7 +83,7 @@ await capacitor.statusBar.configure({
 })
 ```
 
-### カメラ
+#### カメラ
 
 ```ts
 const photo = await capacitor.camera.takePhoto({
@@ -83,7 +93,7 @@ const photo = await capacitor.camera.takePhoto({
 })
 ```
 
-### Preferences
+#### Preferences
 
 ```ts
 await capacitor.preferences.set('my_key', 'value')
@@ -93,7 +103,7 @@ await capacitor.preferences.remove('my_key')
 
 `capacitor.preferences` は言語、テーマ、下書きなどの一般的な設定用です。認証 Token には `createCapacitorTokenStorage()` を使用してください。
 
-## 設定
+### 設定
 
 このモジュールに設定ファイルはありません。`capacitor.init()` は Capacitor の実行環境が利用可能かどうかのみを確認します。
 
@@ -105,9 +115,9 @@ export const prerender = true
 export const ssr = false
 ```
 
-## エラー処理
+### エラー処理
 
-すべての非同期 API は直接 throw せず、`HaiResult<T>` を返します：
+`capacitor.*` と `safe*Preference` は `HaiResult<T>` を返します。TokenStorage のメソッドはプラットフォームや保存エラーで Promise を reject します。
 
 ```ts
 import { capacitor, HaiCapacitorError } from '@h-ai/capacitor'
@@ -138,7 +148,7 @@ if (!result.success) {
 | `HaiCapacitorError.CAMERA_FAILED`             | `hai:capacitor:040` | カメラ操作に失敗             |
 | `HaiCapacitorError.STATUS_BAR_FAILED`         | `hai:capacitor:050` | ステータスバー操作に失敗     |
 
-## テスト
+## 開発とテスト
 
 ```bash
 pnpm --filter @h-ai/capacitor test
@@ -146,6 +156,8 @@ pnpm --filter @h-ai/capacitor test
 
 > ネイティブプラグインへの依存があるため、テストでは `@capacitor/*` モジュールを mock する必要があります。
 
-## License
+公開操作、内部リソースと型には型検査できる例があります。[JSDoc 規約（中国語）](../../.agents/instructions/module-conventions.md#jsdoc-与示例验证) を参照してください。型検査は端末権限や FCM/APNs の実配信を保証しません。
+
+## ライセンス
 
 Apache-2.0

package/README.md

@@ -4,9 +4,11 @@
 
 [框架首页](../../README.md) · 相关模块：[@h-ai/api-client](../api-client/README.md) · [@h-ai/core](../core/README.md)
 
+## 简介
+
 Capacitor 原生桥接模块，为 hai Framework 移动应用提供原生安全 Token 存储、设备信息、推送通知、相机与状态栏等能力的统一封装。
 
-## 支持的能力
+## 核心功能清单
 
 - **Token 存储**：`@aparajita/capacitor-secure-storage`（原生必需）。Android 使用 KeyStore + 加密 SharedPreferences，iOS 使用 Keychain；Web 不回退。
 - **Preferences**：`@capacitor/preferences`（必需）。通用偏好数据存储，适合非敏感配置，不用于认证 Token。
@@ -16,7 +18,9 @@ Capacitor 原生桥接模块，为 hai Framework 移动应用提供原生安全
 - **相机/相册**：`@capacitor/camera`（可选）。拍照、选取相册图片。
 - **状态栏**：`@capacitor/status-bar`（可选）。沉浸式、背景色、样式配置。
 
-## 快速开始
+## 使用入门
+
+### 快速开始
 
 ```ts
 import { capacitor } from '@h-ai/capacitor'
@@ -28,7 +32,7 @@ if (!result.success) {
 }
 ```
 
-### 与 api-client 配合的 Token 安全存储
+#### 与 api-client 配合的 Token 安全存储
 
 ```ts
 import { apiClient } from '@h-ai/api-client'
@@ -43,9 +47,13 @@ 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()` 清理部分持久数据；清理再次失败须明确提示，不得声称设备凭据已删除。
+
+#### 设备信息与推送
 
 ```ts
 import { capacitor } from '@h-ai/capacitor'
@@ -61,7 +69,9 @@ 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
 import { capacitor } from '@h-ai/capacitor'
@@ -73,7 +83,7 @@ await capacitor.statusBar.configure({
 })
 ```
 
-### 相机
+#### 相机
 
 ```ts
 const photo = await capacitor.camera.takePhoto({
@@ -83,7 +93,7 @@ const photo = await capacitor.camera.takePhoto({
 })
 ```
 
-### Preferences
+#### Preferences
 
 ```ts
 await capacitor.preferences.set('my_key', 'value')
@@ -93,7 +103,7 @@ await capacitor.preferences.remove('my_key')
 
 `capacitor.preferences` 适合保存语言、主题、草稿等普通偏好数据；认证 Token 请使用 `createCapacitorTokenStorage()`。
 
-## 配置
+### 配置
 
 本模块无配置文件。`capacitor.init()` 仅检测 Capacitor 运行环境是否可用。
 
@@ -105,9 +115,9 @@ export const prerender = true
 export const ssr = false
 ```
 
-## 错误处理
+### 错误处理
 
-所有异步 API 返回 `HaiResult<T>`，不会直接 throw：
+`capacitor.*` 业务操作与 `safe*Preference` 返回 `HaiResult<T>`；TokenStorage 适配器方法以 Promise 拒绝报告平台与存储错误：
 
 ```ts
 import { capacitor, HaiCapacitorError } from '@h-ai/capacitor'
@@ -138,7 +148,7 @@ if (!result.success) {
 | `HaiCapacitorError.CAMERA_FAILED`             | `hai:capacitor:040` | 相机操作失败         |
 | `HaiCapacitorError.STATUS_BAR_FAILED`         | `hai:capacitor:050` | 状态栏操作失败       |
 
-## 测试
+## 开发测试
 
 ```bash
 pnpm --filter @h-ai/capacitor test
@@ -146,6 +156,8 @@ pnpm --filter @h-ai/capacitor test
 
 > 由于原生插件依赖，测试中需 mock `@capacitor/*` 模块。
 
-## License
+公开操作、内部资源作用域与类型均提供可类型检查的示例；见[模块 JSDoc 约定](../../.agents/instructions/module-conventions.md#jsdoc-与示例验证)。推送示例的类型检查不证明设备权限或 FCM/APNs 实际可用。
+
+## 许可证
 
 Apache-2.0