@hunt-labs/bytekit-sdk 0.10.0 → 0.11.0

package/CHANGELOG.md

@@ -10,6 +10,80 @@ today, see [README.md](./README.md), which remains the authoritative usage guide
 
 ## [Unreleased]
 
+## [0.11.0] - 2026-09-14
+
+### Added
+
+- **`solve_challenge` on `scrape.create` (#4447).** `ScrapeOpts` now carries
+  `solve_challenge?: boolean`, and the generated `ScrapeRequest` schema type carries the field
+  with its server default `false`. When `true`,
+  the scrape attempts to clear a Cloudflare challenge; success is not guaranteed. It is billed
+  as a normal browser render. A scrape that omits the option sends no `solve_challenge` key,
+  so existing calls are unchanged on the wire.
+- **`credits_scrape` on the usage response types (#4452).** The generated `GET /v1/usage`
+  response type and each `GET /v1/usage/daily` data item now carry `credits_scrape: number`:
+  credits drawn under the scrape usage source, such as `/v1/schema` extractions. The gateway
+  always charged this bucket but never returned it, so the published per-source credit fields
+  could not add up to `credits_used`.
+
+### Changed
+
+- **Internal `GET /v1/bulk` is cursor-paginated and its 100-job cap is gone (#4508).** The
+  generated `listBulk` types record a changed response shape: the operation used to return a
+  bare array of at most the 100 newest jobs, and now returns the same page envelope
+  `GET /v1/monitors` does, `{ data, next_cursor, has_more }`, plus `limit` and `cursor` query
+  parameters (`limit` is 1 to 100, default 25). A `status` filter and a `cursor` combine in
+  one request: `status` narrows the set and the cursor addresses a position inside it. The
+  operation's summary also no longer says "in-flight", which was wrong — it has always
+  returned jobs of every status, `cancelled` included. This is a breaking change to the wire
+  shape of an `x-sdk-scope: internal` operation; no SDK method calls it, so no published
+  method signature moves.
+- **`GET /v1/logs` `billing_multiplier` is the bandwidth factor, not a credit count (#4469).**
+  The generated logs-row type records the changed meaning of a public field: the value is now
+  `billable_bytes` / `raw_bytes` rounded to 2 decimal places — the factor the request settled
+  at, carrying the endpoint, cache-hit and clean-markdown factors, and the flat 1.5 Phase-1
+  factor on screenshots and recordings. It used to be the row's persisted `credits_charged`,
+  an account credit count charged per capture option, so two screenshots billed at the same
+  1.5 factor reported `2` and `1`. The 2 decimal places are load-bearing rather than
+  cosmetic: `billable_bytes` is itself rounded, so an odd byte basis would otherwise surface
+  as `1.500001943158721` instead of `1.5` on roughly half of all such rows. Every factor the
+  field can report is a multiple of 0.25, so 2 places is exact for any basis of 100 bytes or
+  more, and `raw_bytes` × `billing_multiplier` rounded to the nearest byte still reproduces
+  `billable_bytes`. The `billable_bytes` doc comment therefore no longer says it is NOT
+  `raw_bytes` × `billing_multiplier`. The field is also null on more rows than before: a
+  search or webhook row has no byte basis, a capture whose Phase 1 was skipped has a zero one,
+  and a capture old enough to predate the Phase-1 basis being recorded has none at all. One
+  residual is documented rather than fixed: a markdown `/v1/fetch` row completed before the
+  billing decomposition was recorded reports 1.0 where settlement charged 1.5, because nothing
+  on such a row distinguishes it. The type shapes are unchanged (`number | null`), and no SDK
+  method calls this endpoint.
+- **An all-null `/v1/schema` extraction your schema allows is validated again (#4490).** The
+  generated `/v1/schema` 200 response type records the exception to #4455's rule: an output
+  whose every leaf is `null` still arrives `validated: true` with the object intact, and is
+  charged, when the schema you sent declares `"null"` in the `type` union of every leaf the
+  output returned as `null`. Only that form counts — `nullable: true`, an `enum` containing
+  `null` and `const: null` do not, and a response that is itself `null` rather than an object is
+  never accepted however the root is declared. Everything else stays the #4455 miss. The `data`
+  doc comment now also states the other half: a `validated: true` response always carries an
+  object, never `null`. The type shapes are unchanged; only their doc comments moved.
+- **An all-null `/v1/schema` extraction is reported, not validated (#4455).** The generated
+  `/v1/schema` 200 response type documents a new additive warning code, `empty_extraction`: a
+  schema-valid output whose every leaf is `null` now arrives with `data: null` and
+  `validated: false`, and is not charged the per-request credits. Previously it arrived as
+  `validated: true` with the all-null object and no warning. The `data` and `validated` doc
+  comments now also say that every `validated: false` response carries `data: null`; the old
+  comment claimed exhausted retries returned the last raw output, which the API never did. The
+  type shapes are unchanged; only their doc comments moved.
+- **An inline `POST /v1/scrape` failure is documented with a persisted `id` (#4454).** The
+  gateway now records a sync scrape that ends `upstream_error` or `blocked` as a failed scrape
+  job, so its `failed` envelope carries that job's `sc_` id instead of `null`, `scrape.get(id)`
+  returns the same envelope, and the request appears in the dashboard Logs. The generated
+  `createScrape` 200 and `ScrapeErrorEnvelope` doc comments and the `scrape.create` doc comment
+  no longer say `id: null`. The type shapes are unchanged (`id` stays `string | null`), and
+  `scrape.create` still throws `ByteKitError` on that envelope exactly as before.
+- **Internal `GET /v1/logs` types list search and webhook rows (#4460).** Both `endpoint` enums
+  add `search` and `webhook`; a row's `source` is now `string | null`. No SDK method calls it.
+
 ## [0.10.0] - 2026-09-11
 
 ### Changed

package/dist/client.js

@@ -221,7 +221,7 @@ function parseJsonBody(text) {
  * The gateway used to report a terminal upstream fetch failure as HTTP 503, and
  * `!response.ok` in {@link ByteKit.send} was this SDK's only failure seam. Now that the
  * same outcome arrives as an intentional 200 — a definitive upstream result is not a
- * transport error, and `id` is `null` because the fetch failed before any job existed —
+ * transport error, and `id` names the failed job the gateway recorded it as —
  * that seam alone would let the failure resolve like a success and silence every caller's
  * `catch`. This restores the exception integrators already write code for, with the
  * envelope's own `code` and `message`.

package/dist/generated/api.d.ts

@@ -202,7 +202,7 @@ export interface paths {
          *     2. Otherwise, a request that needs a full page render — today that is `delay_ms > 0` — is **held open** until the render reaches a terminal state, then returns **200** with the content envelope (`success` or `failed`). If the render is still running when the hold window expires (28 seconds by default), the request returns the **202** receipt instead and the job continues in the background.
          *     3. Otherwise the request is served by the fast HTTP path and returns **200** with the content envelope, typically in under a second.
          *
-         *     **A failed fetch is a result, not a transport error.** An unreachable host, a refused connection, or a target whose bot protection defeats every proxy tier all come back on the same **200** as a `failed` envelope — never a 5xx. Narrow on the envelope's `status` before reading the body. A failure the fast path decides inline happens before any job row exists, so its envelope carries `id: null` and there is nothing to poll; a failure a held render reaches carries that render's real `id`. Either way the request transfers no billable bytes and is charged nothing.
+         *     **A failed fetch is a result, not a transport error.** An unreachable host, a refused connection, or a target whose bot protection defeats every proxy tier all come back on the same **200** as a `failed` envelope — never a 5xx. Narrow on the envelope's `status` before reading the body. A failure the fast path decides inline is recorded as a failed job, so its envelope normally carries that job's `id` and `GET /v1/scrape/{id}` returns the same envelope; if recording the failed job itself fails, the envelope still arrives on the same 200 with `id` set to `null` and there is nothing to poll. A failure a held render reaches carries that render's real `id`. Either way the request transfers no billable bytes and is charged nothing.
          *
          *     So a 202 means one of exactly two things: you asked for one with `async: true`, or the hold window expired. `wait_for_selector` and `wait_until` are `ScreenshotRequest` options, not `ScrapeRequest` options — sending either to this endpoint returns `422 validation_error`, so neither can produce a 202 here.
          */
@@ -391,9 +391,13 @@ export interface paths {
             cookie?: never;
         };
         /**
-         * List in-flight bulk jobs
-         * @description Returns the caller's bulk jobs, most recent first. Optionally filter
-         *     to a single status; when omitted, jobs of every status are returned.
+         * List bulk jobs
+         * @description Returns the caller's bulk jobs, most recent first, one cursor-paginated
+         *     page at a time. Optionally filter to a single status; when omitted, jobs
+         *     of every status are returned. `status` narrows the set and the cursor
+         *     addresses a position inside that already-ordered, already-filtered set,
+         *     so the two can be combined in one request. Follow `next_cursor` while
+         *     `has_more` is true.
          */
         get: operations["listBulk"];
         put?: never;
@@ -716,7 +720,7 @@ export interface paths {
         };
         /**
          * Get the unified request log feed
-         * @description Returns a unified, newest-first feed of the account's capture requests across scrape, fetch, screenshots, and recordings, for the dashboard /logs screen. Cursor-paginated; default range is the last 30 days, max 366 days.
+         * @description Returns a unified, newest-first feed of the account's requests across scrape, fetch, screenshots, recordings and search, plus webhook delivery attempts, for the dashboard /logs screen. Monitor runs are listed as the scrape and screenshots rows they produce (`source: monitor`). Cursor-paginated; default range is the last 30 days, max 366 days.
          */
         get: operations["getLogs"];
         put?: never;
@@ -795,11 +799,13 @@ export interface paths {
         get?: never;
         put?: never;
         /**
-         * One-time bandwidth purchase
-         * @description Creates a hosted Stripe Checkout session for a bandwidth top-up and
-         *     returns its URL. The caller redirects the user to `checkout_url`; the
-         *     balance is credited asynchronously by the `payment_intent.succeeded`
-         *     webhook once payment completes.
+         * One-time dollar deposit
+         * @description Creates a hosted Stripe Checkout session for a deposit into the account's
+         *     USD balance and returns its URL. The caller redirects the user to
+         *     `checkout_url`; the balance is credited asynchronously by the
+         *     `payment_intent.succeeded` webhook once payment completes. The balance
+         *     never expires and pays for usage beyond the included allowance, for
+         *     bandwidth and search credits alike, at the plan's rate when it is used.
          */
         post: operations["createTopup"];
         delete?: never;
@@ -808,29 +814,6 @@ export interface paths {
         patch?: never;
         trace?: never;
     };
-    "/v1/billing/credit-topup": {
-        parameters: {
-            query?: never;
-            header?: never;
-            path?: never;
-            cookie?: never;
-        };
-        get?: never;
-        put?: never;
-        /**
-         * One-time credit purchase
-         * @description Creates a hosted Stripe Checkout session for a credit top-up and returns
-         *     its URL. The caller redirects the user to `checkout_url`; credits are
-         *     added asynchronously by the `payment_intent.succeeded` webhook once
-         *     payment completes.
-         */
-        post: operations["createCreditTopup"];
-        delete?: never;
-        options?: never;
-        head?: never;
-        patch?: never;
-        trace?: never;
-    };
     "/v1/billing/cancel": {
         parameters: {
             query?: never;
@@ -924,8 +907,8 @@ export interface paths {
         get?: never;
         /**
          * Configure auto-topup
-         * @description Enable or disable automatic bandwidth top-ups. When enabling,
-         *     threshold_bytes, amount_bytes, and monthly_cap_cents must all be present;
+         * @description Enable or disable automatic top-ups of the USD balance. When enabling,
+         *     threshold_cents, amount_cents, and monthly_cap_cents must all be present;
          *     monthly_cap_cents may be null, which means no monthly cap.
          */
         put: operations["updateAutoTopup"];
@@ -1738,6 +1721,11 @@ export interface components {
              * @default false
              */
             mobile: boolean;
+            /**
+             * @description Attempts to clear a Cloudflare challenge; success is not guaranteed. Billed as a normal browser render.
+             * @default false
+             */
+            solve_challenge: boolean;
             /**
              * @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
@@ -1980,7 +1968,7 @@ export interface components {
             cache_age_s?: number;
         };
         /**
-         * @description The canonical terminal failure payload. It is returned inline on a `POST /v1/scrape` that fails upstream (HTTP 200, `id: null`), by `GET /v1/scrape/{id}` once a queued job has failed, and delivered to subscribers of `failed` with `X-ByteKit-Event: scrape.failed`.
+         * @description The canonical terminal failure payload. It is returned inline on a `POST /v1/scrape` that fails upstream (HTTP 200, `id` naming the failed job it is recorded as, or `null` in the rare case that recording itself failed), by `GET /v1/scrape/{id}` once a queued job has failed, and delivered to subscribers of `failed` with `X-ByteKit-Event: scrape.failed`.
          * @example {
          *       "schema_version": 1,
          *       "status": "failed",
@@ -2671,8 +2659,8 @@ export interface components {
             };
             auto_topup: {
                 enabled: boolean;
-                threshold_bytes: number;
-                amount_bytes: number;
+                threshold_cents: number;
+                amount_cents: number;
                 monthly_cap_cents: number;
             };
             /** Format: date-time */
@@ -2795,24 +2783,24 @@ export interface components {
             used_bytes: number;
             limit_bytes: number;
             remaining_bytes: number;
-            /** @description Total spendable bytes remaining across purchased top-up and starter-grant lots, after active refund reservations. */
+            /** @description Total spendable top-up bytes: the USD balance's current-plan estimate (`purchased_topup_bytes`) plus the starter grant. */
             topup_bytes: number;
-            /** @description Bytes remaining in purchased top-up lots, after active refund reservations. Starter-grant bytes are excluded. */
+            /** @description Estimate of the bytes the USD balance buys at the current plan's rate, after amounts held by open refunds. Not a separate balance: it changes when the plan changes. Starter-grant bytes are excluded. */
             purchased_topup_bytes: number;
-            /** @description Bytes remaining in starter-grant lots, after active refund reservations. Purchased top-up bytes are excluded. */
+            /** @description Bytes remaining in starter-grant lots, after active refund reservations. The USD balance estimate is 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. 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. */
+            /** @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 the USD balance, then the one-time starter grant. */
             rollover_bytes: number;
         };
         CreditBalance: {
             used: number;
             limit: number;
             remaining: number;
-            /** @description Total spendable credits remaining across purchased top-up and starter-grant lots, after active refund reservations. */
+            /** @description Total spendable top-up credits: the USD balance's current-plan estimate (`purchased_topup_credits`) plus the starter grant. */
             topup_credits: number;
-            /** @description Credits remaining in purchased top-up lots, after active refund reservations. Starter-grant credits are excluded. */
+            /** @description Estimate of the credits the USD balance buys at the current plan's rate, after amounts held by open refunds. Not a separate balance: it changes when the plan changes. Starter-grant credits are excluded. */
             purchased_topup_credits: number;
-            /** @description Credits remaining in starter-grant lots, after active refund reservations. Purchased top-up credits are excluded. */
+            /** @description Credits remaining in starter-grant lots, after active refund reservations. The USD balance estimate is 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;
@@ -3600,7 +3588,7 @@ export interface operations {
             };
         };
         responses: {
-            /** @description Scrape reached a terminal state and the body is that terminal envelope: `success` carrying content, or `failed` carrying the error envelope. Returned by the fast HTTP path in one round trip, and by a browser-path request without `async: true` once its render reaches a terminal state inside the hold window. A held render that ends in failure answers 200 with the same `failed` envelope `GET /v1/scrape/{id}` returns — narrow on `status` before reading the body. A definitive upstream outcome is a result, not a transport error: an unreachable host, a refused connection, or a target whose bot protection defeats every proxy tier all answer 200 with the `failed` envelope, never a 5xx. An inline failure ends before any job row exists, so its envelope carries `id: null` and there is nothing to poll; `error.http_status` is present only when a real upstream HTTP status is known. */
+            /** @description Scrape reached a terminal state and the body is that terminal envelope: `success` carrying content, or `failed` carrying the error envelope. Returned by the fast HTTP path in one round trip, and by a browser-path request without `async: true` once its render reaches a terminal state inside the hold window. A held render that ends in failure answers 200 with the same `failed` envelope `GET /v1/scrape/{id}` returns — narrow on `status` before reading the body. A definitive upstream outcome is a result, not a transport error: an unreachable host, a refused connection, or a target whose bot protection defeats every proxy tier all answer 200 with the `failed` envelope, never a 5xx. An inline failure is recorded as a failed job, so its envelope normally carries that job's `id` and polling it returns the same envelope; `id` is `null` only when recording the failed job itself failed. `error.http_status` is present only when a real upstream HTTP status is known. */
             200: {
                 headers: {
                     /** @description Stable scrape identifier (also present on the envelope as `id`). */
@@ -4615,6 +4603,9 @@ export interface operations {
     listBulk: {
         parameters: {
             query?: {
+                limit?: components["parameters"]["LimitParam"];
+                /** @description Pagination cursor from a previous response. */
+                cursor?: components["parameters"]["CursorParam"];
                 status?: "processing" | "completed" | "failed";
             };
             header?: never;
@@ -4630,27 +4621,31 @@ export interface operations {
                 };
                 content: {
                     "application/json": {
-                        /** @example bulk_01j9abc123 */
-                        id: string;
-                        /** @enum {string} */
-                        status: "processing" | "completed" | "failed";
-                        total: number;
-                        completed: number;
-                        failed: number;
-                        /** Format: date-time */
-                        created_at: string;
-                        /** Format: date-time */
-                        completed_at: string | null;
-                        /** @description Total credits billed for the job. Null until the job is billed. Fractional — credits are NUMERIC(10,2). */
-                        total_credits_charged: number | null;
-                        /** @description Null in GET responses (computed at submission time only). */
-                        estimated_credits: number | null;
-                        /** @description Webhook endpoint URL (HTTPS only; http:// rejected with 400 invalid_url, reason scheme_unsupported) */
-                        webhook_url: string;
-                    }[];
+                        next_cursor: string | null;
+                        has_more: boolean;
+                        data: {
+                            /** @example bulk_01j9abc123 */
+                            id: string;
+                            /** @enum {string} */
+                            status: "processing" | "completed" | "failed";
+                            total: number;
+                            completed: number;
+                            failed: number;
+                            /** Format: date-time */
+                            created_at: string;
+                            /** Format: date-time */
+                            completed_at: string | null;
+                            /** @description Total credits billed for the job. Null until the job is billed. Fractional — credits are NUMERIC(10,2). */
+                            total_credits_charged: number | null;
+                            /** @description Null in GET responses (computed at submission time only). */
+                            estimated_credits: number | null;
+                            /** @description Webhook endpoint URL (HTTPS only; http:// rejected with 400 invalid_url, reason scheme_unsupported) */
+                            webhook_url: string;
+                        }[];
+                    };
                 };
             };
-            /** @description Validation error. Returned when `status` is not one of the documented values. */
+            /** @description Validation error. Returned when `status` is not one of the documented values, or when `cursor` is not a cursor this endpoint issued. */
             422: {
                 headers: {
                     [name: string]: unknown;
@@ -5758,10 +5753,10 @@ export interface operations {
                 };
                 content: {
                     "application/json": {
-                        /** @description Extracted JSON conforming to the normalized schema, or `null` when the model returned a refusal. */
+                        /** @description Extracted JSON conforming to the normalized schema, or `null` when `validated` is `false` — see `validated` for the cases. A `validated: true` response always carries an object here, never `null`. */
                         data: Record<string, never> | null;
                         model: string;
-                        /** @description `true` when the output passed Ajv re-validation; `false` when retries were exhausted (`data` carries the last raw output, with `extract_validation_failed` in `warnings`). */
+                        /** @description `true` when the output passed Ajv re-validation and at least one leaf is non-null. An all-null output is also `true` when your schema explicitly allows it: every leaf the output returned as `null` sits at a node whose `type` is a union containing `"null"` in the schema you sent (only that form counts — `nullable: true`, an `enum` containing `null` and `const: null` do not). An output that is itself `null` rather than an object is never accepted, whatever your root schema declares. `false` (with `data: null`) when the model refused (`model_refusal`), when retries were exhausted (`extract_validation_failed`, `exhausted_retries`), or when a schema-valid output has every leaf `null` and is not one the declaration above accepts (`empty_extraction`). The per-request credits are charged only for `true`. */
                         validated: boolean;
                         metrics: {
                             scrape_ms: number;
@@ -5781,7 +5776,7 @@ export interface operations {
                             /** @description True when markdown exceeded the LLM token budget and was tail-truncated. */
                             truncated: boolean;
                         };
-                        /** @description Additive warning codes, e.g. `content_truncated`, `extract_validation_failed`, `exhausted_retries`, `model_refusal`. */
+                        /** @description Additive warning codes, e.g. `content_truncated`, `extract_validation_failed`, `exhausted_retries`, `model_refusal`, `empty_extraction`. */
                         warnings: string[];
                     };
                 };
@@ -5888,6 +5883,8 @@ export interface operations {
                         credits_single: number;
                         credits_bulk: number;
                         credits_monitor: number;
+                        /** @description Credits drawn under the scrape usage source this billing period, such as `/v1/schema` extractions. `credits_single`, `credits_bulk`, `credits_monitor`, `credits_scrape` and `credits_search` together sum to `credits_used`. */
+                        credits_scrape: number;
                         /** @description Credits consumed by the search endpoint this billing period. Reported as a distinct line item, not folded into other per-source credit counts. */
                         credits_search: number;
                         credits_limit: number;
@@ -5905,7 +5902,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 across purchased top-up lots and the one-time starter grant, already net of any overage consumed against them. Equal to topup_bytes. Present only in dual/bytes billing mode. */
+                        /** @description Remaining top-up bytes: the current-plan estimate of what the USD balance buys plus the one-time starter grant, already net of any overage consumed against them. Equal to topup_bytes. Present only in dual/bytes billing mode. */
                         topup_balance_bytes?: number;
                         /** @description Days elapsed since period_start. */
                         period_days_elapsed: number;
@@ -5915,13 +5912,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. The figure falls as those lots are 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 the USD balance's current-plan byte estimate and the starter grant. The figure falls as they 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. 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. */
+                        /** @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 the USD balance, then the one-time starter grant. */
                         rollover_bytes: number;
-                        /** @description Bytes remaining in purchased top-up and starter-grant lots. Subscription allowance is excluded. */
+                        /** @description The USD balance's current-plan byte estimate plus the starter grant. Subscription allowance is excluded. */
                         topup_bytes: number;
                         /** @description Total API requests in the current billing period. */
                         request_count: number;
@@ -5967,6 +5964,8 @@ export interface operations {
                             credits_single: number;
                             credits_bulk: number;
                             credits_monitor: number;
+                            /** @description Credits drawn under the scrape usage source on this day, such as `/v1/schema` extractions. */
+                            credits_scrape: number;
                             /** @description Credits consumed by the search endpoint on this day. */
                             credits_search: number;
                             credits_total: number;
@@ -6057,12 +6056,12 @@ export interface operations {
                 /** @description End date (YYYY-MM-DD), inclusive. Default today. */
                 to?: string;
                 /** @description Filter to a single endpoint kind. */
-                endpoint?: "scrape" | "fetch" | "screenshots" | "recordings";
+                endpoint?: "scrape" | "fetch" | "screenshots" | "recordings" | "search" | "webhook";
                 /** @description Filter by job outcome. */
                 status?: "pending" | "processing" | "completed" | "failed";
-                /** @description Case-insensitive substring match on the request URL. */
+                /** @description Case-insensitive substring match on the request URL — the search query on search rows and the target URL on webhook rows. */
                 url?: string;
-                /** @description Filter by API key (prefixed ID, e.g. `ak_xxx`). The key must belong to the requesting account; cross-account keys return an empty feed. Resolves the account's playground key too. */
+                /** @description Filter by API key (prefixed ID, e.g. `ak_xxx`). The key must belong to the requesting account; cross-account keys return an empty feed. Resolves the account's playground key too. Webhook delivery attempts are not issued by an API key, so this filter excludes them. */
                 api_key?: string;
                 /** @description Opaque pagination cursor from a prior response's `next_cursor`. */
                 cursor?: string;
@@ -6083,30 +6082,35 @@ export interface operations {
                 content: {
                     "application/json": {
                         data: {
-                            /** @description Prefixed request id (sc_/ss_/rec_). */
+                            /** @description Prefixed request id (sc_/ss_/rec_/sr_/wh_). */
                             id: string;
-                            /** @enum {string} */
-                            endpoint: "scrape" | "fetch" | "screenshots" | "recordings";
-                            /** @description HTTP method. Not persisted; capture endpoints are POST (so this is always "POST"). /v1/fetch also accepts GET, but the stored row cannot distinguish it. */
+                            /**
+                             * @description The request kind. `webhook` rows are webhook delivery attempts ByteKit sent to your endpoint, not requests you made.
+                             * @enum {string}
+                             */
+                            endpoint: "scrape" | "fetch" | "screenshots" | "recordings" | "search" | "webhook";
+                            /** @description HTTP method. Not persisted; capture and search endpoints are POST, and webhook deliveries are sent as POST (so this is always "POST"). /v1/fetch also accepts GET, but the stored row cannot distinguish it. */
                             method: string;
+                            /** @description The request URL. On a search row this is the search query (empty once the retention window has redacted it); on a webhook row it is the delivery target URL. */
                             url: string;
                             final_url?: string | null;
                             /**
-                             * @description Job outcome.
+                             * @description Job outcome. On a webhook row: `completed` = delivered, `processing` = a failed attempt that will be retried, `failed` = retries exhausted, `pending` = not yet delivered or failed (an attempt may be in flight).
                              * @enum {string}
                              */
                             status: "pending" | "processing" | "completed" | "failed";
-                            /** @description Upstream target HTTP status; scrape/fetch only. */
+                            /** @description Upstream target HTTP status on scrape/fetch rows; the HTTP status your endpoint answered on webhook rows. null on every other row. */
                             status_code?: number | null;
                             /** @description Raw upstream bytes the request carried (the billing base before the multiplier). null while pending/failed. */
                             raw_bytes?: number | null;
-                            /** @description The bytes this request was BILLED — the same amount its own response reported in `X-Billable-Bytes`. For a scrape or fetch request this is the settled decomposition replayed as it was recorded at completion, so it already carries every factor that applied: the endpoint factor (`scrape` 1.0, `scrape_md` 1.5, `fetch` 1.0, `fetch_md` 1.5, a monitor run 1.0), the cache-hit ×0.5, and the clean-markdown ×3. Screenshots and recordings are `raw_bytes` × the fixed 1.5 Phase-1 render factor whatever capture options they carried — capture billing composes no discount factor, so that product is exact. It is NOT `raw_bytes` × `billing_multiplier`: that field reports a CREDIT count, a different quantity from the byte factors above, and on a recordings row their product is not bytes at all. One residual: a scrape or fetch row completed before the decomposition was recorded is reconstructed from its endpoint and cache-hit factors, which leaves a markdown `/v1/fetch` request of that vintage reported at 1.0 rather than 1.5 — nothing on such a row distinguishes it. That population ages out of this feed's retention window and is not backfilled. null while pending/failed (the row has no byte basis yet). */
+                            /** @description The bytes this request was BILLED — the same amount its own response reported in `X-Billable-Bytes`. For a scrape or fetch request this is the settled decomposition replayed as it was recorded at completion, so it already carries every factor that applied: the endpoint factor (`scrape` 1.0, `scrape_md` 1.5, `fetch` 1.0, `fetch_md` 1.5, a monitor run 1.0), the cache-hit ×0.5, and the clean-markdown ×3. Screenshots and recordings are `raw_bytes` × the fixed 1.5 Phase-1 render factor whatever capture options they carried — capture billing composes no discount factor, so that product is exact. This is the settled amount itself, never a product reconstructed from another field: `billing_multiplier` below is DERIVED from it (that field is this value over `raw_bytes`), so the dependency runs this way and not the other. One residual: a scrape or fetch row completed before the decomposition was recorded is reconstructed from its endpoint and cache-hit factors, which leaves a markdown `/v1/fetch` request of that vintage reported at 1.0 rather than 1.5 — nothing on such a row distinguishes it. That population ages out of this feed's retention window and is not backfilled. null while pending/failed (the row has no byte basis yet). */
                             billable_bytes?: number | null;
-                            /** @description BASE billing multiplier persisted for this request — the settled `credits_charged` factor. It is NOT what `billable_bytes` above is derived from: that field reports settled BYTES, and multiplying `raw_bytes` by this credit count does not give the amount billed. Its scale is not uniform and is not a rate you can carry from one row to another: each endpoint persists its own credit unit, and the single and bulk paths of the same endpoint may persist different factors for identical options. Read this as the factor this one row settled at, and see https://bytekit.com/docs/billing/credits for what each endpoint charges. This is a LOGS ROW field and is NOT the scrape response envelope field — the envelope carries no flat `billing_multiplier` at all; its billing surface is the `billing` node (see BillingNode). This row reports only the base settled factor, so it can differ from `billing.multiplier` and from the X-Billing-Multiplier response header, both of which report the composed real-endpoint value. null while pending/failed. */
+                            /** @description The bandwidth factor this request settled at, DERIVED from the two fields above as `billable_bytes` / `raw_bytes`, ROUNDED TO 2 DECIMAL PLACES. It carries every factor that applied to the settled amount, composed: the endpoint factor, the cache-hit ×0.5 and the clean-markdown ×3 on a scrape or fetch row, and the flat 1.5 Phase-1 render factor on every screenshot and recording row whatever capture options it carried. Every factor reachable that way is a multiple of 0.25 (0.5, 0.75, 1, 1.5, 2.25, 3, 4.5), so 2 places reports each of them exactly on any basis of 100 bytes or more. The rounding is there because `billable_bytes` is itself rounded, which on an odd basis would otherwise surface here as 1.500001943158721 rather than 1.5. `raw_bytes` × `billing_multiplier`, rounded to the nearest byte, reproduces `billable_bytes` at every basis. CHANGED: this field used to report the row's persisted `credits_charged` — an account CREDIT count on a per-endpoint scale, not a bandwidth factor. On a screenshot that count is charged per capture option (`full_page`, `mobile`), so two captures billed at the same 1.5 factor reported different multipliers. See https://bytekit.com/docs/billing/credits for the credit counts each endpoint charges, which this field no longer reports. This is a LOGS ROW field and is NOT the scrape response envelope field — the envelope carries no flat `billing_multiplier` at all; its billing surface is the `billing` node (see BillingNode). It reports the same composed value as `billing.multiplier` and the X-Billing-Multiplier response header wherever `billable_bytes` is exact, which is every row but one: the residual described above for `billable_bytes`, a markdown `/v1/fetch` request completed before the decomposition was recorded, is reconstructed at 1.0 where settlement charged 1.5, and this field reports that same 1.0. null where the row has no factor to report: while pending/failed; on a search or webhook row (neither has a byte basis); where the basis is zero because Phase 1 was skipped or failed and the request billed nothing; and on a completed screenshot or recording old enough that no Phase-1 basis was ever recorded for it, which reports null rather than claiming a real past charge was nothing. */
                             billing_multiplier?: number | null;
+                            /** @description Request duration in milliseconds; on a webhook row, how long your endpoint took to answer the latest attempt. */
                             duration_ms?: number | null;
-                            /** @description How the request originated (single/bulk/monitor). */
-                            source?: string;
+                            /** @description How the request originated (single/bulk/monitor). null on search and webhook rows. */
+                            source?: string | null;
                             error_code?: string | null;
                             error_message?: string | null;
                             /** @description Prefixed key id (ak_) that issued the request. */
@@ -6272,81 +6276,10 @@ export interface operations {
             content: {
                 "application/json": {
                     /**
-                     * @description Bytes to purchase. Allowed tiers — 5, 25, 50, 75, 100 GB (1 GB = 1,000,000,000 bytes).
+                     * @description Amount to deposit, in US cents. Allowed amounts — $10, $25, $50, $100, $500. Charged exactly; the plan rate prices usage, not the deposit.
                      * @enum {integer}
                      */
-                    bytes: 5000000000 | 25000000000 | 50000000000 | 75000000000 | 100000000000;
-                    /**
-                     * Format: uri
-                     * @description Redirect target after a completed Checkout.
-                     */
-                    success_url: string;
-                    /**
-                     * Format: uri
-                     * @description Redirect target when the user abandons Checkout.
-                     */
-                    cancel_url: string;
-                };
-            };
-        };
-        responses: {
-            /** @description Hosted Checkout session created. */
-            200: {
-                headers: {
-                    [name: string]: unknown;
-                };
-                content: {
-                    "application/json": {
-                        /** Format: uri */
-                        checkout_url: string;
-                        session_id: string;
-                    };
-                };
-            };
-            /** @description No customer or free plan. */
-            400: {
-                headers: {
-                    [name: string]: unknown;
-                };
-                content: {
-                    "application/json": components["schemas"]["Error"];
-                };
-            };
-            /** @description Validation error (missing/invalid fields). */
-            422: {
-                headers: {
-                    [name: string]: unknown;
-                };
-                content: {
-                    "application/json": components["schemas"]["Error"];
-                };
-            };
-            /** @description Stripe error creating the Checkout session. */
-            502: {
-                headers: {
-                    [name: string]: unknown;
-                };
-                content: {
-                    "application/json": components["schemas"]["Error"];
-                };
-            };
-        };
-    };
-    createCreditTopup: {
-        parameters: {
-            query?: never;
-            header?: never;
-            path?: never;
-            cookie?: never;
-        };
-        requestBody: {
-            content: {
-                "application/json": {
-                    /**
-                     * @description Credits to purchase. Allowed tiers — 1k, 10k, 25k, 50k, 100k.
-                     * @enum {integer}
-                     */
-                    credits: 1000 | 10000 | 25000 | 50000 | 100000;
+                    amount_cents: 1000 | 2500 | 5000 | 10000 | 50000;
                     /**
                      * Format: uri
                      * @description Redirect target after a completed Checkout.
@@ -6641,10 +6574,17 @@ export interface operations {
                         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;
+                        /** @description The account's USD top-up balance. It never expires and is spent on usage beyond the included allowance, at the rate of the plan in force when the usage happens. */
+                        usd_balance: {
+                            /** @description Balance in whole US cents, rounded down. Can be negative when usage settled after the balance ran out. */
+                            cents: number;
+                            /** @description Part of `cents` held by an open refund and not spendable, in whole US cents, rounded down. */
+                            reserved_cents: number;
+                        };
                         auto_topup: {
                             enabled: boolean;
-                            threshold_bytes: number | null;
-                            amount_bytes: number | null;
+                            threshold_cents: number | null;
+                            amount_cents: number | null;
                             monthly_cap_cents: number | null;
                             monthly_spend_cents: number;
                         };
@@ -6664,13 +6604,10 @@ export interface operations {
             content: {
                 "application/json": {
                     enabled: boolean;
-                    /** @description Min 1 MB (1,000,000 bytes). Required when enabled. */
-                    threshold_bytes?: number;
-                    /**
-                     * @description Allowed tiers — 5, 25, 50, 75, 100 GB (1 GB = 1,000,000,000 bytes). Required when enabled.
-                     * @enum {integer}
-                     */
-                    amount_bytes?: 5000000000 | 25000000000 | 50000000000 | 75000000000 | 100000000000;
+                    /** @description Top up when the remaining value (plan allowance plus USD balance, priced at the plan's top-up rate) drops below this many US cents. Min $1. Required when enabled. */
+                    threshold_cents?: number;
+                    /** @description US cents added to the USD balance on each auto top-up, $5-$1000. Required when enabled. */
+                    amount_cents?: number;
                     /** @description $1-$1000, or null for no monthly cap. Required when enabled — send an explicit null to remove the cap; omitting the key is rejected. */
                     monthly_cap_cents?: number | null;
                 };
@@ -6685,8 +6622,8 @@ export interface operations {
                 content: {
                     "application/json": {
                         enabled: boolean;
-                        threshold_bytes: number | null;
-                        amount_bytes: number | null;
+                        threshold_cents: number | null;
+                        amount_cents: number | null;
                         monthly_cap_cents: number | null;
                     };
                 };

package/dist/resources/scrape.d.ts

@@ -22,7 +22,7 @@ import type { ScrapeId, BulkId } from '../types.js';
  *    so a receipt can arrive without your ever asking for one.
  * 3. Otherwise the fast HTTP path returns the 200 content envelope, typically
  *    in under a second. A fetch that fails outright is a `failed` envelope on
- *    that same 200, with `id: null`, because it ends before any job exists.
+ *    that same 200; its `id` names the failed job, which `scrape.get(id)` returns.
  *
  * So a 202 is never a surprise: you either asked for it, or the hold expired.
  */
@@ -85,6 +85,8 @@ export interface ScrapeOpts {
     token_budget?: number;
     /** Tokenizer encoding hint for `token_budget`. `cl100k_base` (default) matches GPT-4/4o; `o200k_base` matches GPT-4o-mini / o-series. */
     token_encoding?: TokenEncoding;
+    /** Attempts to clear a Cloudflare challenge; success is not guaranteed. Billed as a normal browser render. */
+    solve_challenge?: boolean;
     /** 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. Set false to preserve them. Does not affect `raw`. */

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.10.0";
+export declare const SDK_VERSION = "0.11.0";

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

package/package.json

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