@h-ai/storage 0.1.0-alpha5

package/dist/browser.d.ts

@@ -0,0 +1,506 @@
+export { ClientDownloadOptions, ClientUploadOptions, UploadProgress, downloadAndSave, downloadWithPresignedUrl, formatFileSize, getFileExtension, getMimeType, uploadWithPresignedUrl } from './client/index.js';
+import { z } from 'zod';
+import * as _h_ai_core from '@h-ai/core';
+import { HaiResult } from '@h-ai/core';
+import { Buffer } from 'node:buffer';
+
+/**
+ * @h-ai/storage — 错误码 + 配置 Schema
+ * @module storage-config
+ */
+
+/**
+ * 存储类型枚举
+ *
+ * 支持的存储类型：
+ * - `s3` - S3 协议对象存储（兼容 AWS S3、MinIO、阿里云 OSS 等）
+ * - `local` - 本地文件存储（仅后端）
+ */
+declare const StorageTypeSchema: z.ZodEnum<{
+    s3: "s3";
+    local: "local";
+}>;
+/** 存储类型 */
+type StorageType = z.infer<typeof StorageTypeSchema>;
+/**
+ * S3 存储配置 Schema
+ *
+ * 支持标准 AWS S3 以及兼容 S3 协议的存储服务（MinIO、阿里云 OSS 等）。
+ * 必填字段：bucket、region、accessKeyId、secretAccessKey。
+ */
+declare const S3ConfigSchema: z.ZodObject<{
+    type: z.ZodLiteral<"s3">;
+    bucket: z.ZodString;
+    region: z.ZodString;
+    accessKeyId: z.ZodString;
+    secretAccessKey: z.ZodString;
+    endpoint: z.ZodOptional<z.ZodString>;
+    forcePathStyle: z.ZodDefault<z.ZodBoolean>;
+    prefix: z.ZodDefault<z.ZodString>;
+    publicUrl: z.ZodOptional<z.ZodString>;
+}, z.core.$strip>;
+/** S3 配置类型（parse 后，所有字段已填充默认值） */
+type S3Config = z.infer<typeof S3ConfigSchema>;
+/**
+ * 本地存储配置 Schema
+ *
+ * 基于本地文件系统，仅后端可用。必填字段：root。
+ */
+declare const LocalConfigSchema: z.ZodObject<{
+    type: z.ZodLiteral<"local">;
+    root: z.ZodString;
+    directoryMode: z.ZodDefault<z.ZodNumber>;
+    fileMode: z.ZodDefault<z.ZodNumber>;
+}, z.core.$strip>;
+/** 本地配置类型（parse 后，所有字段已填充默认值） */
+type LocalConfig = z.infer<typeof LocalConfigSchema>;
+/**
+ * 统一存储配置 Schema
+ *
+ * 支持 S3 和本地文件两种类型的配置验证。
+ *
+ * @example
+ * ```ts
+ * // S3 配置
+ * const s3Config = StorageConfigSchema.parse({
+ *     type: 's3',
+ *     bucket: 'my-bucket',
+ *     region: 'us-east-1',
+ *     accessKeyId: 'AKIAXXXXXXXX',
+ *     secretAccessKey: 'xxxxx'
+ * })
+ *
+ * // MinIO 配置
+ * const minioConfig = StorageConfigSchema.parse({
+ *     type: 's3',
+ *     bucket: 'my-bucket',
+ *     region: 'us-east-1',
+ *     endpoint: 'http://localhost:9000',
+ *     accessKeyId: 'minioadmin',
+ *     secretAccessKey: 'minioadmin',
+ *     forcePathStyle: true
+ * })
+ *
+ * // 本地存储配置
+ * const localConfig = StorageConfigSchema.parse({
+ *     type: 'local',
+ *     root: '/data/uploads'
+ * })
+ * ```
+ */
+declare const StorageConfigSchema: z.ZodDiscriminatedUnion<[z.ZodObject<{
+    type: z.ZodLiteral<"s3">;
+    bucket: z.ZodString;
+    region: z.ZodString;
+    accessKeyId: z.ZodString;
+    secretAccessKey: z.ZodString;
+    endpoint: z.ZodOptional<z.ZodString>;
+    forcePathStyle: z.ZodDefault<z.ZodBoolean>;
+    prefix: z.ZodDefault<z.ZodString>;
+    publicUrl: z.ZodOptional<z.ZodString>;
+}, z.core.$strip>, z.ZodObject<{
+    type: z.ZodLiteral<"local">;
+    root: z.ZodString;
+    directoryMode: z.ZodDefault<z.ZodNumber>;
+    fileMode: z.ZodDefault<z.ZodNumber>;
+}, z.core.$strip>], "type">;
+/** 存储配置类型（parse 后的完整配置） */
+type StorageConfig = z.infer<typeof StorageConfigSchema>;
+/** 存储配置输入类型（parse 前，允许省略带默认值的字段） */
+type StorageConfigInput = z.input<typeof StorageConfigSchema>;
+/**
+ * 签名 URL 配置 Schema
+ *
+ * 用于控制 `storage.presign.getUrl()` 生成的下载签名 URL 参数。
+ *
+ * @example
+ * ```ts
+ * const url = await storage.presign.getUrl('report.pdf', {
+ *   expiresIn: 600,                          // 10 分钟过期
+ *   responseContentDisposition: 'attachment; filename="report.pdf"',
+ * })
+ * ```
+ */
+declare const PresignOptionsSchema: z.ZodObject<{
+    expiresIn: z.ZodDefault<z.ZodNumber>;
+    responseContentType: z.ZodOptional<z.ZodString>;
+    responseContentDisposition: z.ZodOptional<z.ZodString>;
+}, z.core.$strip>;
+/** 签名 URL 配置类型（parse 后） */
+type PresignOptions = z.infer<typeof PresignOptionsSchema>;
+/**
+ * 上传签名 URL 配置 Schema
+ *
+ * 继承 PresignOptionsSchema 并扩展上传专属参数，用于 `storage.presign.putUrl()`。
+ *
+ * @example
+ * ```ts
+ * const url = await storage.presign.putUrl('uploads/avatar.png', {
+ *   contentType: 'image/png',
+ *   maxSize: 5 * 1024 * 1024,   // 5MB 限制
+ *   expiresIn: 300,
+ * })
+ * ```
+ */
+declare const PresignUploadOptionsSchema: z.ZodObject<{
+    expiresIn: z.ZodDefault<z.ZodNumber>;
+    responseContentType: z.ZodOptional<z.ZodString>;
+    responseContentDisposition: z.ZodOptional<z.ZodString>;
+    contentType: z.ZodDefault<z.ZodString>;
+    maxSize: z.ZodOptional<z.ZodNumber>;
+}, z.core.$strip>;
+/** 上传签名 URL 配置类型（parse 后） */
+type PresignUploadOptions = z.infer<typeof PresignUploadOptionsSchema>;
+
+declare const HaiStorageError: {
+    readonly CONNECTION_FAILED: _h_ai_core.HaiErrorDef;
+    readonly OPERATION_FAILED: _h_ai_core.HaiErrorDef;
+    readonly NOT_FOUND: _h_ai_core.HaiErrorDef;
+    readonly ALREADY_EXISTS: _h_ai_core.HaiErrorDef;
+    readonly PERMISSION_DENIED: _h_ai_core.HaiErrorDef;
+    readonly QUOTA_EXCEEDED: _h_ai_core.HaiErrorDef;
+    readonly INVALID_PATH: _h_ai_core.HaiErrorDef;
+    readonly IO_ERROR: _h_ai_core.HaiErrorDef;
+    readonly NETWORK_ERROR: _h_ai_core.HaiErrorDef;
+    readonly NOT_INITIALIZED: _h_ai_core.HaiErrorDef;
+    readonly UNSUPPORTED_TYPE: _h_ai_core.HaiErrorDef;
+    readonly CONFIG_ERROR: _h_ai_core.HaiErrorDef;
+    readonly PRESIGN_FAILED: _h_ai_core.HaiErrorDef;
+    readonly UPLOAD_FAILED: _h_ai_core.HaiErrorDef;
+    readonly DOWNLOAD_FAILED: _h_ai_core.HaiErrorDef;
+};
+/**
+ * 文件元数据接口
+ *
+ * 表示存储中单个文件的元信息，由 put/head/copy/list 等操作返回。
+ */
+interface FileMetadata {
+    /** 文件键/路径（不含配置 prefix，对用户透明） */
+    key: string;
+    /** 文件大小（字节） */
+    size: number;
+    /** 内容类型（MIME），未指定时根据扩展名自动推断 */
+    contentType: string;
+    /** 最后修改时间 */
+    lastModified: Date;
+    /** ETag（用于缓存验证，本地存储为 MD5，S3 由服务端生成） */
+    etag?: string;
+    /** 自定义元数据键值对 */
+    metadata?: Record<string, string>;
+}
+/**
+ * 列表选项
+ *
+ * 用于控制 `storage.dir.list()` 的过滤、分页和目录模拟行为。
+ */
+interface ListOptions {
+    /** 前缀过滤（只返回以此前缀开头的文件） */
+    prefix?: string;
+    /**
+     * 分页标记（从上次 ListResult.nextContinuationToken 获取）
+     *
+     * 注意：本地存储目前不支持此字段，仅 S3 Provider 有效。
+     */
+    continuationToken?: string;
+    /** 每页最大数量（默认 1000） */
+    maxKeys?: number;
+    /** 分隔符（用于模拟目录结构，通常为 '/';传入后子目录作为 commonPrefixes 返回） */
+    delimiter?: string;
+}
+/**
+ * 列表结果
+ *
+ * 包含当前页的文件列表、目录前缀、分页信息。
+ */
+interface ListResult {
+    /** 当前页文件元数据列表 */
+    files: FileMetadata[];
+    /** 公共前缀（使用 delimiter 时由子目录路径组成） */
+    commonPrefixes: string[];
+    /** 下一页标记；无后续页时为 undefined */
+    nextContinuationToken?: string;
+    /** 是否被截断（true 表示还有更多数据，可用 nextContinuationToken 继续拉取） */
+    isTruncated: boolean;
+}
+/**
+ * 上传选项
+ *
+ * 用于控制 `storage.file.put()` 的元数据与缓存行为。
+ */
+interface UploadOptions {
+    /** 内容类型（不指定时根据文件扩展名自动推断） */
+    contentType?: string;
+    /** 自定义元数据键值对（存储后可通过 head 获取） */
+    metadata?: Record<string, string>;
+    /** Cache-Control 响应头（例如 'max-age=3600'） */
+    cacheControl?: string;
+    /** Content-Disposition 响应头（例如 'attachment; filename="a.txt"'） */
+    contentDisposition?: string;
+}
+/**
+ * 下载选项
+ *
+ * 用于控制 `storage.file.get()` 的范围读取。
+ * 两个字段均为字节偏移（含），与 HTTP Range 语义一致。
+ */
+interface DownloadOptions {
+    /** 范围起始位置（字节，含）；不指定时从文件开头读取 */
+    rangeStart?: number;
+    /** 范围结束位置（字节，含）；不指定时读取到文件末尾 */
+    rangeEnd?: number;
+}
+/**
+ * 复制选项
+ *
+ * 用于控制 `storage.file.copy()` 的目标文件元数据。
+ * 提供任意字段时，S3 Provider 会使用 MetadataDirective='REPLACE' 覆盖源文件元数据。
+ */
+interface CopyOptions {
+    /** 目标文件的内容类型（不指定时继承源文件） */
+    contentType?: string;
+    /** 目标文件的自定义元数据（不指定时继承源文件） */
+    metadata?: Record<string, string>;
+}
+/**
+ * 文件操作接口
+ *
+ * 提供文件的读写操作。
+ */
+interface FileOperations {
+    /**
+     * 上传文件
+     *
+     * @param key - 文件键/路径
+     * @param data - 文件内容（Buffer、Uint8Array 或字符串）
+     * @param options - 上传选项
+     * @returns 上传结果包含文件元数据
+     * @example
+     * ```ts
+     * const result = await storage.file.put('uploads/a.txt', 'hello')
+     * if (result.success) {
+     *   result.data.key
+     * }
+     * ```
+     */
+    put: (key: string, data: Buffer | Uint8Array | string, options?: UploadOptions) => Promise<HaiResult<FileMetadata>>;
+    /**
+     * 下载文件
+     *
+     * @param key - 文件键/路径
+     * @param options - 下载选项
+     * @returns 文件内容
+     * @example
+     * ```ts
+     * const result = await storage.file.get('uploads/a.txt')
+     * if (result.success) {
+     *   const buffer = result.data
+     * }
+     * ```
+     */
+    get: (key: string, options?: DownloadOptions) => Promise<HaiResult<Buffer>>;
+    /**
+     * 获取文件元数据
+     *
+     * @param key - 文件键/路径
+     * @returns 文件元数据
+     * @example
+     * ```ts
+     * const result = await storage.file.head('uploads/a.txt')
+     * if (result.success) {
+     *   result.data.size
+     * }
+     * ```
+     */
+    head: (key: string) => Promise<HaiResult<FileMetadata>>;
+    /**
+     * 检查文件是否存在
+     *
+     * @param key - 文件键/路径
+     * @returns 是否存在
+     * @example
+     * ```ts
+     * const result = await storage.file.exists('uploads/a.txt')
+     * if (result.success) {
+     *   result.data
+     * }
+     * ```
+     */
+    exists: (key: string) => Promise<HaiResult<boolean>>;
+    /**
+     * 删除文件
+     *
+     * @param key - 文件键/路径
+     * @returns 删除结果
+     * @example
+     * ```ts
+     * await storage.file.delete('uploads/a.txt')
+     * ```
+     */
+    delete: (key: string) => Promise<HaiResult<void>>;
+    /**
+     * 批量删除文件
+     *
+     * @param keys - 文件键/路径列表
+     * @returns 删除结果
+     * @example
+     * ```ts
+     * await storage.file.deleteMany(['a.txt', 'b.txt'])
+     * ```
+     */
+    deleteMany: (keys: string[]) => Promise<HaiResult<void>>;
+    /**
+     * 复制文件
+     *
+     * @param sourceKey - 源文件键
+     * @param destKey - 目标文件键
+     * @param options - 复制选项
+     * @returns 目标文件元数据
+     * @example
+     * ```ts
+     * await storage.file.copy('a.txt', 'b.txt')
+     * ```
+     */
+    copy: (sourceKey: string, destKey: string, options?: CopyOptions) => Promise<HaiResult<FileMetadata>>;
+}
+/**
+ * 目录操作接口
+ *
+ * 提供目录（前缀）的列表操作。
+ */
+interface DirOperations {
+    /**
+     * 列出目录内容
+     *
+     * @param options - 列表选项
+     * @returns 文件和目录列表
+     * @example
+     * ```ts
+     * const result = await storage.dir.list({ prefix: 'uploads/' })
+     * if (result.success) {
+     *   result.data.files
+     * }
+     * ```
+     */
+    list: (options?: ListOptions) => Promise<HaiResult<ListResult>>;
+    /**
+     * 删除目录（删除指定前缀下的所有文件）
+     *
+     * @param prefix - 目录前缀
+     * @returns 删除结果
+     * @example
+     * ```ts
+     * await storage.dir.delete('uploads/tmp/')
+     * ```
+     */
+    delete: (prefix: string) => Promise<HaiResult<void>>;
+}
+/**
+ * 签名 URL 操作接口
+ *
+ * 提供生成临时授权 URL 的功能，支持前端直接上传下载。
+ */
+interface PresignOperations {
+    /**
+     * 生成下载签名 URL
+     *
+     * @param key - 文件键/路径
+     * @param options - 签名选项
+     * @returns 签名 URL
+     * @example
+     * ```ts
+     * const result = await storage.presign.getUrl('a.txt', { expiresIn: 60 })
+     * ```
+     */
+    getUrl: (key: string, options?: PresignOptions) => Promise<HaiResult<string>>;
+    /**
+     * 生成上传签名 URL
+     *
+     * @param key - 文件键/路径
+     * @param options - 上传签名选项
+     * @returns 签名 URL
+     * @example
+     * ```ts
+     * const result = await storage.presign.putUrl('a.txt', { contentType: 'text/plain' })
+     * ```
+     */
+    putUrl: (key: string, options?: PresignUploadOptions) => Promise<HaiResult<string>>;
+    /**
+     * 获取公开访问 URL（如果配置了 publicUrl）
+     *
+     * @param key - 文件键/路径
+     * @returns 公开 URL，如果未配置 publicUrl 则返回 null
+     * @example
+     * ```ts
+     * const url = storage.presign.publicUrl('a.txt')
+     * ```
+     */
+    publicUrl: (key: string) => string | null;
+}
+/**
+ * 存储函数接口
+ *
+ * 统一的存储访问入口：
+ * - `storage.init()` — 初始化存储连接
+ * - `storage.close()` — 关闭连接并释放资源
+ * - `storage.file` — 文件操作（上传/下载/删除/复制等）
+ * - `storage.dir` — 目录操作（列表/删除）
+ * - `storage.presign` — 签名 URL 操作
+ * - `storage.config` — 当前连接配置（未初始化时为 null）
+ * - `storage.isInitialized` — 初始化状态
+ */
+interface StorageFunctions {
+    /**
+     * 初始化存储连接
+     *
+     * 已有连接时会先 close 再重新初始化。
+     *
+     * @param config - 存储配置（支持省略带默认值的字段）
+     * @returns 成功 ok(undefined)；失败返回 err（含 StorageError）
+     */
+    init: (config: StorageConfigInput) => Promise<HaiResult<void>>;
+    /**
+     * 关闭存储连接并释放资源
+     *
+     * 重复调用不会报错。
+     */
+    close: () => Promise<void>;
+    /** 当前解析后的存储配置；未初始化或已关闭时为 null */
+    readonly config: StorageConfig | null;
+    /** 是否已完成初始化 */
+    readonly isInitialized: boolean;
+    /** 文件操作接口（put / get / head / exists / delete / deleteMany / copy） */
+    readonly file: FileOperations;
+    /** 目录操作接口（list / delete） */
+    readonly dir: DirOperations;
+    /** 签名 URL 操作接口（getUrl / putUrl / publicUrl） */
+    readonly presign: PresignOperations;
+}
+/**
+ * 存储 Provider 接口
+ *
+ * 由各具体存储实现（S3、Local）实现此接口。
+ * Provider 仅在 storage-main 内部使用，不直接对外暴露实例。
+ */
+interface StorageProvider {
+    /** Provider 名称标识（如 's3'、'local'） */
+    readonly name: string;
+    /**
+     * 建立与存储服务的连接
+     *
+     * @param config - 经 Schema 校验后的完整配置
+     * @returns 连接结果
+     */
+    connect: (config: StorageConfig) => Promise<HaiResult<void>>;
+    /** 关闭连接并释放资源 */
+    close: () => Promise<void>;
+    /** 检查是否已连接 */
+    isConnected: () => boolean;
+    /** 文件操作接口 */
+    readonly file: FileOperations;
+    /** 目录操作接口 */
+    readonly dir: DirOperations;
+    /** 签名 URL 操作接口 */
+    readonly presign: PresignOperations;
+}
+
+export { type CopyOptions, type DirOperations, type DownloadOptions, type FileMetadata, type FileOperations, HaiStorageError, type ListOptions, type ListResult, type LocalConfig, LocalConfigSchema, type PresignOperations, type PresignOptions, PresignOptionsSchema, type PresignUploadOptions, PresignUploadOptionsSchema, type S3Config, S3ConfigSchema, type StorageConfig, type StorageConfigInput, StorageConfigSchema, type StorageFunctions, type StorageProvider, type StorageType, StorageTypeSchema, type UploadOptions };

package/dist/browser.js

@@ -0,0 +1,4 @@
+export { HaiStorageError, LocalConfigSchema, PresignOptionsSchema, PresignUploadOptionsSchema, S3ConfigSchema, StorageConfigSchema, StorageTypeSchema } from './chunk-KHZOR6CR.js';
+export { downloadAndSave, downloadWithPresignedUrl, formatFileSize, getFileExtension, getMimeType, uploadWithPresignedUrl } from './chunk-U427BQIQ.js';
+//# sourceMappingURL=browser.js.map
+//# sourceMappingURL=browser.js.map

package/dist/browser.js.map

@@ -0,0 +1 @@
+{"version":3,"sources":[],"names":[],"mappings":"","file":"browser.js"}

package/dist/chunk-KHZOR6CR.js

@@ -0,0 +1,76 @@
+import { storageM } from './chunk-U427BQIQ.js';
+import { z } from 'zod';
+import { core } from '@h-ai/core';
+
+var StorageTypeSchema = z.enum(["s3", "local"]);
+var S3ConfigSchema = z.object({
+  /** 存储类型 */
+  type: z.literal("s3"),
+  /** 存储桶名称 */
+  bucket: z.string().min(1, storageM("storage_config_bucketRequired")),
+  /** 区域 */
+  region: z.string().min(1, storageM("storage_config_regionRequired")),
+  /** Access Key ID */
+  accessKeyId: z.string().min(1, storageM("storage_config_accessKeyIdRequired")),
+  /** Secret Access Key */
+  secretAccessKey: z.string().min(1, storageM("storage_config_secretAccessKeyRequired")),
+  /** 自定义端点（用于 MinIO、阿里云 OSS 等） */
+  endpoint: z.string().url().optional(),
+  /** 强制使用路径风格 URL（某些 S3 兼容服务需要） */
+  forcePathStyle: z.boolean().default(false),
+  /** 路径前缀（所有操作都会加上此前缀） */
+  prefix: z.string().default(""),
+  /** 公开访问基础 URL（用于生成公开 URL） */
+  publicUrl: z.string().url().optional()
+});
+var LocalConfigSchema = z.object({
+  /** 存储类型 */
+  type: z.literal("local"),
+  /** 根目录路径 */
+  root: z.string().min(1, storageM("storage_config_rootRequired")),
+  /** 目录创建权限 */
+  directoryMode: z.number().default(493),
+  /** 文件创建权限 */
+  fileMode: z.number().default(420)
+});
+var StorageConfigSchema = z.discriminatedUnion("type", [
+  S3ConfigSchema,
+  LocalConfigSchema
+]);
+var PresignOptionsSchema = z.object({
+  /** 过期时间（秒），范围 1~604800（7 天），默认 3600（1 小时） */
+  expiresIn: z.number().min(1).max(604800).default(3600),
+  // 最长 7 天
+  /** 响应内容类型（用于下载时设置 Content-Type） */
+  responseContentType: z.string().optional(),
+  /** 响应内容处置（用于设置下载文件名） */
+  responseContentDisposition: z.string().optional()
+});
+var PresignUploadOptionsSchema = PresignOptionsSchema.extend({
+  /** 上传内容类型（必须与实际上传匹配） */
+  contentType: z.string().default("application/octet-stream"),
+  /** 最大文件大小限制（bytes） */
+  maxSize: z.number().optional()
+});
+var StorageErrorInfo = {
+  CONNECTION_FAILED: "001:500",
+  OPERATION_FAILED: "002:500",
+  NOT_FOUND: "003:404",
+  ALREADY_EXISTS: "004:409",
+  PERMISSION_DENIED: "005:403",
+  QUOTA_EXCEEDED: "006:413",
+  INVALID_PATH: "007:400",
+  IO_ERROR: "008:500",
+  NETWORK_ERROR: "009:502",
+  NOT_INITIALIZED: "010:500",
+  UNSUPPORTED_TYPE: "011:400",
+  CONFIG_ERROR: "012:500",
+  PRESIGN_FAILED: "013:500",
+  UPLOAD_FAILED: "014:500",
+  DOWNLOAD_FAILED: "015:500"
+};
+var HaiStorageError = core.error.buildHaiErrorsDef("storage", StorageErrorInfo);
+
+export { HaiStorageError, LocalConfigSchema, PresignOptionsSchema, PresignUploadOptionsSchema, S3ConfigSchema, StorageConfigSchema, StorageTypeSchema };
+//# sourceMappingURL=chunk-KHZOR6CR.js.map
+//# sourceMappingURL=chunk-KHZOR6CR.js.map

package/dist/chunk-KHZOR6CR.js.map

@@ -0,0 +1 @@
+{"version":3,"sources":["../src/storage-config.ts","../src/storage-types.ts"],"names":[],"mappings":";;;;AAiBO,IAAM,oBAAoB,CAAA,CAAE,IAAA,CAAK,CAAC,IAAA,EAAM,OAAO,CAAC;AAWhD,IAAM,cAAA,GAAiB,EAAE,MAAA,CAAO;AAAA;AAAA,EAErC,IAAA,EAAM,CAAA,CAAE,OAAA,CAAQ,IAAI,CAAA;AAAA;AAAA,EAGpB,MAAA,EAAQ,EAAE,MAAA,EAAO,CAAE,IAAI,CAAA,EAAG,QAAA,CAAS,+BAA+B,CAAC,CAAA;AAAA;AAAA,EAGnE,MAAA,EAAQ,EAAE,MAAA,EAAO,CAAE,IAAI,CAAA,EAAG,QAAA,CAAS,+BAA+B,CAAC,CAAA;AAAA;AAAA,EAGnE,WAAA,EAAa,EAAE,MAAA,EAAO,CAAE,IAAI,CAAA,EAAG,QAAA,CAAS,oCAAoC,CAAC,CAAA;AAAA;AAAA,EAG7E,eAAA,EAAiB,EAAE,MAAA,EAAO,CAAE,IAAI,CAAA,EAAG,QAAA,CAAS,wCAAwC,CAAC,CAAA;AAAA;AAAA,EAGrF,UAAU,CAAA,CAAE,MAAA,EAAO,CAAE,GAAA,GAAM,QAAA,EAAS;AAAA;AAAA,EAGpC,cAAA,EAAgB,CAAA,CAAE,OAAA,EAAQ,CAAE,QAAQ,KAAK,CAAA;AAAA;AAAA,EAGzC,MAAA,EAAQ,CAAA,CAAE,MAAA,EAAO,CAAE,QAAQ,EAAE,CAAA;AAAA;AAAA,EAG7B,WAAW,CAAA,CAAE,MAAA,EAAO,CAAE,GAAA,GAAM,QAAA;AAC9B,CAAC;AAUM,IAAM,iBAAA,GAAoB,EAAE,MAAA,CAAO;AAAA;AAAA,EAExC,IAAA,EAAM,CAAA,CAAE,OAAA,CAAQ,OAAO,CAAA;AAAA;AAAA,EAGvB,IAAA,EAAM,EAAE,MAAA,EAAO,CAAE,IAAI,CAAA,EAAG,QAAA,CAAS,6BAA6B,CAAC,CAAA;AAAA;AAAA,EAG/D,aAAA,EAAe,CAAA,CAAE,MAAA,EAAO,CAAE,QAAQ,GAAK,CAAA;AAAA;AAAA,EAGvC,QAAA,EAAU,CAAA,CAAE,MAAA,EAAO,CAAE,QAAQ,GAAK;AACpC,CAAC;AAuCM,IAAM,mBAAA,GAAsB,CAAA,CAAE,kBAAA,CAAmB,MAAA,EAAQ;AAAA,EAC9D,cAAA;AAAA,EACA;AACF,CAAC;AAuBM,IAAM,oBAAA,GAAuB,EAAE,MAAA,CAAO;AAAA;AAAA,EAE3C,SAAA,EAAW,CAAA,CAAE,MAAA,EAAO,CAAE,GAAA,CAAI,CAAC,CAAA,CAAE,GAAA,CAAI,MAAM,CAAA,CAAE,OAAA,CAAQ,IAAI,CAAA;AAAA;AAAA;AAAA,EAGrD,mBAAA,EAAqB,CAAA,CAAE,MAAA,EAAO,CAAE,QAAA,EAAS;AAAA;AAAA,EAGzC,0BAAA,EAA4B,CAAA,CAAE,MAAA,EAAO,CAAE,QAAA;AACzC,CAAC;AAmBM,IAAM,0BAAA,GAA6B,qBAAqB,MAAA,CAAO;AAAA;AAAA,EAEpE,WAAA,EAAa,CAAA,CAAE,MAAA,EAAO,CAAE,QAAQ,0BAA0B,CAAA;AAAA;AAAA,EAG1D,OAAA,EAAS,CAAA,CAAE,MAAA,EAAO,CAAE,QAAA;AACtB,CAAC;AC1JD,IAAM,gBAAA,GAAmB;AAAA,EACvB,iBAAA,EAAmB,SAAA;AAAA,EACnB,gBAAA,EAAkB,SAAA;AAAA,EAClB,SAAA,EAAW,SAAA;AAAA,EACX,cAAA,EAAgB,SAAA;AAAA,EAChB,iBAAA,EAAmB,SAAA;AAAA,EACnB,cAAA,EAAgB,SAAA;AAAA,EAChB,YAAA,EAAc,SAAA;AAAA,EACd,QAAA,EAAU,SAAA;AAAA,EACV,aAAA,EAAe,SAAA;AAAA,EACf,eAAA,EAAiB,SAAA;AAAA,EACjB,gBAAA,EAAkB,SAAA;AAAA,EAClB,YAAA,EAAc,SAAA;AAAA,EACd,cAAA,EAAgB,SAAA;AAAA,EAChB,aAAA,EAAe,SAAA;AAAA,EACf,eAAA,EAAiB;AACnB,CAAA;AAEO,IAAM,eAAA,GAAkB,IAAA,CAAK,KAAA,CAAM,iBAAA,CAAkB,WAAW,gBAAgB","file":"chunk-KHZOR6CR.js","sourcesContent":["/**\n * @h-ai/storage — 错误码 + 配置 Schema\n * @module storage-config\n */\n\nimport { z } from 'zod'\nimport { storageM } from './storage-i18n.js'\n\n// ─── 配置 Schema ───\n\n/**\n * 存储类型枚举\n *\n * 支持的存储类型：\n * - `s3` - S3 协议对象存储（兼容 AWS S3、MinIO、阿里云 OSS 等）\n * - `local` - 本地文件存储（仅后端）\n */\nexport const StorageTypeSchema = z.enum(['s3', 'local'])\n\n/** 存储类型 */\nexport type StorageType = z.infer<typeof StorageTypeSchema>\n\n/**\n * S3 存储配置 Schema\n *\n * 支持标准 AWS S3 以及兼容 S3 协议的存储服务（MinIO、阿里云 OSS 等）。\n * 必填字段：bucket、region、accessKeyId、secretAccessKey。\n */\nexport const S3ConfigSchema = z.object({\n  /** 存储类型 */\n  type: z.literal('s3'),\n\n  /** 存储桶名称 */\n  bucket: z.string().min(1, storageM('storage_config_bucketRequired')),\n\n  /** 区域 */\n  region: z.string().min(1, storageM('storage_config_regionRequired')),\n\n  /** Access Key ID */\n  accessKeyId: z.string().min(1, storageM('storage_config_accessKeyIdRequired')),\n\n  /** Secret Access Key */\n  secretAccessKey: z.string().min(1, storageM('storage_config_secretAccessKeyRequired')),\n\n  /** 自定义端点（用于 MinIO、阿里云 OSS 等） */\n  endpoint: z.string().url().optional(),\n\n  /** 强制使用路径风格 URL（某些 S3 兼容服务需要） */\n  forcePathStyle: z.boolean().default(false),\n\n  /** 路径前缀（所有操作都会加上此前缀） */\n  prefix: z.string().default(''),\n\n  /** 公开访问基础 URL（用于生成公开 URL） */\n  publicUrl: z.string().url().optional(),\n})\n\n/** S3 配置类型（parse 后，所有字段已填充默认值） */\nexport type S3Config = z.infer<typeof S3ConfigSchema>\n\n/**\n * 本地存储配置 Schema\n *\n * 基于本地文件系统，仅后端可用。必填字段：root。\n */\nexport const LocalConfigSchema = z.object({\n  /** 存储类型 */\n  type: z.literal('local'),\n\n  /** 根目录路径 */\n  root: z.string().min(1, storageM('storage_config_rootRequired')),\n\n  /** 目录创建权限 */\n  directoryMode: z.number().default(0o755),\n\n  /** 文件创建权限 */\n  fileMode: z.number().default(0o644),\n})\n\n/** 本地配置类型（parse 后，所有字段已填充默认值） */\nexport type LocalConfig = z.infer<typeof LocalConfigSchema>\n\n/**\n * 统一存储配置 Schema\n *\n * 支持 S3 和本地文件两种类型的配置验证。\n *\n * @example\n * ```ts\n * // S3 配置\n * const s3Config = StorageConfigSchema.parse({\n *     type: 's3',\n *     bucket: 'my-bucket',\n *     region: 'us-east-1',\n *     accessKeyId: 'AKIAXXXXXXXX',\n *     secretAccessKey: 'xxxxx'\n * })\n *\n * // MinIO 配置\n * const minioConfig = StorageConfigSchema.parse({\n *     type: 's3',\n *     bucket: 'my-bucket',\n *     region: 'us-east-1',\n *     endpoint: 'http://localhost:9000',\n *     accessKeyId: 'minioadmin',\n *     secretAccessKey: 'minioadmin',\n *     forcePathStyle: true\n * })\n *\n * // 本地存储配置\n * const localConfig = StorageConfigSchema.parse({\n *     type: 'local',\n *     root: '/data/uploads'\n * })\n * ```\n */\nexport const StorageConfigSchema = z.discriminatedUnion('type', [\n  S3ConfigSchema,\n  LocalConfigSchema,\n])\n\n/** 存储配置类型（parse 后的完整配置） */\nexport type StorageConfig = z.infer<typeof StorageConfigSchema>\n\n/** 存储配置输入类型（parse 前，允许省略带默认值的字段） */\nexport type StorageConfigInput = z.input<typeof StorageConfigSchema>\n\n// ─── 签名 URL 配置 ───\n\n/**\n * 签名 URL 配置 Schema\n *\n * 用于控制 `storage.presign.getUrl()` 生成的下载签名 URL 参数。\n *\n * @example\n * ```ts\n * const url = await storage.presign.getUrl('report.pdf', {\n *   expiresIn: 600,                          // 10 分钟过期\n *   responseContentDisposition: 'attachment; filename=\"report.pdf\"',\n * })\n * ```\n */\nexport const PresignOptionsSchema = z.object({\n  /** 过期时间（秒），范围 1~604800（7 天），默认 3600（1 小时） */\n  expiresIn: z.number().min(1).max(604800).default(3600), // 最长 7 天\n\n  /** 响应内容类型（用于下载时设置 Content-Type） */\n  responseContentType: z.string().optional(),\n\n  /** 响应内容处置（用于设置下载文件名） */\n  responseContentDisposition: z.string().optional(),\n})\n\n/** 签名 URL 配置类型（parse 后） */\nexport type PresignOptions = z.infer<typeof PresignOptionsSchema>\n\n/**\n * 上传签名 URL 配置 Schema\n *\n * 继承 PresignOptionsSchema 并扩展上传专属参数，用于 `storage.presign.putUrl()`。\n *\n * @example\n * ```ts\n * const url = await storage.presign.putUrl('uploads/avatar.png', {\n *   contentType: 'image/png',\n *   maxSize: 5 * 1024 * 1024,   // 5MB 限制\n *   expiresIn: 300,\n * })\n * ```\n */\nexport const PresignUploadOptionsSchema = PresignOptionsSchema.extend({\n  /** 上传内容类型（必须与实际上传匹配） */\n  contentType: z.string().default('application/octet-stream'),\n\n  /** 最大文件大小限制（bytes） */\n  maxSize: z.number().optional(),\n})\n\n/** 上传签名 URL 配置类型（parse 后） */\nexport type PresignUploadOptions = z.infer<typeof PresignUploadOptionsSchema>\n","/**\n * @h-ai/storage — 公共类型定义\n *\n * 包含：\n * - 错误类型（StorageError）\n * - 文件元数据（FileMetadata）\n * - 列表结果（ListResult）\n * - 文件操作接口（FileOperations）\n * - 目录操作接口（DirOperations）\n * - 签名 URL 操作接口（PresignOperations）\n * - 函数接口（StorageFunctions）\n * - Provider 接口（StorageProvider）\n * @module storage-types\n */\n\nimport type { ErrorInfo, HaiResult } from '@h-ai/core'\nimport type { Buffer } from 'node:buffer'\nimport type { PresignOptions, PresignUploadOptions, StorageConfig, StorageConfigInput } from './storage-config.js'\nimport { core } from '@h-ai/core'\n\n// ─── 错误定义（照 @h-ai/core 范式） ───\n\nconst StorageErrorInfo = {\n  CONNECTION_FAILED: '001:500',\n  OPERATION_FAILED: '002:500',\n  NOT_FOUND: '003:404',\n  ALREADY_EXISTS: '004:409',\n  PERMISSION_DENIED: '005:403',\n  QUOTA_EXCEEDED: '006:413',\n  INVALID_PATH: '007:400',\n  IO_ERROR: '008:500',\n  NETWORK_ERROR: '009:502',\n  NOT_INITIALIZED: '010:500',\n  UNSUPPORTED_TYPE: '011:400',\n  CONFIG_ERROR: '012:500',\n  PRESIGN_FAILED: '013:500',\n  UPLOAD_FAILED: '014:500',\n  DOWNLOAD_FAILED: '015:500',\n} as const satisfies ErrorInfo\n\nexport const HaiStorageError = core.error.buildHaiErrorsDef('storage', StorageErrorInfo)\n\n// ─── 文件元数据 ───\n\n/**\n * 文件元数据接口\n *\n * 表示存储中单个文件的元信息，由 put/head/copy/list 等操作返回。\n */\nexport interface FileMetadata {\n  /** 文件键/路径（不含配置 prefix，对用户透明） */\n  key: string\n  /** 文件大小（字节） */\n  size: number\n  /** 内容类型（MIME），未指定时根据扩展名自动推断 */\n  contentType: string\n  /** 最后修改时间 */\n  lastModified: Date\n  /** ETag（用于缓存验证，本地存储为 MD5，S3 由服务端生成） */\n  etag?: string\n  /** 自定义元数据键值对 */\n  metadata?: Record<string, string>\n}\n\n/**\n * 列表选项\n *\n * 用于控制 `storage.dir.list()` 的过滤、分页和目录模拟行为。\n */\nexport interface ListOptions {\n  /** 前缀过滤（只返回以此前缀开头的文件） */\n  prefix?: string\n  /**\n   * 分页标记（从上次 ListResult.nextContinuationToken 获取）\n   *\n   * 注意：本地存储目前不支持此字段，仅 S3 Provider 有效。\n   */\n  continuationToken?: string\n  /** 每页最大数量（默认 1000） */\n  maxKeys?: number\n  /** 分隔符（用于模拟目录结构，通常为 '/';传入后子目录作为 commonPrefixes 返回） */\n  delimiter?: string\n}\n\n/**\n * 列表结果\n *\n * 包含当前页的文件列表、目录前缀、分页信息。\n */\nexport interface ListResult {\n  /** 当前页文件元数据列表 */\n  files: FileMetadata[]\n  /** 公共前缀（使用 delimiter 时由子目录路径组成） */\n  commonPrefixes: string[]\n  /** 下一页标记；无后续页时为 undefined */\n  nextContinuationToken?: string\n  /** 是否被截断（true 表示还有更多数据，可用 nextContinuationToken 继续拉取） */\n  isTruncated: boolean\n}\n\n// ─── 上传下载选项 ───\n\n/**\n * 上传选项\n *\n * 用于控制 `storage.file.put()` 的元数据与缓存行为。\n */\nexport interface UploadOptions {\n  /** 内容类型（不指定时根据文件扩展名自动推断） */\n  contentType?: string\n  /** 自定义元数据键值对（存储后可通过 head 获取） */\n  metadata?: Record<string, string>\n  /** Cache-Control 响应头（例如 'max-age=3600'） */\n  cacheControl?: string\n  /** Content-Disposition 响应头（例如 'attachment; filename=\"a.txt\"'） */\n  contentDisposition?: string\n}\n\n/**\n * 下载选项\n *\n * 用于控制 `storage.file.get()` 的范围读取。\n * 两个字段均为字节偏移（含），与 HTTP Range 语义一致。\n */\nexport interface DownloadOptions {\n  /** 范围起始位置（字节，含）；不指定时从文件开头读取 */\n  rangeStart?: number\n  /** 范围结束位置（字节，含）；不指定时读取到文件末尾 */\n  rangeEnd?: number\n}\n\n/**\n * 复制选项\n *\n * 用于控制 `storage.file.copy()` 的目标文件元数据。\n * 提供任意字段时，S3 Provider 会使用 MetadataDirective='REPLACE' 覆盖源文件元数据。\n */\nexport interface CopyOptions {\n  /** 目标文件的内容类型（不指定时继承源文件） */\n  contentType?: string\n  /** 目标文件的自定义元数据（不指定时继承源文件） */\n  metadata?: Record<string, string>\n}\n\n// ─── 操作接口 ───\n\n/**\n * 文件操作接口\n *\n * 提供文件的读写操作。\n */\nexport interface FileOperations {\n  /**\n   * 上传文件\n   *\n   * @param key - 文件键/路径\n   * @param data - 文件内容（Buffer、Uint8Array 或字符串）\n   * @param options - 上传选项\n   * @returns 上传结果包含文件元数据\n   * @example\n   * ```ts\n   * const result = await storage.file.put('uploads/a.txt', 'hello')\n   * if (result.success) {\n   *   result.data.key\n   * }\n   * ```\n   */\n  put: (key: string, data: Buffer | Uint8Array | string, options?: UploadOptions) => Promise<HaiResult<FileMetadata>>\n\n  /**\n   * 下载文件\n   *\n   * @param key - 文件键/路径\n   * @param options - 下载选项\n   * @returns 文件内容\n   * @example\n   * ```ts\n   * const result = await storage.file.get('uploads/a.txt')\n   * if (result.success) {\n   *   const buffer = result.data\n   * }\n   * ```\n   */\n  get: (key: string, options?: DownloadOptions) => Promise<HaiResult<Buffer>>\n\n  /**\n   * 获取文件元数据\n   *\n   * @param key - 文件键/路径\n   * @returns 文件元数据\n   * @example\n   * ```ts\n   * const result = await storage.file.head('uploads/a.txt')\n   * if (result.success) {\n   *   result.data.size\n   * }\n   * ```\n   */\n  head: (key: string) => Promise<HaiResult<FileMetadata>>\n\n  /**\n   * 检查文件是否存在\n   *\n   * @param key - 文件键/路径\n   * @returns 是否存在\n   * @example\n   * ```ts\n   * const result = await storage.file.exists('uploads/a.txt')\n   * if (result.success) {\n   *   result.data\n   * }\n   * ```\n   */\n  exists: (key: string) => Promise<HaiResult<boolean>>\n\n  /**\n   * 删除文件\n   *\n   * @param key - 文件键/路径\n   * @returns 删除结果\n   * @example\n   * ```ts\n   * await storage.file.delete('uploads/a.txt')\n   * ```\n   */\n  delete: (key: string) => Promise<HaiResult<void>>\n\n  /**\n   * 批量删除文件\n   *\n   * @param keys - 文件键/路径列表\n   * @returns 删除结果\n   * @example\n   * ```ts\n   * await storage.file.deleteMany(['a.txt', 'b.txt'])\n   * ```\n   */\n  deleteMany: (keys: string[]) => Promise<HaiResult<void>>\n\n  /**\n   * 复制文件\n   *\n   * @param sourceKey - 源文件键\n   * @param destKey - 目标文件键\n   * @param options - 复制选项\n   * @returns 目标文件元数据\n   * @example\n   * ```ts\n   * await storage.file.copy('a.txt', 'b.txt')\n   * ```\n   */\n  copy: (sourceKey: string, destKey: string, options?: CopyOptions) => Promise<HaiResult<FileMetadata>>\n}\n\n/**\n * 目录操作接口\n *\n * 提供目录（前缀）的列表操作。\n */\nexport interface DirOperations {\n  /**\n   * 列出目录内容\n   *\n   * @param options - 列表选项\n   * @returns 文件和目录列表\n   * @example\n   * ```ts\n   * const result = await storage.dir.list({ prefix: 'uploads/' })\n   * if (result.success) {\n   *   result.data.files\n   * }\n   * ```\n   */\n  list: (options?: ListOptions) => Promise<HaiResult<ListResult>>\n\n  /**\n   * 删除目录（删除指定前缀下的所有文件）\n   *\n   * @param prefix - 目录前缀\n   * @returns 删除结果\n   * @example\n   * ```ts\n   * await storage.dir.delete('uploads/tmp/')\n   * ```\n   */\n  delete: (prefix: string) => Promise<HaiResult<void>>\n}\n\n/**\n * 签名 URL 操作接口\n *\n * 提供生成临时授权 URL 的功能，支持前端直接上传下载。\n */\nexport interface PresignOperations {\n  /**\n   * 生成下载签名 URL\n   *\n   * @param key - 文件键/路径\n   * @param options - 签名选项\n   * @returns 签名 URL\n   * @example\n   * ```ts\n   * const result = await storage.presign.getUrl('a.txt', { expiresIn: 60 })\n   * ```\n   */\n  getUrl: (key: string, options?: PresignOptions) => Promise<HaiResult<string>>\n\n  /**\n   * 生成上传签名 URL\n   *\n   * @param key - 文件键/路径\n   * @param options - 上传签名选项\n   * @returns 签名 URL\n   * @example\n   * ```ts\n   * const result = await storage.presign.putUrl('a.txt', { contentType: 'text/plain' })\n   * ```\n   */\n  putUrl: (key: string, options?: PresignUploadOptions) => Promise<HaiResult<string>>\n\n  /**\n   * 获取公开访问 URL（如果配置了 publicUrl）\n   *\n   * @param key - 文件键/路径\n   * @returns 公开 URL，如果未配置 publicUrl 则返回 null\n   * @example\n   * ```ts\n   * const url = storage.presign.publicUrl('a.txt')\n   * ```\n   */\n  publicUrl: (key: string) => string | null\n}\n\n// ─── 函数接口 ───\n\n/**\n * 存储函数接口\n *\n * 统一的存储访问入口：\n * - `storage.init()` — 初始化存储连接\n * - `storage.close()` — 关闭连接并释放资源\n * - `storage.file` — 文件操作（上传/下载/删除/复制等）\n * - `storage.dir` — 目录操作（列表/删除）\n * - `storage.presign` — 签名 URL 操作\n * - `storage.config` — 当前连接配置（未初始化时为 null）\n * - `storage.isInitialized` — 初始化状态\n */\nexport interface StorageFunctions {\n  /**\n   * 初始化存储连接\n   *\n   * 已有连接时会先 close 再重新初始化。\n   *\n   * @param config - 存储配置（支持省略带默认值的字段）\n   * @returns 成功 ok(undefined)；失败返回 err（含 StorageError）\n   */\n  init: (config: StorageConfigInput) => Promise<HaiResult<void>>\n\n  /**\n   * 关闭存储连接并释放资源\n   *\n   * 重复调用不会报错。\n   */\n  close: () => Promise<void>\n\n  /** 当前解析后的存储配置；未初始化或已关闭时为 null */\n  readonly config: StorageConfig | null\n\n  /** 是否已完成初始化 */\n  readonly isInitialized: boolean\n\n  /** 文件操作接口（put / get / head / exists / delete / deleteMany / copy） */\n  readonly file: FileOperations\n\n  /** 目录操作接口（list / delete） */\n  readonly dir: DirOperations\n\n  /** 签名 URL 操作接口（getUrl / putUrl / publicUrl） */\n  readonly presign: PresignOperations\n}\n\n// ─── Provider 接口 ───\n\n/**\n * 存储 Provider 接口\n *\n * 由各具体存储实现（S3、Local）实现此接口。\n * Provider 仅在 storage-main 内部使用，不直接对外暴露实例。\n */\nexport interface StorageProvider {\n  /** Provider 名称标识（如 's3'、'local'） */\n  readonly name: string\n\n  /**\n   * 建立与存储服务的连接\n   *\n   * @param config - 经 Schema 校验后的完整配置\n   * @returns 连接结果\n   */\n  connect: (config: StorageConfig) => Promise<HaiResult<void>>\n\n  /** 关闭连接并释放资源 */\n  close: () => Promise<void>\n\n  /** 检查是否已连接 */\n  isConnected: () => boolean\n\n  /** 文件操作接口 */\n  readonly file: FileOperations\n\n  /** 目录操作接口 */\n  readonly dir: DirOperations\n\n  /** 签名 URL 操作接口 */\n  readonly presign: PresignOperations\n}\n"]}