@nitida/sdk 0.28.0 → 0.29.0

package/AGENTS.md

@@ -167,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
 
@@ -434,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.
@@ -1383,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

@@ -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).
@@ -479,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

@@ -422,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;
@@ -432,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}`);
   }
   /**