@nitida/sdk 0.25.3 → 0.27.0

package/AGENTS.md

@@ -24,6 +24,40 @@ import { getTransformUrl, setCdnBase, setTenantId } from "@nitida/asset-client";
 - **Video URLs** → `getAssetUrl({ sha }, "video")` after `setTenantId(id)`. The path segment is
   **base36** (`tenant 12 → /c/v/…`); a decimal prefix 404s.
 
+## Which entry point exports what — read this before your first import
+
+**`@nitida/sdk`, `@nitida/sdk/server` and `@nitida/sdk/web` all carry the same
+surface.** Pick the one that matches your runtime and import everything from it:
+
+```ts
+import { NitidaClient, getTransformUrl, getHlsLadder } from "@nitida/sdk/server";
+```
+
+The other three subpaths are **additive** — they carry only their own
+runtime-specific symbols and you import a complete one alongside:
+
+| subpath | carries | |
+|---|---|---|
+| `/react` | `NitidaProvider`, `useSlot`, `useSlots`, `useNitidaClient` | + `/web` or `/server` |
+| `/native` | `compressImage`, `compressImages` for React Native | + `/web` |
+| `/expo` | `createExpoUploader`, `listResumableSessions`, `cancelResumableSession` | + `/web` |
+
+⚠️ **React Native needs two imports.** `/web` for the client and every URL
+builder — it has no top-level browser imports, its compressor is a dynamic
+`import()` — plus `/native` and/or `/expo`. `/native` on its own gives you a
+compressor and no way to build a URL.
+
+The single deliberate omission: **`NitidaClientOptions` is not on `/web`**, because
+it carries `apiKey` and this subpath exists so that shape is unreachable from
+browser code. Use `WebClientOptions`.
+
+⚠️ **This was not true before 2026-08-21.** `/server` was short **28** of the
+root's 72 exports and `/web` short **37** — the whole palette family, every slot
+helper, the HLS ladder helpers, the preset constants, and on `/web` even
+`setTenantId`. Importing `getHlsLadder` from `/server` failed at **runtime**, not
+at compile time. It is now asserted in CI, so if you are reading an older
+version of this file, verify against the `.d.ts` you actually installed.
+
 ## The four things that bite hardest
 
 1. **`presets` decides what exists forever.** Omit it and you get `original` only. Ask for
@@ -40,6 +74,68 @@ import { getTransformUrl, setCdnBase, setTenantId } from "@nitida/asset-client";
    ASYNCHRONOUSLY: the call answers `{ assetId, status: "processing" }` and a background job flips
    it to `ready` 1–2 min later, so `processAndWait` needs a `timeoutMs` of at least `300_000`.
 
+
+## Private assets — `visibility`
+
+Default is `"public"`. Set `private` and **every public door answers 404** —
+stored variants, the raw original, the HLS ladder, and `/t/` (including the
+poster frame of a private video). The bytes come back only through a signed URL
+that expires.
+
+```ts
+import { getPrivateAssetUrl, getPrivateTransformUrl } from "@nitida/sdk";
+// ON YOUR BACKEND, once you decided this viewer may see it:
+await getPrivateAssetUrl(asset, "lg", signingKey, { expiresInSeconds: 300 });
+await getPrivateTransformUrl(asset, { width: 1280 }, signingKey, { expiresInSeconds: 300 });
+```
+
+- **A 404 on a private asset is NOT a missing file.** Check `visibility` on the
+  DTO before you check storage. It is the number-one support question.
+- **Seven URL builders throw** rather than hand you a doomed URL — `getAssetUrl`,
+  `getAssetSrcSet`, `getTransformUrl`, `getTransformSrcSet`,
+  `getVideoTransformUrl`, `getHlsStreamingUrl`, `getSignedTransformUrl` — but
+  only when the value you pass carries `visibility`. `{ sha }` alone is never
+  refused.
+- **`exp` is mandatory**; revocation is *"within a minute"* (60 s TTL at the edge).
+- **The signing key is a backend secret** — it mints URLs for every private
+  asset the tenant owns.
+
+## Two ways an image gets smaller, and only one of them is yours to call
+
+This is the question every programmatic caller gets wrong, so it is stated flat:
+
+| | who does it | what it shrinks |
+|---|---|---|
+| **Client compressor** (browser / Expo) | the UI, before the PUT | the **upload**: quality 0.85, max 2880 px, WebP. iPhone 9.1 MB → 1.8 MB |
+| **Variants + `/t/`** | the backend, on request | the **delivery**: 19 MB JPEG → 170 kB WebP at 1920 |
+
+**The backend never recompresses the raw. Ever.** That is deliberate: the raw
+has to stay pristine so variants are *regenerable* — the day you add AVIF or
+raise the max dimension, the pipeline re-runs against it. A client→server lossy
+chain bakes artifacts in forever.
+
+So for an API/agent upload there is nothing to "turn on": you were never going
+to compress the raw, and delivery is already optimised two ways.
+
+```ts
+// Ask for the rungs you will actually render…
+await aq.upload(file, { presets: ["original", "thumb", "md", "lg"] });
+
+// …or upload bare and let the transform route make them on demand:
+aq.transform(asset, { width: 1280, format: "webp" });   // → /t/…, cached after the first hit
+```
+
+**`presets` defaults to `["original"]`** — a bare upload stores the raw and no
+rendition. Since 2026-08-22 that is no longer a trap: when the DTO says a preset
+was never materialised, `getAssetUrl` / `urlFor` **fall back to `/t/`** instead
+of returning a URL that 404s. You still get optimised bytes; you just pay the
+first encode. Prefer naming the presets when you know what you will render.
+
+⚠️ `getAssetSrcSet` deliberately does **not** fall back — a srcSet promises
+pixel widths and a transform cannot keep that promise on a source smaller than
+the rung, because the pipeline never enlarges. An empty srcSet degrades to `src`; a lying one
+degrades to a wrong choice.
+
 ## Related packages
 
 | Package | Job |

package/README.md

@@ -15,14 +15,45 @@ SDK**. Stripe/Cloudinary's split into two separate npm packages is the legacy
 shape — modern bundlers tree-shake subpaths perfectly and a single version
 eliminates type drift between server and client surfaces.
 
-| Where you run | Import | What it bundles |
+### Two kinds of subpath, and the difference matters
+
+**COMPLETE entry points** carry the whole surface. Import one and you are done.
+
+| Where you run | Import | |
+|---|---|---|
+| Node 20+, Bun, Cloud Run, Lambda, Edge, agents, cron | **`@nitida/sdk/server`** | `NitidaClient` + **every** export of the root. **No browser-only code.** |
+| Browser, and React Native | **`@nitida/sdk/web`** | everything in `/server`, plus `compressImage` (HEIC→WebP). The one deliberate omission is `NitidaClientOptions`, the options type that carries `apiKey` — use `WebClientOptions`. |
+| Anywhere (the root) | `@nitida/sdk` | the full surface, runtime-agnostic. Prefer an explicit subpath in new code. |
+
+**ADDITIVE modules** are layered *on top* of one of the above. They carry only
+their own runtime-specific symbols — **you import a complete entry point as
+well**:
+
+| For | Import | Carries |
 |---|---|---|
-| Node 20+, Bun, Cloud Run, Lambda, Edge, agents, cron | **`@nitida/sdk/server`** | `NitidaClient` + URL builders + `signTransformUrl`. **No browser-only code.** Hard guarantee against shipping `Blob`-workflow helpers to the wrong runtime. |
-| Browser (Next.js client, Vite, CRA, web workers) | **`@nitida/sdk/web`** | `NitidaClient` + everything in `/server` + `compressImage` (HEIC→WebP, compressorjs). Multipart is not exposed — see *Large uploads (web)*. |
-| React Native / Expo apps | `@nitida/sdk/native` | `compressImage` for RN (libjpeg-turbo via `react-native-compressor`). Pair with `/expo`. |
-| Expo background uploads | `@nitida/sdk/expo` | `createExpoUploader` — native `URLSession` (iOS) / `WorkManager` (Android) sessions that survive app backgrounding. |
-| Next.js / React (hooks) | `@nitida/sdk/react` | `NitidaProvider` + `useSlot` / `useSlots` / `useNitidaClient`. |
-| Backwards-compat (root) | `@nitida/sdk` | Same shape as today; equivalent to `/web` for the public symbols. **Prefer the explicit subpath in new code.** |
+| React hooks | `@nitida/sdk/react` | `NitidaProvider`, `useSlot`, `useSlots`, `useNitidaClient` — and nothing else |
+| RN image compression | `@nitida/sdk/native` | `compressImage` / `compressImages` for RN (`react-native-compressor`) |
+| Expo background uploads | `@nitida/sdk/expo` | `createExpoUploader` — `URLSession` / `WorkManager` sessions that survive backgrounding. ⚠️ **Needs a runtime key on the device** — see below |
+
+⚠️ **`/expo` is the one place a runtime key lives on the device.**
+`createExpoUploader` takes `apiKey` off the client and gives it to the native
+session as its `authToken`, because the OS replays that upload from a background
+task hours later and there is no BFF in that loop. It is the opposite call from
+`@nitida/sdk/web`, which hit the same constraint and chose *not* to expose its
+multipart uploader at all. An `amk_rt_*` in an IPA/APK is readable by anyone who
+unzips it, and it is a write key to a paid platform. If background survival is
+not worth that, build the client from `/web` against your own route and use
+`aq.upload(file)` — no key on the device, and the upload dies with the JS thread.
+
+⚠️ **React Native needs two imports**, and this table used to imply otherwise:
+`@nitida/sdk/web` for the client and every URL builder — it has no top-level
+browser imports, the compressor behind it is a dynamic `import()` — **plus**
+`/native` and/or `/expo` for the native pieces. `/native` alone gives you a
+compressor and no way to build a URL.
+
+That `/server` and `/web` really do mirror the root is **asserted in CI**, not
+maintained by hand. It was not always true: before 2026-08-21 `/server` was
+short 28 of the root's 72 exports and `/web` short 37.
 
 Uploaders + compressors are **optional** peer deps (`@aquienpz/asset-uploader-{web,expo}`,
 `@nitida/asset-compressor-{web,native}`). Skip them if your app only resolves
@@ -32,8 +63,9 @@ slots and reads assets — your bundle stays a few KB.
 
 - Server-side rendering, API routes, BFF, cron, agents → `@nitida/sdk/server`.
 - Browser components, build-time pre-resolution → `@nitida/sdk/web`.
-- Expo / React Native app → `@nitida/sdk/native` + `@nitida/sdk/expo`.
-- React hooks (any env) → `@nitida/sdk/react`.
+- Expo / React Native app → `@nitida/sdk/web` (the client and the URL builders)
+  **plus** `@nitida/sdk/native` and/or `@nitida/sdk/expo` for the native pieces.
+- React hooks (any env) → `@nitida/sdk/react` **plus** `/web` or `/server`.
 
 **Never ship the API key to the browser.** Whichever subpath you import,
 the long-lived `amk_rt_*` key lives on the server. Browser flows hit a BFF
@@ -45,8 +77,44 @@ route that proxies to aquienpz with the real key.
 |---|---|---|
 | Browser (Next.js client component, SPA, Worker, web extension) | `@nitida/sdk/web` | **No `apiKey`** — your BFF injects it. Type omits the field; build error if you try. |
 | Node/Bun server (API route, Server Action, Cloud Run, Fly, BFF) | `@nitida/sdk/server` | Requires `apiKey` at construction. |
-| React Native / Expo | `@nitida/sdk/native` or `@nitida/sdk/expo` | Same BFF model as `/web` — keep keys server-side. |
-| Universal React hook | `@nitida/sdk/react` | Wraps the right subpath for the runtime. |
+| React Native / Expo | `@nitida/sdk/web` **plus** `/native` and/or `/expo` | Same BFF model as `/web` — keep keys server-side. `/native` and `/expo` are additive; on their own they carry no client. |
+| Universal React hook | `@nitida/sdk/react` **plus** `/web` or `/server` | The hooks read a client from context; something has to construct it. |
+
+### …and where does each HELPER live?
+
+The table above answers *"where do I get the client"*. It did **not** used to
+answer *"where do I get `getHlsLadder`"*, and that is the question that cost the
+most time — an agent evaluating this SDK followed `AGENTS.md` to `/server`,
+imported `getHlsLadder` from there, and got a `SyntaxError` at runtime.
+
+**Now there is a one-line answer, and CI keeps it true:**
+
+> **`@nitida/sdk`, `/server` and `/web` all carry the same surface.**
+> Import any helper from whichever of the three you already use.
+
+| what you want | `@nitida/asset-client` | `@nitida/sdk` · `/server` · `/web` | elsewhere |
+|---|---|---|---|
+| URL builders — `getAssetUrl`, `getTransformUrl`, `getVideoTransformUrl`, `getAssetSrcSet`, `getTransformSrcSet`, `getHlsStreamingUrl`, `serializeTransform` | ✅ | ✅ | |
+| Signing — `signTransformUrl`, `getSignedTransformUrl` | ✅ | ✅ | |
+| Asset facts — `hasPreset`, `extractAssetSha`, `getAssetDimensions`, `computeVariantDimensions` | ✅ | ✅ | |
+| HLS — `getHlsLadder`, `hlsLadderAlignment`, `HlsRung` | ✅ | ✅ | |
+| Palette — `pickAmbientBackground`, `iteratePaletteSwatches`, `bestTextContrast`, `getAmbientGradient`, `getPaletteCssVars`, `getPaletteBlurBackground`, `getTextColorForBackground`, `contrastRatio`, `relativeLuminance` | ✅ | ✅ | |
+| Slots — `resolveSlot`, `resolveSlots`, `configureSlotResolver`, `invalidateSlotCache` | ✅ | ✅ | |
+| Constants — `TRANSFORM_WIDTHS`, `TransformWidth`, `PRESET_EXT`, `PRESET_LONG`, `PRESET_SHORT`, `PRESET_MAX_DIM` | ✅ | ✅ | |
+| Config — `setCdnBase`/`getCdnBase`, `setTenantId`/`getTenantId` | ✅ | ✅ | |
+| `NitidaClient` and its option/result types | | ✅ | |
+| Client-side compression — `compressImage`, `compressImages` | | `/web` only | `/native` (React Native) |
+| React hooks — `NitidaProvider`, `useNitidaClient`, `useSlot`, `useSlots` | | | `/react` only |
+| Expo resumable upload — `createExpoUploader`, `listResumableSessions`, `cancelResumableSession` | | | `/expo` only |
+
+The single deliberate exception: **`NitidaClientOptions` is not on `/web`.** That
+is the options type that carries `apiKey`, and this subpath exists so the
+apiKey-bearing shape is unreachable from browser code — use `WebClientOptions`.
+
+This is not maintained by hand. `scripts/check-published-doc-symbols.ts` asserts
+that `/server` and `/web` mirror the root, and that the one denial above still
+has a written reason. Before 2026-08-21 it was not true: `/server` was short
+**28** of the root's 72 and `/web` short **37**, `getHlsLadder` among them.
 
 ### Why subpaths, not a runtime flag
 
@@ -543,6 +611,39 @@ The preset is a **ceiling**, not a target.
 | `video`   | `v`  | original MP4           |
 | `aiproxy` | `a`  | low-res proxy for AI captioning / search (opt-in) |
 
+### ⚠️ What you can ASK FOR is not what a variant can BE
+
+Two different sets, two different types, and confusing them is the most
+expensive type error this package has shipped — three unknown agents evaluating
+the SDK hit it independently in one afternoon.
+
+```ts
+aq.assets.regenerate(id, { presets: ["hls"] });   // ← used to compile. HTTP 400.
+aq.upload(file,          { presets: ["mp3"] });   // ← used to compile. HTTP 400.
+```
+
+Both symbols are real. Neither is orderable.
+
+| | `RequestablePreset` — you may ask | `VariantPreset` — a variant may be |
+|---|---|---|
+| `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 | ❌ | ✅ |
+| `probe` — indexed stills (`-pr0.jpg`), never on the compact `presets` string | ✅ | ❌ |
+
+The write methods (`upload`, `presignUploadUrl`, `regenerate`) take
+`RequestablePreset[]`, so all three lines above are now **compile errors**. The
+read helpers (`hasPreset`, `variants[].preset`, `PRESET_SHORT`) keep
+`VariantPreset`, because `hls` and `mp3` genuinely do exist on assets.
+
+`probe` was the same bug mirrored: the server has always accepted it and the
+type forbade it. It is requestable now.
+
+This is checked in CI against the server itself —
+`scripts/check-preset-contract.ts` reads the Elysia schemas of all four write
+routes and asserts `RequestablePreset` still equals what they accept, so it
+cannot go stale the way a hand-written list would.
+
 ### Per-upload preset selection
 
 **The SDK's default is `["original"]`** — calling `aq.upload(file)`
@@ -679,7 +780,23 @@ returned shape gives you `{ preset, url, width?, height?, bytes }[]`.
 
 Pre-generated presets (`thumb`/`sm`/`md`/`lg`/`xl`) cover the common cases.
 For everything else — exact CSS pixel widths, art-directed crops, devicePixelRatio
-ladders, square thumbs from rectangular sources — call `aq.transform()`:
+ladders, square thumbs from rectangular sources — build a `/t/` URL.
+
+### `aq.transform()` or `getTransformUrl()`? Both, and the rule is which you have
+
+Two agents evaluating this SDK picked different ones for the same task and both
+were right, which is a documentation failure rather than a design one. They are
+**not duplicates**: `aq.transform()` is `getTransformUrl()` plus the client's
+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 |
+| 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
+method — reaching for the standalone one there means passing the tenant twice
+and losing signing.
 
 ```tsx
 import { NitidaClient } from "@nitida/sdk";
@@ -715,8 +832,9 @@ const asset = await aq.assets.byHash(sha256);
 | `dpr` | `1` / `2` / `3` | `1` |
 
 > **`width` is strongly typed.** `TransformOptions.width` is a **`TransformWidth`** — the
-> predefined CDN ladder (`160, 240, 256, 320, 400, 480, 600, 640, 800, 960, 1080, 1200,
-> 1280, 1440, 1600, 1920, 2560, 3840`, exported as `TRANSFORM_WIDTHS`). An off-ladder
+> 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** —
 > `aq.transform(asset, { width: 1490 }, { sign: true })` and `getSignedTransformUrl` take
@@ -809,16 +927,92 @@ hex-encoded. The server canonicalizes the URL the same way the SDK does
 (sort keys, lowercase strings), so two URLs with the same params in
 different order accept the same signature.
 
-**Admin operations** (system-scope admin key):
+## Private assets — `visibility`
+
+Every asset carries `visibility`, and the default is `"public"`.
+
+| | `"public"` | `"private"` |
+|---|---|---|
+| stored variants, raw, HLS ladder, transforms | served to anyone with the URL | **404**, to everyone |
+| how the bytes come back | the URL | a signed URL under `/a/{tenant}/…?exp&sig` |
+| expiry | none | mandatory |
+| edge caching | shared, effectively free | `private`, per-viewer |
+
+```ts
+// Flip it (write scope):
+await fetch(`${endpoint}/assets/${assetId}/visibility`, {
+  method: "PATCH",
+  headers: { Authorization: `Bearer ${apiKey}`, "X-Tenant-Code": code,
+             "Content-Type": "application/json" },
+  body: JSON.stringify({ visibility: "private" }),
+});
+
+// Hand a viewer the bytes — ON YOUR BACKEND:
+import { getPrivateAssetUrl, getPrivateTransformUrl } from "@nitida/sdk";
+
+const url = await getPrivateAssetUrl(asset, "lg", signingKey, {
+  expiresInSeconds: 300,
+});
+// → https://8ok.uk/a/5/v/<sha>-l.webp?exp=…&sig=…
+
+// …or any width/crop/format, not just the materialised ones:
+const resized = await getPrivateTransformUrl(
+  asset,
+  { width: 1280, format: "webp" },
+  signingKey,
+  { expiresInSeconds: 300 },
+);
+// → https://8ok.uk/a/5/t/format=webp,width=1280/<sha>.webp?exp=…&sig=…
+```
+
+Nothing moves when you flip it: one row changes and the edge cache for that
+asset is purged, so a 1 GB video flips as fast as a thumbnail. It is the same
+single copy behind both doors.
+
+**Four things worth knowing before you rely on it:**
+
+1. **A 404 on a private asset is the feature, not a missing file.** Everywhere
+   else here a 404 means the object was never written. Check `visibility` on
+   the DTO before you check storage.
+2. **The SDK refuses instead of handing you a URL that 404s.** `getAssetUrl`,
+   `getAssetSrcSet`, `getTransformUrl`, `getTransformSrcSet`,
+   `getVideoTransformUrl` and `getHlsStreamingUrl` all throw when the value you
+   pass says `visibility: "private"` — with a message naming
+   `getPrivateAssetUrl`. Pass only `{ sha }` and there is nothing to check.
+3. **Revocation is "within a minute".** Flipping back to `private` really does
+   kill URLs already handed out — the edge is purged — but the CDN refreshes
+   its list of private assets on a 60-second TTL.
+4. **The signing key is a backend secret.** It mints URLs for every private
+   asset the tenant owns. It is a different claim from the transform `?sig=`
+   above, computed under a separately derived key, so a signature minted to
+   resize can never be replayed as one to enter.
+
+### ⚠️ Admin operations need the SYSTEM key, not the admin key in your triplet
+
+Both are `amk_ad_*`, and that is the whole trap. The `admin` key issued with
+your tenant is **tenant-scoped**: it manages your assets and cannot touch
+`/admin/projects/*`. Verified 2026-08-21:
+
+```
+tenant admin key  → GET /admin/projects → 403 SYSTEM_KEY_REQUIRED
+                    "API key … is tenant-scoped; this endpoint requires a
+                     system-scope key"
+system admin key  → GET /admin/projects → 200
+```
+
+There is exactly one system-scope key and we hold it. **These calls are ours to
+run, not yours** — ask, and we run them. They are documented here so you know
+what exists and can name what you want done, not so you can copy the `amk_ad_`
+out of your own triplet and get a 403 that reads like a broken credential.
 
 ```bash
 # Rotate the signing key — invalidates every URL signed with the old one.
-curl -X POST -H "Authorization: Bearer amk_ad_..." \
+curl -X POST -H "Authorization: Bearer <SYSTEM amk_ad_...>" \
   https://api.nitida.gofuture.space/admin/projects/your-tenant/rotate-signing-key
 # → { ok: true, tenantId, code, signingKey: "<64-hex>" }
 
 # Flip strict mode on/off.
-curl -X PATCH -H "Authorization: Bearer amk_ad_..." -H "Content-Type: application/json" \
+curl -X PATCH -H "Authorization: Bearer <SYSTEM amk_ad_...>" -H "Content-Type: application/json" \
   -d '{"enabled":true}' \
   https://api.nitida.gofuture.space/admin/projects/your-tenant/strict-transforms
 ```

package/dist/expo.d.ts

@@ -31,6 +31,33 @@ import '@nitida/asset-client';
  *   const { assetId } = await upload.start();
  *   await aq.slots.bind("storefront.tour.video", { assetId, preset: "video" });
  *
+ * ⚠️ THIS PATH PUTS A RUNTIME KEY ON THE DEVICE. Read before shipping.
+ *
+ * `createExpoUploader` reads `client.opts.apiKey` and hands it to the native
+ * session as its `authToken` (see below — it is four lines, and they are the
+ * whole story). The native uploader talks to the API directly, so it needs a
+ * credential the OS can replay hours later from a background task. There is no
+ * BFF in that loop to inject one.
+ *
+ * That is the opposite of what every other surface here does, and the opposite
+ * of what `@nitida/sdk/web` chose when it hit the SAME constraint: `/web`
+ * deliberately does NOT expose the multipart uploader, because it needs a raw
+ * `authToken` a BFF cannot supply. `/expo` exposes it anyway, because
+ * background-surviving uploads are the entire reason a native session exists.
+ *
+ * So, concretely, an `amk_rt_*` key in your app bundle is readable by anyone
+ * who unzips the IPA/APK, and it is a WRITE key to a paid platform.
+ *
+ *   - Uploading big video in the background is worth it to you ⇒ use this, and
+ *     scope the key to one tenant so a leak is contained and revocable.
+ *   - It is not ⇒ build the client from `@nitida/sdk/web` pointed at your own
+ *     route and call `aq.upload(file)`. No key on the device. You lose survival
+ *     across backgrounding and OS kill; the upload dies with the JS thread.
+ *
+ * The real fix — a BFF-minted short-lived token the native session can carry —
+ * is not built. It is the same gap `/web` documents. Ask; there is no public
+ * tracker.
+ *
  * Peer dep: `@aquienpz/asset-uploader-expo` (lazy — apps that don't
  * use the mobile SDK skip the install).
  * @module @nitida/sdk/expo
@@ -39,9 +66,11 @@ import '@nitida/asset-client';
 type ExpoUploadOptions = Omit<UploadTaskOptions, "tenantCode" | "endpoint" | "authToken">;
 /**
  * Spawn a native-backed `UploadTask` bound to a configured client.
- * Inherits the client's endpoint / api key / tenant scope; caller only
- * has to supply the file input + any per-upload tuning (partSize,
- * concurrency).
+ *
+ * ⚠️ It reaches into the client for `apiKey` and uses it as the session's
+ * `authToken`, so the client you pass MUST have been built with a real runtime
+ * key — which means that key is on the device. See the module header for what
+ * that costs and what the alternative is.
  */
 declare function createExpoUploader(client: NitidaClient, options: ExpoUploadOptions): UploadTask;
 

package/dist/expo.js.map

@@ -1 +1 @@
-{"version":3,"sources":["../src/expo/index.ts"],"sourcesContent":["/**\n * @nitida/sdk/expo — native multipart uploads for React Native / Expo.\n *\n * Wraps `@aquienpz/asset-uploader-expo`'s `UploadTask`, which delegates\n * the actual byte transfer to a native background session (URLSession\n * on iOS, WorkManager on Android). The upload survives:\n *   - JS thread freezing\n *   - App backgrounding\n *   - OS-initiated kill (low-memory, user swiping away)\n *   - Network blips (retries with backoff)\n *\n * Usage:\n *\n *   import { createExpoUploader, listResumableSessions } from \"@nitida/sdk/expo\";\n *\n *   const aq = new NitidaClient({ ... });\n *\n *   // Resume any uploads from a prior app launch on boot.\n *   const resumable = await listResumableSessions();\n *   // ...show a banner offering to resume them\n *\n *   const upload = createExpoUploader(aq, {\n *     file: { uri: assetUri, mime: \"video/mp4\", name: \"tour.mp4\" },\n *   });\n *   upload.on(\"progress\", ({ ratio }) => setProgress(ratio));\n *   const { assetId } = await upload.start();\n *   await aq.slots.bind(\"storefront.tour.video\", { assetId, preset: \"video\" });\n *\n * Peer dep: `@aquienpz/asset-uploader-expo` (lazy — apps that don't\n * use the mobile SDK skip the install).\n * @module @nitida/sdk/expo\n */\n\nimport {\n  UploadTask,\n  type UploadTaskOptions,\n} from \"@aquienpz/asset-uploader-expo\";\nimport type { NitidaClient } from \"..\";\n\nexport type ExpoUploadOptions = Omit<\n  UploadTaskOptions,\n  \"tenantCode\" | \"endpoint\" | \"authToken\"\n>;\n\n/**\n * Spawn a native-backed `UploadTask` bound to a configured client.\n * Inherits the client's endpoint / api key / tenant scope; caller only\n * has to supply the file input + any per-upload tuning (partSize,\n * concurrency).\n */\nexport function createExpoUploader(\n  client: NitidaClient,\n  options: ExpoUploadOptions,\n): UploadTask {\n  const access = client as unknown as {\n    opts: { endpoint: string; apiKey: string; tenantCode: string };\n  };\n  return new UploadTask({\n    ...options,\n    endpoint: access.opts.endpoint,\n    authToken: access.opts.apiKey,\n    tenantCode: access.opts.tenantCode,\n  });\n}\n\nexport type {\n  UploadEvents,\n  UploadFileInput,\n  UploadSessionState,\n  UploadTaskOptions,\n} from \"@aquienpz/asset-uploader-expo\";\nexport {\n  cancelResumableSession,\n  listResumableSessions,\n  UploadTask,\n} from \"@aquienpz/asset-uploader-expo\";\n"],"mappings":";AAiCA;AAAA,EACE;AAAA,OAEK;AAmCP;AAAA,EACE;AAAA,EACA;AAAA,EACA,cAAAA;AAAA,OACK;AAzBA,SAAS,mBACd,QACA,SACY;AACZ,QAAM,SAAS;AAGf,SAAO,IAAI,WAAW;AAAA,IACpB,GAAG;AAAA,IACH,UAAU,OAAO,KAAK;AAAA,IACtB,WAAW,OAAO,KAAK;AAAA,IACvB,YAAY,OAAO,KAAK;AAAA,EAC1B,CAAC;AACH;","names":["UploadTask"]}
+{"version":3,"sources":["../src/expo/index.ts"],"sourcesContent":["/**\n * @nitida/sdk/expo — native multipart uploads for React Native / Expo.\n *\n * Wraps `@aquienpz/asset-uploader-expo`'s `UploadTask`, which delegates\n * the actual byte transfer to a native background session (URLSession\n * on iOS, WorkManager on Android). The upload survives:\n *   - JS thread freezing\n *   - App backgrounding\n *   - OS-initiated kill (low-memory, user swiping away)\n *   - Network blips (retries with backoff)\n *\n * Usage:\n *\n *   import { createExpoUploader, listResumableSessions } from \"@nitida/sdk/expo\";\n *\n *   const aq = new NitidaClient({ ... });\n *\n *   // Resume any uploads from a prior app launch on boot.\n *   const resumable = await listResumableSessions();\n *   // ...show a banner offering to resume them\n *\n *   const upload = createExpoUploader(aq, {\n *     file: { uri: assetUri, mime: \"video/mp4\", name: \"tour.mp4\" },\n *   });\n *   upload.on(\"progress\", ({ ratio }) => setProgress(ratio));\n *   const { assetId } = await upload.start();\n *   await aq.slots.bind(\"storefront.tour.video\", { assetId, preset: \"video\" });\n *\n * ⚠️ THIS PATH PUTS A RUNTIME KEY ON THE DEVICE. Read before shipping.\n *\n * `createExpoUploader` reads `client.opts.apiKey` and hands it to the native\n * session as its `authToken` (see below — it is four lines, and they are the\n * whole story). The native uploader talks to the API directly, so it needs a\n * credential the OS can replay hours later from a background task. There is no\n * BFF in that loop to inject one.\n *\n * That is the opposite of what every other surface here does, and the opposite\n * of what `@nitida/sdk/web` chose when it hit the SAME constraint: `/web`\n * deliberately does NOT expose the multipart uploader, because it needs a raw\n * `authToken` a BFF cannot supply. `/expo` exposes it anyway, because\n * background-surviving uploads are the entire reason a native session exists.\n *\n * So, concretely, an `amk_rt_*` key in your app bundle is readable by anyone\n * who unzips the IPA/APK, and it is a WRITE key to a paid platform.\n *\n *   - Uploading big video in the background is worth it to you ⇒ use this, and\n *     scope the key to one tenant so a leak is contained and revocable.\n *   - It is not ⇒ build the client from `@nitida/sdk/web` pointed at your own\n *     route and call `aq.upload(file)`. No key on the device. You lose survival\n *     across backgrounding and OS kill; the upload dies with the JS thread.\n *\n * The real fix — a BFF-minted short-lived token the native session can carry —\n * is not built. It is the same gap `/web` documents. Ask; there is no public\n * tracker.\n *\n * Peer dep: `@aquienpz/asset-uploader-expo` (lazy — apps that don't\n * use the mobile SDK skip the install).\n * @module @nitida/sdk/expo\n */\n\nimport {\n  UploadTask,\n  type UploadTaskOptions,\n} from \"@aquienpz/asset-uploader-expo\";\nimport type { NitidaClient } from \"..\";\n\nexport type ExpoUploadOptions = Omit<\n  UploadTaskOptions,\n  \"tenantCode\" | \"endpoint\" | \"authToken\"\n>;\n\n/**\n * Spawn a native-backed `UploadTask` bound to a configured client.\n *\n * ⚠️ It reaches into the client for `apiKey` and uses it as the session's\n * `authToken`, so the client you pass MUST have been built with a real runtime\n * key — which means that key is on the device. See the module header for what\n * that costs and what the alternative is.\n */\nexport function createExpoUploader(\n  client: NitidaClient,\n  options: ExpoUploadOptions,\n): UploadTask {\n  const access = client as unknown as {\n    opts: { endpoint: string; apiKey: string; tenantCode: string };\n  };\n  return new UploadTask({\n    ...options,\n    endpoint: access.opts.endpoint,\n    authToken: access.opts.apiKey,\n    tenantCode: access.opts.tenantCode,\n  });\n}\n\nexport type {\n  UploadEvents,\n  UploadFileInput,\n  UploadSessionState,\n  UploadTaskOptions,\n} from \"@aquienpz/asset-uploader-expo\";\nexport {\n  cancelResumableSession,\n  listResumableSessions,\n  UploadTask,\n} from \"@aquienpz/asset-uploader-expo\";\n"],"mappings":";AA4DA;AAAA,EACE;AAAA,OAEK;AAqCP;AAAA,EACE;AAAA,EACA;AAAA,EACA,cAAAA;AAAA,OACK;AAzBA,SAAS,mBACd,QACA,SACY;AACZ,QAAM,SAAS;AAGf,SAAO,IAAI,WAAW;AAAA,IACpB,GAAG;AAAA,IACH,UAAU,OAAO,KAAK;AAAA,IACtB,WAAW,OAAO,KAAK;AAAA,IACvB,YAAY,OAAO,KAAK;AAAA,EAC1B,CAAC;AACH;","names":["UploadTask"]}

package/dist/index.d.ts

@@ -1,5 +1,39 @@
-import { ResolveSlotOptions, SlotResolution, SlotDTO, VariantPreset, AssetDTO, AssetVariant, TransformOptions, SignedTransformOptions } from '@nitida/asset-client';
-export { AssetDTO, AssetPalette, AssetVariant, HlsRung, PRESET_EXT, PRESET_LONG, PRESET_MAX_DIM, PRESET_SHORT, PaletteSwatch, ResolveSlotOptions, SignedTransformOptions, SlotDTO, SlotResolution, TRANSFORM_WIDTHS, TransformEffect, TransformFit, TransformFormat, TransformGravity, TransformOptions, TransformWidth, VariantPreset, bestTextContrast, computeVariantDimensions, configureSlotResolver, contrastRatio, extractAssetSha, getAmbientGradient, getAssetDimensions, getAssetSrcSet, getAssetUrl, getCdnBase, getHlsLadder, getHlsStreamingUrl, getPaletteBlurBackground, getPaletteCssVars, getSignedTransformUrl, getTenantId, getTextColorForBackground, getTransformSrcSet, getTransformUrl, getVideoTransformUrl, hasPreset, hlsLadderAlignment, invalidateSlotCache, iteratePaletteSwatches, pickAmbientBackground, relativeLuminance, resolveSlot, resolveSlots, serializeTransform, setCdnBase, setTenantId, signTransformUrl } from '@nitida/asset-client';
+import { ResolveSlotOptions, SlotResolution, SlotDTO, VariantPreset, AssetDTO, AssetVariant, RequestablePreset, TransformOptions, SignedTransformOptions } from '@nitida/asset-client';
+export { AssetDTO, AssetPalette, AssetVariant, HlsRung, PRESET_EXT, PRESET_LONG, PRESET_MAX_DIM, PRESET_SHORT, PaletteSwatch, RequestablePreset, ResolveSlotOptions, SignAccessOptions, SignedTransformOptions, SlotDTO, SlotResolution, TRANSFORM_WIDTHS, TransformEffect, TransformFit, TransformFormat, TransformGravity, TransformOptions, TransformWidth, VariantEntryPreset, VariantPreset, VisibilityHint, accessMessage, assertPublic, bestTextContrast, computeVariantDimensions, configureSlotResolver, contrastRatio, deriveAccessKey, extractAssetSha, getAmbientGradient, getAssetDimensions, getAssetSrcSet, getAssetUrl, getCdnBase, getHlsLadder, getHlsStreamingUrl, getPaletteBlurBackground, getPaletteCssVars, getPrivateAssetUrl, getPrivateTransformUrl, getSignedTransformUrl, getTenantId, getTextColorForBackground, getTransformSrcSet, getTransformUrl, getVideoTransformUrl, hasPreset, hlsLadderAlignment, invalidateSlotCache, iteratePaletteSwatches, pickAmbientBackground, relativeLuminance, resolveSlot, resolveSlots, serializeTransform, setCdnBase, setTenantId, signAccessUrl, signTransformUrl } from '@nitida/asset-client';
+
+/**
+ * Which audio uploads already play everywhere — the single source of truth for
+ * both the server's transcode guard and the client's delivery-preset choice.
+ *
+ * It lives in its own module, rather than beside the preset order that uses it,
+ * for a mechanical reason: `apps/asset-manager` imports it by relative path.
+ * The SDK is a PUBLISHED package, so its `exports` point at `dist/`, and
+ * `dist/` is gitignored — it does not exist inside the Docker image, which
+ * copies `packages/` as source. A bare `@nitida/sdk` import type-checks on any
+ * machine that built the package once and then fails the image build. (It did,
+ * on 2026-08-22, with `@nitida/asset-client`.) A single small file keeps that
+ * relative import from dragging the whole client into the server.
+ *
+ * Two copies of this list drifting apart is how a platform ends up generating
+ * a variant its own client refuses to use — which is exactly the bug this
+ * predicate was introduced to end.
+ */
+/**
+ * `true` when a browser can play these bytes as uploaded, so re-encoding them
+ * to MP3 buys nothing.
+ *
+ * - `audio/mpeg` — unambiguous.
+ * - `audio/mp4` / `audio/aac` — plays in Safari, Chrome, Firefox and Edge on
+ *   desktop and mobile. The historical worry was old AOSP builds without
+ *   proprietary codecs; the call to treat AAC as universal was made with the
+ *   platform's one real AAC consumer, whose viewer is WebGL — a device that
+ *   cannot decode AAC cannot run that product at all, so the fallback would
+ *   only ever protect a device that had already lost.
+ *
+ * Deliberately NOT here: `audio/webm` and `audio/ogg` (Opus). iOS Safari
+ * cannot decode them, and that is the case the MP3 fallback exists for.
+ */
+declare function isUniversallyPlayableAudio(mime: string): boolean;
 
 /**
  * @nitida/sdk — universal client for the aquienpz multi-tenant asset
@@ -86,7 +120,9 @@ type NitidaClientOptions = {
      * only when calling `aq.transform(asset, opts, { sign: true })`.
      *
      * 32 random bytes, generated server-side on tenant creation; fetch
-     * via `GET /admin/tenants/:id` with an admin key. **Keep it
+     * via `POST /admin/projects/:code/rotate-signing-key`, which needs a
+     * SYSTEM-scope credential the platform operator holds — your own admin key
+     * answers `403 SYSTEM_KEY_REQUIRED`. Ask for it. **Keep it
      * server-side only** — do not ship in `NEXT_PUBLIC_*` env vars. Sign
      * URLs from a BFF route handler, or pre-sign at build time.
      */
@@ -235,8 +271,11 @@ type PresignUploadUrlOptions = {
     /**
      * Variant ladder to generate after `/assets/process`. Defaults to
      * `["original"]` server-side when omitted — same contract as `aq.upload`.
+     *
+     * {@link RequestablePreset}, not {@link VariantPreset}: `hls` and `mp3` are
+     * things a variant can BE, never things you can ask for, and asking is a 400.
      */
-    presets?: VariantPreset[];
+    presets?: RequestablePreset[];
     /**
      * Pre-compression size of the source (useful when the browser ran
      * compressorjs / heic2any before computing `bytes`). Recorded
@@ -326,9 +365,10 @@ declare class AssetsApi {
      */
     variants(assetId: string): Promise<AssetVariant[]>;
     /**
-     * Add or rebuild variants on an existing asset. Image presets are
-     * MERGED with what's there — passing `{ presets: ["thumb"] }` adds
-     * the thumb variant without touching `lg`, `sm`, `original`, etc.
+     * Add or rebuild variants on an existing asset. Presets are MERGED
+     * with what's there, for images AND for video — passing
+     * `{ presets: ["thumb"] }` adds the thumb variant without touching
+     * `lg`, `sm`, `original`, etc.
      *
      *   // Day 0: upload original-only logo
      *   const { assetId } = await aq.upload(logoFile);  // defaults to ["original"]
@@ -347,13 +387,21 @@ declare class AssetsApi {
      * reading the source bytes from the permanent `original` variant —
      * no need to re-upload.
      *
-     * Video presets are filtered to `["poster","video","aiproxy"]` and
-     * dispatched to a background job (the call returns immediately
+     * Video presets are filtered to `["poster","video","aiproxy","probe"]`
+     * and dispatched to a background job (the call returns immediately
      * with a dispatch handle; poll `aq.assets.get(id).status` for
      * completion).
+     *
+     * ⚠️ Before 2026-08-22 the video path REPLACED the whole variant
+     * registry instead of merging, so a partial regenerate silently
+     * deregistered `poster`, `video` and — irrecoverably — `hls`, which
+     * is not a {@link RequestablePreset} and therefore cannot be asked
+     * for again. The objects kept serving from the CDN; only the
+     * registry died. Fixed server-side; a client on an older server
+     * still loses them.
      */
     regenerate(assetId: string, opts?: {
-        presets?: VariantPreset[];
+        presets?: RequestablePreset[];
     }): Promise<RegenerateResult>;
     /** Merge metadata into an asset (role / slot / description / tags). */
     patchMetadata(assetId: string, metadata: Record<string, unknown>): Promise<{
@@ -505,8 +553,12 @@ type UploadOptions = {
      * Idempotent: you can always add missing variants later via
      * `aq.assets.regenerate(id, { presets: [...] })`. The platform
      * stores the source so regeneration doesn't require re-uploading.
+     *
+     * {@link RequestablePreset}, not {@link VariantPreset}. `hls` and `mp3` are
+     * produced FOR you — the ladder when a video transcodes, the mp3 alongside
+     * any audio original — and asking for either is a 400.
      */
-    presets?: VariantPreset[];
+    presets?: RequestablePreset[];
     /**
      * Max time to wait for the asset to transition to `ready` (or `failed`)
      * after dispatch. Default `5 * 60_000` (5 min). Bump higher for large
@@ -640,6 +692,7 @@ declare class UsageApi {
     }>;
     private headers;
 }
+
 declare class NitidaClient {
     readonly slots: SlotsApi;
     readonly assets: AssetsApi;
@@ -815,11 +868,29 @@ declare class NitidaClient {
      * `presets` string. Falls back through the preference order
      *   lg → md → sm → thumb → original   (for images)
      *   video → poster                    (for videos)
-     *   mp3 → original                    (for audio)
+     *   original → mp3                    (for audio ALREADY playable everywhere)
+     *   mp3 → original                    (for any other audio)
      * so an upload that was processed with e.g. `["original"]` still
      * returns a non-404 URL in `aq.upload`'s result.
+     *
+     * ⭐ Why audio branches on the source mime (changed 2026-08-22).
+     *
+     * It used to be `mp3 → original` unconditionally, so `upload().cdnUrl`
+     * handed back the server's auto-generated mp3 — libmp3lame, mono ~96 kbps —
+     * even when the caller had uploaded an MP3 or an AAC that already plays in
+     * every target browser. A consumer asking for "my file" silently received a
+     * re-encoded, lower-quality one, with no error to notice.
+     *
+     * Measured across the platform: of 126 audio assets carrying an mp3 variant,
+     * **105 had an `audio/mpeg` source** — an MP3 re-encoded into an MP3, for
+     * zero compatibility gain.
+     *
+     * The mp3 still wins for `audio/webm`/Opus and anything exotic, which is the
+     * case it was built for: Chrome records webm/Opus, which iOS Safari cannot
+     * decode. That guarantee is preserved exactly; only the needless downgrade
+     * is gone.
      */
     private bestPresetForAsset;
 }
 
-export { type ComposeMarketingComposition, type ComposeMarketingOptions, type ComposeMarketingResult, type ComposeMarketingSegment, type CompressOptions, NitidaClient, type NitidaClientOptions, type PresignUploadUrlOptions, type RegenerateResult, type SlotHistoryEntry, type UploadOptions, type UploadResult, type UploadUrlResult, type UploadVideoOptions, type UsageDailyPoint, type UsagePerKey, type UsageSnapshot, type UsageWindow, mimeFromFileName };
+export { type ComposeMarketingComposition, type ComposeMarketingOptions, type ComposeMarketingResult, type ComposeMarketingSegment, type CompressOptions, NitidaClient, type NitidaClientOptions, type PresignUploadUrlOptions, type RegenerateResult, type SlotHistoryEntry, type UploadOptions, type UploadResult, type UploadUrlResult, type UploadVideoOptions, type UsageDailyPoint, type UsagePerKey, type UsageSnapshot, type UsageWindow, isUniversallyPlayableAudio, mimeFromFileName };