@h-ai/api-client 0.1.0-alpha.56 → 0.1.0-alpha.57

package/README.en.md

@@ -0,0 +1,134 @@
+# @h-ai/api-client
+
+[简体中文](./README.md) | [English](./README.en.md) | [日本語](./README.ja.md)
+
+[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.
+
+## Capabilities
+
+- `apiClient`: the default typed client for the iam/storage/ai domains.
+- `apiClient.create(contract)`: create a typed client for a custom contract.
+- `apiClient.tokenStorage.{memory,localStorage,httpOnlyCookie}()`: token storage factories.
+- Custom `fetch` support for browsers, Node, Capacitor, and mini-program bridges.
+- Automatic Bearer token injection, with token refresh and one retry after a 401.
+- Network failures are converted to `HaiResult` errors.
+- 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
+
+```ts
+import { apiClient } from '@h-ai/api-client'
+
+await apiClient.init({
+  baseUrl: 'https://api.example.com/api/v1',
+  auth: {}, // 默认使用 httpOnly cookie 存储（推荐）；SSR 测试请显式传入 apiClient.tokenStorage.memory()
+})
+
+const login = await apiClient.iam.auth.login({
+  identifier: 'alice',
+  password: 'secret',
+})
+
+if (login.success) {
+  // httpOnly cookie 模式下 refresh token 由服务端 Set-Cookie 管理，
+  // api-client 默认存储只需要把 access token 写入内存。
+  await apiClient.auth.setTokens(login.data.tokens)
+}
+
+const me = await apiClient.iam.auth.currentUser()
+if (me.success) {
+  // 身份资料与服务端重新校验后的访问范围一次返回，客户端无需持久化权限快照。
+  const { roles, permissions, ...user } = me.data
+}
+
+await apiClient.close()
+```
+
+### 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.
+
+```ts
+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',
+  auth: {},
+  transport: { crypto }, // 默认协商路径：/api/v1/_hai/key-exchange
+})
+
+await apiClient.close()
+await crypto.close()
+```
+
+## API contracts
+
+Custom applications can bind their own oRPC contract:
+
+```ts
+import { apiClient } from '@h-ai/api-client'
+import { apiContract } from '@h-ai/api-contract'
+
+const contract = apiContract.create({ iam: apiContract.iam })
+const client = apiClient.create(contract)
+
+await client.init({ baseUrl: 'https://api.example.com/api/v1' })
+const result = await client.iam.auth.login({ identifier: 'alice', password: 'secret' })
+```
+
+## API overview
+
+- `apiClient.init(config)`: initialize the default client.
+- `apiClient.close()`: clear client state.
+- `apiClient.auth.setTokens(tokens)`: store the access token; storage other than httpOnly also stores the refresh token.
+- `apiClient.auth.clear()`: clear tokens.
+- `apiClient.create(contract)`: create a custom typed client.
+
+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
+
+- `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.
+- `auth.refreshPath`: token refresh path; defaults to `/auth/refresh`.
+- `timeout`: request timeout; defaults to 30000 ms.
+- `headers`: static or dynamic shared request headers.
+- `fetch`: custom fetch implementation.
+- `transport.crypto`: transparent request/response encryption and decryption; requires an initialized `@h-ai/crypto` instance.
+- `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.
+
+## Error handling
+
+Business APIs return `HaiResult<T>`:
+
+```ts
+const result = await apiClient.iam.auth.currentUser()
+if (!result.success) {
+  // result.error.code / result.error.message
+}
+else {
+  // result.data = User & { roles: string[], permissions: string[] }
+}
+```
+
+Client-side failures such as missing initialization, network errors, timeouts, and 401/403/404 responses are also converted to failed `HaiResult` values.
+
+Automatic refresh is triggered only by an actual HTTP 401 (`Response.status`). Ordinary serv procedures return failed HaiResult values over HTTP 200 by default. `error.httpStatus=401` inside that envelope does not trigger refresh; callers must still check `success` and `error.code` and handle expired authentication.
+
+## Tests
+
+```bash
+pnpm --filter @h-ai/api-client test
+pnpm --filter @h-ai/api-client typecheck
+```
+
+## License
+
+Apache-2.0

package/README.ja.md

@@ -0,0 +1,134 @@
+# @h-ai/api-client
+
+[简体中文](./README.md) | [English](./README.en.md) | [日本語](./README.ja.md)
+
+[フレームワークのホーム](../../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 管理を提供します。
+
+## 機能概要
+
+- `apiClient`：iam/storage/ai ドメインに対応する既定の型付きクライアント。
+- `apiClient.create(contract)`：独自の contract に対応する型付きクライアントを作成。
+- `apiClient.tokenStorage.{memory,localStorage,httpOnlyCookie}()`：Token ストレージのファクトリー。
+- ブラウザー、Node、Capacitor、ミニプログラムのブリッジに対応する独自 `fetch` を指定可能。
+- Bearer Token の自動付与と、401 応答後の更新および 1 回の再試行。
+- ネットワークエラーを `HaiResult` のエラーに変換。
+- 任意の通信暗号化：`apiClient.init({ transport: { crypto } })` が `crypto.transport.createClient()` を自動使用。
+- 通信暗号化と自動更新を併用可能。401 後の `/auth/refresh` も暗号化された fetch を使用し、平文には切り替わりません。
+
+## クイックスタート
+
+```ts
+import { apiClient } from '@h-ai/api-client'
+
+await apiClient.init({
+  baseUrl: 'https://api.example.com/api/v1',
+  auth: {}, // 默认使用 httpOnly cookie 存储（推荐）；SSR 测试请显式传入 apiClient.tokenStorage.memory()
+})
+
+const login = await apiClient.iam.auth.login({
+  identifier: 'alice',
+  password: 'secret',
+})
+
+if (login.success) {
+  // httpOnly cookie 模式下 refresh token 由服务端 Set-Cookie 管理，
+  // api-client 默认存储只需要把 access token 写入内存。
+  await apiClient.auth.setTokens(login.data.tokens)
+}
+
+const me = await apiClient.iam.auth.currentUser()
+if (me.success) {
+  // 身份资料与服务端重新校验后的访问范围一次返回，客户端无需持久化权限快照。
+  const { roles, permissions, ...user } = me.data
+}
+
+await apiClient.close()
+```
+
+### 通信暗号化の有効化
+
+サーバーで先に `serv.createApp({ transport: { crypto } })` を有効にします。クライアントには同じ `@h-ai/crypto` サービスのインスタンスを渡すだけで、鍵交換コードの実装は不要です。
+
+```ts
+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',
+  auth: {},
+  transport: { crypto }, // 默认协商路径：/api/v1/_hai/key-exchange
+})
+
+await apiClient.close()
+await crypto.close()
+```
+
+## API 契約
+
+独自のアプリケーションでは、専用の oRPC contract を指定できます：
+
+```ts
+import { apiClient } from '@h-ai/api-client'
+import { apiContract } from '@h-ai/api-contract'
+
+const contract = apiContract.create({ iam: apiContract.iam })
+const client = apiClient.create(contract)
+
+await client.init({ baseUrl: 'https://api.example.com/api/v1' })
+const result = await client.iam.auth.login({ identifier: 'alice', password: 'secret' })
+```
+
+## API 一覧
+
+- `apiClient.init(config)`：既定のクライアントを初期化。
+- `apiClient.close()`：クライアントの状態を解放。
+- `apiClient.auth.setTokens(tokens)`：access token を保存。httpOnly 以外のストレージでは refresh token も保存します。
+- `apiClient.auth.clear()`：Token を削除。
+- `apiClient.create(contract)`：独自の型付きクライアントを作成。
+
+初期化済みのクライアントで `init()` を再度呼ぶと `CONFIG_ERROR` が返り、既存のクライアントは維持されます。`baseUrl` / `fetch` / `transport` を変更する場合は、先に `await apiClient.close()` を呼んでから再初期化してください。
+
+## 設定
+
+- `baseUrl`：API のベース URL。通常は `/api/v1` を含みます。
+- `auth.storage`：Token ストレージアダプター。既定は `apiClient.tokenStorage.httpOnlyCookie()`（ブラウザー推奨）。SSR / テストでは `apiClient.tokenStorage.memory()` を明示してください。
+- `auth.refreshPath`：Token 更新パス。既定は `/auth/refresh`。
+- `timeout`：リクエストのタイムアウト。既定は 30000 ms。
+- `headers`：静的または動的な共通リクエストヘッダー。
+- `fetch`：独自の fetch 実装。
+- `transport.crypto`：透過的なリクエスト/レスポンス暗号化・復号。初期化済みの `@h-ai/crypto` インスタンスが必要です。
+- `transport.keyExchangePath`：鍵交換のサブパス。既定は `/_hai/key-exchange` で、`baseUrl` に自動的に連結されます。
+- `apiClient.config`：**機密情報をマスクした実行時設定のスナップショット**。`baseUrl` 内の認証情報や `headers.authorization` などの機密値は自動的に非表示になります。
+
+## エラー処理
+
+業務 API は `HaiResult<T>` を返します：
+
+```ts
+const result = await apiClient.iam.auth.currentUser()
+if (!result.success) {
+  // result.error.code / result.error.message
+}
+else {
+  // result.data = User & { roles: string[], permissions: string[] }
+}
+```
+
+未初期化、ネットワークエラー、タイムアウト、401/403/404 などのクライアント側の問題も、失敗の `HaiResult` に変換されます。
+
+自動更新は実際の HTTP 401（`Response.status`）でのみ動作します。serv の通常の procedure は既定で失敗の HaiResult を HTTP 200 で返し、その包絡中の `error.httpStatus=401` は更新を起動しません。呼び出し側は `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

@@ -1,5 +1,9 @@
 # @h-ai/api-client
 
+[简体中文](./README.md) | [English](./README.en.md) | [日本語](./README.ja.md)
+
+[框架首页](../../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 管理。
 
 ## 能力概览
@@ -116,6 +120,8 @@ else {
 
 未初始化、网络错误、超时、401/403/404 等客户端侧问题也会转换为失败的 `HaiResult`。
 
+自动刷新仅由真实 HTTP 401（`Response.status`）触发。serv 普通 procedure 默认通过 HTTP 200 返回失败 HaiResult，包络中的 `error.httpStatus=401` 不会触发刷新；调用方仍须检查 `success` 与 `error.code` 并处理登录失效。
+
 ## 测试
 
 ```bash

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@h-ai/api-client",
   "type": "module",
-  "version": "0.1.0-alpha.56",
+  "version": "0.1.0-alpha.57",
   "description": "Hai Framework universal HTTP client with Bearer token and API contract support.",
   "license": "Apache-2.0",
   "exports": {
@@ -27,9 +27,9 @@
     "@orpc/contract": "^1.14.3",
     "@orpc/openapi-client": "^1.14.3",
     "zod": "^4.4.3",
-    "@h-ai/api-contract": "0.1.0-alpha.56",
-    "@h-ai/core": "0.1.0-alpha.56",
-    "@h-ai/crypto": "0.1.0-alpha.56"
+    "@h-ai/core": "0.1.0-alpha.57",
+    "@h-ai/crypto": "0.1.0-alpha.57",
+    "@h-ai/api-contract": "0.1.0-alpha.57"
   },
   "devDependencies": {
     "@types/node": "^25.9.1",