@h-ai/cli 0.1.0-alpha.12 → 0.1.0-alpha.15

package/templates/skills/hai-api-client/SKILL.md

@@ -1,355 +1,154 @@
 ---
 name: hai-api-client
-description: 使用 @h-ai/api-client 单例模式构建多端共用的纯 TypeScript HTTP 客户端，通过 api.init() 初始化，支持 Bearer Token 自动管理、401 刷新重试、契约调用（EndpointDef）与流式响应；当需求涉及客户端 API 请求、Token 管理、契约调用或多端数据层时使用。
+description: 使用 @h-ai/api-client 构建多端共用的 oRPC/OpenAPI typed client，通过 apiClient.init() 初始化，支持 Bearer Token 自动管理、401 刷新重试与 contract 嵌套方法调用；当需求涉及客户端 API 请求、Token 管理或多端数据层时使用。
 ---
 
 # hai-api-client
 
-> `@h-ai/api-client` 是 hai-framework 的纯 TypeScript HTTP 客户端，多端共用（Web/H5/Android），基于 fetch API 实现。以单例模式暴露 `api` 对象，通过 `api.init()` 初始化。核心能力：Token 自动附加、401 自动刷新重试、基于 EndpointDef 的类型安全契约调用。
+> `@h-ai/api-client` 是跨端 typed API client。公共 HTTP API 由 `@h-ai/api-contract` 定义，服务端由 `@h-ai/serv` 挂载，客户端直接调用 `apiClient.<domain>.<group>.<operation>()`。
 
----
-
-## 运行环境
-
-**浏览器端专用。** 服务端 `+page.server.ts` / `+server.ts` 应直接调用模块 API（如 `iam.auth.login()`），不经过 HTTP 自环。
-
-### 与 kit.client 的分工
-
-| 场景 | 推荐 | 原因 |
-|------|------|------|
-| SSR SvelteKit 应用（同源请求） | `kit.client.create().apiFetch`（见 hai-kit SKILL） | 自动 CSRF、传输加密、同源 Cookie 透传 |
-| SPA / 原生 App（跨域请求） | **本模块** `api.init()` + `api.call()` | 完整 Token 管理、401 自动刷新、独立 baseUrl |
-| 契约调用（类型安全，跨域） | **本模块** `api.call(endpoint, input)` | EndpointDef 双向 Zod 校验 |
-
----
-
-## 适用场景
+## 使用步骤
 
-- 浏览器端/App 端统一 API 请求
-- Bearer Token 自动管理（存储、附加、刷新）
-- 基于 EndpointDef 契约的类型安全调用
-- 流式响应（SSE / ReadableStream）
-- 拦截器（请求/响应前后处理）
+### 1. 初始化
 
----
+浏览器默认使用 httpOnly cookie 存储（推荐）：
 
-## 使用步骤
+```ts
+import { apiClient } from '@h-ai/api-client'
 
-### 1. 初始化客户端
-
-```typescript
-import { api } from '@h-ai/api-client'
-
-// 应用启动时初始化
-await api.init({
-  baseUrl: 'http://localhost:3000',
-  auth: {
-    refreshUrl: '/auth/refresh',
-    // Token 刷新失败回调（可选，常用于跳转登录页）
-    onRefreshFailed: () => {
-      window.location.href = '/login'
-    },
-  },
-  timeout: 15000,
+await apiClient.init({
+  baseUrl: 'https://api.example.com/api/v1',
+  auth: {},
 })
 ```
 
-> `auth.storage` 可选：默认使用 `createLocalStorageTokenStorage()`；SSR/测试建议显式传 `createMemoryTokenStorage()`，App 端建议传 `createCapacitorTokenStorage()`。
+启用传输加密时，只传顶层 `crypto` 句柄；api-client 内部自动调用 `crypto.transport.createClient()`：
 
-### 2. 普通请求
+```ts
+import { apiClient } from '@h-ai/api-client'
+import { crypto } from '@h-ai/crypto'
 
-```typescript
-// GET 请求
-const users = await api.get<User[]>('/api/v1/users')
+await crypto.init()
 
-// POST 请求
-const result = await api.post<CreateResult>('/api/v1/users', {
-  username: 'alice',
-  email: 'alice@example.com',
+await apiClient.init({
+  baseUrl: 'https://api.example.com/api/v1',
+  auth: {},
+  transport: { crypto }, // 默认协商路径：/api/v1/_hai/key-exchange
 })
-
-// 带查询参数（直接传入 Record<string, unknown>）
-const page = await api.get<PageResult>('/api/v1/users', { page: 1, pageSize: 20 })
 ```
 
-### 3. 契约调用（推荐）
+App/Capacitor 场景传入自定义 TokenStorage：
 
-```typescript
-import { iamEndpoints } from '@h-ai/iam/api'
+```ts
+import { createCapacitorTokenStorage } from '@h-ai/capacitor'
 
-// 类型安全：入参和返回值由 EndpointDef 的 Zod schema 推导，入参/出参双向校验
-const loginResult = await api.call(iamEndpoints.login, {
-  identifier: 'admin',
-  password: 'StrongPassword123',
+await apiClient.init({
+  baseUrl: 'https://api.example.com/api/v1',
+  auth: { storage: createCapacitorTokenStorage() },
 })
-
-if (loginResult.success) {
-  // loginResult.data 类型自动推导为 { user, tokens, agreements? }
-  await api.auth.setTokens(loginResult.data.tokens)
-}
 ```
 
-### 4. Token 管理
-
-```typescript
-// 手动设置 Token（登录后）
-await api.auth.setTokens({
-  accessToken: 'xxx',
-  refreshToken: 'yyy',
-  expiresIn: 3600,
-  tokenType: 'Bearer',
-})
+SSR / Node.js 测试场景请显式传入内存存储：
 
-// 清除 Token（登出）
-await api.auth.clear()
+```ts
+import { apiClient } from '@h-ai/api-client'
 
-// 监听 Token 刷新
-api.auth.onTokenRefreshed((tokens) => {
-  // tokens 包含新的 accessToken / refreshToken
+await apiClient.init({
+  baseUrl: 'https://api.example.com/api/v1',
+  auth: { storage: apiClient.tokenStorage.memory() },
 })
 ```
 
-### 5. 流式响应
-
-```typescript
-const controller = new AbortController()
+### 2. 调用 typed API
 
-// stream(path, body?, options?) — 返回 AsyncIterable<string>，按 SSE data: 行 yield
-for await (const chunk of api.stream('/api/v1/ai/chat', { message: 'Hello' }, { signal: controller.signal })) {
-  // 每个 chunk 是 SSE data: 行的内容
+```ts
+const login = await apiClient.iam.auth.login({ identifier: 'alice', password: 'secret' })
+if (login.success) {
+  // 默认 httpOnly cookie 模式下，refresh token 由服务端 Set-Cookie 管理。
+  await apiClient.auth.setTokens(login.data.tokens)
 }
 
-// 主动停止
-controller.abort()
-```
-
-### 6. 关闭
-
-```typescript
-await api.close()
+const me = await apiClient.iam.auth.currentUser()
+const upload = await apiClient.storage.presignedUrls.createUpload({ key: 'avatar.png' })
+const answer = await apiClient.ai.chats.sendMessage({ message: 'hello' })
 ```
 
----
+### 3. 自定义 contract
 
-## 核心 API
+```ts
+import { apiClient } from '@h-ai/api-client'
+import { apiContract } from '@h-ai/api-contract'
 
-| API                                | 用途           | 关键点                                |
-| ---------------------------------- | -------------- | ------------------------------------- |
-| `api.init(config)`                 | 初始化客户端   | 返回 `HaiResult<void>`   |
-| `api.close()`                      | 关闭并释放资源 | 重复调用安全                          |
-| `api.isInitialized`                | 初始化状态     | `boolean`                             |
-| `api.config`                       | 当前配置       | 未初始化时为 `null`                   |
-| `api.get<T>(path, params?)`        | GET 请求       | params 附加到 URL query string        |
-| `api.post<T>(path, body?)`         | POST 请求      | body 自动 JSON 序列化                 |
-| `api.put<T>(path, body?)`          | PUT 请求       | —                                     |
-| `api.patch<T>(path, body?)`        | PATCH 请求     | —                                     |
-| `api.delete<T>(path, params?)`     | DELETE 请求    | params 附加到 URL query string        |
-| `api.call(endpoint, input)`        | 契约调用       | 入参/出参 Zod 双向校验，路径/方法由契约决定 |
-| `api.upload(path, file, options?)`  | 文件上传       | FormData，支持附加字段                |
-| `api.stream(path, body?)`          | 流式请求       | 返回 AsyncIterable<string>（SSE）     |
-| `api.auth.setTokens(tokens)`       | 设置 Token     | 存入 TokenStorage                     |
-| `api.auth.clear()`                 | 清空 Token     | 清空存储                              |
-| `api.auth.onTokenRefreshed(cb)`    | 刷新回调       | 返回取消订阅函数，Token 自动刷新成功时通知 |
-
-### EndpointDef 契约结构
-
-```typescript
-interface EndpointDef<TInput, TOutput> {
-  method: 'GET' | 'POST' | 'PUT' | 'DELETE' | 'PATCH'
-  path: string
-  input: ZodSchema<TInput>
-  output: ZodSchema<TOutput>
-  requireAuth?: boolean
-  meta?: { summary?: string; tags?: string[] }
-}
+const contract = apiContract.create({ iam: apiContract.iam })
+const client = apiClient.create(contract)
+await client.init({ baseUrl: 'https://api.example.com/api/v1' })
 ```
 
-### TokenStorage 接口
+### 4. 关闭
 
-```typescript
-interface TokenStorage {
-  getAccessToken: () => Promise<string | null>
-  setAccessToken: (token: string) => Promise<void>
-  getRefreshToken: () => Promise<string | null>
-  setRefreshToken: (token: string) => Promise<void>
-  clear: () => Promise<void>
-}
+```ts
+await apiClient.close()
 ```
 
-内置实现：`createLocalStorageTokenStorage()`（Web）、`createMemoryTokenStorage()`（SSR/测试）。
-App 端使用 `@h-ai/capacitor` 的 `createCapacitorTokenStorage()`。
+## Token Storage 适配器
 
----
+| 工厂调用 | 存储位置 | 适用场景 |
+| --- | --- | --- |
+| `apiClient.tokenStorage.httpOnlyCookie()` | httpOnly cookie（服务端管理） | **默认**；浏览器端推荐，refresh token 不暴露给 JS |
+| `apiClient.tokenStorage.memory()` | 内存 | SSR / Node.js 单元测试（需显式传入） |
+| `apiClient.tokenStorage.localStorage()` | localStorage | 非敏感场景（有 XSS 风险，生产不推荐） |
 
-## 错误码 — `HaiApiClientError`
-
-| 错误码 | code | 说明 |
-|--------|------|------|
-| `HaiApiClientError.NETWORK_ERROR` | `hai:api-client:001` | 网络不可达 |
-| `HaiApiClientError.TIMEOUT` | `hai:api-client:002` | 请求超时 |
-| `HaiApiClientError.SERVER_ERROR` | `hai:api-client:003` | 5xx 服务端错误 |
-| `HaiApiClientError.UNAUTHORIZED` | `hai:api-client:004` | 401 未认证 |
-| `HaiApiClientError.FORBIDDEN` | `hai:api-client:005` | 403 无权限 |
-| `HaiApiClientError.NOT_FOUND` | `hai:api-client:006` | 404 资源不存在 |
-| `HaiApiClientError.VALIDATION_FAILED` | `hai:api-client:007` | 请求参数校验失败 |
-| `HaiApiClientError.TOKEN_REFRESH_FAILED` | `hai:api-client:008` | Token 刷新失败 |
-| `HaiApiClientError.NOT_INITIALIZED` | `hai:api-client:010` | 未初始化 |
-| `HaiApiClientError.CONFIG_ERROR` | `hai:api-client:011` | 配置错误 |
-| `HaiApiClientError.UNKNOWN` | `hai:api-client:099` | 未知错误 |
+### httpOnly Cookie 模式
 
----
+Access token 存在内存中，refresh token 由服务端通过 `HttpOnly` cookie 管理，浏览器 JS 无法读取，可有效防止 XSS 窃取 token。
 
-## API 契约范式（端到端类型安全）
+**前提**：服务端需配置 `serv.createApp({ iam, refreshCookie: {} })`，参见 `hai-serv` skill。
 
-> `@h-ai/api-client` 和 `@h-ai/kit` 共同消费模块 `api/` 下的 `EndpointDef` 定义，实现客户端↔服务端的全链路类型安全 + 运行时 Zod 校验。
+启用 `transport` 时，登录、业务请求以及 401 后的自动刷新都会复用同一个加密 fetch 链路；不要在业务代码中手写明文 `/auth/refresh` 请求。
 
-### 契约架构
+```ts
+import { apiClient } from '@h-ai/api-client'
 
-```
-┌─────────────────────────────────────────────────────────────┐
-│                    @h-ai/xx/api                             │
-│  xx-api-schemas.ts  ←  Zod Schema（唯一真相源）            │
-│  xx-api-contract.ts ←  xxEndpoints（method + path + schema）│
-└─────────────┬──────────────────────────┬────────────────────┘
-              │                          │
-     ┌────────▼────────┐       ┌─────────▼─────────┐
-     │  客户端（浏览器）│       │  服务端（SvelteKit）│
-     │  api.call(ep, i) │       │  kit.fromContract  │
-     │  @h-ai/api-client│       │  @h-ai/kit         │
-     └────────┬────────┘       └─────────┬─────────┘
-              │      HTTP（类型安全）     │
-              └──────────────────────────┘
-```
-
-### 客户端流程（本模块责任）
-
-1. 从 `@h-ai/xx/api` 导入 `xxEndpoints`
-2. `api.call(xxEndpoints.xxx, input)` → Zod 校验入参 → 按 method/path 发起 HTTP → Zod 校验出参
-3. 入参或出参校验失败均返回 `VALIDATION_FAILED`（1206）
-4. 返回 `HaiResult<TOutput>`
-
-```typescript
-import { storageEndpoints } from '@h-ai/storage/api'
-import { iamEndpoints } from '@h-ai/iam/api'
-import { aiEndpoints } from '@h-ai/ai/api'
-
-// 存储：获取上传签名 URL
-const upload = await api.call(storageEndpoints.presignUpload, {
-  key: 'avatars/user-1.png',
-  contentType: 'image/png',
-})
-
-// IAM：登录
-const login = await api.call(iamEndpoints.login, {
-  username: 'admin',
-  password: 'xxx',
-})
-
-// AI：发送消息
-const chat = await api.call(aiEndpoints.sendMessage, {
-  conversationId: 'conv-1',
-  content: 'Hello',
+// apiClient.tokenStorage.httpOnlyCookie() 是默认存储，无需显式指定
+await apiClient.init({
+  baseUrl: 'https://api.example.com/api/v1',
+  auth: {},
 })
-```
-
-### 已有契约模块一览
-
-| 模块       | 导入路径               | 端点对象             | 典型端点                        |
-| ---------- | -------------------- | -------------------- | ------------------------------- |
-| `storage`  | `@h-ai/storage/api`  | `storageEndpoints`   | presignUpload, listFiles, …     |
-| `iam`      | `@h-ai/iam/api`      | `iamEndpoints`       | login, logout, currentUser, …   |
-| `ai`       | `@h-ai/ai/api`       | `aiEndpoints`        | chat, chatStream, sendMessage   |
-| `payment`  | `@h-ai/payment/api`  | `paymentEndpoints`   | createOrder, queryOrder, …      |
-
 
-## 常见模式
-
-### 与 @h-ai/iam/api 契约配合
-
-```typescript
-import { iamEndpoints } from '@h-ai/iam/api'
-
-// 登录（入参字段为 identifier + password）
-const login = await api.call(iamEndpoints.login, { identifier, password })
+// 登录后设置 access token（refresh token 由服务端写入 cookie，前端无需操作）
+const login = await apiClient.iam.auth.login({ identifier: 'alice', password: 'secret' })
 if (login.success) {
-  // login.data 类型：{ user, tokens, agreements? }
-  await api.auth.setTokens(login.data.tokens)
+  await apiClient.auth.setTokens(login.data.tokens)
 }
+```
 
-// 获取当前用户（自动携带 Bearer Token）
-const me = await api.call(iamEndpoints.currentUser, {})
-// me.data 类型：{ user, roles, permissions }
+## 核心 API
 
-// 修改密码
-await api.call(iamEndpoints.changePassword, { oldPassword, newPassword })
+| API | 用途 |
+| --- | --- |
+| `apiClient.init(config)` | 初始化默认 API Service client |
+| `apiClient.close()` | 清理 client 状态 |
+| `apiClient.auth.setTokens(tokens)` | 写入 access token；非 httpOnly 存储会同时写入 refresh token |
+| `apiClient.auth.clear()` | 清理 Token |
+| `apiClient.auth.onTokenRefreshed(cb)` | 监听刷新结果 |
+| `apiClient.create(contract)` | 创建自定义 typed client |
+| `apiClient.tokenStorage.{memory,localStorage,httpOnlyCookie}()` | TokenStorage 工厂 |
 
-// 登出
-const accessToken = '...' // 从 Token 存储获取
-await api.call(iamEndpoints.logout, { accessToken })
-await api.auth.clear()
-```
+### Transport 配置
 
-#### 401 自动刷新机制
-
-当请求收到 401 响应时，客户端自动执行：
-
-1. 使用存储的 `refreshToken` 调用 `auth.refreshUrl`（POST）
-2. 刷新成功 → 更新存储 → 用新 Token 重试原请求（仅重试一次）
-3. 刷新失败 → 清空 Token → 触发 `onRefreshFailed` 回调
-4. 多个并发 401 → **自动去重**，只发一次刷新请求
-
-> 流式请求（`api.stream()`）同样支持 401 自动刷新 + 重试。
-
-#### 可用的 IAM 端点
-
-| 分类 | 端点 | 方法 | 路径 | 认证 |
-|------|------|------|------|------|
-| 认证 | `iamEndpoints.login` | POST | /auth/login | 否 |
-| | `iamEndpoints.loginWithOtp` | POST | /auth/login/otp | 否 |
-| | `iamEndpoints.logout` | POST | /auth/logout | 是 |
-| | `iamEndpoints.currentUser` | GET | /auth/me | 是 |
-| | `iamEndpoints.refreshToken` | POST | /auth/refresh | 否 |
-| | `iamEndpoints.sendOtp` | POST | /auth/otp/send | 否 |
-| | `iamEndpoints.register` | POST | /auth/register | 否 |
-| | `iamEndpoints.changePassword` | POST | /auth/change-password | 是 |
-| | `iamEndpoints.updateCurrentUser` | PUT | /auth/me | 是 |
-| 用户管理 | `iamEndpoints.listUsers` | GET | /iam/users | 是 |
-| | `iamEndpoints.getUser` | GET | /iam/users/:id | 是 |
-| | `iamEndpoints.createUser` | POST | /iam/users | 是 |
-| | `iamEndpoints.updateUser` | PUT | /iam/users/:id | 是 |
-| | `iamEndpoints.deleteUser` | DELETE | /iam/users/:id | 是 |
-| | `iamEndpoints.adminResetPassword` | POST | /iam/users/:id/reset-password | 是 |
-| 角色管理 | `iamEndpoints.listRoles` | GET | /iam/roles | 是 |
-| | `iamEndpoints.getRole` | GET | /iam/roles/:id | 是 |
-| | `iamEndpoints.createRole` | POST | /iam/roles | 是 |
-| | `iamEndpoints.updateRole` | PUT | /iam/roles/:id | 是 |
-| | `iamEndpoints.deleteRole` | DELETE | /iam/roles/:id | 是 |
-| 权限管理 | `iamEndpoints.listPermissions` | GET | /iam/permissions | 是 |
-| | `iamEndpoints.getPermission` | GET | /iam/permissions/:id | 是 |
-| | `iamEndpoints.createPermission` | POST | /iam/permissions | 是 |
-| | `iamEndpoints.deletePermission` | DELETE | /iam/permissions/:id | 是 |
-
-### Android App 中使用
-
-```typescript
-import { api } from '@h-ai/api-client'
-import { createCapacitorTokenStorage } from '@h-ai/capacitor'
-
-// 应用启动时初始化
-await api.init({
-  baseUrl: import.meta.env.PUBLIC_API_BASE,
-  auth: {
-    storage: createCapacitorTokenStorage(),
-    refreshUrl: '/api/v1/auth/refresh',
-  },
-})
-```
+| 字段 | 说明 |
+| --- | --- |
+| `transport.crypto` | 已初始化的 `@h-ai/crypto` 实例 |
+| `transport.keyExchangePath` | 相对于 `baseUrl` 的协商子路径，默认 `/_hai/key-exchange` |
 
----
+服务端必须对应启用 `serv.createApp({ transport: { crypto } })`。
+自动刷新会沿用 `transport.encryptedFetch`，并在 httpOnly cookie 模式下发送空请求体 + `credentials: 'include'`，由服务端从 cookie 读取 refresh token。
 
-## 相关 Skills
+## 常见模式
 
-- `hai-iam`：认证契约定义（iamEndpoints）
-- `hai-capacitor`：原生 Token 存储
-- `hai-kit`：服务端契约处理（kit.fromContract）
-- `hai-core`：HaiResult 类型、错误处理基础
+- `baseUrl` 通常包含服务端 `apiPrefix`，例如 `/api/v1`。
+- 业务错误不 throw，统一判断 `HaiResult.success`。
+- 客户端不导入服务端 `procedures` 或 `@h-ai/serv`。
+- 客户端不导入 `@h-ai/crypto` 的内部 transport 工厂，只通过 `transport: { crypto }` 装配。
+- 前端只依赖 `@h-ai/api-client` 和 contract 类型，不依赖业务模块实现。
+- httpOnly cookie 模式需服务端与客户端同步配置，不支持跨域刷新（`SameSite=Strict`）。