@hunt-labs/bytekit-sdk 0.4.0 → 0.6.0

package/CHANGELOG.md

@@ -8,6 +8,126 @@ 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.6.0] - 2026-08-07
+
+### Added
+
+- **`ByteKitError.details`** — the API error envelope's structured rejection reason is now
+  reachable from the thrown error. A `422 validation_error` carries
+  `{ formErrors, fieldErrors }`, so a caller can finally read WHICH request field was
+  rejected rather than only that the request was invalid; a `400 invalid_url` carries a flat
+  `{ url, field, reason }`. Typed as `ByteKitErrorDetails | undefined` where
+  `ByteKitErrorDetails = Record<string, unknown>` (also exported), deliberately loose because
+  the contents vary by error code — narrow the member you read. Strictly ADDITIVE: `details`
+  is an optional FOURTH constructor argument, so existing three-argument
+  `new ByteKitError(status, code, message)` construction is unchanged, and `status` / `code` /
+  `message` are byte-identical. Populated only from the canonical `{ error: { … } }`
+  envelope — a flat vendor-masked body (`/v1/search` `502 {"error":"search_provider_error"}`)
+  carries no structured detail and grows none. `http_status` and `failed_at` are deliberately
+  NOT exposed: `http_status` would duplicate the existing `status` property, and a duplicated
+  field that can disagree with its twin is a bug surface. (#2685)
+
+- A `tsc --noEmit`-checked parity pin in `src/types.ts` ties the hand-authored search types
+  (`SearchOpts`, `SearchResult`, `SearchResultImage`, `SearchResponse` — the SDK's only
+  hand-authored request/response types) to the generated `operations['createSearch']`
+  request and `200` response. It asserts key-set and optionality parity in both directions
+  and assignability in each meaningful direction, so a future spec change that search's
+  types do not follow fails the build instead of shipping. Value types are erased before the
+  parity comparison, so a deliberate hand-authored refinement (a branded id, a narrowed
+  union) cannot trip it. Type-level only — the assertions erase at emit and add nothing to
+  `dist/`. (#2678)
+
+### Fixed
+
+- **README: the `fetch` sample's `res.cache` type is corrected to include `null`.** The
+  documented type read `"hit" | "miss" | "bypass"`, but `FetchResult.cache` is
+  `FetchCacheStatus | null` (null when the response carried no recognizable `X-Fetch-Cache`
+  header) — the one strict-`tsc` error a real consumption file copied from the README ever
+  produced. The line is now a TYPED ASSIGNMENT rather than a comment, so the README compile
+  guard (`src/__tests__/readme-compiles.test.ts`) typechecks it: comment-vs-type drift on
+  this field now fails the build instead of shipping. Documentation only — no runtime or type
+  change. (#2685)
+
+- **CHANGELOG: the `[0.1.0]` heading's malformed `- 2026` date is now `- 2026-04-24`**, the
+  commit date of `caf17e56b`, which introduced `packages/sdk-typescript/package.json` at
+  version `0.1.0`. Every other heading in this file already carried a full ISO date; this one
+  broke the Keep a Changelog `## [x.y.z] - YYYY-MM-DD` form. (#2685)
+
+- **Test-only: nine SDK test files mocked wire bodies the API can never send.** A
+  `monitors.create` 200 (the operation declares 201 as its only success arm), a scrape 200
+  carrying `data: { markdown }` (the envelope has no `data` member — content lives under
+  `formats`), a `screenshots.getWithResponse` mock asserting `X-Screenshot-*` headers that
+  `GET /v1/screenshots/{id}` declares on no arm, error bodies omitting the `Error` schema's
+  required `status: 'failed'` / `http_status` / `failed_at`, and twelve `402`/`429` arms on
+  operations that declare neither status. Each is rewritten to a spec-valid shape with a
+  comment naming the arm it now matches, and every test keeps its original assertion target.
+  No shipped code changed. (#2685)
+
+- **`SearchResult.snippet` is now optional (`snippet?: string`) — BREAKING AT COMPILE TIME.**
+  `type: 'images'` search results omit `snippet` entirely (the spec has always declared a
+  result's `required` set as `[position, title, url]`), but the SDK typed it as a required
+  `string`. `hit.snippet.length` therefore compiled under strict TypeScript and threw
+  `TypeError: Cannot read properties of undefined` on every images hit — the TypeScript twin
+  of the Python SDK's #2579 images `KeyError`. **Consumers reading `.snippet` unguarded now
+  see `string | undefined`** and must narrow it (`if (typeof hit.snippet === 'string')` or
+  `hit.snippet ?? ''`), exactly as they already do for `date`. No runtime behavior and no
+  wire bytes change: the field was already absent from those payloads. `web`/`news` results
+  are unaffected — they still carry `snippet`, and a narrowed read yields the same string.
+  (#2678)
+
+- **Path parameters are now percent-encoded.** Every id-bearing method built its request path
+  with a raw template literal, so a crafted or interpolated id silently retargeted the
+  request: `scrape.get('sc_/../../account')` addressed `GET /v1/account` once WHATWG URL
+  parsing collapsed the `../` segments, and `monitors.get('mon_x?admin=1#frag')` turned the id
+  into a real query string plus fragment. The branded id types constrain only the PREFIX of an
+  id, never its tail, so they were never a defence. An id now travels as one percent-encoded
+  path segment — a malformed one 404s server-side instead of reaching a different resource.
+  Ports the Python SDK's #2593 fix. (#2677)
+
+### Changed
+
+- Request paths are assembled by a single internal `buildPath()` helper in `client.ts` rather
+  than by per-resource template literals. It encodes SEGMENTS only — every fixed segment and
+  every `/` separator stays literal — and encodes each value exactly once, so an id that
+  already contains a `%` is not double-encoded. **A well-formed id (`sc_<hex>`, `mon_<hex>`, …)
+  produces a byte-identical URL to before**, on every id-bearing method: encoding is a no-op
+  for those characters, so no existing call changes on the wire. (#2677)
+
+- Four of the guards shipped above could not fail on the change they appeared to protect, and
+  now can. `buildPath()`'s two `TypeError` throws — the fail-loud that replaced the
+  compile-time checking a template literal used to give — each survived its own removal with
+  the whole suite green, and are now pinned by tests separated by input shape rather than by
+  message text. The in-suite path-helper gate read its directory non-recursively while the
+  shell grep it reproduces is `-r`, so an offender one directory down was invisible to it; it
+  now walks the whole of `src/`, a strict superset of the shell gate's set. The `images`
+  search-result literal's key ABSENCE (no `snippet`, no `date`) was held only by a
+  one-directional subtype check, which an extra key cannot break; it is now pinned by explicit
+  key-absence assertions plus an exact key-set assertion. And the spec's `error.details` —
+  read at one site in `client.ts` off a hand-written inline type — is now tied to the
+  generated schema by a PRESENCE pin, so dropping the field from `docs/api/openapi.yaml` fails
+  the build. Every pin is key-level, never value-level, so a deliberate hand-authored value
+  refinement still cannot trip it. Test- and type-level only: no runtime behavior, no exported
+  type, and nothing in `dist/` changes. (#2793)
+
+## [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
@@ -133,7 +253,12 @@ today, see [README.md](./README.md), which remains the authoritative usage guide
   rebuilding the shared `dist`), which is now fixed. No consumer-facing changes
   beyond 0.2.1.
 
-## [0.2.1] - 2026-07-16
+## [0.2.1] - 2026-07-16 [NEVER PUBLISHED]
+
+> **Never published to npm.** This version was cut in-tree but no `@hunt-labs/bytekit-sdk@0.2.1`
+> tarball exists — `npm i @hunt-labs/bytekit-sdk@0.2.1` fails. Everything below shipped to users in
+> **0.2.2**, which is the first published release containing it. Reconciled by issue #2680; the
+> `release-drift` CI gate now blocks a new phantom heading from being introduced.
 
 ### Changed
 
@@ -193,7 +318,7 @@ against 0.1.0 — read each one before upgrading.
 - Publish-ready packaging metadata: types-first `exports`, `engines`, `keywords`,
   `homepage`, `bugs`, `README.md`, `LICENSE`, and an MIT `license` field.
 
-## [0.1.0] - 2026
+## [0.1.0] - 2026-04-24
 
 ### Added
 
@@ -201,6 +326,9 @@ against 0.1.0 — read each one before upgrading.
   (scrape, screenshot, search, and related endpoints), published under the original
   `@rapidcrawl/sdk` name.
 
+[0.6.0]: https://github.com/Hunt-Labs-Inc/ByteKit/tree/main/packages/sdk-typescript
+[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

@@ -77,16 +77,24 @@ binary content (images, PDFs, etc. — `/v1/fetch` supports raw passthrough)
 use `bytes` instead, which is byte-for-byte identical to the wire content:
 
 ```ts
+import type { FetchCacheStatus } from '@hunt-labs/bytekit-sdk';
+
 const res = await client.fetch.create({ url: 'https://example.com' });
 
 console.log(res.body); // raw content (e.g. "<!doctype html>…") — UTF-8 decoded
 console.log(res.bytes); // Uint8Array — byte-exact, safe for binary content
 console.log(res.id); // X-Fetch-ID, e.g. "ft_0123abcd…"
 console.log(res.creditsCharged); // X-Fetch-Credits-Charged, as a number
-console.log(res.cache); // "hit" | "miss" | "bypass"
 console.log(res.custom); // base64 X-Fetch-Custom echo, or null
 console.log(res.contentType); // response Content-Type, e.g. "text/html"
 
+// `cache` is NULLABLE — null when the response carried no X-Fetch-Cache header
+// (or an unrecognized value), so narrow it before use. The annotation is
+// deliberate: the README compile guard typechecks this line, so the documented
+// type can no longer drift from the real one.
+const cache: FetchCacheStatus | null = res.cache; // "hit" | "miss" | "bypass" | null
+if (cache !== null) console.log(cache);
+
 // Anything not surfaced as a named field is on res.headers:
 console.log(res.headers.get('X-Fetch-Waf-Vendor'));
 ```
@@ -97,6 +105,9 @@ console.log(res.headers.get('X-Fetch-Waf-Vendor'));
 const results = await client.search.query({ query: 'ai web scraping', limit: 10 });
 for (const hit of results.results) {
   console.log(hit.position, hit.title, hit.url);
+  // `snippet` and `date` are present for `web`/`news` results and omitted
+  // entirely for `type: 'images'` — read them behind a guard.
+  if (typeof hit.snippet === 'string') console.log(hit.snippet);
 }
 ```
 
@@ -185,12 +196,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 +221,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
@@ -232,6 +250,42 @@ try {
 }
 ```
 
+### Reading which field was rejected
+
+`err.details` carries the API envelope's structured rejection reason when the
+response supplied one, and is `undefined` otherwise. Its type is
+`ByteKitErrorDetails | undefined`, where `ByteKitErrorDetails` is
+`Record<string, unknown>` — deliberately loose, because the contents vary by
+error code:
+
+- a `422 validation_error` carries `{ formErrors, fieldErrors }`, and
+  `fieldErrors` names exactly which request field failed;
+- a `400 invalid_url` carries a flat `{ url, field, reason }`.
+
+Narrow the member you want before using it:
+
+```ts
+import { ByteKit, ByteKitError } from '@hunt-labs/bytekit-sdk';
+
+try {
+  await client.scrape.create({ url: 'https://example.com' });
+} catch (err) {
+  if (err instanceof ByteKitError && err.status === 422) {
+    const fieldErrors = err.details?.['fieldErrors'];
+    if (typeof fieldErrors === 'object' && fieldErrors !== null) {
+      // e.g. { formats: ["Invalid enum value. Expected 'markdown' | …"] }
+      console.error(Object.keys(fieldErrors));
+    }
+  }
+}
+```
+
+Note that `details` is populated only from the API's canonical
+`{ error: { … } }` envelope. A few endpoints answer with a flat, vendor-masked
+body instead (`/v1/search` returns `502 {"error":"search_provider_error"}`);
+those carry no structured detail, so `err.details` stays `undefined` there —
+`err.code` is still the machine-readable reason.
+
 ## Documentation
 
 Full API reference: [bytekit.com/docs](https://bytekit.com/docs).

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

@@ -69,11 +69,57 @@ export interface ApiResponse<T> {
 }
 /** Why a request never produced an HTTP response. */
 export type ConnectionErrorCode = 'timeout' | 'aborted' | 'connection';
+/**
+ * Structured, machine-readable detail about WHY a request was rejected — the
+ * `error.details` member of the API's canonical error envelope
+ * (`docs/api/openapi.yaml` §components.schemas.Error, issue #2685).
+ *
+ * The spec declares the field with no schema at all ("Optional structured details
+ * (e.g. which fields failed validation)"), because its contents vary by error code.
+ * Two shapes are live today and both must survive unchanged:
+ *
+ * - A 422 `validation_error` carries zod's `flatten()` output —
+ *   `{ formErrors: string[], fieldErrors: Record<string, string[]> }` — which is
+ *   the shape that names WHICH field failed.
+ * - A 400 `invalid_url` carries a flat record — `{ url, field, reason }` — with
+ *   none of zod's keys.
+ *
+ * It is therefore typed as a loose record rather than a union of the shapes seen
+ * so far: a narrower type would have to drop or mangle the next variant the API
+ * adds, and the SDK must never lose information the envelope carried. Read a
+ * member and narrow it yourself:
+ *
+ * ```ts
+ * const fieldErrors = err.details?.['fieldErrors'];
+ * if (fieldErrors !== undefined && typeof fieldErrors === 'object') { … }
+ * ```
+ */
+export type ByteKitErrorDetails = Record<string, unknown>;
 /** Thrown when the API responds with a 4xx or 5xx status code. */
 export declare class ByteKitError extends Error {
     readonly status: number;
     readonly code: string;
-    constructor(status: number, code: string, message: string);
+    /**
+     * The envelope's `error.details`, when it carried one — `undefined` otherwise.
+     *
+     * Populated ONLY from the canonical `{ error: { … } }` envelope. A flat
+     * vendor-masked body (`/v1/search` 502 `{"error":"search_provider_error"}`)
+     * has no envelope to read a detail from, so it never grows one (#2685 E3).
+     *
+     * A `details` that is not a JSON object — which the untyped spec field
+     * technically permits — is dropped rather than surfaced, because the declared
+     * type promises something indexable and a value that contradicts its own type
+     * is worse than an absent one.
+     *
+     * `declare` is load-bearing. `target: ES2022` turns on `useDefineForClassFields`,
+     * so a plain `details?: …` declaration would emit a class field and DEFINE the
+     * key as `undefined` on every instance — every error the SDK has ever thrown
+     * would silently grow a `details` key, changing `'details' in err`, spreads, and
+     * `JSON.stringify` output for errors that carry none. `declare` emits no field,
+     * so the key exists only when the envelope really supplied one.
+     */
+    readonly details?: ByteKitErrorDetails;
+    constructor(status: number, code: string, message: string, details?: ByteKitErrorDetails);
 }
 /**
  * Thrown when the request never produced an HTTP response at all — DNS, socket, TLS,
@@ -88,6 +134,43 @@ export declare class ByteKitConnectionError extends Error {
         cause?: unknown;
     });
 }
+/**
+ * Assemble an API request path from a fixed template and caller-supplied dynamic segments
+ * (issue #2677).
+ *
+ * This is the SINGLE place the SDK turns a caller-supplied id into a URL, mirroring the
+ * Python SDK's single-site fix (#2593). Every resource routes through it; no resource
+ * interpolates an id into a path template of its own. Before it existed, every path was a
+ * raw template literal, so a crafted or interpolated id silently retargeted the request —
+ * `scrape.get('sc_/../../account')` addressed `GET /v1/account` once WHATWG URL parsing
+ * collapsed the `../` segments, and an id carrying `?` or `#` grew a real query string and
+ * fragment. Branded id types (`sc_${string}`) constrain the PREFIX, never the tail, so they
+ * were never a defence.
+ *
+ * `template` is an OpenAPI-style path whose `{name}` placeholders are the only parts that
+ * get encoded. Everything else — including every `/` separator and every fixed segment —
+ * is emitted verbatim: the helper encodes SEGMENTS, never the assembled path. Lifting the
+ * encoding to the whole string would turn `/v1/scrape/{id}` into one giant escaped segment
+ * and break every request.
+ *
+ * Each value is passed through `encodeURIComponent` EXACTLY once, so an id that already
+ * contains a `%` becomes `%25…` rather than being double-encoded.
+ *
+ * `query` is appended verbatim after the path. It is the caller's job to hand over an
+ * ALREADY-ENCODED string — `toQueryString()` and `URLSearchParams.toString()` both do that
+ * — because a query string is a composed `?a=1&b=2` structure whose separators must survive,
+ * exactly as the path's separators do.
+ *
+ * A `{name}` with no matching value, or a value with no matching `{name}`, throws a
+ * `TypeError`: a typo in either half would otherwise ship a literal `{id}` in the URL or
+ * silently drop the id.
+ */
+export declare function buildPath(template: string, options?: {
+    /** Dynamic path segments by placeholder name. Each is percent-encoded exactly once. */
+    readonly segments?: Readonly<Record<string, string>>;
+    /** An already-encoded query string, including its leading `?`. Appended verbatim. */
+    readonly query?: string;
+}): string;
 export declare class ByteKit {
     private readonly apiKey;
     private readonly baseUrl;
@@ -125,7 +208,8 @@ export declare class ByteKit {
      * - `ByteKitConnectionError` when no HTTP response was produced at all
      *   (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`.
+     * - `ByteKitError` on any 4xx/5xx, carrying the API's `code`/`message` — plus the
+     *   envelope's structured `details` when it carried one (#2685).
      *
      * 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,
@@ -185,9 +269,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

@@ -21,11 +21,16 @@ const DEFAULT_TIMEOUT_MS = 120_000;
 export class ByteKitError extends Error {
     status;
     code;
-    constructor(status, code, message) {
+    constructor(status, code, message, details) {
         super(message);
         this.name = 'ByteKitError';
         this.status = status;
         this.code = code;
+        // Assigned conditionally under `exactOptionalPropertyTypes`: a three-argument
+        // construction leaves the instance without the key at all, exactly as before.
+        if (details !== undefined) {
+            this.details = details;
+        }
     }
 }
 /**
@@ -44,6 +49,59 @@ export class ByteKitConnectionError extends Error {
     }
 }
 const NOOP = () => { };
+/** A `{name}` placeholder in a {@link buildPath} template. */
+const PATH_PLACEHOLDER = /\{([A-Za-z_][A-Za-z0-9_]*)\}/g;
+/**
+ * Assemble an API request path from a fixed template and caller-supplied dynamic segments
+ * (issue #2677).
+ *
+ * This is the SINGLE place the SDK turns a caller-supplied id into a URL, mirroring the
+ * Python SDK's single-site fix (#2593). Every resource routes through it; no resource
+ * interpolates an id into a path template of its own. Before it existed, every path was a
+ * raw template literal, so a crafted or interpolated id silently retargeted the request —
+ * `scrape.get('sc_/../../account')` addressed `GET /v1/account` once WHATWG URL parsing
+ * collapsed the `../` segments, and an id carrying `?` or `#` grew a real query string and
+ * fragment. Branded id types (`sc_${string}`) constrain the PREFIX, never the tail, so they
+ * were never a defence.
+ *
+ * `template` is an OpenAPI-style path whose `{name}` placeholders are the only parts that
+ * get encoded. Everything else — including every `/` separator and every fixed segment —
+ * is emitted verbatim: the helper encodes SEGMENTS, never the assembled path. Lifting the
+ * encoding to the whole string would turn `/v1/scrape/{id}` into one giant escaped segment
+ * and break every request.
+ *
+ * Each value is passed through `encodeURIComponent` EXACTLY once, so an id that already
+ * contains a `%` becomes `%25…` rather than being double-encoded.
+ *
+ * `query` is appended verbatim after the path. It is the caller's job to hand over an
+ * ALREADY-ENCODED string — `toQueryString()` and `URLSearchParams.toString()` both do that
+ * — because a query string is a composed `?a=1&b=2` structure whose separators must survive,
+ * exactly as the path's separators do.
+ *
+ * A `{name}` with no matching value, or a value with no matching `{name}`, throws a
+ * `TypeError`: a typo in either half would otherwise ship a literal `{id}` in the URL or
+ * silently drop the id.
+ */
+export function buildPath(template, options) {
+    const segments = options?.segments;
+    const filled = new Set();
+    const path = template.replace(PATH_PLACEHOLDER, (_match, name) => {
+        const value = segments === undefined ? undefined : segments[name];
+        if (value === undefined) {
+            throw new TypeError(`ByteKit: no value supplied for path segment "${name}" in "${template}"`);
+        }
+        filled.add(name);
+        return encodeURIComponent(String(value));
+    });
+    if (segments !== undefined) {
+        for (const name of Object.keys(segments)) {
+            if (!filled.has(name)) {
+                throw new TypeError(`ByteKit: path template "${template}" has no "{${name}}" placeholder`);
+            }
+        }
+    }
+    return `${path}${options?.query ?? ''}`;
+}
 /**
  * Validate a timeout option. `undefined` passes through; anything that is not a
  * non-negative finite number throws a `TypeError` naming the option as the caller
@@ -279,7 +337,8 @@ export class ByteKit {
      * - `ByteKitConnectionError` when no HTTP response was produced at all
      *   (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`.
+     * - `ByteKitError` on any 4xx/5xx, carrying the API's `code`/`message` — plus the
+     *   envelope's structured `details` when it carried one (#2685).
      *
      * 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,
@@ -323,6 +382,7 @@ export class ByteKit {
             if (!response.ok) {
                 let code = 'internal_error';
                 let message = response.statusText;
+                let details;
                 try {
                     const json = (await response.json());
                     // Canonical unified envelope. Tested first, so it always wins: the flat
@@ -332,6 +392,15 @@ export class ByteKit {
                     if (typeof json.error === 'object' && json.error !== null) {
                         code = json.error.code ?? code;
                         message = json.error.message ?? message;
+                        // Structured rejection reason (issue #2685). This is the ONLY site
+                        // that reads it: the flat branch below has no envelope to read from
+                        // and must never grow a phantom `details` (E3). Arrays and scalars
+                        // are rejected because `ByteKitErrorDetails` promises an indexable
+                        // record — see the type's doc comment.
+                        const raw = json.error.details;
+                        if (typeof raw === 'object' && raw !== null && !Array.isArray(raw)) {
+                            details = raw;
+                        }
                     }
                     else if (typeof json.error === 'string' && json.error.length > 0) {
                         // Flat vendor-masked shape, e.g. /v1/search 502
@@ -347,7 +416,7 @@ export class ByteKit {
                     // 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, details);
             }
             try {
                 return await readBody(response);
@@ -426,9 +495,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