@hunt-labs/bytekit-sdk 0.11.6 → 0.11.8

package/CHANGELOG.md

@@ -10,6 +10,27 @@ today, see [README.md](./README.md), which remains the authoritative usage guide
 
 ## [Unreleased]
 
+## [0.11.8] - 2026-09-30
+
+### Changed
+
+- **Bulk job types add `total_billed_bytes` and deprecate the bulk credit fields (#5021).** Every
+  bulk job body (`POST`/`GET`/`DELETE /v1/bulk`, `/v1/scrape/bulk`, `/v1/fetch/bulk`, and the
+  `GET /v1/bulk` list) gains `total_billed_bytes: number | null`: the bandwidth billed for the job,
+  in bytes, after multipliers. It is `null` on the create response and for a bulk that predates
+  the field. `total_credits_charged` and the bulk item `credits_charged` are marked
+  `@deprecated`; they report `0` under the `dual` and `bytes` billing modes. Regenerated
+  `src/generated/api.d.ts`; no SDK method signature moves.
+
+## [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

package/dist/generated/api.d.ts

@@ -1517,7 +1517,13 @@ export interface components {
             total: number;
             completed: number;
             failed: number;
+            /**
+             * @deprecated
+             * @description Deprecated: bulk jobs are billed on bandwidth — read `total_billed_bytes`. Reports `0` under the `dual` and `bytes` billing modes, where no credits are drawn. Under `credits` it is the total credits billed for the job.
+             */
             total_credits_charged: number;
+            /** @description Bandwidth billed for the job, in bytes: the settled amount after multipliers, summed over every settled child's `billing.billed_bytes` (not raw wire bytes). Null for a bulk with a completed child missing from the sum (completed before this field, or with no settled amount) — never a partial sum. */
+            total_billed_bytes: number | null;
             /** Format: uri */
             webhook_url: string;
             /** @description Complete item records included before the 500-item or 1-MiB manifest bound. Every record carries a stable `id`, a `type`, and a terminal `status`. */
@@ -2838,10 +2844,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`.
@@ -2864,9 +2873,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
+                 *         }
                  *       }
                  *     }
                  */
@@ -3924,8 +3937,13 @@ export interface operations {
                         created_at: string;
                         /** Format: date-time */
                         completed_at: string | null;
-                        /** @description Always null on the create response — the job has not been billed yet (routes/scrape-bulk.ts builds the 202 body from a partial job row). Fractional when populated (credits are NUMERIC(10,2)); the numeric branch is unreachable on this path and exists only so the 202 and 200 bodies share one shape. */
+                        /**
+                         * @deprecated
+                         * @description Deprecated: bulk jobs are billed on bandwidth — read `total_billed_bytes`. Reports `0` under the `dual` and `bytes` billing modes, where no credits are drawn. Under `credits` it is always null on the create response — the job has not been billed yet (routes/scrape-bulk.ts builds the 202 body from a partial job row).
+                         */
                         total_credits_charged: number | null;
+                        /** @description Bandwidth billed for the job, in bytes: the settled amount after multipliers, summed over every settled child's `billing.billed_bytes` across the whole job (not raw wire bytes, not just this page). Always null on the create response — nothing has settled yet. */
+                        total_billed_bytes: number | null;
                         /** @description Estimated credits at submission time. Null in GET responses. Fetch-bulk items use the raw fetch bandwidth billing factor. */
                         estimated_credits: number | null;
                         /** @description Webhook endpoint URL (HTTPS only; http:// rejected with 400 invalid_url, reason scheme_unsupported) */
@@ -4010,8 +4028,13 @@ export interface operations {
                         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). */
+                        /**
+                         * @deprecated
+                         * @description Deprecated: bulk jobs are billed on bandwidth — read `total_billed_bytes`. Reports `0` under the `dual` and `bytes` billing modes, where no credits are drawn. Under `credits` it is the total credits billed for the job, null until the job is billed; fractional — credits are NUMERIC(10,2).
+                         */
                         total_credits_charged: number | null;
+                        /** @description Bandwidth billed for the job, in bytes: the settled amount after multipliers, summed over every settled child's `billing.billed_bytes` across the whole job (not raw wire bytes, not just this page). Null for a bulk with a completed child missing from the sum (completed before this field, or with no settled amount) — never a partial sum. */
+                        total_billed_bytes: 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) */
@@ -4049,8 +4072,13 @@ export interface operations {
                         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). */
+                        /**
+                         * @deprecated
+                         * @description Deprecated: bulk jobs are billed on bandwidth — read `total_billed_bytes`. Reports `0` under the `dual` and `bytes` billing modes, where no credits are drawn. Under `credits` it is the total credits billed for the job, null until the job is billed; fractional — credits are NUMERIC(10,2).
+                         */
                         total_credits_charged: number | null;
+                        /** @description Bandwidth billed for the job, in bytes: the settled amount after multipliers, summed over every settled child's `billing.billed_bytes` across the whole job (not raw wire bytes, not just this page). Null for a bulk with a completed child missing from the sum (completed before this field, or with no settled amount) — never a partial sum. */
+                        total_billed_bytes: 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) */
@@ -4398,8 +4426,13 @@ export interface operations {
                         created_at: string;
                         /** Format: date-time */
                         completed_at: string | null;
-                        /** @description Always null on the create response — the job has not been billed yet (routes/fetch-bulk.ts builds the 202 body from a partial job row). Fractional when populated (credits are NUMERIC(10,2)); the numeric branch is unreachable on this path and exists only so the 202 and 200 bodies share one shape. */
+                        /**
+                         * @deprecated
+                         * @description Deprecated: bulk jobs are billed on bandwidth — read `total_billed_bytes`. Reports `0` under the `dual` and `bytes` billing modes, where no credits are drawn. Under `credits` it is always null on the create response — the job has not been billed yet (routes/fetch-bulk.ts builds the 202 body from a partial job row).
+                         */
                         total_credits_charged: number | null;
+                        /** @description Bandwidth billed for the job, in bytes: the settled amount after multipliers, summed over every settled child's `billing.billed_bytes` across the whole job (not raw wire bytes, not just this page). Always null on the create response — nothing has settled yet. */
+                        total_billed_bytes: number | null;
                         /** @description Estimated credits at submission time. Null in GET responses. Fetch items are raw passthrough requests and use the raw fetch bandwidth billing factor. */
                         estimated_credits: number | null;
                         /** @description Webhook endpoint URL (HTTPS only; http:// rejected with 400 invalid_url, reason scheme_unsupported) */
@@ -4478,8 +4511,13 @@ export interface operations {
                         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). */
+                        /**
+                         * @deprecated
+                         * @description Deprecated: bulk jobs are billed on bandwidth — read `total_billed_bytes`. Reports `0` under the `dual` and `bytes` billing modes, where no credits are drawn. Under `credits` it is the total credits billed for the job, null until the job is billed; fractional — credits are NUMERIC(10,2).
+                         */
                         total_credits_charged: number | null;
+                        /** @description Bandwidth billed for the job, in bytes: the settled amount after multipliers, summed over every settled child's `billing.billed_bytes` across the whole job (not raw wire bytes, not just this page). Null for a bulk with a completed child missing from the sum (completed before this field, or with no settled amount) — never a partial sum. */
+                        total_billed_bytes: 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) */
@@ -4570,8 +4608,13 @@ export interface operations {
                         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). */
+                        /**
+                         * @deprecated
+                         * @description Deprecated: bulk jobs are billed on bandwidth — read `total_billed_bytes`. Reports `0` under the `dual` and `bytes` billing modes, where no credits are drawn. Under `credits` it is the total credits billed for the job, null until the job is billed; fractional — credits are NUMERIC(10,2).
+                         */
                         total_credits_charged: number | null;
+                        /** @description Bandwidth billed for the job, in bytes: the settled amount after multipliers, summed over every settled child's `billing.billed_bytes` across the whole job (not raw wire bytes, not just this page). Null for a bulk with a completed child missing from the sum (completed before this field, or with no settled amount) — never a partial sum. */
+                        total_billed_bytes: 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) */
@@ -4680,8 +4723,13 @@ export interface operations {
                             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). */
+                            /**
+                             * @deprecated
+                             * @description Deprecated: bulk jobs are billed on bandwidth — read `total_billed_bytes`. Reports `0` under the `dual` and `bytes` billing modes, where no credits are drawn. Under `credits` it is the total credits billed for the job, null until the job is billed; fractional — credits are NUMERIC(10,2).
+                             */
                             total_credits_charged: number | null;
+                            /** @description Bandwidth billed for the job, in bytes: the settled amount after multipliers, summed over every settled child's `billing.billed_bytes` across the whole job (not raw wire bytes, not just this page). Null for a bulk with a completed child missing from the sum (completed before this field, or with no settled amount) — never a partial sum. */
+                            total_billed_bytes: 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) */
@@ -4892,8 +4940,13 @@ export interface operations {
                         created_at: string;
                         /** Format: date-time */
                         completed_at: string | null;
-                        /** @description Always null on the create response — the job has not been billed yet (routes/bulk.ts builds the 202 body from a partial job row). Fractional when populated (credits are NUMERIC(10,2)); the numeric branch is unreachable on this path and exists only so the 202 and 200 bodies share one shape. */
+                        /**
+                         * @deprecated
+                         * @description Deprecated: bulk jobs are billed on bandwidth — read `total_billed_bytes`. Reports `0` under the `dual` and `bytes` billing modes, where no credits are drawn. Under `credits` it is always null on the create response — the job has not been billed yet (routes/bulk.ts builds the 202 body from a partial job row).
+                         */
                         total_credits_charged: number | null;
+                        /** @description Bandwidth billed for the job, in bytes: the settled amount after multipliers, summed over every settled child's `billing.billed_bytes` across the whole job (not raw wire bytes, not just this page). Always null on the create response — nothing has settled yet. */
+                        total_billed_bytes: number | null;
                         /** @description Estimated credits at submission time. Null in GET responses. Fetch-bulk items use the raw fetch bandwidth billing factor. */
                         estimated_credits: number | null;
                         /** @description Webhook endpoint URL (HTTPS only; http:// rejected with 400 invalid_url, reason scheme_unsupported) */
@@ -4975,8 +5028,13 @@ export interface operations {
                         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). */
+                        /**
+                         * @deprecated
+                         * @description Deprecated: bulk jobs are billed on bandwidth — read `total_billed_bytes`. Reports `0` under the `dual` and `bytes` billing modes, where no credits are drawn. Under `credits` it is the total credits billed for the job, null until the job is billed; fractional — credits are NUMERIC(10,2).
+                         */
                         total_credits_charged: number | null;
+                        /** @description Bandwidth billed for the job, in bytes: the settled amount after multipliers, summed over every settled child's `billing.billed_bytes` across the whole job (not raw wire bytes, not just this page). Null for a bulk with a completed child missing from the sum (completed before this field, or with no settled amount) — never a partial sum. */
+                        total_billed_bytes: 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) */
@@ -5007,8 +5065,13 @@ export interface operations {
                         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). */
+                        /**
+                         * @deprecated
+                         * @description Deprecated: bulk jobs are billed on bandwidth — read `total_billed_bytes`. Reports `0` under the `dual` and `bytes` billing modes, where no credits are drawn. Under `credits` it is the total credits billed for the job, null until the job is billed; fractional — credits are NUMERIC(10,2).
+                         */
                         total_credits_charged: number | null;
+                        /** @description Bandwidth billed for the job, in bytes: the settled amount after multipliers, summed over every settled child's `billing.billed_bytes` across the whole job (not raw wire bytes, not just this page). Null for a bulk with a completed child missing from the sum (completed before this field, or with no settled amount) — never a partial sum. */
+                        total_billed_bytes: 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) */
@@ -5056,8 +5119,13 @@ export interface operations {
                         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). */
+                        /**
+                         * @deprecated
+                         * @description Deprecated: bulk jobs are billed on bandwidth — read `total_billed_bytes`. Reports `0` under the `dual` and `bytes` billing modes, where no credits are drawn. Under `credits` it is the total credits billed for the job, null until the job is billed; fractional — credits are NUMERIC(10,2).
+                         */
                         total_credits_charged: number | null;
+                        /** @description Bandwidth billed for the job, in bytes: the settled amount after multipliers, summed over every settled child's `billing.billed_bytes` across the whole job (not raw wire bytes, not just this page). Null for a bulk with a completed child missing from the sum (completed before this field, or with no settled amount) — never a partial sum. */
+                        total_billed_bytes: number | null;
                         /** @description Null in cancel responses (computed at submission time only). */
                         estimated_credits: number | null;
                         /** @description Webhook endpoint URL (HTTPS only; http:// rejected with 400 invalid_url, reason scheme_unsupported) */
@@ -5120,6 +5188,10 @@ export interface operations {
                             status: "pending" | "processing" | "completed" | "failed" | "cancelled";
                             /** Format: uri */
                             url: string;
+                            /**
+                             * @deprecated
+                             * @description Deprecated: bulk jobs are billed on bandwidth — read this item's `billing.billed_bytes`. Reports `0` under the `dual` and `bytes` billing modes, where no credits are drawn. Under `credits` it is the credits billed for the item, null until it is billed; fractional (NUMERIC(10,2), 0.5 cache-hit credits).
+                             */
                             credits_charged?: number | null;
                             /**
                              * @description Itemised account of this item's charge — the basis, the named factors
@@ -6597,6 +6669,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: {

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

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

package/package.json

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