@h-ai/storage 0.1.0-alpha5

package/LICENSE

@@ -0,0 +1,202 @@
+
+                                 Apache License
+                           Version 2.0, January 2004
+                        http://www.apache.org/licenses/
+
+   TERMS AND CONDITIONS FOR USE, REPRODUCTION, AND DISTRIBUTION
+
+   1. Definitions.
+
+      "License" shall mean the terms and conditions for use, reproduction,
+      and distribution as defined by Sections 1 through 9 of this document.
+
+      "Licensor" shall mean the copyright owner or entity authorized by
+      the copyright owner that is granting the License.
+
+      "Legal Entity" shall mean the union of the acting entity and all
+      other entities that control, are controlled by, or are under common
+      control with that entity. For the purposes of this definition,
+      "control" means (i) the power, direct or indirect, to cause the
+      direction or management of such entity, whether by contract or
+      otherwise, or (ii) ownership of fifty percent (50%) or more of the
+      outstanding shares, or (iii) beneficial ownership of such entity.
+
+      "You" (or "Your") shall mean an individual or Legal Entity
+      exercising permissions granted by this License.
+
+      "Source" form shall mean the preferred form for making modifications,
+      including but not limited to software source code, documentation
+      source, and configuration files.
+
+      "Object" form shall mean any form resulting from mechanical
+      transformation or translation of a Source form, including but
+      not limited to compiled object code, generated documentation,
+      and conversions to other media types.
+
+      "Work" shall mean the work of authorship, whether in Source or
+      Object form, made available under the License, as indicated by a
+      copyright notice that is included in or attached to the work
+      (an example is provided in the Appendix below).
+
+      "Derivative Works" shall mean any work, whether in Source or Object
+      form, that is based on (or derived from) the Work and for which the
+      editorial revisions, annotations, elaborations, or other modifications
+      represent, as a whole, an original work of authorship. For the purposes
+      of this License, Derivative Works shall not include works that remain
+      separable from, or merely link (or bind by name) to the interfaces of,
+      the Work and Derivative Works thereof.
+
+      "Contribution" shall mean any work of authorship, including
+      the original version of the Work and any modifications or additions
+      to that Work or Derivative Works thereof, that is intentionally
+      submitted to Licensor for inclusion in the Work by the copyright owner
+      or by an individual or Legal Entity authorized to submit on behalf of
+      the copyright owner. For the purposes of this definition, "submitted"
+      means any form of electronic, verbal, or written communication sent
+      to the Licensor or its representatives, including but not limited to
+      communication on electronic mailing lists, source code control systems,
+      and issue tracking systems that are managed by, or on behalf of, the
+      Licensor for the purpose of discussing and improving the Work, but
+      excluding communication that is conspicuously marked or otherwise
+      designated in writing by the copyright owner as "Not a Contribution."
+
+      "Contributor" shall mean Licensor and any individual or Legal Entity
+      on behalf of whom a Contribution has been received by Licensor and
+      subsequently incorporated within the Work.
+
+   2. Grant of Copyright License. Subject to the terms and conditions of
+      this License, each Contributor hereby grants to You a perpetual,
+      worldwide, non-exclusive, no-charge, royalty-free, irrevocable
+      copyright license to reproduce, prepare Derivative Works of,
+      publicly display, publicly perform, sublicense, and distribute the
+      Work and such Derivative Works in Source or Object form.
+
+   3. Grant of Patent License. Subject to the terms and conditions of
+      this License, each Contributor hereby grants to You a perpetual,
+      worldwide, non-exclusive, no-charge, royalty-free, irrevocable
+      (except as stated in this section) patent license to make, have made,
+      use, offer to sell, sell, import, and otherwise transfer the Work,
+      where such license applies only to those patent claims licensable
+      by such Contributor that are necessarily infringed by their
+      Contribution(s) alone or by combination of their Contribution(s)
+      with the Work to which such Contribution(s) was submitted. If You
+      institute patent litigation against any entity (including a
+      cross-claim or counterclaim in a lawsuit) alleging that the Work
+      or a Contribution incorporated within the Work constitutes direct
+      or contributory patent infringement, then any patent licenses
+      granted to You under this License for that Work shall terminate
+      as of the date such litigation is filed.
+
+   4. Redistribution. You may reproduce and distribute copies of the
+      Work or Derivative Works thereof in any medium, with or without
+      modifications, and in Source or Object form, provided that You
+      meet the following conditions:
+
+      (a) You must give any other recipients of the Work or
+          Derivative Works a copy of this License; and
+
+      (b) You must cause any modified files to carry prominent notices
+          stating that You changed the files; and
+
+      (c) You must retain, in the Source form of any Derivative Works
+          that You distribute, all copyright, patent, trademark, and
+          attribution notices from the Source form of the Work,
+          excluding those notices that do not pertain to any part of
+          the Derivative Works; and
+
+      (d) If the Work includes a "NOTICE" text file as part of its
+          distribution, then any Derivative Works that You distribute must
+          include a readable copy of the attribution notices contained
+          within such NOTICE file, excluding those notices that do not
+          pertain to any part of the Derivative Works, in at least one
+          of the following places: within a NOTICE text file distributed
+          as part of the Derivative Works; within the Source form or
+          documentation, if provided along with the Derivative Works; or,
+          within a display generated by the Derivative Works, if and
+          wherever such third-party notices normally appear. The contents
+          of the NOTICE file are for informational purposes only and
+          do not modify the License. You may add Your own attribution
+          notices within Derivative Works that You distribute, alongside
+          or as an addendum to the NOTICE text from the Work, provided
+          that such additional attribution notices cannot be construed
+          as modifying the License.
+
+      You may add Your own copyright statement to Your modifications and
+      may provide additional or different license terms and conditions
+      for use, reproduction, or distribution of Your modifications, or
+      for any such Derivative Works as a whole, provided Your use,
+      reproduction, and distribution of the Work otherwise complies with
+      the conditions stated in this License.
+
+   5. Submission of Contributions. Unless You explicitly state otherwise,
+      any Contribution intentionally submitted for inclusion in the Work
+      by You to the Licensor shall be under the terms and conditions of
+      this License, without any additional terms or conditions.
+      Notwithstanding the above, nothing herein shall supersede or modify
+      the terms of any separate license agreement you may have executed
+      with Licensor regarding such Contributions.
+
+   6. Trademarks. This License does not grant permission to use the trade
+      names, trademarks, service marks, or product names of the Licensor,
+      except as required for reasonable and customary use in describing the
+      origin of the Work and reproducing the content of the NOTICE file.
+
+   7. Disclaimer of Warranty. Unless required by applicable law or
+      agreed to in writing, Licensor provides the Work (and each
+      Contributor provides its Contributions) on an "AS IS" BASIS,
+      WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or
+      implied, including, without limitation, any warranties or conditions
+      of TITLE, NON-INFRINGEMENT, MERCHANTABILITY, or FITNESS FOR A
+      PARTICULAR PURPOSE. You are solely responsible for determining the
+      appropriateness of using or redistributing the Work and assume any
+      risks associated with Your exercise of permissions under this License.
+
+   8. Limitation of Liability. In no event and under no legal theory,
+      whether in tort (including negligence), contract, or otherwise,
+      unless required by applicable law (such as deliberate and grossly
+      negligent acts) or agreed to in writing, shall any Contributor be
+      liable to You for damages, including any direct, indirect, special,
+      incidental, or consequential damages of any character arising as a
+      result of this License or out of the use or inability to use the
+      Work (including but not limited to damages for loss of goodwill,
+      work stoppage, computer failure or malfunction, or any and all
+      other commercial damages or losses), even if such Contributor
+      has been advised of the possibility of such damages.
+
+   9. Accepting Warranty or Additional Liability. While redistributing
+      the Work or Derivative Works thereof, You may choose to offer,
+      and charge a fee for, acceptance of support, warranty, indemnity,
+      or other liability obligations and/or rights consistent with this
+      License. However, in accepting such obligations, You may act only
+      on Your own behalf and on Your sole responsibility, not on behalf
+      of any other Contributor, and only if You agree to indemnify,
+      defend, and hold each Contributor harmless for any liability
+      incurred by, or claims asserted against, such Contributor by reason
+      of your accepting any such warranty or additional liability.
+
+   END OF TERMS AND CONDITIONS
+
+   APPENDIX: How to apply the Apache License to your work.
+
+      To apply the Apache License to your work, attach the following
+      boilerplate notice, with the fields enclosed by brackets "[]"
+      replaced with your own identifying information. (Don't include
+      the brackets!)  The text should be enclosed in the appropriate
+      comment syntax for the file format. We also recommend that a
+      file or class name and description of purpose be included on the
+      same "printed page" as the copyright notice for easier
+      identification within third-party archives.
+
+   Copyright [2026] [idealworld.group]
+
+   Licensed under the Apache License, Version 2.0 (the "License");
+   you may not use this file except in compliance with the License.
+   You may obtain a copy of the License at
+
+       http://www.apache.org/licenses/LICENSE-2.0
+
+   Unless required by applicable law or agreed to in writing, software
+   distributed under the License is distributed on an "AS IS" BASIS,
+   WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+   See the License for the specific language governing permissions and
+   limitations under the License.

package/README.md

@@ -0,0 +1,151 @@
+# @h-ai/storage
+
+对象存储模块，提供统一 `storage` 访问入口，支持 S3 兼容存储与本地文件系统。
+
+## 支持的后端
+
+- S3 协议（AWS S3 / MinIO / OSS 等）
+- 本地文件系统
+
+## 快速开始
+
+### Node.js 服务端
+
+```ts
+import { storage } from '@h-ai/storage'
+
+// 初始化（S3）
+await storage.init({
+  type: 's3',
+  bucket: 'my-bucket',
+  region: 'us-east-1',
+  accessKeyId: process.env.HAI_STORAGE_S3_ACCESS_KEY!,
+  secretAccessKey: process.env.HAI_STORAGE_S3_SECRET_KEY!,
+})
+
+// 或本地存储
+await storage.init({ type: 'local', root: '/data/uploads' })
+
+// 上传/下载
+await storage.file.put('uploads/image.png', imageBuffer, { contentType: 'image/png' })
+const file = await storage.file.get('uploads/image.png')
+
+// 签名 URL
+const url = await storage.presign.getUrl('uploads/image.png', { expiresIn: 3600 })
+
+// 关闭连接
+await storage.close()
+```
+
+### 浏览器客户端
+
+浏览器环境下仅导出客户端能力（签名 URL 上传/下载），不包含 `storage` 服务对象。
+
+```ts
+import { downloadAndSave, uploadWithPresignedUrl } from '@h-ai/storage/client'
+
+// 业务端点路径由应用自行定义（例如 /api/files/presign-put）
+const { uploadUrl } = await fetch('/api/files/presign-put').then(r => r.json())
+await uploadWithPresignedUrl(uploadUrl, file)
+```
+
+> 注意：`@h-ai/storage` 不内置 HTTP 路由；请在应用层自行实现签名 URL API。
+
+## API 契约（`@h-ai/storage/api`）
+
+独立子路径 `@h-ai/storage/api` 导出所有存储端点的 Zod Schema 和端点契约定义，客户端和服务端共享同一份类型定义，编译时保证 I/O 一致性。
+
+```ts
+import { PresignPutInputSchema, storageEndpoints } from '@h-ai/storage/api'
+
+// 端点契约包含 6 个端点：
+// presignDownload / presignUpload / fileInfo / listFiles / deleteFile / deleteFiles
+
+// 客户端调用
+const { url } = await api.call(storageEndpoints.presignUpload, { key: 'avatar.png' })
+
+// 服务端路由
+export const POST = kit.fromContract(storageEndpoints.presignUpload, async (input) => {
+  const result = await storage.presign.putUrl(input.key, input)
+  return result.success ? result.data : kit.response.internalError(result.error.message)
+})
+
+// 独立使用 Schema 做校验
+const parsed = PresignPutInputSchema.safeParse(requestBody)
+if (!parsed.success) { /* 校验失败 */ }
+```
+
+**导出的 Schema：**
+
+- `FileMetadataSchema` — 文件元数据
+- `PresignGetInputSchema` / `PresignPutInputSchema` — 签名 URL 入参
+- `PresignUrlOutputSchema` — 签名 URL 出参
+- `ListFilesOutputSchema` — 文件列表出参
+- `DeleteFileInputSchema` / `DeleteFilesInputSchema` — 删除入参
+- `FileInfoInputSchema` — 文件信息入参
+
+**导出的类型（从 Schema 推导）：**
+
+`PresignGetInput` / `PresignPutInput` / `PresignUrlOutput` / `ListFilesOutput` / `DeleteFileInput` / `DeleteFilesInput` / `FileInfoInput`
+
+## API 概览
+
+- `storage.file`
+  - `put/get/head/exists/delete/deleteMany/copy`
+- `storage.dir`
+  - `list/delete`
+- `storage.presign`
+  - `getUrl/putUrl/publicUrl`
+
+> 注意：`publicUrl` 仅在 S3 配置了 `publicUrl` 时返回字符串；否则返回 `null`。
+
+## 客户端辅助函数
+
+`@h-ai/storage/client` 还提供以下浏览器侧工具：
+
+- `uploadWithPresignedUrl(url, data, options)`
+- `downloadWithPresignedUrl(url, options)`
+- `downloadAndSave(url, { filename })`
+- `getFileExtension(file)`
+- `getMimeType(extension)`
+- `formatFileSize(bytes)`
+
+## 配置
+
+- **S3**：`bucket / region / accessKeyId / secretAccessKey` 必填，可选 `endpoint / forcePathStyle / prefix / publicUrl`
+- **Local**：`root` 必填，可选 `directoryMode / fileMode`
+
+## 错误处理
+
+```ts
+import { HaiStorageError, storage } from '@h-ai/storage'
+
+const result = await storage.file.get('image.png')
+if (!result.success && result.error.code === HaiStorageError.NOT_INITIALIZED.code) {
+  // 存储未初始化
+}
+```
+
+常用错误码：
+
+| 错误码                              | code              | 说明                |
+| ----------------------------------- | ----------------- | ------------------- |
+| `HaiStorageError.NOT_INITIALIZED`   | `hai:storage:010` | 未初始化            |
+| `HaiStorageError.CONNECTION_FAILED` | `hai:storage:001` | 连接失败            |
+| `HaiStorageError.OPERATION_FAILED`  | `hai:storage:002` | 操作失败            |
+| `HaiStorageError.NOT_FOUND`         | `hai:storage:003` | 文件不存在          |
+| `HaiStorageError.PERMISSION_DENIED` | `hai:storage:005` | 权限不足            |
+| `HaiStorageError.PRESIGN_FAILED`    | `hai:storage:013` | 预签名 URL 生成失败 |
+| `HaiStorageError.CONFIG_ERROR`      | `hai:storage:012` | 配置错误            |
+
+## 测试
+
+```bash
+pnpm --filter @h-ai/storage test
+```
+
+> MinIO/S3 相关测试需要 Docker 环境。
+
+## License
+
+Apache-2.0

package/dist/api/index.d.ts

@@ -0,0 +1,167 @@
+import { z } from 'zod';
+
+/**
+ * @h-ai/storage/api — 存储 API 端点契约定义
+ *
+ * 所有 storage 模块的 API 端点（path + method + schema），
+ * 客户端和服务端都从此处引用，编译时保证一致性。
+ * @module storage-api-contract
+ */
+
+interface EndpointDef<TInput = unknown, TOutput = unknown> {
+    method: 'GET' | 'POST' | 'PUT' | 'DELETE' | 'PATCH';
+    path: string;
+    input: z.ZodType<TInput>;
+    output: z.ZodType<TOutput>;
+    requireAuth?: boolean;
+    meta?: {
+        summary?: string;
+        tags?: string[];
+    };
+}
+/**
+ * storage 所有 API 端点
+ *
+ * @example
+ * ```ts
+ * // 客户端
+ * import { storageEndpoints } from '@h-ai/storage/api'
+ * const { url } = await api.call(storageEndpoints.presignUpload, { key: 'avatar.png' })
+ *
+ * // 服务端
+ * export const POST = kit.fromContract(storageEndpoints.presignUpload, async (input) => {
+ *   const result = await storage.presign.putUrl(input.key, input)
+ *   return result.success ? result.data : kit.response.internalError(result.error.message)
+ * })
+ * ```
+ */
+declare const storageEndpoints: {
+    /** 获取下载签名 URL */
+    readonly presignDownload: EndpointDef<{
+        key: string;
+        expiresIn?: number | undefined;
+    }, {
+        url: string;
+        key: string;
+        expiresAt?: Date | undefined;
+    }>;
+    /** 获取上传签名 URL */
+    readonly presignUpload: EndpointDef<{
+        key: string;
+        contentType?: string | undefined;
+        contentLength?: number | undefined;
+        expiresIn?: number | undefined;
+    }, {
+        url: string;
+        key: string;
+        expiresAt?: Date | undefined;
+    }>;
+    /** 获取文件元数据 */
+    readonly fileInfo: EndpointDef<{
+        key: string;
+    }, {
+        key: string;
+        size: number;
+        contentType: string;
+        lastModified: Date;
+        etag?: string | undefined;
+        metadata?: Record<string, string> | undefined;
+    }>;
+    /** 列出文件 */
+    readonly listFiles: EndpointDef<{
+        prefix?: string | undefined;
+        maxKeys?: number | undefined;
+        continuationToken?: string | undefined;
+        delimiter?: string | undefined;
+    }, {
+        files: {
+            key: string;
+            size: number;
+            contentType: string;
+            lastModified: Date;
+            etag?: string | undefined;
+            metadata?: Record<string, string> | undefined;
+        }[];
+        commonPrefixes: string[];
+        isTruncated: boolean;
+        nextContinuationToken?: string | undefined;
+    }>;
+    /** 删除单个文件 */
+    readonly deleteFile: EndpointDef<{
+        key: string;
+    }, void>;
+    /** 批量删除文件 */
+    readonly deleteFiles: EndpointDef<{
+        keys: string[];
+    }, void>;
+};
+
+/**
+ * @h-ai/storage/api — 存储 API 契约 Schema
+ *
+ * 入参/出参 Schema，客户端和服务端共享的唯一真相源。
+ * @module storage-api-schemas
+ */
+
+/** 文件元数据 Schema */
+declare const FileMetadataSchema: z.ZodObject<{
+    key: z.ZodString;
+    size: z.ZodNumber;
+    contentType: z.ZodString;
+    lastModified: z.ZodCoercedDate<unknown>;
+    etag: z.ZodOptional<z.ZodString>;
+    metadata: z.ZodOptional<z.ZodRecord<z.ZodString, z.ZodString>>;
+}, z.core.$strip>;
+/** 获取下载签名 URL 入参 */
+declare const PresignGetInputSchema: z.ZodObject<{
+    key: z.ZodString;
+    expiresIn: z.ZodOptional<z.ZodNumber>;
+}, z.core.$strip>;
+/** 获取上传签名 URL 入参 */
+declare const PresignPutInputSchema: z.ZodObject<{
+    key: z.ZodString;
+    contentType: z.ZodOptional<z.ZodString>;
+    contentLength: z.ZodOptional<z.ZodNumber>;
+    expiresIn: z.ZodOptional<z.ZodNumber>;
+}, z.core.$strip>;
+/** 签名 URL 出参 */
+declare const PresignUrlOutputSchema: z.ZodObject<{
+    url: z.ZodString;
+    key: z.ZodString;
+    expiresAt: z.ZodOptional<z.ZodCoercedDate<unknown>>;
+}, z.core.$strip>;
+/** 文件列表出参 */
+declare const ListFilesOutputSchema: z.ZodObject<{
+    files: z.ZodArray<z.ZodObject<{
+        key: z.ZodString;
+        size: z.ZodNumber;
+        contentType: z.ZodString;
+        lastModified: z.ZodCoercedDate<unknown>;
+        etag: z.ZodOptional<z.ZodString>;
+        metadata: z.ZodOptional<z.ZodRecord<z.ZodString, z.ZodString>>;
+    }, z.core.$strip>>;
+    commonPrefixes: z.ZodArray<z.ZodString>;
+    nextContinuationToken: z.ZodOptional<z.ZodString>;
+    isTruncated: z.ZodBoolean;
+}, z.core.$strip>;
+/** 删除文件入参 */
+declare const DeleteFileInputSchema: z.ZodObject<{
+    key: z.ZodString;
+}, z.core.$strip>;
+/** 批量删除文件入参 */
+declare const DeleteFilesInputSchema: z.ZodObject<{
+    keys: z.ZodArray<z.ZodString>;
+}, z.core.$strip>;
+/** 获取文件信息入参 */
+declare const FileInfoInputSchema: z.ZodObject<{
+    key: z.ZodString;
+}, z.core.$strip>;
+type PresignGetInput = z.infer<typeof PresignGetInputSchema>;
+type PresignPutInput = z.infer<typeof PresignPutInputSchema>;
+type PresignUrlOutput = z.infer<typeof PresignUrlOutputSchema>;
+type ListFilesOutput = z.infer<typeof ListFilesOutputSchema>;
+type DeleteFileInput = z.infer<typeof DeleteFileInputSchema>;
+type DeleteFilesInput = z.infer<typeof DeleteFilesInputSchema>;
+type FileInfoInput = z.infer<typeof FileInfoInputSchema>;
+
+export { type DeleteFileInput, DeleteFileInputSchema, type DeleteFilesInput, DeleteFilesInputSchema, type FileInfoInput, FileInfoInputSchema, FileMetadataSchema, type ListFilesOutput, ListFilesOutputSchema, type PresignGetInput, PresignGetInputSchema, type PresignPutInput, PresignPutInputSchema, type PresignUrlOutput, PresignUrlOutputSchema, storageEndpoints };

package/dist/api/index.js

@@ -0,0 +1,105 @@
+import { z } from 'zod';
+
+// src/api/storage-api-contract.ts
+var FileMetadataSchema = z.object({
+  key: z.string(),
+  size: z.number(),
+  contentType: z.string(),
+  lastModified: z.coerce.date(),
+  etag: z.string().optional(),
+  metadata: z.record(z.string(), z.string()).optional()
+});
+var PresignGetInputSchema = z.object({
+  key: z.string().min(1),
+  expiresIn: z.number().int().min(1).optional()
+});
+var PresignPutInputSchema = z.object({
+  key: z.string().min(1),
+  contentType: z.string().optional(),
+  contentLength: z.number().int().min(1).optional(),
+  expiresIn: z.number().int().min(1).optional()
+});
+var PresignUrlOutputSchema = z.object({
+  url: z.string(),
+  key: z.string(),
+  expiresAt: z.coerce.date().optional()
+});
+var ListFilesOutputSchema = z.object({
+  files: z.array(FileMetadataSchema),
+  commonPrefixes: z.array(z.string()),
+  nextContinuationToken: z.string().optional(),
+  isTruncated: z.boolean()
+});
+var DeleteFileInputSchema = z.object({
+  key: z.string().min(1)
+});
+var DeleteFilesInputSchema = z.object({
+  keys: z.array(z.string().min(1)).min(1)
+});
+var FileInfoInputSchema = z.object({
+  key: z.string().min(1)
+});
+
+// src/api/storage-api-contract.ts
+function defineEndpoint(def) {
+  return def;
+}
+var storageEndpoints = {
+  /** 获取下载签名 URL */
+  presignDownload: defineEndpoint({
+    method: "POST",
+    path: "/storage/presign/download",
+    input: PresignGetInputSchema,
+    output: PresignUrlOutputSchema,
+    meta: { summary: "Get presigned download URL", tags: ["storage"] }
+  }),
+  /** 获取上传签名 URL */
+  presignUpload: defineEndpoint({
+    method: "POST",
+    path: "/storage/presign/upload",
+    input: PresignPutInputSchema,
+    output: PresignUrlOutputSchema,
+    meta: { summary: "Get presigned upload URL", tags: ["storage"] }
+  }),
+  /** 获取文件元数据 */
+  fileInfo: defineEndpoint({
+    method: "POST",
+    path: "/storage/file/info",
+    input: FileInfoInputSchema,
+    output: FileMetadataSchema,
+    meta: { summary: "Get file metadata", tags: ["storage"] }
+  }),
+  /** 列出文件 */
+  listFiles: defineEndpoint({
+    method: "GET",
+    path: "/storage/files",
+    input: z.object({
+      prefix: z.string().optional(),
+      maxKeys: z.coerce.number().int().min(1).max(1e3).optional(),
+      continuationToken: z.string().optional(),
+      delimiter: z.string().optional()
+    }),
+    output: ListFilesOutputSchema,
+    meta: { summary: "List files by prefix", tags: ["storage"] }
+  }),
+  /** 删除单个文件 */
+  deleteFile: defineEndpoint({
+    method: "POST",
+    path: "/storage/file/delete",
+    input: DeleteFileInputSchema,
+    output: z.void(),
+    meta: { summary: "Delete a file", tags: ["storage"] }
+  }),
+  /** 批量删除文件 */
+  deleteFiles: defineEndpoint({
+    method: "POST",
+    path: "/storage/files/delete",
+    input: DeleteFilesInputSchema,
+    output: z.void(),
+    meta: { summary: "Delete multiple files", tags: ["storage"] }
+  })
+};
+
+export { DeleteFileInputSchema, DeleteFilesInputSchema, FileInfoInputSchema, FileMetadataSchema, ListFilesOutputSchema, PresignGetInputSchema, PresignPutInputSchema, PresignUrlOutputSchema, storageEndpoints };
+//# sourceMappingURL=index.js.map
+//# sourceMappingURL=index.js.map

package/dist/api/index.js.map

@@ -0,0 +1 @@
+{"version":3,"sources":["../../src/api/storage-api-schemas.ts","../../src/api/storage-api-contract.ts"],"names":["z"],"mappings":"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","file":"index.js","sourcesContent":["/**\n * @h-ai/storage/api — 存储 API 契约 Schema\n *\n * 入参/出参 Schema，客户端和服务端共享的唯一真相源。\n * @module storage-api-schemas\n */\n\nimport { z } from 'zod'\n\n// ─── 文件元数据 ───\n\n/** 文件元数据 Schema */\nexport const FileMetadataSchema = z.object({\n  key: z.string(),\n  size: z.number(),\n  contentType: z.string(),\n  lastModified: z.coerce.date(),\n  etag: z.string().optional(),\n  metadata: z.record(z.string(), z.string()).optional(),\n})\n\n// ─── 签名 URL ───\n\n/** 获取下载签名 URL 入参 */\nexport const PresignGetInputSchema = z.object({\n  key: z.string().min(1),\n  expiresIn: z.number().int().min(1).optional(),\n})\n\n/** 获取上传签名 URL 入参 */\nexport const PresignPutInputSchema = z.object({\n  key: z.string().min(1),\n  contentType: z.string().optional(),\n  contentLength: z.number().int().min(1).optional(),\n  expiresIn: z.number().int().min(1).optional(),\n})\n\n/** 签名 URL 出参 */\nexport const PresignUrlOutputSchema = z.object({\n  url: z.string(),\n  key: z.string(),\n  expiresAt: z.coerce.date().optional(),\n})\n\n// ─── 列表 ───\n\n/** 文件列表出参 */\nexport const ListFilesOutputSchema = z.object({\n  files: z.array(FileMetadataSchema),\n  commonPrefixes: z.array(z.string()),\n  nextContinuationToken: z.string().optional(),\n  isTruncated: z.boolean(),\n})\n\n// ─── 删除 ───\n\n/** 删除文件入参 */\nexport const DeleteFileInputSchema = z.object({\n  key: z.string().min(1),\n})\n\n/** 批量删除文件入参 */\nexport const DeleteFilesInputSchema = z.object({\n  keys: z.array(z.string().min(1)).min(1),\n})\n\n// ─── 文件信息 ───\n\n/** 获取文件信息入参 */\nexport const FileInfoInputSchema = z.object({\n  key: z.string().min(1),\n})\n\n// ─── 推导类型 ───\n\nexport type PresignGetInput = z.infer<typeof PresignGetInputSchema>\nexport type PresignPutInput = z.infer<typeof PresignPutInputSchema>\nexport type PresignUrlOutput = z.infer<typeof PresignUrlOutputSchema>\nexport type ListFilesOutput = z.infer<typeof ListFilesOutputSchema>\nexport type DeleteFileInput = z.infer<typeof DeleteFileInputSchema>\nexport type DeleteFilesInput = z.infer<typeof DeleteFilesInputSchema>\nexport type FileInfoInput = z.infer<typeof FileInfoInputSchema>\n","/**\n * @h-ai/storage/api — 存储 API 端点契约定义\n *\n * 所有 storage 模块的 API 端点（path + method + schema），\n * 客户端和服务端都从此处引用，编译时保证一致性。\n * @module storage-api-contract\n */\n\nimport { z } from 'zod'\nimport {\n  DeleteFileInputSchema,\n  DeleteFilesInputSchema,\n  FileInfoInputSchema,\n  FileMetadataSchema,\n  ListFilesOutputSchema,\n  PresignGetInputSchema,\n  PresignPutInputSchema,\n  PresignUrlOutputSchema,\n} from './storage-api-schemas.js'\n\n// ─── 端点定义辅助（内联，避免对 @h-ai/api-client 的循环依赖） ───\n\ninterface EndpointDef<TInput = unknown, TOutput = unknown> {\n  method: 'GET' | 'POST' | 'PUT' | 'DELETE' | 'PATCH'\n  path: string\n  input: z.ZodType<TInput>\n  output: z.ZodType<TOutput>\n  requireAuth?: boolean\n  meta?: { summary?: string, tags?: string[] }\n}\n\nfunction defineEndpoint<TInput, TOutput>(def: EndpointDef<TInput, TOutput>): EndpointDef<TInput, TOutput> {\n  return def\n}\n\n// ─── storage API 端点 ───\n\n/**\n * storage 所有 API 端点\n *\n * @example\n * ```ts\n * // 客户端\n * import { storageEndpoints } from '@h-ai/storage/api'\n * const { url } = await api.call(storageEndpoints.presignUpload, { key: 'avatar.png' })\n *\n * // 服务端\n * export const POST = kit.fromContract(storageEndpoints.presignUpload, async (input) => {\n *   const result = await storage.presign.putUrl(input.key, input)\n *   return result.success ? result.data : kit.response.internalError(result.error.message)\n * })\n * ```\n */\nexport const storageEndpoints = {\n  /** 获取下载签名 URL */\n  presignDownload: defineEndpoint({\n    method: 'POST',\n    path: '/storage/presign/download',\n    input: PresignGetInputSchema,\n    output: PresignUrlOutputSchema,\n    meta: { summary: 'Get presigned download URL', tags: ['storage'] },\n  }),\n\n  /** 获取上传签名 URL */\n  presignUpload: defineEndpoint({\n    method: 'POST',\n    path: '/storage/presign/upload',\n    input: PresignPutInputSchema,\n    output: PresignUrlOutputSchema,\n    meta: { summary: 'Get presigned upload URL', tags: ['storage'] },\n  }),\n\n  /** 获取文件元数据 */\n  fileInfo: defineEndpoint({\n    method: 'POST',\n    path: '/storage/file/info',\n    input: FileInfoInputSchema,\n    output: FileMetadataSchema,\n    meta: { summary: 'Get file metadata', tags: ['storage'] },\n  }),\n\n  /** 列出文件 */\n  listFiles: defineEndpoint({\n    method: 'GET',\n    path: '/storage/files',\n    input: z.object({\n      prefix: z.string().optional(),\n      maxKeys: z.coerce.number().int().min(1).max(1000).optional(),\n      continuationToken: z.string().optional(),\n      delimiter: z.string().optional(),\n    }),\n    output: ListFilesOutputSchema,\n    meta: { summary: 'List files by prefix', tags: ['storage'] },\n  }),\n\n  /** 删除单个文件 */\n  deleteFile: defineEndpoint({\n    method: 'POST',\n    path: '/storage/file/delete',\n    input: DeleteFileInputSchema,\n    output: z.void(),\n    meta: { summary: 'Delete a file', tags: ['storage'] },\n  }),\n\n  /** 批量删除文件 */\n  deleteFiles: defineEndpoint({\n    method: 'POST',\n    path: '/storage/files/delete',\n    input: DeleteFilesInputSchema,\n    output: z.void(),\n    meta: { summary: 'Delete multiple files', tags: ['storage'] },\n  }),\n} as const\n"]}