@transloadit/utils 4.4.1 → 4.5.1

package/README.md

@@ -24,7 +24,11 @@ const verified = await verifyWebhookSignature({
 ## Node usage
 
 ```ts
-import { signParamsSync, getSignedSmartCdnUrl } from '@transloadit/utils/node'
+import {
+  getSignedSmartCdnImageCandidates,
+  getSignedSmartCdnUrl,
+  signParamsSync,
+} from '@transloadit/utils/node'
 
 const signature = signParamsSync(paramsString, authSecret)
 const url = getSignedSmartCdnUrl({
@@ -34,6 +38,19 @@ const url = getSignedSmartCdnUrl({
   authKey,
   authSecret,
 })
+const imageCandidates = getSignedSmartCdnImageCandidates({
+  authKey,
+  authSecret,
+  // Reuse one absolute expiry across a build instead of recomputing it per request.
+  expiresAt,
+  input: 'https://example.com/image.jpg',
+  widths: [320, 640, 960],
+  workspace,
+})
+
+for (const source of imageCandidates.sources) {
+  console.log(source.format, source.quality, source.candidates)
+}
 ```
 
 ## API
@@ -42,3 +59,5 @@ const url = getSignedSmartCdnUrl({
 - `verifyWebhookSignature({ rawBody, signatureHeader, authSecret })`: validates webhook signatures.
 - `signParamsSync(paramsString, authSecret, algorithm?)`: Node-only sync signature helper.
 - `getSignedSmartCdnUrl(options)`: Node-only Smart CDN URL signer.
+- `getSignedSmartCdnImageCandidates(options)`: deterministic structured, signed AVIF and WebP
+  candidates plus the original fallback URL.

package/dist/node.d.ts

@@ -1,6 +1,43 @@
 import type { SignatureAlgorithm } from './index.ts';
 export type { SignatureAlgorithm } from './index.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 {
+    /** 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;
+}
 export type SmartCdnUrlOptions = {
     /**
      * Workspace slug.
@@ -34,4 +71,11 @@ export type SmartCdnUrlOptions = {
 };
 export declare const signParamsSync: (paramsString: string, authSecret: string, algorithm?: SignatureAlgorithmInput) => string;
 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.
+ */
+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;AAIpD,YAAY,EAAE,kBAAkB,EAAE,MAAM,YAAY,CAAA;AAEpD,MAAM,MAAM,uBAAuB,GAAG,kBAAkB,GAAG,CAAC,MAAM,GAAG,EAAE,CAAC,CAAA;AAExE,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,eAAO,MAAM,cAAc,GACzB,cAAc,MAAM,EACpB,YAAY,MAAM,EAClB,YAAW,uBAAkC,KAC5C,MAKF,CAAA;AAED,eAAO,MAAM,oBAAoB,GAAI,MAAM,kBAAkB,KAAG,MA8B/D,CAAA"}
+{"version":3,"file":"node.d.ts","sourceRoot":"","sources":["../src/node.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,kBAAkB,EAAE,MAAM,YAAY,CAAA;AAIpD,YAAY,EAAE,kBAAkB,EAAE,MAAM,YAAY,CAAA;AAEpD,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;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;;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;AAkED,eAAO,MAAM,cAAc,GACzB,cAAc,MAAM,EACpB,YAAY,MAAM,EAClB,YAAW,uBAAkC,KAC5C,MAKF,CAAA;AAED,eAAO,MAAM,oBAAoB,GAAI,MAAM,kBAAkB,KAAG,MA8B/D,CAAA;AAED;;;;;GAKG;AACH,wBAAgB,gCAAgC,CAC9C,IAAI,EAAE,8BAA8B,GACnC,uBAAuB,CAsDzB"}

package/dist/node.js

@@ -1,4 +1,56 @@
 import { createHmac } from 'node:crypto';
+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');
+    }
+}
 export const signParamsSync = (paramsString, authSecret, algorithm = 'sha384') => {
     const signature = createHmac(algorithm, authSecret)
         .update(Buffer.from(paramsString, 'utf-8'))
@@ -35,3 +87,59 @@ export const getSignedSmartCdnUrl = (opts) => {
     queryParams.set('sig', `sha256:${signature}`);
     return `https://${workspaceSlug}.tlcdn.com/${templateSlug}/${inputField}?${queryParams}`;
 };
+/**
+ * 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.
+ */
+export function getSignedSmartCdnImageCandidates(opts) {
+    if (typeof opts.authKey !== 'string' || opts.authKey === '') {
+        throw new TypeError('authKey is required');
+    }
+    if (typeof opts.authSecret !== 'string' || opts.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 };
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@transloadit/utils",
-  "version": "4.4.1",
+  "version": "4.5.1",
   "description": "Transloadit shared utilities",
   "type": "module",
   "license": "MIT",
@@ -27,9 +27,10 @@
     "./package.json": "./package.json"
   },
   "scripts": {
-    "lint:ts": "../../node_modules/.bin/tsc --build tsconfig.build.json",
+    "lint:ts": "../../node_modules/.bin/tsc --build tsconfig.build.json && ../../node_modules/.bin/tsc --noEmit --project tsconfig.json",
     "build": "../../node_modules/.bin/tsc --build tsconfig.build.json",
-    "check": "yarn lint:ts",
+    "check": "yarn lint:ts && yarn test:unit",
+    "test:unit": "../../node_modules/.bin/vitest run ./test",
     "prepack": "yarn build"
   },
   "devDependencies": {