@nitida/asset-client 0.18.0 → 0.19.0

package/dist/index.d.cts

@@ -26,6 +26,20 @@
  *
  * A signed URL that never expires is a public URL as soon as someone forwards
  * it. There is no "no expiry" option here, and there will not be one.
+ *
+ * ## Where `signingKey` comes from
+ *
+ * The response that created your project. `POST /admin/projects` returns
+ * `signingKey` next to the three API keys, and the console shows it in the
+ * same panel — **once**. Save it with the keys.
+ *
+ * If it is gone — or you never saw one, which is the case for every project
+ * created before 2026-08-23 — the only endpoint that returns a key is
+ * `POST /admin/projects/:code/rotate-signing-key`, and rotating invalidates
+ * every URL already signed. That is free for a tenant with nothing in flight
+ * and expensive for a live one, which is exactly why the key is handed over at
+ * creation, when rotating would be free anyway. With URLs already circulating,
+ * ask the platform operator for the current key rather than rotating.
  */
 /**
  * The per-tenant access key, derived from `signing_key`. Same value the origin
@@ -79,12 +93,41 @@ declare function assertPublic(asset: VisibilityHint, fn: string,
 /**
  * The call to make instead — declared per call site, not guessed.
  *
+ * Named `escapeHatch`, not `escape`: the bare name shadows the deprecated
+ * global `escape`, which biome flags as an error. Nothing here calls that
+ * global, so this was never a defect — but it is a lint error standing in a
+ * PUBLISHED package, and a parameter name is not part of the API, so the
+ * cost of clearing it is zero.
+ *
  * It matters which one: `getPrivateAssetUrl` signs a STORED preset, and
  * pointing a transform caller at it sends them to a function that cannot do
  * what they asked for. The first version of this message named
  * `getPrivateAssetUrl` for all seven builders; a test caught it.
  */
-escape: string): void;
+escapeHatch: 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
@@ -546,6 +589,38 @@ type VariantPreset = "thumb" | "sm" | "md" | "lg" | "xl" | "original" | "poster"
  * no drift between them.
  */
 type RequestablePreset = Exclude<VariantPreset, "hls" | "mp3"> | "probe";
+/**
+ * The same set as {@link RequestablePreset}, at RUNTIME.
+ *
+ * The type stops the mistake in TypeScript. It cannot stop it anywhere else,
+ * and "anywhere else" is where it keeps happening: a preset list assembled
+ * from config, from a route body, from JSON, or from a script's argv arrives
+ * as `string[]`, and the only way past the type was a cast.
+ *
+ * Measured in neo-real-estate on 2026-08-23, in THREE independent files:
+ *
+ *     presets: [...opts.presets] as VariantPreset[]
+ *
+ * — a blind cast, and to the wrong type at that: `VariantPreset` includes
+ * `hls` and `mp3`, which are precisely the two you may not ask for. Every one
+ * of those casts would have compiled a request the server answers 400.
+ *
+ * So the narrowing lives here, once, instead of being re-invented per repo.
+ */
+declare const REQUESTABLE_PRESETS: readonly RequestablePreset[];
+/** Type guard for a single value. */
+declare const isRequestablePreset: (v: string) => v is RequestablePreset;
+/**
+ * Narrow a `string[]` to the presets the server can actually produce, or throw
+ * naming the offender.
+ *
+ * Throws rather than filtering silently, for the same reason the seven URL
+ * builders throw on a private asset: **a silence reads as "you can't"**. A
+ * caller that asked for `hls` wants an HLS ladder; dropping it quietly returns
+ * a 200 and no ladder, and the 404 lands later and somewhere else. The error
+ * names the value, says why the server cannot make it, and lists what it can.
+ */
+declare const toRequestablePresets: (input: readonly string[]) => RequestablePreset[];
 /** 1-char alias used in storage keys / wire `presets` string. */
 declare const PRESET_SHORT: Record<VariantPreset, string>;
 declare const PRESET_LONG: Record<string, VariantPreset>;
@@ -889,4 +964,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, REQUESTABLE_PRESETS, 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, isRequestablePreset, iteratePaletteSwatches, pickAmbientBackground, relativeLuminance, resolveSlot, resolveSlots, serializeTransform, setCdnBase, setTenantId, signAccessUrl, signTransformUrl, toRequestablePresets };

package/dist/index.d.ts

@@ -26,6 +26,20 @@
  *
  * A signed URL that never expires is a public URL as soon as someone forwards
  * it. There is no "no expiry" option here, and there will not be one.
+ *
+ * ## Where `signingKey` comes from
+ *
+ * The response that created your project. `POST /admin/projects` returns
+ * `signingKey` next to the three API keys, and the console shows it in the
+ * same panel — **once**. Save it with the keys.
+ *
+ * If it is gone — or you never saw one, which is the case for every project
+ * created before 2026-08-23 — the only endpoint that returns a key is
+ * `POST /admin/projects/:code/rotate-signing-key`, and rotating invalidates
+ * every URL already signed. That is free for a tenant with nothing in flight
+ * and expensive for a live one, which is exactly why the key is handed over at
+ * creation, when rotating would be free anyway. With URLs already circulating,
+ * ask the platform operator for the current key rather than rotating.
  */
 /**
  * The per-tenant access key, derived from `signing_key`. Same value the origin
@@ -79,12 +93,41 @@ declare function assertPublic(asset: VisibilityHint, fn: string,
 /**
  * The call to make instead — declared per call site, not guessed.
  *
+ * Named `escapeHatch`, not `escape`: the bare name shadows the deprecated
+ * global `escape`, which biome flags as an error. Nothing here calls that
+ * global, so this was never a defect — but it is a lint error standing in a
+ * PUBLISHED package, and a parameter name is not part of the API, so the
+ * cost of clearing it is zero.
+ *
  * It matters which one: `getPrivateAssetUrl` signs a STORED preset, and
  * pointing a transform caller at it sends them to a function that cannot do
  * what they asked for. The first version of this message named
  * `getPrivateAssetUrl` for all seven builders; a test caught it.
  */
-escape: string): void;
+escapeHatch: 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
@@ -546,6 +589,38 @@ type VariantPreset = "thumb" | "sm" | "md" | "lg" | "xl" | "original" | "poster"
  * no drift between them.
  */
 type RequestablePreset = Exclude<VariantPreset, "hls" | "mp3"> | "probe";
+/**
+ * The same set as {@link RequestablePreset}, at RUNTIME.
+ *
+ * The type stops the mistake in TypeScript. It cannot stop it anywhere else,
+ * and "anywhere else" is where it keeps happening: a preset list assembled
+ * from config, from a route body, from JSON, or from a script's argv arrives
+ * as `string[]`, and the only way past the type was a cast.
+ *
+ * Measured in neo-real-estate on 2026-08-23, in THREE independent files:
+ *
+ *     presets: [...opts.presets] as VariantPreset[]
+ *
+ * — a blind cast, and to the wrong type at that: `VariantPreset` includes
+ * `hls` and `mp3`, which are precisely the two you may not ask for. Every one
+ * of those casts would have compiled a request the server answers 400.
+ *
+ * So the narrowing lives here, once, instead of being re-invented per repo.
+ */
+declare const REQUESTABLE_PRESETS: readonly RequestablePreset[];
+/** Type guard for a single value. */
+declare const isRequestablePreset: (v: string) => v is RequestablePreset;
+/**
+ * Narrow a `string[]` to the presets the server can actually produce, or throw
+ * naming the offender.
+ *
+ * Throws rather than filtering silently, for the same reason the seven URL
+ * builders throw on a private asset: **a silence reads as "you can't"**. A
+ * caller that asked for `hls` wants an HLS ladder; dropping it quietly returns
+ * a 200 and no ladder, and the 404 lands later and somewhere else. The error
+ * names the value, says why the server cannot make it, and lists what it can.
+ */
+declare const toRequestablePresets: (input: readonly string[]) => RequestablePreset[];
 /** 1-char alias used in storage keys / wire `presets` string. */
 declare const PRESET_SHORT: Record<VariantPreset, string>;
 declare const PRESET_LONG: Record<string, VariantPreset>;
@@ -889,4 +964,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, REQUESTABLE_PRESETS, 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, isRequestablePreset, iteratePaletteSwatches, pickAmbientBackground, relativeLuminance, resolveSlot, resolveSlots, serializeTransform, setCdnBase, setTenantId, signAccessUrl, signTransformUrl, toRequestablePresets };

package/dist/index.js

@@ -61,10 +61,18 @@ async function signAccessUrl(publicUrl, signingKey, opts) {
   u.searchParams.set("sig", sig);
   return u.toString();
 }
-function assertPublic(asset, fn, escape) {
+function assertPublic(asset, fn, escapeHatch) {
   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.`
+    `${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 ${escapeHatch}. 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}`
   );
 }
 
@@ -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",
@@ -421,6 +434,28 @@ function materializeResolution(dto, overridePreset) {
 }
 
 // src/index.ts
+var REQUESTABLE_PRESETS = [
+  "thumb",
+  "sm",
+  "md",
+  "lg",
+  "xl",
+  "original",
+  "poster",
+  "video",
+  "aiproxy",
+  "probe"
+];
+var isRequestablePreset = (v) => REQUESTABLE_PRESETS.includes(v);
+var toRequestablePresets = (input) => {
+  const bad = input.filter((p) => !isRequestablePreset(p));
+  if (bad.length > 0) {
+    throw new Error(
+      `Cannot request ${bad.map((b) => `"${b}"`).join(", ")}. \`hls\` and \`mp3\` are things a variant can BE, not things you may ask for \u2014 the server derives them itself (hls when a video is transcoded, mp3 alongside any audio original). Requestable: ${REQUESTABLE_PRESETS.join(", ")}.`
+    );
+  }
+  return input;
+};
 var PRESET_SHORT = {
   thumb: "q",
   sm: "s",
@@ -546,6 +581,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 +599,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 +641,7 @@ function stripMultiCharTokens(presets) {
 }
 var IMAGE_PRESETS = ["thumb", "sm", "md", "lg", "xl"];
 function getAssetSrcSet(asset) {
+  assertSha(asset, "getAssetSrcSet");
   assertPublic(
     asset,
     "getAssetSrcSet",
@@ -633,9 +671,11 @@ export {
   PRESET_LONG,
   PRESET_MAX_DIM,
   PRESET_SHORT,
+  REQUESTABLE_PRESETS,
   TRANSFORM_WIDTHS,
   accessMessage,
   assertPublic,
+  assertSha,
   bestTextContrast,
   computeVariantDimensions,
   configureSlotResolver,
@@ -662,6 +702,7 @@ export {
   hasPreset,
   hlsLadderAlignment,
   invalidateSlotCache,
+  isRequestablePreset,
   iteratePaletteSwatches,
   pickAmbientBackground,
   relativeLuminance,
@@ -671,6 +712,7 @@ export {
   setCdnBase,
   setTenantId,
   signAccessUrl,
-  signTransformUrl
+  signTransformUrl,
+  toRequestablePresets
 };
 //# sourceMappingURL=index.js.map