@nitida/sdk 0.36.2 → 0.37.0

package/README.md

@@ -608,7 +608,7 @@ this table from the source, so it can't have the wrong one.
 | `sm`      | `s`  | 640                | mobile thumbs, list cards |
 | `md`      | `m`  | 1280               | desktop cards, modal previews |
 | `lg`      | `l`  | 1920 (≈2K)         | hero, full-bleed |
-| `xl`      | `x`  | 3840 (4K)          | print, 4K screens |
+| `xl`      | `x`  | 3840 (4K)          | print, 4K screens · a clean WebP base ≤ 3840 is reused as-is |
 
 **Defaults — what actually runs:**
 
@@ -644,6 +644,16 @@ the full responsive ladder ≈ 4× source bytes.
 (3840) yields a 1080×720 `xl` variant, not a blurry 3840-wide stretch.
 The preset is a **ceiling**, not a target.
 
+**`xl` reuses a ≤ 4K base byte-for-byte.** 4K is the cap for listing
+photos. When the uploaded base is a clean WebP no larger than 3840 px
+(single frame, no EXIF orientation, no EXIF/XMP), the server stores it
+as `xl` unchanged: same sha256, no second lossy pass. Anything else (a
+larger base, JPEG/PNG/HEIC, animated or EXIF-bearing WebP) is re-encoded
+to WebP q82 as before. The default `compressImage` output (3840 px WebP)
+qualifies. URLs, keys and response shapes do not change; `xl` is still
+its own object, the same size as the base. Already-stored assets keep
+their existing `xl`.
+
 ### Non-image / passthrough
 
 | Preset    | Code | Purpose |

package/dist/index.d.ts

@@ -1,5 +1,5 @@
-import { ResolveSlotOptions, SlotResolution, SlotDTO, VariantPreset, AssetDTO, AssetVariant, RequestablePreset, TransformOptions, SignedTransformOptions, SignTransformOptions, TransformWidth } from '@nitida/asset-client';
-export { AssetDTO, AssetPalette, AssetVariant, HlsRung, MAX_SIGNED_TRANSFORM_TTL_SECONDS, MAX_SIGNED_URL_TTL_SECONDS, MIN_SIGNED_TRANSFORM_TTL_SECONDS, PRESET_EXT, PRESET_LONG, PRESET_MAX_DIM, PRESET_SHORT, PaletteSwatch, PrivateTransformOptions, REQUESTABLE_PRESETS, RequestablePreset, ResolveSlotOptions, SignAccessOptions, SignTransformOptions, SignedTransformOptions, SlotDTO, SlotResolution, TRANSFORM_WIDTHS, TransformEffect, TransformFit, TransformFormat, TransformGravity, TransformOptions, TransformWidth, VariantEntryPreset, VariantPreset, VisibilityHint, accessMessage, assertPublic, assertSha, bestTextContrast, computeVariantDimensions, configureSlotResolver, contrastRatio, deriveAccessKey, deriveTransformKid, extractAssetSha, getAmbientGradient, getAssetDimensions, getAssetSrcSet, getAssetUrl, getByteBudgetTransformUrl, getCdnBase, getHlsLadder, getHlsStreamingUrl, getPaletteBlurBackground, getPaletteCssVars, getPrivateAssetUrl, getPrivateTransformUrl, getSignedTransformUrl, getTenantId, getTextColorForBackground, getTransformSrcSet, getTransformUrl, getVideoTransformUrl, hasPreset, hasSizeLadder, hlsLadderAlignment, invalidateSlotCache, isRequestablePreset, iteratePaletteSwatches, pickAmbientBackground, relativeLuminance, resolveSlot, resolveSlots, serializeTransform, setCdnBase, setTenantId, signAccessUrl, signTransformUrl, toRequestablePresets, transformMessage } from '@nitida/asset-client';
+import { ResolveSlotOptions, SlotResolution, SlotDTO, VariantPreset, AssetDTO, AssetVariant, RequestablePreset, ImageRole, TransformOptions, SignedTransformOptions, SignTransformOptions, TransformWidth } from '@nitida/asset-client';
+export { AssetDTO, AssetPalette, AssetVariant, HlsRung, IMAGE_LADDER, IMAGE_ROLES, IMAGE_ROLE_LADDERS, ImageRole, MAX_SIGNED_TRANSFORM_TTL_SECONDS, MAX_SIGNED_URL_TTL_SECONDS, MIN_SIGNED_TRANSFORM_TTL_SECONDS, PRESET_EXT, PRESET_LONG, PRESET_MAX_DIM, PRESET_SHORT, PaletteSwatch, PrivateTransformOptions, REQUESTABLE_PRESETS, RequestablePreset, ResolveSlotOptions, SignAccessOptions, SignTransformOptions, SignedTransformOptions, SlotDTO, SlotResolution, TRANSFORM_WIDTHS, TransformEffect, TransformFit, TransformFormat, TransformGravity, TransformOptions, TransformWidth, VariantEntryPreset, VariantPreset, VisibilityHint, accessMessage, assertPublic, assertSha, bestTextContrast, computeVariantDimensions, configureSlotResolver, contrastRatio, deriveAccessKey, deriveTransformKid, extractAssetSha, getAmbientGradient, getAssetDimensions, getAssetSrcSet, getAssetUrl, getByteBudgetTransformUrl, getCdnBase, getHlsLadder, getHlsStreamingUrl, getPaletteBlurBackground, getPaletteCssVars, getPrivateAssetUrl, getPrivateTransformUrl, getRoleLadder, getRolesLadder, getSignedTransformUrl, getTenantId, getTextColorForBackground, getTransformSrcSet, getTransformUrl, getVideoTransformUrl, hasPreset, hasSizeLadder, hlsLadderAlignment, invalidateSlotCache, isImageRole, isRequestablePreset, iteratePaletteSwatches, pickAmbientBackground, relativeLuminance, resolveSlot, resolveSlots, serializeTransform, setCdnBase, setTenantId, signAccessUrl, signTransformUrl, toRequestablePresets, transformMessage } from '@nitida/asset-client';
 
 /**
  * Which audio uploads already play everywhere — the single source of truth for
@@ -300,6 +300,14 @@ 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(...)`. */
 type ComposeMarketingSegment = {
@@ -604,6 +612,14 @@ 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

package/dist/index.js

@@ -75,6 +75,12 @@ import {
   signAccessUrl,
   signTransformUrl,
   TRANSFORM_WIDTHS,
+  getRoleLadder,
+  getRolesLadder,
+  IMAGE_LADDER,
+  IMAGE_ROLE_LADDERS,
+  IMAGE_ROLES,
+  isImageRole,
   toRequestablePresets as toRequestablePresets2,
   transformMessage
 } from "@nitida/asset-client";
@@ -395,6 +401,7 @@ var AssetsApi = class {
     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",
       headers: { ...this.headers(), "Content-Type": "application/json" },
@@ -821,7 +828,8 @@ var NitidaClient = class {
       fileName,
       presets: opts.presets && opts.presets.length > 0 ? opts.presets : DEFAULT_UPLOAD_PRESETS,
       ...clientOriginalBytes != null && { clientOriginalBytes },
-      ...opts.video != null && { video: opts.video }
+      ...opts.video != null && { video: opts.video },
+      ...opts.warm && opts.warm.length > 0 && { warm: opts.warm }
     });
     if (presign.deduped) {
       const short = sha.slice(0, 16);
@@ -972,6 +980,9 @@ var NitidaClient = class {
   }
 };
 export {
+  IMAGE_LADDER,
+  IMAGE_ROLES,
+  IMAGE_ROLE_LADDERS,
   MAX_SIGNED_TRANSFORM_TTL_SECONDS,
   MAX_SIGNED_URL_TTL_SECONDS,
   MIN_SIGNED_TRANSFORM_TTL_SECONDS,
@@ -1004,6 +1015,8 @@ export {
   getPaletteCssVars,
   getPrivateAssetUrl,
   getPrivateTransformUrl,
+  getRoleLadder,
+  getRolesLadder,
   getSignedTransformUrl2 as getSignedTransformUrl,
   getTenantId,
   getTextColorForBackground,
@@ -1014,6 +1027,7 @@ export {
   hasSizeLadder,
   hlsLadderAlignment,
   invalidateSlotCache2 as invalidateSlotCache,
+  isImageRole,
   isRequestablePreset2 as isRequestablePreset,
   isUniversallyPlayableAudio,
   iteratePaletteSwatches,