@nitida/sdk 0.31.7 → 0.32.0

package/src/index.ts

@@ -1135,7 +1135,37 @@ export type UploadResult = {
    * can close (`.mpga`, `.docx`, `.m4a` all arrive as octet-stream).
    */
   oext?: string | null;
-  cdnUrl: string;
+  /**
+   * La URL pública de una variante razonable — o **`null` si el asset es
+   * privado**, que no tiene ninguna.
+   *
+   * ⭐⭐ ERA `string`, Y ESO HACÍA QUE `upload()` PERDIERA EL HANDLE
+   *
+   * Los tres retornos de `upload()` arman este campo con `urlFor`, que llama a
+   * `assertPublic` y **tira** sobre un asset privado. Medido 2026-08-25 por una
+   * auditoría externa: subir bytes que deduplican contra una fila privada hacía
+   * que `upload()` lanzara DESPUÉS del PUT — los bytes quedaban guardados y el
+   * `assetId` se perdía, porque el error es un `Error` pelado sin `assetId`, sin
+   * `sha` y sin `cause`.
+   *
+   * ⚠️ Y el mensaje nombraba `getAssetUrl` y un preset `"lg"` que el llamador
+   * nunca pidió, así que iba a buscar en su código una función que no llamó.
+   *
+   * Un asset privado **no tiene** URL pública: eso es la feature. Lo que no
+   * puede pasar es que no tenerla cueste el resultado de una subida que ya
+   * ocurrió. Para servirlo, mirá `visibility` y usá `getPrivateAssetUrl` con la
+   * signing key, en tu backend.
+   */
+  cdnUrl: string | null;
+  /**
+   * `"public"` o `"private"`, tal como quedó el asset.
+   *
+   * ⭐ Existe porque `getAssetUrl(up, …)` —el patrón que enseña toda la doc—
+   * no podía detectar un privado: el guarda mira `asset.visibility`, y este
+   * objeto no lo llevaba. El resultado era una URL pública para un asset
+   * privado, servida sin una queja, que después da 404.
+   */
+  visibility: "public" | "private";
 };
 
 async function computeSha256(
@@ -1687,7 +1717,8 @@ export class NitidaClient {
         // Same shape as the presign branch below, for the same reason. This
         // DTO does carry `sha` today — but relying on that is how the other
         // branch broke, and the value we hashed ourselves is authoritative.
-        cdnUrl: this.urlFor(
+        visibility: existing.visibility ?? "public",
+        cdnUrl: this.publicUrlOrNull(
           { ...existing, sha: sha.slice(0, 16) },
           this.bestPresetForAsset(existing, mime),
         ),
@@ -1778,7 +1809,8 @@ export class NitidaClient {
         // ACTUALLY has, now that we waited for it — not from
         // `defaultPresetForMime`, which is a guess made before anything exists.
         // Guessing was safe only while this branch never ran.
-        cdnUrl: this.urlFor(
+        visibility: settled.visibility ?? "public",
+        cdnUrl: this.publicUrlOrNull(
           { ...settled, sha: short },
           this.bestPresetForAsset(settled, mime),
         ),
@@ -1834,10 +1866,27 @@ export class NitidaClient {
       sha: sha.slice(0, 16),
       mime: final.mime ?? mime,
       oext: final.oext ?? null,
-      cdnUrl: this.urlFor(final, this.bestPresetForAsset(final, mime)),
+      visibility: final.visibility ?? "public",
+      cdnUrl: this.publicUrlOrNull(final, this.bestPresetForAsset(final, mime)),
     };
   }
 
+  /**
+   * `urlFor` sin la excepción: `null` cuando el asset es privado.
+   *
+   * `upload()` no puede fallar por no poder construir una URL pública. Los
+   * bytes ya están; el handle tiene que volver igual.
+   */
+  private publicUrlOrNull(
+    asset: Parameters<typeof getAssetUrl>[0] & {
+      visibility?: "public" | "private";
+    },
+    preset: VariantPreset,
+  ): string | null {
+    if (asset.visibility === "private") return null;
+    return this.urlFor(asset, preset);
+  }
+
   private defaultPresetForMime(mime: string): VariantPreset {
     if (mime.startsWith("video/")) return "video";
     // The `mp3` variant only exists AFTER /process transcodes it; at presign