@better-media/framework 0.1.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 abenezeratnafu
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, NEGLIGENCE OR OTHER TORTIOUS
+ACTION, ARISING OUT OF OR IN CONNECTION WITH THE USE OR PERFORMANCE OF THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,49 @@
+# @better-media/framework
+
+The core runtime orchestration engine for Better Media pipelines.
+
+## Overview
+
+Better Media is a modular media framework that handles the entire lifecycle of a file ingest—from intake and validation to transformation and multi-environment storage.
+
+This package provides the `createBetterMedia` factory and the core execution logic to coordinate:
+
+1.  **Ingest**: Handle binary, stream, or file-path inputs.
+2.  **Validation**: Run plugins to check file size, MIME type, or integrity.
+3.  **Persistence**: Save to SQL, NoSQL, or custom database adapters.
+4.  **Storage**: Move files to local disk, S3, or in-memory targets.
+5.  **Processing**: Run background or synchronous jobs (resizing, transpoding, etc).
+
+## Installation
+
+```bash
+pnpm add @better-media/framework
+```
+
+## Basic Usage
+
+```ts
+import { createBetterMedia } from "@better-media/framework";
+import { S3StorageAdapter } from "@better-media/adapter-storage-s3";
+import { KyselyDatabaseAdapter } from "@better-media/adapter-db";
+import { validationPlugin } from "@better-media/plugin-validation";
+
+// 1. Configure the runtime
+const media = createBetterMedia({
+  storage: new S3StorageAdapter(s3Config),
+  database: new KyselyDatabaseAdapter(dbConfig),
+  plugins: [validationPlugin({ maxSize: "10mb", allowedMimeTypes: ["image/jpeg", "image/png"] })],
+});
+
+// 2. Process an upload
+const result = await media.upload({
+  file: myFileBuffer,
+  fileName: "profile-pic.jpg",
+});
+
+console.log("Uploaded file key:", result.fileKey);
+```
+
+## Documentation
+
+Full documentation is available at [better-media.dev](https://better-media.dev).

package/bin/media.mjs

@@ -0,0 +1,3 @@
+#!/usr/bin/env node
+
+import "@better-media/cli";

package/dist/index.d.mts

@@ -0,0 +1,225 @@
+import { HookName, PipelineContext, PluginApi, ValidationResult, PluginManifest, JobAdapter, MediaPlugin, HookContext, PipelinePlugin, MediaRuntime, PgPoolLike, DatabaseAdapter, StorageAdapter, PresignedUploadOptions, PresignedUploadResult, GetUrlOptions } from '@better-media/core';
+export { BmSchema, DatabaseHookContext, DbHooks, FieldDefinition, FieldType, GetAdapterOptions, GetUrlOptions, HOOK_NAMES, HookContext, IndexDefinition, MigrationOperation, MigrationOptions, MigrationPlanner, ModelDefinition, PgClientLike, PgPoolLike, PresignedUploadMethod, PresignedUploadOptions, PresignedUploadResult, QueryResultLike, Queryable, SqlDialect, TableMetadata, applyOperationsToMetadata, compileMigrationOperationsSql, deserializeData, getAdapter, getColumnType, getMigrations, isPgPoolLike, runHooks, runMigrations, schema, serializeData, toCamelCase, toDbFieldName } from '@better-media/core';
+import { Readable } from 'node:stream';
+
+interface BetterMediaSettings {
+    /** Log level for the framework */
+    logLevel?: "debug" | "info" | "warn" | "error";
+}
+
+interface FileHandlingConfig {
+    /** When set, files larger than this use streaming to temp file instead of loading into memory. */
+    maxBufferBytes?: number;
+}
+
+/** Single tapped handler entry */
+interface TapInfo {
+    name: string;
+    fn: (ctx: PipelineContext, api: PluginApi) => Promise<void | ValidationResult>;
+    mode: "sync" | "background";
+    manifest: PluginManifest;
+    stage?: number;
+}
+/** Registry: hook name -> ordered list of handlers */
+type HookRegistry = Map<HookName, TapInfo[]>;
+
+/**
+ * Policy gate for explicitly authorizing trusted plugins.
+ * Prevents unauthorized plugins from claiming "trusted" status.
+ */
+interface TrustedPluginPolicy {
+    isAuthorized(pluginId: string, namespace: string): boolean;
+}
+/**
+ * Build hook registry from plugins via apply pattern.
+ */
+declare function buildPluginRegistry(plugins: PipelinePlugin[], policy?: TrustedPluginPolicy): {
+    registry: HookRegistry;
+    runtime: MediaRuntime;
+};
+
+/**
+ * Validates that a plugin has required fields (name, apply or execute)
+ * and a valid runtimeManifest.
+ * @throws Error if plugin is invalid
+ */
+declare function validatePlugin(plugin: PipelinePlugin): void;
+/**
+ * PluginRegistry: register plugins, maintain hook maps, execute hooks.
+ * Allows dynamic registration and type-safe hook execution.
+ *
+ * @example
+ * ```ts
+ * const registry = new PluginRegistry(jobAdapter);
+ * registry.register(validationPlugin());
+ * registry.register(thumbnailPlugin({ mode: "background" }));
+ *
+ * await registry.executeHook("validation:run", context);
+ * ```
+ */
+declare class PluginRegistry {
+    private readonly plugins;
+    private readonly registry;
+    private readonly engine;
+    constructor(jobAdapter: JobAdapter, initialPlugins?: MediaPlugin[]);
+    /** Register a plugin and rebuild the hook map */
+    register(plugin: MediaPlugin): void;
+    /** Get all registered plugins (shallow copy) */
+    getPlugins(): MediaPlugin[];
+    /**
+     * Execute all handlers for a hook. Runs sync handlers in series.
+     * Enqueues background handlers via JobAdapter.
+     * @returns ValidationResult if validation phase aborts (valid: false)
+     */
+    executeHook(hookName: HookName, context: HookContext): Promise<void | ValidationResult>;
+    /** Access the internal hook registry (for framework wiring) */
+    getRegistry(): HookRegistry;
+}
+/** Check if any handler in the registry is background mode */
+declare function hasBackgroundHandlers(registry: HookRegistry): boolean;
+
+declare function postgresDatabase(pool: PgPoolLike): DatabaseAdapter;
+declare function toDatabaseAdapter(database: DatabaseAdapter | PgPoolLike): DatabaseAdapter;
+
+/** Configuration for the Better Media framework */
+interface BetterMediaConfig {
+    /** Storage adapter for file bytes (S3, GCS, local, etc.) */
+    storage: StorageAdapter;
+    /** Database adapter or a Postgres Pool (built-in) for media metadata/records */
+    database: DatabaseAdapter | PgPoolLike;
+    /** Plugins to run in order during the lifecycle */
+    plugins: PipelinePlugin[];
+    /** Optional job adapter for background execution (default: in-memory) */
+    jobs?: JobAdapter;
+    /** Optional settings */
+    settings?: BetterMediaSettings;
+    /**
+     * Optional file handling. When maxBufferBytes is set, files larger than that
+     * are streamed to a temp file instead of loaded into memory.
+     */
+    fileHandling?: FileHandlingConfig;
+    /** Optional policy gate for authorizing trusted plugins */
+    trustedPolicy?: TrustedPluginPolicy;
+}
+
+/** Background job payload (serializable) */
+interface BackgroundJobPayload {
+    recordId: string;
+    metadata: Record<string, unknown>;
+    file: PipelineContext["file"];
+    storageLocation: PipelineContext["storageLocation"];
+    processing: PipelineContext["processing"];
+    hookName: HookName;
+    pluginName: string;
+    manifest: PluginManifest;
+}
+
+type MediaFileInput = {
+    buffer: Buffer;
+} | {
+    stream: Readable;
+} | {
+    path: string;
+} | {
+    url: string;
+    mode?: "import" | "reference";
+};
+type MediaMetadata = {
+    filename?: string;
+    mimeType?: string;
+    size?: number;
+    context?: Record<string, unknown>;
+    [key: string]: unknown;
+};
+type IngestInput = {
+    file: MediaFileInput;
+    metadata?: MediaMetadata;
+    key?: string;
+    /**
+     * When `file` is a filesystem path, whether to delete that file after ingest completes.
+     * Defaults to `true` (typical for temp uploads, e.g. Multer). Set to `false` when the path
+     * points at a permanent user file that must be kept on disk.
+     */
+    deleteAfterUpload?: boolean;
+};
+type MediaResult = {
+    /** The unique database record identifier (UUID). */
+    id: string;
+    /** The storage key (filename or path). */
+    key: string;
+    url?: string;
+    metadata?: MediaMetadata;
+    status: "stored" | "processed";
+};
+/** Metadata for uploads (e.g. contentType). Accepted at upload time. */
+type Metadata = MediaMetadata;
+/** File record in database (one per file). */
+type FileRecord = MediaMetadata;
+interface BetterMediaRuntime {
+    upload: {
+        ingest(input: IngestInput): Promise<MediaResult>;
+        fromBuffer(buffer: Buffer, input?: Omit<IngestInput, "file">): Promise<MediaResult>;
+        fromStream(stream: Readable, input?: Omit<IngestInput, "file">): Promise<MediaResult>;
+        fromPath(path: string, input?: Omit<IngestInput, "file">): Promise<MediaResult>;
+        fromUrl(url: string, input?: Omit<IngestInput, "file"> & {
+            mode?: "import" | "reference";
+        }): Promise<MediaResult>;
+        /**
+         * Create a presigned upload for direct-to-storage upload.
+         * Supports both PUT (binary body) and POST (multipart form) with strict server-side validation.
+         * After the client uploads, call `complete()` to run the processing pipeline.
+         */
+        requestPresignedUpload(key: string, options: PresignedUploadOptions): Promise<PresignedUploadResult>;
+        /** Called by the client *after* successfully uploading to the presigned URL */
+        complete(key: string, metadata?: MediaMetadata): Promise<MediaResult>;
+    };
+    /** File operations */
+    files: {
+        get(fileKey: string): Promise<FileRecord | null>;
+        delete(fileKey: string): Promise<void>;
+        getUrl(fileKey: string, options?: GetUrlOptions): Promise<string>;
+        reprocess(fileKey: string, metadata?: Metadata): Promise<void>;
+    };
+    /** Execute background job (call from worker). */
+    runBackgroundJob(payload: BackgroundJobPayload): Promise<void>;
+}
+
+/** Error thrown when validation phase aborts the pipeline */
+declare class ValidationError extends Error {
+    readonly recordId: string;
+    readonly fileKey: string;
+    readonly result: ValidationResult;
+    constructor(recordId: string, fileKey: string, result: ValidationResult);
+}
+
+/**
+ * Create and initialize the Better Media runtime.
+ *
+ * @example
+ * ```ts
+ * const media = createBetterMedia({
+ *   storage: new S3StorageAdapter({
+ *     bucket: "my-bucket",
+ *     region: "us-east-1",
+ *     accessKeyId: "...",
+ *     secretAccessKey: "..."
+ *   }),
+ *   database: postgresAdapter(...),
+ *   jobs: redisJobAdapter(),
+ *   plugins: [
+ *     validationPlugin(),
+ *     virusScanPlugin(),
+ *     thumbnailPlugin({ mode: "background" }),
+ *     videoProcessingPlugin({ mode: "background" })
+ *   ]
+ * });
+ *
+ * const result = await media.upload.ingest({
+ *   file: { buffer },
+ *   metadata: { filename: "photo.jpg", mimeType: "image/jpeg" },
+ * });
+ * ```
+ */
+declare function createBetterMedia(config: BetterMediaConfig): BetterMediaRuntime;
+
+export { type BackgroundJobPayload, type BetterMediaRuntime, type FileHandlingConfig, type FileRecord, type IngestInput, type MediaFileInput, type MediaMetadata, type MediaResult, type Metadata, PluginRegistry, ValidationError, buildPluginRegistry, createBetterMedia, hasBackgroundHandlers, postgresDatabase, toDatabaseAdapter, validatePlugin };

package/dist/index.d.ts

@@ -0,0 +1,225 @@
+import { HookName, PipelineContext, PluginApi, ValidationResult, PluginManifest, JobAdapter, MediaPlugin, HookContext, PipelinePlugin, MediaRuntime, PgPoolLike, DatabaseAdapter, StorageAdapter, PresignedUploadOptions, PresignedUploadResult, GetUrlOptions } from '@better-media/core';
+export { BmSchema, DatabaseHookContext, DbHooks, FieldDefinition, FieldType, GetAdapterOptions, GetUrlOptions, HOOK_NAMES, HookContext, IndexDefinition, MigrationOperation, MigrationOptions, MigrationPlanner, ModelDefinition, PgClientLike, PgPoolLike, PresignedUploadMethod, PresignedUploadOptions, PresignedUploadResult, QueryResultLike, Queryable, SqlDialect, TableMetadata, applyOperationsToMetadata, compileMigrationOperationsSql, deserializeData, getAdapter, getColumnType, getMigrations, isPgPoolLike, runHooks, runMigrations, schema, serializeData, toCamelCase, toDbFieldName } from '@better-media/core';
+import { Readable } from 'node:stream';
+
+interface BetterMediaSettings {
+    /** Log level for the framework */
+    logLevel?: "debug" | "info" | "warn" | "error";
+}
+
+interface FileHandlingConfig {
+    /** When set, files larger than this use streaming to temp file instead of loading into memory. */
+    maxBufferBytes?: number;
+}
+
+/** Single tapped handler entry */
+interface TapInfo {
+    name: string;
+    fn: (ctx: PipelineContext, api: PluginApi) => Promise<void | ValidationResult>;
+    mode: "sync" | "background";
+    manifest: PluginManifest;
+    stage?: number;
+}
+/** Registry: hook name -> ordered list of handlers */
+type HookRegistry = Map<HookName, TapInfo[]>;
+
+/**
+ * Policy gate for explicitly authorizing trusted plugins.
+ * Prevents unauthorized plugins from claiming "trusted" status.
+ */
+interface TrustedPluginPolicy {
+    isAuthorized(pluginId: string, namespace: string): boolean;
+}
+/**
+ * Build hook registry from plugins via apply pattern.
+ */
+declare function buildPluginRegistry(plugins: PipelinePlugin[], policy?: TrustedPluginPolicy): {
+    registry: HookRegistry;
+    runtime: MediaRuntime;
+};
+
+/**
+ * Validates that a plugin has required fields (name, apply or execute)
+ * and a valid runtimeManifest.
+ * @throws Error if plugin is invalid
+ */
+declare function validatePlugin(plugin: PipelinePlugin): void;
+/**
+ * PluginRegistry: register plugins, maintain hook maps, execute hooks.
+ * Allows dynamic registration and type-safe hook execution.
+ *
+ * @example
+ * ```ts
+ * const registry = new PluginRegistry(jobAdapter);
+ * registry.register(validationPlugin());
+ * registry.register(thumbnailPlugin({ mode: "background" }));
+ *
+ * await registry.executeHook("validation:run", context);
+ * ```
+ */
+declare class PluginRegistry {
+    private readonly plugins;
+    private readonly registry;
+    private readonly engine;
+    constructor(jobAdapter: JobAdapter, initialPlugins?: MediaPlugin[]);
+    /** Register a plugin and rebuild the hook map */
+    register(plugin: MediaPlugin): void;
+    /** Get all registered plugins (shallow copy) */
+    getPlugins(): MediaPlugin[];
+    /**
+     * Execute all handlers for a hook. Runs sync handlers in series.
+     * Enqueues background handlers via JobAdapter.
+     * @returns ValidationResult if validation phase aborts (valid: false)
+     */
+    executeHook(hookName: HookName, context: HookContext): Promise<void | ValidationResult>;
+    /** Access the internal hook registry (for framework wiring) */
+    getRegistry(): HookRegistry;
+}
+/** Check if any handler in the registry is background mode */
+declare function hasBackgroundHandlers(registry: HookRegistry): boolean;
+
+declare function postgresDatabase(pool: PgPoolLike): DatabaseAdapter;
+declare function toDatabaseAdapter(database: DatabaseAdapter | PgPoolLike): DatabaseAdapter;
+
+/** Configuration for the Better Media framework */
+interface BetterMediaConfig {
+    /** Storage adapter for file bytes (S3, GCS, local, etc.) */
+    storage: StorageAdapter;
+    /** Database adapter or a Postgres Pool (built-in) for media metadata/records */
+    database: DatabaseAdapter | PgPoolLike;
+    /** Plugins to run in order during the lifecycle */
+    plugins: PipelinePlugin[];
+    /** Optional job adapter for background execution (default: in-memory) */
+    jobs?: JobAdapter;
+    /** Optional settings */
+    settings?: BetterMediaSettings;
+    /**
+     * Optional file handling. When maxBufferBytes is set, files larger than that
+     * are streamed to a temp file instead of loaded into memory.
+     */
+    fileHandling?: FileHandlingConfig;
+    /** Optional policy gate for authorizing trusted plugins */
+    trustedPolicy?: TrustedPluginPolicy;
+}
+
+/** Background job payload (serializable) */
+interface BackgroundJobPayload {
+    recordId: string;
+    metadata: Record<string, unknown>;
+    file: PipelineContext["file"];
+    storageLocation: PipelineContext["storageLocation"];
+    processing: PipelineContext["processing"];
+    hookName: HookName;
+    pluginName: string;
+    manifest: PluginManifest;
+}
+
+type MediaFileInput = {
+    buffer: Buffer;
+} | {
+    stream: Readable;
+} | {
+    path: string;
+} | {
+    url: string;
+    mode?: "import" | "reference";
+};
+type MediaMetadata = {
+    filename?: string;
+    mimeType?: string;
+    size?: number;
+    context?: Record<string, unknown>;
+    [key: string]: unknown;
+};
+type IngestInput = {
+    file: MediaFileInput;
+    metadata?: MediaMetadata;
+    key?: string;
+    /**
+     * When `file` is a filesystem path, whether to delete that file after ingest completes.
+     * Defaults to `true` (typical for temp uploads, e.g. Multer). Set to `false` when the path
+     * points at a permanent user file that must be kept on disk.
+     */
+    deleteAfterUpload?: boolean;
+};
+type MediaResult = {
+    /** The unique database record identifier (UUID). */
+    id: string;
+    /** The storage key (filename or path). */
+    key: string;
+    url?: string;
+    metadata?: MediaMetadata;
+    status: "stored" | "processed";
+};
+/** Metadata for uploads (e.g. contentType). Accepted at upload time. */
+type Metadata = MediaMetadata;
+/** File record in database (one per file). */
+type FileRecord = MediaMetadata;
+interface BetterMediaRuntime {
+    upload: {
+        ingest(input: IngestInput): Promise<MediaResult>;
+        fromBuffer(buffer: Buffer, input?: Omit<IngestInput, "file">): Promise<MediaResult>;
+        fromStream(stream: Readable, input?: Omit<IngestInput, "file">): Promise<MediaResult>;
+        fromPath(path: string, input?: Omit<IngestInput, "file">): Promise<MediaResult>;
+        fromUrl(url: string, input?: Omit<IngestInput, "file"> & {
+            mode?: "import" | "reference";
+        }): Promise<MediaResult>;
+        /**
+         * Create a presigned upload for direct-to-storage upload.
+         * Supports both PUT (binary body) and POST (multipart form) with strict server-side validation.
+         * After the client uploads, call `complete()` to run the processing pipeline.
+         */
+        requestPresignedUpload(key: string, options: PresignedUploadOptions): Promise<PresignedUploadResult>;
+        /** Called by the client *after* successfully uploading to the presigned URL */
+        complete(key: string, metadata?: MediaMetadata): Promise<MediaResult>;
+    };
+    /** File operations */
+    files: {
+        get(fileKey: string): Promise<FileRecord | null>;
+        delete(fileKey: string): Promise<void>;
+        getUrl(fileKey: string, options?: GetUrlOptions): Promise<string>;
+        reprocess(fileKey: string, metadata?: Metadata): Promise<void>;
+    };
+    /** Execute background job (call from worker). */
+    runBackgroundJob(payload: BackgroundJobPayload): Promise<void>;
+}
+
+/** Error thrown when validation phase aborts the pipeline */
+declare class ValidationError extends Error {
+    readonly recordId: string;
+    readonly fileKey: string;
+    readonly result: ValidationResult;
+    constructor(recordId: string, fileKey: string, result: ValidationResult);
+}
+
+/**
+ * Create and initialize the Better Media runtime.
+ *
+ * @example
+ * ```ts
+ * const media = createBetterMedia({
+ *   storage: new S3StorageAdapter({
+ *     bucket: "my-bucket",
+ *     region: "us-east-1",
+ *     accessKeyId: "...",
+ *     secretAccessKey: "..."
+ *   }),
+ *   database: postgresAdapter(...),
+ *   jobs: redisJobAdapter(),
+ *   plugins: [
+ *     validationPlugin(),
+ *     virusScanPlugin(),
+ *     thumbnailPlugin({ mode: "background" }),
+ *     videoProcessingPlugin({ mode: "background" })
+ *   ]
+ * });
+ *
+ * const result = await media.upload.ingest({
+ *   file: { buffer },
+ *   metadata: { filename: "photo.jpg", mimeType: "image/jpeg" },
+ * });
+ * ```
+ */
+declare function createBetterMedia(config: BetterMediaConfig): BetterMediaRuntime;
+
+export { type BackgroundJobPayload, type BetterMediaRuntime, type FileHandlingConfig, type FileRecord, type IngestInput, type MediaFileInput, type MediaMetadata, type MediaResult, type Metadata, PluginRegistry, ValidationError, buildPluginRegistry, createBetterMedia, hasBackgroundHandlers, postgresDatabase, toDatabaseAdapter, validatePlugin };