@nitida/sdk 0.31.7 → 0.32.1

package/src/index.ts

@@ -1135,7 +1135,62 @@ 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";
+  /**
+   * La cadena compacta de variantes que EXISTEN (`"lmoqs"`, `"o"`, …).
+   *
+   * ⭐⭐ EL QUINTO DEFECTO DE LA MISMA FAMILIA
+   *
+   * `getAssetUrl` **cambia de estrategia según este campo**. Con él, un preset
+   * de imagen ausente cae a `/t/…width=N/` y el borde lo genera al vuelo:
+   * **200**. Sin él, el builder no sabe qué existe, asume que todo existe, y
+   * devuelve la clave de variante — que da **404 en silencio**.
+   *
+   * Medido 2026-08-25 sobre un asset con `presets: "lmoqs"`:
+   *
+   *     sin `presets`  →  /f/v/<sha>-x.webp                   404
+   *     con `presets`  →  /t/format=webp,width=3840/<sha>.webp 200
+   *
+   * `UploadResult` no lo llevaba, así que `getAssetUrl(up, "xl")` —el patrón
+   * que enseña toda la doc— caía del lado malo.
+   *
+   * ⚠️ Es el mismo error que `sha`, `mime` y `oext`, por cuarta vez: **un tipo
+   * de retorno que omite lo que la próxima llamada necesita convierte la
+   * llamada obvia en un 404 silencioso.** Y el guarda que escribí para esto
+   * fijaba los tres *hints* de `original`; `presets` no es un hint, es lo que
+   * gobierna el fallback, así que quedaba afuera de lo que el guarda miraba.
+   */
+  presets: string;
 };
 
 async function computeSha256(
@@ -1687,7 +1742,9 @@ 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",
+        presets: existing.presets ?? "",
+        cdnUrl: this.publicUrlOrNull(
           { ...existing, sha: sha.slice(0, 16) },
           this.bestPresetForAsset(existing, mime),
         ),
@@ -1778,7 +1835,9 @@ 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",
+        presets: settled.presets ?? "",
+        cdnUrl: this.publicUrlOrNull(
           { ...settled, sha: short },
           this.bestPresetForAsset(settled, mime),
         ),
@@ -1834,10 +1893,28 @@ 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",
+      presets: final.presets ?? "",
+      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