@nitida/sdk 0.32.3 → 0.35.0

package/AGENTS.md

@@ -118,6 +118,32 @@ await getPrivateTransformUrl(asset, { width: 1280 }, signingKey, { expiresInSeco
   instead. This is the wall the T5 agent hit, and the sentence that was
   missing.
 
+## ⚠️ EXIF orientation — two dimension pairs, and mixing them stretches the photo
+
+A phone taking a portrait photo does not store portrait pixels: it writes the
+sensor buffer landscape and tags it `Orientation` 5–8. Every such file has two
+pairs, transposes of each other — `4032×3024` stored, `3024×4032` displayed.
+
+Stored pair → only orientation-invariant quantities (area, a megapixel budget).
+Displayed pair → anything geometric: a resize target, an aspect ratio, a layout
+box, a coordinate you denormalise.
+
+Mixing them shipped twice: `@nitida/asset-compressor-web` 0.6.0–0.6.2 stretched
+every affected photo **1.78×** (fixed in **0.6.3**), and `asset-manager` recorded
+the stored pair as the asset's `w`/`h` until 2026-08-28. Both needed orientation
+5–8 plus a long side above the box, and **HEIC was immune** — which is why it
+looked random. The damage is pre-upload, so affected photos must be re-uploaded,
+not repaired.
+
+Two traps worth naming:
+
+- **`createImageBitmap` with BOTH resize axes does not preserve the ratio.** Pass
+  one axis; the spec derives the other and the proportions survive by
+  construction.
+- **`sharp(x).rotate().metadata()` does NOT apply the rotation** — `.rotate()`
+  queues an operation, `.metadata()` reads the input. Measured on sharp 0.34.5:
+  it returns `4032×3024` while `.rotate().toBuffer()` returns `3024×4032`.
+
 ## Two ways an image gets smaller, and only one of them is yours to call
 
 This is the question every programmatic caller gets wrong, so it is stated flat:

package/README.md

@@ -568,6 +568,28 @@ generated server-side by the asset-manager's variant pipeline. A tenant
 cannot define custom dimensions through the SDK; they pick which preset a
 slot defaults to and emit responsive `srcSet` for browser-side resizing.
 
+### Preset short codes — generated, do not edit by hand
+
+A variant URL carries the **code**, not the preset name (`/v/<sha>-l.webp`,
+not `-lg.webp`). Copy the letter from here — `bun run gen:docs` regenerates
+this table from the source, so it can't have the wrong one.
+
+<!-- BEGIN GENERATED: preset-codes · bun run gen:docs -->
+| Preset | Code |
+|---|---|
+| `thumb` | `q` |
+| `sm` | `s` |
+| `md` | `m` |
+| `lg` | `l` |
+| `xl` | `x` |
+| `original` | `o` |
+| `poster` | `p` |
+| `video` | `v` |
+| `aiproxy` | `a` |
+| `hls` | `h` |
+| `mp3` | `mp3` |
+<!-- END GENERATED: preset-codes -->
+
 ### Image presets
 
 | Preset    | Code | Max-side           | Typical use |
@@ -875,10 +897,13 @@ const asset = await aq.assets.byHash(sha256);
 | `dpr` | `1` / `2` / `3` | `1` |
 
 > **`width` is strongly typed.** `TransformOptions.width` is a **`TransformWidth`** — the
-> predefined CDN ladder (`96, 128, 160, 240, 256, 320, 400, 480, 600, 640, 800, 960,
-> 1080, 1200, 1280, 1440, 1600, 1920, 2560, 3840` — 20 widths, exported as
-> `TRANSFORM_WIDTHS`). An off-ladder width is a **compile error**.
->
+> predefined CDN ladder below, exported as `TRANSFORM_WIDTHS`. An off-ladder width is a
+> **compile error**.
+
+<!-- BEGIN GENERATED: transform-widths · bun run gen:docs -->
+`96, 128, 160, 180, 240, 256, 320, 400, 480, 600, 640, 800, 960, 1080, 1200, 1280, 1440, 1600, 1920, 2560, 3840` — 21 widths.
+<!-- END GENERATED: transform-widths -->
+
 > ⚠️ **The type is narrower than the edge, on purpose.** The edge whitelists a
 > longer list (28 today — its own 400 response enumerates them, and `512`, `768`,
 > `1800`, `2160`, `2400`, `2700`, `2880` and `3600` all serve 200 unsigned). So a
@@ -1001,22 +1026,49 @@ const aq = new NitidaClient({
 });
 
 // Async when { sign: true } is set — overload returns Promise<string>.
-const signed = await aq.transform(asset, { width: 1280 }, { sign: true });
-// → https://8ok.uk/t/width=1280/<sha>.webp?sig=<64-hex>
+// `expiresInSeconds` is REQUIRED: a signature with no expiry is a bearer
+// token with no expiry. 120 s minimum, 7 days maximum.
+const signed = await aq.transform(
+  asset,
+  { width: 1280 },
+  { sign: true, expiresInSeconds: 3600 },
+);
+// → https://8ok.uk/t/width=1280/<sha>.webp?kid=<8-hex>&exp=<unix>&sig=<64-hex>
 
 // Responsive
 const srcset = await aq.transformSrcSet(
   asset,
   [640, 960, 1280, 1920],
   {},
-  { sign: true },
+  { sign: true, expiresInSeconds: 3600 },
 );
 ```
 
-Signature shape: `HMAC-SHA256(signingKey, "<canonical-DSL>/<filename>")`,
-hex-encoded. The server canonicalizes the URL the same way the SDK does
-(sort keys, lowercase strings), so two URLs with the same params in
-different order accept the same signature.
+Signature shape:
+
+```
+message = "nitida/transform/v2\n<tenantId base36>\n<exp>\n<canonical-DSL>/<filename>"
+sig     = HMAC-SHA256(signingKey, message)      // hex
+kid     = HMAC-SHA256(signingKey, "nitida/kid/v1").slice(0, 8)
+```
+
+The server canonicalizes the URL the same way the SDK does (sort keys,
+lowercase strings), so two URLs with the same params in different order accept
+the same signature.
+
+`kid` names the key so a rotation does not kill URLs already in flight: the
+outgoing key keeps verifying for 14 days
+(`POST /admin/projects/:code/rotate-signing-key` returns the new key, its `kid`,
+and when the previous one retires). See
+[the rotation runbook](https://github.com/espaciofuturoio/aquienpz/blob/main/docs/RUNBOOKS/signing-key-rotation.md).
+
+> ⚠️ **A signature does NOT widen the ladder.** Off-ladder widths are 400 at
+> the edge whether or not the URL is signed. Until `@nitida/asset-client`
+> 0.22.0 a valid-looking `?sig=` skipped the edge whitelist entirely, so a
+> signature bought an arbitrary width up to 7680 px — one request measured at
+> 1 850 MB. What a signature buys now is IDENTITY: which tenant asked, proven
+> with its key, until `exp`. That is what `strict_transforms` and the
+> `effect=genfill` cost guard require.
 
 ## Private assets — `visibility`
 

package/dist/index.d.ts

@@ -1,5 +1,5 @@
-import { ResolveSlotOptions, SlotResolution, SlotDTO, VariantPreset, AssetDTO, AssetVariant, RequestablePreset, TransformOptions, SignedTransformOptions } from '@nitida/asset-client';
-export { AssetDTO, AssetPalette, AssetVariant, HlsRung, PRESET_EXT, PRESET_LONG, PRESET_MAX_DIM, PRESET_SHORT, PaletteSwatch, REQUESTABLE_PRESETS, RequestablePreset, ResolveSlotOptions, SignAccessOptions, SignedTransformOptions, SlotDTO, SlotResolution, TRANSFORM_WIDTHS, TransformEffect, TransformFit, TransformFormat, TransformGravity, TransformOptions, TransformWidth, VariantEntryPreset, VariantPreset, 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 } from '@nitida/asset-client';
+import { ResolveSlotOptions, SlotResolution, SlotDTO, VariantPreset, AssetDTO, AssetVariant, RequestablePreset, TransformOptions, SignedTransformOptions, SignTransformOptions, TransformWidth } from '@nitida/asset-client';
+export { AssetDTO, AssetPalette, AssetVariant, 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, PaletteSwatch, PrivateTransformOptions, REQUESTABLE_PRESETS, RequestablePreset, ResolveSlotOptions, SignAccessOptions, SignTransformOptions, SignedTransformOptions, SlotDTO, SlotResolution, TRANSFORM_WIDTHS, TransformEffect, TransformFit, TransformFormat, TransformGravity, TransformOptions, TransformWidth, VariantEntryPreset, VariantPreset, 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 } from '@nitida/asset-client';
 
 /**
  * Which audio uploads already play everywhere — the single source of truth for
@@ -701,6 +701,22 @@ type UploadResult = {
      * objeto no lo llevaba. El resultado era una URL pública para un asset
      * privado, servida sin una queja, que después da 404.
      */
+    /**
+     * What the asset IS (`image` · `video` · `audio` · `document` · `other`).
+     *
+     * ⭐ It exists because it did not, and the guard caught it before anyone
+     * else did — the FIFTH member of this family, after `sha`, `mime`, `oext`
+     * and `presets`. When `getAssetUrl` learned to refuse `hls` on something
+     * that can never have a ladder, it started READING `kind`; an
+     * `UploadResult` without it silently opted out of the refusal and went
+     * right back to building `/t/format=hls/<sha>.m3u8` — which does not 404,
+     * it answers 200 with the image bytes.
+     *
+     * The rule this keeps re-teaching: a return type that omits what the next
+     * call reads is a silent 404 (or worse, a silent 200). The fix is always to
+     * carry the field, never to write a better error message about its absence.
+     */
+    kind: AssetDTO["kind"];
     visibility: "public" | "private";
     /**
      * La cadena compacta de variantes que EXISTEN (`"lmoqs"`, `"o"`, …).
@@ -894,7 +910,7 @@ declare class NitidaClient {
     transform(asset: Pick<AssetDTO, "sha">, opts?: TransformOptions): string;
     transform(asset: Pick<AssetDTO, "sha">, opts: SignedTransformOptions, signOpts: {
         sign: true;
-    }): Promise<string>;
+    } & SignTransformOptions): Promise<string>;
     /**
      * Build a responsive `srcSet` string. One transform URL per width; all
      * other options apply to every URL.
@@ -903,9 +919,9 @@ declare class NitidaClient {
      * call stays synchronous as before.
      */
     transformSrcSet(asset: Pick<AssetDTO, "sha">, widths: number[], extraOpts?: Omit<TransformOptions, "width">): string;
-    transformSrcSet(asset: Pick<AssetDTO, "sha">, widths: number[], extraOpts: Omit<TransformOptions, "width">, signOpts: {
+    transformSrcSet(asset: Pick<AssetDTO, "sha">, widths: TransformWidth[], extraOpts: Omit<TransformOptions, "width">, signOpts: {
         sign: true;
-    }): Promise<string>;
+    } & SignTransformOptions): Promise<string>;
     /**
      * Build an on-the-fly VIDEO transform URL — Phase 4.
      *

package/dist/index.js

@@ -32,6 +32,7 @@ import {
   configureSlotResolver as configureSlotResolver2,
   contrastRatio,
   deriveAccessKey,
+  deriveTransformKid,
   extractAssetSha,
   getAmbientGradient,
   getAssetDimensions,
@@ -55,6 +56,9 @@ import {
   invalidateSlotCache as invalidateSlotCache2,
   isRequestablePreset as isRequestablePreset2,
   iteratePaletteSwatches,
+  MAX_SIGNED_TRANSFORM_TTL_SECONDS,
+  MAX_SIGNED_URL_TTL_SECONDS,
+  MIN_SIGNED_TRANSFORM_TTL_SECONDS,
   PRESET_EXT,
   PRESET_LONG,
   PRESET_MAX_DIM,
@@ -70,7 +74,8 @@ import {
   signAccessUrl,
   signTransformUrl,
   TRANSFORM_WIDTHS,
-  toRequestablePresets as toRequestablePresets2
+  toRequestablePresets as toRequestablePresets2,
+  transformMessage
 } from "@nitida/asset-client";
 function endpointUrl(opts, path, searchParams) {
   const endpoint = opts.endpoint.replace(/\/+$/, "");
@@ -508,6 +513,13 @@ function mimeFromFileName(fileName) {
   return ext ? MIME_BY_EXT[ext] ?? null : null;
 }
 var DEFAULT_UPLOAD_PRESETS = ["original"];
+function kindForMime(mime) {
+  const m = (mime ?? "").toLowerCase();
+  if (m.startsWith("video/")) return "video";
+  if (m.startsWith("audio/")) return "audio";
+  if (m.startsWith("image/")) return "image";
+  return "other";
+}
 async function computeSha256(bytes) {
   const buf = bytes instanceof Blob ? await bytes.arrayBuffer() : bytes instanceof Uint8Array ? bytes.buffer : bytes;
   const digest = await crypto.subtle.digest("SHA-256", buf);
@@ -593,7 +605,11 @@ var NitidaClient = class {
         "aq.transform({ sign: true }) requires `signingKey` in NitidaClientOptions. No signingKey on this client. It is returned ONCE, in the response that creates your project (POST /admin/projects \u2192 `signingKey`, next to the three API keys; the console shows it in the same panel). If you never saw one \u2014 projects created before 2026-08-23 were not handed it \u2014 ask the platform operator to rotate: with no signed URLs in flight that invalidates nothing and is free. If you DO have signed URLs circulating, ask for the current key instead, because rotating would kill them. Then pass it to the SDK constructor on a SERVER-side instance only."
       );
     }
-    return getSignedTransformUrl(asset, opts, this.opts.signingKey) ?? Promise.resolve(this.urlFor(asset, "lg"));
+    return getSignedTransformUrl(asset, opts, this.opts.signingKey, {
+      expiresInSeconds: signOpts.expiresInSeconds,
+      tenantId: signOpts.tenantId ?? this.opts.tenantId,
+      nowSeconds: signOpts.nowSeconds
+    }) ?? Promise.resolve(this.urlFor(asset, "lg"));
   }
   transformSrcSet(asset, widths, extraOpts = {}, signOpts) {
     if (!signOpts?.sign) return getTransformSrcSet(asset, widths, extraOpts);
@@ -603,12 +619,18 @@ var NitidaClient = class {
       );
     }
     const key = this.opts.signingKey;
+    const sign = {
+      expiresInSeconds: signOpts.expiresInSeconds,
+      tenantId: signOpts.tenantId ?? this.opts.tenantId,
+      nowSeconds: signOpts.nowSeconds
+    };
     return Promise.all(
       widths.map(async (w) => {
         const signed = await getSignedTransformUrl(
           asset,
           { ...extraOpts, width: w },
-          key
+          key,
+          sign
         );
         return signed ? `${signed} ${w}w` : null;
       })
@@ -777,6 +799,7 @@ var NitidaClient = class {
         // Same shape as the presign branch below, for the same reason. This
         // DTO does carry `sha` today — but relying on that is how the other
         // branch broke, and the value we hashed ourselves is authoritative.
+        kind: existing.kind ?? kindForMime(mime),
         visibility: existing.visibility ?? "public",
         presets: existing.presets ?? "",
         variants: existing.variants ?? [],
@@ -837,6 +860,7 @@ var NitidaClient = class {
         // ACTUALLY has, now that we waited for it — not from
         // `defaultPresetForMime`, which is a guess made before anything exists.
         // Guessing was safe only while this branch never ran.
+        kind: settled.kind ?? kindForMime(mime),
         visibility: settled.visibility ?? "public",
         presets: settled.presets ?? "",
         variants: settled.variants ?? [],
@@ -888,6 +912,7 @@ var NitidaClient = class {
       sha: sha.slice(0, 16),
       mime: final.mime ?? mime,
       oext: final.oext ?? null,
+      kind: final.kind ?? kindForMime(final.mime ?? mime),
       visibility: final.visibility ?? "public",
       presets: final.presets ?? "",
       variants: final.variants ?? [],
@@ -942,6 +967,9 @@ var NitidaClient = class {
   }
 };
 export {
+  MAX_SIGNED_TRANSFORM_TTL_SECONDS,
+  MAX_SIGNED_URL_TTL_SECONDS,
+  MIN_SIGNED_TRANSFORM_TTL_SECONDS,
   NitidaClient,
   PRESET_EXT,
   PRESET_LONG,
@@ -957,6 +985,7 @@ export {
   configureSlotResolver2 as configureSlotResolver,
   contrastRatio,
   deriveAccessKey,
+  deriveTransformKid,
   extractAssetSha,
   getAmbientGradient,
   getAssetDimensions,
@@ -991,6 +1020,7 @@ export {
   setTenantId2 as setTenantId,
   signAccessUrl,
   signTransformUrl,
-  toRequestablePresets2 as toRequestablePresets
+  toRequestablePresets2 as toRequestablePresets,
+  transformMessage
 };
 //# sourceMappingURL=index.js.map