/**
 * 存储客户端统一接口（中间件层与各云厂商 Adapter 的契约）。
 * 实现类负责将 putObject/headObject 翻译为具体云厂商的 API 调用。
 */

/** 上传单个对象时的参数（body 与 sourceFile 二选一：sourceFile 为本地路径时由 SDK 直接读文件上传，避免先读成 Buffer） */
export interface PutObjectOptions {
  bucket: string;
  key: string;
  /** 文件内容，与 sourceFile 二选一 */
  body?: Buffer | NodeJS.ReadableStream;
  /** 本地文件路径，与 body 二选一；设置时由实现方用 SDK 的 SourceFile 等方式直接上传 */
  sourceFile?: string;
  contentType?: string;
  headers?: Record<string, string>;
}

/** headObject 的返回结果，仅用于判断云端是否已有同名对象（决定是否跳过上传） */
export interface HeadObjectResult {
  exists: boolean;
}

/** 统一存储客户端接口，各 Provider（华为 OBS、阿里 OSS、S3 等）需实现此接口 */
export interface StorageClient {
  putObject(options: PutObjectOptions): Promise<void>;
  headObject(bucket: string, key: string): Promise<HeadObjectResult>;
  /** 可选：按前缀列举 key，用于一次拉取后内存判断存在，避免每个文件都 head */
  listObjectKeys?(bucket: string, prefix: string): Promise<string[]>;
  /** 可选：只列举指定前缀的下一层目录前缀，避免扫描目录中的全部对象 */
  listFolderPrefixes?(bucket: string, prefix: string): Promise<string[]>;
}