@hunt-labs/bytekit-sdk 0.11.5 → 0.11.7

package/CHANGELOG.md

@@ -10,6 +10,24 @@ today, see [README.md](./README.md), which remains the authoritative usage guide
 
 ## [Unreleased]
 
+## [0.11.7] - 2026-09-29
+
+### Changed
+
+- **Internal `GET /v1/billing/topup-balance` types add `bandwidth.debt_bytes` (#4960, #4975).**
+  The bytes the account still owes for bandwidth a finished request used beyond everything it
+  could pay for, net of any repaid. Declared on that endpoint only, not on the shared
+  `BandwidthBalance` schema `GET /v1/usage` returns. No SDK method calls it.
+
+## [0.11.6] - 2026-09-24
+
+### Changed
+
+- Regenerated `src/generated/api.d.ts` (#4865): a documentation-wording correction to the
+  `POST /v1/schema` billing description, which now says the page bandwidth is billed at its
+  upstream wire bytes with no endpoint factor instead of "exactly like `/v1/scrape`". No
+  behavior change: doc comments only, no SDK signature moves.
+
 ## [0.11.5] - 2026-09-22
 
 ### Changed

package/README.md

@@ -358,7 +358,7 @@ try {
 
 Note that `details` is populated only from the API's canonical
 `{ error: { … } }` envelope. A few endpoints answer with a flat, vendor-masked
-body instead (`/v1/search` returns `502 {"error":"search_provider_error"}`);
+body instead (`/v1/search` returns `503 {"error":"search_provider_error"}`);
 those carry no structured detail, so `err.details` stays `undefined` there —
 `err.code` is still the machine-readable reason.
 

package/dist/client.d.ts

@@ -103,7 +103,7 @@ export declare class ByteKitError extends Error {
      * The envelope's `error.details`, when it carried one — `undefined` otherwise.
      *
      * Populated ONLY from the canonical `{ error: { … } }` envelope. A flat
-     * vendor-masked body (`/v1/search` 502 `{"error":"search_provider_error"}`)
+     * vendor-masked body (`/v1/search` 503 `{"error":"search_provider_error"}`)
      * has no envelope to read a detail from, so it never grows one (#2685 E3).
      *
      * A `details` that is not a JSON object — which the untyped spec field

package/dist/client.js

@@ -470,9 +470,9 @@ export class ByteKit {
                         }
                     }
                     else if (typeof json.error === 'string' && json.error.length > 0) {
-                        // Flat vendor-masked shape, e.g. /v1/search 502
+                        // Flat vendor-masked shape, e.g. /v1/search 503
                         // {"error":"search_provider_error"} (docs/api/openapi.yaml §/v1/search
-                        // 502). The string IS the error code. `message` falls back to it only
+                        // 503). The string IS the error code. `message` falls back to it only
                         // when the response carried no statusText, so the thrown error is
                         // never message-empty.
                         code = json.error;

package/dist/generated/api.d.ts

@@ -640,7 +640,8 @@ export interface paths {
          *     `wait_for_selector`) cause a `400 unsupported_option`.
          *
          *     Dual-axis billing: a fixed per-request credit charge **plus** the
-         *     underlying page's bandwidth, billed exactly like `/v1/scrape`. The
+         *     underlying page's bandwidth, billed at its upstream wire bytes with no
+         *     endpoint factor (a 100 KiB estimate is pre-charged, then reconciled). The
          *     bandwidth is still billed when the scrape succeeds but extraction later
          *     fails; both axes are refunded only when the scrape itself never runs.
          *
@@ -2837,10 +2838,13 @@ export interface components {
          *     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`,
+         *     - `quota_exceeded` — the enforced balance for this request's meter
+         *       cannot fund it. Capture endpoints (`/v1/scrape`, `/v1/fetch`,
          *       `/v1/screenshots`, `/v1/sitemap` and the bulk siblings) meter
-         *       bandwidth; `/v1/search` meters credits.
+         *       bandwidth: they reject when the balance cannot fund the request's
+         *       byte reservation, and `error.details.required_bytes` and
+         *       `error.details.available_bytes` report the bytes the request reserves
+         *       and the bytes available. `/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`.
@@ -2863,9 +2867,13 @@ export interface components {
                  *       "status": "failed",
                  *       "error": {
                  *         "code": "quota_exceeded",
-                 *         "message": "Monthly bandwidth quota exhausted.",
+                 *         "message": "Insufficient bandwidth balance: this request reserves 102400 bytes and 4321 are available.",
                  *         "http_status": 402,
-                 *         "failed_at": "2026-01-15T12:00:00Z"
+                 *         "failed_at": "2026-01-15T12:00:00Z",
+                 *         "details": {
+                 *           "required_bytes": 102400,
+                 *           "available_bytes": 4321
+                 *         }
                  *       }
                  *     }
                  */
@@ -4175,35 +4183,20 @@ export interface operations {
                     "application/json": components["schemas"]["Error"];
                 };
             };
-            /**
-             * @description Content transform failed, or a non-2xx upstream response relayed as the unified
-             *     Error envelope. On an upstream relay the HTTP status equals the upstream status
-             *     (code `upstream_error`), so any 4xx/5xx the target returns surfaces here as an
-             *     Error envelope rather than a raw body (#1462).
-             *
-             *     **One divergence.** An upstream `502` is relayed at HTTP `503`, not `502` — see
-             *     the `503` response below. A fetch service that cannot be reached also answers
-             *     `503`, not `502` (#3373); this status no longer covers that condition.
-             */
-            502: {
-                headers: {
-                    [name: string]: unknown;
-                };
-                content: {
-                    "application/json": components["schemas"]["Error"];
-                };
-            };
             /**
              * @description Two distinct conditions answer `503`, and they disagree about what the body's
              *     `error.http_status` reports. Read `error.code` to tell them apart.
              *
-             *     - **`upstream_error`** — the target returned HTTP `502`, relayed here as `503`.
-             *       Cloudflare fronts this API and replaces a clean origin 502 with its own generic
-             *       `text/plain` error page, discarding the envelope before it reaches you, while a
-             *       503 is passed through unchanged. The body's `error.http_status` still reports
-             *       the **true upstream status**, `502` — not `503` — and is the only surviving
-             *       record of what the target answered, so the body rather than the HTTP status is
-             *       authoritative here (#3355).
+             *     - **`upstream_error`** — the target returned HTTP `502` or `504`, relayed here as
+             *       `503`. Cloudflare fronts this API and replaces a clean origin 502 or 504 with its
+             *       own generic `text/plain` error page, discarding the envelope before it reaches
+             *       you, while a 503 is passed through unchanged. The body's `error.http_status`
+             *       still reports the **true upstream status**, `502` or `504` — not `503` — and is
+             *       the only surviving record of what the target answered, so the body rather than
+             *       the HTTP status is authoritative here (#3355, #4891). Every other non-2xx
+             *       upstream response is relayed at its own HTTP status with the same
+             *       `upstream_error` envelope, so any other 4xx/5xx the target returns surfaces as an
+             *       Error envelope rather than a raw body (#1462).
              *     - **`internal_error`** (message `Fetch service unavailable.`) — no fetch service
              *       endpoint could be resolved on this deployment, a fault of this API and not of the
              *       target. There is no upstream status to preserve: the `503` is this API's own
@@ -4325,35 +4318,20 @@ export interface operations {
                     "application/json": components["schemas"]["Error"];
                 };
             };
-            /**
-             * @description Content transform failed, or a non-2xx upstream response relayed as the unified
-             *     Error envelope. On an upstream relay the HTTP status equals the upstream status
-             *     (code `upstream_error`), so any 4xx/5xx the target returns surfaces here as an
-             *     Error envelope rather than a raw body (#1462).
-             *
-             *     **One divergence.** An upstream `502` is relayed at HTTP `503`, not `502` — see
-             *     the `503` response below. A fetch service that cannot be reached also answers
-             *     `503`, not `502` (#3373); this status no longer covers that condition.
-             */
-            502: {
-                headers: {
-                    [name: string]: unknown;
-                };
-                content: {
-                    "application/json": components["schemas"]["Error"];
-                };
-            };
             /**
              * @description Two distinct conditions answer `503`, and they disagree about what the body's
              *     `error.http_status` reports. Read `error.code` to tell them apart.
              *
-             *     - **`upstream_error`** — the target returned HTTP `502`, relayed here as `503`.
-             *       Cloudflare fronts this API and replaces a clean origin 502 with its own generic
-             *       `text/plain` error page, discarding the envelope before it reaches you, while a
-             *       503 is passed through unchanged. The body's `error.http_status` still reports
-             *       the **true upstream status**, `502` — not `503` — and is the only surviving
-             *       record of what the target answered, so the body rather than the HTTP status is
-             *       authoritative here (#3355).
+             *     - **`upstream_error`** — the target returned HTTP `502` or `504`, relayed here as
+             *       `503`. Cloudflare fronts this API and replaces a clean origin 502 or 504 with its
+             *       own generic `text/plain` error page, discarding the envelope before it reaches
+             *       you, while a 503 is passed through unchanged. The body's `error.http_status`
+             *       still reports the **true upstream status**, `502` or `504` — not `503` — and is
+             *       the only surviving record of what the target answered, so the body rather than
+             *       the HTTP status is authoritative here (#3355, #4891). Every other non-2xx
+             *       upstream response is relayed at its own HTTP status with the same
+             *       `upstream_error` envelope, so any other 4xx/5xx the target returns surfaces as an
+             *       Error envelope rather than a raw body (#1462).
              *     - **`internal_error`** (message `Fetch service unavailable.`) — no fetch service
              *       endpoint could be resolved on this deployment, a fault of this API and not of the
              *       target. There is no upstream status to preserve: the `503` is this API's own
@@ -5737,13 +5715,14 @@ export interface operations {
                 };
             };
             /**
-             * @description Upstream search provider error. The body is a fixed,
+             * @description Upstream search provider error, answered at `503` rather than `502` because
+             *     Cloudflare replaces an origin 502 body with its own page (#4891). The body is a fixed,
              *     vendor-masked shape — deliberately NOT the unified `Error`
              *     envelope. The upstream provider's identity and message are
              *     never surfaced, so the response carries only the constant
              *     `error` code `search_provider_error`.
              */
-            502: {
+            503: {
                 headers: {
                     [name: string]: unknown;
                 };
@@ -5903,16 +5882,15 @@ export interface operations {
                     "application/json": components["schemas"]["Error"];
                 };
             };
-            /** @description Underlying scrape failed (`scrape_failed`) or upstream provider error (`provider_error`). */
-            502: {
-                headers: {
-                    [name: string]: unknown;
-                };
-                content: {
-                    "application/json": components["schemas"]["Error"];
-                };
-            };
-            /** @description Extraction provider unconfigured (`provider_unavailable`). */
+            /**
+             * @description Read `error.code` to tell the conditions apart: underlying scrape failed or the
+             *     extraction service was unreachable (`scrape_failed`), upstream provider error
+             *     (`provider_error`), extraction provider unconfigured (`provider_unavailable`), or
+             *     upstream provider timed out (`provider_timeout`). None of these answers `502` or
+             *     `504`: Cloudflare fronts this API and replaces an origin 502 or 504 with its own
+             *     `text/plain` page, discarding the error envelope, while a 503 passes through
+             *     unchanged (#4891).
+             */
             503: {
                 headers: {
                     [name: string]: unknown;
@@ -5921,15 +5899,6 @@ export interface operations {
                     "application/json": components["schemas"]["Error"];
                 };
             };
-            /** @description Upstream provider timed out (`provider_timeout`). */
-            504: {
-                headers: {
-                    [name: string]: unknown;
-                };
-                content: {
-                    "application/json": components["schemas"]["Error"];
-                };
-            };
         };
     };
     getUsage: {
@@ -6401,8 +6370,8 @@ export interface operations {
                     "application/json": components["schemas"]["Error"];
                 };
             };
-            /** @description Stripe error creating the Checkout session. */
-            502: {
+            /** @description Stripe error creating the Checkout session (`stripe_error`). Answered at `503`, not `502`, because Cloudflare replaces an origin 502 body with its own page (#4891). */
+            503: {
                 headers: {
                     [name: string]: unknown;
                 };
@@ -6473,8 +6442,8 @@ export interface operations {
                     "application/json": components["schemas"]["Error"];
                 };
             };
-            /** @description The Stripe subscription schedule could not be read. */
-            502: {
+            /** @description The Stripe subscription schedule could not be read (`stripe_error`). Answered at `503`, not `502`, because Cloudflare replaces an origin 502 body with its own page (#4891). */
+            503: {
                 headers: {
                     [name: string]: unknown;
                 };
@@ -6635,6 +6604,8 @@ export interface operations {
                         bandwidth: components["schemas"]["BandwidthBalance"] & {
                             /** @description Remaining balance of your subscription allowance: bytes still unspent across all allowance lots, the current period's and any rolled over from earlier periods alike, after active refund reservations. This is a remaining balance and falls to zero as the allowance is drawn down. It is not `included_bytes`, which is the plan's configured grant for a period and does not move as it is spent; do not subtract one from the other. `rollover_bytes` is a subset of this figure. */
                             remaining_allowance_bytes: number;
+                            /** @description Bytes you still owe: bandwidth your finished requests used beyond everything your account could pay for, net of any already paid back. It is reported beside the other bandwidth figures and is not subtracted from `remaining_bytes` or `remaining_allowance_bytes`. 0 when nothing is owed. */
+                            debt_bytes: number;
                         };
                         credits: components["schemas"]["CreditBalance"];
                         rates: {
@@ -6871,8 +6842,8 @@ export interface operations {
                     "application/json": components["schemas"]["Error"];
                 };
             };
-            /** @description Stripe API error. */
-            502: {
+            /** @description Stripe API error (`stripe_error`). Answered at `503`, not `502`, because Cloudflare replaces an origin 502 body with its own page (#4891). */
+            503: {
                 headers: {
                     [name: string]: unknown;
                 };

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

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

package/package.json

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