@hunt-labs/bytekit-sdk 0.9.2 → 0.10.0

package/dist/generated/api.d.ts

@@ -194,7 +194,17 @@ export interface paths {
         put?: never;
         /**
          * Scrape a URL
-         * @description Fetches and processes a URL, returning content in one or more formats wrapped in a ScrapeEnvelope. Most requests return synchronously in under a second; requests needing a full page render return HTTP 202 and complete asynchronously.
+         * @description Fetches and processes a URL, returning content in one or more formats wrapped in a ScrapeEnvelope.
+         *
+         *     **The response shape is decided by your request, not by how we route it.** In precedence order:
+         *
+         *     1. `async: true` → **202** with a `ScrapeQueuedEnvelope` receipt, returned immediately. Poll `GET /v1/scrape/{id}` for the result.
+         *     2. Otherwise, a request that needs a full page render — today that is `delay_ms > 0` — is **held open** until the render reaches a terminal state, then returns **200** with the content envelope (`success` or `failed`). If the render is still running when the hold window expires (28 seconds by default), the request returns the **202** receipt instead and the job continues in the background.
+         *     3. Otherwise the request is served by the fast HTTP path and returns **200** with the content envelope, typically in under a second.
+         *
+         *     **A failed fetch is a result, not a transport error.** An unreachable host, a refused connection, or a target whose bot protection defeats every proxy tier all come back on the same **200** as a `failed` envelope — never a 5xx. Narrow on the envelope's `status` before reading the body. A failure the fast path decides inline happens before any job row exists, so its envelope carries `id: null` and there is nothing to poll; a failure a held render reaches carries that render's real `id`. Either way the request transfers no billable bytes and is charged nothing.
+         *
+         *     So a 202 means one of exactly two things: you asked for one with `async: true`, or the hold window expired. `wait_for_selector` and `wait_until` are `ScreenshotRequest` options, not `ScrapeRequest` options — sending either to this endpoint returns `422 validation_error`, so neither can produce a 202 here.
          */
         post: operations["createScrape"];
         delete?: never;
@@ -235,9 +245,10 @@ export interface paths {
         /**
          * Bulk scrape URLs
          * @description Enqueues multiple URLs for scraping. Results delivered via webhook.
-         *     Webhook deliveries include `X-ByteKit-Event: scrape.completed` or
-         *     `X-ByteKit-Event: scrape.failed` so receivers can dispatch on the
-         *     header without parsing the body shape.
+         *     Completion deliveries use `X-ByteKit-Event: bulk.completed` and the
+         *     `BulkCompletedWebhook` contract: at most 500 complete items and 1 MiB,
+         *     followed by cursor recovery through `GET /v1/scrape/bulk/{id}` whenever
+         *     `recovery_required` is true.
          */
         post: operations["createScrapeBulk"];
         delete?: never;
@@ -253,7 +264,20 @@ export interface paths {
             path?: never;
             cookie?: never;
         };
-        /** Get scrape bulk job status */
+        /**
+         * Get scrape bulk job status
+         * @description Returns the job envelope plus its rehydrated per-URL scrape envelopes.
+         *
+         *     **Downloading item content.** A `raw` or `markdown` artifact within the
+         *     10-MiB inline cap is returned inline. An oversized one is replaced by a
+         *     **pre-signed** URL, minted fresh on every read of this endpoint and valid
+         *     for **86400 seconds (24 hours)**. The underlying objects are private, so an
+         *     unsigned URL returns `401`: download the content inside that window, or
+         *     re-poll this endpoint for a fresh signature. An artifact that was never
+         *     stored, or whose object cannot be signed, is omitted from `formats` and
+         *     reported as `artifact_unavailable` in `warnings`. The private unsigned
+         *     storage URL is never returned.
+         */
         get: operations["getScrapeBulk"];
         put?: never;
         post?: never;
@@ -305,6 +329,10 @@ export interface paths {
          * Bulk fetch URLs
          * @description Enqueues multiple URLs for HTTP fetching. Results delivered via webhook.
          *     Does not support options that require page rendering (wait_for_selector, etc.).
+         *     Completion deliveries use `X-ByteKit-Event: bulk.completed` and the
+         *     `BulkCompletedWebhook` contract: at most 500 complete items and 1 MiB,
+         *     followed by cursor recovery through `GET /v1/fetch/bulk/{id}` whenever
+         *     `recovery_required` is true.
          *
          *     **Limits:** request bodies are guarded in a two-tier shape. A streamed body
          *     with no `Content-Length` header is capped at 2 MB before your API key
@@ -342,7 +370,9 @@ export interface paths {
          *     objects are private, so an unsigned URL returns `401`: download the
          *     content inside that window, or re-poll this endpoint for a fresh
          *     signature. Items that are not `completed`, and completed items with no
-         *     stored object, carry `null` or the unsigned stored URL instead.
+         *     stored object, or completed items whose object cannot be signed, carry
+         *     `null`; the latter report `artifact_unavailable`. The private unsigned
+         *     storage URL is never returned.
          */
         get: operations["getFetchBulk"];
         put?: never;
@@ -373,6 +403,9 @@ export interface paths {
          *     Provide `urls` (simple list) or `items` (per-item config), not both.
          *     Webhook deliveries include `X-ByteKit-Event: bulk.completed` so
          *     receivers can dispatch on the header without parsing the body shape.
+         *     The body follows `BulkCompletedWebhook`: at most 500 complete items and
+         *     1 MiB, followed by cursor recovery through the existing mixed-item route
+         *     whenever `recovery_required` is true.
          *
          *     **Limits:** request bodies are guarded in a two-tier shape. A streamed body
          *     with no `Content-Length` header is capped at 4 MB before your API key
@@ -424,15 +457,25 @@ export interface paths {
          * List bulk job items
          * @description Returns the bulk job's items, discriminated by `type`.
          *
-         *     **Downloading item artifacts.** `image_url` (`type: screenshot`) and both
-         *     `content_url` and `markdown_url` (`type: scrape`) are **pre-signed** URLs,
-         *     minted fresh on every read of this endpoint and valid for **600 seconds
-         *     (10 minutes)** —
+         *     **Downloading item artifacts.** For a `completed` item with a storage key,
+         *     `image_url` (`type: screenshot`) and both `content_url` and `markdown_url`
+         *     (`type: scrape`) are **pre-signed** URLs, minted fresh on every read of
+         *     this endpoint and valid for **600 seconds (10 minutes)** —
          *     the same signing lifetime as `content_url` on `GET /v1/fetch/bulk/{id}`.
-         *     The underlying objects are private, so an unsigned URL returns `401`:
-         *     download inside that window, or re-poll this endpoint for a fresh
-         *     signature. Items that are not `completed`, and completed items with no
-         *     stored object, carry `null` or the unsigned stored URL instead.
+         *     Download inside that window, or re-poll this endpoint for a fresh
+         *     signature.
+         *
+         *     **When no signature is minted.** Three cases mint none: an item that is not
+         *     `completed`, a `completed` item with no storage key, and a `completed` item
+         *     whose object could not be signed — during an object-storage outage, for
+         *     instance. In all three the item's stored value is returned unchanged: `null`
+         *     while nothing has been stored, and otherwise a **private, unsigned**
+         *     object-storage URL that answers `401`. These fields are neither nulled nor
+         *     flagged in that case, so treat an artifact URL as usable only once you have
+         *     downloaded it, and re-poll for a fresh signature otherwise.
+         *     `artifact_warnings` and its `artifact_unavailable` code describe the sibling
+         *     `artifacts` object on `type: scrape` items only — they say nothing about
+         *     `image_url`, `content_url`, or `markdown_url`.
          */
         get: operations["listBulkScreenshots"];
         put?: never;
@@ -816,11 +859,19 @@ export interface paths {
             path?: never;
             cookie?: never;
         };
-        get?: never;
+        /**
+         * Read a scheduled plan change
+         * @description The plan change booked for the end of the current period, if any, reconstructed from the Stripe subscription schedule on each call. Both fields are null when nothing is booked, including while the schedule stays attached for one further interval after a change has already landed.
+         */
+        get: operations["getPlanChange"];
         put?: never;
         /** Change subscription plan */
         post: operations["changePlan"];
-        delete?: never;
+        /**
+         * Revoke a scheduled plan change
+         * @description Cancels a plan change booked for the end of the current period. The subscription simply renews on the plan it is already on.
+         */
+        delete: operations["revokePlanChange"];
         options?: never;
         head?: never;
         patch?: never;
@@ -874,7 +925,8 @@ export interface paths {
         /**
          * Configure auto-topup
          * @description Enable or disable automatic bandwidth top-ups. When enabling,
-         *     threshold_bytes, amount_bytes, and monthly_cap_cents are all required.
+         *     threshold_bytes, amount_bytes, and monthly_cap_cents must all be present;
+         *     monthly_cap_cents may be null, which means no monthly cap.
          */
         put: operations["updateAutoTopup"];
         post?: never;
@@ -1343,13 +1395,13 @@ export interface components {
             name: string;
             /**
              * @description Monthly subscription price in cents.
-             * @example 49900
+             * @example 34900
              */
             price_cents: number;
             /**
              * Format: int64
-             * @description Included bandwidth per period, in bytes (binary GiB).
-             * @example 100000000000
+             * @description Included bandwidth per period, in bytes (decimal GB = 1,000,000,000 bytes).
+             * @example 125000000000
              */
             included_bytes: number;
             /**
@@ -1359,7 +1411,7 @@ export interface components {
             included_credits: number;
             /**
              * @description Bandwidth top-up price per MB, in cents.
-             * @example 0.25
+             * @example 0.2
              */
             topup_price_per_mb_cents: number;
             /**
@@ -1405,6 +1457,95 @@ export interface components {
                 details?: unknown;
             };
         };
+        /**
+         * @description Item-local terminal artifact failure. The item's stable id remains usable for paginated recovery, but the requested stored content or signed reference could not be produced. Wherever this code is raised the URL field it describes is `null`; a private object-storage URL is never returned as a substitute for it. Endpoints that do not raise this code document their own fallback — see `image_url` on `GET /v1/bulk/{id}/screenshots`.
+         *
+         *     REFERENCE DOCUMENTATION ONLY (#4340). No operation `$ref`s this schema and no response ever carries an object of this shape, so no client model is generated from it and no SDK re-exports it. On the wire the value appears as the FLAT `error_code` / `error_message` fields on a bulk list item — `GET /v1/fetch/bulk/{id}`, `GET /v1/bulk/{id}/screenshots` — and on the `items[]` entries of the `bulk.completed` webhook body, never as a nested `{ code, message }` object. This schema names the `artifact_unavailable` code and the contract that goes with it; the two properties below describe that code and message, not a wire envelope.
+         */
+        BulkArtifactUnavailableError: {
+            /** @enum {string} */
+            code: "artifact_unavailable";
+            message: string;
+        };
+        /** @description Mandatory bounded scrape record emitted when the ordinary rehydrated envelope cannot fit within the 16-MiB page bound. The stable item identity and terminal outcome always remain available; bounded signed references and failure detail are included when they fit. */
+        BulkMandatoryScrapeItem: {
+            id: string;
+            /** @enum {string} */
+            type: "scrape";
+            /** @enum {string} */
+            terminal_outcome: "pending" | "processing" | "completed" | "failed" | "cancelled";
+            /** Format: uri */
+            url: string;
+            /** @description Bounded signed references retained from the ordinary scrape envelope. Only the formats the job requested are present; the key set is the `/v1/scrape` format vocabulary. */
+            formats?: {
+                raw?: string | null;
+                markdown?: string | null;
+                links?: null | (string | components["schemas"]["ScrapeScoredLink"])[];
+                images?: null | (string | components["schemas"]["ScrapeScoredImage"])[];
+            };
+            error?: {
+                code: string;
+                message: string | null;
+                /** Format: date-time */
+                failed_at: string | null;
+            };
+        };
+        /** @description Whole-job counters. These do not reset or shrink with the current page. */
+        BulkJobCounters: {
+            total: number;
+            completed: number;
+            failed: number;
+        };
+        /**
+         * @description Customer body for `X-ByteKit-Event: bulk.completed`. Delivery is bounded to
+         *     500 complete items and 1 MiB of customer-visible JSON, stopping only between
+         *     items. When either item coverage or artifact coverage is incomplete, follow
+         *     `recovery_url` with cursor pagination; stable `bulk_id` plus each item `id`
+         *     supports idempotent processing after duplicate, delayed, or retried delivery.
+         */
+        BulkCompletedWebhook: {
+            bulk_id: string;
+            /** @enum {string} */
+            status: "completed";
+            total: number;
+            completed: number;
+            failed: number;
+            total_credits_charged: number;
+            /** Format: uri */
+            webhook_url: string;
+            /** @description Complete item records included before the 500-item or 1-MiB manifest bound. Every record carries a stable `id`, a `type`, and a terminal `status`. */
+            items: ({
+                /** @description Stable prefixed item id; deduplicate with `bulk_id` plus this id. */
+                id: string;
+                /** @enum {string} */
+                type: "fetch" | "scrape" | "screenshot" | "recording";
+                /** @enum {string} */
+                status: "success" | "completed" | "failed" | "cancelled";
+                /** @description May be `artifact_unavailable` when no usable result reference exists. */
+                error_code?: string | null;
+                error_message?: string | null;
+                /** @description Present and true when the manifest bounded a long error message. */
+                error_message_truncated?: boolean;
+            } & {
+                [key: string]: unknown;
+            })[];
+            /** @enum {string} */
+            recovery_api: "fetch" | "scrape" | "mixed";
+            /**
+             * @description Existing paginated result-recovery path for this job.
+             * @example /v1/fetch/bulk/bulk_01j9abc123
+             */
+            recovery_url: string;
+            manifest_item_count: number;
+            /** @description True when every terminal job item is present in this webhook body. */
+            manifest_items_complete: boolean;
+            /** @description True when every included completed item has a usable artifact or reference. */
+            manifest_artifacts_complete: boolean;
+            /** @description True only when both item and artifact coverage are complete. */
+            manifest_complete: boolean;
+            /** @description Inverse of `manifest_complete`; follow `recovery_url` when true. */
+            recovery_required: boolean;
+        };
         Viewport: {
             width: number;
             height: number;
@@ -1527,11 +1668,17 @@ export interface components {
             formats: ("raw" | "markdown" | "links" | "images")[];
             /** @default US */
             country: string;
-            /** @default 0 */
+            /**
+             * @description Milliseconds to wait after page load before capturing, for content that renders late. Any value above 0 puts the request on the full browser render path. Unless `async: true` is also set, the request is then HELD until the render finishes and returns 200 with the content envelope, or returns the 202 receipt if the hold window expires first. `0` (the default) keeps the request on the fast HTTP path, which returns 200 in one round trip.
+             * @default 0
+             */
             delay_ms: number;
             /** @default 30000 */
             timeout_ms: number;
-            /** @default false */
+            /**
+             * @description When true, the request returns 202 with a `ScrapeQueuedEnvelope` receipt immediately and the scrape runs in the background; poll `GET /v1/scrape/{id}` for the result. This is the only way to ASK for a receipt, and it outranks every routing consequence: with `async: false` (the default) a browser-path request is held to completion instead of being receipted. A 202 can still arrive with `async: false`, but only when the hold window expires.
+             * @default false
+             */
             async: boolean;
             /**
              * Format: uri
@@ -1821,17 +1968,19 @@ export interface components {
              *     from a prior cache entry (billed at 0.5×). `miss` — no reusable entry was
              *     found, so the result was freshly fetched. `bypass` — `cache_ttl: '0'`
              *     skipped the read. Cache-eligible fresh results are written through;
-             *     safety-classified WAF husks remain live-only. Present on the async success
-             *     envelope (synchronous and webhook delivery); omitted by paths with no cache
-             *     verdict (e.g. bulk results).
+             *     safety-classified WAF husks remain live-only. Present on the synchronous
+             *     response, on webhook delivery, and on `GET /v1/scrape/{id}` for a row whose
+             *     terminal write recorded a disposition; omitted by paths with no cache verdict
+             *     (e.g. bulk results) and for a stored row that recorded none, where absent
+             *     means unknown rather than `miss`.
              * @enum {string}
              */
             cache?: "miss" | "hit" | "bypass";
-            /** @description Age in whole seconds of the cache entry replayed on a `hit`. Clamped to ≥ 0 to absorb clock skew. Present only on `cache: hit`. */
+            /** @description Age in whole seconds of the cache entry replayed on a `hit`. Clamped to ≥ 0 to absorb clock skew. Present only on `cache: hit`. `GET /v1/scrape/{id}` reports `cache: hit` without this field: the age is a property of the replay that happened at completion time, is not persisted on the row, and cannot be derived honestly afterwards. */
             cache_age_s?: number;
         };
         /**
-         * @description Terminal asynchronous scrape failures are delivered to subscribers of `failed` as this payload with `X-ByteKit-Event: scrape.failed`.
+         * @description The canonical terminal failure payload. It is returned inline on a `POST /v1/scrape` that fails upstream (HTTP 200, `id: null`), by `GET /v1/scrape/{id}` once a queued job has failed, and delivered to subscribers of `failed` with `X-ByteKit-Event: scrape.failed`.
          * @example {
          *       "schema_version": 1,
          *       "status": "failed",
@@ -1872,7 +2021,7 @@ export interface components {
          *       "status": "queued",
          *       "id": "sc_01j9abc123",
          *       "url": "https://example.com",
-         *       "status_url": "https://api.bytekit.com/v1/scrape/sc_01j9abc123",
+         *       "status_url": "/v1/scrape/sc_01j9abc123",
          *       "queued_at": "2025-01-15T12:00:00Z",
          *       "events": []
          *     }
@@ -1892,7 +2041,7 @@ export interface components {
             id: string;
             /** Format: uri */
             url: string;
-            /** Format: uri */
+            /** @description Root-relative path to poll for this job's terminal envelope — not an absolute URI. Join it onto the base URL of the server you called (see `servers`; they carry no trailing slash) to get the pollable URL, e.g. `https://api.bytekit.com` + `/v1/scrape/sc_01j9abc123`. */
             status_url: string;
             /** Format: date-time */
             queued_at: string;
@@ -2158,7 +2307,7 @@ export interface components {
             options?: {
                 [key: string]: unknown;
             };
-            /** @description Scrape monitor options (formats, country, headers, etc.). Only for type=scrape. */
+            /** @description Scrape monitor options (formats, country, wait_for_selector, wait_until, delay_ms). Only for type=scrape. */
             scrape_options?: {
                 [key: string]: unknown;
             };
@@ -2227,7 +2376,7 @@ export interface components {
             consecutive_failures: number;
             /** @description Error code from the most recent failed capture, if any. */
             last_error_code: string | null;
-            /** @description Reason the monitor was auto-suspended (e.g. "auto_suspended_consecutive_failures"), if applicable. */
+            /** @description Reason the monitor was auto-suspended, if applicable. `insufficient_balance` means the account ran out of spendable balance; `auto_suspended_consecutive_failures` means the monitor failed too many times in a row. Either way the monitor stops capturing until it is reactivated by sending `status: "active"` to `PATCH /v1/monitors/{id}`. */
             suspension_reason: string | null;
             metadata: Record<string, never> | null;
             /** Format: date-time */
@@ -2536,7 +2685,7 @@ export interface components {
             /** Format: date-time */
             created_at: string;
         };
-        /** @description Minimal account shape returned by GET /v1/account when authenticated with a Clerk session JWT. Omits api_key, subscription, and auto_topup. */
+        /** @description Minimal account shape returned by GET /v1/account when authenticated with a Clerk session JWT. Omits api_key, subscription, and auto_topup; the single boolean `has_subscription` stands in for the bearer path's `subscription` object. */
         AccountSessionResponse: {
             id: string;
             email: string;
@@ -2569,6 +2718,42 @@ export interface components {
             created_at: string;
             /** @description True once the account has SUCCESSFULLY COMPLETED at least one billable request (a scrape/screenshot/fetch/… that settled and was charged credits), regardless of whether it was authenticated with a Clerk session or an API key. All-time — never windowed. A request that failed does not flip it, even when its bandwidth was billed: the monitor terminal-preflight-failure path records bytes without credits, and only the credited settlement counts here. Powers the dashboard onboarding gate — the app shows the guided onboarding flow until this is true, then the dashboard. Lags by up to one usage rollup: the completion service writes the row after the response is returned, so a just-completed first request may still read false for a moment. Treat that as "not visible yet", never as "this account has never made a request". */
             has_activity: boolean;
+            /** @description True when the account has a Stripe subscription, keyed on the same `stripe_subscription_id` column that GET /v1/billing/change-plan's `no_subscription` guard tests — so a client can use it to decide whether that endpoint will answer at all. Stays TRUE while a subscription is mid-cancellation (cancelled but running to the period end): the subscription still exists and a booked plan change is still revocable. It is a boolean, not the bearer path's `subscription` object: this response has no role-dependent fields, so a non-admin member receives it too, and plan pricing does not belong there. */
+            has_subscription: boolean;
+        };
+        /** @description Account shape returned by PATCH /v1/account. Identical to AccountSessionResponse except that it omits `has_activity`: the PATCH handler returns the shared session-account body unchanged and does not run the extra activity lookup that GET /v1/account layers on top of it (issue #4187). */
+        AccountPatchResponse: {
+            id: string;
+            email: string;
+            name: string | null;
+            plan: {
+                id: string;
+                slug: string;
+                name: string;
+                included_screenshots: number;
+                has_overage: boolean;
+                overage_price_cents: number | null;
+                max_concurrency: number;
+                rate_limit_per_sec: number;
+                max_bulk_size: number;
+                max_monitors: number;
+                retention_days: number;
+            };
+            /** @description Prefixed user id of the calling admin user. Null for non-admin members. */
+            owner_user_id: string | null;
+            /** @description Account notification preferences (bandwidth alerts). */
+            notifications: {
+                /** @description Whether the account admin wants an email when bandwidth reaches 80 % of the plan limit. */
+                bandwidth_80_enabled: boolean;
+                /** @description Whether the account admin wants an email when bandwidth reaches 100 % of the plan limit. */
+                bandwidth_100_enabled: boolean;
+            };
+            /** @description The Terms of Service version this account has accepted. An empty string means the account predates clickwrap acceptance (issue #1025). The dashboard diffs this against the published current version to decide whether to show the re-acceptance prompt. */
+            terms_version: string;
+            /** @description True when the account has a Stripe subscription, keyed on the same `stripe_subscription_id` column that GET /v1/billing/change-plan's `no_subscription` guard tests. */
+            has_subscription: boolean;
+            /** Format: date-time */
+            created_at: string;
         };
         /** @description Partial update payload for PATCH /v1/account. All fields are optional; at least one of name, email, or notifications must be provided. */
         PatchAccountRequest: {
@@ -2616,7 +2801,7 @@ export interface components {
             purchased_topup_bytes: number;
             /** @description Bytes remaining in starter-grant lots, after active refund reservations. Purchased top-up bytes are excluded. */
             granted_topup_bytes: number;
-            /** @description Unspent subscription allowance carried over from earlier billing periods: bytes remaining in allowance lots granted before the current period started, after active refund reservations. Carried value is spent before the current period's allowance, so this falls to `0` before `limit_bytes` reaches the current allowance alone. */
+            /** @description Unspent subscription allowance carried over from earlier billing periods: bytes remaining in allowance lots granted before the current period started, after active refund reservations. While your plan tier is unchanged, earlier lots are drawn first, so carried-over allowance is spent before the current period's; after an upgrade, allowance acquired at the higher tier is drawn first. Value is spent in one order: your plan's included allowance, including any rollover from earlier periods, then purchased top-ups, then the one-time starter grant. */
             rollover_bytes: number;
         };
         CreditBalance: {
@@ -2898,7 +3083,7 @@ export interface operations {
                     [name: string]: unknown;
                 };
                 content: {
-                    "application/json": components["schemas"]["Account"];
+                    "application/json": components["schemas"]["AccountPatchResponse"];
                 };
             };
             /** @description Missing or invalid Clerk JWT. */
@@ -3198,7 +3383,7 @@ export interface operations {
                     "X-Screenshot-Status"?: string;
                     /** @description The originally requested URL. */
                     "X-Screenshot-URL"?: string;
-                    /** @description Credits charged for this screenshot. */
+                    /** @description Legacy credit weight for this capture (1, 2 or 4, doubling for `full_page` and again for retina/mobile). It is recorded for reporting only — screenshots are billed on bandwidth, not credits: the charge is the Phase 1 wire bytes x 1.5, and zero when Phase 1 is skipped or fails. */
                     "X-Screenshot-Credits-Charged"?: number;
                     /** @description Handler elapsed time in milliseconds. */
                     "X-Screenshot-Duration-Ms"?: number;
@@ -3239,7 +3424,7 @@ export interface operations {
                     "X-Screenshot-Status"?: string;
                     /** @description The originally requested URL. */
                     "X-Screenshot-URL"?: string;
-                    /** @description Credits charged for this screenshot. */
+                    /** @description Legacy credit weight for this capture (1, 2 or 4, doubling for `full_page` and again for retina/mobile). It is recorded for reporting only — screenshots are billed on bandwidth, not credits: the charge is the Phase 1 wire bytes x 1.5, and zero when Phase 1 is skipped or fails. */
                     "X-Screenshot-Credits-Charged"?: number;
                     /** @description Handler elapsed time in milliseconds. */
                     "X-Screenshot-Duration-Ms"?: number;
@@ -3415,7 +3600,7 @@ export interface operations {
             };
         };
         responses: {
-            /** @description Scrape completed synchronously. */
+            /** @description Scrape reached a terminal state and the body is that terminal envelope: `success` carrying content, or `failed` carrying the error envelope. Returned by the fast HTTP path in one round trip, and by a browser-path request without `async: true` once its render reaches a terminal state inside the hold window. A held render that ends in failure answers 200 with the same `failed` envelope `GET /v1/scrape/{id}` returns — narrow on `status` before reading the body. A definitive upstream outcome is a result, not a transport error: an unreachable host, a refused connection, or a target whose bot protection defeats every proxy tier all answer 200 with the `failed` envelope, never a 5xx. An inline failure ends before any job row exists, so its envelope carries `id: null` and there is nothing to poll; `error.http_status` is present only when a real upstream HTTP status is known. */
             200: {
                 headers: {
                     /** @description Stable scrape identifier (also present on the envelope as `id`). */
@@ -3466,9 +3651,9 @@ export interface operations {
                     "X-Scrape-Markdown-URL"?: string;
                     /** @description Byte length of the markdown artifact. Present only on fast-path responses when formats includes markdown. */
                     "X-Scrape-Markdown-Length"?: number;
-                    /** @description Numeric proxy tier used (diagnostic). Deprecated — use X-Scrape-Proxy-Tier-Label. */
+                    /** @description Legacy numeric form of the tier that served: 1 datacenter, 2 residential, 3 mobile. Omitted for the lean-browser tier, which has no numeric form. Deprecated — use X-Scrape-Proxy-Tier-Label. */
                     "X-Scrape-Proxy-Tier"?: number;
-                    /** @description Human-readable proxy tier label (e.g. residential, datacenter). Present on fast-path responses. */
+                    /** @description The proxy tier that actually served this request's fetch, after any escalation — never the tier first attempted. One of datacenter, residential, mobile, lean. Diagnostic only: it is never an input to routing, billing, caching or escalation. Present on sync fast-path responses. Omitted on a cache hit, which replayed stored bytes and ran no tier; and on responses the fast path did not serve. A third omission — a response replayed from stored bytes after this request's own cache lookup missed, which reports X-Scrape-Cache: miss and likewise ran no tier — exists only as an internal deploy-skew safeguard and is not reachable through this API. */
                     "X-Scrape-Proxy-Tier-Label"?: string;
                     /** @description WAF vendor detected on the target, if any (diagnostic). May be "suspected" when a low-confidence fail-open block marker was served. Omitted when no WAF is detected. */
                     "X-Scrape-Waf"?: string;
@@ -3479,10 +3664,10 @@ export interface operations {
                     [name: string]: unknown;
                 };
                 content: {
-                    "application/json": components["schemas"]["ScrapeSuccessEnvelope"];
+                    "application/json": components["schemas"]["ScrapeSuccessEnvelope"] | components["schemas"]["ScrapeErrorEnvelope"];
                 };
             };
-            /** @description Scrape accepted for async processing. */
+            /** @description Scrape accepted for background processing; the body is a receipt, not content. Returned when `async: true` was requested, or when a browser-path request's hold window expired before the render finished. Poll `GET /v1/scrape/{id}` for the result. */
             202: {
                 headers: {
                     /** @description Stable scrape identifier for the queued job. */
@@ -3771,7 +3956,14 @@ export interface operations {
     };
     getScrapeBulk: {
         parameters: {
-            query?: never;
+            query?: {
+                /** @description Opaque cursor returned by the preceding page. It is bound to this bulk id, this recovery route, and the exact status filter; cross-scope cursors return 422. */
+                cursor?: string;
+                /** @description Maximum result rows considered for this page; the 16-MiB response bound may stop sooner. */
+                limit?: number;
+                /** @description Optional item-status filter. A cursor may be reused only with the same filter. */
+                status?: "pending" | "processing" | "completed" | "failed" | "cancelled";
+            };
             header?: never;
             path: {
                 id: string;
@@ -3810,8 +4002,12 @@ export interface operations {
                         estimated_credits: number | null;
                         /** @description Webhook endpoint URL (HTTPS only; http:// rejected with 400 invalid_url, reason scheme_unsupported) */
                         webhook_url: string;
-                        /** @description Rehydrated per-URL scrape envelopes — the terminal page of results (default 100 rows, `?limit=` up to 500). `routes/scrape-bulk.ts` spreads this key into the SAME body on both status branches, so it is present here exactly as it is on the 202; on the 200 the entries carry their final success or error envelopes (issue #3632). */
-                        items: components["schemas"]["ScrapeEnvelope"][];
+                        /** @description Opaque cursor for the next stable page; null when traversal is complete. */
+                        next_cursor: string | null;
+                        /** @description True when another page is available through `next_cursor`. */
+                        has_more: boolean;
+                        /** @description Rehydrated per-URL scrape envelopes — the terminal page of results (default 500 rows, `?limit=` up to 500). `routes/scrape-bulk.ts` spreads this key into the SAME body on both status branches, so it is present here exactly as it is on the 202; on the 200 the entries carry their final success or error envelopes (issue #3632). */
+                        items: (components["schemas"]["ScrapeEnvelope"] | components["schemas"]["BulkMandatoryScrapeItem"])[];
                     };
                 };
             };
@@ -3845,8 +4041,12 @@ export interface operations {
                         estimated_credits: number | null;
                         /** @description Webhook endpoint URL (HTTPS only; http:// rejected with 400 invalid_url, reason scheme_unsupported) */
                         webhook_url: string;
-                        /** @description Rehydrated per-URL scrape envelopes — the same page the 200 returns (default 100 rows, `?limit=` up to 500). While the job is non-terminal most entries carry the `queued` envelope. */
-                        items: components["schemas"]["ScrapeEnvelope"][];
+                        /** @description Opaque cursor for the next stable page; null when traversal is complete. */
+                        next_cursor: string | null;
+                        /** @description True when another page is available through `next_cursor`. */
+                        has_more: boolean;
+                        /** @description Rehydrated per-URL scrape envelopes — the same page the 200 returns (default 500 rows, `?limit=` up to 500). While the job is non-terminal most entries carry the `queued` envelope. */
+                        items: (components["schemas"]["ScrapeEnvelope"] | components["schemas"]["BulkMandatoryScrapeItem"])[];
                     };
                 };
             };
@@ -4212,7 +4412,14 @@ export interface operations {
     };
     getFetchBulk: {
         parameters: {
-            query?: never;
+            query?: {
+                /** @description Opaque cursor returned by the preceding page. It is bound to this bulk id, this recovery route, and the exact status filter; cross-scope cursors return 422. */
+                cursor?: string;
+                /** @description Maximum result rows considered for this page; the 16-MiB response bound may stop sooner. */
+                limit?: number;
+                /** @description Optional item-status filter. A cursor may be reused only with the same filter. */
+                status?: "pending" | "processing" | "completed" | "failed" | "cancelled";
+            };
             header?: never;
             path: {
                 id: string;
@@ -4245,8 +4452,12 @@ export interface operations {
                         estimated_credits: number | null;
                         /** @description Webhook endpoint URL (HTTPS only; http:// rejected with 400 invalid_url, reason scheme_unsupported) */
                         webhook_url: string;
-                        /** @description Per-URL fetch items, oldest first, capped at 500 (listBulkFetchItemsWithLatestAttempt). */
-                        items: {
+                        /** @description Opaque cursor for the next stable page; null when traversal is complete. */
+                        next_cursor: string | null;
+                        /** @description True when another page is available through `next_cursor`. */
+                        has_more: boolean;
+                        /** @description Stable per-URL fetch items, oldest first. Follow `next_cursor` while `has_more` is true to enumerate the complete filtered job; each page considers at most 500 rows and is bounded to 16 MiB. */
+                        items: ({
                             /**
                              * @description Scrape-row id, `sc_`-prefixed. Fetch-bulk items are rows of the same resource sync `/v1/scrape` returns, so they share its prefix. Not to be confused with the `ft_`-prefixed `X-Fetch-ID` correlation header on sync `/v1/fetch`, which identifies a request rather than a stored item.
                              * @example sc_01j9abc123
@@ -4256,25 +4467,46 @@ export interface operations {
                             url: string;
                             /** @enum {string} */
                             status: "pending" | "processing" | "completed" | "failed" | "cancelled";
-                            content_type: string | null;
-                            content_length: number | null;
-                            /** @description Pre-signed download URL for the fetched body, valid for 600 seconds (10 minutes) from the moment this response was generated — matching the signing TTL of `image_url` on `GET /v1/bulk/{id}/screenshots`. A new signature is minted on every poll. Null for items with no stored body; a completed item whose object cannot be signed falls back to the unsigned stored URL, which returns 401 on download. */
+                            content_type?: string | null;
+                            content_length?: number | null;
+                            /** @description Pre-signed download URL for the fetched body, valid for 600 seconds (10 minutes) from the moment this response was generated — matching the signing TTL of `image_url` on `GET /v1/bulk/{id}/screenshots`. A new signature is minted on every poll. Null for items with no stored body or whose object cannot be signed. In the latter case `error_code` is `artifact_unavailable`; the private unsigned storage URL is never returned. */
                             content_url: string | null;
-                            waf_vendor: string | null;
-                            cache_hit: boolean;
+                            waf_vendor?: string | null;
+                            cache_hit?: boolean;
                             /**
                              * @description Itemised account of this item's charge — the basis, the named factors
                              *     that composed the multiplier, and the resulting billed bytes. Omitted
                              *     for rows that completed before the billing node was persisted.
                              */
                             billing?: components["schemas"]["BillingNode"];
+                            /** @description Stable item-local error code. `artifact_unavailable` means the stored result or a usable signed reference could not be produced. */
                             error_code: string | null;
                             error_message: string | null;
                             /** Format: date-time */
-                            created_at: string;
+                            created_at?: string;
                             /** Format: date-time */
-                            completed_at: string | null;
-                        }[];
+                            completed_at?: string | null;
+                        } | {
+                            /**
+                             * @description Scrape-row id, `sc_`-prefixed — the same stable identity the ordinary item carries, so recovery pagination is unaffected.
+                             * @example sc_01j9abc123
+                             */
+                            id: string;
+                            /** @enum {string} */
+                            type: "fetch";
+                            /**
+                             * @description Terminal state of the item. This is the contract's terminal signal and outranks the ordinary item's legacy `status` spelling.
+                             * @enum {string}
+                             */
+                            terminal_outcome: "pending" | "processing" | "completed" | "failed" | "cancelled";
+                            /** Format: uri */
+                            url: string;
+                            /** @description Bounded pre-signed download URL retained from the ordinary item, or `null` when the reference did not fit or could not be produced. */
+                            content_url: string | null;
+                            error_code: string | null;
+                            /** @description Bounded failure detail; a long message is truncated. */
+                            error_message: string | null;
+                        })[];
                     };
                 };
             };
@@ -4311,8 +4543,12 @@ export interface operations {
                         estimated_credits: number | null;
                         /** @description Webhook endpoint URL (HTTPS only; http:// rejected with 400 invalid_url, reason scheme_unsupported) */
                         webhook_url: string;
-                        /** @description Per-URL fetch items, oldest first, capped at 500 (listBulkFetchItemsWithLatestAttempt). */
-                        items: {
+                        /** @description Opaque cursor for the next stable page; null when traversal is complete. */
+                        next_cursor: string | null;
+                        /** @description True when another page is available through `next_cursor`. */
+                        has_more: boolean;
+                        /** @description Stable per-URL fetch items, oldest first. Follow `next_cursor` while `has_more` is true to enumerate the complete filtered job; each page considers at most 500 rows and is bounded to 16 MiB. */
+                        items: ({
                             /**
                              * @description Scrape-row id, `sc_`-prefixed. Fetch-bulk items are rows of the same resource sync `/v1/scrape` returns, so they share its prefix. Not to be confused with the `ft_`-prefixed `X-Fetch-ID` correlation header on sync `/v1/fetch`, which identifies a request rather than a stored item.
                              * @example sc_01j9abc123
@@ -4322,25 +4558,46 @@ export interface operations {
                             url: string;
                             /** @enum {string} */
                             status: "pending" | "processing" | "completed" | "failed" | "cancelled";
-                            content_type: string | null;
-                            content_length: number | null;
-                            /** @description Pre-signed download URL for the fetched body, valid for 600 seconds (10 minutes) from the moment this response was generated — matching the signing TTL of `image_url` on `GET /v1/bulk/{id}/screenshots`. A new signature is minted on every poll. Null for items with no stored body; a completed item whose object cannot be signed falls back to the unsigned stored URL, which returns 401 on download. */
+                            content_type?: string | null;
+                            content_length?: number | null;
+                            /** @description Pre-signed download URL for the fetched body, valid for 600 seconds (10 minutes) from the moment this response was generated — matching the signing TTL of `image_url` on `GET /v1/bulk/{id}/screenshots`. A new signature is minted on every poll. Null for items with no stored body or whose object cannot be signed. In the latter case `error_code` is `artifact_unavailable`; the private unsigned storage URL is never returned. */
                             content_url: string | null;
-                            waf_vendor: string | null;
-                            cache_hit: boolean;
+                            waf_vendor?: string | null;
+                            cache_hit?: boolean;
                             /**
                              * @description Itemised account of this item's charge — the basis, the named factors
                              *     that composed the multiplier, and the resulting billed bytes. Omitted
                              *     for rows that completed before the billing node was persisted.
                              */
                             billing?: components["schemas"]["BillingNode"];
+                            /** @description Stable item-local error code. `artifact_unavailable` means the stored result or a usable signed reference could not be produced. */
                             error_code: string | null;
                             error_message: string | null;
                             /** Format: date-time */
-                            created_at: string;
+                            created_at?: string;
                             /** Format: date-time */
-                            completed_at: string | null;
-                        }[];
+                            completed_at?: string | null;
+                        } | {
+                            /**
+                             * @description Scrape-row id, `sc_`-prefixed — the same stable identity the ordinary item carries, so recovery pagination is unaffected.
+                             * @example sc_01j9abc123
+                             */
+                            id: string;
+                            /** @enum {string} */
+                            type: "fetch";
+                            /**
+                             * @description Terminal state of the item. This is the contract's terminal signal and outranks the ordinary item's legacy `status` spelling.
+                             * @enum {string}
+                             */
+                            terminal_outcome: "pending" | "processing" | "completed" | "failed" | "cancelled";
+                            /** Format: uri */
+                            url: string;
+                            /** @description Bounded pre-signed download URL retained from the ordinary item, or `null` when the reference did not fit or could not be produced. */
+                            content_url: string | null;
+                            error_code: string | null;
+                            /** @description Bounded failure detail; a long message is truncated. */
+                            error_message: string | null;
+                        })[];
                     };
                 };
             };
@@ -4781,7 +5038,14 @@ export interface operations {
     };
     listBulkScreenshots: {
         parameters: {
-            query?: never;
+            query?: {
+                /** @description Opaque per-type seek cursor returned by the preceding page. It is bound to this bulk id, this mixed recovery route, and the exact status filter; cross-scope cursors return 422. */
+                cursor?: string;
+                /** @description Maximum rows selected per requested item type; the 16-MiB response bound may stop sooner. */
+                limit?: number;
+                /** @description Optional item-status filter. A cursor may be reused only with the same filter. */
+                status?: "pending" | "processing" | "completed" | "failed" | "cancelled";
+            };
             header?: never;
             path: {
                 id: string;
@@ -4801,8 +5065,13 @@ export interface operations {
                         bulk_id: string;
                         /** @description Number of items in `items` (page size, not the job total). */
                         total: number;
+                        /** @description Opaque per-type cursor for the next stable page; null when every selected item type is exhausted. Never advances past an item omitted by the byte bound. */
+                        next_cursor: string | null;
+                        /** @description True when another page is available through `next_cursor`. */
+                        has_more: boolean;
+                        job_counters: components["schemas"]["BulkJobCounters"];
                         /** @description Heterogeneous capture items discriminated by `type`. Fields outside the common set are present only for the matching `type`. */
-                        items: {
+                        items: ({
                             /** @enum {string} */
                             type: "screenshot" | "recording" | "scrape";
                             /** @description Prefixed id — `ss_` / `rec_` / `sc_` per `type`. */
@@ -4811,7 +5080,7 @@ export interface operations {
                             status: "pending" | "processing" | "completed" | "failed" | "cancelled";
                             /** Format: uri */
                             url: string;
-                            credits_charged: number | null;
+                            credits_charged?: number | null;
                             /**
                              * @description Itemised account of this item's charge — the basis, the named factors
                              *     that composed the multiplier, and the resulting billed bytes. Omitted
@@ -4819,12 +5088,13 @@ export interface operations {
                              */
                             billing?: components["schemas"]["BillingNode"];
                             error_code: string | null;
+                            /** @description Bounded human-readable failure detail. */
                             error_message: string | null;
                             /** Format: date-time */
-                            created_at: string;
+                            created_at?: string;
                             /** Format: date-time */
-                            completed_at: string | null;
-                            /** @description `type: screenshot` only. Presigned for completed rows with a storage key; raw image_url otherwise. */
+                            completed_at?: string | null;
+                            /** @description `type: screenshot` only. Pre-signed download URL for the image, minted fresh for completed rows with a storage key and valid for 600 seconds (10 minutes). For every other row the stored value is returned unchanged — `null` while no image has been stored, and otherwise a private, unsigned storage URL that returns 401 on download. That covers non-completed rows, completed rows with no storage key, and completed rows whose object could not be signed; none of them raise an `artifact_warnings` entry. */
                             image_url?: string | null;
                             /** @description `type: screenshot` and `type: scrape` only. */
                             page_title?: string | null;
@@ -4832,7 +5102,7 @@ export interface operations {
                             format?: string;
                             /** @description `type: recording` only. */
                             video_url?: string | null;
-                            /** @description `type: scrape` only. Pre-signed download URL for the scraped body, valid for 600 seconds (10 minutes) from the moment this response was generated — matching the signing TTL of `image_url` above and of `content_url` on `GET /v1/fetch/bulk/{id}`. A new signature is minted on every poll. Null for items with no stored body; a completed item whose object cannot be signed falls back to the unsigned stored URL, which returns 401 on download. */
+                            /** @description `type: scrape` only. Pre-signed download URL for the scraped body, valid for 600 seconds (10 minutes) from the moment this response was generated — matching the signing TTL of `image_url` above and of `content_url` on `GET /v1/fetch/bulk/{id}`. A new signature is minted on every poll for a completed item with a storage key. For every other item the stored value is returned unchanged — `null` while no body has been stored, and otherwise a private, unsigned storage URL that returns 401 on download. No `artifact_warnings` entry is raised for this field; unlike `GET /v1/fetch/bulk/{id}`, this endpoint reports no `artifact_unavailable` when signing fails. */
                             content_url?: string | null;
                             /** @description `type: scrape` only. */
                             content_type?: string | null;
@@ -4840,9 +5110,33 @@ export interface operations {
                             content_length?: number | null;
                             /** @description `type: scrape` only. Always null in bulk listings — fetch the body via `markdown_url`. */
                             markdown?: string | null;
-                            /** @description `type: scrape` only. Pre-signed download URL for the markdown rendering of the page, valid for 600 seconds (10 minutes) from the moment this response was generated — the same signing TTL as `content_url` and `image_url` above. A new signature is minted on every poll. Null for items with no stored markdown; a completed item whose object cannot be signed falls back to the unsigned stored URL, which returns 401 on download. */
+                            /** @description `type: scrape` only. Pre-signed download URL for the markdown rendering of the page, valid for 600 seconds (10 minutes) from the moment this response was generated — the same signing TTL as `content_url` and `image_url` above. A new signature is minted on every poll for a completed item with a markdown key. For every other item the stored value is returned unchanged — `null` while no markdown has been stored, and otherwise a private, unsigned storage URL that returns 401 on download. No `artifact_warnings` entry is raised for this field; unlike `GET /v1/fetch/bulk/{id}`, this endpoint reports no `artifact_unavailable` when signing fails. */
                             markdown_url?: string | null;
-                        }[];
+                            /** @description `type: scrape` only. Exact requested artifact values or signed references. Every key is present; unrequested or unavailable values are null, with nonfatal reference failures in `artifact_warnings`. */
+                            artifacts?: {
+                                raw: string | null;
+                                markdown: string | null;
+                                links: null | (string | components["schemas"]["ScrapeScoredLink"])[];
+                                images: null | (string | components["schemas"]["ScrapeScoredImage"])[];
+                            };
+                            /** @description Nonfatal artifact reference failures for this scrape item. */
+                            artifact_warnings?: components["schemas"]["ScrapeWarning"][];
+                        } | {
+                            /** @description Prefixed id — `ss_` / `rec_` / `sc_` per `type`. The same stable identity the ordinary item carries. */
+                            id: string;
+                            /** @enum {string} */
+                            type: "screenshot" | "recording" | "scrape";
+                            /**
+                             * @description Terminal state of the item. This is the contract's terminal signal and outranks the ordinary item's legacy `status` spelling.
+                             * @enum {string}
+                             */
+                            terminal_outcome: "pending" | "processing" | "completed" | "failed" | "cancelled";
+                            /** Format: uri */
+                            url: string;
+                            error_code: string | null;
+                            /** @description Bounded failure detail; a long message is truncated. */
+                            error_message: string | null;
+                        })[];
                     };
                 };
             };
@@ -5611,7 +5905,7 @@ export interface operations {
                         plan_type: "payg" | "subscription";
                         /** @description Total top-up spend in cents for this billing period. Present only in dual/bytes billing mode. */
                         topup_spent_cents?: number;
-                        /** @description Remaining purchased top-up bytes, already net of any overage consumed against them. Equal to topup_bytes. Present only in dual/bytes billing mode. */
+                        /** @description Remaining top-up bytes across purchased top-up lots and the one-time starter grant, already net of any overage consumed against them. Equal to topup_bytes. Present only in dual/bytes billing mode. */
                         topup_balance_bytes?: number;
                         /** @description Days elapsed since period_start. */
                         period_days_elapsed: number;
@@ -5621,11 +5915,11 @@ export interface operations {
                         bytes_bulk: number;
                         bytes_scrape: number;
                         bytes_monitor: number;
-                        /** @description The spendable byte budget for this period, summed over the account's value lots: the allowance granted for the current period, plus unspent allowance carried over from earlier periods, plus purchased top-up and starter-grant bytes. Carried-over value is spent first, so this figure falls as it is consumed. */
+                        /** @description The spendable byte budget for this period, summed over the account's value lots: the allowance granted for the current period, plus unspent allowance carried over from earlier periods, plus purchased top-up and starter-grant bytes. The figure falls as those lots are consumed. */
                         bytes_limit: number;
                         /** @description Bytes still available across every active lot, after active refund reservations. */
                         bytes_remaining: number;
-                        /** @description Unspent allowance carried over from earlier billing periods. */
+                        /** @description Unspent allowance carried over from earlier billing periods. Value is spent in one order: your plan's included allowance, including any rollover from earlier periods, then purchased top-ups, then the one-time starter grant. */
                         rollover_bytes: number;
                         /** @description Bytes remaining in purchased top-up and starter-grant lots. Subscription allowance is excluded. */
                         topup_bytes: number;
@@ -5817,7 +6111,7 @@ export interface operations {
                             error_message?: string | null;
                             /** @description Prefixed key id (ak_) that issued the request. */
                             api_key_id?: string | null;
-                            /** @description Stored content, image or video URL — null when the row has no stored object. For a `completed` row with a stored object this is a **pre-signed** download URL, minted fresh on every read of this endpoint and valid for **600 seconds (10 minutes)** — the same signing lifetime as `content_url` on `GET /v1/fetch/bulk/{id}` and `image_url` on `GET /v1/bulk/{id}/screenshots`. The underlying objects are private, so an unsigned URL returns 401: download inside that window, or re-poll this endpoint for a fresh signature. Rows that are not `completed`, and completed rows whose object cannot be signed, fall back to the unsigned stored URL, which returns 401 on download. */
+                            /** @description Stored content, image or video URL. For a `completed` row with a non-empty storage key this is a **pre-signed** download URL, minted fresh on every read of this endpoint and valid for **600 seconds (10 minutes)** — the same signing lifetime as `content_url` on `GET /v1/fetch/bulk/{id}` and `image_url` on `GET /v1/bulk/{id}/screenshots`. Download inside that window, or re-poll this endpoint for a fresh signature. For every other row the stored value is returned unchanged — `null` while no object has been stored, and otherwise a private, unsigned storage URL that returns 401 on download. That covers rows that are not `completed`, completed rows with no storage key, and completed rows whose object could not be signed; this endpoint raises no `artifact_unavailable` signal for any of them. */
                             artifact_url?: string | null;
                             /** @description The original request options. */
                             options?: {
@@ -5978,10 +6272,10 @@ export interface operations {
             content: {
                 "application/json": {
                     /**
-                     * @description Bytes to purchase. Allowed tiers — 5, 25, 50, 75, 100 GB.
+                     * @description Bytes to purchase. Allowed tiers — 5, 25, 50, 75, 100 GB (1 GB = 1,000,000,000 bytes).
                      * @enum {integer}
                      */
-                    bytes: 5368709120 | 26843545600 | 53687091200 | 80530636800 | 107374182400;
+                    bytes: 5000000000 | 25000000000 | 50000000000 | 75000000000 | 100000000000;
                     /**
                      * Format: uri
                      * @description Redirect target after a completed Checkout.
@@ -6135,6 +6429,52 @@ export interface operations {
             };
         };
     };
+    getPlanChange: {
+        parameters: {
+            query?: never;
+            header?: never;
+            path?: never;
+            cookie?: never;
+        };
+        requestBody?: never;
+        responses: {
+            /** @description Successful response. */
+            200: {
+                headers: {
+                    [name: string]: unknown;
+                };
+                content: {
+                    "application/json": {
+                        /** @description The plan the subscription switches to, or null. */
+                        pending_plan_slug: string | null;
+                        /**
+                         * Format: date-time
+                         * @description When the booked change lands, or null.
+                         */
+                        pending_effective_at: string | null;
+                    };
+                };
+            };
+            /** @description No subscription. */
+            400: {
+                headers: {
+                    [name: string]: unknown;
+                };
+                content: {
+                    "application/json": components["schemas"]["Error"];
+                };
+            };
+            /** @description The Stripe subscription schedule could not be read. */
+            502: {
+                headers: {
+                    [name: string]: unknown;
+                };
+                content: {
+                    "application/json": components["schemas"]["Error"];
+                };
+            };
+        };
+    };
     changePlan: {
         parameters: {
             query?: never;
@@ -6151,13 +6491,28 @@ export interface operations {
             };
         };
         responses: {
-            /** @description Successful response. */
+            /** @description Upgrades apply immediately (`changed: true`). Downgrades are booked for the end of the paid period (`changed: false`, `pending: true`) so the customer keeps the allowance they already paid for and nothing is prorated. */
             200: {
                 headers: {
                     [name: string]: unknown;
                 };
                 content: {
-                    "application/json": Record<string, never>;
+                    "application/json": {
+                        /** @description Whether the subscription was re-priced now. */
+                        changed: boolean;
+                        /** @description Present and true when the change is booked for a later date. */
+                        pending?: boolean;
+                        previous_plan: string;
+                        new_plan: string;
+                        subscription_id: string;
+                        /**
+                         * Format: date-time
+                         * @description When a booked change lands. Absent on an immediate change.
+                         */
+                        effective_at?: string;
+                        /** @description Stripe proration behaviour applied. Absent on a booked change. */
+                        proration?: string;
+                    };
                 };
             };
             /** @description No subscription, same plan, or invalid plan. */
@@ -6171,6 +6526,40 @@ export interface operations {
             };
         };
     };
+    revokePlanChange: {
+        parameters: {
+            query?: never;
+            header?: never;
+            path?: never;
+            cookie?: never;
+        };
+        requestBody?: never;
+        responses: {
+            /** @description Successful response. */
+            200: {
+                headers: {
+                    [name: string]: unknown;
+                };
+                content: {
+                    "application/json": {
+                        revoked: boolean;
+                        /** @description The plan the subscription stays on. */
+                        plan: string;
+                        subscription_id: string;
+                    };
+                };
+            };
+            /** @description No subscription, or no scheduled plan change to revoke. */
+            400: {
+                headers: {
+                    [name: string]: unknown;
+                };
+                content: {
+                    "application/json": components["schemas"]["Error"];
+                };
+            };
+        };
+    };
     listInvoices: {
         parameters: {
             query?: {
@@ -6234,7 +6623,10 @@ export interface operations {
                 };
                 content: {
                     "application/json": {
-                        bandwidth: components["schemas"]["BandwidthBalance"];
+                        bandwidth: components["schemas"]["BandwidthBalance"] & {
+                            /** @description Remaining balance of your subscription allowance: bytes still unspent across all allowance lots, the current period's and any rolled over from earlier periods alike, after active refund reservations. This is a remaining balance and falls to zero as the allowance is drawn down. It is not `included_bytes`, which is the plan's configured grant for a period and does not move as it is spent; do not subtract one from the other. `rollover_bytes` is a subset of this figure. */
+                            remaining_allowance_bytes: number;
+                        };
                         credits: components["schemas"]["CreditBalance"];
                         rates: {
                             /** @description Bandwidth top-up price in cents per MB. When the authenticated account is on a plan that does not explicitly configure a top-up price (e.g. free, payg, or a custom plan without an explicit value), the API falls back to the rack rate — the highest `topup_price_per_mb_cents` configured across all plans — so the UI never advertises `$0.00/GB`. */
@@ -6272,15 +6664,15 @@ export interface operations {
             content: {
                 "application/json": {
                     enabled: boolean;
-                    /** @description Min 1 MB. Required when enabled. */
+                    /** @description Min 1 MB (1,000,000 bytes). Required when enabled. */
                     threshold_bytes?: number;
                     /**
-                     * @description Allowed tiers — 5, 25, 50, 75, 100 GB. Required when enabled.
+                     * @description Allowed tiers — 5, 25, 50, 75, 100 GB (1 GB = 1,000,000,000 bytes). Required when enabled.
                      * @enum {integer}
                      */
-                    amount_bytes?: 5368709120 | 26843545600 | 53687091200 | 80530636800 | 107374182400;
-                    /** @description $1-$1000. Required when enabled. */
-                    monthly_cap_cents?: number;
+                    amount_bytes?: 5000000000 | 25000000000 | 50000000000 | 75000000000 | 100000000000;
+                    /** @description $1-$1000, or null for no monthly cap. Required when enabled — send an explicit null to remove the cap; omitting the key is rejected. */
+                    monthly_cap_cents?: number | null;
                 };
             };
         };