@nitida/sdk 0.31.1 → 0.31.5

package/skills/nitida-sdk/SKILL.md

@@ -55,6 +55,12 @@ it; point new work at `api.nitida.gofuture.space` and move the rest whenever it
 The URL builders read **process-global** config. Pin it where your helpers live (a `lib/nitida-images.ts`), so every Server/Client Component that imports a builder is configured:
 
 ```ts
+// ℹ️ WHICH PACKAGE TO IMPORT FROM: both work.
+// `@nitida/sdk` re-exports everything `@nitida/asset-client` has — including
+// `setCdnBase` and `setTenantId` — so if you installed the SDK, import from
+// `@nitida/sdk` and never name `asset-client` at all (it is there as a peer
+// dependency). The examples below say `@nitida/asset-client` because this
+// skill also serves consumers who use that package on its own, without the SDK.
 import { setCdnBase, setTenantId } from "@nitida/asset-client";
 
 const TENANT_ID = Number(process.env.NEXT_PUBLIC_NITIDA_TENANT_ID) || /* your id */ 0;
@@ -90,6 +96,11 @@ Output URL shape: `https://8ok.uk/t/format=webp,width=640/<sha16>.webp`.
 
 ⚠️ **Widths MUST be on the unsigned ladder** `TRANSFORM_WIDTHS` (`96,128,160,240,256,320,400,480,600,640,800,960,1080,1200,1280,1440,1600,1920,2560,3840` — 20 widths). Any other width → **HTTP 400** at the edge (DoS guard). The `TransformWidth` type makes an off-ladder width a compile error — import the type, don't hardcode magic numbers. (For a one-off custom width you'd need signed URLs; not used here.)
 
+⚠️ **`getTransformSrcSet` is NOT protected by that type.** Its parameter is `number[]` on purpose —
+a responsive ladder may legitimately carry DPR widths — so `[641, 999]` compiles clean and fails in
+production, one 400 per candidate. There the check is yours:
+`widths.every((w) => TRANSFORM_WIDTHS.includes(w as TransformWidth))`.
+
 ## 2b. A responsive gallery — the widths, with their measured weight
 
 > Full page, with the reasoning: <https://nitida.gofuture.space/examples/responsive-gallery/>
@@ -159,12 +170,10 @@ everyone, and the ladder buys you nothing.
 - ⚠️ **`/t/` never upscales — the master is the ceiling.** Measured: a 2400 px
   master asked for `width=2560` returns **2400 px**. Put widths in the `srcSet`
   that your sources can sustain.
+  Asking for more is **not an error**: it is a smaller image than you think you
+  requested, which is worse than a failure because nothing tells you.
   (There IS a paid, separate `POST /assets/:id/upscale` that genuinely enlarges
   with a model. It is not the transform route and it is not free — §8g.)
-- ⚠️ **There is no upscale — the master is the ceiling.** Measured: a 2400 px
-  master asked for `width=2560` returns **2400 px**. Put widths in the `srcSet`
-  that your sources can sustain — asking for more is not an error, it is a
-  smaller image than you think you requested.
 - ⚠️ The **first** request of each width is generated cold, then cached at the
   edge immutably. Warm them after upload if the first visitor matters.
 
@@ -175,7 +184,7 @@ everyone, and the ladder buys you nothing.
 `/t/` short-circuits to the smallest **stored variant** that covers the request
 — and that variant is already a WebP
 that went through one lossy pass. **The short-circuit only fires when the
-request carries an explicit numeric `quality`**, so the `quality: 75` above is
+request carries an explicit numeric `quality`**, so **passing any explicit numeric `quality` at all** is
 exactly what turns it on.
 
 Measured at `width=800` on five photographs, same photo uploaded twice (full
@@ -280,9 +289,23 @@ If you are uploading to **archive** something (not just to serve it), three serv
 //                                 ↑ the UPLOADED file's extension, not one derived from the mime
 ```
 
-The client's `PRESET_EXT.original` is the literal `"bin"`, so `getAssetUrl({sha}, "original")` **without `mime`** emits `-o.bin` while a PNG is really stored at `-o.png` → 404, always.
+✅ **Since `@nitida/sdk@0.30.0` the obvious call is the correct one.** Pass the
+result of `upload()` — or a DTO from `assets.get(id)` — and `original` resolves
+to the real extension:
 
-> ✅ **Fixed in the 2026-08-17 deploy. Pass the whole DTO and it is simply right:**
+```ts
+const up = await nt.upload(file, { fileName, presets: ["original", "md"] });
+getAssetUrl(up, "original");      // → -o.jpg, not -o.bin
+```
+
+⚠️ **The failure below is what happens when you hand it a BARE `{ sha }`** — no
+`mime`, no `oext`, no variant list. `PRESET_EXT.original` is the literal
+`"bin"`, so `getAssetUrl({ sha }, "original")` emits `-o.bin` while a PNG is
+really stored at `-o.png` → 404. That is the only case left; it is not the
+general one.
+
+> **History, kept because the symptom still gets reported.** Before the
+> 2026-08-17 deploy this happened even with a full DTO:
 >
 > ```ts
 > const asset = await nt.assets.get(id);
@@ -353,12 +376,19 @@ Cleanup keeps the raw bytes of **any** sha referenced by an asset row, soft-dele
 
 | what you call | what you get |
 |---|---|
-| `getAssetUrl(asset, "md")` | **404** — that variant was never generated |
-| `/t/…width=1280/<sha>.webp` | **200** — generated on the fly from the raw |
-| `hasPreset(asset, "lg")` | `false`, correctly |
+| `getAssetUrl(asset, "md")` | **200** — since 2026-08-22 it returns the `/t/` URL and the edge generates from the raw |
+| `/t/…width=1280/<sha>.webp` | **200** — the same thing, written by hand |
+| `hasPreset(asset, "lg")` | `false`, correctly — the *variant* really is absent |
+
+⚠️ **The incoherence this block described is fixed, and in the good direction.** For **image**
+presets (`thumb·sm·md·lg·xl`) a missing preset does NOT 404: `getAssetUrl` returns the `/t/` route
+and the edge generates from the raw. Measured today on an asset with `presets:"lmoqs"` —
+`getAssetUrl(a,"xl")` → `/t/format=webp,width=3840/<sha>.webp` → **200 image/webp**, while the
+variant key `-x.webp` does 404.
 
-One API tells you it does not exist and the other hands it to you. **That** is the expensive part —
-not the loss, the incoherence — plus a cold compute the first time anyone asks for each size.
+What stays true: `hasPreset` is still the truth about whether the **materialised variant** exists,
+and the first request of each width pays a cold compute. And for **video/audio** presets
+(`poster·video·aiproxy·hls·mp3·original`) there is **no fallback** — there, `hasPreset` first or 404.
 
 **It is fixable at any time** with `regenerate({presets:[...]})`, which reads from the raw. No
 window closes.
@@ -674,7 +704,8 @@ await nt.upload(file, { presets: ["original", "thumb", "md", "lg"] });
 |---|---|---|
 | `image/*` | ladder | WebP variants + palette + dimensions |
 | `video/*` | background job | poster · mp4 · HLS · optional `aiproxy`/`probe` |
-| `audio/*` | inline transcode | `mp3` variant (mono ~96 kbps) **+** untouched original |
+| `audio/*` **already playable everywhere** (`audio/mpeg`, `audio/mp4`, `audio/aac`) | none | original ONLY — `presets: "o"`. ⚠️ `getAssetUrl(a,"mp3")` **404s**: re-encoding an MP3 into an MP3 only makes it worse, so we stopped (2026-08-22). |
+| `audio/*` anything else (`wav`, `webm`/opus, `flac`, …) | inline transcode | `mp3` variant (mono ~96 kbps) **+** untouched original — `presets: "mp3o"` |
 | anything else | **passthrough** | raw bytes under `original`, `ready` immediately |
 
 Passthrough covers PDF, xlsx, csv, zip, fonts, glb. You get storage, dedup and
@@ -737,7 +768,7 @@ job. Skip `aiproxy` when nothing reads it — it is an extra encode per video.
   is `number`. Unsigned off-ladder = 400 at the edge (DoS guard). Sign
   server-side.
 - **Upscale** → `POST /assets/:id/upscale`. **A paid add-on, and the SDK does
-  not expose it on purpose** — €0.10 a metered run, so it is never something a
+  not expose it on purpose** — **€0.01–€0.40 per run depending on provider**, so it is never something a
   helper should make easy to call in a loop. Call it over HTTP, deliberately.
 
   ```jsonc
@@ -752,7 +783,7 @@ job. Skip `aiproxy` when nothing reads it — it is an extra encode per video.
     "enhanceRealism": true,     // mode=enhance
     "provider": "wavespeed-phota-enhance"        // €0.09
               | "replicate-p-image-upscale"      // €0.01
-              | "wavespeed-clarity-flux-upscaler"
+              | "wavespeed-clarity-flux-upscaler"  // €0.40 ⚠️ the priciest, 4× the default
   }
   ```
 

package/src/index.ts

@@ -1713,12 +1713,40 @@ export class NitidaClient {
     });
     if (presign.deduped) {
       const short = sha.slice(0, 16);
+      // ⭐⭐ A DEDUP HIT ON A STILL-PROCESSING ASSET HAS TO WAIT, LIKE ANY OTHER
+      //
+      // `upload()` documents itself as "wait until the asset is ready", and
+      // `opts.timeoutMs` as "max time to wait for the asset to transition to
+      // `ready`". Both branches around this one honour that: `byHash` above
+      // gates on `existing.status === "ready"`, and the happy path below calls
+      // `waitReady`. This one returned IMMEDIATELY, whatever the status.
+      //
+      // Measured 2026-08-24: upload a video, wait 15 s, upload the same bytes
+      // again. The second call resolved in 15.5 s — while the first was still
+      // 85 s from done — and handed back `…-v.mp4`, which 404s for those 85
+      // seconds. `status: "processing"`, `presets: ""`, `variants: []`.
+      //
+      // ⚠️ It is the FOURTH defect of one family: a result that hands you a URL
+      // which 404s. The other three were missing FIELDS (`sha`, `mime`,
+      // `oext`); this one is a missing WAIT. Same symptom, and the same
+      // reason it survived — the comment right below used to say this branch
+      // was unreachable by ordinary uploads, so nothing exercised it. A branch
+      // nobody reaches is a branch nobody checks.
+      //
+      // Racing two uploads of the same bytes is not exotic: a retry after a
+      // timeout does it, and so does any parallel importer.
+      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` —
@@ -1735,14 +1763,24 @@ export class NitidaClient {
         // 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),
         ),
       };
     }