@nitida/sdk 0.23.0 → 0.24.1

package/src/index.ts

@@ -78,7 +78,7 @@ import {
  */
 export 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
@@ -348,8 +348,8 @@ 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).
  */
 export type RegenerateResult =
   | {
@@ -383,7 +383,7 @@ export 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.
  */
 export type UploadUrlResult =
@@ -403,7 +403,7 @@ 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
+   * 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;
@@ -420,7 +420,7 @@ export type UploadVideoOptions = {
 
 /** Input shape accepted by `aq.assets.presignUploadUrl(...)`. */
 export 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;
@@ -571,7 +571,7 @@ 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
@@ -606,7 +606,7 @@ 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).
    */
@@ -642,13 +642,13 @@ class AssetsApi {
   }
 
   /**
-   * 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.
@@ -660,16 +660,16 @@ 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).
    */
@@ -701,7 +701,7 @@ 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.
    */
@@ -755,7 +755,7 @@ 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.
    */
   async composeMarketing(
@@ -858,7 +858,7 @@ export 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`.
@@ -1002,9 +1002,37 @@ export 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`.
+ */
+
 export type UsageDailyPoint = {
   date: string;
   reads: number;
@@ -1012,8 +1040,10 @@ export type UsageDailyPoint = {
   lists: number;
   deletes: number;
   processes: number;
-  bytesIn: number;
   bytesStored: number;
+  /** See `UsageWindow.videoMinutes`. Minutes transcoded on this day. */
+  videoMinutes: number;
+  videoEncodes: number;
 };
 
 export type UsagePerKey = {
@@ -1021,7 +1051,6 @@ export type UsagePerKey = {
   prefix: string | null;
   name: string | null;
   opsTotal: number;
-  bytesTotal: number;
   lastSeen: string;
 };
 
@@ -1136,7 +1165,7 @@ export 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.
    *
@@ -1236,8 +1265,8 @@ export 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
@@ -1283,7 +1312,7 @@ export 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.
    *
@@ -1308,7 +1337,7 @@ export 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
@@ -1348,8 +1377,8 @@ export 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.
    * ```
    */
   async upload(
@@ -1360,7 +1389,7 @@ export class NitidaClient {
     //    "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
+    // the file extension, before octet-stream (which the server files as
     // `kind:"other"` — no variants). A File/Blob's own `.type` always wins when present.
     const sourceMime =
       (sourceIsBlob ? input.type : "") ||
@@ -1494,7 +1523,7 @@ export class NitidaClient {
       body: new Blob([bytes as unknown as ArrayBuffer], { 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",