@nitida/asset-client 0.23.0 → 0.24.1

package/dist/index.d.cts

@@ -304,43 +304,36 @@ 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;
     /**
@@ -404,6 +397,15 @@ type SignedTransformOptions = TransformOptions;
 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;
 /**
@@ -432,7 +434,7 @@ type AnyWidthTransformOptions = PrivateTransformOptions;
  * to be an aquienpz asset.
  */
 declare function extractAssetSha(url: string | null | undefined): string | null;
-declare function serializeTransform(opts: AnyWidthTransformOptions): string;
+declare function serializeTransform(opts: AnyWidthTransformOptions | WithPinnedQuality<AnyWidthTransformOptions>): string;
 /**
  * Build a transform URL for a VIDEO asset. Same DSL shape as image
  * transforms; the server branches on the asset's `kind` column. Video
@@ -506,15 +508,64 @@ declare function getHlsStreamingUrl(asset: Pick<AssetDTO, "sha"> & VisibilityHin
 
 declare function getTransformUrl(asset: Pick<AssetDTO, "sha"> & VisibilityHint, opts: TransformOptions): string | null;
 /**
- * Build AND sign a transform URL.
+ * ¿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.
+ */
+declare function hasSizeLadder(asset: {
+    presets?: string | null;
+}): boolean | null;
+/**
+ * ⭐ **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
  *
- * A signature names the caller — it is what a `strict_transforms` tenant
- * requires and what the paid-effect (`effect=genfill`) cost guard requires. It
- * does NOT widen the ladder; see {@link SignedTransformOptions}.
+ * `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.
  *
- * Returns `null` only when `opts` serialize to an empty DSL (no transform
- * requested) — same contract as {@link getTransformUrl}.
+ * ## 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.
  */
+declare function getByteBudgetTransformUrl(asset: Pick<AssetDTO, "sha"> & {
+    presets: string;
+} & VisibilityHint, opts: WithPinnedQuality<TransformOptions>): string | null;
 declare function getSignedTransformUrl(asset: Pick<AssetDTO, "sha"> & VisibilityHint, opts: SignedTransformOptions, signingKey: string, signOpts: SignTransformOptions): Promise<string> | null;
 /**
  * The longest life a signed transform URL may claim: **7 days**.
@@ -638,6 +689,12 @@ type SlotResolution = {
     /** The CDN URL the consumer should use. */
     url: string | null;
 };
+/** Per-call resolver scope. When passed, it fully overrides the process globals. */
+type SlotResolverConfig = {
+    endpoint?: string;
+    apiKey?: string | null;
+    tenantCode?: string | null;
+};
 /**
  * Configure the resolver process-wide. Call once at boot from your
  * storefront layout / server entry / worker init.
@@ -660,6 +717,12 @@ 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;
 };
 /**
  * Resolve a single slot to a CDN URL. Returns `{slot: null, url: null}`
@@ -1136,4 +1199,4 @@ declare function getAssetDimensions(asset: Pick<AssetDTO, "w" | "h">): {
     height: number;
 } | null;
 
-export { type AssetDTO, type AssetPalette, type AssetVariant, type HlsRung, MAX_SIGNED_TRANSFORM_TTL_SECONDS, MAX_SIGNED_URL_TTL_SECONDS, MIN_SIGNED_TRANSFORM_TTL_SECONDS, PRESET_EXT, PRESET_LONG, PRESET_MAX_DIM, PRESET_SHORT, type PaletteSwatch, type PrivateTransformOptions, REQUESTABLE_PRESETS, type RequestablePreset, type ResolveSlotOptions, type SignAccessOptions, type SignTransformOptions, type SignedTransformOptions, type SlotDTO, type SlotResolution, TRANSFORM_WIDTHS, type TransformEffect, type TransformFit, type TransformFormat, type TransformGravity, type TransformOptions, type TransformWidth, type VariantEntryPreset, type VariantPreset, type VisibilityHint, accessMessage, assertPublic, assertSha, bestTextContrast, computeVariantDimensions, configureSlotResolver, contrastRatio, deriveAccessKey, deriveTransformKid, extractAssetSha, getAmbientGradient, getAssetDimensions, getAssetSrcSet, getAssetUrl, getCdnBase, getHlsLadder, getHlsStreamingUrl, getPaletteBlurBackground, getPaletteCssVars, getPrivateAssetUrl, getPrivateTransformUrl, getSignedTransformUrl, getTenantId, getTextColorForBackground, getTransformSrcSet, getTransformUrl, getVideoTransformUrl, hasPreset, hlsLadderAlignment, invalidateSlotCache, isRequestablePreset, iteratePaletteSwatches, pickAmbientBackground, relativeLuminance, resolveSlot, resolveSlots, serializeTransform, setCdnBase, setTenantId, signAccessUrl, signTransformUrl, toRequestablePresets, transformMessage };
+export { type AssetDTO, type AssetPalette, type AssetVariant, type HlsRung, MAX_SIGNED_TRANSFORM_TTL_SECONDS, MAX_SIGNED_URL_TTL_SECONDS, MIN_SIGNED_TRANSFORM_TTL_SECONDS, PRESET_EXT, PRESET_LONG, PRESET_MAX_DIM, PRESET_SHORT, type PaletteSwatch, type PrivateTransformOptions, REQUESTABLE_PRESETS, type RequestablePreset, type ResolveSlotOptions, type SignAccessOptions, type SignTransformOptions, type SignedTransformOptions, type SlotDTO, type SlotResolution, TRANSFORM_WIDTHS, type TransformEffect, type TransformFit, type TransformFormat, type TransformGravity, type TransformOptions, type TransformWidth, type VariantEntryPreset, type VariantPreset, type VisibilityHint, accessMessage, assertPublic, assertSha, bestTextContrast, computeVariantDimensions, configureSlotResolver, contrastRatio, deriveAccessKey, deriveTransformKid, extractAssetSha, getAmbientGradient, getAssetDimensions, getAssetSrcSet, getAssetUrl, getByteBudgetTransformUrl, getCdnBase, getHlsLadder, getHlsStreamingUrl, getPaletteBlurBackground, getPaletteCssVars, getPrivateAssetUrl, getPrivateTransformUrl, getSignedTransformUrl, getTenantId, getTextColorForBackground, getTransformSrcSet, getTransformUrl, getVideoTransformUrl, hasPreset, hasSizeLadder, hlsLadderAlignment, invalidateSlotCache, isRequestablePreset, iteratePaletteSwatches, pickAmbientBackground, relativeLuminance, resolveSlot, resolveSlots, serializeTransform, setCdnBase, setTenantId, signAccessUrl, signTransformUrl, toRequestablePresets, transformMessage };

package/dist/index.d.ts

@@ -304,43 +304,36 @@ 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;
     /**
@@ -404,6 +397,15 @@ type SignedTransformOptions = TransformOptions;
 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;
 /**
@@ -432,7 +434,7 @@ type AnyWidthTransformOptions = PrivateTransformOptions;
  * to be an aquienpz asset.
  */
 declare function extractAssetSha(url: string | null | undefined): string | null;
-declare function serializeTransform(opts: AnyWidthTransformOptions): string;
+declare function serializeTransform(opts: AnyWidthTransformOptions | WithPinnedQuality<AnyWidthTransformOptions>): string;
 /**
  * Build a transform URL for a VIDEO asset. Same DSL shape as image
  * transforms; the server branches on the asset's `kind` column. Video
@@ -506,15 +508,64 @@ declare function getHlsStreamingUrl(asset: Pick<AssetDTO, "sha"> & VisibilityHin
 
 declare function getTransformUrl(asset: Pick<AssetDTO, "sha"> & VisibilityHint, opts: TransformOptions): string | null;
 /**
- * Build AND sign a transform URL.
+ * ¿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.
+ */
+declare function hasSizeLadder(asset: {
+    presets?: string | null;
+}): boolean | null;
+/**
+ * ⭐ **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
  *
- * A signature names the caller — it is what a `strict_transforms` tenant
- * requires and what the paid-effect (`effect=genfill`) cost guard requires. It
- * does NOT widen the ladder; see {@link SignedTransformOptions}.
+ * `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.
  *
- * Returns `null` only when `opts` serialize to an empty DSL (no transform
- * requested) — same contract as {@link getTransformUrl}.
+ * ## 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.
  */
+declare function getByteBudgetTransformUrl(asset: Pick<AssetDTO, "sha"> & {
+    presets: string;
+} & VisibilityHint, opts: WithPinnedQuality<TransformOptions>): string | null;
 declare function getSignedTransformUrl(asset: Pick<AssetDTO, "sha"> & VisibilityHint, opts: SignedTransformOptions, signingKey: string, signOpts: SignTransformOptions): Promise<string> | null;
 /**
  * The longest life a signed transform URL may claim: **7 days**.
@@ -638,6 +689,12 @@ type SlotResolution = {
     /** The CDN URL the consumer should use. */
     url: string | null;
 };
+/** Per-call resolver scope. When passed, it fully overrides the process globals. */
+type SlotResolverConfig = {
+    endpoint?: string;
+    apiKey?: string | null;
+    tenantCode?: string | null;
+};
 /**
  * Configure the resolver process-wide. Call once at boot from your
  * storefront layout / server entry / worker init.
@@ -660,6 +717,12 @@ 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;
 };
 /**
  * Resolve a single slot to a CDN URL. Returns `{slot: null, url: null}`
@@ -1136,4 +1199,4 @@ declare function getAssetDimensions(asset: Pick<AssetDTO, "w" | "h">): {
     height: number;
 } | null;
 
-export { type AssetDTO, type AssetPalette, type AssetVariant, type HlsRung, MAX_SIGNED_TRANSFORM_TTL_SECONDS, MAX_SIGNED_URL_TTL_SECONDS, MIN_SIGNED_TRANSFORM_TTL_SECONDS, PRESET_EXT, PRESET_LONG, PRESET_MAX_DIM, PRESET_SHORT, type PaletteSwatch, type PrivateTransformOptions, REQUESTABLE_PRESETS, type RequestablePreset, type ResolveSlotOptions, type SignAccessOptions, type SignTransformOptions, type SignedTransformOptions, type SlotDTO, type SlotResolution, TRANSFORM_WIDTHS, type TransformEffect, type TransformFit, type TransformFormat, type TransformGravity, type TransformOptions, type TransformWidth, type VariantEntryPreset, type VariantPreset, type VisibilityHint, accessMessage, assertPublic, assertSha, bestTextContrast, computeVariantDimensions, configureSlotResolver, contrastRatio, deriveAccessKey, deriveTransformKid, extractAssetSha, getAmbientGradient, getAssetDimensions, getAssetSrcSet, getAssetUrl, getCdnBase, getHlsLadder, getHlsStreamingUrl, getPaletteBlurBackground, getPaletteCssVars, getPrivateAssetUrl, getPrivateTransformUrl, getSignedTransformUrl, getTenantId, getTextColorForBackground, getTransformSrcSet, getTransformUrl, getVideoTransformUrl, hasPreset, hlsLadderAlignment, invalidateSlotCache, isRequestablePreset, iteratePaletteSwatches, pickAmbientBackground, relativeLuminance, resolveSlot, resolveSlots, serializeTransform, setCdnBase, setTenantId, signAccessUrl, signTransformUrl, toRequestablePresets, transformMessage };
+export { type AssetDTO, type AssetPalette, type AssetVariant, type HlsRung, MAX_SIGNED_TRANSFORM_TTL_SECONDS, MAX_SIGNED_URL_TTL_SECONDS, MIN_SIGNED_TRANSFORM_TTL_SECONDS, PRESET_EXT, PRESET_LONG, PRESET_MAX_DIM, PRESET_SHORT, type PaletteSwatch, type PrivateTransformOptions, REQUESTABLE_PRESETS, type RequestablePreset, type ResolveSlotOptions, type SignAccessOptions, type SignTransformOptions, type SignedTransformOptions, type SlotDTO, type SlotResolution, TRANSFORM_WIDTHS, type TransformEffect, type TransformFit, type TransformFormat, type TransformGravity, type TransformOptions, type TransformWidth, type VariantEntryPreset, type VariantPreset, type VisibilityHint, accessMessage, assertPublic, assertSha, bestTextContrast, computeVariantDimensions, configureSlotResolver, contrastRatio, deriveAccessKey, deriveTransformKid, extractAssetSha, getAmbientGradient, getAssetDimensions, getAssetSrcSet, getAssetUrl, getByteBudgetTransformUrl, getCdnBase, getHlsLadder, getHlsStreamingUrl, getPaletteBlurBackground, getPaletteCssVars, getPrivateAssetUrl, getPrivateTransformUrl, getSignedTransformUrl, getTenantId, getTextColorForBackground, getTransformSrcSet, getTransformUrl, getVideoTransformUrl, hasPreset, hasSizeLadder, hlsLadderAlignment, invalidateSlotCache, isRequestablePreset, iteratePaletteSwatches, pickAmbientBackground, relativeLuminance, resolveSlot, resolveSlots, serializeTransform, setCdnBase, setTenantId, signAccessUrl, signTransformUrl, toRequestablePresets, transformMessage };

package/dist/index.js

@@ -219,10 +219,16 @@ function extractAssetSha(url) {
 function serializeTransform(opts) {
   const entries = [];
   const keys = Object.keys(opts).sort();
+  const VALUE_RE = /^[a-z0-9._-]+$/;
   for (const k of keys) {
     const v = opts[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(",");
@@ -296,6 +302,37 @@ function getTransformUrl(asset, opts) {
   );
   return buildTransformUrl(asset, opts);
 }
+var LADDER_PRESETS = ["thumb", "sm", "md", "lg", "xl"];
+function hasSizeLadder(asset) {
+  const raw = asset.presets;
+  if (raw == null || raw.trim() === "") return null;
+  return LADDER_PRESETS.some((preset) => hasPreset(asset, preset));
+}
+function getByteBudgetTransformUrl(asset, opts) {
+  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 \u2014 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 \u2014 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);
+}
 function getSignedTransformUrl(asset, opts, signingKey, signOpts) {
   assertSha(asset, "getSignedTransformUrl");
   assertPublic(
@@ -387,6 +424,14 @@ var cache = /* @__PURE__ */ new Map();
 var endpoint = "https://api.nitida.gofuture.space";
 var apiKey = null;
 var tenantCode = null;
+function effectiveConfig(cfg) {
+  if (!cfg) return { endpoint, apiKey, tenantCode };
+  return {
+    endpoint: cfg.endpoint ? cfg.endpoint.replace(/\/+$/, "") : endpoint,
+    apiKey: cfg.apiKey ?? null,
+    tenantCode: cfg.tenantCode ?? null
+  };
+}
 function configureSlotResolver(opts) {
   if (opts.endpoint) endpoint = opts.endpoint.replace(/\/+$/, "");
   if (opts.apiKey !== void 0) apiKey = opts.apiKey;
@@ -398,25 +443,25 @@ function invalidateSlotCache(slotKey) {
     for (const k of cache.keys())
       if (k.endsWith(`:${slotKey}`)) cache.delete(k);
 }
-var baseHeaders = () => {
+var baseHeaders = (cfg) => {
   const h = {};
-  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) {
-  const r = await fetch(`${endpoint}/slots/${encodeURIComponent(slotKey)}`, {
-    headers: baseHeaders()
+async function fetchSlot(slotKey, cfg) {
+  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()}`);
   return await r.json();
 }
-async function fetchSlotsBulk(slotKeys) {
+async function fetchSlotsBulk(slotKeys, cfg) {
   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()}`);
@@ -425,14 +470,15 @@ async function fetchSlotsBulk(slotKeys) {
 }
 async function resolveSlot(slotKey, opts = {}) {
   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;
   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);
@@ -440,11 +486,12 @@ async function resolveSlot(slotKey, opts = {}) {
 async function resolveSlots(slotKeys, opts = {}) {
   if (slotKeys.length === 0) return {};
   const ttl = opts.ttlMs ?? DEFAULT_TTL_MS;
+  const cfg = effectiveConfig(opts.config);
   const now = Date.now();
   const missing = [];
   const out = {};
   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);
@@ -453,10 +500,10 @@ async function resolveSlots(slotKeys, opts = {}) {
     }
   }
   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);
     }
   }
@@ -749,6 +796,7 @@ export {
   getAssetDimensions,
   getAssetSrcSet,
   getAssetUrl,
+  getByteBudgetTransformUrl,
   getCdnBase,
   getHlsLadder,
   getHlsStreamingUrl,
@@ -763,6 +811,7 @@ export {
   getTransformUrl,
   getVideoTransformUrl,
   hasPreset,
+  hasSizeLadder,
   hlsLadderAlignment,
   invalidateSlotCache,
   isRequestablePreset,