@nitida/sdk 0.32.3 → 0.33.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@nitida/sdk",
-  "version": "0.32.3",
+  "version": "0.33.0",
   "description": "nitida — the media SDK: browser and mobile upload with resume, client-side compression, on-the-fly transforms behind a CDN, video transcode, HLS ladders and AI proxies. Multi-tenant.",
   "private": false,
   "publishConfig": {
@@ -73,7 +73,7 @@
   },
   "peerDependencies": {
     "react": ">=18",
-    "@nitida/asset-client": "^0.20.4",
+    "@nitida/asset-client": "^0.21.0",
     "@nitida/asset-compressor-web": "^0.6.1",
     "@nitida/asset-compressor-native": "^0.2.1"
   },

package/skills/nitida-sdk/SKILL.md

@@ -574,7 +574,9 @@ That replaces the older hand-run provisioning scripts and SQL that used to live
 | Poster | `getAssetUrl({sha}, 'poster')` | `/<tid b36>/v/<sha>-p.webp` |
 | Sha from URL | `extractAssetSha(url)` | — |
 
-Variant preset short codes — **all of them**: `thumb=q, sm=s, md=m, lg=l, xl=x, original=o, poster=p, video=v, aiproxy=a, hls=h, mp3=mp3`. ⚠️ `mp3` is the one irregular case: three characters, not one. Exts: images `webp`, video `mp4`.
+Variant preset short codes — **all of them**: `thumb=q, sm=s, md=m, lg=l, xl=x, original=o, poster=p, video=v, aiproxy=a, mp3=mp3`. ⚠️ `mp3` is the one irregular case: three characters, not one. Exts: images `webp`, video `mp4`.
+
+⚠️ **`hls` is deliberately NOT in that list.** It has an internal short code (`h`), but it is never a URL you can fetch: a ladder is a PREFIX (`<sha16>-hls<dslHash>/master.m3u8`) whose `<dslHash>` is computed server-side, so a hand-built `<sha16>-h.m3u8` **404s on every asset** (measured). Use `getAssetUrl(asset, "hls")` or `getHlsStreamingUrl({ sha })` — see §3c — and never derive the path yourself.
 
 
 ## Private assets — `visibility`

package/src/index.ts

@@ -1090,6 +1090,27 @@ export type UploadOptions = {
  */
 const DEFAULT_UPLOAD_PRESETS: RequestablePreset[] = ["original"];
 
+/**
+ * Fallback for `UploadResult.kind` when the server DTO does not carry one.
+ *
+ * Mirrors what the asset-manager itself does — it branches on the MIME prefix
+ * (`video/` at `process.routes.ts:149`, `audio/` at `:332`, `image/` at
+ * `:972`) and files everything else as `other`. Kept in step deliberately: a
+ * fallback that disagreed with the server would hand a caller a `kind` the
+ * platform never assigned, and `getAssetUrl` now makes decisions on it.
+ *
+ * This should almost never fire — every DTO the API returns carries `kind`.
+ * It exists so the field is never `undefined`, because `undefined` is exactly
+ * how a builder silently opts out of a refusal it should have honoured.
+ */
+function kindForMime(mime: string | undefined): AssetDTO["kind"] {
+  const m = (mime ?? "").toLowerCase();
+  if (m.startsWith("video/")) return "video";
+  if (m.startsWith("audio/")) return "audio";
+  if (m.startsWith("image/")) return "image";
+  return "other";
+}
+
 export type UploadResult = {
   assetId: string;
   sha256: string;
@@ -1165,6 +1186,22 @@ export type UploadResult = {
    * objeto no lo llevaba. El resultado era una URL pública para un asset
    * privado, servida sin una queja, que después da 404.
    */
+  /**
+   * What the asset IS (`image` · `video` · `audio` · `document` · `other`).
+   *
+   * ⭐ It exists because it did not, and the guard caught it before anyone
+   * else did — the FIFTH member of this family, after `sha`, `mime`, `oext`
+   * and `presets`. When `getAssetUrl` learned to refuse `hls` on something
+   * that can never have a ladder, it started READING `kind`; an
+   * `UploadResult` without it silently opted out of the refusal and went
+   * right back to building `/t/format=hls/<sha>.m3u8` — which does not 404,
+   * it answers 200 with the image bytes.
+   *
+   * The rule this keeps re-teaching: a return type that omits what the next
+   * call reads is a silent 404 (or worse, a silent 200). The fix is always to
+   * carry the field, never to write a better error message about its absence.
+   */
+  kind: AssetDTO["kind"];
   visibility: "public" | "private";
   /**
    * La cadena compacta de variantes que EXISTEN (`"lmoqs"`, `"o"`, …).
@@ -1756,6 +1793,7 @@ 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.
+        kind: existing.kind ?? kindForMime(mime),
         visibility: existing.visibility ?? "public",
         presets: existing.presets ?? "",
         variants: existing.variants ?? [],
@@ -1850,6 +1888,7 @@ 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.
+        kind: settled.kind ?? kindForMime(mime),
         visibility: settled.visibility ?? "public",
         presets: settled.presets ?? "",
         variants: settled.variants ?? [],
@@ -1909,6 +1948,7 @@ export class NitidaClient {
       sha: sha.slice(0, 16),
       mime: final.mime ?? mime,
       oext: final.oext ?? null,
+      kind: final.kind ?? kindForMime(final.mime ?? mime),
       visibility: final.visibility ?? "public",
       presets: final.presets ?? "",
       variants: final.variants ?? [],