@nitida/asset-client 0.23.0 → 0.24.1

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@nitida/asset-client",
-  "version": "0.23.0",
+  "version": "0.24.1",
   "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": {
@@ -42,7 +42,7 @@
   },
   "devDependencies": {
     "tsup": "^8.5.1",
-    "typescript": "^6.0.3"
+    "typescript": "npm:@typescript/typescript6@6.0.2"
   },
   "keywords": [
     "media",

package/src/index.ts

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

package/src/slots.ts

@@ -61,6 +61,31 @@ let endpoint = "https://api.nitida.gofuture.space";
 let apiKey: string | null = null;
 let tenantCode: string | null = null;
 
+/** Per-call resolver scope. When passed, it fully overrides the process globals. */
+export type SlotResolverConfig = {
+  endpoint?: string;
+  apiKey?: string | null;
+  tenantCode?: string | null;
+};
+
+/**
+ * Effective config for one resolve call: explicit per-client config wins, else
+ * the process globals. This is what makes a per-client `slots.resolve()` use ITS
+ * OWN key instead of whatever client was constructed last (audit N15).
+ */
+function effectiveConfig(cfg?: SlotResolverConfig): {
+  endpoint: string;
+  apiKey: string | null;
+  tenantCode: string | null;
+} {
+  if (!cfg) return { endpoint, apiKey, tenantCode };
+  return {
+    endpoint: cfg.endpoint ? cfg.endpoint.replace(/\/+$/, "") : endpoint,
+    apiKey: cfg.apiKey ?? null,
+    tenantCode: cfg.tenantCode ?? null,
+  };
+}
+
 /**
  * Configure the resolver process-wide. Call once at boot from your
  * storefront layout / server entry / worker init.
@@ -93,16 +118,25 @@ export function invalidateSlotCache(slotKey?: string): void {
 // Internal fetch helper
 // ---------------------------------------------------------------------------
 
-const baseHeaders = (): Record<string, string> => {
+type ResolvedConfig = {
+  endpoint: string;
+  apiKey: string | null;
+  tenantCode: string | null;
+};
+
+const baseHeaders = (cfg: ResolvedConfig): Record<string, string> => {
   const h: Record<string, string> = {};
-  if (apiKey) h.Authorization = `Bearer ${apiKey}`;
-  if (tenantCode) h["X-Tenant-Code"] = tenantCode;
+  if (cfg.apiKey) h.Authorization = `Bearer ${cfg.apiKey}`;
+  if (cfg.tenantCode) h["X-Tenant-Code"] = cfg.tenantCode;
   return h;
 };
 
-async function fetchSlot(slotKey: string): Promise<SlotDTO | null> {
-  const r = await fetch(`${endpoint}/slots/${encodeURIComponent(slotKey)}`, {
-    headers: baseHeaders(),
+async function fetchSlot(
+  slotKey: string,
+  cfg: ResolvedConfig,
+): Promise<SlotDTO | null> {
+  const r = await fetch(`${cfg.endpoint}/slots/${encodeURIComponent(slotKey)}`, {
+    headers: baseHeaders(cfg),
   });
   if (r.status === 404) return null;
   if (!r.ok) throw new Error(`slot fetch ${r.status}: ${await r.text()}`);
@@ -111,11 +145,12 @@ async function fetchSlot(slotKey: string): Promise<SlotDTO | null> {
 
 async function fetchSlotsBulk(
   slotKeys: string[],
+  cfg: ResolvedConfig,
 ): Promise<Record<string, SlotDTO | null>> {
   if (slotKeys.length === 0) return {};
-  const r = await fetch(`${endpoint}/slots/resolve`, {
+  const r = await fetch(`${cfg.endpoint}/slots/resolve`, {
     method: "POST",
-    headers: { ...baseHeaders(), "Content-Type": "application/json" },
+    headers: { ...baseHeaders(cfg), "Content-Type": "application/json" },
     body: JSON.stringify({ keys: slotKeys }),
   });
   if (!r.ok) throw new Error(`slots resolve ${r.status}: ${await r.text()}`);
@@ -132,6 +167,12 @@ export type ResolveSlotOptions = {
   preset?: VariantPreset;
   /** TTL for the in-process cache. Default 60s. Set 0 to bypass. */
   ttlMs?: number;
+  /**
+   * Per-client auth/endpoint scope. Omit to use the process globals
+   * (configureSlotResolver). A NitidaClient passes its own here so its
+   * resolve() never uses another client's key (audit N15).
+   */
+  config?: SlotResolverConfig;
 };
 
 /**
@@ -146,14 +187,15 @@ export async function resolveSlot(
   opts: ResolveSlotOptions = {},
 ): Promise<SlotResolution> {
   const ttl = opts.ttlMs ?? DEFAULT_TTL_MS;
-  const cacheKey = `${tenantCode ?? "_"}:${slotKey}`;
+  const cfg = effectiveConfig(opts.config);
+  const cacheKey = `${cfg.tenantCode ?? "_"}:${slotKey}`;
   const now = Date.now();
   let dto: SlotDTO | null;
   const hit = cache.get(cacheKey);
   if (hit && now - hit.fetchedAt < ttl) {
     dto = hit.value;
   } else {
-    dto = await fetchSlot(slotKey);
+    dto = await fetchSlot(slotKey, cfg);
     cache.set(cacheKey, { fetchedAt: now, value: dto });
   }
   return materializeResolution(dto, opts.preset);
@@ -170,11 +212,12 @@ export async function resolveSlots(
 ): Promise<Record<string, SlotResolution>> {
   if (slotKeys.length === 0) return {};
   const ttl = opts.ttlMs ?? DEFAULT_TTL_MS;
+  const cfg = effectiveConfig(opts.config);
   const now = Date.now();
   const missing: string[] = [];
   const out: Record<string, SlotResolution> = {};
   for (const k of slotKeys) {
-    const cacheKey = `${tenantCode ?? "_"}:${k}`;
+    const cacheKey = `${cfg.tenantCode ?? "_"}:${k}`;
     const hit = cache.get(cacheKey);
     if (hit && now - hit.fetchedAt < ttl) {
       out[k] = materializeResolution(hit.value, opts.preset);
@@ -183,10 +226,10 @@ export async function resolveSlots(
     }
   }
   if (missing.length > 0) {
-    const resolved = await fetchSlotsBulk(missing);
+    const resolved = await fetchSlotsBulk(missing, cfg);
     for (const k of missing) {
       const dto = resolved[k] ?? null;
-      cache.set(`${tenantCode ?? "_"}:${k}`, { fetchedAt: now, value: dto });
+      cache.set(`${cfg.tenantCode ?? "_"}:${k}`, { fetchedAt: now, value: dto });
       out[k] = materializeResolution(dto, opts.preset);
     }
   }

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,21 +233,34 @@ 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();
+  // DSL segments are joined with `,` and `/`; a value carrying either (or `=`,
+  // `%`, a space) breaks out of its segment and smuggles extra transform ops
+  // into the path (audit N17). Every legitimate DSL value is [a-z0-9._-] — reject
+  // anything else rather than emit it, keeping the canonical form byte-identical
+  // to what the server parses.
+  const VALUE_RE = /^[a-z0-9._-]+$/;
   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);
+    if (!VALUE_RE.test(serialized)) {
+      throw new Error(
+        `invalid transform value for "${k}": ${JSON.stringify(serialized)} (only [a-z0-9._-] allowed)`,
+      );
+    }
     entries.push([k, serialized]);
   }
   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 +409,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 +440,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,