@file-ud.js/plugins 0.1.0

package/dist/downloader/index.js.map

@@ -0,0 +1 @@
+{"version":3,"sources":["../../src/retry/smart-retry-plugin.ts"],"names":[],"mappings":"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","sourcesContent":["import {\n  type IUDPlugin,\n  type PluginContext,\n  type TransferFile,\n} from \"@file-ud.js/core\";\n\n/**\n * 智能重试策略配置\n */\nexport interface SmartRetryConfig {\n  /** 最大重试次数（默认 3） */\n  maxRetries?: number;\n  /** 重试策略：fixed(固定延迟) | exponential(指数退避) | linear(线性增长) */\n  strategy?: \"fixed\" | \"exponential\" | \"linear\";\n  /** 初始延迟时间（毫秒，默认 1000） */\n  initialDelay?: number;\n  /** 最大延迟时间（毫秒，默认 30000） */\n  maxDelay?: number;\n  /** 仅对特定错误码重试（空数组表示对所有错误重试） */\n  retryableErrors?: string[];\n  /** 是否显示重试提示（默认 true） */\n  showRetryNotification?: boolean;\n}\n\n/**\n * 智能重试插件\n *\n * 通用传输重试，同时支持上传和下载场景。\n *\n * 功能特性：\n * - 支持多种重试策略（固定延迟、指数退避、线性增长）\n * - 可配置重试次数和延迟时间\n * - 自动过滤可重试的错误类型\n * - 提供重试进度通知\n *\n * @example\n * ```typescript\n * import { SmartRetryPlugin } from '@file-ud.js/plugins/retry';\n *\n * // 上传重试\n * const uploader = FileUD.createUploader(\"test\", { ... });\n * uploader.use(new SmartRetryPlugin({ maxRetries: 5, strategy: \"exponential\" }));\n *\n * // 下载重试\n * const downloader = FileUD.createDownloader(\"test\", { ... });\n * downloader.use(new SmartRetryPlugin({ maxRetries: 3, strategy: \"linear\" }));\n * ```\n */\ntype RetryableTransferFile = TransferFile<any, any>;\n\nexport class SmartRetryPlugin implements IUDPlugin<RetryableTransferFile> {\n  name = \"SmartRetryPlugin\";\n  version = \"1.0.0\";\n  desc = \"智能重试策略插件，同时支持上传/下载，支持指数退避、线性增长等多种重试策略\";\n  priority = 10; // 较高优先级，在其他插件之前执行\n\n  private config: Required<SmartRetryConfig>;\n  private retryCountMap = new Map<string, number>(); // 文件ID -> 重试次数\n  private retryTimerMap = new Map<string, ReturnType<typeof setTimeout>>(); // 文件ID -> 重试定时器\n\n  constructor(config: SmartRetryConfig = {}) {\n    this.config = {\n      maxRetries: config.maxRetries ?? 3,\n      strategy: config.strategy ?? \"exponential\",\n      initialDelay: config.initialDelay ?? 1000,\n      maxDelay: config.maxDelay ?? 30000,\n      retryableErrors: config.retryableErrors ?? [],\n      showRetryNotification: config.showRetryNotification ?? true,\n    };\n  }\n\n  /**\n   * 插件初始化\n   */\n  install(transfer: any, options?: any): void {\n    console.log(`✅ [${this.name}] 插件已安装`, this.config);\n  }\n\n  /**\n   * 传输失败时触发（上传/下载通用）\n   */\n  onError(\n    error: Error,\n    file: RetryableTransferFile,\n    context: PluginContext<RetryableTransferFile>,\n  ): void {\n    const fileId = file.fileId;\n    const currentRetries = this.retryCountMap.get(fileId) || 0;\n\n    // 检查是否超过最大重试次数\n    if (currentRetries >= this.config.maxRetries) {\n      console.warn(\n        `[${this.name}] 文件 ${file.fileName} 已达到最大重试次数 (${this.config.maxRetries})，停止重试`\n      );\n      this.cleanup(fileId);\n      return;\n    }\n\n    // 检查是否为可重试的错误\n    if (!this.isRetryableError(error)) {\n      console.log(\n        `[${this.name}] 文件 ${file.fileName} 的错误不可重试，跳过重试`\n      );\n      return;\n    }\n\n    // 计算延迟时间\n    const delay = this.calculateDelay(currentRetries);\n\n    // 设置重试定时器\n    const timer = setTimeout(() => {\n      console.log(\n        `[${this.name}] 文件 ${file.fileName} 第 ${currentRetries + 1}/${this.config.maxRetries} 次重试（延迟 ${delay}ms）`\n      );\n\n      // 更新重试计数\n      this.retryCountMap.set(fileId, currentRetries + 1);\n\n      // 触发重试（TransferFile 基类提供 retry() 方法）\n      file.retry();\n\n      // 清除定时器引用\n      this.retryTimerMap.delete(fileId);\n    }, delay);\n\n    this.retryTimerMap.set(fileId, timer);\n\n    // 显示重试通知\n    if (this.config.showRetryNotification) {\n      console.info(\n        `[${this.name}] ⏳ 文件 ${file.fileName} 将在 ${delay}ms 后自动重试...`\n      );\n    }\n  }\n\n  /**\n   * 传输成功时清理重试状态\n   */\n  onSuccess(\n    response: any,\n    file: RetryableTransferFile,\n    context: PluginContext<RetryableTransferFile>,\n  ): void {\n    this.cleanup(file.fileId);\n  }\n\n  /**\n   * 文件移除时清理重试状态\n   */\n  destroy(): void {\n    // 清除所有待执行的重试定时器\n    this.retryTimerMap.forEach((timer) => clearTimeout(timer));\n    this.retryTimerMap.clear();\n    this.retryCountMap.clear();\n    console.log(`🗑️ [${this.name}] 插件已销毁`);\n  }\n\n  /**\n   * 判断错误是否可重试\n   */\n  private isRetryableError(error: any): boolean {\n    // 如果没有配置可重试错误列表，则对所有错误重试\n    if (this.config.retryableErrors.length === 0) {\n      return true;\n    }\n\n    // 检查错误码是否在可重试列表中\n    const errorCode = error.code || error.message || \"\";\n    return this.config.retryableErrors.some((code) =>\n      errorCode.includes(code)\n    );\n  }\n\n  /**\n   * 计算延迟时间\n   */\n  private calculateDelay(retryCount: number): number {\n    const { strategy, initialDelay, maxDelay } = this.config;\n\n    let delay: number;\n\n    switch (strategy) {\n      case \"fixed\":\n        // 固定延迟\n        delay = initialDelay;\n        break;\n\n      case \"linear\":\n        // 线性增长：delay = initialDelay * (retryCount + 1)\n        delay = initialDelay * (retryCount + 1);\n        break;\n\n      case \"exponential\":\n      default:\n        // 指数退避：delay = initialDelay * 2^retryCount\n        delay = initialDelay * Math.pow(2, retryCount);\n        break;\n    }\n\n    // 限制最大延迟时间\n    return Math.min(delay, maxDelay);\n  }\n\n  /**\n   * 清理文件的重试状态\n   */\n  private cleanup(fileId: string): void {\n    // 清除待执行的定时器\n    const timer = this.retryTimerMap.get(fileId);\n    if (timer) {\n      clearTimeout(timer);\n      this.retryTimerMap.delete(fileId);\n    }\n\n    // 清除重试计数\n    this.retryCountMap.delete(fileId);\n  }\n}\n"]}

package/dist/downloader/index.mjs

@@ -0,0 +1,124 @@
+// src/retry/smart-retry-plugin.ts
+var SmartRetryPlugin = class {
+  // 文件ID -> 重试定时器
+  constructor(config = {}) {
+    this.name = "SmartRetryPlugin";
+    this.version = "1.0.0";
+    this.desc = "\u667A\u80FD\u91CD\u8BD5\u7B56\u7565\u63D2\u4EF6\uFF0C\u540C\u65F6\u652F\u6301\u4E0A\u4F20/\u4E0B\u8F7D\uFF0C\u652F\u6301\u6307\u6570\u9000\u907F\u3001\u7EBF\u6027\u589E\u957F\u7B49\u591A\u79CD\u91CD\u8BD5\u7B56\u7565";
+    this.priority = 10;
+    this.retryCountMap = /* @__PURE__ */ new Map();
+    // 文件ID -> 重试次数
+    this.retryTimerMap = /* @__PURE__ */ new Map();
+    this.config = {
+      maxRetries: config.maxRetries ?? 3,
+      strategy: config.strategy ?? "exponential",
+      initialDelay: config.initialDelay ?? 1e3,
+      maxDelay: config.maxDelay ?? 3e4,
+      retryableErrors: config.retryableErrors ?? [],
+      showRetryNotification: config.showRetryNotification ?? true
+    };
+  }
+  /**
+   * 插件初始化
+   */
+  install(transfer, options) {
+    console.log(`\u2705 [${this.name}] \u63D2\u4EF6\u5DF2\u5B89\u88C5`, this.config);
+  }
+  /**
+   * 传输失败时触发（上传/下载通用）
+   */
+  onError(error, file, context) {
+    const fileId = file.fileId;
+    const currentRetries = this.retryCountMap.get(fileId) || 0;
+    if (currentRetries >= this.config.maxRetries) {
+      console.warn(
+        `[${this.name}] \u6587\u4EF6 ${file.fileName} \u5DF2\u8FBE\u5230\u6700\u5927\u91CD\u8BD5\u6B21\u6570 (${this.config.maxRetries})\uFF0C\u505C\u6B62\u91CD\u8BD5`
+      );
+      this.cleanup(fileId);
+      return;
+    }
+    if (!this.isRetryableError(error)) {
+      console.log(
+        `[${this.name}] \u6587\u4EF6 ${file.fileName} \u7684\u9519\u8BEF\u4E0D\u53EF\u91CD\u8BD5\uFF0C\u8DF3\u8FC7\u91CD\u8BD5`
+      );
+      return;
+    }
+    const delay = this.calculateDelay(currentRetries);
+    const timer = setTimeout(() => {
+      console.log(
+        `[${this.name}] \u6587\u4EF6 ${file.fileName} \u7B2C ${currentRetries + 1}/${this.config.maxRetries} \u6B21\u91CD\u8BD5\uFF08\u5EF6\u8FDF ${delay}ms\uFF09`
+      );
+      this.retryCountMap.set(fileId, currentRetries + 1);
+      file.retry();
+      this.retryTimerMap.delete(fileId);
+    }, delay);
+    this.retryTimerMap.set(fileId, timer);
+    if (this.config.showRetryNotification) {
+      console.info(
+        `[${this.name}] \u23F3 \u6587\u4EF6 ${file.fileName} \u5C06\u5728 ${delay}ms \u540E\u81EA\u52A8\u91CD\u8BD5...`
+      );
+    }
+  }
+  /**
+   * 传输成功时清理重试状态
+   */
+  onSuccess(response, file, context) {
+    this.cleanup(file.fileId);
+  }
+  /**
+   * 文件移除时清理重试状态
+   */
+  destroy() {
+    this.retryTimerMap.forEach((timer) => clearTimeout(timer));
+    this.retryTimerMap.clear();
+    this.retryCountMap.clear();
+    console.log(`\u{1F5D1}\uFE0F [${this.name}] \u63D2\u4EF6\u5DF2\u9500\u6BC1`);
+  }
+  /**
+   * 判断错误是否可重试
+   */
+  isRetryableError(error) {
+    if (this.config.retryableErrors.length === 0) {
+      return true;
+    }
+    const errorCode = error.code || error.message || "";
+    return this.config.retryableErrors.some(
+      (code) => errorCode.includes(code)
+    );
+  }
+  /**
+   * 计算延迟时间
+   */
+  calculateDelay(retryCount) {
+    const { strategy, initialDelay, maxDelay } = this.config;
+    let delay;
+    switch (strategy) {
+      case "fixed":
+        delay = initialDelay;
+        break;
+      case "linear":
+        delay = initialDelay * (retryCount + 1);
+        break;
+      case "exponential":
+      default:
+        delay = initialDelay * Math.pow(2, retryCount);
+        break;
+    }
+    return Math.min(delay, maxDelay);
+  }
+  /**
+   * 清理文件的重试状态
+   */
+  cleanup(fileId) {
+    const timer = this.retryTimerMap.get(fileId);
+    if (timer) {
+      clearTimeout(timer);
+      this.retryTimerMap.delete(fileId);
+    }
+    this.retryCountMap.delete(fileId);
+  }
+};
+
+export { SmartRetryPlugin };
+//# sourceMappingURL=out.js.map
+//# sourceMappingURL=index.mjs.map

package/dist/downloader/index.mjs.map

@@ -0,0 +1 @@
+{"version":3,"sources":["../../src/retry/smart-retry-plugin.ts"],"names":[],"mappings":"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","sourcesContent":["import {\n  type IUDPlugin,\n  type PluginContext,\n  type TransferFile,\n} from \"@file-ud.js/core\";\n\n/**\n * 智能重试策略配置\n */\nexport interface SmartRetryConfig {\n  /** 最大重试次数（默认 3） */\n  maxRetries?: number;\n  /** 重试策略：fixed(固定延迟) | exponential(指数退避) | linear(线性增长) */\n  strategy?: \"fixed\" | \"exponential\" | \"linear\";\n  /** 初始延迟时间（毫秒，默认 1000） */\n  initialDelay?: number;\n  /** 最大延迟时间（毫秒，默认 30000） */\n  maxDelay?: number;\n  /** 仅对特定错误码重试（空数组表示对所有错误重试） */\n  retryableErrors?: string[];\n  /** 是否显示重试提示（默认 true） */\n  showRetryNotification?: boolean;\n}\n\n/**\n * 智能重试插件\n *\n * 通用传输重试，同时支持上传和下载场景。\n *\n * 功能特性：\n * - 支持多种重试策略（固定延迟、指数退避、线性增长）\n * - 可配置重试次数和延迟时间\n * - 自动过滤可重试的错误类型\n * - 提供重试进度通知\n *\n * @example\n * ```typescript\n * import { SmartRetryPlugin } from '@file-ud.js/plugins/retry';\n *\n * // 上传重试\n * const uploader = FileUD.createUploader(\"test\", { ... });\n * uploader.use(new SmartRetryPlugin({ maxRetries: 5, strategy: \"exponential\" }));\n *\n * // 下载重试\n * const downloader = FileUD.createDownloader(\"test\", { ... });\n * downloader.use(new SmartRetryPlugin({ maxRetries: 3, strategy: \"linear\" }));\n * ```\n */\ntype RetryableTransferFile = TransferFile<any, any>;\n\nexport class SmartRetryPlugin implements IUDPlugin<RetryableTransferFile> {\n  name = \"SmartRetryPlugin\";\n  version = \"1.0.0\";\n  desc = \"智能重试策略插件，同时支持上传/下载，支持指数退避、线性增长等多种重试策略\";\n  priority = 10; // 较高优先级，在其他插件之前执行\n\n  private config: Required<SmartRetryConfig>;\n  private retryCountMap = new Map<string, number>(); // 文件ID -> 重试次数\n  private retryTimerMap = new Map<string, ReturnType<typeof setTimeout>>(); // 文件ID -> 重试定时器\n\n  constructor(config: SmartRetryConfig = {}) {\n    this.config = {\n      maxRetries: config.maxRetries ?? 3,\n      strategy: config.strategy ?? \"exponential\",\n      initialDelay: config.initialDelay ?? 1000,\n      maxDelay: config.maxDelay ?? 30000,\n      retryableErrors: config.retryableErrors ?? [],\n      showRetryNotification: config.showRetryNotification ?? true,\n    };\n  }\n\n  /**\n   * 插件初始化\n   */\n  install(transfer: any, options?: any): void {\n    console.log(`✅ [${this.name}] 插件已安装`, this.config);\n  }\n\n  /**\n   * 传输失败时触发（上传/下载通用）\n   */\n  onError(\n    error: Error,\n    file: RetryableTransferFile,\n    context: PluginContext<RetryableTransferFile>,\n  ): void {\n    const fileId = file.fileId;\n    const currentRetries = this.retryCountMap.get(fileId) || 0;\n\n    // 检查是否超过最大重试次数\n    if (currentRetries >= this.config.maxRetries) {\n      console.warn(\n        `[${this.name}] 文件 ${file.fileName} 已达到最大重试次数 (${this.config.maxRetries})，停止重试`\n      );\n      this.cleanup(fileId);\n      return;\n    }\n\n    // 检查是否为可重试的错误\n    if (!this.isRetryableError(error)) {\n      console.log(\n        `[${this.name}] 文件 ${file.fileName} 的错误不可重试，跳过重试`\n      );\n      return;\n    }\n\n    // 计算延迟时间\n    const delay = this.calculateDelay(currentRetries);\n\n    // 设置重试定时器\n    const timer = setTimeout(() => {\n      console.log(\n        `[${this.name}] 文件 ${file.fileName} 第 ${currentRetries + 1}/${this.config.maxRetries} 次重试（延迟 ${delay}ms）`\n      );\n\n      // 更新重试计数\n      this.retryCountMap.set(fileId, currentRetries + 1);\n\n      // 触发重试（TransferFile 基类提供 retry() 方法）\n      file.retry();\n\n      // 清除定时器引用\n      this.retryTimerMap.delete(fileId);\n    }, delay);\n\n    this.retryTimerMap.set(fileId, timer);\n\n    // 显示重试通知\n    if (this.config.showRetryNotification) {\n      console.info(\n        `[${this.name}] ⏳ 文件 ${file.fileName} 将在 ${delay}ms 后自动重试...`\n      );\n    }\n  }\n\n  /**\n   * 传输成功时清理重试状态\n   */\n  onSuccess(\n    response: any,\n    file: RetryableTransferFile,\n    context: PluginContext<RetryableTransferFile>,\n  ): void {\n    this.cleanup(file.fileId);\n  }\n\n  /**\n   * 文件移除时清理重试状态\n   */\n  destroy(): void {\n    // 清除所有待执行的重试定时器\n    this.retryTimerMap.forEach((timer) => clearTimeout(timer));\n    this.retryTimerMap.clear();\n    this.retryCountMap.clear();\n    console.log(`🗑️ [${this.name}] 插件已销毁`);\n  }\n\n  /**\n   * 判断错误是否可重试\n   */\n  private isRetryableError(error: any): boolean {\n    // 如果没有配置可重试错误列表，则对所有错误重试\n    if (this.config.retryableErrors.length === 0) {\n      return true;\n    }\n\n    // 检查错误码是否在可重试列表中\n    const errorCode = error.code || error.message || \"\";\n    return this.config.retryableErrors.some((code) =>\n      errorCode.includes(code)\n    );\n  }\n\n  /**\n   * 计算延迟时间\n   */\n  private calculateDelay(retryCount: number): number {\n    const { strategy, initialDelay, maxDelay } = this.config;\n\n    let delay: number;\n\n    switch (strategy) {\n      case \"fixed\":\n        // 固定延迟\n        delay = initialDelay;\n        break;\n\n      case \"linear\":\n        // 线性增长：delay = initialDelay * (retryCount + 1)\n        delay = initialDelay * (retryCount + 1);\n        break;\n\n      case \"exponential\":\n      default:\n        // 指数退避：delay = initialDelay * 2^retryCount\n        delay = initialDelay * Math.pow(2, retryCount);\n        break;\n    }\n\n    // 限制最大延迟时间\n    return Math.min(delay, maxDelay);\n  }\n\n  /**\n   * 清理文件的重试状态\n   */\n  private cleanup(fileId: string): void {\n    // 清除待执行的定时器\n    const timer = this.retryTimerMap.get(fileId);\n    if (timer) {\n      clearTimeout(timer);\n      this.retryTimerMap.delete(fileId);\n    }\n\n    // 清除重试计数\n    this.retryCountMap.delete(fileId);\n  }\n}\n"]}

package/dist/index-CVuMEvjg.d.ts

@@ -0,0 +1,201 @@
+import { IUDPlugin, UploadFile, FileUDError, PluginContext, UploaderConfig, Uploader } from '@file-ud.js/core';
+
+/**
+ * 插件基类
+ * 提供通用的错误处理和日志功能
+ */
+declare abstract class BasePlugin implements IUDPlugin<UploadFile> {
+    /** 插件名称 */
+    abstract name: string;
+    /** 插件版本 */
+    version: string;
+    /** 插件优先级 */
+    priority: number;
+    /** 是否关键插件 */
+    critical: boolean;
+    /** 插件描述 */
+    desc: string;
+    /**
+     * 安装插件 - 统一日志输出
+     */
+    install(transfer: any): void;
+    /**
+     * 创建基础错误对象
+     * @param file - 当前文件
+     * @param uploader - 上传器实例
+     * @returns 基础错误对象
+     */
+    protected createBaseError(file: UploadFile, uploader: any): FileUDError;
+    /**
+     * 抛出验证错误
+     * @param error - 错误对象
+     * @returns Promise.reject
+     */
+    protected throwError(error: FileUDError): Promise<never>;
+    /**
+     * 文件选择时的验证逻辑（由子类实现）
+     */
+    abstract onFileSelect(file: UploadFile, context: PluginContext<UploadFile>): Promise<UploadFile | void>;
+    /**
+     * 销毁插件
+     */
+    destroy?(): void;
+}
+
+interface ImageCompressPluginOptions {
+    /** 压缩质量 (0-1) */
+    quality?: number;
+    /** 最大宽度 (px) */
+    maxWidth?: number;
+    /** 最大高度 (px) */
+    maxHeight?: number;
+    /** 输出格式 */
+    format?: "jpeg" | "png" | "webp";
+    /** 是否显示压缩信息 */
+    showInfo?: boolean;
+    /** 压缩开始时触发 */
+    onCompressStart?: (file: UploadFile) => void;
+    /** 压缩完成时触发 */
+    onCompressComplete?: (file: UploadFile, compressedFile: File) => void;
+}
+declare class CompressImagePlugin extends BasePlugin {
+    name: string;
+    priority: number;
+    desc: string;
+    options: Required<ImageCompressPluginOptions>;
+    private defaultOptions;
+    constructor(options?: ImageCompressPluginOptions);
+    onFileSelect(uploadFile: UploadFile, context: PluginContext<UploadFile>): Promise<UploadFile | void>;
+    private compressImage;
+}
+
+interface WatermarkPluginOptions {
+    /** 水印文字 */
+    text?: string;
+    /** 水印图片URL */
+    imageUrl?: string;
+    /** 位置 */
+    position?: "top-left" | "top-right" | "bottom-left" | "bottom-right" | "center";
+    /** 透明度 (0-1) */
+    opacity?: number;
+    /** 字体大小 */
+    fontSize?: number;
+    /** 字体颜色 */
+    color?: string;
+    /** 边距 */
+    padding?: number;
+    /** 水印图片宽度（可选） */
+    imageWidth?: number;
+    /** 水印图片高度（可选） */
+    imageHeight?: number;
+}
+declare class WatermarkPlugin extends BasePlugin {
+    name: string;
+    priority: number;
+    desc: string;
+    options: Required<WatermarkPluginOptions>;
+    private defaultOptions;
+    constructor(options?: Partial<WatermarkPluginOptions>);
+    onFileSelect(file: UploadFile, context: PluginContext<UploadFile>): Promise<UploadFile | void>;
+    private addWatermark;
+    /**
+     * 添加文字水印
+     */
+    private addTextWatermark;
+    /**
+     * 添加图片水印
+     */
+    private addImageWatermark;
+    /**
+     * 计算水印位置
+     */
+    private calculatePosition;
+}
+
+interface FileValidatorPluginOptions {
+    /** 最大文件大小 (字节) */
+    maxSize?: number;
+    /** 最小文件大小 (字节) */
+    minSize?: number;
+    /** 允许的文件类型 (MIME类型或扩展名) */
+    accept?: UploaderConfig["accept"];
+    /** 是否允许空文件 */
+    allowEmpty?: boolean;
+    /** 自定义验证函数 */
+    customValidate?: (file: File, error: typeof FileUDError) => boolean | Promise<boolean>;
+    /** 错误消息定制 */
+    messages?: {
+        maxSize?: (max: number, current: number) => string;
+        minSize?: (min: number, current: number) => string;
+        accept?: (accept: string[], fileName: string) => string;
+        empty?: () => string;
+        custom?: (fileName: string) => string;
+    };
+}
+declare class FileValidatorPlugin extends BasePlugin {
+    name: string;
+    priority: number;
+    critical: boolean;
+    desc: string;
+    private options;
+    private defaultOptions;
+    constructor(options?: FileValidatorPluginOptions);
+    created(uploader: Uploader): Promise<void>;
+    onFileSelect(file: UploadFile, context: PluginContext<UploadFile>): Promise<UploadFile<any>>;
+}
+
+interface ImageValidatorOptions {
+    exactWidth?: number;
+    minWidth?: number;
+    maxWidth?: number;
+    exactHeight?: number;
+    minHeight?: number;
+    maxHeight?: number;
+    square?: boolean;
+    minAspectRatio?: number;
+    maxAspectRatio?: number;
+    aspectRatios?: number[];
+    minResolution?: number;
+    maxResolution?: number;
+    allowAnimated?: boolean;
+}
+declare class ImageValidatorPlugin extends BasePlugin {
+    private options;
+    name: string;
+    priority: number;
+    desc: string;
+    constructor(options?: ImageValidatorOptions);
+    onFileSelect(file: UploadFile, context: PluginContext<UploadFile>): Promise<UploadFile | void>;
+    /**
+     * 获取图片尺寸
+     */
+    private getImageDimensions;
+    /**
+     * 检查 GIF 是否为动态图片
+     */
+    private isAnimatedGif;
+}
+
+interface VideoValidatorOptions {
+    minDuration?: number;
+    maxDuration?: number;
+    minWidth?: number;
+    minHeight?: number;
+    minBitrate?: number;
+    maxBitrate?: number;
+    allowedCodecs?: string[];
+}
+declare class VideoValidatorPlugin extends BasePlugin {
+    private options;
+    name: string;
+    version: string;
+    priority: number;
+    constructor(options?: VideoValidatorOptions);
+    onFileSelect(file: UploadFile, context: PluginContext<UploadFile>): Promise<UploadFile | void>;
+    /**
+     * 获取视频元数据
+     */
+    private getVideoMetadata;
+}
+
+export { BasePlugin as B, CompressImagePlugin as C, FileValidatorPlugin as F, type ImageCompressPluginOptions as I, type VideoValidatorOptions as V, WatermarkPlugin as W, type FileValidatorPluginOptions as a, type ImageValidatorOptions as b, ImageValidatorPlugin as c, VideoValidatorPlugin as d, type WatermarkPluginOptions as e };

package/dist/index.d.mts

@@ -0,0 +1,3 @@
+export { B as BasePlugin, C as CompressImagePlugin, F as FileValidatorPlugin, a as FileValidatorPluginOptions, I as ImageCompressPluginOptions, b as ImageValidatorOptions, c as ImageValidatorPlugin, V as VideoValidatorOptions, d as VideoValidatorPlugin, W as WatermarkPlugin, e as WatermarkPluginOptions } from './index-CVuMEvjg.js';
+export { SmartRetryConfig, SmartRetryPlugin } from './retry/index.mjs';
+import '@file-ud.js/core';

package/dist/index.d.ts

@@ -0,0 +1,3 @@
+export { B as BasePlugin, C as CompressImagePlugin, F as FileValidatorPlugin, a as FileValidatorPluginOptions, I as ImageCompressPluginOptions, b as ImageValidatorOptions, c as ImageValidatorPlugin, V as VideoValidatorOptions, d as VideoValidatorPlugin, W as WatermarkPlugin, e as WatermarkPluginOptions } from './index-CVuMEvjg.js';
+export { SmartRetryConfig, SmartRetryPlugin } from './retry/index.js';
+import '@file-ud.js/core';