@hunt-labs/bytekit-sdk 0.3.0 → 0.5.0

package/CHANGELOG.md

@@ -8,6 +8,91 @@ 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
+
+- `RequestOptions` (per-call `requestTimeoutMs` + caller `signal`) is now accepted by
+  **every** resource method, not just `scrape.create` / `scrape.get`. It is always a
+  trailing optional parameter — on `screenshots.create` it is the third positional, after
+  `params` — so every existing call site compiles and serializes byte-identically. Per-call
+  options continue to beat the constructor's `timeoutMs` default; omitting them leaves the
+  constructor default in force exactly as before. (#2547)
+- `ApiResponse<T>` (`{ data, headers, status }`), a generic `client.requestWithResponse<T>()`
+  transport, and three typed siblings — `sitemap.getWithResponse`,
+  `screenshots.createWithResponse`, `screenshots.getWithResponse` — make the documented
+  `X-Raw-Bytes`, `X-Billable-Bytes`, `X-Billing-Multiplier` and `X-Screenshot-*` response
+  headers reachable. This surface is purely **additive**: it issues the identical request
+  with the identical options as the base method, and no existing return type changes.
+  (#2547)
+- `MonitorStatus` and `ScrapeCookie` are exported from the package entrypoint. (#2547)
+
+### Changed (**BREAKING** at compile time)
+
+- `ScrapeOpts.cookies` is now `ScrapeCookie[]`, derived from the spec's `Cookie` schema
+  (`name` and `value` required; `domain`, `path`, `secure`, `httpOnly` optional), instead of
+  an open bag of untyped records. A cookie missing `name` used to compile and fail as a 422
+  on the wire; it is a compile error now. Serialization is unchanged. (#2547)
+- `ListMonitorsParams.status` is now the spec enum
+  (`'active' | 'processing' | 'paused' | 'cancelled' | 'suspended'`), derived from the
+  generated `listMonitors` query type, instead of `string`. A typo like `'activee'` used to
+  compile and 422; it is a compile error now. The serialized query string is unchanged.
+  (#2547)
+
+### Fixed
+
+- `timeoutMs` / `requestTimeoutMs` (and a caller-supplied `signal`) now cover the
+  **response body read**, not just the time to first byte of headers. The abort budget was
+  armed for `fetch` and cleared the moment headers arrived, after which `request()`'s
+  `response.text()`, `requestRaw()`'s `response.arrayBuffer()`, and the error-body
+  `response.json()` on a non-2xx all read the body unbounded — so a server that answered
+  with headers and then stalled its body hung the caller forever. A mid-body abort now
+  surfaces as `ByteKitConnectionError` with `code: 'timeout'` (budget) or `'aborted'`
+  (caller signal) instead of a bare `TypeError: terminated`.
+
+  The default is **unchanged at 120 s**, and the precedence table for
+  `signal` / `requestTimeoutMs` / `timeoutMs` is untouched. One consequence worth planning
+  for: a legitimately large body (a multi-MB `/v1/fetch` document) now counts against that
+  same budget, where previously only the wait for headers did. (#2546)
+
+- The README's webhook-retry sample used an invalid delivery id prefix (`whd_`) that its own
+  branded type rejects. The sample is corrected, and a new test compiles every TypeScript
+  sample in the README against the SDK's sources so a non-compiling sample can no longer
+  ship. (#2547)
+
+### Fixed (**BREAKING** at compile time)
+
+- `fetch.get` no longer accepts the eleven markdown-tuning options (`markdown_mode`,
+  `markdown_query`, `markdown_links`, `markdown_images`, `with_links_summary`,
+  `with_images_summary`, `markdown_compact`, `markdown_filter_images`,
+  `markdown_include_media`, `markdown_include_warnings`, `markdown_include_stats`).
+  The spec's `GET /v1/fetch` declares only `url`, `format`, `country`, `timeout_ms`
+  and `cache_ttl`, so those options were silently dropped by the query builder — a
+  caller asking for `markdown_mode: 'llm'` compiled and received default article-mode
+  markdown. They are now compile errors instead of silent no-ops; use `fetch.create`
+  (POST), which accepts and serializes all of them unchanged. `FetchGetOpts` is now
+  derived from the generated `getFetch` query type, so future spec drift fails
+  `tsc --noEmit` rather than reaching production. (#2539)
+
 ## [0.3.0] - 2026-07-21
 
 ### Removed (**BREAKING**)
@@ -135,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

@@ -155,13 +155,14 @@ await client.monitors.delete('mon_123abc');
 ### Sitemap crawl
 
 ```ts
+// `url` is the only required field — every other option can be omitted.
+const minimal = await client.sitemap.create({ url: 'https://example.com' });
+
 const crawl = await client.sitemap.create({
   url: 'https://example.com',
   strategy: 'standard',
   max_depth: 2,
   max_urls: 5000,
-  process: null,
-  webhook_secret: null,
   cache_ttl: '30d',
   compact: false,
 });
@@ -181,15 +182,45 @@ const byEndpoint = await client.usage.byEndpoint();
 
 // Webhook deliveries
 const deliveries = await client.webhooks.list();
-await client.webhooks.retry('whd_123abc');
+await client.webhooks.retry('wh_123abc');
+```
+
+> **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
+
+The API carries billing and capture metadata in `X-*` response headers alongside the
+JSON body — `X-Raw-Bytes`, `X-Billable-Bytes`, `X-Billing-Multiplier`, and the
+`X-Screenshot-*` family. Every resource method returns just the parsed body, so use a
+`*WithResponse` sibling when you also need the headers:
+
+```ts
+const { data, headers, status } = await client.sitemap.getWithResponse('sm_123abc');
+
+console.log(data.status); // exactly what sitemap.get('sm_123abc') resolves to
+console.log(headers.get('X-Raw-Bytes')); // e.g. "12345"
+console.log(status); // 200
 ```
 
-> **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.
+`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
+identical options as their base methods, and `data` is exactly what the base method
+resolves to — no existing return type changes.
 
 ## Error handling
 

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

@@ -13,7 +13,9 @@ export interface ByteKitOptions {
     baseUrl?: string;
     /**
      * Default CLIENT-SIDE request timeout in ms — the abort budget for the whole HTTP
-     * round-trip made by this SDK. `0` disables the SDK-side timeout. Default 120000.
+     * round-trip made by this SDK, covering time-to-headers **and** the response body
+     * read (so a large legitimate body counts against it too). `0` disables the SDK-side
+     * timeout. Default 120000.
      *
      * NOT the same thing as `ScrapeOpts.timeout_ms`, which is the SERVER-side budget the
      * gateway applies to the scrape itself. Override per call with
@@ -26,12 +28,14 @@ export interface RequestOptions {
     /**
      * Caller-owned abort signal. When supplied WITHOUT a per-call `requestTimeoutMs`, it
      * fully replaces the constructor timeout — supply `requestTimeoutMs` alongside it to
-     * keep a bound (the request then aborts on whichever fires first).
+     * keep a bound (the request then aborts on whichever fires first). Firing it aborts an
+     * in-flight response body read as well, not only the wait for headers.
      */
     signal?: AbortSignal;
     /**
-     * Per-call CLIENT-SIDE abort budget in ms. Wins over the constructor's `timeoutMs`.
-     * `0` disables the SDK-side timeout for this call.
+     * Per-call CLIENT-SIDE abort budget in ms, covering headers **and** the response body
+     * read. Wins over the constructor's `timeoutMs`. `0` disables the SDK-side timeout for
+     * this call.
      *
      * Deliberately NOT named `timeoutMs`: it rides on the same call as `ScrapeOpts.timeout_ms`
      * (the SERVER-side scrape budget), and the two mean different things —
@@ -40,6 +44,29 @@ export interface RequestOptions {
      */
     requestTimeoutMs?: number;
 }
+/**
+ * A JSON response together with its transport metadata (#2547).
+ *
+ * Returned by {@link ByteKit.requestWithResponse} and by the `*WithResponse` sibling
+ * methods. `data` is exactly what the corresponding base method resolves to, so a caller
+ * can migrate from `x = await r.get(id)` to `{ data: x, headers } = await
+ * r.getWithResponse(id)` with no change to how `x` is used.
+ *
+ * This is an ADDITIVE surface: it never changes the return type, the request bytes, or the
+ * abort semantics of any existing method.
+ */
+export interface ApiResponse<T> {
+    /** The parsed JSON body — identical to what the base method returns. `undefined` on 204/empty. */
+    data: T;
+    /**
+     * The full RESPONSE headers, e.g. `X-Raw-Bytes`, `X-Billable-Bytes`,
+     * `X-Billing-Multiplier`. The `Authorization` header lives on the REQUEST and is never
+     * reachable here.
+     */
+    headers: Headers;
+    /** The HTTP status code of the successful response (2xx; non-2xx already threw). */
+    status: number;
+}
 /** Why a request never produced an HTTP response. */
 export type ConnectionErrorCode = 'timeout' | 'aborted' | 'connection';
 /** Thrown when the API responds with a 4xx or 5xx status code. */
@@ -91,17 +118,28 @@ export declare class ByteKit {
      */
     private resolveSignal;
     /**
-     * Perform the authenticated round-trip and return the raw `Response`, having
-     * already thrown for the two non-body failure modes:
+     * Perform the authenticated round-trip and return whatever the caller's `readBody`
+     * continuation makes of the successful response, having already thrown for the two
+     * non-body failure modes:
      *
      * - `ByteKitConnectionError` when no HTTP response was produced at all
-     *   (DNS/socket/TLS failure, client-side timeout, or caller abort).
+     *   (DNS/socket/TLS failure, client-side timeout, or caller abort) — including one
+     *   that fires while the body is streaming.
      * - `ByteKitError` on any 4xx/5xx, carrying the API's `code`/`message`.
      *
-     * The body is left unread so each caller can decode it as it needs — JSON for
-     * `request()`, raw text + headers for `requestRaw()`. This is the single place
-     * that owns auth, the abort budget, and the error taxonomy; the two public
-     * transports differ only in how they read a successful body.
+     * The body is read through a continuation each caller supplies — JSON text for
+     * `request()`, raw bytes for `requestRaw()`. This is the single place that owns auth,
+     * the abort budget, and the error taxonomy; the two public transports differ only in
+     * how they read a successful body.
+     *
+     * The abort budget spans headers **and** body (#2546). Returning the `Response` used to
+     * end the guarded region at the headers boundary, leaving `response.text()` /
+     * `response.arrayBuffer()` — and the `!response.ok` branch's `response.json()` —
+     * unbounded: a server that sent headers and then stalled its body hung the caller
+     * forever. `readBody` must therefore ONLY consume the stream; `JSON.parse` and
+     * `TextDecoder` run in the callers, outside the guard, so a malformed body still
+     * surfaces its own parse error rather than being remapped to a connection error.
+     * `cleanup()` still runs exactly once per call, now after the body completes.
      */
     private send;
     /**
@@ -135,4 +173,23 @@ export declare class ByteKit {
         headers: Headers;
         status: number;
     }>;
+    /**
+     * Make an authenticated JSON request and return the parsed body TOGETHER WITH the
+     * response headers and status (#2547).
+     *
+     * Identical to {@link ByteKit.request} in every observable respect — same method, path,
+     * body, `RequestOptions` precedence, error taxonomy, and empty-body handling (both drain
+     * the body through {@link readSuccessText} and parse it through {@link parseJsonBody}). It
+     * differs only in what it returns, so nothing about an existing call changes by switching
+     * to it.
+     *
+     * 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` 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

@@ -124,12 +124,59 @@ function composeSignals(caller, timeout) {
     }
     return { signal: controller.signal, cleanup };
 }
-/** Map a `fetch` rejection onto the connection-error taxonomy. Never leaks the API key. */
+/**
+ * Read a successful response body as text INSIDE the transport's abort-guarded region
+ * (#2546), short-circuiting a 204 to `undefined`. The `JSON.parse` step is deliberately
+ * kept OUT of the guard — see {@link parseJsonBody} — so a malformed body still surfaces
+ * its own SyntaxError rather than being remapped to a `ByteKitConnectionError`.
+ *
+ * Shared as the `readBody` continuation of `request()` and (wrapped) `requestWithResponse()`
+ * so empty-body/204 handling can never diverge between the two (#2547).
+ */
+async function readSuccessText(response) {
+    return response.status === 204 ? undefined : await response.text();
+}
+/**
+ * Parse an already-read success body (see {@link readSuccessText}) into its JSON value.
+ *
+ * A 204 or otherwise-empty body resolves to `undefined` — this is how a successful
+ * `revoke()` (DELETE → 204) resolves instead of throwing a JSON-parse error. Runs OUTSIDE
+ * the transport's abort-guarded region (#2546), so `JSON.parse` failures stay ordinary
+ * SyntaxErrors. Shared by `request()` and `requestWithResponse()` (#2547).
+ */
+function parseJsonBody(text) {
+    if (text === undefined || text.trim().length === 0) {
+        return undefined;
+    }
+    return JSON.parse(text);
+}
+/** The `name` of an error-shaped value, or `undefined` when it carries none. */
+const nameOf = (e) => typeof e === 'object' && e !== null && 'name' in e ? String(e.name) : undefined;
+/** The `cause` of an error-shaped value, or `undefined` when it carries none. */
+const causeOf = (e) => typeof e === 'object' && e !== null && 'cause' in e ? e.cause : undefined;
+/**
+ * The abort-taxonomy name of a rejection, seeing through undici's mid-body wrapper.
+ *
+ * When a request is aborted while its BODY is streaming, undici does not reject with the abort
+ * reason itself — it rejects with `TypeError: terminated` carrying the reason on `.cause` (#2546).
+ * A name-only check would read that as a plain connection failure. Nothing that reached this
+ * function before #2546 carried a `.cause`, so every previously-asserted classification is
+ * unchanged; a `.cause` whose own name is not abort-shaped still falls through to `'connection'`.
+ */
+function abortNameOf(err) {
+    const top = nameOf(err);
+    if (top === 'TimeoutError' || top === 'AbortError')
+        return top;
+    return nameOf(causeOf(err));
+}
+/**
+ * Map a `fetch` or body-read rejection onto the connection-error taxonomy. Never leaks the API key.
+ */
 function toConnectionError(err, method, url, timeoutSignal) {
     // undici rejects an aborted fetch with the signal's own reason, so the thrown value's
-    // `name` is the primary discriminator (`TimeoutError` / `AbortError`).
-    const rawName = typeof err === 'object' && err !== null && 'name' in err ? err.name : undefined;
-    const name = typeof rawName === 'string' ? rawName : '';
+    // `name` is the primary discriminator (`TimeoutError` / `AbortError`) — read through
+    // undici's mid-body `TypeError: terminated` wrapper when there is one.
+    const name = abortNameOf(err) ?? '';
     let code;
     if (name === 'TimeoutError') {
         code = 'timeout';
@@ -225,19 +272,30 @@ export class ByteKit {
         };
     }
     /**
-     * Perform the authenticated round-trip and return the raw `Response`, having
-     * already thrown for the two non-body failure modes:
+     * Perform the authenticated round-trip and return whatever the caller's `readBody`
+     * continuation makes of the successful response, having already thrown for the two
+     * non-body failure modes:
      *
      * - `ByteKitConnectionError` when no HTTP response was produced at all
-     *   (DNS/socket/TLS failure, client-side timeout, or caller abort).
+     *   (DNS/socket/TLS failure, client-side timeout, or caller abort) — including one
+     *   that fires while the body is streaming.
      * - `ByteKitError` on any 4xx/5xx, carrying the API's `code`/`message`.
      *
-     * The body is left unread so each caller can decode it as it needs — JSON for
-     * `request()`, raw text + headers for `requestRaw()`. This is the single place
-     * that owns auth, the abort budget, and the error taxonomy; the two public
-     * transports differ only in how they read a successful body.
+     * The body is read through a continuation each caller supplies — JSON text for
+     * `request()`, raw bytes for `requestRaw()`. This is the single place that owns auth,
+     * the abort budget, and the error taxonomy; the two public transports differ only in
+     * how they read a successful body.
+     *
+     * The abort budget spans headers **and** body (#2546). Returning the `Response` used to
+     * end the guarded region at the headers boundary, leaving `response.text()` /
+     * `response.arrayBuffer()` — and the `!response.ok` branch's `response.json()` —
+     * unbounded: a server that sent headers and then stalled its body hung the caller
+     * forever. `readBody` must therefore ONLY consume the stream; `JSON.parse` and
+     * `TextDecoder` run in the callers, outside the guard, so a malformed body still
+     * surfaces its own parse error rather than being remapped to a connection error.
+     * `cleanup()` still runs exactly once per call, now after the body completes.
      */
-    async send(method, path, body, options) {
+    async send(method, path, body, options, readBody) {
         const url = `${this.baseUrl}${path}`;
         const { signal, timeoutSignal, cleanup } = this.resolveSignal(options);
         const init = {
@@ -254,32 +312,58 @@ export class ByteKit {
         if (signal !== undefined) {
             init.signal = signal;
         }
-        let response;
         try {
-            response = await fetch(url, init);
-        }
-        catch (err) {
-            throw toConnectionError(err, method, url, timeoutSignal);
-        }
-        finally {
-            // Runs on success, on HTTP error, and on abort alike — no dangling timer,
-            // no listener left behind on the caller's (long-lived) signal.
-            cleanup();
-        }
-        if (!response.ok) {
-            let code = 'internal_error';
-            let message = response.statusText;
+            let response;
             try {
-                const json = (await response.json());
-                code = json.error?.code ?? code;
-                message = json.error?.message ?? message;
+                response = await fetch(url, init);
+            }
+            catch (err) {
+                throw toConnectionError(err, method, url, timeoutSignal);
             }
-            catch {
-                // leave defaults
+            if (!response.ok) {
+                let code = 'internal_error';
+                let message = response.statusText;
+                try {
+                    const json = (await response.json());
+                    // Canonical unified envelope. Tested first, so it always wins: the flat
+                    // form below is strictly a fallback and can never override an envelope
+                    // (issue #2541). The explicit `!== null` guard matters — `typeof null`
+                    // is `'object'`.
+                    if (typeof json.error === 'object' && json.error !== null) {
+                        code = json.error.code ?? code;
+                        message = json.error.message ?? message;
+                    }
+                    else if (typeof json.error === 'string' && json.error.length > 0) {
+                        // Flat vendor-masked shape, e.g. /v1/search 502
+                        // {"error":"search_provider_error"} (docs/api/openapi.yaml §/v1/search
+                        // 502). The string IS the error code. `message` falls back to it only
+                        // when the response carried no statusText, so the thrown error is
+                        // never message-empty.
+                        code = json.error;
+                        message = message || json.error;
+                    }
+                }
+                catch {
+                    // leave defaults — including when the error body itself stalls and the
+                    // budget aborts the read (#2546), so a stuck 500 still surfaces its status.
+                }
+                throw new ByteKitError(response.status, code, message);
             }
-            throw new ByteKitError(response.status, code, message);
+            try {
+                return await readBody(response);
+            }
+            catch (err) {
+                // A body read that never completes is aborted by the same budget; the runtime
+                // then errors the stream (#2546). Map it into the same taxonomy the headers
+                // phase uses, so a mid-body timeout/abort is not a bare `TypeError: terminated`.
+                throw toConnectionError(err, method, url, timeoutSignal);
+            }
+        }
+        finally {
+            // Runs on success (body read included), on HTTP error, and on abort alike — no
+            // dangling timer, no listener left behind on the caller's (long-lived) signal.
+            cleanup();
         }
-        return response;
     }
     /**
      * Make an authenticated JSON request to the ByteKit API.
@@ -289,21 +373,18 @@ export class ByteKit {
      * timeout, or caller abort).
      */
     async request(method, path, body, options) {
-        const response = await this.send(method, path, body, options);
         // A 204 No Content has an empty body, and a genuinely empty body can arrive on
         // other success codes too (defensive). Calling response.json() on an empty body
         // rejects with a SyntaxError — which is how a successful revoke() (DELETE → 204)
         // used to throw instead of resolving. Read the body once as text and short-circuit
         // to `undefined` when it is empty; a JSON-bearing response (scrape.create,
         // apiKeys.create/get, …) still parses and returns unchanged.
-        if (response.status === 204) {
-            return undefined;
-        }
-        const text = await response.text();
-        if (text.trim().length === 0) {
-            return undefined;
-        }
-        return JSON.parse(text);
+        //
+        // Only the read runs inside the transport's guarded region (#2546) — `JSON.parse`
+        // stays out here (in `parseJsonBody`), so a malformed body still throws its own
+        // SyntaxError rather than being remapped to a ByteKitConnectionError.
+        const text = await this.send(method, path, body, options, readSuccessText);
+        return parseJsonBody(text);
     }
     /**
      * Make an authenticated request whose response body IS the content, not a JSON
@@ -323,9 +404,44 @@ export class ByteKit {
      * content is text.
      */
     async requestRaw(method, path, body, options) {
-        const response = await this.send(method, path, body, options);
-        const bytes = new Uint8Array(await response.arrayBuffer());
+        // As in `request()`: the continuation only drains the stream, so the abort budget
+        // covers the read (#2546); the UTF-8 decode happens outside the guarded region.
+        const { bytes, headers, status } = await this.send(method, path, body, options, async (response) => ({
+            bytes: new Uint8Array(await response.arrayBuffer()),
+            headers: response.headers,
+            status: response.status,
+        }));
         const text = new TextDecoder('utf-8').decode(bytes);
-        return { body: text, bytes, headers: response.headers, status: response.status };
+        return { body: text, bytes, headers, status };
+    }
+    /**
+     * Make an authenticated JSON request and return the parsed body TOGETHER WITH the
+     * response headers and status (#2547).
+     *
+     * Identical to {@link ByteKit.request} in every observable respect — same method, path,
+     * body, `RequestOptions` precedence, error taxonomy, and empty-body handling (both drain
+     * the body through {@link readSuccessText} and parse it through {@link parseJsonBody}). It
+     * differs only in what it returns, so nothing about an existing call changes by switching
+     * to it.
+     *
+     * 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` 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
+        // ONLY drains the stream (and captures headers/status) inside the abort-guarded region,
+        // so a mid-body stall counts against the budget. `JSON.parse` runs afterwards, outside
+        // the guard, in `parseJsonBody` — a malformed body stays a SyntaxError.
+        const { text, headers, status } = await this.send(method, path, body, options, async (response) => ({
+            text: await readSuccessText(response),
+            headers: response.headers,
+            status: response.status,
+        }));
+        return { data: parseJsonBody(text), headers, status };
     }
 }