@nitida/sdk 0.33.0 → 0.36.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, 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 } from '@nitida/asset-client';
 
 /**
  * Which audio uploads already play everywhere — the single source of truth for
@@ -910,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.
@@ -919,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,
@@ -42,6 +43,7 @@ import {
   getHlsStreamingUrl as getHlsStreamingUrl2,
   getPaletteBlurBackground,
   getPaletteCssVars,
+  getByteBudgetTransformUrl,
   getPrivateAssetUrl,
   getPrivateTransformUrl,
   getSignedTransformUrl as getSignedTransformUrl2,
@@ -51,10 +53,14 @@ import {
   getTransformUrl as getTransformUrl2,
   getVideoTransformUrl as getVideoTransformUrl2,
   hasPreset as hasPreset2,
+  hasSizeLadder,
   hlsLadderAlignment,
   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 +76,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(/\/+$/, "");
@@ -600,7 +607,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);
@@ -610,12 +621,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;
       })
@@ -952,6 +969,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,
@@ -967,11 +987,13 @@ export {
   configureSlotResolver2 as configureSlotResolver,
   contrastRatio,
   deriveAccessKey,
+  deriveTransformKid,
   extractAssetSha,
   getAmbientGradient,
   getAssetDimensions,
   getAssetSrcSet2 as getAssetSrcSet,
   getAssetUrl2 as getAssetUrl,
+  getByteBudgetTransformUrl,
   getCdnBase,
   getHlsLadder,
   getHlsStreamingUrl2 as getHlsStreamingUrl,
@@ -986,6 +1008,7 @@ export {
   getTransformUrl2 as getTransformUrl,
   getVideoTransformUrl2 as getVideoTransformUrl,
   hasPreset2 as hasPreset,
+  hasSizeLadder,
   hlsLadderAlignment,
   invalidateSlotCache2 as invalidateSlotCache,
   isRequestablePreset2 as isRequestablePreset,
@@ -1001,6 +1024,7 @@ export {
   setTenantId2 as setTenantId,
   signAccessUrl,
   signTransformUrl,
-  toRequestablePresets2 as toRequestablePresets
+  toRequestablePresets2 as toRequestablePresets,
+  transformMessage
 };
 //# sourceMappingURL=index.js.map