@nitida/asset-client 0.23.0 → 0.24.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@nitida/asset-client",
-  "version": "0.23.0",
+  "version": "0.24.0",
   "description": "nitida URL builders — construct image, video and HLS URLs for the nitida CDN. No network, no key, no config beyond a tenant id.",
   "private": false,
   "publishConfig": {

package/src/index.ts

@@ -1082,6 +1082,8 @@ export {
   type PrivateTransformOptions,
   type SignedTransformOptions,
   type SignTransformOptions,
+  getByteBudgetTransformUrl,
+  hasSizeLadder,
   serializeTransform,
   signTransformUrl,
   TRANSFORM_WIDTHS,

package/src/transform.ts

@@ -20,7 +20,7 @@
 
 import { assertPublic, assertSha, type VisibilityHint } from "./access";
 import type { AssetDTO } from "./index";
-import { getCdnBase, getTenantId } from "./index";
+import { getCdnBase, getTenantId, hasPreset } from "./index";
 
 /**
  * Widths the CDN edge whitelists (DoS guard).
@@ -93,43 +93,36 @@ export type TransformOptions = {
   /** Output format. `auto` → the platform's policy decides. */
   format?: TransformFormat;
   /**
-   * @deprecated **Do not set this.** Omit the key — that is the correct call for
-   * every surface this platform serves. Kept in the type for one narrow case
-   * (a hard, MEASURED byte budget), and struck through on purpose so reaching
-   * for it is a decision, not an accident.
+   * ⛔ **`quality` no existe en este tipo, y eso es deliberado.**
    *
-   * There are only two things you can pass, and neither is worth having:
+   * No es un dial del encoder: elige QUÉ BYTES decodifica el servidor. Con un
+   * número, `/t/` salta a la variante almacenada más chica que cubra el pedido
+   * — que ya pasó por una compresión — y la salida es una segunda generación.
+   * Sobre un asset CON escalera eso es pérdida pura (medido: +2…+8 % de peso y
+   * −0,50…−0,85 dB). Y `"auto"` era un no-op: byte a byte idéntico a omitir la
+   * clave, mismo sha256.
    *
-   * **`"auto"` is a no-op.** Byte-for-byte identical to omitting the key —
-   * measured 2026-08-31 on a production laddered asset at `width=1920`:
-   * both answered 136 680 B, sha256 `3a9ba57d…`, `x-transform-source:
-   * original`. It buys nothing but the illusion of having chosen.
+   * El único uso legítimo —un presupuesto de bytes medido, sobre un asset SIN
+   * escalera— tiene su propia puerta, que no se puede llamar a ciegas:
+   * {@link getByteBudgetTransformUrl}.
    *
-   * **A NUMBER costs you image quality.** It is not an encoder knob — it
-   * selects WHICH BYTES the server decodes. With a number in hand, `/t/`
-   * short-circuits to the smallest STORED variant that covers the request, and
-   * that variant already went through one lossy pass, so the output is a second
-   * generation. `"auto"` is a *string*, fails that `typeof` test, and therefore
-   * keeps the master path. Measured on two corpora:
+   * ## Por qué no alcanzaba con documentarlo
    *
-   *   - 5 photographs, `width=800` → 7–9 % smaller **and worse 5 of 5**, down
-   *     to −3.01 dB PSNR (`/guides/transform-benchmark/`).
-   *   - 5056 px architectural renders at 1280 / 1920 / 3840 — the widths that
-   *     MATCH `md`/`lg`/`xl` exactly, so no downscale hides the first pass →
-   *     **+2…+8 % HEAVIER and −0.50…−0.85 dB, 3 of 3**. Not even a byte saving
-   *     to trade for it.
+   * Estuvo `@deprecated` con la medición al lado durante exactamente una
+   * versión, y eso ya era mejor que nada. Pero un aviso **avisa**; no impide.
+   * `getTransformUrl` recibe un `Pick<AssetDTO, "sha">` —un sha y nada más—,
+   * así que un `quality: 75` en el call site era **ciego**: nadie ahí, humano o
+   * modelo, podía saber si ese asset tenía escalera. La misma línea era
+   * correcta o dañina según un dato que no estaba en la llamada.
    *
-   * Raising the number does not undo it: doubly-compressed at 80 is worse than
-   * single-pass at 60, and 31 % heavier.
+   * Y hay un llamador que no lee tildados: **un modelo generando código.**
+   * `quality` es el parámetro que todo el mundo espera encontrar en una API de
+   * imágenes, así que se escribe solo. Next.js llegó a la misma conclusión por
+   * el mismo camino y dejó de recomendar `quality` por imagen: la configuración
+   * ya decide, y un valor por llamada sólo agrega formas de equivocarse.
    *
-   * If you truly have a byte budget, pin it AND upload that asset with
-   * `presets: ["original"]` — with no ladder there is nothing to short-circuit
-   * to, and the pin becomes an honest encoder setting again.
-   *
-   * The one-line check is on the response: `x-transform-source` names the
-   * variant the edge decoded. `original` = one pass; `md`/`lg`/`xl` = two.
+   * ⇒ El parámetro no se documenta como peligroso. **No se puede escribir.**
    */
-  quality?: "auto" | number;
   /** Device pixel ratio. Width/height are multiplied by this before resize. */
   dpr?: 1 | 2 | 3;
   /**
@@ -195,6 +188,14 @@ export type SignedTransformOptions = TransformOptions;
 export type PrivateTransformOptions = Omit<TransformOptions, "width"> & {
   width?: number;
 };
+
+/**
+ * `TransformOptions` + el `quality` que el tipo público ya no admite.
+ *
+ * INTERNO. Existe porque el serializador tiene que poder emitir `quality=` para
+ * {@link getByteBudgetTransformUrl}; no porque un llamador deba construirlo.
+ */
+type WithPinnedQuality<T> = T & { quality: number };
 /** @deprecated internal alias kept for the builders below. */
 type AnyWidthTransformOptions = PrivateTransformOptions;
 
@@ -232,13 +233,13 @@ export function extractAssetSha(url: string | null | undefined): string | null {
   return m ? m[1]! : null;
 }
 
-export function serializeTransform(opts: AnyWidthTransformOptions): string {
+export function serializeTransform(
+  opts: AnyWidthTransformOptions | WithPinnedQuality<AnyWidthTransformOptions>,
+): string {
   const entries: Array<[string, string]> = [];
-  const keys = Object.keys(opts).sort() as Array<
-    keyof AnyWidthTransformOptions
-  >;
+  const keys = Object.keys(opts).sort();
   for (const k of keys) {
-    const v = opts[k];
+    const v = (opts as Record<string, unknown>)[k];
     if (v == null) continue;
     const serialized = typeof v === "string" ? v.toLowerCase() : String(v);
     entries.push([k, serialized]);
@@ -246,7 +247,9 @@ export function serializeTransform(opts: AnyWidthTransformOptions): string {
   return entries.map(([k, v]) => `${k}=${v}`).join(",");
 }
 
-function extForOptions(opts: AnyWidthTransformOptions): string {
+function extForOptions(
+  opts: AnyWidthTransformOptions | WithPinnedQuality<AnyWidthTransformOptions>,
+): string {
   // effect=removebg forces PNG output server-side (needs alpha).
   if (opts.effect === "removebg") return "png";
   // effect=genfill defaults to WebP (12× lighter than the raw generated
@@ -395,7 +398,7 @@ export { buildTransformUrl as getTransformUrlUnchecked };
 
 function buildTransformUrl(
   asset: Pick<AssetDTO, "sha">,
-  opts: AnyWidthTransformOptions,
+  opts: AnyWidthTransformOptions | WithPinnedQuality<AnyWidthTransformOptions>,
 ): string | null {
   const dsl = serializeTransform(opts);
   if (!dsl) return null;
@@ -426,6 +429,119 @@ export function getTransformUrl(
  * Returns `null` only when `opts` serialize to an empty DSL (no transform
  * requested) — same contract as {@link getTransformUrl}.
  */
+/**
+ * Los presets de TAMAÑO — los únicos cuya existencia convierte un `quality`
+ * pinneado en una segunda compresión.
+ *
+ * `original`, `poster`, `video`, `aiproxy`, `hls` y `mp3` NO cuentan: `/t/`
+ * nunca los usa como fuente de una imagen redimensionada.
+ */
+const LADDER_PRESETS = ["thumb", "sm", "md", "lg", "xl"] as const;
+
+/**
+ * ¿Este asset tiene variantes de tamaño almacenadas, o sea algo a lo que `/t/`
+ * pueda saltar?
+ *
+ * `null` cuando **no se sabe** — un DTO sin `presets` no dice que no las tenga,
+ * dice que no lo trae. Tres estados, tres respuestas: un booleano acá mentiría
+ * en un tercio de los casos, y mentiría hacia el lado inseguro.
+ *
+ * ⚠️ **Se pregunta con `hasPreset`, JAMÁS con `presets.includes("s")`.** La
+ * cadena lleva tokens de varias letras —`transform-<hex>`, `upscale_…`, `pr`—
+ * que donan `s`, `m`, `l` y `o` de regalo. Ese es el falso positivo que
+ * `test/presets-false-positives.test.ts` existe para cazar.
+ */
+export function hasSizeLadder(asset: {
+  presets?: string | null;
+}): boolean | null {
+  const raw = asset.presets;
+  if (raw == null || raw.trim() === "") return null;
+  return LADDER_PRESETS.some((preset) => hasPreset(asset, preset));
+}
+
+/**
+ * ⭐ **La ÚNICA puerta por la que se puede pinnear un `quality` numérico** —
+ * y está construida para que no se pueda usar mal.
+ *
+ * ## El problema que resuelve
+ *
+ * `getTransformUrl` recibe un `Pick<AssetDTO, "sha">`: **un sha y nada más.**
+ * Con eso, un `quality: 75` en el call site es CIEGO — la misma línea es un
+ * ajuste honesto del encoder sobre un asset sin escalera, y una segunda
+ * compresión silenciosa sobre uno con escalera. Nada en el tipo, en el nombre
+ * ni en el editor distinguía los dos casos. Un aviso avisa; esto impide.
+ *
+ * ## Las dos barreras
+ *
+ * 1. **En COMPILACIÓN**: el parámetro exige `presets: string`. Un
+ *    `{ sha }` pelado —la llamada ciega— ya no compila. Para pasar por acá hay
+ *    que tener el DTO en la mano, y tener el DTO es saber la respuesta.
+ * 2. **En EJECUCIÓN**: si el asset tiene cualquier preset de tamaño, **tira**.
+ *    Si `presets` no vino, **tira** — «no sé» nunca se resuelve como «dale».
+ *
+ * ## Cuándo es legítimo, con el número
+ *
+ * Un presupuesto de bytes que alguien MIDIÓ, sobre un asset subido con
+ * `presets: ["original"]`. Ahí no hay a qué saltar y el pin hace lo que su
+ * nombre dice. Medido 2026-08-31 contra producción, ancho 1 920, las seis
+ * respuestas `x-transform-source: original`:
+ *
+ * | quality | bytes | vs auto | PSNR |
+ * |---|---|---|---|
+ * | 40 | 82 112 | **−33,6 %** | 35,32 dB |
+ * | 60 | 106 892 | −13,5 % | 36,85 dB |
+ * | *(auto)* | 123 614 | — | 37,65 dB |
+ * | 90 | 269 026 | +117,6 % | 41,46 dB |
+ *
+ * Monótona y sin sorpresas: −33,6 % de peso por −2,32 dB. **Eso sí es un
+ * intercambio**, y es la razón por la que el parámetro no se borró del todo.
+ *
+ * @throws si el asset tiene escalera, si no se sabe si la tiene, o si
+ *   `quality` no está en 1..100.
+ */
+export function getByteBudgetTransformUrl(
+  asset: Pick<AssetDTO, "sha"> & { presets: string } & VisibilityHint,
+  opts: WithPinnedQuality<TransformOptions>,
+): string | null {
+  assertSha(asset, "getByteBudgetTransformUrl");
+  assertPublic(
+    asset,
+    "getByteBudgetTransformUrl",
+    "getPrivateTransformUrl(asset, opts, signingKey, { expiresInSeconds: 300 })",
+  );
+
+  if (
+    !Number.isInteger(opts.quality) ||
+    opts.quality < 1 ||
+    opts.quality > 100
+  ) {
+    throw new Error(
+      `getByteBudgetTransformUrl: quality must be an integer 1..100, got ${String(opts.quality)}. ` +
+        "If you do not have a measured byte budget, use getTransformUrl and omit quality entirely.",
+    );
+  }
+
+  const ladder = hasSizeLadder(asset);
+  if (ladder === null) {
+    throw new Error(
+      `getByteBudgetTransformUrl: asset ${asset.sha} carries no 'presets', so whether a pinned ` +
+        "quality would re-compress it is UNKNOWN — and unknown is not permission. Fetch the full " +
+        "DTO (assets.get / assets.byHash) and pass it, or use getTransformUrl with no quality.",
+    );
+  }
+  if (ladder) {
+    throw new Error(
+      `getByteBudgetTransformUrl: asset ${asset.sha} has stored size variants (presets="${asset.presets}"). ` +
+        "A pinned quality there does not set the encoder — it makes /t/ decode one of those " +
+        "already-compressed variants, so the output is a SECOND lossy generation: measured " +
+        "+2..+8% HEAVIER and -0.50..-0.85 dB. Use getTransformUrl with no quality (one pass from " +
+        "the master), or upload this asset with presets: [\"original\"] if the byte budget is real.",
+    );
+  }
+
+  return buildTransformUrl(asset, opts);
+}
+
 export function getSignedTransformUrl(
   asset: Pick<AssetDTO, "sha"> & VisibilityHint,
   opts: SignedTransformOptions,