@nitida/sdk 0.29.0 → 0.30.1

package/skills/nitida-sdk/SKILL.md

@@ -278,15 +278,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

@@ -1109,6 +1109,32 @@ export type UploadResult = {
    * message about the wrong one.
    */
   sha: string;
+  /**
+   * The MIME the upload was stored under.
+   *
+   * ⭐ It exists because it did not, and that cost the THIRD 404 of this exact
+   * family. Found 2026-08-23 by an agent running the getting-started doc
+   * verbatim: `getAssetUrl(up, "original")` built `<sha>-o.bin` and 404'd,
+   * while the object served fine at `-o.jpg`.
+   *
+   * `original` is the one preset whose extension is not fixed — it is the
+   * bytes you uploaded, so the extension comes from the MIME (`ORIGINAL_EXT_BY_MIME`),
+   * and `PRESET_EXT.original` is only the `"bin"` fallback for when nothing
+   * says otherwise. `UploadResult` said nothing, so every caller handing an
+   * upload result straight to a URL builder got the fallback.
+   *
+   * The pattern is now three for three — `sha256` vs `sha`, and this:
+   * **a result type that omits what the next call needs turns the obvious
+   * call into a silent 404.** The fix is never a better error message.
+   */
+  mime: string;
+  /**
+   * The extension the server actually stored the original under, when it said
+   * so. Authoritative — it beats any client-side MIME table, because the
+   * server keys the object off the uploaded filename for the cases no table
+   * can close (`.mpga`, `.docx`, `.m4a` all arrive as octet-stream).
+   */
+  oext?: string | null;
   cdnUrl: string;
 };
 
@@ -1656,7 +1682,15 @@ export class NitidaClient {
         assetId: existing.id,
         sha256: sha,
         sha: sha.slice(0, 16),
-        cdnUrl: this.urlFor(existing, this.bestPresetForAsset(existing, mime)),
+        mime: existing.mime ?? mime,
+        oext: existing.oext ?? null,
+        // 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),
+        ),
       };
     }
 
@@ -1678,11 +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),
-        cdnUrl: this.urlFor(presign.asset, this.defaultPresetForMime(mime)),
+        sha: short,
+        mime: presign.asset.mime ?? mime,
+        oext: presign.asset.oext ?? null,
+        // ⭐ `{ ...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),
+        ),
       };
     }
 
@@ -1733,6 +1794,8 @@ export class NitidaClient {
       assetId,
       sha256: sha,
       sha: sha.slice(0, 16),
+      mime: final.mime ?? mime,
+      oext: final.oext ?? null,
       cdnUrl: this.urlFor(final, this.bestPresetForAsset(final, mime)),
     };
   }