@hunt-labs/bytekit-sdk 0.9.0 → 0.9.2

package/CHANGELOG.md

@@ -10,6 +10,58 @@ today, see [README.md](./README.md), which remains the authoritative usage guide
 
 ## [Unreleased]
 
+## [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
+
+- The generated `paths` type for the `200` of `GET /v1/scrape/bulk/{id}` now declares `items`
+  (#3632). The route builds one body and varies only the status code, so the terminal `200`
+  has always carried the per-URL scrape envelopes — but only the `202` documented them, so
+  `scrape.bulk.get()` typed the results away at exactly the poll that has them. Types only:
+  the field was already on the wire, and server behavior is unchanged.
+
+- The generated `paths` types now describe the `202` that `GET /v1/scrape/bulk/{id}`,
+  `GET /v1/fetch/bulk/{id}` and `GET /v1/bulk/{id}` already serve while a bulk job is
+  non-terminal (#3533). Each of the three returns 202 with the job envelope until the job is
+  terminal and 200 afterwards, but only the 200 was declared, so anything typed off the spec
+  had no shape for the response the very first poll receives. Types only: `scrape.bulk.get()`,
+  `fetch.bulk.get()` and `bulk.get()` already resolved the body on any 2xx, and server behavior
+  is unchanged.
+
+### Changed
+
+- The generated `topup_balance_bytes` description on `GET /v1/usage` now states that the value is
+  the remaining purchased top-up bytes, already net of any overage consumed against them (#3459).
+  Types only: the field's name, type and wire format are unchanged. The server previously
+  subtracted the consumed overage a second time when computing this value, so the number a client
+  reads is larger than before for accounts that ran past their included allowance.
+
 ## [0.9.0] - 2026-08-20
 
 ### Removed

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

@@ -1521,10 +1521,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 +1539,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 +1574,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 +1592,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 +1672,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 +1711,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": [
          *           {
@@ -2147,6 +2148,7 @@ export interface components {
              * @description Webhook endpoint URL (HTTPS only; http:// rejected with 400 invalid_url, reason scheme_unsupported)
              */
             webhook_url: string;
+            /** @description HMAC secret used to sign webhook deliveries. Each delivery carries `X-Webhook-Timestamp` and `X-Webhook-Signature` (`sha256=` + the hex HMAC-SHA256 of `timestamp.body`). See https://bytekit.com/docs/guides/webhooks for verification code. */
             webhook_secret?: string;
             /** @description Max 20 headers. Keys must match /^[A-Za-z0-9-]+$/ and not be reserved. */
             webhook_headers?: {
@@ -2176,6 +2178,7 @@ export interface components {
              * @description Webhook endpoint URL (HTTPS only; http:// rejected with 400 invalid_url, reason scheme_unsupported)
              */
             webhook_url?: string;
+            /** @description HMAC secret used to sign webhook deliveries. Each delivery carries `X-Webhook-Timestamp` and `X-Webhook-Signature` (`sha256=` + the hex HMAC-SHA256 of `timestamp.body`). See https://bytekit.com/docs/guides/webhooks for verification code. */
             webhook_secret?: string;
             webhook_headers?: {
                 [key: string]: string;
@@ -2236,7 +2239,7 @@ export interface components {
         };
         MonitorCreateResponse: components["schemas"]["MonitorResponse"] & {
             /**
-             * @description The webhook signing secret — returned **once** at creation time only. Subsequent GET requests omit this field. Always present on a create response (`webhook_url` is required on create). Format: 64 lowercase hex characters (32 bytes of entropy).
+             * @description The webhook signing secret — returned **once** at creation time only. Subsequent GET requests omit this field. Always present on a create response (`webhook_url` is required on create). Format: 64 lowercase hex characters (32 bytes of entropy). Use it to verify the `X-Webhook-Signature` header on each delivery — see https://bytekit.com/docs/guides/webhooks.
              * @example a3f1b2c4d5e6f7a8b9c0d1e2f3a4b5c6d7e8f9a0b1c2d3e4f5a6b7c8d9e0f1a2
              */
             webhook_secret?: string;
@@ -2285,7 +2288,10 @@ export interface components {
              * @description Optional webhook endpoint URL (HTTPS only; http:// rejected with 400 invalid_url, reason scheme_unsupported). When omitted, no `sitemap.completed`/`sitemap.failed` webhook is delivered and the job is poll-only via `GET /v1/sitemap/{id}`. When present, delivery is unchanged. `webhook_secret` is ignored when `webhook_url` is absent.
              */
             webhook_url?: string;
-            /** @default null */
+            /**
+             * @description HMAC secret used to sign webhook deliveries. Each delivery carries `X-Webhook-Timestamp` and `X-Webhook-Signature` (`sha256=` + the hex HMAC-SHA256 of `timestamp.body`). See https://bytekit.com/docs/guides/webhooks for verification code.
+             * @default null
+             */
             webhook_secret: string | null;
             /**
              * @description Max 90 days.
@@ -2522,7 +2528,10 @@ export interface components {
             };
             /** Format: date-time */
             cancelled_at: string | null;
-            /** Format: date-time */
+            /**
+             * Format: date-time
+             * @description Reserved, and always `null` today: it reflects the account's cancellation grace deadline, which no current code path sets. It is not the payment-failure grace period — that deadline is tracked per invoice (7 days from the failed payment) in `billing_dunning_graces` and is not exposed on this response.
+             */
             grace_period_expires_at: string | null;
             /** Format: date-time */
             created_at: string;
@@ -2607,6 +2616,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. */
             rollover_bytes: number;
         };
         CreditBalance: {
@@ -2619,10 +2629,52 @@ export interface components {
             purchased_topup_credits: number;
             /** @description Credits remaining in starter-grant lots, after active refund reservations. Purchased top-up credits are excluded. */
             granted_topup_credits: number;
+            /** @description Always `0`. Search credits do not carry over between billing periods; the field is retained for contract stability and will not become non-zero without an announced plan change. */
             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
@@ -2663,8 +2715,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. */
@@ -3168,6 +3220,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: {
@@ -3197,6 +3253,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: {
@@ -3222,15 +3282,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):
@@ -3262,6 +3314,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: {
@@ -3339,7 +3395,7 @@ export interface operations {
                  * @example {
                  *       "url": "https://example.com",
                  *       "formats": [
-                 *         "raw_html",
+                 *         "raw",
                  *         "markdown"
                  *       ],
                  *       "markdown_mode": "article",
@@ -3386,7 +3442,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;
@@ -3416,6 +3472,10 @@ export interface operations {
                     "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: {
@@ -3429,6 +3489,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: {
@@ -3454,6 +3518,7 @@ export interface operations {
                     "application/json": components["schemas"]["Error"];
                 };
             };
+            402: components["responses"]["PaymentRequired"];
             /** @description Validation error. */
             422: {
                 headers: {
@@ -3529,7 +3594,7 @@ export interface operations {
                  *         {
                  *           "url": "https://example.com",
                  *           "formats": [
-                 *             "raw_html",
+                 *             "raw",
                  *             "markdown"
                  *           ],
                  *           "custom": {
@@ -3545,7 +3610,7 @@ export interface operations {
                  *       ],
                  *       "defaults": {
                  *         "formats": [
-                 *           "raw_html"
+                 *           "raw"
                  *         ],
                  *         "country": "US"
                  *       },
@@ -3562,7 +3627,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;
@@ -3592,10 +3657,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 */
@@ -3619,6 +3684,7 @@ export interface operations {
                      * @description Webhook endpoint URL (HTTPS only; http:// rejected with 400 invalid_url, reason scheme_unsupported)
                      */
                     webhook_url: string;
+                    /** @description HMAC secret used to sign webhook deliveries. Each delivery carries `X-Webhook-Timestamp` and `X-Webhook-Signature` (`sha256=` + the hex HMAC-SHA256 of `timestamp.body`). See https://bytekit.com/docs/guides/webhooks for verification code. */
                     webhook_secret?: string;
                     metadata?: components["schemas"]["Metadata"];
                     /**
@@ -3640,6 +3706,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: {
@@ -3683,6 +3753,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
@@ -3739,6 +3810,43 @@ export interface operations {
                         estimated_credits: number | null;
                         /** @description Webhook endpoint URL (HTTPS only; http:// rejected with 400 invalid_url, reason scheme_unsupported) */
                         webhook_url: string;
+                        /** @description Rehydrated per-URL scrape envelopes — the terminal page of results (default 100 rows, `?limit=` up to 500). `routes/scrape-bulk.ts` spreads this key into the SAME body on both status branches, so it is present here exactly as it is on the 202; on the 200 the entries carry their final success or error envelopes (issue #3632). */
+                        items: components["schemas"]["ScrapeEnvelope"][];
+                    };
+                };
+            };
+            /**
+             * @description Bulk job still processing. `routes/scrape-bulk.ts` ends the poll handler
+             *     with `status: isTerminal ? 200 : 202` over an identical body, so this is
+             *     the SAME envelope the 200 documents — only the status code and the
+             *     reachable `status` values differ. Keep polling until you get a 200
+             *     (issue #3533).
+             */
+            202: {
+                headers: {
+                    [name: string]: unknown;
+                };
+                content: {
+                    "application/json": {
+                        /** @example bulk_01j9abc123 */
+                        id: string;
+                        /** @enum {string} */
+                        status: "processing";
+                        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 Rehydrated per-URL scrape envelopes — the same page the 200 returns (default 100 rows, `?limit=` up to 500). While the job is non-terminal most entries carry the `queued` envelope. */
+                        items: components["schemas"]["ScrapeEnvelope"][];
                     };
                 };
             };
@@ -3794,6 +3902,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: {
@@ -3809,6 +3921,7 @@ export interface operations {
                     "application/json": components["schemas"]["Error"];
                 };
             };
+            402: components["responses"]["PaymentRequired"];
             /** @description Validation error (e.g. slow-path-only field). */
             422: {
                 headers: {
@@ -3915,6 +4028,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: {
@@ -3930,6 +4047,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: {
@@ -4019,6 +4137,7 @@ export interface operations {
                      * @description Webhook endpoint URL (HTTPS only; http:// rejected with 400 invalid_url, reason scheme_unsupported)
                      */
                     webhook_url: string;
+                    /** @description HMAC secret used to sign webhook deliveries. Each delivery carries `X-Webhook-Timestamp` and `X-Webhook-Signature` (`sha256=` + the hex HMAC-SHA256 of `timestamp.body`). See https://bytekit.com/docs/guides/webhooks for verification code. */
                     webhook_secret?: string;
                     metadata?: components["schemas"]["Metadata"];
                 };
@@ -4028,6 +4147,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: {
@@ -4071,6 +4194,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
@@ -4154,6 +4278,72 @@ export interface operations {
                     };
                 };
             };
+            /**
+             * @description Bulk job still processing. `routes/fetch-bulk.ts` ends the poll handler
+             *     with `status: isTerminal ? 200 : 202` over an identical body, so this is
+             *     the SAME envelope the 200 documents — only the status code and the
+             *     reachable `status` values differ. Keep polling until you get a 200; a
+             *     **cancelled** job stays on this branch forever (issue #3533).
+             *
+             *     Item `content_url` values are pre-signed exactly as on the 200 — a fresh
+             *     600-second signature on every poll.
+             */
+            202: {
+                headers: {
+                    [name: string]: unknown;
+                };
+                content: {
+                    "application/json": {
+                        /** @example bulk_01j9abc123 */
+                        id: string;
+                        /** @enum {string} */
+                        status: "processing" | "cancelled";
+                        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;
+                            /**
+                             * @description Itemised account of this item's charge — the basis, the named factors
+                             *     that composed the multiplier, and the resulting billed bytes. Omitted
+                             *     for rows that completed before the billing node was persisted.
+                             */
+                            billing?: components["schemas"]["BillingNode"];
+                            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. */
             404: {
                 headers: {
@@ -4244,7 +4434,7 @@ export interface operations {
                  *           "type": "scrape",
                  *           "formats": [
                  *             "markdown",
-                 *             "html"
+                 *             "raw"
                  *           ],
                  *           "include_html": true,
                  *           "wait_until": "networkidle",
@@ -4260,7 +4450,7 @@ export interface operations {
                  *         "device": "desktop",
                  *         "country": "US",
                  *         "formats": [
-                 *           "raw_html"
+                 *           "raw"
                  *         ],
                  *         "device_scale_factor": 2
                  *       },
@@ -4297,7 +4487,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;
@@ -4350,7 +4540,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}
@@ -4376,6 +4566,7 @@ export interface operations {
                      * @description Webhook endpoint URL (HTTPS only; http:// rejected with 400 invalid_url, reason scheme_unsupported)
                      */
                     webhook_url: string;
+                    /** @description HMAC secret used to sign webhook deliveries. Each delivery carries `X-Webhook-Timestamp` and `X-Webhook-Signature` (`sha256=` + the hex HMAC-SHA256 of `timestamp.body`). See https://bytekit.com/docs/guides/webhooks for verification code. */
                     webhook_secret?: string;
                     metadata?: components["schemas"]["Metadata"];
                 };
@@ -4385,6 +4576,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: {
@@ -4428,6 +4623,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
@@ -4491,6 +4687,38 @@ export interface operations {
                     };
                 };
             };
+            /**
+             * @description Bulk job still processing. `routes/bulk.ts` ends the poll handler with
+             *     `status: isTerminal ? 200 : 202` over an identical body, so this is the
+             *     SAME envelope the 200 documents — only the status code and the reachable
+             *     `status` values differ. Keep polling until you get a 200 (issue #3533).
+             */
+            202: {
+                headers: {
+                    [name: string]: unknown;
+                };
+                content: {
+                    "application/json": {
+                        /** @example bulk_01j9abc123 */
+                        id: string;
+                        /** @enum {string} */
+                        status: "processing";
+                        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 Resource not found. */
             404: {
                 headers: {
@@ -4915,6 +5143,7 @@ export interface operations {
                     "application/json": components["schemas"]["Error"];
                 };
             };
+            402: components["responses"]["PaymentRequired"];
             /** @description Validation error. */
             422: {
                 headers: {
@@ -5119,15 +5348,7 @@ export interface operations {
                     "application/json": components["schemas"]["Error"];
                 };
             };
-            /** @description Payment required — the account is out of credits. */
-            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: {
@@ -5289,15 +5510,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: {
@@ -5398,7 +5611,7 @@ export interface operations {
                         plan_type: "payg" | "subscription";
                         /** @description Total top-up spend in cents for this billing period. Present only in dual/bytes billing mode. */
                         topup_spent_cents?: number;
-                        /** @description Remaining top-up bytes: max(0, topup_bytes − max(0, bytes_used − included_bytes − rollover_bytes)). Present only in dual/bytes billing mode. */
+                        /** @description Remaining purchased top-up bytes, already net of any overage consumed against them. Equal to topup_bytes. Present only in dual/bytes billing mode. */
                         topup_balance_bytes?: number;
                         /** @description Days elapsed since period_start. */
                         period_days_elapsed: number;
@@ -5408,9 +5621,13 @@ 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. */
                         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. */
                         rollover_bytes: number;
+                        /** @description Bytes remaining in purchased top-up and starter-grant lots. Subscription allowance is excluded. */
                         topup_bytes: number;
                         /** @description Total API requests in the current billing period. */
                         request_count: number;
@@ -5524,7 +5741,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;
@@ -6028,7 +6245,7 @@ export interface operations {
                             /** @description Whether the authenticated account's plan supports bandwidth top-up purchases. False for free and PAYG plans. The frontend should disable or hide the Buy Bandwidth affordance when this is false. */
                             available: boolean;
                         };
-                        /** @description The number of bandwidth bytes included in the account's current plan allotment (before any rollover or top-up bytes). Use this value instead of computing plan allotment client-side from `limit_bytes - rollover_bytes - topup_bytes`. */
+                        /** @description The bandwidth allotment configured on the account's current plan (before any rollover or top-up bytes). Use this value instead of computing the plan allotment client-side from `limit_bytes - rollover_bytes - topup_bytes`: the allowance actually granted is the lot written when the period's invoice was paid, so the two can differ before the first paid invoice of a plan. */
                         included_bytes?: number;
                         /** @description Number of automatic top-up transactions (bandwidth and credit) that have been triggered in the current calendar month. Includes both pending and completed transactions. */
                         triggers_this_month?: 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.0";
+export declare const SDK_VERSION = "0.9.2";

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.0';
+export const SDK_VERSION = '0.9.2';

package/package.json

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