@plyaz/types 1.15.20 → 1.16.1

package/dist/storage/plugins.d.ts

@@ -0,0 +1,1056 @@
+/**
+ * Storage Plugin System Types
+ * @module @plyaz/types/storage/plugins
+ *
+ * Defines the plugin system for extending storage functionality with lifecycle hooks.
+ * Plugins are separate from webhooks - they run synchronously during file operations.
+ */
+import type { FileMetadata, UploadParams, UploadResult, DownloadParams, DownloadResult, DeleteParams, FileDeleteResult, PresignedUrlOptions, PresignedUrlResult, AdapterHealthCheck, StorageListFilesParams, StorageListFilesResult, StorageCopyFileParams, StorageMoveFileParams, StorageReplaceFileParams } from './interfaces';
+import type { STORAGE_PLUGIN_TYPE } from './enums';
+/**
+ * Known plugin names for type safety
+ * Use this for skipPlugins/onlyPlugins parameters
+ */
+export type StorageKnownPluginName = 'virus-scanner' | 'sharp-image-processor' | 'ffmpeg-video-processor' | 'metadata-extractor' | 'cdn-invalidator' | 'file-size-validator' | 'metadata-enricher' | 'upload-notifier' | 'delete-auditor' | 'access-logger' | string;
+/**
+ * Plugin execution options for filtering which plugins to run
+ * Used to control plugin execution per operation
+ */
+export interface StoragePluginExecutionOptions {
+    /** Skip specific plugins by name for this operation */
+    skipPlugins?: readonly StorageKnownPluginName[];
+    /** Only run these specific plugins for this operation */
+    onlyPlugins?: readonly StorageKnownPluginName[];
+}
+/**
+ * Base plugin configuration
+ */
+export interface BasePluginConfig {
+    /** Plugin name */
+    name: StorageKnownPluginName;
+    /** Plugin type */
+    type: STORAGE_PLUGIN_TYPE;
+    /** Plugin priority (1-100, lower runs first) */
+    priority?: number;
+    /** Plugin version */
+    version?: string;
+    /** Plugin description */
+    description?: string;
+    /** Whether the plugin is enabled */
+    enabled?: boolean;
+    /** Logger instance */
+    logger?: unknown;
+    /** API client configuration (for REST API-based plugins) */
+    apiClientConfig?: {
+        baseURL: string;
+        headers?: Record<string, string>;
+        timeout?: number;
+        [key: string]: unknown;
+    };
+}
+/**
+ * Plugin Registry Configuration
+ */
+export interface PluginRegistryConfig {
+    /** Logger instance */
+    logger?: unknown;
+    /** Whether to continue execution if a plugin fails */
+    continueOnError?: boolean;
+    /** Maximum execution time for all plugins (milliseconds) */
+    maxExecutionTime?: number;
+}
+/**
+ * Storage Adapter Interface for Plugins
+ * Provides access to all public storage operations
+ * BaseStorageAdapter implements this interface
+ *
+ * Note: This interface uses structural typing to match BaseStorageAdapter
+ * without creating circular dependencies between packages
+ */
+export interface PluginStorageAdapterInterface {
+    /** Adapter name */
+    readonly name: string;
+    /** Adapter type */
+    readonly type: string;
+    /** Adapter priority */
+    readonly priority: number;
+    /** Whether adapter is enabled */
+    readonly enabled: boolean;
+    /** Upload a file to storage - uses UploadParams signature */
+    upload: (params: UploadParams) => Promise<UploadResult>;
+    /** Download a file from storage - uses DownloadParams signature */
+    download: (params: DownloadParams) => Promise<DownloadResult>;
+    /** Delete a file from storage - uses DeleteParams signature */
+    delete: (params: DeleteParams) => Promise<FileDeleteResult>;
+    /** Generate a presigned/signed URL for file access */
+    getSignedUrl: (options: PresignedUrlOptions) => Promise<PresignedUrlResult>;
+    /** Check if adapter is available */
+    isAvailable: () => boolean;
+    /** Perform health check on adapter */
+    healthCheck: () => Promise<AdapterHealthCheck>;
+    /** Get file metadata */
+    getFileMetadata: (fileId: string, bucket?: string) => Promise<FileMetadata>;
+    /** Restore a soft-deleted file */
+    restoreFile?: (fileId: string) => Promise<FileMetadata>;
+    /** List files with optional filters */
+    listFiles?: (params: StorageListFilesParams) => Promise<StorageListFilesResult>;
+    /** Copy a file */
+    copyFile?: (params: StorageCopyFileParams) => Promise<FileMetadata>;
+    /** Move a file */
+    moveFile?: (params: StorageMoveFileParams) => Promise<FileMetadata>;
+    /** Replace a file */
+    replaceFile?: (params: StorageReplaceFileParams) => Promise<FileMetadata>;
+}
+/**
+ * Plugin lifecycle hook context
+ * Provides information about the current operation to plugins
+ */
+export interface StoragePluginContext {
+    /** Operation type (upload, delete, access, etc.) */
+    operation: 'upload' | 'delete' | 'access' | 'update';
+    /** Timestamp when operation started */
+    timestamp: Date;
+    /** User ID performing the operation (if available) */
+    userId?: string;
+    /** Request correlation ID for tracing */
+    correlationId?: string;
+    /** Storage adapter for file operations - provides access to all public storage methods */
+    storageAdapter: PluginStorageAdapterInterface;
+    /** Additional context metadata */
+    metadata?: Record<string, unknown>;
+}
+/**
+ * Result from beforeUpload hook
+ * Can modify metadata or reject the upload
+ */
+export interface BeforeUploadResult {
+    /** Whether to allow the upload */
+    allowed: boolean;
+    /** Reason if upload is rejected */
+    reason?: string;
+    /** Modified file (if plugin wants to return modified file) */
+    file?: StoragePluginFile;
+    /** Modified metadata (if plugin wants to add/modify) */
+    modifiedMetadata?: Partial<FileMetadata>;
+    /** Additional data to pass to afterUpload hooks */
+    pluginData?: Record<string, unknown>;
+}
+/**
+ * Result from beforeDelete hook
+ * Can prevent deletion
+ */
+export interface BeforeDeleteResult {
+    /** Whether to allow the deletion */
+    allowed: boolean;
+    /** Reason if deletion is rejected */
+    reason?: string;
+    /** Additional data to pass to afterDelete hooks */
+    pluginData?: Record<string, unknown>;
+}
+/**
+ * File buffer with metadata for plugin hooks
+ */
+export interface StoragePluginFile {
+    /** File buffer */
+    buffer: globalThis.Buffer;
+    /** File metadata */
+    metadata: FileMetadata;
+    /** Original filename */
+    filename: string;
+    /** MIME type */
+    mimeType: string;
+    /** File size in bytes */
+    size: number;
+    /** Custom metadata that plugins can add */
+    customMetadata?: Record<string, unknown>;
+}
+/**
+ * Upload result passed to afterUpload hooks
+ */
+export interface StoragePluginUploadResult {
+    /** Uploaded file ID */
+    fileId: string;
+    /** Public URL to access the file */
+    url: string;
+    /** CDN URL (if applicable) */
+    cdnUrl?: string;
+    /** File metadata */
+    metadata: FileMetadata;
+    /** Storage adapter that handled the upload */
+    adapter: string;
+    /** Upload duration in milliseconds */
+    duration: number;
+    /** Data passed from beforeUpload hooks */
+    pluginData?: Record<string, unknown>;
+}
+/**
+ * Delete result passed to afterDelete hooks
+ */
+export interface StoragePluginDeleteResult {
+    /** Deleted file ID */
+    fileId: string;
+    /** File metadata (before deletion) */
+    metadata: FileMetadata;
+    /** Whether it was a soft delete */
+    softDelete: boolean;
+    /** Deletion timestamp */
+    deletedAt: Date;
+    /** Data passed from beforeDelete hooks */
+    pluginData?: Record<string, unknown>;
+}
+/**
+ * Access event passed to onAccess hooks
+ */
+export interface StoragePluginAccessEvent {
+    /** Accessed file ID */
+    fileId: string;
+    /** User ID who accessed the file */
+    userId: string;
+    /** Access type (download, view, preview, etc.) */
+    accessType: 'download' | 'view' | 'preview' | 'stream' | 'other';
+    /** Access timestamp */
+    timestamp: Date;
+    /** File metadata */
+    metadata?: FileMetadata;
+    /** IP address of the accessor */
+    ipAddress?: string;
+    /** User agent */
+    userAgent?: string;
+}
+/**
+ * Plugin health status
+ */
+export interface StoragePluginHealth {
+    /** Plugin name */
+    plugin: StorageKnownPluginName;
+    /** Whether the plugin is healthy */
+    healthy: boolean;
+    /** Status message */
+    message?: string;
+    /** Last check timestamp */
+    lastCheck: Date;
+    /** Error details if unhealthy */
+    error?: {
+        code: string;
+        message: string;
+        stack?: string;
+    };
+}
+/**
+ * Base Storage Plugin Interface
+ * All plugins must implement this interface
+ *
+ * @example
+ * ```typescript
+ * class VirusScanPlugin implements StoragePlugin {
+ *   readonly name = 'virus-scan';
+ *   readonly type = STORAGE_PLUGIN_TYPE.SECURITY;
+ *   readonly priority = 10; // Run first
+ *
+ *   async beforeUpload(file: StoragePluginFile, context: StoragePluginContext): Promise<BeforeUploadResult> {
+ *     const scanResult = await this.scanFile(file.buffer);
+ *     if (scanResult.infected) {
+ *       return {
+ *         allowed: false,
+ *         reason: `Virus detected: ${scanResult.virusName}`,
+ *       };
+ *     }
+ *     return { allowed: true };
+ *   }
+ * }
+ * ```
+ */
+export interface StoragePlugin {
+    /** Unique plugin name (lowercase-with-dashes) */
+    readonly name: StorageKnownPluginName;
+    /** Plugin type for categorization */
+    readonly type: STORAGE_PLUGIN_TYPE;
+    /**
+     * Plugin priority (1-100)
+     * Lower numbers run first
+     * Security plugins typically use 1-20
+     * Metadata plugins typically use 21-40
+     * Other plugins typically use 41-100
+     */
+    readonly priority: number;
+    /** Plugin version */
+    readonly version?: string;
+    /** Plugin description */
+    readonly description?: string;
+    /** Whether the plugin is enabled */
+    enabled?: boolean;
+    /**
+     * Initialize the plugin
+     * Called once when plugin is registered
+     * Use this to setup connections, validate configuration, etc.
+     */
+    initialize?(): Promise<void>;
+    /**
+     * Cleanup the plugin
+     * Called when plugin is destroyed
+     * Use this to close connections, release resources, etc.
+     */
+    destroy?(): Promise<void>;
+    /**
+     * Check plugin health
+     * Used for monitoring and diagnostics
+     */
+    healthCheck?(): Promise<StoragePluginHealth>;
+    /**
+     * PRE-UPLOAD HOOK (BLOCKING)
+     * Called BEFORE file is uploaded to storage
+     * Can reject upload by returning { allowed: false }
+     * Can modify metadata by returning { modifiedMetadata: {...} }
+     *
+     * @param file - File to be uploaded with metadata
+     * @param context - Operation context
+     * @returns Result indicating whether to allow upload and any modifications
+     */
+    beforeUpload?(file: StoragePluginFile, context: StoragePluginContext): Promise<BeforeUploadResult>;
+    /**
+     * POST-UPLOAD HOOK (ASYNC)
+     * Called AFTER file is successfully uploaded to storage
+     * Runs asynchronously, doesn't block the upload response
+     * Use for metadata extraction, CDN invalidation, audit logging, etc.
+     *
+     * @param result - Upload result with file ID and metadata
+     * @param context - Operation context
+     */
+    afterUpload?(result: StoragePluginUploadResult, context: StoragePluginContext): Promise<void>;
+    /**
+     * PRE-DELETE HOOK (BLOCKING)
+     * Called BEFORE file is deleted from storage
+     * Can prevent deletion by returning { allowed: false }
+     *
+     * @param fileId - File ID to be deleted
+     * @param metadata - File metadata (if available)
+     * @param context - Operation context
+     * @returns Result indicating whether to allow deletion
+     */
+    beforeDelete?(fileId: string, metadata: FileMetadata | undefined, context: StoragePluginContext): Promise<BeforeDeleteResult>;
+    /**
+     * POST-DELETE HOOK (ASYNC)
+     * Called AFTER file is deleted from storage
+     * Runs asynchronously, doesn't block the delete response
+     * Use for CDN cache purging, audit logging, cleanup, etc.
+     *
+     * @param result - Delete result with file ID and metadata
+     * @param context - Operation context
+     */
+    afterDelete?(result: StoragePluginDeleteResult, context: StoragePluginContext): Promise<void>;
+    /**
+     * ON-ACCESS HOOK (ASYNC)
+     * Called when a file is accessed (downloaded, viewed, etc.)
+     * Runs asynchronously, doesn't block the access
+     * Use for access logging, analytics, compliance tracking, etc.
+     *
+     * @param event - Access event details
+     * @param context - Operation context
+     */
+    onAccess?(event: StoragePluginAccessEvent, context: StoragePluginContext): Promise<void>;
+}
+/**
+ * Plugin configuration
+ * Used to configure a plugin instance
+ */
+export interface StoragePluginConfig {
+    /** Plugin instance */
+    plugin: StoragePlugin;
+    /** Whether the plugin is enabled */
+    enabled?: boolean;
+    /** Override priority */
+    priority?: number;
+    /** Additional configuration */
+    config?: Record<string, unknown>;
+}
+/**
+ * Plugin execution result
+ * Returned by plugin registry after executing hooks
+ */
+export interface StoragePluginExecutionResult {
+    /** Whether all plugins allowed the operation */
+    allowed: boolean;
+    /** Reason if operation was rejected */
+    reason?: string;
+    /** Plugin that rejected the operation */
+    rejectedBy?: string;
+    /** Modified metadata from plugins */
+    modifiedMetadata?: Partial<FileMetadata>;
+    /** Plugin data to pass to subsequent hooks */
+    pluginData?: Record<string, unknown>;
+    /** Execution duration in milliseconds */
+    duration: number;
+    /** Number of plugins executed */
+    pluginsExecuted: number;
+    /** Errors from plugins (non-fatal) */
+    errors?: Array<{
+        plugin: string;
+        error: Error;
+    }>;
+}
+/**
+ * Virus scan result
+ */
+export interface VirusScanResult {
+    /** Whether the file is clean (no threats detected) */
+    clean: boolean;
+    /** Whether the file is infected with malware */
+    infected: boolean;
+    /** Name of the virus/malware detected (if any) */
+    virusName?: string;
+    /** Scan duration in milliseconds */
+    scanTime: number;
+    /** Timestamp when scan was performed */
+    scanDate: Date;
+    /** Scan confidence score (0-100) */
+    confidence?: number;
+    /** Additional scan metadata from the provider */
+    metadata?: Record<string, unknown>;
+    /** Provider-specific scan ID for tracking */
+    scanId?: string;
+    /** Detailed threat information */
+    threats?: VirusThreat[];
+}
+/**
+ * Detailed threat information
+ */
+export interface VirusThreat {
+    /** Threat name/signature */
+    name: string;
+    /** Threat type (virus, trojan, ransomware, etc.) */
+    type?: string;
+    /** Threat severity (low, medium, high, critical) */
+    severity?: 'low' | 'medium' | 'high' | 'critical';
+    /** Detection engine that found this threat */
+    engine?: string;
+}
+/**
+ * Base virus scan provider configuration
+ * Common configuration for all virus scanning providers
+ */
+export interface VirusScanProviderConfig {
+    /** API key or authentication token */
+    apiKey?: string;
+    /** Provider API endpoint (baseURL) */
+    endpoint?: string;
+    /** Request timeout in milliseconds */
+    timeout?: number;
+    /** Maximum file size to scan (in bytes) */
+    maxFileSize?: number;
+    /** Enable verbose logging */
+    verbose?: boolean;
+    /** Additional provider-specific options */
+    options?: Record<string, unknown>;
+}
+/**
+ * Base virus scan provider interface
+ * All virus scan providers must implement this interface
+ */
+export interface VirusScanProvider {
+    /** Provider name */
+    readonly providerName: string;
+    /**
+     * Scan a file for viruses/malware
+     * @param file - File buffer to scan
+     * @param filename - Original filename (for context)
+     * @returns Scan result with threat information
+     */
+    scan(file: globalThis.Buffer, filename: string): Promise<VirusScanResult>;
+    /**
+     * Check if provider is available and healthy
+     * @returns True if provider can accept scan requests
+     */
+    isAvailable(): Promise<boolean>;
+    /**
+     * Get provider statistics (optional)
+     * @returns Provider usage statistics
+     */
+    getStatistics?(): Promise<{
+        scansPerformed: number;
+        threatsDetected: number;
+        averageScanTime: number;
+    }>;
+}
+/**
+ * Virus scan plugin configuration
+ */
+export interface VirusScanPluginConfig extends Omit<BasePluginConfig, 'name' | 'type'> {
+    /** Virus scan provider instance */
+    provider: VirusScanProvider;
+    /** API key for the provider (for REST-based providers like VirusTotal) */
+    apiKey?: string;
+    /** Provider API endpoint (for REST-based providers) */
+    apiEndpoint?: string;
+    /** Reject upload if scan fails (default: true) */
+    rejectOnError?: boolean;
+    /** Skip scan for files above this size (bytes, default: no limit) */
+    skipAboveSize?: number;
+    /** File extensions to skip scanning (e.g., ['.txt', '.md']) */
+    skipExtensions?: string[];
+}
+/**
+ * VirusTotal provider configuration
+ * @see VirusTotalProvider in @plyaz/storage/plugins
+ * Note: API key and endpoint are configured at the plugin level
+ */
+export interface VirusTotalProviderConfig extends VirusScanProviderConfig {
+    /** Wait for scan to complete (default: true) */
+    waitForResult?: boolean;
+    /** Maximum wait time for scan results in milliseconds (default: 60000) */
+    maxWaitTime?: number;
+    /** Poll interval for checking scan status in milliseconds (default: 5000) */
+    pollInterval?: number;
+}
+/**
+ * ClamAV provider configuration for virus scanning
+ * @see ClamAVProvider in @plyaz/storage/plugins
+ */
+export interface ClamAVProviderConfig extends VirusScanProviderConfig {
+    /** ClamAV daemon host (default: 'localhost') */
+    host?: string;
+    /** ClamAV daemon port (default: 3310) */
+    port?: number;
+    /** Socket path for Unix domain socket (alternative to host/port) */
+    socketPath?: string;
+    /** Enable quarantine for infected files (default: false) */
+    enableQuarantine?: boolean;
+    /** Quarantine directory path (default: './quarantine') */
+    quarantinePath?: string;
+    /** Enable streaming scan mode (default: true for better performance) */
+    streamScan?: boolean;
+}
+/**
+ * Image variant configuration for Sharp image processing
+ * @see SharpImagePlugin in @plyaz/storage/plugins
+ */
+export interface ImageVariant {
+    /** Variant name (thumbnail, medium, large, etc.) */
+    name: string;
+    /** Target width in pixels */
+    width?: number;
+    /** Target height in pixels */
+    height?: number;
+    /** Resize fit mode */
+    fit?: 'cover' | 'contain' | 'fill' | 'inside' | 'outside';
+    /** Resize position (when fit is 'cover' or 'contain') */
+    position?: 'center' | 'top' | 'right top' | 'right' | 'right bottom' | 'bottom' | 'left bottom' | 'left' | 'left top';
+    /** Custom quality for this variant (overrides global quality) */
+    quality?: number;
+    /** Custom format for this variant */
+    format?: 'jpeg' | 'png' | 'webp' | 'avif';
+}
+/**
+ * Watermark configuration for Sharp image processing
+ * @see SharpImagePlugin in @plyaz/storage/plugins
+ */
+export interface WatermarkConfig {
+    /** Enable watermarking */
+    enabled: boolean;
+    /** Path to watermark image file */
+    imagePath?: string;
+    /** Watermark image buffer (alternative to imagePath) */
+    imageBuffer?: globalThis.Buffer;
+    /** Watermark opacity (0-1) */
+    opacity?: number;
+    /** Watermark position */
+    position?: 'top-left' | 'top-right' | 'bottom-left' | 'bottom-right' | 'center';
+    /** Watermark size as percentage of image (default: 20%) */
+    size?: number;
+}
+/**
+ * Sharp Image Plugin configuration
+ * @see SharpImagePlugin in @plyaz/storage/plugins
+ */
+export interface SharpImagePluginConfig {
+    /** Image variants to generate */
+    variants?: ImageVariant[];
+    /** Output formats to generate (default: ['webp', 'jpeg']) */
+    formats?: Array<'jpeg' | 'png' | 'webp' | 'avif'>;
+    /** JPEG/WEBP quality (1-100, default: 85) */
+    quality?: number;
+    /** Strip metadata (EXIF) for privacy (default: true) */
+    stripMetadata?: boolean;
+    /** Watermark configuration */
+    watermark?: WatermarkConfig;
+    /** Only process these MIME types (default: all image/* types) */
+    supportedMimeTypes?: string[];
+    /** Upload variants back to storage (default: true) */
+    uploadVariants?: boolean;
+    /** Preserve original file (default: true) */
+    preserveOriginal?: boolean;
+    /** Plugin priority (1-100, lower runs first) */
+    priority?: number;
+    /** Plugin version */
+    version?: string;
+    /** Plugin description */
+    description?: string;
+    /** Whether the plugin is enabled */
+    enabled?: boolean;
+    /** Logger instance */
+    logger?: unknown;
+}
+/**
+ * Video resolution configuration for FFmpeg video processing
+ * @see FFmpegVideoPlugin in @plyaz/storage/plugins
+ */
+export interface VideoResolution {
+    /** Resolution name (480p, 720p, 1080p, 4k) */
+    name: string;
+    /** Target width in pixels */
+    width: number;
+    /** Target height in pixels */
+    height: number;
+    /** Video bitrate (e.g., '1000k', '2500k') */
+    bitrate: string;
+    /** Video codec (e.g., 'libx264', 'libx265') */
+    codec?: string;
+    /** Audio codec (e.g., 'aac', 'mp3') */
+    audioCodec?: string;
+    /** Audio bitrate (e.g., '128k') */
+    audioBitrate?: string;
+}
+/**
+ * Thumbnail generation configuration for FFmpeg video processing
+ * @see FFmpegVideoPlugin in @plyaz/storage/plugins
+ */
+export interface ThumbnailConfig {
+    /** Number of thumbnails to generate */
+    count: number;
+    /** Timestamps as percentage of duration (0-1) */
+    timestamps: number[];
+    /** Thumbnail format (jpeg, png) */
+    format?: 'jpeg' | 'png';
+    /** Thumbnail quality (1-100) */
+    quality?: number;
+    /** Thumbnail width (height auto-calculated) */
+    width?: number;
+    /** Thumbnail size (width x height) */
+    size?: {
+        width: number;
+        height: number;
+    };
+}
+/**
+ * HLS streaming configuration for FFmpeg video processing
+ * @see FFmpegVideoPlugin in @plyaz/storage/plugins
+ */
+export interface HLSConfig {
+    /** Enable HLS streaming */
+    enabled: boolean;
+    /** Segment duration in seconds */
+    segmentDuration?: number;
+    /** Variant bitrates for adaptive streaming */
+    variantBitrates?: string[];
+}
+/**
+ * FFmpeg Video Plugin configuration
+ * @see FFmpegVideoPlugin in @plyaz/storage/plugins
+ */
+export interface FFmpegVideoPluginConfig {
+    /** Path to ffmpeg binary */
+    ffmpegPath?: string;
+    /** Path to ffprobe binary */
+    ffprobePath?: string;
+    /** Video resolutions to generate */
+    resolutions?: VideoResolution[];
+    /** Thumbnail configuration */
+    thumbnails?: ThumbnailConfig;
+    /** HLS streaming configuration */
+    hls?: HLSConfig;
+    /** Process in background queue */
+    useQueue?: boolean;
+    /** Only process these MIME types */
+    supportedMimeTypes?: string[];
+    /** Upload variants back to storage */
+    uploadVariants?: boolean;
+    /** Plugin priority (1-100, lower runs first) */
+    priority?: number;
+    /** Plugin version */
+    version?: string;
+    /** Plugin description */
+    description?: string;
+    /** Whether the plugin is enabled */
+    enabled?: boolean;
+    /** Logger instance */
+    logger?: unknown;
+}
+/**
+ * Extracted metadata structure
+ */
+export interface ExtractedMetadata {
+    /** File type category */
+    category: 'image' | 'audio' | 'video' | 'document' | 'other';
+    /** Image EXIF data */
+    exif?: {
+        make?: string;
+        model?: string;
+        software?: string;
+        dateTime?: string;
+        exposureTime?: number;
+        fNumber?: number;
+        iso?: number;
+        focalLength?: number;
+        flash?: number;
+        whiteBalance?: number;
+        orientation?: number;
+        xResolution?: number;
+        yResolution?: number;
+        resolutionUnit?: number;
+        gps?: {
+            latitude?: number;
+            longitude?: number;
+            altitude?: number;
+        };
+    };
+    /** Audio ID3 tags */
+    id3?: {
+        title?: string;
+        artist?: string;
+        album?: string;
+        year?: number;
+        genre?: string;
+        trackNumber?: number;
+        albumArtist?: string;
+        composer?: string;
+        duration?: number;
+        bitrate?: number;
+        sampleRate?: number;
+        codec?: string;
+    };
+    /** Video metadata */
+    video?: {
+        duration?: number;
+        width?: number;
+        height?: number;
+        codec?: string;
+        bitrate?: number;
+        fps?: number;
+        audioCodec?: string;
+        format?: string;
+    };
+    /** Document metadata */
+    document?: {
+        title?: string;
+        author?: string;
+        subject?: string;
+        creator?: string;
+        producer?: string;
+        creationDate?: string;
+        modificationDate?: string;
+        pageCount?: number;
+    };
+}
+/**
+ * Metadata Extraction Plugin configuration
+ */
+export interface MetadataExtractionPluginConfig {
+    /** Extract EXIF data from images */
+    extractExif?: boolean;
+    /** Extract ID3 tags from audio files */
+    extractId3?: boolean;
+    /** Extract metadata from videos */
+    extractVideoMeta?: boolean;
+    /** Extract metadata from documents */
+    extractDocMeta?: boolean;
+    /** Strip sensitive data (GPS, serial numbers) */
+    stripSensitiveData?: boolean;
+    /** Preserve original metadata in files */
+    preserveOriginal?: boolean;
+    /** Supported file mime types */
+    supportedMimeTypes?: string[];
+    priority?: number;
+    version?: string;
+    description?: string;
+    enabled?: boolean;
+    logger?: unknown;
+}
+/**
+ * CDN Provider Types
+ */
+export type CDNProviderType = 'cloudflare' | 'cloudfront' | 'fastly';
+/**
+ * Base CDN Provider Configuration
+ */
+export interface BaseCDNProviderConfig {
+    /** CDN provider type */
+    type: CDNProviderType;
+    /** Base URL pattern for generating cache URLs */
+    baseUrl?: string;
+}
+/**
+ * Cloudflare CDN Configuration
+ */
+export interface CloudflareCDNConfig extends BaseCDNProviderConfig {
+    type: 'cloudflare';
+    /** Cloudflare Zone ID */
+    zoneId: string;
+    /** Cloudflare API Token */
+    apiToken: string;
+}
+/**
+ * AWS CloudFront Configuration
+ */
+export interface CloudFrontCDNConfig extends BaseCDNProviderConfig {
+    type: 'cloudfront';
+    /** CloudFront Distribution ID */
+    distributionId: string;
+    /** AWS Access Key ID */
+    accessKeyId: string;
+    /** AWS Secret Access Key */
+    secretAccessKey: string;
+    /** AWS Region */
+    region?: string;
+}
+/**
+ * Fastly CDN Configuration
+ */
+export interface FastlyCDNConfig extends BaseCDNProviderConfig {
+    type: 'fastly';
+    /** Fastly Service ID */
+    serviceId: string;
+    /** Fastly API Key */
+    apiKey: string;
+}
+/**
+ * CDN Provider Configuration Union
+ */
+export type CDNProviderConfig = CloudflareCDNConfig | CloudFrontCDNConfig | FastlyCDNConfig;
+/**
+ * CDN Invalidation Plugin Configuration
+ */
+export interface CDNInvalidationPluginConfig {
+    /** CDN provider configurations */
+    providers: CDNProviderConfig[];
+    /** Maximum URLs per invalidation request */
+    batchSize?: number;
+    /** Number of retry attempts on failure */
+    retryAttempts?: number;
+    /** Retry delay in milliseconds */
+    retryDelay?: number;
+    /** Enable invalidation on delete */
+    invalidateOnDelete?: boolean;
+    /** Enable invalidation on update */
+    invalidateOnUpdate?: boolean;
+    /** URL pattern generator function */
+    urlGenerator?: (fileId: string, filename: string) => string[];
+    priority?: number;
+    version?: string;
+    description?: string;
+    enabled?: boolean;
+    logger?: unknown;
+}
+/**
+ * Cloudflare CDN Plugin Configuration
+ */
+export interface CloudflareCDNPluginConfig {
+    /** Cloudflare Zone ID */
+    zoneId: string;
+    /** Cloudflare API Token with Cache Purge permission */
+    apiToken: string;
+    /** Base URL for CDN (optional) */
+    baseUrl?: string;
+    /** Maximum URLs per purge request (default: 30) */
+    batchSize?: number;
+    /** Number of retry attempts on failure (default: 3) */
+    retryAttempts?: number;
+    /** Retry delay in milliseconds (default: 1000) */
+    retryDelay?: number;
+    /** Enable invalidation on delete (default: true) */
+    invalidateOnDelete?: boolean;
+    /** Enable invalidation on update (default: true) */
+    invalidateOnUpdate?: boolean;
+    /** URL generator function */
+    urlGenerator?: (fileId: string, filename: string) => string[];
+    priority?: number;
+    version?: string;
+    description?: string;
+    enabled?: boolean;
+    logger?: unknown;
+}
+/**
+ * CloudFront CDN Plugin Configuration
+ */
+export interface CloudFrontCDNPluginConfig {
+    /** CloudFront Distribution ID */
+    distributionId: string;
+    /** AWS Access Key ID */
+    accessKeyId: string;
+    /** AWS Secret Access Key */
+    secretAccessKey: string;
+    /** AWS Region (default: us-east-1) */
+    region?: string;
+    /** Base URL for CDN (optional) */
+    baseUrl?: string;
+    /** Maximum paths per invalidation (default: 1000) */
+    batchSize?: number;
+    /** Number of retry attempts on failure (default: 3) */
+    retryAttempts?: number;
+    /** Retry delay in milliseconds (default: 1000) */
+    retryDelay?: number;
+    /** Enable invalidation on delete (default: true) */
+    invalidateOnDelete?: boolean;
+    /** Enable invalidation on update (default: true) */
+    invalidateOnUpdate?: boolean;
+    /** Path generator function */
+    pathGenerator?: (fileId: string, filename: string) => string[];
+    priority?: number;
+    version?: string;
+    description?: string;
+    enabled?: boolean;
+    logger?: unknown;
+}
+/**
+ * Fastly CDN Plugin Configuration
+ */
+export interface FastlyCDNPluginConfig {
+    /** Fastly Service ID */
+    serviceId: string;
+    /** Fastly API Token with Purge permission */
+    apiToken: string;
+    /** Base URL for CDN (optional) */
+    baseUrl?: string;
+    /** Number of retry attempts on failure (default: 3) */
+    retryAttempts?: number;
+    /** Retry delay in milliseconds (default: 1000) */
+    retryDelay?: number;
+    /** Enable invalidation on delete (default: true) */
+    invalidateOnDelete?: boolean;
+    /** Enable invalidation on update (default: true) */
+    invalidateOnUpdate?: boolean;
+    /** URL generator function */
+    urlGenerator?: (fileId: string, filename: string) => string[];
+    priority?: number;
+    version?: string;
+    description?: string;
+    enabled?: boolean;
+    logger?: unknown;
+}
+/**
+ * CDN Invalidation Result
+ */
+export interface CDNInvalidationResult {
+    /** CDN provider type */
+    provider: CDNProviderType;
+    /** Whether invalidation was successful */
+    success: boolean;
+    /** URLs that were invalidated */
+    urls: string[];
+    /** Error message if failed */
+    error?: string;
+    /** Invalidation ID from CDN provider */
+    invalidationId?: string;
+}
+/**
+ * CDN Plugin Statistics
+ * Statistics for CDN invalidation operations
+ */
+export interface StorageCDNPluginStatistics {
+    /** Total number of successful invalidations performed */
+    invalidationsPerformed: number;
+    /** Total number of failed invalidations */
+    invalidationsFailed: number;
+    /** Total number of URLs/paths invalidated (use one or both depending on CDN) */
+    urlsInvalidated?: number;
+    pathsInvalidated?: number;
+    /** Number of queued URLs/paths waiting to be invalidated (use one or both depending on CDN) */
+    queuedUrls?: number;
+    queuedPaths?: number;
+}
+/**
+ * Image Processing Plugin Statistics
+ * Statistics for image processing operations
+ */
+export interface StorageImageProcessingPluginStatistics {
+    /** Total number of images processed */
+    imagesProcessed: number;
+    /** Total number of variants generated */
+    variantsGenerated: number;
+    /** Average number of variants generated per image */
+    averageVariantsPerImage: number;
+}
+/**
+ * Metadata Extraction Plugin Statistics
+ * Statistics for metadata extraction operations
+ */
+export interface StorageMetadataExtractionPluginStatistics {
+    /** Total number of files with metadata extracted */
+    filesProcessed: number;
+    /** Success rate as a percentage (0-100) */
+    successRate: number;
+    metadataExtracted?: number;
+}
+/**
+ * Video Processing Plugin Statistics
+ * Statistics for video processing operations
+ */
+export interface StorageVideoProcessingPluginStatistics {
+    /** Total number of videos processed */
+    videosProcessed: number;
+    /** Total number of thumbnails generated */
+    thumbnailsGenerated?: number;
+    /** Average thumbnails per video */
+    averageThumbnailsPerVideo?: number;
+    /** Total number of variants generated */
+    variantsGenerated: number;
+    averageVariantsPerVideo?: number;
+}
+/**
+ * FFmpeg/FFprobe Types
+ * Types for video processing using FFmpeg
+ */
+/**
+ * FFprobe stream information
+ */
+export interface FFprobeStream {
+    codec_type?: string;
+    codec_name?: string;
+    width?: number;
+    height?: number;
+    duration?: string;
+    bit_rate?: string;
+    r_frame_rate?: string;
+}
+/**
+ * FFprobe format information
+ */
+export interface FFprobeFormat {
+    duration?: number;
+    bit_rate?: number | string;
+    size?: string;
+    format_name?: string;
+}
+/**
+ * FFprobe output data
+ */
+export interface FFprobeData {
+    streams: FFprobeStream[];
+    format: FFprobeFormat;
+}
+/**
+ * FFmpeg progress information
+ */
+export interface FFmpegProgress {
+    percent?: number;
+    currentTime?: number;
+    targetSize?: number;
+    timemark?: string;
+}
+/**
+ * FFmpeg command options
+ */
+export interface FFmpegOptions {
+    input: string;
+    output: string;
+    args: string[];
+    onProgress?: (progress: FFmpegProgress) => void;
+    onStart?: (command: string) => void;
+}
+/**
+ * Screenshot options for FFmpeg
+ */
+export interface ScreenshotOptions {
+    timestamps: number[];
+    folder: string;
+    filename: string;
+    size?: string;
+}