@socialtip/asset-proxy-url-generator 0.5.0

package/README.md

@@ -0,0 +1,50 @@
+# @socialtip/asset-proxy-url-generator
+
+Generate [asset-proxy](../../README.md)-compatible URL paths programmatically, with optional source URL encryption and HMAC signing.
+
+## Installation
+
+```bash
+npm install @socialtip/asset-proxy-url-generator
+```
+
+## Usage
+
+```ts
+import { generateUrl } from "@socialtip/asset-proxy-url-generator";
+
+const url = generateUrl({
+  sourceUrl: "https://example.com/photo.jpg",
+  outputFormat: "webp",
+  resize: { type: "fill", width: 480, height: 360 },
+  quality: 80,
+});
+// => /_/rs:fill:480:360/q:80/plain/https://example.com/photo.jpg@webp
+```
+
+### Encrypted source URLs
+
+```ts
+const url = generateUrl(
+  { sourceUrl: "https://example.com/photo.jpg", outputFormat: "webp" },
+  { encryptionKey: "0123456789abcdef..." }, // hex-encoded 32-byte key
+);
+// => /_/enc/dGhpcyBpcy...@webp
+```
+
+### Signed URLs
+
+```ts
+const url = generateUrl(
+  { sourceUrl: "https://example.com/photo.jpg" },
+  {
+    signingKey: "...", // hex-encoded HMAC key
+    signingSalt: "...", // hex-encoded salt
+  },
+);
+// => /oKfUtW34Dvo.../plain/https://example.com/photo.jpg
+```
+
+### All options
+
+The `generateUrl` function accepts all processing options from the asset-proxy URL schema. See the [full options reference](../../README.md#processing-options) for details.

package/dist/index.d.ts

@@ -0,0 +1,25 @@
+import { type ParsedUrlInput, type InfoOptions } from "@socialtip/asset-proxy-url-parser";
+export type { ParsedUrlInput, InfoOptions, } from "@socialtip/asset-proxy-url-parser";
+/** Options for generating a URL, derived from the asset-proxy parsed URL schema. All fields except `sourceUrl` are optional. */
+export type UrlGeneratorOptions = Partial<ParsedUrlInput> & {
+    sourceUrl: string;
+};
+/** Configuration for URL encryption and signing. */
+export interface UrlGeneratorConfig {
+    /** Hex-encoded 32-byte AES-256-CBC key for encrypting the source URL. When set, the source URL is encrypted and the `/enc/` prefix is used. */
+    encryptionKey?: string;
+    /** When true (and `encryptionKey` is set), derives the encryption IV from the source URL instead of using random bytes. This makes the generated URL deterministic for the same input, which is useful when URLs need to be stable for caching purposes. */
+    deterministicEncryption?: boolean;
+    /** Hex-encoded HMAC-SHA256 key for URL signing. Must be set together with `signingSalt`. */
+    signingKey?: string;
+    /** Hex-encoded salt prepended to the path before HMAC signing. Must be set together with `signingKey`. */
+    signingSalt?: string;
+}
+/** Generates an asset-proxy-compatible URL path. */
+export declare function generateUrl(options: UrlGeneratorOptions, config?: UrlGeneratorConfig): string;
+/** Options for generating an info URL. Only `sourceUrl` is required; security options (encryption, signing) come from the config. */
+export interface InfoUrlOptions {
+    sourceUrl: string;
+}
+/** Generates an asset-proxy info URL path that returns JSON metadata about the source asset. */
+export declare function generateInfoUrl(options: InfoUrlOptions, config?: UrlGeneratorConfig, infoOptions?: InfoOptions): string;

package/dist/index.js

@@ -0,0 +1,314 @@
+import { encryptSourceUrl, sign, SHORTHANDS, } from "@socialtip/asset-proxy-url-parser";
+/** Generates an asset-proxy-compatible URL path. */
+export function generateUrl(options, config) {
+    const segments = serializeOptions(options);
+    segments.sort((a, b) => {
+        const keyA = SHORTHANDS[a.slice(0, a.indexOf(":"))] ?? a;
+        const keyB = SHORTHANDS[b.slice(0, b.indexOf(":"))] ?? b;
+        return keyA < keyB ? -1 : keyA > keyB ? 1 : 0;
+    });
+    let sourceUrlPart;
+    if (config?.encryptionKey) {
+        const key = Buffer.from(config.encryptionKey, "hex");
+        sourceUrlPart = `enc/${encryptSourceUrl(options.sourceUrl, key, { deterministic: config.deterministicEncryption })}`;
+    }
+    else {
+        sourceUrlPart = `plain/${options.sourceUrl}`;
+    }
+    const optionsPath = segments.length > 0 ? segments.join("/") + "/" : "";
+    const pathAfterSignature = `/${optionsPath}${sourceUrlPart}`;
+    let signature = "insecure";
+    if (config?.signingKey && config?.signingSalt) {
+        signature = sign(pathAfterSignature, Buffer.from(config.signingKey, "hex"), Buffer.from(config.signingSalt, "hex"));
+    }
+    return `/${signature}${pathAfterSignature}`;
+}
+/** Generates an asset-proxy info URL path that returns JSON metadata about the source asset. */
+export function generateInfoUrl(options, config, infoOptions) {
+    const infoSegments = serializeInfoOptions(infoOptions);
+    const infoPath = infoSegments.length > 0 ? infoSegments.join("/") + "/" : "";
+    let sourceUrlPart;
+    if (config?.encryptionKey) {
+        const key = Buffer.from(config.encryptionKey, "hex");
+        sourceUrlPart = `enc/${encryptSourceUrl(options.sourceUrl, key, { deterministic: config.deterministicEncryption })}`;
+    }
+    else {
+        sourceUrlPart = `plain/${options.sourceUrl}`;
+    }
+    const pathAfterSignature = `/${infoPath}${sourceUrlPart}`;
+    let signature = "insecure";
+    if (config?.signingKey && config?.signingSalt) {
+        signature = sign(pathAfterSignature, Buffer.from(config.signingKey, "hex"), Buffer.from(config.signingSalt, "hex"));
+    }
+    return `/info/${signature}${pathAfterSignature}`;
+}
+function serializeInfoOptions(options) {
+    if (!options)
+        return [];
+    const segments = [];
+    if (options.exif)
+        segments.push("exif:t");
+    if (options.iptc)
+        segments.push("iptc:t");
+    if (options.xmp)
+        segments.push("xmp:t");
+    if (options.colorspace)
+        segments.push("cs:t");
+    if (options.bands)
+        segments.push("b:t");
+    if (options.sampleFormat)
+        segments.push("sf:t");
+    if (options.pagesNumber)
+        segments.push("pn:t");
+    if (options.alpha)
+        segments.push("a:t");
+    if (options.palette)
+        segments.push(`p:${options.palette}`);
+    if (options.average) {
+        let seg = "avg:t";
+        if (options.average.ignoreTransparent)
+            seg += ":t";
+        segments.push(seg);
+    }
+    if (options.dominantColors)
+        segments.push("dc:t");
+    if (options.blurhash)
+        segments.push(`bh:${options.blurhash.xComponents}:${options.blurhash.yComponents}`);
+    if (options.calcHashsums?.length)
+        segments.push(`chs:${options.calcHashsums.join(":")}`);
+    if (options.page !== undefined)
+        segments.push(`pg:${options.page}`);
+    return segments;
+}
+function bool(v) {
+    return v ? "1" : "0";
+}
+function serializeGravity(g) {
+    if (typeof g === "string")
+        return g;
+    return `fp:${g.x}:${g.y}`;
+}
+function serializeOptions(options) {
+    const segments = [];
+    if (options.outputFormat)
+        segments.push(`f:${options.outputFormat}`);
+    if (options.resize) {
+        segments.push(`rs:${options.resize.type}:${options.resize.width}:${options.resize.height}`);
+    }
+    if (options.resizingAlgorithm) {
+        const ra = options.resizingAlgorithm;
+        if (ra.mode === "cpu") {
+            segments.push(`ra:${ra.algorithm}`);
+        }
+        else {
+            let s = `ra:gpu:${ra.scaler}`;
+            if (ra.algorithm)
+                s += `:${ra.algorithm}`;
+            segments.push(s);
+        }
+    }
+    if (options.minWidth !== undefined)
+        segments.push(`mw:${options.minWidth}`);
+    if (options.minHeight !== undefined)
+        segments.push(`mh:${options.minHeight}`);
+    if (options.enlarge !== undefined)
+        segments.push(`el:${bool(options.enlarge)}`);
+    if (options.extend) {
+        segments.push(`ex:${bool(options.extend.enabled)}:${options.extend.gravity}`);
+    }
+    if (options.extendAspectRatio) {
+        segments.push(`exar:${bool(options.extendAspectRatio.enabled)}:${options.extendAspectRatio.gravity}`);
+    }
+    if (options.crop) {
+        let s = `c:${options.crop.width}:${options.crop.height}`;
+        if (options.crop.gravity)
+            s += `:${serializeGravity(options.crop.gravity)}`;
+        segments.push(s);
+    }
+    if (options.cropAspectRatio !== undefined) {
+        segments.push(`car:${options.cropAspectRatio}:1`);
+    }
+    if (options.gravity) {
+        segments.push(`g:${serializeGravity(options.gravity)}`);
+    }
+    if (options.quality !== undefined)
+        segments.push(`q:${options.quality}`);
+    if (options.formatQuality) {
+        const parts = Object.entries(options.formatQuality).flatMap(([fmt, q]) => [
+            fmt,
+            String(q),
+        ]);
+        segments.push(`fq:${parts.join(":")}`);
+    }
+    if (options.autoquality) {
+        const aq = options.autoquality;
+        segments.push(`aq:${aq.method}:${aq.target}:${aq.min}:${aq.max}:${aq.allowedError}`);
+    }
+    if (options.maxBytes !== undefined)
+        segments.push(`mb:${options.maxBytes}`);
+    if (options.blur !== undefined)
+        segments.push(`bl:${options.blur}`);
+    if (options.sharpen !== undefined)
+        segments.push(`sh:${options.sharpen}`);
+    if (options.pixelate !== undefined)
+        segments.push(`px:${options.pixelate}`);
+    if (options.unsharpMasking) {
+        const u = options.unsharpMasking;
+        segments.push(`ush:${u.mode}:${u.weight}:${u.divider}`);
+    }
+    if (options.brightness !== undefined && options.brightness !== 0) {
+        segments.push(`br:${options.brightness}`);
+    }
+    if (options.contrast !== undefined && options.contrast !== 1) {
+        segments.push(`co:${options.contrast}`);
+    }
+    if (options.saturation !== undefined && options.saturation !== 1) {
+        segments.push(`sa:${options.saturation}`);
+    }
+    if (options.monochrome) {
+        segments.push(`mc:${options.monochrome.intensity}:${options.monochrome.colour}`);
+    }
+    if (options.duotone) {
+        segments.push(`dt:${options.duotone.intensity}:${options.duotone.colour1}:${options.duotone.colour2}`);
+    }
+    if (options.colorize) {
+        const c = options.colorize;
+        segments.push(`clrz:${c.opacity}:${c.colour}:${bool(c.keepAlpha)}`);
+    }
+    if (options.gradient) {
+        const g = options.gradient;
+        segments.push(`grd:${g.opacity}:${g.colour}:${g.direction}:${g.start}:${g.stop}`);
+    }
+    if (options.rotate !== undefined)
+        segments.push(`rot:${options.rotate}`);
+    if (options.flip) {
+        segments.push(`fl:${bool(options.flip.horizontal)}:${bool(options.flip.vertical)}`);
+    }
+    if (options.autoRotate !== undefined) {
+        segments.push(`ar:${bool(options.autoRotate)}`);
+    }
+    if (options.background) {
+        segments.push(`bg:${options.background.r}:${options.background.g}:${options.background.b}`);
+    }
+    if (options.backgroundAlpha !== undefined) {
+        segments.push(`bga:${options.backgroundAlpha}`);
+    }
+    if (options.padding) {
+        const p = options.padding;
+        segments.push(`pd:${p.top}:${p.right}:${p.bottom}:${p.left}`);
+    }
+    if (options.stripMetadata !== undefined) {
+        segments.push(`sm:${bool(options.stripMetadata)}`);
+    }
+    if (options.keepCopyright !== undefined) {
+        segments.push(`kcr:${bool(options.keepCopyright)}`);
+    }
+    if (options.stripColorProfile !== undefined) {
+        segments.push(`scp:${bool(options.stripColorProfile)}`);
+    }
+    if (options.dpi !== undefined)
+        segments.push(`dpi:${options.dpi}`);
+    if (options.enforceThumbnail !== undefined) {
+        segments.push(`eth:${bool(options.enforceThumbnail)}`);
+    }
+    if (options.framerate !== undefined)
+        segments.push(`fr:${options.framerate}`);
+    if (options.cut !== undefined)
+        segments.push(`ct:${options.cut}`);
+    if (options.mute !== undefined)
+        segments.push(`mu:${bool(options.mute)}`);
+    if (options.trim) {
+        const parts = [String(options.trim.threshold)];
+        if (options.trim.colour !== undefined ||
+            options.trim.equalHor ||
+            options.trim.equalVert) {
+            parts.push(options.trim.colour ?? "");
+        }
+        if (options.trim.equalHor || options.trim.equalVert) {
+            parts.push(bool(options.trim.equalHor), bool(options.trim.equalVert));
+        }
+        segments.push(`tr:${parts.join(":")}`);
+    }
+    if (options.videoThumbnailSecond !== undefined) {
+        segments.push(`vts:${options.videoThumbnailSecond}`);
+    }
+    if (options.videoThumbnailKeyframes !== undefined) {
+        segments.push(`vtk:${bool(options.videoThumbnailKeyframes)}`);
+    }
+    if (options.videoThumbnailAnimation) {
+        const v = options.videoThumbnailAnimation;
+        let vtaStr = `vta:${v.step}:${v.delay}:${v.frames}:${v.frameWidth}:${v.frameHeight}`;
+        if (v.fill ||
+            v.extendFrame ||
+            v.trim ||
+            (v.focusX !== undefined && v.focusX !== 0.5) ||
+            (v.focusY !== undefined && v.focusY !== 0.5)) {
+            vtaStr += `:${bool(v.extendFrame ?? false)}:${bool(v.trim ?? false)}:${bool(v.fill ?? false)}:${v.focusX ?? 0.5}:${v.focusY ?? 0.5}`;
+        }
+        segments.push(vtaStr);
+    }
+    if (options.jpegOptions) {
+        const j = options.jpegOptions;
+        let s = `jpgo:${bool(j.progressive)}:${bool(j.noSubsample)}:${bool(j.trellisQuant)}:${bool(j.overshootDeringing)}:${bool(j.optimizeScans)}`;
+        if (j.quantTable !== undefined)
+            s += `:${j.quantTable}`;
+        segments.push(s);
+    }
+    if (options.pngOptions) {
+        const p = options.pngOptions;
+        let s = `pngo:${bool(p.interlaced)}:${bool(p.quantize)}`;
+        if (p.quantizationColours !== undefined)
+            s += `:${p.quantizationColours}`;
+        segments.push(s);
+    }
+    if (options.webpOptions) {
+        const w = options.webpOptions;
+        let s = `wpo:${w.compression ?? ""}:${bool(w.smartSubsample)}`;
+        if (w.preset)
+            s += `:${w.preset}`;
+        segments.push(s);
+    }
+    if (options.avifOptions?.subsample) {
+        segments.push(`avo:${options.avifOptions.subsample}`);
+    }
+    if (options.skipProcessing?.length) {
+        segments.push(`skp:${options.skipProcessing.join(":")}`);
+    }
+    if (options.raw !== undefined)
+        segments.push(`raw:${bool(options.raw)}`);
+    if (options.cacheBuster !== undefined) {
+        segments.push(`cb:${options.cacheBuster}`);
+    }
+    if (options.expires !== undefined)
+        segments.push(`exp:${options.expires}`);
+    if (options.filename !== undefined)
+        segments.push(`fn:${options.filename}`);
+    if (options.returnAttachment !== undefined) {
+        segments.push(`att:${bool(options.returnAttachment)}`);
+    }
+    if (options.fallbackImageUrl !== undefined) {
+        segments.push(`fiu:${options.fallbackImageUrl}`);
+    }
+    if (options.hashsum) {
+        segments.push(`hs:${options.hashsum.type}:${options.hashsum.hash}`);
+    }
+    if (options.maxSrcResolution !== undefined) {
+        segments.push(`msr:${options.maxSrcResolution}`);
+    }
+    if (options.maxSrcFileSize !== undefined) {
+        segments.push(`msfs:${options.maxSrcFileSize}`);
+    }
+    if (options.maxAnimationFrames !== undefined) {
+        segments.push(`maf:${options.maxAnimationFrames}`);
+    }
+    if (options.maxAnimationFrameResolution !== undefined) {
+        segments.push(`mafr:${options.maxAnimationFrameResolution}`);
+    }
+    if (options.maxResultDimension !== undefined) {
+        segments.push(`mrd:${options.maxResultDimension}`);
+    }
+    if (options.bestFormat) {
+        segments.push("f:best");
+    }
+    return segments;
+}

package/package.json

@@ -0,0 +1,37 @@
+{
+  "name": "@socialtip/asset-proxy-url-generator",
+  "version": "0.5.0",
+  "description": "Generate asset-proxy-compatible URL paths with optional encryption and signing",
+  "type": "module",
+  "main": "dist/index.js",
+  "types": "dist/index.d.ts",
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "import": "./dist/index.js"
+    }
+  },
+  "files": [
+    "dist"
+  ],
+  "scripts": {
+    "build": "tsc -p tsconfig.build.json",
+    "typecheck": "tsc --noEmit",
+    "test": "vitest run"
+  },
+  "dependencies": {
+    "@socialtip/asset-proxy-url-parser": "workspace:*"
+  },
+  "devDependencies": {
+    "@imgproxy/imgproxy-node": "^1.1.0",
+    "@types/node": "^25.5.0",
+    "typescript": "^5.9.3",
+    "vitest": "^4.1.0"
+  },
+  "license": "UNLICENSED",
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/SocialTip/asset-proxy.git",
+    "directory": "packages/url-generator"
+  }
+}