Types

Types to import when annotating your own code against the Better Media API.

All types are exported from @better-media/framework.

Upload

`IngestInput`

The argument to media.upload.ingest().

import type { IngestInput } from "@better-media/framework";

const input: IngestInput = {
  file: { buffer },           // or stream, path, url
  metadata: { filename: "photo.jpg", mimeType: "image/jpeg" },
  key: "uploads/photo.jpg",   // optional — auto-generated if omitted
  deleteAfterUpload: true,    // path-based only, default true
};

`MediaFileInput`

The file field of IngestInput. Provide one variant:

type MediaFileInput =
  | { buffer: Buffer }
  | { stream: Readable }
  | { path: string }
  | { url: string; mode?: "import" | "reference" };

"import" (default) downloads the URL to storage. "reference" registers the URL as the storage key without downloading.

`MediaMetadata`

Caller-supplied metadata attached to an upload. All fields are optional.

type MediaMetadata = {
  filename?: string;
  mimeType?: string;
  size?: number;
  context?: Record<string, unknown>; // e.g. { userId, tenantId }
  [key: string]: unknown;            // any extra fields
};

`MediaResult`

Returned by all upload methods.

type MediaResult = {
  id: string;      // database record UUID — use this to reference the file later
  key: string;     // storage key
  url?: string;
  metadata?: MediaMetadata;
  status: "stored" | "processed";
};

Events

Use these when typing your events callbacks.

import type { BetterMediaEvents, ProcessingCompleteEvent, ErrorEvent } from "@better-media/framework";

const events: BetterMediaEvents = {
  onUploadComplete: (result: MediaResult) => { /* ... */ },
  onProcessingComplete: (event: ProcessingCompleteEvent) => { /* ... */ },
  onError: (error: Error, context: ErrorEvent) => { /* ... */ },
};

type ProcessingCompleteEvent = { id: string; key: string; pluginName: string };
type ErrorEvent = { id?: string; key?: string };

Background Jobs

The only type you need when wiring a worker:

import type { BackgroundJobPayload } from "@better-media/framework";

const worker = createBullMQWorker(
  (payload) => media.runBackgroundJob(payload as BackgroundJobPayload),
  { connection }
);

Plugin Authoring

These are only needed when writing a custom plugin. See Plugin Architecture for context.

import type {
  PipelinePlugin,    // interface your plugin class implements
  PipelineContext,   // the context object passed to handlers
  PluginApi,         // the write interface (emitMetadata, emitProcessing)
} from "@better-media/core";

Types

On this page