@nitida/asset-client 0.18.0 → 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,9 +24,11 @@ __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,
+  assertSha: () => assertSha,
   bestTextContrast: () => bestTextContrast,
   computeVariantDimensions: () => computeVariantDimensions,
   configureSlotResolver: () => configureSlotResolver,
@@ -53,6 +55,7 @@ __export(index_exports, {
   hasPreset: () => hasPreset,
   hlsLadderAlignment: () => hlsLadderAlignment,
   invalidateSlotCache: () => invalidateSlotCache,
+  isRequestablePreset: () => isRequestablePreset,
   iteratePaletteSwatches: () => iteratePaletteSwatches,
   pickAmbientBackground: () => pickAmbientBackground,
   relativeLuminance: () => relativeLuminance,
@@ -62,7 +65,8 @@ __export(index_exports, {
   setCdnBase: () => setCdnBase,
   setTenantId: () => setTenantId,
   signAccessUrl: () => signAccessUrl,
-  signTransformUrl: () => signTransformUrl
+  signTransformUrl: () => signTransformUrl,
+  toRequestablePresets: () => toRequestablePresets
 });
 module.exports = __toCommonJS(index_exports);
 
@@ -129,10 +133,18 @@ 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) {
+  const sha = asset?.sha;
+  if (typeof sha === "string" && /^[0-9a-f]{16,64}$/i.test(sha)) return;
+  const hint = asset && typeof asset === "object" && "sha256" in asset ? " The value you passed has `sha256` but not `sha` \u2014 that is the shape `upload()` returns. Use `{ sha: result.sha256.slice(0, 16) }`, or fetch the DTO with `assets.get(id)`." : ` Got ${JSON.stringify(sha)}.`;
+  throw new Error(
+    `${fn}: no usable \`sha\` on the value you passed, so the URL would contain "undefined" and 404 somewhere else.${hint}`
   );
 }
 
@@ -311,6 +323,7 @@ function extForOptions(opts) {
   }
 }
 function getVideoTransformUrl(asset, opts) {
+  assertSha(asset, "getVideoTransformUrl");
   assertPublic(
     asset,
     "getVideoTransformUrl",
@@ -322,6 +335,7 @@ function getVideoTransformUrl(asset, opts) {
   return `${getCdnBase()}/t/${dsl}/${asset.sha}.${ext}`;
 }
 function getHlsStreamingUrl(asset, opts = {}) {
+  assertSha(asset, "getHlsStreamingUrl");
   assertPublic(
     asset,
     "getHlsStreamingUrl",
@@ -338,6 +352,7 @@ function buildTransformUrl(asset, opts) {
   return `${getCdnBase()}/t/${dsl}/${asset.sha}.${ext}`;
 }
 function getTransformUrl(asset, opts) {
+  assertSha(asset, "getTransformUrl");
   assertPublic(
     asset,
     "getTransformUrl",
@@ -346,6 +361,7 @@ function getTransformUrl(asset, opts) {
   return buildTransformUrl(asset, opts);
 }
 function getSignedTransformUrl(asset, opts, signingKey) {
+  assertSha(asset, "getSignedTransformUrl");
   assertPublic(
     asset,
     "getSignedTransformUrl",
@@ -381,6 +397,7 @@ async function hmacSha256Hex(key, message) {
   return [...new Uint8Array(buf)].map((b) => b.toString(16).padStart(2, "0")).join("");
 }
 function getTransformSrcSet(asset, widths, extraOpts = {}) {
+  assertSha(asset, "getTransformSrcSet");
   assertPublic(
     asset,
     "getTransformSrcSet",
@@ -489,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",
@@ -614,6 +653,7 @@ function originalExtForMime(mime) {
   return (mime ? ORIGINAL_EXT_BY_MIME[mime] : void 0) ?? PRESET_EXT.original;
 }
 function getAssetUrl(asset, preset) {
+  assertSha(asset, "getAssetUrl");
   assertPublic(
     asset,
     "getAssetUrl",
@@ -631,6 +671,7 @@ function transformFallbackFor(asset, preset) {
   return `${cdnBaseUrl}/t/format=webp,width=${maxDim}/${asset.sha}.webp`;
 }
 function buildPublicAssetUrl(asset, preset) {
+  assertSha(asset, "getPrivateAssetUrl");
   if (preset === "original") {
     const stored = asset.variants?.find((v) => v.preset === "original")?.url;
     if (stored) return stored;
@@ -672,6 +713,7 @@ function stripMultiCharTokens(presets) {
 }
 var IMAGE_PRESETS = ["thumb", "sm", "md", "lg", "xl"];
 function getAssetSrcSet(asset) {
+  assertSha(asset, "getAssetSrcSet");
   assertPublic(
     asset,
     "getAssetSrcSet",
@@ -702,9 +744,11 @@ function getAssetDimensions(asset) {
   PRESET_LONG,
   PRESET_MAX_DIM,
   PRESET_SHORT,
+  REQUESTABLE_PRESETS,
   TRANSFORM_WIDTHS,
   accessMessage,
   assertPublic,
+  assertSha,
   bestTextContrast,
   computeVariantDimensions,
   configureSlotResolver,
@@ -731,6 +775,7 @@ function getAssetDimensions(asset) {
   hasPreset,
   hlsLadderAlignment,
   invalidateSlotCache,
+  isRequestablePreset,
   iteratePaletteSwatches,
   pickAmbientBackground,
   relativeLuminance,
@@ -740,6 +785,7 @@ function getAssetDimensions(asset) {
   setCdnBase,
   setTenantId,
   signAccessUrl,
-  signTransformUrl
+  signTransformUrl,
+  toRequestablePresets
 });
 //# sourceMappingURL=index.cjs.map