@nitida/sdk 0.30.1 → 0.31.0

package/README.md

@@ -661,7 +661,13 @@ with `aq.assets.regenerate()` (no re-upload required).
 // Default: only the original variant lands on the CDN.
 const { assetId, cdnUrl } = await aq.upload(logoFile);
 // asset.presets === "o"
-// cdnUrl = https://8ok.uk/<sha>-o.svg
+// cdnUrl = https://8ok.uk/<tid b36>/v/<sha>-o.svg   ← the tenant segment is not optional
+
+// Processing is asynchronous. `upload()` returns as soon as the bytes are
+// accepted; the variants are not on the CDN yet. Wait for them:
+const ready = await aq.assets.waitReady(assetId, 90_000); // MILLISECONDS
+// ready.presets is the compact string ("o", "lmoqs", …), ALPHABETICALLY
+// sorted — not in the order you asked for.
 ```
 
 **Responsive ladder (the old default — now explicit):**
@@ -1307,12 +1313,25 @@ server-side pipeline (a platform-wide addition, not a per-tenant one).
 
 ### CDN URL format
 
-`<cdnBase>/<sha16>-<presetCode>.<ext>`
+`<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`).
+
+⚠️ **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
+shape — it is not a legacy path, it is a 404. Call `setTenantId(id)` once at
+boot (or construct a `NitidaClient` with `tenantId`, which does it for you);
+without it the builders **throw** rather than hand you a URL that cannot work.
+
+Within one tenant the path is content-addressed: the same source bytes always
+produce the same URL, and that URL never invalidates.
 
-Example: `https://8ok.uk/c482458e824c730e-q.webp` (the `thumb` preset of
-sha `c482458e…` rendered as WebP). The path is content-addressed, so the
-same source bytes produce the same URL regardless of which tenant uploaded
-them — and the same URL never invalidates.
+> Before `@nitida/asset-client@0.20.0` this section documented the bare
+> `<cdnBase>/<sha16>-<preset>.<ext>` form, with an example that 404s, and said
+> the URL was the same "regardless of which tenant uploaded them". That stopped
+> being true at the tenant-prefix cutover. If you copied a URL from an older
+> README, add the `<tid b36>/v/` segment.
 
 ## Auth
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@nitida/sdk",
-  "version": "0.30.1",
+  "version": "0.31.0",
   "description": "nitida — the media SDK: browser and mobile upload with resume, client-side compression, on-the-fly transforms behind a CDN, video transcode, HLS ladders and AI proxies. Multi-tenant.",
   "private": false,
   "publishConfig": {
@@ -73,7 +73,7 @@
   },
   "peerDependencies": {
     "react": ">=18",
-    "@nitida/asset-client": "^0.19.1",
+    "@nitida/asset-client": "^0.20.0",
     "@nitida/asset-compressor-web": "^0.6.1",
     "@nitida/asset-compressor-native": "^0.2.1"
   },

package/skills/nitida-sdk/SKILL.md

@@ -60,7 +60,7 @@ import { setCdnBase, setTenantId } from "@nitida/asset-client";
 const TENANT_ID = Number(process.env.NEXT_PUBLIC_NITIDA_TENANT_ID) || /* your id */ 0;
 
 setCdnBase("https://8ok.uk"); // OPTIONAL — this is already the default; set it only if you were given another host
-setTenantId(TENANT_ID);       // REQUIRED for video URLs (base36 variant prefix) — see §3
+setTenantId(TENANT_ID);       // REQUIRED for EVERY variant URL — images too (base36 prefix), see §3
 ```
 
 `NEXT_PUBLIC_*` so the tenant id reaches the client bundle (hero/about videos render client-side). The runtime read-only consumer needs only these public vars — the `amk_rt_*` runtime key is for **uploads** (server-only), not for building URLs.
@@ -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.
@@ -508,7 +517,7 @@ That replaces the older hand-run provisioning scripts and SQL that used to live
 | Poster | `getAssetUrl({sha}, 'poster')` | `/<tid b36>/v/<sha>-p.webp` |
 | Sha from URL | `extractAssetSha(url)` | — |
 
-Variant preset short codes: `thumb=q, sm=s, md=m, lg=l, xl=x, original=o, poster=p, video=v`. Exts: images `webp`, video `mp4`.
+Variant preset short codes — **all of them**: `thumb=q, sm=s, md=m, lg=l, xl=x, original=o, poster=p, video=v, aiproxy=a, hls=h, mp3=mp3`. ⚠️ `mp3` is the one irregular case: three characters, not one. Exts: images `webp`, video `mp4`.
 
 
 ## Private assets — `visibility`