@nitida/sdk 0.25.2 → 0.26.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

package/README.md

@@ -1,6 +1,6 @@
 # `@nitida/sdk`
 
-Universal SDK for the [aquienpz](https://aquienpz.com) multi-tenant asset platform.
+Universal SDK for the [nitida](https://nitida.gofuture.space) multi-tenant media platform.
 A Cloudinary-style asset manager with deterministic CDN URLs, content-addressed
 dedup, server-side variants (thumb / sm / md / lg / poster / video), and **slot
 bindings** — admin-managed names that resolve to assets at runtime.
@@ -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";
@@ -809,16 +926,32 @@ 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):
+### ⚠️ 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,5 @@
-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, SignedTransformOptions, SlotDTO, SlotResolution, TRANSFORM_WIDTHS, TransformEffect, TransformFit, TransformFormat, TransformGravity, TransformOptions, TransformWidth, VariantEntryPreset, 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';
 
 /**
  * @nitida/sdk — universal client for the aquienpz multi-tenant asset
@@ -235,8 +235,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
@@ -353,7 +356,7 @@ declare class AssetsApi {
      * completion).
      */
     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<{
@@ -479,7 +482,7 @@ type UploadOptions = {
      * this option — those go to the upload pipeline raw.
      *
      * @see {@link CompressOptions}
-     * @see https://github.com/espaciofuturoio/aquienpz/tree/main/packages/sdk#client-side-compression-browsers
+     * @see https://nitida.gofuture.space/guides/advanced/ — client-side compression
      */
     compress?: boolean | CompressOptions;
     /**
@@ -505,8 +508,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