@h-ai/storage 0.1.0-alpha.66 → 0.1.0-alpha.68

package/dist/browser.d.ts

@@ -1,11 +1,12 @@
 export { ClientDownloadOptions, ClientUploadOptions, UploadProgress, downloadAndSave, downloadWithPresignedUrl, formatFileSize, getFileExtension, getMimeType, uploadWithPresignedUrl } from './client/index.js';
 import { z } from 'zod';
+export { STORAGE_DELETE_MAX_KEYS, STORAGE_KEY_MAX_BYTES, StorageDeleteKeysSchema, StorageKeyIssue, StorageKeySchema, StoragePrefixSchema, StoragePresignExpiresInSchema, getStorageKeyIssue } from './schemas.js';
 import * as _h_ai_core from '@h-ai/core';
-import { HaiResult } from '@h-ai/core';
+import { HaiResult, HaiError } from '@h-ai/core';
 import { Buffer } from 'node:buffer';
 
 /**
- * @h-ai/storage — 错误码 + 配置 Schema
+ * @h-ai/storage — 存储配置 Schema
  * @module storage-config
  */
 
@@ -15,13 +16,39 @@ import { Buffer } from 'node:buffer';
  * 支持的存储类型：
  * - `s3` - S3 协议对象存储（兼容 AWS S3、MinIO、RustFS、阿里云 OSS 等）
  * - `local` - 本地文件存储（仅后端）
+ * @example
+ * ```ts
+ * import { StorageTypeSchema } from '@h-ai/storage'
+ *
+ * const value = StorageTypeSchema.parse('local')
+ * void value
+ * ```
  */
 declare const StorageTypeSchema: z.ZodEnum<{
     s3: "s3";
     local: "local";
 }>;
-/** 存储类型 */
+/**
+ * 存储类型
+ * @example
+ * ```ts
+ * import type { StorageType } from '@h-ai/storage'
+ *
+ * const value: StorageType = 's3'
+ * void value
+ * ```
+ */
 type StorageType = z.infer<typeof StorageTypeSchema>;
+/**
+ * StorageOperationLogConfigSchema 的数据约束与操作契约。
+ * @example
+ * ```ts
+ * import { StorageOperationLogConfigSchema } from '@h-ai/storage'
+ *
+ * const value = StorageOperationLogConfigSchema.parse({ read: false, write: true, maxLength: 500, level: 'debug' })
+ * void value
+ * ```
+ */
 declare const StorageOperationLogConfigSchema: z.ZodObject<{
     read: z.ZodDefault<z.ZodBoolean>;
     write: z.ZodDefault<z.ZodBoolean>;
@@ -32,12 +59,29 @@ declare const StorageOperationLogConfigSchema: z.ZodObject<{
         trace: "trace";
     }>>;
 }, z.core.$strip>;
+/**
+ * StorageOperationLogConfig 的数据约束与操作契约。
+ * @example
+ * ```ts
+ * import { StorageOperationLogConfigSchema, type StorageOperationLogConfig } from '@h-ai/storage'
+ *
+ * const value: StorageOperationLogConfig = StorageOperationLogConfigSchema.parse({ read: false, write: true, maxLength: 500, level: 'debug' })
+ * void value
+ * ```
+ */
 type StorageOperationLogConfig = z.infer<typeof StorageOperationLogConfigSchema>;
 /**
  * S3 存储配置 Schema
  *
  * 支持标准 AWS S3 以及兼容 S3 协议的存储服务（MinIO、RustFS、阿里云 OSS 等）。
  * 必填字段：bucket、region、accessKeyId、secretAccessKey。
+ * @example
+ * ```ts
+ * import { S3ConfigSchema } from '@h-ai/storage'
+ *
+ * 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 })
+ * void value
+ * ```
  */
 declare const S3ConfigSchema: z.ZodObject<{
     operationLog: z.ZodOptional<z.ZodObject<{
@@ -60,12 +104,28 @@ declare const S3ConfigSchema: z.ZodObject<{
     prefix: z.ZodDefault<z.ZodString>;
     publicUrl: z.ZodOptional<z.ZodString>;
 }, z.core.$strip>;
-/** S3 配置类型（parse 后，所有字段已填充默认值） */
+/**
+ * S3 配置类型（parse 后，带默认值的字段已填充，optional 字段仍可缺省）
+ * @example
+ * ```ts
+ * import { S3ConfigSchema, type S3Config } from '@h-ai/storage'
+ *
+ * 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 })
+ * void value
+ * ```
+ */
 type S3Config = z.infer<typeof S3ConfigSchema>;
 /**
  * 本地存储配置 Schema
  *
  * 基于本地文件系统，仅后端可用。必填字段：root。
+ * @example
+ * ```ts
+ * import { LocalConfigSchema } from '@h-ai/storage'
+ *
+ * const value = LocalConfigSchema.parse({ type: 'local', root: './data/uploads' })
+ * void value
+ * ```
  */
 declare const LocalConfigSchema: z.ZodObject<{
     operationLog: z.ZodOptional<z.ZodObject<{
@@ -83,40 +143,27 @@ declare const LocalConfigSchema: z.ZodObject<{
     directoryMode: z.ZodDefault<z.ZodNumber>;
     fileMode: z.ZodDefault<z.ZodNumber>;
 }, z.core.$strip>;
-/** 本地配置类型（parse 后，所有字段已填充默认值） */
+/**
+ * 本地配置类型（parse 后，带默认值的字段已填充，optional 字段仍可缺省）
+ * @example
+ * ```ts
+ * import { LocalConfigSchema, type LocalConfig } from '@h-ai/storage'
+ *
+ * const value: LocalConfig = LocalConfigSchema.parse({ type: 'local', root: './data/uploads' })
+ * void value
+ * ```
+ */
 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
- * })
+ * import { StorageConfigSchema } from '@h-ai/storage'
  *
- * // 本地存储配置
- * const localConfig = StorageConfigSchema.parse({
- *     type: 'local',
- *     root: '/data/uploads'
- * })
+ * const value = StorageConfigSchema.parse({ type: 'local', root: './data/uploads' })
+ * void value
  * ```
  */
 declare const StorageConfigSchema: z.ZodDiscriminatedUnion<[z.ZodObject<{
@@ -155,21 +202,38 @@ declare const StorageConfigSchema: z.ZodDiscriminatedUnion<[z.ZodObject<{
     directoryMode: z.ZodDefault<z.ZodNumber>;
     fileMode: z.ZodDefault<z.ZodNumber>;
 }, z.core.$strip>], "type">;
-/** 存储配置类型（parse 后的完整配置） */
+/**
+ * 存储配置类型（parse 后的完整配置）
+ * @example
+ * ```ts
+ * import { StorageConfigSchema, type StorageConfig } from '@h-ai/storage'
+ *
+ * const value: StorageConfig = StorageConfigSchema.parse({ type: 'local', root: './data/uploads' })
+ * void value
+ * ```
+ */
 type StorageConfig = z.infer<typeof StorageConfigSchema>;
-/** 存储配置输入类型（parse 前，允许省略带默认值的字段） */
+/**
+ * 存储配置输入类型（parse 前，允许省略带默认值的字段）
+ * @example
+ * ```ts
+ * import type { StorageConfigInput } from '@h-ai/storage'
+ *
+ * const value: StorageConfigInput = { type: 'local', root: './data/uploads' }
+ * void value
+ * ```
+ */
 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"',
- * })
+ * import { PresignOptionsSchema } from '@h-ai/storage'
+ *
+ * const value = PresignOptionsSchema.parse({ expiresIn: 60 })
+ * void value
  * ```
  */
 declare const PresignOptionsSchema: z.ZodObject<{
@@ -177,19 +241,27 @@ declare const PresignOptionsSchema: z.ZodObject<{
     responseContentType: z.ZodOptional<z.ZodString>;
     responseContentDisposition: z.ZodOptional<z.ZodString>;
 }, z.core.$strip>;
-/** 签名 URL 配置类型（parse 后） */
-type PresignOptions = z.infer<typeof PresignOptionsSchema>;
+/**
+ * 签名 URL 输入选项，允许省略带默认值的字段。
+ * @example
+ * ```ts
+ * import type { PresignOptions } from '@h-ai/storage'
+ *
+ * const value: PresignOptions = { expiresIn: 60, responseContentType: 'text/plain' }
+ * void value
+ * ```
+ */
+type PresignOptions = z.input<typeof PresignOptionsSchema>;
 /**
  * 上传签名 URL 配置 Schema
  *
  * 继承 PresignOptionsSchema 并扩展上传专属参数，用于 `storage.presign.putUrl()`。
- *
  * @example
  * ```ts
- * const url = await storage.presign.putUrl('uploads/avatar.png', {
- *   contentType: 'image/png',
- *   expiresIn: 300,
- * })
+ * import { PresignUploadOptionsSchema } from '@h-ai/storage'
+ *
+ * const value = PresignUploadOptionsSchema.parse({ contentType: 'text/plain' })
+ * void value
  * ```
  */
 declare const PresignUploadOptionsSchema: z.ZodObject<{
@@ -198,9 +270,29 @@ declare const PresignUploadOptionsSchema: z.ZodObject<{
     responseContentDisposition: z.ZodOptional<z.ZodString>;
     contentType: z.ZodDefault<z.ZodString>;
 }, z.core.$strip>;
-/** 上传签名 URL 配置类型（parse 后） */
-type PresignUploadOptions = z.infer<typeof PresignUploadOptionsSchema>;
+/**
+ * 上传签名 URL 输入选项，省略 contentType 时使用 application/octet-stream。
+ * @example
+ * ```ts
+ * import type { PresignUploadOptions } from '@h-ai/storage'
+ *
+ * const value: PresignUploadOptions = { expiresIn: 60, contentType: 'text/plain' }
+ * void value
+ * ```
+ */
+type PresignUploadOptions = z.input<typeof PresignUploadOptionsSchema>;
 
+/**
+ * HaiStorageError 的数据约束与操作契约。
+ * @example
+ * ```ts
+ * import { HaiStorageError } from '@h-ai/storage'
+ * import { err } from '@h-ai/core'
+ *
+ * const result = err(HaiStorageError.NOT_FOUND, 'File missing')
+ * if (!result.success) void result.error.code
+ * ```
+ */
 declare const HaiStorageError: {
     readonly CONNECTION_FAILED: _h_ai_core.HaiErrorDef;
     readonly OPERATION_FAILED: _h_ai_core.HaiErrorDef;
@@ -219,11 +311,79 @@ declare const HaiStorageError: {
     readonly DOWNLOAD_FAILED: _h_ai_core.HaiErrorDef;
     readonly CHECKSUM_FAILED: _h_ai_core.HaiErrorDef;
     readonly INVALID_CHECKSUM: _h_ai_core.HaiErrorDef;
+    readonly UNSUPPORTED_OPERATION: _h_ai_core.HaiErrorDef;
+    readonly INVALID_LIST_OPTIONS: _h_ai_core.HaiErrorDef;
+};
+/**
+ * 批量删除中未确认完成的一项；key 始终使用调用方视角，不含 Provider prefix。
+ * @example
+ * ```ts
+ * import type { StorageDeleteFailure } from '@h-ai/storage'
+ *
+ * const value: StorageDeleteFailure = { key: 'private.txt', code: 'AccessDenied', retryable: false, outcome: 'failed' }
+ * void value
+ * ```
+ */
+interface StorageDeleteFailure {
+    /** 调用方提交的文件键。 */
+    key: string;
+    /** 渠道/框架错误标识，不包含渠道原始 Message。 */
+    code: string;
+    /** 是否属于可重试的瞬时故障；未知结果重试前仍需考虑并发上传/版本语义。 */
+    retryable: boolean;
+    /** failed 为已知失败，unknown 为已发送但结果未知，notAttempted 为尚未发送。 */
+    outcome: 'failed' | 'unknown' | 'notAttempted';
+}
+/**
+ * 批量删除进度；任一失败不能宣称全部删除完成。
+ * @example
+ * ```ts
+ * import type { StorageDeleteSummary } from '@h-ai/storage'
+ *
+ * const value: StorageDeleteSummary = { deletedKeys: ['a.txt'], failures: [] }
+ * void value
+ * ```
+ */
+interface StorageDeleteSummary {
+    /** 已确认删除或本来就不存在的唯一文件键。 */
+    deletedKeys: string[];
+    /** 失败、未知及尚未尝试的唯一文件键。 */
+    failures: StorageDeleteFailure[];
+}
+/**
+ * 批量删除结果；失败仍遵守 HaiResult，部分进度置于 error.ext.deleteMany。
+ * @example
+ * ```ts
+ * import { storage, type StorageDeleteResult } from '@h-ai/storage'
+ *
+ * async function remove() {
+ *   const result: StorageDeleteResult = await storage.file.deleteMany(['a.txt', 'b.txt'])
+ *   return result.success ? result.data : result.error.ext?.deleteMany
+ * }
+ * ```
+ */
+type StorageDeleteResult = {
+    success: true;
+    data: StorageDeleteSummary;
+} | {
+    success: false;
+    error: HaiError & {
+        ext?: Record<string, unknown> & {
+            deleteMany?: StorageDeleteSummary;
+        };
+    };
 };
 /**
  * 文件元数据接口
  *
  * 表示存储中单个文件的元信息，由 put/head/copy/list 等操作返回。
+ * @example
+ * ```ts
+ * import type { FileMetadata } from '@h-ai/storage'
+ *
+ * const value: FileMetadata = { key: 'a.txt', size: 5, contentType: 'text/plain', lastModified: new Date() }
+ * void value
+ * ```
  */
 interface FileMetadata {
     /** 文件键/路径（不含配置 prefix，对用户透明） */
@@ -243,6 +403,13 @@ interface FileMetadata {
  * 列表选项
  *
  * 用于控制 `storage.dir.list()` 的过滤、分页和目录模拟行为。
+ * @example
+ * ```ts
+ * import type { ListOptions } from '@h-ai/storage'
+ *
+ * const value: ListOptions = { prefix: 'reports/', delimiter: '/', maxKeys: 100 }
+ * void value
+ * ```
  */
 interface ListOptions {
     /** 前缀过滤（只返回以此前缀开头的文件） */
@@ -250,23 +417,30 @@ interface ListOptions {
     /**
      * 分页标记（从上次 ListResult.nextContinuationToken 获取）
      *
-     * 注意：本地存储目前不支持此字段，仅 S3 Provider 有效。
+     * Local 游标绑定根目录、prefix 和 delimiter，可跨实例使用；不得跨查询或 provider 混用。
      */
     continuationToken?: string;
-    /** 每页最大数量（默认 1000） */
+    /** 每页逻辑条目上限（1–1000，默认 1000）；files 和 commonPrefixes 合计计数。 */
     maxKeys?: number;
-    /** 分隔符（用于模拟目录结构，通常为 '/';传入后子目录作为 commonPrefixes 返回） */
+    /** 分隔符，通常为 '/'；从 prefix 之后首次出现的位置折叠 commonPrefixes，空字符串表示不折叠。 */
     delimiter?: string;
 }
 /**
  * 列表结果
  *
  * 包含当前页的文件列表、目录前缀、分页信息。
+ * @example
+ * ```ts
+ * import type { ListResult } from '@h-ai/storage'
+ *
+ * const value: ListResult = { files: [], commonPrefixes: ['reports/'], isTruncated: false }
+ * void value
+ * ```
  */
 interface ListResult {
     /** 当前页文件元数据列表 */
     files: FileMetadata[];
-    /** 公共前缀（使用 delimiter 时由子目录路径组成） */
+    /** 公共前缀：由实际匹配文件按 delimiter 折叠，不包含 Local 空物理目录。 */
     commonPrefixes: string[];
     /** 下一页标记；无后续页时为 undefined */
     nextContinuationToken?: string;
@@ -277,6 +451,13 @@ interface ListResult {
  * 上传选项
  *
  * 用于控制 `storage.file.put()` 的元数据与缓存行为。
+ * @example
+ * ```ts
+ * import type { UploadOptions } from '@h-ai/storage'
+ *
+ * const value: UploadOptions = { ifNoneMatch: '*', contentType: 'text/plain', signal: new AbortController().signal }
+ * void value
+ * ```
  */
 interface UploadOptions {
     /** 仅当 key 不存在时原子写入；S3 使用标准 If-None-Match，后端不支持时返回错误。 */
@@ -297,6 +478,13 @@ interface UploadOptions {
  *
  * 用于控制 `storage.file.get()` 的范围读取。
  * 两个字段均为字节偏移（含），与 HTTP Range 语义一致。
+ * @example
+ * ```ts
+ * import type { DownloadOptions } from '@h-ai/storage'
+ *
+ * const value: DownloadOptions = { rangeStart: 0, rangeEnd: 99 }
+ * void value
+ * ```
  */
 interface DownloadOptions {
     /** 取消读取。 */
@@ -311,6 +499,13 @@ interface DownloadOptions {
  *
  * 用于控制 `storage.file.copy()` 的目标文件元数据。
  * 提供任意字段时，S3 Provider 会使用 MetadataDirective='REPLACE' 覆盖源文件元数据。
+ * @example
+ * ```ts
+ * import type { CopyOptions } from '@h-ai/storage'
+ *
+ * const value: CopyOptions = { contentType: 'text/plain', metadata: { category: 'reports' } }
+ * void value
+ * ```
  */
 interface CopyOptions {
     /** 目标文件的内容类型（不指定时继承源文件） */
@@ -318,17 +513,56 @@ interface CopyOptions {
     /** 目标文件的自定义元数据（不指定时继承源文件） */
     metadata?: Record<string, string>;
 }
-/** 文件内容；异步字节流支持 Node Readable 等，不将整个文件载入内存。 */
+/**
+ * 文件内容；异步字节流支持 Node Readable 等，不将整个文件载入内存。
+ * @example
+ * ```ts
+ * import type { StorageData } from '@h-ai/storage'
+ *
+ * const value: StorageData = new TextEncoder().encode('hello')
+ * void value
+ * ```
+ */
 type StorageData = Buffer | Uint8Array | string | AsyncIterable<Uint8Array>;
-/** 常见 checksum 算法；MD5/SHA-1 仅用于兼容性完整性校验，不用于安全认证。 */
+/**
+ * 常见 checksum 算法；MD5/SHA-1 仅用于兼容性完整性校验，不用于安全认证。
+ * @example
+ * ```ts
+ * import type { ChecksumAlgorithm } from '@h-ai/storage'
+ *
+ * const value: ChecksumAlgorithm = 'sha256'
+ * void value
+ * ```
+ */
 type ChecksumAlgorithm = 'sha256' | 'sha384' | 'sha512' | 'sha1' | 'md5';
-/** checksum 计算选项；默认 SHA-256、小写 hex。 */
+/**
+ * checksum 计算选项；默认 SHA-256、小写 hex。
+ * @example
+ * ```ts
+ * import type { ChecksumOptions } from '@h-ai/storage'
+ *
+ * const value: ChecksumOptions = { algorithm: 'sha256', encoding: 'hex' }
+ * void value
+ * ```
+ */
 interface ChecksumOptions {
     algorithm?: ChecksumAlgorithm;
     encoding?: 'hex' | 'base64';
     signal?: AbortSignal;
 }
-/** Node 端无状态 checksum 工具，不依赖 storage.init；流输入仅消费一次。 */
+/**
+ * Node 端无状态 checksum 工具，不依赖 storage.init；流输入仅消费一次。
+ * @example
+ * ```ts
+ * import type { ChecksumOperations } from '@h-ai/storage'
+ *
+ * async function inspect(operations: ChecksumOperations) {
+ *   const result = await operations.generate('hello')
+ *   if (!result.success) return result.error.message
+ *   return result.data
+ * }
+ * ```
+ */
 interface ChecksumOperations {
     generate: (data: StorageData, options?: ChecksumOptions) => Promise<HaiResult<string>>;
     verify: (data: StorageData, expected: string, options?: ChecksumOptions) => Promise<HaiResult<boolean>>;
@@ -337,6 +571,16 @@ interface ChecksumOperations {
  * 文件操作接口
  *
  * 提供文件的读写操作。
+ * @example
+ * ```ts
+ * import type { FileOperations } from '@h-ai/storage'
+ *
+ * async function inspect(operations: FileOperations) {
+ *   const result = await operations.getStream('reports/a.txt')
+ *   if (!result.success) return result.error.message
+ *   for await (const chunk of result.data) void chunk.byteLength
+ * }
+ * ```
  */
 interface FileOperations {
     /**
@@ -366,6 +610,7 @@ interface FileOperations {
      * const result = await storage.file.get('uploads/a.txt')
      * if (result.success) {
      *   const buffer = result.data
+     *   void buffer
      * }
      * ```
      */
@@ -373,6 +618,19 @@ interface FileOperations {
     /**
      * 读取字节流，支持 Range 与取消；消费方负责及时迭代或关闭流。
      * @throws 迭代期间的 I/O/取消错误；初始请求失败通过 HaiResult 返回。
+     * @example
+     * ```ts
+     * import { storage } from '@h-ai/storage'
+     *
+     * const result = await storage.file.getStream('reports/a.txt')
+     * if (!result.success) throw new Error(result.error.message)
+     * try {
+     *   for await (const chunk of result.data) void chunk.byteLength
+     * } catch (error) {
+     *   // 初始请求成功后，迭代仍可能因 I/O/取消失败。
+     *   throw error
+     * }
+     * ```
      */
     getStream: (key: string, options?: DownloadOptions) => Promise<HaiResult<AsyncIterable<Uint8Array>>>;
     /**
@@ -410,7 +668,10 @@ interface FileOperations {
      * @returns 删除结果
      * @example
      * ```ts
-     * await storage.file.delete('uploads/a.txt')
+     * import { storage } from '@h-ai/storage'
+     *
+     * const result = await storage.file.delete('uploads/a.txt')
+     * if (!result.success) throw new Error(result.error.message)
      * ```
      */
     delete: (key: string) => Promise<HaiResult<void>>;
@@ -418,13 +679,15 @@ interface FileOperations {
      * 批量删除文件
      *
      * @param keys - 文件键/路径列表
-     * @returns 删除结果
+     * @returns 全部成功时返回进度；任一失败时 success=false，进度在 error.ext.deleteMany
      * @example
      * ```ts
-     * await storage.file.deleteMany(['a.txt', 'b.txt'])
+     * const result = await storage.file.deleteMany(['a.txt', 'b.txt'])
+     * const progress = result.success ? result.data : result.error.ext?.deleteMany
+     * void progress
      * ```
      */
-    deleteMany: (keys: string[]) => Promise<HaiResult<void>>;
+    deleteMany: (keys: string[]) => Promise<StorageDeleteResult>;
     /**
      * 复制文件
      *
@@ -434,7 +697,11 @@ interface FileOperations {
      * @returns 目标文件元数据
      * @example
      * ```ts
-     * await storage.file.copy('a.txt', 'b.txt')
+     * import { storage } from '@h-ai/storage'
+     *
+     * const result = await storage.file.copy('a.txt', 'b.txt')
+     * if (!result.success) throw new Error(result.error.message)
+     * void result.data.key
      * ```
      */
     copy: (sourceKey: string, destKey: string, options?: CopyOptions) => Promise<HaiResult<FileMetadata>>;
@@ -443,6 +710,16 @@ interface FileOperations {
  * 目录操作接口
  *
  * 提供目录（前缀）的列表操作。
+ * @example
+ * ```ts
+ * import type { DirOperations } from '@h-ai/storage'
+ *
+ * async function inspect(operations: DirOperations) {
+ *   const page = await operations.list({ prefix: 'reports/', maxKeys: 100 })
+ *   if (!page.success) return page.error.message
+ *   return page.data.files
+ * }
+ * ```
  */
 interface DirOperations {
     /**
@@ -466,7 +743,10 @@ interface DirOperations {
      * @returns 删除结果
      * @example
      * ```ts
-     * await storage.dir.delete('uploads/tmp/')
+     * import { storage } from '@h-ai/storage'
+     *
+     * const result = await storage.dir.delete('uploads/tmp/')
+     * if (!result.success) throw new Error(result.error.message)
      * ```
      */
     delete: (prefix: string) => Promise<HaiResult<void>>;
@@ -474,7 +754,18 @@ interface DirOperations {
 /**
  * 签名 URL 操作接口
  *
- * 提供生成临时授权 URL 的功能，支持前端直接上传下载。
+ * S3 provider 提供临时授权 URL，支持前端直接上传下载。
+ * local 的 getUrl/putUrl 返回 UNSUPPORTED_OPERATION，publicUrl 返回 null。
+ * @example
+ * ```ts
+ * import type { PresignOperations } from '@h-ai/storage'
+ *
+ * async function inspect(operations: PresignOperations) {
+ *   const signed = await operations.putUrl('reports/a.txt', { contentType: 'text/plain', expiresIn: 300 })
+ *   if (!signed.success) return signed.error.message
+ *   return signed.data
+ * }
+ * ```
  */
 interface PresignOperations {
     /**
@@ -482,10 +773,13 @@ interface PresignOperations {
      *
      * @param key - 文件键/路径
      * @param options - 签名选项
-     * @returns 签名 URL
+     * @returns 成功时为可访问的 S3 签名 URL；local 返回 UNSUPPORTED_OPERATION。
      * @example
      * ```ts
      * const result = await storage.presign.getUrl('a.txt', { expiresIn: 60 })
+     * if (!result.success) throw new Error(result.error.message)
+     * const downloadUrl = result.data
+     * void downloadUrl
      * ```
      */
     getUrl: (key: string, options?: PresignOptions) => Promise<HaiResult<string>>;
@@ -494,10 +788,13 @@ interface PresignOperations {
      *
      * @param key - 文件键/路径
      * @param options - 上传签名选项
-     * @returns 签名 URL
+     * @returns 成功时为可访问的 S3 签名 URL；local 返回 UNSUPPORTED_OPERATION。
      * @example
      * ```ts
      * const result = await storage.presign.putUrl('a.txt', { contentType: 'text/plain' })
+     * if (!result.success) throw new Error(result.error.message)
+     * const uploadUrl = result.data
+     * void uploadUrl
      * ```
      */
     putUrl: (key: string, options?: PresignUploadOptions) => Promise<HaiResult<string>>;
@@ -505,10 +802,11 @@ interface PresignOperations {
      * 获取公开访问 URL（如果配置了 publicUrl）
      *
      * @param key - 文件键/路径
-     * @returns 公开 URL，如果未配置 publicUrl 则返回 null
+     * @returns 公开 URL；S3 未配置 publicUrl 或 local provider 均返回 null。
      * @example
      * ```ts
      * const url = storage.presign.publicUrl('a.txt')
+     * void url
      * ```
      */
     publicUrl: (key: string) => string | null;
@@ -524,6 +822,23 @@ interface PresignOperations {
  * - `storage.presign` — 签名 URL 操作
  * - `storage.config` — 当前脱敏配置快照（未初始化时为 null）
  * - `storage.isInitialized` — 初始化状态
+ * @example
+ * ```ts
+ * import { storage } from '@h-ai/storage'
+ *
+ * const initialized = await storage.init({ type: 'local', root: './data/uploads' })
+ * if (!initialized.success) throw new Error(initialized.error.message)
+ * try {
+ *   const uploaded = await storage.file.put('reports/a.txt', 'hello', { ifNoneMatch: '*' })
+ *   if (!uploaded.success) throw new Error(uploaded.error.message)
+ *   const downloaded = await storage.file.get('reports/a.txt')
+ *   if (!downloaded.success) throw new Error(downloaded.error.message)
+ *   void downloaded.data
+ * } finally {
+ *   const closed = await storage.close()
+ *   if (!closed.success) throw new Error(closed.error.message)
+ * }
+ * ```
  */
 interface StorageFunctions {
     /** 无状态 checksum 生成与校验，Node 专用，无需初始化。 */
@@ -534,13 +849,30 @@ interface StorageFunctions {
      * 已有连接时会先 close 再重新初始化。
      *
      * @param config - 存储配置（支持省略带默认值的字段）
-     * @returns 成功 ok(undefined)；失败返回 err（含 StorageError）
+     * @returns 成功 ok(undefined)；失败返回 err（含 HaiStorageError 定义的错误信息）
+     * @example
+     * ```ts
+     * import { storage } from '@h-ai/storage'
+     *
+     * const initialized = await storage.init({ type: 'local', root: './data/uploads' })
+     * if (!initialized.success) throw new Error(initialized.error.message)
+     * const closed = await storage.close()
+     * if (!closed.success) throw new Error(closed.error.message)
+     * ```
      */
     init: (config: StorageConfigInput) => Promise<HaiResult<void>>;
     /**
      * 关闭存储连接并释放资源
      *
-     * 重复调用不会报错。
+     * 等待初始化并合并并发关闭；失败时操作不可用，资源保留供 close/init 重试。
+     * @returns 所有资源释放成功才返回成功；未初始化时同样成功。
+     * @example
+     * ```ts
+     * import { storage } from '@h-ai/storage'
+     *
+     * const closed = await storage.close()
+     * if (!closed.success) throw new Error(closed.error.message)
+     * ```
      */
     close: () => Promise<HaiResult<void>>;
     /** 当前脱敏后的存储配置快照；未初始化或已关闭时为 null */
@@ -554,31 +886,5 @@ interface StorageFunctions {
     /** 签名 URL 操作接口（getUrl / putUrl / publicUrl） */
     readonly presign: PresignOperations;
 }
-/**
- * 存储 Provider 接口
- *
- * 由各具体存储实现（S3、Local）实现此接口。
- */
-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 ChecksumAlgorithm, type ChecksumOperations, type ChecksumOptions, 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 StorageData, type StorageFunctions, type StorageOperationLogConfig, StorageOperationLogConfigSchema, type StorageProvider, type StorageType, StorageTypeSchema, type UploadOptions };
+export { type ChecksumAlgorithm, type ChecksumOperations, type ChecksumOptions, 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 StorageData, type StorageDeleteFailure, type StorageDeleteResult, type StorageDeleteSummary, type StorageFunctions, type StorageOperationLogConfig, StorageOperationLogConfigSchema, type StorageType, StorageTypeSchema, type UploadOptions };