@nitida/asset-client 0.18.1 → 0.19.0

package/AGENTS.md

@@ -91,6 +91,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.
 
 ## The endpoint
 

package/dist/index.cjs

@@ -24,6 +24,7 @@ __export(index_exports, {
   PRESET_LONG: () => PRESET_LONG,
   PRESET_MAX_DIM: () => PRESET_MAX_DIM,
   PRESET_SHORT: () => PRESET_SHORT,
+  REQUESTABLE_PRESETS: () => REQUESTABLE_PRESETS,
   TRANSFORM_WIDTHS: () => TRANSFORM_WIDTHS,
   accessMessage: () => accessMessage,
   assertPublic: () => assertPublic,
@@ -54,6 +55,7 @@ __export(index_exports, {
   hasPreset: () => hasPreset,
   hlsLadderAlignment: () => hlsLadderAlignment,
   invalidateSlotCache: () => invalidateSlotCache,
+  isRequestablePreset: () => isRequestablePreset,
   iteratePaletteSwatches: () => iteratePaletteSwatches,
   pickAmbientBackground: () => pickAmbientBackground,
   relativeLuminance: () => relativeLuminance,
@@ -63,7 +65,8 @@ __export(index_exports, {
   setCdnBase: () => setCdnBase,
   setTenantId: () => setTenantId,
   signAccessUrl: () => signAccessUrl,
-  signTransformUrl: () => signTransformUrl
+  signTransformUrl: () => signTransformUrl,
+  toRequestablePresets: () => toRequestablePresets
 });
 module.exports = __toCommonJS(index_exports);
 
@@ -130,10 +133,10 @@ async function signAccessUrl(publicUrl, signingKey, opts) {
   u.searchParams.set("sig", sig);
   return u.toString();
 }
-function assertPublic(asset, fn, escape) {
+function assertPublic(asset, fn, escapeHatch) {
   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.`
+    `${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 ${escapeHatch}. Never ship the signing key to a browser.`
   );
 }
 function assertSha(asset, fn) {
@@ -503,6 +506,28 @@ function materializeResolution(dto, overridePreset) {
 }
 
 // src/index.ts
+var REQUESTABLE_PRESETS = [
+  "thumb",
+  "sm",
+  "md",
+  "lg",
+  "xl",
+  "original",
+  "poster",
+  "video",
+  "aiproxy",
+  "probe"
+];
+var isRequestablePreset = (v) => REQUESTABLE_PRESETS.includes(v);
+var toRequestablePresets = (input) => {
+  const bad = input.filter((p) => !isRequestablePreset(p));
+  if (bad.length > 0) {
+    throw new Error(
+      `Cannot request ${bad.map((b) => `"${b}"`).join(", ")}. \`hls\` and \`mp3\` are things a variant can BE, not things you may ask for \u2014 the server derives them itself (hls when a video is transcoded, mp3 alongside any audio original). Requestable: ${REQUESTABLE_PRESETS.join(", ")}.`
+    );
+  }
+  return input;
+};
 var PRESET_SHORT = {
   thumb: "q",
   sm: "s",
@@ -719,6 +744,7 @@ function getAssetDimensions(asset) {
   PRESET_LONG,
   PRESET_MAX_DIM,
   PRESET_SHORT,
+  REQUESTABLE_PRESETS,
   TRANSFORM_WIDTHS,
   accessMessage,
   assertPublic,
@@ -749,6 +775,7 @@ function getAssetDimensions(asset) {
   hasPreset,
   hlsLadderAlignment,
   invalidateSlotCache,
+  isRequestablePreset,
   iteratePaletteSwatches,
   pickAmbientBackground,
   relativeLuminance,
@@ -758,6 +785,7 @@ function getAssetDimensions(asset) {
   setCdnBase,
   setTenantId,
   signAccessUrl,
-  signTransformUrl
+  signTransformUrl,
+  toRequestablePresets
 });
 //# sourceMappingURL=index.cjs.map