@hunt-labs/bytekit-sdk 0.4.0 → 0.6.0

package/dist/generated/api.d.ts

@@ -155,6 +155,9 @@ export interface paths {
          * Capture a screenshot
          * @description Sync by default (holds up to 28s). Pass `?async=true` to return 202 immediately.
          *     Poll via GET /v1/screenshots/{id}.
+         *
+         *     **Limits:** request bodies are capped at 512 KB. An oversized body
+         *     returns a `400` with error code `request_too_large`.
          */
         post: operations["createScreenshot"];
         delete?: never;
@@ -277,6 +280,9 @@ export interface paths {
         /**
          * Fetch a URL (POST)
          * @description Same as GET /v1/fetch but with a JSON request body.
+         *
+         *     **Limits:** request bodies are capped at 512 KB. An oversized body
+         *     returns a `400` with error code `request_too_large`.
          */
         post: operations["postFetch"];
         delete?: never;
@@ -298,6 +304,17 @@ 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 (cookies, wait_for_selector, etc.).
+         *
+         *     **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
+         *     is checked; a body that declares `Content-Length` is instead bounded
+         *     there by a 20 MB fail-safe (not the real limit — see below), since
+         *     that branch reads nothing until your key is verified. Once your key
+         *     is verified, a second check re-gates the body against your account's
+         *     own `max_bulk_size` (at this endpoint's per-item override budget),
+         *     which reaches 16.8 MB for the largest documented account. A
+         *     standard-plan account's effective ceiling is 2 MB; either tier's
+         *     overrun returns a `400` with error code `request_too_large`.
          */
         post: operations["createFetchBulk"];
         delete?: never;
@@ -313,7 +330,19 @@ export interface paths {
             path?: never;
             cookie?: never;
         };
-        /** Get fetch bulk job status */
+        /**
+         * Get fetch bulk job status
+         * @description Returns the job envelope plus its per-URL items.
+         *
+         *     **Downloading item content.** Each completed item's `content_url` is a
+         *     **pre-signed** URL, minted fresh on every read of this endpoint and valid
+         *     for **600 seconds (10 minutes)** — the same signing lifetime as the
+         *     `image_url` returned by `GET /v1/bulk/{id}/screenshots`. 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. Items that are not `completed`, and completed items with no
+         *     stored object, carry `null` or the unsigned stored URL instead.
+         */
         get: operations["getFetchBulk"];
         put?: never;
         post?: never;
@@ -343,6 +372,17 @@ 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.
+         *
+         *     **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
+         *     is checked; a body that declares `Content-Length` is instead bounded
+         *     there by a 32 MB fail-safe (not the real limit — see below), since
+         *     that branch reads nothing until your key is verified. Once your key
+         *     is verified, a second check re-gates the body against your account's
+         *     own `max_bulk_size` (at this endpoint's richer per-item override
+         *     budget), which reaches 28.7 MB for the largest documented account. A
+         *     standard-plan account's effective ceiling is 4 MB; either tier's
+         *     overrun returns a `400` with error code `request_too_large`.
          */
         post: operations["createBulk"];
         delete?: never;
@@ -379,7 +419,20 @@ export interface paths {
             path?: never;
             cookie?: never;
         };
-        /** List bulk job items */
+        /**
+         * 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)** —
+         *     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.
+         */
         get: operations["listBulkScreenshots"];
         put?: never;
         post?: never;
@@ -402,6 +455,9 @@ export interface paths {
         /**
          * Create a change-detection monitor
          * @description Creates a recurring change-detection monitor for a URL, delivering results via webhook.
+         *
+         *     **Limits:** request bodies are capped at 512 KB. An oversized body
+         *     returns a `400` with error code `request_too_large`.
          */
         post: operations["createMonitor"];
         delete?: never;
@@ -462,6 +518,9 @@ export interface paths {
          *     Webhook deliveries include `X-ByteKit-Event: sitemap.completed` or
          *     `X-ByteKit-Event: sitemap.failed` so receivers can dispatch on the
          *     header without parsing the body shape.
+         *
+         *     **Limits:** request bodies are capped at 512 KB. An oversized body
+         *     returns a `400` with error code `request_too_large`.
          */
         post: operations["createSitemap"];
         delete?: never;
@@ -738,9 +797,9 @@ export interface paths {
         get?: never;
         put?: never;
         /**
-         * Cancel subscription
-         * @description Immediately cancels the Stripe subscription with proration.
-         *     Takes a balance snapshot for 6-month grace-period restoration on re-subscribe.
+         * Legacy cancellation compatibility terminal
+         * @description Returns 410. Customer cancellation is initiated through the hosted
+         *     Billing Portal and projected through Stripe webhooks.
          */
         post: operations["cancelSubscription"];
         delete?: never;
@@ -917,6 +976,12 @@ export interface paths {
         /**
          * Stripe webhook receiver
          * @description Receives Stripe webhook events. Verified via signature.
+         *
+         *     **Limits:** request bodies are capped at 256 KB — real Stripe event
+         *     payloads stay in the tens of KB. An oversized body returns a `400`
+         *     with a bespoke `{ error }` body (this route predates issue #699's
+         *     unified REST envelope and answers Stripe's own webhook contract, not
+         *     the public API's error shape).
          */
         post: operations["stripeWebhook"];
         delete?: never;
@@ -954,6 +1019,10 @@ export interface paths {
         /**
          * Retry a webhook delivery
          * @description Requeues a failed or exhausted webhook delivery for another attempt.
+         *
+         *     **Limits:** this endpoint takes no request body; any body sent is
+         *     capped at 64 KB. An oversized body returns a `400` with error code
+         *     `request_too_large`.
          */
         post: operations["retryWebhookDelivery"];
         delete?: never;
@@ -1236,6 +1305,12 @@ export interface paths {
          * Clerk webhook receiver
          * @description Receives Clerk events (user.created, user.updated, user.deleted, etc.).
          *     Authentication is via Svix signature verification — no bearer token required.
+         *
+         *     **Limits:** request bodies are capped at 256 KB — real Clerk event
+         *     payloads (user/membership/invitation objects) stay well under this.
+         *     An oversized body returns a `400` with error code `request_too_large`
+         *     (bespoke `{ error }` slug shape, matching this route's existing
+         *     error convention, not the unified REST envelope).
          */
         post: operations["clerkWebhook"];
         delete?: never;
@@ -2605,6 +2680,15 @@ export interface operations {
                     "application/json": components["schemas"]["AccountBearerResponse"] | components["schemas"]["AccountSessionResponse"];
                 };
             };
+            /** @description Rate limit exceeded (`rate_limited`). Only reachable when authenticated via Clerk session (the 60-request/60-second per-user window) — the bearer and in-process auth branches are not rate-limited at this endpoint. Carries a `Retry-After` header derived from the same clock as the window reset. */
+            429: {
+                headers: {
+                    [name: string]: unknown;
+                };
+                content: {
+                    "application/json": components["schemas"]["Error"];
+                };
+            };
         };
     };
     deleteAccount: {
@@ -2690,6 +2774,15 @@ export interface operations {
                     "application/json": components["schemas"]["Error"];
                 };
             };
+            /** @description Rate limit exceeded (`rate_limited`) — the Clerk-session 60-request/60-second per-user window. Carries a `Retry-After` header derived from the same clock as the window reset. */
+            429: {
+                headers: {
+                    [name: string]: unknown;
+                };
+                content: {
+                    "application/json": components["schemas"]["Error"];
+                };
+            };
         };
     };
     listApiKeys: {
@@ -2916,7 +3009,7 @@ export interface operations {
                     "application/json": components["schemas"]["Error"];
                 };
             };
-            /** @description Rate limit exceeded. */
+            /** @description Reveal rate limit exceeded (per-account anti-harvest cap, distinct from the per-second API rate limit). Carries a `Retry-After` header. */
             429: {
                 headers: {
                     [name: string]: unknown;
@@ -3045,8 +3138,45 @@ export interface operations {
                     "application/json": components["schemas"]["Error"];
                 };
             };
-            /** @description Validation error or screenshot failed. */
+            /**
+             * @description Validation error, or a screenshot that failed inside the sync hold.
+             *     The two carry DIFFERENT bodies (issue #2679):
+             *
+             *     - A request-validation failure returns the unified `Error` envelope
+             *       with code `validation_error`.
+             *     - A capture that reached a terminal `failed` state inside the sync
+             *       hold returns the full `ScreenshotResponse` resource, whose
+             *       `error_code`/`error_message` carry the real failure (`blocked`,
+             *       `timeout`, …). This is the canonical shape for that case: the
+             *       resource body is what carries the `ss_` handle, `poll_url` and
+             *       `expires_at` a client needs to redeem the failed capture, none of
+             *       which fit the `Error` envelope.
+             *
+             *     Discriminate on the shape of the top-level `error` key. The envelope
+             *     form carries `error` as an OBJECT (`{ code, message, http_status,
+             *     failed_at }`); the resource form has no `error` key at all, and
+             *     carries the flat `error_code`/`error_message` pair plus `id` instead.
+             *
+             *     Do NOT discriminate on `status`. Both forms carry
+             *     `"status": "failed"` on this response — `Error.status` is a required
+             *     property with `enum: [failed]` — so it separates nothing here.
+             *
+             *     `X-Screenshot-ID` accompanies the resource form only: a
+             *     request-validation failure is raised before a screenshot row exists,
+             *     so no screenshot headers travel with it.
+             */
             422: {
+                headers: {
+                    /** @description Stable screenshot identifier (matches `id` in the resource body). Emitted only on the failed-capture variant; absent on a request-validation failure. */
+                    "X-Screenshot-ID"?: string;
+                    [name: string]: unknown;
+                };
+                content: {
+                    "application/json": components["schemas"]["Error"] | components["schemas"]["ScreenshotResponse"];
+                };
+            };
+            /** @description Rate limit (`rate_limited`) or concurrency limit (`concurrency_limit`) exceeded. Carries a `Retry-After` header — seconds derived from the same clock as `X-RateLimit-Reset` for the rate-limit variant, a fixed small back-off for the concurrency variant. */
+            429: {
                 headers: {
                     [name: string]: unknown;
                 };
@@ -3246,7 +3376,7 @@ export interface operations {
                     "application/json": components["schemas"]["Error"];
                 };
             };
-            /** @description Rate limit exceeded. */
+            /** @description Rate limit (`rate_limited`) or concurrency limit (`concurrency_limit`) exceeded. Carries a `Retry-After` header — seconds derived from the same clock as `X-RateLimit-Reset` for the rate-limit variant, a fixed small back-off for the concurrency variant. */
             429: {
                 headers: {
                     [name: string]: unknown;
@@ -3446,8 +3576,9 @@ export interface operations {
                         created_at: string;
                         /** Format: date-time */
                         completed_at: string | null;
-                        total_credits_charged: number;
-                        /** @description Estimated credits at submission time. Null in GET responses. */
+                        /** @description Always null on the create response — the job has not been billed yet (routes/scrape-bulk.ts builds the 202 body from a partial job row). Fractional when populated (credits are NUMERIC(10,2)); the numeric branch is unreachable on this path and exists only so the 202 and 200 bodies share one shape. */
+                        total_credits_charged: number | null;
+                        /** @description Estimated credits at submission time. Null in GET responses. Fractional — markdown/html formats weigh 0.5 credits each (scrape-shared/src/credits.ts), so a one-item markdown job is 1.5. */
                         estimated_credits: number | null;
                         /** @description Webhook endpoint URL (HTTPS only; http:// rejected with 400 invalid_url, reason scheme_unsupported) */
                         webhook_url: string;
@@ -3523,7 +3654,8 @@ export interface operations {
                         created_at: string;
                         /** Format: date-time */
                         completed_at: string | null;
-                        total_credits_charged: number;
+                        /** @description Total credits billed for the job. Null until the job is billed. Fractional — credits are NUMERIC(10,2). */
+                        total_credits_charged: number | null;
                         /** @description Null in GET responses (computed at submission time only). */
                         estimated_credits: number | null;
                         /** @description Webhook endpoint URL (HTTPS only; http:// rejected with 400 invalid_url, reason scheme_unsupported) */
@@ -3610,6 +3742,15 @@ export interface operations {
                     "application/json": components["schemas"]["Error"];
                 };
             };
+            /** @description Rate limit (`rate_limited`) or concurrency limit (`concurrency_limit`) exceeded. Carries a `Retry-After` header — seconds derived from the same clock as `X-RateLimit-Reset` for the rate-limit variant, a fixed small back-off for the concurrency variant. */
+            429: {
+                headers: {
+                    [name: string]: unknown;
+                };
+                content: {
+                    "application/json": components["schemas"]["Error"];
+                };
+            };
             /**
              * @description Fetch service unavailable, content transform failed, or a non-2xx upstream
              *     response relayed as the unified Error envelope. On an upstream relay the HTTP
@@ -3699,6 +3840,15 @@ export interface operations {
                     "application/json": components["schemas"]["Error"];
                 };
             };
+            /** @description Rate limit (`rate_limited`) or concurrency limit (`concurrency_limit`) exceeded. Carries a `Retry-After` header — seconds derived from the same clock as `X-RateLimit-Reset` for the rate-limit variant, a fixed small back-off for the concurrency variant. */
+            429: {
+                headers: {
+                    [name: string]: unknown;
+                };
+                content: {
+                    "application/json": components["schemas"]["Error"];
+                };
+            };
             /**
              * @description Fetch service unavailable, content transform failed, or a non-2xx upstream
              *     response relayed as the unified Error envelope. On an upstream relay the HTTP
@@ -3758,7 +3908,25 @@ export interface operations {
                     [name: string]: unknown;
                 };
                 content: {
-                    "application/json": Record<string, never>;
+                    "application/json": {
+                        /** @example bulk_01j9abc123 */
+                        id: string;
+                        /** @enum {string} */
+                        status: "processing" | "completed" | "failed";
+                        total: number;
+                        completed: number;
+                        failed: number;
+                        /** Format: date-time */
+                        created_at: string;
+                        /** Format: date-time */
+                        completed_at: string | null;
+                        /** @description Always null on the create response — the job has not been billed yet (routes/fetch-bulk.ts builds the 202 body from a partial job row). Fractional when populated (credits are NUMERIC(10,2)); the numeric branch is unreachable on this path and exists only so the 202 and 200 bodies share one shape. */
+                        total_credits_charged: number | null;
+                        /** @description Estimated credits at submission time. Null in GET responses. Fractional — markdown/html formats weigh 0.5 credits each (scrape-shared/src/credits.ts), so a one-item markdown job is 1.5. */
+                        estimated_credits: number | null;
+                        /** @description Webhook endpoint URL (HTTPS only; http:// rejected with 400 invalid_url, reason scheme_unsupported) */
+                        webhook_url: string;
+                    };
                 };
             };
             /**
@@ -3812,7 +3980,49 @@ export interface operations {
                     [name: string]: unknown;
                 };
                 content: {
-                    "application/json": Record<string, never>;
+                    "application/json": {
+                        /** @example bulk_01j9abc123 */
+                        id: string;
+                        /** @enum {string} */
+                        status: "processing" | "completed" | "failed";
+                        total: number;
+                        completed: number;
+                        failed: number;
+                        /** Format: date-time */
+                        created_at: string;
+                        /** Format: date-time */
+                        completed_at: string | null;
+                        /** @description Total credits billed for the job. Null until the job is billed. Fractional — credits are NUMERIC(10,2). */
+                        total_credits_charged: number | null;
+                        /** @description Null in GET responses (computed at submission time only). */
+                        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 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
+                             */
+                            id: string;
+                            /** Format: uri */
+                            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_url: string | null;
+                            waf_vendor: string | null;
+                            cache_hit: boolean;
+                            error_code: string | null;
+                            error_message: string | null;
+                            /** Format: date-time */
+                            created_at: string;
+                            /** Format: date-time */
+                            completed_at: string | null;
+                        }[];
+                    };
                 };
             };
             /** @description Resource not found. */
@@ -3855,7 +4065,8 @@ export interface operations {
                         created_at: string;
                         /** Format: date-time */
                         completed_at: string | null;
-                        total_credits_charged: number;
+                        /** @description Total credits billed for the job. Null until the job is billed. Fractional — credits are NUMERIC(10,2). */
+                        total_credits_charged: number | null;
                         /** @description Null in GET responses (computed at submission time only). */
                         estimated_credits: number | null;
                         /** @description Webhook endpoint URL (HTTPS only; http:// rejected with 400 invalid_url, reason scheme_unsupported) */
@@ -3938,7 +4149,7 @@ export interface operations {
                         /** Format: uri */
                         url: string;
                         /**
-                         * @default screenshot
+                         * @description Capture kind for this entry. If omitted, inherits `defaults.type`; if that is also omitted, falls back to `screenshot`.
                          * @enum {string}
                          */
                         type?: "screenshot" | "scrape";
@@ -4060,8 +4271,9 @@ export interface operations {
                         created_at: string;
                         /** Format: date-time */
                         completed_at: string | null;
-                        total_credits_charged: number;
-                        /** @description Estimated credits at submission time. Null in GET responses. */
+                        /** @description Always null on the create response — the job has not been billed yet (routes/bulk.ts builds the 202 body from a partial job row). Fractional when populated (credits are NUMERIC(10,2)); the numeric branch is unreachable on this path and exists only so the 202 and 200 bodies share one shape. */
+                        total_credits_charged: number | null;
+                        /** @description Estimated credits at submission time. Null in GET responses. Fractional — markdown/html formats weigh 0.5 credits each (scrape-shared/src/credits.ts), so a one-item markdown job is 1.5. */
                         estimated_credits: number | null;
                         /** @description Webhook endpoint URL (HTTPS only; http:// rejected with 400 invalid_url, reason scheme_unsupported) */
                         webhook_url: string;
@@ -4090,7 +4302,17 @@ export interface operations {
             /**
              * @description Validation error. `bulk_too_large` is returned when the item count
              *     exceeds the account plan's `max_bulk_size` cap (also surfaced as
-             *     `max_bulk_size` on `GET /v1/account`).
+             *     `max_bulk_size` on `GET /v1/account`). `validation_error` is
+             *     returned when the request body contains an unrecognized key
+             *     anywhere in the top-level object, an `items[]` entry, or
+             *     `defaults` — all three reject unknown keys with a 422
+             *     `validation_error` whose `details` message names the offending
+             *     key, instead of silently discarding it. The two nested objects
+             *     do not accept the same field set: `device_scale_factor` is
+             *     `defaults`-only (rejected per item), and `duration`/`scenario`
+             *     are `items[]`-only (rejected under `defaults`). `metadata` is
+             *     valid both at the top level of the body and per item, but is
+             *     rejected with this same 422 if placed under `defaults`.
              */
             422: {
                 headers: {
@@ -4131,7 +4353,8 @@ export interface operations {
                         created_at: string;
                         /** Format: date-time */
                         completed_at: string | null;
-                        total_credits_charged: number;
+                        /** @description Total credits billed for the job. Null until the job is billed. Fractional — credits are NUMERIC(10,2). */
+                        total_credits_charged: number | null;
                         /** @description Null in GET responses (computed at submission time only). */
                         estimated_credits: number | null;
                         /** @description Webhook endpoint URL (HTTPS only; http:// rejected with 400 invalid_url, reason scheme_unsupported) */
@@ -4179,7 +4402,8 @@ export interface operations {
                         created_at: string;
                         /** Format: date-time */
                         completed_at: string | null;
-                        total_credits_charged: number;
+                        /** @description Total credits billed for the job. Null until the job is billed. Fractional — credits are NUMERIC(10,2). */
+                        total_credits_charged: number | null;
                         /** @description Null in cancel responses (computed at submission time only). */
                         estimated_credits: number | null;
                         /** @description Webhook endpoint URL (HTTPS only; http:// rejected with 400 invalid_url, reason scheme_unsupported) */
@@ -4215,7 +4439,48 @@ export interface operations {
                     [name: string]: unknown;
                 };
                 content: {
-                    "application/json": Record<string, never>;
+                    "application/json": {
+                        /** @example bulk_01j9abc123 */
+                        bulk_id: string;
+                        /** @description Number of items in `items` (page size, not the job total). */
+                        total: number;
+                        /** @description Heterogeneous capture items discriminated by `type`. Fields outside the common set are present only for the matching `type`. */
+                        items: {
+                            /** @enum {string} */
+                            type: "screenshot" | "recording" | "scrape";
+                            /** @description Prefixed id — `ss_` / `rec_` / `sc_` per `type`. */
+                            id: string;
+                            /** @enum {string} */
+                            status: "pending" | "processing" | "completed" | "failed" | "cancelled";
+                            /** Format: uri */
+                            url: string;
+                            credits_charged: number | null;
+                            error_code: string | null;
+                            error_message: string | null;
+                            /** Format: date-time */
+                            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. */
+                            image_url?: string | null;
+                            /** @description `type: screenshot` and `type: scrape` only. */
+                            page_title?: string | null;
+                            /** @description `type: recording` only. */
+                            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. */
+                            content_url?: string | null;
+                            /** @description `type: scrape` only. */
+                            content_type?: string | null;
+                            /** @description `type: scrape` only. */
+                            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. */
+                            markdown_url?: string | null;
+                        }[];
+                    };
                 };
             };
         };
@@ -4524,6 +4789,15 @@ export interface operations {
                     "application/json": components["schemas"]["Error"];
                 };
             };
+            /** @description Rate limit (`rate_limited`) or concurrency limit (`concurrency_limit`) exceeded. Carries a `Retry-After` header — seconds derived from the same clock as `X-RateLimit-Reset` for the rate-limit variant, a fixed small back-off for the concurrency variant. */
+            429: {
+                headers: {
+                    [name: string]: unknown;
+                };
+                content: {
+                    "application/json": components["schemas"]["Error"];
+                };
+            };
         };
     };
     getSitemap: {
@@ -4563,6 +4837,15 @@ export interface operations {
                     "application/json": components["schemas"]["Error"];
                 };
             };
+            /** @description The id path segment is not a well-formed sitemap job id (genuinely malformed — a well-formed-but-absent id returns 404, not 422; see the Inverse case in issue */
+            422: {
+                headers: {
+                    [name: string]: unknown;
+                };
+                content: {
+                    "application/json": components["schemas"]["Error"];
+                };
+            };
         };
     };
     createSearch: {
@@ -4656,7 +4939,7 @@ export interface operations {
                             /** Format: uri */
                             url: string;
                             /** @description Short text excerpt for the result. Present for `web` and `news` results; omitted for `images` results. */
-                            snippet: string;
+                            snippet?: string;
                             /** @description Published date of the result. For `web` and `news` results the key is always present but is `null` when the provider reports no date; omitted entirely for `images` results. */
                             date?: string | null;
                             /** @description Publisher / source name. Present for `news` and `images` results, when the provider reports one. */
@@ -4710,7 +4993,7 @@ export interface operations {
                     "application/json": components["schemas"]["Error"];
                 };
             };
-            /** @description Rate limit exceeded. */
+            /** @description Rate limit exceeded (`rate_limited`). Carries the `X-RateLimit-Limit`/`X-RateLimit-Remaining`/`X-RateLimit-Reset` triplet and a `Retry-After` header. The window is per-second for a bearer API key, or the 60-request/60-second Clerk session window when authenticated via `resolveDualAuth` — `Retry-After` reflects whichever window applies to the request. */
             429: {
                 headers: {
                     [name: string]: unknown;
@@ -4984,10 +5267,10 @@ export interface operations {
                         /** @description Plan base price in cents. */
                         plan_price_cents: number;
                         /**
-                         * @description Derived plan category. "payg" for pay-as-you-go plans, "free" for the free tier, "subscription" for all others.
+                         * @description Derived plan category. "payg" for pay-as-you-go plans, "subscription" for all recurring paid plans.
                          * @enum {string}
                          */
-                        plan_type: "payg" | "free" | "subscription";
+                        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 top-up bytes: max(0, topup_bytes − max(0, bytes_used − included_bytes − rollover_bytes)). Present only in dual/bytes billing mode. */
@@ -5192,7 +5475,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/video URL, if any. */
+                            /** @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. */
                             artifact_url?: string | null;
                             /** @description The original request options. */
                             options?: {
@@ -5262,6 +5545,8 @@ export interface operations {
         requestBody: {
             content: {
                 "application/json": {
+                    /** @enum {string} */
+                    purpose: "payment_method_update" | "invoice_history" | "subscription_cancel";
                     /** Format: uri */
                     return_url: string;
                 };
@@ -5289,6 +5574,15 @@ export interface operations {
                     "application/json": components["schemas"]["Error"];
                 };
             };
+            /** @description Cancellation disclosure revision is absent or stale. */
+            409: {
+                headers: {
+                    [name: string]: unknown;
+                };
+                content: {
+                    "application/json": components["schemas"]["Error"];
+                };
+            };
         };
     };
     registerPayg: {
@@ -5488,23 +5782,8 @@ export interface operations {
             };
         };
         responses: {
-            /** @description Successful response. */
-            200: {
-                headers: {
-                    [name: string]: unknown;
-                };
-                content: {
-                    "application/json": {
-                        cancelled: boolean;
-                        /** @enum {string} */
-                        refund: "prorated";
-                        /** Format: date-time */
-                        grace_period_expires_at: string;
-                    };
-                };
-            };
-            /** @description No subscription or already cancelled. */
-            400: {
+            /** @description Cancellation moved to hosted Billing Portal. */
+            410: {
                 headers: {
                     [name: string]: unknown;
                 };
@@ -5876,6 +6155,21 @@ export interface operations {
                 };
                 content?: never;
             };
+            /**
+             * @description Bad request. Returned when the request body exceeds this
+             *     endpoint's 256 KB size limit (bespoke `{ error }` body, not the
+             *     unified envelope — see the endpoint description).
+             */
+            400: {
+                headers: {
+                    [name: string]: unknown;
+                };
+                content: {
+                    "application/json": {
+                        error?: string;
+                    };
+                };
+            };
         };
     };
     listWebhookDeliveries: {
@@ -5929,6 +6223,18 @@ export interface operations {
                     "application/json": components["schemas"]["WebhookDeliveryResponse"];
                 };
             };
+            /**
+             * @description Bad request. Returned when the request body exceeds this
+             *     endpoint's size limit; the error code is `request_too_large`.
+             */
+            400: {
+                headers: {
+                    [name: string]: unknown;
+                };
+                content: {
+                    "application/json": components["schemas"]["Error"];
+                };
+            };
             /** @description Delivery not found or not in a retryable state. */
             404: {
                 headers: {
@@ -6145,6 +6451,15 @@ export interface operations {
                     "application/json": components["schemas"]["Error"];
                 };
             };
+            /** @description Rate limit exceeded (`rate_limited`) — the Clerk-session 60-request/60-second per-user window. Carries a `Retry-After` header derived from the same clock as the window reset. */
+            429: {
+                headers: {
+                    [name: string]: unknown;
+                };
+                content: {
+                    "application/json": components["schemas"]["Error"];
+                };
+            };
         };
     };
     updateMe: {
@@ -6181,6 +6496,15 @@ export interface operations {
                     "application/json": components["schemas"]["Error"];
                 };
             };
+            /** @description Rate limit exceeded (`rate_limited`) — the Clerk-session 60-request/60-second per-user window. Carries a `Retry-After` header derived from the same clock as the window reset. */
+            429: {
+                headers: {
+                    [name: string]: unknown;
+                };
+                content: {
+                    "application/json": components["schemas"]["Error"];
+                };
+            };
         };
     };
     requestEmailChange: {
@@ -6244,6 +6568,15 @@ export interface operations {
                     "application/json": components["schemas"]["Error"];
                 };
             };
+            /** @description Rate limit exceeded (`rate_limited`) — the Clerk-session 60-request/60-second per-user window. Carries a `Retry-After` header derived from the same clock as the window reset. */
+            429: {
+                headers: {
+                    [name: string]: unknown;
+                };
+                content: {
+                    "application/json": components["schemas"]["Error"];
+                };
+            };
         };
     };
     removeMember: {
@@ -6387,6 +6720,15 @@ export interface operations {
                     "application/json": components["schemas"]["Error"];
                 };
             };
+            /** @description Rate limit exceeded (`rate_limited`) — the Clerk-session 60-request/60-second per-user window. Carries a `Retry-After` header derived from the same clock as the window reset. */
+            429: {
+                headers: {
+                    [name: string]: unknown;
+                };
+                content: {
+                    "application/json": components["schemas"]["Error"];
+                };
+            };
         };
     };
     createInvite: {
@@ -6443,6 +6785,15 @@ export interface operations {
                     "application/json": components["schemas"]["Error"];
                 };
             };
+            /** @description Rate limit exceeded (`rate_limited`) — the Clerk-session 60-request/60-second per-user window. Carries a `Retry-After` header derived from the same clock as the window reset. */
+            429: {
+                headers: {
+                    [name: string]: unknown;
+                };
+                content: {
+                    "application/json": components["schemas"]["Error"];
+                };
+            };
         };
     };
     acceptInvite: {