@nitida/sdk 0.24.1 → 0.25.0

package/dist/index.d.ts

@@ -1,5 +1,5 @@
 import { ResolveSlotOptions, SlotResolution, SlotDTO, VariantPreset, AssetDTO, AssetVariant, TransformOptions, SignedTransformOptions } from '@nitida/asset-client';
-export { AssetDTO, AssetVariant, ResolveSlotOptions, SignedTransformOptions, SlotDTO, SlotResolution, TransformEffect, TransformFit, TransformFormat, TransformGravity, TransformOptions, VariantPreset, computeVariantDimensions, extractAssetSha, getAssetDimensions, getAssetSrcSet, getAssetUrl, getHlsStreamingUrl, getSignedTransformUrl, getTenantId, getTransformSrcSet, getTransformUrl, getVideoTransformUrl, hasPreset, serializeTransform, setTenantId, signTransformUrl } from '@nitida/asset-client';
+export { AssetDTO, AssetPalette, AssetVariant, HlsRung, PRESET_EXT, PRESET_LONG, PRESET_MAX_DIM, PRESET_SHORT, PaletteSwatch, ResolveSlotOptions, SignedTransformOptions, SlotDTO, SlotResolution, TRANSFORM_WIDTHS, TransformEffect, TransformFit, TransformFormat, TransformGravity, TransformOptions, TransformWidth, VariantPreset, bestTextContrast, computeVariantDimensions, configureSlotResolver, contrastRatio, extractAssetSha, getAmbientGradient, getAssetDimensions, getAssetSrcSet, getAssetUrl, getCdnBase, getHlsLadder, getHlsStreamingUrl, getPaletteBlurBackground, getPaletteCssVars, getSignedTransformUrl, getTenantId, getTextColorForBackground, getTransformSrcSet, getTransformUrl, getVideoTransformUrl, hasPreset, hlsLadderAlignment, invalidateSlotCache, iteratePaletteSwatches, pickAmbientBackground, relativeLuminance, resolveSlot, resolveSlots, serializeTransform, setCdnBase, setTenantId, signTransformUrl } from '@nitida/asset-client';
 
 /**
  * @nitida/sdk — universal client for the aquienpz multi-tenant asset
@@ -7,8 +7,8 @@ export { AssetDTO, AssetVariant, ResolveSlotOptions, SignedTransformOptions, Slo
  *
  * One ergonomic facade over the underlying packages
  * (`@nitida/asset-client` URL builders + `@aquienpz/asset-uploader-web`
- * + the slot resolver). Auth is a Better Auth API key (`amk_rt_*`)
- * issued by aquienpz `bootstrap-project.ts`; tenant scope comes from
+ * + the slot resolver). Auth is a bearer API key (`amk_rt_*`), issued
+ * per tenant when the tenant is created; tenant scope comes from
  * the key's metadata (`X-Tenant-Code` is log-only).
  *
  * Usage:
@@ -17,8 +17,8 @@ export { AssetDTO, AssetVariant, ResolveSlotOptions, SignedTransformOptions, Slo
  *
  *   const aq = new NitidaClient({
  *     endpoint: "https://api.nitida.gofuture.space",
- *     apiKey:   process.env.ASSET_MANAGER_RUNTIME_KEY!,
- *     tenantCode: "realtyone-cr",
+ *     apiKey:   process.env.AQUIENPZ_API_KEY!,   // amk_rt_* — server-only
+ *     tenantCode: "acme-co",
  *     cdnBase: "https://8ok.uk",  // optional override
  *     tenantId: 4,                 // required for tenant-prefixed URLs
  *   });
@@ -60,7 +60,7 @@ type NitidaClientOptions = {
      */
     endpoint: string;
     /**
-     * Better Auth API key with the `amk_rt_*` prefix.
+     * Bearer API key with the `amk_rt_*` prefix.
      *
      * **Server-only.** Omit when constructing from `@nitida/sdk/web` —
      * your BFF / route handler injects the bearer header in proxy mode.
@@ -85,8 +85,8 @@ type NitidaClientOptions = {
      * Tenant's HMAC signing key for transform URLs (Phase 3). Required
      * only when calling `aq.transform(asset, opts, { sign: true })`.
      *
-     * Generated server-side per tenant (see `infra/sql/tenants_signed_transforms.sql`);
-     * fetch via `GET /admin/tenants/:id` with an admin key. **Keep it
+     * 32 random bytes, generated server-side on tenant creation; fetch
+     * via `GET /admin/tenants/:id` with an admin key. **Keep it
      * server-side only** — do not ship in `NEXT_PUBLIC_*` env vars. Sign
      * URLs from a BFF route handler, or pre-sign at build time.
      */
@@ -214,7 +214,7 @@ type UploadVideoOptions = {
     hls?: boolean;
     /**
      * `true` → when the uploaded MP4 is ALREADY web-safe (H.264 + yuv420p),
-     * re-mux the `video` variant with `-c copy` instead of re-encoding. Use for
+     * re-mux the `video` variant instead of re-encoding it. Use for
      * delivery-ready uploads (the bytes are already H.264 High / yuv420p /
      * +faststart / capped bitrate) to skip a wasteful re-encode + generational
      * quality loss. Falls back to a full re-encode automatically when the source
@@ -239,8 +239,8 @@ type PresignUploadUrlOptions = {
     presets?: VariantPreset[];
     /**
      * Pre-compression size of the source (useful when the browser ran
-     * compressorjs / heic2any before computing `bytes`). Surfaces in admin
-     * dashboards under `assets.client_original_bytes`.
+     * compressorjs / heic2any before computing `bytes`). Recorded
+     * server-side, so the savings show up in the admin usage dashboards.
      */
     clientOriginalBytes?: number;
     /** VIDEO-only delivery knobs forwarded into `/assets/process`. See {@link UploadVideoOptions}. */
@@ -318,8 +318,8 @@ declare class AssetsApi {
      *   const v = await aq.assets.variants(logoId);
      *   v.map((x) => x.preset);  // → ("thumb" | "sm" | … | "original")[]
      *
-     * ⚠️ Returns `[]` — not an error — against a server deploy older than the
-     * 2026-08-17 deploy, which never sent the field (doc 240 §4.3). An empty
+     * ⚠️ Returns `[]` — not an error — against a server older than the
+     * 2026-08-17 release, which never sent the field at all. An empty
      * array is therefore "no variants OR old server". For a plain existence
      * check prefer `hasPreset(dto, preset)` on `dto.presets`, which every server
      * version sends; use this when you need the URLs and sizes.
@@ -342,12 +342,13 @@ declare class AssetsApi {
      * Passing no presets re-runs the FULL default pipeline for that
      * asset's kind (thumb+sm+md+lg for images, poster+video for video).
      *
-     * If the asset was uploaded original-only and the cleanup job has
-     * already reaped `raw/`, the route falls back to reading the source
-     * bytes from `variants/o.<ext>` — no need to re-upload.
+     * If the asset was uploaded original-only and the ~24 h grace window
+     * on the uploaded bytes has already closed, the route falls back to
+     * reading the source bytes from the permanent `original` variant —
+     * no need to re-upload.
      *
      * Video presets are filtered to `["poster","video","aiproxy"]` and
-     * dispatched to the background job (the call returns immediately
+     * dispatched to a background job (the call returns immediately
      * with a dispatch handle; poll `aq.assets.get(id).status` for
      * completion).
      */
@@ -509,8 +510,8 @@ type UploadOptions = {
     /**
      * 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
-     * videos / HLS transcodes — aquienpz processing time scales with input
-     * size and per-instance CPU.
+     * videos / HLS transcodes — processing time scales with input size,
+     * and with how much other work the platform is doing at that moment.
      *
      * Throws `Error("waitReady timeout for <id>")` if the deadline passes
      * without the asset transitioning. The asset row stays in aquienpz
@@ -572,11 +573,11 @@ type UsageWindow = {
      * encode passes, so a 7-rung HLS ladder over a 2-minute clip books 14.
      *
      * A re-encode of a video already ingested counts AGAIN. That is the point:
-     * `assets.assets` cannot report it, because its insert is
-     * `ON CONFLICT DO UPDATE` and a re-encode creates no row there.
+     * an asset count cannot report it, because re-encoding an asset that already
+     * exists creates no new asset.
      *
-     * A stream copy (`-c copy` passthrough, an idempotent cache skip) books
-     * nothing, so a tenant that ran no encoder reads `0` — and that `0` is real.
+     * A stream copy (`video: { passthrough: true }`, or an idempotent cache skip)
+     * books nothing, so a tenant that ran no encoder reads `0` — and that `0` is real.
      */
     videoMinutes: number;
     /** Encode passes behind `videoMinutes`. 0 when nothing was encoded. */
@@ -708,7 +709,7 @@ declare class NitidaClient {
      * images).
      *
      * On the first request the route returns **202 Accepted** with
-     * `Retry-After: 10` while the Job runs (typically 5-30 s for a
+     * `Retry-After: 10` while the encode runs (typically 5-30 s for a
      * short clip). The response body includes `outputUrl` which is the
      * eventual CDN URL — poll the same transform URL after the
      * retry-after window to get a 302 redirect to it.
@@ -768,8 +769,8 @@ declare class NitidaClient {
      *
      * ⚠️ `presets` decides what exists FOREVER. Omit it and only `original` is written; ask for
      * `["thumb"]` and the bytes you just uploaded are **not retrievable**. A variant not requested in
-     * this first ingest cannot be added later once the cleanup job reaps `raw/` — measured once as
-     * "97 files archived successfully, zero recoverable".
+     * this first ingest cannot be added later once the ~24 h grace window on the uploaded bytes
+     * closes — measured once as "97 files archived successfully, zero recoverable".
      *
      * @example Deliver an image on a site (the responsive ladder)
      * ```ts
@@ -800,7 +801,7 @@ declare class NitidaClient {
      * @example Video — and what does NOT work there
      * ```ts
      * // `original` is accepted and then silently DROPPED: /assets/process filters video presets to
-     * // {poster, video, aiproxy, probe} before dispatching the transcode Job.
+     * // {poster, video, aiproxy, probe} before dispatching the background transcode.
      * await aq.upload(clip, { fileName: "tour.mp4", presets: ["poster", "video"] });
      *
      * // Omit `aiproxy`/`probe` unless the asset really goes to a vision model — they cost encode

package/dist/index.js

@@ -16,21 +16,43 @@ import {
   setTenantId
 } from "@nitida/asset-client";
 import {
+  bestTextContrast,
   computeVariantDimensions,
+  configureSlotResolver as configureSlotResolver2,
+  contrastRatio,
   extractAssetSha,
+  getAmbientGradient,
   getAssetDimensions,
   getAssetSrcSet as getAssetSrcSet2,
   getAssetUrl as getAssetUrl2,
+  getCdnBase,
+  getHlsLadder,
   getHlsStreamingUrl as getHlsStreamingUrl2,
+  getPaletteBlurBackground,
+  getPaletteCssVars,
   getSignedTransformUrl as getSignedTransformUrl2,
   getTenantId,
+  getTextColorForBackground,
   getTransformSrcSet as getTransformSrcSet2,
   getTransformUrl as getTransformUrl2,
   getVideoTransformUrl as getVideoTransformUrl2,
   hasPreset as hasPreset2,
+  hlsLadderAlignment,
+  invalidateSlotCache as invalidateSlotCache2,
+  iteratePaletteSwatches,
+  PRESET_EXT,
+  PRESET_LONG,
+  PRESET_MAX_DIM,
+  PRESET_SHORT,
+  pickAmbientBackground,
+  relativeLuminance,
+  resolveSlot as resolveSlot2,
+  resolveSlots as resolveSlots2,
   serializeTransform,
+  setCdnBase as setCdnBase2,
   setTenantId as setTenantId2,
-  signTransformUrl
+  signTransformUrl,
+  TRANSFORM_WIDTHS
 } from "@nitida/asset-client";
 function endpointUrl(opts, path, searchParams) {
   const endpoint = opts.endpoint.replace(/\/+$/, "");
@@ -223,8 +245,8 @@ var AssetsApi = class {
    *   const v = await aq.assets.variants(logoId);
    *   v.map((x) => x.preset);  // → ("thumb" | "sm" | … | "original")[]
    *
-   * ⚠️ Returns `[]` — not an error — against a server deploy older than the
-   * 2026-08-17 deploy, which never sent the field (doc 240 §4.3). An empty
+   * ⚠️ Returns `[]` — not an error — against a server older than the
+   * 2026-08-17 release, which never sent the field at all. An empty
    * array is therefore "no variants OR old server". For a plain existence
    * check prefer `hasPreset(dto, preset)` on `dto.presets`, which every server
    * version sends; use this when you need the URLs and sizes.
@@ -250,12 +272,13 @@ var AssetsApi = class {
    * Passing no presets re-runs the FULL default pipeline for that
    * asset's kind (thumb+sm+md+lg for images, poster+video for video).
    *
-   * If the asset was uploaded original-only and the cleanup job has
-   * already reaped `raw/`, the route falls back to reading the source
-   * bytes from `variants/o.<ext>` — no need to re-upload.
+   * If the asset was uploaded original-only and the ~24 h grace window
+   * on the uploaded bytes has already closed, the route falls back to
+   * reading the source bytes from the permanent `original` variant —
+   * no need to re-upload.
    *
    * Video presets are filtered to `["poster","video","aiproxy"]` and
-   * dispatched to the background job (the call returns immediately
+   * dispatched to a background job (the call returns immediately
    * with a dispatch handle; poll `aq.assets.get(id).status` for
    * completion).
    */
@@ -558,7 +581,7 @@ var NitidaClient = class {
    * images).
    *
    * On the first request the route returns **202 Accepted** with
-   * `Retry-After: 10` while the Job runs (typically 5-30 s for a
+   * `Retry-After: 10` while the encode runs (typically 5-30 s for a
    * short clip). The response body includes `outputUrl` which is the
    * eventual CDN URL — poll the same transform URL after the
    * retry-after window to get a 302 redirect to it.
@@ -622,8 +645,8 @@ var NitidaClient = class {
    *
    * ⚠️ `presets` decides what exists FOREVER. Omit it and only `original` is written; ask for
    * `["thumb"]` and the bytes you just uploaded are **not retrievable**. A variant not requested in
-   * this first ingest cannot be added later once the cleanup job reaps `raw/` — measured once as
-   * "97 files archived successfully, zero recoverable".
+   * this first ingest cannot be added later once the ~24 h grace window on the uploaded bytes
+   * closes — measured once as "97 files archived successfully, zero recoverable".
    *
    * @example Deliver an image on a site (the responsive ladder)
    * ```ts
@@ -654,7 +677,7 @@ var NitidaClient = class {
    * @example Video — and what does NOT work there
    * ```ts
    * // `original` is accepted and then silently DROPPED: /assets/process filters video presets to
-   * // {poster, video, aiproxy, probe} before dispatching the transcode Job.
+   * // {poster, video, aiproxy, probe} before dispatching the background transcode.
    * await aq.upload(clip, { fileName: "tour.mp4", presets: ["poster", "video"] });
    *
    * // Omit `aiproxy`/`probe` unless the asset really goes to a vision model — they cost encode
@@ -788,20 +811,42 @@ var NitidaClient = class {
 };
 export {
   NitidaClient,
+  PRESET_EXT,
+  PRESET_LONG,
+  PRESET_MAX_DIM,
+  PRESET_SHORT,
+  TRANSFORM_WIDTHS,
+  bestTextContrast,
   computeVariantDimensions,
+  configureSlotResolver2 as configureSlotResolver,
+  contrastRatio,
   extractAssetSha,
+  getAmbientGradient,
   getAssetDimensions,
   getAssetSrcSet2 as getAssetSrcSet,
   getAssetUrl2 as getAssetUrl,
+  getCdnBase,
+  getHlsLadder,
   getHlsStreamingUrl2 as getHlsStreamingUrl,
+  getPaletteBlurBackground,
+  getPaletteCssVars,
   getSignedTransformUrl2 as getSignedTransformUrl,
   getTenantId,
+  getTextColorForBackground,
   getTransformSrcSet2 as getTransformSrcSet,
   getTransformUrl2 as getTransformUrl,
   getVideoTransformUrl2 as getVideoTransformUrl,
   hasPreset2 as hasPreset,
+  hlsLadderAlignment,
+  invalidateSlotCache2 as invalidateSlotCache,
+  iteratePaletteSwatches,
   mimeFromFileName,
+  pickAmbientBackground,
+  relativeLuminance,
+  resolveSlot2 as resolveSlot,
+  resolveSlots2 as resolveSlots,
   serializeTransform,
+  setCdnBase2 as setCdnBase,
   setTenantId2 as setTenantId,
   signTransformUrl
 };