@nitida/asset-client 0.16.4 → 0.18.0

package/AGENTS.md

@@ -8,6 +8,34 @@ version-pinned answer rather than recalling an API from training data.
 This package **builds URLs**. It makes no network calls and takes no API key. If the task involves
 uploading, that is `@nitida/sdk` — and its `skills/nitida-sdk/SKILL.md` is the deeper guide.
 
+## Where these symbols also live
+
+All **53** exports of this package are re-exported by `@nitida/sdk`, and by its
+`/server` and `/web` subpaths alike — a consumer that already installed the SDK
+never needs a second import, from any of the three.
+
+That is asserted in CI, not maintained by hand. ⚠️ It was **not** true before
+2026-08-21: `/server` was short 28 of the root's 72 exports and `/web` short 37,
+the palette helpers, the slot helpers, the HLS-ladder helpers and the preset
+constants among them. If you are on an older `@nitida/sdk`, import them from
+the root or from this package.
+
+## ⚠️ `RequestablePreset` is not `VariantPreset`
+
+Two sets, two types. What a variant can **be** is not what you can **ask for**.
+
+| | ask for it | a variant can be it |
+|---|---|---|
+| `thumb` `sm` `md` `lg` `xl` `original` `poster` `video` `aiproxy` | ✅ | ✅ |
+| `hls` — the ladder, built when a video transcodes | ❌ | ✅ |
+| `mp3` — emitted by itself alongside any audio original | ❌ | ✅ |
+| `probe` — indexed stills, never on the compact `presets` string | ✅ | ❌ |
+
+`regenerate(id, { presets: ["hls"] })` and `upload(f, { presets: ["mp3"] })`
+used to compile and answer **HTTP 400**. Three agents hit that in one
+afternoon. They are compile errors now. Checked in CI against the server's own
+schemas, not against a hand-kept list.
+
 ## The three that are wrong most often
 
 1. **Image widths must be on `TRANSFORM_WIDTHS`.** Any other width is **HTTP 400** at the edge.
@@ -38,6 +66,32 @@ now emits only the 1-char vocabulary, and `hasPreset` strips multi-char tokens b
 either half covers you — a hand-rolled `includes` covers neither. **`mp3` is a deliberate multi-char
 token that stays in the vocabulary**, so a naive test also reads its `m` as `md`.
 
+
+## 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.
+
 ## The endpoint
 
 The API this client's URLs belong to is `https://api.nitida.gofuture.space`. An older, longer

package/README.md

@@ -9,6 +9,17 @@ to **upload**, that is `@nitida/sdk` (which re-exports everything here).
 bun add @nitida/asset-client
 ```
 
+## Where these symbols live
+
+Everything documented here is exported by **`@nitida/asset-client`**, and all
+53 exports are re-exported by the root **`@nitida/sdk`** — if you already
+installed the SDK, importing from its root works and needs no second dependency.
+
+`@nitida/sdk/server` and `@nitida/sdk/web` carry the same 53 as well, so any of
+the three works. ⚠️ Not so before 2026-08-21 — `/server` was short 28 of the
+root's exports and `/web` short 37. On an older SDK, import these from the root
+or from this package.
+
 ## Configure once, at module load
 
 The builders read **process-global** config, so pin it where your helpers live — every Server and
@@ -33,7 +44,7 @@ getTransformSrcSet({ sha }, [640, 960, 1280], { format: "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`). Anything else
+(`96,128,160,240,256,320,400,480,600,640,800,960,1080,1200,1280,1440,1600,1920,2560,3840` — 20 widths). Anything else
 is **HTTP 400** at the edge — it is a DoS guard, not a bug. Import the `TransformWidth` type and an
 off-ladder number becomes a compile error instead of a runtime 400.
 
@@ -51,7 +62,10 @@ getAssetUrl({ sha }, "video");   // → https://8ok.uk/<tenantId base36>/v/<sha1
 `getAssetUrl` build the path.
 
 ⚠️ **Never `getVideoTransformUrl` for a stored video.** That builds a `/t/…` transform URL, which
-**410s** for a stored video sha. It is for on-the-fly re-encodes, a different feature.
+does NOT give you the video. On a video sha it transforms the **poster frame**
+and answers `200 image/webp` (`x-transform-source: poster`) — useful, but an
+image. If that video has no poster it answers `410`. Either way you never get
+playable video out of `/t/`; use `getAssetUrl(asset, "video")`.
 
 ## The `original` variant
 
@@ -66,6 +80,20 @@ getAssetUrl({ sha, mime }, "original");        // → …-o.webp ✓
 those disagree (`image/jpeg` → `jpeg`, but a camera writes `.jpg`) — measured, `-o.jpeg` **404s**
 while `-o.jpg` is 200. If the URL must be right, **verify it with a HEAD** before relying on it.
 
+## Asking for a preset vs. a preset existing
+
+`VariantPreset` is what a variant can **be**. `RequestablePreset` is what you
+can **ask for**. They overlap in nine values and differ in three:
+
+- **`hls`** and **`mp3`** exist but cannot be ordered — the ladder is built when
+  a video transcodes, the mp3 is emitted alongside any audio original.
+- **`probe`** can be ordered but never reaches the compact `presets` string, so
+  it is not a `VariantPreset`.
+
+Sending either of the first two answers **HTTP 400**; the write methods now take
+`RequestablePreset[]`, so it is a compile error instead. A CI check reads the
+server's own schemas and asserts the type still matches them.
+
 ## Which presets exist
 
 Read `dto.presets` — the compact code string (`"oq"` = original + thumb, `"pv"` = poster + video) —
@@ -94,7 +122,7 @@ shape. `presets` is populated everywhere, on every version — so read existence
 | Symptom | Cause |
 |---|---|
 | **400** on an image URL | width not on `TRANSFORM_WIDTHS` |
-| **410** on a video URL | used `/t/` (transform) for a stored video |
+| **410** on a video `/t/` URL | that video has no `poster` variant. With one, `/t/` returns the poster as an image — never the video. Use `getAssetUrl(asset, "video")` |
 | **404** on a video URL | decimal tenant prefix instead of base36 |
 | `original` 404s | no `mime` passed, or the stored ext came from the filename (`-o.jpg` vs `-o.jpeg`), or it was never written |
 

package/dist/index.cjs

@@ -25,10 +25,13 @@ __export(index_exports, {
   PRESET_MAX_DIM: () => PRESET_MAX_DIM,
   PRESET_SHORT: () => PRESET_SHORT,
   TRANSFORM_WIDTHS: () => TRANSFORM_WIDTHS,
+  accessMessage: () => accessMessage,
+  assertPublic: () => assertPublic,
   bestTextContrast: () => bestTextContrast,
   computeVariantDimensions: () => computeVariantDimensions,
   configureSlotResolver: () => configureSlotResolver,
   contrastRatio: () => contrastRatio,
+  deriveAccessKey: () => deriveAccessKey,
   extractAssetSha: () => extractAssetSha,
   getAmbientGradient: () => getAmbientGradient,
   getAssetDimensions: () => getAssetDimensions,
@@ -39,6 +42,8 @@ __export(index_exports, {
   getHlsStreamingUrl: () => getHlsStreamingUrl,
   getPaletteBlurBackground: () => getPaletteBlurBackground,
   getPaletteCssVars: () => getPaletteCssVars,
+  getPrivateAssetUrl: () => getPrivateAssetUrl,
+  getPrivateTransformUrl: () => getPrivateTransformUrl,
   getSignedTransformUrl: () => getSignedTransformUrl,
   getTenantId: () => getTenantId,
   getTextColorForBackground: () => getTextColorForBackground,
@@ -56,10 +61,81 @@ __export(index_exports, {
   serializeTransform: () => serializeTransform,
   setCdnBase: () => setCdnBase,
   setTenantId: () => setTenantId,
+  signAccessUrl: () => signAccessUrl,
   signTransformUrl: () => signTransformUrl
 });
 module.exports = __toCommonJS(index_exports);
 
+// src/access.ts
+var ACCESS_KEY_INFO = "nitida/access/v1";
+async function hmac(key, message) {
+  const cryptoKey = await crypto.subtle.importKey(
+    "raw",
+    key,
+    { name: "HMAC", hash: "SHA-256" },
+    false,
+    ["sign"]
+  );
+  return new Uint8Array(
+    await crypto.subtle.sign(
+      "HMAC",
+      cryptoKey,
+      new TextEncoder().encode(message)
+    )
+  );
+}
+var toHex = (b) => [...b].map((x) => x.toString(16).padStart(2, "0")).join("");
+async function deriveAccessKey(signingKey) {
+  return hmac(new TextEncoder().encode(signingKey), ACCESS_KEY_INFO);
+}
+function accessMessage(tenantPrefix, exp, resourcePath) {
+  return `${tenantPrefix}
+${exp}
+${resourcePath.replace(/^\/+/, "")}`;
+}
+async function signAccessUrl(publicUrl, signingKey, opts) {
+  if (!Number.isFinite(opts.expiresInSeconds) || opts.expiresInSeconds <= 0) {
+    throw new Error(
+      "signAccessUrl: `expiresInSeconds` must be a positive number \u2014 a signed URL without an expiry is a public URL the moment it is forwarded."
+    );
+  }
+  const u = new URL(publicUrl);
+  const segments = u.pathname.split("/").filter(Boolean);
+  if (segments[0] === "a" && segments[2] && /^[vrt]$/.test(segments[2])) {
+    segments.shift();
+  }
+  const tenantPrefix = segments.shift();
+  if (!tenantPrefix || segments.length === 0) {
+    throw new Error(
+      `signAccessUrl: expected a tenant-prefixed CDN path like /<tenant>/v/<sha>-<preset>.<ext>, got ${u.pathname}`
+    );
+  }
+  if (!/^[vrt]$/.test(segments[0])) {
+    throw new Error(
+      `signAccessUrl: expected /<tenant>/<v|r|t>/\u2026 but the segment after the tenant is "${segments[0]}". ` + (segments[0]?.includes("=") ? `That looks like a transform DSL, so the path is probably /t/<dsl>/<sha>.<ext> \u2014 which has no tenant in it (\`t\` here was read as tenant ${Number.parseInt(tenantPrefix, 36)}). Use getPrivateTransformUrl(asset, opts, signingKey, { expiresInSeconds }) instead.` : `Got ${u.pathname}.`)
+    );
+  }
+  const resourcePath = segments.join("/");
+  const now = opts.nowSeconds ?? Math.floor(Date.now() / 1e3);
+  const exp = now + Math.floor(opts.expiresInSeconds);
+  const sig = toHex(
+    await hmac(
+      await deriveAccessKey(signingKey),
+      accessMessage(tenantPrefix, exp, resourcePath)
+    )
+  );
+  u.pathname = `/a/${tenantPrefix}/${resourcePath}`;
+  u.searchParams.set("exp", String(exp));
+  u.searchParams.set("sig", sig);
+  return u.toString();
+}
+function assertPublic(asset, fn, escape) {
+  if (asset.visibility !== "private") return;
+  throw new Error(
+    `${fn}: this asset is private, so a public CDN URL for it will answer 404 \u2014 that is the feature, not a missing file. Mint a signed URL on your BACKEND instead: await ${escape}. Never ship the signing key to a browser.`
+  );
+}
+
 // src/palette.ts
 function resolveSwatch(palette, ...keys) {
   if (!palette) return null;
@@ -77,9 +153,9 @@ function pickAmbientBackground(palette) {
 function getAmbientGradient(palette, opts = {}) {
   if (!palette) return void 0;
   const fromHex = palette[opts.from ?? "lm"] ?? palette.m ?? palette.d;
-  const toHex = palette[opts.to ?? "m"] ?? palette.dm ?? palette.d;
-  if (!fromHex || !toHex) return void 0;
-  return `linear-gradient(${opts.angle ?? "135deg"}, ${fromHex}, ${toHex})`;
+  const toHex2 = palette[opts.to ?? "m"] ?? palette.dm ?? palette.d;
+  if (!fromHex || !toHex2) return void 0;
+  return `linear-gradient(${opts.angle ?? "135deg"}, ${fromHex}, ${toHex2})`;
 }
 function getTextColorForBackground(swatch) {
   if (!swatch) return "#000000";
@@ -164,102 +240,6 @@ function getPaletteBlurBackground(palette) {
   return layers.length > 0 ? `${layers.join(", ")}, ${base}` : base;
 }
 
-// src/slots.ts
-var DEFAULT_TTL_MS = 6e4;
-var cache = /* @__PURE__ */ new Map();
-var endpoint = "https://api.nitida.gofuture.space";
-var apiKey = null;
-var tenantCode = null;
-function configureSlotResolver(opts) {
-  if (opts.endpoint) endpoint = opts.endpoint.replace(/\/+$/, "");
-  if (opts.apiKey !== void 0) apiKey = opts.apiKey;
-  if (opts.tenantCode !== void 0) tenantCode = opts.tenantCode;
-}
-function invalidateSlotCache(slotKey) {
-  if (slotKey === void 0) cache.clear();
-  else
-    for (const k of cache.keys())
-      if (k.endsWith(`:${slotKey}`)) cache.delete(k);
-}
-var baseHeaders = () => {
-  const h = {};
-  if (apiKey) h.Authorization = `Bearer ${apiKey}`;
-  if (tenantCode) h["X-Tenant-Code"] = tenantCode;
-  return h;
-};
-async function fetchSlot(slotKey) {
-  const r = await fetch(`${endpoint}/slots/${encodeURIComponent(slotKey)}`, {
-    headers: baseHeaders()
-  });
-  if (r.status === 404) return null;
-  if (!r.ok) throw new Error(`slot fetch ${r.status}: ${await r.text()}`);
-  return await r.json();
-}
-async function fetchSlotsBulk(slotKeys) {
-  if (slotKeys.length === 0) return {};
-  const r = await fetch(`${endpoint}/slots/resolve`, {
-    method: "POST",
-    headers: { ...baseHeaders(), "Content-Type": "application/json" },
-    body: JSON.stringify({ keys: slotKeys })
-  });
-  if (!r.ok) throw new Error(`slots resolve ${r.status}: ${await r.text()}`);
-  const body = await r.json();
-  return body.resolved;
-}
-async function resolveSlot(slotKey, opts = {}) {
-  const ttl = opts.ttlMs ?? DEFAULT_TTL_MS;
-  const cacheKey = `${tenantCode ?? "_"}:${slotKey}`;
-  const now = Date.now();
-  let dto;
-  const hit = cache.get(cacheKey);
-  if (hit && now - hit.fetchedAt < ttl) {
-    dto = hit.value;
-  } else {
-    dto = await fetchSlot(slotKey);
-    cache.set(cacheKey, { fetchedAt: now, value: dto });
-  }
-  return materializeResolution(dto, opts.preset);
-}
-async function resolveSlots(slotKeys, opts = {}) {
-  if (slotKeys.length === 0) return {};
-  const ttl = opts.ttlMs ?? DEFAULT_TTL_MS;
-  const now = Date.now();
-  const missing = [];
-  const out = {};
-  for (const k of slotKeys) {
-    const cacheKey = `${tenantCode ?? "_"}:${k}`;
-    const hit = cache.get(cacheKey);
-    if (hit && now - hit.fetchedAt < ttl) {
-      out[k] = materializeResolution(hit.value, opts.preset);
-    } else {
-      missing.push(k);
-    }
-  }
-  if (missing.length > 0) {
-    const resolved = await fetchSlotsBulk(missing);
-    for (const k of missing) {
-      const dto = resolved[k] ?? null;
-      cache.set(`${tenantCode ?? "_"}:${k}`, { fetchedAt: now, value: dto });
-      out[k] = materializeResolution(dto, opts.preset);
-    }
-  }
-  return out;
-}
-function defaultPresetFor(asset) {
-  if (!asset) return "lg";
-  return asset.kind === "video" ? "video" : "lg";
-}
-function materializeResolution(dto, overridePreset) {
-  if (!dto) return { slot: null, preset: overridePreset ?? "lg", url: null };
-  const effective = overridePreset ?? dto.preset ?? defaultPresetFor(dto.asset);
-  const finalPreset = hasPreset(dto.asset, effective) ? effective : defaultPresetFor(dto.asset);
-  return {
-    slot: dto,
-    preset: finalPreset,
-    url: getAssetUrl(dto.asset, finalPreset)
-  };
-}
-
 // src/transform.ts
 var TRANSFORM_WIDTHS = [
   96,
@@ -331,12 +311,22 @@ function extForOptions(opts) {
   }
 }
 function getVideoTransformUrl(asset, opts) {
+  assertPublic(
+    asset,
+    "getVideoTransformUrl",
+    "getPrivateTransformUrl(asset, opts, signingKey, { expiresInSeconds: 300 })"
+  );
   const dsl = serializeTransform(opts);
   if (!dsl) return null;
   const ext = opts.format === "webm" ? "webm" : "mp4";
   return `${getCdnBase()}/t/${dsl}/${asset.sha}.${ext}`;
 }
 function getHlsStreamingUrl(asset, opts = {}) {
+  assertPublic(
+    asset,
+    "getHlsStreamingUrl",
+    'getPrivateAssetUrl(asset, "hls", signingKey, { expiresInSeconds: 300 }) \u2014 the worker re-signs the playlist children'
+  );
   const merged = { ...opts, format: "hls" };
   const dsl = serializeTransform(merged);
   return `${getCdnBase()}/t/${dsl}/${asset.sha}.m3u8`;
@@ -348,9 +338,19 @@ function buildTransformUrl(asset, opts) {
   return `${getCdnBase()}/t/${dsl}/${asset.sha}.${ext}`;
 }
 function getTransformUrl(asset, opts) {
+  assertPublic(
+    asset,
+    "getTransformUrl",
+    "getPrivateTransformUrl(asset, opts, signingKey, { expiresInSeconds: 300 })"
+  );
   return buildTransformUrl(asset, opts);
 }
 function getSignedTransformUrl(asset, opts, signingKey) {
+  assertPublic(
+    asset,
+    "getSignedTransformUrl",
+    "getPrivateTransformUrl(asset, opts, signingKey, { expiresInSeconds: 300 })"
+  );
   const url = buildTransformUrl(asset, opts);
   if (!url) return null;
   return signTransformUrl(url, signingKey);
@@ -381,12 +381,113 @@ async function hmacSha256Hex(key, message) {
   return [...new Uint8Array(buf)].map((b) => b.toString(16).padStart(2, "0")).join("");
 }
 function getTransformSrcSet(asset, widths, extraOpts = {}) {
+  assertPublic(
+    asset,
+    "getTransformSrcSet",
+    "getPrivateTransformUrl(asset, opts, signingKey, { expiresInSeconds: 300 }) per width"
+  );
   return widths.map((w) => {
     const url = buildTransformUrl(asset, { ...extraOpts, width: w });
     return url ? `${url} ${w}w` : null;
   }).filter((s) => s != null).join(", ");
 }
 
+// src/slots.ts
+var DEFAULT_TTL_MS = 6e4;
+var cache = /* @__PURE__ */ new Map();
+var endpoint = "https://api.nitida.gofuture.space";
+var apiKey = null;
+var tenantCode = null;
+function configureSlotResolver(opts) {
+  if (opts.endpoint) endpoint = opts.endpoint.replace(/\/+$/, "");
+  if (opts.apiKey !== void 0) apiKey = opts.apiKey;
+  if (opts.tenantCode !== void 0) tenantCode = opts.tenantCode;
+}
+function invalidateSlotCache(slotKey) {
+  if (slotKey === void 0) cache.clear();
+  else
+    for (const k of cache.keys())
+      if (k.endsWith(`:${slotKey}`)) cache.delete(k);
+}
+var baseHeaders = () => {
+  const h = {};
+  if (apiKey) h.Authorization = `Bearer ${apiKey}`;
+  if (tenantCode) h["X-Tenant-Code"] = tenantCode;
+  return h;
+};
+async function fetchSlot(slotKey) {
+  const r = await fetch(`${endpoint}/slots/${encodeURIComponent(slotKey)}`, {
+    headers: baseHeaders()
+  });
+  if (r.status === 404) return null;
+  if (!r.ok) throw new Error(`slot fetch ${r.status}: ${await r.text()}`);
+  return await r.json();
+}
+async function fetchSlotsBulk(slotKeys) {
+  if (slotKeys.length === 0) return {};
+  const r = await fetch(`${endpoint}/slots/resolve`, {
+    method: "POST",
+    headers: { ...baseHeaders(), "Content-Type": "application/json" },
+    body: JSON.stringify({ keys: slotKeys })
+  });
+  if (!r.ok) throw new Error(`slots resolve ${r.status}: ${await r.text()}`);
+  const body = await r.json();
+  return body.resolved;
+}
+async function resolveSlot(slotKey, opts = {}) {
+  const ttl = opts.ttlMs ?? DEFAULT_TTL_MS;
+  const cacheKey = `${tenantCode ?? "_"}:${slotKey}`;
+  const now = Date.now();
+  let dto;
+  const hit = cache.get(cacheKey);
+  if (hit && now - hit.fetchedAt < ttl) {
+    dto = hit.value;
+  } else {
+    dto = await fetchSlot(slotKey);
+    cache.set(cacheKey, { fetchedAt: now, value: dto });
+  }
+  return materializeResolution(dto, opts.preset);
+}
+async function resolveSlots(slotKeys, opts = {}) {
+  if (slotKeys.length === 0) return {};
+  const ttl = opts.ttlMs ?? DEFAULT_TTL_MS;
+  const now = Date.now();
+  const missing = [];
+  const out = {};
+  for (const k of slotKeys) {
+    const cacheKey = `${tenantCode ?? "_"}:${k}`;
+    const hit = cache.get(cacheKey);
+    if (hit && now - hit.fetchedAt < ttl) {
+      out[k] = materializeResolution(hit.value, opts.preset);
+    } else {
+      missing.push(k);
+    }
+  }
+  if (missing.length > 0) {
+    const resolved = await fetchSlotsBulk(missing);
+    for (const k of missing) {
+      const dto = resolved[k] ?? null;
+      cache.set(`${tenantCode ?? "_"}:${k}`, { fetchedAt: now, value: dto });
+      out[k] = materializeResolution(dto, opts.preset);
+    }
+  }
+  return out;
+}
+function defaultPresetFor(asset) {
+  if (!asset) return "lg";
+  return asset.kind === "video" ? "video" : "lg";
+}
+function materializeResolution(dto, overridePreset) {
+  if (!dto) return { slot: null, preset: overridePreset ?? "lg", url: null };
+  const effective = overridePreset ?? dto.preset ?? defaultPresetFor(dto.asset);
+  const finalPreset = hasPreset(dto.asset, effective) ? effective : defaultPresetFor(dto.asset);
+  return {
+    slot: dto,
+    preset: finalPreset,
+    url: getAssetUrl(dto.asset, finalPreset)
+  };
+}
+
 // src/index.ts
 var PRESET_SHORT = {
   thumb: "q",
@@ -513,6 +614,23 @@ function originalExtForMime(mime) {
   return (mime ? ORIGINAL_EXT_BY_MIME[mime] : void 0) ?? PRESET_EXT.original;
 }
 function getAssetUrl(asset, preset) {
+  assertPublic(
+    asset,
+    "getAssetUrl",
+    `getPrivateAssetUrl(asset, "${preset}", signingKey, { expiresInSeconds: 300 })`
+  );
+  const fallback = transformFallbackFor(asset, preset);
+  if (fallback) return fallback;
+  return buildPublicAssetUrl(asset, preset);
+}
+function transformFallbackFor(asset, preset) {
+  if (typeof asset.presets !== "string") return null;
+  if (hasPreset({ presets: asset.presets }, preset)) return null;
+  const maxDim = PRESET_MAX_DIM[preset];
+  if (maxDim == null) return null;
+  return `${cdnBaseUrl}/t/format=webp,width=${maxDim}/${asset.sha}.webp`;
+}
+function buildPublicAssetUrl(asset, preset) {
   if (preset === "original") {
     const stored = asset.variants?.find((v) => v.preset === "original")?.url;
     if (stored) return stored;
@@ -526,6 +644,25 @@ function getAssetUrl(asset, preset) {
   }
   return `${cdnBaseUrl}/${variantPrefix()}${asset.sha}-${PRESET_SHORT[preset]}.${PRESET_EXT[preset]}`;
 }
+async function getPrivateAssetUrl(asset, preset, signingKey, opts) {
+  return signAccessUrl(buildPublicAssetUrl(asset, preset), signingKey, opts);
+}
+async function getPrivateTransformUrl(asset, opts, signingKey, signOpts) {
+  const url = buildTransformUrl(asset, opts);
+  if (!url) return null;
+  const tid = getTenantId();
+  if (tid == null) {
+    throw new Error(
+      "getPrivateTransformUrl: no tenant is configured. Call setTenantId(id) (or construct a NitidaClient with `tenantId`) \u2014 the tenant is part of what the signature covers, so this cannot be guessed."
+    );
+  }
+  const u = new URL(url);
+  return signAccessUrl(
+    `${u.origin}/${tid.toString(36)}${u.pathname}`,
+    signingKey,
+    signOpts
+  );
+}
 function hasPreset(asset, preset) {
   if (preset === "mp3") return asset.presets.includes("mp3");
   return stripMultiCharTokens(asset.presets).includes(PRESET_SHORT[preset]);
@@ -535,6 +672,11 @@ function stripMultiCharTokens(presets) {
 }
 var IMAGE_PRESETS = ["thumb", "sm", "md", "lg", "xl"];
 function getAssetSrcSet(asset) {
+  assertPublic(
+    asset,
+    "getAssetSrcSet",
+    "getPrivateAssetUrl(asset, preset, signingKey, { expiresInSeconds: 300 }) per preset"
+  );
   return IMAGE_PRESETS.filter(
     (p) => hasPreset(asset, p) && PRESET_MAX_DIM[p] != null
   ).map((p) => `${getAssetUrl(asset, p)} ${PRESET_MAX_DIM[p]}w`).join(", ");
@@ -561,10 +703,13 @@ function getAssetDimensions(asset) {
   PRESET_MAX_DIM,
   PRESET_SHORT,
   TRANSFORM_WIDTHS,
+  accessMessage,
+  assertPublic,
   bestTextContrast,
   computeVariantDimensions,
   configureSlotResolver,
   contrastRatio,
+  deriveAccessKey,
   extractAssetSha,
   getAmbientGradient,
   getAssetDimensions,
@@ -575,6 +720,8 @@ function getAssetDimensions(asset) {
   getHlsStreamingUrl,
   getPaletteBlurBackground,
   getPaletteCssVars,
+  getPrivateAssetUrl,
+  getPrivateTransformUrl,
   getSignedTransformUrl,
   getTenantId,
   getTextColorForBackground,
@@ -592,6 +739,7 @@ function getAssetDimensions(asset) {
   serializeTransform,
   setCdnBase,
   setTenantId,
+  signAccessUrl,
   signTransformUrl
 });
 //# sourceMappingURL=index.cjs.map