@transloadit/utils 4.6.0 → 4.7.1

package/README.md

@@ -14,7 +14,14 @@ Everything in the root export runs on WebCrypto, so it works in browsers (secure
 `https://` or `localhost`), edge runtimes, and Node.
 
 ```ts
-import { getSignedSmartCdnUrl, signParams, verifyWebhookSignature } from '@transloadit/utils'
+import {
+  getSignedSmartCdnUrl,
+  getSmartCdnUrl,
+  parseSmartCdnUrl,
+  signParams,
+  stripSmartCdnAuth,
+  verifyWebhookSignature,
+} from '@transloadit/utils'
 
 const signature = await signParams(paramsString, authSecret)
 const verified = await verifyWebhookSignature({
@@ -31,6 +38,32 @@ const url = await getSignedSmartCdnUrl({
 })
 ```
 
+### Smart CDN URL grammar
+
+The URL builders and parser share one grammar, so a URL built here parses back into the options
+that built it (and vice versa):
+
+```ts
+// Unsigned, for workspaces that do not require signature authentication.
+const publicUrl = getSmartCdnUrl({ workspace, template, input, urlParams: { w: 640 } })
+
+// Inverse of the builders: percent-decodes once, keeps repeated params as arrays,
+// and returns `auth_key`/`exp`/`sig` separately as `auth`.
+const { workspace, template, input, urlParams, auth } = parseSmartCdnUrl(url)
+
+// Drops `auth_key`, `exp`, `sig` (and api2's `hsh`), leaving every other byte untouched.
+const unsigned = stripSmartCdnAuth(url)
+```
+
+`auth_key`, `exp`, and `sig` are reserved: signed builders replace them and the unsigned builder
+omits them. Other fields, including `hsh`, round-trip through the builders and parser.
+
+Both builders accept a `baseUrl` that replaces `https://{workspace}.tlcdn.com`, for example a local
+api2's URL Transform endpoint `https://api2-devdock.transloadit.dev/file/{workspace}` (a literal
+`{workspace}` is substituted). The signature does not cover the host, so treat `baseUrl` as trusted
+configuration and never derive it from user input. Pass the same `baseUrl` to `parseSmartCdnUrl` to
+parse URLs built with it.
+
 ## Node usage
 
 ```ts
@@ -53,7 +86,12 @@ const imageCandidates = getSignedSmartCdnImageCandidates({
   authSecret,
   // Reuse one absolute expiry across a build instead of recomputing it per request.
   expiresAt,
-  input: 'https://example.com/image.jpg',
+  // The browser fallback is independent from the Template's input grammar.
+  fallbackUrl: '/images/photo.jpg',
+  // This workspace Template pins https://example.com/ and accepts a relative path.
+  input: 'images/photo.jpg',
+  sourceDimensions: { height: 1600, width: 2400 },
+  template: 'website-images',
   widths: [320, 640, 960],
   workspace,
 })
@@ -70,7 +108,20 @@ for (const source of imageCandidates.sources) {
 - `verifyWebhookSignature({ rawBody, signatureHeader, authSecret })`: validates webhook signatures.
 - `getSignedSmartCdnUrl(options)`: async, WebCrypto-based Smart CDN URL signer. Byte-identical to
   the Node variant below.
+- `getSmartCdnUrl(options)`: unsigned Smart CDN URL builder (same options minus credentials/expiry).
+- `parseSmartCdnUrl(url, { baseUrl?, workspace? })`: parses a Smart CDN URL into
+  `{ workspace, template, input, urlParams, auth?, baseUrl? }`; throws on anything else.
+- `stripSmartCdnAuth(url)`: removes the signature parameters, byte-for-byte otherwise.
+- `baseUrl` (option of both builders): trusted replacement for `https://{workspace}.tlcdn.com`.
 - `signParamsSync(paramsString, authSecret, algorithm?)`: Node-only sync signature helper.
 - `getSignedSmartCdnUrl(options)` from `@transloadit/utils/node`: synchronous Smart CDN URL signer.
 - `getSignedSmartCdnImageCandidates(options)`: deterministic structured, signed AVIF and WebP
-  candidates plus the original fallback URL.
+  candidates plus an explicit browser fallback. `template` is mandatory: use a trusted workspace
+  Template that owns its source policy. `fallbackUrl` is deliberately separate from `input`, which
+  may use a Template-specific grammar such as a relative origin-pinned path. Supply
+  `sourceDimensions` to prevent upscaling and keep both output dimensions within backend limits.
+- `createSmartCdnImageCandidates(options, sign)` from `@transloadit/utils`: the same deterministic
+  image policy with an injected synchronous signer, for framework and package adapters that own
+  their credential boundary.
+- `resolveSmartCdnImageFormats(formats)` and `resolveSmartCdnImageWidths(widths, maximumWidth?)`:
+  shared validation and normalization for adapters that use a different image Built-in.

package/dist/index.d.ts

@@ -1,7 +1,10 @@
 import type { SmartCdnUrlOptions } from './smartCdn.ts';
 export type SignatureAlgorithm = 'sha1' | 'sha256' | 'sha384' | 'sha512';
-export type { SmartCdnUrlOptions } from './smartCdn.ts';
+export type { ParsedSmartCdnUrl, ParseSmartCdnUrlOptions, SmartCdnUnsignedUrlOptions, SmartCdnUrlOptions, SmartCdnUrlParams, } from './smartCdn.ts';
+export type { SignSmartCdnImageRequest, SmartCdnImageCandidate, SmartCdnImageCandidates, SmartCdnImageFormat, SmartCdnImageFormatQuality, SmartCdnImageFormats, SmartCdnImagePolicyOptions, SmartCdnImageSignRequest, SmartCdnImageSource, SmartCdnImageSourceDimensions, } from './smartCdnImage.ts';
 export * from './assemblyInstructionsCompiler.ts';
+export { getSmartCdnUrl, parseSmartCdnUrl, stripSmartCdnAuth } from './smartCdn.ts';
+export { createSmartCdnImageCandidates, resolveSmartCdnImageFormats, resolveSmartCdnImageWidths, smartCdnImageMaxDimension, } from './smartCdnImage.ts';
 export declare const signParams: (paramsString: string, authSecret: string, algorithm?: SignatureAlgorithm) => Promise<string>;
 export type VerifyWebhookSignatureOptions = {
     rawBody: string;

package/dist/index.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,kBAAkB,EAAE,MAAM,eAAe,CAAA;AAIvD,MAAM,MAAM,kBAAkB,GAAG,MAAM,GAAG,QAAQ,GAAG,QAAQ,GAAG,QAAQ,CAAA;AAExE,YAAY,EAAE,kBAAkB,EAAE,MAAM,eAAe,CAAA;AAEvD,cAAc,mCAAmC,CAAA;AAqDjD,eAAO,MAAM,UAAU,GACrB,cAAc,MAAM,EACpB,YAAY,MAAM,EAClB,YAAW,kBAA6B,KACvC,OAAO,CAAC,MAAM,CAOhB,CAAA;AAED,MAAM,MAAM,6BAA6B,GAAG;IAC1C,OAAO,EAAE,MAAM,CAAA;IACf,eAAe,CAAC,EAAE,MAAM,CAAA;IACxB,UAAU,EAAE,MAAM,CAAA;CACnB,CAAA;AAED,eAAO,MAAM,sBAAsB,GACjC,SAAS,6BAA6B,KACrC,OAAO,CAAC,OAAO,CAkBjB,CAAA;AAED;;;GAGG;AACH,eAAO,MAAM,oBAAoB,GAAU,MAAM,kBAAkB,KAAG,OAAO,CAAC,MAAM,CAInF,CAAA"}
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,kBAAkB,EAAE,MAAM,eAAe,CAAA;AAIvD,MAAM,MAAM,kBAAkB,GAAG,MAAM,GAAG,QAAQ,GAAG,QAAQ,GAAG,QAAQ,CAAA;AAExE,YAAY,EACV,iBAAiB,EACjB,uBAAuB,EACvB,0BAA0B,EAC1B,kBAAkB,EAClB,iBAAiB,GAClB,MAAM,eAAe,CAAA;AACtB,YAAY,EACV,wBAAwB,EACxB,sBAAsB,EACtB,uBAAuB,EACvB,mBAAmB,EACnB,0BAA0B,EAC1B,oBAAoB,EACpB,0BAA0B,EAC1B,wBAAwB,EACxB,mBAAmB,EACnB,6BAA6B,GAC9B,MAAM,oBAAoB,CAAA;AAE3B,cAAc,mCAAmC,CAAA;AACjD,OAAO,EAAE,cAAc,EAAE,gBAAgB,EAAE,iBAAiB,EAAE,MAAM,eAAe,CAAA;AACnF,OAAO,EACL,6BAA6B,EAC7B,2BAA2B,EAC3B,0BAA0B,EAC1B,yBAAyB,GAC1B,MAAM,oBAAoB,CAAA;AAqD3B,eAAO,MAAM,UAAU,GACrB,cAAc,MAAM,EACpB,YAAY,MAAM,EAClB,YAAW,kBAA6B,KACvC,OAAO,CAAC,MAAM,CAOhB,CAAA;AAED,MAAM,MAAM,6BAA6B,GAAG;IAC1C,OAAO,EAAE,MAAM,CAAA;IACf,eAAe,CAAC,EAAE,MAAM,CAAA;IACxB,UAAU,EAAE,MAAM,CAAA;CACnB,CAAA;AAED,eAAO,MAAM,sBAAsB,GACjC,SAAS,6BAA6B,KACrC,OAAO,CAAC,OAAO,CAkBjB,CAAA;AAED;;;GAGG;AACH,eAAO,MAAM,oBAAoB,GAAU,MAAM,kBAAkB,KAAG,OAAO,CAAC,MAAM,CAInF,CAAA"}

package/dist/index.js

@@ -1,5 +1,7 @@
 import { finishSmartCdnUrl, prepareSmartCdnUrl } from "./smartCdn.js";
 export * from "./assemblyInstructionsCompiler.js";
+export { getSmartCdnUrl, parseSmartCdnUrl, stripSmartCdnAuth } from "./smartCdn.js";
+export { createSmartCdnImageCandidates, resolveSmartCdnImageFormats, resolveSmartCdnImageWidths, smartCdnImageMaxDimension, } from "./smartCdnImage.js";
 const algorithmMap = {
     sha1: 'SHA-1',
     sha256: 'SHA-256',

package/dist/node.d.ts

@@ -1,42 +1,18 @@
 import type { SignatureAlgorithm } from './index.ts';
 import type { SmartCdnUrlOptions } from './smartCdn.ts';
+import type { SmartCdnImageCandidates, SmartCdnImagePolicyOptions } from './smartCdnImage.ts';
 export type { SignatureAlgorithm } from './index.ts';
-export type { SmartCdnUrlOptions } from './smartCdn.ts';
+export type { ParsedSmartCdnUrl, ParseSmartCdnUrlOptions, SmartCdnUnsignedUrlOptions, SmartCdnUrlOptions, SmartCdnUrlParams, } from './smartCdn.ts';
+export type { SignSmartCdnImageRequest, SmartCdnImageCandidate, SmartCdnImageCandidates, SmartCdnImageFormat, SmartCdnImageFormatQuality, SmartCdnImageFormats, SmartCdnImagePolicyOptions, SmartCdnImageSignRequest, SmartCdnImageSource, SmartCdnImageSourceDimensions, } from './smartCdnImage.ts';
+export { getSmartCdnUrl, parseSmartCdnUrl, stripSmartCdnAuth } from './smartCdn.ts';
+export { resolveSmartCdnImageFormats, resolveSmartCdnImageWidths, smartCdnImageMaxDimension, } from './smartCdnImage.ts';
 export type SignatureAlgorithmInput = SignatureAlgorithm | (string & {});
-/** Image formats supported by the responsive-image Built-in. */
-export type SmartCdnImageFormat = 'avif' | 'png' | 'webp';
-/** One signed Smart CDN rendition at a specific intrinsic width. */
-export interface SmartCdnImageCandidate {
-    url: string;
-    width: number;
-}
-/** Ordered candidates for one image format and quality. */
-export interface SmartCdnImageSource {
-    candidates: readonly SmartCdnImageCandidate[];
-    format: SmartCdnImageFormat;
-    quality: number;
-}
-/** Structured data for rendering a responsive image. */
-export interface SmartCdnImageCandidates {
-    fallbackUrl: string;
-    sources: readonly SmartCdnImageSource[];
-}
 /** Options for deterministic, server-generated Smart CDN image candidates. */
-export interface SmartCdnImageCandidatesOptions {
+export interface SmartCdnImageCandidatesOptions extends SmartCdnImagePolicyOptions {
     /** Transloadit auth key used to sign every candidate URL. */
     authKey: string;
     /** Transloadit auth secret used to sign every candidate URL. */
     authSecret: string;
-    /** One absolute expiry in milliseconds since UNIX epoch, shared by every candidate. */
-    expiresAt: number;
-    /** Formats and their quality values. Defaults to AVIF 45 and WebP 75. */
-    formats?: Readonly<Partial<Record<SmartCdnImageFormat, number>>>;
-    /** Absolute HTTP(S) source URL accepted by the responsive-image Template. */
-    input: string;
-    /** Compatible Template override. Defaults to `builtin/serve-image@0.0.1`. */
-    template?: string;
-    /** Up to 32 intrinsic widths. Each value must be an integer from 1 through 8000. */
-    widths: readonly number[];
     /** Workspace slug. */
     workspace: string;
 }
@@ -46,8 +22,8 @@ export declare const getSignedSmartCdnUrl: (opts: SmartCdnUrlOptions) => string;
 /**
  * Builds deterministic signed Smart CDN candidates for server-rendered `<picture>` elements.
  *
- * Width descriptors are only accurate when callers do not request widths above the source image's
- * intrinsic width. The helper deliberately keeps the Built-in in width-only `fit` mode.
+ * Pass `sourceDimensions` when known so width descriptors remain truthful without producing a
+ * rendition above the backend's width or derived-height limits.
  */
 export declare function getSignedSmartCdnImageCandidates(opts: SmartCdnImageCandidatesOptions): SmartCdnImageCandidates;
 //# sourceMappingURL=node.d.ts.map

package/dist/node.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"node.d.ts","sourceRoot":"","sources":["../src/node.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,kBAAkB,EAAE,MAAM,YAAY,CAAA;AACpD,OAAO,KAAK,EAAE,kBAAkB,EAAE,MAAM,eAAe,CAAA;AAMvD,YAAY,EAAE,kBAAkB,EAAE,MAAM,YAAY,CAAA;AACpD,YAAY,EAAE,kBAAkB,EAAE,MAAM,eAAe,CAAA;AAEvD,MAAM,MAAM,uBAAuB,GAAG,kBAAkB,GAAG,CAAC,MAAM,GAAG,EAAE,CAAC,CAAA;AAExE,gEAAgE;AAChE,MAAM,MAAM,mBAAmB,GAAG,MAAM,GAAG,KAAK,GAAG,MAAM,CAAA;AAEzD,oEAAoE;AACpE,MAAM,WAAW,sBAAsB;IACrC,GAAG,EAAE,MAAM,CAAA;IACX,KAAK,EAAE,MAAM,CAAA;CACd;AAED,2DAA2D;AAC3D,MAAM,WAAW,mBAAmB;IAClC,UAAU,EAAE,SAAS,sBAAsB,EAAE,CAAA;IAC7C,MAAM,EAAE,mBAAmB,CAAA;IAC3B,OAAO,EAAE,MAAM,CAAA;CAChB;AAED,wDAAwD;AACxD,MAAM,WAAW,uBAAuB;IACtC,WAAW,EAAE,MAAM,CAAA;IACnB,OAAO,EAAE,SAAS,mBAAmB,EAAE,CAAA;CACxC;AAED,8EAA8E;AAC9E,MAAM,WAAW,8BAA8B;IAC7C,6DAA6D;IAC7D,OAAO,EAAE,MAAM,CAAA;IACf,gEAAgE;IAChE,UAAU,EAAE,MAAM,CAAA;IAClB,uFAAuF;IACvF,SAAS,EAAE,MAAM,CAAA;IACjB,yEAAyE;IACzE,OAAO,CAAC,EAAE,QAAQ,CAAC,OAAO,CAAC,MAAM,CAAC,mBAAmB,EAAE,MAAM,CAAC,CAAC,CAAC,CAAA;IAChE,6EAA6E;IAC7E,KAAK,EAAE,MAAM,CAAA;IACb,6EAA6E;IAC7E,QAAQ,CAAC,EAAE,MAAM,CAAA;IACjB,oFAAoF;IACpF,MAAM,EAAE,SAAS,MAAM,EAAE,CAAA;IACzB,sBAAsB;IACtB,SAAS,EAAE,MAAM,CAAA;CAClB;AAkED,eAAO,MAAM,cAAc,GACzB,cAAc,MAAM,EACpB,YAAY,MAAM,EAClB,YAAW,uBAAkC,KAC5C,MAKF,CAAA;AAED,4FAA4F;AAC5F,eAAO,MAAM,oBAAoB,GAAI,MAAM,kBAAkB,KAAG,MAM/D,CAAA;AAED;;;;;GAKG;AACH,wBAAgB,gCAAgC,CAC9C,IAAI,EAAE,8BAA8B,GACnC,uBAAuB,CAsDzB"}
+{"version":3,"file":"node.d.ts","sourceRoot":"","sources":["../src/node.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,kBAAkB,EAAE,MAAM,YAAY,CAAA;AACpD,OAAO,KAAK,EAAE,kBAAkB,EAAE,MAAM,eAAe,CAAA;AACvD,OAAO,KAAK,EAAE,uBAAuB,EAAE,0BAA0B,EAAE,MAAM,oBAAoB,CAAA;AAO7F,YAAY,EAAE,kBAAkB,EAAE,MAAM,YAAY,CAAA;AACpD,YAAY,EACV,iBAAiB,EACjB,uBAAuB,EACvB,0BAA0B,EAC1B,kBAAkB,EAClB,iBAAiB,GAClB,MAAM,eAAe,CAAA;AACtB,YAAY,EACV,wBAAwB,EACxB,sBAAsB,EACtB,uBAAuB,EACvB,mBAAmB,EACnB,0BAA0B,EAC1B,oBAAoB,EACpB,0BAA0B,EAC1B,wBAAwB,EACxB,mBAAmB,EACnB,6BAA6B,GAC9B,MAAM,oBAAoB,CAAA;AAE3B,OAAO,EAAE,cAAc,EAAE,gBAAgB,EAAE,iBAAiB,EAAE,MAAM,eAAe,CAAA;AACnF,OAAO,EACL,2BAA2B,EAC3B,0BAA0B,EAC1B,yBAAyB,GAC1B,MAAM,oBAAoB,CAAA;AAE3B,MAAM,MAAM,uBAAuB,GAAG,kBAAkB,GAAG,CAAC,MAAM,GAAG,EAAE,CAAC,CAAA;AAExE,8EAA8E;AAC9E,MAAM,WAAW,8BAA+B,SAAQ,0BAA0B;IAChF,6DAA6D;IAC7D,OAAO,EAAE,MAAM,CAAA;IACf,gEAAgE;IAChE,UAAU,EAAE,MAAM,CAAA;IAClB,sBAAsB;IACtB,SAAS,EAAE,MAAM,CAAA;CAClB;AAED,eAAO,MAAM,cAAc,GACzB,cAAc,MAAM,EACpB,YAAY,MAAM,EAClB,YAAW,uBAAkC,KAC5C,MAKF,CAAA;AAED,4FAA4F;AAC5F,eAAO,MAAM,oBAAoB,GAAI,MAAM,kBAAkB,KAAG,MAM/D,CAAA;AAED;;;;;GAKG;AACH,wBAAgB,gCAAgC,CAC9C,IAAI,EAAE,8BAA8B,GACnC,uBAAuB,CAsBzB"}

package/dist/node.js

@@ -1,57 +1,8 @@
 import { createHmac } from 'node:crypto';
 import { finishSmartCdnUrl, prepareSmartCdnUrl } from "./smartCdn.js";
-const defaultSmartCdnImageFormats = {
-    avif: 45,
-    webp: 75,
-};
-const defaultSmartCdnImageTemplate = 'builtin/serve-image@0.0.1';
-const smartCdnImageFormats = ['avif', 'webp', 'png'];
-const smartCdnImageMaxDimension = 8000;
-const smartCdnImageMaxWidths = 32;
-function isSmartCdnImageFormat(value) {
-    return value === 'avif' || value === 'png' || value === 'webp';
-}
-function validateSmartCdnImageDimension(width) {
-    if (!Number.isInteger(width) || width < 1 || width > smartCdnImageMaxDimension) {
-        throw new RangeError(`width must be an integer from 1 through ${smartCdnImageMaxDimension}`);
-    }
-}
-function validateSmartCdnImageQuality(quality) {
-    if (!Number.isInteger(quality) || quality < 1 || quality > 100) {
-        throw new RangeError('quality must be an integer from 1 through 100');
-    }
-}
-function validateSmartCdnImageInput(input) {
-    if (typeof input !== 'string' || input.trim() !== input || input.includes('|')) {
-        throw new TypeError('input must be a single HTTP or HTTPS URL string');
-    }
-    if (!URL.canParse(input)) {
-        throw new TypeError('input must be an HTTP or HTTPS URL');
-    }
-    const protocol = new URL(input).protocol;
-    if (protocol !== 'http:' && protocol !== 'https:') {
-        throw new TypeError('input must be an HTTP or HTTPS URL');
-    }
-}
-function validateSmartCdnImageFormats(formats) {
-    for (const format of Object.keys(formats)) {
-        if (!isSmartCdnImageFormat(format)) {
-            throw new TypeError(`Unsupported Smart CDN image format: ${format}`);
-        }
-    }
-    let formatCount = 0;
-    for (const format of smartCdnImageFormats) {
-        const quality = formats[format];
-        if (quality == null) {
-            continue;
-        }
-        validateSmartCdnImageQuality(quality);
-        formatCount += 1;
-    }
-    if (formatCount === 0) {
-        throw new TypeError('formats must contain at least one value');
-    }
-}
+import { createSmartCdnImageCandidates } from "./smartCdnImage.js";
+export { getSmartCdnUrl, parseSmartCdnUrl, stripSmartCdnAuth } from "./smartCdn.js";
+export { resolveSmartCdnImageFormats, resolveSmartCdnImageWidths, smartCdnImageMaxDimension, } from "./smartCdnImage.js";
 export const signParamsSync = (paramsString, authSecret, algorithm = 'sha384') => {
     const signature = createHmac(algorithm, authSecret)
         .update(Buffer.from(paramsString, 'utf-8'))
@@ -69,56 +20,26 @@ export const getSignedSmartCdnUrl = (opts) => {
 /**
  * Builds deterministic signed Smart CDN candidates for server-rendered `<picture>` elements.
  *
- * Width descriptors are only accurate when callers do not request widths above the source image's
- * intrinsic width. The helper deliberately keeps the Built-in in width-only `fit` mode.
+ * Pass `sourceDimensions` when known so width descriptors remain truthful without producing a
+ * rendition above the backend's width or derived-height limits.
  */
 export function getSignedSmartCdnImageCandidates(opts) {
-    if (typeof opts.authKey !== 'string' || opts.authKey === '') {
+    const authKey = opts.authKey;
+    const authSecret = opts.authSecret;
+    const workspace = opts.workspace;
+    if (typeof authKey !== 'string' || authKey === '') {
         throw new TypeError('authKey is required');
     }
-    if (typeof opts.authSecret !== 'string' || opts.authSecret === '') {
+    if (typeof authSecret !== 'string' || authSecret === '') {
         throw new TypeError('authSecret is required');
     }
-    if (!Number.isSafeInteger(opts.expiresAt) || opts.expiresAt <= 0) {
-        throw new RangeError('expiresAt must be a positive safe integer');
-    }
-    if (!Array.isArray(opts.widths) || opts.widths.length === 0) {
-        throw new TypeError('widths must contain at least one value');
-    }
-    if (opts.widths.length > smartCdnImageMaxWidths) {
-        throw new RangeError(`widths must contain at most ${smartCdnImageMaxWidths} values`);
-    }
-    validateSmartCdnImageInput(opts.input);
-    const widths = [...new Set(opts.widths)];
-    if (widths.length > smartCdnImageMaxWidths) {
-        throw new RangeError(`widths must contain at most ${smartCdnImageMaxWidths} unique values`);
-    }
-    for (const width of widths) {
-        validateSmartCdnImageDimension(width);
-    }
-    const formats = opts.formats ?? defaultSmartCdnImageFormats;
-    validateSmartCdnImageFormats(formats);
-    widths.sort((left, right) => left - right);
-    const sources = [];
-    for (const format of smartCdnImageFormats) {
-        const quality = formats[format];
-        if (quality == null) {
-            continue;
-        }
-        const candidates = [];
-        for (const width of widths) {
-            const url = getSignedSmartCdnUrl({
-                authKey: opts.authKey,
-                authSecret: opts.authSecret,
-                expiresAt: opts.expiresAt,
-                input: opts.input,
-                template: opts.template ?? defaultSmartCdnImageTemplate,
-                urlParams: { f: format, q: quality, r: 'fit', w: width },
-                workspace: opts.workspace,
-            });
-            candidates.push({ url, width });
-        }
-        sources.push({ candidates, format, quality });
-    }
-    return { fallbackUrl: opts.input, sources };
+    return createSmartCdnImageCandidates(opts, (request) => getSignedSmartCdnUrl({
+        authKey,
+        authSecret,
+        expiresAt: request.expiresAt,
+        input: request.input,
+        template: request.template,
+        urlParams: { ...request.urlParams },
+        workspace,
+    }));
 }

package/dist/smartCdn.d.ts

@@ -1,8 +1,10 @@
 /**
- * Smart CDN URL building shared by the synchronous Node signer (`@transloadit/utils/node`) and the
- * asynchronous WebCrypto signer (`@transloadit/utils`). Only the HMAC differs between the two, so
- * the string-to-sign and the final URL are assembled here and cannot drift apart.
+ * Smart CDN URL grammar shared by the synchronous Node signer (`@transloadit/utils/node`) and the
+ * asynchronous WebCrypto signer (`@transloadit/utils`): building (signed and unsigned), parsing,
+ * and stripping signature parameters. Only the HMAC differs between the two signers, so the
+ * string-to-sign and the final URL are assembled here and cannot drift apart.
  */
+export type SmartCdnUrlParams = Record<string, boolean | number | string | (boolean | number | string)[]>;
 export type SmartCdnUrlOptions = {
     /**
      * Workspace slug.
@@ -17,9 +19,10 @@ export type SmartCdnUrlOptions = {
      */
     input: string;
     /**
-     * Additional parameters for the URL query string.
+     * Additional parameters for the URL query string. `auth_key`, `exp`, and `sig` are reserved:
+     * signed builders replace them and unsigned builders omit them.
      */
-    urlParams?: Record<string, boolean | number | string | (boolean | number | string)[]>;
+    urlParams?: SmartCdnUrlParams;
     /**
      * Expiration timestamp of the signature in milliseconds since UNIX epoch.
      * Defaults to 1 hour from now.
@@ -33,7 +36,19 @@ export type SmartCdnUrlOptions = {
      * Transloadit auth secret used to sign the URL.
      */
     authSecret: string;
+    /**
+     * Base URL that replaces `https://{workspace}.tlcdn.com`, e.g. a local api2's URL Transform
+     * endpoint `https://api2-devdock.transloadit.dev/file/{workspace}`. A literal `{workspace}` is
+     * substituted with the encoded workspace slug; a trailing slash is ignored.
+     *
+     * **Trusted configuration only.** The signature does not cover the host, so a base URL taken from
+     * user input would let anyone redirect a signed URL (auth key included) to an origin of their
+     * choosing. Never derive it from request data.
+     */
+    baseUrl?: string;
 };
+/** Options for an unsigned Smart CDN URL: the signed options without credentials or expiry. */
+export type SmartCdnUnsignedUrlOptions = Omit<SmartCdnUrlOptions, 'authKey' | 'authSecret' | 'expiresAt'>;
 /** A Smart CDN URL with everything but its signature in place. */
 export interface PreparedSmartCdnUrl {
     /** `workspace/template/input?sortedQuery`, the message the auth secret signs with HMAC-SHA256. */
@@ -44,10 +59,56 @@ export interface PreparedSmartCdnUrl {
         templateSlug: string;
         inputField: string;
         queryParams: URLSearchParams;
+        /** Resolved origin + path prefix that precedes `/{template}/{input}`. */
+        baseUrl: string;
+    };
+}
+/** The components of a Smart CDN URL, as produced by `parseSmartCdnUrl`. */
+export interface ParsedSmartCdnUrl {
+    workspace: string;
+    template: string;
+    input: string;
+    /** Every query parameter except auth fields; repeated parameters become arrays. */
+    urlParams: Record<string, string | string[]>;
+    /** Present when the URL carries `auth_key`, `exp` and `sig`. */
+    auth?: {
+        key: string;
+        /** Milliseconds since UNIX epoch. */
+        expiresAt: number;
+        /** The `sig` value, e.g. `sha256:…`. */
+        signature: string;
     };
+    /** Only set when the URL was parsed against a custom `baseUrl`; feeds straight back into the builders. */
+    baseUrl?: string;
+}
+export interface ParseSmartCdnUrlOptions {
+    /**
+     * The same trusted `baseUrl` the URL was built with (with or without `{workspace}`). Without it
+     * only `https://{workspace}.tlcdn.com/…` URLs are accepted.
+     */
+    baseUrl?: string;
+    /** Workspace slug for a `baseUrl` without a `{workspace}` placeholder, where the URL cannot tell. */
+    workspace?: string;
 }
 /** Validates the options and assembles the string to sign; the caller supplies the HMAC. */
 export declare const prepareSmartCdnUrl: (opts: SmartCdnUrlOptions) => PreparedSmartCdnUrl;
 /** Appends the `sig` parameter and returns the final `https://{workspace}.tlcdn.com/…` URL. */
 export declare const finishSmartCdnUrl: ({ parts }: PreparedSmartCdnUrl, signatureHex: string) => string;
+/**
+ * Builds an unsigned Smart CDN URL (`https://{workspace}.tlcdn.com/{template}/{input}?sortedQuery`)
+ * for workspaces that do not require signature authentication.
+ */
+export declare const getSmartCdnUrl: (opts: SmartCdnUnsignedUrlOptions) => string;
+/**
+ * Removes the signature parameters (`auth_key`, `exp`, `sig`, and api2's `hsh`) from a Smart CDN
+ * URL. Every other byte of the URL is left untouched, so the result stays comparable with URLs
+ * produced elsewhere. Idempotent.
+ */
+export declare const stripSmartCdnAuth: (url: string) => string;
+/**
+ * Parses a Smart CDN URL back into the options that built it: the inverse of `getSmartCdnUrl` and
+ * `getSignedSmartCdnUrl`. Path segments are percent-decoded exactly once; query parameters are
+ * decoded by `URLSearchParams` semantics; `auth_key`/`exp`/`sig` are returned separately as `auth`.
+ */
+export declare const parseSmartCdnUrl: (url: string, options?: ParseSmartCdnUrlOptions) => ParsedSmartCdnUrl;
 //# sourceMappingURL=smartCdn.d.ts.map

package/dist/smartCdn.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"smartCdn.d.ts","sourceRoot":"","sources":["../src/smartCdn.ts"],"names":[],"mappings":"AAAA;;;;GAIG;AAEH,MAAM,MAAM,kBAAkB,GAAG;IAC/B;;OAEG;IACH,SAAS,EAAE,MAAM,CAAA;IACjB;;OAEG;IACH,QAAQ,EAAE,MAAM,CAAA;IAChB;;OAEG;IACH,KAAK,EAAE,MAAM,CAAA;IACb;;OAEG;IACH,SAAS,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,GAAG,MAAM,GAAG,MAAM,GAAG,CAAC,OAAO,GAAG,MAAM,GAAG,MAAM,CAAC,EAAE,CAAC,CAAA;IACrF;;;OAGG;IACH,SAAS,CAAC,EAAE,MAAM,CAAA;IAClB;;OAEG;IACH,OAAO,EAAE,MAAM,CAAA;IACf;;OAEG;IACH,UAAU,EAAE,MAAM,CAAA;CACnB,CAAA;AAED,kEAAkE;AAClE,MAAM,WAAW,mBAAmB;IAClC,kGAAkG;IAClG,YAAY,EAAE,MAAM,CAAA;IACpB,sEAAsE;IACtE,KAAK,EAAE;QACL,aAAa,EAAE,MAAM,CAAA;QACrB,YAAY,EAAE,MAAM,CAAA;QACpB,UAAU,EAAE,MAAM,CAAA;QAClB,WAAW,EAAE,eAAe,CAAA;KAC7B,CAAA;CACF;AAED,4FAA4F;AAC5F,eAAO,MAAM,kBAAkB,GAAI,MAAM,kBAAkB,KAAG,mBA6B7D,CAAA;AAED,+FAA+F;AAC/F,eAAO,MAAM,iBAAiB,GAAI,WAAW,mBAAmB,EAAE,cAAc,MAAM,KAAG,MAIxF,CAAA"}
+{"version":3,"file":"smartCdn.d.ts","sourceRoot":"","sources":["../src/smartCdn.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AAQH,MAAM,MAAM,iBAAiB,GAAG,MAAM,CACpC,MAAM,EACN,OAAO,GAAG,MAAM,GAAG,MAAM,GAAG,CAAC,OAAO,GAAG,MAAM,GAAG,MAAM,CAAC,EAAE,CAC1D,CAAA;AAED,MAAM,MAAM,kBAAkB,GAAG;IAC/B;;OAEG;IACH,SAAS,EAAE,MAAM,CAAA;IACjB;;OAEG;IACH,QAAQ,EAAE,MAAM,CAAA;IAChB;;OAEG;IACH,KAAK,EAAE,MAAM,CAAA;IACb;;;OAGG;IACH,SAAS,CAAC,EAAE,iBAAiB,CAAA;IAC7B;;;OAGG;IACH,SAAS,CAAC,EAAE,MAAM,CAAA;IAClB;;OAEG;IACH,OAAO,EAAE,MAAM,CAAA;IACf;;OAEG;IACH,UAAU,EAAE,MAAM,CAAA;IAClB;;;;;;;;OAQG;IACH,OAAO,CAAC,EAAE,MAAM,CAAA;CACjB,CAAA;AAED,+FAA+F;AAC/F,MAAM,MAAM,0BAA0B,GAAG,IAAI,CAC3C,kBAAkB,EAClB,SAAS,GAAG,YAAY,GAAG,WAAW,CACvC,CAAA;AAED,kEAAkE;AAClE,MAAM,WAAW,mBAAmB;IAClC,kGAAkG;IAClG,YAAY,EAAE,MAAM,CAAA;IACpB,sEAAsE;IACtE,KAAK,EAAE;QACL,aAAa,EAAE,MAAM,CAAA;QACrB,YAAY,EAAE,MAAM,CAAA;QACpB,UAAU,EAAE,MAAM,CAAA;QAClB,WAAW,EAAE,eAAe,CAAA;QAC5B,yEAAyE;QACzE,OAAO,EAAE,MAAM,CAAA;KAChB,CAAA;CACF;AAED,4EAA4E;AAC5E,MAAM,WAAW,iBAAiB;IAChC,SAAS,EAAE,MAAM,CAAA;IACjB,QAAQ,EAAE,MAAM,CAAA;IAChB,KAAK,EAAE,MAAM,CAAA;IACb,mFAAmF;IACnF,SAAS,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,GAAG,MAAM,EAAE,CAAC,CAAA;IAC5C,gEAAgE;IAChE,IAAI,CAAC,EAAE;QACL,GAAG,EAAE,MAAM,CAAA;QACX,qCAAqC;QACrC,SAAS,EAAE,MAAM,CAAA;QACjB,wCAAwC;QACxC,SAAS,EAAE,MAAM,CAAA;KAClB,CAAA;IACD,0GAA0G;IAC1G,OAAO,CAAC,EAAE,MAAM,CAAA;CACjB;AAED,MAAM,WAAW,uBAAuB;IACtC;;;OAGG;IACH,OAAO,CAAC,EAAE,MAAM,CAAA;IAChB,qGAAqG;IACrG,SAAS,CAAC,EAAE,MAAM,CAAA;CACnB;AAyCD,4FAA4F;AAC5F,eAAO,MAAM,kBAAkB,GAAI,MAAM,kBAAkB,KAAG,mBAyB7D,CAAA;AAED,+FAA+F;AAC/F,eAAO,MAAM,iBAAiB,GAAI,WAAW,mBAAmB,EAAE,cAAc,MAAM,KAAG,MAIxF,CAAA;AAED;;;GAGG;AACH,eAAO,MAAM,cAAc,GAAI,MAAM,0BAA0B,KAAG,MAajE,CAAA;AAUD;;;;GAIG;AACH,eAAO,MAAM,iBAAiB,GAAI,KAAK,MAAM,KAAG,MAsB/C,CAAA;AAwDD;;;;GAIG;AACH,eAAO,MAAM,gBAAgB,GAC3B,KAAK,MAAM,EACX,UAAS,uBAA4B,KACpC,iBA4DF,CAAA"}

package/dist/smartCdn.js

@@ -1,22 +1,41 @@
 /**
- * Smart CDN URL building shared by the synchronous Node signer (`@transloadit/utils/node`) and the
- * asynchronous WebCrypto signer (`@transloadit/utils`). Only the HMAC differs between the two, so
- * the string-to-sign and the final URL are assembled here and cannot drift apart.
+ * Smart CDN URL grammar shared by the synchronous Node signer (`@transloadit/utils/node`) and the
+ * asynchronous WebCrypto signer (`@transloadit/utils`): building (signed and unsigned), parsing,
+ * and stripping signature parameters. Only the HMAC differs between the two signers, so the
+ * string-to-sign and the final URL are assembled here and cannot drift apart.
  */
-/** Validates the options and assembles the string to sign; the caller supplies the HMAC. */
-export const prepareSmartCdnUrl = (opts) => {
+const SMART_CDN_HOST_SUFFIX = '.tlcdn.com';
+const WORKSPACE_PLACEHOLDER = '{workspace}';
+/** Query parameters that carry the signature; `hsh` is an api2-side hash that is stripped too. */
+const SIGNATURE_PARAMS = new Set(['auth_key', 'exp', 'sig']);
+const STRIPPED_PARAMS = new Set([...SIGNATURE_PARAMS, 'hsh']);
+const validateRequired = (opts) => {
     if (opts.workspace == null || opts.workspace === '')
         throw new TypeError('workspace is required');
     if (opts.template == null || opts.template === '')
         throw new TypeError('template is required');
     if (opts.input == null)
         throw new TypeError('input is required');
-    const workspaceSlug = encodeURIComponent(opts.workspace);
-    const templateSlug = encodeURIComponent(opts.template);
-    const inputField = encodeURIComponent(opts.input);
-    const expiresAt = opts.expiresAt || Date.now() + 60 * 60 * 1000;
+};
+const resolveBaseUrl = (baseUrl, workspaceSlug) => {
+    if (baseUrl == null)
+        return `https://${workspaceSlug}${SMART_CDN_HOST_SUFFIX}`;
+    const resolved = baseUrl.replace(/\/+$/, '').split(WORKSPACE_PLACEHOLDER).join(workspaceSlug);
+    let parsed;
+    try {
+        parsed = new URL(resolved);
+    }
+    catch {
+        throw new TypeError(`baseUrl must be an absolute URL, got '${baseUrl}'`);
+    }
+    if (parsed.search !== '' || parsed.hash !== '') {
+        throw new TypeError('baseUrl must not contain a query string or fragment');
+    }
+    return resolved;
+};
+const buildQueryParams = (urlParams) => {
     const queryParams = new URLSearchParams();
-    for (const [key, value] of Object.entries(opts.urlParams || {})) {
+    for (const [key, value] of Object.entries(urlParams || {})) {
         if (Array.isArray(value)) {
             for (const val of value) {
                 queryParams.append(key, `${val}`);
@@ -26,17 +45,197 @@ export const prepareSmartCdnUrl = (opts) => {
             queryParams.append(key, `${value}`);
         }
     }
+    return queryParams;
+};
+/** Validates the options and assembles the string to sign; the caller supplies the HMAC. */
+export const prepareSmartCdnUrl = (opts) => {
+    validateRequired(opts);
+    const workspaceSlug = encodeURIComponent(opts.workspace);
+    const templateSlug = encodeURIComponent(opts.template);
+    const inputField = encodeURIComponent(opts.input);
+    const expiresAt = opts.expiresAt || Date.now() + 60 * 60 * 1000;
+    const queryParams = buildQueryParams(opts.urlParams);
+    // Keep accepting legacy values: the signer safely replaces its own authentication fields.
+    queryParams.delete('sig');
     queryParams.set('auth_key', opts.authKey);
     queryParams.set('exp', `${expiresAt}`);
     queryParams.sort();
     return {
         stringToSign: `${workspaceSlug}/${templateSlug}/${inputField}?${queryParams}`,
-        parts: { workspaceSlug, templateSlug, inputField, queryParams },
+        parts: {
+            workspaceSlug,
+            templateSlug,
+            inputField,
+            queryParams,
+            baseUrl: resolveBaseUrl(opts.baseUrl, workspaceSlug),
+        },
     };
 };
 /** Appends the `sig` parameter and returns the final `https://{workspace}.tlcdn.com/…` URL. */
 export const finishSmartCdnUrl = ({ parts }, signatureHex) => {
-    const { workspaceSlug, templateSlug, inputField, queryParams } = parts;
+    const { baseUrl, templateSlug, inputField, queryParams } = parts;
     queryParams.set('sig', `sha256:${signatureHex}`);
-    return `https://${workspaceSlug}.tlcdn.com/${templateSlug}/${inputField}?${queryParams}`;
+    return `${baseUrl}/${templateSlug}/${inputField}?${queryParams}`;
+};
+/**
+ * Builds an unsigned Smart CDN URL (`https://{workspace}.tlcdn.com/{template}/{input}?sortedQuery`)
+ * for workspaces that do not require signature authentication.
+ */
+export const getSmartCdnUrl = (opts) => {
+    validateRequired(opts);
+    const workspaceSlug = encodeURIComponent(opts.workspace);
+    const templateSlug = encodeURIComponent(opts.template);
+    const inputField = encodeURIComponent(opts.input);
+    const queryParams = buildQueryParams(opts.urlParams);
+    // An unsigned builder must not emit fields that make the URL look partially or fully signed.
+    for (const param of SIGNATURE_PARAMS)
+        queryParams.delete(param);
+    queryParams.sort();
+    const query = queryParams.toString();
+    return `${resolveBaseUrl(opts.baseUrl, workspaceSlug)}/${templateSlug}/${inputField}${query === '' ? '' : `?${query}`}`;
+};
+const decodeOnce = (value, what) => {
+    try {
+        return decodeURIComponent(value);
+    }
+    catch {
+        throw new TypeError(`Not a Smart CDN URL: malformed percent-encoding in ${what}`);
+    }
+};
+/**
+ * Removes the signature parameters (`auth_key`, `exp`, `sig`, and api2's `hsh`) from a Smart CDN
+ * URL. Every other byte of the URL is left untouched, so the result stays comparable with URLs
+ * produced elsewhere. Idempotent.
+ */
+export const stripSmartCdnAuth = (url) => {
+    const hashIndex = url.indexOf('#');
+    const fragment = hashIndex === -1 ? '' : url.slice(hashIndex);
+    const withoutFragment = hashIndex === -1 ? url : url.slice(0, hashIndex);
+    const queryIndex = withoutFragment.indexOf('?');
+    if (queryIndex === -1)
+        return url;
+    const path = withoutFragment.slice(0, queryIndex);
+    const kept = withoutFragment
+        .slice(queryIndex + 1)
+        .split('&')
+        .filter((pair) => {
+        if (pair === '')
+            return false;
+        const rawName = pair.slice(0, pair.indexOf('=') === -1 ? pair.length : pair.indexOf('='));
+        let name = rawName;
+        try {
+            name = decodeURIComponent(rawName.replace(/\+/g, ' '));
+        }
+        catch {
+            // An undecodable name is never one of ours; keep it.
+        }
+        return !STRIPPED_PARAMS.has(name);
+    });
+    return `${path}${kept.length === 0 ? '' : `?${kept.join('&')}`}${fragment}`;
+};
+const notSmartCdnUrl = (detail) => new TypeError(`Not a Smart CDN URL: ${detail} (expected https://{workspace}.tlcdn.com/{template}/{input}, or the configured baseUrl)`);
+/** Splits `origin + pathname` into the workspace slug and the `{template}/{input}` remainder. */
+const locateSmartCdnPath = (parsed, options) => {
+    const full = `${parsed.origin}${parsed.pathname}`;
+    if (options.baseUrl == null) {
+        const match = /^([^.]+)\.tlcdn\.com$/i.exec(parsed.hostname);
+        if (match?.[1] == null || parsed.protocol !== 'https:') {
+            throw notSmartCdnUrl(`unexpected origin '${parsed.origin}'`);
+        }
+        return { workspaceSlug: match[1], remainder: parsed.pathname.slice(1) };
+    }
+    const template = options.baseUrl.replace(/\/+$/, '');
+    const placeholderIndex = template.indexOf(WORKSPACE_PLACEHOLDER);
+    if (placeholderIndex === -1) {
+        const prefix = `${template}/`;
+        if (!full.startsWith(prefix))
+            throw notSmartCdnUrl(`'${full}' is not under baseUrl '${template}'`);
+        const hostMatch = /^([^.]+)\.tlcdn\.com$/i.exec(parsed.hostname);
+        const workspaceSlug = options.workspace != null ? encodeURIComponent(options.workspace) : hostMatch?.[1];
+        if (workspaceSlug == null) {
+            throw notSmartCdnUrl('the workspace cannot be determined; pass `workspace` next to a baseUrl without {workspace}');
+        }
+        return { workspaceSlug, remainder: full.slice(prefix.length), baseUrl: template };
+    }
+    const before = template.slice(0, placeholderIndex);
+    const after = template.slice(placeholderIndex + WORKSPACE_PLACEHOLDER.length);
+    if (!full.startsWith(before))
+        throw notSmartCdnUrl(`'${full}' is not under baseUrl '${template}'`);
+    const rest = full.slice(before.length);
+    const slashIndex = rest.indexOf('/');
+    const workspaceSlug = slashIndex === -1 ? rest : rest.slice(0, slashIndex);
+    const afterPart = slashIndex === -1 ? '' : rest.slice(slashIndex);
+    if (workspaceSlug === '' || !afterPart.startsWith(`${after}/`)) {
+        throw notSmartCdnUrl(`'${full}' does not match baseUrl '${template}'`);
+    }
+    return {
+        workspaceSlug,
+        remainder: afterPart.slice(after.length + 1),
+        baseUrl: `${before}${workspaceSlug}${after}`,
+    };
+};
+/**
+ * Parses a Smart CDN URL back into the options that built it: the inverse of `getSmartCdnUrl` and
+ * `getSignedSmartCdnUrl`. Path segments are percent-decoded exactly once; query parameters are
+ * decoded by `URLSearchParams` semantics; `auth_key`/`exp`/`sig` are returned separately as `auth`.
+ */
+export const parseSmartCdnUrl = (url, options = {}) => {
+    let parsed;
+    try {
+        parsed = new URL(url);
+    }
+    catch {
+        throw notSmartCdnUrl(`'${url}' is not an absolute URL`);
+    }
+    const { workspaceSlug, remainder, baseUrl } = locateSmartCdnPath(parsed, options);
+    const slashIndex = remainder.indexOf('/');
+    if (slashIndex === -1)
+        throw notSmartCdnUrl('missing the input segment');
+    const templateSlug = remainder.slice(0, slashIndex);
+    if (templateSlug === '')
+        throw notSmartCdnUrl('missing the template segment');
+    const urlParams = {};
+    let authKey;
+    let expiration;
+    let signatureValue;
+    for (const [key, value] of new URLSearchParams(parsed.search)) {
+        if (key === 'auth_key') {
+            authKey = value;
+            continue;
+        }
+        if (key === 'exp') {
+            expiration = value;
+            continue;
+        }
+        if (key === 'sig') {
+            signatureValue = value;
+            continue;
+        }
+        const existing = urlParams[key];
+        if (existing === undefined)
+            urlParams[key] = value;
+        else if (Array.isArray(existing))
+            existing.push(value);
+        else
+            urlParams[key] = [existing, value];
+    }
+    let auth;
+    const present = [authKey, expiration, signatureValue].filter((value) => value !== undefined).length;
+    if (present > 0) {
+        if (authKey === undefined || expiration === undefined || signatureValue === undefined) {
+            throw notSmartCdnUrl('incomplete signature parameters; expected auth_key, exp and sig together');
+        }
+        const expiresAt = Number(expiration);
+        if (!Number.isInteger(expiresAt))
+            throw notSmartCdnUrl(`exp '${expiration}' is not a timestamp`);
+        auth = { key: authKey, expiresAt, signature: signatureValue };
+    }
+    return {
+        workspace: decodeOnce(workspaceSlug, 'the workspace'),
+        template: decodeOnce(templateSlug, 'the template'),
+        input: decodeOnce(remainder.slice(slashIndex + 1), 'the input'),
+        urlParams,
+        ...(auth && { auth }),
+        ...(baseUrl != null && { baseUrl }),
+    };
 };

package/dist/smartCdnImage.d.ts

@@ -0,0 +1,68 @@
+/** Maximum requested width or height accepted by the responsive-image Built-ins. */
+export declare const smartCdnImageMaxDimension = 8000;
+/** Image formats supported by the responsive-image Built-in. */
+export type SmartCdnImageFormat = 'avif' | 'png' | 'webp';
+/** Formats and their format-specific quality values. */
+export type SmartCdnImageFormats = Readonly<Partial<Record<SmartCdnImageFormat, number>>>;
+/** One responsive-image candidate at a specific intrinsic width. */
+export interface SmartCdnImageCandidate {
+    url: string;
+    width: number;
+}
+/** Ordered candidates for one image format and quality. */
+export interface SmartCdnImageSource {
+    candidates: readonly SmartCdnImageCandidate[];
+    format: SmartCdnImageFormat;
+    quality: number;
+}
+/** One validated format and its encoding quality, in browser preference order. */
+export interface SmartCdnImageFormatQuality {
+    format: SmartCdnImageFormat;
+    quality: number;
+}
+/** Structured data for rendering a responsive image. */
+export interface SmartCdnImageCandidates {
+    fallbackUrl: string;
+    sources: readonly SmartCdnImageSource[];
+}
+/** Intrinsic dimensions used to prevent upscaling or an oversized derived height. */
+export interface SmartCdnImageSourceDimensions {
+    height: number;
+    width: number;
+}
+/** One rendition request passed to an injected Smart CDN signer. */
+export interface SmartCdnImageSignRequest {
+    expiresAt: number;
+    input: string;
+    template: string;
+    urlParams: Readonly<Record<string, boolean | number | string>>;
+}
+/** Injected signer that keeps responsive-image policy independent from credentials and runtimes. */
+export type SignSmartCdnImageRequest = (request: SmartCdnImageSignRequest) => string;
+/** Framework-neutral options for deterministic Smart CDN image candidates. */
+export interface SmartCdnImagePolicyOptions {
+    /** One absolute expiry in milliseconds since UNIX epoch, shared by every candidate. */
+    expiresAt: number;
+    /** Browser-safe fallback URL, kept separate from the Template-specific input value. */
+    fallbackUrl: string;
+    /** Formats and their quality values. Defaults to AVIF 45 and WebP 75. */
+    formats?: SmartCdnImageFormats;
+    /** One source value accepted by the explicitly selected responsive-image Template. */
+    input: string;
+    /** Intrinsic dimensions, when known, used to keep generated output within backend limits. */
+    sourceDimensions?: SmartCdnImageSourceDimensions;
+    /** Trusted Template whose source policy is controlled by the caller's workspace. */
+    template: string;
+    /** Up to 32 intrinsic widths. Each value must be an integer from 1 through 8000. */
+    widths: readonly number[];
+}
+/** Resolves and validates format-specific qualities in deterministic browser preference order. */
+export declare function resolveSmartCdnImageFormats(formats: SmartCdnImageFormats | undefined): SmartCdnImageFormatQuality[];
+/** Validates, caps, deduplicates, and sorts requested responsive-image widths. */
+export declare function resolveSmartCdnImageWidths(widths: readonly number[], maximumWidth?: number): number[];
+/**
+ * Creates signed responsive-image candidates while leaving credential storage and HMAC choice to
+ * the injected signer.
+ */
+export declare function createSmartCdnImageCandidates(options: SmartCdnImagePolicyOptions, sign: SignSmartCdnImageRequest): SmartCdnImageCandidates;
+//# sourceMappingURL=smartCdnImage.d.ts.map

package/dist/smartCdnImage.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"smartCdnImage.d.ts","sourceRoot":"","sources":["../src/smartCdnImage.ts"],"names":[],"mappings":"AAKA,oFAAoF;AACpF,eAAO,MAAM,yBAAyB,OAAO,CAAA;AAE7C,gEAAgE;AAChE,MAAM,MAAM,mBAAmB,GAAG,MAAM,GAAG,KAAK,GAAG,MAAM,CAAA;AAEzD,wDAAwD;AACxD,MAAM,MAAM,oBAAoB,GAAG,QAAQ,CAAC,OAAO,CAAC,MAAM,CAAC,mBAAmB,EAAE,MAAM,CAAC,CAAC,CAAC,CAAA;AAEzF,oEAAoE;AACpE,MAAM,WAAW,sBAAsB;IACrC,GAAG,EAAE,MAAM,CAAA;IACX,KAAK,EAAE,MAAM,CAAA;CACd;AAED,2DAA2D;AAC3D,MAAM,WAAW,mBAAmB;IAClC,UAAU,EAAE,SAAS,sBAAsB,EAAE,CAAA;IAC7C,MAAM,EAAE,mBAAmB,CAAA;IAC3B,OAAO,EAAE,MAAM,CAAA;CAChB;AAED,kFAAkF;AAClF,MAAM,WAAW,0BAA0B;IACzC,MAAM,EAAE,mBAAmB,CAAA;IAC3B,OAAO,EAAE,MAAM,CAAA;CAChB;AAED,wDAAwD;AACxD,MAAM,WAAW,uBAAuB;IACtC,WAAW,EAAE,MAAM,CAAA;IACnB,OAAO,EAAE,SAAS,mBAAmB,EAAE,CAAA;CACxC;AAED,qFAAqF;AACrF,MAAM,WAAW,6BAA6B;IAC5C,MAAM,EAAE,MAAM,CAAA;IACd,KAAK,EAAE,MAAM,CAAA;CACd;AAED,oEAAoE;AACpE,MAAM,WAAW,wBAAwB;IACvC,SAAS,EAAE,MAAM,CAAA;IACjB,KAAK,EAAE,MAAM,CAAA;IACb,QAAQ,EAAE,MAAM,CAAA;IAChB,SAAS,EAAE,QAAQ,CAAC,MAAM,CAAC,MAAM,EAAE,OAAO,GAAG,MAAM,GAAG,MAAM,CAAC,CAAC,CAAA;CAC/D;AAED,oGAAoG;AACpG,MAAM,MAAM,wBAAwB,GAAG,CAAC,OAAO,EAAE,wBAAwB,KAAK,MAAM,CAAA;AAEpF,8EAA8E;AAC9E,MAAM,WAAW,0BAA0B;IACzC,uFAAuF;IACvF,SAAS,EAAE,MAAM,CAAA;IACjB,uFAAuF;IACvF,WAAW,EAAE,MAAM,CAAA;IACnB,yEAAyE;IACzE,OAAO,CAAC,EAAE,oBAAoB,CAAA;IAC9B,sFAAsF;IACtF,KAAK,EAAE,MAAM,CAAA;IACb,6FAA6F;IAC7F,gBAAgB,CAAC,EAAE,6BAA6B,CAAA;IAChD,oFAAoF;IACpF,QAAQ,EAAE,MAAM,CAAA;IAChB,oFAAoF;IACpF,MAAM,EAAE,SAAS,MAAM,EAAE,CAAA;CAC1B;AA0CD,kGAAkG;AAClG,wBAAgB,2BAA2B,CACzC,OAAO,EAAE,oBAAoB,GAAG,SAAS,GACxC,0BAA0B,EAAE,CAkB9B;AAqBD,kFAAkF;AAClF,wBAAgB,0BAA0B,CACxC,MAAM,EAAE,SAAS,MAAM,EAAE,EACzB,YAAY,SAA4B,GACvC,MAAM,EAAE,CAeV;AAED;;;GAGG;AACH,wBAAgB,6BAA6B,CAC3C,OAAO,EAAE,0BAA0B,EACnC,IAAI,EAAE,wBAAwB,GAC7B,uBAAuB,CAgDzB"}

package/dist/smartCdnImage.js

@@ -0,0 +1,137 @@
+const defaultSmartCdnImageFormats = { avif: 45, webp: 75 };
+const minimumMillisecondTimestamp = 1_000_000_000_000;
+const smartCdnImageFormats = ['avif', 'webp', 'png'];
+const smartCdnImageMaxWidths = 32;
+/** Maximum requested width or height accepted by the responsive-image Built-ins. */
+export const smartCdnImageMaxDimension = 8000;
+function isSmartCdnImageFormat(value) {
+    return value === 'avif' || value === 'png' || value === 'webp';
+}
+function validatePositiveSafeInteger(value, name) {
+    if (!Number.isSafeInteger(value) || value <= 0) {
+        throw new RangeError(`${name} must be a positive safe integer`);
+    }
+}
+function validateSmartCdnImageDimension(value, name) {
+    if (!Number.isInteger(value) || value < 1 || value > smartCdnImageMaxDimension) {
+        throw new RangeError(`${name} must be an integer from 1 through ${smartCdnImageMaxDimension}`);
+    }
+}
+function validateSmartCdnImageQuality(quality) {
+    if (!Number.isInteger(quality) || quality < 1 || quality > 100) {
+        throw new RangeError('quality must be an integer from 1 through 100');
+    }
+}
+function validateSmartCdnImageInput(input) {
+    if (typeof input !== 'string' || input === '' || input.trim() !== input || input.includes('|')) {
+        throw new TypeError('input must be one non-empty Template input string');
+    }
+}
+function validateSmartCdnImageFallbackUrl(fallbackUrl) {
+    if (typeof fallbackUrl !== 'string' || fallbackUrl === '' || fallbackUrl.trim() !== fallbackUrl) {
+        throw new TypeError('fallbackUrl must be a non-empty string without surrounding whitespace');
+    }
+}
+function validateSmartCdnImageTemplate(template) {
+    if (typeof template !== 'string' || template === '' || template.trim() !== template) {
+        throw new TypeError('template must be a non-empty string without surrounding whitespace');
+    }
+}
+/** Resolves and validates format-specific qualities in deterministic browser preference order. */
+export function resolveSmartCdnImageFormats(formats) {
+    const resolved = formats ?? defaultSmartCdnImageFormats;
+    for (const format of Object.keys(resolved)) {
+        if (!isSmartCdnImageFormat(format)) {
+            throw new TypeError(`Unsupported Smart CDN image format: ${format}`);
+        }
+    }
+    const selected = [];
+    for (const format of smartCdnImageFormats) {
+        if (!Object.hasOwn(resolved, format))
+            continue;
+        const quality = resolved[format];
+        if (quality === undefined)
+            continue;
+        validateSmartCdnImageQuality(quality);
+        selected.push({ format, quality });
+    }
+    if (selected.length === 0)
+        throw new TypeError('formats must contain at least one value');
+    return selected;
+}
+function getMaximumCandidateWidth(sourceDimensions) {
+    if (sourceDimensions === undefined)
+        return smartCdnImageMaxDimension;
+    validatePositiveSafeInteger(sourceDimensions.width, 'sourceDimensions.width');
+    validatePositiveSafeInteger(sourceDimensions.height, 'sourceDimensions.height');
+    const heightLimitedWidth = Number((BigInt(smartCdnImageMaxDimension) * BigInt(sourceDimensions.width)) /
+        BigInt(sourceDimensions.height));
+    if (heightLimitedWidth < 1) {
+        // Even a one-pixel-wide rendition would exceed the backend height limit; no truthful candidate
+        // can preserve this aspect ratio.
+        throw new RangeError('sourceDimensions aspect ratio cannot fit within backend dimensions');
+    }
+    return Math.min(smartCdnImageMaxDimension, sourceDimensions.width, heightLimitedWidth);
+}
+/** Validates, caps, deduplicates, and sorts requested responsive-image widths. */
+export function resolveSmartCdnImageWidths(widths, maximumWidth = smartCdnImageMaxDimension) {
+    if (!Array.isArray(widths) || widths.length === 0) {
+        throw new TypeError('widths must contain at least one value');
+    }
+    if (widths.length > smartCdnImageMaxWidths) {
+        throw new RangeError(`widths must contain at most ${smartCdnImageMaxWidths} values`);
+    }
+    validateSmartCdnImageDimension(maximumWidth, 'maximumWidth');
+    const candidates = new Set();
+    for (const [index, width] of widths.entries()) {
+        validateSmartCdnImageDimension(width, `widths[${index}]`);
+        candidates.add(Math.min(width, maximumWidth));
+    }
+    return [...candidates].sort((left, right) => left - right);
+}
+/**
+ * Creates signed responsive-image candidates while leaving credential storage and HMAC choice to
+ * the injected signer.
+ */
+export function createSmartCdnImageCandidates(options, sign) {
+    const expiresAt = options.expiresAt;
+    const fallbackUrl = options.fallbackUrl;
+    const formatOptions = options.formats;
+    const formatsSnapshot = formatOptions === undefined ? undefined : { ...formatOptions };
+    const input = options.input;
+    const sourceDimensionOptions = options.sourceDimensions;
+    const sourceDimensions = sourceDimensionOptions === undefined
+        ? undefined
+        : { height: sourceDimensionOptions.height, width: sourceDimensionOptions.width };
+    const template = options.template;
+    const widthOptions = options.widths;
+    const widthsSnapshot = Array.isArray(widthOptions) ? [...widthOptions] : widthOptions;
+    validatePositiveSafeInteger(expiresAt, 'expiresAt');
+    if (expiresAt < minimumMillisecondTimestamp) {
+        throw new RangeError('expiresAt must be a millisecond timestamp');
+    }
+    validateSmartCdnImageFallbackUrl(fallbackUrl);
+    validateSmartCdnImageInput(input);
+    validateSmartCdnImageTemplate(template);
+    if (typeof sign !== 'function')
+        throw new TypeError('sign must be a function');
+    const formats = resolveSmartCdnImageFormats(formatsSnapshot);
+    const widths = resolveSmartCdnImageWidths(widthsSnapshot, getMaximumCandidateWidth(sourceDimensions));
+    const sources = [];
+    for (const { format, quality } of formats) {
+        sources.push({
+            candidates: widths.map((width) => ({
+                url: sign({
+                    expiresAt,
+                    input,
+                    template,
+                    urlParams: { f: format, q: quality, r: 'fit', w: width },
+                }),
+                width,
+            })),
+            format,
+            quality,
+        });
+    }
+    return { fallbackUrl, sources };
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@transloadit/utils",
-  "version": "4.6.0",
+  "version": "4.7.1",
   "description": "Transloadit shared utilities",
   "type": "module",
   "license": "MIT",