@hunt-labs/bytekit-sdk 0.9.2 → 0.9.3

package/CHANGELOG.md

@@ -10,6 +10,23 @@ today, see [README.md](./README.md), which remains the authoritative usage guide
 
 ## [Unreleased]
 
+## [0.9.3] - 2026-09-04
+
+### Changed
+
+- Regenerated `src/generated/api.d.ts` against the corrected queued-scrape `status_url`
+  documentation (#3925). `status_url` is a root-relative path, never an absolute URI: join it
+  onto the API base URL you called (`https://api.bytekit.com`, no trailing slash) to get the URL
+  to poll. The spec had declared it `format: uri` with an absolute example, which no server has
+  ever emitted; the emitted value is unchanged, so no client behaviour moves.
+- Regenerated `src/generated/api.d.ts` against the documented proxy-tier response headers
+  (#3926). `X-Scrape-Proxy-Tier-Label` now documents that it reports the tier that ACTUALLY
+  served a scrape — after any escalation, never the tier first attempted — that it is
+  diagnostic only, and that it is omitted on a cache hit, which replayed stored bytes and ran
+  no tier. The deprecated numeric `X-Scrape-Proxy-Tier` documents the legacy `1` datacenter /
+  `2` residential / `3` mobile vocabulary and its omission for the lean-browser tier. Types are
+  unchanged; only the documentation on them moved.
+
 ## [0.9.2] - 2026-09-03
 
 ### Changed

package/dist/generated/api.d.ts

@@ -816,11 +816,19 @@ export interface paths {
             path?: never;
             cookie?: never;
         };
-        get?: never;
+        /**
+         * Read a scheduled plan change
+         * @description The plan change booked for the end of the current period, if any, reconstructed from the Stripe subscription schedule on each call. Both fields are null when nothing is booked, including while the schedule stays attached for one further interval after a change has already landed.
+         */
+        get: operations["getPlanChange"];
         put?: never;
         /** Change subscription plan */
         post: operations["changePlan"];
-        delete?: never;
+        /**
+         * Revoke a scheduled plan change
+         * @description Cancels a plan change booked for the end of the current period. The subscription simply renews on the plan it is already on.
+         */
+        delete: operations["revokePlanChange"];
         options?: never;
         head?: never;
         patch?: never;
@@ -1343,13 +1351,13 @@ export interface components {
             name: string;
             /**
              * @description Monthly subscription price in cents.
-             * @example 49900
+             * @example 34900
              */
             price_cents: number;
             /**
              * Format: int64
-             * @description Included bandwidth per period, in bytes (binary GiB).
-             * @example 100000000000
+             * @description Included bandwidth per period, in bytes (decimal GB = 1,000,000,000 bytes).
+             * @example 125000000000
              */
             included_bytes: number;
             /**
@@ -1359,7 +1367,7 @@ export interface components {
             included_credits: number;
             /**
              * @description Bandwidth top-up price per MB, in cents.
-             * @example 0.25
+             * @example 0.2
              */
             topup_price_per_mb_cents: number;
             /**
@@ -1872,7 +1880,7 @@ export interface components {
          *       "status": "queued",
          *       "id": "sc_01j9abc123",
          *       "url": "https://example.com",
-         *       "status_url": "https://api.bytekit.com/v1/scrape/sc_01j9abc123",
+         *       "status_url": "/v1/scrape/sc_01j9abc123",
          *       "queued_at": "2025-01-15T12:00:00Z",
          *       "events": []
          *     }
@@ -1892,7 +1900,7 @@ export interface components {
             id: string;
             /** Format: uri */
             url: string;
-            /** Format: uri */
+            /** @description Root-relative path to poll for this job's terminal envelope — not an absolute URI. Join it onto the base URL of the server you called (see `servers`; they carry no trailing slash) to get the pollable URL, e.g. `https://api.bytekit.com` + `/v1/scrape/sc_01j9abc123`. */
             status_url: string;
             /** Format: date-time */
             queued_at: string;
@@ -2227,7 +2235,7 @@ export interface components {
             consecutive_failures: number;
             /** @description Error code from the most recent failed capture, if any. */
             last_error_code: string | null;
-            /** @description Reason the monitor was auto-suspended (e.g. "auto_suspended_consecutive_failures"), if applicable. */
+            /** @description Reason the monitor was auto-suspended, if applicable. `insufficient_balance` means the account ran out of spendable balance; `auto_suspended_consecutive_failures` means the monitor failed too many times in a row. Either way the monitor stops capturing until it is reactivated by sending `status: "active"` to `PATCH /v1/monitors/{id}`. */
             suspension_reason: string | null;
             metadata: Record<string, never> | null;
             /** Format: date-time */
@@ -2616,7 +2624,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. */
+            /** @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. */
             rollover_bytes: number;
         };
         CreditBalance: {
@@ -3198,7 +3206,7 @@ export interface operations {
                     "X-Screenshot-Status"?: string;
                     /** @description The originally requested URL. */
                     "X-Screenshot-URL"?: string;
-                    /** @description Credits charged for this screenshot. */
+                    /** @description Legacy credit weight for this capture (1, 2 or 4, doubling for `full_page` and again for retina/mobile). It is recorded for reporting only — screenshots are billed on bandwidth, not credits: the charge is the Phase 1 wire bytes x 1.5, and zero when Phase 1 is skipped or fails. */
                     "X-Screenshot-Credits-Charged"?: number;
                     /** @description Handler elapsed time in milliseconds. */
                     "X-Screenshot-Duration-Ms"?: number;
@@ -3239,7 +3247,7 @@ export interface operations {
                     "X-Screenshot-Status"?: string;
                     /** @description The originally requested URL. */
                     "X-Screenshot-URL"?: string;
-                    /** @description Credits charged for this screenshot. */
+                    /** @description Legacy credit weight for this capture (1, 2 or 4, doubling for `full_page` and again for retina/mobile). It is recorded for reporting only — screenshots are billed on bandwidth, not credits: the charge is the Phase 1 wire bytes x 1.5, and zero when Phase 1 is skipped or fails. */
                     "X-Screenshot-Credits-Charged"?: number;
                     /** @description Handler elapsed time in milliseconds. */
                     "X-Screenshot-Duration-Ms"?: number;
@@ -3466,9 +3474,9 @@ export interface operations {
                     "X-Scrape-Markdown-URL"?: string;
                     /** @description Byte length of the markdown artifact. Present only on fast-path responses when formats includes markdown. */
                     "X-Scrape-Markdown-Length"?: number;
-                    /** @description Numeric proxy tier used (diagnostic). Deprecated — use X-Scrape-Proxy-Tier-Label. */
+                    /** @description Legacy numeric form of the tier that served: 1 datacenter, 2 residential, 3 mobile. Omitted for the lean-browser tier, which has no numeric form. Deprecated — use X-Scrape-Proxy-Tier-Label. */
                     "X-Scrape-Proxy-Tier"?: number;
-                    /** @description Human-readable proxy tier label (e.g. residential, datacenter). Present on fast-path responses. */
+                    /** @description The proxy tier that actually served this request's fetch, after any escalation — never the tier first attempted. One of datacenter, residential, mobile, lean. Diagnostic only: it is never an input to routing, billing, caching or escalation. Present on sync fast-path responses. Omitted on a cache hit, which replayed stored bytes and ran no tier, and on responses the fast path did not serve. */
                     "X-Scrape-Proxy-Tier-Label"?: string;
                     /** @description WAF vendor detected on the target, if any (diagnostic). May be "suspected" when a low-confidence fail-open block marker was served. Omitted when no WAF is detected. */
                     "X-Scrape-Waf"?: string;
@@ -5621,11 +5629,11 @@ 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. */
+                        /** @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. */
                         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. */
+                        /** @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. */
                         rollover_bytes: number;
                         /** @description Bytes remaining in purchased top-up and starter-grant lots. Subscription allowance is excluded. */
                         topup_bytes: number;
@@ -5978,10 +5986,10 @@ export interface operations {
             content: {
                 "application/json": {
                     /**
-                     * @description Bytes to purchase. Allowed tiers — 5, 25, 50, 75, 100 GB.
+                     * @description Bytes to purchase. Allowed tiers — 5, 25, 50, 75, 100 GB (1 GB = 1,000,000,000 bytes).
                      * @enum {integer}
                      */
-                    bytes: 5368709120 | 26843545600 | 53687091200 | 80530636800 | 107374182400;
+                    bytes: 5000000000 | 25000000000 | 50000000000 | 75000000000 | 100000000000;
                     /**
                      * Format: uri
                      * @description Redirect target after a completed Checkout.
@@ -6135,6 +6143,52 @@ export interface operations {
             };
         };
     };
+    getPlanChange: {
+        parameters: {
+            query?: never;
+            header?: never;
+            path?: never;
+            cookie?: never;
+        };
+        requestBody?: never;
+        responses: {
+            /** @description Successful response. */
+            200: {
+                headers: {
+                    [name: string]: unknown;
+                };
+                content: {
+                    "application/json": {
+                        /** @description The plan the subscription switches to, or null. */
+                        pending_plan_slug: string | null;
+                        /**
+                         * Format: date-time
+                         * @description When the booked change lands, or null.
+                         */
+                        pending_effective_at: string | null;
+                    };
+                };
+            };
+            /** @description No subscription. */
+            400: {
+                headers: {
+                    [name: string]: unknown;
+                };
+                content: {
+                    "application/json": components["schemas"]["Error"];
+                };
+            };
+            /** @description The Stripe subscription schedule could not be read. */
+            502: {
+                headers: {
+                    [name: string]: unknown;
+                };
+                content: {
+                    "application/json": components["schemas"]["Error"];
+                };
+            };
+        };
+    };
     changePlan: {
         parameters: {
             query?: never;
@@ -6151,13 +6205,28 @@ export interface operations {
             };
         };
         responses: {
-            /** @description Successful response. */
+            /** @description Upgrades apply immediately (`changed: true`). Downgrades are booked for the end of the paid period (`changed: false`, `pending: true`) so the customer keeps the allowance they already paid for and nothing is prorated. */
             200: {
                 headers: {
                     [name: string]: unknown;
                 };
                 content: {
-                    "application/json": Record<string, never>;
+                    "application/json": {
+                        /** @description Whether the subscription was re-priced now. */
+                        changed: boolean;
+                        /** @description Present and true when the change is booked for a later date. */
+                        pending?: boolean;
+                        previous_plan: string;
+                        new_plan: string;
+                        subscription_id: string;
+                        /**
+                         * Format: date-time
+                         * @description When a booked change lands. Absent on an immediate change.
+                         */
+                        effective_at?: string;
+                        /** @description Stripe proration behaviour applied. Absent on a booked change. */
+                        proration?: string;
+                    };
                 };
             };
             /** @description No subscription, same plan, or invalid plan. */
@@ -6171,6 +6240,40 @@ export interface operations {
             };
         };
     };
+    revokePlanChange: {
+        parameters: {
+            query?: never;
+            header?: never;
+            path?: never;
+            cookie?: never;
+        };
+        requestBody?: never;
+        responses: {
+            /** @description Successful response. */
+            200: {
+                headers: {
+                    [name: string]: unknown;
+                };
+                content: {
+                    "application/json": {
+                        revoked: boolean;
+                        /** @description The plan the subscription stays on. */
+                        plan: string;
+                        subscription_id: string;
+                    };
+                };
+            };
+            /** @description No subscription, or no scheduled plan change to revoke. */
+            400: {
+                headers: {
+                    [name: string]: unknown;
+                };
+                content: {
+                    "application/json": components["schemas"]["Error"];
+                };
+            };
+        };
+    };
     listInvoices: {
         parameters: {
             query?: {
@@ -6272,13 +6375,13 @@ export interface operations {
             content: {
                 "application/json": {
                     enabled: boolean;
-                    /** @description Min 1 MB. Required when enabled. */
+                    /** @description Min 1 MB (1,000,000 bytes). Required when enabled. */
                     threshold_bytes?: number;
                     /**
-                     * @description Allowed tiers — 5, 25, 50, 75, 100 GB. Required when enabled.
+                     * @description Allowed tiers — 5, 25, 50, 75, 100 GB (1 GB = 1,000,000,000 bytes). Required when enabled.
                      * @enum {integer}
                      */
-                    amount_bytes?: 5368709120 | 26843545600 | 53687091200 | 80530636800 | 107374182400;
+                    amount_bytes?: 5000000000 | 25000000000 | 50000000000 | 75000000000 | 100000000000;
                     /** @description $1-$1000. Required when enabled. */
                     monthly_cap_cents?: 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.2";
+export declare const SDK_VERSION = "0.9.3";

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

package/package.json

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