@nitida/asset-client 0.20.3 → 0.21.0

package/dist/index.d.cts

@@ -770,6 +770,15 @@ declare function hlsLadderAlignment(rungs: HlsRung[]): {
  */
 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";
@@ -841,6 +850,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"];
 };
 /**
  * Build the public CDN URL for a specific variant of an asset. The variant
@@ -959,7 +975,9 @@ declare function getPrivateTransformUrl(asset: Pick<AssetDTO, "sha">, opts: Sign
  * hasPreset({ presets: "pv" }, "aiproxy");   // → false  — video without the AI proxy
  * ```
  */
-declare function hasPreset(asset: Pick<AssetDTO, "presets">, preset: VariantPreset): boolean;
+declare function hasPreset(asset: {
+    presets?: string | null;
+}, preset: VariantPreset): boolean;
 declare function getAssetSrcSet(asset: Pick<AssetDTO, "sha" | "presets"> & VisibilityHint): string;
 /**
  * Compute the dimensions a variant would have given the source asset's

package/dist/index.d.ts

@@ -770,6 +770,15 @@ declare function hlsLadderAlignment(rungs: HlsRung[]): {
  */
 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";
@@ -841,6 +850,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"];
 };
 /**
  * Build the public CDN URL for a specific variant of an asset. The variant
@@ -959,7 +975,9 @@ declare function getPrivateTransformUrl(asset: Pick<AssetDTO, "sha">, opts: Sign
  * hasPreset({ presets: "pv" }, "aiproxy");   // → false  — video without the AI proxy
  * ```
  */
-declare function hasPreset(asset: Pick<AssetDTO, "presets">, preset: VariantPreset): boolean;
+declare function hasPreset(asset: {
+    presets?: string | null;
+}, preset: VariantPreset): boolean;
 declare function getAssetSrcSet(asset: Pick<AssetDTO, "sha" | "presets"> & VisibilityHint): string;
 /**
  * Compute the dimensions a variant would have given the source asset's

package/dist/index.js

@@ -615,6 +615,11 @@ function buildPublicAssetUrl(asset, preset, caller) {
   if (preset === "hls") {
     const stored = asset.variants?.find((v) => v.preset === "hls")?.url;
     if (stored) return stored;
+    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 \u2014 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]}`;
@@ -643,11 +648,12 @@ async function getPrivateTransformUrl(asset, opts, signingKey, signOpts) {
   );
 }
 function hasPreset(asset, preset) {
-  if (preset === "mp3") return asset.presets.includes("mp3");
-  return stripMultiCharTokens(asset.presets).includes(PRESET_SHORT[preset]);
+  const presets = asset.presets ?? "";
+  if (preset === "mp3") return presets.includes("mp3");
+  return stripMultiCharTokens(presets).includes(PRESET_SHORT[preset]);
 }
 function stripMultiCharTokens(presets) {
-  return presets.replace(/transform-[0-9a-f]*/g, "").replace(/upscale_[a-z0-9_]*/g, "").replace(/mp3/g, "").replace(/u[2-8]|t[1248ghij]/g, "").replace(/pr/g, "");
+  return (presets ?? "").replace(/transform-[0-9a-f]*/g, "").replace(/upscale_[a-z0-9_]*/g, "").replace(/mp3/g, "").replace(/u[2-8]|t[1248ghij]/g, "").replace(/pr/g, "");
 }
 var IMAGE_PRESETS = ["thumb", "sm", "md", "lg", "xl"];
 function getAssetSrcSet(asset) {