@nitida/asset-client 0.14.2

package/dist/index.d.ts

@@ -0,0 +1,560 @@
+/**
+ * Color palette helpers — render harmonious ambient backgrounds behind
+ * product images, inspired by Spotify Now Playing / Apple Music / Pico.
+ *
+ * Wire format is intentionally compact: only the hex per swatch, only the
+ * swatches the source actually had. The full names map to 1-2 letter aliases
+ * (`d` dominant, `v` vibrant, `m` muted, `dv` darkVibrant, `lv` lightVibrant,
+ * `dm` darkMuted, `lm` lightMuted) to shave bytes for catalog-sized payloads
+ * (palette was 62% of asset DTO before this).
+ *
+ * Population + RGB array + textColor are derivable client-side; we don't
+ * ship them. textColor is computed via WCAG relative luminance on demand.
+ */
+/** Compact wire shape for an asset's palette. All swatches optional except dominant. */
+type AssetPalette = {
+    /** dominant hex (always present when palette exists) */
+    d: string;
+    /** vibrant */ v?: string;
+    /** muted */ m?: string;
+    /** darkVibrant */ dv?: string;
+    /** lightVibrant */ lv?: string;
+    /** darkMuted */ dm?: string;
+    /** lightMuted */ lm?: string;
+};
+/** Backwards-compat alias for older callers that referenced PaletteSwatch. */
+type PaletteSwatch = {
+    hex: string;
+    textColor: "#000000" | "#FFFFFF";
+};
+/**
+ * Pick the swatch best suited for an ambient surface behind the image.
+ * Prefers muted/light tones — too vibrant a background fights the image.
+ *
+ * Order: lightMuted → muted → lightVibrant → dominant.
+ */
+declare function pickAmbientBackground(palette: AssetPalette | null | undefined): PaletteSwatch | null;
+/**
+ * Build a CSS linear-gradient from the palette. Useful for hero / detail
+ * backgrounds.
+ */
+declare function getAmbientGradient(palette: AssetPalette | null | undefined, opts?: {
+    angle?: string;
+    from?: keyof AssetPalette;
+    to?: keyof AssetPalette;
+}): string | undefined;
+/**
+ * Recommended text color (#000 or #FFF) for any background hex,
+ * computed via WCAG relative luminance.
+ */
+declare function getTextColorForBackground(swatch: PaletteSwatch | string | null | undefined): string;
+/**
+ * CSS variables for a wrapper so a subtree can read --asset-bg / --asset-fg /
+ * --asset-dominant / --asset-vibrant / etc.
+ */
+declare function getPaletteCssVars(palette: AssetPalette | null | undefined): Record<string, string>;
+/**
+ * Iterate the palette in display order (dominant first, then vibrant +
+ * muted families). Useful for rendering a swatch strip in admin UIs.
+ */
+declare function iteratePaletteSwatches(palette: AssetPalette | null | undefined): Array<{
+    key: keyof AssetPalette;
+    label: string;
+    hex: string;
+}>;
+/**
+ * Build a multi-radial-gradient CSS `background` string from the palette
+ * swatches. Acts as a zero-extra-bytes alternative to the WebP LQIP: the
+ * palette is already in the DTO, so this placeholder costs nothing extra
+ * to ship. Renders as a smooth abstract "color cloud" reminiscent of the
+ * source image's vibe.
+ *
+ * Strategy: anchor 4 radial gradients at fixed corners using vibrant/muted
+ * pairs, layered over the dominant fill. Skips missing swatches gracefully.
+ */
+declare function getPaletteBlurBackground(palette: AssetPalette | null | undefined): string | undefined;
+
+/**
+ * @nitida/asset-client/slots — slot resolver for tenant-named assets.
+ *
+ * Slots give tenants a way to attach stable, human-readable names
+ * ("webapp.wizard.pool-type.icon-1", "storefront.cr.hero-video.landscape_hd_16x9.mp4")
+ * to assets they uploaded. Consumers resolve names → AssetDTOs at
+ * build / runtime so their source never hardcodes a CDN URL; the
+ * admin rebinds a slot from `asset-lab-web` and every consumer picks
+ * up the swap on cache refresh.
+ *
+ * Two layers in this package:
+ *   - `resolveSlot` / `resolveSlots` — universal (server, edge,
+ *     workers) fetch helpers. Cache 60s by default.
+ *   - React hooks live in `@nitida/asset-client/react/use-slot`
+ *     (kept out of this module so the SSR-safe core stays
+ *     dependency-free of react).
+ */
+
+type SlotDTO = {
+    slotKey: string;
+    /** Preset hint set when the slot was bound (e.g. `thumb` for icon slots). */
+    preset: VariantPreset | null;
+    description: string | null;
+    updatedAt: string;
+    asset: AssetDTO;
+};
+type SlotResolution = {
+    /** The resolved DTO (`null` when the slot is unbound or asset missing). */
+    slot: SlotDTO | null;
+    /**
+     * Effective preset — what `url` below was built with. Resolution order:
+     *   1. caller's `preset` override
+     *   2. slot's `preset` hint
+     *   3. `lg` for images, `video` for video kind
+     */
+    preset: VariantPreset;
+    /** The CDN URL the consumer should use. */
+    url: string | null;
+};
+/**
+ * Configure the resolver process-wide. Call once at boot from your
+ * storefront layout / server entry / worker init.
+ *
+ *   configureSlotResolver({
+ *     endpoint: process.env.AQUIENPZ_URL,
+ *     apiKey:   process.env.ASSET_MANAGER_RUNTIME_KEY,
+ *     tenantCode: "realtyone-cr",
+ *   });
+ */
+declare function configureSlotResolver(opts: {
+    endpoint?: string;
+    apiKey?: string;
+    tenantCode?: string;
+}): void;
+/** Wipe the in-process cache (test helper or forced refresh). */
+declare function invalidateSlotCache(slotKey?: string): void;
+type ResolveSlotOptions = {
+    /** Override preset (caller knows the use case better than the slot binding). */
+    preset?: VariantPreset;
+    /** TTL for the in-process cache. Default 60s. Set 0 to bypass. */
+    ttlMs?: number;
+};
+/**
+ * Resolve a single slot to a CDN URL. Returns `{slot: null, url: null}`
+ * when the slot is unbound — callers fall back to a placeholder.
+ *
+ * Cached for `ttlMs` (default 60s). Slot rebindings propagate within the
+ * TTL window without an app restart.
+ */
+declare function resolveSlot(slotKey: string, opts?: ResolveSlotOptions): Promise<SlotResolution>;
+/**
+ * Bulk-resolve N slot keys in one round-trip. The SDK's `useSlots`
+ * React hook calls this so every storefront header (logo + tagline +
+ * nav cover + …) loads as one request.
+ */
+declare function resolveSlots(slotKeys: string[], opts?: ResolveSlotOptions): Promise<Record<string, SlotResolution>>;
+
+/**
+ * On-the-fly transform URL builder.
+ *
+ * Mirrors the server's DSL canonicalizer byte-for-byte so a URL generated
+ * here hashes to the same R2 cache key as the server's canonical form.
+ *
+ * Canonicalization rules (keep in sync with
+ * `apps/asset-manager/src/features/assets/transform.dsl.ts`):
+ *   - Drop entries whose value is `undefined`
+ *   - Sort keys alphabetically
+ *   - Numbers rendered without leading zeros or trailing dots
+ *   - String values lowercased
+ *
+ * URL shape:
+ *   <cdnBase>/t/<dsl>/<sha>.<ext>
+ *
+ * The `.ext` is informational (browser content-sniff hint); the server
+ * decides the actual output format from the DSL `format` param + the
+ * request's Accept header.
+ */
+
+/**
+ * Widths the CDN edge whitelists (DoS guard — see `apps/cdn-proxy` WHITELIST_WIDTHS).
+ * Requesting any OTHER width returns HTTP 400 at the edge (unsigned URLs). These are the
+ * 1× base ladder values; DPR ×2/×3 multiples are applied + whitelisted server-side. Import
+ * this instead of hardcoding magic widths so an unsupported size is caught in review/IDE.
+ */
+declare const TRANSFORM_WIDTHS: readonly [96, 128, 160, 240, 256, 320, 400, 480, 600, 640, 800, 960, 1080, 1200, 1280, 1440, 1600, 1920, 2560, 3840];
+/**
+ * A CDN-whitelisted transform width — the only widths `TransformOptions.width`
+ * accepts. Off-ladder widths are a compile error; for signed URLs that need a
+ * custom width, use {@link SignedTransformOptions} (number) via
+ * {@link getSignedTransformUrl} / `aq.transform(asset, opts, { sign: true })`.
+ */
+type TransformWidth = (typeof TRANSFORM_WIDTHS)[number];
+type TransformFit = "cover" | "contain" | "fill" | "inside" | "outside";
+type TransformGravity = "auto" | "face" | "center" | "north" | "south" | "east" | "west";
+type TransformFormat = "auto" | "avif" | "webp" | "jpeg" | "png" | "mp4" | "webm" | "hls";
+type TransformEffect = "removebg" | "genfill";
+type TransformOptions = {
+    /**
+     * Target max-side width in CSS pixels (multiplied by `dpr` server-side).
+     * MUST be a {@link TRANSFORM_WIDTHS} value — off-ladder widths are rejected
+     * (HTTP 400) by the edge whitelist for unsigned URLs, so the type forbids
+     * them at compile time. For SIGNED URLs with a custom width, use
+     * {@link SignedTransformOptions} (which widens this to `number`).
+     */
+    width?: TransformWidth;
+    /** Target max-side height. Multiplied by `dpr` server-side. */
+    height?: number;
+    /** Resize fit mode. Default `cover` server-side. */
+    fit?: TransformFit;
+    /** Crop gravity. `auto` uses sharp's `attention` strategy. */
+    gravity?: TransformGravity;
+    /** Output format. `auto` → policy decides (see asset-manager bench). */
+    format?: TransformFormat;
+    /** Output quality. `auto` → format-specific default. */
+    quality?: "auto" | number;
+    /** Device pixel ratio. Width/height are multiplied by this before resize. */
+    dpr?: 1 | 2 | 3;
+    /**
+     * AI effect applied before resize/encode.
+     *
+     *   - `removebg`: remove the background; output is a transparent PNG
+     *     of the foreground subject. Forces `format=png` regardless of
+     *     other format hints. Runs U²-Net ONNX locally (or BRIA via
+     *     Replicate when `BG_REMOVAL_BACKEND=replicate`). Single cache
+     *     miss per (sha, dsl) tuple; subsequent identical DSLs serve
+     *     from R2 — no inference, no per-image cost.
+     *
+     *   - `genfill`: aspect-extension outpaint via Flux-Fill Pro on
+     *     Replicate. Requires BOTH `width` and `height` — the server
+     *     fits the source centered into the target canvas and outpaints
+     *     the gutters. Output is PNG (forced) at exactly target dims.
+     *     ~$0.05/image first time; same R2 cache as removebg after.
+     *     Primary use case: building OG cards (1200×630) from portrait
+     *     listing photos without awkward edge mirroring.
+     */
+    effect?: TransformEffect;
+    /**
+     * Video-only: clip start in seconds. Image transforms ignore.
+     * Accepts decimals (e.g. 1.5 for sub-second seek).
+     */
+    start?: number;
+    /**
+     * Video-only: clip duration in seconds (1..300). Image transforms
+     * ignore. With `start`, lets a single request grab a sub-clip.
+     */
+    duration?: number;
+};
+/**
+ * Like {@link TransformOptions} but with `width` widened to any `number` —
+ * the escape hatch for SIGNED URLs that need an off-ladder custom width.
+ *
+ * The edge whitelist only rejects off-ladder widths on UNSIGNED URLs; a valid
+ * `?sig=` earns the whitelist bypass at the worker (the asset-manager still
+ * does the real HMAC check). So a custom width is ONLY safe when the URL is
+ * signed — hence this type is accepted exclusively by the signing helpers
+ * ({@link getSignedTransformUrl} / `aq.transform(asset, opts, { sign: true })`),
+ * never by the plain unsigned {@link getTransformUrl}.
+ */
+type SignedTransformOptions = Omit<TransformOptions, "width"> & {
+    /** Off-ladder width — valid ONLY on signed URLs (edge whitelist bypass). */
+    width?: number;
+};
+/**
+ * Serialize transform options into the canonical DSL path segment.
+ * Empty options return an empty string (caller should fall back to a
+ * variant URL instead of a transform URL in that case).
+ *
+ * Accepts {@link SignedTransformOptions} (the wider type) so it also covers
+ * custom-width signed URLs; {@link TransformOptions} is assignable to it.
+ */
+/**
+ * Extract the 16-hex short sha from an aquienpz CDN URL, regardless of
+ * shape:
+ *   - tenant-prefixed variant:  `https://8ok.uk/4/v/<sha16>-<preset>.<ext>`
+ *   - legacy variant:           `https://8ok.uk/<sha16>-<preset>.<ext>`
+ *   - on-the-fly transform:     `https://8ok.uk/t/<dsl>/<sha16>.<ext>`
+ *   - streaming HLS:            `https://8ok.uk/t/format=hls/<sha16>.m3u8`
+ *
+ * Returns `null` for non-aquienpz URLs (pexels, googleusercontent, raw
+ * uploaded URLs to other CDNs) so call sites can fall back to the URL
+ * with a plain `<img>` instead of generating a broken transform URL.
+ *
+ * Useful when a value reaches the component as a pre-built URL string
+ * (legacy data, site-config JSON, third-party feeds) but you want to
+ * drop in `getTransformSrcSet` for the responsive ladder if it happens
+ * to be an aquienpz asset.
+ */
+declare function extractAssetSha(url: string | null | undefined): string | null;
+declare function serializeTransform(opts: SignedTransformOptions): string;
+/**
+ * Build a transform URL for a VIDEO asset. Same DSL shape as image
+ * transforms; the server branches on the asset's `kind` column. Video
+ * URLs use `.mp4` (default) or `.webm` extension and on cache miss the
+ * server returns 202 Accepted while a Cloud Run Job encodes the clip;
+ * subsequent GETs return 302 to the cached R2 object.
+ *
+ *   <video src={aq.transformVideo(asset, { width: 1080, height: 1920 })}
+ *          autoPlay muted loop playsInline />
+ */
+declare function getVideoTransformUrl(asset: Pick<AssetDTO, "sha">, opts: TransformOptions): string | null;
+/**
+ * Build an HLS streaming URL for a VIDEO asset (Phase 5). Returns the
+ * master.m3u8 entry point — HLS-aware players (Video.js's
+ * @videojs/http-streaming, hls.js, native iOS Safari) follow it to
+ * fetch the variant playlist + segments at the appropriate bitrate
+ * for the connection.
+ *
+ * ⚠️ A master.m3u8 is NOT a video file. Assigning it to `<video src>`
+ * works only where the engine has native HLS; everywhere else it needs
+ * an MSE player. And the classic feature test is now WRONG: Chrome 147
+ * (April 2026) added native HLS, so `canPlayType("application/vnd.apple.mpegurl")`
+ * answers "maybe" there and routes Chrome to the native branch, where it
+ * opened a measured 17 s hero at 426x240 for ~8 s. Branch on the ENGINE:
+ *
+ * @example
+ * ```ts
+ * function prefersNativeHls(video: HTMLVideoElement): boolean {
+ *   if (video.canPlayType("application/vnd.apple.mpegurl") === "") return false;
+ *   // Apple's engine, or an engine with no MSE to fall back on (iOS < 17.1).
+ *   return "ManagedMediaSource" in globalThis || !("MediaSource" in globalThis);
+ * }
+ *
+ * const src = getHlsStreamingUrl(asset);
+ * if (prefersNativeHls(video)) {
+ *   video.src = src;
+ * } else {
+ *   // Defaults open at a fixed low rung — measure instead of guessing.
+ *   const hls = new Hls({ startLevel: -1, testBandwidth: true, abrEwmaDefaultEstimate: 1_000_000 });
+ *   hls.loadSource(src);
+ *   hls.attachMedia(video);
+ * }
+ * ```
+ *
+ * On first request the server returns 202 Accepted while a Cloud Run
+ * Job transcodes the ladder (typically 1-3 min for a 90 s source);
+ * subsequent requests get 302 to the cached master.m3u8. Keep the
+ * progressive MP4 as a fallback source for that window.
+ *
+ * The ladder's ceiling is the source the job probes: built at ingest it
+ * reads the RAW upload and a 4K master yields 1440p/2160p rungs; rebuilt
+ * on demand after the raw is unavailable it reads the `-v.mp4`, which is
+ * capped at 1920 wide. `getAssetUrl(sha, "video")` is always <= 1080p.
+ */
+declare function getHlsStreamingUrl(asset: Pick<AssetDTO, "sha">, opts?: Omit<TransformOptions, "format">): string;
+declare function getTransformUrl(asset: Pick<AssetDTO, "sha">, opts: TransformOptions): string | null;
+/**
+ * Build AND sign a transform URL, allowing an off-ladder custom `width`.
+ *
+ * This is the escape hatch for {@link SignedTransformOptions}: off-ladder
+ * widths only pass the edge whitelist when the URL is signed, so building one
+ * and signing it must happen together. For on-ladder widths prefer the plain
+ * {@link getTransformUrl} (+ {@link signTransformUrl} if you need a signature).
+ *
+ * Returns `null` only when `opts` serialize to an empty DSL (no transform
+ * requested) — same contract as {@link getTransformUrl}.
+ */
+declare function getSignedTransformUrl(asset: Pick<AssetDTO, "sha">, opts: SignedTransformOptions, signingKey: string): Promise<string> | null;
+/**
+ * Sign a transform URL with the tenant's HMAC signing key. Appends
+ * `?sig=<hex>` where hex = HMAC-SHA256(signingKey, `<canonical-DSL>/<filename>`).
+ *
+ * Must agree byte-for-byte with the server's `verifyTransformSignature`.
+ * Uses WebCrypto, so works in browsers, Node ≥ 16, Bun, and Workers.
+ *
+ * The canonical DSL is the one already produced by `serializeTransform`
+ * (sort keys + lowercase strings), so signing a URL built by `getTransformUrl`
+ * is automatic — the same canonical form is in the URL path.
+ */
+declare function signTransformUrl(unsignedUrl: string, signingKey: string): Promise<string>;
+/**
+ * Build a responsive `srcSet` string by generating one transform URL per
+ * width. All other options apply to every URL.
+ *
+ *   <img
+ *     src={aq.transform(asset, { width: 800 })!}
+ *     srcSet={aq.transformSrcSet(asset, [320, 640, 960, 1280])}
+ *     sizes="(max-width: 768px) 100vw, 50vw"
+ *   />
+ */
+declare function getTransformSrcSet(asset: Pick<AssetDTO, "sha">, widths: number[], extraOpts?: Omit<TransformOptions, "width">): string;
+
+/**
+ * @nitida/asset-client — read helpers for asset URLs.
+ *
+ * Universal CDN model (May 2026): the API ships a compact AssetDTO with a
+ * 16-char SHA prefix + a `presets` string of 1-char codes; client helpers
+ * construct CDN URLs deterministically from `(cdnBase, sha, preset, ext)`.
+ *
+ * Why: catalog sync over Electric SSE shipped 4 nearly-identical full URLs
+ * per asset × hundreds of thousands of assets per snapshot. Sending only
+ * what differs — sha + presets bitmap — collapses ~600 bytes per asset to
+ * ~70 (88% reduction).
+ *
+ * No runtime dependencies — pure types + pure functions. Safe everywhere.
+ * @module @nitida/asset-client
+ */
+/**
+ * Image presets are size-based (Vercel `next/image` style):
+ *   - `thumb` is the only square crop — semantic icon use case
+ *   - `sm/md/lg` are max-side bounding boxes that preserve aspect ratio
+ *
+ * Naming over the legacy `thumbnail/cover/web/hero` because the new names
+ * say what the variant IS (a size class) rather than what it might be
+ * USED for, removing the implicit landscape-only assumption that bit us
+ * with vertical product photos.
+ */
+type VariantPreset = "thumb" | "sm" | "md" | "lg" | "xl" | "original" | "poster" | "video" | "aiproxy" | "mp3";
+/** 1-char alias used in R2 keys / wire `presets` string. */
+declare const PRESET_SHORT: Record<VariantPreset, string>;
+declare const PRESET_LONG: Record<string, VariantPreset>;
+/** Variant extension by preset. Image variants are always WebP, video MP4. */
+declare const PRESET_EXT: Record<VariantPreset, string>;
+/** Max-side dimension by preset; null for video / passthrough. */
+declare const PRESET_MAX_DIM: Record<VariantPreset, number | null>;
+/**
+ * One generated variant of an asset. Returned by the admin endpoints
+ * (`GET /assets/:id`, `POST /assets/:id/regenerate`).
+ */
+type AssetVariant = {
+    /** Long name (`thumb` / `sm` / … / `original`) — see {@link VariantPreset}. */
+    preset: VariantPreset;
+    /** Public CDN URL of this variant. */
+    url: string;
+    /** Pixel width. Absent for `original`-only assets where sharp was skipped, or for video presets. */
+    width?: number;
+    /** Pixel height. Same caveat as `width`. */
+    height?: number;
+    /** Byte size of the variant file on R2. */
+    bytes: number;
+    /**
+     * Where the bytes for this variant came from. Useful for quality
+     * traceability — a `thumb` with `sourceFrom: "original"` is the
+     * canonical case, while `sourceFrom: "lg"` means it was derived
+     * from an already-encoded WebP (slight quality compounding).
+     *
+     *   - `"upload"` → first-write at `/assets/process`. The bytes came
+     *     straight from the client's PUT.
+     *   - `VariantPreset` → regenerated from that preset's variant.
+     *
+     * Absent on variants written before the trace field existed.
+     */
+    sourceFrom?: VariantPreset | "upload";
+    /** ISO timestamp this variant was written. Absent on pre-trace variants. */
+    createdAt?: string;
+};
+/**
+ * Compact wire shape — what the server actually sends. Aliases (`w`, `h`,
+ * `dur`) are intentional to shave bytes per asset on dense lists.
+ */
+type AssetDTO = {
+    id: string;
+    /** First 16 hex chars of sha256 — used to derive CDN URLs. */
+    sha: string;
+    kind: "image" | "video" | "document" | "audio" | "other";
+    mime: string;
+    bytes: number;
+    /** Source dims (for aspect-ratio calc on the client). Optional for non-images. */
+    w?: number | null;
+    h?: number | null;
+    /** Duration ms for videos. */
+    dur?: number | null;
+    /** LQIP placeholder (data URL). */
+    blur?: string | null;
+    palette?: AssetPalette | null;
+    /**
+     * Compact list of generated variants as their 1-char codes
+     * concatenated, e.g. "tcwh" (image) / "pv" (video without aiproxy).
+     * Ordered by ascending dimension.
+     */
+    presets: string;
+    status: "processing" | "ready" | "failed";
+    /** Soft-delete timestamp (ISO). Hidden from catalog when set. */
+    deletedAt?: string | null;
+    /**
+     * Full variant list with URLs + sizes. Present on admin responses
+     * (`GET /assets/:id`); absent on the slim list shape used by the
+     * resolver / catalog. Use `presets` for compact existence checks.
+     */
+    variants?: AssetVariant[];
+};
+
+/**
+ * Override the CDN base for the entire process (e.g. in tests, or when
+ * pointing at a tenant-specific CDN). Storefront layouts call this once at
+ * boot.
+ */
+declare function setCdnBase(url: string): void;
+declare function getCdnBase(): string;
+/** Set the process-global tenant id used to build tenant-prefixed CDN URLs. */
+declare function setTenantId(id: number | null | undefined): void;
+declare function getTenantId(): number | null;
+/**
+ * Build the public CDN URL for a specific variant of an asset. The variant
+ * may not actually exist (regenerate may not have run, or video has no
+ * `aiproxy`); call `hasPreset()` first or expect a 404.
+ *
+ * Pass the asset's `mime` (present on the full `AssetDTO`) so the `original`
+ * preset resolves to the correct extension; without it the original falls back
+ * to the `"bin"` sentinel.
+ *
+ * @example Video — the tenant segment is base36, so let this build the path
+ * ```ts
+ * import { getAssetUrl, setTenantId } from "@nitida/asset-client";
+ *
+ * setTenantId(12);                        // 12 → "c"; a decimal "/12/v/" 404s
+ * getAssetUrl({ sha }, "video");          // → https://8ok.uk/c/v/<sha16>-v.mp4
+ * getAssetUrl({ sha }, "poster");         // → https://8ok.uk/c/v/<sha16>-p.webp
+ * ```
+ *
+ * @example The `original`, which needs the mime — and still deserves a HEAD
+ * ```ts
+ * getAssetUrl({ sha }, "original");             // → …-o.bin   ❌ 404, always
+ * getAssetUrl({ sha, mime }, "original");       // → …-o.webp  ✓
+ *
+ * // ⚠️ The stored extension comes from the UPLOADED FILENAME, not the mime:
+ * // "image/jpeg" builds "-o.jpeg" while a camera's ".jpg" was stored as "-o.jpg".
+ * // When the URL must be right, verify it:
+ * const res = await fetch(url, { method: "HEAD" });
+ * ```
+ *
+ * @example Check before you link
+ * ```ts
+ * import { getAssetUrl, hasPreset } from "@nitida/asset-client";
+ * const url = hasPreset(asset, "thumb") ? getAssetUrl(asset, "thumb") : null;
+ * ```
+ */
+declare function getAssetUrl(asset: Pick<AssetDTO, "sha"> & {
+    mime?: string;
+}, preset: VariantPreset): string;
+/**
+ * Did the processor actually generate this preset?
+ *
+ * Reads `dto.presets` — the compact 1-char code string the server always sends. Prefer this over
+ * the `variants` array, which is documented as present on admin responses and, measured
+ * 2026-08-15, comes back EMPTY even with an admin key while the database row holds the variants.
+ *
+ * @example
+ * ```ts
+ * import { hasPreset } from "@nitida/asset-client";
+ *
+ * hasPreset({ presets: "oq" }, "original");  // → true   ("o" = original, "q" = thumb)
+ * hasPreset({ presets: "oq" }, "lg");        // → false  — do not link to it
+ * hasPreset({ presets: "pv" }, "aiproxy");   // → false  — video without the AI proxy
+ * ```
+ */
+declare function hasPreset(asset: Pick<AssetDTO, "presets">, preset: VariantPreset): boolean;
+declare function getAssetSrcSet(asset: Pick<AssetDTO, "sha" | "presets">): string;
+/**
+ * Compute the dimensions a variant would have given the source asset's
+ * width/height and the variant's bounding box. For thumbnails (square
+ * smart-crop) the result is always 256×256; for the other presets, scales
+ * the max side to the box dimension and the other side proportionally.
+ */
+declare function computeVariantDimensions(asset: Pick<AssetDTO, "w" | "h">, preset: VariantPreset): {
+    width: number;
+    height: number;
+} | null;
+/** Source dimensions, for aspect-ratio sizing. */
+declare function getAssetDimensions(asset: Pick<AssetDTO, "w" | "h">): {
+    width: number;
+    height: number;
+} | null;
+
+export { type AssetDTO, type AssetPalette, type AssetVariant, PRESET_EXT, PRESET_LONG, PRESET_MAX_DIM, PRESET_SHORT, type PaletteSwatch, type ResolveSlotOptions, type SignedTransformOptions, type SlotDTO, type SlotResolution, TRANSFORM_WIDTHS, type TransformEffect, type TransformFit, type TransformFormat, type TransformGravity, type TransformOptions, type TransformWidth, type VariantPreset, computeVariantDimensions, configureSlotResolver, extractAssetSha, getAmbientGradient, getAssetDimensions, getAssetSrcSet, getAssetUrl, getCdnBase, getHlsStreamingUrl, getPaletteBlurBackground, getPaletteCssVars, getSignedTransformUrl, getTenantId, getTextColorForBackground, getTransformSrcSet, getTransformUrl, getVideoTransformUrl, hasPreset, invalidateSlotCache, iteratePaletteSwatches, pickAmbientBackground, resolveSlot, resolveSlots, serializeTransform, setCdnBase, setTenantId, signTransformUrl };