@h-ai/storage 0.1.0-alpha.65 → 0.1.0-alpha.67

package/README.en.md

@@ -4,16 +4,20 @@
 
 [Framework home](../../README.en.md) · Related modules: [@h-ai/core](../core/README.en.md)
 
+## Introduction
+
 An object storage module with a unified `storage` entry point for S3-compatible storage and local filesystems.
 
-## Supported backends
+## Core features
 
 - S3 protocol (AWS S3 / MinIO / RustFS / OSS, etc.)
 - Local filesystem
 
-## Quick start
+## Getting started
+
+### Quick start
 
-### Node.js server
+#### Node.js server
 
 ```ts
 import { storage } from '@h-ai/storage'
@@ -44,7 +48,7 @@ if (!closeResult.success) {
 }
 ```
 
-### Browser client
+#### Browser client
 
 The browser entry exports only client capabilities (signed URL uploads/downloads), without the `storage` service object.
 
@@ -58,7 +62,7 @@ await uploadWithPresignedUrl(uploadUrl, file)
 
 > Note: `@h-ai/storage` does not include HTTP routes. Implement the signed URL API in the application layer.
 
-## HTTP API contracts
+### HTTP API contracts
 
 Public HTTP contracts come from `@h-ai/api-contract`; `createStorageProcedures({ storage })` in `@h-ai/serv` binds them to this module.
 
@@ -68,7 +72,7 @@ import { apiClient } from '@h-ai/api-client'
 const result = await apiClient.storage.presignedUrls.createUpload({ key: 'avatar.png' })
 ```
 
-## API overview
+### API overview
 
 - `storage.file`
   - `put/get/getStream/head/exists/delete/deleteMany/copy`
@@ -91,7 +95,7 @@ Cancelling a checksum stops waiting for the next chunk and requests closure of t
 
 > Note: `storage.config` returns a **redacted configuration snapshot**. S3 secret fields are replaced with `[REDACTED]`, so it cannot be used for reinitialization.
 
-## Client helpers
+### Client helpers
 
 `@h-ai/storage/client` also provides these browser utilities:
 
@@ -102,7 +106,7 @@ Cancelling a checksum stops waiting for the next chunk and requests closure of t
 - `getMimeType(extension)`
 - `formatFileSize(bytes)`
 
-## Configuration
+### Configuration
 
 - **S3**: requires `bucket / region / accessKeyId / secretAccessKey`; optional `endpoint / forcePathStyle / prefix / publicUrl`.
 - **Local**: requires `root`; optional `directoryMode / fileMode`.
@@ -124,7 +128,7 @@ if (!initResult.success) {
 }
 ```
 
-### Operation logging
+#### Operation logging
 
 Enable file, directory, and presigned URL operation logs with `operationLog`. Logs are emitted at the actual Local/S3 provider operations, without a shared wrapper in `storage-main.ts`. File contents are never logged; uploads log only the byte length.
 
@@ -156,7 +160,7 @@ await storage.init({
 
 For local storage, `storage.dir.list()` recursively scans files under the matching prefix. It supports `maxKeys` truncation but no true pagination with `continuationToken`. For large directories, narrow `prefix` or use the S3 provider's native pagination.
 
-## Error handling
+### Error handling
 
 ```ts
 import { HaiStorageError, storage } from '@h-ai/storage'
@@ -179,7 +183,7 @@ Common error codes:
 | `HaiStorageError.PRESIGN_FAILED`    | `hai:storage:013` | Presigned URL generation failed |
 | `HaiStorageError.CONFIG_ERROR`      | `hai:storage:012` | Invalid configuration           |
 
-## Tests
+## Development and testing
 
 ```bash
 pnpm --filter @h-ai/storage test

package/README.ja.md

@@ -4,16 +4,20 @@
 
 [フレームワークのホーム](../../README.ja.md) · 関連モジュール：[@h-ai/core](../core/README.ja.md)
 
+## 概要
+
 共通の `storage` 入口で S3 互換ストレージとローカルファイルシステムを操作するオブジェクトストレージモジュールです。
 
-## 対応バックエンド
+## 主な機能
 
 - S3 プロトコル（AWS S3 / MinIO / RustFS / OSS など）
 - ローカルファイルシステム
 
-## クイックスタート
+## 使い始める
+
+### クイックスタート
 
-### Node.js サーバー
+#### Node.js サーバー
 
 ```ts
 import { storage } from '@h-ai/storage'
@@ -44,7 +48,7 @@ if (!closeResult.success) {
 }
 ```
 
-### ブラウザークライアント
+#### ブラウザークライアント
 
 ブラウザー環境ではクライアント機能（署名付き URL のアップロード・ダウンロード）のみをエクスポートし、`storage` サービスオブジェクトは含みません。
 
@@ -58,7 +62,7 @@ await uploadWithPresignedUrl(uploadUrl, file)
 
 > 注：`@h-ai/storage` に HTTP ルートは組み込まれていません。署名付き URL API はアプリケーション層で実装してください。
 
-## HTTP API 契約
+### HTTP API 契約
 
 公開 HTTP API は `@h-ai/api-contract` で定義し、`@h-ai/serv` の `createStorageProcedures({ storage })` で本モジュールの機能に接続します。
 
@@ -68,7 +72,7 @@ import { apiClient } from '@h-ai/api-client'
 const result = await apiClient.storage.presignedUrls.createUpload({ key: 'avatar.png' })
 ```
 
-## API 一覧
+### API 一覧
 
 - `storage.file`
   - `put/get/getStream/head/exists/delete/deleteMany/copy`
@@ -91,7 +95,7 @@ checksum の中止時は次のチャンクを待つ処理を終了し、入力
 
 > 注：`storage.config` は**機密情報をマスクした設定スナップショット**を返します。S3 の秘密情報は `[REDACTED]` に置換され、再初期化には使用できません。
 
-## クライアントヘルパー
+### クライアントヘルパー
 
 `@h-ai/storage/client` は以下のブラウザー用ツールも提供します：
 
@@ -102,7 +106,7 @@ checksum の中止時は次のチャンクを待つ処理を終了し、入力
 - `getMimeType(extension)`
 - `formatFileSize(bytes)`
 
-## 設定
+### 設定
 
 - **S3**：`bucket / region / accessKeyId / secretAccessKey` は必須。`endpoint / forcePathStyle / prefix / publicUrl` は任意。
 - **Local**：`root` は必須。`directoryMode / fileMode` は任意。
@@ -124,7 +128,7 @@ if (!initResult.success) {
 }
 ```
 
-### 操作ログ
+#### 操作ログ
 
 `operationLog` でファイル・ディレクトリー・署名付き URL の操作ログを有効にできます。Local/S3 Provider の実際の操作箇所で出力し、`storage-main.ts` で一括ラップしません。ファイル内容は記録せず、アップロードデータはバイト数のみを記録します。
 
@@ -156,7 +160,7 @@ await storage.init({
 
 ローカルの `storage.dir.list()` は prefix に一致するファイルを再帰的に走査します。`maxKeys` による打ち切りのみ対応し、`continuationToken` による実際のページ分割はありません。大きなディレクトリーでは `prefix` を絞るか、S3 Provider のページ分割を使用してください。
 
-## エラー処理
+### エラー処理
 
 ```ts
 import { HaiStorageError, storage } from '@h-ai/storage'
@@ -179,7 +183,7 @@ if (!result.success && result.error.code === HaiStorageError.NOT_INITIALIZED.cod
 | `HaiStorageError.PRESIGN_FAILED`    | `hai:storage:013` | 署名付き URL の生成に失敗 |
 | `HaiStorageError.CONFIG_ERROR`      | `hai:storage:012` | 設定エラー                |
 
-## テスト
+## 開発とテスト
 
 ```bash
 pnpm --filter @h-ai/storage test
@@ -192,6 +196,6 @@ S3 統合テストには Docker または互換ランタイムが必要です。
 
 コンテナーは一時生成したテスト認証情報を使用します。サービスの準備完了後に S3 API でバケットを作成し、最後のリース解放時にコンテナーと匿名ボリュームを削除します。
 
-## License
+## ライセンス
 
 Apache-2.0

package/README.md

@@ -4,16 +4,20 @@
 
 [框架首页](../../README.md) · 相关模块：[@h-ai/core](../core/README.md)
 
+## 简介
+
 对象存储模块，提供统一 `storage` 访问入口，支持 S3 兼容存储与本地文件系统。
 
-## 支持的后端
+## 核心功能清单
 
 - S3 协议（AWS S3 / MinIO / RustFS / OSS 等）
 - 本地文件系统
 
-## 快速开始
+## 使用入门
+
+### 快速开始
 
-### Node.js 服务端
+#### Node.js 服务端
 
 ```ts
 import { storage } from '@h-ai/storage'
@@ -44,7 +48,7 @@ if (!closeResult.success) {
 }
 ```
 
-### 浏览器客户端
+#### 浏览器客户端
 
 浏览器环境下仅导出客户端能力（签名 URL 上传/下载），不包含 `storage` 服务对象。
 
@@ -58,7 +62,7 @@ await uploadWithPresignedUrl(uploadUrl, file)
 
 > 注意：`@h-ai/storage` 不内置 HTTP 路由；请在应用层自行实现签名 URL API。
 
-## HTTP API 契约
+### HTTP API 契约
 
 公共 HTTP API 统一由 `@h-ai/api-contract` 提供，并由 `@h-ai/serv` 的 `createStorageProcedures({ storage })` 绑定到本模块能力。
 
@@ -68,7 +72,7 @@ import { apiClient } from '@h-ai/api-client'
 const result = await apiClient.storage.presignedUrls.createUpload({ key: 'avatar.png' })
 ```
 
-## API 概览
+### API 概览
 
 - `storage.file`
   - `put/get/getStream/head/exists/delete/deleteMany/copy`
@@ -91,7 +95,7 @@ const result = await apiClient.storage.presignedUrls.createUpload({ key: 'avatar
 
 > 注意：`storage.config` 返回的是**脱敏配置快照**；S3 密钥类字段会被替换为 `[REDACTED]`，不能用于重新初始化。
 
-## 客户端辅助函数
+### 客户端辅助函数
 
 `@h-ai/storage/client` 还提供以下浏览器侧工具：
 
@@ -102,7 +106,7 @@ const result = await apiClient.storage.presignedUrls.createUpload({ key: 'avatar
 - `getMimeType(extension)`
 - `formatFileSize(bytes)`
 
-## 配置
+### 配置
 
 - **S3**：`bucket / region / accessKeyId / secretAccessKey` 必填，可选 `endpoint / forcePathStyle / prefix / publicUrl`
 - **Local**：`root` 必填，可选 `directoryMode / fileMode`
@@ -124,7 +128,7 @@ if (!initResult.success) {
 }
 ```
 
-### 操作日志
+#### 操作日志
 
 可在存储配置中通过 `operationLog` 开启文件、目录和预签名 URL 操作日志。日志在 Local/S3 Provider 的真实操作处输出，不在 `storage-main.ts` 中做统一包装；文件内容不会写入日志，上传数据只记录字节长度。
 
@@ -156,7 +160,7 @@ await storage.init({
 
 本地存储的 `storage.dir.list()` 会递归扫描匹配前缀下的文件，仅支持 `maxKeys` 截断，不支持 `continuationToken` 真分页；大目录场景建议优先使用更窄的 `prefix`，或改用 S3 Provider 获取原生分页能力。
 
-## 错误处理
+### 错误处理
 
 ```ts
 import { HaiStorageError, storage } from '@h-ai/storage'
@@ -179,7 +183,7 @@ if (!result.success && result.error.code === HaiStorageError.NOT_INITIALIZED.cod
 | `HaiStorageError.PRESIGN_FAILED`    | `hai:storage:013` | 预签名 URL 生成失败 |
 | `HaiStorageError.CONFIG_ERROR`      | `hai:storage:012` | 配置错误            |
 
-## 测试
+## 开发测试
 
 ```bash
 pnpm --filter @h-ai/storage test
@@ -192,6 +196,6 @@ S3 集成测试需要可用的 Docker 或兼容运行时；同一套初始化、
 
 容器使用临时生成的测试凭据，等待服务就绪后通过 S3 API 建桶；最后一个租约释放时移除容器及匿名卷。
 
-## License
+## 许可证
 
 Apache-2.0

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@h-ai/storage",
   "type": "module",
-  "version": "0.1.0-alpha.65",
+  "version": "0.1.0-alpha.67",
   "description": "Hai Framework object storage module for S3-compatible and local backends.",
   "license": "Apache-2.0",
   "exports": {
@@ -32,7 +32,7 @@
     "@aws-sdk/client-s3": "^3.1149.0",
     "@aws-sdk/lib-storage": "^3.1149.0",
     "@aws-sdk/s3-request-presigner": "^3.1149.0",
-    "@h-ai/core": "0.1.0-alpha.65",
+    "@h-ai/core": "0.1.0-alpha.67",
     "zod": "^4.6.5"
   },
   "devDependencies": {