@nitida/sdk 0.28.0 → 0.30.0

package/src/expo/index.ts

@@ -1,7 +1,7 @@
 /**
  * @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
@@ -53,7 +53,7 @@
  * 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
  */
@@ -61,7 +61,7 @@
 import {
   UploadTask,
   type UploadTaskOptions,
-} from "@aquienpz/asset-uploader-expo";
+} from "@nitida/asset-uploader-expo";
 import type { NitidaClient } from "..";
 
 export type ExpoUploadOptions = Omit<
@@ -97,9 +97,9 @@ export type {
   UploadFileInput,
   UploadSessionState,
   UploadTaskOptions,
-} from "@aquienpz/asset-uploader-expo";
+} from "@nitida/asset-uploader-expo";
 export {
   cancelResumableSession,
   listResumableSessions,
   UploadTask,
-} from "@aquienpz/asset-uploader-expo";
+} from "@nitida/asset-uploader-expo";

package/src/index.ts

@@ -3,7 +3,7 @@
  * 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).
@@ -820,7 +820,49 @@ class AssetsApi {
    * Default timeout is 5 minutes; videos / HLS ladders may need a
    * higher cap (pass `10 * 60_000` for compositions, transcodes).
    */
-  async waitReady(assetId: string, timeoutMs = 5 * 60_000): Promise<AssetDTO> {
+  async 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 } = 5 * 60_000,
+  ): Promise<AssetDTO> {
+    // A string, a Date, anything else: refuse it. Falling back to the default
+    // would be the same silent-success this whole method just stopped doing —
+    // `waitReady(id, "90s")` would wait five minutes and the caller would
+    // never learn why.
+    const timeoutMs =
+      typeof timeout === "number"
+        ? timeout
+        : timeout !== null && typeof timeout === "object"
+          ? (timeout.timeoutMs ?? 5 * 60_000)
+          : 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: AssetDTO | null = null;
@@ -830,7 +872,15 @@ class AssetsApi {
       await new Promise((r) => setTimeout(r, delay));
       delay = Math.min(delay * 1.5, 5_000);
     }
-    if (!last) throw new Error(`waitReady: no asset ${assetId}`);
+    // Unreachable now that a non-numeric timeout is refused above: any
+    // positive timeout runs the loop at least once, so `last` is set. Kept as
+    // a belt, with a message that no longer accuses the asset of not existing.
+    if (!last) {
+      throw new Error(
+        `waitReady: polled ${assetId} zero times in ${timeoutMs}ms — this is a ` +
+          "bug in the SDK, not a missing asset.",
+      );
+    }
     throw new Error(`waitReady timeout for ${assetId}`);
   }
 
@@ -1059,6 +1109,32 @@ export type UploadResult = {
    * message about the wrong one.
    */
   sha: string;
+  /**
+   * The MIME the upload was stored under.
+   *
+   * ⭐ It exists because it did not, and that cost the THIRD 404 of this exact
+   * family. Found 2026-08-23 by an agent running the getting-started doc
+   * verbatim: `getAssetUrl(up, "original")` built `<sha>-o.bin` and 404'd,
+   * while the object served fine at `-o.jpg`.
+   *
+   * `original` is the one preset whose extension is not fixed — it is the
+   * bytes you uploaded, so the extension comes from the MIME (`ORIGINAL_EXT_BY_MIME`),
+   * and `PRESET_EXT.original` is only the `"bin"` fallback for when nothing
+   * says otherwise. `UploadResult` said nothing, so every caller handing an
+   * upload result straight to a URL builder got the fallback.
+   *
+   * The pattern is now three for three — `sha256` vs `sha`, and this:
+   * **a result type that omits what the next call needs turns the obvious
+   * call into a silent 404.** The fix is never a better error message.
+   */
+  mime: string;
+  /**
+   * The extension the server actually stored the original under, when it said
+   * so. Authoritative — it beats any client-side MIME table, because the
+   * server keys the object off the uploaded filename for the cases no table
+   * can close (`.mpga`, `.docx`, `.m4a` all arrive as octet-stream).
+   */
+  oext?: string | null;
   cdnUrl: string;
 };
 
@@ -1545,10 +1621,10 @@ export class NitidaClient {
       // was not enough: `bun build --compile` constant-folds simple
       // strings and still eagerly bundled `./web.js`, which
       // top-level-imports the browser-only peer deps
-      // `@aquienpz/asset-uploader-web` / `@nitida/asset-compressor-web`
+      // `@nitida/asset-uploader-web` / `@nitida/asset-compressor-web`
       // — neither installed on server consumers — crashing the
       // single-binary on boot with `Cannot find module
-      // '@aquienpz/asset-uploader-web'`.
+      // '@nitida/asset-uploader-web'`.
       //
       // The earlier `new URL("./web.js", import.meta.url)` + `await import(URL)`
       // dance survived bun-compile but Turbopack still tracks the URL literal
@@ -1606,6 +1682,8 @@ export class NitidaClient {
         assetId: existing.id,
         sha256: sha,
         sha: sha.slice(0, 16),
+        mime: existing.mime ?? mime,
+        oext: existing.oext ?? null,
         cdnUrl: this.urlFor(existing, this.bestPresetForAsset(existing, mime)),
       };
     }
@@ -1632,6 +1710,8 @@ export class NitidaClient {
         assetId: presign.asset.id,
         sha256: sha,
         sha: sha.slice(0, 16),
+        mime: presign.asset.mime ?? mime,
+        oext: presign.asset.oext ?? null,
         cdnUrl: this.urlFor(presign.asset, this.defaultPresetForMime(mime)),
       };
     }
@@ -1683,6 +1763,8 @@ export class NitidaClient {
       assetId,
       sha256: sha,
       sha: sha.slice(0, 16),
+      mime: final.mime ?? mime,
+      oext: final.oext ?? null,
       cdnUrl: this.urlFor(final, this.bestPresetForAsset(final, mime)),
     };
   }

package/src/web/index.ts

@@ -44,7 +44,7 @@
  * `apiKey` and bundles cleanly only in Node/Bun/edge runtimes.
  *
  * Peer deps (auto-installed via npm peer deps — declared optional):
- *   - `@aquienpz/asset-uploader-web` for multipart uploads
+ *   - `@nitida/asset-uploader-web` for multipart uploads
  *   - `@nitida/asset-compressor-web` for client-side compression
  *
  * Both are lazy-imported; bundles that never call into them skip the cost.
@@ -197,7 +197,7 @@ export {
 
 // Multipart uploader helpers are NOT re-exported from this subpath.
 //
-// `@aquienpz/asset-uploader-web` is an optional peer-dep that isn't on
+// `@nitida/asset-uploader-web` is an optional peer-dep that isn't on
 // npm yet, so a static `import` at module top broke every consumer of
 // `@nitida/sdk/web` (the bundler tries to resolve before the optional
 // peer check kicks in). The old `createWebUploader` + `UploadTask`
@@ -209,7 +209,7 @@ export {
 //     token is not exposed yet. Ask us; there is no public tracker.
 //
 // Apps that need `UploadTask` directly today should depend on
-// `@aquienpz/asset-uploader-web` themselves once it's published.
+// `@nitida/asset-uploader-web` themselves once it's published.
 
 // ---------------------------------------------------------------------------
 // Client-side compression (Phase 1.5)