@nitida/sdk 0.20.0

package/dist/server.js

@@ -0,0 +1,808 @@
+// src/index.ts
+import {
+  configureSlotResolver,
+  getAssetSrcSet,
+  getAssetUrl,
+  getHlsStreamingUrl,
+  getSignedTransformUrl,
+  getTransformSrcSet,
+  getTransformUrl,
+  getVideoTransformUrl,
+  hasPreset,
+  invalidateSlotCache,
+  resolveSlot,
+  resolveSlots,
+  setCdnBase,
+  setTenantId
+} from "@nitida/asset-client";
+import {
+  computeVariantDimensions,
+  extractAssetSha,
+  getAssetDimensions,
+  getAssetSrcSet as getAssetSrcSet2,
+  getAssetUrl as getAssetUrl2,
+  getHlsStreamingUrl as getHlsStreamingUrl2,
+  getSignedTransformUrl as getSignedTransformUrl2,
+  getTenantId,
+  getTransformSrcSet as getTransformSrcSet2,
+  getTransformUrl as getTransformUrl2,
+  getVideoTransformUrl as getVideoTransformUrl2,
+  hasPreset as hasPreset2,
+  serializeTransform,
+  setTenantId as setTenantId2,
+  signTransformUrl
+} from "@nitida/asset-client";
+function endpointUrl(opts, path, searchParams) {
+  const endpoint = opts.endpoint.replace(/\/+$/, "");
+  const isAbsolute = /^https?:\/\//i.test(endpoint);
+  let base;
+  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 !== void 0 && v !== null && v !== "") {
+        u.searchParams.set(k, String(v));
+      }
+    }
+  }
+  return u;
+}
+function endpointHref(opts, path) {
+  return endpointUrl(opts, path).toString();
+}
+function authHeaders(opts) {
+  const h = {
+    // 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;
+}
+var SlotsApi = class {
+  constructor(opts) {
+    this.opts = opts;
+  }
+  opts;
+  /** Resolve one slot — returns `{slot, preset, url}` or `{slot: null, url: null}` when unbound. */
+  resolve(slotKey, options = {}) {
+    return resolveSlot(slotKey, options);
+  }
+  /** Bulk-resolve N slots in one HTTP round-trip. */
+  resolveMany(slotKeys, options = {}) {
+    return resolveSlots(slotKeys, options);
+  }
+  /** List slots for the tenant (admin). Optional prefix filter for tree views. */
+  async list(opts = {}) {
+    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();
+    return body.slots;
+  }
+  /** Bind / rebind a slot to an asset. Admin-only operation. */
+  async bind(slotKey, body) {
+    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();
+  }
+  /**
+   * 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, opts = {}) {
+    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();
+    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, args) {
+    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();
+  }
+  /** Remove a slot binding. The asset itself is left alone. */
+  async unbind(slotKey) {
+    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();
+  }
+  /** Invalidate the in-process cache after a slot rebind. */
+  invalidateCache(slotKey) {
+    invalidateSlotCache(slotKey);
+  }
+  headers() {
+    return authHeaders(this.opts);
+  }
+};
+var AssetsApi = class {
+  constructor(opts) {
+    this.opts = opts;
+  }
+  opts;
+  /** Look up an asset by full sha256 (64 hex). Returns null on 404. */
+  async byHash(sha256) {
+    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();
+  }
+  /** Bulk lookup by sha256s. */
+  async byHashes(hashes) {
+    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();
+  }
+  /** Paginated list of recent assets for the tenant. */
+  async list(opts = {}) {
+    const u = endpointUrl(this.opts, "/assets", {
+      limit: opts.limit,
+      cursor: opts.cursor,
+      include_deleted: opts.includeDeleted ? "true" : void 0
+    });
+    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();
+  }
+  /** Full DTO for an asset (admin view — includes audit-only fields). */
+  async get(assetId) {
+    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();
+  }
+  /**
+   * 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) {
+    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();
+    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) {
+    const dto = await this.get(assetId);
+    return Array.isArray(dto.variants) ? dto.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, opts = {}) {
+    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();
+  }
+  /** Merge metadata into an asset (role / slot / description / tags). */
+  async patchMetadata(assetId, metadata) {
+    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();
+  }
+  /**
+   * 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) {
+    const body = {
+      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();
+  }
+  /**
+   * 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, opts = {}) {
+    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();
+    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, timeoutMs = 5 * 6e4) {
+    const start = Date.now();
+    let delay = 500;
+    let last = null;
+    while (Date.now() - start < timeoutMs) {
+      last = await this.get(assetId);
+      if (last.status === "ready" || last.status === "failed") return last;
+      await new Promise((r) => setTimeout(r, delay));
+      delay = Math.min(delay * 1.5, 5e3);
+    }
+    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) {
+    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();
+    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 };
+  }
+  headers() {
+    return authHeaders(this.opts);
+  }
+};
+var MIME_BY_EXT = {
+  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"
+};
+function mimeFromFileName(fileName) {
+  if (!fileName) return null;
+  const ext = fileName.split(".").pop()?.toLowerCase();
+  return ext ? MIME_BY_EXT[ext] ?? null : null;
+}
+var DEFAULT_UPLOAD_PRESETS = ["original"];
+async function computeSha256(bytes) {
+  const buf = bytes instanceof Blob ? await bytes.arrayBuffer() : bytes instanceof Uint8Array ? bytes.buffer : bytes;
+  const digest = await crypto.subtle.digest("SHA-256", buf);
+  return [...new Uint8Array(digest)].map((b) => b.toString(16).padStart(2, "0")).join("");
+}
+var UsageApi = class {
+  constructor(opts) {
+    this.opts = opts;
+  }
+  opts;
+  /** Snapshot for the active tenant — storage + today + last 30 days totals. */
+  async snapshot() {
+    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();
+  }
+  /** Daily rollup for charts — 1..365 days, default 30. */
+  async timeseries(days = 30) {
+    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();
+  }
+  /** Per-API-key breakdown for the current month. */
+  async keys() {
+    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();
+  }
+  headers() {
+    return authHeaders(this.opts);
+  }
+};
+var AquienpzClient = class {
+  slots;
+  assets;
+  usage;
+  /**
+   * 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.
+   */
+  opts;
+  constructor(opts) {
+    this.opts = opts;
+    const cdn = opts.cdnBase ?? "https://8ok.uk";
+    setCdnBase(cdn);
+    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() {
+    return `${this.opts.tenantId.toString(36)}/v/`;
+  }
+  /** Build the canonical CDN URL deterministically from sha + preset. */
+  urlFor(asset, preset = "lg") {
+    return getAssetUrl(asset, preset);
+  }
+  /** Build a responsive srcSet across the available image presets. */
+  srcSetFor(asset) {
+    return getAssetSrcSet(asset);
+  }
+  transform(asset, opts = {}, signOpts) {
+    if (!signOpts?.sign) {
+      return getTransformUrl(asset, opts) ?? 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."
+      );
+    }
+    return getSignedTransformUrl(asset, opts, this.opts.signingKey) ?? Promise.resolve(this.urlFor(asset, "lg"));
+  }
+  transformSrcSet(asset, widths, extraOpts = {}, signOpts) {
+    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) => {
+        const signed = await getSignedTransformUrl(
+          asset,
+          { ...extraOpts, width: w },
+          key
+        );
+        return signed ? `${signed} ${w}w` : null;
+      })
+    ).then((parts) => parts.filter((s) => 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, opts = {}) {
+    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, opts = {}) {
+    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, opts = {}) {
+    const sourceIsBlob = input instanceof File || input instanceof Blob;
+    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) \u2014 the asset will be stored as kind:"other" with NO image/video variants and regenerate() unsupported. Pass `contentType` or a `fileName` with an extension.'
+      );
+    }
+    let bytes;
+    let effectiveMime;
+    let clientOriginalBytes;
+    const wantCompression = !!opts.compress && sourceIsBlob && typeof window !== "undefined" && sourceMime.startsWith("image/");
+    if (wantCompression) {
+      const compressOpts = opts.compress === true ? {} : opts.compress;
+      const dynImport = new Function(
+        "base",
+        "return import(new URL('./' + 'web' + '.js', base).href)"
+      );
+      const { compressImage } = await dynImport(import.meta.url);
+      const result = await compressImage(input, 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 \u2014 uploading raw bytes."
+        );
+      } else if (opts.compress && typeof window === "undefined") {
+        console.warn(
+          "[@nitida/sdk] compress: true is browser-only \u2014 uploading raw bytes."
+        );
+      } else if (opts.compress && !sourceMime.startsWith("image/")) {
+      }
+      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`);
+    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))
+      };
+    }
+    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], { 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();
+    let assetId = proc.assetId;
+    if (!assetId && proc.kind === "video") {
+      const start = Date.now();
+      let delay = 1e3;
+      while (Date.now() - start < 6e4) {
+        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, 5e3);
+      }
+    }
+    if (!assetId) throw new Error("upload: process returned no assetId");
+    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))
+    };
+  }
+  defaultPresetForMime(mime) {
+    if (mime.startsWith("video/")) return "video";
+    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.
+   */
+  bestPresetForAsset(asset, mime) {
+    const order = mime.startsWith("video/") ? ["video", "poster"] : mime.startsWith("audio/") ? ["mp3", "original"] : ["lg", "md", "sm", "thumb", "xl", "original"];
+    return order.find((p) => hasPreset(asset, p)) ?? this.defaultPresetForMime(mime);
+  }
+};
+
+// src/server/index.ts
+var AquienpzClient2 = class extends AquienpzClient {
+  constructor(opts) {
+    super(opts);
+  }
+};
+export {
+  AquienpzClient2 as AquienpzClient,
+  computeVariantDimensions,
+  extractAssetSha,
+  getAssetDimensions,
+  getAssetSrcSet2 as getAssetSrcSet,
+  getAssetUrl2 as getAssetUrl,
+  getHlsStreamingUrl2 as getHlsStreamingUrl,
+  getSignedTransformUrl2 as getSignedTransformUrl,
+  getTenantId,
+  getTransformSrcSet2 as getTransformSrcSet,
+  getTransformUrl2 as getTransformUrl,
+  getVideoTransformUrl2 as getVideoTransformUrl,
+  hasPreset2 as hasPreset,
+  serializeTransform,
+  setTenantId2 as setTenantId,
+  signTransformUrl
+};
+//# sourceMappingURL=server.js.map