@h-ai/api-contract 0.1.0-alpha.66 → 0.1.0-alpha.67

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,9 @@
 - 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
+## Getting started
+
+### Quick start
 
 ```ts
 import { apiContract } from '@h-ai/api-contract'
@@ -42,7 +46,7 @@ export const appContract = {
 }
 ```
 
-## API contracts
+### API contracts
 
 ```ts
 import { apiContract } from '@h-ai/api-contract'
@@ -79,7 +83,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.
@@ -89,11 +93,11 @@ const app = serv.createApp({
 
 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
 
 Agreements support configuration-loaded userAgreementMarkdown/privacyPolicyMarkdown and URLs. Markdown takes priority for the same agreement and is safely rendered in a modal.
 
@@ -101,11 +105,11 @@ 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
+## Development and testing
 
 ```bash
 pnpm --filter @h-ai/api-contract test

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,9 @@
 - IAM Token DTO は httpOnly cookie に対応。レスポンス本文に `refreshToken` が含まれない場合は、サーバーが `Set-Cookie` で管理します。
 - IAM の `auth.currentUser` はユーザー情報と現在のサーバーセッションの `roles` / `permissions` を返します。セッション復元のためにクライアントが権限のスナップショットを永続化する必要はありません。
 
-## クイックスタート
+## 使い始める
+
+### クイックスタート
 
 ```ts
 import { apiContract } from '@h-ai/api-contract'
@@ -42,7 +46,7 @@ export const appContract = {
 }
 ```
 
-## API 契約
+### API 契約
 
 ```ts
 import { apiContract } from '@h-ai/api-contract'
@@ -79,7 +83,7 @@ const app = serv.createApp({
 })
 ```
 
-## API 一覧
+### API 一覧
 
 - `apiContract.create(options)`：`false` / `undefined` のドメインを除外し、アプリケーション contract を構成。
 - `apiContract.route(routeConfig)`：独自 endpoint の method/path/operationId/tags などのルートメタデータを定義。
@@ -89,11 +93,11 @@ const app = serv.createApp({
 
 業務 path は対応する `*-contract.ts` に直接記述します。一度しか使わない出力 Schema は `.output(...)` にインラインで定義します。同じ contract ファイル内で再利用する場合は非公開の定数にできますが、schemas からエクスポートしてはいけません。
 
-## 設定
+### 設定
 
 このパッケージには実行時設定がなく、環境変数も読み込みません。
 
-## 設定による認証画面
+### 設定による認証画面
 
 規約は設定の userAgreementMarkdown/privacyPolicyMarkdown または URL を使用できます。同じ規約は Markdown 本文を優先して安全な Modal で描画します。
 
@@ -101,17 +105,17 @@ IAM に公開設定、LDAP、復旧要求と確定の標準 route を追加し
 
 [完整 IAM 配置 / IAM configuration](../iam/README.ja.md)
 
-## エラー処理
+### エラー処理
 
 Contract は入出力構造のみを定義します。業務エラーは procedure が返す `HaiResult<T>` で表し、クライアント側で業務例外を捕捉する必要はありません。
 
-## テスト
+## 開発とテスト
 
 ```bash
 pnpm --filter @h-ai/api-contract test
 pnpm --filter @h-ai/api-contract typecheck
 ```
 
-## License
+## ライセンス
 
 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,9 @@
 - IAM token DTO 兼容 httpOnly cookie 模式：响应体中 `refreshToken` 可能不存在，由服务端 `Set-Cookie` 管理。
 - IAM `auth.currentUser` 返回用户资料以及服务端当前会话的 `roles` / `permissions`，客户端恢复会话时无需持久化权限快照。
 
-## 快速开始
+## 使用入门
+
+### 快速开始
 
 ```ts
 import { apiContract } from '@h-ai/api-contract'
@@ -42,7 +46,7 @@ export const appContract = {
 }
 ```
 
-## API 契约
+### API 契约
 
 ```ts
 import { apiContract } from '@h-ai/api-contract'
@@ -79,7 +83,7 @@ const app = serv.createApp({
 })
 ```
 
-## API 概览
+### API 概览
 
 - `apiContract.create(options)`：过滤 `false` / `undefined` 领域并组合应用级 contract。
 - `apiContract.route(routeConfig)`：定义自定义 endpoint 的 method/path/operationId/tags 等路由元数据。
@@ -89,11 +93,11 @@ const app = serv.createApp({
 
 业务 path 必须直接写在对应 `*-contract.ts`。只使用一次的输出 Schema 直接内联到 `.output(...)`；同一 contract 文件内重复使用时可保留私有常量，但不得从 schemas 导出。
 
-## 配置
+### 配置
 
 本包无运行时配置，不读取环境变量。
 
-## 配置驱动认证页面
+### 配置驱动认证页面
 
 协议支持配置中的 userAgreementMarkdown/privacyPolicyMarkdown 正文及 URL；同主题优先 Markdown，由安全渲染器在弹窗显示。
 
@@ -101,17 +105,17 @@ const app = serv.createApp({
 
 [完整 IAM 配置 / IAM configuration](../iam/README.md)
 
-## 错误处理
+### 错误处理
 
 Contract 只描述输入输出结构。业务错误由 procedure 返回 `HaiResult<T>` 表达，客户端不需要捕获业务异常。
 
-## 测试
+## 开发测试
 
 ```bash
 pnpm --filter @h-ai/api-contract test
 pnpm --filter @h-ai/api-contract typecheck
 ```
 
-## License
+## 许可证
 
 Apache-2.0

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@h-ai/api-contract",
   "type": "module",
-  "version": "0.1.0-alpha.66",
+  "version": "0.1.0-alpha.67",
   "description": "Hai Framework public API contracts powered by oRPC and Zod.",
   "license": "Apache-2.0",
   "exports": {
@@ -39,7 +39,7 @@
     "node": "^22.22.2 || ^24.15.0 || >=26.0.0"
   },
   "dependencies": {
-    "@h-ai/core": "0.1.0-alpha.66",
+    "@h-ai/core": "0.1.0-alpha.67",
     "@orpc/contract": "^1.15.5",
     "zod": "^4.6.5"
   },