@cloudbase/manager-node 4.11.0-alpha.2 → 4.11.0-alpha.4

package/types/storage/index.d.ts

@@ -66,6 +66,82 @@ export interface IStorageAclRule {
     /** 写权限规则，true 表示所有用户可写，字符串表示自定义规则表达式 */
     write: boolean | string;
 }
+/** 复制文件选项 */
+export interface ICopyOptions {
+    /** 源路径（云端路径，如 images/a.jpg） */
+    sourcePath: string;
+    /** 目标路径（云端路径，如 backup/a.jpg） */
+    destPath: string;
+    /** 是否强制覆盖已存在的文件 */
+    force?: boolean;
+    /** 是否跳过已存在的文件 */
+    skipExisting?: boolean;
+}
+/** 复制目录选项 */
+export interface ICopyDirectoryOptions extends ICopyOptions {
+    /** 包含模式（glob 格式） */
+    include?: string | string[];
+    /** 排除模式（glob 格式） */
+    exclude?: string | string[];
+    /** 并发数，默认 20 */
+    parallel?: number;
+    /** 进度回调 */
+    onProgress?: (info: ICopyProgress) => void;
+}
+/** 复制进度信息 */
+export interface ICopyProgress {
+    /** 已复制数量 */
+    copied: number;
+    /** 已跳过数量 */
+    skipped: number;
+    /** 总数量 */
+    total: number;
+    /** 当前正在处理的文件 */
+    currentFile: string;
+}
+/** 复制结果状态 */
+export type CopyStatus = 'copied' | 'skipped' | 'failed';
+/** 复制结果 */
+export interface ICopyResult {
+    /** 是否成功 */
+    success: boolean;
+    /** 源路径 */
+    sourcePath: string;
+    /** 目标路径 */
+    destPath: string;
+    /** 文件大小 (bytes) */
+    size?: number;
+    /** 复制状态 */
+    status: CopyStatus;
+    /** 失败时的错误信息 */
+    error?: string;
+}
+/** 搜索文件选项 */
+export interface ISearchOptions {
+    /** 搜索模式（glob 或正则表达式） */
+    pattern: string;
+    /** 搜索目录路径（不指定则搜索根目录） */
+    path?: string;
+    /** 是否为正则表达式 */
+    isRegex?: boolean;
+    /** 文件类型过滤（如 jpg, png） */
+    fileType?: string;
+    /** 限制数量，默认 100 */
+    limit?: number;
+    /** 是否包含详细信息 */
+    includeDetails?: boolean;
+}
+/** 搜索结果 */
+export interface ISearchResult {
+    /** 文件路径（云端路径） */
+    key: string;
+    /** 类型：file 或 directory */
+    type: 'file' | 'directory';
+    /** 文件大小 (bytes)，仅文件有效 */
+    size?: number;
+    /** 最后修改时间 (ISO 格式)，仅文件有效 */
+    lastModified?: string;
+}
 type OnProgress = (progressData: IProgressData) => void;
 type OnFileFinish = (error: Error, res: any, fileData: any) => void;
 export declare class StorageService {
@@ -227,9 +303,23 @@ export declare class StorageService {
      * ADMINWRITE：所有用户可读，仅管理员可写
      * ADMINONLY：仅管理员可读写
      * CUSTOM：自定义安全规则
-     * @returns {Promise<{ acl: AclType, rule?: IStorageAclRule }>}
-     */
-    getStorageAcl(): Promise<{
+     *
+     * @param options.withRule 是否返回自定义安全规则，默认 false 以保持向后兼容
+     * @returns 不传参数时返回 AclType（向后兼容），传入 { withRule: true } 时返回 { acl: AclType, rule?: IStorageAclRule }
+     *
+     * @example
+     * // 向后兼容的简单用法（返回 AclType）
+     * const acl = await storage.getStorageAcl()
+     * if (acl === 'READONLY') { ... }
+     *
+     * // 获取自定义安全规则（返回对象）
+     * const result = await storage.getStorageAcl({ withRule: true })
+     * console.log(result.acl, result.rule)
+     */
+    getStorageAcl(): Promise<AclType>;
+    getStorageAcl(options: {
+        withRule: true;
+    }): Promise<{
         acl: AclType;
         rule?: IStorageAclRule;
     }>;
@@ -270,6 +360,16 @@ export declare class StorageService {
      * @returns {Promise<IListFileInfo[]>}
      */
     walkCloudDirCustom(options: IWalkCloudDirOptions): Promise<IListFileInfo[]>;
+    /**
+     * 列出指定目录下的文件和子目录（不递归，只列当前层）
+     * 使用 COS Delimiter 参数实现
+     * @param {string} dirPath 目录路径，空字符串表示根目录
+     * @returns {Promise<{ files: IListFileInfo[], directories: string[] }>}
+     */
+    listCurrentDirectory(dirPath?: string): Promise<{
+        files: IListFileInfo[];
+        directories: string[];
+    }>;
     /**
      * 遍历本地文件夹
      * 忽略不包含 dir 路径，即如果 ignore 匹配 dir，dir 也不会被忽略
@@ -300,6 +400,54 @@ export declare class StorageService {
      * @memberof StorageService
      */
     getBucket(options: IGetBucketOpions): Promise<any>;
+    /**
+     * 复制单个文件
+     * @param options.sourcePath 源文件路径（云端路径，如 images/a.jpg）
+     * @param options.destPath 目标文件路径（云端路径，如 backup/a.jpg）
+     * @param options.force 是否强制覆盖
+     * @param options.skipExisting 是否跳过已存在的文件
+     * @returns 复制结果
+     */
+    copyFile(options: ICopyOptions): Promise<ICopyResult>;
+    /**
+     * 复制目录
+     * 遍历源目录下的所有文件，并行复制到目标目录
+     * @param options.sourcePath 源目录路径
+     * @param options.destPath 目标目录路径
+     * @param options.include 包含模式（glob 格式）
+     * @param options.exclude 排除模式（glob 格式）
+     * @param options.force 是否强制覆盖
+     * @param options.skipExisting 是否跳过已存在的文件
+     * @param options.parallel 并发数，默认 20
+     * @param options.onProgress 进度回调
+     * @returns 复制结果数组
+     */
+    copyDirectory(options: ICopyDirectoryOptions): Promise<ICopyResult[]>;
+    /**
+     * 移动文件（复制后删除源文件）
+     * 注意：移动操作是「复制 + 删除」的两步操作，如果删除失败，文件会同时存在于源和目标位置
+     * @param options 与 copyFile 相同的选项
+     * @returns 移动结果，如果删除源文件失败会在 error 字段说明
+     */
+    moveFile(options: ICopyOptions): Promise<ICopyResult>;
+    /**
+     * 移动目录（复制后删除源目录）
+     * 注意：移动操作是「复制 + 删除」的两步操作，如果部分删除失败，文件会同时存在于源和目标位置
+     * @param options 与 copyDirectory 相同的选项
+     * @returns 移动结果数组，删除失败的文件会在对应结果的 error 字段说明
+     */
+    moveDirectory(options: ICopyDirectoryOptions): Promise<ICopyResult[]>;
+    /**
+     * 搜索文件和目录（只搜索当前目录，不递归）
+     * @param options.pattern 搜索模式（支持 glob 或正则表达式）
+     * @param options.path 搜索目录路径（不指定则搜索根目录）
+     * @param options.isRegex 是否为正则表达式模式
+     * @param options.fileType 文件类型过滤
+     * @param options.limit 限制返回数量，默认 100
+     * @param options.includeDetails 是否包含详细信息（大小、修改时间）
+     * @returns 搜索结果数组（包含文件和目录）
+     */
+    searchFiles(options: ISearchOptions): Promise<ISearchResult[]>;
     /**
      * 获取 COS 配置
      */