@nitida/asset-client 0.20.3 → 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]}`;
@@ -878,11 +921,30 @@ export async function getPrivateTransformUrl(
  * ```
  */
 export function hasPreset(
-  asset: Pick<AssetDTO, "presets">,
+  asset: { presets?: string | null },
   preset: VariantPreset,
 ): boolean {
-  if (preset === "mp3") return asset.presets.includes("mp3");
-  return stripMultiCharTokens(asset.presets).includes(PRESET_SHORT[preset]);
+  // ⭐⭐ `presets` PUEDE FALTAR, Y ASUMIR QUE NO ERA UN CRASH EN PRODUCCIÓN
+  //
+  // El DTO que `assets.byHash(sha)` devuelve no siempre trae `presets` — igual
+  // que no traía `sha`. Y `upload()` le pasa ese DTO crudo a `bestPresetForAsset`
+  // → `hasPreset` → acá. Con `presets` ausente, `asset.presets.includes(...)`
+  // y `stripMultiCharTokens(asset.presets)` reventaban con
+  // `undefined is not an object (evaluating 'presets.replace')`.
+  //
+  // Medido en el canario de neo 2026-08-25: verde con 0.30.2, rojo con 0.32.2,
+  // en la rama ORDINARIA del dedup (`existing.status === "ready"`) — o sea toda
+  // re-subida de bytes que ya existen, no el caso raro de ayer.
+  //
+  // ⭐ La invariante que faltaba no era «el objeto lleva `sha`» sino «todo
+  // objeto que `upload()` le pasa a un helper satisface la forma que el helper
+  // asume». Se arregla ensanchando la forma del helper —`presets` opcional—, no
+  // parcheando cada llamador de a uno. Un `presets` ausente significa «no sé qué
+  // variantes tiene», que es `false` para cualquier preset: el llamador cae a su
+  // default, que es lo correcto.
+  const presets = asset.presets ?? "";
+  if (preset === "mp3") return presets.includes("mp3");
+  return stripMultiCharTokens(presets).includes(PRESET_SHORT[preset]);
 }
 
 /**
@@ -909,8 +971,8 @@ export function hasPreset(
  * keep sending them, and this is the check every guide points at as the
  * reliable one. Order matters — strip the longest tokens first.
  */
-function stripMultiCharTokens(presets: string): string {
-  return presets
+function stripMultiCharTokens(presets: string | null | undefined): string {
+  return (presets ?? "")
     .replace(/transform-[0-9a-f]*/g, "")
     .replace(/upscale_[a-z0-9_]*/g, "")
     .replace(/mp3/g, "")