@nitida/sdk 0.26.0 → 0.27.1

package/skills/nitida-sdk/SKILL.md

@@ -87,7 +87,7 @@ const COVER_CROP = { fit: "cover", gravity: "auto" } as const;
 
 Output URL shape: `https://8ok.uk/t/format=webp,width=640/<sha16>.webp`.
 
-⚠️ **Widths MUST be on the unsigned ladder** `TRANSFORM_WIDTHS` (`160,240,256,320,400,480,600,640,800,960,1080,1200,1280,1440,1600,1920,2560,3840`). Any other width → **HTTP 400** at the edge (DoS guard). The `TransformWidth` type makes an off-ladder width a compile error — import the type, don't hardcode magic numbers. (For a one-off custom width you'd need signed URLs; not used here.)
+⚠️ **Widths MUST be on the unsigned ladder** `TRANSFORM_WIDTHS` (`96,128,160,240,256,320,400,480,600,640,800,960,1080,1200,1280,1440,1600,1920,2560,3840` — 20 widths). Any other width → **HTTP 400** at the edge (DoS guard). The `TransformWidth` type makes an off-ladder width a compile error — import the type, don't hardcode magic numbers. (For a one-off custom width you'd need signed URLs; not used here.)
 
 ## 2b. A responsive gallery — the widths, with their measured weight
 
@@ -221,7 +221,7 @@ export function videoUrl(sha: string, tenantId = TENANT_ID): string {
 Output: `https://8ok.uk/<tenantId.toString(36)>/v/<sha16>-v.mp4`.
 
 **Do NOT:**
-- ❌ Use `getVideoTransformUrl` — that builds a `/t/...` transform URL, which **410s** for a stored video sha. (`getVideoTransformUrl` is for on-the-fly re-encodes, a different feature.)
+- ❌ Use `getVideoTransformUrl` — that builds a `/t/...` transform URL, which never returns playable video. On a video sha `/t/` transforms the **poster frame**: `200 image/webp` with `x-transform-source: poster` when a poster exists, `410` when it does not. (`getVideoTransformUrl` is for on-the-fly re-encodes, a different feature.)
 - ❌ Hand-roll the path with the decimal tenant id. The path segment is **base36**: `tenantId.toString(36)`. **Tenant 10 → `/a/v/`**, and the decimal `/10/v/` **404s**. This is invisible for tenants ≤ 9 (`8`→`8`, `9`→`9`) and bit a real migration only at tenant 10. Always delegate to `getAssetUrl` so the encoding can't drift.
 
 **Audio IS supported (updated 2026-07-01 — verify against the SDK types, this used to say "not supported").** The platform recognizes `kind: "image" | "video" | "document" | "audio" | "other"` and ships an **`mp3`** variant preset (`VariantPreset` in `@nitida/asset-client`). Uploads are hash-deduped (byte-identical re-uploads return the existing sha — that's *byte* dedup, NOT semantic "find a similar track"). `nt.upload` also accepts an `audioTrack` on video-composition calls. Serve via the `mp3` preset / `original`. Confirm the current preset/kind list in `node_modules/@nitida/asset-client/dist/index.d.ts` before relying on a specific ext.
@@ -384,7 +384,11 @@ hls.js, which cannot start there, and fall through to the MP4. The `|| !MediaSou
 covers it: native if the engine is Apple's **OR** if there is no MSE to fall back on.
 
 **When you use hls.js, stop it guessing** — the defaults are how a fast connection still opens at
-240p: `{ startLevel: -1, testBandwidth: true, abrEwmaDefaultEstimate: 1_000_000 }`.
+240p. ⚠️ **Do NOT pass `startLevel: -1` together with `testBandwidth: true`** — measured,
+that pair is the *cause*: on a clip short enough to be one segment the bandwidth probe IS
+the whole video, so it plays at the bottom rung start to finish (a 5.04 s 4K asset was
+delivered at 426×240 because of it). Leave the start level unset and raise the estimate:
+`{ abrEwmaDefaultEstimate: 5_000_000 }`.
 
 **The first request can answer `202`** while the background job builds the ladder (1–3 min for a
 90 s source), then `302`s to the cached master. Keep the progressive MP4 as the fallback `<source>`
@@ -398,7 +402,7 @@ What it does NOT do is prefer Apple's engine where both work: a modern iPhone ge
 hls.js tuning goes in the `config` prop:
 
 ```tsx
-const HLS_CONFIG = { capLevelToPlayerSize: false, startLevel: -1, testBandwidth: true, abrEwmaDefaultEstimate: 1_000_000 };
+const HLS_CONFIG = { capLevelToPlayerSize: false, abrEwmaDefaultEstimate: 5_000_000 };
 <HlsVideo src={getHlsStreamingUrl(asset)} config={HLS_CONFIG} poster={poster} playsInline crossOrigin="anonymous" />
 ```
 
@@ -475,6 +479,77 @@ That replaces the older hand-run provisioning scripts and SQL that used to live
 
 Variant preset short codes: `thumb=q, sm=s, md=m, lg=l, xl=x, original=o, poster=p, video=v`. Exts: images `webp`, video `mp4`.
 
+
+## Private assets — `visibility`
+
+Default is `"public"`. Set `private` and **every public door answers 404** —
+stored variants, the raw original, the HLS ladder, and `/t/` (including the
+poster frame of a private video). The bytes come back only through a signed URL
+that expires.
+
+```ts
+import { getPrivateAssetUrl, getPrivateTransformUrl } from "@nitida/sdk";
+// ON YOUR BACKEND, once you decided this viewer may see it:
+await getPrivateAssetUrl(asset, "lg", signingKey, { expiresInSeconds: 300 });
+await getPrivateTransformUrl(asset, { width: 1280 }, signingKey, { expiresInSeconds: 300 });
+```
+
+- **A 404 on a private asset is NOT a missing file.** Check `visibility` on the
+  DTO before you check storage. It is the number-one support question.
+- **Seven URL builders throw** rather than hand you a doomed URL — `getAssetUrl`,
+  `getAssetSrcSet`, `getTransformUrl`, `getTransformSrcSet`,
+  `getVideoTransformUrl`, `getHlsStreamingUrl`, `getSignedTransformUrl` — but
+  only when the value you pass says `visibility: "private"`. A DTO that says
+  `"public"`, or a bare `{ sha }`, is never refused — and this is a DIFFERENT
+  rule from the missing-preset fallback below, which is about presets, not
+  privacy.
+- **`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.
+
+## Two ways an image gets smaller, and only one of them is yours to call
+
+This is the question every programmatic caller gets wrong, so it is stated flat:
+
+| | who does it | what it shrinks |
+|---|---|---|
+| **Client compressor** (browser / Expo) | the UI, before the PUT | the **upload**: quality 0.85, max 2880 px, WebP. iPhone 9.1 MB → 1.8 MB |
+| **Variants + `/t/`** | the backend, on request | the **delivery**: 19 MB JPEG → 170 kB WebP at 1920 |
+
+**The backend never recompresses the raw. Ever.** That is deliberate: the raw
+has to stay pristine so variants are *regenerable* — the day you add AVIF or
+raise the max dimension, the pipeline re-runs against it. A client→server lossy
+chain bakes artifacts in forever.
+
+So for an API/agent upload there is nothing to "turn on": you were never going
+to compress the raw, and delivery is already optimised two ways.
+
+```ts
+await aq.upload(file);
+aq.transform(asset, { width: 1280, format: "webp" });  // → /t/…, generated once, cached after
+
+// Only for a rung you KNOW will be rendered over and over:
+await aq.upload(file, { presets: ["original", "thumb"] });
+```
+
+**`presets` defaults to `["original"]`** — a bare upload stores the raw and no
+rendition. Since 2026-08-22 that is no longer a trap: when the DTO says a preset
+was never materialised, `getAssetUrl` / `urlFor` **fall back to `/t/`** instead
+of returning a URL that 404s. You still get optimised bytes; you just pay the
+first encode.
+
+**On demand is the default, and it is the right one.** A variant exists because
+somebody asked for it; we do not manufacture sizes on the chance that they might
+be wanted. Name presets at upload only for a rung you *know* will be rendered
+over and over — a card thumbnail on every listing page — where paying the encode
+once up front beats paying it once lazily. For everything else, upload bare and
+let `/t/` do it.
+
+⚠️ `getAssetSrcSet` deliberately does **not** fall back — a srcSet promises
+pixel widths and a transform cannot keep that promise on a source smaller than
+the rung, because the pipeline never enlarges. An empty srcSet degrades to `src`; a lying one
+degrades to a wrong choice.
+
 ## 7. Browser-direct uploads — three things that only fail in a real browser
 
 Measured 2026-08-15 on the public bench at <https://media-harness.vercel.app> — no credentials
@@ -507,7 +582,7 @@ needed. Reproduce there before debugging any of these by hand.
 | Symptom | Cause |
 |---|---|
 | **400** on an image URL | width not on `TRANSFORM_WIDTHS` ladder |
-| **410** on a video URL | used `/t/` (transform) for a stored video — use `getAssetUrl(...,'video')` |
+| **410** on a video `/t/` URL | that video has no `poster`. With one, `/t/` returns the poster as an image, never the video — use `getAssetUrl(...,'video')` |
 | **404** on a video URL | decimal tenant prefix (`/10/v/`) instead of base36 (`/a/v/`) — call `setTenantId` + `getAssetUrl`. Tenant 12 → `/c/v/` |
 | `process returned no assetId` | fixed in the 2026-08-16 deploy — you are on a server deploy older than that, §7.2 |
 | `waitReady timeout` on a video | a transcode + HLS ladder takes 1–2 min; the default `timeoutMs` is 5 min but a 4K source can beat it. Raise it, §7.2 |

package/src/audio-compat.ts

@@ -0,0 +1,37 @@
+/**
+ * Which audio uploads already play everywhere — the single source of truth for
+ * both the server's transcode guard and the client's delivery-preset choice.
+ *
+ * It lives in its own module, rather than beside the preset order that uses it,
+ * for a mechanical reason: `apps/asset-manager` imports it by relative path.
+ * The SDK is a PUBLISHED package, so its `exports` point at `dist/`, and
+ * `dist/` is gitignored — it does not exist inside the Docker image, which
+ * copies `packages/` as source. A bare `@nitida/sdk` import type-checks on any
+ * machine that built the package once and then fails the image build. (It did,
+ * on 2026-08-22, with `@nitida/asset-client`.) A single small file keeps that
+ * relative import from dragging the whole client into the server.
+ *
+ * Two copies of this list drifting apart is how a platform ends up generating
+ * a variant its own client refuses to use — which is exactly the bug this
+ * predicate was introduced to end.
+ */
+
+/**
+ * `true` when a browser can play these bytes as uploaded, so re-encoding them
+ * to MP3 buys nothing.
+ *
+ * - `audio/mpeg` — unambiguous.
+ * - `audio/mp4` / `audio/aac` — plays in Safari, Chrome, Firefox and Edge on
+ *   desktop and mobile. The historical worry was old AOSP builds without
+ *   proprietary codecs; the call to treat AAC as universal was made with the
+ *   platform's one real AAC consumer, whose viewer is WebGL — a device that
+ *   cannot decode AAC cannot run that product at all, so the fallback would
+ *   only ever protect a device that had already lost.
+ *
+ * Deliberately NOT here: `audio/webm` and `audio/ogg` (Opus). iOS Safari
+ * cannot decode them, and that is the case the MP3 fallback exists for.
+ */
+export function isUniversallyPlayableAudio(mime: string): boolean {
+  const base = (mime.split(";")[0] ?? "").trim().toLowerCase();
+  return base === "audio/mpeg" || base === "audio/mp4" || base === "audio/aac";
+}

package/src/index.ts

@@ -61,6 +61,7 @@ import {
   type VariantEntryPreset,
   type VariantPreset,
 } from "@nitida/asset-client";
+import { isUniversallyPlayableAudio } from "./audio-compat";
 
 // ---------------------------------------------------------------------------
 // Config
@@ -114,7 +115,9 @@ export type NitidaClientOptions = {
    * only when calling `aq.transform(asset, opts, { sign: true })`.
    *
    * 32 random bytes, generated server-side on tenant creation; fetch
-   * via `GET /admin/tenants/:id` with an admin key. **Keep it
+   * 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.
    */
@@ -207,6 +210,7 @@ export type {
   PaletteSwatch,
   RequestablePreset,
   ResolveSlotOptions,
+  SignAccessOptions,
   SignedTransformOptions,
   SlotDTO,
   SlotResolution,
@@ -218,12 +222,17 @@ export type {
   TransformWidth,
   VariantEntryPreset,
   VariantPreset,
+  VisibilityHint,
 } from "@nitida/asset-client";
 export {
+  accessMessage,
+  assertPublic,
+  assertSha,
   bestTextContrast,
   computeVariantDimensions,
   configureSlotResolver,
   contrastRatio,
+  deriveAccessKey,
   extractAssetSha,
   getAmbientGradient,
   getAssetDimensions,
@@ -234,6 +243,8 @@ export {
   getHlsStreamingUrl,
   getPaletteBlurBackground,
   getPaletteCssVars,
+  getPrivateAssetUrl,
+  getPrivateTransformUrl,
   getSignedTransformUrl,
   getTenantId,
   getTextColorForBackground,
@@ -255,6 +266,7 @@ export {
   serializeTransform,
   setCdnBase,
   setTenantId,
+  signAccessUrl,
   signTransformUrl,
   TRANSFORM_WIDTHS,
 } from "@nitida/asset-client";
@@ -625,9 +637,10 @@ class AssetsApi {
   }
 
   /**
-   * Add or rebuild variants on an existing asset. Image presets are
-   * MERGED with what's there — passing `{ presets: ["thumb"] }` adds
-   * the thumb variant without touching `lg`, `sm`, `original`, etc.
+   * Add or rebuild variants on an existing asset. Presets are MERGED
+   * with what's there, for images AND for video — passing
+   * `{ presets: ["thumb"] }` adds the thumb variant without touching
+   * `lg`, `sm`, `original`, etc.
    *
    *   // Day 0: upload original-only logo
    *   const { assetId } = await aq.upload(logoFile);  // defaults to ["original"]
@@ -646,10 +659,18 @@ class AssetsApi {
    * reading the source bytes from the permanent `original` variant —
    * no need to re-upload.
    *
-   * Video presets are filtered to `["poster","video","aiproxy"]` and
-   * dispatched to a background job (the call returns immediately
+   * Video presets are filtered to `["poster","video","aiproxy","probe"]`
+   * and dispatched to a background job (the call returns immediately
    * with a dispatch handle; poll `aq.assets.get(id).status` for
    * completion).
+   *
+   * ⚠️ Before 2026-08-22 the video path REPLACED the whole variant
+   * registry instead of merging, so a partial regenerate silently
+   * deregistered `poster`, `video` and — irrecoverably — `hls`, which
+   * is not a {@link RequestablePreset} and therefore cannot be asked
+   * for again. The objects kept serving from the CDN; only the
+   * registry died. Fixed server-side; a client on an older server
+   * still loses them.
    */
   async regenerate(
     assetId: string,
@@ -998,6 +1019,22 @@ const DEFAULT_UPLOAD_PRESETS: RequestablePreset[] = ["original"];
 export type UploadResult = {
   assetId: string;
   sha256: string;
+  /**
+   * The SAME 16-hex prefix an `AssetDTO` carries, so the result of an upload can
+   * be handed straight to any URL builder.
+   *
+   * ⭐ It exists because it did not, and that cost a real 404. A Haiku agent
+   * evaluating the SDK on 2026-08-23 did the most natural thing there is —
+   * `transform(await upload(file), { width: 1280 })` — and got
+   * `https://8ok.uk/t/width=1280/undefined.webp`. The builders read `sha`; this
+   * type only had `sha256`. TypeScript caught it; running through `bun`, or in
+   * plain JS, nothing did.
+   *
+   * The guard (`assertSha`) is the backstop. This field is the actual fix: the
+   * obvious call is now the correct one, which is worth more than a good error
+   * message about the wrong one.
+   */
+  sha: string;
   cdnUrl: string;
 };
 
@@ -1158,6 +1195,8 @@ class UsageApi {
   }
 }
 
+export { isUniversallyPlayableAudio } from "./audio-compat";
+
 export class NitidaClient {
   readonly slots: SlotsApi;
   readonly assets: AssetsApi;
@@ -1257,7 +1296,7 @@ export class NitidaClient {
     if (!this.opts.signingKey) {
       throw new Error(
         "aq.transform({ sign: true }) requires `signingKey` in NitidaClientOptions. " +
-          "Pull the tenant's signing key from /admin/tenants/:id and pass it to the SDK constructor on a SERVER-side instance only.",
+          "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.",
       );
     }
     // Signed path — custom (off-ladder) widths allowed. Empty opts → no
@@ -1541,6 +1580,7 @@ export class NitidaClient {
       return {
         assetId: existing.id,
         sha256: sha,
+        sha: sha.slice(0, 16),
         cdnUrl: this.urlFor(existing, this.bestPresetForAsset(existing, mime)),
       };
     }
@@ -1566,6 +1606,7 @@ export class NitidaClient {
       return {
         assetId: presign.asset.id,
         sha256: sha,
+        sha: sha.slice(0, 16),
         cdnUrl: this.urlFor(presign.asset, this.defaultPresetForMime(mime)),
       };
     }
@@ -1616,6 +1657,7 @@ export class NitidaClient {
     return {
       assetId,
       sha256: sha,
+      sha: sha.slice(0, 16),
       cdnUrl: this.urlFor(final, this.bestPresetForAsset(final, mime)),
     };
   }
@@ -1633,15 +1675,35 @@ export class NitidaClient {
    * `presets` string. Falls back through the preference order
    *   lg → md → sm → thumb → original   (for images)
    *   video → poster                    (for videos)
-   *   mp3 → original                    (for audio)
+   *   original → mp3                    (for audio ALREADY playable everywhere)
+   *   mp3 → original                    (for any other audio)
    * so an upload that was processed with e.g. `["original"]` still
    * returns a non-404 URL in `aq.upload`'s result.
+   *
+   * ⭐ Why audio branches on the source mime (changed 2026-08-22).
+   *
+   * It used to be `mp3 → original` unconditionally, so `upload().cdnUrl`
+   * handed back the server's auto-generated mp3 — libmp3lame, mono ~96 kbps —
+   * even when the caller had uploaded an MP3 or an AAC that already plays in
+   * every target browser. A consumer asking for "my file" silently received a
+   * re-encoded, lower-quality one, with no error to notice.
+   *
+   * Measured across the platform: of 126 audio assets carrying an mp3 variant,
+   * **105 had an `audio/mpeg` source** — an MP3 re-encoded into an MP3, for
+   * zero compatibility gain.
+   *
+   * The mp3 still wins for `audio/webm`/Opus and anything exotic, which is the
+   * case it was built for: Chrome records webm/Opus, which iOS Safari cannot
+   * decode. That guarantee is preserved exactly; only the needless downgrade
+   * is gone.
    */
   private bestPresetForAsset(asset: AssetDTO, mime: string): VariantPreset {
     const order: VariantPreset[] = mime.startsWith("video/")
       ? ["video", "poster"]
       : mime.startsWith("audio/")
-        ? ["mp3", "original"] // prefer the cross-browser mp3, else the playable original; never image presets
+        ? isUniversallyPlayableAudio(mime)
+          ? ["original", "mp3"] // the upload already plays everywhere — don't hand back a re-encode
+          : ["mp3", "original"] // exotic codec: the cross-browser mp3 earns its place
         : ["lg", "md", "sm", "thumb", "xl", "original"];
     return (
       order.find((p) => hasPreset(asset, p)) ?? this.defaultPresetForMime(mime)

package/src/server/index.ts

@@ -94,6 +94,9 @@ export {
   type AssetDTO,
   type AssetPalette,
   type AssetVariant,
+  accessMessage,
+  assertPublic,
+  assertSha,
   bestTextContrast,
   type ComposeMarketingComposition,
   type ComposeMarketingOptions,
@@ -103,6 +106,7 @@ export {
   computeVariantDimensions,
   configureSlotResolver,
   contrastRatio,
+  deriveAccessKey,
   extractAssetSha,
   getAmbientGradient,
   getAssetDimensions,
@@ -113,6 +117,8 @@ export {
   getHlsStreamingUrl,
   getPaletteBlurBackground,
   getPaletteCssVars,
+  getPrivateAssetUrl,
+  getPrivateTransformUrl,
   getSignedTransformUrl,
   getTenantId,
   getTextColorForBackground,
@@ -123,6 +129,7 @@ export {
   hasPreset,
   hlsLadderAlignment,
   invalidateSlotCache,
+  isUniversallyPlayableAudio,
   iteratePaletteSwatches,
   mimeFromFileName,
   type NitidaClientOptions,
@@ -139,6 +146,7 @@ export {
   relativeLuminance,
   resolveSlot,
   resolveSlots,
+  type SignAccessOptions,
   type SignedTransformOptions,
   type SlotDTO,
   type SlotHistoryEntry,
@@ -146,6 +154,7 @@ export {
   serializeTransform,
   setCdnBase,
   setTenantId,
+  signAccessUrl,
   signTransformUrl,
   TRANSFORM_WIDTHS,
   type TransformEffect,
@@ -164,4 +173,5 @@ export {
   type UsageWindow,
   type VariantEntryPreset,
   type VariantPreset,
+  type VisibilityHint,
 } from "..";

package/src/web/index.ts

@@ -111,6 +111,9 @@ export {
   type AssetDTO,
   type AssetPalette,
   type AssetVariant,
+  accessMessage,
+  assertPublic,
+  assertSha,
   bestTextContrast,
   type ComposeMarketingComposition,
   type ComposeMarketingOptions,
@@ -120,6 +123,7 @@ export {
   computeVariantDimensions,
   configureSlotResolver,
   contrastRatio,
+  deriveAccessKey,
   extractAssetSha,
   getAmbientGradient,
   getAssetDimensions,
@@ -130,6 +134,8 @@ export {
   getHlsStreamingUrl,
   getPaletteBlurBackground,
   getPaletteCssVars,
+  getPrivateAssetUrl,
+  getPrivateTransformUrl,
   getSignedTransformUrl,
   getTenantId,
   getTextColorForBackground,
@@ -140,6 +146,7 @@ export {
   hasPreset,
   hlsLadderAlignment,
   invalidateSlotCache,
+  isUniversallyPlayableAudio,
   iteratePaletteSwatches,
   mimeFromFileName,
   type PaletteSwatch,
@@ -155,6 +162,7 @@ export {
   relativeLuminance,
   resolveSlot,
   resolveSlots,
+  type SignAccessOptions,
   type SignedTransformOptions,
   type SlotDTO,
   type SlotHistoryEntry,
@@ -162,6 +170,7 @@ export {
   serializeTransform,
   setCdnBase,
   setTenantId,
+  signAccessUrl,
   signTransformUrl,
   TRANSFORM_WIDTHS,
   type TransformEffect,
@@ -180,6 +189,7 @@ export {
   type UsageWindow,
   type VariantEntryPreset,
   type VariantPreset,
+  type VisibilityHint,
 } from "..";
 
 // Multipart uploader helpers are NOT re-exported from this subpath.