@nitida/sdk 0.30.0 → 0.30.2

package/skills/nitida-sdk/SKILL.md

@@ -159,6 +159,10 @@ everyone, and the ladder buys you nothing.
   that your sources can sustain.
   (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.
 
@@ -223,6 +227,11 @@ Output: `https://8ok.uk/<tenantId.toString(36)>/v/<sha16>-v.mp4`.
 
 **Do NOT:**
 - ❌ Use `getVideoTransformUrl` — that builds a `/t/...` transform URL, which never returns playable video. On a video sha `/t/` transforms the **poster frame**: `200 image/webp` with `x-transform-source: poster` when a poster exists, `410` when it does not. (`getVideoTransformUrl` is for on-the-fly re-encodes, a different feature.)
+- ❌ Use `getVideoTransformUrl` for the HLS entry — that builds a `/t/…`
+  transform URL. ⚠️ **A 410 there means the SOURCE BYTES ARE GONE**
+  (`source_unavailable`), **not** that you used the wrong builder. Do not go
+  change the call site while data loss goes unnoticed. (`getVideoTransformUrl`
+  is for on-the-fly re-encodes — a different feature.)
 - ❌ Hand-roll the path with the decimal tenant id. The path segment is **base36**: `tenantId.toString(36)`. **Tenant 10 → `/a/v/`**, and the decimal `/10/v/` **404s**. This is invisible for tenants ≤ 9 (`8`→`8`, `9`→`9`) and bit a real migration only at tenant 10. Always delegate to `getAssetUrl` so the encoding can't drift.
 
 **Audio IS supported (updated 2026-07-01 — verify against the SDK types, this used to say "not supported").** The platform recognizes `kind: "image" | "video" | "document" | "audio" | "other"` and ships an **`mp3`** variant preset (`VariantPreset` in `@nitida/asset-client`). Uploads are hash-deduped (byte-identical re-uploads return the existing sha — that's *byte* dedup, NOT semantic "find a similar track"). `nt.upload` also accepts an `audioTrack` on video-composition calls. Serve via the `mp3` preset / `original`. Confirm the current preset/kind list in `node_modules/@nitida/asset-client/dist/index.d.ts` before relying on a specific ext.
@@ -278,15 +287,45 @@ The client's `PRESET_EXT.original` is the literal `"bin"`, so `getAssetUrl({sha}
 > getAssetUrl(asset, "original");   // → the stored key, verbatim
 > ```
 >
+> ⭐ **And since `@nitida/sdk@0.30.0`, the result of `upload()` works too** —
+> it carries `mime` and `oext`, so the obvious call is the correct one and you
+> do not have to fetch the DTO first:
+>
+> ```ts
+> const up = await nt.upload(file, { fileName, presets: ["original", "md"] });
+> getAssetUrl(up, "original");      // → -o.jpg, not -o.bin
+> ```
+>
+> Before 0.30.0 that call built `-o.bin` and 404'd over a file that was there.
+> An agent running the getting-started doc verbatim found it on 2026-08-23.
+>
 > `GET /assets/:id` now sends `variants` (the full list, URLs included) and `oext` (the extension
 > the original was really stored under). `getAssetUrl` prefers the stored URL, falls back to
 > `oext`, and only then guesses from the mime.
 >
 > **Why guessing could never work.** The server keys the original off the **uploaded filename's
-> extension**, which the mime does not determine. Measured over the 2 001 stored
-> originals in production: all **420** `image/jpeg` originals are `.jpg` and none are `.jpeg`, so
-> the old mime table 404'd on every JPEG; and **234** originals are `application/octet-stream`
-> (`.mpga`, `.docx`, `.m4a`), where no mime table can ever produce the right key.
+> extension**, which the mime does not determine. `image/jpeg` originals are stored `.jpg` and
+> never `.jpeg`, so a mime table that guessed `.jpeg` 404'd on every one of them.
+>
+> And a tail exists that **no** mime table can close: originals stored as
+> `application/octet-stream`, where the mime says nothing about the extension.
+> Re-measured 2026-08-24 over 3 211 live originals: **113** — and the split is
+> the part worth carrying, because the total hides it:
+>
+> | | | |
+> |---|---|---|
+> | **109** | `.bin` in `sdk-e2e` | 29-byte degenerate PNG fixtures — test residue, and `bin` IS their extension, so the fallback is right |
+> | **4** | `.docx` in `realtyone-cr` | the fallback builds `-o.bin` → **404**, while `-o.docx` → **200** |
+>
+> ⚠️ **This number used to read 234, and that was true until it wasn't.**
+> `heal-misclassified-assets` (#245) reclassified 121 of them to their real
+> mime — MP3s that had round-tripped through `.mpga`, WebPs uploaded with no
+> declared type. 234 − 121 = 113. A published measurement with no date is a
+> claim that decays silently; this one is dated, and so should the next.
+>
+> ⭐ **A fallback that is right 109 times out of 113 is the shape of bug that
+> survives for months**, because almost every sample agrees with it. Only the
+> four `.docx` ever fail, and only `oext` rescues them.
 >
 > Two things that did NOT change: existence still comes from `dto.presets` + `hasPreset` (the only
 > field on every response shape), and `getAssetUrl` was always correct for `video`/`poster`, whose

package/src/index.ts

@@ -1684,7 +1684,13 @@ export class NitidaClient {
         sha: sha.slice(0, 16),
         mime: existing.mime ?? mime,
         oext: existing.oext ?? null,
-        cdnUrl: this.urlFor(existing, this.bestPresetForAsset(existing, mime)),
+        // 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.
+        cdnUrl: this.urlFor(
+          { ...existing, sha: sha.slice(0, 16) },
+          this.bestPresetForAsset(existing, mime),
+        ),
       };
     }
 
@@ -1706,13 +1712,38 @@ export class NitidaClient {
       ...(opts.video != null && { video: opts.video }),
     });
     if (presign.deduped) {
+      const short = sha.slice(0, 16);
       return {
         assetId: presign.asset.id,
         sha256: sha,
-        sha: sha.slice(0, 16),
+        sha: short,
         mime: presign.asset.mime ?? mime,
         oext: presign.asset.oext ?? null,
-        cdnUrl: this.urlFor(presign.asset, this.defaultPresetForMime(mime)),
+        // ⭐ `{ ...asset, sha: short }`, never `asset` alone.
+        //
+        // The presign route answers a dedup hit with `sha256` and NO `sha` —
+        // literally the shape `assertSha`'s message names. Handing it straight
+        // to a URL builder threw:
+        //
+        //   getAssetUrl: no usable `sha` … has `sha256` but not `sha` —
+        //   that is the shape `upload()` returns.
+        //
+        // …with `upload()` as BOTH the accuser and the caller. Found
+        // 2026-08-24 by neo's hourly canary, ~16 alerts deep. Before
+        // asset-client 0.18.1 the same line produced a `cdnUrl` with the word
+        // `undefined` inside it, silently; the guard did its job and made a
+        // 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.
+        //
+        // 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.
+        cdnUrl: this.urlFor(
+          { ...presign.asset, sha: short },
+          this.defaultPresetForMime(mime),
+        ),
       };
     }