@hunt-labs/bytekit-sdk 0.4.0 → 0.5.0

package/CHANGELOG.md

@@ -8,6 +8,25 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 This file records only the delta between versions. For how to use the package
 today, see [README.md](./README.md), which remains the authoritative usage guide.
 
+## [0.5.0] - 2026-07-29
+
+### Added
+
+- `src/generated/api.d.ts` now models the `400` responses that the gateway's new
+  request-body-size guards can return. `operations['stripeWebhook']['responses']` gains a
+  `400` with this route's bespoke `{ error?: string }` body, and
+  `operations['retryWebhookDelivery']['responses']` gains a `400` carrying the unified
+  `components['schemas']['Error']` envelope. Both are purely additive — no existing member
+  changed shape — so every current call site still compiles. (#2640)
+
+### Changed
+
+- Regenerated `src/generated/api.d.ts` against the merged spec. Beyond the two added `400`
+  members above, the delta is JSDoc only: every guarded endpoint's description now carries a
+  `**Limits:**` block stating its byte ceiling and the `request_too_large` error code
+  (#2640), and `POST /v1/bulk`'s description documents `defaults.type` inheritance and the
+  422 on unrecognized keys (#2643). No runtime code changed. (#2640, #2643)
+
 ## [0.4.0] - 2026-07-24
 
 ### Added
@@ -201,6 +220,8 @@ against 0.1.0 — read each one before upgrading.
   (scrape, screenshot, search, and related endpoints), published under the original
   `@rapidcrawl/sdk` name.
 
+[0.5.0]: https://github.com/Hunt-Labs-Inc/ByteKit/tree/main/packages/sdk-typescript
+[0.4.0]: https://github.com/Hunt-Labs-Inc/ByteKit/tree/main/packages/sdk-typescript
 [0.3.0]: https://github.com/Hunt-Labs-Inc/ByteKit/tree/main/packages/sdk-typescript
 [0.2.2]: https://github.com/Hunt-Labs-Inc/ByteKit/tree/main/packages/sdk-typescript
 [0.2.1]: https://github.com/Hunt-Labs-Inc/ByteKit/tree/main/packages/sdk-typescript

package/README.md

@@ -185,12 +185,15 @@ const deliveries = await client.webhooks.list();
 await client.webhooks.retry('wh_123abc');
 ```
 
-> **Note:** `client.account.*` (including `client.account.apiKeys.*`) targets the
-> `/v1/account/*` endpoints, which authenticate with a Clerk dashboard session —
-> **not** a Bearer API key. Calling them with an API-key client will fail auth.
-> They remain on the SDK surface for dashboard/session consumers and are marked
-> `x-sdk-scope: internal` in the spec, so they are intentionally excluded from the
-> v0.1 Bearer-key parity guarantee.
+> **Note (the real auth split):** `account.get()` authenticates with the same Bearer
+> API key as every other v0.1 method above — it succeeds normally. `client.account.apiKeys.*`
+> is different: it targets `/v1/account/api-keys*`, which authenticates with a Clerk
+> dashboard session, **not** a Bearer API key — calling any `apiKeys.*` method with an
+> API-key client fails auth. `apiKeys.*` remains on the SDK surface for dashboard/session
+> consumers (deliberate retention — see `DOCUMENTED_SURFACE_EXCEPTIONS` in
+> `src/allowlist.ts`) and is marked `x-sdk-scope: internal` in the spec, so it is
+> intentionally excluded from the v0.1 Bearer-key parity guarantee. `account.get()` is not:
+> it is a real `V01_METHODS` entry.
 
 ### Response headers
 
@@ -207,8 +210,12 @@ console.log(headers.get('X-Raw-Bytes')); // e.g. "12345"
 console.log(status); // 200
 ```
 
-`client.screenshots.createWithResponse()` and `client.screenshots.getWithResponse()`
-work the same way. Any other endpoint's headers are reachable through the generic
+`client.screenshots.createWithResponse()` works the same way, and is where the
+`X-Screenshot-*`/`X-Raw-Bytes`/`X-Billable-Bytes`/`X-Billing-Multiplier` headers
+actually live — they're declared on `POST /v1/screenshots` only. Its sibling
+`client.screenshots.getWithResponse()` is still additive and safe to call, but
+`GET /v1/screenshots/{id}` emits none of those headers, so `headers` will be
+empty for it. Any other endpoint's headers are reachable through the generic
 transport, `client.requestWithResponse('GET', '/v1/scrape/sc_123abc')`.
 
 These siblings are purely additive: they issue the identical request and accept the

package/dist/allowlist.d.ts

@@ -10,3 +10,25 @@
  */
 export declare const V01_METHODS: readonly ["scrape.create", "scrape.get", "screenshots.create", "screenshots.get", "bulk.create", "bulk.get", "bulk.cancel", "bulk.screenshots.list", "scrape.bulk.create", "scrape.bulk.get", "fetch.create", "fetch.get", "fetch.bulk.create", "fetch.bulk.get", "monitors.create", "monitors.list", "monitors.get", "monitors.update", "monitors.delete", "monitors.captures.list", "sitemap.create", "sitemap.get", "search.query", "account.get", "usage.get", "usage.daily", "usage.byEndpoint", "webhooks.list", "webhooks.retry"];
 export type V01Method = (typeof V01_METHODS)[number];
+/**
+ * Methods that exist on the real, instantiated `ByteKit` client surface but are
+ * deliberately EXCLUDED from `V01_METHODS` — each with the reason it stays off the
+ * v0.1 parity guard.
+ *
+ * `parity.test.ts` only compares the OpenAPI spec's `x-sdk-scope: v0.1` operations
+ * against `V01_METHODS` — it says nothing about what the actual client *instance*
+ * exposes. That gap is how the six `account.apiKeys.*` methods shipped unguarded
+ * (issue #2595): they are real, callable methods on `client.account.apiKeys`, are
+ * NOT in `V01_METHODS`, and no test walked the instantiated surface to notice.
+ *
+ * `surface-guard.test.ts` walks the real client and asserts every callable is
+ * either in `V01_METHODS` or listed here — removing a method (from either list) or
+ * adding an undocumented one fails that test. To add a new client-surface method
+ * that is deliberately NOT part of the v0.1 Bearer-key parity guarantee, add an
+ * entry here with the reason; to add one that IS part of it, add it to
+ * `V01_METHODS` instead (and annotate the spec operation with `x-sdk-method`).
+ */
+export declare const DOCUMENTED_SURFACE_EXCEPTIONS: ReadonlyArray<{
+    readonly method: string;
+    readonly reason: string;
+}>;

package/dist/allowlist.js

@@ -42,3 +42,67 @@ export const V01_METHODS = [
     'webhooks.list',
     'webhooks.retry',
 ];
+/**
+ * Methods that exist on the real, instantiated `ByteKit` client surface but are
+ * deliberately EXCLUDED from `V01_METHODS` — each with the reason it stays off the
+ * v0.1 parity guard.
+ *
+ * `parity.test.ts` only compares the OpenAPI spec's `x-sdk-scope: v0.1` operations
+ * against `V01_METHODS` — it says nothing about what the actual client *instance*
+ * exposes. That gap is how the six `account.apiKeys.*` methods shipped unguarded
+ * (issue #2595): they are real, callable methods on `client.account.apiKeys`, are
+ * NOT in `V01_METHODS`, and no test walked the instantiated surface to notice.
+ *
+ * `surface-guard.test.ts` walks the real client and asserts every callable is
+ * either in `V01_METHODS` or listed here — removing a method (from either list) or
+ * adding an undocumented one fails that test. To add a new client-surface method
+ * that is deliberately NOT part of the v0.1 Bearer-key parity guarantee, add an
+ * entry here with the reason; to add one that IS part of it, add it to
+ * `V01_METHODS` instead (and annotate the spec operation with `x-sdk-method`).
+ */
+export const DOCUMENTED_SURFACE_EXCEPTIONS = [
+    // account.apiKeys.* — x-sdk-scope: internal in the spec (Clerk-session-only auth;
+    // a Bearer API key 401s on every one of these). Deliberate retention: the resource
+    // stays on the SDK surface for dashboard/session consumers rather than being
+    // removed, matching the split documented in README.md's "Account, usage, and API
+    // keys" section (issue #2595).
+    {
+        method: 'account.apiKeys.create',
+        reason: 'Clerk-session-only (x-sdk-scope: internal) — deliberate retention for dashboard/session consumers, not part of the Bearer-key v0.1 surface.',
+    },
+    {
+        method: 'account.apiKeys.list',
+        reason: 'Clerk-session-only (x-sdk-scope: internal) — deliberate retention for dashboard/session consumers, not part of the Bearer-key v0.1 surface.',
+    },
+    {
+        method: 'account.apiKeys.get',
+        reason: 'Clerk-session-only (x-sdk-scope: internal) — deliberate retention for dashboard/session consumers, not part of the Bearer-key v0.1 surface.',
+    },
+    {
+        method: 'account.apiKeys.update',
+        reason: 'Clerk-session-only (x-sdk-scope: internal) — deliberate retention for dashboard/session consumers, not part of the Bearer-key v0.1 surface.',
+    },
+    {
+        method: 'account.apiKeys.revoke',
+        reason: 'Clerk-session-only (x-sdk-scope: internal) — deliberate retention for dashboard/session consumers, not part of the Bearer-key v0.1 surface.',
+    },
+    {
+        method: 'account.apiKeys.reveal',
+        reason: 'Clerk-session-only (x-sdk-scope: internal) — deliberate retention for dashboard/session consumers, not part of the Bearer-key v0.1 surface.',
+    },
+    // *WithResponse siblings (#2547) — additive `ApiResponse<T>` shorthands over an
+    // already-allowlisted base method (same HTTP method, path, and body). Not a
+    // distinct v0.1 API operation, so not a `V01_METHODS` entry in its own right.
+    {
+        method: 'screenshots.createWithResponse',
+        reason: 'Additive #2547 ApiResponse<T> shorthand over screenshots.create (same request) — not a distinct v0.1 API operation.',
+    },
+    {
+        method: 'screenshots.getWithResponse',
+        reason: 'Additive #2547 ApiResponse<T> shorthand over screenshots.get (same request) — not a distinct v0.1 API operation.',
+    },
+    {
+        method: 'sitemap.getWithResponse',
+        reason: 'Additive #2547 ApiResponse<T> shorthand over sitemap.get (same request) — not a distinct v0.1 API operation.',
+    },
+];

package/dist/client.d.ts

@@ -185,9 +185,11 @@ export declare class ByteKit {
      *
      * Use it to read the documented `X-*` metadata the API emits alongside a JSON envelope —
      * `X-Raw-Bytes`, `X-Billable-Bytes`, `X-Billing-Multiplier`, the `X-Screenshot-*` family
-     * — for any endpoint. `sitemap.getWithResponse`, `screenshots.createWithResponse` and
-     * `screenshots.getWithResponse` are typed shorthands over this for the endpoints whose
-     * headers are documented in the API reference.
+     * — for any endpoint. `sitemap.getWithResponse` and `screenshots.createWithResponse` are
+     * typed shorthands over this for the endpoints whose headers are documented in the API
+     * reference. `screenshots.getWithResponse` is the same shorthand shape applied to
+     * `GET /v1/screenshots/{id}`, which the spec declares with NO `X-*` response headers — call
+     * it for the typed body, not for header metadata.
      */
     requestWithResponse<T>(method: string, path: string, body?: unknown, options?: RequestOptions): Promise<ApiResponse<T>>;
 }

package/dist/client.js

@@ -426,9 +426,11 @@ export class ByteKit {
      *
      * Use it to read the documented `X-*` metadata the API emits alongside a JSON envelope —
      * `X-Raw-Bytes`, `X-Billable-Bytes`, `X-Billing-Multiplier`, the `X-Screenshot-*` family
-     * — for any endpoint. `sitemap.getWithResponse`, `screenshots.createWithResponse` and
-     * `screenshots.getWithResponse` are typed shorthands over this for the endpoints whose
-     * headers are documented in the API reference.
+     * — for any endpoint. `sitemap.getWithResponse` and `screenshots.createWithResponse` are
+     * typed shorthands over this for the endpoints whose headers are documented in the API
+     * reference. `screenshots.getWithResponse` is the same shorthand shape applied to
+     * `GET /v1/screenshots/{id}`, which the spec declares with NO `X-*` response headers — call
+     * it for the typed body, not for header metadata.
      */
     async requestWithResponse(method, path, body, options) {
         // Same continuation shape as request()/requestRaw() (#2546): the readBody continuation

package/dist/generated/api.d.ts

@@ -155,6 +155,9 @@ export interface paths {
          * Capture a screenshot
          * @description Sync by default (holds up to 28s). Pass `?async=true` to return 202 immediately.
          *     Poll via GET /v1/screenshots/{id}.
+         *
+         *     **Limits:** request bodies are capped at 512 KB. An oversized body
+         *     returns a `400` with error code `request_too_large`.
          */
         post: operations["createScreenshot"];
         delete?: never;
@@ -277,6 +280,9 @@ export interface paths {
         /**
          * Fetch a URL (POST)
          * @description Same as GET /v1/fetch but with a JSON request body.
+         *
+         *     **Limits:** request bodies are capped at 512 KB. An oversized body
+         *     returns a `400` with error code `request_too_large`.
          */
         post: operations["postFetch"];
         delete?: never;
@@ -298,6 +304,17 @@ export interface paths {
          * Bulk fetch URLs
          * @description Enqueues multiple URLs for HTTP fetching. Results delivered via webhook.
          *     Does not support options that require page rendering (cookies, wait_for_selector, etc.).
+         *
+         *     **Limits:** request bodies are guarded in a two-tier shape. A streamed body
+         *     with no `Content-Length` header is capped at 2 MB before your API key
+         *     is checked; a body that declares `Content-Length` is instead bounded
+         *     there by a 20 MB fail-safe (not the real limit — see below), since
+         *     that branch reads nothing until your key is verified. Once your key
+         *     is verified, a second check re-gates the body against your account's
+         *     own `max_bulk_size` (at this endpoint's per-item override budget),
+         *     which reaches 16.8 MB for the largest documented account. A
+         *     standard-plan account's effective ceiling is 2 MB; either tier's
+         *     overrun returns a `400` with error code `request_too_large`.
          */
         post: operations["createFetchBulk"];
         delete?: never;
@@ -343,6 +360,17 @@ export interface paths {
          *     Provide `urls` (simple list) or `items` (per-item config), not both.
          *     Webhook deliveries include `X-ByteKit-Event: bulk.completed` so
          *     receivers can dispatch on the header without parsing the body shape.
+         *
+         *     **Limits:** request bodies are guarded in a two-tier shape. A streamed body
+         *     with no `Content-Length` header is capped at 4 MB before your API key
+         *     is checked; a body that declares `Content-Length` is instead bounded
+         *     there by a 32 MB fail-safe (not the real limit — see below), since
+         *     that branch reads nothing until your key is verified. Once your key
+         *     is verified, a second check re-gates the body against your account's
+         *     own `max_bulk_size` (at this endpoint's richer per-item override
+         *     budget), which reaches 28.7 MB for the largest documented account. A
+         *     standard-plan account's effective ceiling is 4 MB; either tier's
+         *     overrun returns a `400` with error code `request_too_large`.
          */
         post: operations["createBulk"];
         delete?: never;
@@ -402,6 +430,9 @@ export interface paths {
         /**
          * Create a change-detection monitor
          * @description Creates a recurring change-detection monitor for a URL, delivering results via webhook.
+         *
+         *     **Limits:** request bodies are capped at 512 KB. An oversized body
+         *     returns a `400` with error code `request_too_large`.
          */
         post: operations["createMonitor"];
         delete?: never;
@@ -462,6 +493,9 @@ export interface paths {
          *     Webhook deliveries include `X-ByteKit-Event: sitemap.completed` or
          *     `X-ByteKit-Event: sitemap.failed` so receivers can dispatch on the
          *     header without parsing the body shape.
+         *
+         *     **Limits:** request bodies are capped at 512 KB. An oversized body
+         *     returns a `400` with error code `request_too_large`.
          */
         post: operations["createSitemap"];
         delete?: never;
@@ -917,6 +951,12 @@ export interface paths {
         /**
          * Stripe webhook receiver
          * @description Receives Stripe webhook events. Verified via signature.
+         *
+         *     **Limits:** request bodies are capped at 256 KB — real Stripe event
+         *     payloads stay in the tens of KB. An oversized body returns a `400`
+         *     with a bespoke `{ error }` body (this route predates issue #699's
+         *     unified REST envelope and answers Stripe's own webhook contract, not
+         *     the public API's error shape).
          */
         post: operations["stripeWebhook"];
         delete?: never;
@@ -954,6 +994,10 @@ export interface paths {
         /**
          * Retry a webhook delivery
          * @description Requeues a failed or exhausted webhook delivery for another attempt.
+         *
+         *     **Limits:** this endpoint takes no request body; any body sent is
+         *     capped at 64 KB. An oversized body returns a `400` with error code
+         *     `request_too_large`.
          */
         post: operations["retryWebhookDelivery"];
         delete?: never;
@@ -1236,6 +1280,12 @@ export interface paths {
          * Clerk webhook receiver
          * @description Receives Clerk events (user.created, user.updated, user.deleted, etc.).
          *     Authentication is via Svix signature verification — no bearer token required.
+         *
+         *     **Limits:** request bodies are capped at 256 KB — real Clerk event
+         *     payloads (user/membership/invitation objects) stay well under this.
+         *     An oversized body returns a `400` with error code `request_too_large`
+         *     (bespoke `{ error }` slug shape, matching this route's existing
+         *     error convention, not the unified REST envelope).
          */
         post: operations["clerkWebhook"];
         delete?: never;
@@ -2605,6 +2655,15 @@ export interface operations {
                     "application/json": components["schemas"]["AccountBearerResponse"] | components["schemas"]["AccountSessionResponse"];
                 };
             };
+            /** @description Rate limit exceeded (`rate_limited`). Only reachable when authenticated via Clerk session (the 60-request/60-second per-user window) — the bearer and in-process auth branches are not rate-limited at this endpoint. Carries a `Retry-After` header derived from the same clock as the window reset. */
+            429: {
+                headers: {
+                    [name: string]: unknown;
+                };
+                content: {
+                    "application/json": components["schemas"]["Error"];
+                };
+            };
         };
     };
     deleteAccount: {
@@ -2690,6 +2749,15 @@ export interface operations {
                     "application/json": components["schemas"]["Error"];
                 };
             };
+            /** @description Rate limit exceeded (`rate_limited`) — the Clerk-session 60-request/60-second per-user window. Carries a `Retry-After` header derived from the same clock as the window reset. */
+            429: {
+                headers: {
+                    [name: string]: unknown;
+                };
+                content: {
+                    "application/json": components["schemas"]["Error"];
+                };
+            };
         };
     };
     listApiKeys: {
@@ -2916,7 +2984,7 @@ export interface operations {
                     "application/json": components["schemas"]["Error"];
                 };
             };
-            /** @description Rate limit exceeded. */
+            /** @description Reveal rate limit exceeded (per-account anti-harvest cap, distinct from the per-second API rate limit). Carries a `Retry-After` header. */
             429: {
                 headers: {
                     [name: string]: unknown;
@@ -3054,6 +3122,15 @@ export interface operations {
                     "application/json": components["schemas"]["Error"];
                 };
             };
+            /** @description Rate limit (`rate_limited`) or concurrency limit (`concurrency_limit`) exceeded. Carries a `Retry-After` header — seconds derived from the same clock as `X-RateLimit-Reset` for the rate-limit variant, a fixed small back-off for the concurrency variant. */
+            429: {
+                headers: {
+                    [name: string]: unknown;
+                };
+                content: {
+                    "application/json": components["schemas"]["Error"];
+                };
+            };
         };
     };
     getScreenshot: {
@@ -3246,7 +3323,7 @@ export interface operations {
                     "application/json": components["schemas"]["Error"];
                 };
             };
-            /** @description Rate limit exceeded. */
+            /** @description Rate limit (`rate_limited`) or concurrency limit (`concurrency_limit`) exceeded. Carries a `Retry-After` header — seconds derived from the same clock as `X-RateLimit-Reset` for the rate-limit variant, a fixed small back-off for the concurrency variant. */
             429: {
                 headers: {
                     [name: string]: unknown;
@@ -3446,8 +3523,9 @@ export interface operations {
                         created_at: string;
                         /** Format: date-time */
                         completed_at: string | null;
-                        total_credits_charged: number;
-                        /** @description Estimated credits at submission time. Null in GET responses. */
+                        /** @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. */
+                        total_credits_charged: number | null;
+                        /** @description Estimated credits at submission time. Null in GET responses. Fractional — markdown/html formats weigh 0.5 credits each (scrape-shared/src/credits.ts), so a one-item markdown job is 1.5. */
                         estimated_credits: number | null;
                         /** @description Webhook endpoint URL (HTTPS only; http:// rejected with 400 invalid_url, reason scheme_unsupported) */
                         webhook_url: string;
@@ -3523,7 +3601,8 @@ export interface operations {
                         created_at: string;
                         /** Format: date-time */
                         completed_at: string | null;
-                        total_credits_charged: number;
+                        /** @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) */
@@ -3610,6 +3689,15 @@ export interface operations {
                     "application/json": components["schemas"]["Error"];
                 };
             };
+            /** @description Rate limit (`rate_limited`) or concurrency limit (`concurrency_limit`) exceeded. Carries a `Retry-After` header — seconds derived from the same clock as `X-RateLimit-Reset` for the rate-limit variant, a fixed small back-off for the concurrency variant. */
+            429: {
+                headers: {
+                    [name: string]: unknown;
+                };
+                content: {
+                    "application/json": components["schemas"]["Error"];
+                };
+            };
             /**
              * @description Fetch service unavailable, content transform failed, or a non-2xx upstream
              *     response relayed as the unified Error envelope. On an upstream relay the HTTP
@@ -3699,6 +3787,15 @@ export interface operations {
                     "application/json": components["schemas"]["Error"];
                 };
             };
+            /** @description Rate limit (`rate_limited`) or concurrency limit (`concurrency_limit`) exceeded. Carries a `Retry-After` header — seconds derived from the same clock as `X-RateLimit-Reset` for the rate-limit variant, a fixed small back-off for the concurrency variant. */
+            429: {
+                headers: {
+                    [name: string]: unknown;
+                };
+                content: {
+                    "application/json": components["schemas"]["Error"];
+                };
+            };
             /**
              * @description Fetch service unavailable, content transform failed, or a non-2xx upstream
              *     response relayed as the unified Error envelope. On an upstream relay the HTTP
@@ -3758,7 +3855,25 @@ export interface operations {
                     [name: string]: unknown;
                 };
                 content: {
-                    "application/json": Record<string, never>;
+                    "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 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. */
+                        total_credits_charged: number | null;
+                        /** @description Estimated credits at submission time. Null in GET responses. Fractional — markdown/html formats weigh 0.5 credits each (scrape-shared/src/credits.ts), so a one-item markdown job is 1.5. */
+                        estimated_credits: number | null;
+                        /** @description Webhook endpoint URL (HTTPS only; http:// rejected with 400 invalid_url, reason scheme_unsupported) */
+                        webhook_url: string;
+                    };
                 };
             };
             /**
@@ -3812,7 +3927,45 @@ export interface operations {
                     [name: string]: unknown;
                 };
                 content: {
-                    "application/json": Record<string, never>;
+                    "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;
+                        /** @description Per-URL fetch items, oldest first, capped at 500 (listBulkFetchItemsWithLatestAttempt). */
+                        items: {
+                            /** @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;
+                            content_url: string | null;
+                            waf_vendor: string | null;
+                            cache_hit: boolean;
+                            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. */
@@ -3855,7 +4008,8 @@ export interface operations {
                         created_at: string;
                         /** Format: date-time */
                         completed_at: string | null;
-                        total_credits_charged: number;
+                        /** @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) */
@@ -3938,7 +4092,7 @@ export interface operations {
                         /** Format: uri */
                         url: string;
                         /**
-                         * @default screenshot
+                         * @description Capture kind for this entry. If omitted, inherits `defaults.type`; if that is also omitted, falls back to `screenshot`.
                          * @enum {string}
                          */
                         type?: "screenshot" | "scrape";
@@ -4060,8 +4214,9 @@ export interface operations {
                         created_at: string;
                         /** Format: date-time */
                         completed_at: string | null;
-                        total_credits_charged: number;
-                        /** @description Estimated credits at submission time. Null in GET responses. */
+                        /** @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. */
+                        total_credits_charged: number | null;
+                        /** @description Estimated credits at submission time. Null in GET responses. Fractional — markdown/html formats weigh 0.5 credits each (scrape-shared/src/credits.ts), so a one-item markdown job is 1.5. */
                         estimated_credits: number | null;
                         /** @description Webhook endpoint URL (HTTPS only; http:// rejected with 400 invalid_url, reason scheme_unsupported) */
                         webhook_url: string;
@@ -4090,7 +4245,17 @@ export interface operations {
             /**
              * @description Validation error. `bulk_too_large` is returned when the item count
              *     exceeds the account plan's `max_bulk_size` cap (also surfaced as
-             *     `max_bulk_size` on `GET /v1/account`).
+             *     `max_bulk_size` on `GET /v1/account`). `validation_error` is
+             *     returned when the request body contains an unrecognized key
+             *     anywhere in the top-level object, an `items[]` entry, or
+             *     `defaults` — all three reject unknown keys with a 422
+             *     `validation_error` whose `details` message names the offending
+             *     key, instead of silently discarding it. The two nested objects
+             *     do not accept the same field set: `device_scale_factor` is
+             *     `defaults`-only (rejected per item), and `duration`/`scenario`
+             *     are `items[]`-only (rejected under `defaults`). `metadata` is
+             *     valid both at the top level of the body and per item, but is
+             *     rejected with this same 422 if placed under `defaults`.
              */
             422: {
                 headers: {
@@ -4131,7 +4296,8 @@ export interface operations {
                         created_at: string;
                         /** Format: date-time */
                         completed_at: string | null;
-                        total_credits_charged: number;
+                        /** @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) */
@@ -4179,7 +4345,8 @@ export interface operations {
                         created_at: string;
                         /** Format: date-time */
                         completed_at: string | null;
-                        total_credits_charged: number;
+                        /** @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 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) */
@@ -4215,7 +4382,48 @@ export interface operations {
                     [name: string]: unknown;
                 };
                 content: {
-                    "application/json": Record<string, never>;
+                    "application/json": {
+                        /** @example bulk_01j9abc123 */
+                        bulk_id: string;
+                        /** @description Number of items in `items` (page size, not the job total). */
+                        total: number;
+                        /** @description Heterogeneous capture items discriminated by `type`. Fields outside the common set are present only for the matching `type`. */
+                        items: {
+                            /** @enum {string} */
+                            type: "screenshot" | "recording" | "scrape";
+                            /** @description Prefixed id — `ss_` / `rec_` / `sc_` per `type`. */
+                            id: string;
+                            /** @enum {string} */
+                            status: "pending" | "processing" | "completed" | "failed" | "cancelled";
+                            /** Format: uri */
+                            url: string;
+                            credits_charged: number | null;
+                            error_code: string | null;
+                            error_message: string | null;
+                            /** Format: date-time */
+                            created_at: string;
+                            /** Format: date-time */
+                            completed_at: string | null;
+                            /** @description `type: screenshot` only. Presigned for completed rows with a storage key; raw image_url otherwise. */
+                            image_url?: string | null;
+                            /** @description `type: screenshot` and `type: scrape` only. */
+                            page_title?: string | null;
+                            /** @description `type: recording` only. */
+                            format?: string;
+                            /** @description `type: recording` only. */
+                            video_url?: string | null;
+                            /** @description `type: scrape` only. */
+                            content_url?: string | null;
+                            /** @description `type: scrape` only. */
+                            content_type?: string | null;
+                            /** @description `type: scrape` only. */
+                            content_length?: number | null;
+                            /** @description `type: scrape` only. Always null in bulk listings — fetch the body via `markdown_url`. */
+                            markdown?: string | null;
+                            /** @description `type: scrape` only. */
+                            markdown_url?: string | null;
+                        }[];
+                    };
                 };
             };
         };
@@ -4524,6 +4732,15 @@ export interface operations {
                     "application/json": components["schemas"]["Error"];
                 };
             };
+            /** @description Rate limit (`rate_limited`) or concurrency limit (`concurrency_limit`) exceeded. Carries a `Retry-After` header — seconds derived from the same clock as `X-RateLimit-Reset` for the rate-limit variant, a fixed small back-off for the concurrency variant. */
+            429: {
+                headers: {
+                    [name: string]: unknown;
+                };
+                content: {
+                    "application/json": components["schemas"]["Error"];
+                };
+            };
         };
     };
     getSitemap: {
@@ -4563,6 +4780,15 @@ export interface operations {
                     "application/json": components["schemas"]["Error"];
                 };
             };
+            /** @description The id path segment is not a well-formed sitemap job id (genuinely malformed — a well-formed-but-absent id returns 404, not 422; see the Inverse case in issue */
+            422: {
+                headers: {
+                    [name: string]: unknown;
+                };
+                content: {
+                    "application/json": components["schemas"]["Error"];
+                };
+            };
         };
     };
     createSearch: {
@@ -4656,7 +4882,7 @@ export interface operations {
                             /** Format: uri */
                             url: string;
                             /** @description Short text excerpt for the result. Present for `web` and `news` results; omitted for `images` results. */
-                            snippet: string;
+                            snippet?: string;
                             /** @description Published date of the result. For `web` and `news` results the key is always present but is `null` when the provider reports no date; omitted entirely for `images` results. */
                             date?: string | null;
                             /** @description Publisher / source name. Present for `news` and `images` results, when the provider reports one. */
@@ -4710,7 +4936,7 @@ export interface operations {
                     "application/json": components["schemas"]["Error"];
                 };
             };
-            /** @description Rate limit exceeded. */
+            /** @description Rate limit exceeded (`rate_limited`). Carries the `X-RateLimit-Limit`/`X-RateLimit-Remaining`/`X-RateLimit-Reset` triplet and a `Retry-After` header. The window is per-second for a bearer API key, or the 60-request/60-second Clerk session window when authenticated via `resolveDualAuth` — `Retry-After` reflects whichever window applies to the request. */
             429: {
                 headers: {
                     [name: string]: unknown;
@@ -5876,6 +6102,21 @@ export interface operations {
                 };
                 content?: never;
             };
+            /**
+             * @description Bad request. Returned when the request body exceeds this
+             *     endpoint's 256 KB size limit (bespoke `{ error }` body, not the
+             *     unified envelope — see the endpoint description).
+             */
+            400: {
+                headers: {
+                    [name: string]: unknown;
+                };
+                content: {
+                    "application/json": {
+                        error?: string;
+                    };
+                };
+            };
         };
     };
     listWebhookDeliveries: {
@@ -5929,6 +6170,18 @@ export interface operations {
                     "application/json": components["schemas"]["WebhookDeliveryResponse"];
                 };
             };
+            /**
+             * @description Bad request. Returned when the request body exceeds this
+             *     endpoint's size limit; the error code is `request_too_large`.
+             */
+            400: {
+                headers: {
+                    [name: string]: unknown;
+                };
+                content: {
+                    "application/json": components["schemas"]["Error"];
+                };
+            };
             /** @description Delivery not found or not in a retryable state. */
             404: {
                 headers: {
@@ -6145,6 +6398,15 @@ export interface operations {
                     "application/json": components["schemas"]["Error"];
                 };
             };
+            /** @description Rate limit exceeded (`rate_limited`) — the Clerk-session 60-request/60-second per-user window. Carries a `Retry-After` header derived from the same clock as the window reset. */
+            429: {
+                headers: {
+                    [name: string]: unknown;
+                };
+                content: {
+                    "application/json": components["schemas"]["Error"];
+                };
+            };
         };
     };
     updateMe: {
@@ -6181,6 +6443,15 @@ export interface operations {
                     "application/json": components["schemas"]["Error"];
                 };
             };
+            /** @description Rate limit exceeded (`rate_limited`) — the Clerk-session 60-request/60-second per-user window. Carries a `Retry-After` header derived from the same clock as the window reset. */
+            429: {
+                headers: {
+                    [name: string]: unknown;
+                };
+                content: {
+                    "application/json": components["schemas"]["Error"];
+                };
+            };
         };
     };
     requestEmailChange: {
@@ -6244,6 +6515,15 @@ export interface operations {
                     "application/json": components["schemas"]["Error"];
                 };
             };
+            /** @description Rate limit exceeded (`rate_limited`) — the Clerk-session 60-request/60-second per-user window. Carries a `Retry-After` header derived from the same clock as the window reset. */
+            429: {
+                headers: {
+                    [name: string]: unknown;
+                };
+                content: {
+                    "application/json": components["schemas"]["Error"];
+                };
+            };
         };
     };
     removeMember: {
@@ -6387,6 +6667,15 @@ export interface operations {
                     "application/json": components["schemas"]["Error"];
                 };
             };
+            /** @description Rate limit exceeded (`rate_limited`) — the Clerk-session 60-request/60-second per-user window. Carries a `Retry-After` header derived from the same clock as the window reset. */
+            429: {
+                headers: {
+                    [name: string]: unknown;
+                };
+                content: {
+                    "application/json": components["schemas"]["Error"];
+                };
+            };
         };
     };
     createInvite: {
@@ -6443,6 +6732,15 @@ export interface operations {
                     "application/json": components["schemas"]["Error"];
                 };
             };
+            /** @description Rate limit exceeded (`rate_limited`) — the Clerk-session 60-request/60-second per-user window. Carries a `Retry-After` header derived from the same clock as the window reset. */
+            429: {
+                headers: {
+                    [name: string]: unknown;
+                };
+                content: {
+                    "application/json": components["schemas"]["Error"];
+                };
+            };
         };
     };
     acceptInvite: {

package/dist/index.d.ts

@@ -3,7 +3,7 @@ export type { ByteKitOptions, RequestOptions, ApiResponse, ConnectionErrorCode }
 export { V01_METHODS } from './allowlist.js';
 export type { V01Method } from './allowlist.js';
 export type { ScrapeId, ScreenshotId, BulkId, MonitorId, SitemapId, ApiKeyId, WebhookDeliveryId, SearchType, SearchDateRange, SearchOpts, SearchResult, SearchResultImage, SearchResponse, } from './types.js';
-export type { ScrapeCookie, ScrapeCreateResponse, ScrapeGetResponse, ScrapeBulkCreateRequest, ScrapeBulkCreateResponse, ScrapeBulkGetResponse, } from './resources/scrape.js';
+export type { ScrapeCookie, ScrapeOpts, MarkdownMode, MarkdownLinks, MarkdownImages, TokenEncoding, ScrapeCreateResponse, ScrapeGetResponse, ScrapeBulkCreateRequest, ScrapeBulkCreateResponse, ScrapeBulkGetResponse, } from './resources/scrape.js';
 export type { ScreenshotCreateRequest, ScreenshotCreateResponse, ScreenshotGetResponse, } from './resources/screenshots.js';
 export type { FetchOpts, FetchGetOpts, FetchResult, FetchCacheStatus, FetchBulkCreateRequest, FetchBulkCreateResponse, FetchBulkGetResponse, } from './resources/fetch.js';
 export type { MonitorCreateRequest, MonitorCreateResponse, ListMonitorsParams, MonitorStatus, ListMonitorsResponse, MonitorResponse, MonitorUpdateRequest, UpdateMonitorResponse, ListMonitorCapturesResponse, } from './resources/monitors.js';

package/dist/resources/fetch.js

@@ -14,7 +14,10 @@ const CACHE_STATUSES = ['hit', 'miss', 'bypass'];
 function toFetchResult(raw) {
     const { body, bytes, headers } = raw;
     const creditsRaw = headers.get('X-Fetch-Credits-Charged');
-    const credits = creditsRaw === null ? NaN : Number(creditsRaw);
+    // An empty-but-present header must be treated the same as an absent one: `Number('')`
+    // is `0` (finite), so without this check an empty header parsed as a real zero-credit
+    // charge instead of "unparseable" (#2595).
+    const credits = creditsRaw === null || creditsRaw.trim() === '' ? NaN : Number(creditsRaw);
     const cacheRaw = headers.get('X-Fetch-Cache');
     return {
         body,

package/dist/resources/monitors.d.ts

@@ -46,6 +46,19 @@ export type MonitorUpdateRequest = operations['updateMonitor']['requestBody']['c
 export type UpdateMonitorResponse = operations['updateMonitor']['responses'][200]['content']['application/json'];
 /** 200 payload of GET /v1/monitors/{id}/captures — the paginated capture list. */
 export type ListMonitorCapturesResponse = operations['listMonitorCaptures']['responses'][200]['content']['application/json'];
+/**
+ * Query params of GET /v1/monitors/{id}/captures — `limit`/`cursor`, both optional and
+ * omitted when unset.
+ *
+ * DERIVED from the generated `listMonitorCaptures` query type (#2594), mirroring
+ * {@link ListMonitorsParams} — never hand-authored, so a spec drift (a renamed/removed query
+ * param) surfaces as a `tsc` error here rather than a silent request-shape mismatch (E1).
+ *
+ * Still a `type` alias (not an `interface`), for the same implicit-index-signature reason as
+ * {@link ListMonitorsParams} — it must stay assignable to {@link toQueryString}'s
+ * `Record<string, string | number | undefined>` param.
+ */
+export type ListMonitorCapturesParams = NonNullable<operations['listMonitorCaptures']['parameters']['query']>;
 export declare class MonitorsResource {
     private readonly client;
     readonly captures: MonitorCapturesResource;
@@ -79,7 +92,13 @@ export declare class MonitorsResource {
 declare class MonitorCapturesResource {
     private readonly client;
     constructor(client: ByteKit);
-    /** GET /v1/monitors/{id}/captures — list captures for a monitor */
-    list(id: MonitorId, requestOptions?: RequestOptions): Promise<ListMonitorCapturesResponse>;
+    /**
+     * GET /v1/monitors/{id}/captures — list captures for a monitor.
+     *
+     * `params` is optional and each key is omitted-when-absent (#2594), so `list(id)` with no
+     * second argument serializes the bare `/v1/monitors/{id}/captures` URL unchanged — existing
+     * zero-arg callers are unaffected (inverse case).
+     */
+    list(id: MonitorId, params?: ListMonitorCapturesParams, requestOptions?: RequestOptions): Promise<ListMonitorCapturesResponse>;
 }
 export {};

package/dist/resources/monitors.js

@@ -47,8 +47,14 @@ class MonitorCapturesResource {
     constructor(client) {
         this.client = client;
     }
-    /** GET /v1/monitors/{id}/captures — list captures for a monitor */
-    list(id, requestOptions) {
-        return this.client.request('GET', `/v1/monitors/${id}/captures`, undefined, requestOptions);
+    /**
+     * GET /v1/monitors/{id}/captures — list captures for a monitor.
+     *
+     * `params` is optional and each key is omitted-when-absent (#2594), so `list(id)` with no
+     * second argument serializes the bare `/v1/monitors/{id}/captures` URL unchanged — existing
+     * zero-arg callers are unaffected (inverse case).
+     */
+    list(id, params, requestOptions) {
+        return this.client.request('GET', `/v1/monitors/${id}/captures${toQueryString(params)}`, undefined, requestOptions);
     }
 }

package/package.json

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