@h-ai/cli 0.1.0-alpha.66 → 0.1.0-alpha.67

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

@@ -0,0 +1,166 @@
+# hai-api-client 参考
+
+> `@h-ai/api-client` 是跨端 typed API client。公共 HTTP API 由 `@h-ai/api-contract` 定义，服务端由 `@h-ai/serv` 挂载，客户端直接调用 `apiClient.<domain>.<group>.<operation>()`。
+
+## 使用步骤
+
+### 1. 初始化
+
+浏览器默认使用 httpOnly cookie 存储（推荐）：
+
+```ts
+import { apiClient } from '@h-ai/api-client'
+
+await apiClient.init({
+  baseUrl: 'https://api.example.com/api/v1',
+  auth: {},
+})
+```
+
+启用传输加密时，只传顶层 `crypto` 句柄；api-client 内部自动调用 `crypto.transport.createClient()`：
+
+```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
+})
+```
+
+App/Capacitor 场景传入自定义 TokenStorage：
+
+```ts
+import { createCapacitorTokenStorage } from '@h-ai/capacitor'
+
+await apiClient.init({
+  baseUrl: 'https://api.example.com/api/v1',
+  auth: { storage: createCapacitorTokenStorage() },
+})
+```
+
+> `createCapacitorTokenStorage()` 仅在 Android/iOS 原生环境 + `@aparajita/capacitor-secure-storage` 已安装时持久化 token；纯 Web 不会回退到 `localStorage`。
+
+SSR / Node.js 测试场景请显式传入内存存储：
+
+```ts
+import { apiClient } from '@h-ai/api-client'
+
+await apiClient.init({
+  baseUrl: 'https://api.example.com/api/v1',
+  auth: { storage: apiClient.tokenStorage.memory() },
+})
+```
+
+### 2. 调用 typed API
+
+```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)
+}
+
+const me = await apiClient.iam.auth.currentUser()
+if (me.success) {
+  // currentUser 返回服务端最新角色/权限；不要把权限快照持久化到 localStorage。
+  const { roles, permissions, ...user } = me.data
+}
+const upload = await apiClient.storage.presignedUrls.createUpload({ key: 'avatar.png' })
+const answer = await apiClient.ai.chats.sendMessage({ message: 'hello' })
+```
+
+### 3. 自定义 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' })
+```
+
+`client.config` / `apiClient.config` 返回的是脱敏后的运行配置快照；`baseUrl` 的内嵌凭证与 `headers.authorization` 等敏感值会自动隐藏。
+
+### 4. 关闭
+
+```ts
+await apiClient.close()
+```
+
+> 已初始化后再次 `init()` 会返回 `CONFIG_ERROR`，不会覆盖现有 client；切换 `baseUrl` / `fetch` / `transport` 前必须先 `close()`，避免旧 transport 会话泄漏。
+
+## Token Storage 适配器
+
+| 工厂调用 | 存储位置 | 适用场景 |
+| --- | --- | --- |
+| `apiClient.tokenStorage.httpOnlyCookie()` | httpOnly cookie（服务端管理） | **默认**；浏览器端推荐，refresh token 不暴露给 JS |
+| `apiClient.tokenStorage.memory()` | 内存 | SSR / Node.js 单元测试（需显式传入） |
+| `apiClient.tokenStorage.localStorage()` | localStorage | 非敏感场景（有 XSS 风险，生产不推荐） |
+
+### httpOnly Cookie 模式
+
+Access token 存在内存中，refresh token 由服务端通过 `HttpOnly` cookie 管理，浏览器 JS 无法读取，可有效防止 XSS 窃取 token。
+
+**前提**：服务端需配置 `serv.createApp({ iam, refreshCookie: {} })`，参见 `hai-serv` skill。
+
+启用 `transport` 时，登录、业务请求以及 401 后的自动刷新都会复用同一个加密 fetch 链路；不要在业务代码中手写明文 `/auth/refresh` 请求。
+
+自动刷新识别真实 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` 并处理刷新失败后的登录失效。
+
+```ts
+import { apiClient } from '@h-ai/api-client'
+
+// apiClient.tokenStorage.httpOnlyCookie() 是默认存储，无需显式指定
+await apiClient.init({
+  baseUrl: 'https://api.example.com/api/v1',
+  auth: {},
+})
+
+// 登录后设置 access token（refresh token 由服务端写入 cookie，前端无需操作）
+const login = await apiClient.iam.auth.login({ identifier: 'alice', password: 'secret' })
+if (login.success) {
+  await apiClient.auth.setTokens(login.data.tokens)
+}
+```
+
+## 核心 API
+
+| API | 用途 |
+| --- | --- |
+| `apiClient.init(config)` | 初始化默认 API Service client；重复初始化返回 `CONFIG_ERROR` |
+| `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 工厂 |
+
+### Transport 配置
+
+| 字段 | 说明 |
+| --- | --- |
+| `transport.crypto` | 已初始化的 `@h-ai/crypto` 实例 |
+| `transport.keyExchangePath` | 相对于 `baseUrl` 的协商子路径，默认 `/_hai/key-exchange` |
+
+服务端必须对应启用 `serv.createApp({ transport: { crypto } })`。
+自动刷新会沿用 `transport.encryptedFetch`，并在 httpOnly cookie 模式下发送空请求体 + `credentials: 'include'`，由服务端从 cookie 读取 refresh token。
+
+## 常见模式
+
+- `baseUrl` 通常包含服务端 `apiPrefix`，例如 `/api/v1`。
+- 业务错误不 throw，统一判断 `HaiResult.success`。
+- 客户端不导入服务端 `procedures` 或 `@h-ai/serv`。
+- 客户端不导入 `@h-ai/crypto` 的内部 transport 工厂，只通过 `transport: { crypto }` 装配。
+- 前端只依赖 `@h-ai/api-client` 和 contract 类型，不依赖业务模块实现。
+- httpOnly cookie 模式需服务端与客户端同步配置，跨 Origin 请求需正确设置 CORS 与 credentials；`SameSite=Strict` 限制跨站 Cookie，跨域不等于跨站。
+
+
+## 配置驱动认证页面
+
+`apiClient.createAuthActions(client)` 为含标准 iam contract 的客户端提供 publicConfig、login、register、sendOtp、requestPasswordReset、confirmPasswordReset。login 输入使用 identifier/password/method/code，method 为 password、ldap、email、sms。成功认证自动调用既有安全 TokenStorage；应用只需把动作传给 AuthPanel，并在 onauthenticated 中刷新自己的用户状态或导航。

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

@@ -1,6 +1,6 @@
 ---
 name: hai-api-contract
-description: "使用 @h-ai/api-contract 定义、组合和扩展共享 HTTP contract 与 Zod 输入输出。"
+description: "新增、组合或修改共享 HTTP 接口的路径与输入输出 Schema，供 serv 与 typed client 共用。"
 ---
 
 # hai-api-contract
@@ -15,279 +15,21 @@ description: "使用 @h-ai/api-contract 定义、组合和扩展共享 HTTP cont
 | 输出 | 供 serv 实现和 api-client 消费的 contract |
 | 限制 | 纯定义，无 init/close；不包含服务端实现或密钥。业务路径属于 contract，公共传输配置属于 transport。 |
 
-> `@h-ai/api-contract` 是 hai-framework 的公共 HTTP API 契约包，使用 oRPC contract + Zod v4 作为唯一接口真相源。本包只描述接口边界，不包含任何 procedure 实现。
+## 使用路径
 
-## 运行环境
+1. 查当前公开 exports 与已有领域 contract，确认业务路径唯一来源。
+2. 在 contract 中声明 method/path 与输入输出 Schema；只导出真正跨接口或跨层复用的 Schema。
+3. 用 `apiContract.create` 组合领域；不把服务实现、私有配置或传输前缀写进 contract。
+4. 同步 serv procedures、typed client、调用方与失败/校验测试；普通业务输出按当前 HaiResult 契约。
 
-> ✅ **契约定义包，无服务端业务依赖；Zod/oRPC schema 构造仍有运行时代码。** 可在客户端、服务端、测试环境直接引用。
+## 按需参考
 
-## 适用场景
+按本次操作读取对应小节；以已安装版本的公开类型核验签名，示例中的业务变量由应用提供。
 
-- 定义新领域的 oRPC contract（输入/输出 Schema + HTTP 路由元数据）
-- 组合多个领域 contract 为应用级 contract
-- 向 `@h-ai/serv` 提供 contract（装配为 HTTP API）
-- 向 `@h-ai/api-client` 提供 contract（生成类型安全客户端）
-- 复用内置领域 contract（iam/storage/ai/payment）
-- 复用公共 Schema 工厂（`apiContract.haiResultSchema`、分页 Schema）
-
-## 使用步骤
-
-### 1. 组合应用级 contract
-
-```typescript
-import { apiContract } from '@h-ai/api-contract'
-
-// 按需组合，传 false/undefined 的领域不会出现在 contract 或 OpenAPI spec 中
-export const myContract = apiContract.create({
-  iam: apiContract.iam,
-  storage: apiContract.storage,
-  ai: apiContract.ai,
-  payment: false, // 禁用领域
-})
-
-// myContract.iam.auth.login
-// myContract.storage.presignedUrls.createUpload
-// myContract.ai.chats.createCompletion
-```
-
-### 2. 组合自定义 contract
-
-```typescript
-import { apiContract } from '@h-ai/api-contract'
-
-export const myContract = apiContract.create({
-  iam: apiContract.iam,
-  storage: apiContract.storage,
-  payment: false, // 禁用领域（不会出现在 contract 或 OpenAPI spec 中）
-})
-```
-
-### 3. 定义新领域 contract
-
-```typescript
-import { apiContract } from '@h-ai/api-contract'
-import { z } from 'zod'
-
-// 输入 Schema
-const WidgetCreateInputSchema = z.object({
-  name: z.string().min(1),
-  description: z.string().optional(),
-})
-
-// 同一 contract 内两个接口复用，因此保留为文件私有常量，不从 schemas 导出。
-const WidgetOutputSchema = apiContract.haiResultSchema(z.object({
-  id: z.string(),
-  name: z.string(),
-  createdAt: z.string(),
-}))
-
-// 领域 contract
-export const widgetContract = {
-  widget: {
-    create: apiContract
-      .route({
-        method: 'POST',
-        path: '/widgets',
-        operationId: 'widget.create',
-        summary: 'Create widget',
-        tags: ['widget'],
-      })
-      .input(WidgetCreateInputSchema)
-      .output(WidgetOutputSchema),
-
-    getById: apiContract
-      .route({
-        method: 'GET',
-        path: '/widgets/{id}',
-        operationId: 'widget.getById',
-        summary: 'Get widget by id',
-        tags: ['widget'],
-      })
-      .input(z.object({ id: z.string() }))
-      .output(WidgetOutputSchema),
-  },
-}
-```
-
-### 4. 将新 contract 挂入应用级 contract
-
-```typescript
-import { apiContract } from '@h-ai/api-contract'
-import { widgetContract } from './widget-contract.js'
-
-export const appContract = apiContract.create({
-  iam: apiContract.iam,
-  widget: widgetContract,
-})
-```
-
-### 5. 传给 `@h-ai/serv`（服务端）
-
-```typescript
-import { serv } from '@h-ai/serv'
-import { appContract } from './app-contract.js'
-import { createMyProcedures } from './procedures/widget.js'
-
-const app = serv.createApp({
-  contract: appContract,
-  procedures: {
-    iam: createIamProcedures({ iam }),
-    widget: createMyProcedures(),
-  },
-  http: { apiPrefix: '/api/v1' },
-})
-```
-
-## 核心 API
-
-### `apiContract.create(options)` — 组合领域 contract
-
-```typescript
-import { apiContract } from '@h-ai/api-contract'
-
-const contract = apiContract.create({
-  iam: apiContract.iam,      // 启用：纳入 contract
-  storage: false,            // 禁用：不出现在 OpenAPI spec 中
-  custom: myContract,        // 自定义领域
-})
-// 类型自动收窄，被禁用的 key 不出现在 contract 类型中
-```
-
-### 内置领域 contract
-
-| 访问路径 | 领域 | 功能概述 |
-| --- | --- | --- |
-| `apiContract.iam` | IAM | auth（登录/登出/OTP/刷新/注册/改密码）、users、roles、permissions Admin CRUD |
-| `apiContract.storage` | Storage | presignedUrls（上传/下载/批量）、files（元数据查询/删除） |
-| `apiContract.ai` | AI | chats（completion/流式）、knowledge（上传/查询） |
-| `apiContract.payment` | Payment | orders、subscriptions |
-
-### 内置 contract 路径示例
-
-```typescript
-const myContract = apiContract.create({ iam: apiContract.iam, storage: apiContract.storage, ai: apiContract.ai })
-
-// IAM
-myContract.iam.auth.login        // POST /auth/login
-myContract.iam.auth.logout       // POST /auth/logout
-myContract.iam.users.list        // GET  /iam/users
-myContract.iam.roles.create      // POST /iam/roles
-
-// Storage
-myContract.storage.presignedUrls.createUpload   // POST /storage/presigned-urls/upload
-
-// AI
-myContract.ai.chats.createCompletion  // POST /ai/chats/completion
-```
-
-### `apiContract.haiResultSchema(dataSchema)` — 标准输出包装
-
-所有 HTTP 输出必须通过 `apiContract.haiResultSchema` 包装为 `HaiResult<T>`，与 `@h-ai/core` 的 `ok()/err()` 返回结构一致：
-
-```typescript
-import { apiContract } from '@h-ai/api-contract'
-import { z } from 'zod'
-
-const getWidget = apiContract
-  .route({ method: 'GET', path: '/widgets/{id}' })
-  .output(apiContract.haiResultSchema(z.object({
-    id: z.string(),
-    name: z.string(),
-  })))
-
-// 等价于:
-// { success: true, data: { id: string, name: string } }
-// | { success: false, error: HaiError }
-```
-
-### `apiContract.pathOf(procedure)` — 读取业务路径
-
-```typescript
-const refreshPath = apiContract.pathOf(apiContract.iam.auth.refresh)
-// '/auth/refresh'
-```
-
-middleware、client 与 E2E 需要业务路径时从 contract 元数据读取，不维护第二份 route 常量。服务端挂载时再与 `_serv.yml` 的 `http.apiPrefix` 拼接。
-
-### 公共 Schema 工具
-
-| 访问路径 | 说明 |
-| --- | --- |
-| `apiContract.haiResultSchema(dataSchema)` | `HaiResult<T>` 输出包装 |
-| `apiContract.voidResultSchema` | `HaiResult<void>` 空结果包装 |
-| `apiContract.paginatedSchema(itemSchema)` | 分页列表输出 Schema |
-| `HaiErrorSchema` | HaiError 公共字段 Schema |
-| `PaginationQuerySchema` | 分页参数 Schema（可选 page/pageSize，pageSize 上限 100；默认值由服务端处理） |
-
-## Contract 定义规范
-
-### 必须遵循
-
-- **输出必须包装为 `apiContract.haiResultSchema`** — 客户端依赖 `success` 判断成功/失败
-- **业务 path 直接写在对应 `*-contract.ts`** — 禁止新增 `*-routes.ts` 或业务路径常量
-- **一次性 `*OutputSchema` 直接内联** — 不在 schemas 文件声明或导出
-- **同一 contract 内重复使用的输出可设私有常量** — 不得为复用扩大公共导出
-- **公共 HTTP 传输配置以配置文件为准** — API 前缀、健康检查、OpenAPI/docs、密钥协商路径与跨端 Header 放在 service 的 `_serv.yml`，不放 contract 包
-- **schemas 只保留真实复用结构** — 至少被多个接口或 contract/procedure 等不同层共同消费
-- **`operationId` 全局唯一** — 格式为 `domain.resource.action`，如 `iam.auth.login`
-- **`tags` 至少包含领域名** — 供 OpenAPI 文档分组
-- **输入 Schema 用 Zod v4** — 与 `@orpc/zod/zod4` 的 `ZodToJsonSchemaConverter` 配套
-- **Contract 不含业务逻辑** — 只有 Schema + 路由元数据，没有 `async function`
-
-### 禁止
-
-- ❌ Contract 文件中 `import` 任何业务模块（`@h-ai/iam`、`@h-ai/storage` 等）
-- ❌ 在 contract 中使用 `z.any()` 或 `z.unknown()` 作为输出类型
-- ❌ 重复定义已存在的领域 contract
-- ❌ 导出只被单个 contract 接口使用的 `*OutputSchema`
-- ❌ 用独立 `*-routes.ts` 维护业务接口路径
-
-### 文件职责
-
-| 文件 | 只负责 |
-| --- | --- |
-| `*-contract.ts` | 业务接口 path、method、输入与输出边界 |
-| `*-schemas.ts` | 跨接口或跨层复用的输入、实体、数据结构 |
-| service `config/_serv.yml` | API 前缀、基础设施端点、跨端 Header 与加密 transport 配置 |
-
-## 常见模式
-
-### 带分页的列表接口
-
-```typescript
-import { apiContract, PaginationQuerySchema } from '@h-ai/api-contract'
-import { z } from 'zod'
-
-const WidgetSchema = z.object({ id: z.string(), name: z.string() })
-
-const listWidgets = apiContract
-  .route({ method: 'GET', path: '/widgets', operationId: 'widget.list', tags: ['widget'] })
-  .input(PaginationQuerySchema.extend({ keyword: z.string().optional() }))
-  .output(apiContract.haiResultSchema(apiContract.paginatedSchema(WidgetSchema)))
-```
-
-### 路径参数
-
-```typescript
-// 路径中的 {id} 对应 input 中的 id 字段
-const getWidget = apiContract
-  .route({ method: 'GET', path: '/widgets/{id}', operationId: 'widget.getById', tags: ['widget'] })
-  .input(z.object({ id: z.string() }))
-  .output(apiContract.haiResultSchema(WidgetSchema))
-```
-
-### 无输入的端点
-
-```typescript
-const versionContract = apiContract
-  .route({ method: 'GET', path: '/system/version', operationId: 'system.version', tags: ['system'] })
-  .output(apiContract.haiResultSchema(z.object({ version: z.string() })))
-```
-
-## 测试
-
-```bash
-pnpm --filter @h-ai/api-contract test
-pnpm --filter @h-ai/api-contract typecheck
-pnpm --filter @h-ai/api-contract lint
-```
+- [运行环境](reference.md#运行环境)
+- [适用场景](reference.md#适用场景)
+- [使用步骤](reference.md#使用步骤)
+- [核心 API](reference.md#核心-api)
+- [Contract 定义规范](reference.md#contract-定义规范)
+- [常见模式](reference.md#常见模式)
+- [测试](reference.md#测试)