@nitida/sdk 0.31.7 → 0.32.1

package/README.md

@@ -283,7 +283,11 @@ const result = await aq.upload(file, { fileName: "cover.jpg" });
 await aq.upload(bytes, { fileName: "cover.webp" });              // MIME inferred from .webp ✓
 await aq.upload(bytes, { contentType: "image/webp" });          // or be explicit ✓
 // And request the variants you'll render — `presets` DEFAULTS TO ["original"] (just the raw
-// bytes), so getAssetUrl(sha, "md") style preset URLs 404 unless you ask for the ladder:
+// bytes). ⚠️ Corrected 2026-08-25: a BARE sha does not 404 — it THROWS
+// (`assertSha`); and with the full object, a missing IMAGE preset does not
+// 404 either — it falls back to `/t/` and serves 200. What 404s is a
+// hand-built variant key. Ask for the ladder anyway when you want
+// materialised bytes instead of an on-the-fly transform:
 await aq.upload(bytes, { contentType: "image/webp", presets: ["thumb", "sm", "md", "lg", "xl"] });
 
 // Bind a slot (admin operation).

package/dist/index.d.ts

@@ -671,7 +671,62 @@ 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;
 };
 type SlotHistoryEntry = {
     id: string;
@@ -946,6 +1001,13 @@ declare class NitidaClient {
      * ```
      */
     upload(input: File | Blob | Uint8Array, opts?: UploadOptions): Promise<UploadResult>;
+    /**
+     * `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;
     private defaultPresetForMime;
     /**
      * Pick a sensible preset to build a URL for, given the asset's actual

package/dist/index.js

@@ -777,7 +777,9 @@ var NitidaClient = class {
         // 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)
         )
@@ -834,7 +836,9 @@ var NitidaClient = class {
         // 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)
         )
@@ -882,9 +886,21 @@ var NitidaClient = class {
       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.
+   */
+  publicUrlOrNull(asset, preset) {
+    if (asset.visibility === "private") return null;
+    return this.urlFor(asset, preset);
+  }
   defaultPresetForMime(mime) {
     if (mime.startsWith("video/")) return "video";
     if (mime.startsWith("audio/")) return "original";