@nitida/sdk 0.27.1 → 0.29.0

package/AGENTS.md

@@ -101,6 +101,22 @@ await getPrivateTransformUrl(asset, { width: 1280 }, signingKey, { expiresInSeco
 - **`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.
+- **⭐ Where the signing key comes from: the response that CREATED your
+  project, once.** `POST /admin/projects` returns `signingKey` next to the
+  three API keys, and the console shows it in the same panel. Nothing else
+  hands it out — `GET /admin/projects/:code` does **not** include it. If it is
+  lost, the only endpoint that returns a key is
+  `POST /admin/projects/:code/rotate-signing-key`, which **invalidates every
+  URL already signed** and needs the system-scope key the platform operator
+  holds. A tenant with nothing signed yet can rotate for free; a live one
+  cannot, which is why you save it at creation.
+- **⭐ Already have a project and never saw a signing key?** Then you never got
+  one — projects created before 2026-08-23 were not handed it, and no endpoint
+  shows you the current one. **If you have not signed any URLs yet, ask us to
+  rotate: with nothing in flight, rotation invalidates nothing and is free.**
+  If you already have signed URLs circulating, ask us for the current key
+  instead. This is the wall the T5 agent hit, and the sentence that was
+  missing.
 
 ## Two ways an image gets smaller, and only one of them is yours to call
 
@@ -151,4 +167,4 @@ degrades to a wrong choice.
 |---|---|
 | `@nitida/asset-client` | URL builders + preset tables. No network, no key. |
 | `@nitida/asset-compressor-web` | Browser image compression (worker → OffscreenCanvas → WebP). |
-| `@aquienpz/asset-uploader-web` | Per-file transport: multipart, resume via IndexedDB, progress. |
+| `@nitida/asset-uploader-web` | Per-file transport: multipart, resume via IndexedDB, progress. |

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Espacio Futuro LTD
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -55,7 +55,7 @@ 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}`,
+Uploaders + compressors are **optional** peer deps (`@nitida/asset-uploader-{web,expo}`,
 `@nitida/asset-compressor-{web,native}`). Skip them if your app only resolves
 slots and reads assets — your bundle stays a few KB.
 
@@ -229,10 +229,13 @@ Peer deps: `@nitida/asset-client` (URL builders + types) and `react` (only if
 you use the `/react` subpath). Both compressors are optional and lazy — the
 SDK never imports them unless you call a compress path.
 
-> ⚠️ The multipart uploader packages (`@aquienpz/asset-uploader-web` /
-> `-expo`) are **not published on npm**. `aq.upload()` covers files in a
-> single PUT and is what every consumer uses today; see *Large uploads* below
-> for where the ceiling actually is.
+> The multipart uploader packages (`@nitida/asset-uploader-web` / `-expo`) are
+> on npm since 2026-08-23. You do not need them for ordinary uploads:
+> `aq.upload()` covers a file in a single PUT and is what every consumer uses
+> today — see *Large uploads* below for where that ceiling actually is. Reach
+> for an uploader when you need **resume**: a 2 GB upload that must survive a
+> reload (web, IndexedDB) or the app being backgrounded (Expo, iOS URLSession
+> / Android WorkManager).
 
 ## Quick start
 
@@ -259,8 +262,11 @@ const heroes = await aq.slots.resolveMany([
   "storefront.home.tile-2",
 ]);
 
-// Lower-level operations.
+// Lower-level operations. `byHash` takes the full 64-hex sha256 that
+// `upload()` returns as `.sha256`, OR its 16-char prefix — the short form
+// that appears inside every CDN URL. Both resolve to the same asset.
 const asset = await aq.assets.byHash("3c…<64 hex>…");
+const same = await aq.assets.byHash("3c8f1a20b7d94e05"); // 16-char prefix ✓
 const { assets, nextCursor } = await aq.assets.list({ limit: 50 });
 
 // Uploads — hash-deduped; returns the canonical v2 URL immediately.
@@ -431,7 +437,7 @@ export function UploadHeroScreen() {
 }
 ```
 
-⚠️ The Expo background-upload path depends on `@aquienpz/asset-uploader-expo`,
+⚠️ The Expo background-upload path depends on `@nitida/asset-uploader-expo`,
 which is **not on npm**. `aq.upload()` works on Expo today without it; the
 background/resumable variant is not something an external consumer can install
 yet.
@@ -894,6 +900,29 @@ as they specify the same params.
 
 Every tenant has an HMAC-SHA256 signing key — 32 random bytes, generated
 on tenant creation.
+
+> **Where you get it: the response that created your project, once.**
+> `POST /admin/projects` returns `signingKey` next to the three API keys, and
+> the console shows it in the same panel. Save it with the keys — nothing else
+> hands it out. In particular `GET /admin/projects/:code` does **not** return
+> it, and neither does any tenant-scoped endpoint.
+>
+> **Your project already exists and you never saw a signing key?** Then you
+> never got one: projects created before 2026-08-23 were not handed it, and
+> there is no endpoint that shows you the current one. This is the exact wall
+> to hit, so here is the way through it:
+>
+> - **If you have not signed any URLs yet** — which is true of every project
+>   that has not shipped private assets — ask us to rotate. Rotation returns a
+>   key, and with nothing in flight it invalidates nothing. It is free.
+> - **If you already have signed URLs in circulation**, rotation kills them.
+>   Ask us for the current key instead; we can read it.
+>
+> Either way it is one request to us, because
+> `POST /admin/projects/:code/rotate-signing-key` needs the system-scope key
+> the platform operator holds — your own admin key answers
+> `403 SYSTEM_KEY_REQUIRED`.
+
 Optionally enable `strict_transforms = true` to reject unsigned URLs
 with a 401 — useful when transform URLs leak from a private surface
 (internal admin, b2b portal) and you don't want third parties
@@ -905,7 +934,8 @@ const aq = new NitidaClient({
   apiKey:     process.env.AQUIENPZ_API_KEY!,
   tenantCode: "your-tenant",
   tenantId:   42,
-  // Fetch via GET /admin/projects/your-tenant; do NOT ship to the browser.
+  // Handed to you once, by the response that created the project.
+  // do NOT ship to the browser.
   signingKey: process.env.AQUIENPZ_SIGNING_KEY!,
 });
 
@@ -1304,7 +1334,7 @@ API key tiers:
 | `aq.slots` | `bind(key, {assetId, preset})` | Admin rebind |
 | `aq.slots` | `unbind(key)` | Remove binding |
 | `aq.slots` | `invalidateCache(key?)` | After admin rebind |
-| `aq.assets` | `byHash(sha)` / `byHashes([])` | Lookup |
+| `aq.assets` | `byHash(sha)` / `byHashes([])` | Lookup — full 64-hex sha **or** its 16-char prefix |
 | `aq.assets` | `list({limit, cursor})` | Paginated |
 | `aq.assets` | `get(id)` | Full DTO |
 | `aq.assets` | `patchMetadata(id, {…})` | Merge JSON |
@@ -1356,4 +1386,10 @@ or a cache hit runs no encoder and books nothing, so `0` means zero.
 
 ## License
 
-UNLICENSED — internal use only.
+MIT — see [LICENSE](./LICENSE).
+
+⚠️ **The licence covers this client code, not the service.** MIT lets you use,
+modify and redistribute the SDK; it does not grant access to nitida. The
+service is governed by its own terms and plan tiers, and every call still needs
+credentials issued to your project. Same shape as every other API client you
+already depend on.

package/SECURITY.md

@@ -0,0 +1,56 @@
+# Security
+
+## Reporting a vulnerability
+
+Email **security@espaciofuturo.io**. Please do not open a public issue — a
+public report is a disclosure, and it reaches attackers at the same moment it
+reaches us.
+
+Include what you have: the affected package and version, what you did, and what
+happened. A URL that reproduces it is worth more than a paragraph describing
+one. We will confirm receipt and tell you what we found.
+
+## What is in scope
+
+The published client packages and the service they talk to:
+
+- `@nitida/sdk`, `@nitida/asset-client`
+- `@nitida/asset-compressor-web`, `@nitida/asset-compressor-native`
+- `@nitida/asset-uploader-web`, `@nitida/asset-uploader-expo`
+- the delivery edge (`8ok.uk`) and the API (`api.nitida.gofuture.space`)
+
+## Two behaviours that look like bugs and are not
+
+Reported often enough to state up front, so a real report is not lost among
+them:
+
+**A 404 on a private asset is the feature.** An asset with
+`visibility: "private"` answers 404 on every public URL — the raw path, every
+stored variant, every `/t/` transform and every HLS segment. It is not a
+missing file. Signed access lives at `/a/{tenant}/…?exp&sig`, minted on your
+backend. See the SDK's `getPrivateAssetUrl`.
+
+**A presigned upload URL is a bearer credential, on purpose.** The browser
+uploader persists presigned R2 PUT URLs in IndexedDB, because that is what
+resuming after a reload means. They are write-only, scoped to the parts of one
+upload the holder started, expire in 60 minutes, and are deleted on complete
+and on abort.
+
+## Credentials, and the one mistake that matters
+
+An API key (`amk_rt_*`, `amk_ad_*`, `amk_ci_*`) is a **server-side** credential.
+It must never reach a browser bundle, an `NEXT_PUBLIC_*` variable, or a mobile
+app binary.
+
+The same goes for a tenant's **URL signing key**: it mints signed URLs for
+every private asset that tenant owns. Sign on your backend, or pre-sign at
+build time.
+
+The client packages are built so this is hard to get wrong — the web entrypoint
+`@nitida/sdk/web` does not accept `apiKey` or `signingKey` at all; the types
+reject them. If you find a path that leaks either one, that is exactly the
+report we want.
+
+If you believe a key has been exposed, email the address above and we will
+rotate it. Rotating a signing key invalidates every URL already signed with it,
+so tell us whether you have signed URLs in circulation.

package/dist/expo.d.ts

@@ -1,12 +1,12 @@
-import { UploadTaskOptions, UploadTask } from '@aquienpz/asset-uploader-expo';
-export { UploadEvents, UploadFileInput, UploadSessionState, UploadTask, UploadTaskOptions, cancelResumableSession, listResumableSessions } from '@aquienpz/asset-uploader-expo';
+import { UploadTaskOptions, UploadTask } from '@nitida/asset-uploader-expo';
+export { UploadEvents, UploadFileInput, UploadSessionState, UploadTask, UploadTaskOptions, cancelResumableSession, listResumableSessions } from '@nitida/asset-uploader-expo';
 import { NitidaClient } from './index.js';
 import '@nitida/asset-client';
 
 /**
  * @nitida/sdk/expo — native multipart uploads for React Native / Expo.
  *
- * Wraps `@aquienpz/asset-uploader-expo`'s `UploadTask`, which delegates
+ * Wraps `@nitida/asset-uploader-expo`'s `UploadTask`, which delegates
  * the actual byte transfer to a native background session (URLSession
  * on iOS, WorkManager on Android). The upload survives:
  *   - JS thread freezing
@@ -58,7 +58,7 @@ import '@nitida/asset-client';
  * 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
+ * Peer dep: `@nitida/asset-uploader-expo` (lazy — apps that don't
  * use the mobile SDK skip the install).
  * @module @nitida/sdk/expo
  */

package/dist/expo.js

@@ -1,12 +1,12 @@
 // src/expo/index.ts
 import {
   UploadTask
-} from "@aquienpz/asset-uploader-expo";
+} from "@nitida/asset-uploader-expo";
 import {
   cancelResumableSession,
   listResumableSessions,
   UploadTask as UploadTask2
-} from "@aquienpz/asset-uploader-expo";
+} from "@nitida/asset-uploader-expo";
 function createExpoUploader(client, options) {
   const access = client;
   return new 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 * ⚠️ 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"]}
+{"version":3,"sources":["../src/expo/index.ts"],"sourcesContent":["/**\n * @nitida/sdk/expo — native multipart uploads for React Native / Expo.\n *\n * Wraps `@nitida/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: `@nitida/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 \"@nitida/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 \"@nitida/asset-uploader-expo\";\nexport {\n  cancelResumableSession,\n  listResumableSessions,\n  UploadTask,\n} from \"@nitida/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, 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, assertSha, 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';
+export { AssetDTO, AssetPalette, AssetVariant, HlsRung, PRESET_EXT, PRESET_LONG, PRESET_MAX_DIM, PRESET_SHORT, PaletteSwatch, REQUESTABLE_PRESETS, RequestablePreset, ResolveSlotOptions, SignAccessOptions, SignedTransformOptions, SlotDTO, SlotResolution, TRANSFORM_WIDTHS, TransformEffect, TransformFit, TransformFormat, TransformGravity, TransformOptions, TransformWidth, VariantEntryPreset, VariantPreset, VisibilityHint, accessMessage, assertPublic, assertSha, 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, isRequestablePreset, iteratePaletteSwatches, pickAmbientBackground, relativeLuminance, resolveSlot, resolveSlots, serializeTransform, setCdnBase, setTenantId, signAccessUrl, signTransformUrl, toRequestablePresets } from '@nitida/asset-client';
 
 /**
  * Which audio uploads already play everywhere — the single source of truth for
@@ -40,7 +40,7 @@ declare function isUniversallyPlayableAudio(mime: string): boolean;
  * platform.
  *
  * One ergonomic facade over the underlying packages
- * (`@nitida/asset-client` URL builders + `@aquienpz/asset-uploader-web`
+ * (`@nitida/asset-client` URL builders + `@nitida/asset-uploader-web`
  * + the slot resolver). Auth is a bearer API key (`amk_rt_*`), issued
  * per tenant when the tenant is created; tenant scope comes from
  * the key's metadata (`X-Tenant-Code` is log-only).
@@ -119,12 +119,25 @@ type NitidaClientOptions = {
      * Tenant's HMAC signing key for transform URLs (Phase 3). Required
      * only when calling `aq.transform(asset, opts, { sign: true })`.
      *
-     * 32 random bytes, generated server-side on tenant creation; fetch
-     * 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.
+     * 32 random bytes, generated server-side on tenant creation.
+     *
+     * **Where you get it: the response to your project's creation, once.**
+     * `POST /admin/projects` returns `signingKey` next to the three API keys,
+     * and the console shows it in the same panel. It is shown there and nowhere
+     * else — save it with the keys.
+     *
+     * **Never saw one?** Projects created before 2026-08-23 were not handed it,
+     * and no endpoint shows you the current one. If you have not signed any URLs
+     * yet — true of every project that has not shipped private assets — ask for
+     * a rotation: with nothing in flight it invalidates nothing and is free. If
+     * you already have signed URLs circulating, ask for the current key instead.
+     *
+     * Either way it is one request to the platform operator:
+     * `POST /admin/projects/:code/rotate-signing-key` needs a SYSTEM-scope
+     * credential, and your own admin key answers `403 SYSTEM_KEY_REQUIRED`.
+     *
+     * **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.
      */
     signingKey?: string;
 };
@@ -319,7 +332,12 @@ type ComposeMarketingResult = {
 declare class AssetsApi {
     private readonly opts;
     constructor(opts: NitidaClientOptions);
-    /** Look up an asset by full sha256 (64 hex). Returns null on 404. */
+    /**
+     * Look up an asset by sha256. Accepts the full 64-hex digest that
+     * `upload()` returns as `sha256`, or the 16-char short prefix that appears
+     * in every CDN URL. Returns null on 404; throws with a message naming the
+     * expected shape if the string is neither form.
+     */
     byHash(sha256: string): Promise<AssetDTO | null>;
     /** Bulk lookup by sha256s. */
     byHashes(hashes: string[]): Promise<{
@@ -461,7 +479,31 @@ declare class AssetsApi {
      * Default timeout is 5 minutes; videos / HLS ladders may need a
      * higher cap (pass `10 * 60_000` for compositions, transcodes).
      */
-    waitReady(assetId: string, timeoutMs?: number): Promise<AssetDTO>;
+    waitReady(assetId: string, 
+    /**
+     * Milliseconds, OR `{ timeoutMs }`.
+     *
+     * ⭐ It accepts the object because that is what people write. Found
+     * 2026-08-23 while smoke-testing a brand-new tenant: I passed
+     * `{ timeoutMs: 90_000 }` — every other option-taking method in this SDK
+     * takes an object — and got
+     *
+     *     Error: waitReady: no asset a379fbbb-…
+     *
+     * about an asset that existed, was `ready`, and whose variants were all
+     * serving 200. `Date.now() - start < {…}` compares against NaN, so the
+     * loop body never ran, `last` stayed null, and the message blamed the one
+     * thing that was fine.
+     *
+     * TypeScript catches the wrong shape. Running it through `bun` does not —
+     * the same gap that let `upload()`'s `sha256` reach a URL builder wanting
+     * `sha` and produce `.../undefined.webp`. The lesson there was the same as
+     * here: a guard with a good message is still a mistake the user has to
+     * make first. Make the obvious call correct instead.
+     */
+    timeout?: number | {
+        timeoutMs?: number;
+    }): Promise<AssetDTO>;
     /**
      * Dispatch `POST /assets/compose-marketing` to stitch pre-uploaded clip
      * segments into a single MP4 composition. Returns the processing asset

package/dist/index.js

@@ -53,12 +53,14 @@ import {
   hasPreset as hasPreset2,
   hlsLadderAlignment,
   invalidateSlotCache as invalidateSlotCache2,
+  isRequestablePreset as isRequestablePreset2,
   iteratePaletteSwatches,
   PRESET_EXT,
   PRESET_LONG,
   PRESET_MAX_DIM,
   PRESET_SHORT,
   pickAmbientBackground,
+  REQUESTABLE_PRESETS as REQUESTABLE_PRESETS2,
   relativeLuminance,
   resolveSlot as resolveSlot2,
   resolveSlots as resolveSlots2,
@@ -67,7 +69,8 @@ import {
   setTenantId as setTenantId2,
   signAccessUrl,
   signTransformUrl,
-  TRANSFORM_WIDTHS
+  TRANSFORM_WIDTHS,
+  toRequestablePresets as toRequestablePresets2
 } from "@nitida/asset-client";
 function endpointUrl(opts, path, searchParams) {
   const endpoint = opts.endpoint.replace(/\/+$/, "");
@@ -199,7 +202,12 @@ var AssetsApi = class {
     this.opts = opts;
   }
   opts;
-  /** Look up an asset by full sha256 (64 hex). Returns null on 404. */
+  /**
+   * Look up an asset by sha256. Accepts the full 64-hex digest that
+   * `upload()` returns as `sha256`, or the 16-char short prefix that appears
+   * in every CDN URL. Returns null on 404; throws with a message naming the
+   * expected shape if the string is neither form.
+   */
   async byHash(sha256) {
     const r = await fetch(
       endpointHref(this.opts, `/assets/by-hash/${sha256}`),
@@ -414,7 +422,13 @@ var AssetsApi = class {
    * Default timeout is 5 minutes; videos / HLS ladders may need a
    * higher cap (pass `10 * 60_000` for compositions, transcodes).
    */
-  async waitReady(assetId, timeoutMs = 5 * 6e4) {
+  async waitReady(assetId, timeout = 5 * 6e4) {
+    const timeoutMs = typeof timeout === "number" ? timeout : timeout !== null && typeof timeout === "object" ? timeout.timeoutMs ?? 5 * 6e4 : Number.NaN;
+    if (!Number.isFinite(timeoutMs) || timeoutMs <= 0) {
+      throw new Error(
+        `waitReady: timeout must be a positive number of milliseconds or { timeoutMs }, got ${JSON.stringify(timeout)}. A non-numeric timeout makes the poll loop exit before its first iteration, which used to surface as "no asset <id>" about an asset that was fine.`
+      );
+    }
     const start = Date.now();
     let delay = 500;
     let last = null;
@@ -424,7 +438,11 @@ var AssetsApi = class {
       await new Promise((r) => setTimeout(r, delay));
       delay = Math.min(delay * 1.5, 5e3);
     }
-    if (!last) throw new Error(`waitReady: no asset ${assetId}`);
+    if (!last) {
+      throw new Error(
+        `waitReady: polled ${assetId} zero times in ${timeoutMs}ms \u2014 this is a bug in the SDK, not a missing asset.`
+      );
+    }
     throw new Error(`waitReady timeout for ${assetId}`);
   }
   /**
@@ -572,7 +590,7 @@ var NitidaClient = class {
     }
     if (!this.opts.signingKey) {
       throw new Error(
-        "aq.transform({ sign: true }) requires `signingKey` in NitidaClientOptions. No signingKey on this client. The key is minted by POST /admin/projects/:code/rotate-signing-key, which needs a system-scope credential the platform operator holds \u2014 your own admin key gets 403 SYSTEM_KEY_REQUIRED, so ask for it. Then pass it to the SDK constructor on a SERVER-side instance only."
+        "aq.transform({ sign: true }) requires `signingKey` in NitidaClientOptions. No signingKey on this client. It is returned ONCE, in the response that creates your project (POST /admin/projects \u2192 `signingKey`, next to the three API keys; the console shows it in the same panel). If you never saw one \u2014 projects created before 2026-08-23 were not handed it \u2014 ask the platform operator to rotate: with no signed URLs in flight that invalidates nothing and is free. If you DO have signed URLs circulating, ask for the current key instead, because rotating would kill them. Then pass it to the SDK constructor on a SERVER-side instance only."
       );
     }
     return getSignedTransformUrl(asset, opts, this.opts.signingKey) ?? Promise.resolve(this.urlFor(asset, "lg"));
@@ -581,7 +599,7 @@ var NitidaClient = class {
     if (!signOpts?.sign) return getTransformSrcSet(asset, widths, extraOpts);
     if (!this.opts.signingKey) {
       throw new Error(
-        "aq.transformSrcSet({ sign: true }) requires `signingKey` in NitidaClientOptions."
+        "aq.transformSrcSet({ sign: true }) requires `signingKey` in NitidaClientOptions. It was returned ONCE, by the response that created your project (POST /admin/projects \u2192 `signingKey`). See the `signingKey` docs on NitidaClientOptions."
       );
     }
     const key = this.opts.signingKey;
@@ -860,6 +878,7 @@ export {
   PRESET_LONG,
   PRESET_MAX_DIM,
   PRESET_SHORT,
+  REQUESTABLE_PRESETS2 as REQUESTABLE_PRESETS,
   TRANSFORM_WIDTHS,
   accessMessage,
   assertPublic,
@@ -890,6 +909,7 @@ export {
   hasPreset2 as hasPreset,
   hlsLadderAlignment,
   invalidateSlotCache2 as invalidateSlotCache,
+  isRequestablePreset2 as isRequestablePreset,
   isUniversallyPlayableAudio,
   iteratePaletteSwatches,
   mimeFromFileName,
@@ -901,6 +921,7 @@ export {
   setCdnBase2 as setCdnBase,
   setTenantId2 as setTenantId,
   signAccessUrl,
-  signTransformUrl
+  signTransformUrl,
+  toRequestablePresets2 as toRequestablePresets
 };
 //# sourceMappingURL=index.js.map