@nitida/asset-client 0.18.0 → 0.19.0

package/src/index.ts

@@ -80,6 +80,67 @@ export type RequestablePreset =
   // compact `presets` wire string — so it is here and not on VariantPreset.
   | "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.
+ */
+export const REQUESTABLE_PRESETS: readonly RequestablePreset[] = [
+  "thumb",
+  "sm",
+  "md",
+  "lg",
+  "xl",
+  "original",
+  "poster",
+  "video",
+  "aiproxy",
+  "probe",
+] as const;
+
+/** Type guard for a single value. */
+export const isRequestablePreset = (v: string): v is RequestablePreset =>
+  (REQUESTABLE_PRESETS as readonly string[]).includes(v);
+
+/**
+ * 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.
+ */
+export const toRequestablePresets = (
+  input: readonly string[],
+): RequestablePreset[] => {
+  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 — the server derives them itself (hls when a video is " +
+        "transcoded, mp3 alongside any audio original). " +
+        `Requestable: ${REQUESTABLE_PRESETS.join(", ")}.`,
+    );
+  }
+  return input as RequestablePreset[];
+};
+
 /** 1-char alias used in storage keys / wire `presets` string. */
 export const PRESET_SHORT: Record<VariantPreset, string> = {
   thumb: "q",
@@ -374,6 +435,7 @@ export type AssetDTO = {
 export {
   accessMessage,
   assertPublic,
+  assertSha,
   deriveAccessKey,
   type SignAccessOptions,
   signAccessUrl,
@@ -398,6 +460,7 @@ export {
 
 import {
   assertPublic,
+  assertSha,
   type SignAccessOptions,
   signAccessUrl,
   type VisibilityHint,
@@ -556,6 +619,7 @@ export function getAssetUrl(
   preset: VariantPreset,
 ): string {
   // Refuses rather than returning a URL that 404s. See `assertPublic`.
+  assertSha(asset, "getAssetUrl");
   assertPublic(
     asset,
     "getAssetUrl",
@@ -626,6 +690,13 @@ function buildPublicAssetUrl(
   asset: Pick<AssetDTO, "sha"> & OriginalHints,
   preset: VariantPreset,
 ): string {
+  // The guard lives HERE and not only in `getAssetUrl`, because
+  // `getPrivateAssetUrl` reaches this function directly. Without it, passing an
+  // upload result produced `/a/5/v/undefined-l.webp?exp=…&sig=…` — a URL with a
+  // **cryptographically valid signature over a path containing `undefined`**.
+  // That is strictly worse than the public case: the signature makes it look
+  // authoritative, and it passes shape checks at the edge before 404ing.
+  assertSha(asset, "getPrivateAssetUrl");
   if (preset === "original") {
     // The stored URL beats every derivation, because it IS the key. Only fall
     // through to a guess when the caller gave us the sha and nothing else.
@@ -818,6 +889,7 @@ export function getAssetSrcSet(
   // Doing this properly means capping the rungs by the asset's real width, and
   // this signature does not carry it (`Pick<AssetDTO,"sha"|"presets">`). Worth
   // doing; not worth guessing.
+  assertSha(asset, "getAssetSrcSet");
   assertPublic(
     asset,
     "getAssetSrcSet",

package/src/transform.ts

@@ -18,7 +18,7 @@
  * request's Accept header.
  */
 
-import { assertPublic, type VisibilityHint } from "./access";
+import { assertPublic, assertSha, type VisibilityHint } from "./access";
 import type { AssetDTO } from "./index";
 import { getCdnBase } from "./index";
 
@@ -231,6 +231,7 @@ export function getVideoTransformUrl(
   asset: Pick<AssetDTO, "sha"> & VisibilityHint,
   opts: TransformOptions,
 ): string | null {
+  assertSha(asset, "getVideoTransformUrl");
   assertPublic(
     asset,
     "getVideoTransformUrl",
@@ -304,6 +305,7 @@ export function getHlsStreamingUrl(
   asset: Pick<AssetDTO, "sha"> & VisibilityHint,
   opts: Omit<TransformOptions, "format"> = {},
 ): string {
+  assertSha(asset, "getHlsStreamingUrl");
   assertPublic(
     asset,
     "getHlsStreamingUrl",
@@ -336,6 +338,7 @@ export function getTransformUrl(
   asset: Pick<AssetDTO, "sha"> & VisibilityHint,
   opts: TransformOptions,
 ): string | null {
+  assertSha(asset, "getTransformUrl");
   assertPublic(
     asset,
     "getTransformUrl",
@@ -366,6 +369,7 @@ export function getSignedTransformUrl(
   // where a backend developer holding a signing key and a private asset ends
   // up — so without this, the same call site throws when unsigned and returns
   // a doomed URL when signed, which is the worst of both.
+  assertSha(asset, "getSignedTransformUrl");
   assertPublic(
     asset,
     "getSignedTransformUrl",
@@ -438,6 +442,7 @@ export function getTransformSrcSet(
   widths: number[],
   extraOpts: Omit<TransformOptions, "width"> = {},
 ): string {
+  assertSha(asset, "getTransformSrcSet");
   assertPublic(
     asset,
     "getTransformSrcSet",