@hunt-labs/bytekit-sdk 0.9.1 → 0.9.3

package/CHANGELOG.md

@@ -10,6 +10,49 @@ today, see [README.md](./README.md), which remains the authoritative usage guide
 
 ## [Unreleased]
 
+## [0.9.3] - 2026-09-04
+
+### Changed
+
+- Regenerated `src/generated/api.d.ts` against the corrected queued-scrape `status_url`
+  documentation (#3925). `status_url` is a root-relative path, never an absolute URI: join it
+  onto the API base URL you called (`https://api.bytekit.com`, no trailing slash) to get the URL
+  to poll. The spec had declared it `format: uri` with an absolute example, which no server has
+  ever emitted; the emitted value is unchanged, so no client behaviour moves.
+- Regenerated `src/generated/api.d.ts` against the documented proxy-tier response headers
+  (#3926). `X-Scrape-Proxy-Tier-Label` now documents that it reports the tier that ACTUALLY
+  served a scrape — after any escalation, never the tier first attempted — that it is
+  diagnostic only, and that it is omitted on a cache hit, which replayed stored bytes and ran
+  no tier. The deprecated numeric `X-Scrape-Proxy-Tier` documents the legacy `1` datacenter /
+  `2` residential / `3` mobile vocabulary and its omission for the lean-browser tier. Types are
+  unchanged; only the documentation on them moved.
+
+## [0.9.2] - 2026-09-03
+
+### Changed
+
+- **Breaking (API):** the scrape `formats` vocabulary is now `raw | markdown | links | images`
+  (#3775). The unprocessed-source format is called `raw` — it has returned JSON, XML and plain
+  text alongside HTML since #1853, so the old raw-HTML name misdescribed it — and the
+  cleaned-article-HTML format is gone. The server accepts no alias for either retired value, so
+  a request naming one now comes back `422` with the new set in the message. Update `formats`
+  and read the content back from `formats.raw`:
+
+  ```ts
+  const result = await client.scrape.create({ url, formats: ['raw', 'markdown'] });
+  console.log(result.formats.raw);
+  ```
+
+- Regenerated `src/generated/api.d.ts` against the documented `402` contract (#3784). Every
+  quota-enforced operation now declares `402` through one shared `PaymentRequired` response, and
+  the `X-Quota-*` headers are referenced by the operations that actually emit them. Types only —
+  no runtime behavior changed.
+
+- The generated `events` field description on the scrape request type now documents the
+  widened server default (`queued`, `completed`, `failed`) and that a caller may send an
+  explicit subset to receive fewer deliveries (#3777). Types/docs only — this regeneration
+  followed a server-side default change; the SDK carried no logic tied to the old default.
+
 ## [0.9.1] - 2026-08-25
 
 ### Fixed

package/README.md

@@ -56,7 +56,7 @@ const client = new ByteKit({
 ```ts
 const result = await client.scrape.create({
   url: 'https://example.com',
-  formats: ['markdown', 'html'],
+  formats: ['markdown', 'raw'],
 });
 ```
 

package/dist/generated/api.d.ts

@@ -816,11 +816,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;
@@ -1343,13 +1351,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 +1367,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;
             /**
@@ -1521,10 +1529,10 @@ export interface components {
             url: string;
             /**
              * @default [
-             *       "raw_html"
+             *       "raw"
              *     ]
              */
-            formats: ("raw_html" | "html" | "markdown" | "links" | "images")[];
+            formats: ("raw" | "markdown" | "links" | "images")[];
             /** @default US */
             country: string;
             /** @default 0 */
@@ -1539,7 +1547,9 @@ export interface components {
              */
             webhook_url?: string;
             /**
+             * @description Webhook event types to deliver when webhook_url is set. Defaults to all three (queued, completed, failed); send an explicit subset to receive fewer.
              * @default [
+             *       "queued",
              *       "completed",
              *       "failed"
              *     ]
@@ -1572,7 +1582,7 @@ export interface components {
             markdown_filter_images?: boolean;
             /** @description When true, `formats.links` and `formats.images` return `ScrapeScoredLink[]` / `ScrapeScoredImage[]` (rich objects) instead of `string[]`, and a top-level `tables` array is included. Only effective when `markdown` is in `formats`. */
             markdown_include_media?: boolean;
-            /** @description When true, enables markdown-pipeline and tag-filter warnings for affected `html` and `markdown` requests. Artifact availability warnings such as `artifact_unavailable` may appear independently of this flag. */
+            /** @description When true, enables markdown-pipeline and tag-filter warnings for requests that include the `markdown` format. Artifact availability warnings such as `artifact_unavailable` may appear independently of this flag. */
             markdown_include_warnings?: boolean;
             /** @description When true, the response includes a top-level `stats` object with `ScrapeStats` (chars, tokens, blocks). Only effective when `markdown` is in `formats`. */
             markdown_include_stats?: boolean;
@@ -1590,17 +1600,17 @@ export interface components {
              */
             mobile: boolean;
             /**
-             * @description When true (default), base64-encoded `data:` image sources are stripped from the HTML before markdown conversion and from the `html` format output. Set to false to preserve base64 images in the pipeline output. Does not affect `raw_html`, which always returns the original HTML unchanged.
+             * @description When true (default), base64-encoded `data:` image sources are stripped from the HTML before markdown conversion. Set to false to preserve base64 images in the pipeline output. Does not affect `raw`, which always returns the original source unchanged.
              * @default true
              */
             remove_base64_images: boolean;
             /**
-             * @description HTML element names (not CSS selectors) to keep. When non-empty, only content within these elements is included in the `html` and `markdown` output. Applied before `exclude_tags`. Does not affect `raw_html`, which always returns the full page.
+             * @description HTML element names (not CSS selectors) to keep. When non-empty, only content within these elements is included in the `markdown` output. Applied before `exclude_tags`. Does not affect `raw`, which always returns the full page.
              * @default []
              */
             include_tags: string[];
             /**
-             * @description HTML element names (not CSS selectors) to strip from the `html` and `markdown` output. Applied after `include_tags` when both are present. Does not affect `raw_html`, which always returns the full page.
+             * @description HTML element names (not CSS selectors) to strip from the `markdown` output. Applied after `include_tags` when both are present. Does not affect `raw`, which always returns the full page.
              * @default []
              */
             exclude_tags: string[];
@@ -1670,8 +1680,8 @@ export interface components {
             truncated: boolean;
         };
         ScrapeFormats: {
-            raw_html?: string;
-            html?: string;
+            /** @description The untouched upstream source of whatever the URL served — HTML, JSON, XML or plain text. */
+            raw?: string;
             markdown?: string;
             /** @description Plain URL strings by default. When markdownIncludeMedia=true, an array of ScrapeScoredLink objects. */
             links?: string[] | components["schemas"]["ScrapeScoredLink"][];
@@ -1709,8 +1719,7 @@ export interface components {
          *       "status_code": 200,
          *       "retrieved_at": "2025-01-15T12:00:00Z",
          *       "formats": {
-         *         "raw_html": "<html><body><h1>Hello World</h1><p>Example page with a <a href=\"/about\">link</a> and an image.</p></body></html>",
-         *         "html": "<html><body><h1>Hello World</h1><p>Example page with a <a href=\"/about\">link</a> and an image.</p></body></html>",
+         *         "raw": "<html><body><h1>Hello World</h1><p>Example page with a <a href=\"/about\">link</a> and an image.</p></body></html>",
          *         "markdown": "# Hello World\n\nExample page with a [link](/about) and an image.\n\n![Alt text](https://example.com/photo.png)",
          *         "links": [
          *           {
@@ -1871,7 +1880,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": []
          *     }
@@ -1891,7 +1900,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;
@@ -2226,7 +2235,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 */
@@ -2615,7 +2624,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: {
@@ -2632,7 +2641,48 @@ export interface components {
             rollover_credits: number;
         };
     };
-    responses: never;
+    responses: {
+        /**
+         * @description Payment required. The account cannot fund this request, and no work was
+         *     performed. The unified `Error` envelope carries one of the billing codes
+         *     below in `error.code`; match on the code, never on the prose.
+         *
+         *     - `quota_exceeded` — the enforced balance for this request's meter is
+         *       exhausted. Capture endpoints (`/v1/scrape`, `/v1/fetch`,
+         *       `/v1/screenshots`, `/v1/sitemap` and the bulk siblings) meter
+         *       bandwidth; `/v1/search` meters credits.
+         *     - `spending_cap_reached` — the request would push overage spend past the
+         *       account's configured cap. Only reachable on a custom overage-enabled
+         *       plan; standard plans stop at `quota_exceeded`.
+         *     - `billing_entitlement_impaired` — the paid subscription is in a payment
+         *       impairment (e.g. `past_due`). `error.message` names the reason.
+         *     - `billing_entitlement_expired` — the paid subscription entitlement
+         *       period has ended, or its dunning grace period has run out.
+         *
+         *     Not retryable as-is: settle the balance, raise the cap, or restore the
+         *     subscription first. This response carries no `X-Quota-*` headers — they
+         *     travel with the 2xx responses of the operations that emit them.
+         */
+        PaymentRequired: {
+            headers: {
+                [name: string]: unknown;
+            };
+            content: {
+                /**
+                 * @example {
+                 *       "status": "failed",
+                 *       "error": {
+                 *         "code": "quota_exceeded",
+                 *         "message": "Monthly bandwidth quota exhausted.",
+                 *         "http_status": 402,
+                 *         "failed_at": "2026-01-15T12:00:00Z"
+                 *       }
+                 *     }
+                 */
+                "application/json": components["schemas"]["Error"];
+            };
+        };
+    };
     parameters: {
         /**
          * @description Optional. Identifies which published ByteKit client sent the request, as
@@ -2673,8 +2723,8 @@ export interface components {
         XQuotaUsed: number;
         /** @description Remaining quota in the billing period. */
         XQuotaRemaining: number;
-        /** @description ISO 8601 timestamp when the billing period ends. */
-        XQuotaReset: string;
+        /** @description Unix epoch second at which the current billing period ends — the same unit as `X-RateLimit-Reset`, not an ISO 8601 timestamp (issue #1538). */
+        XQuotaReset: number;
         /** @description Maximum concurrent jobs allowed. */
         XConcurrencyLimit: number;
         /** @description Currently active concurrent jobs. */
@@ -3156,7 +3206,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;
@@ -3178,6 +3228,10 @@ export interface operations {
                     "X-Screenshot-Cache"?: "hit" | "miss" | "bypass";
                     /** @description Age of the cached screenshot in seconds. Present only on cache hits. */
                     "X-Screenshot-Cache-Age"?: number;
+                    "X-Quota-Limit": components["headers"]["XQuotaLimit"];
+                    "X-Quota-Used": components["headers"]["XQuotaUsed"];
+                    "X-Quota-Remaining": components["headers"]["XQuotaRemaining"];
+                    "X-Quota-Reset": components["headers"]["XQuotaReset"];
                     [name: string]: unknown;
                 };
                 content: {
@@ -3193,7 +3247,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;
@@ -3207,6 +3261,10 @@ export interface operations {
                     "X-Billable-Bytes"?: number;
                     /** @description Billing multiplier applied to raw bytes to compute billable bytes. A rendering of the response body's `billing` node, which is the authoritative surface: it names each factor that composed this value. Where the two disagree, the node is correct. */
                     "X-Billing-Multiplier"?: number;
+                    "X-Quota-Limit": components["headers"]["XQuotaLimit"];
+                    "X-Quota-Used": components["headers"]["XQuotaUsed"];
+                    "X-Quota-Remaining": components["headers"]["XQuotaRemaining"];
+                    "X-Quota-Reset": components["headers"]["XQuotaReset"];
                     [name: string]: unknown;
                 };
                 content: {
@@ -3232,15 +3290,7 @@ export interface operations {
                     "application/json": components["schemas"]["Error"];
                 };
             };
-            /** @description Quota exceeded. */
-            402: {
-                headers: {
-                    [name: string]: unknown;
-                };
-                content: {
-                    "application/json": components["schemas"]["Error"];
-                };
-            };
+            402: components["responses"]["PaymentRequired"];
             /**
              * @description Validation error, or a screenshot that failed inside the sync hold.
              *     The two carry DIFFERENT bodies (issue #2679):
@@ -3272,6 +3322,10 @@ export interface operations {
                 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;
+                    "X-Quota-Limit": components["headers"]["XQuotaLimit"];
+                    "X-Quota-Used": components["headers"]["XQuotaUsed"];
+                    "X-Quota-Remaining": components["headers"]["XQuotaRemaining"];
+                    "X-Quota-Reset": components["headers"]["XQuotaReset"];
                     [name: string]: unknown;
                 };
                 content: {
@@ -3349,7 +3403,7 @@ export interface operations {
                  * @example {
                  *       "url": "https://example.com",
                  *       "formats": [
-                 *         "raw_html",
+                 *         "raw",
                  *         "markdown"
                  *       ],
                  *       "markdown_mode": "article",
@@ -3396,7 +3450,7 @@ export interface operations {
                     "X-Raw-Bytes"?: number;
                     /** @description Chargeable bytes after applying the billing multiplier. Equals round(X-Raw-Bytes × X-Billing-Multiplier). */
                     "X-Billable-Bytes"?: number;
-                    /** @description Bandwidth cost multiplier (e.g. 1.0 for raw_html-only, 1.5 for +markdown/html). Cache hits compose the endpoint format factor: raw 0.5, markdown 0.75. Excludes the `clean_markdown` surcharge: when `clean_markdown: true` and the clean succeeded, the settled usage is 3× this header's value, so this header does not predict the amount you are billed. The response body's `billing` node is the authoritative surface — it DOES carry the `clean_markdown` factor, so its `multiplier` and `billed_bytes` are what you are charged. Where the two disagree, the node is correct. */
+                    /** @description Bandwidth cost multiplier (e.g. 1.0 for a `raw`-only scrape, 1.5 when `markdown` is also requested). Cache hits compose the endpoint format factor, which is a separate number from this one: 0.5 for an unprocessed-source scrape, 0.75 with markdown. Excludes the `clean_markdown` surcharge: when `clean_markdown: true` and the clean succeeded, the settled usage is 3× this header's value, so this header does not predict the amount you are billed. The response body's `billing` node is the authoritative surface — it DOES carry the `clean_markdown` factor, so its `multiplier` and `billed_bytes` are what you are charged. Where the two disagree, the node is correct. */
                     "X-Billing-Multiplier"?: number;
                     /** @description Credits charged for this scrape (multiplier applied to base 1.0 per format). */
                     "X-Scrape-Credits-Charged"?: number;
@@ -3420,12 +3474,16 @@ 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. */
                     "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;
+                    "X-Quota-Limit": components["headers"]["XQuotaLimit"];
+                    "X-Quota-Used": components["headers"]["XQuotaUsed"];
+                    "X-Quota-Remaining": components["headers"]["XQuotaRemaining"];
+                    "X-Quota-Reset": components["headers"]["XQuotaReset"];
                     [name: string]: unknown;
                 };
                 content: {
@@ -3439,6 +3497,10 @@ export interface operations {
                     "X-Scrape-ID"?: string;
                     /** @description Always `queued` on a 202 response. */
                     "X-Scrape-Status"?: "queued";
+                    "X-Quota-Limit": components["headers"]["XQuotaLimit"];
+                    "X-Quota-Used": components["headers"]["XQuotaUsed"];
+                    "X-Quota-Remaining": components["headers"]["XQuotaRemaining"];
+                    "X-Quota-Reset": components["headers"]["XQuotaReset"];
                     [name: string]: unknown;
                 };
                 content: {
@@ -3464,6 +3526,7 @@ export interface operations {
                     "application/json": components["schemas"]["Error"];
                 };
             };
+            402: components["responses"]["PaymentRequired"];
             /** @description Validation error. */
             422: {
                 headers: {
@@ -3539,7 +3602,7 @@ export interface operations {
                  *         {
                  *           "url": "https://example.com",
                  *           "formats": [
-                 *             "raw_html",
+                 *             "raw",
                  *             "markdown"
                  *           ],
                  *           "custom": {
@@ -3555,7 +3618,7 @@ export interface operations {
                  *       ],
                  *       "defaults": {
                  *         "formats": [
-                 *           "raw_html"
+                 *           "raw"
                  *         ],
                  *         "country": "US"
                  *       },
@@ -3572,7 +3635,7 @@ export interface operations {
                     items?: {
                         /** Format: uri */
                         url: string;
-                        formats?: ("raw_html" | "html" | "markdown" | "links" | "images")[];
+                        formats?: ("raw" | "markdown" | "links" | "images")[];
                         country?: string;
                         delay_ms?: number;
                         timeout_ms?: number;
@@ -3602,10 +3665,10 @@ export interface operations {
                     defaults?: {
                         /**
                          * @default [
-                         *       "raw_html"
+                         *       "raw"
                          *     ]
                          */
-                        formats?: ("raw_html" | "html" | "markdown" | "links" | "images")[];
+                        formats?: ("raw" | "markdown" | "links" | "images")[];
                         /** @default US */
                         country?: string;
                         /** @default 0 */
@@ -3651,6 +3714,10 @@ export interface operations {
             /** @description Bulk scrape job accepted. */
             202: {
                 headers: {
+                    "X-Quota-Limit": components["headers"]["XQuotaLimit"];
+                    "X-Quota-Used": components["headers"]["XQuotaUsed"];
+                    "X-Quota-Remaining": components["headers"]["XQuotaRemaining"];
+                    "X-Quota-Reset": components["headers"]["XQuotaReset"];
                     [name: string]: unknown;
                 };
                 content: {
@@ -3694,6 +3761,7 @@ export interface operations {
                     "application/json": components["schemas"]["Error"];
                 };
             };
+            402: components["responses"]["PaymentRequired"];
             /**
              * @description Validation error. `bulk_too_large` is returned when the item count
              *     exceeds the account plan's `max_bulk_size` cap (also surfaced as
@@ -3842,6 +3910,10 @@ export interface operations {
                     "X-Billing-Multiplier"?: number;
                     /** @description Back-compat duplicate of `X-Billing-Multiplier` — identical value on every path. Prefer `X-Billing-Multiplier`; this alias is retained for clients that read the `X-Fetch-*` header family. */
                     "X-Fetch-Billing-Multiplier"?: number;
+                    "X-Quota-Limit": components["headers"]["XQuotaLimit"];
+                    "X-Quota-Used": components["headers"]["XQuotaUsed"];
+                    "X-Quota-Remaining": components["headers"]["XQuotaRemaining"];
+                    "X-Quota-Reset": components["headers"]["XQuotaReset"];
                     [name: string]: unknown;
                 };
                 content: {
@@ -3857,6 +3929,7 @@ export interface operations {
                     "application/json": components["schemas"]["Error"];
                 };
             };
+            402: components["responses"]["PaymentRequired"];
             /** @description Validation error (e.g. slow-path-only field). */
             422: {
                 headers: {
@@ -3963,6 +4036,10 @@ export interface operations {
                     "X-Billing-Multiplier"?: number;
                     /** @description Back-compat duplicate of `X-Billing-Multiplier` — identical value on every path. Prefer `X-Billing-Multiplier`; this alias is retained for clients that read the `X-Fetch-*` header family. */
                     "X-Fetch-Billing-Multiplier"?: number;
+                    "X-Quota-Limit": components["headers"]["XQuotaLimit"];
+                    "X-Quota-Used": components["headers"]["XQuotaUsed"];
+                    "X-Quota-Remaining": components["headers"]["XQuotaRemaining"];
+                    "X-Quota-Reset": components["headers"]["XQuotaReset"];
                     [name: string]: unknown;
                 };
                 content: {
@@ -3978,6 +4055,7 @@ export interface operations {
                     "application/json": components["schemas"]["Error"];
                 };
             };
+            402: components["responses"]["PaymentRequired"];
             /** @description Validation error (e.g. malformed JSON, unsupported fetch format, or slow-path-only field). */
             422: {
                 headers: {
@@ -4077,6 +4155,10 @@ export interface operations {
             /** @description Fetch bulk job accepted. */
             202: {
                 headers: {
+                    "X-Quota-Limit": components["headers"]["XQuotaLimit"];
+                    "X-Quota-Used": components["headers"]["XQuotaUsed"];
+                    "X-Quota-Remaining": components["headers"]["XQuotaRemaining"];
+                    "X-Quota-Reset": components["headers"]["XQuotaReset"];
                     [name: string]: unknown;
                 };
                 content: {
@@ -4120,6 +4202,7 @@ export interface operations {
                     "application/json": components["schemas"]["Error"];
                 };
             };
+            402: components["responses"]["PaymentRequired"];
             /**
              * @description Validation error. `bulk_too_large` is returned when the item count
              *     exceeds the account plan's `max_bulk_size` cap (also surfaced as
@@ -4359,7 +4442,7 @@ export interface operations {
                  *           "type": "scrape",
                  *           "formats": [
                  *             "markdown",
-                 *             "html"
+                 *             "raw"
                  *           ],
                  *           "include_html": true,
                  *           "wait_until": "networkidle",
@@ -4375,7 +4458,7 @@ export interface operations {
                  *         "device": "desktop",
                  *         "country": "US",
                  *         "formats": [
-                 *           "raw_html"
+                 *           "raw"
                  *         ],
                  *         "device_scale_factor": 2
                  *       },
@@ -4412,7 +4495,7 @@ export interface operations {
                         language?: string | null;
                         dark_mode?: boolean;
                         /** @description Scrape output formats (scrape entries). */
-                        formats?: ("raw_html" | "html" | "markdown" | "links" | "images")[];
+                        formats?: ("raw" | "markdown" | "links" | "images")[];
                         /** @enum {string} */
                         wait_until?: "load" | "domcontentloaded" | "networkidle";
                         wait_for_selector?: string | null;
@@ -4465,7 +4548,7 @@ export interface operations {
                         language?: string | null;
                         /** @default false */
                         dark_mode?: boolean;
-                        formats?: ("raw_html" | "html" | "markdown" | "links" | "images")[];
+                        formats?: ("raw" | "markdown" | "links" | "images")[];
                         /**
                          * @default load
                          * @enum {string}
@@ -4501,6 +4584,10 @@ export interface operations {
             /** @description Bulk job accepted. */
             202: {
                 headers: {
+                    "X-Quota-Limit": components["headers"]["XQuotaLimit"];
+                    "X-Quota-Used": components["headers"]["XQuotaUsed"];
+                    "X-Quota-Remaining": components["headers"]["XQuotaRemaining"];
+                    "X-Quota-Reset": components["headers"]["XQuotaReset"];
                     [name: string]: unknown;
                 };
                 content: {
@@ -4544,6 +4631,7 @@ export interface operations {
                     "application/json": components["schemas"]["Error"];
                 };
             };
+            402: components["responses"]["PaymentRequired"];
             /**
              * @description Validation error. `bulk_too_large` is returned when the item count
              *     exceeds the account plan's `max_bulk_size` cap (also surfaced as
@@ -5063,6 +5151,7 @@ export interface operations {
                     "application/json": components["schemas"]["Error"];
                 };
             };
+            402: components["responses"]["PaymentRequired"];
             /** @description Validation error. */
             422: {
                 headers: {
@@ -5267,15 +5356,7 @@ export interface operations {
                     "application/json": components["schemas"]["Error"];
                 };
             };
-            /** @description Payment required. Either the account is out of credits (`quota_exceeded`), or a custom overage-enabled plan would cross its configured overage spending cap (`spending_cap_reached`). */
-            402: {
-                headers: {
-                    [name: string]: unknown;
-                };
-                content: {
-                    "application/json": components["schemas"]["Error"];
-                };
-            };
+            402: components["responses"]["PaymentRequired"];
             /** @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: {
@@ -5437,15 +5518,7 @@ export interface operations {
                     "application/json": components["schemas"]["Error"];
                 };
             };
-            /** @description Bandwidth quota exhausted (`quota_exceeded`). */
-            402: {
-                headers: {
-                    [name: string]: unknown;
-                };
-                content: {
-                    "application/json": components["schemas"]["Error"];
-                };
-            };
+            402: components["responses"]["PaymentRequired"];
             /** @description Endpoint not available (feature flag disabled). */
             404: {
                 headers: {
@@ -5556,11 +5629,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;
@@ -5676,7 +5749,7 @@ export interface operations {
                             endpoint: "screenshots" | "recordings" | "scrape" | "scrape_md" | "fetch" | "fetch_md" | "crawl" | "crawl_links" | "sitemap" | "monitors";
                             /** @description Raw upstream wire bytes for the endpoint. Screenshot and recording rows created before issue 2179 may reflect legacy billable Phase 1 bytes because exact raw totals cannot be recovered after per-job rounding. */
                             raw_bytes: number;
-                            /** @description Billing multiplier applied to raw bytes (e.g. 1.5 for screenshots/recordings/scrape_md/crawl, 1.0 otherwise). */
+                            /** @description Billing multiplier applied to raw bytes, enumerated for every `endpoint` value above — there is no catch-all default: 1.5 for `screenshots`, `recordings`, `scrape_md`, `fetch_md` and `crawl`; 1.0 for `scrape`, `fetch`, `crawl_links`, `sitemap` and `monitors`. Requesting Markdown output moves a request from the plain endpoint key to its `_md` key, so a Markdown scrape AND a Markdown fetch both bill at 1.5× (#3779). Source of truth: `ENDPOINT_BILLING_MULTIPLIER` in packages/scrape-shared/src/billing-multipliers.ts. */
                             multiplier: number;
                             /** @description raw_bytes × multiplier, rounded. */
                             billable_bytes: number;
@@ -5913,10 +5986,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.
@@ -6070,6 +6143,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;
@@ -6086,13 +6205,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. */
@@ -6106,6 +6240,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?: {
@@ -6207,13 +6375,13 @@ 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;
+                    amount_bytes?: 5000000000 | 25000000000 | 50000000000 | 75000000000 | 100000000000;
                     /** @description $1-$1000. Required when enabled. */
                     monthly_cap_cents?: number;
                 };

package/dist/resources/scrape.d.ts

@@ -29,7 +29,7 @@ export type TokenEncoding = 'cl100k_base' | 'o200k_base';
 /** Options for POST /v1/scrape. */
 export interface ScrapeOpts {
     url: string;
-    formats?: Array<'raw_html' | 'html' | 'markdown' | 'links' | 'images'>;
+    formats?: Array<'raw' | 'markdown' | 'links' | 'images'>;
     country?: string;
     delay_ms?: number;
     /** SERVER-side scrape budget in ms — how long the gateway may spend on the scrape itself. For the CLIENT-side abort budget (when this SDK gives up on the wire), see `RequestOptions.requestTimeoutMs`. */
@@ -65,11 +65,11 @@ export interface ScrapeOpts {
     token_encoding?: TokenEncoding;
     /** When true, emulate a mobile device (mobile UA + viewport). Default false (desktop). Part of the cache key, so mobile and desktop responses cache independently. */
     mobile?: boolean;
-    /** When true (default), base64-encoded `data:` image sources are stripped before markdown conversion and from `html` output. Set false to preserve them. Does not affect `raw_html`. */
+    /** When true (default), base64-encoded `data:` image sources are stripped before markdown conversion. Set false to preserve them. Does not affect `raw`. */
     remove_base64_images?: boolean;
-    /** HTML element names (not CSS selectors) to keep. When non-empty, only content within these elements is included in `html`/`markdown` output. Applied before `exclude_tags`. Does not affect `raw_html`. */
+    /** HTML element names (not CSS selectors) to keep. When non-empty, only content within these elements is included in `markdown` output. Applied before `exclude_tags`. Does not affect `raw`. */
     include_tags?: string[];
-    /** HTML element names (not CSS selectors) to strip from `html`/`markdown` output. Applied after `include_tags`. Does not affect `raw_html`. */
+    /** HTML element names (not CSS selectors) to strip from `markdown` output. Applied after `include_tags`. Does not affect `raw`. */
     exclude_tags?: string[];
     /** When true and `markdown` is in `formats`, the converted markdown is sent to Groq for cleaning before return. Graceful degradation on any Groq failure. Billing: 3× credits and bytes applied only when cleaning succeeds. */
     clean_markdown?: boolean;

package/dist/version.d.ts

@@ -5,4 +5,4 @@
  * outbound request carries — see the emit site in `client.ts`. The header name is spelled
  * only there, so issue #2905's pre-merge gate 1 counts exactly one occurrence in `src/`.
  */
-export declare const SDK_VERSION = "0.9.1";
+export declare const SDK_VERSION = "0.9.3";

package/dist/version.js

@@ -9,4 +9,4 @@
  * outbound request carries — see the emit site in `client.ts`. The header name is spelled
  * only there, so issue #2905's pre-merge gate 1 counts exactly one occurrence in `src/`.
  */
-export const SDK_VERSION = '0.9.1';
+export const SDK_VERSION = '0.9.3';

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@hunt-labs/bytekit-sdk",
-  "version": "0.9.1",
+  "version": "0.9.3",
   "description": "Official TypeScript SDK for the ByteKit API",
   "license": "MIT",
   "type": "module",