@hunt-labs/bytekit-sdk 0.6.1 → 0.7.1

package/CHANGELOG.md

@@ -8,6 +8,181 @@ 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.
 
+## [Unreleased]
+
+## [0.7.1] - 2026-08-11
+
+### Changed
+
+- **Generated types follow the spec's corrected error and format vocabularies** (#2959). Two
+  vocabulary corrections in `docs/api/openapi.yaml` flow through `src/generated/api.d.ts`:
+  - `ScrapeErrorEnvelope.error.code` no longer lists `quota_exhausted`. The API has emitted
+    `quota_exceeded` since #1539 and there is no throw site for `quota_exhausted` anywhere in
+    the gateway, so this removes a code that has never been sent — not one that stops being
+    sent. A consumer switching on it was matching a branch that could not be reached; the
+    live code for an exceeded quota is `quota_exceeded`. `invalid_url`, which the API does
+    emit, is unchanged and still listed.
+  - `createBulk`'s `formats` now spells the raw-HTML value `raw_html`, matching `ScrapeRequest`
+    and `createScrapeBulk`. `/v1/bulk` previously accepted only the internal `rawHtml`
+    spelling and the spec documented that; it now accepts both, so the one endpoint that
+    disagreed with the rest of the surface no longer does. `rawHtml` keeps working.
+
+### Added
+
+- **`ByteKitError.headers` — the failing response's headers, so you can write your own backoff**
+  (#2957). This SDK performs exactly one `fetch` per call and never retries, deliberately, so that
+  retry policy stays the caller's. But the policy was unwritable: `ByteKitError` carried no
+  headers and `requestWithResponse` returns headers only on 2xx — which a rate-limited request
+  never reaches — so `Retry-After` and the `X-RateLimit-*` family were unreachable through the SDK
+  at every entry point. `err.headers` closes that:
+
+  ```ts
+  if (err instanceof ByteKitError && err.status === 429) {
+    const waitMs = Number(err.headers?.get('Retry-After') ?? 1) * 1000;
+  }
+  ```
+
+  It is the runtime's own `Headers` object rather than a snapshot, so `get()` stays
+  case-insensitive whatever casing the wire used. **Strictly additive**: it is optional and last
+  on the constructor, follows the same `declare` discipline `details` uses, and an error
+  constructed without one carries no `headers` key at all — `'headers' in err`, spreads and
+  `JSON.stringify` are unchanged for every pre-existing construction, as are `status`, `code`,
+  `message`, `details` and both 2xx return shapes. Only **response** headers are exposed;
+  `Authorization` rides on the request and is never reachable through it.
+  `ByteKitConnectionError` is unchanged — no response, no headers to carry.
+
+### Fixed
+
+- **`screenshots.getWithResponse`'s docstring no longer promises headers that endpoint never
+  emits** (#2957). The JSDoc — the one an IDE surfaces on hover, and the one the published SDK
+  reference is generated from — claimed the documented `X-Screenshot-*` / `X-Raw-Bytes` /
+  `X-Billable-Bytes` / `X-Billing-Multiplier` headers "are on `headers`". They are not:
+  `GET /v1/screenshots/{id}` is declared with **no** `X-*` response headers, which is what
+  `ByteKit.requestWithResponse`'s own doc comment and the README have said all along, and what a
+  live GET confirms. Documentation only — no signature, return type or runtime behavior changed.
+  `screenshots.createWithResponse` (`POST /v1/screenshots`) really does emit that family, and its
+  docstring still says so.
+
+- **README documents the `signal`-vs-`timeoutMs` precedence and the `requestTimeoutMs` escape
+  hatch** (#2957). Passing your own `AbortSignal` silently disables the constructor's `timeoutMs`
+  — the signal becomes the request's only abort source, so a client built with `timeoutMs: 200`
+  waits indefinitely if the signal never fires. That precedence was documented on
+  `RequestOptions.signal` in the types, where only a reader already inspecting the option would
+  meet it, and nowhere in the README. A new "Timeouts and cancellation" section states it with the
+  full four-row precedence table and shows `requestTimeoutMs` composed alongside a caller signal
+  (the request then aborts on whichever fires first). No behavior changed — the precedence is what
+  it always was.
+
+- **`ScrapeWarning.code` now carries all 12 codes the server can emit** (#2948). The generated
+  union in `src/generated/api.d.ts` listed 10. `low_quality_extraction` and
+  `fragment_menu_stripped` — added to the server-side emitter union by #1701 — never reached
+  `docs/api/openapi.yaml`, so every regeneration since faithfully reproduced the gap and the
+  exported type was non-exhaustive: a `switch` over `warning.code` that TypeScript proved
+  exhaustive would silently fall through on a warning the API really returns. Widening the spec
+  and regenerating fixes the type; no runtime code changed. The other 10 codes are unaffected.
+
+- **Gateway wire-type correction: `billing_multiplier` is a JSON number on `scrape.get()` again**
+  (#2954). `GET /v1/scrape/{id}` (and `GET /v1/scrape/bulk/{id}` items) were serializing
+  `billing_multiplier` as a JSON string (e.g. `"0.50"`) instead of a number — the pg driver
+  returns the underlying `NUMERIC(10,2)` column as a string, and the gateway's GET serializer
+  passed it through unconverted, while `POST /v1/scrape`'s create-path value (computed in JS) was
+  already correct. Fixed upstream in the gateway; this SDK required no code change, only removal
+  of the `KNOWN DRIFT (#2426)` JSDoc on `ScrapeResource.get()` that documented the workaround —
+  the static `number` type this SDK has shipped all along is accurate again. A caller that was
+  defensively coercing with `Number(...)` per the old note does not need to change anything; a
+  caller relying on the exact string form `"0.50"` (rather than doing arithmetic) will now see
+  `0.5`.
+
+### Changed
+
+- **Alignment release — no consumer-visible change _in the alignment itself_** (the `#2948` type
+  widening above is a separate, deliberate change under this same version). `0.7.0` published to npm at
+  `2026-08-11T21:17:42.790Z`. Two doc comments, in `src/client.ts` and `src/version.ts`, were
+  reworded **after** the commit that introduced the `0.7.0` version string — they had re-spelled
+  the `X-ByteKit-Client` header name in prose, which issue #2905's pre-merge gate 1 counts. No
+  exported function, type, or runtime behavior differs from `0.7.0`.
+
+  This release exists because `check-release-drift` (#2680) is version-gated and anchors on the
+  commit that introduced a version, not on the commit whose tree was actually published. Once
+  `0.7.0` reached npm, any shipped-file change after that anchor reads as post-release drift.
+  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.
+
+## [0.7.0] - 2026-08-11
+
+### Added
+
+- **Every outbound request now carries `X-ByteKit-Client: sdk_ts/<version>`.** The SDK identifies
+  itself with the sanctioned `client_surface` marker (issue #2905, slice 2 of #2701), so requests
+  made through `@hunt-labs/bytekit-sdk` are distinguishable from raw API calls in ByteKit's own
+  analytics instead of all resolving to `api_direct`. `sdk_ts` is a member of the closed
+  `client_surface` vocabulary declared in issue #2904; the version affix is this package's own
+  version, baked in at build time from `package.json`.
+
+  Set at exactly ONE place — the header literal inside the private transport every request funnels
+  through — so it rides on the JSON path, the raw `/v1/fetch` path and every resource method
+  alike. **Nothing else about a request changed:** same `Authorization` and `Content-Type`, same
+  body bytes, same client-side abort budget, same error taxonomy, same return shapes. The marker
+  carries no caller data and cannot be set, overridden or read by callers — there is no
+  `headers` option on `ByteKitOptions` or `RequestOptions`.
+
+  Minor rather than patch because the wire format of every request changes, even though no
+  documented API does. A gateway that does not yet recognize the header ignores it.
+
+- `SDK_VERSION` — an internal, build-time-generated constant (`src/version.ts`, written by
+  `pnpm gen:version` from `package.json` and gated by `src/__tests__/version-parity.test.ts`).
+  It backs the marker's version affix. **Not part of the public export surface**;
+  `package.json`'s `version` field remains the only version consumers should read.
+
+### Unchanged
+
+- **Still ZERO runtime dependencies.** The `client_surface` vocabulary lives in an internal,
+  unpublished workspace package, so the emitted value is a string literal here and the binding to
+  that registry is a test-only import. `dependencies` stays empty, asserted by
+  `src/__tests__/package-manifest.test.ts`.
+
+## [0.6.2] - 2026-08-11 [NEVER PUBLISHED]
+
+**This version was cut but NEVER PUBLISHED — npm `latest` went from 0.6.1 straight to 0.7.0.**
+The two documentation/regeneration changes below reached consumers in the **0.7.0** artifact,
+which contains all of them. Nothing under this heading is missing from 0.7.0, and nothing is
+installable at 0.6.2: `npm i @hunt-labs/bytekit-sdk@0.6.2` fails.
+
+Why it was stranded: 0.6.2 was cut for two `src/generated/api.d.ts` regenerations, and the next
+change (issue #2905's new outbound request header) altered the wire format of every request —
+additive behavior that belongs at a MINOR, not a patch. Folding it into the still-unpublished
+0.6.2 would have shipped a new request header to consumers pinning `^0.6.1` unannounced, so 0.7.0
+was cut instead and this heading annotated per `ci/scripts/check-release-drift.sh`'s
+reconciliation form (#2680).
+
+### Documentation
+
+- **`AccountSessionResponse.has_activity` now documents what it actually means.** The generated
+  type's JSDoc previously said the flag was true once the account had "ever recorded billable
+  activity", which read as "ever made a request". It is true only once a request has
+  **successfully completed and been charged credits** — a request that failed does not flip it,
+  even when its bandwidth was billed (issue #2890). The doc comment also now states the
+  all-time (never windowed) scope and the up-to-one-rollup lag, so a caller polling it after a
+  first request knows `false` can mean "not visible yet" rather than "never made a request".
+  Regenerated from `docs/api/openapi.yaml`; the emitted TYPE is unchanged
+  (`has_activity: boolean`), so this release is source-compatible in both directions.
+
+### Changed
+
+- Regenerated `src/generated/api.d.ts` from `docs/api/openapi.yaml` after issue #2904 declared the
+  optional `X-ByteKit-Client` request header as `components.parameters.ClientSurfaceMarker`. The
+  regeneration is ADDITIVE and touches no method signature: one entry appears under
+  `components["parameters"]`, because the parameter is deliberately `$ref`-ed from no operation.
+  **No consumer-visible change** — no exported function, type or runtime behavior differs from
+  0.6.1. The entry exists because `check-release-drift` (#2680) requires a version bump for any
+  post-release change to a shipped file, and the publish pipeline is version-gated.
+
+  Documented under 0.6.2 alongside the #2890 regeneration above, rather than under a 0.6.3 of its
+  own, because 0.6.2 has been CUT BUT NOT PUBLISHED (npm `latest` is 0.6.1). Both regenerations
+  therefore ship in the same single artifact. Numbering this 0.6.3 would leave 0.6.2 documented and
+  unpublishable — the version-gated pipeline would publish 0.6.3 and skip it — which is precisely
+  the phantom-version class #2680 exists to kill, and `check-release-drift` rejects it by name.
+
 ## [0.6.1] - 2026-08-10
 
 ### Changed
@@ -332,6 +507,11 @@ against 0.1.0 — read each one before upgrading.
   (scrape, screenshot, search, and related endpoints), published under the original
   `@rapidcrawl/sdk` name.
 
+[Unreleased]: https://github.com/Hunt-Labs-Inc/ByteKit/tree/main/packages/sdk-typescript
+[0.7.1]: https://github.com/Hunt-Labs-Inc/ByteKit/tree/main/packages/sdk-typescript
+[0.7.0]: https://github.com/Hunt-Labs-Inc/ByteKit/tree/main/packages/sdk-typescript
+[0.6.2]: https://github.com/Hunt-Labs-Inc/ByteKit/tree/main/packages/sdk-typescript
+[0.6.1]: https://github.com/Hunt-Labs-Inc/ByteKit/tree/main/packages/sdk-typescript
 [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

package/README.md

@@ -233,6 +233,56 @@ These siblings are purely additive: they issue the identical request and accept
 identical options as their base methods, and `data` is exactly what the base method
 resolves to — no existing return type changes.
 
+## Timeouts and cancellation
+
+Every request carries a **client-side** abort budget covering the whole HTTP
+round-trip — time-to-headers _and_ the response body read. It defaults to
+120000 ms and is set on the constructor:
+
+```ts
+import { ByteKit } from '@hunt-labs/bytekit-sdk';
+
+const bounded = new ByteKit({
+  apiKey: process.env.BYTEKIT_API_KEY!,
+  timeoutMs: 30_000, // client-side abort budget for every call; 0 disables it
+});
+```
+
+`timeoutMs` is **not** `ScrapeOpts.timeout_ms`. The former is how long this SDK
+waits on the wire; the latter is the server-side budget the gateway applies to
+the scrape itself.
+
+### `signal` replaces the default timeout — `requestTimeoutMs` keeps it
+
+Passing your own `AbortSignal` **silently disables the constructor's
+`timeoutMs`**: the signal becomes the request's only abort source, so a client
+built with `timeoutMs: 200` waits indefinitely if the signal never fires. That
+is deliberate — a caller who brought their own cancellation owns it — but it is
+easy to hit by accident. The escape hatch is `requestTimeoutMs`, which is
+composed _with_ your signal rather than replaced by it, so the request aborts on
+whichever fires first:
+
+| `signal` | `requestTimeoutMs` | what bounds the request         |
+| -------- | ------------------ | ------------------------------- |
+| absent   | absent             | the constructor's `timeoutMs`   |
+| absent   | present            | `requestTimeoutMs`              |
+| present  | absent             | your signal **only** — no timer |
+| present  | present            | whichever fires first           |
+
+```ts
+const controller = new AbortController();
+
+// Cancellable AND bounded: aborts on controller.abort() or after 5 s.
+await client.scrape.create(
+  { url: 'https://example.com' },
+  { signal: controller.signal, requestTimeoutMs: 5_000 },
+);
+```
+
+`0` at either level means "no SDK-side timeout". A request that never produced
+an HTTP response at all throws `ByteKitConnectionError`, whose `code`
+distinguishes `'timeout'` from `'aborted'` and `'connection'`.
+
 ## Error handling
 
 Any 4xx/5xx response throws a `ByteKitError` carrying the HTTP status and
@@ -286,6 +336,38 @@ 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.
 
+### Rate limits, `Retry-After`, and your own backoff
+
+This SDK performs **exactly one** `fetch` per call and never retries — retry
+policy stays yours. To make that policy writable, `err.headers` carries the
+response headers of the failing request, so `Retry-After` and the
+`X-RateLimit-*` family are readable straight off the error:
+
+```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 === 429) {
+    const retryAfter = err.headers?.get('Retry-After'); // string | null | undefined
+    const waitMs =
+      retryAfter === null || retryAfter === undefined ? 1000 : Number(retryAfter) * 1000;
+    console.error(`rate limited; retry in ${waitMs}ms`, err.headers?.get('X-RateLimit-Remaining'));
+  }
+}
+```
+
+It is the runtime's own `Headers` object, so `get()` is case-insensitive —
+`get('Retry-After')` and `get('retry-after')` are the same lookup. It is present
+on every error thrown from a real HTTP response and `undefined` on an error you
+constructed yourself, which is why the reads above are optional-chained. Only
+**response** headers are here: `Authorization` rides on the request and is never
+reachable through it. `status`, `code`, `message` and `details` are unchanged.
+
+`ByteKitConnectionError` — thrown when no HTTP response was produced at all —
+carries no headers, because there was no response to read them from.
+
 ## Documentation
 
 Full API reference: [bytekit.com/docs](https://bytekit.com/docs).

package/dist/client.d.ts

@@ -119,7 +119,40 @@ export declare class ByteKitError extends Error {
      * so the key exists only when the envelope really supplied one.
      */
     readonly details?: ByteKitErrorDetails;
-    constructor(status: number, code: string, message: string, details?: ByteKitErrorDetails);
+    /**
+     * The RESPONSE headers of the failing HTTP response (issue #2957).
+     *
+     * This SDK performs exactly ONE `fetch` per call and never retries — a deliberate
+     * design, so that retry policy stays the caller's. That is only a defensible position
+     * if the caller can actually IMPLEMENT a policy, and until this field existed they
+     * could not: `requestWithResponse` returns headers on 2xx only, and a rate-limited
+     * request never reaches a 2xx. `Retry-After` and the `X-RateLimit-*` family were
+     * therefore unreachable through the SDK at every entry point.
+     *
+     * ```ts
+     * catch (err) {
+     *   if (err instanceof ByteKitError && err.status === 429) {
+     *     const wait = Number(err.headers?.get('Retry-After') ?? 1) * 1000;
+     *   }
+     * }
+     * ```
+     *
+     * It is the runtime's own `Headers` object, carried by reference rather than
+     * snapshotted into a plain record, so `get()` stays CASE-INSENSITIVE per the WHATWG
+     * spec — `get('Retry-After')` and `get('retry-after')` are the same lookup whatever
+     * casing undici put on the wire (E1). Only RESPONSE headers are here; `Authorization`
+     * lives on the REQUEST and is never reachable through it, exactly as for
+     * {@link ApiResponse.headers}.
+     *
+     * Present on every error thrown from a real HTTP response, and absent on an error
+     * constructed by hand without one. `declare` is load-bearing for the same reason it is
+     * on `details` above: `target: ES2022` turns on `useDefineForClassFields`, so a plain
+     * `headers?: …` declaration would emit a class field and DEFINE the key as `undefined`
+     * on every instance, changing `'headers' in err`, spreads and `JSON.stringify` output
+     * for every error that carries none.
+     */
+    readonly headers?: Headers;
+    constructor(status: number, code: string, message: string, details?: ByteKitErrorDetails, headers?: Headers);
 }
 /**
  * Thrown when the request never produced an HTTP response at all — DNS, socket, TLS,

package/dist/client.js

@@ -8,6 +8,7 @@ import { SearchResource } from './resources/search.js';
 import { AccountResource } from './resources/account.js';
 import { UsageResource } from './resources/usage.js';
 import { WebhooksResource } from './resources/webhooks.js';
+import { SDK_VERSION } from './version.js';
 const DEFAULT_BASE_URL = 'https://api.bytekit.com';
 /**
  * Default client-side request timeout (2 minutes).
@@ -21,7 +22,7 @@ const DEFAULT_TIMEOUT_MS = 120_000;
 export class ByteKitError extends Error {
     status;
     code;
-    constructor(status, code, message, details) {
+    constructor(status, code, message, details, headers) {
         super(message);
         this.name = 'ByteKitError';
         this.status = status;
@@ -31,6 +32,11 @@ export class ByteKitError extends Error {
         if (details !== undefined) {
             this.details = details;
         }
+        // Same discipline for the #2957 additive field: `headers` is OPTIONAL and LAST, so
+        // every pre-existing three- and four-argument construction is byte-identical.
+        if (headers !== undefined) {
+            this.headers = headers;
+        }
     }
 }
 /**
@@ -362,6 +368,20 @@ export class ByteKit {
             headers: {
                 Authorization: `Bearer ${this.apiKey}`,
                 'Content-Type': 'application/json',
+                // The client_surface marker (issue #2905, slice 2 of #2701). Its NAME is
+                // `CLIENT_SURFACE_HEADER` and its `<surface>/<version>` shape and closed vocabulary
+                // `CLIENT_SURFACES` are declared in `@bytekit/analytics-contract` — deliberately
+                // spelled as literals HERE and not imported, because this package publishes with ZERO
+                // runtime dependencies and a `workspace:*` dependency on that private, unpublished
+                // package would break the published artifact. The binding to the registry is a
+                // TEST-ONLY import, in `client-surface-marker.test.ts`.
+                //
+                // This is the SINGLE emit site by construction: `send()` is the one transport both
+                // `request()` and `requestRaw()` funnel through, so a per-resource or per-method emit
+                // would be a duplicate rather than a completeness fix (#2905 E4). The ticket's pre-merge
+                // gate 1 counts occurrences of the header name in non-test `src/` and expects exactly
+                // one — the line below — which is why the prose above names the constant instead.
+                'X-ByteKit-Client': `sdk_ts/${SDK_VERSION}`,
             },
         };
         if (body !== undefined) {
@@ -416,7 +436,12 @@ 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, details);
+                // `response.headers` is attached to EVERY non-2xx, from this one throw site —
+                // the canonical-envelope arm, the flat vendor-masked arm and the unparseable-body
+                // `catch` above all land here, so a rate-limited caller can read `Retry-After`
+                // whatever shape the error body took (#2957). It is the response's own `Headers`
+                // instance, so lookups stay case-insensitive (E1).
+                throw new ByteKitError(response.status, code, message, details, response.headers);
             }
             try {
                 return await readBody(response);

package/dist/generated/api.d.ts

@@ -1351,11 +1351,21 @@ export interface components {
              * @example 100000000000
              */
             included_bytes: number;
+            /**
+             * @description Included credits per period.
+             * @example 100000
+             */
+            included_credits: number;
             /**
              * @description Bandwidth top-up price per MB, in cents.
              * @example 0.25
              */
             topup_price_per_mb_cents: number;
+            /**
+             * @description Credit top-up price per 1,000 credits, in cents.
+             * @example 150
+             */
+            credit_topup_price_per_k_cents: number;
             /** @example 50 */
             max_concurrency: number;
             /** @example 50 */
@@ -1568,7 +1578,7 @@ export interface components {
         };
         ScrapeWarning: {
             /** @enum {string} */
-            code: "lossy_table" | "complex_math" | "unsupported_element" | "extraction_fallback" | "truncated" | "query_no_match" | "mode_disabled_fallback" | "artifact_unavailable" | "llm_clean_unavailable" | "llm_clean_failed";
+            code: "lossy_table" | "complex_math" | "unsupported_element" | "extraction_fallback" | "truncated" | "query_no_match" | "mode_disabled_fallback" | "artifact_unavailable" | "llm_clean_unavailable" | "llm_clean_failed" | "low_quality_extraction" | "fragment_menu_stripped";
             message: string;
             element: string | null;
         };
@@ -1720,7 +1730,7 @@ 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 (e.g. 0.5 for a cache hit, 1.0-2.0 for format combinations, or higher when `clean_markdown` succeeded). Present whenever this call's billing amount has been finalized; omitted if unavailable. */
+            /** @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;
@@ -1770,7 +1780,7 @@ export interface components {
             id: string | null;
             error: {
                 /** @enum {string} */
-                code: "validation_error" | "invalid_url" | "request_too_large" | "quota_exhausted" | "payload_too_large" | "unsupported_content_type" | "rate_limited" | "upstream_error" | "blocked" | "timeout" | "internal_error";
+                code: "validation_error" | "invalid_url" | "request_too_large" | "payload_too_large" | "unsupported_content_type" | "rate_limited" | "upstream_error" | "blocked" | "timeout" | "internal_error";
                 message: string;
                 http_status?: number;
                 /** Format: date-time */
@@ -2495,7 +2505,7 @@ export interface components {
             terms_version: string;
             /** Format: date-time */
             created_at: string;
-            /** @description True once the account has ever recorded billable activity (any successful scrape/screenshot/fetch/… request, regardless of whether it was authenticated with a Clerk session or an API key). Powers the dashboard onboarding gate — the app shows the guided onboarding flow until this is true, then the dashboard. */
+            /** @description True once the account has SUCCESSFULLY COMPLETED at least one billable request (a scrape/screenshot/fetch/… that settled and was charged credits), regardless of whether it was authenticated with a Clerk session or an API key. All-time — never windowed. A request that failed does not flip it, even when its bandwidth was billed: the monitor terminal-preflight-failure path records bytes without credits, and only the credited settlement counts here. Powers the dashboard onboarding gate — the app shows the guided onboarding flow until this is true, then the dashboard. Lags by up to one usage rollup: the completion service writes the row after the response is returned, so a just-completed first request may still read false for a moment. Treat that as "not visible yet", never as "this account has never made a request". */
             has_activity: boolean;
         };
         /** @description Partial update payload for PATCH /v1/account. All fields are optional; at least one of name, email, or notifications must be provided. */
@@ -2538,19 +2548,45 @@ export interface components {
             used_bytes: number;
             limit_bytes: number;
             remaining_bytes: number;
+            /** @description Total spendable bytes remaining across purchased top-up and starter-grant lots, after active refund reservations. */
             topup_bytes: number;
+            /** @description Bytes remaining in purchased top-up lots, after active refund reservations. Starter-grant bytes are excluded. */
+            purchased_topup_bytes: number;
+            /** @description Bytes remaining in starter-grant lots, after active refund reservations. Purchased top-up bytes are excluded. */
+            granted_topup_bytes: number;
             rollover_bytes: number;
         };
         CreditBalance: {
             used: number;
             limit: number;
             remaining: number;
+            /** @description Total spendable credits remaining across purchased top-up and starter-grant lots, after active refund reservations. */
             topup_credits: number;
+            /** @description Credits remaining in purchased top-up lots, after active refund reservations. Starter-grant credits are excluded. */
+            purchased_topup_credits: number;
+            /** @description Credits remaining in starter-grant lots, after active refund reservations. Purchased top-up credits are excluded. */
+            granted_topup_credits: number;
             rollover_credits: number;
         };
     };
     responses: never;
     parameters: {
+        /**
+         * @description Optional. Identifies which published ByteKit client sent the request, as
+         *     `<surface>/<version>`. The surface comes from a closed set — `api_direct`, `sdk_ts`,
+         *     `sdk_python`, `cli`, `mcp` — and the version affix is the emitting client's own version.
+         *
+         *     You do not need to send this. ByteKit's own clients set it for you, and a request that
+         *     omits it is authenticated, rate-limited, quota-checked, billed and answered exactly as one
+         *     that sends it. Requests without the header are attributed to `api_direct`.
+         *
+         *     A header that is absent, unrecognized or malformed is attributed to `api_direct` and the
+         *     value you sent is discarded — never stored and never logged. The header never changes how a
+         *     request is routed, priced or prioritised, and `User-Agent` is never used as a substitute
+         *     for it.
+         * @example sdk_ts/1.4.0
+         */
+        ClientSurfaceMarker: string;
         FetchUrl: string;
         FetchFormat: "markdown" | "html";
         FetchCountry: string;
@@ -3293,7 +3329,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. */
+                    /** @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. */
                     "X-Billing-Multiplier"?: number;
                     /** @description Credits charged for this scrape (multiplier applied to base 1.0 per format). */
                     "X-Scrape-Credits-Charged"?: number;
@@ -4131,7 +4167,7 @@ export interface operations {
                  *         "device": "desktop",
                  *         "country": "US",
                  *         "formats": [
-                 *           "rawHtml"
+                 *           "raw_html"
                  *         ],
                  *         "device_scale_factor": 2
                  *       },
@@ -4168,7 +4204,7 @@ export interface operations {
                         language?: string | null;
                         dark_mode?: boolean;
                         /** @description Scrape output formats (scrape entries). */
-                        formats?: ("rawHtml" | "html" | "markdown" | "links" | "images")[];
+                        formats?: ("raw_html" | "html" | "markdown" | "links" | "images")[];
                         /** @enum {string} */
                         wait_until?: "load" | "domcontentloaded" | "networkidle";
                         wait_for_selector?: string | null;
@@ -4221,7 +4257,7 @@ export interface operations {
                         language?: string | null;
                         /** @default false */
                         dark_mode?: boolean;
-                        formats?: ("rawHtml" | "html" | "markdown" | "links" | "images")[];
+                        formats?: ("raw_html" | "html" | "markdown" | "links" | "images")[];
                         /**
                          * @default load
                          * @enum {string}
@@ -5466,7 +5502,7 @@ export interface operations {
                             raw_bytes?: number | null;
                             /** @description Billable bytes — raw_bytes × billing_multiplier, rounded. Mirrors the X-Billable-Bytes response header. null while pending/failed. */
                             billable_bytes?: number | null;
-                            /** @description Billing multiplier applied to raw_bytes (e.g. 1.0 for raw scrape, 1.5 for markdown/screenshot); cache hits compose the endpoint format factor — raw 0.5, markdown 0.75. Mirrors the X-Billing-Multiplier response header. null while pending/failed. */
+                            /** @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. */
                             billing_multiplier?: number | null;
                             duration_ms?: number | null;
                             /** @description How the request originated (single/bulk/monitor). */

package/dist/resources/scrape.d.ts

@@ -118,19 +118,6 @@ export declare class ScrapeResource {
     create(opts: ScrapeOpts, requestOptions?: RequestOptions): Promise<ScrapeCreateResponse>;
     /**
      * GET /v1/scrape/{id} — poll a scrape by ID
-     *
-     * KNOWN DRIFT (#2426): live staging spot-checks (two independent fetches)
-     * found the gateway serializes `billing_multiplier` as a JSON **string**
-     * (e.g. `"0.50"`) on this GET path, while the OpenAPI spec — and this
-     * derived `ScrapeGetResponse` type — declare it `number`. `POST /v1/scrape`'s
-     * success envelope for the same job serializes the identical field as a
-     * proper number, so the drift is specific to the GET path (likely a Postgres
-     * NUMERIC column round-tripping as a string on this query path). A consumer
-     * doing arithmetic on `billing_multiplier` after `get()` (e.g.
-     * `content_length * billing_multiplier`) should coerce with `Number(...)`
-     * defensively rather than trust the static type. This is a gateway/worker
-     * serialization bug, not a client bug — the fix belongs upstream in the
-     * gateway and is out of this ticket's scope.
      */
     get(id: ScrapeId, requestOptions?: RequestOptions): Promise<ScrapeGetResponse>;
 }

package/dist/resources/scrape.js

@@ -21,19 +21,6 @@ export class ScrapeResource {
     }
     /**
      * GET /v1/scrape/{id} — poll a scrape by ID
-     *
-     * KNOWN DRIFT (#2426): live staging spot-checks (two independent fetches)
-     * found the gateway serializes `billing_multiplier` as a JSON **string**
-     * (e.g. `"0.50"`) on this GET path, while the OpenAPI spec — and this
-     * derived `ScrapeGetResponse` type — declare it `number`. `POST /v1/scrape`'s
-     * success envelope for the same job serializes the identical field as a
-     * proper number, so the drift is specific to the GET path (likely a Postgres
-     * NUMERIC column round-tripping as a string on this query path). A consumer
-     * doing arithmetic on `billing_multiplier` after `get()` (e.g.
-     * `content_length * billing_multiplier`) should coerce with `Number(...)`
-     * defensively rather than trust the static type. This is a gateway/worker
-     * serialization bug, not a client bug — the fix belongs upstream in the
-     * gateway and is out of this ticket's scope.
      */
     get(id, requestOptions) {
         return this.client.request('GET', buildPath('/v1/scrape/{id}', { segments: { id } }), undefined, requestOptions);

package/dist/resources/screenshots.d.ts

@@ -90,8 +90,15 @@ export declare class ScreenshotsResource {
      *
      * Same request as `screenshots.get`, and `data` is exactly what `get()`
      * resolves to (including the #2027 failed-envelope arm). `get()`'s own return type is
-     * UNCHANGED; this is an additive sibling. The documented `X-Screenshot-*`,
-     * `X-Raw-Bytes`, `X-Billable-Bytes` and `X-Billing-Multiplier` headers are on `headers`.
+     * UNCHANGED; this is an additive sibling.
+     *
+     * Call it for the typed body, NOT for header metadata: the spec declares
+     * `GET /v1/screenshots/{id}` with NO `X-*` response headers, and a live GET returns
+     * none, so `headers` carries only the transport's own entries (`Content-Type`, …).
+     * The `X-Screenshot-*` / `X-Raw-Bytes` / `X-Billable-Bytes` / `X-Billing-Multiplier`
+     * family is emitted by `POST /v1/screenshots` — use `screenshots.createWithResponse`
+     * to read it (issue #2957). This matches `ByteKit.requestWithResponse` and the README,
+     * which are the truth for what this endpoint emits.
      */
     getWithResponse(id: ScreenshotId, requestOptions?: RequestOptions): Promise<ApiResponse<ScreenshotGetResponse>>;
 }

package/dist/resources/screenshots.js

@@ -50,9 +50,22 @@ export class ScreenshotsResource {
      *
      * Same request as `screenshots.get`, and `data` is exactly what `get()`
      * resolves to (including the #2027 failed-envelope arm). `get()`'s own return type is
-     * UNCHANGED; this is an additive sibling. The documented `X-Screenshot-*`,
-     * `X-Raw-Bytes`, `X-Billable-Bytes` and `X-Billing-Multiplier` headers are on `headers`.
+     * UNCHANGED; this is an additive sibling.
+     *
+     * Call it for the typed body, NOT for header metadata: the spec declares
+     * `GET /v1/screenshots/{id}` with NO `X-*` response headers, and a live GET returns
+     * none, so `headers` carries only the transport's own entries (`Content-Type`, …).
+     * The `X-Screenshot-*` / `X-Raw-Bytes` / `X-Billable-Bytes` / `X-Billing-Multiplier`
+     * family is emitted by `POST /v1/screenshots` — use `screenshots.createWithResponse`
+     * to read it (issue #2957). This matches `ByteKit.requestWithResponse` and the README,
+     * which are the truth for what this endpoint emits.
      */
+    // NOTE (#2957): the doc block above deliberately spells sibling method names in plain
+    // backticks rather than as JSDoc link tags. `scripts/generate-docs.ts` copies these
+    // comments verbatim into the published reference and DROPS a link tag without emitting
+    // anything in its place, leaving a dangling "use  to read it" — the very class of broken
+    // doc this correction exists to remove. Keep it a `//` comment: the generator would
+    // publish it too if it were part of the block.
     getWithResponse(id, requestOptions) {
         return this.client.requestWithResponse('GET', buildPath('/v1/screenshots/{id}', { segments: { id } }), undefined, requestOptions);
     }

package/dist/version.d.ts

@@ -0,0 +1,8 @@
+/**
+ * The published version of `@hunt-labs/bytekit-sdk`, baked in at build time.
+ *
+ * Used for the version affix of the client-surface marker (`sdk_ts/<version>`) that every
+ * 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.1";

package/dist/version.js

@@ -0,0 +1,12 @@
+// GENERATED FILE — do not edit by hand.
+// Regenerate with `pnpm --filter @hunt-labs/bytekit-sdk gen:version` (also chained into `build`).
+// Source of truth: this package's `package.json` "version" field.
+// Guarded by `src/__tests__/version-parity.test.ts` (issue #2905, failure mode E5).
+/**
+ * The published version of `@hunt-labs/bytekit-sdk`, baked in at build time.
+ *
+ * Used for the version affix of the client-surface marker (`sdk_ts/<version>`) that every
+ * 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.1';

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@hunt-labs/bytekit-sdk",
-  "version": "0.6.1",
+  "version": "0.7.1",
   "description": "Official TypeScript SDK for the ByteKit API",
   "license": "MIT",
   "type": "module",
@@ -48,8 +48,9 @@
     "url": "https://bytekit.com/contact"
   },
   "scripts": {
-    "build": "rm -rf dist tsconfig.tsbuildinfo tsconfig.build.tsbuildinfo && tsc -p tsconfig.build.json && mkdir -p dist/generated && cp src/generated/api.d.ts dist/generated/api.d.ts",
+    "build": "pnpm gen:version && rm -rf dist tsconfig.tsbuildinfo tsconfig.build.tsbuildinfo && tsc -p tsconfig.build.json && mkdir -p dist/generated && cp src/generated/api.d.ts dist/generated/api.d.ts",
     "gen:types": "openapi-typescript ../../docs/api/openapi.yaml -o src/generated/api.d.ts",
+    "gen:version": "tsx scripts/gen-version.ts",
     "gen:types-check": "pnpm gen:types && git diff --exit-code src/generated/api.d.ts",
     "generate:docs": "tsx scripts/generate-docs.ts",
     "typecheck": "tsc --noEmit",