@nitida/sdk 0.36.3 → 0.37.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@nitida/sdk",
-  "version": "0.36.3",
+  "version": "0.37.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.24.1",
+    "@nitida/asset-client": "^0.25.0",
     "@nitida/asset-compressor-web": "^0.6.1",
     "@nitida/asset-compressor-native": "^0.2.1"
   },

package/src/index.ts

@@ -59,6 +59,7 @@ import {
   type SignTransformOptions,
   type SlotDTO,
   type SlotResolution,
+  type ImageRole,
   setCdnBase,
   setTenantId,
   type TransformOptions,
@@ -241,6 +242,7 @@ export type {
   TransformGravity,
   TransformOptions,
   TransformWidth,
+  ImageRole,
   VariantEntryPreset,
   VariantPreset,
   VisibilityHint,
@@ -298,6 +300,12 @@ export {
   signAccessUrl,
   signTransformUrl,
   TRANSFORM_WIDTHS,
+  getRoleLadder,
+  getRolesLadder,
+  IMAGE_LADDER,
+  IMAGE_ROLE_LADDERS,
+  IMAGE_ROLES,
+  isImageRole,
   toRequestablePresets,
   transformMessage,
 } from "@nitida/asset-client";
@@ -534,6 +542,14 @@ export type PresignUploadUrlOptions = {
   clientOriginalBytes?: number;
   /** VIDEO-only delivery knobs forwarded into `/assets/process`. See {@link UploadVideoOptions}. */
   video?: UploadVideoOptions;
+  /**
+   * Image roles whose transform ladder (`IMAGE_ROLE_LADDERS`) the platform warms
+   * at the CDN edge once the asset is ready, so the first visitor does not pay
+   * a cold encode. Omit to warm nothing. Ignored for non-images and when the
+   * bytes were already stored (a deduped upload runs no processing; use the
+   * backfill for those).
+   */
+  warm?: ImageRole[];
 };
 
 /** Input shape accepted by `aq.assets.composeMarketing(...)`. */
@@ -794,6 +810,7 @@ class AssetsApi {
     if (opts.clientOriginalBytes != null)
       body.clientOriginalBytes = opts.clientOriginalBytes;
     if (opts.video != null) body.video = opts.video;
+    if (opts.warm && opts.warm.length > 0) body.warm = opts.warm;
 
     const r = await fetch(endpointHref(this.opts, "/assets/upload-url"), {
       method: "POST",
@@ -1075,6 +1092,14 @@ export type UploadOptions = {
    * any audio original — and asking for either is a 400.
    */
   presets?: RequestablePreset[];
+  /**
+   * Image roles whose transform ladder (`IMAGE_ROLE_LADDERS`) the platform warms
+   * at the CDN edge once the asset is ready, so the first visitor does not pay
+   * a cold encode. Omit to warm nothing. Ignored for non-images and when the
+   * bytes were already stored (a deduped upload runs no processing; use the
+   * backfill for those).
+   */
+  warm?: ImageRole[];
   /**
    * Max time to wait for the asset to transition to `ready` (or `failed`)
    * after dispatch. Default `5 * 60_000` (5 min). Bump higher for large
@@ -1848,6 +1873,7 @@ export class NitidaClient {
           : DEFAULT_UPLOAD_PRESETS,
       ...(clientOriginalBytes != null && { clientOriginalBytes }),
       ...(opts.video != null && { video: opts.video }),
+      ...(opts.warm && opts.warm.length > 0 && { warm: opts.warm }),
     });
     if (presign.deduped) {
       const short = sha.slice(0, 16);

package/src/server/index.ts

@@ -167,12 +167,19 @@ export {
   signAccessUrl,
   signTransformUrl,
   TRANSFORM_WIDTHS,
+  getRoleLadder,
+  getRolesLadder,
+  IMAGE_LADDER,
+  IMAGE_ROLE_LADDERS,
+  IMAGE_ROLES,
+  isImageRole,
   type TransformEffect,
   type TransformFit,
   type TransformFormat,
   type TransformGravity,
   type TransformOptions,
   type TransformWidth,
+  type ImageRole,
   toRequestablePresets,
   transformMessage,
   type UploadOptions,

package/src/web/index.ts

@@ -193,12 +193,19 @@ export {
   signAccessUrl,
   signTransformUrl,
   TRANSFORM_WIDTHS,
+  getRoleLadder,
+  getRolesLadder,
+  IMAGE_LADDER,
+  IMAGE_ROLE_LADDERS,
+  IMAGE_ROLES,
+  isImageRole,
   type TransformEffect,
   type TransformFit,
   type TransformFormat,
   type TransformGravity,
   type TransformOptions,
   type TransformWidth,
+  type ImageRole,
   toRequestablePresets,
   transformMessage,
   type UploadOptions,