@visulima/storage 1.0.0-alpha.1 → 1.0.0-alpha.3

package/dist/transformer/validation-error.d.ts

@@ -0,0 +1,23 @@
+/**
+ * Custom error class for validation failures
+ */
+declare class ValidationError extends Error {
+    readonly code: string;
+    readonly details: {
+        invalidParams: string[];
+        mediaType: string;
+        suggestions?: string[];
+        validParams: string[];
+    };
+    /**
+     * Creates a new ValidationError instance with detailed error information.
+     * @param message Human-readable error message describing the validation failure
+     * @param code Machine-readable error code for programmatic error handling
+     * @param mediaType The media type where validation failed ('image', 'video', or 'audio')
+     * @param invalidParameters Array of parameter names that were invalid
+     * @param validParameters Array of valid parameter names or values
+     * @param suggestions Optional array of suggested corrections or valid values
+     */
+    constructor(message: string, code: string, mediaType: string, invalidParameters: string[], validParameters: string[], suggestions?: string[]);
+}
+export default ValidationError;

package/dist/transformer/video-transformer.d.ts

@@ -0,0 +1,145 @@
+import type { BaseStorage } from "../storage/storage.d.ts";
+import type { File, FileReturn } from "../storage/utils/index.d.ts";
+import BaseTransformer from "./base-transformer.d.ts";
+import type { VideoCropOptions, VideoResizeOptions, VideoRotateOptions, VideoTransformationStep, VideoTransformerConfig, VideoTransformOptions, VideoTransformResult } from "./types.d.ts";
+/**
+ * Video transformer that uses storage backends and Mediabunny library to retrieve and transform videos.
+ * @template TFile The file type used by this transformer.
+ * @template TFileReturn The return type for file retrieval operations.
+ *
+ * Supports video transformations with query parameters for on-demand video processing.
+ * @example
+ * ```ts
+ * const transformer = new VideoTransformer(storage, {
+ *   maxVideoSize: 100 * 1024 * 1024, // 100MB
+ *   cache: new Map()
+ * });
+ *
+ * // Programmatic usage - resize a video
+ * const result = await transformer.resize('video-id', {
+ *   width: 1920,
+ *   height: 1080,
+ *   fit: 'contain'
+ * });
+ *
+ * // URL-based transformations
+ * // GET /files/video-id?width=1280&height=720&fit=cover&bitrate=2000000
+ * // GET /files/video-id?codec=vp9&bitrate=1000000
+ * ```
+ *
+ * ## Supported Query Parameters
+ *
+ * - `width`: Width in pixels (Number)
+ * - `height`: Height in pixels (Number)
+ * - `fit`: Resize fit mode - cover/contain/fill/inside/outside
+ * - `codec`: Video codec - avc/hevc/vp8/vp9/av1
+ * - `bitrate`: Video bitrate in bits per second (Number)
+ * - `frameRate`: Frame rate in Hz (Number)
+ * - `format`: Output format - mp4/webm/mkv/ogg
+ */
+declare class VideoTransformer<TFile extends File = File, TFileReturn extends FileReturn = FileReturn> extends BaseTransformer<VideoTransformerConfig, VideoTransformResult<TFileReturn>, TFile, TFileReturn> {
+    /**
+     * Creates a new VideoTransformer instance.
+     * @param storage The storage backend for retrieving and storing video files.
+     * @param config Configuration options for video transformation including cache settings, codec defaults, and size limits.
+     */
+    constructor(storage: BaseStorage<TFile, TFileReturn>, config?: VideoTransformerConfig);
+    /**
+     * Resizes a video to specified dimensions with optional fit mode.
+     * @param fileId Unique identifier of the video file to resize.
+     * @param options Resize options including width, height, and fit mode.
+     * @returns Promise resolving to transformed video result.
+     */
+    resize(fileId: string, options: VideoResizeOptions): Promise<VideoTransformResult<TFileReturn>>;
+    /**
+     * Crops a video to the specified region.
+     * @param fileId Unique identifier of the video file to crop.
+     * @param options Crop options including region coordinates.
+     * @returns Promise resolving to transformed video result.
+     */
+    crop(fileId: string, options: VideoCropOptions): Promise<VideoTransformResult<TFileReturn>>;
+    /**
+     * Rotates a video by the specified angle.
+     * @param fileId Unique identifier of the video file to rotate.
+     * @param options Rotation configuration with angle in degrees and optional background color.
+     * @returns Promise resolving to transformed video result.
+     */
+    rotate(fileId: string, options: VideoRotateOptions): Promise<VideoTransformResult<TFileReturn>>;
+    /**
+     * Converts video format or codec.
+     * @param fileId Unique identifier of the video file to convert.
+     * @param format Target video format (e.g., "mp4", "webm", "mkv").
+     * @param options Video transformation options including quality, bitrate, and codec settings.
+     * @returns Promise resolving to transformed video result with updated format metadata.
+     */
+    convertFormat(fileId: string, format: string, options?: VideoTransformOptions): Promise<VideoTransformResult<TFileReturn>>;
+    /**
+     * Transcodes video to different codec.
+     * @param fileId Unique identifier of the video file to transcode.
+     * @param codec Target video codec (e.g., "avc", "hevc", "vp9").
+     * @param options Additional transform options.
+     * @returns Promise resolving to transformed video result.
+     */
+    transcode(fileId: string, codec: VideoTransformOptions["codec"], options?: Omit<VideoTransformOptions, "codec">): Promise<VideoTransformResult<TFileReturn>>;
+    /**
+     * Applies a custom transformation pipeline to a video.
+     * @param fileId Unique identifier of the video file to transform.
+     * @param steps Array of transformation steps to apply in sequence.
+     * @returns Promise resolving to transformed video result.
+     */
+    transform(fileId: string, steps: VideoTransformationStep[]): Promise<VideoTransformResult<TFileReturn>>;
+    /**
+     * Applies multiple transformations in sequence using Mediabunny.
+     * @param buffer The original video buffer.
+     * @param steps Array of video transformation steps to apply.
+     * @returns Promise resolving to transformed video buffer.
+     * @private
+     */
+    private applyTransformations;
+    /**
+     * Converts transformation steps to Mediabunny video options.
+     * @param steps Array of video transformation steps to convert.
+     * @returns Mediabunny video options object for conversion.
+     * @private
+     */
+    private stepsToVideoOptions;
+    /**
+     * Determines output format based on transformation steps.
+     * @param steps Array of video transformation steps.
+     * @returns Mediabunny output format instance (defaults to MP4).
+     * @private
+     */
+    private determineOutputFormat;
+    /**
+     * Converts format string to Mediabunny output format.
+     * @param format Video format string (mp4, webm, mkv, ogg).
+     * @returns Mediabunny output format instance.
+     * @private
+     */
+    private formatStringToOutputFormat;
+    /**
+     * Validates that the file is a supported video.
+     * @param file The file to validate.
+     * @returns Promise that resolves if validation passes.
+     * @throws Error if file size exceeds limits, wrong content type, unsupported format, or invalid video.
+     * @private
+     */
+    private validateVideo;
+    /**
+     * Creates transformation result with metadata.
+     * @param buffer The transformed video buffer.
+     * @param originalFile The original file information.
+     * @returns Video transformation result with metadata.
+     * @private
+     */
+    private createTransformResult;
+    /**
+     * Generates cache key for transformation.
+     * @param fileId The file identifier.
+     * @param steps Array of transformation steps.
+     * @returns Unique cache key string.
+     * @private
+     */
+    private generateCacheKey;
+}
+export default VideoTransformer;

package/dist/transformer/video-transformer.js

@@ -0,0 +1,310 @@
+import { Input, BufferSource, ALL_FORMATS, Output, BufferTarget, Conversion, Mp4OutputFormat, WebMOutputFormat, OggOutputFormat, MkvOutputFormat } from 'mediabunny';
+import BaseTransformer from '../packem_shared/BaseTransformer-C2gLib6v.js';
+import { isValidMediaType, getFormatFromContentType } from '../packem_shared/isValidMediaType-BeDgiObq.js';
+
+class VideoTransformer extends BaseTransformer {
+  /**
+   * Creates a new VideoTransformer instance.
+   * @param storage The storage backend for retrieving and storing video files.
+   * @param config Configuration options for video transformation including cache settings, codec defaults, and size limits.
+   */
+  constructor(storage, config = {}) {
+    const logger = config.logger || storage.logger;
+    const transformerConfig = {
+      cacheTtl: 3600,
+      // 1 hour
+      defaultBitrate: 2e6,
+      // 2 Mbps
+      defaultCodec: "avc",
+      // No cache provided - no caching
+      maxCacheSize: 50,
+      // Max 50 transformed videos in cache
+      maxVideoSize: 500 * 1024 * 1024,
+      // 500MB
+      supportedFormats: ["mp4", "webm", "mkv", "avi", "mov", "flv", "wmv"],
+      ...config
+    };
+    super(storage, transformerConfig, logger);
+  }
+  /**
+   * Resizes a video to specified dimensions with optional fit mode.
+   * @param fileId Unique identifier of the video file to resize.
+   * @param options Resize options including width, height, and fit mode.
+   * @returns Promise resolving to transformed video result.
+   */
+  async resize(fileId, options) {
+    return this.transform(fileId, [{ options, type: "resize" }]);
+  }
+  /**
+   * Crops a video to the specified region.
+   * @param fileId Unique identifier of the video file to crop.
+   * @param options Crop options including region coordinates.
+   * @returns Promise resolving to transformed video result.
+   */
+  async crop(fileId, options) {
+    return this.transform(fileId, [{ options, type: "crop" }]);
+  }
+  /**
+   * Rotates a video by the specified angle.
+   * @param fileId Unique identifier of the video file to rotate.
+   * @param options Rotation configuration with angle in degrees and optional background color.
+   * @returns Promise resolving to transformed video result.
+   */
+  async rotate(fileId, options) {
+    return this.transform(fileId, [{ options, type: "rotate" }]);
+  }
+  /**
+   * Converts video format or codec.
+   * @param fileId Unique identifier of the video file to convert.
+   * @param format Target video format (e.g., "mp4", "webm", "mkv").
+   * @param options Video transformation options including quality, bitrate, and codec settings.
+   * @returns Promise resolving to transformed video result with updated format metadata.
+   */
+  async convertFormat(fileId, format, options = {}) {
+    return this.transform(fileId, [{ options: { ...options, format }, type: "format" }]);
+  }
+  /**
+   * Transcodes video to different codec.
+   * @param fileId Unique identifier of the video file to transcode.
+   * @param codec Target video codec (e.g., "avc", "hevc", "vp9").
+   * @param options Additional transform options.
+   * @returns Promise resolving to transformed video result.
+   */
+  async transcode(fileId, codec, options = {}) {
+    return this.transform(fileId, [{ options: { ...options, codec }, type: "codec" }]);
+  }
+  /**
+   * Applies a custom transformation pipeline to a video.
+   * @param fileId Unique identifier of the video file to transform.
+   * @param steps Array of transformation steps to apply in sequence.
+   * @returns Promise resolving to transformed video result.
+   */
+  async transform(fileId, steps) {
+    const fileQuery = { id: fileId };
+    const cacheKey = this.generateCacheKey(fileId, steps);
+    if (this.cache) {
+      const cached = await Promise.resolve(this.cache.get(cacheKey));
+      if (cached) {
+        this.logger?.debug("Returning cached transformed video for %s", fileId);
+        return cached;
+      }
+    }
+    const originalFile = await this.storage.get(fileQuery);
+    await this.validateVideo(originalFile);
+    const transformedBuffer = await this.applyTransformations(originalFile.content, steps);
+    const result = await this.createTransformResult(transformedBuffer, originalFile);
+    if (this.cache) {
+      this.cache.set(cacheKey, result);
+    }
+    return result;
+  }
+  /**
+   * Applies multiple transformations in sequence using Mediabunny.
+   * @param buffer The original video buffer.
+   * @param steps Array of video transformation steps to apply.
+   * @returns Promise resolving to transformed video buffer.
+   * @private
+   */
+  async applyTransformations(buffer, steps) {
+    const input = new Input({
+      formats: ALL_FORMATS,
+      source: new BufferSource(buffer)
+    });
+    const outputFormat = this.determineOutputFormat(steps);
+    const output = new Output({
+      format: outputFormat,
+      target: new BufferTarget()
+    });
+    const videoOptions = this.stepsToVideoOptions(steps);
+    const conversion = await Conversion.init({
+      input,
+      output,
+      video: videoOptions
+    });
+    if (!conversion.isValid) {
+      const reasons = conversion.discardedTracks.map((track) => track.reason).join(", ");
+      throw new Error(`Video transformation failed: ${reasons}`);
+    }
+    await conversion.execute();
+    return Buffer.from(output.target.buffer);
+  }
+  /**
+   * Converts transformation steps to Mediabunny video options.
+   * @param steps Array of video transformation steps to convert.
+   * @returns Mediabunny video options object for conversion.
+   * @private
+   */
+  // eslint-disable-next-line class-methods-use-this
+  stepsToVideoOptions(steps) {
+    const options = {};
+    for (const step of steps) {
+      switch (step.type) {
+        case "bitrate": {
+          const bitrateOptions = step.options;
+          if (bitrateOptions.bitrate) {
+            options.bitrate = bitrateOptions.bitrate;
+          }
+          break;
+        }
+        case "codec": {
+          const codecOptions = step.options;
+          if (codecOptions.codec) {
+            options.codec = codecOptions.codec;
+          }
+          if (codecOptions.bitrate) {
+            options.bitrate = codecOptions.bitrate;
+          }
+          break;
+        }
+        case "crop": {
+          const cropOptions = step.options;
+          options.crop = {
+            height: cropOptions.height,
+            left: cropOptions.left,
+            top: cropOptions.top,
+            width: cropOptions.width
+          };
+          break;
+        }
+        case "frameRate": {
+          const frameRateOptions = step.options;
+          if (frameRateOptions.frameRate) {
+            options.frameRate = frameRateOptions.frameRate;
+          }
+          break;
+        }
+        case "resize": {
+          const resizeOptions = step.options;
+          options.width = resizeOptions.width;
+          options.height = resizeOptions.height;
+          options.fit = resizeOptions.fit;
+          if (resizeOptions.position !== void 0) {
+            options.position = resizeOptions.position;
+          }
+          break;
+        }
+        case "rotate": {
+          const rotateOptions = step.options;
+          options.rotate = rotateOptions.angle;
+          if (rotateOptions.background) {
+            options.background = rotateOptions.background;
+          }
+          break;
+        }
+      }
+    }
+    return options;
+  }
+  /**
+   * Determines output format based on transformation steps.
+   * @param steps Array of video transformation steps.
+   * @returns Mediabunny output format instance (defaults to MP4).
+   * @private
+   */
+  determineOutputFormat(steps) {
+    for (const step of steps) {
+      if (step.type === "format" && step.options.format) {
+        return this.formatStringToOutputFormat(step.options.format);
+      }
+    }
+    return new Mp4OutputFormat();
+  }
+  /**
+   * Converts format string to Mediabunny output format.
+   * @param format Video format string (mp4, webm, mkv, ogg).
+   * @returns Mediabunny output format instance.
+   * @private
+   */
+  // eslint-disable-next-line class-methods-use-this
+  formatStringToOutputFormat(format) {
+    switch (format.toLowerCase()) {
+      case "mkv": {
+        return new MkvOutputFormat();
+      }
+      case "mp4": {
+        return new Mp4OutputFormat();
+      }
+      case "ogg": {
+        return new OggOutputFormat();
+      }
+      case "webm": {
+        return new WebMOutputFormat();
+      }
+      default: {
+        return new Mp4OutputFormat();
+      }
+    }
+  }
+  /**
+   * Validates that the file is a supported video.
+   * @param file The file to validate.
+   * @returns Promise that resolves if validation passes.
+   * @throws Error if file size exceeds limits, wrong content type, unsupported format, or invalid video.
+   * @private
+   */
+  async validateVideo(file) {
+    const fileSize = typeof file.size === "string" ? Number.parseInt(file.size, 10) : file.size;
+    if (this.config?.maxVideoSize && fileSize > this.config.maxVideoSize) {
+      throw new Error(`Video size ${fileSize} exceeds maximum allowed size ${this.config.maxVideoSize}`);
+    }
+    if (!isValidMediaType(file.contentType, "video")) {
+      throw new Error(`File is not a video: ${file.contentType}`);
+    }
+    const format = getFormatFromContentType(file.contentType);
+    if (this.config?.supportedFormats && format && !this.config.supportedFormats.includes(format)) {
+      throw new Error(`Unsupported video format: ${format}`);
+    }
+    try {
+      const input = new Input({
+        formats: ALL_FORMATS,
+        source: new BufferSource(file.content)
+      });
+      const primaryTrack = await input.getPrimaryVideoTrack();
+      if (!primaryTrack) {
+        throw new Error("No video track found");
+      }
+    } catch (error) {
+      throw new Error(`Invalid video file: ${error}`);
+    }
+  }
+  /**
+   * Creates transformation result with metadata.
+   * @param buffer The transformed video buffer.
+   * @param originalFile The original file information.
+   * @returns Video transformation result with metadata.
+   * @private
+   */
+  async createTransformResult(buffer, originalFile) {
+    const input = new Input({
+      formats: ALL_FORMATS,
+      source: new BufferSource(buffer)
+    });
+    const videoTrack = await input.getPrimaryVideoTrack();
+    const duration = await input.computeDuration();
+    return {
+      bitrate: this.config.defaultBitrate,
+      buffer,
+      duration,
+      format: "mp4",
+      // Default, would need to detect actual format
+      height: videoTrack?.displayHeight || 0,
+      originalFile,
+      size: buffer.length,
+      width: videoTrack?.displayWidth || 0
+    };
+  }
+  /**
+   * Generates cache key for transformation.
+   * @param fileId The file identifier.
+   * @param steps Array of transformation steps.
+   * @returns Unique cache key string.
+   * @private
+   */
+  // eslint-disable-next-line class-methods-use-this
+  generateCacheKey(fileId, steps) {
+    const stepsKey = steps.map((step) => `${step.type}:${JSON.stringify(step.options)}`).join("|");
+    return `${fileId}:${stepsKey}`;
+  }
+}
+
+export { VideoTransformer as default };

package/dist/utils/cache.d.ts

@@ -0,0 +1,32 @@
+/**
+ * Simple cache interface that any cache implementation can follow
+ */
+export interface Cache<K = string, V = unknown> {
+    /** Clear all cache entries */
+    clear: () => void | Promise<void>;
+    /** Delete a value from cache */
+    delete: (key: K) => boolean | Promise<boolean>;
+    /** Get a value from cache */
+    get: (key: K) => V | undefined | Promise<V | undefined>;
+    /** Check if a key exists in cache */
+    has: (key: K) => boolean | Promise<boolean>;
+    /** Set a value in cache */
+    set: (key: K, value: V, options?: CacheOptions) => boolean | Promise<boolean>;
+}
+/**
+ * Options for cache operations
+ */
+export interface CacheOptions {
+    /** TTL in milliseconds */
+    ttl?: number;
+}
+/**
+ * No-op cache implementation that does nothing (used when caching is disabled)
+ */
+export declare class NoOpCache<K = string, V = unknown> implements Cache<K, V> {
+    get(): undefined;
+    set(): boolean;
+    delete(): boolean;
+    clear(): void;
+    has(): boolean;
+}

package/dist/utils/chunked-upload.d.ts

@@ -0,0 +1,65 @@
+import type { UploadFile } from "../storage/utils/index.d.ts";
+/**
+ * Chunk information structure for tracking uploaded chunks.
+ */
+export interface ChunkInfo {
+    /** Optional checksum for validation */
+    checksum?: string;
+    /** Length of chunk in bytes */
+    length: number;
+    /** Byte offset where chunk starts */
+    offset: number;
+}
+/**
+ * Checks if upload is complete based on chunks coverage.
+ * Verifies that all chunks form a continuous sequence covering the total file size.
+ * @param chunks Array of chunk information objects
+ * @param totalSize Total expected file size in bytes
+ * @returns True if upload is complete, false otherwise
+ */
+export declare const isUploadComplete: (chunks: ChunkInfo[], totalSize: number) => boolean;
+/**
+ * Validates a chunk against file constraints.
+ * @param chunkOffset Byte offset where chunk starts
+ * @param chunkLength Length of chunk in bytes
+ * @param totalSize Total file size in bytes
+ * @param maxChunkSize Maximum allowed chunk size (optional)
+ * @throws {Error} If validation fails
+ */
+export declare const validateChunk: (chunkOffset: number, chunkLength: number, totalSize: number, maxChunkSize?: number) => void;
+/**
+ * Tracks a chunk in the metadata chunks array (idempotent).
+ * @param chunks Existing chunks array
+ * @param chunkInfo New chunk information to track
+ * @returns Updated chunks array
+ */
+export declare const trackChunk: (chunks: ChunkInfo[], chunkInfo: ChunkInfo) => ChunkInfo[];
+/**
+ * Calculates upload progress based on chunks.
+ * @param chunks Array of chunk information objects
+ * @param totalSize Total expected file size in bytes
+ * @returns Object with bytesWritten and completion percentage
+ */
+export declare const calculateUploadProgress: (chunks: ChunkInfo[], totalSize: number) => {
+    bytesWritten: number;
+    percentage: number;
+};
+/**
+ * Gets the total bytes written based on file metadata.
+ * For chunked uploads, uses bytesWritten from file or calculates from chunks.
+ * @param file The file object
+ * @returns Total bytes written
+ */
+export declare const getBytesWritten: <TFile extends UploadFile>(file: TFile) => number;
+/**
+ * Checks if a file is a chunked upload based on metadata.
+ * @param file The file object
+ * @returns True if file is a chunked upload
+ */
+export declare const isChunkedUpload: <TFile extends UploadFile>(file: TFile) => boolean;
+/**
+ * Gets the total size for a chunked upload.
+ * @param file The file object
+ * @returns Total size or undefined if not a chunked upload
+ */
+export declare const getTotalSize: <TFile extends UploadFile>(file: TFile) => number | undefined;

package/dist/utils/detect-file-type.d.ts

@@ -0,0 +1,28 @@
+import type { Readable } from "node:stream";
+/**
+ * Detects the file type from a buffer using magic numbers (binary signatures).
+ * This provides more accurate file type detection than relying on file extensions or Content-Type headers.
+ * @param buffer The buffer to detect file type from
+ * @returns The detected file type with extension and MIME type, or undefined if detection fails
+ */
+export declare const detectFileTypeFromBuffer: (buffer: Buffer | Uint8Array) => Promise<{
+    ext: string;
+    mime: string;
+} | undefined>;
+/**
+ * Detects file type from a Node.js stream by peeking at the first chunk and returns both the detected type and a new stream.
+ * This peeks at the stream data without consuming it, allowing the original stream to be used normally.
+ * @param stream The readable stream to detect file type from
+ * @param options Optional configuration for file type detection
+ * @param options.sampleSize The sample size in bytes to peek (default: 4100)
+ * @returns An object with the detected file type and a new readable stream
+ */
+export declare const detectFileTypeFromStream: (stream: Readable, options?: {
+    sampleSize?: number;
+}) => Promise<{
+    fileType?: {
+        ext: string;
+        mime: string;
+    };
+    stream: Readable;
+}>;

package/dist/utils/errors.d.ts

@@ -0,0 +1,74 @@
+import type { HttpError } from "./types.d.ts";
+/**
+ * Canonical error codes used across handlers and storage adapters.
+ * These codes map to standardized HTTP status codes and error messages.
+ */
+export declare enum ERRORS {
+    BAD_REQUEST = "BadRequest",
+    CHECKSUM_MISMATCH = "ChecksumMismatch",
+    FILE_CONFLICT = "FileConflict",
+    FILE_ERROR = "FileError",
+    FILE_LOCKED = "FileLocked",
+    FILE_NOT_ALLOWED = "FileNotAllowed",
+    FILE_NOT_FOUND = "FileNotFound",
+    FORBIDDEN = "Forbidden",
+    GONE = "Gone",
+    INVALID_FILE_NAME = "InvalidFileName",
+    INVALID_FILE_SIZE = "InvalidFileSize",
+    INVALID_RANGE = "InvalidRange",
+    INVALID_TYPE = "Invalidtype",
+    METHOD_NOT_ALLOWED = "MethodNotAllowed",
+    REQUEST_ABORTED = "RequestAborted",
+    REQUEST_ENTITY_TOO_LARGE = "RequestEntityTooLarge",
+    STORAGE_BUSY = "StorageBusy",
+    STORAGE_ERROR = "StorageError",
+    TOO_MANY_REQUESTS = "TooManyRequests",
+    UNKNOWN_ERROR = "UnknownError",
+    UNPROCESSABLE_ENTITY = "UnprocessableEntity",
+    UNSUPPORTED_CHECKSUM_ALGORITHM = "UnsupportedChecksumAlgorithm",
+    UNSUPPORTED_MEDIA_TYPE = "UnsupportedMediaType"
+}
+/**
+ * Type mapping of error codes to standardized HTTP error responses.
+ * @template T - The error code type (defaults to string)
+ */
+export type ErrorResponses<T extends string = string> = {
+    [K in T]: HttpError;
+};
+/**
+ * Mapping of error codes to HttpError response objects.
+ * @returns Map of error codes to standardized HTTP error responses
+ */
+export declare const ErrorMap: ErrorResponses<ERRORS>;
+/**
+ * Error subclass carrying a stable error code and optional detail.
+ * Provides structured error information for upload operations.
+ */
+export declare class UploadError extends Error {
+    name: string;
+    /** The standardized error code from the ERRORS enum */
+    UploadErrorCode: ERRORS;
+    /** Optional additional error details */
+    detail?: unknown;
+    /**
+     * Creates a new UploadError instance.
+     * @param code Standardized error code (defaults to UNKNOWN_ERROR)
+     * @param message Human-readable error message (defaults to the code)
+     * @param detail Optional additional error details
+     */
+    constructor(code?: ERRORS, message?: string, detail?: unknown);
+}
+/**
+ * Type guard to check if an error is an UploadError instance.
+ * @param error Error to check
+ * @returns True if the error is an UploadError with a valid error code
+ */
+export declare const isUploadError: (error: unknown) => error is UploadError;
+/**
+ * Convenience function to throw an UploadError from a string error code.
+ * Looks up the appropriate error message from ErrorMap.
+ * @param UploadErrorCode String error code to convert to UploadError
+ * @param detail Optional additional error details
+ * @throws UploadError with the specified code and message
+ */
+export declare const throwErrorCode: (UploadErrorCode: ERRORS | string, detail?: string) => never;