@nitida/sdk 0.20.0

package/src/index.ts

@@ -0,0 +1,1562 @@
+/**
+ * @nitida/sdk — universal client for the aquienpz multi-tenant asset
+ * platform.
+ *
+ * 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 key's metadata (`X-Tenant-Code` is log-only).
+ *
+ * Usage:
+ *
+ *   import { AquienpzClient } from "@nitida/sdk";
+ *
+ *   const aq = new AquienpzClient({
+ *     endpoint: "https://aquienpz-asset-manager-xxx.run.app",
+ *     apiKey:   process.env.ASSET_MANAGER_RUNTIME_KEY!,
+ *     tenantCode: "realtyone-cr",
+ *     cdnBase: "https://8ok.uk",  // optional override
+ *     tenantId: 4,                 // required for tenant-prefixed URLs
+ *   });
+ *
+ *   // Slot system (recommended — admin can rebind without redeploys).
+ *   const hero = await aq.slots.resolve("storefront.cr.hero");
+ *   const set  = await aq.slots.resolveMany(["a", "b", "c"]);
+ *
+ *   // Lower-level asset operations.
+ *   const asset = await aq.assets.byHash(sha);
+ *   const list  = await aq.assets.list({ limit: 50 });
+ *
+ *   // Upload bytes / files.
+ *   const up = await aq.upload(file, { fileName: "cover.jpg" });
+ *
+ * For React, see `@nitida/sdk/react` (useSlot, useSlots, useAsset).
+ * @module @nitida/sdk
+ */
+
+import {
+  type AssetDTO,
+  type AssetVariant,
+  configureSlotResolver,
+  getAssetSrcSet,
+  getAssetUrl,
+  getHlsStreamingUrl,
+  getSignedTransformUrl,
+  getTransformSrcSet,
+  getTransformUrl,
+  getVideoTransformUrl,
+  hasPreset,
+  invalidateSlotCache,
+  type ResolveSlotOptions,
+  resolveSlot,
+  resolveSlots,
+  type SignedTransformOptions,
+  type SlotDTO,
+  type SlotResolution,
+  setCdnBase,
+  setTenantId,
+  type TransformOptions,
+  type VariantPreset,
+} from "@nitida/asset-client";
+
+// ---------------------------------------------------------------------------
+// Config
+// ---------------------------------------------------------------------------
+
+/**
+ * Permissive constructor options for the root `AquienpzClient`.
+ *
+ * App code should NOT import this type directly — prefer the strict
+ * variants from the subpaths:
+ *
+ *   - `WebClientOptions`    from `@nitida/sdk/web`     (no `apiKey`)
+ *   - `ServerClientOptions` from `@nitida/sdk/server`  (`apiKey` required)
+ *
+ * This root type is the union both modes resolve to; the underlying class
+ * accepts both shapes so subpath wrappers can extend without duplication.
+ */
+export type AquienpzClientOptions = {
+  /**
+   * Base URL of the aquienpz asset-manager (Cloud Run service URL).
+   *
+   * May be relative (e.g. `/api/am`) ONLY in browser contexts where the
+   * SDK resolves it against `window.location.origin`. Node/Bun consumers
+   * must always pass an absolute URL.
+   */
+  endpoint: string;
+  /**
+   * Better Auth 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.
+   */
+  apiKey?: string;
+  /**
+   * Extra headers merged into every request. The documented way for
+   * mobile/Expo clients to authenticate a BFF that gates on the Better Auth
+   * session: they can't send cookies automatically, so they pass
+   * `{ Cookie: authClient.getCookie() }` here (see Better Auth Expo docs,
+   * "Making Authenticated Requests to Your Server"). Web/server consumers omit
+   * this — browsers attach the same-origin cookie and servers pass `apiKey`.
+   */
+  headers?: Record<string, string>;
+  /** Tenant code — sent as `X-Tenant-Code` (log-only). Authoritative scope is the key's metadata.tenantId. */
+  tenantCode: string;
+  /** Numeric tenant id — used to build tenant-prefixed CDN URLs `<cdn>/<tenantId b36>/v/<sha>-<preset>.<ext>`. */
+  tenantId: number;
+  /** Override the public CDN base. Defaults to `https://8ok.uk`. */
+  cdnBase?: string;
+  /**
+   * 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
+   * server-side only** — do not ship in `NEXT_PUBLIC_*` env vars. Sign
+   * URLs from a BFF route handler, or pre-sign at build time.
+   */
+  signingKey?: string;
+};
+
+// ---------------------------------------------------------------------------
+// URL construction
+// ---------------------------------------------------------------------------
+
+/**
+ * Build a fully-qualified URL for an aquienpz endpoint path.
+ *
+ * Accepts both absolute endpoints (`https://aquienpz...run.app`) and
+ * relative ones (`/api/am`) — the latter only works in browser contexts
+ * (resolved against `window.location.origin`). Node/Bun throws a clear
+ * error if a relative endpoint is configured.
+ *
+ * The native `URL` constructor throws on relative inputs, so every fetch
+ * site in the SDK must go through this helper instead of `new URL(...)`.
+ */
+function endpointUrl(
+  opts: Pick<AquienpzClientOptions, "endpoint">,
+  path: string,
+  searchParams?: Record<string, string | number | boolean | undefined>,
+): URL {
+  const endpoint = opts.endpoint.replace(/\/+$/, "");
+  const isAbsolute = /^https?:\/\//i.test(endpoint);
+  let base: string;
+  if (isAbsolute) {
+    base = `${endpoint}${path}`;
+  } else if (typeof window !== "undefined" && window.location?.origin) {
+    base = `${window.location.origin}${endpoint}${path}`;
+  } else {
+    throw new Error(
+      `[@nitida/sdk] relative endpoint "${endpoint}" requires a browser; ` +
+        "pass an absolute URL when using the SDK from Node/Bun.",
+    );
+  }
+  const u = new URL(base);
+  if (searchParams) {
+    for (const [k, v] of Object.entries(searchParams)) {
+      if (v !== undefined && v !== null && v !== "") {
+        u.searchParams.set(k, String(v));
+      }
+    }
+  }
+  return u;
+}
+
+/** Build a request URL as a plain string (no search params). */
+function endpointHref(
+  opts: Pick<AquienpzClientOptions, "endpoint">,
+  path: string,
+): string {
+  return endpointUrl(opts, path).toString();
+}
+
+/**
+ * Auth headers — conditionally includes `Authorization` only when an
+ * `apiKey` is present. In BFF-proxy mode (browser via `/web`) the
+ * proxy injects the real bearer header, so we omit it here.
+ */
+function authHeaders(opts: AquienpzClientOptions): Record<string, string> {
+  const h: Record<string, string> = {
+    // Caller-supplied headers first; `X-Tenant-Code` stays authoritative below.
+    ...opts.headers,
+    "X-Tenant-Code": opts.tenantCode,
+  };
+  if (opts.apiKey) h.Authorization = `Bearer ${opts.apiKey}`;
+  return h;
+}
+
+// ---------------------------------------------------------------------------
+// Re-exports (so consumers don't double-import from asset-client)
+// ---------------------------------------------------------------------------
+
+export type {
+  AssetDTO,
+  AssetVariant,
+  ResolveSlotOptions,
+  SignedTransformOptions,
+  SlotDTO,
+  SlotResolution,
+  TransformEffect,
+  TransformFit,
+  TransformFormat,
+  TransformGravity,
+  TransformOptions,
+  VariantPreset,
+} from "@nitida/asset-client";
+export {
+  computeVariantDimensions,
+  extractAssetSha,
+  getAssetDimensions,
+  getAssetSrcSet,
+  getAssetUrl,
+  getHlsStreamingUrl,
+  getSignedTransformUrl,
+  getTenantId,
+  getTransformSrcSet,
+  getTransformUrl,
+  getVideoTransformUrl,
+  hasPreset,
+  serializeTransform,
+  setTenantId,
+  signTransformUrl,
+} from "@nitida/asset-client";
+
+// ---------------------------------------------------------------------------
+// Sub-namespaces
+// ---------------------------------------------------------------------------
+
+class SlotsApi {
+  constructor(private readonly opts: AquienpzClientOptions) {}
+
+  /** Resolve one slot — returns `{slot, preset, url}` or `{slot: null, url: null}` when unbound. */
+  resolve(
+    slotKey: string,
+    options: ResolveSlotOptions = {},
+  ): Promise<SlotResolution> {
+    return resolveSlot(slotKey, options);
+  }
+
+  /** Bulk-resolve N slots in one HTTP round-trip. */
+  resolveMany(
+    slotKeys: string[],
+    options: ResolveSlotOptions = {},
+  ): Promise<Record<string, SlotResolution>> {
+    return resolveSlots(slotKeys, options);
+  }
+
+  /** List slots for the tenant (admin). Optional prefix filter for tree views. */
+  async list(
+    opts: { prefix?: string; limit?: number } = {},
+  ): Promise<SlotDTO[]> {
+    const u = endpointUrl(this.opts, "/slots", {
+      prefix: opts.prefix,
+      limit: opts.limit,
+    });
+    const r = await fetch(u, { headers: this.headers() });
+    if (!r.ok) throw new Error(`slots list ${r.status}: ${await r.text()}`);
+    const body = (await r.json()) as { slots: SlotDTO[] };
+    return body.slots;
+  }
+
+  /** Bind / rebind a slot to an asset. Admin-only operation. */
+  async bind(
+    slotKey: string,
+    body: {
+      assetId: string;
+      preset?: VariantPreset;
+      description?: string;
+      updatedBy?: string;
+    },
+  ): Promise<{ ok: true; slotKey: string; assetId: string }> {
+    const r = await fetch(
+      endpointHref(this.opts, `/slots/${encodeURIComponent(slotKey)}`),
+      {
+        method: "PUT",
+        headers: { ...this.headers(), "Content-Type": "application/json" },
+        body: JSON.stringify(body),
+      },
+    );
+    if (!r.ok) throw new Error(`slot bind ${r.status}: ${await r.text()}`);
+    return (await r.json()) as { ok: true; slotKey: string; assetId: string };
+  }
+
+  /**
+   * Recent bindings for a slot. Lets the admin audit who changed
+   * what and restore a previous binding without remembering the
+   * asset id. Default limit 20, max 100.
+   */
+  async history(
+    slotKey: string,
+    opts: { limit?: number } = {},
+  ): Promise<SlotHistoryEntry[]> {
+    const u = endpointUrl(
+      this.opts,
+      `/slots/${encodeURIComponent(slotKey)}/history`,
+      { limit: opts.limit },
+    );
+    const r = await fetch(u, { headers: this.headers() });
+    if (!r.ok) throw new Error(`slots history ${r.status}: ${await r.text()}`);
+    const body = (await r.json()) as { history: SlotHistoryEntry[] };
+    return body.history;
+  }
+
+  /**
+   * Restore the slot to a previous binding. Equivalent to
+   * `bind(key, { assetId: previous.assetId, action: "restore" })`
+   * — the audit row is tagged `restore` instead of `bind`.
+   */
+  async restore(
+    slotKey: string,
+    args: { assetId: string; preset?: VariantPreset; updatedBy?: string },
+  ): Promise<{ ok: true; slotKey: string; assetId: string }> {
+    const r = await fetch(
+      endpointHref(this.opts, `/slots/${encodeURIComponent(slotKey)}`),
+      {
+        method: "PUT",
+        headers: { ...this.headers(), "Content-Type": "application/json" },
+        body: JSON.stringify({ ...args, action: "restore" }),
+      },
+    );
+    if (!r.ok) throw new Error(`slot restore ${r.status}: ${await r.text()}`);
+    return (await r.json()) as { ok: true; slotKey: string; assetId: string };
+  }
+
+  /** Remove a slot binding. The asset itself is left alone. */
+  async unbind(slotKey: string): Promise<{ ok: true; removed: number }> {
+    const r = await fetch(
+      endpointHref(this.opts, `/slots/${encodeURIComponent(slotKey)}`),
+      {
+        method: "DELETE",
+        headers: this.headers(),
+      },
+    );
+    if (!r.ok) throw new Error(`slot unbind ${r.status}: ${await r.text()}`);
+    return (await r.json()) as { ok: true; removed: number };
+  }
+
+  /** Invalidate the in-process cache after a slot rebind. */
+  invalidateCache(slotKey?: string): void {
+    invalidateSlotCache(slotKey);
+  }
+
+  private headers(): Record<string, string> {
+    return authHeaders(this.opts);
+  }
+}
+
+/**
+ * Returned by `aq.assets.regenerate(...)`. The shape varies by kind —
+ * images return immediately with the merged variant list; videos
+ * return a dispatch handle (the actual transcode runs in a Cloud Run
+ * Job and finishes async).
+ */
+export type RegenerateResult =
+  | {
+      ok: true;
+      kind: "image";
+      /** Full variant set after the merge. */
+      variants: AssetVariant[];
+      /** Presets newly written this run. Useful for showing "added X". */
+      newVariants: VariantPreset[];
+      /**
+       * Which source the server read to derive the new variants:
+       *   - `"original"` / `"raw"` → lossless source bytes (best)
+       *   - `"xl"` / `"lg"` / `"md"` / `"sm"` / `"thumb"` → a previously
+       *     encoded WebP variant was used as the source. Output is
+       *     re-encoded WebP — fine for thumb/sm from lg, lossier when
+       *     working from already-small sources.
+       *
+       * The no-upscale clamp still applies: deriving `lg` (1920) from
+       * a 640 `sm` source produces a 640-side `lg` variant, not a
+       * stretched 1920.
+       */
+      sourceUsed: VariantPreset | "raw";
+    }
+  | {
+      ok: true;
+      kind: "video";
+      dispatch: unknown;
+      regenerated: string[] | "default";
+    };
+
+/**
+ * Wire shape returned by `POST /assets/upload-url`. Either the server
+ * resolves the upload synchronously via dedup (`deduped: true` + existing
+ * asset DTO) or it returns a presigned R2 PUT URL plus a `process` payload
+ * the caller must POST to `/assets/process` after the PUT lands.
+ */
+export type UploadUrlResult =
+  | { deduped: true; asset: AssetDTO }
+  | {
+      deduped: false;
+      upload: { url: string; headers?: Record<string, string> };
+      process: { url: string; body: Record<string, unknown> };
+    };
+
+/**
+ * VIDEO-only delivery knobs threaded into `/assets/process`. Ignored for
+ * image / audio / other uploads. Both fields default to today's behavior when
+ * omitted, so existing callers are unaffected.
+ */
+export type UploadVideoOptions = {
+  /**
+   * `false` → skip the auto-dispatched HLS adaptive ladder (240p–2160p). Use
+   * for download-only assets served as a progressive `-v.mp4` and never
+   * streamed (e.g. share-video reels) — it avoids a second Cloud Run Job no
+   * one watches. Default/absent → the ladder is generated as before.
+   */
+  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
+   * 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
+   * is not web-safe. Default/absent → unconditional re-encode (today's path).
+   */
+  passthrough?: boolean;
+};
+
+/** Input shape accepted by `aq.assets.presignUploadUrl(...)`. */
+export type PresignUploadUrlOptions = {
+  /** Full sha256 (64 hex) of the bytes that will be PUT to R2. */
+  sha256: string;
+  /** MIME type of the bytes (e.g. `image/jpeg`, `video/mp4`). */
+  mime: string;
+  /** Byte length of the upload payload. */
+  bytes: number;
+  /** Suggested file name; surfaces in admin dashboards + extension fallback. */
+  fileName: string;
+  /**
+   * Variant ladder to generate after `/assets/process`. Defaults to
+   * `["original"]` server-side when omitted — same contract as `aq.upload`.
+   */
+  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`.
+   */
+  clientOriginalBytes?: number;
+  /** VIDEO-only delivery knobs forwarded into `/assets/process`. See {@link UploadVideoOptions}. */
+  video?: UploadVideoOptions;
+};
+
+/** Input shape accepted by `aq.assets.composeMarketing(...)`. */
+export type ComposeMarketingSegment = {
+  /** Public URL of the source clip (typically a `/t/.../video.mp4` transform). */
+  sourceUrl: string;
+  /** Optional clip duration in seconds (cap for that segment). */
+  durationSec?: number;
+};
+
+export type ComposeMarketingComposition = {
+  /** Transition between consecutive segments. Default `"cut"`. */
+  transition?: "cut" | "fade";
+  /** Optional audio track to mix on top of the final composition. */
+  audioTrack?: { url: string };
+  /** Final composition length in seconds (server may clamp). */
+  finalDurationSec?: number;
+};
+
+export type ComposeMarketingOptions = {
+  /** Marketing-kit id this composition belongs to (server uses it for naming + dedup). */
+  marketingKitId: string;
+  /** Ordered clip segments to stitch. */
+  segments: ComposeMarketingSegment[];
+  /** Optional composition-level knobs (transitions, audio, duration). */
+  composition?: ComposeMarketingComposition;
+};
+
+export type ComposeMarketingResult = {
+  /** Aquienpz asset id of the in-flight composition. Poll `aq.assets.waitReady(id)`. */
+  assetId: string;
+  /** Asset status at dispatch time — usually `"processing"`. */
+  status: "processing" | "ready" | "failed";
+};
+
+class AssetsApi {
+  constructor(private readonly opts: AquienpzClientOptions) {}
+
+  /** Look up an asset by full sha256 (64 hex). Returns null on 404. */
+  async byHash(sha256: string): Promise<AssetDTO | null> {
+    const r = await fetch(
+      endpointHref(this.opts, `/assets/by-hash/${sha256}`),
+      { headers: this.headers() },
+    );
+    if (r.status === 404) return null;
+    if (!r.ok) throw new Error(`assets byHash ${r.status}: ${await r.text()}`);
+    return (await r.json()) as AssetDTO;
+  }
+
+  /** Bulk lookup by sha256s. */
+  async byHashes(
+    hashes: string[],
+  ): Promise<{ existing: AssetDTO[]; missing: string[] }> {
+    const r = await fetch(endpointHref(this.opts, "/assets/by-hashes"), {
+      method: "POST",
+      headers: { ...this.headers(), "Content-Type": "application/json" },
+      body: JSON.stringify({ hashes }),
+    });
+    if (!r.ok)
+      throw new Error(`assets byHashes ${r.status}: ${await r.text()}`);
+    return (await r.json()) as { existing: AssetDTO[]; missing: string[] };
+  }
+
+  /** Paginated list of recent assets for the tenant. */
+  async list(
+    opts: { limit?: number; cursor?: string; includeDeleted?: boolean } = {},
+  ): Promise<{
+    assets: AssetDTO[];
+    nextCursor: string | null;
+  }> {
+    const u = endpointUrl(this.opts, "/assets", {
+      limit: opts.limit,
+      cursor: opts.cursor,
+      include_deleted: opts.includeDeleted ? "true" : undefined,
+    });
+    const r = await fetch(u, { headers: this.headers() });
+    if (!r.ok) throw new Error(`assets list ${r.status}: ${await r.text()}`);
+    return (await r.json()) as {
+      assets: AssetDTO[];
+      nextCursor: string | null;
+    };
+  }
+
+  /** Full DTO for an asset (admin view — includes audit-only fields). */
+  async get(assetId: string): Promise<AssetDTO & Record<string, unknown>> {
+    const r = await fetch(endpointHref(this.opts, `/assets/${assetId}`), {
+      headers: this.headers(),
+    });
+    if (!r.ok) throw new Error(`asset get ${r.status}: ${await r.text()}`);
+    return (await r.json()) as AssetDTO & Record<string, unknown>;
+  }
+
+  /**
+   * Slot bindings pointing at an asset. Use this before deleting an
+   * asset so the admin sees which storefront slots would suddenly
+   * resolve to nothing.
+   */
+  async bindings(assetId: string): Promise<
+    Array<{
+      slotKey: string;
+      preset: VariantPreset | null;
+      description: string | null;
+      updatedAt: string;
+      updatedBy: string | null;
+    }>
+  > {
+    const r = await fetch(endpointHref(this.opts, `/assets/${assetId}/slots`), {
+      headers: this.headers(),
+    });
+    if (!r.ok) throw new Error(`asset bindings ${r.status}: ${await r.text()}`);
+    const body = (await r.json()) as {
+      slots: Array<{
+        slotKey: string;
+        preset: VariantPreset | null;
+        description: string | null;
+        updatedAt: string;
+        updatedBy: string | null;
+      }>;
+    };
+    return body.slots;
+  }
+
+  /**
+   * Full variant list for an asset — preset, URL, dimensions, bytes.
+   * Stronger-typed wrapper around `get()` that exposes only the
+   * `variants` field with the proper `AssetVariant[]` shape.
+   *
+   *   const v = await aq.assets.variants(logoId);
+   *   v.map((x) => x.preset);  // → ("thumb" | "sm" | … | "original")[]
+   */
+  async variants(assetId: string): Promise<AssetVariant[]> {
+    const dto = await this.get(assetId);
+    return Array.isArray((dto as { variants?: unknown }).variants)
+      ? (dto as { variants: AssetVariant[] }).variants
+      : [];
+  }
+
+  /**
+   * Add or rebuild variants on an existing asset. Image presets are
+   * MERGED with what's there — passing `{ presets: ["thumb"] }` adds
+   * the thumb variant without touching `lg`, `sm`, `original`, etc.
+   *
+   *   // Day 0: upload original-only logo
+   *   const { assetId } = await aq.upload(logoFile);  // defaults to ["original"]
+   *
+   *   // Day 7: need a thumb without re-uploading
+   *   await aq.assets.regenerate(assetId, { presets: ["thumb"] });
+   *
+   *   const after = await aq.assets.variants(assetId);
+   *   after.map((v) => v.preset);  // → ["original", "thumb"]
+   *
+   * 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.
+   *
+   * Video presets are filtered to `["poster","video","aiproxy"]` and
+   * dispatched to the Cloud Run Job (the call returns immediately
+   * with a dispatch handle; poll `aq.assets.get(id).status` for
+   * completion).
+   */
+  async regenerate(
+    assetId: string,
+    opts: { presets?: VariantPreset[] } = {},
+  ): Promise<RegenerateResult> {
+    const r = await fetch(
+      endpointHref(this.opts, `/assets/${assetId}/regenerate`),
+      {
+        method: "POST",
+        headers: { ...this.headers(), "Content-Type": "application/json" },
+        body: JSON.stringify(opts.presets ? { presets: opts.presets } : {}),
+      },
+    );
+    if (!r.ok)
+      throw new Error(`asset regenerate ${r.status}: ${await r.text()}`);
+    return (await r.json()) as RegenerateResult;
+  }
+
+  /** Merge metadata into an asset (role / slot / description / tags). */
+  async patchMetadata(
+    assetId: string,
+    metadata: Record<string, unknown>,
+  ): Promise<{ ok: true; metadata: Record<string, unknown> }> {
+    const r = await fetch(endpointHref(this.opts, `/assets/${assetId}`), {
+      method: "PATCH",
+      headers: { ...this.headers(), "Content-Type": "application/json" },
+      body: JSON.stringify({ metadata }),
+    });
+    if (!r.ok) throw new Error(`asset patch ${r.status}: ${await r.text()}`);
+    return (await r.json()) as { ok: true; metadata: Record<string, unknown> };
+  }
+
+  /**
+   * Request a presigned R2 PUT URL for direct browser-side uploads.
+   *
+   * Mirrors the first half of `aq.upload()` — the caller (typically a
+   * BFF / share-link dropzone) computes sha256 in the browser, then
+   * uploads bytes straight to R2 with the returned `upload.url`, then
+   * POSTs `process.body` to `/assets/process` (see {@link processAndWait})
+   * once R2 has the bytes.
+   *
+   * If the sha is already known to the tenant the server short-circuits
+   * with `{ deduped: true, asset }` — no PUT needed.
+   *
+   * @example The browser-direct flow, in full
+   * ```ts
+   * // SERVER (holds the amk_rt_* key — never the browser):
+   * const presign = await aq.assets.presignUploadUrl({ sha256, mime, bytes, fileName, presets });
+   * if (presign.deduped) return presign.asset;      // those bytes already exist; none fly
+   *
+   * // BROWSER: PUT straight to presign.upload.url — the bytes never touch your server.
+   * // ⚠️ R2 answers that preflight ITSELF, so your origin must be in the BUCKET's CORS policy.
+   * //    Symptom when it is not: "PUT failed: network error" with every earlier step green —
+   * //    and it cannot be fixed in this SDK, in your app, or in `storefront_origins`.
+   *
+   * // SERVER again, forwarding presign.process.body VERBATIM:
+   * const asset = await aq.assets.processAndWait(presign.process.body, { timeoutMs: 300_000 });
+   * ```
+   *
+   * Works for images AND video. A video answers immediately with
+   * `{ assetId, status: "processing" }` while a Cloud Run Job transcodes, so
+   * give `processAndWait` a bigger `timeoutMs` (a transcode + HLS ladder runs
+   * 1–2 min; 300_000 is a sane floor).
+   */
+  async presignUploadUrl(
+    opts: PresignUploadUrlOptions,
+  ): Promise<UploadUrlResult> {
+    const body: Record<string, unknown> = {
+      sha256: opts.sha256,
+      mime: opts.mime,
+      bytes: opts.bytes,
+      fileName: opts.fileName,
+    };
+    if (opts.presets && opts.presets.length > 0) body.presets = opts.presets;
+    if (opts.clientOriginalBytes != null)
+      body.clientOriginalBytes = opts.clientOriginalBytes;
+    if (opts.video != null) body.video = opts.video;
+
+    const r = await fetch(endpointHref(this.opts, "/assets/upload-url"), {
+      method: "POST",
+      headers: { ...this.headers(), "Content-Type": "application/json" },
+      body: JSON.stringify(body),
+    });
+    if (!r.ok) throw new Error(`upload-url ${r.status}: ${await r.text()}`);
+    return (await r.json()) as UploadUrlResult;
+  }
+
+  /**
+   * Dispatch `/assets/process` with the body returned by a prior
+   * {@link presignUploadUrl} call, then poll until the asset transitions
+   * to `ready` or `failed`. Throws on `failed` or timeout.
+   *
+   * Use this when bytes were uploaded directly from the browser to R2 —
+   * `aq.upload()` already does presign + PUT + process + wait in one
+   * step when the server holds the bytes.
+   */
+  async processAndWait(
+    processBody: Record<string, unknown>,
+    opts: { timeoutMs?: number } = {},
+  ): Promise<AssetDTO> {
+    const r = await fetch(endpointHref(this.opts, "/assets/process"), {
+      method: "POST",
+      headers: { ...this.headers(), "Content-Type": "application/json" },
+      body: JSON.stringify(processBody),
+    });
+    if (!r.ok) throw new Error(`process ${r.status}: ${await r.text()}`);
+    const proc = (await r.json()) as { assetId?: string };
+    if (!proc.assetId) throw new Error("process returned no assetId");
+    const final = await this.waitReady(proc.assetId, opts.timeoutMs);
+    if (final.status === "failed") {
+      throw new Error(
+        `processAndWait: asset ${proc.assetId} ended status=failed`,
+      );
+    }
+    return final;
+  }
+
+  /**
+   * Poll `GET /assets/:id` until the asset transitions to `ready` or
+   * `failed`. Returns the final DTO (whether ready OR failed — callers
+   * decide whether to throw on `failed`). Throws on timeout.
+   *
+   * Default timeout is 5 minutes; videos / HLS ladders may need a
+   * higher cap (pass `10 * 60_000` for compositions, transcodes).
+   */
+  async waitReady(assetId: string, timeoutMs = 5 * 60_000): Promise<AssetDTO> {
+    const start = Date.now();
+    let delay = 500;
+    let last: AssetDTO | null = null;
+    while (Date.now() - start < timeoutMs) {
+      last = (await this.get(assetId)) as AssetDTO;
+      if (last.status === "ready" || last.status === "failed") return last;
+      await new Promise((r) => setTimeout(r, delay));
+      delay = Math.min(delay * 1.5, 5_000);
+    }
+    if (!last) throw new Error(`waitReady: no asset ${assetId}`);
+    throw new Error(`waitReady timeout for ${assetId}`);
+  }
+
+  /**
+   * Dispatch `POST /assets/compose-marketing` to stitch pre-uploaded clip
+   * segments into a single MP4 composition. Returns the processing asset
+   * id immediately — does NOT block on completion. Callers poll via
+   * {@link waitReady} (typical timeout: 10 min for multi-segment kits).
+   *
+   * Tenant scope is inherited from the SDK client; `tenantCode` is added
+   * to the request body so the Cloud Run Job can resolve it without
+   * re-reading the header.
+   */
+  async composeMarketing(
+    opts: ComposeMarketingOptions,
+  ): Promise<ComposeMarketingResult> {
+    const r = await fetch(
+      endpointHref(this.opts, "/assets/compose-marketing"),
+      {
+        method: "POST",
+        headers: { ...this.headers(), "Content-Type": "application/json" },
+        body: JSON.stringify({
+          tenantCode: this.opts.tenantCode,
+          marketingKitId: opts.marketingKitId,
+          segments: opts.segments,
+          composition: opts.composition ?? {},
+        }),
+      },
+    );
+    if (!r.ok) {
+      throw new Error(`compose-marketing ${r.status}: ${await r.text()}`);
+    }
+    const body = (await r.json()) as {
+      asset?: { id: string; status: "processing" | "ready" | "failed" };
+      assetId?: string;
+      status?: "processing" | "ready" | "failed";
+    };
+    // Server returns `{ asset: { id, status }, dispatch? }`; some older
+    // builds returned `{ assetId, status }` directly. Normalize both.
+    const assetId = body.asset?.id ?? body.assetId;
+    const status = body.asset?.status ?? body.status ?? "processing";
+    if (!assetId) {
+      throw new Error("compose-marketing: response missing assetId");
+    }
+    return { assetId, status };
+  }
+
+  private headers(): Record<string, string> {
+    return authHeaders(this.opts);
+  }
+}
+
+// ---------------------------------------------------------------------------
+// Upload helpers
+// ---------------------------------------------------------------------------
+
+/**
+ * Best-effort MIME from a file name's extension. Used as a fallback for `Uint8Array`
+ * uploads (which carry no inherent type) so they still get classified correctly instead
+ * of silently becoming `application/octet-stream` → `kind:"other"`. Returns `null` when
+ * the extension is unknown.
+ */
+const MIME_BY_EXT: Record<string, string> = {
+  webp: "image/webp",
+  jpg: "image/jpeg",
+  jpeg: "image/jpeg",
+  png: "image/png",
+  gif: "image/gif",
+  avif: "image/avif",
+  heic: "image/heic",
+  heif: "image/heif",
+  svg: "image/svg+xml",
+  bmp: "image/bmp",
+  tiff: "image/tiff",
+  mp4: "video/mp4",
+  webm: "video/webm",
+  mov: "video/quicktime",
+  m4v: "video/x-m4v",
+  pdf: "application/pdf",
+};
+export function mimeFromFileName(fileName: string | undefined): string | null {
+  if (!fileName) return null;
+  const ext = fileName.split(".").pop()?.toLowerCase();
+  return ext ? (MIME_BY_EXT[ext] ?? null) : null;
+}
+
+/**
+ * Subset of compressorjs options exposed through the SDK. Re-imported here
+ * to avoid a hard import dependency on `./web` from this top-level module
+ * (the /web subpath uses browser-only APIs). The runtime `compress`
+ * implementation is lazy-loaded so Node/Bun callers don't pay the bundle
+ * cost — see `aq.upload` below.
+ */
+export type CompressOptions = {
+  quality?: number;
+  mimeType?: "image/jpeg" | "image/webp";
+  maxWidth?: number;
+  maxHeight?: number;
+  convertSize?: number;
+  strict?: boolean;
+  keepOriginalDimensions?: boolean;
+  convertHeic?: boolean;
+  onProgress?: (
+    stage: "convertingHeic" | "compressing" | "compressingKeepingDimensions",
+  ) => void;
+};
+
+export type UploadOptions = {
+  fileName?: string;
+  /**
+   * MIME type of the bytes. **Only needed for a `Uint8Array` input** — a `File`/`Blob`
+   * already carries its `.type`. Raw bytes have no inherent MIME, so without this (and
+   * without an extension on `fileName` to infer from) they upload as
+   * `application/octet-stream`, which the asset-manager classifies as `kind:"other"` —
+   * meaning NO image/video variants are generated and `regenerate()` is unsupported.
+   * Resolution order for the effective MIME: `Blob.type` → `contentType` →
+   * inferred from `fileName`'s extension → `application/octet-stream`.
+   *
+   *   aq.upload(bytes, { fileName: "cover.webp" })                 // inferred → image/webp ✓
+   *   aq.upload(bytes, { contentType: "image/webp" })             // explicit ✓
+   *   aq.upload(bytes)                                             // octet-stream → kind:"other" ⚠
+   */
+  contentType?: string;
+  /** Computed sha256 of bytes. Skip to compute locally with WebCrypto (browser only). */
+  sha256?: string;
+  /**
+   * Client-side compression before upload. Saves user bandwidth — typical
+   * 5–10× reduction for raw phone photos. Browser-only; in Node/Bun this
+   * silently no-ops with a console.warn and the raw bytes upload as-is.
+   *
+   *   - `true`             → use SDK `DEFAULT_COMPRESSION_OPTIONS` (webapp-tuned)
+   *   - `CompressOptions`  → merge over defaults
+   *   - `false` / omit     → no compression (current default behavior)
+   *
+   * Implementation is lazy-imported from `@nitida/sdk/web` so callers
+   * that never set `compress` don't pay the compressorjs + heic2any
+   * bundle cost. Skipped for non-image MIMEs (video, PDF) regardless of
+   * this option — those go to the upload pipeline raw.
+   *
+   * @see {@link CompressOptions}
+   * @see https://github.com/espaciofuturoio/aquienpz/tree/main/packages/sdk#client-side-compression-browsers
+   */
+  compress?: boolean | CompressOptions;
+  /**
+   * Variant set to generate. **Defaults to `["original"]`** —
+   * if you omit this option, only the raw bytes land on the CDN
+   * under the `o` path. Pass an explicit array to request more.
+   *
+   * Image presets (`thumb` 256 · `sm` 640 · `md` 1280 · `lg` 1920 ·
+   * `xl` 3840 · `original`):
+   *   - `["original"]` (default) → just the raw bytes. Right call for
+   *     logos / SVGs / anything you'll resize browser-side or via
+   *     `aq.assets.regenerate(id, { presets: ["thumb"] })` later.
+   *   - `["thumb","sm","md","lg"]` → the classic responsive ladder.
+   *   - `["thumb","sm","md","lg","xl"]` → add 4K.
+   *
+   * Video presets (`poster`, `video`, `aiproxy`): omit `aiproxy` if
+   * the tenant doesn't need the low-res transcode for AI captioning.
+   *
+   * No upscaling. Each size preset is a **ceiling**; a 1080×720 source
+   * asked for `xl` (3840) yields a 1080×720 xl variant, not a stretched
+   * 3840-wide image.
+   *
+   * Idempotent: you can always add missing variants later via
+   * `aq.assets.regenerate(id, { presets: [...] })`. The platform
+   * stores the source so regeneration doesn't require re-uploading.
+   */
+  presets?: VariantPreset[];
+  /**
+   * 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.
+   *
+   * Throws `Error("waitReady timeout for <id>")` if the deadline passes
+   * without the asset transitioning. The asset row stays in aquienpz
+   * (status="processing") and the next byHash lookup will return it once
+   * processing completes; the caller can resume with their own poll.
+   */
+  timeoutMs?: number;
+  /**
+   * VIDEO-only delivery knobs forwarded into `/assets/process`. See
+   * {@link UploadVideoOptions}. Ignored for non-video uploads.
+   *
+   *   // A delivery-ready reel: skip the unused HLS ladder + skip re-encode.
+   *   await aq.upload(mp4Bytes, {
+   *     fileName: "reel.mp4",
+   *     presets: ["poster", "video"],
+   *     video: { hls: false, passthrough: true },
+   *   });
+   */
+  video?: UploadVideoOptions;
+};
+
+/** Default preset set the SDK sends to `/assets/upload-url` when the caller omits `presets`. */
+const DEFAULT_UPLOAD_PRESETS: VariantPreset[] = ["original"];
+
+export type UploadResult = {
+  assetId: string;
+  sha256: string;
+  cdnUrl: string;
+};
+
+async function computeSha256(
+  bytes: ArrayBuffer | Uint8Array | Blob,
+): Promise<string> {
+  const buf =
+    bytes instanceof Blob
+      ? await bytes.arrayBuffer()
+      : bytes instanceof Uint8Array
+        ? (bytes.buffer as ArrayBuffer)
+        : bytes;
+  const digest = await crypto.subtle.digest("SHA-256", buf);
+  return [...new Uint8Array(digest)]
+    .map((b) => b.toString(16).padStart(2, "0"))
+    .join("");
+}
+
+// ---------------------------------------------------------------------------
+// Main facade
+// ---------------------------------------------------------------------------
+
+// ---------------------------------------------------------------------------
+// Usage (Cloudinary-style consumption dashboard data)
+// ---------------------------------------------------------------------------
+
+// ---------------------------------------------------------------------------
+// Slot history
+// ---------------------------------------------------------------------------
+
+export type SlotHistoryEntry = {
+  id: string;
+  action: "bind" | "unbind" | "restore";
+  preset: VariantPreset | null;
+  description: string | null;
+  updatedAt: string;
+  updatedBy: string | null;
+  assetId: string | null;
+  /** Resolved DTO when the asset still exists; `null` after delete / 404. */
+  asset: AssetDTO | null;
+};
+
+export type UsageSnapshot = {
+  tenant: { id: number; code: string };
+  storage: { totalBytes: number; assetCount: number };
+  today: UsageWindow;
+  last30Days: UsageWindow;
+};
+
+export type UsageWindow = {
+  reads: number;
+  writes: number;
+  lists: number;
+  deletes: number;
+  admins: number;
+  upscales: number;
+  processes: number;
+  bytesIn: number;
+};
+
+export type UsageDailyPoint = {
+  date: string;
+  reads: number;
+  writes: number;
+  lists: number;
+  deletes: number;
+  processes: number;
+  bytesIn: number;
+  bytesStored: number;
+};
+
+export type UsagePerKey = {
+  apiKeyId: string;
+  prefix: string | null;
+  name: string | null;
+  opsTotal: number;
+  bytesTotal: number;
+  lastSeen: string;
+};
+
+class UsageApi {
+  constructor(private readonly opts: AquienpzClientOptions) {}
+
+  /** Snapshot for the active tenant — storage + today + last 30 days totals. */
+  async snapshot(): Promise<UsageSnapshot> {
+    const r = await fetch(endpointHref(this.opts, "/usage"), {
+      headers: this.headers(),
+    });
+    if (!r.ok) throw new Error(`usage snapshot ${r.status}: ${await r.text()}`);
+    return (await r.json()) as UsageSnapshot;
+  }
+
+  /** Daily rollup for charts — 1..365 days, default 30. */
+  async timeseries(days = 30): Promise<{
+    tenant: { id: number; code: string };
+    days: UsageDailyPoint[];
+  }> {
+    const r = await fetch(
+      endpointUrl(this.opts, "/usage/timeseries", { days }),
+      { headers: this.headers() },
+    );
+    if (!r.ok)
+      throw new Error(`usage timeseries ${r.status}: ${await r.text()}`);
+    return (await r.json()) as {
+      tenant: { id: number; code: string };
+      days: UsageDailyPoint[];
+    };
+  }
+
+  /** Per-API-key breakdown for the current month. */
+  async keys(): Promise<{
+    tenant: { id: number; code: string };
+    monthStart: string;
+    keys: UsagePerKey[];
+  }> {
+    const r = await fetch(endpointHref(this.opts, "/usage/keys"), {
+      headers: this.headers(),
+    });
+    if (!r.ok) throw new Error(`usage keys ${r.status}: ${await r.text()}`);
+    return (await r.json()) as {
+      tenant: { id: number; code: string };
+      monthStart: string;
+      keys: UsagePerKey[];
+    };
+  }
+
+  private headers(): Record<string, string> {
+    return authHeaders(this.opts);
+  }
+}
+
+export class AquienpzClient {
+  readonly slots: SlotsApi;
+  readonly assets: AssetsApi;
+  readonly usage: UsageApi;
+  /**
+   * Effective options — read-only. Exposed so the `/web` and `/expo`
+   * subpaths can inherit endpoint / apiKey / tenant scope from the
+   * configured client without re-passing them per call site.
+   */
+  readonly opts: AquienpzClientOptions;
+
+  constructor(opts: AquienpzClientOptions) {
+    this.opts = opts;
+    const cdn = opts.cdnBase ?? "https://8ok.uk";
+    setCdnBase(cdn);
+    // Configure the process-global tenant so every variant URL builder
+    // (`getAssetUrl`, `urlFor`, `srcSetFor`, upload `cdnUrl`) emits the
+    // tenant-prefixed path `<cdn>/<tid b36>/v/<sha>-<preset>.<ext>`.
+    setTenantId(opts.tenantId);
+    configureSlotResolver({
+      endpoint: opts.endpoint,
+      apiKey: opts.apiKey,
+      tenantCode: opts.tenantCode,
+    });
+    this.slots = new SlotsApi(opts);
+    this.assets = new AssetsApi(opts);
+    this.usage = new UsageApi(opts);
+  }
+
+  /** Tenant id as base36 path segment (e.g. tenantId=4 → "4/v/"). */
+  get tenantSegment(): string {
+    return `${this.opts.tenantId.toString(36)}/v/`;
+  }
+
+  /** Build the canonical CDN URL deterministically from sha + preset. */
+  urlFor(asset: Pick<AssetDTO, "sha">, preset: VariantPreset = "lg"): string {
+    return getAssetUrl(asset, preset);
+  }
+
+  /** Build a responsive srcSet across the available image presets. */
+  srcSetFor(asset: Pick<AssetDTO, "sha" | "presets">): string {
+    return getAssetSrcSet(asset);
+  }
+
+  /**
+   * Build an on-the-fly transform URL — `<cdn>/t/<dsl>/<sha>.<ext>`.
+   *
+   * ## URL CONVENTION — transforms are NOT tenant-prefixed (variants are)
+   * Two distinct delivery paths, by design:
+   *   - **Variants / presets** (`urlFor`, `srcSetFor`, upload `cdnUrl`):
+   *       `<cdn>/<tenantId b36>/v/<sha>-<preset>.<ext>`   ← tenant-scoped (e.g. `/4/v/<sha>-lg.webp`)
+   *   - **On-the-fly transforms** (`transform`, `transformSrcSet`):
+   *       `<cdn>/t/<dsl>/<sha>.<ext>`                      ← GLOBAL, no tenant segment (`/t/...`)
+   * The transform service is content-addressed by sha + resizes from the source on demand,
+   * so it needs no tenant in the path. Prefixing a transform URL with `/<tenant>/t/...` 404s.
+   * Consumers that build URLs by hand must NOT add the tenant segment to `/t/` URLs.
+   *
+   * Returns the canonical `lg` variant URL when called with empty options,
+   * so callers can swap `urlFor()` for `transform()` without thinking.
+   *
+   * URLs with the same params in different order produce the same R2
+   * cache entry (the server canonicalizes both sides). Safe to use as
+   * stable cache keys.
+   *
+   *   <Image
+   *     src={aq.transform(asset, { width: 1280 })}
+   *     srcSet={aq.transformSrcSet(asset, [640, 960, 1280, 1920])}
+   *     sizes="(max-width: 768px) 100vw, 50vw"
+   *   />
+   *
+   * @see {@link TransformOptions} for the full param matrix.
+   */
+  // Overload 1: no signing — synchronous, on-ladder width only (strict).
+  transform(asset: Pick<AssetDTO, "sha">, opts?: TransformOptions): string;
+  // Overload 2: with { sign: true } — async; returns `?sig=<hmac>` URL.
+  // Accepts SignedTransformOptions so a signed URL may carry an off-ladder
+  // custom width (the signature earns the edge whitelist bypass).
+  transform(
+    asset: Pick<AssetDTO, "sha">,
+    opts: SignedTransformOptions,
+    signOpts: { sign: true },
+  ): Promise<string>;
+  transform(
+    asset: Pick<AssetDTO, "sha">,
+    opts: SignedTransformOptions = {},
+    signOpts?: { sign: true },
+  ): string | Promise<string> {
+    if (!signOpts?.sign) {
+      // Unsigned path. Overload 1 constrains `width` to the ladder at every
+      // public call site, so an off-ladder width can't reach here through the
+      // typed API — narrow back to TransformOptions for the strict builder.
+      return (
+        getTransformUrl(asset, opts as TransformOptions) ??
+        this.urlFor(asset, "lg")
+      );
+    }
+    if (!this.opts.signingKey) {
+      throw new Error(
+        "aq.transform({ sign: true }) requires `signingKey` in AquienpzClientOptions. " +
+          "Pull the tenant's signing key from /admin/tenants/:id and pass it to the SDK constructor on a SERVER-side instance only.",
+      );
+    }
+    // Signed path — custom (off-ladder) widths allowed. Empty opts → no
+    // transform DSL, fall back to the unsigned `lg` variant URL.
+    return (
+      getSignedTransformUrl(asset, opts, this.opts.signingKey) ??
+      Promise.resolve(this.urlFor(asset, "lg"))
+    );
+  }
+
+  /**
+   * Build a responsive `srcSet` string. One transform URL per width; all
+   * other options apply to every URL.
+   *
+   * Pass `{ sign: true }` to return signed URLs (async). Without it, the
+   * call stays synchronous as before.
+   */
+  transformSrcSet(
+    asset: Pick<AssetDTO, "sha">,
+    widths: number[],
+    extraOpts?: Omit<TransformOptions, "width">,
+  ): string;
+  transformSrcSet(
+    asset: Pick<AssetDTO, "sha">,
+    widths: number[],
+    extraOpts: Omit<TransformOptions, "width">,
+    signOpts: { sign: true },
+  ): Promise<string>;
+  transformSrcSet(
+    asset: Pick<AssetDTO, "sha">,
+    widths: number[],
+    extraOpts: Omit<TransformOptions, "width"> = {},
+    signOpts?: { sign: true },
+  ): string | Promise<string> {
+    if (!signOpts?.sign) return getTransformSrcSet(asset, widths, extraOpts);
+    if (!this.opts.signingKey) {
+      throw new Error(
+        "aq.transformSrcSet({ sign: true }) requires `signingKey` in AquienpzClientOptions.",
+      );
+    }
+    const key = this.opts.signingKey;
+    return Promise.all(
+      widths.map(async (w) => {
+        // Signed path → off-ladder widths allowed; build+sign via the
+        // custom-width helper (the strict `getTransformUrl` would reject a
+        // raw `number` width).
+        const signed = await getSignedTransformUrl(
+          asset,
+          { ...extraOpts, width: w },
+          key,
+        );
+        return signed ? `${signed} ${w}w` : null;
+      }),
+    ).then((parts) => parts.filter((s): s is string => s != null).join(", "));
+  }
+
+  /**
+   * Build an on-the-fly VIDEO transform URL — Phase 4.
+   *
+   * Same DSL shape as `transform()` but the URL has a `.mp4` (default)
+   * or `.webm` extension and the server routes the request to a Cloud
+   * Run Job for ffmpeg encoding (vs the inline sharp pipeline for
+   * images).
+   *
+   * On the first request the route returns **202 Accepted** with
+   * `Retry-After: 10` while the Job 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.
+   *
+   *   const url = aq.transformVideo(asset, {
+   *     width: 1080, height: 1920, fit: "cover",
+   *     start: 0, duration: 15,
+   *   });
+   *   // Pass to Video.js / <video src={url}>; on the first load it
+   *   // gets 202 + body.outputUrl; subsequent loads hit cache → 302.
+   *
+   * Video-specific DSL params:
+   *   - `start` (seconds, decimal OK)
+   *   - `duration` (seconds, 1..300)
+   *   - `format`: "mp4" (default) or "webm"
+   *
+   * The other params (`width`, `height`, `fit`) work identically to
+   * image transforms. `gravity`, `quality`, `effect`, `dpr` are
+   * accepted by the DSL but currently ignored on the video path.
+   */
+  transformVideo(
+    asset: Pick<AssetDTO, "sha">,
+    opts: TransformOptions = {},
+  ): string {
+    return getVideoTransformUrl(asset, opts) ?? this.urlFor(asset, "lg");
+  }
+
+  /**
+   * Build the HLS master playlist URL for a VIDEO asset (Phase 5).
+   *
+   * Returns `<cdn>/t/format=hls(,start=…,duration=…)/<sha>.m3u8`. Pass
+   * to an HLS-aware player:
+   *
+   *   <video
+   *     src={aq.streamingUrl(asset)}
+   *     controls playsInline
+   *     // Video.js v10's @videojs/http-streaming ships native HLS —
+   *     // no plugin needed.
+   *   />
+   *
+   * On the first request the server returns **202 Accepted** while a
+   * Cloud Run Job builds the multi-rung ladder (typically 1-3 min for
+   * a 90 s source — five rungs of 240p/360p/480p/720p/1080p @ AAC).
+   * Subsequent requests hit the cache → **302** to the master.m3u8.
+   *
+   * Supports `start` + `duration` to ladder a sub-clip. Other DSL
+   * params (width, height, fit) are ignored on the HLS path because
+   * the rungs determine resolution.
+   */
+  streamingUrl(
+    asset: Pick<AssetDTO, "sha">,
+    opts: Omit<TransformOptions, "format"> = {},
+  ): string {
+    return getHlsStreamingUrl(asset, opts);
+  }
+
+  /**
+   * Upload a file or raw bytes. Returns the new asset id + canonical
+   * URL. Hash-deduped — uploading the same bytes twice returns the
+   * existing asset.
+   *
+   * Browser-first: uses `Blob` + WebCrypto. For Node 20+, pass a
+   * Uint8Array and a precomputed `sha256` (since `crypto.subtle` works
+   * but isn't always available depending on the runtime).
+   */
+  /**
+   * Upload bytes end to end: optional client compression → sha256 → presign → **direct-to-R2 PUT**
+   * → `/assets/process` → wait until the asset is ready.
+   *
+   * ⚠️ `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".
+   *
+   * @example Deliver an image on a site (the responsive ladder)
+   * ```ts
+   * import { AquienpzClient } from "@nitida/sdk/server";
+   *
+   * const aq = new AquienpzClient({ endpoint, apiKey, tenantCode, tenantId });
+   * const { assetId, sha256 } = await aq.upload(file, {
+   *   fileName: file.name,
+   *   presets: ["thumb", "sm", "md", "lg"],
+   * });
+   * ```
+   *
+   * @example ARCHIVE a file — you must ask for `original`
+   * ```ts
+   * await aq.upload(bytes, {
+   *   fileName: "contrato.pdf",
+   *   contentType: "application/pdf",
+   *   presets: ["original"],          // without this the bytes are unrecoverable
+   * });
+   * ```
+   *
+   * @example Raw bytes need an explicit MIME
+   * ```ts
+   * await aq.upload(bytes, { fileName: "track.mp3", contentType: "audio/mpeg" });
+   * // Without either, it stores as kind:"other" — no variants, and regenerate() is unsupported.
+   * ```
+   *
+   * @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.
+   * await aq.upload(clip, { fileName: "tour.mp4", presets: ["poster", "video"] });
+   *
+   * // Omit `aiproxy`/`probe` unless the asset really goes to a vision model — they cost Job time
+   * // and permanent R2 objects that nothing else reads.
+   * ```
+   */
+  async upload(
+    input: File | Blob | Uint8Array,
+    opts: UploadOptions = {},
+  ): Promise<UploadResult> {
+    // 1. Resolve incoming bytes + mime first (the source of truth for
+    //    "should we compress this?")
+    const sourceIsBlob = input instanceof File || input instanceof Blob;
+    // A Uint8Array has no inherent MIME. Fall back to an explicit `contentType`, then to
+    // the file extension, before octet-stream (which the asset-manager files as
+    // `kind:"other"` — no variants). A File/Blob's own `.type` always wins when present.
+    const sourceMime =
+      (sourceIsBlob ? input.type : "") ||
+      opts.contentType ||
+      mimeFromFileName(opts.fileName) ||
+      "application/octet-stream";
+    if (!sourceIsBlob && sourceMime === "application/octet-stream") {
+      console.warn(
+        "[@nitida/sdk] upload(Uint8Array): no MIME resolved (no `contentType`, no recognizable " +
+          '`fileName` extension) — the asset will be stored as kind:"other" with NO image/video ' +
+          "variants and regenerate() unsupported. Pass `contentType` or a `fileName` with an extension.",
+      );
+    }
+
+    // 2. Optional client-side compression. Image MIMEs only; non-image
+    //    sources pass through unchanged so a video or PDF upload still
+    //    works when the caller sets `compress: true` blanket-fashion.
+    let bytes: Uint8Array;
+    let effectiveMime: string;
+    let clientOriginalBytes: number | undefined;
+
+    const wantCompression =
+      !!opts.compress &&
+      sourceIsBlob &&
+      typeof window !== "undefined" &&
+      sourceMime.startsWith("image/");
+
+    if (wantCompression) {
+      const compressOpts =
+        opts.compress === true ? {} : (opts.compress as CompressOptions);
+      // Lazy: keeps compressorjs/heic2any out of bundles that don't use it.
+      //
+      // Resolve `./web` against `import.meta.url` at runtime so no static
+      // analyzer — esbuild, tsup, `bun build --compile`, vite, rollup —
+      // can follow the specifier. Holding the path in a plain `const`
+      // was not enough: `bun build --compile` constant-folds simple
+      // strings and still eagerly bundled `./web.js`, which
+      // top-level-imports the browser-only peer deps
+      // `@aquienpz/asset-uploader-web` / `@nitida/asset-compressor-web`
+      // — neither installed on server consumers — crashing the
+      // single-binary on boot with `Cannot find module
+      // '@aquienpz/asset-uploader-web'`.
+      //
+      // The earlier `new URL("./web.js", import.meta.url)` + `await import(URL)`
+      // dance survived bun-compile but Turbopack still tracks the URL literal
+      // and tries to resolve `./web.js` at build time (no such file exists in
+      // src/, only src/web/index.ts), failing with "Module not found".
+      //
+      // Indirect-eval via the Function constructor is opaque to BOTH static
+      // analyzers — neither bun-compile nor Turbopack can follow the string
+      // back to a module specifier. The browser `typeof window` guard above
+      // ensures the branch never runs on the server, so the indirection is
+      // safe at runtime.
+      // Build the URL inside the Function body too — Turbopack still tracks
+      // `new URL(<any expr>, import.meta.url)` as a resolution pattern even
+      // when the first arg isn't a literal, so we have to hide both the URL
+      // construction AND the import() behind indirect eval.
+      const dynImport = new Function(
+        "base",
+        "return import(new URL('./' + 'web' + '.js', base).href)",
+      ) as (base: string) => Promise<typeof import("./web")>;
+      const { compressImage } = await dynImport(import.meta.url);
+      const result = await compressImage(input as File | Blob, compressOpts);
+      bytes = new Uint8Array(await result.blob.arrayBuffer());
+      clientOriginalBytes = result.originalBytes;
+      effectiveMime = result.blob.type || sourceMime;
+    } else {
+      if (opts.compress && !sourceIsBlob) {
+        console.warn(
+          "[@nitida/sdk] compress: true requires a File or Blob input; got Uint8Array — uploading raw bytes.",
+        );
+      } else if (opts.compress && typeof window === "undefined") {
+        console.warn(
+          "[@nitida/sdk] compress: true is browser-only — uploading raw bytes.",
+        );
+      } else if (opts.compress && !sourceMime.startsWith("image/")) {
+        // Silent: callers can set `compress: true` for batched mixed
+        // media and not have to special-case images vs videos.
+      }
+      bytes =
+        input instanceof Uint8Array
+          ? input
+          : new Uint8Array(await input.arrayBuffer());
+      effectiveMime = sourceMime;
+    }
+
+    const sha = opts.sha256 ?? (await computeSha256(bytes));
+    const mime = effectiveMime;
+    const fileName =
+      opts.fileName ??
+      (input instanceof File ? input.name : `upload-${sha.slice(0, 8)}.bin`);
+
+    // Dedup probe.
+    const existing = await this.assets.byHash(sha);
+    if (existing && existing.status === "ready") {
+      return {
+        assetId: existing.id,
+        sha256: sha,
+        cdnUrl: this.urlFor(existing, this.bestPresetForAsset(existing, mime)),
+      };
+    }
+
+    // Presign + PUT + process. Delegates to `assets.presignUploadUrl()` so
+    // the public method and `aq.upload()` share one code path; always
+    // threads an explicit preset list so the default matches the SDK
+    // contract (`["original"]`) instead of inheriting the server's older
+    // default (`thumb+sm+md+lg`).
+    const presign = await this.assets.presignUploadUrl({
+      sha256: sha,
+      mime,
+      bytes: bytes.byteLength,
+      fileName,
+      presets:
+        opts.presets && opts.presets.length > 0
+          ? opts.presets
+          : DEFAULT_UPLOAD_PRESETS,
+      ...(clientOriginalBytes != null && { clientOriginalBytes }),
+      ...(opts.video != null && { video: opts.video }),
+    });
+    if (presign.deduped) {
+      return {
+        assetId: presign.asset.id,
+        sha256: sha,
+        cdnUrl: this.urlFor(presign.asset, this.defaultPresetForMime(mime)),
+      };
+    }
+
+    const putR = await fetch(presign.upload.url, {
+      method: "PUT",
+      headers: { "Content-Type": mime, ...(presign.upload.headers ?? {}) },
+      body: new Blob([bytes as unknown as ArrayBuffer], { type: mime }),
+    });
+    if (!putR.ok)
+      throw new Error(`R2 PUT ${putR.status}: ${await putR.text()}`);
+
+    const procR = await fetch(endpointHref(this.opts, presign.process.url), {
+      method: "POST",
+      headers: {
+        ...authHeaders(this.opts),
+        "Content-Type": "application/json",
+      },
+      body: JSON.stringify(presign.process.body),
+    });
+    if (!procR.ok)
+      throw new Error(`process ${procR.status}: ${await procR.text()}`);
+    const proc = (await procR.json()) as { assetId?: string; kind?: string };
+
+    let assetId = proc.assetId;
+    if (!assetId && proc.kind === "video") {
+      // Videos are async — poll by-hash until the row lands.
+      const start = Date.now();
+      let delay = 1000;
+      while (Date.now() - start < 60_000) {
+        const dto = await this.assets.byHash(sha);
+        if (dto?.id) {
+          assetId = dto.id;
+          break;
+        }
+        await new Promise((r) => setTimeout(r, delay));
+        delay = Math.min(delay * 1.5, 5_000);
+      }
+    }
+    if (!assetId) throw new Error("upload: process returned no assetId");
+
+    // Wait until variants are ready so the URL works immediately.
+    // Passing `undefined` keeps waitReady's own default (5 min). Callers
+    // uploading large videos can opt in to a longer deadline via opts.timeoutMs.
+    const final = await this.assets.waitReady(assetId, opts.timeoutMs);
+    if (final.status !== "ready")
+      throw new Error(`upload: asset ended status=${final.status}`);
+    return {
+      assetId,
+      sha256: sha,
+      cdnUrl: this.urlFor(final, this.bestPresetForAsset(final, mime)),
+    };
+  }
+
+  private defaultPresetForMime(mime: string): VariantPreset {
+    if (mime.startsWith("video/")) return "video";
+    // The `mp3` variant only exists AFTER /process transcodes it; at presign
+    // time only the original is guaranteed to be playable, so bind to it.
+    if (mime.startsWith("audio/")) return "original";
+    return "lg";
+  }
+
+  /**
+   * Pick a sensible preset to build a URL for, given the asset's actual
+   * `presets` string. Falls back through the preference order
+   *   lg → md → sm → thumb → original   (for images)
+   *   video → poster                    (for videos)
+   *   mp3 → original                    (for audio)
+   * so an upload that was processed with e.g. `["original"]` still
+   * returns a non-404 URL in `aq.upload`'s result.
+   */
+  private bestPresetForAsset(asset: AssetDTO, mime: string): VariantPreset {
+    const order: VariantPreset[] = mime.startsWith("video/")
+      ? ["video", "poster"]
+      : mime.startsWith("audio/")
+        ? ["mp3", "original"] // prefer the cross-browser mp3, else the playable original; never image presets
+        : ["lg", "md", "sm", "thumb", "xl", "original"];
+    return (
+      order.find((p) => hasPreset(asset, p)) ?? this.defaultPresetForMime(mime)
+    );
+  }
+}