API Reference

Complete API documentation for FluxMedia packages.

MediaUploader

The main class for uploading files.

Constructor


new MediaUploader(provider: MediaProvider, plugins?: FluxMediaPlugin[])

Methods

upload(file, options?)

Upload a single file.


async upload(file: File | Buffer, options?: UploadOptions): Promise<UploadResult>

delete(id)

Delete a file by ID.


async delete(id: string): Promise<void>

get(id)

Get file metadata.


async get(id: string): Promise<UploadResult>

getUrl(id, transform?)

Generate a URL, optionally with transformations.


getUrl(id: string, transform?: TransformationOptions): string

uploadMultiple(files, options?)

Upload multiple files with concurrency control.


async uploadMultiple(
  files: File[] | Buffer[], 
  options?: UploadOptions & {
    concurrency?: number;
    onBatchProgress?: (completed: number, total: number) => void;
  }
): Promise<UploadResult[]>

deleteMultiple(ids)

Delete multiple files.


async deleteMultiple(ids: string[]): Promise<void>

supports(feature)

Check if provider supports a feature.


supports(feature: string): boolean

use(plugin)


async use(plugin: FluxMediaPlugin): Promise<this>

Types

UploadOptions


interface UploadOptions {
  folder?: string;
  filename?: string;
  tags?: string[];
  metadata?: Record<string, unknown>;
  transformation?: TransformationOptions;
  onProgress?: (percent: number) => void;
  uniqueFilename?: boolean;  // Generate unique names (default: true)
}

UploadResult


interface UploadResult {
  id: string;
  url: string;
  publicUrl: string;
  size: number;
  format: string;
  width?: number;
  height?: number;
  provider: string;
  metadata: Record<string, unknown>;
  createdAt: Date;
}

TransformationOptions


interface TransformationOptions {
  width?: number;
  height?: number;
  fit?: 'cover' | 'contain' | 'fill' | 'inside' | 'outside';
  quality?: number;
  format?: 'auto' | 'webp' | 'avif' | 'jpg' | 'png';
}

MediaProvider


interface MediaProvider {
  readonly name: string;
  readonly features: ProviderFeatures;
  readonly native: unknown;
 
  upload(file: File | Buffer, options?: UploadOptions): Promise<UploadResult>;
  delete(id: string): Promise<void>;
  get(id: string): Promise<UploadResult>;
  getUrl(id: string, transform?: TransformationOptions): string;
  uploadMultiple(files: File[] | Buffer[], options?: UploadOptions): Promise<UploadResult[]>;
  deleteMultiple(ids: string[]): Promise<void>;
  search?(query: SearchOptions): Promise<UploadResult[]>;
}

ProviderFeatures


interface ProviderFeatures {
  transformations: {
    resize: boolean;
    crop: boolean;
    format: boolean;
    quality: boolean;
    blur: boolean;
    rotate: boolean;
    effects: boolean;
  };
  capabilities: {
    signedUploads: boolean;
    directUpload: boolean;
    multipartUpload: boolean;
    videoProcessing: boolean;
    aiTagging: boolean;
    facialDetection: boolean;
  };
  storage: {
    maxFileSize: number;
    supportedFormats: string[];
  };
}

File Type Detection

Detect file types using magic bytes (more reliable than extensions).

getFileType(buffer)


import { getFileType } from '@fluxmedia/core';
 
const type = await getFileType(buffer);
console.log(type); // { mime: 'image/jpeg', ext: 'jpg' }

getFileTypeFromStream(stream)

For large files without loading into memory:


import { getFileTypeFromStream } from '@fluxmedia/core';
 
const type = await getFileTypeFromStream(readableStream);

Helper Functions


import { isImage, isVideo } from '@fluxmedia/core';
 
if (await isImage(buffer)) {
  // Handle image
}
 
if (await isVideo(buffer)) {
  // Handle video
}

Errors

MediaError


class MediaError extends Error {
  code: MediaErrorCode;
  provider: string;
  originalError?: unknown;
  details?: Record<string, unknown>;
}

MediaErrorCode


enum MediaErrorCode {
  // Upload errors
  UPLOAD_FAILED = 'UPLOAD_FAILED',
  FILE_TOO_LARGE = 'FILE_TOO_LARGE',
  INVALID_FILE_TYPE = 'INVALID_FILE_TYPE',
  NETWORK_ERROR = 'NETWORK_ERROR',
 
  // Authentication errors
  INVALID_CREDENTIALS = 'INVALID_CREDENTIALS',
  UNAUTHORIZED = 'UNAUTHORIZED',
 
  // Provider errors
  PROVIDER_ERROR = 'PROVIDER_ERROR',
  RATE_LIMITED = 'RATE_LIMITED',
  QUOTA_EXCEEDED = 'QUOTA_EXCEEDED',
 
  // Configuration errors
  INVALID_CONFIG = 'INVALID_CONFIG',
  MISSING_CREDENTIALS = 'MISSING_CREDENTIALS',
 
  // File errors
  FILE_NOT_FOUND = 'FILE_NOT_FOUND',
  DELETE_FAILED = 'DELETE_FAILED',
}

Plugin Types

FluxMediaPlugin


interface FluxMediaPlugin {
  name: string;
  version?: string;
  hooks: PluginHooks;
  init?: () => Promise<void> | void;
  destroy?: () => Promise<void> | void;
}

PluginHooks


interface PluginHooks {
  beforeUpload?: (file, options) => Promise<{ file, options } | void>;
  afterUpload?: (result) => Promise<UploadResult>;
  onError?: (error, context) => Promise<void>;
  beforeDelete?: (id) => Promise<string | void>;
  afterDelete?: (id) => Promise<void>;
  beforeGetUrl?: (id, transform?) => Promise<{ id, transform? } | void>;
}

Analytics Event Types

Typed events for the analytics plugin.

AnalyticsEventType


type AnalyticsEventType =
  | 'media.upload.started'
  | 'media.upload.completed'
  | 'media.delete.completed'
  | 'media.error';

TrackFunction


type TrackFunction = <T extends AnalyticsEventType>(
  event: T,
  data: AnalyticsEventMap[T]
) => void;

Event Data Types


interface UploadStartedEventData {
  fileName: string;
  fileSize: number;
  folder?: string;
  uploadId: string;
}
 
interface UploadCompletedEventData {
  fileId: string;
  fileName: string;
  fileSize: number;
  format: string;
  provider: string;
  duration: number;
  totalUploads: number;
  totalSize: number;
}
 
interface DeleteCompletedEventData {
  fileId: string;
}
 
interface ErrorEventData {
  operation: 'upload' | 'delete' | 'get';
  error: { message: string; name: string };
  totalErrors: number;
}