@h-ai/api-contract 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/core](../core/README.en.md)
 
-> Public HTTP API contracts for hai-framework, with oRPC contract + Zod as the single source of truth.
+## Introduction
 
-## Capabilities
+Public HTTP API contracts for hai-framework, with oRPC contract + Zod as the single source of truth.
+
+## Core features
 
 - `apiContract.iam`, `apiContract.storage`, `apiContract.ai`, `apiContract.payment`: domain contracts.
 - `apiContract.create()`: compose enabled domain contracts for an application.
@@ -17,7 +19,11 @@
 - IAM token DTOs support httpOnly cookies: `refreshToken` may be absent from the response body and managed by the server through `Set-Cookie`.
 - IAM `auth.currentUser` returns the user profile and the current server session's `roles` / `permissions`; clients need not persist a permission snapshot to restore a session.
 
-## Quick start
+Payment creation inputs and outputs accept WeChat `jsapi`, Alipay `h5`, and Stripe `h5` only; WeChat requires `userId` (openid). App, Native, mini-program, and other combinations fail validation. Alipay returns `{ gateway, fields }` page parameters; creation success does not establish payment. See [Payment](../payment/README.en.md) for client handling.
+
+## Getting started
+
+### Quick start
 
 ```ts
 import { apiContract } from '@h-ai/api-contract'
@@ -42,7 +48,9 @@ export const appContract = {
 }
 ```
 
-## API contracts
+### API contracts
+
+For standalone contract declaration builds, this package re-exports the upstream public types `ContractProcedureBuilderWithInputOutput`, `ContractProcedureBuilderWithOutput`, and `Schema`, preserving inference for custom routes. Import explicit types from `@h-ai/api-contract` with `import type`; do not reference internal dependency installation paths.
 
 ```ts
 import { apiContract } from '@h-ai/api-contract'
@@ -54,6 +62,8 @@ myContract.storage.presignedUrls.createUpload
 myContract.ai.chats.createCompletion
 ```
 
+`ai.chats.createCompletion` is `POST /ai/chats/completions` and returns a non-streaming `HaiResult<AiChatCompletionData>`. Its strict input rejects undeclared fields, including `stream`. Function tools preserve their complete nested JSON Schema and `strict`; choices support `auto`, `none`, `required`, or a supplied function name. Role-specific messages accept text for system/assistant/tool and images for user; tool results require a nonempty `tool_call_id`, and assistants require content or `tool_calls`. Applications authorize and execute tools and define a separate contract for streaming.
+
 Clients call nested methods directly through `@h-ai/api-client`:
 
 ```ts
@@ -79,7 +89,7 @@ const app = serv.createApp({
 })
 ```
 
-## API overview
+### API overview
 
 - `apiContract.create(options)`: omit domains set to `false` / `undefined` and compose the application contract.
 - `apiContract.route(routeConfig)`: define method/path/operationId/tags and other route metadata for a custom endpoint.
@@ -87,13 +97,17 @@ const app = serv.createApp({
 - `apiContract.haiResultSchema(dataSchema)` / `apiContract.voidResultSchema` / `apiContract.paginatedSchema(itemSchema)`: shared DTO schema factories.
 - `Iam*Schema` / `Storage*Schema` / `Ai*Schema` / `Payment*Schema`: inputs and data structures reused across APIs and layers.
 
+Batch deletion via `storage.files.deleteMany` returns `{ deletedKeys, failures: [] }` on success. Failures preserve progress in `error.ext.deleteMany` (`failed / unknown / notAttempted`); HTTP 200 alone does not mean completion. See [Storage batch deletion](../storage/README.en.md#api-overview).
+
 Write each business path directly in its `*-contract.ts` file. Inline output schemas used only once in `.output(...)`; schemas reused within the same contract file may be private constants, but must not be exported from schemas.
 
-## Configuration
+### Configuration
 
 This package has no runtime configuration and does not read environment variables.
 
-## Configuration driven authentication
+### Configuration driven authentication
+
+Password login submits only `identifier` and `password`; `AuthPanel` maps the `LoginForm` field `username` to `identifier`. Server settings `session.maxAge` / `session.refreshTokenMaxAge` control session lifetimes. The login form has no per-login persistent-session option.
 
 Agreements support configuration-loaded userAgreementMarkdown/privacyPolicyMarkdown and URLs. Markdown takes priority for the same agreement and is safely rendered in a modal.
 
@@ -101,17 +115,23 @@ IAM adds GET /auth/config and POST /auth/login/ldap, /auth/password-reset/reques
 
 [完整 IAM 配置 / IAM configuration](../iam/README.en.md)
 
-## Error handling
+### Error handling
 
 Contracts describe input and output structures only. Procedures express business errors with `HaiResult<T>`, so clients need not catch business exceptions.
 
-## Tests
+## Input limits and HTTP capabilities
+
+Object keys are limited to 1024 UTF-8 bytes and reject absolute paths, backslashes, control characters and dot segments. Each public HTTP batch delete accepts 1–1000 entries. `@h-ai/storage/schemas` exposes the shared browser-safe rules. Presign expiry is an integer from 1 to 604800 seconds (Node default 3600, HTTP default 900). Upload signing accepts only key/contentType/expiresIn; contentLength/maxSize/metadata/checksum are unsupported. Invalid input returns HTTP 400 and the typed client maps it to VALIDATION_FAILED. FileUpload limits guide file selection; applications must validate actual objects on the server. Node streaming/checksum/conditional-write options have no default HTTP endpoints. See the [capability and authorization matrix (Chinese)](../storage/README.md#存储输入约束与跨端能力).
+
+## Development and testing
 
 ```bash
 pnpm --filter @h-ai/api-contract test
 pnpm --filter @h-ai/api-contract typecheck
 ```
 
+Schemas, inferred types and composition helpers include typechecked examples; see the [JSDoc conventions (Chinese)](../../.agents/instructions/module-conventions.md#jsdoc-与示例验证). Schema samples use validated local data and do not prove provider execution.
+
 ## License
 
 Apache-2.0

package/README.ja.md

@@ -4,9 +4,11 @@
 
 [フレームワークのホーム](../../README.ja.md) · 関連モジュール：[@h-ai/core](../core/README.ja.md)
 
-> hai-framework の公開 HTTP API 契約パッケージ。oRPC contract + Zod を唯一の定義元として使用します。
+## 概要
 
-## 機能概要
+hai-framework の公開 HTTP API 契約パッケージ。oRPC contract + Zod を唯一の定義元として使用します。
+
+## 主な機能
 
 - `apiContract.iam`、`apiContract.storage`、`apiContract.ai`、`apiContract.payment`：ドメイン単位の contract。
 - `apiContract.create()`：アプリケーションに必要なドメインの contract を組み合わせる。
@@ -17,7 +19,11 @@
 - IAM Token DTO は httpOnly cookie に対応。レスポンス本文に `refreshToken` が含まれない場合は、サーバーが `Set-Cookie` で管理します。
 - IAM の `auth.currentUser` はユーザー情報と現在のサーバーセッションの `roles` / `permissions` を返します。セッション復元のためにクライアントが権限のスナップショットを永続化する必要はありません。
 
-## クイックスタート
+支払い作成の入出力は WeChat `jsapi`・Alipay `h5`・Stripe `h5` のみ受け付け、WeChat は `userId`（openid）が必須です。App・Native・ミニプログラムなどは検証で拒否します。Alipay は `{ gateway, fields }` のページパラメーターを返し、作成成功は支払い完了を意味しません。クライアント処理は [Payment](../payment/README.ja.md) を参照してください。
+
+## 使い始める
+
+### クイックスタート
 
 ```ts
 import { apiContract } from '@h-ai/api-contract'
@@ -42,7 +48,9 @@ export const appContract = {
 }
 ```
 
-## API 契約
+### API 契約
+
+独立した contract パッケージの宣言ファイルを生成するため、上流の公開型 `ContractProcedureBuilderWithInputOutput`、`ContractProcedureBuilderWithOutput`、`Schema` を本パッケージから再エクスポートしています。独自ルートの入出力の型推論を維持し、明示的な型が必要な場合は `@h-ai/api-contract` から `import type` で取得してください。依存パッケージの内部インストールパスは参照しないでください。
 
 ```ts
 import { apiContract } from '@h-ai/api-contract'
@@ -54,6 +62,8 @@ myContract.storage.presignedUrls.createUpload
 myContract.ai.chats.createCompletion
 ```
 
+`ai.chats.createCompletion` は `POST /ai/chats/completions` で、非ストリーミングの `HaiResult<AiChatCompletionData>` を返します。厳密な入力 Schema は `stream` など未定義のフィールドを拒否します。function ツールのネストした JSON Schema と `strict` を保持し、選択は `auto` / `none` / `required` / 提供した関数名に対応します。system/assistant/tool はテキスト、user は画像にも対応し、ツール結果の空でない `tool_call_id`、助手の内容または `tool_calls` が必須です。アプリがツールを認可・実行し、ストリーミング用には別の契約を定義します。
+
 クライアントは `@h-ai/api-client` でネストしたメソッドを直接呼び出します：
 
 ```ts
@@ -79,7 +89,7 @@ const app = serv.createApp({
 })
 ```
 
-## API 一覧
+### API 一覧
 
 - `apiContract.create(options)`：`false` / `undefined` のドメインを除外し、アプリケーション contract を構成。
 - `apiContract.route(routeConfig)`：独自 endpoint の method/path/operationId/tags などのルートメタデータを定義。
@@ -87,13 +97,17 @@ const app = serv.createApp({
 - `apiContract.haiResultSchema(dataSchema)` / `apiContract.voidResultSchema` / `apiContract.paginatedSchema(itemSchema)`：共通 DTO Schema のファクトリー。
 - `Iam*Schema` / `Storage*Schema` / `Ai*Schema` / `Payment*Schema`：複数の API・層で再利用する入力とデータ構造。
 
+`storage.files.deleteMany` の成功データは `{ deletedKeys, failures: [] }` です。失敗進捗は `error.ext.deleteMany`（`failed / unknown / notAttempted`）にあり、HTTP 200 だけで完了と判断しません。[Storage の一括削除](../storage/README.ja.md#api-一覧)を参照してください。
+
 業務 path は対応する `*-contract.ts` に直接記述します。一度しか使わない出力 Schema は `.output(...)` にインラインで定義します。同じ contract ファイル内で再利用する場合は非公開の定数にできますが、schemas からエクスポートしてはいけません。
 
-## 設定
+### 設定
 
 このパッケージには実行時設定がなく、環境変数も読み込みません。
 
-## 設定による認証画面
+### 設定による認証画面
+
+パスワードログインの送信項目は `identifier` と `password` のみです。`AuthPanel` は `LoginForm` の `username` を `identifier` に変換します。有効期間はサーバーの `session.maxAge` / `session.refreshTokenMaxAge` で設定し、フォームにログインごとの永続セッション選択肢はありません。
 
 規約は設定の userAgreementMarkdown/privacyPolicyMarkdown または URL を使用できます。同じ規約は Markdown 本文を優先して安全な Modal で描画します。
 
@@ -101,17 +115,23 @@ IAM に公開設定、LDAP、復旧要求と確定の標準 route を追加し
 
 [完整 IAM 配置 / IAM configuration](../iam/README.ja.md)
 
-## エラー処理
+### エラー処理
 
 Contract は入出力構造のみを定義します。業務エラーは procedure が返す `HaiResult<T>` で表し、クライアント側で業務例外を捕捉する必要はありません。
 
-## テスト
+## 入力制約と HTTP 機能
+
+キーは UTF-8 で最大 1024 バイトで、絶対パス、バックスラッシュ、制御文字、ドットセグメントを拒否します。公開 HTTP 一括削除は一度に 1–1000 件です。共通規則はブラウザー対応の `@h-ai/storage/schemas` から参照できます。署名有効期限は整数 1–604800 秒（Node 既定 3600、HTTP 既定 900）。アップロード署名の入力は key/contentType/expiresIn のみで、contentLength/maxSize/metadata/checksum は未対応です。不正入力は HTTP 400、typed client では VALIDATION_FAILED です。FileUpload の制限は選択時の補助であり、実際のオブジェクトはサーバーで検証してください。Node のストリーム/checksum/条件付き書き込みには既定の HTTP エンドポイントがありません。[機能と認可の対応表（中国語）](../storage/README.md#存储输入约束与跨端能力)を参照してください。
+
+## 開発とテスト
 
 ```bash
 pnpm --filter @h-ai/api-contract test
 pnpm --filter @h-ai/api-contract typecheck
 ```
 
-## License
+Schema、推論型と組合せツールには型検査できる例があります。[JSDoc 規約（中国語）](../../.agents/instructions/module-conventions.md#jsdoc-与示例验证) を参照してください。Schema のローカル例は provider の実行証明ではありません。
+
+## ライセンス
 
 Apache-2.0

package/README.md

@@ -4,9 +4,11 @@
 
 [框架首页](../../README.md) · 相关模块：[@h-ai/core](../core/README.md)
 
-> hai-framework 的公共 HTTP API 契约包，使用 oRPC contract + Zod 作为唯一真相源。
+## 简介
 
-## 能力概览
+hai-framework 的公共 HTTP API 契约包，用 oRPC contract 和 Zod 让前后端共用接口路径、输入输出校验与类型。
+
+## 核心功能清单
 
 - `apiContract.iam`、`apiContract.storage`、`apiContract.ai`、`apiContract.payment`：领域级 contract。
 - `apiContract.create()`：按应用场景组合启用的领域 contract。
@@ -17,7 +19,11 @@
 - IAM token DTO 兼容 httpOnly cookie 模式：响应体中 `refreshToken` 可能不存在，由服务端 `Set-Cookie` 管理。
 - IAM `auth.currentUser` 返回用户资料以及服务端当前会话的 `roles` / `permissions`，客户端恢复会话时无需持久化权限快照。
 
-## 快速开始
+支付创建输入和输出仅接受微信 `jsapi`、支付宝 `h5`、Stripe `h5`；微信输入必填 `userId`（openid）。App、Native、小程序与其它组合会在输入校验时失败。支付宝输出是 `{ gateway, fields }` 页面参数，创建成功不代表支付完成；客户端处理见 [Payment](../payment/README.md)。
+
+## 使用入门
+
+### 快速开始
 
 ```ts
 import { apiContract } from '@h-ai/api-contract'
@@ -42,7 +48,9 @@ export const appContract = {
 }
 ```
 
-## API 契约
+### API 契约
+
+独立 contract 包构建声明文件时，`ContractProcedureBuilderWithInputOutput`、`ContractProcedureBuilderWithOutput` 和 `Schema` 由本包按上游真实类型公开转出，保持自定义路由的输入输出推导。需要显式类型时从 `@h-ai/api-contract` 使用 `import type`，不要引用依赖的内部安装路径。
 
 ```ts
 import { apiContract } from '@h-ai/api-contract'
@@ -54,6 +62,8 @@ myContract.storage.presignedUrls.createUpload
 myContract.ai.chats.createCompletion
 ```
 
+`ai.chats.createCompletion` 为 `POST /ai/chats/completions`，只返回非流式 `HaiResult<AiChatCompletionData>`；输入严格拒绝 `stream` 等未声明字段。function 工具保留完整嵌套 JSON Schema 和 `strict`，工具选择支持 `auto` / `none` / `required` / 已提供的函数名。消息按角色校验：system/assistant/tool 接收文本，user 另支持图片；工具结果必填非空 `tool_call_id`，助手必须包含内容或 `tool_calls`。默认工具调用由业务方授权与执行，流式能力由应用定义独立契约。
+
 客户端通过 `@h-ai/api-client` 直接调用嵌套方法：
 
 ```ts
@@ -79,7 +89,7 @@ const app = serv.createApp({
 })
 ```
 
-## API 概览
+### API 概览
 
 - `apiContract.create(options)`：过滤 `false` / `undefined` 领域并组合应用级 contract。
 - `apiContract.route(routeConfig)`：定义自定义 endpoint 的 method/path/operationId/tags 等路由元数据。
@@ -87,13 +97,17 @@ const app = serv.createApp({
 - `apiContract.haiResultSchema(dataSchema)` / `apiContract.voidResultSchema` / `apiContract.paginatedSchema(itemSchema)`：公共 DTO Schema 工厂。
 - `Iam*Schema` / `Storage*Schema` / `Ai*Schema` / `Payment*Schema`：真正跨接口、跨层复用的输入与数据结构。
 
+批量删除 `storage.files.deleteMany` 成功时返回 `{ deletedKeys, failures: [] }`；失败进度位于 `error.ext.deleteMany`（`failed / unknown / notAttempted`），不能只根据 HTTP 200 判断完成。详见 [Storage 批量删除](../storage/README.md#api-概览)。
+
 业务 path 必须直接写在对应 `*-contract.ts`。只使用一次的输出 Schema 直接内联到 `.output(...)`；同一 contract 文件内重复使用时可保留私有常量，但不得从 schemas 导出。
 
-## 配置
+### 配置
 
 本包无运行时配置，不读取环境变量。
 
-## 配置驱动认证页面
+### 配置驱动认证页面
+
+密码登录只提交 `identifier` 和 `password`；`AuthPanel` 将 `LoginForm` 的 `username` 映射为 `identifier`。会话有效期由服务端 `session.maxAge` / `session.refreshTokenMaxAge` 配置决定，登录表单不提供按次登录的持久会话选项。
 
 协议支持配置中的 userAgreementMarkdown/privacyPolicyMarkdown 正文及 URL；同主题优先 Markdown，由安全渲染器在弹窗显示。
 
@@ -101,17 +115,23 @@ const app = serv.createApp({
 
 [完整 IAM 配置 / IAM configuration](../iam/README.md)
 
-## 错误处理
+### 错误处理
 
 Contract 只描述输入输出结构。业务错误由 procedure 返回 `HaiResult<T>` 表达，客户端不需要捕获业务异常。
 
-## 测试
+## 输入约束与 HTTP 能力
+
+存储 key 按 UTF-8 最多 1024 字节，并拒绝绝对路径、反斜线、控制字符及点路径段；公开 HTTP 批量删除每次 1–1000 项。`@h-ai/storage/schemas` 提供浏览器安全的共同规则。预签名有效期为整数 1–604800 秒（Node 默认 3600，HTTP 默认 900）；HTTP 上传仅接受 key/contentType/expiresIn，不支持 contentLength/maxSize/metadata/checksum。无效输入返回 HTTP 400，typed client 映射 VALIDATION_FAILED。FileUpload 的大小/类型限制仅为前端体验，实际对象须由应用服务端复核。Node 流式读写/checksum/条件写等没有默认 HTTP 端点。完整映射与授权边界见 [存储 API 能力](../storage/README.md#存储输入约束与跨端能力)。
+
+## 开发测试
 
 ```bash
 pnpm --filter @h-ai/api-contract test
 pnpm --filter @h-ai/api-contract typecheck
 ```
 
-## License
+Schema、推导类型与组合工具均提供可类型检查的示例；见[模块 JSDoc 约定](../../.agents/instructions/module-conventions.md#jsdoc-与示例验证)。Schema 示例使用受约束的本地数据，不代表 provider 已执行。
+
+## 许可证
 
 Apache-2.0