@nitida/sdk 0.27.1 → 0.29.0

package/skills/nitida-sdk/SKILL.md

@@ -13,8 +13,9 @@ description: How to consume the nitida media platform (@nitida/sdk + @nitida/ass
 > (2026-06-28) and 0.14.2 (2026-07-18). They receive nothing. If you are pinned to either, you are
 > on a line that predates the `variants`/`oext` fixes, the HLS ladder registration, and a
 > `hasPreset` that does not report an `original` that is not there. Move to `@nitida/*`.
-> `tenant-config`, `asset-uploader-web` and `asset-uploader-expo` are internal and not on npm at
-> all.
+> `@nitida/asset-uploader-web` and `@nitida/asset-uploader-expo` ARE on npm since 2026-08-23 —
+> they were workspace-only until another repo started consuming them as `workspace:*` copies, which
+> is public in effect without being auditable. `@aquienpz/tenant-config` is still internal.
 
 > Durable source of truth: **the published docs at <https://nitida.gofuture.space>** — most of it
 > generated from the types, so the API reference cannot rot. Agents can download it: the site
@@ -506,6 +507,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
 

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).
@@ -48,6 +48,8 @@ import {
   getVideoTransformUrl,
   hasPreset,
   invalidateSlotCache,
+  isRequestablePreset,
+  REQUESTABLE_PRESETS,
   type RequestablePreset,
   type ResolveSlotOptions,
   resolveSlot,
@@ -58,6 +60,7 @@ import {
   setCdnBase,
   setTenantId,
   type TransformOptions,
+  toRequestablePresets,
   type VariantEntryPreset,
   type VariantPreset,
 } from "@nitida/asset-client";
@@ -114,12 +117,25 @@ export 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;
 };
@@ -254,12 +270,14 @@ export {
   hasPreset,
   hlsLadderAlignment,
   invalidateSlotCache,
+  isRequestablePreset,
   iteratePaletteSwatches,
   PRESET_EXT,
   PRESET_LONG,
   PRESET_MAX_DIM,
   PRESET_SHORT,
   pickAmbientBackground,
+  REQUESTABLE_PRESETS,
   relativeLuminance,
   resolveSlot,
   resolveSlots,
@@ -269,6 +287,7 @@ export {
   signAccessUrl,
   signTransformUrl,
   TRANSFORM_WIDTHS,
+  toRequestablePresets,
 } from "@nitida/asset-client";
 
 // ---------------------------------------------------------------------------
@@ -531,7 +550,12 @@ export type ComposeMarketingResult = {
 class AssetsApi {
   constructor(private readonly 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.
+   */
   async byHash(sha256: string): Promise<AssetDTO | null> {
     const r = await fetch(
       endpointHref(this.opts, `/assets/by-hash/${sha256}`),
@@ -796,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;
@@ -806,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}`);
   }
 
@@ -1296,7 +1370,7 @@ export class NitidaClient {
     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 — 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.",
+          "No signingKey on this client. It is returned ONCE, in the response that creates your project (POST /admin/projects → `signingKey`, next to the three API keys; the console shows it in the same panel). If you never saw one — projects created before 2026-08-23 were not handed it — 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.",
       );
     }
     // Signed path — custom (off-ladder) widths allowed. Empty opts → no
@@ -1334,7 +1408,8 @@ export class NitidaClient {
     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 → `signingKey`). See the `signingKey` docs on NitidaClientOptions.",
       );
     }
     const key = this.opts.signingKey;
@@ -1520,10 +1595,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

package/src/server/index.ts

@@ -129,6 +129,7 @@ export {
   hasPreset,
   hlsLadderAlignment,
   invalidateSlotCache,
+  isRequestablePreset,
   isUniversallyPlayableAudio,
   iteratePaletteSwatches,
   mimeFromFileName,
@@ -140,6 +141,7 @@ export {
   PRESET_SHORT,
   type PresignUploadUrlOptions,
   pickAmbientBackground,
+  REQUESTABLE_PRESETS,
   type RegenerateResult,
   type RequestablePreset,
   type ResolveSlotOptions,
@@ -163,6 +165,7 @@ export {
   type TransformGravity,
   type TransformOptions,
   type TransformWidth,
+  toRequestablePresets,
   type UploadOptions,
   type UploadResult,
   type UploadUrlResult,

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.
@@ -146,6 +146,7 @@ export {
   hasPreset,
   hlsLadderAlignment,
   invalidateSlotCache,
+  isRequestablePreset,
   isUniversallyPlayableAudio,
   iteratePaletteSwatches,
   mimeFromFileName,
@@ -156,6 +157,7 @@ export {
   PRESET_SHORT,
   type PresignUploadUrlOptions,
   pickAmbientBackground,
+  REQUESTABLE_PRESETS,
   type RegenerateResult,
   type RequestablePreset,
   type ResolveSlotOptions,
@@ -179,6 +181,7 @@ export {
   type TransformGravity,
   type TransformOptions,
   type TransformWidth,
+  toRequestablePresets,
   type UploadOptions,
   type UploadResult,
   type UploadUrlResult,
@@ -194,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`
@@ -206,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)