@nitida/asset-client 0.18.0 → 0.18.1

package/dist/index.d.cts

@@ -85,6 +85,29 @@ declare function assertPublic(asset: VisibilityHint, fn: string,
  * `getPrivateAssetUrl` for all seven builders; a test caught it.
  */
 escape: string): void;
+/**
+ * Refuse a value whose `sha` is missing or malformed, instead of interpolating
+ * it into a URL.
+ *
+ * ## Found by a Haiku agent, 2026-08-23
+ *
+ * It did the most natural thing there is — passed the result of `upload()`
+ * straight to `transform()` — and got:
+ *
+ *     https://8ok.uk/t/width=1280/undefined.webp
+ *
+ * `UploadResult` carries `sha256`; every URL builder wants `sha`. TypeScript
+ * catches the mismatch, but an agent running through `bun` (or anyone in plain
+ * JS) sees no error at all: just a 200-shaped URL with the word `undefined` in
+ * it, which 404s later and somewhere else.
+ *
+ * The house rule applies exactly as it does to private assets: **a silence
+ * reads as "you can't"**. A builder that cannot name the asset must say so at
+ * the call site, not hand back a string that will fail far from here.
+ */
+declare function assertSha(asset: {
+    sha?: unknown;
+}, fn: string): void;
 
 /**
  * Color palette helpers — render harmonious ambient backgrounds behind
@@ -889,4 +912,4 @@ declare function getAssetDimensions(asset: Pick<AssetDTO, "w" | "h">): {
     height: number;
 } | null;
 
-export { type AssetDTO, type AssetPalette, type AssetVariant, type HlsRung, PRESET_EXT, PRESET_LONG, PRESET_MAX_DIM, PRESET_SHORT, type PaletteSwatch, type RequestablePreset, type ResolveSlotOptions, type SignAccessOptions, type SignedTransformOptions, type SlotDTO, type SlotResolution, TRANSFORM_WIDTHS, type TransformEffect, type TransformFit, type TransformFormat, type TransformGravity, type TransformOptions, type TransformWidth, type VariantEntryPreset, type VariantPreset, type VisibilityHint, accessMessage, assertPublic, bestTextContrast, computeVariantDimensions, configureSlotResolver, contrastRatio, deriveAccessKey, extractAssetSha, getAmbientGradient, getAssetDimensions, getAssetSrcSet, getAssetUrl, getCdnBase, getHlsLadder, getHlsStreamingUrl, getPaletteBlurBackground, getPaletteCssVars, getPrivateAssetUrl, getPrivateTransformUrl, getSignedTransformUrl, getTenantId, getTextColorForBackground, getTransformSrcSet, getTransformUrl, getVideoTransformUrl, hasPreset, hlsLadderAlignment, invalidateSlotCache, iteratePaletteSwatches, pickAmbientBackground, relativeLuminance, resolveSlot, resolveSlots, serializeTransform, setCdnBase, setTenantId, signAccessUrl, signTransformUrl };
+export { type AssetDTO, type AssetPalette, type AssetVariant, type HlsRung, PRESET_EXT, PRESET_LONG, PRESET_MAX_DIM, PRESET_SHORT, type PaletteSwatch, type RequestablePreset, type ResolveSlotOptions, type SignAccessOptions, type SignedTransformOptions, type SlotDTO, type SlotResolution, TRANSFORM_WIDTHS, type TransformEffect, type TransformFit, type TransformFormat, type TransformGravity, type TransformOptions, type TransformWidth, type VariantEntryPreset, type VariantPreset, type VisibilityHint, accessMessage, assertPublic, assertSha, bestTextContrast, computeVariantDimensions, configureSlotResolver, contrastRatio, deriveAccessKey, extractAssetSha, getAmbientGradient, getAssetDimensions, getAssetSrcSet, getAssetUrl, getCdnBase, getHlsLadder, getHlsStreamingUrl, getPaletteBlurBackground, getPaletteCssVars, getPrivateAssetUrl, getPrivateTransformUrl, getSignedTransformUrl, getTenantId, getTextColorForBackground, getTransformSrcSet, getTransformUrl, getVideoTransformUrl, hasPreset, hlsLadderAlignment, invalidateSlotCache, iteratePaletteSwatches, pickAmbientBackground, relativeLuminance, resolveSlot, resolveSlots, serializeTransform, setCdnBase, setTenantId, signAccessUrl, signTransformUrl };

package/dist/index.d.ts

@@ -85,6 +85,29 @@ declare function assertPublic(asset: VisibilityHint, fn: string,
  * `getPrivateAssetUrl` for all seven builders; a test caught it.
  */
 escape: string): void;
+/**
+ * Refuse a value whose `sha` is missing or malformed, instead of interpolating
+ * it into a URL.
+ *
+ * ## Found by a Haiku agent, 2026-08-23
+ *
+ * It did the most natural thing there is — passed the result of `upload()`
+ * straight to `transform()` — and got:
+ *
+ *     https://8ok.uk/t/width=1280/undefined.webp
+ *
+ * `UploadResult` carries `sha256`; every URL builder wants `sha`. TypeScript
+ * catches the mismatch, but an agent running through `bun` (or anyone in plain
+ * JS) sees no error at all: just a 200-shaped URL with the word `undefined` in
+ * it, which 404s later and somewhere else.
+ *
+ * The house rule applies exactly as it does to private assets: **a silence
+ * reads as "you can't"**. A builder that cannot name the asset must say so at
+ * the call site, not hand back a string that will fail far from here.
+ */
+declare function assertSha(asset: {
+    sha?: unknown;
+}, fn: string): void;
 
 /**
  * Color palette helpers — render harmonious ambient backgrounds behind
@@ -889,4 +912,4 @@ declare function getAssetDimensions(asset: Pick<AssetDTO, "w" | "h">): {
     height: number;
 } | null;
 
-export { type AssetDTO, type AssetPalette, type AssetVariant, type HlsRung, PRESET_EXT, PRESET_LONG, PRESET_MAX_DIM, PRESET_SHORT, type PaletteSwatch, type RequestablePreset, type ResolveSlotOptions, type SignAccessOptions, type SignedTransformOptions, type SlotDTO, type SlotResolution, TRANSFORM_WIDTHS, type TransformEffect, type TransformFit, type TransformFormat, type TransformGravity, type TransformOptions, type TransformWidth, type VariantEntryPreset, type VariantPreset, type VisibilityHint, accessMessage, assertPublic, bestTextContrast, computeVariantDimensions, configureSlotResolver, contrastRatio, deriveAccessKey, extractAssetSha, getAmbientGradient, getAssetDimensions, getAssetSrcSet, getAssetUrl, getCdnBase, getHlsLadder, getHlsStreamingUrl, getPaletteBlurBackground, getPaletteCssVars, getPrivateAssetUrl, getPrivateTransformUrl, getSignedTransformUrl, getTenantId, getTextColorForBackground, getTransformSrcSet, getTransformUrl, getVideoTransformUrl, hasPreset, hlsLadderAlignment, invalidateSlotCache, iteratePaletteSwatches, pickAmbientBackground, relativeLuminance, resolveSlot, resolveSlots, serializeTransform, setCdnBase, setTenantId, signAccessUrl, signTransformUrl };
+export { type AssetDTO, type AssetPalette, type AssetVariant, type HlsRung, PRESET_EXT, PRESET_LONG, PRESET_MAX_DIM, PRESET_SHORT, type PaletteSwatch, type RequestablePreset, type ResolveSlotOptions, type SignAccessOptions, type SignedTransformOptions, type SlotDTO, type SlotResolution, TRANSFORM_WIDTHS, type TransformEffect, type TransformFit, type TransformFormat, type TransformGravity, type TransformOptions, type TransformWidth, type VariantEntryPreset, type VariantPreset, type VisibilityHint, accessMessage, assertPublic, assertSha, bestTextContrast, computeVariantDimensions, configureSlotResolver, contrastRatio, deriveAccessKey, extractAssetSha, getAmbientGradient, getAssetDimensions, getAssetSrcSet, getAssetUrl, getCdnBase, getHlsLadder, getHlsStreamingUrl, getPaletteBlurBackground, getPaletteCssVars, getPrivateAssetUrl, getPrivateTransformUrl, getSignedTransformUrl, getTenantId, getTextColorForBackground, getTransformSrcSet, getTransformUrl, getVideoTransformUrl, hasPreset, hlsLadderAlignment, invalidateSlotCache, iteratePaletteSwatches, pickAmbientBackground, relativeLuminance, resolveSlot, resolveSlots, serializeTransform, setCdnBase, setTenantId, signAccessUrl, signTransformUrl };

package/dist/index.js

@@ -67,6 +67,14 @@ function assertPublic(asset, fn, escape) {
     `${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) {
@@ -243,6 +251,7 @@ function extForOptions(opts) {
   }
 }
 function getVideoTransformUrl(asset, opts) {
+  assertSha(asset, "getVideoTransformUrl");
   assertPublic(
     asset,
     "getVideoTransformUrl",
@@ -254,6 +263,7 @@ function getVideoTransformUrl(asset, opts) {
   return `${getCdnBase()}/t/${dsl}/${asset.sha}.${ext}`;
 }
 function getHlsStreamingUrl(asset, opts = {}) {
+  assertSha(asset, "getHlsStreamingUrl");
   assertPublic(
     asset,
     "getHlsStreamingUrl",
@@ -270,6 +280,7 @@ function buildTransformUrl(asset, opts) {
   return `${getCdnBase()}/t/${dsl}/${asset.sha}.${ext}`;
 }
 function getTransformUrl(asset, opts) {
+  assertSha(asset, "getTransformUrl");
   assertPublic(
     asset,
     "getTransformUrl",
@@ -278,6 +289,7 @@ function getTransformUrl(asset, opts) {
   return buildTransformUrl(asset, opts);
 }
 function getSignedTransformUrl(asset, opts, signingKey) {
+  assertSha(asset, "getSignedTransformUrl");
   assertPublic(
     asset,
     "getSignedTransformUrl",
@@ -313,6 +325,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",
@@ -546,6 +559,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",
@@ -563,6 +577,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;
@@ -604,6 +619,7 @@ function stripMultiCharTokens(presets) {
 }
 var IMAGE_PRESETS = ["thumb", "sm", "md", "lg", "xl"];
 function getAssetSrcSet(asset) {
+  assertSha(asset, "getAssetSrcSet");
   assertPublic(
     asset,
     "getAssetSrcSet",
@@ -636,6 +652,7 @@ export {
   TRANSFORM_WIDTHS,
   accessMessage,
   assertPublic,
+  assertSha,
   bestTextContrast,
   computeVariantDimensions,
   configureSlotResolver,