@socialtip/asset-proxy-url-parser 0.5.0

package/dist/parse.d.ts

@@ -0,0 +1,581 @@
+import { z } from "zod/v4";
+declare const resizingType: z.ZodEnum<{
+    fill: "fill";
+    fit: "fit";
+    "fill-down": "fill-down";
+    force: "force";
+    auto: "auto";
+}>;
+export type ResizingType = z.output<typeof resizingType>;
+declare const cpuAlgorithms: readonly ["nearest", "linear", "cubic", "lanczos2", "lanczos3"];
+declare const gpuScalers: readonly ["scale_cuda", "scale_npp"];
+type CpuAlgorithm = (typeof cpuAlgorithms)[number];
+type GpuScaler = (typeof gpuScalers)[number];
+export type ResizingAlgorithm = {
+    mode: "cpu";
+    algorithm: CpuAlgorithm;
+} | {
+    mode: "gpu";
+    scaler: GpuScaler;
+    algorithm?: CpuAlgorithm;
+};
+declare const videoFormat: z.ZodEnum<{
+    mp4: "mp4";
+    webm: "webm";
+}>;
+declare const imageFormat: z.ZodEnum<{
+    jpg: "jpg";
+    png: "png";
+    webp: "webp";
+    avif: "avif";
+    gif: "gif";
+}>;
+declare const outputFormat: z.ZodUnion<readonly [z.ZodEnum<{
+    mp4: "mp4";
+    webm: "webm";
+}>, z.ZodEnum<{
+    jpg: "jpg";
+    png: "png";
+    webp: "webp";
+    avif: "avif";
+    gif: "gif";
+}>]>;
+export type VideoFormat = z.output<typeof videoFormat>;
+export type ImageFormat = z.output<typeof imageFormat>;
+export type OutputFormat = z.output<typeof outputFormat>;
+export type MediaType = "video" | "image";
+declare const compassGravity: z.ZodEnum<{
+    no: "no";
+    so: "so";
+    ea: "ea";
+    we: "we";
+    noea: "noea";
+    nowe: "nowe";
+    soea: "soea";
+    sowe: "sowe";
+    ce: "ce";
+}>;
+export type CompassGravity = z.output<typeof compassGravity>;
+declare const focusPointGravity: z.ZodObject<{
+    type: z.ZodLiteral<"fp">;
+    x: z.ZodNumber;
+    y: z.ZodNumber;
+}, z.core.$strip>;
+export type FocusPointGravity = z.output<typeof focusPointGravity>;
+declare const gravitySchema: z.ZodUnion<readonly [z.ZodEnum<{
+    no: "no";
+    so: "so";
+    ea: "ea";
+    we: "we";
+    noea: "noea";
+    nowe: "nowe";
+    soea: "soea";
+    sowe: "sowe";
+    ce: "ce";
+}>, z.ZodObject<{
+    type: z.ZodLiteral<"fp">;
+    x: z.ZodNumber;
+    y: z.ZodNumber;
+}, z.core.$strip>]>;
+export type Gravity = z.output<typeof gravitySchema>;
+declare const resizeOptions: z.ZodObject<{
+    type: z.ZodEnum<{
+        fill: "fill";
+        fit: "fit";
+        "fill-down": "fill-down";
+        force: "force";
+        auto: "auto";
+    }>;
+    width: z.ZodNumber;
+    height: z.ZodNumber;
+}, z.core.$strip>;
+export type ResizeOptions = z.output<typeof resizeOptions>;
+export declare const SHORTHANDS: Record<string, string>;
+/** All processing options for an asset-proxy URL. Defined as an explicit interface so JSDoc is preserved in declaration output. */
+export interface ParsedUrlInput {
+    /** Resize dimensions and mode (fit, fill, fill-down, force, auto). */
+    resize?: ResizeOptions;
+    /** Scaling algorithm — CPU interpolation (e.g. lanczos3) or GPU scaler (scale_cuda, scale_npp). */
+    resizingAlgorithm?: ResizingAlgorithm;
+    /** The source image/video URL to process. */
+    sourceUrl: string;
+    /** Output format: jpg, png, webp, avif, gif, mp4, webm. */
+    outputFormat: OutputFormat;
+    /** Minimum output width — upscales if the result would be narrower. */
+    minWidth?: number;
+    /** Minimum output height — upscales if the result would be shorter. */
+    minHeight?: number;
+    /** Pad undersized images to fill the target resize dimensions. */
+    extend?: {
+        enabled: boolean;
+        gravity: CompassGravity;
+    };
+    /** Extend the image to match the target aspect ratio. */
+    extendAspectRatio?: {
+        enabled: boolean;
+        gravity: CompassGravity;
+    };
+    /** Output framerate in fps (video only). */
+    framerate?: number;
+    /** Limit output duration in seconds (video only). */
+    cut?: number;
+    /** Strip audio from video output. */
+    mute?: boolean;
+    /** Remove uniform borders from an image via cropdetect. */
+    trim?: {
+        /** Colour similarity tolerance (0–255). */
+        threshold: number;
+        /** Hex colour to trim. Auto-detected if omitted. */
+        colour?: string;
+        /** Trim equal amounts from left and right. */
+        equalHor: boolean;
+        /** Trim equal amounts from top and bottom. */
+        equalVert: boolean;
+    };
+    /** Brightness adjustment (-255 to 255, 0 = no change). */
+    brightness: number;
+    /** Contrast multiplier (1 = no change). */
+    contrast: number;
+    /** Saturation multiplier (1 = no change). */
+    saturation: number;
+    /** Convert to monochrome with optional intensity and base colour. */
+    monochrome?: {
+        intensity: number;
+        colour: string;
+    };
+    /** Apply duotone effect with two colours. */
+    duotone?: {
+        intensity: number;
+        colour1: string;
+        colour2: string;
+    };
+    /** Output quality 1–100 for lossy formats (JPEG, WebP, AVIF). */
+    quality?: number;
+    /** Per-format quality overrides: { jpg: 80, webp: 90, ... }. */
+    formatQuality?: Record<string, number>;
+    /** Autoquality: dssim (target DSSIM) or size (target bytes). */
+    autoquality?: {
+        method: "dssim" | "size";
+        target: number;
+        min: number;
+        max: number;
+        allowedError: number;
+    };
+    /** Max output size in bytes — degrades quality to fit. */
+    maxBytes?: number;
+    /** JPEG encoder options. */
+    jpegOptions?: {
+        progressive: boolean;
+        noSubsample: boolean;
+        trellisQuant: boolean;
+        overshootDeringing: boolean;
+        optimizeScans: boolean;
+        quantTable?: number;
+    };
+    /** PNG encoder options. */
+    pngOptions?: {
+        interlaced: boolean;
+        quantize: boolean;
+        quantizationColours?: number;
+    };
+    /** WebP encoder options. */
+    webpOptions?: {
+        compression?: number;
+        smartSubsample: boolean;
+        preset?: string;
+    };
+    /** AVIF encoder options. */
+    avifOptions?: {
+        subsample?: string;
+    };
+    /** Gaussian blur sigma. */
+    blur?: number;
+    /** Sharpening sigma. */
+    sharpen?: number;
+    /** Pixelate block size in pixels. */
+    pixelate?: number;
+    /** Unsharp masking: mode (auto/always/none), weight, divider. */
+    unsharpMasking?: {
+        mode: string;
+        weight: number;
+        divider: number;
+    };
+    /** Colour overlay with opacity. */
+    colorize?: {
+        opacity: number;
+        colour: string;
+        keepAlpha: boolean;
+    };
+    /** Gradient overlay from transparent to colour. */
+    gradient?: {
+        opacity: number;
+        colour: string;
+        direction: string;
+        start: number;
+        stop: number;
+    };
+    /** Rotation angle: 0, 90, 180, or 270 degrees. */
+    rotate?: number;
+    /** Flip the image horizontally and/or vertically. */
+    flip?: {
+        horizontal: boolean;
+        vertical: boolean;
+    };
+    /** Rotate based on EXIF orientation data. */
+    autoRotate?: boolean;
+    /** Background colour (RGB) for padding, extend, and alpha flattening. */
+    background?: {
+        r: number;
+        g: number;
+        b: number;
+    };
+    /** Background opacity (0–1). */
+    backgroundAlpha?: number;
+    /** Canvas padding in pixels: top, right, bottom, left. */
+    padding?: {
+        top: number;
+        right: number;
+        bottom: number;
+        left: number;
+    };
+    /** Remove EXIF and other metadata from the output. */
+    stripMetadata?: boolean;
+    /** Preserve copyright metadata when stripping. */
+    keepCopyright?: boolean;
+    /** Convert ICC colour profile to sRGB and remove it. */
+    stripColorProfile?: boolean;
+    /** Output DPI metadata value. */
+    dpi?: number;
+    /** Prefer embedded thumbnail over full image (HEIC/AVIF). */
+    enforceThumbnail?: boolean;
+    /** Extract video frame at this second. */
+    videoThumbnailSecond?: number;
+    /** Use only keyframes for video thumbnails. */
+    videoThumbnailKeyframes?: boolean;
+    /** Video animation config. */
+    videoThumbnailAnimation?: {
+        /** Interval in seconds between sampled video frames (0 = auto). */
+        step: number;
+        /** Delay between animation frames in milliseconds. */
+        delay: number;
+        /** Maximum number of output frames (0 = unlimited). */
+        frames: number;
+        /** Target frame width in pixels (0 = derive from aspect ratio). */
+        frameWidth: number;
+        /** Target frame height in pixels (0 = derive from aspect ratio). */
+        frameHeight: number;
+        /** Pad frames with black to match exact frameWidth/frameHeight. */
+        extendFrame: boolean;
+        /** Remove unused frames from the animation. */
+        trim: boolean;
+        /** Crop-fill to exact frameWidth/frameHeight instead of fitting. */
+        fill: boolean;
+        /** Horizontal crop anchor for fill mode (0–1, default 0.5). */
+        focusX: number;
+        /** Vertical crop anchor for fill mode (0–1, default 0.5). */
+        focusY: number;
+    };
+    /** Extract a region before resizing (width, height, optional gravity). */
+    crop?: {
+        width: number;
+        height: number;
+        gravity?: Gravity;
+    };
+    /** Crop to a target aspect ratio (width/height as a float). */
+    cropAspectRatio?: number;
+    /** Anchor point for crop: compass direction or focus point. */
+    gravity?: Gravity;
+    /** Allow upscaling when the image is smaller than the target. */
+    enlarge?: boolean;
+    /** Automatically select the most efficient output format. */
+    bestFormat?: boolean;
+    /** Skip processing when the source extension matches one of these formats. */
+    skipProcessing?: string[];
+    /** Return the source without any processing. */
+    raw?: boolean;
+    /** Ignored cache-busting value. */
+    cacheBuster?: string;
+    /** Unix timestamp after which the URL returns 404. */
+    expires?: number;
+    /** Override the download filename in Content-Disposition. */
+    filename?: string;
+    /** When true, set Content-Disposition: attachment. */
+    returnAttachment?: boolean;
+    /** Fallback image URL (base64url-encoded) to serve when the source fails. */
+    fallbackImageUrl?: string;
+    /** Expected checksum of the source image. */
+    hashsum?: {
+        type: string;
+        hash: string;
+    };
+    /** Max source resolution in megapixels. */
+    maxSrcResolution?: number;
+    /** Max source file size in bytes. */
+    maxSrcFileSize?: number;
+    /** Max animation frames. */
+    maxAnimationFrames?: number;
+    /** Max animation frame resolution in megapixels. */
+    maxAnimationFrameResolution?: number;
+    /** Max result width or height in pixels. */
+    maxResultDimension?: number;
+}
+/** Zod schema for runtime validation of parsed asset-proxy URL options. The `ParsedUrlInput` interface is the authoritative type definition; this schema validates against it at compile time via `satisfies`. */
+export declare const parsedUrlSchema: z.ZodObject<{
+    resize: z.ZodOptional<z.ZodObject<{
+        type: z.ZodEnum<{
+            fill: "fill";
+            fit: "fit";
+            "fill-down": "fill-down";
+            force: "force";
+            auto: "auto";
+        }>;
+        width: z.ZodNumber;
+        height: z.ZodNumber;
+    }, z.core.$strip>>;
+    resizingAlgorithm: z.ZodOptional<z.ZodUnion<readonly [z.ZodObject<{
+        mode: z.ZodLiteral<"cpu">;
+        algorithm: z.ZodEnum<{
+            nearest: "nearest";
+            linear: "linear";
+            cubic: "cubic";
+            lanczos2: "lanczos2";
+            lanczos3: "lanczos3";
+        }>;
+    }, z.core.$strip>, z.ZodObject<{
+        mode: z.ZodLiteral<"gpu">;
+        scaler: z.ZodEnum<{
+            scale_cuda: "scale_cuda";
+            scale_npp: "scale_npp";
+        }>;
+        algorithm: z.ZodOptional<z.ZodEnum<{
+            nearest: "nearest";
+            linear: "linear";
+            cubic: "cubic";
+            lanczos2: "lanczos2";
+            lanczos3: "lanczos3";
+        }>>;
+    }, z.core.$strip>]>>;
+    sourceUrl: z.ZodString;
+    outputFormat: z.ZodUnion<readonly [z.ZodEnum<{
+        mp4: "mp4";
+        webm: "webm";
+    }>, z.ZodEnum<{
+        jpg: "jpg";
+        png: "png";
+        webp: "webp";
+        avif: "avif";
+        gif: "gif";
+    }>]>;
+    minWidth: z.ZodOptional<z.ZodNumber>;
+    minHeight: z.ZodOptional<z.ZodNumber>;
+    extend: z.ZodOptional<z.ZodObject<{
+        enabled: z.ZodBoolean;
+        gravity: z.ZodEnum<{
+            no: "no";
+            so: "so";
+            ea: "ea";
+            we: "we";
+            noea: "noea";
+            nowe: "nowe";
+            soea: "soea";
+            sowe: "sowe";
+            ce: "ce";
+        }>;
+    }, z.core.$strip>>;
+    extendAspectRatio: z.ZodOptional<z.ZodObject<{
+        enabled: z.ZodBoolean;
+        gravity: z.ZodEnum<{
+            no: "no";
+            so: "so";
+            ea: "ea";
+            we: "we";
+            noea: "noea";
+            nowe: "nowe";
+            soea: "soea";
+            sowe: "sowe";
+            ce: "ce";
+        }>;
+    }, z.core.$strip>>;
+    framerate: z.ZodOptional<z.ZodNumber>;
+    cut: z.ZodOptional<z.ZodNumber>;
+    mute: z.ZodOptional<z.ZodBoolean>;
+    trim: z.ZodOptional<z.ZodObject<{
+        threshold: z.ZodNumber;
+        colour: z.ZodOptional<z.ZodString>;
+        equalHor: z.ZodBoolean;
+        equalVert: z.ZodBoolean;
+    }, z.core.$strip>>;
+    brightness: z.ZodNumber;
+    contrast: z.ZodNumber;
+    saturation: z.ZodNumber;
+    monochrome: z.ZodOptional<z.ZodObject<{
+        intensity: z.ZodNumber;
+        colour: z.ZodString;
+    }, z.core.$strip>>;
+    duotone: z.ZodOptional<z.ZodObject<{
+        intensity: z.ZodNumber;
+        colour1: z.ZodString;
+        colour2: z.ZodString;
+    }, z.core.$strip>>;
+    quality: z.ZodOptional<z.ZodNumber>;
+    formatQuality: z.ZodOptional<z.ZodRecord<z.ZodString, z.ZodNumber>>;
+    autoquality: z.ZodOptional<z.ZodObject<{
+        method: z.ZodEnum<{
+            size: "size";
+            dssim: "dssim";
+        }>;
+        target: z.ZodNumber;
+        min: z.ZodNumber;
+        max: z.ZodNumber;
+        allowedError: z.ZodNumber;
+    }, z.core.$strip>>;
+    maxBytes: z.ZodOptional<z.ZodNumber>;
+    jpegOptions: z.ZodOptional<z.ZodObject<{
+        progressive: z.ZodBoolean;
+        noSubsample: z.ZodBoolean;
+        trellisQuant: z.ZodBoolean;
+        overshootDeringing: z.ZodBoolean;
+        optimizeScans: z.ZodBoolean;
+        quantTable: z.ZodOptional<z.ZodNumber>;
+    }, z.core.$strip>>;
+    pngOptions: z.ZodOptional<z.ZodObject<{
+        interlaced: z.ZodBoolean;
+        quantize: z.ZodBoolean;
+        quantizationColours: z.ZodOptional<z.ZodNumber>;
+    }, z.core.$strip>>;
+    webpOptions: z.ZodOptional<z.ZodObject<{
+        compression: z.ZodOptional<z.ZodNumber>;
+        smartSubsample: z.ZodBoolean;
+        preset: z.ZodOptional<z.ZodString>;
+    }, z.core.$strip>>;
+    avifOptions: z.ZodOptional<z.ZodObject<{
+        subsample: z.ZodOptional<z.ZodString>;
+    }, z.core.$strip>>;
+    blur: z.ZodOptional<z.ZodNumber>;
+    sharpen: z.ZodOptional<z.ZodNumber>;
+    pixelate: z.ZodOptional<z.ZodNumber>;
+    unsharpMasking: z.ZodOptional<z.ZodObject<{
+        mode: z.ZodString;
+        weight: z.ZodNumber;
+        divider: z.ZodNumber;
+    }, z.core.$strip>>;
+    colorize: z.ZodOptional<z.ZodObject<{
+        opacity: z.ZodNumber;
+        colour: z.ZodString;
+        keepAlpha: z.ZodBoolean;
+    }, z.core.$strip>>;
+    gradient: z.ZodOptional<z.ZodObject<{
+        opacity: z.ZodNumber;
+        colour: z.ZodString;
+        direction: z.ZodString;
+        start: z.ZodNumber;
+        stop: z.ZodNumber;
+    }, z.core.$strip>>;
+    rotate: z.ZodOptional<z.ZodNumber>;
+    flip: z.ZodOptional<z.ZodObject<{
+        horizontal: z.ZodBoolean;
+        vertical: z.ZodBoolean;
+    }, z.core.$strip>>;
+    autoRotate: z.ZodOptional<z.ZodBoolean>;
+    background: z.ZodOptional<z.ZodObject<{
+        r: z.ZodNumber;
+        g: z.ZodNumber;
+        b: z.ZodNumber;
+    }, z.core.$strip>>;
+    backgroundAlpha: z.ZodOptional<z.ZodNumber>;
+    padding: z.ZodOptional<z.ZodObject<{
+        top: z.ZodNumber;
+        right: z.ZodNumber;
+        bottom: z.ZodNumber;
+        left: z.ZodNumber;
+    }, z.core.$strip>>;
+    stripMetadata: z.ZodOptional<z.ZodBoolean>;
+    keepCopyright: z.ZodOptional<z.ZodBoolean>;
+    stripColorProfile: z.ZodOptional<z.ZodBoolean>;
+    dpi: z.ZodOptional<z.ZodNumber>;
+    enforceThumbnail: z.ZodOptional<z.ZodBoolean>;
+    videoThumbnailSecond: z.ZodOptional<z.ZodNumber>;
+    videoThumbnailKeyframes: z.ZodOptional<z.ZodBoolean>;
+    videoThumbnailAnimation: z.ZodOptional<z.ZodObject<{
+        step: z.ZodNumber;
+        delay: z.ZodNumber;
+        frames: z.ZodNumber;
+        frameWidth: z.ZodNumber;
+        frameHeight: z.ZodNumber;
+        extendFrame: z.ZodBoolean;
+        trim: z.ZodBoolean;
+        fill: z.ZodBoolean;
+        focusX: z.ZodNumber;
+        focusY: z.ZodNumber;
+    }, z.core.$strip>>;
+    crop: z.ZodOptional<z.ZodObject<{
+        width: z.ZodNumber;
+        height: z.ZodNumber;
+        gravity: z.ZodOptional<z.ZodUnion<readonly [z.ZodEnum<{
+            no: "no";
+            so: "so";
+            ea: "ea";
+            we: "we";
+            noea: "noea";
+            nowe: "nowe";
+            soea: "soea";
+            sowe: "sowe";
+            ce: "ce";
+        }>, z.ZodObject<{
+            type: z.ZodLiteral<"fp">;
+            x: z.ZodNumber;
+            y: z.ZodNumber;
+        }, z.core.$strip>]>>;
+    }, z.core.$strip>>;
+    cropAspectRatio: z.ZodOptional<z.ZodNumber>;
+    gravity: z.ZodOptional<z.ZodUnion<readonly [z.ZodEnum<{
+        no: "no";
+        so: "so";
+        ea: "ea";
+        we: "we";
+        noea: "noea";
+        nowe: "nowe";
+        soea: "soea";
+        sowe: "sowe";
+        ce: "ce";
+    }>, z.ZodObject<{
+        type: z.ZodLiteral<"fp">;
+        x: z.ZodNumber;
+        y: z.ZodNumber;
+    }, z.core.$strip>]>>;
+    enlarge: z.ZodOptional<z.ZodBoolean>;
+    bestFormat: z.ZodOptional<z.ZodBoolean>;
+    skipProcessing: z.ZodOptional<z.ZodArray<z.ZodString>>;
+    raw: z.ZodOptional<z.ZodBoolean>;
+    cacheBuster: z.ZodOptional<z.ZodString>;
+    expires: z.ZodOptional<z.ZodNumber>;
+    filename: z.ZodOptional<z.ZodString>;
+    returnAttachment: z.ZodOptional<z.ZodBoolean>;
+    fallbackImageUrl: z.ZodOptional<z.ZodString>;
+    hashsum: z.ZodOptional<z.ZodObject<{
+        type: z.ZodString;
+        hash: z.ZodString;
+    }, z.core.$strip>>;
+    maxSrcResolution: z.ZodOptional<z.ZodNumber>;
+    maxSrcFileSize: z.ZodOptional<z.ZodNumber>;
+    maxAnimationFrames: z.ZodOptional<z.ZodNumber>;
+    maxAnimationFrameResolution: z.ZodOptional<z.ZodNumber>;
+    maxResultDimension: z.ZodOptional<z.ZodNumber>;
+}, z.core.$strip>;
+/** Fully parsed URL with all processing options validated. */
+export type ParsedUrl = z.output<typeof parsedUrlSchema>;
+export type ImageUrl = ParsedUrl & {
+    outputFormat: ImageFormat;
+};
+export type VideoUrl = ParsedUrl & {
+    outputFormat: VideoFormat;
+};
+export declare function isImageUrl(parsed: ParsedUrl): parsed is ImageUrl;
+export declare function isVideoUrl(parsed: ParsedUrl): parsed is VideoUrl;
+export interface ParseOptions {
+    /** AES-256-CBC key for decrypting `/enc/` source URLs. */
+    encryptionKey?: Buffer;
+}
+/** Parses an imgproxy-format processing path (after signature has been stripped). Supports `/<options>/plain/<source_url>[@<format>]` and `/<options>/enc/<encrypted_source_url>[@<format>]`. */
+export declare function parseProcessingUrl(path: string, options?: ParseOptions): ParsedUrl;
+export {};