@nitida/sdk 0.23.0 → 0.24.1

package/AGENTS.md

@@ -3,7 +3,7 @@
 **Read `skills/nitida-sdk/SKILL.md` in this package first.** It is the canonical guide and it
 ships inside the tarball, so it is already on disk in `node_modules/@nitida/sdk/skills/`. It
 carries the things that cost real incidents to learn — the base36 tenant prefix, the width ladder,
-the `original`-preset trap, the R2 CORS boundary — not just the API shape.
+the `original`-preset trap, the object-storage CORS boundary — not just the API shape.
 
 **Then read `src/`.** This package publishes its TypeScript sources (`files: ["dist/**", "src/**"]`),
 so the source *is* the reference: every public method carries TSDoc, and the ones worth copying
@@ -13,12 +13,12 @@ recalling an API from training data — this SDK moves.
 ## The five-minute version
 
 ```ts
-import { AquienpzClient } from "@nitida/sdk/server";   // uploads: server-only, holds the amk_rt_* key
+import { NitidaClient } from "@nitida/sdk/server";   // uploads: server-only, holds the amk_rt_* key
 import { getTransformUrl, setCdnBase, setTenantId } from "@nitida/asset-client"; // URLs: anywhere
 ```
 
 - **Uploading** → `aq.upload(file, { fileName, contentType, presets })`. One call does compress →
-  sha256 → presign → direct-to-R2 PUT → `/assets/process` → wait-until-ready.
+  sha256 → presign → direct-to-storage PUT → `/assets/process` → wait-until-ready.
 - **Image URLs** → `getTransformUrl({ sha }, { format: "webp", width })`. The width MUST be on
   `TRANSFORM_WIDTHS` or the edge answers **400**.
 - **Video URLs** → `getAssetUrl({ sha }, "video")` after `setTenantId(id)`. The path segment is
@@ -30,14 +30,15 @@ import { getTransformUrl, setCdnBase, setTenantId } from "@nitida/asset-client";
    `["thumb"]` and the bytes you PUT are *not* retrievable. A variant not requested at the FIRST
    ingest cannot be added later once the cleanup job reaps `raw/`.
 2. **The `amk_rt_*` key is server-only.** The browser talks to *your* route; your server talks to
-   aquienpz. A runtime key in a client bundle is a write key to a paid platform.
-3. **The PUT goes browser → R2 directly, so R2 answers the CORS preflight.** An origin missing from
-   the bucket policy cannot be fixed in this SDK, in your app, or in `storefront_origins`. Symptom:
-   `R2 PUT failed: network error` with every earlier step green.
+   the platform. A runtime key in a client bundle is a write key to a paid platform.
+3. **The PUT goes browser → object storage directly, so the STORAGE BUCKET answers the CORS
+   preflight.** An origin missing from the bucket policy cannot be fixed in this SDK, in your app,
+   or by the API's allowed-origins setting — ask us to add it. Symptom: the direct PUT fails with a
+   bare network error while every earlier step is green.
 4. **Video is not image.** `/assets/process` filters video presets to
    `{poster, video, aiproxy, probe}` — `original` is silently dropped — and a video finalizes
-   ASYNCHRONOUSLY: the call answers `{ assetId, status: "processing" }` and a Cloud Run Job flips it
-   to `ready` 1–2 min later, so `processAndWait` needs a `timeoutMs` of at least `300_000`.
+   ASYNCHRONOUSLY: the call answers `{ assetId, status: "processing" }` and a background job flips
+   it to `ready` 1–2 min later, so `processAndWait` needs a `timeoutMs` of at least `300_000`.
 
 ## Related packages
 

package/README.md

@@ -721,11 +721,11 @@ const asset = await aq.assets.byHash(sha256);
 > `2400`). `height` stays `number` — for the responsive path it's derived from `width`
 > by aspect ratio; only fixed-canvas crops / `genfill` set it explicitly.
 
-`format=auto` resolves to **WebP** by default. The bench in `apps/asset-manager/bench/avif-vs-webp-summary.md`
-(100 random realtyone-cr `lg.webp` samples, sharp 0.34.5) showed AVIF was 4.5–9.8% **larger**
-than WebP in every source-size bracket with virtually identical SSIM. The policy lives
-in a single function (`pickAutoFormat` in `transform.format-policy.ts`) so re-evaluation
-when libavif improves is a one-file swap.
+`format=auto` resolves to **WebP** by default. Our bench over 100 random
+production `lg.webp` samples showed AVIF was 4.5–9.8% **larger** than WebP in every
+source-size bracket with virtually identical SSIM. The policy is re-evaluated as
+libavif improves, so `auto` may resolve differently in the future — that is the
+point of asking for `auto` instead of naming a format.
 
 `gravity=face` runs the source image through a ~1 MB Ultra-Light face
 detector (ultraface-RFB-320 via ONNX Runtime) and crops to the
@@ -746,12 +746,11 @@ instance boots.
 | normal (25–55) — most photos | 70 | 60 | 80 |
 | complex (≥ 55) — busy textures | 72 | 65 | 82 |
 
-Validated on 100 random realtyone-cr `lg.webp` samples: **+15.4 %
+Validated on 100 random production `lg.webp` samples: **+15.4 %
 bytes saved vs fixed `quality=80` baseline, |ΔSSIM| 0.0011** (budget
-0.005). See `bench/auto-quality-summary.md`. Both the bucket
-boundaries and per-format table live in
-`transform.quality-policy.ts` — re-tune by editing the constant and
-re-running `bun run apps/asset-manager/scripts/bench-auto-quality.ts`.
+0.005). The bucket boundaries and the per-format table are server-side
+policy and may be re-tuned; pass an explicit `quality=` when you need a
+number that does not move.
 
 ### Canonicalization & caching
 
@@ -844,19 +843,15 @@ const jpegUrl = aq.transform(asset, { format: "jpeg" });
 // → https://8ok.uk/t/format=jpeg/<sha>.jpg
 ```
 
-`effect=removebg` is provider-pluggable via the
-`BG_REMOVAL_BACKEND` env on the asset-manager:
+`effect=removebg` runs on one of two server-side matting backends, chosen
+per deployment. What the caller sees:
 
-- **`local`** (default) — U²-Net ONNX inference, Apache 2.0 weights
-  shipped under `/app/models/u2net.onnx` (~176 MB, fetched at
-  Docker build time, sha256-verified). ~1-2 s warm CPU inference,
-  ~5-7 s cold-start. Free runtime.
-- **`replicate`** — proxies to Replicate's `851-labs/background-remover`
-  (BRIA-quality, commercially licensed via Replicate). ~3-8 s GPU,
-  ~$0.001-0.005 per image. Requires `REPLICATE_API_TOKEN` in Secret
-  Manager.
+- **CPU matting** (default) — ~1-2 s warm, ~5-7 s cold. No per-image cost.
+- **GPU matting** — ~3-8 s, ~$0.001-0.005 per image, better edges on hair
+  and fine detail.
 
-In both cases the route caches the PNG in R2 under the standard
+Either way the contract is the same, and the first request is the only one
+that pays. In both cases the route caches the PNG in R2 under the standard
 `<sha>-t<dslHash>.png` key, so subsequent identical requests are 302
 redirects to the CDN — no inference, no per-image cost. **Always
 forces `format=png`** because the entire point is preserving alpha.
@@ -865,12 +860,9 @@ The output is the same dimensions as the source. Chain with `width`
 to resize the cutout in a single request (cached as one R2 entry per
 canonical DSL).
 
-To re-tune or swap the model:
-1. Drop a new `.onnx` into `apps/asset-manager/src/features/assets/bg/`
-2. Update `MODEL_PATH` + preprocessing constants in `bg/remove.ts`
-3. Update the Dockerfile's `COPY src/features/assets/bg/*.onnx /app/models/`
-4. Re-bench against a sample set (a CSV in `apps/asset-manager/bench/`
-   makes sense once the comparison is non-trivial).
+The matting model is server-side and may be swapped for a better one
+without any change on your side — the URL, the PNG-with-alpha output and
+the cache semantics are the contract.
 
 ### Generative fill / aspect outpaint (`effect=genfill`)
 
@@ -923,9 +915,8 @@ Powered by Replicate's `black-forest-labs/flux-fill-pro`. ~$0.05 per
 first request per (sha, dsl, format) tuple; subsequent identical
 requests are 302 redirects to the R2 cache — zero Replicate cost.
 
-Requires `REPLICATE_API_TOKEN` in the asset-manager's Secret Manager
-secrets. Same token as `BG_REMOVAL_BACKEND=replicate`; no separate
-provisioning needed.
+Server-side credentials for the generative provider are part of the
+deployment; nothing to provision on your side.
 
 **Short-circuit**: when the source already matches the target aspect
 exactly (resized to fill the canvas with zero padding), the server
@@ -1141,8 +1132,8 @@ const usage = await aq.usage.snapshot();
 // {
 //   tenant: { id: 4, code: "realtyone-cr" },
 //   storage: { totalBytes: 4_810_000_000, assetCount: 15_760 },
-//   today: { reads: 3201, writes: 18, processes: 6, bytesIn: 12_400_000, ... },
-//   last30Days: { reads: 86_400, writes: 412, ... }
+//   today: { reads: 3201, writes: 18, processes: 6, videoMinutes: 4.5, ... },
+//   last30Days: { reads: 86_400, writes: 412, videoMinutes: 312.75, ... }
 // }
 
 const chart = await aq.usage.timeseries(30); // for a 30-day line chart
@@ -1151,7 +1142,24 @@ const byKey = await aq.usage.keys();         // who's using the most quota
 
 Backed by the daily rollup of `assets.api_key_usage` →
 `assets.tenant_usage_daily`. The "today" window queries the raw
-`api_key_usage` table since the rollup runs once per day at ~00:30 UTC.
+`api_key_usage` table since the rollup runs once per day at ~00:30 UTC —
+except `videoMinutes`, which is accumulated live and so is real-time on
+every window.
+
+**`videoMinutes` counts minutes actually TRANSCODED, not videos stored.**
+It is *source minutes × encode passes*, so a 7-rung HLS ladder over a
+2-minute clip books 14. Re-encoding a video you already uploaded counts
+**again** — that is the point: the asset row is upserted on `sha256`, so
+nothing else in the system can see a re-encode. A passthrough stream copy
+or a cache hit runs no encoder and books nothing, so `0` means zero.
+
+> ⚠️ **Removed 2026-08-17:** `bytesIn` (on the usage windows and daily
+> points) and `bytesTotal` (on the per-key rows). They were fed by
+> `api_key_usage.bytes`, which is structurally zero — measured at 440,820
+> rows, none above 0 — and could not be instrumented, because uploads go to
+> R2 through presigned URLs and never traverse the API. A field that always
+> reads `0` is worse than an absent one. The byte figure that is true,
+> `storage.totalBytes`, is unchanged.
 
 ## License
 

package/dist/index.d.ts

@@ -52,7 +52,7 @@ export { AssetDTO, AssetVariant, ResolveSlotOptions, SignedTransformOptions, Slo
  */
 type NitidaClientOptions = {
     /**
-     * Base URL of the aquienpz asset-manager (Cloud Run service URL).
+     * Base URL of the nitida API (e.g. `https://api.nitida.gofuture.space`).
      *
      * May be relative (e.g. `/api/am`) ONLY in browser contexts where the
      * SDK resolves it against `window.location.origin`. Node/Bun consumers
@@ -150,8 +150,8 @@ declare class SlotsApi {
 /**
  * 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).
+ * return a dispatch handle (the actual transcode runs in a background
+ * job and finishes async).
  */
 type RegenerateResult = {
     ok: true;
@@ -182,7 +182,7 @@ type RegenerateResult = {
 /**
  * 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
+ * asset DTO) or it returns a presigned storage PUT URL plus a `process` payload
  * the caller must POST to `/assets/process` after the PUT lands.
  */
 type UploadUrlResult = {
@@ -208,7 +208,7 @@ 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
+     * streamed (e.g. share-video reels) — it avoids a second background job no
      * one watches. Default/absent → the ladder is generated as before.
      */
     hls?: boolean;
@@ -224,7 +224,7 @@ type UploadVideoOptions = {
 };
 /** Input shape accepted by `aq.assets.presignUploadUrl(...)`. */
 type PresignUploadUrlOptions = {
-    /** Full sha256 (64 hex) of the bytes that will be PUT to R2. */
+    /** Full sha256 (64 hex) of the bytes that will be PUT to storage. */
     sha256: string;
     /** MIME type of the bytes (e.g. `image/jpeg`, `video/mp4`). */
     mime: string;
@@ -318,7 +318,7 @@ declare class AssetsApi {
      *   const v = await aq.assets.variants(logoId);
      *   v.map((x) => x.preset);  // → ("thumb" | "sm" | … | "original")[]
      *
-     * ⚠️ Returns `[]` — not an error — against an `asset-manager` older than the
+     * ⚠️ Returns `[]` — not an error — against a server deploy older than the
      * 2026-08-17 deploy, which never sent the field (doc 240 §4.3). An empty
      * array is therefore "no variants OR old server". For a plain existence
      * check prefer `hasPreset(dto, preset)` on `dto.presets`, which every server
@@ -347,7 +347,7 @@ declare class AssetsApi {
      * 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
+     * dispatched to the background job (the call returns immediately
      * with a dispatch handle; poll `aq.assets.get(id).status` for
      * completion).
      */
@@ -360,13 +360,13 @@ declare class AssetsApi {
         metadata: Record<string, unknown>;
     }>;
     /**
-     * Request a presigned R2 PUT URL for direct browser-side uploads.
+     * Request a presigned storage 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.
+     * uploads bytes straight to object storage with the returned `upload.url`,
+     * then POSTs `process.body` to `/assets/process` (see {@link processAndWait})
+     * once storage has the bytes.
      *
      * If the sha is already known to the tenant the server short-circuits
      * with `{ deduped: true, asset }` — no PUT needed.
@@ -378,16 +378,16 @@ declare class AssetsApi {
      * 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`.
+     * // ⚠️ The STORAGE BUCKET answers that preflight itself, so your origin must be in its 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 by the API's allowed 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
+     * `{ assetId, status: "processing" }` while a background job transcodes, so
      * give `processAndWait` a bigger `timeoutMs` (a transcode + HLS ladder runs
      * 1–2 min; 300_000 is a sane floor).
      */
@@ -397,7 +397,7 @@ declare class AssetsApi {
      * {@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 —
+     * Use this when bytes were uploaded directly from the browser to storage —
      * `aq.upload()` already does presign + PUT + process + wait in one
      * step when the server holds the bytes.
      */
@@ -420,7 +420,7 @@ declare class AssetsApi {
      * {@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
+     * to the request body so the background job can resolve it without
      * re-reading the header.
      */
     composeMarketing(opts: ComposeMarketingOptions): Promise<ComposeMarketingResult>;
@@ -451,7 +451,7 @@ type UploadOptions = {
      * 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"` —
+     * `application/octet-stream`, which the server 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`.
@@ -567,8 +567,35 @@ type UsageWindow = {
     admins: number;
     upscales: number;
     processes: number;
-    bytesIn: number;
+    /**
+     * Minutes of video actually TRANSCODED in the window — source minutes ×
+     * encode passes, so a 7-rung HLS ladder over a 2-minute clip books 14.
+     *
+     * A re-encode of a video already ingested counts AGAIN. That is the point:
+     * `assets.assets` cannot report it, because its insert is
+     * `ON CONFLICT DO UPDATE` and a re-encode creates no row there.
+     *
+     * A stream copy (`-c copy` passthrough, an idempotent cache skip) books
+     * nothing, so a tenant that ran no encoder reads `0` — and that `0` is real.
+     */
+    videoMinutes: number;
+    /** Encode passes behind `videoMinutes`. 0 when nothing was encoded. */
+    videoEncodes: number;
 };
+/**
+ * ⚠️ REMOVED 2026-08-17: `bytesIn` on `UsageWindow`/`UsageDailyPoint` and
+ * `bytesTotal` on `UsagePerKey`.
+ *
+ * All three were structurally zero: the field behind them was never populated,
+ * on any row. They could not be instrumented in place either — uploads go to
+ * object storage through presigned URLs, so the payload never passes through
+ * the API, and the only figure measurable there is a JSON envelope of a few
+ * hundred bytes.
+ *
+ * A field that always reads `0` is worse than an absent field, because absent
+ * is honest — a `0` next to a real `storage.totalBytes` reads as a measurement.
+ * The byte number that IS true is still served: `storage.totalBytes`.
+ */
 type UsageDailyPoint = {
     date: string;
     reads: number;
@@ -576,15 +603,16 @@ type UsageDailyPoint = {
     lists: number;
     deletes: number;
     processes: number;
-    bytesIn: number;
     bytesStored: number;
+    /** See `UsageWindow.videoMinutes`. Minutes transcoded on this day. */
+    videoMinutes: number;
+    videoEncodes: number;
 };
 type UsagePerKey = {
     apiKeyId: string;
     prefix: string | null;
     name: string | null;
     opsTotal: number;
-    bytesTotal: number;
     lastSeen: string;
 };
 declare class UsageApi {
@@ -644,7 +672,7 @@ declare class NitidaClient {
      * 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
+     * URLs with the same params in different order produce the same
      * cache entry (the server canonicalizes both sides). Safe to use as
      * stable cache keys.
      *
@@ -675,8 +703,8 @@ declare class NitidaClient {
      * 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
+     * or `.webm` extension and the server routes the request to a
+     * background job for video encoding (vs the inline pipeline for
      * images).
      *
      * On the first request the route returns **202 Accepted** with
@@ -716,7 +744,7 @@ declare class NitidaClient {
      *   />
      *
      * On the first request the server returns **202 Accepted** while a
-     * Cloud Run Job builds the multi-rung ladder (typically 1-3 min for
+     * background 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.
      *
@@ -735,7 +763,7 @@ declare class NitidaClient {
      * but isn't always available depending on the runtime).
      */
     /**
-     * Upload bytes end to end: optional client compression → sha256 → presign → **direct-to-R2 PUT**
+     * Upload bytes end to end: optional client compression → sha256 → presign → **direct-to-storage PUT**
      * → `/assets/process` → wait until the asset is ready.
      *
      * ⚠️ `presets` decides what exists FOREVER. Omit it and only `original` is written; ask for
@@ -775,8 +803,8 @@ declare class NitidaClient {
      * // {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.
+     * // Omit `aiproxy`/`probe` unless the asset really goes to a vision model — they cost encode
+     * // time and permanent stored objects that nothing else reads.
      * ```
      */
     upload(input: File | Blob | Uint8Array, opts?: UploadOptions): Promise<UploadResult>;

package/dist/index.js

@@ -223,7 +223,7 @@ var AssetsApi = class {
    *   const v = await aq.assets.variants(logoId);
    *   v.map((x) => x.preset);  // → ("thumb" | "sm" | … | "original")[]
    *
-   * ⚠️ Returns `[]` — not an error — against an `asset-manager` older than the
+   * ⚠️ Returns `[]` — not an error — against a server deploy older than the
    * 2026-08-17 deploy, which never sent the field (doc 240 §4.3). An empty
    * array is therefore "no variants OR old server". For a plain existence
    * check prefer `hasPreset(dto, preset)` on `dto.presets`, which every server
@@ -255,7 +255,7 @@ var AssetsApi = class {
    * 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
+   * dispatched to the background job (the call returns immediately
    * with a dispatch handle; poll `aq.assets.get(id).status` for
    * completion).
    */
@@ -283,13 +283,13 @@ var AssetsApi = class {
     return await r.json();
   }
   /**
-   * Request a presigned R2 PUT URL for direct browser-side uploads.
+   * Request a presigned storage 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.
+   * uploads bytes straight to object storage with the returned `upload.url`,
+   * then POSTs `process.body` to `/assets/process` (see {@link processAndWait})
+   * once storage has the bytes.
    *
    * If the sha is already known to the tenant the server short-circuits
    * with `{ deduped: true, asset }` — no PUT needed.
@@ -301,16 +301,16 @@ var AssetsApi = class {
    * 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`.
+   * // ⚠️ The STORAGE BUCKET answers that preflight itself, so your origin must be in its 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 by the API's allowed 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
+   * `{ assetId, status: "processing" }` while a background job transcodes, so
    * give `processAndWait` a bigger `timeoutMs` (a transcode + HLS ladder runs
    * 1–2 min; 300_000 is a sane floor).
    */
@@ -338,7 +338,7 @@ var AssetsApi = class {
    * {@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 —
+   * Use this when bytes were uploaded directly from the browser to storage —
    * `aq.upload()` already does presign + PUT + process + wait in one
    * step when the server holds the bytes.
    */
@@ -387,7 +387,7 @@ var AssetsApi = class {
    * {@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
+   * to the request body so the background job can resolve it without
    * re-reading the header.
    */
   async composeMarketing(opts) {
@@ -553,8 +553,8 @@ var NitidaClient = class {
    * 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
+   * or `.webm` extension and the server routes the request to a
+   * background job for video encoding (vs the inline pipeline for
    * images).
    *
    * On the first request the route returns **202 Accepted** with
@@ -596,7 +596,7 @@ var NitidaClient = class {
    *   />
    *
    * On the first request the server returns **202 Accepted** while a
-   * Cloud Run Job builds the multi-rung ladder (typically 1-3 min for
+   * background 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.
    *
@@ -617,7 +617,7 @@ var NitidaClient = class {
    * but isn't always available depending on the runtime).
    */
   /**
-   * Upload bytes end to end: optional client compression → sha256 → presign → **direct-to-R2 PUT**
+   * Upload bytes end to end: optional client compression → sha256 → presign → **direct-to-storage PUT**
    * → `/assets/process` → wait until the asset is ready.
    *
    * ⚠️ `presets` decides what exists FOREVER. Omit it and only `original` is written; ask for
@@ -657,8 +657,8 @@ var NitidaClient = class {
    * // {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.
+   * // Omit `aiproxy`/`probe` unless the asset really goes to a vision model — they cost encode
+   * // time and permanent stored objects that nothing else reads.
    * ```
    */
   async upload(input, opts = {}) {
@@ -731,7 +731,7 @@ var NitidaClient = class {
       body: new Blob([bytes], { type: mime })
     });
     if (!putR.ok)
-      throw new Error(`R2 PUT ${putR.status}: ${await putR.text()}`);
+      throw new Error(`Storage PUT ${putR.status}: ${await putR.text()}`);
     const procR = await fetch(endpointHref(this.opts, presign.process.url), {
       method: "POST",
       headers: {