@nitida/sdk 0.31.1 → 0.31.5

package/README.md

@@ -246,14 +246,14 @@ const aq = new NitidaClient({
   endpoint: "https://api.nitida.gofuture.space",
   apiKey:   process.env.AQUIENPZ_API_KEY!,          // amk_rt_* runtime API key
   tenantCode: "your-tenant",
-  tenantId:   42,                  // numeric tenant id (used in CDN URL prefix)
+  tenantId:   42,                  // ⚠️ va en la URL en BASE36: 42 → "16". Ni decimal, ni hex.
   cdnBase:    "https://8ok.uk",    // optional, defaults to https://8ok.uk
 });
 
 // Slots — the recommended way to reference brand assets in code.
 // Source never hardcodes a CDN URL; an admin rebinds it from the console.
 const hero = await aq.slots.resolve("storefront.home.hero");
-//   → { slot: { asset, preset, … }, preset: "lg", url: "https://8ok.uk/2a/v/<sha>-l.webp" }
+//   → { slot: { asset, preset, … }, preset: "lg", url: "https://8ok.uk/16/v/<sha>-l.webp" }
 
 // Bulk resolution in one round-trip.
 const heroes = await aq.slots.resolveMany([
@@ -271,7 +271,12 @@ const { assets, nextCursor } = await aq.assets.list({ limit: 50 });
 
 // Uploads — hash-deduped; returns the canonical v2 URL immediately.
 const result = await aq.upload(file, { fileName: "cover.jpg" });
-// → { assetId, sha256, cdnUrl }
+// → { assetId, sha256, sha, mime, oext, cdnUrl }
+//   `sha` (16 hex), `mime` y `oext` existen desde 0.30.0 para que el resultado
+//   se pueda pasar DIRECTO a cualquier builder, sin volver a buscar el DTO:
+//     getAssetUrl(result, "original")   // → -o.jpg, no -o.bin
+//   Un objeto armado a mano con sólo { assetId, sha256, cdnUrl } NO sirve:
+//   los builders leen `sha`, no `sha256`, y `assertSha` lo rechaza.
 
 // Uploading raw bytes (Node/Bun, e.g. re-hosting a remote image)? A Uint8Array has no
 // inherent MIME, so give it one — otherwise it stores as kind:"other" (NO image variants):
@@ -437,10 +442,10 @@ export function UploadHeroScreen() {
 }
 ```
 
-⚠️ The Expo background-upload path depends on `@nitida/asset-uploader-expo`,
-which is **not on npm**. `aq.upload()` works on Expo today without it; the
-background/resumable variant is not something an external consumer can install
-yet.
+ℹ️ `@nitida/asset-uploader-expo` **is on npm** (`0.2.0`, MIT) and installs
+normally. `aq.upload()` works on Expo without it; you want the uploader when you
+need a **resumable, background** upload — the only way a transfer survives iOS
+suspending the app. See the note above on when an uploader is worth adding.
 
 ## Next.js App Router (Server Components)
 
@@ -634,7 +639,7 @@ Both symbols are real. Neither is orderable.
 |---|---|---|
 | `thumb` `sm` `md` `lg` `xl` `original` `poster` `video` `aiproxy` | ✅ | ✅ |
 | `hls` — the adaptive ladder, built when a video transcodes | ❌ | ✅ |
-| `mp3` — emitted automatically alongside any audio original | ❌ | ✅ |
+| `mp3` — emitted alongside an audio original **only when the original is not already universally playable** (i.e. NOT `audio/mpeg`, `audio/mp4`, `audio/aac`) | ❌ | ✅ |
 | `probe` — indexed stills (`-pr0.jpg`), never on the compact `presets` string | ✅ | ❌ |
 
 The write methods (`upload`, `presignUploadUrl`, `regenerate`) take
@@ -803,7 +808,29 @@ context.
 
 | you have | use | why |
 |---|---|---|
-| a client (`aq`) | **`aq.transform(asset, opts)`** | it already knows your CDN base and tenant, and it is the only one that can **sign** — `aq.transform(asset, opts, { sign: true })` returns a `?sig=` URL, which is the only way to an off-ladder width |
+| a client (`aq`) | **`aq.transform(asset, opts)`** | it already knows your CDN base and tenant (⚠️ see the multi-tenant warning below), and it is the only one that can **sign** — `aq.transform(asset, opts, { sign: true })` returns a `?sig=` URL, the only way to an **arbitrary** width |
+
+> ⚠️ **THE TENANT IS ONE MODULE-WIDE GLOBAL, NOT PER-CLIENT STATE.**
+>
+> Constructing a `NitidaClient` calls `setTenantId()` — the same global the standalone
+> setter writes. **The last client constructed wins**, and every client made before it
+> silently starts emitting the other tenant's URLs. Measured:
+>
+> ```ts
+> const a = new NitidaClient({ …, tenantId: 15 });
+> a.urlFor(asset, "md");   // → https://8ok.uk/f/v/<sha>-m.webp   ✅
+>
+> const b = new NitidaClient({ …, tenantId: 4 });
+> a.urlFor(asset, "md");   // → https://8ok.uk/4/v/<sha>-m.webp   ❌ 404, no error
+> ```
+>
+> It affects everything that carries a tenant segment — `urlFor`, `srcSetFor`,
+> `getAssetUrl`, and the private `/a/{tenant}/…` tree. Public `transform()` has no tenant
+> segment, so it is unaffected.
+>
+> In a multi-tenant process (a BFF, a cron, a migration) use **one process per tenant**,
+> or call `setTenantId(n)` immediately before each block of URL building. Holding two
+> clients and trusting each to remember its own tenant does not work.
 | only a DTO — a component, a Server Component, a worker | **`getTransformUrl(asset, opts)`** | no client needed. Call `setCdnBase()` / `setTenantId()` once at module load first |
 
 Same builder underneath, same URL out. If you are holding a client, use its
@@ -846,12 +873,30 @@ const asset = await aq.assets.byHash(sha256);
 > **`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**: the edge whitelists exactly these as a DoS guard and
-> HTTP 400s anything else on unsigned URLs. Need a custom off-ladder width? **Sign it** —
+> `TRANSFORM_WIDTHS`). An off-ladder width is a **compile error**.
+>
+> ⚠️ **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
+> width outside the TYPE is not automatically a 400; a width outside the EDGE's
+> list is. Signing is the only way to an **arbitrary** width — not to every width
+> outside `TransformWidth`. Need an arbitrary one? **Sign it** —
 > `aq.transform(asset, { width: 1490 }, { sign: true })` and `getSignedTransformUrl` take
 > `SignedTransformOptions` (where `width` widens to `number`); a valid `?sig=` earns the
-> edge-whitelist bypass. `transformSrcSet` / `getTransformSrcSet` deliberately keep
+> edge-whitelist bypass.
+>
+> ⚠️ **Signed widths have two ceilings the edge does not announce** (measured
+> 2026-08-24):
+>
+> 1. **7680 is the hard cap.** `7680` → 200, `7681` → 400. Unsigned, the real
+>    cap is 3840 — so `3841…4320` is a dead band the old 400 message called
+>    "in range", and `4321…7680` works signed while that message called it
+>    impossible.
+> 2. **Above the source width it CLAMPS and still answers 200.** `/t/` never
+>    upscales. Ask for 5000 on an 800 px master and you get **800 px of bytes
+>    with HTTP 200** — no error, no warning. Read `x-transform-dsl` on the
+>    response (it names the width actually used) or size against the source, if
+>    the exact width matters. `transformSrcSet` / `getTransformSrcSet` deliberately keep
 > `number[]` because a responsive ladder may legitimately include DPR-row widths (e.g.
 > `2400`). `height` stays `number` — for the responsive path it's derived from `width`
 > by aspect ratio; only fixed-canvas crops / `genfill` set it explicitly.
@@ -865,8 +910,14 @@ point of asking for `auto` instead of naming a format.
 `gravity=face` detects the highest-confidence face and crops to it with
 sensible padding (50 % of face dimensions on each side, clamped to source
 bounds, keeping the requested aspect ratio). When no face is detected it
-falls back to saliency-based cropping and returns the response with
-`X-Transform-Face: fallback`, so you can tell the two apart. Cost to you:
+falls back to saliency-based cropping. The response **always** carries
+`X-Transform-Face`, with one of two values: **`matched`** when a face was found,
+**`fallback`** when it saliency-cropped.
+
+⚠️ Check the VALUE, not the presence. The header is emitted **only for
+`gravity=face`** — with `center` or `auto` it is absent, and that absence does
+not mean "no face". Code that tests for presence is right 0 % of the time on
+photos that do contain a face. Cost to you:
 ~10 ms warm; ~150 ms on the first request after a cold start.
 
 `quality=auto` adapts the per-format quality to source complexity
@@ -1098,6 +1149,14 @@ the cache semantics are the contract.
 
 ### Generative fill / aspect outpaint (`effect=genfill`)
 
+⚠️ **`genfill` only works on SIGNED URLs.** It is a cost guard: the effect runs
+a generative model per unique tuple. Without `{ sign: true }` the edge answers
+`401 {"error":"signature_required"}` — whether or not your tenant has
+`strict_transforms`, and unlike `width=` or `effect=removebg`, which serve 200
+unsigned. You need the project's **signing key** (see *Signed URLs*); for a
+project created before 2026-08-23, ask your operator — it cannot be recovered
+afterwards. Every example below therefore passes `{ sign: true }`.
+
 Extend a source image into a different aspect ratio without the
 awkward edge mirroring that classic content-aware fill produces.
 Primary use case: building OG cards (1200×630) from portrait listing
@@ -1106,24 +1165,26 @@ photos, or 1:1 social tiles from 16:9 originals.
 ```ts
 // 1200×630 OG card from a portrait listing cover — the gutters are
 // generated, the source is pasted centered.
-const ogUrl = aq.transform(asset, {
-  effect: "genfill",
-  width: 1200,
-  height: 630,
-});
-// → https://8ok.uk/t/effect=genfill,height=630,width=1200/<sha>.png
+const ogUrl = await aq.transform(
+  asset,
+  { effect: "genfill", width: 1200, height: 630 },
+  { sign: true },                       // ⚠️ sin esto: 401 signature_required
+);
+// → https://8ok.uk/t/effect=genfill,height=630,width=1200/<sha>.webp
 
 // 1:1 social tile from a landscape original
-const tileUrl = aq.transform(asset, {
-  effect: "genfill",
-  width: 1080,
-  height: 1080,
-});
+const tileUrl = await aq.transform(
+  asset,
+  { effect: "genfill", width: 1080, height: 1080 },
+  { sign: true },
+);
 ```
 
 **Requires both `width` and `height`.** Without them the route returns
 422 — the effect needs an explicit target canvas to know what to
-outpaint.
+outpaint. ⚠️ You only ever see that 422 **after** signing: unsigned, the 401
+comes first, so a missing `{ sign: true }` looks like a different bug than it
+is.
 
 **Output defaults to WebP** at q=85 (~150KB for a 1200×630 OG card —
 12× lighter than the raw generated PNG). Honors `format=` for
@@ -1144,7 +1205,19 @@ landscape source ✓). For bigger crops, prefer `gravity=auto` smart-crop,
 which is deterministic and free — no generation, no invention.
 
 **What it costs you: ~$0.05 for the first request** per (sha, dsl, format)
-tuple. Subsequent identical requests are 302 redirects to the cached PNG —
+⚠️ **The signature guards GENERATION, not DELIVERY.** Once a signed transform
+runs, its result is written to `/{tenant}/v/<sha>-t<dslHash>.<ext>` and served
+there **with HTTP 200 and no `?sig=`**. `<dslHash>` is `sha256(canonical DSL)`
+truncated to 16 — **no secret in it**, so anyone who guesses the DSL derives the
+URL. Measured: a signed `width=641` (unreachable unsigned) went from 404 to 200
+at the derived path after a single signed GET.
+
+Two consequences worth planning around: turning on `strict_transforms` does not
+un-publish anything already generated, and for `genfill` — whose entire cost
+guard is the signature — the result you paid for stays publicly readable. Treat
+a signed transform as "pay once, publish forever", not as an access control.
+
+tuple. Subsequent identical requests are 302 redirects to the cached WebP —
 zero generative cost, forever. The model is server-side and may be swapped
 for a better one without any change on your side; the DSL, the output and
 the cache semantics are the contract.
@@ -1229,7 +1302,15 @@ First request to a new HLS URL returns **202 Accepted** with
 
 The ladder shrinks to fit the source: a 480p source produces three
 rungs (240p / 360p / 480p), a 1080p source produces five, and a 4K
-source goes up to 2160p. The player picks the right rung on the fly
+source goes up to 2160p.
+
+> ⚠️ **Clips under 18 seconds are the exception, and they are common.**
+> A short source is restricted to the 720p–1080p band on purpose, so an 8 s
+> 720p clip gets **one rung**, not four — the rung-switching a ladder exists
+> for cannot happen inside a clip that short, and building five of them just
+> burns transcode budget. Read `switchable` on the ladder rather than
+> `rungs.length`: it is `false` exactly when there is nothing to switch
+> between. A test asserting `rungs.length > 1` will fail on every short clip. The player picks the right rung on the fly
 based on the current connection — a user on 3G starts at 240p and
 climbs to 1080p as bandwidth improves, vs the monolithic MP4 that
 either loaded or timed out.
@@ -1268,7 +1349,10 @@ const bg = getAmbientGradient(asset.palette);
 //   bg = "linear-gradient(135deg, oklch(...), oklch(...))"
 
 // Auto-pick text color that contrasts with the chosen ambient:
-const fg = getTextColorForBackground(asset.palette);
+// ⚠️ `getTextColorForBackground` toma UN SWATCH, no la paleta entera.
+// Pasarle `asset.palette` tira `TypeError: … evaluating 'hex.replace'`.
+const bg = pickAmbientBackground(asset.palette);   // PaletteSwatch | null
+const fg = getTextColorForBackground(bg);
 //   fg = "#fff" | "#000" | similar
 
 // Or just the blurry LQIP for a CSS background placeholder:
@@ -1277,8 +1361,16 @@ const placeholder = getPaletteBlurBackground(asset.palette);
 
 The wire format is intentionally tight: `{d, v, m, dv, lv, dm, lm}`
 (dominant, vibrant, muted, dark-vibrant, light-vibrant, dark-muted,
-light-muted). 7 hex strings per asset — much smaller than a full
-base64 LQIP, but composes into nicer ambient UX.
+light-muted) — **up to** 7 hex strings per asset, much smaller than a full
+base64 LQIP but composing into nicer ambient UX.
+
+⚠️ **Only `d` (dominant) is guaranteed. Every other key is optional**, because
+only the swatches the source actually had get extracted — measured across 30
+assets, palettes carry anywhere from 2 to 7 keys. Never index one directly:
+`palette.dv` on a 2-swatch palette emits
+`linear-gradient(135deg, #1a1a1a, undefined)`. Use the helpers
+(`pickAmbientBackground`, `getAmbientGradient`, `getPaletteCssVars`), which skip
+the missing ones.
 
 When the image can't be decoded (SVG sources, exotic formats,
 deliberately corrupted bytes), palette + blur silently come back
@@ -1315,8 +1407,13 @@ server-side pipeline (a platform-wide addition, not a per-tenant one).
 
 `<cdnBase>/<tenantId base36>/v/<sha16>-<presetCode>.<ext>`
 
-Example: `https://8ok.uk/f/v/c482458e824c730e-q.webp` — the `thumb` preset of
-sha `c482458e…` as WebP, for **tenant 15** (`15` in base36 is `f`).
+Example: `https://8ok.uk/f/v/<sha16>-q.webp` — the `thumb` preset of a 16-hex
+sha as WebP, for **tenant 15** (`15` in base36 is `f`).
+
+> `<sha16>` is a placeholder on purpose. A concrete sha pinned here rots: the
+> previous example pasted a **real tenant-4 URL with the prefix swapped to
+> `f`**, so it 404'd on every preset while the identical path under `/4/` served
+> 200. Substitute a sha from your own tenant — `upload()` returns it as `sha`.
 
 ⚠️ **The tenant segment is not optional, and it is base36.** `/15/…` 404s;
 so does a bare `/<sha16>-q.webp` with no tenant at all. Nothing serves that

package/dist/index.js

@@ -794,12 +794,15 @@ var NitidaClient = class {
     });
     if (presign.deduped) {
       const short = sha.slice(0, 16);
+      const settled = presign.asset.status === "ready" ? presign.asset : await this.assets.waitReady(presign.asset.id, opts.timeoutMs);
+      if (settled.status !== "ready")
+        throw new Error(`upload: asset ended status=${settled.status}`);
       return {
-        assetId: presign.asset.id,
+        assetId: settled.id,
         sha256: sha,
         sha: short,
-        mime: presign.asset.mime ?? mime,
-        oext: presign.asset.oext ?? null,
+        mime: settled.mime ?? mime,
+        oext: settled.oext ?? null,
         // ⭐ `{ ...asset, sha: short }`, never `asset` alone.
         //
         // The presign route answers a dedup hit with `sha256` and NO `sha` —
@@ -816,14 +819,24 @@ var NitidaClient = class {
         // latent defect loud.
         //
         // This branch is only reached when the asset EXISTS but is not
-        // `ready` — the `byHash` branch above returns first otherwise — so
-        // ordinary uploads never touched it and no test did either.
+        // `ready` — the `byHash` branch above returns first otherwise.
+        //
+        // That sentence used to end with "so ordinary uploads never touched it
+        // and no test did either", and that was the whole problem: it read as
+        // reassurance when it was the risk. Two callers uploading the same
+        // bytes at once land here, and a retry after a timeout is exactly that.
+        // Covered now by `every-upload-branch-waits-for-ready.test.ts`.
         //
         // The sha is not the DTO's to supply: we hashed the bytes ourselves at
         // the top of this method. Build from what we KNOW.
+        //
+        // And the preset comes from `bestPresetForAsset` — what this asset
+        // 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.
         cdnUrl: this.urlFor(
-          { ...presign.asset, sha: short },
-          this.defaultPresetForMime(mime)
+          { ...settled, sha: short },
+          this.bestPresetForAsset(settled, mime)
         )
       };
     }