@nitida/asset-client 0.14.2

package/src/index.ts

@@ -0,0 +1,413 @@
+/**
+ * @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.
+ */
+export type VariantPreset =
+  // image presets
+  | "thumb" // 256x256 square smart-crop (icon)
+  | "sm" // 640 max-side
+  | "md" // 1280 max-side
+  | "lg" // 1920 max-side
+  | "xl" // 3840 max-side (4K) — OPT-IN; not generated by default
+  // passthrough for non-image kinds (PDF etc.)
+  | "original"
+  // video presets — semantic (not size classes)
+  | "poster"
+  | "video"
+  | "aiproxy"
+  // audio preset — the cross-browser mp3 transcode of a voice note
+  // (libmp3lame) emitted alongside the original so chat audio plays on
+  // both Chrome/Android (webm/opus) and iOS Safari (which can't decode opus).
+  | "mp3";
+
+/** 1-char alias used in R2 keys / wire `presets` string. */
+export const PRESET_SHORT: Record<VariantPreset, string> = {
+  thumb: "q",
+  sm: "s",
+  md: "m",
+  lg: "l",
+  xl: "x",
+  original: "o",
+  poster: "p",
+  video: "v",
+  aiproxy: "a",
+  // 3 chars, NOT a 1-char alias: the asset-manager has no short-form for
+  // audio so its `shortPreset("mp3")` falls through to the literal token,
+  // and the deployed server already writes the `-mp3.mp3` variant + emits
+  // the bare `mp3` token in the wire `presets` string. Must stay in lockstep.
+  mp3: "mp3",
+};
+export const PRESET_LONG: Record<string, VariantPreset> = Object.fromEntries(
+  Object.entries(PRESET_SHORT).map(([k, v]) => [v, k as VariantPreset]),
+);
+
+/** Variant extension by preset. Image variants are always WebP, video MP4. */
+export const PRESET_EXT: Record<VariantPreset, string> = {
+  thumb: "webp",
+  sm: "webp",
+  md: "webp",
+  lg: "webp",
+  xl: "webp",
+  original: "bin", // overridden per-asset via mime when needed
+  poster: "webp",
+  video: "mp4",
+  aiproxy: "mp4",
+  mp3: "mp3",
+};
+
+/** Max-side dimension by preset; null for video / passthrough. */
+export const PRESET_MAX_DIM: Record<VariantPreset, number | null> = {
+  thumb: 256,
+  sm: 640,
+  md: 1280,
+  lg: 1920,
+  xl: 3840,
+  original: null,
+  poster: null,
+  video: null,
+  aiproxy: null,
+  // audio has no pixel dimensions; `null` keeps mp3 out of the
+  // dimension-based `getAssetSrcSet` / `computeVariantDimensions` logic.
+  mp3: null,
+};
+
+/**
+ * One generated variant of an asset. Returned by the admin endpoints
+ * (`GET /assets/:id`, `POST /assets/:id/regenerate`).
+ */
+export 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.
+ */
+export 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[];
+};
+
+export type {
+  AssetPalette,
+  PaletteSwatch,
+} from "./palette";
+
+export {
+  getAmbientGradient,
+  getPaletteBlurBackground,
+  getPaletteCssVars,
+  getTextColorForBackground,
+  iteratePaletteSwatches,
+  pickAmbientBackground,
+} from "./palette";
+
+import type { AssetPalette } from "./palette";
+
+// ---------------------------------------------------------------------------
+// CDN base
+// ---------------------------------------------------------------------------
+
+let cdnBaseUrl = "https://8ok.uk";
+/**
+ * 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.
+ */
+export function setCdnBase(url: string): void {
+  cdnBaseUrl = url.replace(/\/$/, "");
+}
+export function getCdnBase(): string {
+  return cdnBaseUrl;
+}
+
+// ---------------------------------------------------------------------------
+// Tenant scope
+//
+// Post-May-2026 the CDN serves variants under a tenant-prefixed path
+// `<cdn>/<tenantId base36>/v/<sha16>-<preset>.<ext>` (see asset-manager
+// `variantKey`). Variant URL builders MUST include that prefix or every
+// URL 404s. The tenant id is process-global (one tenant per client/app),
+// set once at boot — `AquienpzClient` does this from its `tenantId` option;
+// standalone consumers call `setTenantId()` directly. Left unset, builders
+// fall back to the legacy pre-cutover bare path for back-compat.
+// ---------------------------------------------------------------------------
+
+let tenantId: number | null = null;
+/** Set the process-global tenant id used to build tenant-prefixed CDN URLs. */
+export function setTenantId(id: number | null | undefined): void {
+  tenantId =
+    typeof id === "number" && Number.isFinite(id) && id > 0 ? id : null;
+}
+export function getTenantId(): number | null {
+  return tenantId;
+}
+/** Variant path prefix `<tid b36>/v/`, or "" when no tenant is configured. */
+function variantPrefix(): string {
+  return tenantId != null ? `${tenantId.toString(36)}/v/` : "";
+}
+
+// ---------------------------------------------------------------------------
+// URL builders
+// ---------------------------------------------------------------------------
+
+/**
+ * Extension for the ORIGINAL variant, derived from the asset's mime — the
+ * original is stored under its real extension (keyed via `extOfMime`), so the
+ * static `PRESET_EXT.original` sentinel ("bin") only applies when the mime is
+ * unknown/absent. Mirrors the asset-manager's `extOfMime` (mime-types) for the
+ * common image/video kinds so the built URL matches the stored R2 key —
+ * otherwise original-only uploads build a `-o.bin` URL that 404s while the asset
+ * is served at e.g. `-o.png`.
+ */
+const ORIGINAL_EXT_BY_MIME: Record<string, string> = {
+  "image/png": "png",
+  "image/jpeg": "jpeg",
+  "image/webp": "webp",
+  "image/gif": "gif",
+  "image/avif": "avif",
+  "image/svg+xml": "svg",
+  "image/heic": "heic",
+  "image/heif": "heif",
+  "image/bmp": "bmp",
+  "image/tiff": "tiff",
+  "application/pdf": "pdf",
+  "video/mp4": "mp4",
+  "video/webm": "webm",
+  "video/quicktime": "mov",
+};
+function originalExtForMime(mime: string | undefined): string {
+  return (mime ? ORIGINAL_EXT_BY_MIME[mime] : undefined) ?? PRESET_EXT.original;
+}
+
+/**
+ * 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;
+ * ```
+ */
+export function getAssetUrl(
+  asset: Pick<AssetDTO, "sha"> & { mime?: string },
+  preset: VariantPreset,
+): string {
+  const ext =
+    preset === "original" ? originalExtForMime(asset.mime) : PRESET_EXT[preset];
+  return `${cdnBaseUrl}/${variantPrefix()}${asset.sha}-${PRESET_SHORT[preset]}.${ext}`;
+}
+
+/**
+ * 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
+ * ```
+ */
+export function hasPreset(
+  asset: Pick<AssetDTO, "presets">,
+  preset: VariantPreset,
+): boolean {
+  // `presets` concatenates 1-char short codes, but the audio `mp3` variant is a
+  // literal 3-char token. Query `mp3` against that token; for every other preset
+  // strip `mp3` first so its `m`/`p` can't substring-false-match `md`/`poster`.
+  if (preset === "mp3") return asset.presets.includes("mp3");
+  return asset.presets.replace(/mp3/g, "").includes(PRESET_SHORT[preset]);
+}
+
+/**
+ * Build a srcSet string for responsive `<img>`. Walks the available image
+ * presets in size order and only includes the ones the asset actually has.
+ *
+ *   <img
+ *     src={getAssetUrl(asset, 'web')}
+ *     srcSet={getAssetSrcSet(asset)}
+ *     sizes="(max-width: 768px) 100vw, 800px"
+ *   />
+ */
+const IMAGE_PRESETS: VariantPreset[] = ["thumb", "sm", "md", "lg", "xl"];
+export function getAssetSrcSet(
+  asset: Pick<AssetDTO, "sha" | "presets">,
+): string {
+  return IMAGE_PRESETS.filter(
+    (p) => hasPreset(asset, p) && PRESET_MAX_DIM[p] != null,
+  )
+    .map((p) => `${getAssetUrl(asset, p)} ${PRESET_MAX_DIM[p]}w`)
+    .join(", ");
+}
+
+/**
+ * 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.
+ */
+export function computeVariantDimensions(
+  asset: Pick<AssetDTO, "w" | "h">,
+  preset: VariantPreset,
+): { width: number; height: number } | null {
+  const cap = PRESET_MAX_DIM[preset];
+  if (cap == null) return null;
+  if (preset === "thumb") return { width: cap, height: cap };
+  if (!asset.w || !asset.h) return null;
+  const scale = Math.min(cap / asset.w, cap / asset.h, 1);
+  return {
+    width: Math.round(asset.w * scale),
+    height: Math.round(asset.h * scale),
+  };
+}
+
+/** Source dimensions, for aspect-ratio sizing. */
+export function getAssetDimensions(
+  asset: Pick<AssetDTO, "w" | "h">,
+): { width: number; height: number } | null {
+  if (asset.w && asset.h) return { width: asset.w, height: asset.h };
+  return null;
+}
+
+// ---------------------------------------------------------------------------
+// Slot system — tenant-named asset bindings.
+// See ./slots for full docs.
+// ---------------------------------------------------------------------------
+
+export {
+  configureSlotResolver,
+  invalidateSlotCache,
+  type ResolveSlotOptions,
+  resolveSlot,
+  resolveSlots,
+  type SlotDTO,
+  type SlotResolution,
+} from "./slots";
+
+// ---------------------------------------------------------------------------
+// On-the-fly transforms — see ./transform for docs.
+// ---------------------------------------------------------------------------
+
+export {
+  extractAssetSha,
+  getHlsStreamingUrl,
+  getSignedTransformUrl,
+  getTransformSrcSet,
+  getTransformUrl,
+  getVideoTransformUrl,
+  type SignedTransformOptions,
+  serializeTransform,
+  signTransformUrl,
+  TRANSFORM_WIDTHS,
+  type TransformEffect,
+  type TransformFit,
+  type TransformFormat,
+  type TransformGravity,
+  type TransformOptions,
+  type TransformWidth,
+} from "./transform";

package/src/palette.ts

@@ -0,0 +1,182 @@
+/**
+ * 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. */
+export 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. */
+export type PaletteSwatch = { hex: string; textColor: "#000000" | "#FFFFFF" };
+
+/**
+ * Resolve a palette key to its hex value if present.
+ */
+function resolveSwatch(
+  palette: AssetPalette | null | undefined,
+  ...keys: (keyof AssetPalette)[]
+): string | null {
+  if (!palette) return null;
+  for (const k of keys) {
+    const v = palette[k];
+    if (v) return v;
+  }
+  return null;
+}
+
+/**
+ * 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.
+ */
+export function pickAmbientBackground(
+  palette: AssetPalette | null | undefined,
+): PaletteSwatch | null {
+  const hex = resolveSwatch(palette, "lm", "m", "lv", "d");
+  if (!hex) return null;
+  return { hex, textColor: textColorForHex(hex) };
+}
+
+/**
+ * Build a CSS linear-gradient from the palette. Useful for hero / detail
+ * backgrounds.
+ */
+export function getAmbientGradient(
+  palette: AssetPalette | null | undefined,
+  opts: {
+    angle?: string;
+    from?: keyof AssetPalette;
+    to?: keyof AssetPalette;
+  } = {},
+): string | undefined {
+  if (!palette) return undefined;
+  const fromHex = palette[opts.from ?? "lm"] ?? palette.m ?? palette.d;
+  const toHex = palette[opts.to ?? "m"] ?? palette.dm ?? palette.d;
+  if (!fromHex || !toHex) return undefined;
+  return `linear-gradient(${opts.angle ?? "135deg"}, ${fromHex}, ${toHex})`;
+}
+
+/**
+ * Recommended text color (#000 or #FFF) for any background hex,
+ * computed via WCAG relative luminance.
+ */
+export function getTextColorForBackground(
+  swatch: PaletteSwatch | string | null | undefined,
+): string {
+  if (!swatch) return "#000000";
+  const hex = typeof swatch === "string" ? swatch : swatch.hex;
+  return textColorForHex(hex);
+}
+
+function textColorForHex(hex: string): "#000000" | "#FFFFFF" {
+  const h = hex.replace("#", "");
+  const r = Number.parseInt(h.slice(0, 2), 16) / 255;
+  const g = Number.parseInt(h.slice(2, 4), 16) / 255;
+  const b = Number.parseInt(h.slice(4, 6), 16) / 255;
+  // sRGB → linear
+  const lin = (c: number) =>
+    c <= 0.03928 ? c / 12.92 : ((c + 0.055) / 1.055) ** 2.4;
+  const L = 0.2126 * lin(r) + 0.7152 * lin(g) + 0.0722 * lin(b);
+  return L > 0.5 ? "#000000" : "#FFFFFF";
+}
+
+/**
+ * CSS variables for a wrapper so a subtree can read --asset-bg / --asset-fg /
+ * --asset-dominant / --asset-vibrant / etc.
+ */
+export function getPaletteCssVars(
+  palette: AssetPalette | null | undefined,
+): Record<string, string> {
+  if (!palette) return {};
+  const bg = pickAmbientBackground(palette);
+  return {
+    "--asset-bg": bg?.hex ?? "transparent",
+    "--asset-fg": bg ? bg.textColor : "#000000",
+    "--asset-dominant": palette.d,
+    ...(palette.v && { "--asset-vibrant": palette.v }),
+    ...(palette.m && { "--asset-muted": palette.m }),
+    ...(palette.lv && { "--asset-light-vibrant": palette.lv }),
+    ...(palette.dv && { "--asset-dark-vibrant": palette.dv }),
+    ...(palette.lm && { "--asset-light-muted": palette.lm }),
+    ...(palette.dm && { "--asset-dark-muted": palette.dm }),
+  };
+}
+
+/**
+ * Iterate the palette in display order (dominant first, then vibrant +
+ * muted families). Useful for rendering a swatch strip in admin UIs.
+ */
+export function iteratePaletteSwatches(
+  palette: AssetPalette | null | undefined,
+): Array<{ key: keyof AssetPalette; label: string; hex: string }> {
+  if (!palette) return [];
+  const order: Array<{ key: keyof AssetPalette; label: string }> = [
+    { key: "d", label: "dominant" },
+    { key: "v", label: "vibrant" },
+    { key: "lv", label: "lightVibrant" },
+    { key: "dv", label: "darkVibrant" },
+    { key: "m", label: "muted" },
+    { key: "lm", label: "lightMuted" },
+    { key: "dm", label: "darkMuted" },
+  ];
+  return order
+    .map(({ key, label }) => {
+      const hex = palette[key];
+      return hex ? { key, label, hex } : null;
+    })
+    .filter(
+      (s): s is { key: keyof AssetPalette; label: string; hex: string } =>
+        s != null,
+    );
+}
+
+/**
+ * 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.
+ */
+export function getPaletteBlurBackground(
+  palette: AssetPalette | null | undefined,
+): string | undefined {
+  if (!palette) return undefined;
+  const corners: Array<{ pos: string; key: keyof AssetPalette }> = [
+    { pos: "20% 20%", key: "lv" },
+    { pos: "80% 25%", key: "v" },
+    { pos: "25% 80%", key: "lm" },
+    { pos: "80% 80%", key: "dv" },
+  ];
+  const layers = corners
+    .map(({ pos, key }) => {
+      const hex = palette[key];
+      if (!hex) return null;
+      return `radial-gradient(circle at ${pos}, ${hex} 0%, transparent 55%)`;
+    })
+    .filter(Boolean) as string[];
+  // Fallback fill = dominant (or muted if dominant is missing — shouldn't happen)
+  const base = palette.d ?? palette.m ?? "#888";
+  return layers.length > 0 ? `${layers.join(", ")}, ${base}` : base;
+}