@hunt-labs/bytekit-sdk 0.5.0 → 0.6.0

package/CHANGELOG.md

@@ -8,6 +8,107 @@ 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
@@ -152,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
 
@@ -212,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
 
@@ -220,6 +326,7 @@ 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

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);
 }
 ```
 
@@ -239,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/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,

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);

package/dist/generated/api.d.ts

@@ -330,7 +330,19 @@ export interface paths {
             path?: never;
             cookie?: never;
         };
-        /** Get fetch bulk job status */
+        /**
+         * Get fetch bulk job status
+         * @description Returns the job envelope plus its per-URL items.
+         *
+         *     **Downloading item content.** Each completed item's `content_url` is a
+         *     **pre-signed** URL, minted fresh on every read of this endpoint and valid
+         *     for **600 seconds (10 minutes)** — the same signing lifetime as the
+         *     `image_url` returned by `GET /v1/bulk/{id}/screenshots`. The underlying
+         *     objects are private, so an unsigned URL returns `401`: download the
+         *     content inside that window, or re-poll this endpoint for a fresh
+         *     signature. Items that are not `completed`, and completed items with no
+         *     stored object, carry `null` or the unsigned stored URL instead.
+         */
         get: operations["getFetchBulk"];
         put?: never;
         post?: never;
@@ -407,7 +419,20 @@ export interface paths {
             path?: never;
             cookie?: never;
         };
-        /** List bulk job items */
+        /**
+         * List bulk job items
+         * @description Returns the bulk job's items, discriminated by `type`.
+         *
+         *     **Downloading item artifacts.** `image_url` (`type: screenshot`) and both
+         *     `content_url` and `markdown_url` (`type: scrape`) are **pre-signed** URLs,
+         *     minted fresh on every read of this endpoint and valid for **600 seconds
+         *     (10 minutes)** —
+         *     the same signing lifetime as `content_url` on `GET /v1/fetch/bulk/{id}`.
+         *     The underlying objects are private, so an unsigned URL returns `401`:
+         *     download inside that window, or re-poll this endpoint for a fresh
+         *     signature. Items that are not `completed`, and completed items with no
+         *     stored object, carry `null` or the unsigned stored URL instead.
+         */
         get: operations["listBulkScreenshots"];
         put?: never;
         post?: never;
@@ -772,9 +797,9 @@ export interface paths {
         get?: never;
         put?: never;
         /**
-         * Cancel subscription
-         * @description Immediately cancels the Stripe subscription with proration.
-         *     Takes a balance snapshot for 6-month grace-period restoration on re-subscribe.
+         * Legacy cancellation compatibility terminal
+         * @description Returns 410. Customer cancellation is initiated through the hosted
+         *     Billing Portal and projected through Stripe webhooks.
          */
         post: operations["cancelSubscription"];
         delete?: never;
@@ -3113,13 +3138,41 @@ export interface operations {
                     "application/json": components["schemas"]["Error"];
                 };
             };
-            /** @description Validation error or screenshot failed. */
+            /**
+             * @description Validation error, or a screenshot that failed inside the sync hold.
+             *     The two carry DIFFERENT bodies (issue #2679):
+             *
+             *     - A request-validation failure returns the unified `Error` envelope
+             *       with code `validation_error`.
+             *     - A capture that reached a terminal `failed` state inside the sync
+             *       hold returns the full `ScreenshotResponse` resource, whose
+             *       `error_code`/`error_message` carry the real failure (`blocked`,
+             *       `timeout`, …). This is the canonical shape for that case: the
+             *       resource body is what carries the `ss_` handle, `poll_url` and
+             *       `expires_at` a client needs to redeem the failed capture, none of
+             *       which fit the `Error` envelope.
+             *
+             *     Discriminate on the shape of the top-level `error` key. The envelope
+             *     form carries `error` as an OBJECT (`{ code, message, http_status,
+             *     failed_at }`); the resource form has no `error` key at all, and
+             *     carries the flat `error_code`/`error_message` pair plus `id` instead.
+             *
+             *     Do NOT discriminate on `status`. Both forms carry
+             *     `"status": "failed"` on this response — `Error.status` is a required
+             *     property with `enum: [failed]` — so it separates nothing here.
+             *
+             *     `X-Screenshot-ID` accompanies the resource form only: a
+             *     request-validation failure is raised before a screenshot row exists,
+             *     so no screenshot headers travel with it.
+             */
             422: {
                 headers: {
+                    /** @description Stable screenshot identifier (matches `id` in the resource body). Emitted only on the failed-capture variant; absent on a request-validation failure. */
+                    "X-Screenshot-ID"?: string;
                     [name: string]: unknown;
                 };
                 content: {
-                    "application/json": components["schemas"]["Error"];
+                    "application/json": components["schemas"]["Error"] | components["schemas"]["ScreenshotResponse"];
                 };
             };
             /** @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. */
@@ -3947,7 +4000,10 @@ export interface operations {
                         webhook_url: string;
                         /** @description Per-URL fetch items, oldest first, capped at 500 (listBulkFetchItemsWithLatestAttempt). */
                         items: {
-                            /** @example sc_01j9abc123 */
+                            /**
+                             * @description Scrape-row id, `sc_`-prefixed. Fetch-bulk items are rows of the same resource sync `/v1/scrape` returns, so they share its prefix. Not to be confused with the `ft_`-prefixed `X-Fetch-ID` correlation header on sync `/v1/fetch`, which identifies a request rather than a stored item.
+                             * @example sc_01j9abc123
+                             */
                             id: string;
                             /** Format: uri */
                             url: string;
@@ -3955,6 +4011,7 @@ export interface operations {
                             status: "pending" | "processing" | "completed" | "failed" | "cancelled";
                             content_type: string | null;
                             content_length: number | null;
+                            /** @description Pre-signed download URL for the fetched body, valid for 600 seconds (10 minutes) from the moment this response was generated — matching the signing TTL of `image_url` on `GET /v1/bulk/{id}/screenshots`. A new signature is minted on every poll. Null for items with no stored body; a completed item whose object cannot be signed falls back to the unsigned stored URL, which returns 401 on download. */
                             content_url: string | null;
                             waf_vendor: string | null;
                             cache_hit: boolean;
@@ -4412,7 +4469,7 @@ export interface operations {
                             format?: string;
                             /** @description `type: recording` only. */
                             video_url?: string | null;
-                            /** @description `type: scrape` only. */
+                            /** @description `type: scrape` only. Pre-signed download URL for the scraped body, valid for 600 seconds (10 minutes) from the moment this response was generated — matching the signing TTL of `image_url` above and of `content_url` on `GET /v1/fetch/bulk/{id}`. A new signature is minted on every poll. Null for items with no stored body; a completed item whose object cannot be signed falls back to the unsigned stored URL, which returns 401 on download. */
                             content_url?: string | null;
                             /** @description `type: scrape` only. */
                             content_type?: string | null;
@@ -4420,7 +4477,7 @@ export interface operations {
                             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. */
+                            /** @description `type: scrape` only. Pre-signed download URL for the markdown rendering of the page, valid for 600 seconds (10 minutes) from the moment this response was generated — the same signing TTL as `content_url` and `image_url` above. A new signature is minted on every poll. Null for items with no stored markdown; a completed item whose object cannot be signed falls back to the unsigned stored URL, which returns 401 on download. */
                             markdown_url?: string | null;
                         }[];
                     };
@@ -5210,10 +5267,10 @@ export interface operations {
                         /** @description Plan base price in cents. */
                         plan_price_cents: number;
                         /**
-                         * @description Derived plan category. "payg" for pay-as-you-go plans, "free" for the free tier, "subscription" for all others.
+                         * @description Derived plan category. "payg" for pay-as-you-go plans, "subscription" for all recurring paid plans.
                          * @enum {string}
                          */
-                        plan_type: "payg" | "free" | "subscription";
+                        plan_type: "payg" | "subscription";
                         /** @description Total top-up spend in cents for this billing period. Present only in dual/bytes billing mode. */
                         topup_spent_cents?: number;
                         /** @description Remaining top-up bytes: max(0, topup_bytes − max(0, bytes_used − included_bytes − rollover_bytes)). Present only in dual/bytes billing mode. */
@@ -5418,7 +5475,7 @@ export interface operations {
                             error_message?: string | null;
                             /** @description Prefixed key id (ak_) that issued the request. */
                             api_key_id?: string | null;
-                            /** @description Stored content/image/video URL, if any. */
+                            /** @description Stored content, image or video URL — null when the row has no stored object. For a `completed` row with a stored object this is a **pre-signed** download URL, minted fresh on every read of this endpoint and valid for **600 seconds (10 minutes)** — the same signing lifetime as `content_url` on `GET /v1/fetch/bulk/{id}` and `image_url` on `GET /v1/bulk/{id}/screenshots`. The underlying objects are private, so an unsigned URL returns 401: download inside that window, or re-poll this endpoint for a fresh signature. Rows that are not `completed`, and completed rows whose object cannot be signed, fall back to the unsigned stored URL, which returns 401 on download. */
                             artifact_url?: string | null;
                             /** @description The original request options. */
                             options?: {
@@ -5488,6 +5545,8 @@ export interface operations {
         requestBody: {
             content: {
                 "application/json": {
+                    /** @enum {string} */
+                    purpose: "payment_method_update" | "invoice_history" | "subscription_cancel";
                     /** Format: uri */
                     return_url: string;
                 };
@@ -5515,6 +5574,15 @@ export interface operations {
                     "application/json": components["schemas"]["Error"];
                 };
             };
+            /** @description Cancellation disclosure revision is absent or stale. */
+            409: {
+                headers: {
+                    [name: string]: unknown;
+                };
+                content: {
+                    "application/json": components["schemas"]["Error"];
+                };
+            };
         };
     };
     registerPayg: {
@@ -5714,23 +5782,8 @@ export interface operations {
             };
         };
         responses: {
-            /** @description Successful response. */
-            200: {
-                headers: {
-                    [name: string]: unknown;
-                };
-                content: {
-                    "application/json": {
-                        cancelled: boolean;
-                        /** @enum {string} */
-                        refund: "prorated";
-                        /** Format: date-time */
-                        grace_period_expires_at: string;
-                    };
-                };
-            };
-            /** @description No subscription or already cancelled. */
-            400: {
+            /** @description Cancellation moved to hosted Billing Portal. */
+            410: {
                 headers: {
                     [name: string]: unknown;
                 };

package/dist/index.d.ts

@@ -1,5 +1,5 @@
 export { ByteKit, ByteKitError, ByteKitConnectionError } from './client.js';
-export type { ByteKitOptions, RequestOptions, ApiResponse, ConnectionErrorCode } from './client.js';
+export type { ByteKitOptions, RequestOptions, ApiResponse, ConnectionErrorCode, ByteKitErrorDetails, } from './client.js';
 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';

package/dist/resources/account.js

@@ -1,3 +1,4 @@
+import { buildPath } from '../client.js';
 export class AccountResource {
     client;
     apiKeys;
@@ -35,11 +36,11 @@ class ApiKeysResource {
     }
     /** GET /v1/account/api-keys/{id} — get an API key by ID */
     get(id, requestOptions) {
-        return this.client.request('GET', `/v1/account/api-keys/${id}`, undefined, requestOptions);
+        return this.client.request('GET', buildPath('/v1/account/api-keys/{id}', { segments: { id } }), undefined, requestOptions);
     }
     /** PATCH /v1/account/api-keys/{id} — update an API key */
     update(id, opts, requestOptions) {
-        return this.client.request('PATCH', `/v1/account/api-keys/${id}`, opts, requestOptions);
+        return this.client.request('PATCH', buildPath('/v1/account/api-keys/{id}', { segments: { id } }), opts, requestOptions);
     }
     /**
      * DELETE /v1/account/api-keys/{id} — revoke an API key (idempotent).
@@ -53,10 +54,10 @@ class ApiKeysResource {
      * method resolves cleanly on the gateway's empty 204 body.
      */
     revoke(id, requestOptions) {
-        return this.client.request('DELETE', `/v1/account/api-keys/${id}`, undefined, requestOptions);
+        return this.client.request('DELETE', buildPath('/v1/account/api-keys/{id}', { segments: { id } }), undefined, requestOptions);
     }
     /** POST /v1/account/api-keys/{id}/reveal — reveal the plaintext API key value */
     reveal(id, requestOptions) {
-        return this.client.request('POST', `/v1/account/api-keys/${id}/reveal`, undefined, requestOptions);
+        return this.client.request('POST', buildPath('/v1/account/api-keys/{id}/reveal', { segments: { id } }), undefined, requestOptions);
     }
 }

package/dist/resources/bulk.js

@@ -1,3 +1,4 @@
+import { buildPath } from '../client.js';
 export class BulkResource {
     client;
     screenshots;
@@ -16,11 +17,11 @@ export class BulkResource {
     }
     /** GET /v1/bulk/{id} — get a bulk job status */
     get(id, requestOptions) {
-        return this.client.request('GET', `/v1/bulk/${id}`, undefined, requestOptions);
+        return this.client.request('GET', buildPath('/v1/bulk/{id}', { segments: { id } }), undefined, requestOptions);
     }
     /** DELETE /v1/bulk/{id} — cancel an in-flight bulk job */
     cancel(id, requestOptions) {
-        return this.client.request('DELETE', `/v1/bulk/${id}`, undefined, requestOptions);
+        return this.client.request('DELETE', buildPath('/v1/bulk/{id}', { segments: { id } }), undefined, requestOptions);
     }
 }
 class BulkScreenshotsResource {
@@ -30,6 +31,6 @@ class BulkScreenshotsResource {
     }
     /** GET /v1/bulk/{id}/screenshots — list screenshots in a bulk job */
     list(id, requestOptions) {
-        return this.client.request('GET', `/v1/bulk/${id}/screenshots`, undefined, requestOptions);
+        return this.client.request('GET', buildPath('/v1/bulk/{id}/screenshots', { segments: { id } }), undefined, requestOptions);
     }
 }

package/dist/resources/fetch.js

@@ -1,3 +1,4 @@
+import { buildPath } from '../client.js';
 /**
  * The query params `GET /v1/fetch` accepts, in serialization order.
  *
@@ -80,7 +81,7 @@ export class FetchResource {
             if (value !== undefined)
                 params.set(key, String(value));
         }
-        return toFetchResult(await this.client.requestRaw('GET', `/v1/fetch?${params.toString()}`, undefined, requestOptions));
+        return toFetchResult(await this.client.requestRaw('GET', buildPath('/v1/fetch', { query: `?${params.toString()}` }), undefined, requestOptions));
     }
 }
 class FetchBulkResource {
@@ -94,6 +95,6 @@ class FetchBulkResource {
     }
     /** GET /v1/fetch/bulk/{id} — get a bulk fetch job */
     get(id, requestOptions) {
-        return this.client.request('GET', `/v1/fetch/bulk/${id}`, undefined, requestOptions);
+        return this.client.request('GET', buildPath('/v1/fetch/bulk/{id}', { segments: { id } }), undefined, requestOptions);
     }
 }

package/dist/resources/monitors.js

@@ -1,4 +1,5 @@
 import { toQueryString } from './query-string.js';
+import { buildPath } from '../client.js';
 export class MonitorsResource {
     client;
     captures;
@@ -20,15 +21,15 @@ export class MonitorsResource {
      * serializes the bare `/v1/monitors` URL unchanged — existing zero-arg callers are unaffected.
      */
     list(params, requestOptions) {
-        return this.client.request('GET', `/v1/monitors${toQueryString(params)}`, undefined, requestOptions);
+        return this.client.request('GET', buildPath('/v1/monitors', { query: toQueryString(params) }), undefined, requestOptions);
     }
     /** GET /v1/monitors/{id} — get a monitor by ID */
     get(id, requestOptions) {
-        return this.client.request('GET', `/v1/monitors/${id}`, undefined, requestOptions);
+        return this.client.request('GET', buildPath('/v1/monitors/{id}', { segments: { id } }), undefined, requestOptions);
     }
     /** PATCH /v1/monitors/{id} — update a monitor */
     update(id, opts, requestOptions) {
-        return this.client.request('PATCH', `/v1/monitors/${id}`, opts, requestOptions);
+        return this.client.request('PATCH', buildPath('/v1/monitors/{id}', { segments: { id } }), opts, requestOptions);
     }
     /**
      * DELETE /v1/monitors/{id} — delete a monitor.
@@ -39,7 +40,7 @@ export class MonitorsResource {
      * body to `undefined` before it would parse as JSON (#2450).
      */
     delete(id, requestOptions) {
-        return this.client.request('DELETE', `/v1/monitors/${id}`, undefined, requestOptions);
+        return this.client.request('DELETE', buildPath('/v1/monitors/{id}', { segments: { id } }), undefined, requestOptions);
     }
 }
 class MonitorCapturesResource {
@@ -55,6 +56,6 @@ class MonitorCapturesResource {
      * zero-arg callers are unaffected (inverse case).
      */
     list(id, params, requestOptions) {
-        return this.client.request('GET', `/v1/monitors/${id}/captures${toQueryString(params)}`, undefined, requestOptions);
+        return this.client.request('GET', buildPath('/v1/monitors/{id}/captures', { segments: { id }, query: toQueryString(params) }), undefined, requestOptions);
     }
 }

package/dist/resources/scrape.js

@@ -1,3 +1,4 @@
+import { buildPath } from '../client.js';
 export class ScrapeResource {
     client;
     bulk;
@@ -35,7 +36,7 @@ export class ScrapeResource {
      * gateway and is out of this ticket's scope.
      */
     get(id, requestOptions) {
-        return this.client.request('GET', `/v1/scrape/${id}`, undefined, requestOptions);
+        return this.client.request('GET', buildPath('/v1/scrape/{id}', { segments: { id } }), undefined, requestOptions);
     }
 }
 class ScrapeBulkResource {
@@ -54,6 +55,6 @@ class ScrapeBulkResource {
     }
     /** GET /v1/scrape/bulk/{id} — get a bulk scrape job */
     get(id, requestOptions) {
-        return this.client.request('GET', `/v1/scrape/bulk/${id}`, undefined, requestOptions);
+        return this.client.request('GET', buildPath('/v1/scrape/bulk/{id}', { segments: { id } }), undefined, requestOptions);
     }
 }

package/dist/resources/screenshots.js

@@ -1,3 +1,4 @@
+import { buildPath } from '../client.js';
 export class ScreenshotsResource {
     client;
     constructor(client) {
@@ -17,7 +18,7 @@ export class ScreenshotsResource {
      */
     create(opts, params, requestOptions) {
         const suffix = params?.async === true ? '?async=true' : '';
-        return this.client.request('POST', `/v1/screenshots${suffix}`, opts, requestOptions);
+        return this.client.request('POST', buildPath('/v1/screenshots', { query: suffix }), opts, requestOptions);
     }
     /**
      * GET /v1/screenshots/{id} — poll a screenshot by ID.
@@ -26,7 +27,7 @@ export class ScreenshotsResource {
      * (issue #2027), so narrow the result before reading `image_url`.
      */
     get(id, requestOptions) {
-        return this.client.request('GET', `/v1/screenshots/${id}`, undefined, requestOptions);
+        return this.client.request('GET', buildPath('/v1/screenshots/{id}', { segments: { id } }), undefined, requestOptions);
     }
     /**
      * POST /v1/screenshots, returning the header set alongside the body (#2547).
@@ -42,7 +43,7 @@ export class ScreenshotsResource {
      */
     createWithResponse(opts, params, requestOptions) {
         const suffix = params?.async === true ? '?async=true' : '';
-        return this.client.requestWithResponse('POST', `/v1/screenshots${suffix}`, opts, requestOptions);
+        return this.client.requestWithResponse('POST', buildPath('/v1/screenshots', { query: suffix }), opts, requestOptions);
     }
     /**
      * GET /v1/screenshots/{id}, returning the header set alongside the body (#2547).
@@ -53,6 +54,6 @@ export class ScreenshotsResource {
      * `X-Raw-Bytes`, `X-Billable-Bytes` and `X-Billing-Multiplier` headers are on `headers`.
      */
     getWithResponse(id, requestOptions) {
-        return this.client.requestWithResponse('GET', `/v1/screenshots/${id}`, undefined, requestOptions);
+        return this.client.requestWithResponse('GET', buildPath('/v1/screenshots/{id}', { segments: { id } }), undefined, requestOptions);
     }
 }

package/dist/resources/sitemap.js

@@ -1,3 +1,4 @@
+import { buildPath } from '../client.js';
 export class SitemapResource {
     client;
     constructor(client) {
@@ -14,7 +15,7 @@ export class SitemapResource {
     }
     /** GET /v1/sitemap/{id} — get a sitemap job by ID */
     get(id, requestOptions) {
-        return this.client.request('GET', `/v1/sitemap/${id}`, undefined, requestOptions);
+        return this.client.request('GET', buildPath('/v1/sitemap/{id}', { segments: { id } }), undefined, requestOptions);
     }
     /**
      * GET /v1/sitemap/{id}, returning the header set alongside the body (#2547).
@@ -27,6 +28,6 @@ export class SitemapResource {
      * `X-Billable-Bytes` on this endpoint's 200; every one of them is on `headers`.
      */
     getWithResponse(id, requestOptions) {
-        return this.client.requestWithResponse('GET', `/v1/sitemap/${id}`, undefined, requestOptions);
+        return this.client.requestWithResponse('GET', buildPath('/v1/sitemap/{id}', { segments: { id } }), undefined, requestOptions);
     }
 }

package/dist/resources/usage.js

@@ -1,4 +1,5 @@
 import { toQueryString } from './query-string.js';
+import { buildPath } from '../client.js';
 export class UsageResource {
     client;
     constructor(client) {
@@ -18,13 +19,13 @@ export class UsageResource {
      * Default range is the last 30 days; max range is 366 days.
      */
     daily(params, requestOptions) {
-        return this.client.request('GET', `/v1/usage/daily${toQueryString(params)}`, undefined, requestOptions);
+        return this.client.request('GET', buildPath('/v1/usage/daily', { query: toQueryString(params) }), undefined, requestOptions);
     }
     /**
      * GET /v1/usage/by-endpoint — get per-endpoint bandwidth breakdown.
      * Default range is the last 30 days; max range is 366 days.
      */
     byEndpoint(params, requestOptions) {
-        return this.client.request('GET', `/v1/usage/by-endpoint${toQueryString(params)}`, undefined, requestOptions);
+        return this.client.request('GET', buildPath('/v1/usage/by-endpoint', { query: toQueryString(params) }), undefined, requestOptions);
     }
 }

package/dist/resources/webhooks.js

@@ -1,4 +1,5 @@
 import { toQueryString } from './query-string.js';
+import { buildPath } from '../client.js';
 export class WebhooksResource {
     client;
     constructor(client) {
@@ -11,10 +12,10 @@ export class WebhooksResource {
      * optional caller `signal`; both override the constructor's `timeoutMs` default.
      */
     list(params, requestOptions) {
-        return this.client.request('GET', `/v1/webhook-deliveries${toQueryString(params)}`, undefined, requestOptions);
+        return this.client.request('GET', buildPath('/v1/webhook-deliveries', { query: toQueryString(params) }), undefined, requestOptions);
     }
     /** POST /v1/webhook-deliveries/{id}/retry — requeue a failed or exhausted delivery. */
     retry(id, requestOptions) {
-        return this.client.request('POST', `/v1/webhook-deliveries/${id}/retry`, undefined, requestOptions);
+        return this.client.request('POST', buildPath('/v1/webhook-deliveries/{id}/retry', { segments: { id } }), undefined, requestOptions);
     }
 }

package/dist/types.d.ts

@@ -64,8 +64,12 @@ export interface SearchResult {
     position: number;
     title: string;
     url: string;
-    /** Short text excerpt for the result. Omitted for `images` results. */
-    snippet: string;
+    /**
+     * Short text excerpt for the result. Present for `web` and `news` results;
+     * omitted entirely (`undefined`) for `images` results — read it behind a
+     * guard, exactly like `date` (#2678).
+     */
+    snippet?: string;
     /**
      * Published date when the provider reports one, else `null`. Present for
      * `web`/`news` results; omitted entirely (`undefined`) for `images` results.

package/package.json

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