@hunt-labs/bytekit-sdk 0.7.4 → 0.9.0

package/CHANGELOG.md

@@ -10,6 +10,130 @@ today, see [README.md](./README.md), which remains the authoritative usage guide
 
 ## [Unreleased]
 
+## [0.9.0] - 2026-08-20
+
+### Removed
+
+- **BREAKING: the `cookies` and `headers` request-body fields are gone from every capture
+  endpoint** (#3242) — `/v1/scrape`, `/v1/scrape/bulk`, `/v1/screenshots`, `/v1/recordings` and
+  `/v1/schema`. A request that carries either field is rejected with `400 validation_error`; it
+  is not ignored, and there is no deprecation window, feature flag, or compatibility header.
+  `ScrapeOpts.cookies`, `ScrapeOpts.headers` and the exported `ScrapeCookie` type are removed
+  from the SDK surface, so a call that still passes them no longer compiles.
+
+  ```ts
+  // before — compiled, and the values were forwarded to the target site
+  await client.scrape.create({ url, cookies: [{ name: 'session', value: 'abc' }] });
+  // after — does not compile; the same body over raw HTTP is a 400 validation_error
+  await client.scrape.create({ url });
+  ```
+
+  ByteKit continues to manage its own cookie jar and request headers internally; what was removed
+  is the caller's ability to inject or override them.
+
+### Changed
+
+- **The generated types now declare the `503` response of `GET`/`POST /v1/fetch`** (#3372).
+  `/v1/fetch` answers `503` on two conditions and both carry the ordinary `Error` envelope, so
+  a typed consumer reading `operations['getFetch']['responses']` / `['postFetch']` can handle it
+  instead of meeting an undeclared status at runtime. Read `error.code` to tell the two apart,
+  because they disagree about `error.http_status`:
+  - `upstream_error` — the target returned HTTP `502`, relayed at `503` because Cloudflare
+    replaces a clean origin 502 with its own error page. `error.http_status` stays `502`, the
+    **true upstream status**, and is the only surviving record of what the target answered.
+  - `internal_error` (`Fetch service unavailable.`) — the fetch service was unreachable. There
+    is no upstream, so `error.http_status` reports `503`, matching what was served.
+
+  No runtime behaviour changes, and every other documented `/v1/fetch` status is unaffected.
+
+## [0.8.0] - 2026-08-19
+
+### Removed
+
+- **BREAKING: `billing_multiplier` and `billed_bytes` are gone from the scrape success
+  envelope** (#3143). Read `billing` instead — a `BillingNode` that names every factor
+  applied to the charge, the multiplier they compose to, and the resulting billed bytes:
+
+  ```ts
+  // before
+  const spend = res.billed_bytes; // flat, base-endpoint only
+  // after
+  const spend = res.billing?.billed_bytes;
+  const why = res.billing?.factors; // [{ name: 'endpoint', value: 1.5, reason: 'scrape_md' }, …]
+  ```
+
+  This is a correction, not a rename: the two surfaces reported **different numbers for the
+  same charge**. The flat pair carried the BASE-endpoint composition, so a markdown cache hit
+  read `0.5` / `400` while the real charge — and the `X-Billing-Multiplier` header — was
+  `0.75` / `600`; an html-only miss read the per-format credits estimate `1.5` / `150` against
+  an endpoint factor of `1.0` / `100`. The flat pair also never carried the `clean_markdown`
+  ×3 surcharge, so on a successful clean it under-reported the amount billed by two thirds.
+  `billing.multiplier` composes every applied factor behind exactly one rounding, so it is the
+  number that predicts your invoice.
+
+  `billing` is optional and is **absent** on resources that completed before the billing node
+  existed. A pre-node row omits the field rather than reporting a zero node, because a zero
+  node would assert that a real past charge was zero. Test the node for presence
+  (`res.billing !== undefined`, or equivalently a plain truthiness check — `billing` is an
+  object or `undefined`, and an object is always truthy, so the two are the same test here).
+  The hazard is a condition that reaches _into_ the node: `if (res.billing?.billed_bytes)`
+  silently skips a genuine zero-byte charge, because `0` is falsy. Check that the node is
+  present, then read `billed_bytes` from it.
+
+  ```ts
+  // wrong — a real 0-byte charge is falsy and disappears
+  if (res.billing?.billed_bytes) record(res.billing.billed_bytes);
+  // right — presence first, value second
+  if (res.billing) record(res.billing.billed_bytes); // 0 is a charge, not an absence
+  ```
+
+  Two endpoints deliberately carry no node: `/v1/search` is billed per credit and reports
+  `credits_used`, and a single `/v1/fetch` reports its charge through response headers only.
+  The `/v1/logs` row field named `billing_multiplier` is a **different field** and is not the
+  envelope field this release removed. It carries the BASE settled `credits_charged` factor,
+  not the composed real-endpoint value the `X-Billing-Multiplier` header reports — a markdown
+  cache hit reads `0.5` on the logs row and `0.75` on the header.
+
+### Changed
+
+- Generated `ScrapeErrorEnvelope` types now describe terminal asynchronous `scrape.failed`
+  webhook delivery (#1856). No runtime SDK behavior or API shape changed.
+
+### Fixed
+
+- **`GET /v1/logs` entries now carry `billing_multiplier`, as a JSON number** (#3022). The
+  gateway had been serializing that value under an undeclared key `credits`, and as the raw
+  Postgres `NUMERIC(10,2)` string (`"1.50"`), while the OpenAPI spec — and therefore the
+  generated types in `src/generated/api.d.ts` — declared `billing_multiplier?: number | null`.
+  Anything typed against this package read `undefined` for the field.
+
+  **Breaking at the wire level:** the undeclared `credits` key is gone from every `/v1/logs`
+  entry. Code that reached past the generated types to read `credits` must read
+  `billing_multiplier`. No SDK method exposes this endpoint, so the only change inside this
+  package is the regenerated type description.
+
+- **`change_threshold` (on `monitors.create`/`monitors.list`/`monitors.get`/
+  `monitors.update` responses) and `change_pct` (on `monitors.captures.list` entries)
+  now serialize as JSON numbers, not strings** (#3021). Both are Postgres `NUMERIC(5,2)`
+  columns; the gateway passed the raw driver string through unconverted (`"5.00"` /
+  `"7.25"`) while the OpenAPI spec's _request_ schemas already declared `number` — only
+  the _response_ schemas had been (incorrectly) edited to match the buggy string output.
+  This release fixes the gateway serializer and corrects the two response schemas to
+  `number` / `number | null`, so spec and runtime now agree.
+
+  **Breaking at the wire level:** `client.monitors.create()`, `client.monitors.list()`,
+  `client.monitors.get()`, and `client.monitors.update()` now return a JS number for
+  `change_threshold` instead of a string (screenshot-type monitors only); the create
+  response's `MonitorCreateResponse` and every other monitor route serialize through the
+  same `MonitorResponse` schema, so all four are affected identically.
+  `client.monitors.captures.list()` now returns a JS number for `change_pct` instead of a
+  string. Code doing `parseFloat(monitor.change_threshold)` or template-literal
+  interpolation keeps working; strict `typeof x === 'string'` checks or string methods
+  (`.trim()`, `.padStart()`) will now throw. `change_pct` is `null` (not `0`) when there is
+  no prior capture to diff against, unchanged from before. No SDK method-level shape
+  changed otherwise — the only change inside this package is the regenerated type
+  description.
+
 ## [0.7.4] - 2026-08-19
 
 ### Changed
@@ -157,6 +281,16 @@ behave exactly as before.
   Bumping moves the anchor past those comments. The published `0.7.0` artifact is **not** stale in
   any way a consumer can observe — the divergence is comment text only.
 
+- **Corrected a false legacy-name claim carried since the rename (#2950).** The `0.7.0`-era note
+  below said the prior `rapidcrawl`/`@rapidcrawl/sdk` name "remains installable at its last
+  version but is deprecated." Verified 2026-08-13: both `rapidcrawl` and `@rapidcrawl/sdk` return
+  npm `404` ("is not in this registry"), and `npm deprecate` against either fails with the same
+  `404` — there is no published version left for a deprecation notice to attach to, so the claim
+  never held. No registry stub or deprecation was possible to publish; root `CLAUDE.md` carried
+  the same false claim and is corrected alongside this entry. Users of the old names should
+  install `@hunt-labs/bytekit-sdk` directly. No exported function, type, or runtime behavior
+  changes.
+
 ## [0.7.0] - 2026-08-11
 
 ### Added
@@ -538,8 +672,10 @@ against 0.1.0 — read each one before upgrading.
 ### Changed
 
 - Package renamed to `@hunt-labs/bytekit-sdk` (the `@bytekit` npm scope was
-  unobtainable). The prior `rapidcrawl`/`@rapidcrawl/sdk` name remains installable at
-  its last version but is deprecated.
+  unobtainable). ~~The prior `rapidcrawl`/`@rapidcrawl/sdk` name remains installable at
+  its last version but is deprecated.~~ **Corrected in 0.7.1 (see above): that claim
+  does not hold — both names 404 on npm and there is no published version left to
+  deprecate.**
 - Generated API types (`dist/generated/api.d.ts`) are now shipped in the tarball so
   consumers get the typed request/response surface without regenerating from the spec.
 

package/dist/generated/api.d.ts

@@ -272,8 +272,9 @@ export interface paths {
         };
         /**
          * Fetch a URL (GET)
-         * @description Direct HTTP fetch. The response body IS the content; metadata is returned in X-Fetch-* headers.
-         *     Omit `format` for raw passthrough. Use `format=markdown` or `format=html` for conversion.
+         * @description Direct HTTP fetch. Successful responses return the upstream response bytes verbatim;
+         *     metadata is returned in X-Fetch-* headers. Non-2xx upstream responses use the
+         *     `upstream_error` JSON envelope with the upstream HTTP status.
          */
         get: operations["getFetch"];
         put?: never;
@@ -303,7 +304,7 @@ export interface paths {
         /**
          * Bulk fetch URLs
          * @description Enqueues multiple URLs for HTTP fetching. Results delivered via webhook.
-         *     Does not support options that require page rendering (cookies, wait_for_selector, etc.).
+         *     Does not support options that require page rendering (wait_for_selector, etc.).
          *
          *     **Limits:** request bodies are guarded in a two-tier shape. A streamed body
          *     with no `Content-Length` header is capped at 2 MB before your API key
@@ -588,8 +589,8 @@ export interface paths {
          * Schema-driven structured extraction
          * @description Fetches `url` and extracts structured JSON conforming to the supplied
          *     JSON Schema (draft 2020-12) using an LLM. Fast-path only — slow-path
-         *     rendering options (`wait_until=networkidle`, `cookies`, `delay_ms`,
-         *     custom `headers`, `wait_for_selector`) cause a `400 unsupported_url`.
+         *     rendering options (`wait_until=networkidle`, `delay_ms`,
+         *     `wait_for_selector`) cause a `400 unsupported_url`.
          *
          *     Dual-axis billing: a fixed per-request credit charge **plus** the
          *     underlying page's bandwidth, billed exactly like `/v1/scrape`. The
@@ -1041,7 +1042,7 @@ export interface paths {
         /**
          * Query scrape by URL (deprecated)
          * @deprecated
-         * @description Use GET /v1/fetch?url=...&format=markdown instead.
+         * @description Use GET /v1/fetch?url=... instead.
          */
         get: operations["queryScrapeLegacy"];
         put?: never;
@@ -1404,14 +1405,6 @@ export interface components {
                 details?: unknown;
             };
         };
-        Cookie: {
-            name: string;
-            value: string;
-            domain?: string;
-            path?: string;
-            secure?: boolean;
-            httpOnly?: boolean;
-        };
         Viewport: {
             width: number;
             height: number;
@@ -1436,6 +1429,93 @@ export interface components {
             next_cursor: string | null;
             has_more: boolean;
         };
+        /**
+         * @description One named multiplicative term in a charge. A factor that did not apply is
+         *     ABSENT from the list rather than present with `value: 1` — an entry reading
+         *     `cache_hit ×1` would claim a cache-hit discount had been applied. The
+         *     `endpoint` factor is the exception: every billed request has an endpoint, so
+         *     it is always listed even when its value is 1.0.
+         */
+        BillingFactor: {
+            /**
+             * @description Closed vocabulary. `endpoint` — the per-endpoint format factor.
+             *     `cache_hit` — the 0.5× replay discount. `clean_markdown` — the 3×
+             *     surcharge, present only when the LLM clean actually succeeded.
+             *     `phase1_render` — the screenshot/recording render-overhead factor,
+             *     which is never composed with `cache_hit` or `clean_markdown`.
+             *     Treat an unrecognised name as a term you do not model rather than as an
+             *     error: the product of all `value`s always equals `multiplier`.
+             * @example endpoint
+             * @enum {string}
+             */
+            name: "endpoint" | "cache_hit" | "clean_markdown" | "phase1_render";
+            /**
+             * @description The multiplicative value of this term.
+             * @example 1.5
+             */
+            value: number;
+            /**
+             * @description Human-readable explanation of why this factor applied — for example the
+             *     endpoint bucket name, or `hit, age 412s`. NOT CONTRACTUAL: this string is
+             *     free text for display and debugging only. Its wording, its format, and
+             *     whether it carries any particular detail may change at any time without a
+             *     version bump. Never parse it, branch on it, or assert on it — read
+             *     `name` and `value` instead.
+             * @example scrape_md
+             */
+            reason: string;
+        };
+        /**
+         * @description The authoritative, self-explaining account of what this call was billed and
+         *     why. `multiplier` is the product of every entry in `factors`, composed in
+         *     list order (`endpoint` → `cache_hit` → `clean_markdown`), and
+         *     `billed_bytes = round(raw_bytes × multiplier)` behind exactly one rounding.
+         *     The factor list is the DEFINITION of the charge; the `X-Raw-Bytes` /
+         *     `X-Billing-Multiplier` / `X-Billable-Bytes` response headers are a rendering
+         *     of this same node, so where a header and this node disagree, the header is
+         *     the bug.
+         *
+         *     Two billable surfaces carry no node, by design rather than by omission:
+         *
+         *     * `POST /v1/search` is billed per credit, not per byte. Its charge is
+         *       reported by `credits_used`; no byte multiplier applies to it and the
+         *       factor vocabulary has no `search` term.
+         *     * Single (non-bulk) `POST /v1/fetch` returns the fetched bytes as the
+         *       response body, so it has no JSON envelope in which to carry a node. Its
+         *       charge is reported by the `X-Raw-Bytes` / `X-Billing-Multiplier` /
+         *       `X-Billable-Bytes` header trio alone. Items under
+         *       `GET /v1/fetch/bulk/{id}` DO carry the node.
+         *
+         *     Historical rows: for a resource that completed before its billing node was
+         *     persisted, this field is OMITTED rather than emitted as a zero node — a zero
+         *     node would assert that a real past charge was zero. Treat absence as "not
+         *     available for this row" and read the charge from `GET /v1/usage`.
+         */
+        BillingNode: {
+            /**
+             * @description The unmultiplied basis of the charge. For byte-billed endpoints this is
+             *     the upstream wire bytes actually transferred. For screenshots and
+             *     recordings it is the Phase 1 HTML fetch's wire bytes — the only proxied
+             *     traffic in the happy path — never the size of the returned PNG/JPEG/MP4
+             *     artifact.
+             * @example 1024
+             */
+            raw_bytes: number;
+            /** @description The named terms whose product is `multiplier`, in composition order. */
+            factors: components["schemas"]["BillingFactor"][];
+            /**
+             * @description The product of every `factors[].value` — the REAL composed multiplier for
+             *     this call, including the per-endpoint format factor. A markdown cache hit
+             *     reads 0.75 here (1.5 × 0.5).
+             * @example 0.75
+             */
+            multiplier: number;
+            /**
+             * @description `round(raw_bytes × multiplier)` — the bandwidth actually settled for this call.
+             * @example 768
+             */
+            billed_bytes: number;
+        };
         ScrapeRequest: {
             /** Format: uri */
             url: string;
@@ -1447,12 +1527,6 @@ export interface components {
             formats: ("raw_html" | "html" | "markdown" | "links" | "images")[];
             /** @default US */
             country: string;
-            /** @default [] */
-            cookies: components["schemas"]["Cookie"][];
-            /** @default {} */
-            headers: {
-                [key: string]: string;
-            };
             /** @default 0 */
             delay_ms: number;
             /** @default 30000 */
@@ -1730,10 +1804,13 @@ export interface components {
             stats?: components["schemas"]["ScrapeStats"];
             /** @description Token-budget accounting. Present only when `token_budget` was supplied in the request. Contains `kept` (tokens in returned markdown), `total` (tokens in full pre-truncation markdown), and `truncated` (whether output was cut). Absent on uncapped requests to avoid noise. */
             markdown_tokens?: components["schemas"]["ScrapeMarkdownTokens"];
-            /** @description The multiplier applied to wire bytes to compute `billed_bytes` for this call (1.0-2.0 for format combinations on a cache miss). The value is pre-clean-markdown: when `clean_markdown: true` and the clean succeeded, the settled usage is 3× this number, and that surcharge is carried by neither this field nor the `X-Billing-Multiplier` response header — so on a successful clean neither surface predicts the amount you are billed. This field reports the BASE-endpoint composition, so every cache hit reads a flat 0.5 here whatever formats were requested — the per-endpoint format factor is applied later, at report time, by `GET /v1/usage/by-endpoint`. It can therefore differ from the `X-Billing-Multiplier` response header, which carries the composed real-endpoint value: a markdown cache hit reads 0.5 in this field and 0.75 in that header. Present whenever this call's billing amount has been finalized; omitted if unavailable. */
-            billing_multiplier?: number;
-            /** @description The actual bandwidth billed for this call — `round(content_length * billing_multiplier)`. Present alongside `billing_multiplier`. */
-            billed_bytes?: number;
+            /**
+             * @description Itemised account of this call's charge — the basis, the named factors
+             *     that composed the multiplier, and the resulting billed bytes. This node
+             *     is the authoritative billing surface for the response body. Omitted for
+             *     rows persisted before the billing node existed.
+             */
+            billing?: components["schemas"]["BillingNode"];
             /** @description Custom metadata provided by the caller in the request `custom` field. Stored verbatim and round-tripped on the synchronous response and webhook delivery. Not included in `GET /v1/scrape/:id`, bulk results, or cached hits. Omitted when no custom metadata was provided. */
             custom?: {
                 [key: string]: unknown;
@@ -1753,6 +1830,7 @@ export interface components {
             cache_age_s?: number;
         };
         /**
+         * @description Terminal asynchronous scrape failures are delivered to subscribers of `failed` as this payload with `X-ByteKit-Event: scrape.failed`.
          * @example {
          *       "schema_version": 1,
          *       "status": "failed",
@@ -1823,8 +1901,6 @@ export interface components {
         FetchRequest: {
             /** Format: uri */
             url: string;
-            /** @enum {string} */
-            format?: "markdown" | "html";
             /** @default US */
             country: string;
             /** @default 60000 */
@@ -1841,37 +1917,6 @@ export interface components {
             custom: {
                 [key: string]: unknown;
             };
-            /**
-             * @description Markdown processing mode. Only used when format=markdown.
-             * @enum {string}
-             */
-            markdown_mode?: "article" | "raw" | "llm";
-            /** @description BM25 query string for relevance-ranked filtering. Only used when format=markdown. */
-            markdown_query?: string;
-            /**
-             * @description Link rendering style. Only used when format=markdown.
-             * @enum {string}
-             */
-            markdown_links?: "inline" | "references" | "none" | "text";
-            /**
-             * @description Image retention mode. Only used when format=markdown.
-             * @enum {string}
-             */
-            markdown_images?: "inline" | "references" | "none" | "text";
-            /** @description Append a Links footer to the markdown output. Only used when format=markdown. */
-            with_links_summary?: boolean;
-            /** @description Append an Images footer to the markdown output. Only used when format=markdown. */
-            with_images_summary?: boolean;
-            /** @description Compact whitespace output. Only used when format=markdown. */
-            markdown_compact?: boolean;
-            /** @description Filter low-signal images. Only used when format=markdown. */
-            markdown_filter_images?: boolean;
-            /** @description When true, `formats.links` and `formats.images` return `ScrapeScoredLink[]` / `ScrapeScoredImage[]` (rich objects) instead of `string[]`, and a top-level `tables` array is included. Only used when format=markdown. */
-            markdown_include_media?: boolean;
-            /** @description When true, enables markdown-pipeline and tag-filter warnings for affected html and markdown requests. Artifact availability warnings such as `artifact_unavailable` may appear independently of this flag. */
-            markdown_include_warnings?: boolean;
-            /** @description When true, includes a top-level `stats` object with `ScrapeStats` (chars, tokens, blocks). Only used when format=markdown. */
-            markdown_include_stats?: boolean;
         };
         ScreenshotRequest: {
             /** Format: uri */
@@ -1909,12 +1954,6 @@ export interface components {
             scroll: boolean;
             /** @default null */
             clip: components["schemas"]["Clip"] | null;
-            /** @default {} */
-            headers: {
-                [key: string]: string;
-            };
-            /** @default [] */
-            cookies: components["schemas"]["Cookie"][];
             /** @default false */
             dark_mode: boolean;
             /**
@@ -1947,6 +1986,13 @@ export interface components {
              */
             file_size_bytes: number | null;
             credits_charged: number | null;
+            /**
+             * @description Itemised account of this capture's charge — the Phase 1 wire bytes it
+             *     was billed on, the `phase1_render` factor, and the resulting billed
+             *     bytes. Omitted for rows that completed before the billing node was
+             *     persisted, and for rows that have not completed.
+             */
+            billing?: components["schemas"]["BillingNode"];
             error_code: string | null;
             error_message: string | null;
             /** Format: date-time */
@@ -2027,12 +2073,6 @@ export interface components {
             /** @default 0 */
             delay_ms: number;
             scroll?: components["schemas"]["ScrollOptions"];
-            /** @default {} */
-            headers: {
-                [key: string]: string;
-            };
-            /** @default [] */
-            cookies: components["schemas"]["Cookie"][];
             /** @default false */
             dark_mode: boolean;
             /** @default US */
@@ -2066,6 +2106,13 @@ export interface components {
              */
             file_size_bytes: number | null;
             credits_charged: number | null;
+            /**
+             * @description Itemised account of this capture's charge — the Phase 1 wire bytes it
+             *     was billed on, the `phase1_render` factor, and the resulting billed
+             *     bytes. Omitted for rows that completed before the billing node was
+             *     persisted, and for rows that have not completed.
+             */
+            billing?: components["schemas"]["BillingNode"];
             error_code: string | null;
             error_message: string | null;
             /** Format: date-time */
@@ -2161,7 +2208,7 @@ export interface components {
             webhook_url: string;
             webhook_headers: Record<string, never> | null;
             /** @description Present on screenshot monitors only. */
-            change_threshold?: string;
+            change_threshold?: number;
             /** @description Present on scrape monitors only. */
             scrape_options?: unknown;
             /** @description Present on scrape monitors only. */
@@ -2203,7 +2250,7 @@ export interface components {
             content_hash: string | null;
             previous_hash: string | null;
             hash_distance: number | null;
-            change_pct: string | null;
+            change_pct: number | null;
             has_change: boolean;
             title_changed: boolean | null;
             /**
@@ -2284,6 +2331,12 @@ export interface components {
             cache?: "miss" | "hit" | "bypass";
             /** @description Age in whole seconds of the cached source job (its `completed_at`) replayed on a `cache: hit`. Clamped to ≥ 0 to absorb clock skew. Present only on `cache: hit`; null on `miss`/`bypass`. */
             cache_age_s?: number | null;
+            /**
+             * @description Itemised account of this job's charge — the basis, the named factors
+             *     that composed the multiplier, and the resulting billed bytes. Omitted
+             *     for jobs that completed before the billing node was persisted.
+             */
+            billing?: components["schemas"]["BillingNode"];
             warnings: string[] | null;
             error_code: string | null;
             error_message: string | null;
@@ -2588,7 +2641,6 @@ export interface components {
          */
         ClientSurfaceMarker: string;
         FetchUrl: string;
-        FetchFormat: "markdown" | "html";
         FetchCountry: string;
         FetchTimeoutMs: number;
         /** @description How long a freshly fetched URL may be served from cache. `0` skips the cache read; cache-eligible fresh results are still written with the default 7-day TTL so later non-zero-TTL callers can HIT. Safety-classified WAF husks remain live-only and are not written. Accepts `Nh` (hours, up to 168h), `Nd` (days, up to 7d), or the integer `0`. Examples: `0`, `48h`, `2d`. Invalid values receive a 422 validation_error with an actionable message. */
@@ -2628,11 +2680,9 @@ export interface components {
         XFetchURL: string;
         /**
          * @description Byte length of the response body served on this request (integer as string) — NOT the
-         *     billing basis. On a passthrough request (no `format`) the body is the relayed upstream
-         *     payload, so this equals the upstream wire byte count. With `format=html` or
-         *     `format=markdown` the body is the transformed document, so this is the transformed byte
-         *     count and is typically far smaller than what is billed. Billing always reads the upstream
-         *     compressed wire bytes from `X-Raw-Bytes` / `X-Billable-Bytes`, on every path.
+         *     billing basis. The body is always the upstream response bytes, so this equals the upstream wire byte
+         *     count. Billing always reads the upstream compressed wire bytes from `X-Raw-Bytes` /
+         *     `X-Billable-Bytes`, on every path.
          */
         XFetchContentLength: string;
         XFetchCreditsCharged: string;
@@ -3110,7 +3160,7 @@ export interface operations {
                     "X-Raw-Bytes"?: number;
                     /** @description Chargeable bytes — round(X-Raw-Bytes × X-Billing-Multiplier). */
                     "X-Billable-Bytes"?: number;
-                    /** @description Billing multiplier applied to raw bytes to compute billable bytes. */
+                    /** @description Billing multiplier applied to raw bytes to compute billable bytes. A rendering of the response body's `billing` node, which is the authoritative surface: it names each factor that composed this value. Where the two disagree, the node is correct. */
                     "X-Billing-Multiplier"?: number;
                     /** @description HTTP status code returned by the target site during the screenshot capture. */
                     "X-Screenshot-Status-Code"?: number;
@@ -3145,7 +3195,7 @@ export interface operations {
                     "X-Raw-Bytes"?: number;
                     /** @description Chargeable bytes — round(X-Raw-Bytes × X-Billing-Multiplier). */
                     "X-Billable-Bytes"?: number;
-                    /** @description Billing multiplier applied to raw bytes to compute billable bytes. */
+                    /** @description Billing multiplier applied to raw bytes to compute billable bytes. A rendering of the response body's `billing` node, which is the authoritative surface: it names each factor that composed this value. Where the two disagree, the node is correct. */
                     "X-Billing-Multiplier"?: number;
                     [name: string]: unknown;
                 };
@@ -3336,7 +3386,7 @@ export interface operations {
                     "X-Raw-Bytes"?: number;
                     /** @description Chargeable bytes after applying the billing multiplier. Equals round(X-Raw-Bytes × X-Billing-Multiplier). */
                     "X-Billable-Bytes"?: number;
-                    /** @description Bandwidth cost multiplier (e.g. 1.0 for raw_html-only, 1.5 for +markdown/html). Cache hits compose the endpoint format factor: raw 0.5, markdown 0.75. Excludes the `clean_markdown` surcharge, exactly like the `billing_multiplier` body field: when `clean_markdown: true` and the clean succeeded, the settled usage is 3× this header's value, so neither surface predicts the amount you are billed. */
+                    /** @description Bandwidth cost multiplier (e.g. 1.0 for raw_html-only, 1.5 for +markdown/html). Cache hits compose the endpoint format factor: raw 0.5, markdown 0.75. Excludes the `clean_markdown` surcharge: when `clean_markdown: true` and the clean succeeded, the settled usage is 3× this header's value, so this header does not predict the amount you are billed. The response body's `billing` node is the authoritative surface — it DOES carry the `clean_markdown` factor, so its `multiplier` and `billed_bytes` are what you are charged. Where the two disagree, the node is correct. */
                     "X-Billing-Multiplier"?: number;
                     /** @description Credits charged for this scrape (multiplier applied to base 1.0 per format). */
                     "X-Scrape-Credits-Charged"?: number;
@@ -3514,10 +3564,6 @@ export interface operations {
                         url: string;
                         formats?: ("raw_html" | "html" | "markdown" | "links" | "images")[];
                         country?: string;
-                        cookies?: components["schemas"]["Cookie"][];
-                        headers?: {
-                            [key: string]: string;
-                        };
                         delay_ms?: number;
                         timeout_ms?: number;
                         metadata?: components["schemas"]["Metadata"];
@@ -3552,10 +3598,6 @@ export interface operations {
                         formats?: ("raw_html" | "html" | "markdown" | "links" | "images")[];
                         /** @default US */
                         country?: string;
-                        cookies?: components["schemas"]["Cookie"][];
-                        headers?: {
-                            [key: string]: string;
-                        };
                         /** @default 0 */
                         delay_ms?: number;
                         /** @default 30000 */
@@ -3615,7 +3657,7 @@ export interface operations {
                         completed_at: string | null;
                         /** @description Always null on the create response — the job has not been billed yet (routes/scrape-bulk.ts builds the 202 body from a partial job row). Fractional when populated (credits are NUMERIC(10,2)); the numeric branch is unreachable on this path and exists only so the 202 and 200 bodies share one shape. */
                         total_credits_charged: number | null;
-                        /** @description Estimated credits at submission time. Null in GET responses. Fractional — markdown/html formats weigh 0.5 credits each (scrape-shared/src/credits.ts), so a one-item markdown job is 1.5. */
+                        /** @description Estimated credits at submission time. Null in GET responses. Fetch-bulk items use the raw fetch bandwidth billing factor. */
                         estimated_credits: number | null;
                         /** @description Webhook endpoint URL (HTTPS only; http:// rejected with 400 invalid_url, reason scheme_unsupported) */
                         webhook_url: string;
@@ -3715,7 +3757,6 @@ export interface operations {
         parameters: {
             query: {
                 url: components["parameters"]["FetchUrl"];
-                format?: components["parameters"]["FetchFormat"];
                 country?: components["parameters"]["FetchCountry"];
                 timeout_ms?: components["parameters"]["FetchTimeoutMs"];
                 /** @description How long a freshly fetched URL may be served from cache. `0` skips the cache read; cache-eligible fresh results are still written with the default 7-day TTL so later non-zero-TTL callers can HIT. Safety-classified WAF husks remain live-only and are not written. Accepts `Nh` (hours, up to 168h), `Nd` (days, up to 7d), or the integer `0`. Examples: `0`, `48h`, `2d`. Invalid values receive a 422 validation_error with an actionable message. */
@@ -3749,16 +3790,14 @@ export interface operations {
                     "X-Raw-Bytes"?: number;
                     /** @description Chargeable bytes after applying the billing multiplier. Equals round(X-Raw-Bytes × X-Billing-Multiplier). */
                     "X-Billable-Bytes"?: number;
-                    /** @description Bandwidth cost multiplier applied to X-Raw-Bytes. A markdown fetch bills as fetch_md (miss 1.5, hit 0.75); a raw fetch bills 1.0 on a miss, 0.5 on a cache hit. */
+                    /** @description Bandwidth cost multiplier applied to X-Raw-Bytes. Single `/v1/fetch` returns the fetched bytes as the body, so it carries no `billing` node — this header trio is the ONLY billing surface here. Items under `GET /v1/fetch/bulk/{id}` do carry the node. */
                     "X-Billing-Multiplier"?: number;
                     /** @description Back-compat duplicate of `X-Billing-Multiplier` — identical value on every path. Prefer `X-Billing-Multiplier`; this alias is retained for clients that read the `X-Fetch-*` header family. */
                     "X-Fetch-Billing-Multiplier"?: number;
                     [name: string]: unknown;
                 };
                 content: {
-                    "*/*": string;
-                    "text/markdown": string;
-                    "text/html": string;
+                    "text/plain": string;
                 };
             };
             /** @description Invalid URL (`invalid_url`) or oversized request. */
@@ -3770,7 +3809,7 @@ export interface operations {
                     "application/json": components["schemas"]["Error"];
                 };
             };
-            /** @description Validation error (e.g. unsupported `format`, slow-path-only field, or `format=html` against a non-HTML content type). */
+            /** @description Validation error (e.g. slow-path-only field). */
             422: {
                 headers: {
                     [name: string]: unknown;
@@ -3789,10 +3828,14 @@ export interface operations {
                 };
             };
             /**
-             * @description Fetch service unavailable, content transform failed, or a non-2xx upstream
-             *     response relayed as the unified Error envelope. On an upstream relay the HTTP
-             *     status equals the upstream status (code `upstream_error`), so any 4xx/5xx the
-             *     target returns surfaces here as an Error envelope rather than a raw body (#1462).
+             * @description Content transform failed, or a non-2xx upstream response relayed as the unified
+             *     Error envelope. On an upstream relay the HTTP status equals the upstream status
+             *     (code `upstream_error`), so any 4xx/5xx the target returns surfaces here as an
+             *     Error envelope rather than a raw body (#1462).
+             *
+             *     **One divergence.** An upstream `502` is relayed at HTTP `503`, not `502` — see
+             *     the `503` response below. A fetch service that cannot be reached also answers
+             *     `503`, not `502` (#3373); this status no longer covers that condition.
              */
             502: {
                 headers: {
@@ -3802,6 +3845,30 @@ export interface operations {
                     "application/json": components["schemas"]["Error"];
                 };
             };
+            /**
+             * @description Two distinct conditions answer `503`, and they disagree about what the body's
+             *     `error.http_status` reports. Read `error.code` to tell them apart.
+             *
+             *     - **`upstream_error`** — the target returned HTTP `502`, relayed here as `503`.
+             *       Cloudflare fronts this API and replaces a clean origin 502 with its own generic
+             *       `text/plain` error page, discarding the envelope before it reaches you, while a
+             *       503 is passed through unchanged. The body's `error.http_status` still reports
+             *       the **true upstream status**, `502` — not `503` — and is the only surviving
+             *       record of what the target answered, so the body rather than the HTTP status is
+             *       authoritative here (#3355).
+             *     - **`internal_error`** (message `Fetch service unavailable.`) — the fetch service
+             *       could not be reached at all. There is no upstream status to preserve: the `503`
+             *       is this API's own choice of wire status, so the body's `error.http_status`
+             *       reports `503`, mirroring what was served (#3373).
+             */
+            503: {
+                headers: {
+                    [name: string]: unknown;
+                };
+                content: {
+                    "application/json": components["schemas"]["Error"];
+                };
+            };
         };
     };
     postFetch: {
@@ -3815,10 +3882,7 @@ export interface operations {
             content: {
                 /**
                  * @example {
-                 *       "url": "https://example.com",
-                 *       "format": "markdown",
-                 *       "markdown_mode": "article",
-                 *       "markdown_links": "inline"
+                 *       "url": "https://example.com"
                  *     }
                  */
                 "application/json": components["schemas"]["FetchRequest"];
@@ -3847,16 +3911,14 @@ export interface operations {
                     "X-Raw-Bytes"?: number;
                     /** @description Chargeable bytes after applying the billing multiplier. Equals round(X-Raw-Bytes × X-Billing-Multiplier). */
                     "X-Billable-Bytes"?: number;
-                    /** @description Bandwidth cost multiplier applied to X-Raw-Bytes. A markdown fetch bills as fetch_md (miss 1.5, hit 0.75); a raw fetch bills 1.0 on a miss, 0.5 on a cache hit. */
+                    /** @description Bandwidth cost multiplier applied to X-Raw-Bytes. Single `/v1/fetch` returns the fetched bytes as the body, so it carries no `billing` node — this header trio is the ONLY billing surface here. Items under `GET /v1/fetch/bulk/{id}` do carry the node. */
                     "X-Billing-Multiplier"?: number;
                     /** @description Back-compat duplicate of `X-Billing-Multiplier` — identical value on every path. Prefer `X-Billing-Multiplier`; this alias is retained for clients that read the `X-Fetch-*` header family. */
                     "X-Fetch-Billing-Multiplier"?: number;
                     [name: string]: unknown;
                 };
                 content: {
-                    "*/*": string;
-                    "text/markdown": string;
-                    "text/html": string;
+                    "text/plain": string;
                 };
             };
             /** @description Invalid URL (`invalid_url`) or oversized request body. */
@@ -3868,7 +3930,7 @@ export interface operations {
                     "application/json": components["schemas"]["Error"];
                 };
             };
-            /** @description Validation error (e.g. malformed JSON, unsupported `format`, slow-path-only field, or `format=html` against a non-HTML content type). */
+            /** @description Validation error (e.g. malformed JSON, unsupported fetch format, or slow-path-only field). */
             422: {
                 headers: {
                     [name: string]: unknown;
@@ -3887,10 +3949,14 @@ export interface operations {
                 };
             };
             /**
-             * @description Fetch service unavailable, content transform failed, or a non-2xx upstream
-             *     response relayed as the unified Error envelope. On an upstream relay the HTTP
-             *     status equals the upstream status (code `upstream_error`), so any 4xx/5xx the
-             *     target returns surfaces here as an Error envelope rather than a raw body (#1462).
+             * @description Content transform failed, or a non-2xx upstream response relayed as the unified
+             *     Error envelope. On an upstream relay the HTTP status equals the upstream status
+             *     (code `upstream_error`), so any 4xx/5xx the target returns surfaces here as an
+             *     Error envelope rather than a raw body (#1462).
+             *
+             *     **One divergence.** An upstream `502` is relayed at HTTP `503`, not `502` — see
+             *     the `503` response below. A fetch service that cannot be reached also answers
+             *     `503`, not `502` (#3373); this status no longer covers that condition.
              */
             502: {
                 headers: {
@@ -3900,6 +3966,30 @@ export interface operations {
                     "application/json": components["schemas"]["Error"];
                 };
             };
+            /**
+             * @description Two distinct conditions answer `503`, and they disagree about what the body's
+             *     `error.http_status` reports. Read `error.code` to tell them apart.
+             *
+             *     - **`upstream_error`** — the target returned HTTP `502`, relayed here as `503`.
+             *       Cloudflare fronts this API and replaces a clean origin 502 with its own generic
+             *       `text/plain` error page, discarding the envelope before it reaches you, while a
+             *       503 is passed through unchanged. The body's `error.http_status` still reports
+             *       the **true upstream status**, `502` — not `503` — and is the only surviving
+             *       record of what the target answered, so the body rather than the HTTP status is
+             *       authoritative here (#3355).
+             *     - **`internal_error`** (message `Fetch service unavailable.`) — the fetch service
+             *       could not be reached at all. There is no upstream status to preserve: the `503`
+             *       is this API's own choice of wire status, so the body's `error.http_status`
+             *       reports `503`, mirroring what was served (#3373).
+             */
+            503: {
+                headers: {
+                    [name: string]: unknown;
+                };
+                content: {
+                    "application/json": components["schemas"]["Error"];
+                };
+            };
         };
     };
     createFetchBulk: {
@@ -3915,14 +4005,10 @@ export interface operations {
                     urls: (string | {
                         /** Format: uri */
                         url: string;
-                        /** @enum {string} */
-                        format?: "markdown" | "html";
                         country?: string;
                         cache_ttl?: string;
                     })[];
                     defaults?: {
-                        /** @enum {string} */
-                        format?: "markdown" | "html";
                         /** @default US */
                         country?: string;
                         /** @default 48h */
@@ -3959,7 +4045,7 @@ export interface operations {
                         completed_at: string | null;
                         /** @description Always null on the create response — the job has not been billed yet (routes/fetch-bulk.ts builds the 202 body from a partial job row). Fractional when populated (credits are NUMERIC(10,2)); the numeric branch is unreachable on this path and exists only so the 202 and 200 bodies share one shape. */
                         total_credits_charged: number | null;
-                        /** @description Estimated credits at submission time. Null in GET responses. Fractional — markdown/html formats weigh 0.5 credits each (scrape-shared/src/credits.ts), so a one-item markdown job is 1.5. */
+                        /** @description Estimated credits at submission time. Null in GET responses. Fetch items are raw passthrough requests and use the raw fetch bandwidth billing factor. */
                         estimated_credits: number | null;
                         /** @description Webhook endpoint URL (HTTPS only; http:// rejected with 400 invalid_url, reason scheme_unsupported) */
                         webhook_url: string;
@@ -4052,6 +4138,12 @@ export interface operations {
                             content_url: string | null;
                             waf_vendor: string | null;
                             cache_hit: boolean;
+                            /**
+                             * @description Itemised account of this item's charge — the basis, the named factors
+                             *     that composed the multiplier, and the resulting billed bytes. Omitted
+                             *     for rows that completed before the billing node was persisted.
+                             */
+                            billing?: components["schemas"]["BillingNode"];
                             error_code: string | null;
                             error_message: string | null;
                             /** Format: date-time */
@@ -4310,7 +4402,7 @@ export interface operations {
                         completed_at: string | null;
                         /** @description Always null on the create response — the job has not been billed yet (routes/bulk.ts builds the 202 body from a partial job row). Fractional when populated (credits are NUMERIC(10,2)); the numeric branch is unreachable on this path and exists only so the 202 and 200 bodies share one shape. */
                         total_credits_charged: number | null;
-                        /** @description Estimated credits at submission time. Null in GET responses. Fractional — markdown/html formats weigh 0.5 credits each (scrape-shared/src/credits.ts), so a one-item markdown job is 1.5. */
+                        /** @description Estimated credits at submission time. Null in GET responses. Fetch-bulk items use the raw fetch bandwidth billing factor. */
                         estimated_credits: number | null;
                         /** @description Webhook endpoint URL (HTTPS only; http:// rejected with 400 invalid_url, reason scheme_unsupported) */
                         webhook_url: string;
@@ -4492,6 +4584,12 @@ export interface operations {
                             /** Format: uri */
                             url: string;
                             credits_charged: number | null;
+                            /**
+                             * @description Itemised account of this item's charge — the basis, the named factors
+                             *     that composed the multiplier, and the resulting billed bytes. Omitted
+                             *     for rows that completed before the billing node was persisted.
+                             */
+                            billing?: components["schemas"]["BillingNode"];
                             error_code: string | null;
                             error_message: string | null;
                             /** Format: date-time */
@@ -4855,7 +4953,7 @@ export interface operations {
                     "X-Sitemap-ID"?: string;
                     /** @description Gzipped results CSV wire bytes — the bandwidth-billing basis. Emitted only when `status: completed`. */
                     "X-Raw-Bytes"?: number;
-                    /** @description Billing multiplier applied to raw bytes (1 for sitemap). Emitted only when `status: completed`. */
+                    /** @description Billing multiplier applied to raw bytes (1 for sitemap). Emitted only when `status: completed`. A rendering of the response body's `billing` node, which is the authoritative surface; where the two disagree, the node is correct. */
                     "X-Billing-Multiplier"?: number;
                     /** @description Billable bytes = round(X-Raw-Bytes × X-Billing-Multiplier). Emitted only when `status: completed`. */
                     "X-Billable-Bytes"?: number;
@@ -5125,18 +5223,8 @@ export interface operations {
                      * @enum {string}
                      */
                     wait_until?: "load" | "domcontentloaded" | "networkidle";
-                    /** @default [] */
-                    cookies?: {
-                        name: string;
-                        value: string;
-                        domain: string;
-                    }[];
                     /** @default 0 */
                     delay_ms?: number;
-                    /** @default {} */
-                    headers?: {
-                        [key: string]: string;
-                    };
                     /**
                      * @description Two-letter country code, upper-cased. `null` is coerced to `US`.
                      * @default US
@@ -5501,9 +5589,9 @@ export interface operations {
                             status_code?: number | null;
                             /** @description Raw upstream bytes the request carried (the billing base before the multiplier). null while pending/failed. */
                             raw_bytes?: number | null;
-                            /** @description Billable bytes — raw_bytes × billing_multiplier, rounded. Mirrors the X-Billable-Bytes response header. null while pending/failed. */
+                            /** @description The bytes this request was BILLED — the same amount its own response reported in `X-Billable-Bytes`. For a scrape or fetch request this is the settled decomposition replayed as it was recorded at completion, so it already carries every factor that applied: the endpoint factor (`scrape` 1.0, `scrape_md` 1.5, `fetch` 1.0, `fetch_md` 1.5, a monitor run 1.0), the cache-hit ×0.5, and the clean-markdown ×3. Screenshots and recordings are `raw_bytes` × the fixed 1.5 Phase-1 render factor whatever capture options they carried — capture billing composes no discount factor, so that product is exact. It is NOT `raw_bytes` × `billing_multiplier`: that field reports a CREDIT count, a different quantity from the byte factors above, and on a recordings row their product is not bytes at all. One residual: a scrape or fetch row completed before the decomposition was recorded is reconstructed from its endpoint and cache-hit factors, which leaves a markdown `/v1/fetch` request of that vintage reported at 1.0 rather than 1.5 — nothing on such a row distinguishes it. That population ages out of this feed's retention window and is not backfilled. null while pending/failed (the row has no byte basis yet). */
                             billable_bytes?: number | null;
-                            /** @description Billing multiplier applied to raw_bytes (e.g. 1.0 for raw scrape, 1.5 for markdown/screenshot). Unlike the scrape response body field of the same name, this row reports the real-endpoint composition — the one the X-Billing-Multiplier response header carries — so cache hits compose the endpoint format factor and a markdown cache hit reads 0.75 here while the response body field reads 0.5. Mirrors the X-Billing-Multiplier response header. null while pending/failed. */
+                            /** @description BASE billing multiplier persisted for this request — the settled `credits_charged` factor. It is NOT what `billable_bytes` above is derived from: that field reports settled BYTES, and multiplying `raw_bytes` by this credit count does not give the amount billed. Its scale is not uniform and is not a rate you can carry from one row to another: each endpoint persists its own credit unit, and the single and bulk paths of the same endpoint may persist different factors for identical options. Read this as the factor this one row settled at, and see https://bytekit.com/docs/billing/credits for what each endpoint charges. This is a LOGS ROW field and is NOT the scrape response envelope field — the envelope carries no flat `billing_multiplier` at all; its billing surface is the `billing` node (see BillingNode). This row reports only the base settled factor, so it can differ from `billing.multiplier` and from the X-Billing-Multiplier response header, both of which report the composed real-endpoint value. null while pending/failed. */
                             billing_multiplier?: number | null;
                             duration_ms?: number | null;
                             /** @description How the request originated (single/bulk/monitor). */

package/dist/index.d.ts

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

package/dist/resources/fetch.d.ts

@@ -15,32 +15,8 @@ export type FetchBulkGetResponse = operations['getFetchBulk']['responses'][200][
  */
 export interface FetchOpts {
     url: string;
-    /** Output format. `'markdown'` runs the HTML→markdown pipeline; `'html'` returns raw HTML. Narrowed to the spec union — off-spec values (e.g. `'pdf'`) are rejected at compile time. */
-    format?: 'markdown' | 'html';
     country?: string;
     timeout_ms?: number;
-    /** Markdown processing mode. Only used when `format=markdown`. article/raw/llm. */
-    markdown_mode?: 'article' | 'raw' | 'llm';
-    /** BM25 query string for relevance-ranked filtering. Only used when `format=markdown`. */
-    markdown_query?: string;
-    /** Link rendering style. Only used when `format=markdown`. */
-    markdown_links?: 'inline' | 'references' | 'none' | 'text';
-    /** Image retention mode. Only used when `format=markdown`. */
-    markdown_images?: 'inline' | 'references' | 'none' | 'text';
-    /** Append a `Links:` footer to the markdown output. Only used when `format=markdown`. */
-    with_links_summary?: boolean;
-    /** Append an `Images:` footer to the markdown output. Only used when `format=markdown`. */
-    with_images_summary?: boolean;
-    /** Compact whitespace output. Only used when `format=markdown`. */
-    markdown_compact?: boolean;
-    /** Filter low-signal images. Only used when `format=markdown`. */
-    markdown_filter_images?: boolean;
-    /** When true, `formats.links`/`formats.images` return rich objects and a top-level `tables` array is included. Only used when `format=markdown`. */
-    markdown_include_media?: boolean;
-    /** When true, enables markdown-pipeline and tag-filter warnings for affected html/markdown requests. */
-    markdown_include_warnings?: boolean;
-    /** When true, includes a top-level `stats` object (chars, tokens, blocks). Only used when `format=markdown`. */
-    markdown_include_stats?: boolean;
     /**
      * How long a freshly fetched URL may be served from cache. Matches the
      * OpenAPI `FetchRequest.cache_ttl` schema: a duration string (`"48h"`,
@@ -66,17 +42,15 @@ export interface FetchOpts {
  * the generated `getFetch` query type by `_AssertFetchGetQueryKeysCoverSpec`
  * below, so it cannot drift away from the spec silently.
  */
-declare const FETCH_GET_QUERY_KEYS: readonly ["url", "format", "country", "timeout_ms", "cache_ttl"];
+declare const FETCH_GET_QUERY_KEYS: readonly ["url", "country", "timeout_ms", "cache_ttl"];
 type FetchGetQueryKey = (typeof FETCH_GET_QUERY_KEYS)[number];
 /**
  * Options accepted by `fetch.get` (GET /v1/fetch).
  *
- * A strict subset of {@link FetchOpts}: only the five params the spec's
+ * A strict subset of {@link FetchOpts}: only the four params the spec's
  * `GET /v1/fetch` actually declares. Everything else on the POST body —
- * `custom` (#2481) and the eleven `markdown_*` / `with_*` tuning fields (#2539) —
- * has no GET query param and was silently dropped by the query builder, so it is
- * excluded here and passing it is a compile error. Use `create()` (POST) for
- * those.
+ * `custom` has no GET query param and is excluded here; passing it is a compile
+ * error. Use `create()` (POST) for custom metadata.
  */
 export type FetchGetOpts = Pick<FetchOpts, FetchGetQueryKey>;
 /** Cache-lookup outcome reported in the `X-Fetch-Cache` response header. */
@@ -84,8 +58,8 @@ export type FetchCacheStatus = 'hit' | 'miss' | 'bypass';
 /**
  * The result of `fetch.create` / `fetch.get`.
  *
- * `/v1/fetch` returns the fetched content AS the response body (text/html,
- * text/markdown, or raw binary passthrough) with metadata carried in `X-Fetch-*`
+ * `/v1/fetch` returns the fetched content AS the response body, including its
+ * original media type and raw bytes, with metadata carried in `X-Fetch-*`
  * headers on the response — it is NOT a JSON envelope. `body` is therefore the raw
  * content string, never a parsed object, and the named fields decode the
  * headers the docs call out. Anything not surfaced here is available on
@@ -144,10 +118,8 @@ export declare class FetchResource {
      *
      * Resolves a `FetchResult` — the raw content body plus `X-Fetch-*` metadata.
      *
-     * Accepts only the five params the spec declares for this endpoint. `custom`
-     * (#2481) and the `markdown_*` / `with_*` tuning fields (#2539) are POST-body
-     * options with no GET query param — they were silently dropped by this builder,
-     * so they are now compile errors instead. Use `create()` (POST) for those.
+     * Accepts only the four params the spec declares for this endpoint. `custom`
+     * is a POST-body option with no GET query param; use `create()` for custom metadata.
      *
      * The query string is built by iterating `FETCH_GET_QUERY_KEYS`, the same list
      * `FetchGetOpts` is derived from, so every accepted option is necessarily

package/dist/resources/fetch.js

@@ -9,7 +9,7 @@ import { buildPath } from '../client.js';
  * the generated `getFetch` query type by `_AssertFetchGetQueryKeysCoverSpec`
  * below, so it cannot drift away from the spec silently.
  */
-const FETCH_GET_QUERY_KEYS = ['url', 'format', 'country', 'timeout_ms', 'cache_ttl'];
+const FETCH_GET_QUERY_KEYS = ['url', 'country', 'timeout_ms', 'cache_ttl'];
 const CACHE_STATUSES = ['hit', 'miss', 'bypass'];
 /** Build a typed {@link FetchResult} from a raw body + its header set. */
 function toFetchResult(raw) {
@@ -60,10 +60,8 @@ export class FetchResource {
      *
      * Resolves a `FetchResult` — the raw content body plus `X-Fetch-*` metadata.
      *
-     * Accepts only the five params the spec declares for this endpoint. `custom`
-     * (#2481) and the `markdown_*` / `with_*` tuning fields (#2539) are POST-body
-     * options with no GET query param — they were silently dropped by this builder,
-     * so they are now compile errors instead. Use `create()` (POST) for those.
+     * Accepts only the four params the spec declares for this endpoint. `custom`
+     * is a POST-body option with no GET query param; use `create()` for custom metadata.
      *
      * The query string is built by iterating `FETCH_GET_QUERY_KEYS`, the same list
      * `FetchGetOpts` is derived from, so every accepted option is necessarily

package/dist/resources/scrape.d.ts

@@ -1,5 +1,5 @@
 import type { ByteKit, RequestOptions } from '../client.js';
-import type { components, operations } from '../generated/api.js';
+import type { operations } from '../generated/api.js';
 import type { ScrapeId, BulkId } from '../types.js';
 /**
  * Response of POST /v1/scrape — a 200 sync success envelope or a 202 queued
@@ -26,23 +26,11 @@ export type MarkdownLinks = 'inline' | 'references' | 'none' | 'text';
 export type MarkdownImages = 'inline' | 'references' | 'none' | 'text';
 /** Tokenizer encoding hint for `token_budget`. */
 export type TokenEncoding = 'cl100k_base' | 'o200k_base';
-/**
- * A cookie to set before loading the page — the spec's `Cookie` schema verbatim
- * (`name` and `value` required; `domain`, `path`, `secure`, `httpOnly` optional).
- *
- * DERIVED from the generated schema (#2547), never hand-authored: `cookies` was
- * previously an open bag of untyped records, so a nameless cookie compiled and only
- * failed as a 422 on the wire.
- */
-export type ScrapeCookie = components['schemas']['Cookie'];
 /** Options for POST /v1/scrape. */
 export interface ScrapeOpts {
     url: string;
     formats?: Array<'raw_html' | 'html' | 'markdown' | 'links' | 'images'>;
     country?: string;
-    /** Cookies to set before loading the page. `name` and `value` are required (spec `Cookie` schema). */
-    cookies?: ScrapeCookie[];
-    headers?: Record<string, string>;
     delay_ms?: number;
     /** SERVER-side scrape budget in ms — how long the gateway may spend on the scrape itself. For the CLIENT-side abort budget (when this SDK gives up on the wire), see `RequestOptions.requestTimeoutMs`. */
     timeout_ms?: number;

package/dist/version.d.ts

@@ -5,4 +5,4 @@
  * outbound request carries — see the emit site in `client.ts`. The header name is spelled
  * only there, so issue #2905's pre-merge gate 1 counts exactly one occurrence in `src/`.
  */
-export declare const SDK_VERSION = "0.7.4";
+export declare const SDK_VERSION = "0.9.0";

package/dist/version.js

@@ -9,4 +9,4 @@
  * outbound request carries — see the emit site in `client.ts`. The header name is spelled
  * only there, so issue #2905's pre-merge gate 1 counts exactly one occurrence in `src/`.
  */
-export const SDK_VERSION = '0.7.4';
+export const SDK_VERSION = '0.9.0';

package/package.json

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