@h-ai/api-client 0.1.0-alpha.65 → 0.1.0-alpha.67

package/README.en.md

@@ -4,9 +4,11 @@
 
 [Framework home](../../README.en.md) · Related modules: [@h-ai/api-contract](../api-contract/README.en.md) · [@h-ai/core](../core/README.en.md) · [@h-ai/crypto](../crypto/README.en.md)
 
-> A cross-platform oRPC/OpenAPI typed client for hai-framework, with consistent API calls and token management across Web, apps, and mini programs.
+## Introduction
 
-## Capabilities
+A cross-platform oRPC/OpenAPI typed client for hai-framework, with consistent API calls and token management across Web, apps, and mini programs.
+
+## Core features
 
 - `apiClient`: the default typed client for the iam/storage/ai domains.
 - `apiClient.create(contract)`: create a typed client for a custom contract.
@@ -17,7 +19,9 @@
 - Optional transport encryption: `apiClient.init({ transport: { crypto } })` automatically uses `crypto.transport.createClient()`.
 - Transport encryption and automatic refresh can run together: `/auth/refresh` after a 401 still uses encrypted fetch without falling back to plaintext.
 
-## Quick start
+## Getting started
+
+### Quick start
 
 ```ts
 import { apiClient } from '@h-ai/api-client'
@@ -47,7 +51,7 @@ if (me.success) {
 await apiClient.close()
 ```
 
-### Enable transport encryption
+#### Enable transport encryption
 
 First enable `serv.createApp({ transport: { crypto } })` on the server. The client only needs the same `@h-ai/crypto` service instance; no manual key exchange code is required.
 
@@ -67,7 +71,7 @@ await apiClient.close()
 await crypto.close()
 ```
 
-## API contracts
+### API contracts
 
 Custom applications can bind their own oRPC contract:
 
@@ -82,7 +86,7 @@ await client.init({ baseUrl: 'https://api.example.com/api/v1' })
 const result = await client.iam.auth.login({ identifier: 'alice', password: 'secret' })
 ```
 
-## API overview
+### API overview
 
 - `apiClient.init(config)`: initialize the default client.
 - `apiClient.close()`: clear client state.
@@ -92,7 +96,7 @@ const result = await client.iam.auth.login({ identifier: 'alice', password: 'sec
 
 Calling `init()` on an initialized client returns `CONFIG_ERROR` and leaves the existing client intact. To change `baseUrl` / `fetch` / `transport`, call `await apiClient.close()` before initializing again.
 
-## Configuration
+### Configuration
 
 - `baseUrl`: API base URL, usually including `/api/v1`.
 - `auth.storage`: token storage adapter; defaults to `apiClient.tokenStorage.httpOnlyCookie()` (recommended for browsers). Explicitly use `apiClient.tokenStorage.memory()` for SSR / tests.
@@ -104,7 +108,7 @@ Calling `init()` on an initialized client returns `CONFIG_ERROR` and leaves the
 - `transport.keyExchangePath`: key exchange subpath; defaults to `/_hai/key-exchange` and is appended to `baseUrl` automatically.
 - `apiClient.config`: a **redacted snapshot of runtime configuration**; credentials embedded in `baseUrl`, `headers.authorization`, and other sensitive values are hidden automatically.
 
-## Configuration driven authentication
+### Configuration driven authentication
 
 Agreements support configuration-loaded userAgreementMarkdown/privacyPolicyMarkdown and URLs. Markdown takes priority for the same agreement and is safely rendered in a modal.
 
@@ -112,7 +116,7 @@ apiClient.createAuthActions(client) supplies publicConfig, login, register, send
 
 [完整 IAM 配置 / IAM configuration](../iam/README.en.md)
 
-## Error handling
+### Error handling
 
 Business APIs return `HaiResult<T>`:
 
@@ -130,7 +134,7 @@ Client-side failures such as missing initialization, network errors, timeouts, a
 
 Automatic refresh handles an actual HTTP 401 (`Response.status`) or a valid failed HaiResult over HTTP 200 (`success=false`, string `error.code/message` and `error.httpStatus=401`). After a successful refresh, the original request is retried once. Built-in login and registration routes and the configured `auth.refreshPath` never trigger automatic refresh; other failures such as 403/500 do not trigger it either. Ordinary serv procedures still return HTTP 200. Callers must check the final `success` and `error.code` and handle expired authentication when refresh fails.
 
-## Tests
+## Development and testing
 
 ```bash
 pnpm --filter @h-ai/api-client test

package/README.ja.md

@@ -4,9 +4,11 @@
 
 [フレームワークのホーム](../../README.ja.md) · 関連モジュール：[@h-ai/api-contract](../api-contract/README.ja.md) · [@h-ai/core](../core/README.ja.md) · [@h-ai/crypto](../crypto/README.ja.md)
 
-> hai-framework のクロスプラットフォーム oRPC/OpenAPI 型付きクライアント。Web、アプリ、ミニプログラムに共通の API 呼び出しと Token 管理を提供します。
+## 概要
 
-## 機能概要
+hai-framework のクロスプラットフォーム oRPC/OpenAPI 型付きクライアント。Web、アプリ、ミニプログラムに共通の API 呼び出しと Token 管理を提供します。
+
+## 主な機能
 
 - `apiClient`：iam/storage/ai ドメインに対応する既定の型付きクライアント。
 - `apiClient.create(contract)`：独自の contract に対応する型付きクライアントを作成。
@@ -17,7 +19,9 @@
 - 任意の通信暗号化：`apiClient.init({ transport: { crypto } })` が `crypto.transport.createClient()` を自動使用。
 - 通信暗号化と自動更新を併用可能。401 後の `/auth/refresh` も暗号化された fetch を使用し、平文には切り替わりません。
 
-## クイックスタート
+## 使い始める
+
+### クイックスタート
 
 ```ts
 import { apiClient } from '@h-ai/api-client'
@@ -47,7 +51,7 @@ if (me.success) {
 await apiClient.close()
 ```
 
-### 通信暗号化の有効化
+#### 通信暗号化の有効化
 
 サーバーで先に `serv.createApp({ transport: { crypto } })` を有効にします。クライアントには同じ `@h-ai/crypto` サービスのインスタンスを渡すだけで、鍵交換コードの実装は不要です。
 
@@ -67,7 +71,7 @@ await apiClient.close()
 await crypto.close()
 ```
 
-## API 契約
+### API 契約
 
 独自のアプリケーションでは、専用の oRPC contract を指定できます：
 
@@ -82,7 +86,7 @@ await client.init({ baseUrl: 'https://api.example.com/api/v1' })
 const result = await client.iam.auth.login({ identifier: 'alice', password: 'secret' })
 ```
 
-## API 一覧
+### API 一覧
 
 - `apiClient.init(config)`：既定のクライアントを初期化。
 - `apiClient.close()`：クライアントの状態を解放。
@@ -92,7 +96,7 @@ const result = await client.iam.auth.login({ identifier: 'alice', password: 'sec
 
 初期化済みのクライアントで `init()` を再度呼ぶと `CONFIG_ERROR` が返り、既存のクライアントは維持されます。`baseUrl` / `fetch` / `transport` を変更する場合は、先に `await apiClient.close()` を呼んでから再初期化してください。
 
-## 設定
+### 設定
 
 - `baseUrl`：API のベース URL。通常は `/api/v1` を含みます。
 - `auth.storage`：Token ストレージアダプター。既定は `apiClient.tokenStorage.httpOnlyCookie()`（ブラウザー推奨）。SSR / テストでは `apiClient.tokenStorage.memory()` を明示してください。
@@ -104,7 +108,7 @@ const result = await client.iam.auth.login({ identifier: 'alice', password: 'sec
 - `transport.keyExchangePath`：鍵交換のサブパス。既定は `/_hai/key-exchange` で、`baseUrl` に自動的に連結されます。
 - `apiClient.config`：**機密情報をマスクした実行時設定のスナップショット**。`baseUrl` 内の認証情報や `headers.authorization` などの機密値は自動的に非表示になります。
 
-## 設定による認証画面
+### 設定による認証画面
 
 規約は設定の userAgreementMarkdown/privacyPolicyMarkdown または URL を使用できます。同じ規約は Markdown 本文を優先して安全な Modal で描画します。
 
@@ -112,7 +116,7 @@ const result = await client.iam.auth.login({ identifier: 'alice', password: 'sec
 
 [完整 IAM 配置 / IAM configuration](../iam/README.ja.md)
 
-## エラー処理
+### エラー処理
 
 業務 API は `HaiResult<T>` を返します：
 
@@ -130,13 +134,13 @@ else {
 
 自動更新は実際の HTTP 401（`Response.status`）、または HTTP 200 の有効な失敗 HaiResult（`success=false`、文字列の `error.code/message`、`error.httpStatus=401`）で動作します。更新が成功すると元のリクエストを一度だけ再試行します。組み込みのログイン・登録と設定された `auth.refreshPath` は自動更新の対象外で、403/500 など他の失敗でも更新しません。serv の通常の procedure は引き続き HTTP 200 を返します。呼び出し側は最終結果の `success` と `error.code` を確認し、更新失敗による認証失効を処理してください。
 
-## テスト
+## 開発とテスト
 
 ```bash
 pnpm --filter @h-ai/api-client test
 pnpm --filter @h-ai/api-client typecheck
 ```
 
-## License
+## ライセンス
 
 Apache-2.0

package/README.md

@@ -4,9 +4,11 @@
 
 [框架首页](../../README.md) · 相关模块：[@h-ai/api-contract](../api-contract/README.md) · [@h-ai/core](../core/README.md) · [@h-ai/crypto](../crypto/README.md)
 
-> hai-framework 的跨端 oRPC/OpenAPI typed client，面向 Web、App、小程序等运行时提供统一 API 调用与 Token 管理。
+## 简介
 
-## 能力概览
+hai-framework 的跨端 oRPC/OpenAPI typed client，面向 Web、App、小程序等运行时提供统一 API 调用与 Token 管理。
+
+## 核心功能清单
 
 - `apiClient`：默认绑定 iam/storage/ai 领域的统一 typed client 入口。
 - `apiClient.create(contract)`：为自定义 contract 创建 typed client。
@@ -17,7 +19,9 @@
 - 可选传输加密：`apiClient.init({ transport: { crypto } })` 自动使用 `crypto.transport.createClient()`。
 - 传输加密与自动刷新可同时启用：401 后的 `/auth/refresh` 会继续走 encrypted fetch，不降级明文。
 
-## 快速开始
+## 使用入门
+
+### 快速开始
 
 ```ts
 import { apiClient } from '@h-ai/api-client'
@@ -47,7 +51,7 @@ if (me.success) {
 await apiClient.close()
 ```
 
-### 启用传输加密
+#### 启用传输加密
 
 服务端需先启用 `serv.createApp({ transport: { crypto } })`；客户端只注入同一个 `@h-ai/crypto` 服务实例，无需手写密钥协商代码。
 
@@ -67,7 +71,7 @@ await apiClient.close()
 await crypto.close()
 ```
 
-## API 契约
+### API 契约
 
 自定义应用可以绑定自己的 oRPC contract：
 
@@ -82,7 +86,7 @@ await client.init({ baseUrl: 'https://api.example.com/api/v1' })
 const result = await client.iam.auth.login({ identifier: 'alice', password: 'secret' })
 ```
 
-## API 概览
+### API 概览
 
 - `apiClient.init(config)`：初始化默认 client。
 - `apiClient.close()`：清理 client 状态。
@@ -92,7 +96,7 @@ const result = await client.iam.auth.login({ identifier: 'alice', password: 'sec
 
 已初始化后再次调用 `init()` 会返回 `CONFIG_ERROR`，不会覆盖现有 client；如需切换 `baseUrl` / `fetch` / `transport`，请先 `await apiClient.close()` 再重新初始化。
 
-## 配置
+### 配置
 
 - `baseUrl`：API 基础地址，通常包含 `/api/v1`。
 - `auth.storage`：Token 存储适配器；默认 `apiClient.tokenStorage.httpOnlyCookie()`（浏览器推荐）；SSR / 测试场景请显式传入 `apiClient.tokenStorage.memory()`。
@@ -104,7 +108,7 @@ const result = await client.iam.auth.login({ identifier: 'alice', password: 'sec
 - `transport.keyExchangePath`：密钥协商子路径，默认 `/_hai/key-exchange`；会自动拼接到 `baseUrl` 后。
 - `apiClient.config`：返回**脱敏后的运行配置快照**；`baseUrl` 的内嵌凭证、`headers.authorization` 等敏感值会自动隐藏。
 
-## 配置驱动认证页面
+### 配置驱动认证页面
 
 协议支持配置中的 userAgreementMarkdown/privacyPolicyMarkdown 正文及 URL；同主题优先 Markdown，由安全渲染器在弹窗显示。
 
@@ -112,7 +116,7 @@ const result = await client.iam.auth.login({ identifier: 'alice', password: 'sec
 
 [完整 IAM 配置 / IAM configuration](../iam/README.md)
 
-## 错误处理
+### 错误处理
 
 业务 API 返回 `HaiResult<T>`：
 
@@ -130,13 +134,13 @@ else {
 
 自动刷新在真实 HTTP 401（`Response.status`）或 HTTP 200 的有效失败 HaiResult（`success=false`、`error.code/message` 为字符串且 `error.httpStatus=401`）后触发，刷新成功后只重试一次原请求。内置登录、注册与配置的 `auth.refreshPath` 不触发自动刷新，403/500 等其它失败也不会触发。serv 普通 procedure 的 HTTP 状态仍为 200；调用方须检查最终结果的 `success` 与 `error.code`，并处理刷新失败后的登录失效。
 
-## 测试
+## 开发测试
 
 ```bash
 pnpm --filter @h-ai/api-client test
 pnpm --filter @h-ai/api-client typecheck
 ```
 
-## License
+## 许可证
 
 Apache-2.0

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@h-ai/api-client",
   "type": "module",
-  "version": "0.1.0-alpha.65",
+  "version": "0.1.0-alpha.67",
   "description": "Hai Framework universal HTTP client with Bearer token and API contract support.",
   "license": "Apache-2.0",
   "exports": {
@@ -23,9 +23,9 @@
     "node": "^22.22.2 || ^24.15.0 || >=26.0.0"
   },
   "dependencies": {
-    "@h-ai/api-contract": "0.1.0-alpha.65",
-    "@h-ai/core": "0.1.0-alpha.65",
-    "@h-ai/crypto": "0.1.0-alpha.65",
+    "@h-ai/api-contract": "0.1.0-alpha.67",
+    "@h-ai/core": "0.1.0-alpha.67",
+    "@h-ai/crypto": "0.1.0-alpha.67",
     "@orpc/client": "^1.15.5",
     "@orpc/contract": "^1.15.5",
     "@orpc/openapi-client": "^1.15.5",