@nitida/sdk 0.31.6 → 0.32.0

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).
@@ -1403,6 +1407,43 @@ If you need a dimension that doesn't exist, two options: use the closest
 preset and let the browser scale, or file an issue to add it to the
 server-side pipeline (a platform-wide addition, not a per-tenant one).
 
+### ⭐ What happens when two tenants upload the SAME image
+
+Dedup is **content-addressed and cross-tenant**: the sha is a hash of the bytes,
+so if you and another customer upload the same logo, the same stock photo or the
+same placeholder, you share a candidate row. This is normal, not exotic.
+
+A `/t/…` transform URL names **content**, not a tenant — there is no tenant
+segment in it. Three consequences follow, and all three are measured behaviour:
+
+**1 · A signed transform is resolved by the SIGNATURE, not by tenant id.**
+The signature proves possession of one specific tenant's key, which is exactly
+the identity the URL lacks. Before `2026-08-25` the lowest tenant id won, so a
+correctly signed URL could be verified against someone else's key and answer
+`invalid_signature`. Nothing to do on your side — just know the signature is
+what disambiguates.
+
+**2 · `strict_transforms` fails CLOSED across every tenant that shares the sha.**
+If any tenant holding those bytes requires signed URLs, the unsigned request is
+refused — because an unsigned request cannot say which tenant it belongs to, and
+picking the most permissive one would let a third party defeat your policy.
+
+> ⚠️ The cost, stated plainly: if you do **not** use `strict_transforms` but you
+> share content with someone who does, that sha needs a signed URL from you too.
+> The alternative — failing open — means your own strict setting is silently
+> cancelled by a stranger. A 401 you fix by signing is the cheaper mistake.
+
+**3 · Making an asset private does NOT unpublish another tenant's public copy.**
+`visibility: "private"` retracts **your** row. If another tenant uploaded the
+same bytes and left them public, that copy keeps serving, and a `/t/` request
+resolves to it. No new information leaks — those exact bytes were already public
+— but do not read "private" as "these bytes are now unreachable". It means
+"reachable through me only by signature".
+
+> If that distinction matters for your content, the answer is not a flag: it is
+> not to share the bytes. Anything unique to you (a customer photo, a document,
+> a render) has a unique sha and never collides.
+
 ### CDN URL format
 
 `<cdnBase>/<tenantId base36>/v/<sha16>-<presetCode>.<ext>`

package/dist/index.d.ts

@@ -671,7 +671,37 @@ 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";
 };
 type SlotHistoryEntry = {
     id: string;
@@ -946,6 +976,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,8 @@ 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",
+        cdnUrl: this.publicUrlOrNull(
           { ...existing, sha: sha.slice(0, 16) },
           this.bestPresetForAsset(existing, mime)
         )
@@ -834,7 +835,8 @@ 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",
+        cdnUrl: this.publicUrlOrNull(
           { ...settled, sha: short },
           this.bestPresetForAsset(settled, mime)
         )
@@ -882,9 +884,20 @@ 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",
+      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";