@nitida/asset-client 0.23.0 → 0.24.1

package/README.md

@@ -11,11 +11,12 @@ 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.
+Everything documented here is exported by **`@nitida/asset-client`**, and
+**every one of those exports** is 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
+`@nitida/sdk/server` and `@nitida/sdk/web` carry the full set 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.

package/dist/index.cjs

@@ -43,6 +43,7 @@ __export(index_exports, {
   getAssetDimensions: () => getAssetDimensions,
   getAssetSrcSet: () => getAssetSrcSet,
   getAssetUrl: () => getAssetUrl,
+  getByteBudgetTransformUrl: () => getByteBudgetTransformUrl,
   getCdnBase: () => getCdnBase,
   getHlsLadder: () => getHlsLadder,
   getHlsStreamingUrl: () => getHlsStreamingUrl,
@@ -57,6 +58,7 @@ __export(index_exports, {
   getTransformUrl: () => getTransformUrl,
   getVideoTransformUrl: () => getVideoTransformUrl,
   hasPreset: () => hasPreset,
+  hasSizeLadder: () => hasSizeLadder,
   hlsLadderAlignment: () => hlsLadderAlignment,
   invalidateSlotCache: () => invalidateSlotCache,
   isRequestablePreset: () => isRequestablePreset,
@@ -296,10 +298,16 @@ function extractAssetSha(url) {
 function serializeTransform(opts) {
   const entries = [];
   const keys = Object.keys(opts).sort();
+  const VALUE_RE = /^[a-z0-9._-]+$/;
   for (const k of keys) {
     const v = opts[k];
     if (v == null) continue;
     const serialized = typeof v === "string" ? v.toLowerCase() : String(v);
+    if (!VALUE_RE.test(serialized)) {
+      throw new Error(
+        `invalid transform value for "${k}": ${JSON.stringify(serialized)} (only [a-z0-9._-] allowed)`
+      );
+    }
     entries.push([k, serialized]);
   }
   return entries.map(([k, v]) => `${k}=${v}`).join(",");
@@ -373,6 +381,37 @@ function getTransformUrl(asset, opts) {
   );
   return buildTransformUrl(asset, opts);
 }
+var LADDER_PRESETS = ["thumb", "sm", "md", "lg", "xl"];
+function hasSizeLadder(asset) {
+  const raw = asset.presets;
+  if (raw == null || raw.trim() === "") return null;
+  return LADDER_PRESETS.some((preset) => hasPreset(asset, preset));
+}
+function getByteBudgetTransformUrl(asset, opts) {
+  assertSha(asset, "getByteBudgetTransformUrl");
+  assertPublic(
+    asset,
+    "getByteBudgetTransformUrl",
+    "getPrivateTransformUrl(asset, opts, signingKey, { expiresInSeconds: 300 })"
+  );
+  if (!Number.isInteger(opts.quality) || opts.quality < 1 || opts.quality > 100) {
+    throw new Error(
+      `getByteBudgetTransformUrl: quality must be an integer 1..100, got ${String(opts.quality)}. If you do not have a measured byte budget, use getTransformUrl and omit quality entirely.`
+    );
+  }
+  const ladder = hasSizeLadder(asset);
+  if (ladder === null) {
+    throw new Error(
+      `getByteBudgetTransformUrl: asset ${asset.sha} carries no 'presets', so whether a pinned quality would re-compress it is UNKNOWN \u2014 and unknown is not permission. Fetch the full DTO (assets.get / assets.byHash) and pass it, or use getTransformUrl with no quality.`
+    );
+  }
+  if (ladder) {
+    throw new Error(
+      `getByteBudgetTransformUrl: asset ${asset.sha} has stored size variants (presets="${asset.presets}"). A pinned quality there does not set the encoder \u2014 it makes /t/ decode one of those already-compressed variants, so the output is a SECOND lossy generation: measured +2..+8% HEAVIER and -0.50..-0.85 dB. Use getTransformUrl with no quality (one pass from the master), or upload this asset with presets: ["original"] if the byte budget is real.`
+    );
+  }
+  return buildTransformUrl(asset, opts);
+}
 function getSignedTransformUrl(asset, opts, signingKey, signOpts) {
   assertSha(asset, "getSignedTransformUrl");
   assertPublic(
@@ -464,6 +503,14 @@ var cache = /* @__PURE__ */ new Map();
 var endpoint = "https://api.nitida.gofuture.space";
 var apiKey = null;
 var tenantCode = null;
+function effectiveConfig(cfg) {
+  if (!cfg) return { endpoint, apiKey, tenantCode };
+  return {
+    endpoint: cfg.endpoint ? cfg.endpoint.replace(/\/+$/, "") : endpoint,
+    apiKey: cfg.apiKey ?? null,
+    tenantCode: cfg.tenantCode ?? null
+  };
+}
 function configureSlotResolver(opts) {
   if (opts.endpoint) endpoint = opts.endpoint.replace(/\/+$/, "");
   if (opts.apiKey !== void 0) apiKey = opts.apiKey;
@@ -475,25 +522,25 @@ function invalidateSlotCache(slotKey) {
     for (const k of cache.keys())
       if (k.endsWith(`:${slotKey}`)) cache.delete(k);
 }
-var baseHeaders = () => {
+var baseHeaders = (cfg) => {
   const h = {};
-  if (apiKey) h.Authorization = `Bearer ${apiKey}`;
-  if (tenantCode) h["X-Tenant-Code"] = tenantCode;
+  if (cfg.apiKey) h.Authorization = `Bearer ${cfg.apiKey}`;
+  if (cfg.tenantCode) h["X-Tenant-Code"] = cfg.tenantCode;
   return h;
 };
-async function fetchSlot(slotKey) {
-  const r = await fetch(`${endpoint}/slots/${encodeURIComponent(slotKey)}`, {
-    headers: baseHeaders()
+async function fetchSlot(slotKey, cfg) {
+  const r = await fetch(`${cfg.endpoint}/slots/${encodeURIComponent(slotKey)}`, {
+    headers: baseHeaders(cfg)
   });
   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) {
+async function fetchSlotsBulk(slotKeys, cfg) {
   if (slotKeys.length === 0) return {};
-  const r = await fetch(`${endpoint}/slots/resolve`, {
+  const r = await fetch(`${cfg.endpoint}/slots/resolve`, {
     method: "POST",
-    headers: { ...baseHeaders(), "Content-Type": "application/json" },
+    headers: { ...baseHeaders(cfg), "Content-Type": "application/json" },
     body: JSON.stringify({ keys: slotKeys })
   });
   if (!r.ok) throw new Error(`slots resolve ${r.status}: ${await r.text()}`);
@@ -502,14 +549,15 @@ async function fetchSlotsBulk(slotKeys) {
 }
 async function resolveSlot(slotKey, opts = {}) {
   const ttl = opts.ttlMs ?? DEFAULT_TTL_MS;
-  const cacheKey = `${tenantCode ?? "_"}:${slotKey}`;
+  const cfg = effectiveConfig(opts.config);
+  const cacheKey = `${cfg.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);
+    dto = await fetchSlot(slotKey, cfg);
     cache.set(cacheKey, { fetchedAt: now, value: dto });
   }
   return materializeResolution(dto, opts.preset);
@@ -517,11 +565,12 @@ async function resolveSlot(slotKey, opts = {}) {
 async function resolveSlots(slotKeys, opts = {}) {
   if (slotKeys.length === 0) return {};
   const ttl = opts.ttlMs ?? DEFAULT_TTL_MS;
+  const cfg = effectiveConfig(opts.config);
   const now = Date.now();
   const missing = [];
   const out = {};
   for (const k of slotKeys) {
-    const cacheKey = `${tenantCode ?? "_"}:${k}`;
+    const cacheKey = `${cfg.tenantCode ?? "_"}:${k}`;
     const hit = cache.get(cacheKey);
     if (hit && now - hit.fetchedAt < ttl) {
       out[k] = materializeResolution(hit.value, opts.preset);
@@ -530,10 +579,10 @@ async function resolveSlots(slotKeys, opts = {}) {
     }
   }
   if (missing.length > 0) {
-    const resolved = await fetchSlotsBulk(missing);
+    const resolved = await fetchSlotsBulk(missing, cfg);
     for (const k of missing) {
       const dto = resolved[k] ?? null;
-      cache.set(`${tenantCode ?? "_"}:${k}`, { fetchedAt: now, value: dto });
+      cache.set(`${cfg.tenantCode ?? "_"}:${k}`, { fetchedAt: now, value: dto });
       out[k] = materializeResolution(dto, opts.preset);
     }
   }
@@ -827,6 +876,7 @@ function getAssetDimensions(asset) {
   getAssetDimensions,
   getAssetSrcSet,
   getAssetUrl,
+  getByteBudgetTransformUrl,
   getCdnBase,
   getHlsLadder,
   getHlsStreamingUrl,
@@ -841,6 +891,7 @@ function getAssetDimensions(asset) {
   getTransformUrl,
   getVideoTransformUrl,
   hasPreset,
+  hasSizeLadder,
   hlsLadderAlignment,
   invalidateSlotCache,
   isRequestablePreset,