@nitida/sdk 0.26.0 → 0.27.0

package/AGENTS.md

@@ -74,6 +74,68 @@ version of this file, verify against the `.d.ts` you actually installed.
    ASYNCHRONOUSLY: the call answers `{ assetId, status: "processing" }` and a background job flips
    it to `ready` 1–2 min later, so `processAndWait` needs a `timeoutMs` of at least `300_000`.
 
+
+## 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 carries `visibility`. `{ sha }` alone is never
+  refused.
+- **`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
+// Ask for the rungs you will actually render…
+await aq.upload(file, { presets: ["original", "thumb", "md", "lg"] });
+
+// …or upload bare and let the transform route make them on demand:
+aq.transform(asset, { width: 1280, format: "webp" });   // → /t/…, cached after the first hit
+```
+
+**`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. Prefer naming the presets when you know what you will render.
+
+⚠️ `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.
+
 ## Related packages
 
 | Package | Job |

package/README.md

@@ -832,8 +832,9 @@ const asset = await aq.assets.byHash(sha256);
 | `dpr` | `1` / `2` / `3` | `1` |
 
 > **`width` is strongly typed.** `TransformOptions.width` is a **`TransformWidth`** — the
-> predefined CDN ladder (`160, 240, 256, 320, 400, 480, 600, 640, 800, 960, 1080, 1200,
-> 1280, 1440, 1600, 1920, 2560, 3840`, exported as `TRANSFORM_WIDTHS`). An off-ladder
+> predefined CDN ladder (`96, 128, 160, 240, 256, 320, 400, 480, 600, 640, 800, 960,
+> 1080, 1200, 1280, 1440, 1600, 1920, 2560, 3840` — 20 widths, exported as
+> `TRANSFORM_WIDTHS`). An off-ladder
 > width is a **compile error**: the edge whitelists exactly these as a DoS guard and
 > HTTP 400s anything else on unsigned URLs. Need a custom off-ladder width? **Sign it** —
 > `aq.transform(asset, { width: 1490 }, { sign: true })` and `getSignedTransformUrl` take
@@ -926,6 +927,66 @@ hex-encoded. The server canonicalizes the URL the same way the SDK does
 (sort keys, lowercase strings), so two URLs with the same params in
 different order accept the same signature.
 
+## Private assets — `visibility`
+
+Every asset carries `visibility`, and the default is `"public"`.
+
+| | `"public"` | `"private"` |
+|---|---|---|
+| stored variants, raw, HLS ladder, transforms | served to anyone with the URL | **404**, to everyone |
+| how the bytes come back | the URL | a signed URL under `/a/{tenant}/…?exp&sig` |
+| expiry | none | mandatory |
+| edge caching | shared, effectively free | `private`, per-viewer |
+
+```ts
+// Flip it (write scope):
+await fetch(`${endpoint}/assets/${assetId}/visibility`, {
+  method: "PATCH",
+  headers: { Authorization: `Bearer ${apiKey}`, "X-Tenant-Code": code,
+             "Content-Type": "application/json" },
+  body: JSON.stringify({ visibility: "private" }),
+});
+
+// Hand a viewer the bytes — ON YOUR BACKEND:
+import { getPrivateAssetUrl, getPrivateTransformUrl } from "@nitida/sdk";
+
+const url = await getPrivateAssetUrl(asset, "lg", signingKey, {
+  expiresInSeconds: 300,
+});
+// → https://8ok.uk/a/5/v/<sha>-l.webp?exp=…&sig=…
+
+// …or any width/crop/format, not just the materialised ones:
+const resized = await getPrivateTransformUrl(
+  asset,
+  { width: 1280, format: "webp" },
+  signingKey,
+  { expiresInSeconds: 300 },
+);
+// → https://8ok.uk/a/5/t/format=webp,width=1280/<sha>.webp?exp=…&sig=…
+```
+
+Nothing moves when you flip it: one row changes and the edge cache for that
+asset is purged, so a 1 GB video flips as fast as a thumbnail. It is the same
+single copy behind both doors.
+
+**Four things worth knowing before you rely on it:**
+
+1. **A 404 on a private asset is the feature, not a missing file.** Everywhere
+   else here a 404 means the object was never written. Check `visibility` on
+   the DTO before you check storage.
+2. **The SDK refuses instead of handing you a URL that 404s.** `getAssetUrl`,
+   `getAssetSrcSet`, `getTransformUrl`, `getTransformSrcSet`,
+   `getVideoTransformUrl` and `getHlsStreamingUrl` all throw when the value you
+   pass says `visibility: "private"` — with a message naming
+   `getPrivateAssetUrl`. Pass only `{ sha }` and there is nothing to check.
+3. **Revocation is "within a minute".** Flipping back to `private` really does
+   kill URLs already handed out — the edge is purged — but the CDN refreshes
+   its list of private assets on a 60-second TTL.
+4. **The signing key is a backend secret.** It mints URLs for every private
+   asset the tenant owns. It is a different claim from the transform `?sig=`
+   above, computed under a separately derived key, so a signature minted to
+   resize can never be replayed as one to enter.
+
 ### ⚠️ Admin operations need the SYSTEM key, not the admin key in your triplet
 
 Both are `amk_ad_*`, and that is the whole trap. The `admin` key issued with

package/dist/index.d.ts

@@ -1,5 +1,39 @@
 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, SignedTransformOptions, SlotDTO, SlotResolution, TRANSFORM_WIDTHS, TransformEffect, TransformFit, TransformFormat, TransformGravity, TransformOptions, TransformWidth, VariantEntryPreset, VariantPreset, bestTextContrast, computeVariantDimensions, configureSlotResolver, contrastRatio, extractAssetSha, getAmbientGradient, getAssetDimensions, getAssetSrcSet, getAssetUrl, getCdnBase, getHlsLadder, getHlsStreamingUrl, getPaletteBlurBackground, getPaletteCssVars, getSignedTransformUrl, getTenantId, getTextColorForBackground, getTransformSrcSet, getTransformUrl, getVideoTransformUrl, hasPreset, hlsLadderAlignment, invalidateSlotCache, iteratePaletteSwatches, pickAmbientBackground, relativeLuminance, resolveSlot, resolveSlots, serializeTransform, setCdnBase, setTenantId, signTransformUrl } 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, 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';
+
+/**
+ * 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.
+ */
+declare function isUniversallyPlayableAudio(mime: string): boolean;
 
 /**
  * @nitida/sdk — universal client for the aquienpz multi-tenant asset
@@ -86,7 +120,9 @@ 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.
      */
@@ -329,9 +365,10 @@ declare class AssetsApi {
      */
     variants(assetId: string): Promise<AssetVariant[]>;
     /**
-     * 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"]
@@ -350,10 +387,18 @@ declare 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.
      */
     regenerate(assetId: string, opts?: {
         presets?: RequestablePreset[];
@@ -647,6 +692,7 @@ declare class UsageApi {
     }>;
     private headers;
 }
+
 declare class NitidaClient {
     readonly slots: SlotsApi;
     readonly assets: AssetsApi;
@@ -822,11 +868,29 @@ declare 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;
 }
 
-export { type ComposeMarketingComposition, type ComposeMarketingOptions, type ComposeMarketingResult, type ComposeMarketingSegment, type CompressOptions, NitidaClient, type NitidaClientOptions, type PresignUploadUrlOptions, type RegenerateResult, type SlotHistoryEntry, type UploadOptions, type UploadResult, type UploadUrlResult, type UploadVideoOptions, type UsageDailyPoint, type UsagePerKey, type UsageSnapshot, type UsageWindow, mimeFromFileName };
+export { type ComposeMarketingComposition, type ComposeMarketingOptions, type ComposeMarketingResult, type ComposeMarketingSegment, type CompressOptions, NitidaClient, type NitidaClientOptions, type PresignUploadUrlOptions, type RegenerateResult, type SlotHistoryEntry, type UploadOptions, type UploadResult, type UploadUrlResult, type UploadVideoOptions, type UsageDailyPoint, type UsagePerKey, type UsageSnapshot, type UsageWindow, isUniversallyPlayableAudio, mimeFromFileName };

package/dist/index.js

@@ -15,11 +15,22 @@ import {
   setCdnBase,
   setTenantId
 } from "@nitida/asset-client";
+
+// src/audio-compat.ts
+function isUniversallyPlayableAudio(mime) {
+  const base = (mime.split(";")[0] ?? "").trim().toLowerCase();
+  return base === "audio/mpeg" || base === "audio/mp4" || base === "audio/aac";
+}
+
+// src/index.ts
 import {
+  accessMessage,
+  assertPublic,
   bestTextContrast,
   computeVariantDimensions,
   configureSlotResolver as configureSlotResolver2,
   contrastRatio,
+  deriveAccessKey,
   extractAssetSha,
   getAmbientGradient,
   getAssetDimensions,
@@ -30,6 +41,8 @@ import {
   getHlsStreamingUrl as getHlsStreamingUrl2,
   getPaletteBlurBackground,
   getPaletteCssVars,
+  getPrivateAssetUrl,
+  getPrivateTransformUrl,
   getSignedTransformUrl as getSignedTransformUrl2,
   getTenantId,
   getTextColorForBackground,
@@ -51,6 +64,7 @@ import {
   serializeTransform,
   setCdnBase as setCdnBase2,
   setTenantId as setTenantId2,
+  signAccessUrl,
   signTransformUrl,
   TRANSFORM_WIDTHS
 } from "@nitida/asset-client";
@@ -256,9 +270,10 @@ var AssetsApi = class {
     return Array.isArray(dto.variants) ? dto.variants : [];
   }
   /**
-   * 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"]
@@ -277,10 +292,18 @@ var AssetsApi = class {
    * 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, opts = {}) {
     const r = await fetch(
@@ -548,7 +571,7 @@ var NitidaClient = class {
     }
     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."
+        "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."
       );
     }
     return getSignedTransformUrl(asset, opts, this.opts.signingKey) ?? Promise.resolve(this.urlFor(asset, "lg"));
@@ -800,12 +823,30 @@ var NitidaClient = class {
    * `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.
    */
   bestPresetForAsset(asset, mime) {
-    const order = mime.startsWith("video/") ? ["video", "poster"] : mime.startsWith("audio/") ? ["mp3", "original"] : ["lg", "md", "sm", "thumb", "xl", "original"];
+    const order = mime.startsWith("video/") ? ["video", "poster"] : mime.startsWith("audio/") ? isUniversallyPlayableAudio(mime) ? ["original", "mp3"] : ["mp3", "original"] : ["lg", "md", "sm", "thumb", "xl", "original"];
     return order.find((p) => hasPreset(asset, p)) ?? this.defaultPresetForMime(mime);
   }
 };
@@ -816,10 +857,13 @@ export {
   PRESET_MAX_DIM,
   PRESET_SHORT,
   TRANSFORM_WIDTHS,
+  accessMessage,
+  assertPublic,
   bestTextContrast,
   computeVariantDimensions,
   configureSlotResolver2 as configureSlotResolver,
   contrastRatio,
+  deriveAccessKey,
   extractAssetSha,
   getAmbientGradient,
   getAssetDimensions,
@@ -830,6 +874,8 @@ export {
   getHlsStreamingUrl2 as getHlsStreamingUrl,
   getPaletteBlurBackground,
   getPaletteCssVars,
+  getPrivateAssetUrl,
+  getPrivateTransformUrl,
   getSignedTransformUrl2 as getSignedTransformUrl,
   getTenantId,
   getTextColorForBackground,
@@ -839,6 +885,7 @@ export {
   hasPreset2 as hasPreset,
   hlsLadderAlignment,
   invalidateSlotCache2 as invalidateSlotCache,
+  isUniversallyPlayableAudio,
   iteratePaletteSwatches,
   mimeFromFileName,
   pickAmbientBackground,
@@ -848,6 +895,7 @@ export {
   serializeTransform,
   setCdnBase2 as setCdnBase,
   setTenantId2 as setTenantId,
+  signAccessUrl,
   signTransformUrl
 };
 //# sourceMappingURL=index.js.map