@nitida/asset-client 0.17.0 → 0.18.1

package/dist/index.js

@@ -1,3 +1,81 @@
+// 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.`
+  );
+}
+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}`
+  );
+}
+
 // src/palette.ts
 function resolveSwatch(palette, ...keys) {
   if (!palette) return null;
@@ -15,9 +93,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";
@@ -102,102 +180,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,
@@ -269,12 +251,24 @@ function extForOptions(opts) {
   }
 }
 function getVideoTransformUrl(asset, opts) {
+  assertSha(asset, "getVideoTransformUrl");
+  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 = {}) {
+  assertSha(asset, "getHlsStreamingUrl");
+  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`;
@@ -286,9 +280,21 @@ function buildTransformUrl(asset, opts) {
   return `${getCdnBase()}/t/${dsl}/${asset.sha}.${ext}`;
 }
 function getTransformUrl(asset, opts) {
+  assertSha(asset, "getTransformUrl");
+  assertPublic(
+    asset,
+    "getTransformUrl",
+    "getPrivateTransformUrl(asset, opts, signingKey, { expiresInSeconds: 300 })"
+  );
   return buildTransformUrl(asset, opts);
 }
 function getSignedTransformUrl(asset, opts, signingKey) {
+  assertSha(asset, "getSignedTransformUrl");
+  assertPublic(
+    asset,
+    "getSignedTransformUrl",
+    "getPrivateTransformUrl(asset, opts, signingKey, { expiresInSeconds: 300 })"
+  );
   const url = buildTransformUrl(asset, opts);
   if (!url) return null;
   return signTransformUrl(url, signingKey);
@@ -319,12 +325,114 @@ 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",
+    "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",
@@ -451,6 +559,25 @@ 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",
+    `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) {
+  assertSha(asset, "getPrivateAssetUrl");
   if (preset === "original") {
     const stored = asset.variants?.find((v) => v.preset === "original")?.url;
     if (stored) return stored;
@@ -464,6 +591,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]);
@@ -473,6 +619,12 @@ function stripMultiCharTokens(presets) {
 }
 var IMAGE_PRESETS = ["thumb", "sm", "md", "lg", "xl"];
 function getAssetSrcSet(asset) {
+  assertSha(asset, "getAssetSrcSet");
+  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(", ");
@@ -498,10 +650,14 @@ export {
   PRESET_MAX_DIM,
   PRESET_SHORT,
   TRANSFORM_WIDTHS,
+  accessMessage,
+  assertPublic,
+  assertSha,
   bestTextContrast,
   computeVariantDimensions,
   configureSlotResolver,
   contrastRatio,
+  deriveAccessKey,
   extractAssetSha,
   getAmbientGradient,
   getAssetDimensions,
@@ -512,6 +668,8 @@ export {
   getHlsStreamingUrl,
   getPaletteBlurBackground,
   getPaletteCssVars,
+  getPrivateAssetUrl,
+  getPrivateTransformUrl,
   getSignedTransformUrl,
   getTenantId,
   getTextColorForBackground,
@@ -529,6 +687,7 @@ export {
   serializeTransform,
   setCdnBase,
   setTenantId,
+  signAccessUrl,
   signTransformUrl
 };
 //# sourceMappingURL=index.js.map