@better-media/plugin-validation 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,32 @@
+# @better-media/plugin-validation
+
+Validation plugin for the Better Media framework.
+
+## Features
+
+- **MIME Type Validation**: Enforce allowed file types (e.g., `image/jpeg`, `video/mp4`).
+- **File Size Validation**: Enforce minimum and maximum file dimensions.
+- **Header Inspection**: Inspect raw bytes to verify MIME type.
+
+## Installation
+
+```bash
+pnpm add @better-media/plugin-validation
+```
+
+## Usage
+
+```ts
+import { validationPlugin } from "@better-media/plugin-validation";
+
+const media = createBetterMedia({
+  plugins: [
+    validationPlugin({
+      maxSize: "10mb",
+      allowedMimeTypes: ["image/jpeg", "image/png"],
+    }),
+  ],
+});
+```
+
+For more, visit [better-media.dev/docs/plugins/validation](https://better-media.dev/docs/plugins/validation).

package/dist/index.d.mts

@@ -0,0 +1,110 @@
+import { PipelinePlugin } from '@better-media/core';
+
+interface ValidationErrorItem {
+    rule: string;
+    message: string;
+    details?: Record<string, unknown>;
+}
+
+/**
+ * Validation plugin configuration.
+ * All rules are optional; omit to skip that validation.
+ */
+interface ValidationPluginOptions {
+    /**
+     * Execution mode. Default: "background".
+     * Sync: runs inline and can abort the pipeline on failure.
+     * Background: enqueues work; pipeline continues; result stored in DB.
+     */
+    executionMode?: "sync" | "background";
+    /**
+     * When validation fails: "abort" (return ValidationResult, stop pipeline),
+     * "continue" (record failure in DB, let pipeline continue), or "custom" (invoke onFailureCallback).
+     * Applies to sync mode. Background mode always records to DB.
+     */
+    onFailure?: "abort" | "continue" | "custom";
+    /** Called when onFailure is "custom". Receives errors; return to control pipeline (abort if ValidationResult). */
+    onFailureCallback?: (fileKey: string, errors: ValidationErrorItem[]) => void | Promise<{
+        valid: boolean;
+        message?: string;
+    } | void>;
+    /** Allowed file extensions (e.g. [".jpg", ".png"]). Omit to skip. */
+    allowedExtensions?: string[];
+    /** Allowed MIME types (e.g. ["image/jpeg", "image/png"]). Omit to skip. */
+    allowedMimeTypes?: string[];
+    /** Validate MIME via magic bytes (not extension). Requires file bytes. Default: true. */
+    useMagicBytes?: boolean;
+    /**
+     * Extract critical metadata from file content and override context.file.
+     * Trust library-extracted values over caller-provided metadata.
+     * Default: true.
+     */
+    extractMetadata?: boolean;
+    /**
+     * Checksum algorithms to compute when extractMetadata is true.
+     * Default: ["sha256"].
+     */
+    extractChecksums?: ("sha256" | "md5")[];
+    /** Min file size in bytes. Omit to skip. */
+    minBytes?: number;
+    /** Max file size in bytes. Omit to skip. */
+    maxBytes?: number;
+    /** Min width in pixels (images/video). Omit to skip. */
+    minWidth?: number;
+    /** Max width in pixels. Omit to skip. */
+    maxWidth?: number;
+    /** Min height in pixels. Omit to skip. */
+    minHeight?: number;
+    /** Max height in pixels. Omit to skip. */
+    maxHeight?: number;
+    /** Max duration in seconds (video/audio). Use customValidators for implementation. */
+    maxDurationSeconds?: number;
+    /**
+     * Expected checksum for integrity. If provided, computed hash must match.
+     * metadata should contain the expected value (e.g. metadata.sha256).
+     */
+    checksum?: {
+        algorithm: "sha256" | "sha512" | "md5";
+        /** Key in metadata where expected hash is stored, or a literal value. */
+        metadataKey?: string;
+    };
+    /**
+     * Behavior when file is not found in storage (e.g. presigned URL, upload not complete).
+     * "fail": return validation error.
+     * "retry": retry with backoff (uses retryOptions).
+     * "skip": skip validation, return valid (risky).
+     */
+    fileNotFoundBehavior?: "fail" | "retry" | "skip";
+    /** Used when fileNotFoundBehavior is "retry". */
+    retryOptions?: {
+        maxAttempts?: number;
+        delayMs?: number;
+        backoff?: "linear" | "exponential";
+    };
+    /**
+     * Block upload if a file with the same checksum already exists in the database.
+     * Default: false.
+     */
+    preventDuplicates?: boolean | {
+        algorithm?: "sha256" | "md5";
+        metadataKey?: string;
+    };
+    /**
+     * Filename handling when sanitizing for storage (see `sanitizeFilename`).
+     * @default "sanitize"
+     */
+    filenameSafety?: "sanitize" | "randomize";
+    /** Max length for sanitized filenames (default 255). */
+    maxFilenameLength?: number;
+    /** Custom validators. Receives buffer and metadata; return errors to fail. */
+    customValidators?: Array<(buffer: Buffer, metadata: Record<string, unknown>, fileKey: string) => ValidationErrorItem[] | Promise<ValidationErrorItem[]>>;
+}
+
+/**
+ * Validation plugin for the Better Media pipeline.
+ * Supports file type, size, dimensions, checksum, and custom validators.
+ * Configurable failure behavior and file-not-found handling (presigned URLs).
+ */
+declare function validationPlugin(opts?: ValidationPluginOptions): PipelinePlugin;
+
+export { type ValidationPluginOptions, validationPlugin };

package/dist/index.d.ts

@@ -0,0 +1,110 @@
+import { PipelinePlugin } from '@better-media/core';
+
+interface ValidationErrorItem {
+    rule: string;
+    message: string;
+    details?: Record<string, unknown>;
+}
+
+/**
+ * Validation plugin configuration.
+ * All rules are optional; omit to skip that validation.
+ */
+interface ValidationPluginOptions {
+    /**
+     * Execution mode. Default: "background".
+     * Sync: runs inline and can abort the pipeline on failure.
+     * Background: enqueues work; pipeline continues; result stored in DB.
+     */
+    executionMode?: "sync" | "background";
+    /**
+     * When validation fails: "abort" (return ValidationResult, stop pipeline),
+     * "continue" (record failure in DB, let pipeline continue), or "custom" (invoke onFailureCallback).
+     * Applies to sync mode. Background mode always records to DB.
+     */
+    onFailure?: "abort" | "continue" | "custom";
+    /** Called when onFailure is "custom". Receives errors; return to control pipeline (abort if ValidationResult). */
+    onFailureCallback?: (fileKey: string, errors: ValidationErrorItem[]) => void | Promise<{
+        valid: boolean;
+        message?: string;
+    } | void>;
+    /** Allowed file extensions (e.g. [".jpg", ".png"]). Omit to skip. */
+    allowedExtensions?: string[];
+    /** Allowed MIME types (e.g. ["image/jpeg", "image/png"]). Omit to skip. */
+    allowedMimeTypes?: string[];
+    /** Validate MIME via magic bytes (not extension). Requires file bytes. Default: true. */
+    useMagicBytes?: boolean;
+    /**
+     * Extract critical metadata from file content and override context.file.
+     * Trust library-extracted values over caller-provided metadata.
+     * Default: true.
+     */
+    extractMetadata?: boolean;
+    /**
+     * Checksum algorithms to compute when extractMetadata is true.
+     * Default: ["sha256"].
+     */
+    extractChecksums?: ("sha256" | "md5")[];
+    /** Min file size in bytes. Omit to skip. */
+    minBytes?: number;
+    /** Max file size in bytes. Omit to skip. */
+    maxBytes?: number;
+    /** Min width in pixels (images/video). Omit to skip. */
+    minWidth?: number;
+    /** Max width in pixels. Omit to skip. */
+    maxWidth?: number;
+    /** Min height in pixels. Omit to skip. */
+    minHeight?: number;
+    /** Max height in pixels. Omit to skip. */
+    maxHeight?: number;
+    /** Max duration in seconds (video/audio). Use customValidators for implementation. */
+    maxDurationSeconds?: number;
+    /**
+     * Expected checksum for integrity. If provided, computed hash must match.
+     * metadata should contain the expected value (e.g. metadata.sha256).
+     */
+    checksum?: {
+        algorithm: "sha256" | "sha512" | "md5";
+        /** Key in metadata where expected hash is stored, or a literal value. */
+        metadataKey?: string;
+    };
+    /**
+     * Behavior when file is not found in storage (e.g. presigned URL, upload not complete).
+     * "fail": return validation error.
+     * "retry": retry with backoff (uses retryOptions).
+     * "skip": skip validation, return valid (risky).
+     */
+    fileNotFoundBehavior?: "fail" | "retry" | "skip";
+    /** Used when fileNotFoundBehavior is "retry". */
+    retryOptions?: {
+        maxAttempts?: number;
+        delayMs?: number;
+        backoff?: "linear" | "exponential";
+    };
+    /**
+     * Block upload if a file with the same checksum already exists in the database.
+     * Default: false.
+     */
+    preventDuplicates?: boolean | {
+        algorithm?: "sha256" | "md5";
+        metadataKey?: string;
+    };
+    /**
+     * Filename handling when sanitizing for storage (see `sanitizeFilename`).
+     * @default "sanitize"
+     */
+    filenameSafety?: "sanitize" | "randomize";
+    /** Max length for sanitized filenames (default 255). */
+    maxFilenameLength?: number;
+    /** Custom validators. Receives buffer and metadata; return errors to fail. */
+    customValidators?: Array<(buffer: Buffer, metadata: Record<string, unknown>, fileKey: string) => ValidationErrorItem[] | Promise<ValidationErrorItem[]>>;
+}
+
+/**
+ * Validation plugin for the Better Media pipeline.
+ * Supports file type, size, dimensions, checksum, and custom validators.
+ * Configurable failure behavior and file-not-found handling (presigned URLs).
+ */
+declare function validationPlugin(opts?: ValidationPluginOptions): PipelinePlugin;
+
+export { type ValidationPluginOptions, validationPlugin };