@hunt-labs/bytekit-sdk 0.9.0 → 0.9.1

package/CHANGELOG.md

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

package/dist/generated/api.d.ts

@@ -2147,6 +2147,7 @@ export interface components {
              * @description Webhook endpoint URL (HTTPS only; http:// rejected with 400 invalid_url, reason scheme_unsupported)
              */
             webhook_url: string;
+            /** @description HMAC secret used to sign webhook deliveries. Each delivery carries `X-Webhook-Timestamp` and `X-Webhook-Signature` (`sha256=` + the hex HMAC-SHA256 of `timestamp.body`). See https://bytekit.com/docs/guides/webhooks for verification code. */
             webhook_secret?: string;
             /** @description Max 20 headers. Keys must match /^[A-Za-z0-9-]+$/ and not be reserved. */
             webhook_headers?: {
@@ -2176,6 +2177,7 @@ export interface components {
              * @description Webhook endpoint URL (HTTPS only; http:// rejected with 400 invalid_url, reason scheme_unsupported)
              */
             webhook_url?: string;
+            /** @description HMAC secret used to sign webhook deliveries. Each delivery carries `X-Webhook-Timestamp` and `X-Webhook-Signature` (`sha256=` + the hex HMAC-SHA256 of `timestamp.body`). See https://bytekit.com/docs/guides/webhooks for verification code. */
             webhook_secret?: string;
             webhook_headers?: {
                 [key: string]: string;
@@ -2236,7 +2238,7 @@ export interface components {
         };
         MonitorCreateResponse: components["schemas"]["MonitorResponse"] & {
             /**
-             * @description The webhook signing secret — returned **once** at creation time only. Subsequent GET requests omit this field. Always present on a create response (`webhook_url` is required on create). Format: 64 lowercase hex characters (32 bytes of entropy).
+             * @description The webhook signing secret — returned **once** at creation time only. Subsequent GET requests omit this field. Always present on a create response (`webhook_url` is required on create). Format: 64 lowercase hex characters (32 bytes of entropy). Use it to verify the `X-Webhook-Signature` header on each delivery — see https://bytekit.com/docs/guides/webhooks.
              * @example a3f1b2c4d5e6f7a8b9c0d1e2f3a4b5c6d7e8f9a0b1c2d3e4f5a6b7c8d9e0f1a2
              */
             webhook_secret?: string;
@@ -2285,7 +2287,10 @@ export interface components {
              * @description Optional webhook endpoint URL (HTTPS only; http:// rejected with 400 invalid_url, reason scheme_unsupported). When omitted, no `sitemap.completed`/`sitemap.failed` webhook is delivered and the job is poll-only via `GET /v1/sitemap/{id}`. When present, delivery is unchanged. `webhook_secret` is ignored when `webhook_url` is absent.
              */
             webhook_url?: string;
-            /** @default null */
+            /**
+             * @description HMAC secret used to sign webhook deliveries. Each delivery carries `X-Webhook-Timestamp` and `X-Webhook-Signature` (`sha256=` + the hex HMAC-SHA256 of `timestamp.body`). See https://bytekit.com/docs/guides/webhooks for verification code.
+             * @default null
+             */
             webhook_secret: string | null;
             /**
              * @description Max 90 days.
@@ -2522,7 +2527,10 @@ export interface components {
             };
             /** Format: date-time */
             cancelled_at: string | null;
-            /** Format: date-time */
+            /**
+             * Format: date-time
+             * @description Reserved, and always `null` today: it reflects the account's cancellation grace deadline, which no current code path sets. It is not the payment-failure grace period — that deadline is tracked per invoice (7 days from the failed payment) in `billing_dunning_graces` and is not exposed on this response.
+             */
             grace_period_expires_at: string | null;
             /** Format: date-time */
             created_at: string;
@@ -2607,6 +2615,7 @@ export interface components {
             purchased_topup_bytes: number;
             /** @description Bytes remaining in starter-grant lots, after active refund reservations. Purchased top-up bytes are excluded. */
             granted_topup_bytes: number;
+            /** @description Unspent subscription allowance carried over from earlier billing periods: bytes remaining in allowance lots granted before the current period started, after active refund reservations. Carried value is spent before the current period's allowance, so this falls to `0` before `limit_bytes` reaches the current allowance alone. */
             rollover_bytes: number;
         };
         CreditBalance: {
@@ -2619,6 +2628,7 @@ export interface components {
             purchased_topup_credits: number;
             /** @description Credits remaining in starter-grant lots, after active refund reservations. Purchased top-up credits are excluded. */
             granted_topup_credits: number;
+            /** @description Always `0`. Search credits do not carry over between billing periods; the field is retained for contract stability and will not become non-zero without an announced plan change. */
             rollover_credits: number;
         };
     };
@@ -3619,6 +3629,7 @@ export interface operations {
                      * @description Webhook endpoint URL (HTTPS only; http:// rejected with 400 invalid_url, reason scheme_unsupported)
                      */
                     webhook_url: string;
+                    /** @description HMAC secret used to sign webhook deliveries. Each delivery carries `X-Webhook-Timestamp` and `X-Webhook-Signature` (`sha256=` + the hex HMAC-SHA256 of `timestamp.body`). See https://bytekit.com/docs/guides/webhooks for verification code. */
                     webhook_secret?: string;
                     metadata?: components["schemas"]["Metadata"];
                     /**
@@ -3739,6 +3750,43 @@ export interface operations {
                         estimated_credits: number | null;
                         /** @description Webhook endpoint URL (HTTPS only; http:// rejected with 400 invalid_url, reason scheme_unsupported) */
                         webhook_url: string;
+                        /** @description Rehydrated per-URL scrape envelopes — the terminal page of results (default 100 rows, `?limit=` up to 500). `routes/scrape-bulk.ts` spreads this key into the SAME body on both status branches, so it is present here exactly as it is on the 202; on the 200 the entries carry their final success or error envelopes (issue #3632). */
+                        items: components["schemas"]["ScrapeEnvelope"][];
+                    };
+                };
+            };
+            /**
+             * @description Bulk job still processing. `routes/scrape-bulk.ts` ends the poll handler
+             *     with `status: isTerminal ? 200 : 202` over an identical body, so this is
+             *     the SAME envelope the 200 documents — only the status code and the
+             *     reachable `status` values differ. Keep polling until you get a 200
+             *     (issue #3533).
+             */
+            202: {
+                headers: {
+                    [name: string]: unknown;
+                };
+                content: {
+                    "application/json": {
+                        /** @example bulk_01j9abc123 */
+                        id: string;
+                        /** @enum {string} */
+                        status: "processing";
+                        total: number;
+                        completed: number;
+                        failed: number;
+                        /** Format: date-time */
+                        created_at: string;
+                        /** Format: date-time */
+                        completed_at: string | null;
+                        /** @description Total credits billed for the job. Null until the job is billed. Fractional — credits are NUMERIC(10,2). */
+                        total_credits_charged: number | null;
+                        /** @description Null in GET responses (computed at submission time only). */
+                        estimated_credits: number | null;
+                        /** @description Webhook endpoint URL (HTTPS only; http:// rejected with 400 invalid_url, reason scheme_unsupported) */
+                        webhook_url: string;
+                        /** @description Rehydrated per-URL scrape envelopes — the same page the 200 returns (default 100 rows, `?limit=` up to 500). While the job is non-terminal most entries carry the `queued` envelope. */
+                        items: components["schemas"]["ScrapeEnvelope"][];
                     };
                 };
             };
@@ -4019,6 +4067,7 @@ export interface operations {
                      * @description Webhook endpoint URL (HTTPS only; http:// rejected with 400 invalid_url, reason scheme_unsupported)
                      */
                     webhook_url: string;
+                    /** @description HMAC secret used to sign webhook deliveries. Each delivery carries `X-Webhook-Timestamp` and `X-Webhook-Signature` (`sha256=` + the hex HMAC-SHA256 of `timestamp.body`). See https://bytekit.com/docs/guides/webhooks for verification code. */
                     webhook_secret?: string;
                     metadata?: components["schemas"]["Metadata"];
                 };
@@ -4154,6 +4203,72 @@ export interface operations {
                     };
                 };
             };
+            /**
+             * @description Bulk job still processing. `routes/fetch-bulk.ts` ends the poll handler
+             *     with `status: isTerminal ? 200 : 202` over an identical body, so this is
+             *     the SAME envelope the 200 documents — only the status code and the
+             *     reachable `status` values differ. Keep polling until you get a 200; a
+             *     **cancelled** job stays on this branch forever (issue #3533).
+             *
+             *     Item `content_url` values are pre-signed exactly as on the 200 — a fresh
+             *     600-second signature on every poll.
+             */
+            202: {
+                headers: {
+                    [name: string]: unknown;
+                };
+                content: {
+                    "application/json": {
+                        /** @example bulk_01j9abc123 */
+                        id: string;
+                        /** @enum {string} */
+                        status: "processing" | "cancelled";
+                        total: number;
+                        completed: number;
+                        failed: number;
+                        /** Format: date-time */
+                        created_at: string;
+                        /** Format: date-time */
+                        completed_at: string | null;
+                        /** @description Total credits billed for the job. Null until the job is billed. Fractional — credits are NUMERIC(10,2). */
+                        total_credits_charged: number | null;
+                        /** @description Null in GET responses (computed at submission time only). */
+                        estimated_credits: number | null;
+                        /** @description Webhook endpoint URL (HTTPS only; http:// rejected with 400 invalid_url, reason scheme_unsupported) */
+                        webhook_url: string;
+                        /** @description Per-URL fetch items, oldest first, capped at 500 (listBulkFetchItemsWithLatestAttempt). */
+                        items: {
+                            /**
+                             * @description Scrape-row id, `sc_`-prefixed. Fetch-bulk items are rows of the same resource sync `/v1/scrape` returns, so they share its prefix. Not to be confused with the `ft_`-prefixed `X-Fetch-ID` correlation header on sync `/v1/fetch`, which identifies a request rather than a stored item.
+                             * @example sc_01j9abc123
+                             */
+                            id: string;
+                            /** Format: uri */
+                            url: string;
+                            /** @enum {string} */
+                            status: "pending" | "processing" | "completed" | "failed" | "cancelled";
+                            content_type: string | null;
+                            content_length: number | null;
+                            /** @description Pre-signed download URL for the fetched body, valid for 600 seconds (10 minutes) from the moment this response was generated — matching the signing TTL of `image_url` on `GET /v1/bulk/{id}/screenshots`. A new signature is minted on every poll. Null for items with no stored body; a completed item whose object cannot be signed falls back to the unsigned stored URL, which returns 401 on download. */
+                            content_url: string | null;
+                            waf_vendor: string | null;
+                            cache_hit: boolean;
+                            /**
+                             * @description Itemised account of this item's charge — the basis, the named factors
+                             *     that composed the multiplier, and the resulting billed bytes. Omitted
+                             *     for rows that completed before the billing node was persisted.
+                             */
+                            billing?: components["schemas"]["BillingNode"];
+                            error_code: string | null;
+                            error_message: string | null;
+                            /** Format: date-time */
+                            created_at: string;
+                            /** Format: date-time */
+                            completed_at: string | null;
+                        }[];
+                    };
+                };
+            };
             /** @description Resource not found. */
             404: {
                 headers: {
@@ -4376,6 +4491,7 @@ export interface operations {
                      * @description Webhook endpoint URL (HTTPS only; http:// rejected with 400 invalid_url, reason scheme_unsupported)
                      */
                     webhook_url: string;
+                    /** @description HMAC secret used to sign webhook deliveries. Each delivery carries `X-Webhook-Timestamp` and `X-Webhook-Signature` (`sha256=` + the hex HMAC-SHA256 of `timestamp.body`). See https://bytekit.com/docs/guides/webhooks for verification code. */
                     webhook_secret?: string;
                     metadata?: components["schemas"]["Metadata"];
                 };
@@ -4491,6 +4607,38 @@ export interface operations {
                     };
                 };
             };
+            /**
+             * @description Bulk job still processing. `routes/bulk.ts` ends the poll handler with
+             *     `status: isTerminal ? 200 : 202` over an identical body, so this is the
+             *     SAME envelope the 200 documents — only the status code and the reachable
+             *     `status` values differ. Keep polling until you get a 200 (issue #3533).
+             */
+            202: {
+                headers: {
+                    [name: string]: unknown;
+                };
+                content: {
+                    "application/json": {
+                        /** @example bulk_01j9abc123 */
+                        id: string;
+                        /** @enum {string} */
+                        status: "processing";
+                        total: number;
+                        completed: number;
+                        failed: number;
+                        /** Format: date-time */
+                        created_at: string;
+                        /** Format: date-time */
+                        completed_at: string | null;
+                        /** @description Total credits billed for the job. Null until the job is billed. Fractional — credits are NUMERIC(10,2). */
+                        total_credits_charged: number | null;
+                        /** @description Null in GET responses (computed at submission time only). */
+                        estimated_credits: number | null;
+                        /** @description Webhook endpoint URL (HTTPS only; http:// rejected with 400 invalid_url, reason scheme_unsupported) */
+                        webhook_url: string;
+                    };
+                };
+            };
             /** @description Resource not found. */
             404: {
                 headers: {
@@ -5119,7 +5267,7 @@ export interface operations {
                     "application/json": components["schemas"]["Error"];
                 };
             };
-            /** @description Payment required — the account is out of credits. */
+            /** @description Payment required. Either the account is out of credits (`quota_exceeded`), or a custom overage-enabled plan would cross its configured overage spending cap (`spending_cap_reached`). */
             402: {
                 headers: {
                     [name: string]: unknown;
@@ -5398,7 +5546,7 @@ export interface operations {
                         plan_type: "payg" | "subscription";
                         /** @description Total top-up spend in cents for this billing period. Present only in dual/bytes billing mode. */
                         topup_spent_cents?: number;
-                        /** @description Remaining top-up bytes: max(0, topup_bytes − max(0, bytes_used − included_bytes − rollover_bytes)). Present only in dual/bytes billing mode. */
+                        /** @description Remaining purchased top-up bytes, already net of any overage consumed against them. Equal to topup_bytes. Present only in dual/bytes billing mode. */
                         topup_balance_bytes?: number;
                         /** @description Days elapsed since period_start. */
                         period_days_elapsed: number;
@@ -5408,9 +5556,13 @@ export interface operations {
                         bytes_bulk: number;
                         bytes_scrape: number;
                         bytes_monitor: number;
+                        /** @description The spendable byte budget for this period, summed over the account's value lots: the allowance granted for the current period, plus unspent allowance carried over from earlier periods, plus purchased top-up and starter-grant bytes. Carried-over value is spent first, so this figure falls as it is consumed. */
                         bytes_limit: number;
+                        /** @description Bytes still available across every active lot, after active refund reservations. */
                         bytes_remaining: number;
+                        /** @description Unspent allowance carried over from earlier billing periods. */
                         rollover_bytes: number;
+                        /** @description Bytes remaining in purchased top-up and starter-grant lots. Subscription allowance is excluded. */
                         topup_bytes: number;
                         /** @description Total API requests in the current billing period. */
                         request_count: number;
@@ -6028,7 +6180,7 @@ export interface operations {
                             /** @description Whether the authenticated account's plan supports bandwidth top-up purchases. False for free and PAYG plans. The frontend should disable or hide the Buy Bandwidth affordance when this is false. */
                             available: boolean;
                         };
-                        /** @description The number of bandwidth bytes included in the account's current plan allotment (before any rollover or top-up bytes). Use this value instead of computing plan allotment client-side from `limit_bytes - rollover_bytes - topup_bytes`. */
+                        /** @description The bandwidth allotment configured on the account's current plan (before any rollover or top-up bytes). Use this value instead of computing the plan allotment client-side from `limit_bytes - rollover_bytes - topup_bytes`: the allowance actually granted is the lot written when the period's invoice was paid, so the two can differ before the first paid invoice of a plan. */
                         included_bytes?: number;
                         /** @description Number of automatic top-up transactions (bandwidth and credit) that have been triggered in the current calendar month. Includes both pending and completed transactions. */
                         triggers_this_month?: number;

package/dist/version.d.ts

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

package/dist/version.js

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

package/package.json

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