@nitida/asset-client 0.19.1 → 0.20.0

package/src/index.ts

@@ -496,8 +496,27 @@ export function getCdnBase(): string {
 // `variantKey`). Variant URL builders MUST include that prefix or every
 // URL 404s. The tenant id is process-global (one tenant per client/app),
 // set once at boot — `NitidaClient` does this from its `tenantId` option;
-// standalone consumers call `setTenantId()` directly. Left unset, builders
-// fall back to the legacy pre-cutover bare path for back-compat.
+// standalone consumers call `setTenantId()` directly.
+//
+// ⭐ THE BACK-COMPAT FALLBACK FELL BACK TO A 404, SO IT IS GONE
+//
+// This used to return `""` when no tenant was set, "for back-compat with the
+// legacy pre-cutover bare path". Measured 2026-08-24: **nothing serves that
+// shape.** The edge parser understands exactly two schemes —
+// `<tid_b36>/<v|r>/<sha…>` and the literal `raw/…` prefix (`legacyRawSha16`)
+// — and a bare `<sha16>-<preset>.<ext>` matches neither. So the fallback was
+// not back-compat; it was a silent 404 generator wearing its name.
+//
+// It cost more than a 404. The README documented the bare shape as THE CDN
+// URL format, with a worked example that 404s, and the sentence "the same
+// bytes produce the same URL regardless of which tenant uploaded them" —
+// which stopped being true at the cutover. Code and docs agreed with each
+// other and disagreed with the CDN, which is the hardest kind of wrong to
+// find: nothing contradicts you until a user opens the URL.
+//
+// Now it throws, like `getPrivateTransformUrl` already did for the same
+// missing config. Same reason as `assertSha`: a builder that cannot produce a
+// working URL must say so, not hand back a polite lie.
 // ---------------------------------------------------------------------------
 
 let tenantId: number | null = null;
@@ -509,9 +528,23 @@ export function setTenantId(id: number | null | undefined): void {
 export function getTenantId(): number | null {
   return tenantId;
 }
-/** Variant path prefix `<tid b36>/v/`, or "" when no tenant is configured. */
-function variantPrefix(): string {
-  return tenantId != null ? `${tenantId.toString(36)}/v/` : "";
+/**
+ * Variant path prefix `<tid b36>/v/`.
+ *
+ * @throws when no tenant is configured — see the note above for why this is
+ * not a "" fallback.
+ */
+function variantPrefix(caller: string): string {
+  if (tenantId == null) {
+    throw new Error(
+      `${caller}: no tenant is configured, so every variant URL would 404. ` +
+        "Call setTenantId(id) once at boot, or construct a NitidaClient with " +
+        "`tenantId` (it does this for you). The tenant is part of the CDN " +
+        "path (`<cdn>/<tenantId base36>/v/<sha16>-<preset>.<ext>`) and cannot " +
+        "be guessed from the asset.",
+    );
+  }
+  return `${tenantId.toString(36)}/v/`;
 }
 
 // ---------------------------------------------------------------------------
@@ -646,7 +679,7 @@ export function getAssetUrl(
   // untouched and no existing behaviour changes.
   const fallback = transformFallbackFor(asset, preset);
   if (fallback) return fallback;
-  return buildPublicAssetUrl(asset, preset);
+  return buildPublicAssetUrl(asset, preset, "getAssetUrl");
 }
 
 /**
@@ -689,6 +722,10 @@ function transformFallbackFor(
 function buildPublicAssetUrl(
   asset: Pick<AssetDTO, "sha"> & OriginalHints,
   preset: VariantPreset,
+  // Named by the PUBLIC entry point, not by this helper: the caller is the
+  // function the user actually typed, and it is the one whose name has to
+  // appear in the error for the fix to be obvious.
+  caller: string,
 ): string {
   // The guard lives HERE and not only in `getAssetUrl`, because
   // `getPrivateAssetUrl` reaches this function directly. Without it, passing an
@@ -696,14 +733,14 @@ function buildPublicAssetUrl(
   // **cryptographically valid signature over a path containing `undefined`**.
   // That is strictly worse than the public case: the signature makes it look
   // authoritative, and it passes shape checks at the edge before 404ing.
-  assertSha(asset, "getPrivateAssetUrl");
+  assertSha(asset, caller);
   if (preset === "original") {
     // The stored URL beats every derivation, because it IS the key. Only fall
     // through to a guess when the caller gave us the sha and nothing else.
     const stored = asset.variants?.find((v) => v.preset === "original")?.url;
     if (stored) return stored;
     const ext = asset.oext || originalExtForMime(asset.mime);
-    return `${cdnBaseUrl}/${variantPrefix()}${asset.sha}-${PRESET_SHORT.original}.${ext}`;
+    return `${cdnBaseUrl}/${variantPrefix(caller)}${asset.sha}-${PRESET_SHORT.original}.${ext}`;
   }
   if (preset === "hls") {
     // A ladder is a PREFIX (`<sha16>-hls<dslHash>/master.m3u8`), not a
@@ -718,7 +755,7 @@ function buildPublicAssetUrl(
     if (stored) return stored;
     return `${cdnBaseUrl}/t/format=hls/${asset.sha}.m3u8`;
   }
-  return `${cdnBaseUrl}/${variantPrefix()}${asset.sha}-${PRESET_SHORT[preset]}.${PRESET_EXT[preset]}`;
+  return `${cdnBaseUrl}/${variantPrefix(caller)}${asset.sha}-${PRESET_SHORT[preset]}.${PRESET_EXT[preset]}`;
 }
 
 /**
@@ -751,7 +788,11 @@ export async function getPrivateAssetUrl(
   signingKey: string,
   opts: SignAccessOptions,
 ): Promise<string> {
-  return signAccessUrl(buildPublicAssetUrl(asset, preset), signingKey, opts);
+  return signAccessUrl(
+    buildPublicAssetUrl(asset, preset, "getPrivateAssetUrl"),
+    signingKey,
+    opts,
+  );
 }
 
 /**