@nitida/asset-client 0.23.0 → 0.24.0

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,
@@ -373,6 +375,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(
@@ -827,6 +860,7 @@ function getAssetDimensions(asset) {
   getAssetDimensions,
   getAssetSrcSet,
   getAssetUrl,
+  getByteBudgetTransformUrl,
   getCdnBase,
   getHlsLadder,
   getHlsStreamingUrl,
@@ -841,6 +875,7 @@ function getAssetDimensions(asset) {
   getTransformUrl,
   getVideoTransformUrl,
   hasPreset,
+  hasSizeLadder,
   hlsLadderAlignment,
   invalidateSlotCache,
   isRequestablePreset,