@capacms/sdk 1.0.0-next.0 → 1.0.0-next.10

package/dist/http.js

@@ -10,7 +10,7 @@ class CapaError extends Error {
     status;
     path;
     constructor(status, path, body) {
-        super(`Capa API ${status} on ${path}${body ? ` — ${body.slice(0, 200)}` : ""}`);
+        super(`Capa API ${status} on ${path}${body ? `: ${body.slice(0, 200)}` : ""}`);
         this.name = "CapaError";
         this.status = status;
         this.path = path;

package/dist/image/index.d.ts

@@ -0,0 +1,120 @@
+/**
+ * `@capacms/sdk/image`: URLs for Capa's image CDN, for any framework.
+ *
+ * Capa serves every upload at `https://cdn.capacms.com/files/<key>` and
+ * resizes it by query: `width`, `height`, `fit`, `quality`, `dpr`, `blur` and
+ * `format`. The API answers a URL whose query is spelled any other way than
+ * its canonical spelling with a 301 the edge keeps for a year, so every URL
+ * built here is already canonical. The spelling is not decided here: it comes
+ * from the rules the API serves by (`canonicalQuery` and `parseImageParams`,
+ * compiled in from @capa/shared at build time), so the two cannot drift.
+ *
+ * Three rules beside the API's:
+ * - Nothing is enlarged. When the image's own width is known (the `/api/`
+ *   media shape carries it), a request for more pixels than it has is brought
+ *   down to its size, keeping the requested shape.
+ * - `format=auto` is only sent when asked for.
+ * - A URL that is not a Capa image comes back unchanged.
+ *
+ * A stored URL on `api.capacms.com/files/` (older uploads) names the same file
+ * as the CDN: the CDN fetches from that host. Built URLs go to the CDN host,
+ * where a resized copy is cached at the edge rather than made again by the
+ * origin on every request.
+ */
+import { MAX_OUTPUT_EDGE, type ImageFit, type ImageFormat } from "./shared-params.generated.js";
+export type { ImageFit, ImageFormat };
+export { MAX_OUTPUT_EDGE };
+/** Where Capa serves files. A media `url` from the API starts with this and `/files/`. */
+export declare const CAPA_CDN_ORIGIN = "https://cdn.capacms.com";
+/**
+ * True when `src` is a full URL of a file on Capa: `https://cdn.capacms.com/files/...`
+ * or `https://api.capacms.com/files/...`. A key, a path or another host is not.
+ * Use it to mark the other images `unoptimized` in next/image.
+ */
+export declare function isCapaImageUrl(src: string): boolean;
+/**
+ * A media value: the `/api/` shape `{ id, url, alt, type, width, height }`, the
+ * legacy client's `CapaImage`, or anything else with a `url`. `width` and
+ * `height` are the image's own pixel size, used so it is never enlarged.
+ */
+export interface ImageLike {
+    url: string | null;
+    width?: number | null;
+    height?: number | null;
+    /** The file's kind. Anything but `image` (or a missing kind) is returned unchanged. */
+    type?: string | null;
+}
+/** A media value, a full CDN URL, or a file key (`sunns_1790971326210_d54fed020806.jpg`). */
+export type ImageSource = string | ImageLike;
+/** What Capa's CDN can do to an image. Every one is optional, and a default is left out of the URL. */
+export interface ImageOptions {
+    /** Width in CSS pixels; with `dpr`, the image is `width × dpr` pixels wide. */
+    width?: number | null;
+    /** Height in CSS pixels. */
+    height?: number | null;
+    /** How the image meets a box given by both `width` and `height`: `inside` (the default), `cover` (crop) or `contain` (pad). */
+    fit?: ImageFit;
+    /** 1 to 100; Capa's default is 80. Ignored for png. */
+    quality?: number;
+    /** Device pixel ratio, 1 to 3. */
+    dpr?: number;
+    /** A blurred placeholder `blur × blur` pixels square, 1 to 256. */
+    blur?: number;
+    /**
+     * The format to encode. Left out, the image keeps its own format. `auto`
+     * picks AVIF or WebP from the browser's `Accept` header; through the CDN it
+     * currently returns JPEG, so use `webp` until that is fixed.
+     */
+    format?: ImageFormat;
+}
+/** The options `srcSet` takes: each candidate's width comes from its list, and its height from `aspectRatio`. */
+export interface SrcSetOptions {
+    /** Width over height. Given, each candidate is `width` by `width / aspectRatio`; use it with `fit: "cover"` to crop. */
+    aspectRatio?: number;
+    fit?: ImageFit;
+    quality?: number;
+    format?: ImageFormat;
+}
+/**
+ * The URL of a Capa image, resized as `options` say, spelled exactly as Capa's
+ * CDN serves it without a redirect.
+ *
+ * `image` is a media value (`entry.fields.hero`), a CDN URL, or a file key.
+ * Gives `undefined` when there is no image (`null`, or a media value whose
+ * `url` is null or empty, which is how the legacy API sends an unset image),
+ * so a media value always gives `string | undefined`; a string always gives a
+ * string. Gives back unchanged a URL that is not a Capa image (another host, a
+ * site path) or a media value that is not an image. Throws a `TypeError` for
+ * an option Capa would refuse with a 400.
+ *
+ * ```ts
+ * imageUrl(entry.fields.hero, { width: 1200, format: "webp" })
+ * // https://cdn.capacms.com/files/<key>?format=webp&width=1200
+ * ```
+ */
+export declare function imageUrl(image: string, options?: ImageOptions): string;
+export declare function imageUrl(image: ImageSource | null | undefined, options?: ImageOptions): string | undefined;
+/**
+ * A `srcset` for a Capa image: one candidate per width, smallest first, each
+ * as `<url> <width>w`. Widths past the image's own width (when known) are
+ * dropped in favour of one candidate at its own width.
+ *
+ * Gives `undefined` when there is nothing to resize: no image, or one that is
+ * not Capa's. Throws a `TypeError` for a width list that is empty or not whole
+ * pixels, or an option Capa would refuse.
+ *
+ * ```ts
+ * srcSet(entry.fields.hero, [640, 960, 1280, 1920], { format: "webp" })
+ * ```
+ */
+export declare function srcSet(image: ImageSource | null | undefined, widths: readonly number[], options?: SrcSetOptions): string | undefined;
+/**
+ * A `sizes` attribute from min-width breakpoints, widest first so the first
+ * match is the right one, then the fallback.
+ *
+ * ```ts
+ * sizes({ 768: "50vw", 1280: "33vw" })
+ * // (min-width: 1280px) 33vw, (min-width: 768px) 50vw, 100vw
+ * ```
+ */
+export declare function sizes(breakpoints: Readonly<Record<number, string>>, fallback?: string): string;

package/dist/image/index.js

@@ -0,0 +1,257 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.CAPA_CDN_ORIGIN = exports.MAX_OUTPUT_EDGE = void 0;
+exports.isCapaImageUrl = isCapaImageUrl;
+exports.imageUrl = imageUrl;
+exports.srcSet = srcSet;
+exports.sizes = sizes;
+/**
+ * `@capacms/sdk/image`: URLs for Capa's image CDN, for any framework.
+ *
+ * Capa serves every upload at `https://cdn.capacms.com/files/<key>` and
+ * resizes it by query: `width`, `height`, `fit`, `quality`, `dpr`, `blur` and
+ * `format`. The API answers a URL whose query is spelled any other way than
+ * its canonical spelling with a 301 the edge keeps for a year, so every URL
+ * built here is already canonical. The spelling is not decided here: it comes
+ * from the rules the API serves by (`canonicalQuery` and `parseImageParams`,
+ * compiled in from @capa/shared at build time), so the two cannot drift.
+ *
+ * Three rules beside the API's:
+ * - Nothing is enlarged. When the image's own width is known (the `/api/`
+ *   media shape carries it), a request for more pixels than it has is brought
+ *   down to its size, keeping the requested shape.
+ * - `format=auto` is only sent when asked for.
+ * - A URL that is not a Capa image comes back unchanged.
+ *
+ * A stored URL on `api.capacms.com/files/` (older uploads) names the same file
+ * as the CDN: the CDN fetches from that host. Built URLs go to the CDN host,
+ * where a resized copy is cached at the edge rather than made again by the
+ * origin on every request.
+ */
+const shared_params_generated_js_1 = require("./shared-params.generated.js");
+Object.defineProperty(exports, "MAX_OUTPUT_EDGE", { enumerable: true, get: function () { return shared_params_generated_js_1.MAX_OUTPUT_EDGE; } });
+/** Where Capa serves files. A media `url` from the API starts with this and `/files/`. */
+exports.CAPA_CDN_ORIGIN = "https://cdn.capacms.com";
+/**
+ * The API's own host, which some stored URLs name (`https://api.capacms.com/files/<key>`).
+ * It is the CDN's origin, with nothing in front of it, so the same key is the
+ * same file on both; a URL built here always names the CDN.
+ */
+const CAPA_API_ORIGIN = "https://api.capacms.com";
+const CAPA_ORIGINS = new Set([exports.CAPA_CDN_ORIGIN, CAPA_API_ORIGIN]);
+const FILES_PATH = "/files/";
+/** A full `https://` URL of a file on Capa's CDN or API host, as a URL, or null. */
+function capaFileUrl(text) {
+    let url;
+    try {
+        url = new URL(text);
+    }
+    catch {
+        return null;
+    }
+    if (!CAPA_ORIGINS.has(url.origin) || !url.pathname.startsWith(FILES_PATH) || url.pathname.length === FILES_PATH.length)
+        return null;
+    // The same path, query and fragment on the CDN host.
+    return url.origin === exports.CAPA_CDN_ORIGIN ? url : new URL(`${url.pathname}${url.search}${url.hash}`, exports.CAPA_CDN_ORIGIN);
+}
+/**
+ * True when `src` is a full URL of a file on Capa: `https://cdn.capacms.com/files/...`
+ * or `https://api.capacms.com/files/...`. A key, a path or another host is not.
+ * Use it to mark the other images `unoptimized` in next/image.
+ */
+function isCapaImageUrl(src) {
+    return typeof src === "string" && /^https:\/\//i.test(src) && capaFileUrl(src) !== null;
+}
+const OPTION_KEYS = ["width", "height", "fit", "quality", "dpr", "blur", "format"];
+function positive(value) {
+    return typeof value === "number" && Number.isFinite(value) && value > 0 ? value : undefined;
+}
+/** True when `text` names a scheme (`https:`, `data:`), so it is a URL rather than a file key. */
+function hasScheme(text) {
+    return /^[a-z][a-z0-9+.-]*:/i.test(text);
+}
+/** A string or `url` as a Capa image, or why not. */
+function resolveUrl(text, image) {
+    if (hasScheme(text)) {
+        const url = capaFileUrl(text);
+        if (url === null)
+            return { unchanged: text };
+        return { target: { url, intrinsicWidth: positive(image?.width), intrinsicHeight: positive(image?.height) } };
+    }
+    // A path (`/logo.png`, `//host/x`) is the site's own or another host's.
+    if (text === "" || text.startsWith("/"))
+        return { unchanged: text };
+    // A file key, which may hold folders: each segment is encoded on its own.
+    const path = text.split("/").map(encodeURIComponent).join("/");
+    return { target: { url: new URL(`${exports.CAPA_CDN_ORIGIN}${FILES_PATH}${path}`), intrinsicWidth: positive(image?.width), intrinsicHeight: positive(image?.height) } };
+}
+function resolve(image) {
+    if (image === null || image === undefined)
+        return null;
+    if (typeof image === "string")
+        return resolveUrl(image);
+    if (typeof image !== "object" || typeof image.url !== "string" || image.url === "")
+        return null;
+    if (typeof image.type === "string" && image.type !== "image" && !image.type.startsWith("image/"))
+        return { unchanged: image.url };
+    return resolveUrl(image.url, image);
+}
+/** A number from a query value, when it is one. */
+function numeric(value) {
+    if (typeof value !== "string" || !/^\d+(\.\d+)?$/.test(value.trim()))
+        return undefined;
+    return positive(Number(value));
+}
+/**
+ * Brings a request that would enlarge the image down to the image's own size.
+ *
+ * The scale the request puts on the image's content is worked out for its
+ * fit. `inside` and `contain` fit the image within the box, so the smaller of
+ * the two ratios rules and both sizes must be known; `cover` fills the box, so
+ * the larger rules, and with only the width known the width's ratio is a floor
+ * on it. Above 1, the box is divided by that scale, which keeps its shape and
+ * makes the content its own size. Nothing changes when the scale cannot be
+ * worked out. Blur is left alone: its size comes from `blur`, not the box.
+ */
+function capToImage(query, target) {
+    const W = target.intrinsicWidth;
+    const H = target.intrinsicHeight;
+    if ((W === undefined && H === undefined) || query.blur !== undefined)
+        return;
+    const width = numeric(query.width);
+    const height = numeric(query.height);
+    const dpr = numeric(query.dpr) ?? 1;
+    const fit = typeof query.fit === "string" ? query.fit.trim().toLowerCase() : "inside";
+    const sw = width !== undefined && W !== undefined ? (width * dpr) / W : undefined;
+    const sh = height !== undefined && H !== undefined ? (height * dpr) / H : undefined;
+    let scale;
+    if (width !== undefined && height === undefined)
+        scale = sw;
+    else if (height !== undefined && width === undefined)
+        scale = sh;
+    else if (width !== undefined && height !== undefined) {
+        if (fit === "cover")
+            scale = sh === undefined ? sw : sw === undefined ? sh : Math.max(sw, sh);
+        else
+            scale = sw === undefined || sh === undefined ? undefined : Math.min(sw, sh);
+    }
+    if (scale === undefined || scale <= 1)
+        return;
+    // The epsilon keeps a division that is exact on paper (1600 / (4/3)) from flooring to one less.
+    const down = (n) => String(Math.max(1, Math.floor(n / scale + 1e-9)));
+    if (width !== undefined)
+        query.width = down(width);
+    if (height !== undefined)
+        query.height = down(height);
+}
+function fail(fn, message) {
+    throw new TypeError(`@capacms/sdk: ${fn}: ${message}`);
+}
+/** The canonical URL for a Capa image, and the pixel width it asks for. */
+function build(fn, target, options) {
+    const { url } = target;
+    const search = url.search.slice(1);
+    // The URL's own image parameters, as Fastify would hand them to the API.
+    const query = {};
+    for (const [key, value] of new URLSearchParams(search)) {
+        if (!shared_params_generated_js_1.LEGACY_PARAMS.has(key) && !shared_params_generated_js_1.NEW_PARAMS.has(key))
+            continue;
+        const prior = query[key];
+        query[key] = prior === undefined ? value : [].concat(prior, value);
+    }
+    // The options win over them.
+    for (const key of OPTION_KEYS) {
+        const value = options[key];
+        if (value !== undefined && value !== null)
+            query[key] = String(value);
+    }
+    capToImage(query, target);
+    const parsed = (0, shared_params_generated_js_1.parseImageParams)(query);
+    if (!parsed.ok)
+        fail(fn, parsed.rejection.error);
+    const canonical = (0, shared_params_generated_js_1.canonicalQuery)(search, parsed.params);
+    const href = `${url.origin}${url.pathname}${canonical ? `?${canonical}` : ""}${url.hash}`;
+    return { href, width: parsed.params.width };
+}
+function imageUrl(image, options = {}) {
+    const resolved = resolve(image);
+    if (resolved === null)
+        return undefined;
+    if ("unchanged" in resolved)
+        return resolved.unchanged;
+    return build("imageUrl", resolved.target, options).href;
+}
+/**
+ * A `srcset` for a Capa image: one candidate per width, smallest first, each
+ * as `<url> <width>w`. Widths past the image's own width (when known) are
+ * dropped in favour of one candidate at its own width.
+ *
+ * Gives `undefined` when there is nothing to resize: no image, or one that is
+ * not Capa's. Throws a `TypeError` for a width list that is empty or not whole
+ * pixels, or an option Capa would refuse.
+ *
+ * ```ts
+ * srcSet(entry.fields.hero, [640, 960, 1280, 1920], { format: "webp" })
+ * ```
+ */
+function srcSet(image, widths, options = {}) {
+    if (!Array.isArray(widths) || widths.length === 0 || !widths.every((w) => Number.isSafeInteger(w) && w > 0)) {
+        fail("srcSet", `widths must be a list of whole pixel widths, such as [640, 1280]. Got ${JSON.stringify(widths)}.`);
+    }
+    const loose = options;
+    if (loose.width !== undefined)
+        fail("srcSet", "srcSet takes its widths as the second argument, not a `width` option.");
+    if (loose.height !== undefined)
+        fail("srcSet", "give `aspectRatio` (width / height) rather than `height`; each candidate's height follows its width.");
+    if (loose.dpr !== undefined || loose.blur !== undefined) {
+        fail("srcSet", "`dpr` and `blur` do not apply to a srcset: the browser picks a candidate by its w descriptor.");
+    }
+    const { aspectRatio } = options;
+    if (aspectRatio !== undefined && positive(aspectRatio) === undefined) {
+        fail("srcSet", `\`aspectRatio\` must be a positive number (width / height). Got ${JSON.stringify(aspectRatio)}.`);
+    }
+    const resolved = resolve(image);
+    if (resolved === null || "unchanged" in resolved)
+        return undefined;
+    const seen = new Set();
+    const candidates = [];
+    for (const width of [...new Set(widths)].sort((a, b) => a - b)) {
+        const height = aspectRatio === undefined ? undefined : Math.max(1, Math.round(width / aspectRatio));
+        const { href, width: built } = build("srcSet", resolved.target, {
+            width,
+            height,
+            fit: options.fit,
+            quality: options.quality,
+            format: options.format,
+        });
+        if (seen.has(href))
+            continue;
+        seen.add(href);
+        candidates.push(`${href} ${built ?? width}w`);
+    }
+    return candidates.join(", ");
+}
+/**
+ * A `sizes` attribute from min-width breakpoints, widest first so the first
+ * match is the right one, then the fallback.
+ *
+ * ```ts
+ * sizes({ 768: "50vw", 1280: "33vw" })
+ * // (min-width: 1280px) 33vw, (min-width: 768px) 50vw, 100vw
+ * ```
+ */
+function sizes(breakpoints, fallback = "100vw") {
+    const rules = [];
+    for (const [key, size] of Object.entries(breakpoints)) {
+        const px = Number(key);
+        if (!/^\d+$/.test(key) || px <= 0)
+            fail("sizes", `breakpoints are min-widths in pixels, such as { 768: "50vw" }. Got ${JSON.stringify(key)}.`);
+        if (typeof size !== "string" || size.trim() === "")
+            fail("sizes", `the size for ${key}px must be a length, such as "50vw". Got ${JSON.stringify(size)}.`);
+        rules.push([px, size.trim()]);
+    }
+    if (typeof fallback !== "string" || fallback.trim() === "")
+        fail("sizes", `the fallback must be a length, such as "100vw". Got ${JSON.stringify(fallback)}.`);
+    rules.sort(([a], [b]) => b - a);
+    return [...rules.map(([px, size]) => `(min-width: ${px}px) ${size}`), fallback.trim()].join(", ");
+}

package/dist/image/shared-params.generated.d.ts

@@ -0,0 +1,190 @@
+/**
+ * Query parsing, validation and canonicalisation for `GET /files/*`
+ * (ADMIN_UI_OVERHAUL §0i.1, "The image processor, made tight").
+ *
+ * PURE ON PURPOSE. Nothing here touches sharp, the network or the database, so
+ * the whole parameter surface — every accepted value, every rejection, and the
+ * canonical spelling of every URL — is testable without a server and without a
+ * live Backblaze object. That matters for this route in particular: its eight
+ * parity fixtures are all 400/404 cases because a DB hit immediately leaves the
+ * process (docs/TURBINE_PORT_NOTES.md, "Deferred to the P6 cloud parity pass"),
+ * so the transform surface has no golden coverage at all unless it is reachable
+ * from a unit test.
+ *
+ * THE RULE THAT SHAPES EVERYTHING BELOW: a caller that sends only today's three
+ * parameters (`width`, `height`, `blur`) must get today's response. Every
+ * default here is therefore today's behaviour, and the one place that could
+ * have broken it — the canonical-query redirect — is deliberately gated on a
+ * NEW parameter being present. See `canonicalise`.
+ *
+ * WHY IT LIVES IN @capa/shared. `@capacms/sdk` builds image URLs, and a URL
+ * that is not spelled the way `canonicalise` spells it costs every first view
+ * a 301 that the edge then keeps for a year. So the SDK compiles this file into
+ * its own build rather than keeping a second copy of the rules, and its tests
+ * run what it builds back through `canonicalise`. The API imports it from here.
+ */
+export type ImageFit = "inside" | "cover" | "contain";
+export type ImageFormat = "webp" | "avif" | "jpeg" | "png" | "auto";
+export type ConcreteFormat = Exclude<ImageFormat, "auto">;
+/** Content type emitted for each explicitly requestable output format. */
+export declare const OUTPUT_MIME: Record<ConcreteFormat, string>;
+/**
+ * The longest edge this route will ever produce.
+ *
+ * A cap rather than a clamp, because a clamp makes two different URLs return
+ * the same bytes and therefore occupy two edge objects for one representation.
+ * 4096 is the §0i.1 figure; it is also comfortably above any real layout width
+ * at dpr 3 (1365 CSS px).
+ */
+export declare const MAX_OUTPUT_EDGE = 4096;
+/** Today's blur bounds, previously applied as a silent clamp. */
+export declare const MIN_BLUR = 1;
+export declare const MAX_BLUR = 256;
+/** Default quality for lossy outputs except AVIF. Ignored for png, which is lossless. */
+export declare const DEFAULT_QUALITY = 80;
+/**
+ * AVIF's own default quality (Penelope Hospitality onboarding, #300). At 80,
+ * AVIF came back larger than WebP at 80; 60 at effort 2 is 16 to 18% smaller
+ * than WebP with equal or better SSIM on eight client photos. The route's
+ * encoder and the effort live in apps/api (image-transform.ts); the number
+ * lives here because canonicalQuery has to know it (see droppableQuality).
+ */
+export declare const AVIF_DEFAULT_QUALITY = 60;
+/**
+ * The quality an encode into `output` uses when the URL names none.
+ *
+ * The route only ever calls this with a format the URL asked for, explicitly or
+ * through `auto`: with no `format` and no `quality` it selects no encoder at
+ * all and the source keeps its own format (`resolveOutputFormat`).
+ */
+export declare function defaultQuality(output: ConcreteFormat): number;
+/**
+ * The `quality` canonicalQuery drops from a URL with this `format`, or null
+ * when it keeps every value.
+ *
+ * CANONICALISATION MUST NEVER CHANGE WHAT A URL RENDERS. A value may be dropped
+ * only when the URL without it encodes at that same value. After #300 gave
+ * AVIF its own default, dropping 80 everywhere sent `format=avif&quality=80`
+ * to `format=avif`, which is quality 60.
+ *
+ * - `avif`: null. 80 is not AVIF's default, so it must stay. 60 is, and could
+ *   be dropped without changing the bytes; it is KEPT ON PURPOSE. The SDK's
+ *   frozen URLs (#316, and @capacms/sdk's own tests) include
+ *   `format=avif&quality=60`, which would start taking a 301; and an explicit
+ *   number keeps meaning that number if AVIF's default is retuned, which
+ *   `format=avif` does not. The cost is two edge objects for one image when a
+ *   caller spells the default out.
+ * - `auto`: null. Negotiation picks AVIF (default 60) or WebP or the source's
+ *   own format (default 80), so no single value means "no quality" for every
+ *   browser.
+ * - `webp`, `jpeg`, `png` and no format: DEFAULT_QUALITY, as before.
+ *
+ * KNOWN GAP, older than #300 and left as it is because a URL with no `format`
+ * keeps its spelling: with no format the output follows the SOURCE, which a URL
+ * cannot see. `?quality=80&width=200` on an AVIF or HEIF source is an AVIF at
+ * 80, and `?width=200` keeps sharp's own AVIF default (50). `?quality=80` with
+ * nothing else redirects to the bare URL, which is the stored file, not a
+ * re-encode.
+ */
+export declare function droppableQuality(format: ImageFormat | undefined): number | null;
+/**
+ * The parameters that existed before §0i.1.
+ *
+ * A URL built only from these is GRANDFATHERED: it is treated as already
+ * canonical and is never redirected, however it is spelled. Without this, every
+ * live `?width=100&height=50` in every customer's markup would start taking a
+ * 301 — which is not a behaviour anyone asked to change, and "keep today's
+ * calls byte-identical" outranks de-duplicating an edge object that has been
+ * duplicated for years already.
+ */
+export declare const LEGACY_PARAMS: Set<string>;
+/** Parameters introduced by §0i.1. Their presence is what enables canonicalisation. */
+export declare const NEW_PARAMS: Set<string>;
+export interface ImageParams {
+    /** Requested width AFTER dpr multiplication. */
+    width?: number;
+    /** Requested height AFTER dpr multiplication. */
+    height?: number;
+    blur?: number;
+    format?: ImageFormat;
+    /** Present only when the caller asked for it — see `quality` in `buildSignature`. */
+    quality?: number;
+    fit: ImageFit;
+    dpr: number;
+    upscale: boolean;
+    keepMetadata: boolean;
+    /** True when any parameter that changes the bytes was supplied. */
+    wantsTransform: boolean;
+}
+export interface ParamRejection {
+    error: string;
+    param: string;
+}
+export type ParseResult = {
+    ok: true;
+    params: ImageParams;
+} | {
+    ok: false;
+    rejection: ParamRejection;
+};
+/**
+ * Parse and validate the whole query in one pass.
+ *
+ * Unknown VALUES for a known parameter are rejected. Unknown KEYS are not:
+ * `?v=3` cache-busters and analytics tags are real traffic on a public CDN
+ * origin, and turning them into 400s would break callers who are not using the
+ * image surface at all. They are carried through canonicalisation untouched.
+ */
+export declare function parseImageParams(query: Record<string, unknown>): ParseResult;
+export interface CanonicalResult {
+    /** The canonical query STRING, without a leading `?`. Empty when there is none. */
+    query: string;
+    /** True when the caller's spelling already matches and no redirect is owed. */
+    isCanonical: boolean;
+}
+/**
+ * The canonical spelling of a query, so `?width=200&format=webp` and
+ * `?format=webp&width=200` are one edge object rather than two.
+ *
+ * GATED, DELIBERATELY. Canonicalisation only applies once the caller uses a
+ * parameter introduced by §0i.1. A URL made only of `width`/`height`/`blur` is
+ * declared canonical as received, whatever its key order — see LEGACY_PARAMS
+ * for why. The gate is also what keeps the `files-404-params-ignored` parity
+ * fixture (`?width=100&height=50&blur=9`) from becoming a 301.
+ *
+ * @param rawQuery the query string as received, without the leading `?`
+ */
+export declare function canonicalise(rawQuery: string, params: ImageParams): CanonicalResult;
+/**
+ * The canonical spelling itself, without `canonicalise`'s gate.
+ *
+ * `canonicalise` is this plus the LEGACY_PARAMS grandfather clause. For a query
+ * that uses a new parameter the two agree; for one made only of
+ * `width`/`height`/`blur` this still sorts and re-spells it, which the API
+ * accepts as canonical too, since the gate declares any legacy spelling
+ * canonical. So a URL built with this is never redirected, whichever
+ * parameters it carries. @capacms/sdk builds every image URL with it.
+ *
+ * @param rawQuery the query string, without the leading `?`; read only for the
+ *   keys this module does not know, which are kept
+ */
+export declare function canonicalQuery(rawQuery: string, params: ImageParams): string;
+/**
+ * A stable string identifying the transform, for the ETag.
+ *
+ * Built from the RESOLVED parameters rather than the URL, so two spellings of
+ * one representation share an ETag even when the redirect is not in play.
+ * `auto` resolves per request, so the caller passes the resolved format in.
+ */
+export declare function buildSignature(params: ImageParams, resolvedFormat?: ConcreteFormat | null): string;
+/**
+ * Which concrete format `format=auto` resolves to for this request.
+ *
+ * Returns null when the client advertises neither modern format, in which case
+ * the source format is kept — `auto` never makes a response worse than the
+ * object already is.
+ *
+ * `q=0` is an explicit REFUSAL in RFC 9110 content negotiation, not a weak
+ * preference, so an entry carrying it is skipped rather than matched.
+ */
+export declare function resolveAutoFormat(accept: string | undefined | null): "avif" | "webp" | null;