export interface IUploadObjectHttpOptions {
    /** Bucket ID */
    bucketId: string;
    /** 对象名，支持路径，例如 folder/file.png */
    objectName: string;
    /**
     * 文件来源（二选一）：
     * - localPath：本地文件绝对/相对路径
     * - body：Buffer 或可读流
     */
    localPath?: string;
    body?: Buffer | NodeJS.ReadableStream;
    /** MIME 类型，默认 application/octet-stream */
    contentType?: string;
    /** 文件字节数；不传时若为 localPath/Buffer 会自动推断 */
    contentLength?: number;
    /**
     * 缓存控制；传 number 自动转换为 max-age=<value>，传 string 直接作为 Cache-Control 头值
     */
    cacheControl?: number | string;
    /** 自定义 metadata（JSON 对象），将以 Base64 编码后放入 x-metadata 头 */
    metadata?: Record<string, any>;
    /** 爬虫指令（X-Robots-Tag 头） */
    xRobotsTag?: string;
    /** POST 时是否允许覆盖（x-upsert: true） */
    upsert?: boolean;
    /** 使用 PUT 方法（始终覆盖，等价于 x-upsert: true） */
    usePut?: boolean;
    /**
     * 鉴权令牌（Bearer Token），支持以下三种类型之一：
     * - access_token：登录态访问令牌
     * - apiKey：服务端管理员访问凭证（JWT 格式，可由 env.createApiKey 创建，长期有效）
     * - publishableKey：前端匿名访问凭证
     *
     * 调用时以 `Authorization: Bearer <token>` 形式传递。
     * ⚠️ apiKey 严禁在客户端使用。
     */
    accessToken: string;
    /** 可选覆盖 envId，不传则取当前环境 */
    envId?: string;
}
export interface IUploadObjectHttpResult {
    Id: string;
    Key: string;
}
/** 删除单个对象参数 */
export interface IDeleteObjectHttpOptions {
    /** Bucket ID */
    bucketId: string;
    /** 对象名，支持路径，例如 folder/file.png */
    objectName: string;
    /** Bearer Token（access_token / apiKey / publishableKey 均可） */
    accessToken: string;
    /** 可选覆盖 envId */
    envId?: string;
}
/** 删除单个对象响应 */
export interface IDeleteObjectHttpResult {
    message: string;
}
/** 批量删除对象参数 */
export interface IDeleteObjectsHttpOptions {
    /** Bucket ID */
    bucketId: string;
    /**
     * 要删除的对象名列表，1 ~ 20 个。
     * ⚠️ 官方文档字段名为 `prefixes`，但本质是完整 object name 的精确匹配（非前缀匹配）
     */
    prefixes: string[];
    /** Bearer Token */
    accessToken: string;
    /** 可选覆盖 envId */
    envId?: string;
}
/** 批量删除对象响应（单条） */
export interface IDeletedObjectInfo {
    name: string;
    bucket_id: string;
    owner_id: string;
    [key: string]: any;
}
/** 复制对象参数 */
export interface ICopyObjectHttpOptions {
    /** 源 Bucket ID */
    bucketId: string;
    /** 源对象名 */
    sourceKey: string;
    /** 目标对象名 */
    destinationKey: string;
    /** 目标 Bucket ID，默认与源 Bucket 相同 */
    destinationBucket?: string;
    /**
     * 系统 metadata（对应 DB 列 storage.objects.metadata），
     * 仅在 copyMetadata=false 时生效：以源 metadata 为底，与请求 metadata 合并（同 key 覆盖）。
     * COS 后端实际会识别的字段：cacheControl / mimetype / contentType。
     * 通过 body.metadata 字段传递。
     */
    metadata?: Record<string, any>;
    /**
     * 用户自定义 metadata（对应 DB 列 storage.objects.user_metadata），
     * 仅在 copyMetadata=false 时生效：**整体替换**目标对象的 user_metadata（不是合并）。
     * 通过 x-metadata Header 传递，内部会 Base64(JSON) 编码。
     */
    userMetadata?: Record<string, any>;
    /**
     * 是否复制源对象的 metadata，默认 true。
     * - true：直接继承源对象 metadata / user_metadata，请求里的 metadata 和 userMetadata 均被忽略
     * - false：
     *   · metadata 字段（若传）与源 metadata 合并
     *   · userMetadata 字段（若传）整体替换源 user_metadata
     */
    copyMetadata?: boolean;
    /** 是否允许覆盖目标位置已有对象（x-upsert: "true"） */
    upsert?: boolean;
    /** Bearer Token（access_token / apiKey / publishableKey 均可） */
    accessToken: string;
    /** 可选覆盖 envId */
    envId?: string;
}
/** 复制对象响应 */
export interface ICopyObjectHttpResult {
    Id: string;
    Key: string;
    name: string;
    bucket_id: string;
    owner_id: string;
    version: string;
    id: string;
    updated_at: string;
    created_at: string;
    last_accessed_at: string;
    metadata: Record<string, any>;
    user_metadata: Record<string, any>;
    [key: string]: any;
}
/** 移动对象参数 */
export interface IMoveObjectHttpOptions {
    /** 源 Bucket ID */
    bucketId: string;
    /** 源对象名 */
    sourceKey: string;
    /** 目标对象名 */
    destinationKey: string;
    /** 目标 Bucket ID，默认与源 Bucket 相同 */
    destinationBucket?: string;
    /** Bearer Token（access_token / apiKey / publishableKey 均可） */
    accessToken: string;
    /** 可选覆盖 envId */
    envId?: string;
}
/** 移动对象响应 */
export interface IMoveObjectHttpResult {
    message: string;
    Id: string;
    Key: string;
}
export type IListObjectsSortColumn = 'name' | 'created_at' | 'updated_at';
export type IListObjectsSortOrder = 'asc' | 'desc';
/** 列出对象参数 */
export interface IListObjectsHttpOptions {
    /** Bucket ID（Path 参数） */
    bucketId: string;
    /** 路径前缀 */
    prefix?: string;
    /** 分页限制，1 ~ 1000 */
    limit?: number;
    /** 游标（由上一次响应的 nextCursor 提供） */
    cursor?: string;
    /** 是否使用 / 作为分隔符区分文件夹 */
    withDelimiter?: boolean;
    /** 排序选项 */
    sortBy?: {
        /** 允许值：name、created_at、updated_at */
        column?: IListObjectsSortColumn;
        /** 排序方向：asc（默认）、desc */
        order?: IListObjectsSortOrder;
    };
    /** Bearer Token（access_token / apiKey / publishableKey 均可） */
    accessToken: string;
    /** 可选覆盖 envId */
    envId?: string;
}
/** 列表中的“文件夹”条目 */
export interface IListObjectsFolderItem {
    key: string;
    name: string;
    id: string | null;
    updated_at: string | null;
    created_at: string | null;
    last_accessed_at: string | null;
    metadata: Record<string, any> | null;
}
/** 列表中的“对象/文件”条目 */
export interface IListObjectsObjectItem {
    name: string;
    id: string;
    updated_at: string;
    created_at: string;
    last_accessed_at: string;
    metadata: Record<string, any>;
    [key: string]: any;
}
/** 列出对象响应 */
export interface IListObjectsHttpResult {
    folders: IListObjectsFolderItem[];
    objects: IListObjectsObjectItem[];
    hasNext: boolean;
    nextCursor?: string;
    nextCursorKey?: string;
    [key: string]: any;
}
/** 生成签名下载 URL 参数 */
export interface ISignObjectHttpOptions {
    /** Bucket ID（Path 参数） */
    bucketId: string;
    /** 对象名称（Path 参数） */
    objectName: string;
    /** 过期时间（秒），必须 >= 1 */
    expiresIn: number;
    /** Bearer Token（access_token / apiKey / publishableKey 均可） */
    accessToken: string;
    /** 可选覆盖 envId */
    envId?: string;
}
/** 生成签名下载 URL 响应 */
export interface ISignObjectHttpResult {
    signedURL: string;
}
/** 批量生成签名 URL 参数 */
export interface ISignObjectsHttpOptions {
    /** Bucket ID（Path 参数） */
    bucketId: string;
    /** 过期时间（秒），必须 >= 1 */
    expiresIn: number;
    /** 对象名称列表，不能为空，最多 500 个 */
    paths: string[];
    /** Bearer Token（access_token / apiKey / publishableKey 均可） */
    accessToken: string;
    /** 可选覆盖 envId */
    envId?: string;
}
/** 批量签名结果条目 */
export interface ISignedObjectItem {
    path: string;
    signedURL: string | null;
    error: string | null;
    [key: string]: any;
}
/** 批量生成签名 URL 响应 */
export type ISignObjectsHttpResult = ISignedObjectItem[];
/** 生成签名上传 URL 参数 */
export interface ISignUploadObjectHttpOptions {
    /** Bucket ID（Path 参数） */
    bucketId: string;
    /** 对象名称（Path 参数） */
    objectName: string;
    /** "true" 时允许覆盖（x-upsert: true） */
    upsert?: boolean;
    /** Bearer Token（access_token / apiKey / publishableKey 均可） */
    accessToken: string;
    /** 可选覆盖 envId */
    envId?: string;
}
/** 生成签名上传 URL 响应 */
export interface ISignUploadObjectHttpResult {
    url: string;
    token: string;
}
/** 通过签名 URL 上传参数 */
export interface IUploadObjectBySignHttpOptions {
    /** Bucket ID（Path 参数） */
    bucketId: string;
    /** 对象名称（Path 参数） */
    objectName: string;
    /** 签名上传 token（Query 参数） */
    token: string;
    /** 文件来源（二选一）：localPath 或 body */
    localPath?: string;
    body?: Buffer | NodeJS.ReadableStream;
    /** MIME 类型，默认 application/octet-stream */
    contentType?: string;
    /** 文件字节数；不传时若为 localPath/Buffer 会自动推断 */
    contentLength?: number;
    /** 可选覆盖 envId */
    envId?: string;
}
/** 通过签名 URL 上传响应 */
export interface IUploadObjectBySignHttpResult {
    Key: string;
}
/** 本地 manifest 条目：待发布文件的内容摘要 */
export interface ILocalManifestItem {
    /** 云端 Key */
    key: string;
    /** 本地文件内容 MD5（32 位小写十六进制） */
    md5: string;
    /** 文件大小（字节） */
    size: number;
    /** 本地文件绝对路径 */
    localPath: string;
}
/** 远端 manifest 条目：远端 COS 对象信息 */
export interface IRemoteManifestItem {
    /** 云端 Key */
    key: string;
    /** 对象 ETag（去除首尾引号后） */
    etag: string;
    /** 对象大小（字节） */
    size: number;
}
/** manifest 差异结果：用于回滚判定与发布后清理 */
export interface IManifestDiffResult {
    /** 本地有、远端无 —— 本次新增 */
    added: string[];
    /** 本地有、远端也有 —— 本次覆盖 */
    overwritten: string[];
    /** 远端有、本地无 —— 可作为 prune 候选 */
    removed: string[];
}
/** manifest 校验结果：用于发布后确认远端内容是否与本地一致 */
export interface IManifestVerifyResult {
    /** 是否校验通过 */
    ok: boolean;
    /** 本地有但远端不存在的 Key */
    missing: string[];
    /** 远端存在但摘要或大小不匹配的 Key */
    mismatched: string[];
}
/** 上传进度回调（与 StorageService 上传回调语义一致） */
export type IConsistentUploadProgress = (progressData: {
    loaded: number;
    total: number;
    speed: number;
    percent: number;
}) => void;
/** 单文件上传完成回调（与 StorageService 的 onFileFinish 语义一致） */
export type IConsistentUploadFileFinish = (error: Error, res: any, fileData: any) => void;
/** 一致性发布上传选项 */
export interface IConsistentUploadOptions {
    /** 本地待发布目录（绝对或相对路径） */
    localPath: string;
    /** 云端目标前缀，无前导斜杠（如 'dist'）；为空表示桶根 */
    cloudPath?: string;
    /** 目标桶 */
    bucket: string;
    /** 目标地域 */
    region: string;
    /** 忽略规则，语义与现有 uploadDirectoryCustom 的 ignore 一致 */
    ignore?: string | string[];
    /** 是否获取文件 fileId */
    fileId?: boolean;
    /** 并发数量 */
    parallel?: number;
    /** 重试次数 */
    retryCount?: number;
    /** 重试时间间隔（毫秒） */
    retryInterval?: number;
    /** 上传进度回调 */
    onProgress?: IConsistentUploadProgress;
    /** 单文件上传完成回调（error / res / fileData，与普通上传语义一致） */
    onFileFinish?: IConsistentUploadFileFinish;
    /** 发布后校验远端与本地产物一致 */
    verify?: boolean;
    /** 安全发布：发布前快照备份 + 失败自动回滚 */
    safe?: boolean;
    /**
     * ⚠️ 危险参数：发布后清理远端多余文件。
     * 会删除云端 cloudPath 下、本地构建中不存在的全部文件。
     * 若误传错误的 localPath/cloudPath，整个目录都会被判定为冗余而删除。
     * 发布成功后备份默认保留，prune 误删的文件可从备份前缀人工恢复；
     * 调用方（CLI）必须经用户二次确认后才可开启。
     */
    prune?: boolean;
    /**
     * 入口文件列表。
     * 为相对 localPath 的相对路径，如 'index.html'、'admin/index.html'。
     * 未指定时默认识别所有层级下的 index.html。
     */
    entries?: string[];
    /** 共享桶（ExternalStorage）内的目录前缀，未传时按 COS 原始 Key 处理 */
    basePath?: string;
}
/** 远端多余文件清理结果 */
export interface IPruneResult {
    /** 成功删除的云端 Key */
    deletedKeys: string[];
    /** 删除失败的文件及原因 */
    failedKeys: {
        key: string;
        error: string;
    }[];
}
/** 一致性发布结果 */
export interface IConsistentUploadResult {
    /** 本次成功上传的云端 Key */
    uploadedKeys: string[];
    /** 是否执行了发布后校验 */
    verified: boolean;
    /**
     * 发布前备份前缀，仅 safe 开启时返回，如 .cloudbase-backup/1724073600000/。
     * 备份一律不由编排自动清理（发布成功与回滚后均保留）：prune 误删或需要
     * 人工核查时可从中恢复；调用方确认无误后应通过 cleanupBackup 显式清理。
     */
    backupPrefix?: string;
    /** 远端多余文件清理结果，仅 prune 开启时存在 */
    prune?: IPruneResult;
}
/** 下载方法，仅支持 GET / HEAD */
export type IDownloadObjectHttpMethod = 'GET' | 'HEAD';
/** 下载对象公共参数 */
export interface IDownloadObjectBaseHttpOptions {
    /** Bucket ID（Path 参数） */
    bucketId: string;
    /** 对象名称（Path 参数） */
    objectName: string;
    /** HTTP 方法：GET 返回文件流；HEAD 仅返回响应头 */
    method?: IDownloadObjectHttpMethod;
    /** Query 参数：存在时触发浏览器下载，值作为下载文件名 */
    download?: string;
    /** 条件请求头：ETag 校验 */
    ifNoneMatch?: string;
    /** 条件请求头：修改时间校验 */
    ifModifiedSince?: string;
    /** 范围请求头（断点续传） */
    range?: string;
    /** 可选覆盖 envId */
    envId?: string;
}
/** 下载对象（需认证）参数 */
export interface IDownloadAuthenticatedObjectHttpOptions extends IDownloadObjectBaseHttpOptions {
    /** Bearer Token（access_token / apiKey / publishableKey 均可） */
    accessToken: string;
}
/** 下载对象（可选认证）参数 */
export interface IDownloadObjectHttpOptions extends IDownloadObjectBaseHttpOptions {
    /** Bearer Token（可选；不传时仅 public bucket 可访问） */
    accessToken?: string;
}
/** 下载公开对象参数 */
export interface IDownloadPublicObjectHttpOptions {
    /** Bucket ID（Path 参数，必须为 public bucket） */
    bucketId: string;
    /** 对象名称（Path 参数） */
    objectName: string;
    /** HTTP 方法：GET 返回文件流；HEAD 仅返回响应头 */
    method?: IDownloadObjectHttpMethod;
    /** Query 参数：存在时触发浏览器下载，值作为下载文件名 */
    download?: string;
    /** 可选覆盖 envId */
    envId?: string;
}
/** 通过签名 URL 下载对象参数 */
export interface IDownloadObjectBySignHttpOptions {
    /** Bucket ID（Path 参数） */
    bucketId: string;
    /** 对象名称（Path 参数） */
    objectName: string;
    /** 签名 token（Query 参数，必填） */
    token: string;
    /** HTTP 方法：GET 返回文件流；HEAD 仅返回响应头 */
    method?: IDownloadObjectHttpMethod;
    /** Query 参数：存在时触发浏览器下载，值作为下载文件名 */
    download?: string;
    /** 可选覆盖 envId */
    envId?: string;
}
/** Storage 响应头（小写 key） */
export interface IStorageResponseHeaders {
    /** 是否支持 Range 请求（断点续传） */
    'accept-ranges'?: string;
    /** 缓存控制（HTTP 响应级别） */
    'cache-control'?: string;
    /** 响应体字节数 */
    'content-length'?: string;
    /** MIME 类型 */
    'content-type'?: string;
    /** 响应时间（GMT） */
    'date'?: string;
    /** 响应体 ETag */
    etag?: string;
    /** 对象最后修改时间 */
    'last-modified'?: string;
    /** 服务器标识 */
    server?: string;
    /** CloudBase 请求追踪 ID */
    'x-cloudbase-request-id'?: string;
    /** 通用请求追踪 ID */
    'x-request-id'?: string;
    /** 爬虫指令 */
    'x-robots-tag'?: string;
    /** 其他未枚举的头 */
    [key: string]: string | undefined;
}
/** 下载对象响应（GET 返回流；HEAD 的 body 为 null） */
export interface IDownloadObjectHttpResult {
    /** HTTP 状态码，例如 200 / 206 / 304 */
    status: number;
    /** 响应头（小写 key） */
    headers: IStorageResponseHeaders;
    /** GET 时为可读流，HEAD 时为 null */
    body: NodeJS.ReadableStream | null;
}
/** 对象元信息（GET 响应 JSON） */
export interface IObjectInfoHttpPayload {
    id: string;
    name: string;
    version: string;
    bucket_id: string;
    size: number;
    content_type: string;
    cache_control: string;
    etag: string;
    metadata: Record<string, any>;
    last_modified: string;
    created_at: string;
    [key: string]: any;
}
/** 获取对象元信息（需认证）参数 */
export interface IGetObjectInfoAuthenticatedHttpOptions {
    /** Bucket ID（Path 参数） */
    bucketId: string;
    /** 对象名称（Path 参数） */
    objectName: string;
    /** HTTP 方法：GET 返回 JSON；HEAD 仅返回响应头 */
    method?: IDownloadObjectHttpMethod;
    /** Bearer Token（access_token / apiKey / publishableKey 均可） */
    accessToken: string;
    /** 可选覆盖 envId */
    envId?: string;
}
/** 获取公开对象元信息参数（仅支持 GET） */
export interface IGetObjectInfoPublicHttpOptions {
    /** Bucket ID（Path 参数，必须为 public bucket） */
    bucketId: string;
    /** 对象名称（Path 参数） */
    objectName: string;
    /** 可选覆盖 envId */
    envId?: string;
}
/** 获取对象元信息响应（HEAD 不返回 body） */
export interface IGetObjectInfoHttpResult {
    /** HTTP 状态码，例如 200 / 304 */
    status: number;
    /** 响应头（小写 key） */
    headers: IStorageResponseHeaders;
    /** GET 时返回 JSON；HEAD 时为 null */
    body: IObjectInfoHttpPayload | null;
}