img-upload-kit 0.0.0-stage → 2.0.0

package/dist/index-Brk_uHs6.d.cts

@@ -0,0 +1,234 @@
+import { S as StorageAdapter, U as UploadRecordHook } from './types-BrP-o9nd.cjs';
+import { c as ImageOutputFormat, b as ImageDimensions, E as ExplicitOutputFormat, d as ImageUploadOptions, m as UploadedImageData, k as UploadPresetConfig, i as StandardPresetName } from './upload-C5Trd6Dh.cjs';
+
+interface OptimizedImageResult {
+    buffer: Buffer;
+    width: number;
+    height: number;
+    format: ImageOutputFormat;
+    size: number;
+    quality?: number;
+}
+interface BlurHashResult {
+    dataURL: string;
+    color: string;
+    blurHash?: string;
+}
+interface OptimizeImageOptions {
+    /** Max bounding box dimensions (fit: 'inside', withoutEnlargement: true). Defaults to 1920x1080. */
+    maxDimensions?: ImageDimensions;
+    /** Explicit output format; omit for smart size-guarded AVIF/WebP selection */
+    outputFormat?: ExplicitOutputFormat;
+    /** 1–100 compression quality. Defaults to smart photo/graphic heuristic (85–88). */
+    quality?: number;
+    /** Maximum input pixel count allowed by Sharp (defaults to 50 MP = 50,000,000) */
+    limitInputPixels?: number;
+    /** AVIF/WebP encoding effort (defaults to 6) */
+    effort?: number;
+}
+declare const DEFAULT_LIMIT_INPUT_PIXELS = 50000000;
+interface GenerateBlurOptions {
+    width?: number;
+    fallbackWidth?: number;
+    quality?: number;
+    maxDataUrlChars?: number;
+    includeBlurHash?: boolean;
+}
+type ColorSamplingMode = 'balanced' | 'edge';
+type EdgeKey = 'top' | 'right' | 'bottom' | 'left';
+type EdgeColorSet = Record<EdgeKey, string>;
+declare const PRIMARY_AVIF_EFFORT = 6;
+declare const RETRY_AVIF_EFFORT = 5;
+declare const BLUR_PLACEHOLDER_WIDTH = 128;
+declare const BLUR_PLACEHOLDER_FALLBACK_WIDTH = 96;
+declare const BLUR_PLACEHOLDER_QUALITY = 80;
+declare const BLUR_PLACEHOLDER_MAX_CHARS = 8000;
+declare const EDGE_COLOR_FALLBACK = "#6B7280";
+declare const EDGE_WHITE_FALLBACK = "#F9FAFB";
+declare const WHITE_DOMINANCE_RATIO = 1.35;
+
+interface ProcessedImageBufferResult {
+    optimized: OptimizedImageResult;
+    blurData: BlurHashResult;
+    contentHash: string;
+    originalSize: number;
+}
+interface ProcessImageBufferOptions {
+    maxDimensions?: ImageDimensions;
+    outputFormat?: ExplicitOutputFormat;
+    quality?: number;
+    includeBlurHash?: boolean;
+    optimizationTimeoutMs?: number;
+    blurTimeoutMs?: number;
+    limitInputPixels?: number;
+    effort?: number;
+    allowSvg?: boolean;
+    signal?: AbortSignal;
+}
+interface StoragePathContext {
+    bucket: string;
+    folder?: string;
+    preset?: string;
+    format: ImageOutputFormat;
+    extension: string;
+    customFilename?: string;
+    isClientFilename?: boolean;
+    contentHash: string;
+    originalName?: string;
+    metadata?: Record<string, string>;
+}
+interface GeneratedStorageTarget {
+    bucket: string;
+    path: string;
+    filename: string;
+}
+type StoragePathGenerator = (context: StoragePathContext) => GeneratedStorageTarget;
+interface ImageUploaderOptions<TPresets extends Record<string, UploadPresetConfig> = Record<StandardPresetName, UploadPresetConfig>> {
+    /** Pluggable storage backend (Supabase, S3, R2, Local FS, Memory, or custom) */
+    storage: StorageAdapter;
+    /** Default bucket name when neither `options.bucket` nor `preset.bucket` is provided (defaults to `'images'`) */
+    defaultBucket?: string;
+    /** Default folder prefix within the bucket (defaults to `''` or preset folder) */
+    defaultFolder?: string;
+    /** Default max input size in MB (defaults to `10`) */
+    defaultMaxSizeMB?: number;
+    /** Default allowed MIME formats */
+    defaultAllowedFormats?: string[];
+    /** Default max bounding box dimensions (defaults to `1920x1080`) */
+    defaultMaxDimensions?: ImageDimensions;
+    /** Opt-in to allow SVG uploads by default (sanitized before storage). Defaults to `false`. */
+    allowSvg?: boolean;
+    /** Maximum input pixel count allowed by Sharp (defaults to `50_000_000` = 50 MP) */
+    limitInputPixels?: number;
+    /** Default AVIF/WebP encoding effort (defaults to `6`) */
+    effort?: number;
+    /**
+     * Project-specific named presets (merged over universal `STANDARD_PRESETS` unless `includeStandardPresets: false`).
+     * Preset names are automatically inferred in `uploader.uploadImage(file, { preset })`.
+     */
+    presets?: TPresets;
+    /** Include universal visual role presets (`thumbnail`, `avatar`, `card`, `cover`, `hero`, `logo`, `original`). Defaults to `true`. */
+    includeStandardPresets?: boolean;
+    /** Custom storage path generator for full control over bucket/folder/filename layout */
+    pathGenerator?: StoragePathGenerator;
+    /** Optional database/analytics hook invoked after each successful upload */
+    onUploadRecord?: UploadRecordHook;
+    /** Wait for `onUploadRecord` before returning (defaults to `false` best-effort) */
+    awaitRecordHook?: boolean;
+    /** Optional error hook invoked when a non-awaited `onUploadRecord` fails */
+    onError?: (error: unknown, ctx: {
+        action: 'recordHook' | 'mirrorCleanup';
+    }) => void;
+    /** Max concurrent Sharp + LQIP image processing pipelines (defaults to `2`) */
+    concurrency?: number;
+    /** Max queued processing jobs waiting for a semaphore slot before rejecting with 503 */
+    maxQueue?: number;
+    /** Timeout per Sharp optimization job in ms (defaults to `60000`) */
+    optimizationTimeoutMs?: number;
+    /** Timeout per LQIP/blur generation job in ms (defaults to `30000`) */
+    blurTimeoutMs?: number;
+    /** Generate compact BlurHash strings by default on every upload */
+    includeBlurHash?: boolean;
+}
+type InferredPresetKey<TPresets extends Record<string, UploadPresetConfig>, TIncludeStandard extends boolean = true> = (keyof TPresets & string) | (TIncludeStandard extends false ? never : StandardPresetName) | (string & {});
+interface ImageUploader<TPreset extends string = string> {
+    readonly defaultBucket?: string;
+    uploadImage(file: File | {
+        buffer: Buffer;
+        name?: string;
+        type: string;
+        size?: number;
+    }, options?: ImageUploadOptions<TPreset>): Promise<UploadedImageData>;
+    processBuffer(buffer: Buffer, options?: ProcessImageBufferOptions): Promise<ProcessedImageBufferResult>;
+    deleteImage(path: string, bucket?: string): Promise<void>;
+    deleteByUrl(url: string): Promise<boolean>;
+    resolvePreset(presetName?: string): UploadPresetConfig | undefined;
+    getAllowedBuckets?(): string[];
+    getMaxSizeMB?(allowedPresets?: string[]): number;
+    parseUrl?(url: string): {
+        bucket?: string;
+        path: string;
+    } | null;
+}
+
+interface AuthorizeContext {
+    action: 'upload' | 'delete';
+    request: Request;
+    path?: string;
+    bucket?: string;
+    preset?: string;
+}
+interface AllowClientOverrides {
+    /** Allow client `customFilename` field (always sanitized, forced to output extension, never upserted). */
+    filename?: boolean;
+    /**
+     * Allow client `folder` field. Pass `true` to accept sanitized folder names, or a callback
+     * `(folder, ctx) => string | null` that returns the scoped folder (or `null` to reject with 400).
+     */
+    folder?: boolean | ((folder: string, ctx: AuthorizeContext) => string | null | undefined);
+    /** Allow client `maxWidth` / `maxHeight` fields (clamped to the active preset's `maxDimensions`). */
+    dimensions?: boolean;
+    /** Allow client `outputFormat` field (`jpeg`, `png`, `webp`, `avif`). */
+    format?: boolean;
+    /** Allow client `quality` field (1–100, clamped to the active preset's `quality` when set). */
+    quality?: boolean;
+}
+interface UploadErrorContext {
+    action: 'upload' | 'delete';
+    request: Request;
+}
+interface UploadHttpHandlerOptions<TPreset extends string = string> {
+    uploader: ImageUploader<TPreset>;
+    /**
+     * Optional authorization check. Return `false` or throw to reject with 401.
+     */
+    authorize?: (ctx: AuthorizeContext) => boolean | Promise<boolean>;
+    /**
+     * Optional whitelist of allowed preset names.
+     */
+    allowedPresets?: TPreset[];
+    /**
+     * Optional CSRF/CORS origin allowlist (`string[]` of origins or predicate).
+     * When set, requests with a missing or disallowed `Origin`/`Referer` are rejected with 403.
+     */
+    allowedOrigins?: string[] | ((origin: string) => boolean);
+    /**
+     * Maximum allowed request body size in bytes (enforced via Content-Length precheck and stream cap).
+     * Defaults to `1.25 × max(preset.maxSizeMB, defaultMaxSizeMB)` (minimum 1 MB when unset).
+     */
+    maxBodyBytes?: number;
+    /**
+     * Opt-in switches for client-supplied FormData overrides. All default to `false` (ignored).
+     */
+    allowClientOverrides?: AllowClientOverrides;
+    /**
+     * Allow clients to override `bucket` via FormData or DELETE query params. Defaults to `false`.
+     */
+    allowClientBucketOverride?: boolean;
+    /**
+     * Optional explicit allowlist of bucket names permitted for upload and delete operations.
+     */
+    allowedBuckets?: string[];
+    /**
+     * Hook invoked when an unexpected 500 internal error occurs. Raw error details are never sent to clients.
+     */
+    onError?: (error: unknown, ctx: UploadErrorContext) => void;
+}
+
+declare class UploadValidationError extends Error {
+    readonly status = 400;
+    constructor(message: string);
+}
+declare function isClientValidationError(error: unknown): boolean;
+
+/**
+ * Standard Web Fetch (`Request` -> `Response`) upload & delete route handlers.
+ * Works across Next.js App Router, Remix, React Router, SvelteKit, Astro, Hono, and Node Fetch servers.
+ */
+declare function createUploadHttpHandler<TPreset extends string = string>(options: UploadHttpHandlerOptions<TPreset>): {
+    POST: (request: Request) => Promise<Response>;
+    DELETE: (request: Request) => Promise<Response>;
+};
+declare const createUploadHandler: typeof createUploadHttpHandler;
+
+export { type AllowClientOverrides as A, type BlurHashResult as B, type ColorSamplingMode as C, DEFAULT_LIMIT_INPUT_PIXELS as D, type EdgeColorSet as E, type GenerateBlurOptions as G, type ImageUploaderOptions as I, type OptimizeImageOptions as O, type ProcessImageBufferOptions as P, RETRY_AVIF_EFFORT as R, type StoragePathGenerator as S, type UploadErrorContext as U, WHITE_DOMINANCE_RATIO as W, type OptimizedImageResult as a, type ProcessedImageBufferResult as b, type ImageUploader as c, type InferredPresetKey as d, type StoragePathContext as e, type GeneratedStorageTarget as f, type AuthorizeContext as g, BLUR_PLACEHOLDER_FALLBACK_WIDTH as h, BLUR_PLACEHOLDER_MAX_CHARS as i, BLUR_PLACEHOLDER_QUALITY as j, BLUR_PLACEHOLDER_WIDTH as k, EDGE_COLOR_FALLBACK as l, EDGE_WHITE_FALLBACK as m, type EdgeKey as n, PRIMARY_AVIF_EFFORT as o, type UploadHttpHandlerOptions as p, UploadValidationError as q, createUploadHandler as r, createUploadHttpHandler as s, isClientValidationError as t };