@cloudbase/js-sdk 3.4.7 → 3.4.9-alpha.0

package/index.d.ts

@@ -453,6 +453,8 @@ declare namespace cloudbase.app {
      * @param params.onUploadProgress 【可选】上传进度回调函数
      *
      * @return Promise-上传结果
+     *
+     * @deprecated 传统云存储 API 已不推荐使用，请改用 `app.storage.from().upload()`。
      */
     uploadFile(
       params: cloudbase.storage.ICloudbaseUploadFileParams,
@@ -477,6 +479,8 @@ declare namespace cloudbase.app {
      * @param params.fileID 要下载的文件的 `id`，在控制台云存储中查看
      *
      * @return Promise-下载结果
+     *
+     * @deprecated 传统云存储 API 已不推荐使用，请改用 `app.storage.from().download()`。
      */
     downloadFile(
       params: cloudbase.storage.ICloudbaseDownloadFileParams,
@@ -507,6 +511,8 @@ declare namespace cloudbase.app {
      * @param params.fileList 要复制的文件信息组成的数组
      *
      * @return Promise-复制结果
+     *
+     * @deprecated 传统云存储 API 已不推荐使用，请改用 `app.storage.from().copy()`。
      */
     copyFile(
       params: cloudbase.storage.ICloudbaseCopyFileParams,
@@ -539,6 +545,8 @@ declare namespace cloudbase.app {
      * @param params.fileList[].maxAge 下载链接的有效期，单位`ms`
      *
      * @return Promise-文件下载链接
+     *
+     * @deprecated 传统云存储 API 已不推荐使用，请改用 `app.storage.from().createSignedUrl()`。
      */
     getTempFileURL(
       params: cloudbase.storage.ICloudbaseGetTempFileURLParams,
@@ -566,12 +574,19 @@ declare namespace cloudbase.app {
      * @param params.fileList 要删除的文件ID数组
      *
      * @return Promise-删除结果
+     *
+     * @deprecated 传统云存储 API 已不推荐使用，请改用 `app.storage.from().remove()`。
      */
     deleteFile(
       params: cloudbase.storage.ICloudbaseDeleteFileParams,
       callback?: Function,
     ): Promise<cloudbase.storage.ICloudbaseDeleteFileResult>
 
+    /**
+     * 云存储-获取文件信息
+     *
+     * @deprecated 传统云存储 API 已不推荐使用，请改用 `app.storage.from().info()`。
+     */
     getFileInfo(
       params: cloudbase.storage.ICloudbaseGetTempFileURLParams,
     ): Promise<cloudbase.storage.ICloudbaseGetFileInfoResult>
@@ -581,6 +596,8 @@ declare namespace cloudbase.app {
      *
      * @param params
      * @param callback
+     *
+     * @deprecated 传统云存储 API 已不推荐使用，请改用 `app.storage.from().createSignedUploadUrl()`。
      */
     getUploadMetadata(params: cloudbase.storage.ICloudbaseGetUploadMetadataParams, callback?: Function): Promise<any>
 
@@ -593,7 +610,7 @@ declare namespace cloudbase.app {
      * const { data, error } = await bucket.upload('path/to/file.jpg', file)
      * ```
      */
-    storage: cloudbase.storage.SupabaseFileAPILikeStorage
+    storage: cloudbase.storage.StorageClient
     /**
      * 获取数据库实例
      *
@@ -1917,32 +1934,68 @@ declare namespace cloudbase.storage {
 
   // ---- Supabase-like Storage Types ----
 
+  /** Node.js 风格可读流的最小兼容类型，避免依赖 `@types/node`。 */
+  interface NodeReadableStreamLike {
+    /** 将当前流管道输出到目标流。 */
+    pipe(destination: any, options?: any): any
+  }
+
+  /**
+   * Node.js `Buffer` 的兼容类型。
+   *
+   * 在安装了 `@types/node` 的项目中解析为 `Buffer`，未安装时退化为 `never`，
+   * 从而既能让 Node 端继续显式传入 `Buffer`，又不会让纯浏览器项目因缺少
+   * `@types/node` 而报“找不到名称 Buffer”，避免对 `@types/node` 的硬依赖。
+   */
+  type MaybeNodeBuffer = typeof globalThis extends { Buffer: new (...args: any[]) => infer B } ? B : never
+
+  /**
+   * 可上传的文件内容类型。
+   *
+   * @remarks
+   * - Node.js `Buffer`：通过 `MaybeNodeBuffer` 兼容（装有 `@types/node` 时可直接传入）；
+   *   即便未装 `@types/node`，`Buffer` 仍可作为 `ArrayBufferView` / `Uint8Array` 传入。
+   * - Node.js 可读流（如 `NodeJS.ReadableStream` / `fs.ReadStream`）：可作为 `NodeReadableStreamLike` 传入。
+   */
   type FileBody =
     | ArrayBuffer
     | ArrayBufferView
     | Blob
-    | Buffer
     | File
     | FormData
-    | NodeJS.ReadableStream
+    | MaybeNodeBuffer
+    | NodeReadableStreamLike
     | ReadableStream<Uint8Array>
     | URLSearchParams
     | string
 
+  /** 上传 / 覆盖对象选项。 */
   interface FileOptions {
+    /** 缓存时间，单位为秒；会转换为 `Cache-Control: max-age=<seconds>`。 */
     cacheControl?: string
+    /** 文件 MIME 类型；当 `fileBody` 不是 `Blob` / `File` / `FormData` 时建议显式指定。 */
     contentType?: string
+    /** 是否允许覆盖同名对象。 */
     upsert?: boolean
+    /** 透传给底层 `fetch` 的 duplex 配置，用于流式请求场景。 */
     duplex?: string
+    /** 用户自定义元数据。 */
     metadata?: Record<string, any>
+    /** 额外请求头。 */
     headers?: Record<string, string>
   }
 
+  /** 图片转换选项。 */
   interface TransformOptions {
+    /** 图片宽度，单位为像素。 */
     width?: number
+    /** 图片高度，单位为像素。 */
     height?: number
+    /** 缩放模式：`cover` 保持比例裁剪填满；`contain` 保持比例完整适配；`fill` 拉伸填满。 */
     resize?: 'cover' | 'contain' | 'fill'
+    /** 图片质量，通常取值 20 到 100，数值越大质量越高。 */
     quality?: number
+    /** 输出格式；`origin` 表示保持原图格式。 */
     format?: 'origin'
   }
 
@@ -2008,25 +2061,12 @@ declare namespace cloudbase.storage {
    * const { data } = await bucket.download('path/to/file.jpg')
    * ```
    */
-  interface SupabaseFileAPILikeStorage {
+  interface ClassicStorageFileApi {
     /**
      * 启用错误抛出模式，而非返回 `{ data: null, error }` 格式
      */
     throwOnError(): this
 
-    /**
-     * 选择存储桶
-     *
-     * @param bucket 存储桶名称
-     * @returns 当前实例（链式调用）
-     *
-     * @example
-     * ```typescript
-     * const bucket = app.storage.from('my-bucket')
-     * ```
-     */
-    from(bucket?: string): this
-
     /**
      * 上传文件
      *
@@ -2216,42 +2256,611 @@ declare namespace cloudbase.storage {
       | { data: FileObject[]; error: null }
       | { data: null; error: StorageError }
     >
+  }
 
-    // ---- 继承自 CloudbaseStorage 的方法 ----
+  /**
+   * Bucket 管理 API，挂载在 `app.storage` 上。
+   *
+   * @remarks 权限由 `storage.buckets` 的 RLS Policy 决定。暂不提供
+   * `emptyBucket()`、`headBucket()`、Bucket CORS、Bucket ACL 等 COS/S3 风格 Bucket 管理 API。
+   */
+  interface StorageBucketApi {
+    /**
+     * 启用错误抛出模式。开启后请求失败会抛异常；请求成功仍返回 `{ data, error: null }`。
+     * 该设置会传递给 `from()` 返回的客户端。
+     */
+    throwOnError(): this
 
-    uploadFile(
-      params: ICloudbaseUploadFileParams,
-      callback?: Function,
-    ): Promise<ICloudbaseUploadFileResult>
+    /**
+     * 获取 Bucket 列表，支持偏移分页、排序和搜索。
+     *
+     * @param options 查询参数：`limit`、`offset`、`sortColumn`、`sortOrder`、`search`。
+     */
+    listBuckets(options?: ListBucketOptions): Promise<
+      | { data: Bucket[]; error: null }
+      | { data: null; error: StorageError }
+    >
 
-    deleteFile(
-      params: ICloudbaseDeleteFileParams,
-      callback?: Function,
-    ): Promise<ICloudbaseDeleteFileResult>
+    /**
+     * 获取指定 Bucket 详情。
+     *
+     * @param bucketId Bucket ID。
+     */
+    getBucket(bucketId: string): Promise<
+      | { data: Bucket; error: null }
+      | { data: null; error: StorageError }
+    >
 
-    getTempFileURL(
-      params: ICloudbaseGetTempFileURLParams,
-      callback?: Function,
-    ): Promise<ICloudbaseGetTempFileURLResult>
+    /**
+     * 创建 Bucket。
+     *
+     * @param bucketId Bucket ID，同时作为后端 `id` 与 `name` 传入。
+     * @param options 创建参数：`public`、`fileSizeLimit`、`allowedMimeTypes`、`type`。
+     * @remarks `public` 默认 `false`。
+     */
+    createBucket(bucketId: string, options?: CreateBucketOptions): Promise<
+      | { data: { name: string }; error: null }
+      | { data: null; error: StorageError }
+    >
 
-    downloadFile(
-      params: ICloudbaseDownloadFileParams,
-      callback?: Function,
-    ): Promise<ICloudbaseDownloadFileResult>
+    /**
+     * 更新 Bucket 配置。
+     *
+     * @param bucketId Bucket ID。
+     * @param options 更新参数：`public`、`fileSizeLimit`、`allowedMimeTypes`。不支持更新 `type`。
+     */
+    updateBucket(bucketId: string, options: UpdateBucketOptions): Promise<
+      | { data: { message: string }; error: null }
+      | { data: null; error: StorageError }
+    >
 
-    getUploadMetadata(
-      params: ICloudbaseGetUploadMetadataParams,
-      callback?: Function,
-    ): Promise<ICloudbaseFileMetaDataRes>
+    /**
+     * 删除空 Bucket。
+     *
+     * @param bucketId Bucket ID。
+     * @remarks Bucket 非空时后端会返回错误。
+     */
+    deleteBucket(bucketId: string): Promise<
+      | { data: { message: string }; error: null }
+      | { data: null; error: StorageError }
+    >
+  }
 
-    copyFile(
-      params: ICloudbaseCopyFileParams,
-      callback?: Function,
-    ): Promise<ICloudbaseCopyFileResult>
+  /**
+   * `app.storage` 命名空间（分流器）。继承 `StorageBucketApi` 的 Bucket 管理能力，并提供 `from()` 分流。
+   *
+   * `from()` 分流到两个**对等且独立**的客户端——`ClassicStorageFileApi`（传统环境）
+   * 与 `StorageFileApi`（针对全新的 Neo 环境）。
+   *
+   * - `from()`：返回 `ClassicStorageFileApi`；
+   * - `from(bucketId)`：返回 `StorageFileApi`。
+   */
+  interface StorageClient extends StorageBucketApi {
+    /**
+     * 进入对象操作客户端。
+     *
+     * - `from()`（不传 bucketId）：返回传统环境对象操作客户端；
+     * - `from(bucketId)`：返回 Neo 环境对象操作（`bucketId + objectName` 语义）客户端。
+     *
+     * @remarks 传入 `bucketId` 时返回的客户端仅 Neo 环境可用。
+     *
+     * @example
+     * ```typescript
+     * // 传统环境
+     * const file = app.storage.from()
+     * // Neo 环境
+     * const avatars = app.storage.from('avatars')
+     * ```
+     */
+    from(): ClassicStorageFileApi
+    from<B extends string>(bucketId: B): StorageFileApi
+  }
 
-    getFileInfo(
-      params: ICloudbaseGetTempFileURLParams,
-    ): Promise<ICloudbaseGetFileInfoResult>
+  // ==================== Storage 类型 ====================
+  // 以下类型通过 app.storage.from(bucketId) 与 Bucket 管理 API 暴露。
+
+  type BucketType = 'STANDARD'
+
+  /** Bucket 资源（对应 storage.buckets 表记录）。 */
+  interface Bucket {
+    /** Bucket ID。 */
+    id: string
+    /** Bucket 名称。 */
+    name: string
+    /** 创建者用户 ID；可能为空。 */
+    owner_id?: string | null
+    /** 是否为公开 Bucket。 */
+    public: boolean
+    /** Bucket 类型。 */
+    type?: BucketType
+    /** 文件大小限制，单位为字节；`null` 表示不限制。 */
+    file_size_limit?: number | null
+    /** 允许上传的 MIME 类型列表；`null` 表示不限制。 */
+    allowed_mime_types?: string[] | null
+    /** 创建时间，ISO 8601 日期时间字符串。 */
+    created_at: string
+    /** 更新时间，ISO 8601 日期时间字符串。 */
+    updated_at: string
+  }
+
+  interface ListBucketOptions {
+    /** 返回数量限制。 */
+    limit?: number
+    /** 分页偏移量。 */
+    offset?: number
+    /** 排序字段。 */
+    sortColumn?: 'id' | 'name' | 'created_at' | 'updated_at'
+    /** 排序方向。 */
+    sortOrder?: 'asc' | 'desc'
+    /** 搜索关键词。 */
+    search?: string
+  }
+
+  interface CreateBucketOptions {
+    /** 是否公开，默认 `false`。 */
+    public?: boolean
+    /** 文件大小限制；数字按字节处理，字符串支持如 `100MB`，`null` 表示不限制。 */
+    fileSizeLimit?: number | string | null
+    /** 允许上传的 MIME 类型列表，`null` 表示不限制。 */
+    allowedMimeTypes?: string[] | null
+    /** Bucket 类型，仅创建时可传。 */
+    type?: BucketType
+  }
+
+  interface UpdateBucketOptions {
+    /** 是否公开。 */
+    public?: boolean
+    /** 文件大小限制；数字按字节处理，字符串支持如 `100MB`，`null` 表示不限制。 */
+    fileSizeLimit?: number | string | null
+    /** 允许上传的 MIME 类型列表，`null` 表示不限制。 */
+    allowedMimeTypes?: string[] | null
+  }
+
+  /** 上传选项。 */
+  type UploadOptions = FileOptions
+
+  interface UploadResult {
+    /** 对象 UUID（后端 `Id`）。 */
+    id: string
+    /** Bucket 内相对路径。 */
+    path: string
+    /** 对象完整路径 `bucketId/objectName`（后端 `Key`）。 */
+    fullPath: string
+  }
+
+  interface DownloadOptions {
+    /** 触发浏览器下载，传字符串作为下载文件名。 */
+    download?: string | boolean
+    /** 缓存失效 nonce，追加到请求 URL 以绕过 CDN 缓存。 */
+    cacheNonce?: string
+  }
+
+  interface ListOptions {
+    /** 返回数量限制。 */
+    limit?: number
+    /** 翻页游标，由上一页响应的 `nextCursor` 提供。 */
+    cursor?: string
+    /** 是否使用 `/` 作为分隔符区分文件夹。 */
+    withDelimiter?: boolean
+    /** 排序配置。 */
+    sortBy?: {
+      /** 排序字段。 */
+      column?: 'name' | 'created_at' | 'updated_at'
+      /** 排序方向。 */
+      order?: 'asc' | 'desc'
+    }
+  }
+
+  interface ListObjectsEntry {
+    /** 对象完整 key；文件夹条目可能为空。 */
+    key?: string | null
+    /** 对象名或文件夹名。 */
+    name: string
+    /** 对象 UUID；文件夹条目可能为空。 */
+    id?: string | null
+    /** 更新时间，ISO 8601 日期时间字符串。 */
+    updated_at?: string | null
+    /** 创建时间，ISO 8601 日期时间字符串。 */
+    created_at?: string | null
+    /** 最后访问时间，ISO 8601 日期时间字符串。 */
+    last_accessed_at?: string | null
+    /** 对象元数据。 */
+    metadata?: Record<string, any> | null
+  }
+
+  interface ListObjectsResponse {
+    /** 当前前缀下的文件夹条目。 */
+    folders: ListObjectsEntry[]
+    /** 当前前缀下的对象条目。 */
+    objects: ListObjectsEntry[]
+    /** 是否还有下一页。 */
+    hasNext: boolean
+    /** 下一页游标。 */
+    nextCursor?: string
+    /** 下一页起始 key。 */
+    nextCursorKey?: string
+  }
+
+  interface ObjectInfo {
+    /** 对象 UUID。 */
+    id: string
+    /** Bucket 内相对路径。 */
+    name: string
+    /** 对象版本标识；可能为空。 */
+    version?: string | null
+    /** 所属 Bucket ID。 */
+    bucketId: string
+    /** 文件大小，单位为字节；可能为空。 */
+    size?: number | null
+    /** 文件 MIME 类型；可能为空。 */
+    contentType?: string | null
+    /** 缓存控制信息；可能为空。 */
+    cacheControl?: string | null
+    /** 对象 ETag；可能为空。 */
+    etag?: string | null
+    /** 用户自定义元数据。 */
+    metadata?: Record<string, any>
+    /** 最后修改时间，ISO 8601 日期时间字符串。 */
+    lastModified?: string | null
+    /** 创建时间，ISO 8601 日期时间字符串。 */
+    createdAt?: string | null
+  }
+
+  interface FullObject {
+    /** Bucket 内相对路径。 */
+    name: string
+    /** 所属 Bucket ID。 */
+    bucket_id: string
+    /** 创建者用户 ID；可能为空。 */
+    owner_id?: string | null
+    /** 对象版本标识；可能为空。 */
+    version?: string | null
+    /** 对象 UUID；可能为空。 */
+    id?: string | null
+    /** 更新时间，ISO 8601 日期时间字符串。 */
+    updated_at?: string | null
+    /** 创建时间，ISO 8601 日期时间字符串。 */
+    created_at?: string | null
+    /** 最后访问时间，ISO 8601 日期时间字符串。 */
+    last_accessed_at?: string | null
+    /** 系统或对象元数据。 */
+    metadata?: Record<string, any>
+    /** 用户自定义元数据。 */
+    user_metadata?: Record<string, any>
+  }
+
+  interface DestinationOptions {
+    /** 目标 Bucket ID，默认与源相同。 */
+    destinationBucket?: string
+    /** 允许覆盖目标位置已有对象。 */
+    upsert?: boolean
+    /** 是否复制源对象元数据，默认 true。 */
+    copyMetadata?: boolean
+    /** `copyMetadata=false` 时合并到目标对象的用户元数据。 */
+    metadata?: Record<string, any>
+  }
+
+  interface SignedUrlOptions {
+    /** 触发浏览器下载，传字符串作为下载文件名。 */
+    download?: string | boolean
+    /** 缓存失效 nonce，追加到请求 URL 以绕过 CDN 缓存。 */
+    cacheNonce?: string
+  }
+
+  /** 公开 URL 选项。 */
+  interface PublicUrlOptions {
+    /** 触发浏览器下载，传字符串作为下载文件名。 */
+    download?: string | boolean
+    /** 缓存失效 nonce，追加到请求 URL 以绕过 CDN 缓存。 */
+    cacheNonce?: string
+  }
+
+  /**
+   * 请求级 fetch 控制参数（对齐 Supabase `FetchParameters`）。
+   *
+   * 纯客户端能力：`signal` 用于取消请求；`cache` 透传给底层 fetch 的缓存策略
+   * （主要在浏览器 fetch 路径生效，XHR / 部分运行时会忽略）。
+   */
+  interface FetchParameters {
+    /** 请求取消信号。 */
+    signal?: AbortSignal
+    /** 透传给底层 `fetch` 的缓存策略。 */
+    cache?: 'default' | 'no-store' | 'reload' | 'no-cache' | 'force-cache' | 'only-if-cached'
+  }
+
+  /**
+   * 流式下载构建器（thenable）。`await` 后 resolve 为 `Result<ReadableStream>`。
+   * 由 `DownloadBuilder.asStream()` 创建。
+   */
+  interface StreamDownloadBuilder extends PromiseLike<
+    | { data: ReadableStream<Uint8Array>; error: null }
+    | { data: null; error: StorageError }
+  > {}
+
+  /**
+   * 下载构建器（thenable）。默认 `await` 得 `Result<Blob>`；`.asStream()` 切换为流式终态。
+   * 惰性执行：请求在 `await` / `.then()` 时才真正发出。
+   */
+  interface DownloadBuilder extends PromiseLike<
+    | { data: Blob; error: null }
+    | { data: null; error: StorageError }
+  > {
+    /** 切换为流式下载终态，返回 `StreamDownloadBuilder`。 */
+    asStream(): StreamDownloadBuilder
+  }
+
+  /**
+   * 单 Bucket 对象操作客户端。通过 `app.storage.from(bucketId)` 获取。
+   *
+   * @remarks 所有 `objectName` 均为 Bucket 内相对路径。
+   */
+  interface StorageFileApi {
+    /** 当前客户端绑定的 Bucket ID。 */
+    readonly bucketId: string
+
+    /**
+     * 启用错误抛出模式。开启后请求失败会抛异常；请求成功仍返回 `{ data, error: null }`。
+     */
+    throwOnError(): this
+
+    /**
+     * 设置自定义请求头（链式）。
+     *
+     * @remarks 设置后对当前实例后续所有请求生效；每个 `from(bucketId)` 返回独立实例，互不影响。
+     * 单次请求内部的功能性头（如上传的 `Content-Type` / `x-upsert`）优先级更高，会覆盖此处同名头。
+     * name 为空或 name/value 含 CR/LF 时抛 `StorageError`。
+     */
+    setHeader(name: string, value: string): this
+
+    /**
+     * 直接上传对象，默认不覆盖同名对象。
+     *
+     * 需要当前用户已登录，权限由 `storage.objects` 的 RLS `INSERT` / `UPDATE` 策略判定。
+     *
+     * 上传行为：
+     * - `options.upsert` 默认 `false`：目标路径已有对象时，上传失败。
+     * - `options.upsert` 设为 `true`：目标路径已有对象时，覆盖写入。
+     * - 成功时返回 `{ id, path, fullPath }`。
+     *
+     * @param path Bucket 内相对路径。
+     * @param fileBody 文件内容。
+     * @param fileOptions 上传选项，如 `contentType`、`cacheControl`、`upsert`、`metadata`。
+     * @see createSignedUploadUrl uploadToSignedUrl
+     */
+    upload(path: string, fileBody: FileBody, fileOptions?: UploadOptions): Promise<
+      | { data: UploadResult; error: null }
+      | { data: null; error: StorageError }
+    >
+
+    /**
+     * 覆盖更新对象。
+     *
+     * 与 `upload` 共享同一底层，区别：
+     * - 使用 `PUT` 方法（语义为覆盖）。
+     * - 目标路径不存在时也会创建（upsert 行为）。
+     *
+     * @param path Bucket 内相对路径。
+     * @param fileBody 文件内容。
+     * @param fileOptions 上传选项，如 `contentType`、`cacheControl`、`metadata`。
+     */
+    update(path: string, fileBody: FileBody, fileOptions?: UploadOptions): Promise<
+      | { data: UploadResult; error: null }
+      | { data: null; error: StorageError }
+    >
+
+    /**
+     * 下载对象。返回**下载构建器**（thenable），默认 `await` 得到 `Blob`。
+     *
+     * 需要登录态，权限由 `storage.objects` 的 RLS `SELECT` 策略判定。
+     *
+     * 两种终态：
+     * - 默认：`await bucket.download(path)` → `{ data: Blob, error }`。
+     * - 流式：`await bucket.download(path).asStream()` → `{ data: ReadableStream, error }`，
+     *   适合 Node 大文件等不希望整体读入内存的场景。
+     *
+     * 两者统一走原生 `fetch` 的 `Response`：流式终态返回 `Response.body`，Blob 终态调 `Response.blob()`。
+     *
+     * 下载行为：
+     * - 惰性执行：请求在 `await` / `.then()` 时才真正发出。
+     * - 返回的 `Blob` 不会自动触发浏览器下载或渲染，需配合 `URL.createObjectURL` 手动处理。
+     * - 支持 `parameters.signal`（AbortSignal）取消进行中的下载。
+     *
+     * @param path Bucket 内相对路径。
+     * @param options 下载选项，支持 `download`（触发浏览器下载）、`cacheNonce`（绕过 CDN 缓存）。
+     * @param parameters 请求控制参数，支持 `signal` / `cache`。
+     * @returns `DownloadBuilder`：可 `await` 得 `Blob`，或 `.asStream()` 后得 `ReadableStream`。
+     */
+    download(path: string, options?: DownloadOptions, parameters?: FetchParameters): DownloadBuilder
+
+    /**
+     * 获取对象列表（游标分页）。
+     *
+     * 采用**游标分页**，与 Supabase 的 `listV2` 对应。
+     *
+     * - 首次查询不传 `cursor`，后续用上一页的 `nextCursor` 继续翻页。
+     * - 返回 `{ folders, objects, hasNext, nextCursor }`（区别于 Supabase `list` 的 offset 分页 `FileObject[]`）。
+     * - `path` 不传时列出 Bucket 根目录。
+     * - `options.withDelimiter` 为 `true` 时以 `/` 分隔文件夹和文件。
+     *
+     * @param path 路径前缀，不传表示 Bucket 根目录。
+     * @param options 列表选项，支持 `limit`、`cursor`、`withDelimiter`、`sortBy`。
+     * @param parameters 请求控制参数，支持 `signal` / `cache`。
+     * @remarks 本方法对应 Supabase 的 `listV2`（游标分页），而非 `list`（offset 分页）。
+     */
+    list(path?: string, options?: ListOptions, parameters?: FetchParameters): Promise<
+      | { data: ListObjectsResponse; error: null }
+      | { data: null; error: StorageError }
+    >
+
+    /**
+     * 删除一个或多个对象。
+     *
+     * 权限由 `storage.objects` 的 RLS `DELETE` 策略判定。
+     *
+     * - 后端单次最多删除 100 个对象，超出时 SDK 自动分批发送。
+     * - 返回所有被成功删除的对象信息（`FullObject[]`）。
+     *
+     * @param paths Bucket 内相对路径数组。
+     */
+    remove(paths: string[]): Promise<
+      | { data: FullObject[]; error: null }
+      | { data: null; error: StorageError }
+    >
+
+    /**
+     * 复制对象，支持跨 Bucket。
+     *
+     * 权限由 `storage.objects` 的 RLS 策略判定：读取源需要 `SELECT`，写入目标需要 `INSERT`。
+     *
+     * - `options.destinationBucket` 不传时在同一 Bucket 内复制。
+     * - `options.upsert` 为 `true` 时，目标路径已有对象则覆盖。
+     * - `options.copyMetadata` 设为 `false` 并传 `options.metadata` 时替换原 metadata。
+     * - 返回目标对象的完整路径。
+     *
+     * @param fromPath 源对象 Bucket 内相对路径。
+     * @param toPath 目标对象相对路径。
+     * @param options 目标 Bucket、覆盖、元数据复制等选项。
+     */
+    copy(fromPath: string, toPath: string, options?: DestinationOptions): Promise<
+      | { data: { path: string }; error: null }
+      | { data: null; error: StorageError }
+    >
+
+    /**
+     * 移动对象，支持跨 Bucket；源对象会被删除。
+     *
+     * 语义为"复制到目标 → 删除源"，非原地重命名。
+     * 权限由 `storage.objects` 的 RLS 策略判定：读取源需要 `SELECT`，写入目标需要 `INSERT`，删除源需要 `DELETE`。
+     *
+     * - `options.destinationBucket` 不传时在同一 Bucket 内移动。
+     *
+     * @param fromPath 源对象 Bucket 内相对路径。
+     * @param toPath 目标对象相对路径。
+     * @param options 目标 Bucket 等选项。
+     */
+    move(fromPath: string, toPath: string, options?: DestinationOptions): Promise<
+      | { data: { message: string }; error: null }
+      | { data: null; error: StorageError }
+    >
+
+    /**
+     * 获取对象元信息。
+     *
+     * 返回对象在 `storage.objects` 表中的记录信息，包括 `bucketId`、`version`、`etag`、
+     * `contentType`、`cacheControl`、`metadata`、`lastModified`、`createdAt` 等。
+     *
+     * @param path Bucket 内相对路径。
+     */
+    info(path: string): Promise<
+      | { data: ObjectInfo; error: null }
+      | { data: null; error: StorageError }
+    >
+
+    /**
+     * 判断对象是否存在。
+     *
+     * 底层调用 `info` 端点：
+     * - HTTP 200 → 存在（返回 `true`）。
+     * - HTTP 400 或 404 → 不存在（返回 `false`）。
+     * - 其他异常 → 返回 `{ data: null, error }`。
+     *
+     * @param path Bucket 内相对路径。
+     */
+    exists(path: string): Promise<
+      | { data: boolean; error: null }
+      | { data: null; error: StorageError }
+    >
+
+    /**
+     * 生成单个对象的签名下载 URL。
+     *
+     * 需要登录态，权限由 `storage.objects` 的 RLS `SELECT` 策略判定。
+     *
+     * - `expiresIn` 以秒为单位，过期后 URL 不可用。
+     * - 返回的 `fullSignedURL` 是服务端已拼接好的完整 URL，客户端可直接使用（无需再拼 HOST）。
+     * - `options.download` 为 `true` 时追加 `?download`，浏览器访问时自动触发下载。
+     *
+     * @param path Bucket 内相对路径。
+     * @param expiresIn 过期时间，单位为秒。
+     * @param options 签名下载 URL 选项；当前仅支持 `download`，不支持图片 `transform`。
+     */
+    createSignedUrl(path: string, expiresIn: number, options?: SignedUrlOptions): Promise<
+      | { data: { fullSignedURL: string }; error: null }
+      | { data: null; error: StorageError }
+    >
+
+    /**
+     * 批量生成对象的签名下载 URL。
+     *
+     * 需要登录态，权限由 `storage.objects` 的 RLS `SELECT` 策略判定。
+     *
+     * - 后端单次最多 500 个，超出时 SDK 自动分批发送。
+     * - 返回数组中每个元素包含 `path`、`fullSignedURL`（完整 URL，生成失败时为 `null`）、`error`。
+     * - 部分路径生成失败不会影响其他路径。
+     *
+     * @param paths Bucket 内相对路径数组。
+     * @param expiresIn 过期时间，单位为秒。
+     * @param options 签名下载 URL 选项；当前仅支持 `download`，不支持图片 `transform`。
+     */
+    createSignedUrls(paths: string[], expiresIn: number, options?: SignedUrlOptions): Promise<
+      | { data: Array<{ path: string; fullSignedURL: string | null; error: string | null }>; error: null }
+      | { data: null; error: StorageError }
+    >
+
+    /**
+     * 两阶段上传（第一阶段）：生成签名上传 URL，需登录态。
+     *
+     * 服务端基于调用者身份 + RLS 策略判断上传权限，生成临时签名 URL 和 token。
+     * 适合的场景：服务端鉴定用户权限后，将 `token` 下发给不受信客户端（如浏览器前端），
+     * 让客户端用 `uploadToSignedUrl` 直接上传文件，无需暴露登录凭证。
+     *
+     * - 返回的 `fullSignedURL` 是服务端已拼接好的完整上传 URL。
+     * - 返回的 `token` 是临时凭证，与 `uploadToSignedUrl` 配合使用。
+     * - `options.upsert` 为 `true` 时允许覆盖同名对象。
+     *
+     * @param path Bucket 内相对路径。
+     * @param options 签名上传选项，`upsert=true` 时允许覆盖。
+     * @see uploadToSignedUrl
+     */
+    createSignedUploadUrl(path: string, options?: { upsert?: boolean }): Promise<
+      | { data: { fullSignedURL: string; token: string; path: string }; error: null }
+      | { data: null; error: StorageError }
+    >
+
+    /**
+     * 两阶段上传（第二阶段）：使用签名上传 token 上传对象，无需登录态。
+     *
+     * 配合 `createSignedUploadUrl` 完成两阶段上传：
+     * 1. 服务端调用 `createSignedUploadUrl` 生成 token（需登录态）
+     * 2. 客户端调用本方法，凭 token 上传文件（无需登录态）
+     *
+     * - 请求**不携带**登录态，仅凭 `token` 鉴权。
+     * - `path` 和 `token` 必须与 `createSignedUploadUrl` 的返回值对应。
+     *
+     * @param path Bucket 内相对路径，需与 `createSignedUploadUrl` 的 `path` 一致。
+     * @param token `createSignedUploadUrl()` 返回的 `token`。
+     * @param fileBody 文件内容。
+     * @param fileOptions 上传选项。
+     * @see createSignedUploadUrl
+     */
+    uploadToSignedUrl(path: string, token: string, fileBody: FileBody, fileOptions?: UploadOptions): Promise<
+      | { data: { path: string; fullPath: string }; error: null }
+      | { data: null; error: StorageError }
+    >
+
+    /**
+     * 同步获取 public bucket 对象的公开访问 URL；不发请求、不返回 `error`。
+     *
+     * **同步方法**，不发起网络请求，不会抛异常。
+     *
+     * - URL 由客户端直接拼接 `{gateway}/v1/storages/object/public/{bucketId}/{path}` 得到。
+     * - URL 是否可访问取决于 Bucket 的 `public` 属性。
+     * - `options.download` 为 `true` 时追加 `?download`。
+     *
+     * @param path Bucket 内相对路径。
+     * @param options 公开 URL 选项；当前仅支持 `download`，不支持图片 `transform`。
+     */
+    getPublicUrl(path: string, options?: PublicUrlOptions): { data: { publicUrl: string } }
   }
 }