@nitida/asset-client 0.21.0 → 0.24.0

package/dist/index.d.ts

@@ -56,8 +56,22 @@ declare function deriveAccessKey(signingKey: string): Promise<Uint8Array>;
  * path.
  */
 declare function accessMessage(tenantPrefix: string, exp: number, resourcePath: string): string;
+/**
+ * The longest life a signed URL may claim: **7 days**.
+ *
+ * ⚠️ Must equal `MAX_SIGNED_TRANSFORM_TTL_SECONDS` on the origin and
+ * `MAX_SIGNED_URL_TTL_SECONDS` in the CDN worker — one policy, three runtimes,
+ * pinned in all three suites. Both verifiers refuse anything longer, so a
+ * bigger number here would only mint a URL that 401s.
+ *
+ * Why there is a ceiling at all: `expiresInSeconds` was validated as
+ * "> 0" and nothing else, so `{ expiresInSeconds: 315_360_000 }` produced a
+ * ten-year link that every check called valid. "Has an expiry" and "expires"
+ * are different properties, and only the second makes a leaked link die.
+ */
+declare const MAX_SIGNED_URL_TTL_SECONDS: number;
 type SignAccessOptions = {
-    /** Lifetime in seconds. Required — see the header. */
+    /** Lifetime in seconds, 1 .. 604 800. Required — see the header. */
     expiresInSeconds: number;
     /** Injectable clock, for tests that need a URL already dead on arrival. */
     nowSeconds?: number;
@@ -248,13 +262,24 @@ declare function getPaletteBlurBackground(palette: AssetPalette | null | undefin
  * Requesting any OTHER width returns HTTP 400 at the edge (unsigned URLs). These are the
  * 1× base ladder values; DPR ×2/×3 multiples are applied + whitelisted server-side. Import
  * this instead of hardcoding magic widths so an unsupported size is caught in review/IDE.
+ *
+ * ⭐ **180 es el `apple-touch-icon`, y está acá por eso.** Apple pide 180×180 para
+ * el icono de pantalla de inicio en un iPhone 3×, y el monorepo de neo ya lo
+ * estandarizó: `webapp-storefront` commitea un `apple-icon.png` de 180×180 por
+ * tenant. Sin este escalón, una app que sirve el icono desde el CDN tiene que
+ * elegir entre 160 (iOS lo agranda, sale borroso) y 240 (lo achica, sale bien
+ * pero pesa de más). Medido 2026-08-29 sobre la foto de un agente: 240² en PNG
+ * son 57,5 KB contra 6,5 KB del WebP a 400², así que el tamaño de más no es
+ * gratis. El caso real: `apps/bio-web/src/lib/seo/favicon.ts`, que sirve **la
+ * foto del propio negocio** como icono de su página.
  */
-declare const TRANSFORM_WIDTHS: readonly [96, 128, 160, 240, 256, 320, 400, 480, 600, 640, 800, 960, 1080, 1200, 1280, 1440, 1600, 1920, 2560, 3840];
+declare const TRANSFORM_WIDTHS: readonly [96, 128, 160, 180, 240, 256, 320, 400, 480, 600, 640, 800, 960, 1080, 1200, 1280, 1440, 1600, 1920, 2560, 3840];
 /**
  * A CDN-whitelisted transform width — the only widths `TransformOptions.width`
  * accepts. Off-ladder widths are a compile error; for signed URLs that need a
- * custom width, use {@link SignedTransformOptions} (number) via
- * {@link getSignedTransformUrl} / `aq.transform(asset, opts, { sign: true })`.
+ * signature, use {@link getSignedTransformUrl} /
+ * `aq.transform(asset, opts, { sign: true, expiresInSeconds })` — which names
+ * the caller but does NOT widen the ladder.
  */
 type TransformWidth = (typeof TRANSFORM_WIDTHS)[number];
 type TransformFit = "cover" | "contain" | "fill" | "inside" | "outside";
@@ -265,9 +290,9 @@ type TransformOptions = {
     /**
      * Target max-side width in CSS pixels (multiplied by `dpr` server-side).
      * MUST be a {@link TRANSFORM_WIDTHS} value — off-ladder widths are rejected
-     * (HTTP 400) by the edge whitelist for unsigned URLs, so the type forbids
-     * them at compile time. For SIGNED URLs with a custom width, use
-     * {@link SignedTransformOptions} (which widens this to `number`).
+     * (HTTP 400) by the edge whitelist, so the type forbids them at compile
+     * time. Signing does NOT lift this: since doc blindaje WS-6 the edge
+     * validates signed and unsigned requests identically.
      */
     width?: TransformWidth;
     /** Target max-side height. Multiplied by `dpr` server-side. */
@@ -278,8 +303,37 @@ type TransformOptions = {
     gravity?: TransformGravity;
     /** Output format. `auto` → the platform's policy decides. */
     format?: TransformFormat;
-    /** Output quality. `auto` → format-specific default. */
-    quality?: "auto" | number;
+    /**
+     * ⛔ **`quality` no existe en este tipo, y eso es deliberado.**
+     *
+     * 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.
+     *
+     * 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}.
+     *
+     * ## Por qué no alcanzaba con documentarlo
+     *
+     * 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.
+     *
+     * 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.
+     *
+     * ⇒ El parámetro no se documenta como peligroso. **No se puede escribir.**
+     */
     /** Device pixel ratio. Width/height are multiplied by this before resize. */
     dpr?: 1 | 2 | 3;
     /**
@@ -312,20 +366,48 @@ type TransformOptions = {
     duration?: number;
 };
 /**
- * Like {@link TransformOptions} but with `width` widened to any `number` —
- * the escape hatch for SIGNED URLs that need an off-ladder custom width.
- *
- * The edge whitelist only rejects off-ladder widths on UNSIGNED URLs; a valid
- * `?sig=` earns the whitelist bypass at the edge (the server still
- * does the real HMAC check). So a custom width is ONLY safe when the URL is
- * signed — hence this type is accepted exclusively by the signing helpers
- * ({@link getSignedTransformUrl} / `aq.transform(asset, opts, { sign: true })`),
- * never by the plain unsigned {@link getTransformUrl}.
+ * Options for a SIGNED transform URL.
+ *
+ * ⚠️ **`width` is the same ladder as unsigned**, since `@nitida/asset-client`
+ * 0.22.0. This type used to widen it to any `number`, because a valid `?sig=`
+ * made the CDN edge skip its whitelist entirely — so a signature bought an
+ * off-ladder size. It does not any more: the edge validates every `/t/`
+ * request identically and answers 400 for an off-ladder width whether or not
+ * it is signed (doc blindaje WS-6). Keeping the wide type would only let
+ * TypeScript bless a URL that 400s.
+ *
+ * A signature now buys IDENTITY: which tenant asked, proven with its key, until
+ * `exp`. That is what a strict tenant and the paid-effect cost guard require.
  */
-type SignedTransformOptions = Omit<TransformOptions, "width"> & {
-    /** Off-ladder width — valid ONLY on signed URLs (edge whitelist bypass). */
+type SignedTransformOptions = TransformOptions;
+/**
+ * `width` widened to any `number` — the PRIVATE tree's option type.
+ *
+ * ⚠️ Not an escape hatch for the public tree: `/t/` answers 400 for an
+ * off-ladder width, signed or not (doc blindaje WS-6). What this is for is the
+ * `/a/<tenant>/t/…` tree, where the ladder deliberately does NOT apply — the
+ * request arrives HMAC-verified against the tenant's key, so only a key-holder
+ * can ask, and "any width/crop/format, not just the materialised ones" is the
+ * written promise of `getPrivateTransformUrl`.
+ *
+ * Also used by the two builders that take an explicit ladder the caller chose
+ * (`getTransformSrcSet`) or that are documented as unchecked
+ * (`getTransformUrlUnchecked`).
+ */
+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;
 /**
  * Serialize transform options into the canonical DSL path segment.
  * Empty options return an empty string (caller should fall back to a
@@ -352,7 +434,7 @@ type SignedTransformOptions = Omit<TransformOptions, "width"> & {
  * to be an aquienpz asset.
  */
 declare function extractAssetSha(url: string | null | undefined): string | null;
-declare function serializeTransform(opts: SignedTransformOptions): 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
@@ -426,20 +508,115 @@ 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, allowing an off-ladder custom `width`.
+ * ¿Este asset tiene variantes de tamaño almacenadas, o sea algo a lo que `/t/`
+ * pueda saltar?
  *
- * This is the escape hatch for {@link SignedTransformOptions}: off-ladder
- * widths only pass the edge whitelist when the URL is signed, so building one
- * and signing it must happen together. For on-ladder widths prefer the plain
- * {@link getTransformUrl} (+ {@link signTransformUrl} if you need a signature).
+ * `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.
  *
- * Returns `null` only when `opts` serialize to an empty DSL (no transform
- * requested) — same contract as {@link getTransformUrl}.
+ * ⚠️ **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 getSignedTransformUrl(asset: Pick<AssetDTO, "sha"> & VisibilityHint, opts: SignedTransformOptions, signingKey: string): Promise<string> | null;
+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
+ *
+ * `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.
+ */
+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**.
+ *
+ * ⚠️ Must equal `MAX_SIGNED_TRANSFORM_TTL_SECONDS` on the origin
+ * (`transform.signing.ts`), which enforces it on every verify — asking for
+ * more here would only build a URL the platform answers 401 to, which is why
+ * this throws instead.
+ */
+declare const MAX_SIGNED_TRANSFORM_TTL_SECONDS: number;
+/**
+ * The shortest, so that the minute-rounding below can never mint a dead URL.
+ * 120 s = two rounding steps of headroom.
+ */
+declare const MIN_SIGNED_TRANSFORM_TTL_SECONDS = 120;
+type SignTransformOptions = {
+    /**
+     * Lifetime in seconds, 120 .. 604 800. Required — there is no "forever"
+     * option, for the same reason `signAccessUrl` has none: a signed URL that
+     * never expires is a public URL the moment someone forwards it.
+     */
+    expiresInSeconds: number;
+    /**
+     * The tenant this signature speaks for. Defaults to the process-global
+     * (`setTenantId`, or a `NitidaClient` with `tenantId`) — the tenant is part
+     * of the signed message, so it cannot be guessed from the asset.
+     */
+    tenantId?: number;
+    /** Injectable clock, for tests that need a URL already dead on arrival. */
+    nowSeconds?: number;
+};
+/**
+ * The public name of a signing key, derived from the key itself, so a signer
+ * never has to be told a second value. Byte-identical to the origin's
+ * `deriveKid`.
+ */
+declare function deriveTransformKid(signingKey: string): Promise<string>;
+/**
+ * The signed message. Byte-identical to the origin's `transformMessage`.
+ *
+ *     nitida/transform/v2 \n <tenantPrefix> \n <exp> \n <dsl>/<filename>
+ */
+declare function transformMessage(args: {
+    tenantPrefix: string;
+    exp: number;
+    canonicalDsl: string;
+    filename: string;
+}): string;
 /**
  * Sign a transform URL with the tenant's HMAC signing key. Appends
- * `?sig=<hex>` where hex = HMAC-SHA256(signingKey, `<canonical-DSL>/<filename>`).
+ * `?kid=<8 hex>&exp=<unix seconds>&sig=<64 hex>`.
  *
  * Must agree byte-for-byte with the server's `verifyTransformSignature`.
  * Uses WebCrypto, so works in browsers, Node ≥ 16, Bun, and Workers.
@@ -447,8 +624,20 @@ declare function getSignedTransformUrl(asset: Pick<AssetDTO, "sha"> & Visibility
  * The canonical DSL is the one already produced by `serializeTransform`
  * (sort keys + lowercase strings), so signing a URL built by `getTransformUrl`
  * is automatic — the same canonical form is in the URL path.
+ *
+ * ## ⚠️ `exp` IS ROUNDED DOWN TO THE MINUTE, AND THAT IS LOAD-BEARING
+ *
+ * The edge cache key for `/t/` is the FULL URL. A per-request `exp` would make
+ * every render of the same image a distinct cache entry — turning a path that
+ * reaches the origin roughly never into one that reaches it on every view.
+ * Rounding down to the minute means every renderer signing the same URL in the
+ * same minute produces the same bytes, so the entry is shared. Down, never up,
+ * so the URL never outlives the lifetime the caller asked for.
+ *
+ * A build-time signer that wants ONE stable URL per deploy should pass a fixed
+ * `nowSeconds` (the build timestamp) rather than a longer lifetime.
  */
-declare function signTransformUrl(unsignedUrl: string, signingKey: string): Promise<string>;
+declare function signTransformUrl(unsignedUrl: string, signingKey: string, opts: SignTransformOptions): Promise<string>;
 /**
  * Build a responsive `srcSet` string by generating one transform URL per
  * width. All other options apply to every URL.
@@ -583,19 +772,23 @@ type VariantPreset = "thumb" | "sm" | "md" | "lg" | "xl" | "original" | "poster"
  * **`probe` is requestable and was not on `VariantPreset` at all**, so the type
  * forbade a request the server has always accepted.
  *
- * Verified 2026-08-21 against the Elysia schemas of all four write routes —
- * `/assets/process`, the presign route, `/assets/:id/regenerate` and both
- * multipart routes. All four accept exactly this list and nothing else, with
- * no drift between them.
+ * Generated from the Elysia schemas of all four write routes — `/assets/process`,
+ * the presign route, `/assets/:id/regenerate` and both multipart routes —
+ * by `scripts/gen-docs.ts` (doc derivar WS-4). `bun run gen:docs` rewrites it;
+ * `--check` fails the build if a route's schema drifts and nobody reran it.
+ * `probe` is still frames at evenly spaced offsets, stored under indexed keys
+ * (`-pr0.jpg`, `-pr1.jpg`, …) — requestable, and deliberately absent from the
+ * compact `presets` wire string, so it is here and not on `VariantPreset`.
  */
-type RequestablePreset = Exclude<VariantPreset, "hls" | "mp3"> | "probe";
+declare const REQUESTABLE_PRESETS: readonly ["aiproxy", "lg", "md", "original", "poster", "probe", "sm", "thumb", "video", "xl"];
+type RequestablePreset = (typeof REQUESTABLE_PRESETS)[number];
 /**
- * The same set as {@link RequestablePreset}, at RUNTIME.
- *
- * The type stops the mistake in TypeScript. It cannot stop it anywhere else,
- * and "anywhere else" is where it keeps happening: a preset list assembled
- * from config, from a route body, from JSON, or from a script's argv arrives
- * as `string[]`, and the only way past the type was a cast.
+ * `REQUESTABLE_PRESETS` (above) is the same set as `RequestablePreset`, at
+ * RUNTIME. The type stops the mistake in TypeScript. It cannot stop it
+ * anywhere else, and "anywhere else" is where it keeps happening: a preset
+ * list assembled from config, from a route body, from JSON, or from a
+ * script's argv arrives as `string[]`, and the only way past the type was a
+ * cast.
  *
  * Measured in neo-real-estate on 2026-08-23, in THREE independent files:
  *
@@ -607,7 +800,6 @@ type RequestablePreset = Exclude<VariantPreset, "hls" | "mp3"> | "probe";
  *
  * So the narrowing lives here, once, instead of being re-invented per repo.
  */
-declare const REQUESTABLE_PRESETS: readonly RequestablePreset[];
 /** Type guard for a single value. */
 declare const isRequestablePreset: (v: string) => v is RequestablePreset;
 /**
@@ -957,7 +1149,7 @@ declare function getPrivateAssetUrl(asset: Pick<AssetDTO, "sha"> & OriginalHints
  * `number`: a signed URL is a trusted caller, so the edge ladder does not
  * apply — the same rule `getSignedTransformUrl` already follows.
  */
-declare function getPrivateTransformUrl(asset: Pick<AssetDTO, "sha">, opts: SignedTransformOptions, signingKey: string, signOpts: SignAccessOptions): Promise<string | null>;
+declare function getPrivateTransformUrl(asset: Pick<AssetDTO, "sha">, opts: PrivateTransformOptions, signingKey: string, signOpts: SignAccessOptions): Promise<string | null>;
 /**
  * Did the processor actually generate this preset?
  *
@@ -995,4 +1187,4 @@ declare function getAssetDimensions(asset: Pick<AssetDTO, "w" | "h">): {
     height: number;
 } | null;
 
-export { type AssetDTO, type AssetPalette, type AssetVariant, type HlsRung, PRESET_EXT, PRESET_LONG, PRESET_MAX_DIM, PRESET_SHORT, type PaletteSwatch, REQUESTABLE_PRESETS, type RequestablePreset, type ResolveSlotOptions, type SignAccessOptions, 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, 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 };
+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

@@ -25,12 +25,18 @@ function accessMessage(tenantPrefix, exp, resourcePath) {
 ${exp}
 ${resourcePath.replace(/^\/+/, "")}`;
 }
+var MAX_SIGNED_URL_TTL_SECONDS = 7 * 24 * 60 * 60;
 async function signAccessUrl(publicUrl, signingKey, opts) {
   if (!Number.isFinite(opts.expiresInSeconds) || opts.expiresInSeconds <= 0) {
     throw new Error(
       "signAccessUrl: `expiresInSeconds` must be a positive number \u2014 a signed URL without an expiry is a public URL the moment it is forwarded."
     );
   }
+  if (opts.expiresInSeconds > MAX_SIGNED_URL_TTL_SECONDS) {
+    throw new Error(
+      `signAccessUrl: \`expiresInSeconds\` may not exceed ${MAX_SIGNED_URL_TTL_SECONDS} (7 days). Both verifiers refuse a longer one, so this would build a URL that 401s. An expiry that never arrives is not an expiry.`
+    );
+  }
   const u = new URL(publicUrl);
   const segments = u.pathname.split("/").filter(Boolean);
   if (segments[0] === "a" && segments[2] && /^[vrt]$/.test(segments[2])) {
@@ -186,6 +192,7 @@ var TRANSFORM_WIDTHS = [
   96,
   128,
   160,
+  180,
   240,
   256,
   320,
@@ -289,7 +296,38 @@ function getTransformUrl(asset, opts) {
   );
   return buildTransformUrl(asset, opts);
 }
-function getSignedTransformUrl(asset, opts, signingKey) {
+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(
     asset,
@@ -298,9 +336,34 @@ function getSignedTransformUrl(asset, opts, signingKey) {
   );
   const url = buildTransformUrl(asset, opts);
   if (!url) return null;
-  return signTransformUrl(url, signingKey);
-}
-async function signTransformUrl(unsignedUrl, signingKey) {
+  return signTransformUrl(url, signingKey, signOpts);
+}
+var TRANSFORM_SIG_DOMAIN = "nitida/transform/v2";
+var KID_INFO = "nitida/kid/v1";
+var MAX_SIGNED_TRANSFORM_TTL_SECONDS = 7 * 24 * 60 * 60;
+var MIN_SIGNED_TRANSFORM_TTL_SECONDS = 120;
+async function deriveTransformKid(signingKey) {
+  return (await hmacSha256Hex(signingKey, KID_INFO)).slice(0, 8);
+}
+function transformMessage(args) {
+  return `${TRANSFORM_SIG_DOMAIN}
+${args.tenantPrefix}
+${args.exp}
+${args.canonicalDsl}/${args.filename}`;
+}
+async function signTransformUrl(unsignedUrl, signingKey, opts) {
+  const ttl = Math.floor(opts.expiresInSeconds);
+  if (!Number.isFinite(ttl) || ttl < MIN_SIGNED_TRANSFORM_TTL_SECONDS || ttl > MAX_SIGNED_TRANSFORM_TTL_SECONDS) {
+    throw new Error(
+      `signTransformUrl: \`expiresInSeconds\` must be between ${MIN_SIGNED_TRANSFORM_TTL_SECONDS} and ${MAX_SIGNED_TRANSFORM_TTL_SECONDS}. The platform refuses a longer one on every verify, so a bigger number here just builds a URL that 401s.`
+    );
+  }
+  const tid = opts.tenantId ?? getTenantId();
+  if (tid == null) {
+    throw new Error(
+      "signTransformUrl: no tenant is configured. Call setTenantId(id) (or construct a NitidaClient with `tenantId`) \u2014 the tenant is part of what the signature covers, so this cannot be guessed."
+    );
+  }
   const u = new URL(unsignedUrl);
   const parts = u.pathname.split("/").filter(Boolean);
   if (parts[0] !== "t" || parts.length < 3) {
@@ -308,8 +371,19 @@ async function signTransformUrl(unsignedUrl, signingKey) {
   }
   const filename = parts[parts.length - 1];
   const dsl = parts.slice(1, -1).join("/");
-  const message = `${dsl}/${filename}`;
-  const sig = await hmacSha256Hex(signingKey, message);
+  const now = opts.nowSeconds ?? Math.floor(Date.now() / 1e3);
+  const exp = Math.floor((now + ttl) / 60) * 60;
+  const sig = await hmacSha256Hex(
+    signingKey,
+    transformMessage({
+      tenantPrefix: tid.toString(36),
+      exp,
+      canonicalDsl: dsl,
+      filename
+    })
+  );
+  u.searchParams.set("kid", await deriveTransformKid(signingKey));
+  u.searchParams.set("exp", String(exp));
   u.searchParams.set("sig", sig);
   return u.toString();
 }
@@ -436,16 +510,16 @@ function materializeResolution(dto, overridePreset) {
 
 // src/index.ts
 var REQUESTABLE_PRESETS = [
-  "thumb",
-  "sm",
-  "md",
+  "aiproxy",
   "lg",
-  "xl",
+  "md",
   "original",
   "poster",
+  "probe",
+  "sm",
+  "thumb",
   "video",
-  "aiproxy",
-  "probe"
+  "xl"
 ];
 var isRequestablePreset = (v) => REQUESTABLE_PRESETS.includes(v);
 var toRequestablePresets = (input) => {
@@ -683,6 +757,9 @@ function getAssetDimensions(asset) {
   return null;
 }
 export {
+  MAX_SIGNED_TRANSFORM_TTL_SECONDS,
+  MAX_SIGNED_URL_TTL_SECONDS,
+  MIN_SIGNED_TRANSFORM_TTL_SECONDS,
   PRESET_EXT,
   PRESET_LONG,
   PRESET_MAX_DIM,
@@ -697,11 +774,13 @@ export {
   configureSlotResolver,
   contrastRatio,
   deriveAccessKey,
+  deriveTransformKid,
   extractAssetSha,
   getAmbientGradient,
   getAssetDimensions,
   getAssetSrcSet,
   getAssetUrl,
+  getByteBudgetTransformUrl,
   getCdnBase,
   getHlsLadder,
   getHlsStreamingUrl,
@@ -716,6 +795,7 @@ export {
   getTransformUrl,
   getVideoTransformUrl,
   hasPreset,
+  hasSizeLadder,
   hlsLadderAlignment,
   invalidateSlotCache,
   isRequestablePreset,
@@ -729,6 +809,7 @@ export {
   setTenantId,
   signAccessUrl,
   signTransformUrl,
-  toRequestablePresets
+  toRequestablePresets,
+  transformMessage
 };
 //# sourceMappingURL=index.js.map