@h-ai/storage 1.0.0-beta.21 → 1.0.0-beta.22

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (15) hide show
  1. package/README.en.md +14 -6
  2. package/README.ja.md +14 -6
  3. package/README.md +14 -6
  4. package/dist/browser.d.ts +17 -32
  5. package/dist/browser.js +2 -2
  6. package/dist/{chunk-JAJYHGLI.js → chunk-RXYTWURA.js} +29 -42
  7. package/dist/chunk-RXYTWURA.js.map +1 -0
  8. package/dist/{chunk-FK7KRCML.js → chunk-WOVOQXRY.js} +19 -7
  9. package/dist/chunk-WOVOQXRY.js.map +1 -0
  10. package/dist/client/index.js +1 -1
  11. package/dist/node.js +320 -142
  12. package/dist/node.js.map +1 -1
  13. package/package.json +2 -2
  14. package/dist/chunk-FK7KRCML.js.map +0 -1
  15. package/dist/chunk-JAJYHGLI.js.map +0 -1
package/dist/chunk-WOVOQXRY.js.map ADDED
@@ -0,0 +1 @@
1
+ {"version":3,"sources":["../src/storage-config.ts","../src/storage-types.ts"],"names":[],"mappings":";;;;;AASA,IAAM,sBAAA,GAAyB,IAAI,IAAA,IAAQ,CAAA;AAC3C,IAAM,sBAAA,GAAyB,IAAI,IAAA,IAAQ,CAAA;AAkBpC,IAAM,oBAAoB,CAAA,CAAE,IAAA,CAAK,CAAC,IAAA,EAAM,OAAO,CAAC;AAwBhD,IAAM,+BAAA,GAAkC,EAAE,MAAA,CAAO;AAAA;AAAA,EAEtD,IAAA,EAAM,CAAA,CAAE,OAAA,EAAQ,CAAE,QAAQ,KAAK,CAAA;AAAA;AAAA,EAE/B,KAAA,EAAO,CAAA,CAAE,OAAA,EAAQ,CAAE,QAAQ,IAAI,CAAA;AAAA;AAAA,EAE/B,SAAA,EAAW,CAAA,CAAE,MAAA,EAAO,CAAE,GAAA,GAAM,GAAA,CAAI,CAAC,CAAA,CAAE,OAAA,CAAQ,GAAI;AACjD,CAAC;AAcD,IAAM,6BAAA,GAAgC;AAAA;AAAA,EAEpC,YAAA,EAAc,+BAAA,CAAgC,QAAA,CAAS,EAAE;AAC3D,CAAA;AAeO,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,YAAA,EAAc,CAAA,CAAE,OAAA,EAAQ,CAAE,QAAQ,KAAK,CAAA;AAAA;AAAA,EAGvC,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,gBAAgB,CAAA,CAAE,MAAA,EAAO,CAAE,MAAA,CAAO,CAAC,KAAA,KAAU;AAG3C,IAAA,OAAO,CAAC,2BAA2B,IAAA,CAAK,KAAK,KAAK,CAAC,yBAAA,CAA0B,KAAK,KAAK,CAAA;AAAA,EACzF,CAAA,EAAG,SAAS,sCAAsC,CAAC,EAAE,GAAA,EAAI,CAAE,MAAA,CAAO,CAAC,KAAA,KAAU;AAC3E,IAAA,IAAI;AACF,MAAA,MAAM,GAAA,GAAM,IAAI,GAAA,CAAI,KAAK,CAAA;AACzB,MAAA,OAAO,CAAC,SAAS,QAAQ,CAAA,CAAE,SAAS,GAAA,CAAI,QAAQ,CAAA,IAAK,CAAC,GAAA,CAAI,QAAA,IAAY,CAAC,GAAA,CAAI,QAAA,IACtE,mCAAA,CAAoC,IAAA,CAAK,GAAA,CAAI,QAAQ,KAAK,CAAC,GAAA,CAAI,MAAA,IAAU,CAAC,GAAA,CAAI,IAAA;AAAA,IACrF,CAAA,CAAA,MACM;AACJ,MAAA,OAAO,KAAA;AAAA,IACT;AAAA,EACF,CAAA,EAAG,QAAA,CAAS,sCAAsC,CAAC,EAAE,QAAA,EAAS;AAAA;AAAA,EAG9D,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,EAAS;AAAA;AAAA,EAGrC,SAAA,EAAW,EAAE,MAAA,CAAO;AAAA;AAAA,IAElB,aAAA,EAAe,CAAA,CAAE,MAAA,EAAO,CAAE,GAAA,EAAI,CAAE,GAAA,CAAI,sBAAsB,CAAA,CAAE,GAAA,CAAI,sBAAsB,CAAA,CAAE,QAAQ,sBAAsB,CAAA;AAAA;AAAA,IAEtH,SAAA,EAAW,CAAA,CAAE,MAAA,EAAO,CAAE,GAAA,GAAM,GAAA,CAAI,CAAC,CAAA,CAAE,OAAA,CAAQ,CAAC;AAAA,GAC7C,CAAA,CAAE,QAAA,CAAS,EAAE,CAAA;AAAA,EAEd,GAAG;AACL,CAAC;AA0BM,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,CAAA;AAAA,EAElC,GAAG;AACL,CAAC;AA0BM,IAAM,mBAAA,GAAsB,CAAA,CAAE,kBAAA,CAAmB,MAAA,EAAQ;AAAA,EAC9D,cAAA;AAAA,EACA;AACF,CAAC;AAwCM,IAAM,oBAAA,GAAuB,EAAE,MAAA,CAAO;AAAA;AAAA,EAE3C,SAAA,EAAW,6BAAA,CAA8B,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;AA0BM,IAAM,0BAAA,GAA6B,qBAAqB,MAAA,CAAO;AAAA;AAAA,EAEpE,WAAA,EAAa,CAAA,CAAE,MAAA,EAAO,CAAE,QAAQ,0BAA0B;AAC5D,CAAC;ACjRD,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,SAAA;AAAA,EACjB,eAAA,EAAiB,SAAA;AAAA,EACjB,gBAAA,EAAkB,SAAA;AAAA,EAClB,qBAAA,EAAuB,SAAA;AAAA,EACvB,oBAAA,EAAsB;AACxB,CAAA;AAaO,IAAM,eAAA,GAAkB,IAAA,CAAK,KAAA,CAAM,iBAAA,CAAkB,WAAW,gBAAgB","file":"chunk-WOVOQXRY.js","sourcesContent":["/**\n * @h-ai/storage — 存储配置 Schema\n * @module storage-config\n */\n\nimport { z } from 'zod'\nimport { storageM } from './storage-i18n.js'\nimport { StoragePresignExpiresInSchema } from './storage-schemas.js'\n\nconst S3_MIN_PART_SIZE_BYTES = 5 * 1024 ** 2\nconst S3_MAX_PART_SIZE_BYTES = 5 * 1024 ** 3\n\n// ─── 配置 Schema ───\n\n/**\n * 存储类型枚举\n *\n * 支持的存储类型：\n * - `s3` - S3 协议对象存储（兼容 AWS S3、MinIO、RustFS、阿里云 OSS 等）\n * - `local` - 本地文件存储（仅后端）\n * @example\n * ```ts\n * import { StorageTypeSchema } from '@h-ai/storage'\n *\n * const value = StorageTypeSchema.parse('local')\n * void value\n * ```\n */\nexport const StorageTypeSchema = z.enum(['s3', 'local'])\n\n/**\n * 存储类型\n * @example\n * ```ts\n * import type { StorageType } from '@h-ai/storage'\n *\n * const value: StorageType = 's3'\n * void value\n * ```\n */\nexport type StorageType = z.infer<typeof StorageTypeSchema>\n\n/**\n * StorageOperationLogConfigSchema 的数据约束与操作契约。\n * @example\n * ```ts\n * import { StorageOperationLogConfigSchema } from '@h-ai/storage'\n *\n * const value = StorageOperationLogConfigSchema.parse({ read: false, write: true, maxLength: 500 })\n * void value\n * ```\n */\nexport const StorageOperationLogConfigSchema = z.object({\n /** 以 debug 记录读取操作，默认关闭。 */\n read: z.boolean().default(false),\n /** 以 debug 记录写入操作，默认开启。 */\n write: z.boolean().default(true),\n /** 诊断摘要的字符上限，0 省略摘要。 */\n maxLength: z.number().int().min(0).default(1000),\n})\n\n/**\n * StorageOperationLogConfig 的数据约束与操作契约。\n * @example\n * ```ts\n * import { StorageOperationLogConfigSchema, type StorageOperationLogConfig } from '@h-ai/storage'\n *\n * const value: StorageOperationLogConfig = StorageOperationLogConfigSchema.parse({ read: false, write: true, maxLength: 500 })\n * void value\n * ```\n */\nexport type StorageOperationLogConfig = z.infer<typeof StorageOperationLogConfigSchema>\n\nconst OperationLogConfigFieldSchema = {\n /** 文件、目录和签名操作的 debug 日志开关与安全摘要长度。 */\n operationLog: StorageOperationLogConfigSchema.prefault({}),\n}\n\n/**\n * S3 存储配置 Schema\n *\n * 支持标准 AWS S3 以及兼容 S3 协议的存储服务（MinIO、RustFS、阿里云 OSS 等）。\n * 必填字段：bucket、region、accessKeyId、secretAccessKey。\n * @example\n * ```ts\n * import { S3ConfigSchema } from '@h-ai/storage'\n *\n * const value = S3ConfigSchema.parse({ type: 's3', bucket: 'uploads', region: 'us-east-1', accessKeyId: process.env.HAI_STORAGE_ACCESS_KEY_ID, secretAccessKey: process.env.HAI_STORAGE_SECRET_ACCESS_KEY })\n * void value\n * ```\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 createBucket: z.boolean().default(false),\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、RustFS、阿里云 OSS 等） */\n endpoint: z.string().url().optional(),\n\n /** 浏览器预签名端点，可含代理目录（如 /delivery/files），不含桶名、凭据或查询；代理须去除目录并保留 Host。 */\n publicEndpoint: z.string().refine((value) => {\n // 必须先检查原始文本；URL 校验会移除制表符和换行，不能在标准化后再检查。\n // eslint-disable-next-line no-control-regex -- 在入口显式拒绝控制字符，避免校验与代理解释不一致。\n return !/[\\u0000-\\u0020\\u007F\\\\%]/.test(value) && !/(?:^|\\/)\\.{1,2}(?:\\/|$)/.test(value)\n }, storageM('storage_config_publicEndpointInvalid')).url().refine((value) => {\n try {\n const url = new URL(value)\n return ['http:', 'https:'].includes(url.protocol) && !url.username && !url.password\n && /^\\/(?:[\\w.-]+(?:\\/[\\w.-]+)*\\/?)?$/.test(url.pathname) && !url.search && !url.hash\n }\n catch {\n return false\n }\n }, storageM('storage_config_publicEndpointInvalid')).optional(),\n\n /** 强制使用路径风格 URL（某些 S3 兼容服务需要） */\n forcePathStyle: z.boolean().default(false),\n\n /** S3 桶内对象键前缀，例如 my-app/uploads/，留空使用桶根 */\n prefix: z.string().default(''),\n\n /** 公开访问基础 URL（用于生成公开 URL） */\n publicUrl: z.string().url().optional(),\n\n /** S3 服务端流式上传的分片设置。 */\n multipart: z.object({\n /** 每片字节数，默认 5 MiB，范围 5 MiB 至 5 GiB。 */\n partSizeBytes: z.number().int().min(S3_MIN_PART_SIZE_BYTES).max(S3_MAX_PART_SIZE_BYTES).default(S3_MIN_PART_SIZE_BYTES),\n /** 单次上传的最大并发片数，默认 2。 */\n queueSize: z.number().int().min(1).default(2),\n }).prefault({}),\n\n ...OperationLogConfigFieldSchema,\n})\n\n/**\n * S3 配置类型（parse 后，带默认值的字段已填充，optional 字段仍可缺省）\n * @example\n * ```ts\n * import { S3ConfigSchema, type S3Config } from '@h-ai/storage'\n *\n * const value: S3Config = S3ConfigSchema.parse({ type: 's3', bucket: 'uploads', region: 'us-east-1', accessKeyId: process.env.HAI_STORAGE_ACCESS_KEY_ID, secretAccessKey: process.env.HAI_STORAGE_SECRET_ACCESS_KEY })\n * void value\n * ```\n */\nexport type S3Config = z.infer<typeof S3ConfigSchema>\n\n/**\n * 本地存储配置 Schema\n *\n * 基于本地文件系统，仅后端可用。必填字段：root。\n * @example\n * ```ts\n * import { LocalConfigSchema } from '@h-ai/storage'\n *\n * const value = LocalConfigSchema.parse({ type: 'local', root: './data/uploads' })\n * void value\n * ```\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 ...OperationLogConfigFieldSchema,\n})\n\n/**\n * 本地配置类型（parse 后，带默认值的字段已填充，optional 字段仍可缺省）\n * @example\n * ```ts\n * import { LocalConfigSchema, type LocalConfig } from '@h-ai/storage'\n *\n * const value: LocalConfig = LocalConfigSchema.parse({ type: 'local', root: './data/uploads' })\n * void value\n * ```\n */\nexport type LocalConfig = z.infer<typeof LocalConfigSchema>\n\n/**\n * 统一存储配置 Schema\n *\n * 支持 S3 和本地文件两种类型的配置验证。\n * @example\n * ```ts\n * import { StorageConfigSchema } from '@h-ai/storage'\n *\n * const value = StorageConfigSchema.parse({ type: 'local', root: './data/uploads' })\n * void value\n * ```\n */\nexport const StorageConfigSchema = z.discriminatedUnion('type', [\n S3ConfigSchema,\n LocalConfigSchema,\n])\n\n/**\n * 存储配置类型（parse 后的完整配置）\n * @example\n * ```ts\n * import { StorageConfigSchema, type StorageConfig } from '@h-ai/storage'\n *\n * const value: StorageConfig = StorageConfigSchema.parse({ type: 'local', root: './data/uploads' })\n * void value\n * ```\n */\nexport type StorageConfig = z.infer<typeof StorageConfigSchema>\n\n/**\n * 存储配置输入类型（parse 前，允许省略带默认值的字段）\n * @example\n * ```ts\n * import type { StorageConfigInput } from '@h-ai/storage'\n *\n * const value: StorageConfigInput = { type: 'local', root: './data/uploads' }\n * void value\n * ```\n */\nexport type StorageConfigInput = z.input<typeof StorageConfigSchema>\n\n// ─── 签名 URL 配置 ───\n\n/**\n * 签名 URL 配置 Schema\n *\n * 用于控制 `storage.presign.getUrl()` 生成的下载签名 URL 参数。\n * @example\n * ```ts\n * import { PresignOptionsSchema } from '@h-ai/storage'\n *\n * const value = PresignOptionsSchema.parse({ expiresIn: 60 })\n * void value\n * ```\n */\nexport const PresignOptionsSchema = z.object({\n /** 过期时间（秒），范围 1~604800（7 天），默认 3600（1 小时） */\n expiresIn: StoragePresignExpiresInSchema.default(3600), // 最长 7 天\n\n /** 响应内容类型（用于下载时设置 Content-Type） */\n responseContentType: z.string().optional(),\n\n /** 响应内容处置（用于设置下载文件名） */\n responseContentDisposition: z.string().optional(),\n})\n\n/**\n * 签名 URL 输入选项，允许省略带默认值的字段。\n * @example\n * ```ts\n * import type { PresignOptions } from '@h-ai/storage'\n *\n * const value: PresignOptions = { expiresIn: 60, responseContentType: 'text/plain' }\n * void value\n * ```\n */\nexport type PresignOptions = z.input<typeof PresignOptionsSchema>\n\n/**\n * 上传签名 URL 配置 Schema\n *\n * 继承 PresignOptionsSchema 并扩展上传专属参数，用于 `storage.presign.putUrl()`。\n * @example\n * ```ts\n * import { PresignUploadOptionsSchema } from '@h-ai/storage'\n *\n * const value = PresignUploadOptionsSchema.parse({ contentType: 'text/plain' })\n * void value\n * ```\n */\nexport const PresignUploadOptionsSchema = PresignOptionsSchema.extend({\n /** 上传内容类型（必须与实际上传匹配） */\n contentType: z.string().default('application/octet-stream'),\n})\n\n/**\n * 上传签名 URL 输入选项，省略 contentType 时使用 application/octet-stream。\n * @example\n * ```ts\n * import type { PresignUploadOptions } from '@h-ai/storage'\n *\n * const value: PresignUploadOptions = { expiresIn: 60, contentType: 'text/plain' }\n * void value\n * ```\n */\nexport type PresignUploadOptions = z.input<typeof PresignUploadOptionsSchema>\n","/**\n * @h-ai/storage — 公共类型定义\n *\n * 包含：\n * - 错误定义（HaiStorageError）\n * - 文件元数据（FileMetadata）\n * - 列表结果（ListResult）\n * - 文件操作接口（FileOperations）\n * - 目录操作接口（DirOperations）\n * - 签名 URL 操作接口（PresignOperations）\n * - 函数接口（StorageFunctions）\n * @module storage-types\n */\n\nimport type { ErrorInfo, HaiError, 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 CHECKSUM_FAILED: '016:500',\n INVALID_CHECKSUM: '017:400',\n UNSUPPORTED_OPERATION: '018:400',\n INVALID_LIST_OPTIONS: '019:400',\n} as const satisfies ErrorInfo\n\n/**\n * HaiStorageError 的数据约束与操作契约。\n * @example\n * ```ts\n * import { HaiStorageError } from '@h-ai/storage'\n * import { err } from '@h-ai/core'\n *\n * const result = err(HaiStorageError.NOT_FOUND, 'File missing')\n * if (!result.success) void result.error.code\n * ```\n */\nexport const HaiStorageError = core.error.buildHaiErrorsDef('storage', StorageErrorInfo)\n\n/**\n * 批量删除中未确认完成的一项；key 始终使用调用方视角，不含 Provider prefix。\n * @example\n * ```ts\n * import type { StorageDeleteFailure } from '@h-ai/storage'\n *\n * const value: StorageDeleteFailure = { key: 'private.txt', code: 'AccessDenied', retryable: false, outcome: 'failed' }\n * void value\n * ```\n */\nexport interface StorageDeleteFailure {\n /** 调用方提交的文件键。 */\n key: string\n /** 渠道/框架错误标识，不包含渠道原始 Message。 */\n code: string\n /** 是否属于可重试的瞬时故障；未知结果重试前仍需考虑并发上传/版本语义。 */\n retryable: boolean\n /** failed 为已知失败，unknown 为已发送但结果未知，notAttempted 为尚未发送。 */\n outcome: 'failed' | 'unknown' | 'notAttempted'\n}\n\n/**\n * 批量删除进度；任一失败不能宣称全部删除完成。\n * @example\n * ```ts\n * import type { StorageDeleteSummary } from '@h-ai/storage'\n *\n * const value: StorageDeleteSummary = { deletedKeys: ['a.txt'], failures: [] }\n * void value\n * ```\n */\nexport interface StorageDeleteSummary {\n /** 已确认删除或本来就不存在的唯一文件键。 */\n deletedKeys: string[]\n /** 失败、未知及尚未尝试的唯一文件键。 */\n failures: StorageDeleteFailure[]\n}\n\n/**\n * 批量删除结果；失败仍遵守 HaiResult，部分进度置于 error.ext.deleteMany。\n * @example\n * ```ts\n * import { storage, type StorageDeleteResult } from '@h-ai/storage'\n *\n * async function remove() {\n * const result: StorageDeleteResult = await storage.file.deleteMany(['a.txt', 'b.txt'])\n * return result.success ? result.data : result.error.ext?.deleteMany\n * }\n * ```\n */\nexport type StorageDeleteResult\n = | { success: true, data: StorageDeleteSummary }\n | { success: false, error: HaiError & { ext?: Record<string, unknown> & { deleteMany?: StorageDeleteSummary } } }\n\n// ─── 文件元数据 ───\n\n/**\n * 文件元数据接口\n *\n * 表示存储中单个文件的元信息，由 put/head/copy/list 等操作返回。\n * @example\n * ```ts\n * import type { FileMetadata } from '@h-ai/storage'\n *\n * const value: FileMetadata = { key: 'a.txt', size: 5, contentType: 'text/plain', lastModified: new Date() }\n * void value\n * ```\n */\nexport interface FileMetadata {\n /** 文件键/路径（不含配置 prefix，对用户透明） */\n key: string\n /** 文件大小（字节） */\n size: number\n /** 内容类型（MIME），未指定时根据扩展名自动推断 */\n contentType: string\n /** 最后修改时间 */\n lastModified: Date\n /** ETag（缓存验证标记；本地为 size-mtime，S3 由服务端生成，不等同于内容 checksum） */\n etag?: string\n /** 自定义元数据键值对 */\n metadata?: Record<string, string>\n}\n\n/**\n * 列表选项\n *\n * 用于控制 `storage.dir.list()` 的过滤、分页和目录模拟行为。\n * @example\n * ```ts\n * import type { ListOptions } from '@h-ai/storage'\n *\n * const value: ListOptions = { prefix: 'reports/', delimiter: '/', maxKeys: 100 }\n * void value\n * ```\n */\nexport interface ListOptions {\n /** 前缀过滤（只返回以此前缀开头的文件） */\n prefix?: string\n /**\n * 分页标记（从上次 ListResult.nextContinuationToken 获取）\n *\n * Local 游标绑定根目录、prefix 和 delimiter，可跨实例使用；不得跨查询或 provider 混用。\n */\n continuationToken?: string\n /** 每页逻辑条目上限（1–1000，默认 1000）；files 和 commonPrefixes 合计计数。 */\n maxKeys?: number\n /** 分隔符，通常为 '/'；从 prefix 之后首次出现的位置折叠 commonPrefixes，空字符串表示不折叠。 */\n delimiter?: string\n}\n\n/**\n * 列表结果\n *\n * 包含当前页的文件列表、目录前缀、分页信息。\n * @example\n * ```ts\n * import type { ListResult } from '@h-ai/storage'\n *\n * const value: ListResult = { files: [], commonPrefixes: ['reports/'], isTruncated: false }\n * void value\n * ```\n */\nexport interface ListResult {\n /** 当前页文件元数据列表 */\n files: FileMetadata[]\n /** 公共前缀：由实际匹配文件按 delimiter 折叠，不包含 Local 空物理目录。 */\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 * @example\n * ```ts\n * import type { UploadOptions } from '@h-ai/storage'\n *\n * const value: UploadOptions = { ifNoneMatch: '*', contentType: 'text/plain', signal: new AbortController().signal }\n * void value\n * ```\n */\nexport interface UploadOptions {\n /** 仅当 key 不存在时原子写入；S3 使用标准 If-None-Match，后端不支持时返回错误。 */\n ifNoneMatch?: '*'\n /** 取消上传；失败或取消时清理未完成的临时文件/分片。 */\n signal?: AbortSignal\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 * @example\n * ```ts\n * import type { DownloadOptions } from '@h-ai/storage'\n *\n * const value: DownloadOptions = { rangeStart: 0, rangeEnd: 99 }\n * void value\n * ```\n */\nexport interface DownloadOptions {\n /** 取消读取。 */\n signal?: AbortSignal\n /** 范围起始位置（字节，含）；不指定时从文件开头读取 */\n rangeStart?: number\n /** 范围结束位置（字节，含）；不指定时读取到文件末尾 */\n rangeEnd?: number\n}\n\n/**\n * 复制选项\n *\n * 用于控制 `storage.file.copy()` 的目标文件元数据。\n * 提供任意字段时，S3 Provider 会使用 MetadataDirective='REPLACE' 覆盖源文件元数据。\n * @example\n * ```ts\n * import type { CopyOptions } from '@h-ai/storage'\n *\n * const value: CopyOptions = { contentType: 'text/plain', metadata: { category: 'reports' } }\n * void value\n * ```\n */\nexport interface CopyOptions {\n /** 目标文件的内容类型（不指定时继承源文件） */\n contentType?: string\n /** 目标文件的自定义元数据（不指定时继承源文件） */\n metadata?: Record<string, string>\n}\n\n// ─── 操作接口 ───\n\n/**\n * 文件内容；异步字节流支持 Node Readable 等，不将整个文件载入内存。\n * @example\n * ```ts\n * import type { StorageData } from '@h-ai/storage'\n *\n * const value: StorageData = new TextEncoder().encode('hello')\n * void value\n * ```\n */\nexport type StorageData = Buffer | Uint8Array | string | AsyncIterable<Uint8Array>\n\n/**\n * 常见 checksum 算法；MD5/SHA-1 仅用于兼容性完整性校验，不用于安全认证。\n * @example\n * ```ts\n * import type { ChecksumAlgorithm } from '@h-ai/storage'\n *\n * const value: ChecksumAlgorithm = 'sha256'\n * void value\n * ```\n */\nexport type ChecksumAlgorithm = 'sha256' | 'sha384' | 'sha512' | 'sha1' | 'md5'\n\n/**\n * checksum 计算选项；默认 SHA-256、小写 hex。\n * @example\n * ```ts\n * import type { ChecksumOptions } from '@h-ai/storage'\n *\n * const value: ChecksumOptions = { algorithm: 'sha256', encoding: 'hex' }\n * void value\n * ```\n */\nexport interface ChecksumOptions {\n algorithm?: ChecksumAlgorithm\n encoding?: 'hex' | 'base64'\n signal?: AbortSignal\n}\n\n/**\n * Node 端无状态 checksum 工具，不依赖 storage.init；流输入仅消费一次。\n * @example\n * ```ts\n * import type { ChecksumOperations } from '@h-ai/storage'\n *\n * async function inspect(operations: ChecksumOperations) {\n * const result = await operations.generate('hello')\n * if (!result.success) return result.error.message\n * return result.data\n * }\n * ```\n */\nexport interface ChecksumOperations {\n generate: (data: StorageData, options?: ChecksumOptions) => Promise<HaiResult<string>>\n verify: (data: StorageData, expected: string, options?: ChecksumOptions) => Promise<HaiResult<boolean>>\n}\n\n/**\n * 文件操作接口\n *\n * 提供文件的读写操作。\n * @example\n * ```ts\n * import type { FileOperations } from '@h-ai/storage'\n *\n * async function inspect(operations: FileOperations) {\n * const result = await operations.getStream('reports/a.txt')\n * if (!result.success) return result.error.message\n * for await (const chunk of result.data) void chunk.byteLength\n * }\n * ```\n */\nexport interface FileOperations {\n /**\n * 上传文件\n *\n * @param key - 文件键/路径\n * @param data - 文件内容（Buffer、Uint8Array、字符串或异步字节流）\n * @param options - 上传选项\n * @returns 成功包含文件元数据。失败包含错误码和消息，底层原因可用时保留在 error.cause。\n * `ifNoneMatch: '*'` 的目标冲突返回 ALREADY_EXISTS，上传源读取失败返回 UPLOAD_FAILED。\n * S3 流式上传可从 error.ext.s3Operation 获取失败操作，清理错误单独保存在 error.ext.cleanupError。\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: StorageData, 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 * void buffer\n * }\n * ```\n */\n get: (key: string, options?: DownloadOptions) => Promise<HaiResult<Buffer>>\n\n /**\n * 读取字节流，支持 Range 与取消；消费方负责及时迭代或关闭流。\n * @throws 迭代期间的 I/O/取消错误；初始请求失败通过 HaiResult 返回。\n * @example\n * ```ts\n * import { storage } from '@h-ai/storage'\n *\n * const result = await storage.file.getStream('reports/a.txt')\n * if (!result.success) throw new Error(result.error.message)\n * try {\n * for await (const chunk of result.data) void chunk.byteLength\n * } catch (error) {\n * // 初始请求成功后，迭代仍可能因 I/O/取消失败。\n * throw error\n * }\n * ```\n */\n getStream: (key: string, options?: DownloadOptions) => Promise<HaiResult<AsyncIterable<Uint8Array>>>\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 * import { storage } from '@h-ai/storage'\n *\n * const result = await storage.file.delete('uploads/a.txt')\n * if (!result.success) throw new Error(result.error.message)\n * ```\n */\n delete: (key: string) => Promise<HaiResult<void>>\n\n /**\n * 批量删除文件\n *\n * @param keys - 文件键/路径列表\n * @returns 全部成功时返回进度；任一失败时 success=false，进度在 error.ext.deleteMany\n * @example\n * ```ts\n * const result = await storage.file.deleteMany(['a.txt', 'b.txt'])\n * const progress = result.success ? result.data : result.error.ext?.deleteMany\n * void progress\n * ```\n */\n deleteMany: (keys: string[]) => Promise<StorageDeleteResult>\n\n /**\n * 复制文件\n *\n * @param sourceKey - 源文件键\n * @param destKey - 目标文件键\n * @param options - 复制选项\n * @returns 目标文件元数据\n * @example\n * ```ts\n * import { storage } from '@h-ai/storage'\n *\n * const result = await storage.file.copy('a.txt', 'b.txt')\n * if (!result.success) throw new Error(result.error.message)\n * void result.data.key\n * ```\n */\n copy: (sourceKey: string, destKey: string, options?: CopyOptions) => Promise<HaiResult<FileMetadata>>\n}\n\n/**\n * 目录操作接口\n *\n * 提供目录（前缀）的列表操作。\n * @example\n * ```ts\n * import type { DirOperations } from '@h-ai/storage'\n *\n * async function inspect(operations: DirOperations) {\n * const page = await operations.list({ prefix: 'reports/', maxKeys: 100 })\n * if (!page.success) return page.error.message\n * return page.data.files\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 * import { storage } from '@h-ai/storage'\n *\n * const result = await storage.dir.delete('uploads/tmp/')\n * if (!result.success) throw new Error(result.error.message)\n * ```\n */\n delete: (prefix: string) => Promise<HaiResult<void>>\n}\n\n/**\n * 签名 URL 操作接口\n *\n * S3 provider 提供临时授权 URL，支持前端直接上传下载。\n * local 的 getUrl/putUrl 返回 UNSUPPORTED_OPERATION，publicUrl 返回 null。\n * @example\n * ```ts\n * import type { PresignOperations } from '@h-ai/storage'\n *\n * async function inspect(operations: PresignOperations) {\n * const signed = await operations.putUrl('reports/a.txt', { contentType: 'text/plain', expiresIn: 300 })\n * if (!signed.success) return signed.error.message\n * return signed.data\n * }\n * ```\n */\nexport interface PresignOperations {\n /**\n * 生成 GET 下载签名 URL；使用 publicEndpoint，缺省回退 endpoint/AWS 端点。\n * publicEndpoint 可含代理目录，返回值已带此前缀；代理须去除它并保留 S3 URI/Host/query，调用方不得自行改写。\n *\n * @param key - 文件键/路径\n * @param options - 签名选项\n * @returns 成功时为可访问的 S3 签名 URL；local 返回 UNSUPPORTED_OPERATION。\n * @example\n * ```ts\n * const result = await storage.presign.getUrl('a.txt', { expiresIn: 60 })\n * if (!result.success) throw new Error(result.error.message)\n * const downloadUrl = result.data\n * void downloadUrl\n * ```\n */\n getUrl: (key: string, options?: PresignOptions) => Promise<HaiResult<string>>\n\n /**\n * 生成 PUT 上传签名 URL；publicEndpoint 目录与 GET 相同处理，服务端 CRUD 仍使用内部 endpoint。\n *\n * @param key - 文件键/路径\n * @param options - 上传签名选项\n * @returns 成功时为可访问的 S3 签名 URL；local 返回 UNSUPPORTED_OPERATION。\n * @example\n * ```ts\n * const result = await storage.presign.putUrl('a.txt', { contentType: 'text/plain' })\n * if (!result.success) throw new Error(result.error.message)\n * const uploadUrl = result.data\n * void uploadUrl\n * ```\n */\n putUrl: (key: string, options?: PresignUploadOptions) => Promise<HaiResult<string>>\n\n /**\n * 获取公开访问 URL（如果配置了 publicUrl）\n *\n * @param key - 文件键/路径\n * @returns 公开 URL；S3 未配置 publicUrl 或 local provider 均返回 null。\n * @example\n * ```ts\n * const url = storage.presign.publicUrl('a.txt')\n * void url\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 * @example\n * ```ts\n * import { storage } from '@h-ai/storage'\n *\n * const initialized = await storage.init({ type: 'local', root: './data/uploads' })\n * if (!initialized.success) throw new Error(initialized.error.message)\n * try {\n * const uploaded = await storage.file.put('reports/a.txt', 'hello', { ifNoneMatch: '*' })\n * if (!uploaded.success) throw new Error(uploaded.error.message)\n * const downloaded = await storage.file.get('reports/a.txt')\n * if (!downloaded.success) throw new Error(downloaded.error.message)\n * void downloaded.data\n * } finally {\n * const closed = await storage.close()\n * if (!closed.success) throw new Error(closed.error.message)\n * }\n * ```\n */\nexport interface StorageFunctions {\n /** 无状态 checksum 生成与校验，Node 专用，无需初始化。 */\n readonly checksum: ChecksumOperations\n /**\n * 初始化存储连接\n *\n * 已有连接时会先 close 再重新初始化。\n *\n * @param config - 存储配置（支持省略带默认值的字段）\n * @returns 成功 ok(undefined)；失败返回 err（含 HaiStorageError 定义的错误信息）\n * @example\n * ```ts\n * import { storage } from '@h-ai/storage'\n *\n * const initialized = await storage.init({ type: 'local', root: './data/uploads' })\n * if (!initialized.success) throw new Error(initialized.error.message)\n * const closed = await storage.close()\n * if (!closed.success) throw new Error(closed.error.message)\n * ```\n */\n init: (config: StorageConfigInput) => Promise<HaiResult<void>>\n\n /**\n * 关闭存储连接并释放资源\n *\n * 等待初始化并合并并发关闭；失败时操作不可用，资源保留供 close/init 重试。\n * @returns 所有资源释放成功才返回成功；未初始化时同样成功。\n * @example\n * ```ts\n * import { storage } from '@h-ai/storage'\n *\n * const closed = await storage.close()\n * if (!closed.success) throw new Error(closed.error.message)\n * ```\n */\n close: () => Promise<HaiResult<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"]}
package/dist/client/index.js CHANGED
@@ -1,3 +1,3 @@
1
- export { downloadAndSave, downloadWithPresignedUrl, formatFileSize, getFileExtension, getMimeType, uploadWithPresignedUrl } from '../chunk-JAJYHGLI.js';
1
+ export { downloadAndSave, downloadWithPresignedUrl, formatFileSize, getFileExtension, getMimeType, uploadWithPresignedUrl } from '../chunk-RXYTWURA.js';
2
2
  //# sourceMappingURL=index.js.map
3
3
  //# sourceMappingURL=index.js.map