@nitida/asset-client 0.20.4 → 0.21.0

package/src/index.ts

@@ -378,6 +378,15 @@ export function hlsLadderAlignment(rungs: HlsRung[]): {
  */
 export type AssetDTO = {
   id: string;
+  /**
+   * ⭐ The same value as `id`, under the name the WRITE side uses.
+   *
+   * `upload()` returns `assetId`; the read endpoints returned only `id`, so
+   * what `assets.byHash()` handed back could not be fed to `assets.get()`
+   * without renaming a field. Optional here because a DTO produced by an older
+   * server will not carry it — read `dto.assetId ?? dto.id`.
+   */
+  assetId?: string;
   /** First 16 hex chars of sha256 — used to derive CDN URLs. */
   sha: string;
   kind: "image" | "video" | "document" | "audio" | "other";
@@ -611,6 +620,13 @@ type OriginalHints = {
   oext?: string | null;
   /** Full variant list — carries the stored URL verbatim. Authoritative. */
   variants?: AssetVariant[];
+  /**
+   * What the asset IS. Optional because these builders accept a minimal
+   * `{ sha }`, and absent means "we cannot know" — never "assume the worst".
+   * Used to refuse `hls` on something that can never have a ladder; see the
+   * `hls` branch of `getAssetUrl`.
+   */
+  kind?: AssetDTO["kind"];
 };
 
 /**
@@ -768,6 +784,33 @@ function buildPublicAssetUrl(
     // missing. Both are real; neither is a guess.
     const stored = asset.variants?.find((v) => v.preset === "hls")?.url;
     if (stored) return stored;
+    // No stored ladder. Before falling through to the transform route, refuse
+    // the kinds that can never HAVE one.
+    //
+    // `/t/format=hls/<sha>.m3u8` on an IMAGE does not 404 — measured against
+    // production 2026-08-25, it answers **200 with `content-type: image/webp`**
+    // (306 kB, cached `immutable` for a year) because the edge's transform
+    // planner short-circuits every image to the image pipeline before it ever
+    // looks at `format`. So the polite lie this branch was written to avoid
+    // comes back through the other door: not a 404, but a WebP wearing an
+    // `.m3u8` filename, which is worse — a player cannot even tell it failed.
+    //
+    // HLS is built when a VIDEO transcodes; audio gets `mp3`, images get the
+    // ladder of resized variants. The stored-URL check above runs FIRST on
+    // purpose: if a DTO really carries an `hls` variant, the data beats this
+    // inference and we hand it over whatever `kind` claims. We only refuse
+    // when we would otherwise fabricate a URL we already know is wrong.
+    if (asset.kind != null && asset.kind !== "video") {
+      throw new Error(
+        `${caller}: this asset is \`${asset.kind}\`, and only a video has an ` +
+          "HLS ladder. Asking for `hls` here would build " +
+          "`/t/format=hls/<sha>.m3u8`, which does NOT 404 — the edge answers " +
+          "200 with the image bytes under an .m3u8 name, so a player fails " +
+          "with no way to see why. For an image use a size preset " +
+          `(\`${caller}(asset, "md")\`) or a transform ` +
+          "(`getTransformUrl`); for audio use `mp3`.",
+      );
+    }
     return `${cdnBaseUrl}/t/format=hls/${asset.sha}.m3u8`;
   }
   return `${cdnBaseUrl}/${variantPrefix(caller)}${asset.sha}-${PRESET_SHORT[preset]}.${PRESET_EXT[preset]}`;