@hunt-labs/bytekit-sdk 0.2.2 → 0.4.0

package/dist/resources/fetch.d.ts

@@ -1,5 +1,12 @@
-import type { RapidCrawl } from '../client.js';
+import type { ByteKit, RequestOptions } from '../client.js';
+import type { operations } from '../generated/api.js';
 import type { BulkId } from '../types.js';
+/** Body of POST /v1/fetch/bulk. */
+export type FetchBulkCreateRequest = operations['createFetchBulk']['requestBody']['content']['application/json'];
+/** 202 payload of POST /v1/fetch/bulk — bulk fetch jobs are always async. */
+export type FetchBulkCreateResponse = operations['createFetchBulk']['responses'][202]['content']['application/json'];
+/** 200 payload of GET /v1/fetch/bulk/{id}. */
+export type FetchBulkGetResponse = operations['getFetchBulk']['responses'][200]['content']['application/json'];
 /**
  * Options for fetch endpoints.
  *
@@ -8,9 +15,32 @@ import type { BulkId } from '../types.js';
  */
 export interface FetchOpts {
     url: string;
-    format?: 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"`,
@@ -26,29 +56,116 @@ export interface FetchOpts {
      */
     custom?: Record<string, unknown>;
 }
+/**
+ * The query params `GET /v1/fetch` accepts, in serialization order.
+ *
+ * This is the single source of truth for BOTH halves of the GET path: the
+ * {@link FetchGetOpts} key set and the query string the builder emits. Keeping
+ * them derived from one list is what makes "accepted by the type but dropped by
+ * the serializer" — the #2539 bug — unrepresentable. The list itself is pinned to
+ * 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"];
+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
+ * `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.
+ */
+export type FetchGetOpts = Pick<FetchOpts, FetchGetQueryKey>;
+/** Cache-lookup outcome reported in the `X-Fetch-Cache` response header. */
+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-*`
+ * 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
+ * `headers` (e.g. `X-Fetch-Duration-Ms`, `X-Fetch-Waf-Vendor`).
+ */
+export interface FetchResult {
+    /**
+     * The raw response body exactly as returned — never `JSON.parse`d. Decoded as
+     * UTF-8: for text content (HTML, markdown, JSON-as-string) this is exact, but for
+     * true binary content (images, PDFs, etc. — `/v1/fetch` supports raw passthrough)
+     * any byte sequence that isn't valid UTF-8 is silently replaced with U+FFFD. Use
+     * {@link FetchResult.bytes} when the content may be binary.
+     */
+    body: string;
+    /**
+     * The raw response body as bytes, byte-for-byte identical to the wire content —
+     * lossless for both text and true binary content (images, PDFs, etc.). Prefer
+     * this over `body` whenever the fetched content might not be UTF-8 text.
+     */
+    bytes: Uint8Array;
+    /** `X-Fetch-ID` — unique fetch id (`ft_…`), or `null` if the header is absent. */
+    id: string | null;
+    /** `X-Fetch-Credits-Charged` parsed as a number, or `null` if absent/unparseable. */
+    creditsCharged: number | null;
+    /** `X-Fetch-Cache` — `hit` | `miss` | `bypass`, or `null` if absent. */
+    cache: FetchCacheStatus | null;
+    /**
+     * `X-Fetch-Custom` — base64-encoded echo of the request's `custom` payload,
+     * or `null` when the request sent no `custom`.
+     */
+    custom: string | null;
+    /** The response `Content-Type` (e.g. `text/html`), or `null` if absent. */
+    contentType: string | null;
+    /** The full header set on the response, for any `X-Fetch-*` value not surfaced above. */
+    headers: Headers;
+}
 export declare class FetchResource {
     private readonly client;
     readonly bulk: FetchBulkResource;
-    constructor(client: RapidCrawl);
+    constructor(client: ByteKit);
     /**
      * POST /v1/fetch — fetch URL content via POST body.
      *
-     * Returns content directly (not ID-based).
+     * Resolves a `FetchResult` — the raw content body plus `X-Fetch-*` metadata.
+     * The body is returned verbatim — a JSON-serving upstream comes back as the
+     * raw JSON string, not a parsed object.
+     *
+     * `requestOptions` carries the CLIENT-side abort budget (`requestTimeoutMs`) and an
+     * optional caller `signal`. It matters most here: the gateway's own ceiling for a
+     * fetch is 60 s, so without a per-call budget a slow upstream holds the caller for
+     * the constructor default (2 minutes) rather than a duration the caller chose.
      */
-    create(opts: FetchOpts): Promise<unknown>;
+    create(opts: FetchOpts, requestOptions?: RequestOptions): Promise<FetchResult>;
     /**
      * GET /v1/fetch — fetch URL content via query params.
      *
-     * Returns content directly (not ID-based).
+     * 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.
+     *
+     * The query string is built by iterating `FETCH_GET_QUERY_KEYS`, the same list
+     * `FetchGetOpts` is derived from, so every accepted option is necessarily
+     * serialized.
+     *
+     * `requestOptions` carries the CLIENT-side abort budget (`requestTimeoutMs`) and an
+     * optional caller `signal`. As on `create`, the gateway's own ceiling for a fetch is
+     * 60 s, so a per-call budget is what keeps a slow upstream from holding the caller
+     * for the constructor default.
      */
-    get(opts: FetchOpts): Promise<unknown>;
+    get(opts: FetchGetOpts, requestOptions?: RequestOptions): Promise<FetchResult>;
 }
 declare class FetchBulkResource {
     private readonly client;
-    constructor(client: RapidCrawl);
+    constructor(client: ByteKit);
     /** POST /v1/fetch/bulk — create a bulk fetch job */
-    create(opts: Record<string, unknown>): Promise<unknown>;
+    create(opts: FetchBulkCreateRequest, requestOptions?: RequestOptions): Promise<FetchBulkCreateResponse>;
     /** GET /v1/fetch/bulk/{id} — get a bulk fetch job */
-    get(id: BulkId): Promise<unknown>;
+    get(id: BulkId, requestOptions?: RequestOptions): Promise<FetchBulkGetResponse>;
 }
 export {};

package/dist/resources/fetch.js

@@ -1,3 +1,34 @@
+/**
+ * The query params `GET /v1/fetch` accepts, in serialization order.
+ *
+ * This is the single source of truth for BOTH halves of the GET path: the
+ * {@link FetchGetOpts} key set and the query string the builder emits. Keeping
+ * them derived from one list is what makes "accepted by the type but dropped by
+ * the serializer" — the #2539 bug — unrepresentable. The list itself is pinned to
+ * 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 CACHE_STATUSES = ['hit', 'miss', 'bypass'];
+/** Build a typed {@link FetchResult} from a raw body + its header set. */
+function toFetchResult(raw) {
+    const { body, bytes, headers } = raw;
+    const creditsRaw = headers.get('X-Fetch-Credits-Charged');
+    const credits = creditsRaw === null ? NaN : Number(creditsRaw);
+    const cacheRaw = headers.get('X-Fetch-Cache');
+    return {
+        body,
+        bytes,
+        id: headers.get('X-Fetch-ID'),
+        creditsCharged: Number.isFinite(credits) ? credits : null,
+        cache: cacheRaw !== null && CACHE_STATUSES.includes(cacheRaw)
+            ? cacheRaw
+            : null,
+        custom: headers.get('X-Fetch-Custom'),
+        contentType: headers.get('Content-Type'),
+        headers,
+    };
+}
 export class FetchResource {
     client;
     bulk;
@@ -8,28 +39,45 @@ export class FetchResource {
     /**
      * POST /v1/fetch — fetch URL content via POST body.
      *
-     * Returns content directly (not ID-based).
+     * Resolves a `FetchResult` — the raw content body plus `X-Fetch-*` metadata.
+     * The body is returned verbatim — a JSON-serving upstream comes back as the
+     * raw JSON string, not a parsed object.
+     *
+     * `requestOptions` carries the CLIENT-side abort budget (`requestTimeoutMs`) and an
+     * optional caller `signal`. It matters most here: the gateway's own ceiling for a
+     * fetch is 60 s, so without a per-call budget a slow upstream holds the caller for
+     * the constructor default (2 minutes) rather than a duration the caller chose.
      */
-    create(opts) {
-        return this.client.request('POST', '/v1/fetch', opts);
+    async create(opts, requestOptions) {
+        return toFetchResult(await this.client.requestRaw('POST', '/v1/fetch', opts, requestOptions));
     }
     /**
      * GET /v1/fetch — fetch URL content via query params.
      *
-     * Returns content directly (not ID-based).
+     * 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.
+     *
+     * The query string is built by iterating `FETCH_GET_QUERY_KEYS`, the same list
+     * `FetchGetOpts` is derived from, so every accepted option is necessarily
+     * serialized.
+     *
+     * `requestOptions` carries the CLIENT-side abort budget (`requestTimeoutMs`) and an
+     * optional caller `signal`. As on `create`, the gateway's own ceiling for a fetch is
+     * 60 s, so a per-call budget is what keeps a slow upstream from holding the caller
+     * for the constructor default.
      */
-    get(opts) {
+    async get(opts, requestOptions) {
         const params = new URLSearchParams();
-        params.set('url', opts.url);
-        if (opts.format !== undefined)
-            params.set('format', opts.format);
-        if (opts.country !== undefined)
-            params.set('country', opts.country);
-        if (opts.timeout_ms !== undefined)
-            params.set('timeout_ms', String(opts.timeout_ms));
-        if (opts.cache_ttl !== undefined)
-            params.set('cache_ttl', String(opts.cache_ttl));
-        return this.client.request('GET', `/v1/fetch?${params.toString()}`);
+        for (const key of FETCH_GET_QUERY_KEYS) {
+            const value = opts[key];
+            if (value !== undefined)
+                params.set(key, String(value));
+        }
+        return toFetchResult(await this.client.requestRaw('GET', `/v1/fetch?${params.toString()}`, undefined, requestOptions));
     }
 }
 class FetchBulkResource {
@@ -38,11 +86,11 @@ class FetchBulkResource {
         this.client = client;
     }
     /** POST /v1/fetch/bulk — create a bulk fetch job */
-    create(opts) {
-        return this.client.request('POST', '/v1/fetch/bulk', opts);
+    create(opts, requestOptions) {
+        return this.client.request('POST', '/v1/fetch/bulk', opts, requestOptions);
     }
     /** GET /v1/fetch/bulk/{id} — get a bulk fetch job */
-    get(id) {
-        return this.client.request('GET', `/v1/fetch/bulk/${id}`);
+    get(id, requestOptions) {
+        return this.client.request('GET', `/v1/fetch/bulk/${id}`, undefined, requestOptions);
     }
 }

package/dist/resources/monitors.d.ts

@@ -1,27 +1,85 @@
-import type { RapidCrawl } from '../client.js';
+import type { ByteKit, RequestOptions } from '../client.js';
+import type { operations } from '../generated/api.js';
 import type { MonitorId } from '../types.js';
+/**
+ * Query params of GET /v1/monitors — all optional, omitted when unset.
+ *
+ * DERIVED from the generated `listMonitors` query type (#2547), never hand-authored:
+ * `status` was previously typed a bare `string`, so a typo like `'activee'` compiled and
+ * only failed as a 422 on the wire. Deriving it pins the filter to the spec enum, exactly
+ * as {@link ListWebhookDeliveriesParams} does for `/v1/webhook-deliveries`.
+ *
+ * Still a `type` alias (not an `interface`) so it carries an implicit index signature and
+ * stays assignable to {@link toQueryString}'s `Record<string, string | number | undefined>`
+ * param (interfaces do not get the implicit index signature; type aliases do).
+ */
+export type ListMonitorsParams = NonNullable<operations['listMonitors']['parameters']['query']>;
+/**
+ * Lifecycle status a monitor can be filtered by — the spec enum behind
+ * {@link ListMonitorsParams.status}. Exported so callers (and the CLI) can name it.
+ */
+export type MonitorStatus = NonNullable<ListMonitorsParams['status']>;
+/** The `createMonitor` request body exactly as the OpenAPI spec declares it. */
+type MonitorRequestSpec = operations['createMonitor']['requestBody']['content']['application/json'];
+/**
+ * Body of POST /v1/monitors — `url`, `interval_type`, `webhook_url` required,
+ * every other field optional.
+ *
+ * Same `defaultNonNullable` drift documented on `ScreenshotCreateRequest`
+ * (screenshots.ts:12-31, follow-up #2540): the spec's
+ * `required: [url, interval_type, webhook_url]` is narrow, but `type`,
+ * `change_threshold`, and `notify_on` carry `default:` and `openapi-typescript`
+ * v7 promotes them to non-optional in the generated type. Relaxed here so the
+ * spec-minimal `create(...)` compiles — still DERIVED from the operation type,
+ * never hand-authored.
+ */
+export type MonitorCreateRequest = Partial<MonitorRequestSpec> & Pick<MonitorRequestSpec, 'url' | 'interval_type' | 'webhook_url'>;
+/** 201 payload of POST /v1/monitors. */
+export type MonitorCreateResponse = operations['createMonitor']['responses'][201]['content']['application/json'];
+/** 200 payload of GET /v1/monitors — the paginated monitor list. */
+export type ListMonitorsResponse = operations['listMonitors']['responses'][200]['content']['application/json'];
+/** 200 payload of GET /v1/monitors/{id} — a single monitor. */
+export type MonitorResponse = operations['getMonitor']['responses'][200]['content']['application/json'];
+/** Body of PATCH /v1/monitors/{id}. */
+export type MonitorUpdateRequest = operations['updateMonitor']['requestBody']['content']['application/json'];
+/** 200 payload of PATCH /v1/monitors/{id}. */
+export type UpdateMonitorResponse = operations['updateMonitor']['responses'][200]['content']['application/json'];
+/** 200 payload of GET /v1/monitors/{id}/captures — the paginated capture list. */
+export type ListMonitorCapturesResponse = operations['listMonitorCaptures']['responses'][200]['content']['application/json'];
 export declare class MonitorsResource {
     private readonly client;
     readonly captures: MonitorCapturesResource;
-    constructor(client: RapidCrawl);
+    constructor(client: ByteKit);
     /**
      * POST /v1/monitors — create a page-change monitor (screenshot or scrape capture).
      * First-capture behavior is the same for both types: the first capture is a silent baseline (has_change=false, change_pct=null) with no change_detected webhook, whether the monitor is `scrape` or `screenshot`. From the second capture onward both types diff against the previous capture.
      */
-    create(opts: Record<string, unknown>): Promise<unknown>;
-    /** GET /v1/monitors — list all monitors for the account */
-    list(): Promise<unknown>;
+    create(opts: MonitorCreateRequest, requestOptions?: RequestOptions): Promise<MonitorCreateResponse>;
+    /**
+     * GET /v1/monitors — list monitors for the account.
+     *
+     * `params` is optional and each key is omitted-when-absent, so `list()` with no argument
+     * serializes the bare `/v1/monitors` URL unchanged — existing zero-arg callers are unaffected.
+     */
+    list(params?: ListMonitorsParams, requestOptions?: RequestOptions): Promise<ListMonitorsResponse>;
     /** GET /v1/monitors/{id} — get a monitor by ID */
-    get(id: MonitorId): Promise<unknown>;
+    get(id: MonitorId, requestOptions?: RequestOptions): Promise<MonitorResponse>;
     /** PATCH /v1/monitors/{id} — update a monitor */
-    update(id: MonitorId, opts: Record<string, unknown>): Promise<unknown>;
-    /** DELETE /v1/monitors/{id} — delete a monitor */
-    delete(id: MonitorId): Promise<unknown>;
+    update(id: MonitorId, opts: MonitorUpdateRequest, requestOptions?: RequestOptions): Promise<UpdateMonitorResponse>;
+    /**
+     * DELETE /v1/monitors/{id} — delete a monitor.
+     *
+     * Returns 204 No Content (`operations['deleteMonitor']['responses'][204]`
+     * declares `content?: never`), so there is no JSON arm to derive a payload
+     * from — hence `Promise<void>`. `client.request()` short-circuits the empty
+     * body to `undefined` before it would parse as JSON (#2450).
+     */
+    delete(id: MonitorId, requestOptions?: RequestOptions): Promise<void>;
 }
 declare class MonitorCapturesResource {
     private readonly client;
-    constructor(client: RapidCrawl);
+    constructor(client: ByteKit);
     /** GET /v1/monitors/{id}/captures — list captures for a monitor */
-    list(id: MonitorId): Promise<unknown>;
+    list(id: MonitorId, requestOptions?: RequestOptions): Promise<ListMonitorCapturesResponse>;
 }
 export {};

package/dist/resources/monitors.js

@@ -1,3 +1,4 @@
+import { toQueryString } from './query-string.js';
 export class MonitorsResource {
     client;
     captures;
@@ -9,24 +10,36 @@ export class MonitorsResource {
      * POST /v1/monitors — create a page-change monitor (screenshot or scrape capture).
      * First-capture behavior is the same for both types: the first capture is a silent baseline (has_change=false, change_pct=null) with no change_detected webhook, whether the monitor is `scrape` or `screenshot`. From the second capture onward both types diff against the previous capture.
      */
-    create(opts) {
-        return this.client.request('POST', '/v1/monitors', opts);
+    create(opts, requestOptions) {
+        return this.client.request('POST', '/v1/monitors', opts, requestOptions);
     }
-    /** GET /v1/monitors — list all monitors for the account */
-    list() {
-        return this.client.request('GET', '/v1/monitors');
+    /**
+     * GET /v1/monitors — list monitors for the account.
+     *
+     * `params` is optional and each key is omitted-when-absent, so `list()` with no argument
+     * serializes the bare `/v1/monitors` URL unchanged — existing zero-arg callers are unaffected.
+     */
+    list(params, requestOptions) {
+        return this.client.request('GET', `/v1/monitors${toQueryString(params)}`, undefined, requestOptions);
     }
     /** GET /v1/monitors/{id} — get a monitor by ID */
-    get(id) {
-        return this.client.request('GET', `/v1/monitors/${id}`);
+    get(id, requestOptions) {
+        return this.client.request('GET', `/v1/monitors/${id}`, undefined, requestOptions);
     }
     /** PATCH /v1/monitors/{id} — update a monitor */
-    update(id, opts) {
-        return this.client.request('PATCH', `/v1/monitors/${id}`, opts);
+    update(id, opts, requestOptions) {
+        return this.client.request('PATCH', `/v1/monitors/${id}`, opts, requestOptions);
     }
-    /** DELETE /v1/monitors/{id} — delete a monitor */
-    delete(id) {
-        return this.client.request('DELETE', `/v1/monitors/${id}`);
+    /**
+     * DELETE /v1/monitors/{id} — delete a monitor.
+     *
+     * Returns 204 No Content (`operations['deleteMonitor']['responses'][204]`
+     * declares `content?: never`), so there is no JSON arm to derive a payload
+     * from — hence `Promise<void>`. `client.request()` short-circuits the empty
+     * body to `undefined` before it would parse as JSON (#2450).
+     */
+    delete(id, requestOptions) {
+        return this.client.request('DELETE', `/v1/monitors/${id}`, undefined, requestOptions);
     }
 }
 class MonitorCapturesResource {
@@ -35,7 +48,7 @@ class MonitorCapturesResource {
         this.client = client;
     }
     /** GET /v1/monitors/{id}/captures — list captures for a monitor */
-    list(id) {
-        return this.client.request('GET', `/v1/monitors/${id}/captures`);
+    list(id, requestOptions) {
+        return this.client.request('GET', `/v1/monitors/${id}/captures`, undefined, requestOptions);
     }
 }

package/dist/resources/query-string.d.ts

@@ -0,0 +1,10 @@
+/**
+ * Serialize a flat params object to a `?a=1&b=2` query string, omitting `undefined` values.
+ *
+ * Returns `''` (not `'?'`) for a `undefined` param bag or one whose every value is `undefined`,
+ * so a caller can unconditionally append the result to a path and get a bare URL when no params
+ * are set. This is the single query-string serializer shared across the query-param resources
+ * (`usage`, `webhooks`, `monitors`) — extracting it keeps their omit-when-absent semantics
+ * byte-identical rather than drifting across per-file copies.
+ */
+export declare function toQueryString(params: Record<string, string | number | undefined> | undefined): string;

package/dist/resources/query-string.js

@@ -0,0 +1,20 @@
+/**
+ * Serialize a flat params object to a `?a=1&b=2` query string, omitting `undefined` values.
+ *
+ * Returns `''` (not `'?'`) for a `undefined` param bag or one whose every value is `undefined`,
+ * so a caller can unconditionally append the result to a path and get a bare URL when no params
+ * are set. This is the single query-string serializer shared across the query-param resources
+ * (`usage`, `webhooks`, `monitors`) — extracting it keeps their omit-when-absent semantics
+ * byte-identical rather than drifting across per-file copies.
+ */
+export function toQueryString(params) {
+    if (!params)
+        return '';
+    const search = new URLSearchParams();
+    for (const [key, value] of Object.entries(params)) {
+        if (value !== undefined)
+            search.set(key, String(value));
+    }
+    const qs = search.toString();
+    return qs ? `?${qs}` : '';
+}

package/dist/resources/scrape.d.ts

@@ -1,5 +1,5 @@
-import type { RapidCrawl, RequestOptions } from '../client.js';
-import type { operations } from '../generated/api.js';
+import type { ByteKit, RequestOptions } from '../client.js';
+import type { components, 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
@@ -21,13 +21,27 @@ export type ScrapeBulkGetResponse = operations['getScrapeBulk']['responses'][200
 /** Markdown processing mode for the pipeline. */
 export type MarkdownMode = 'article' | 'raw' | 'llm';
 /** Link rendering style in the markdown output. */
-export type MarkdownLinks = 'inline' | 'references' | 'none';
+export type MarkdownLinks = 'inline' | 'references' | 'none' | 'text';
+/** Image retention mode in the markdown output. */
+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?: Array<Record<string, unknown>>;
+    /** 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`. */
@@ -41,6 +55,12 @@ export interface ScrapeOpts {
     markdown_query?: string;
     /** Link rendering style in the markdown output. */
     markdown_links?: MarkdownLinks;
+    /** Image retention mode in the markdown output. Distinct from `markdown_filter_images` (which drops low-signal images before conversion). */
+    markdown_images?: MarkdownImages;
+    /** When true, appends a `Links:` footer to the markdown output. Automatically enabled when `markdown_links` is `'references'`. */
+    with_links_summary?: boolean;
+    /** When true, appends an `Images:` footer to the markdown output. */
+    with_images_summary?: boolean;
     /** Collapse excessive whitespace for a more compact output. */
     markdown_compact?: boolean;
     /** Filter low-signal images from the markdown output. */
@@ -51,6 +71,20 @@ export interface ScrapeOpts {
     markdown_include_warnings?: boolean;
     /** When true, the response includes a top-level `stats` object with `ScrapeStats` (chars, tokens, blocks). Only effective when `markdown` is in `formats`. */
     markdown_include_stats?: boolean;
+    /** Maximum token count for the markdown output. Truncates at the last paragraph → sentence → token boundary under the limit. Absent → no truncation. */
+    token_budget?: number;
+    /** Tokenizer encoding hint for `token_budget`. `cl100k_base` (default) matches GPT-4/4o; `o200k_base` matches GPT-4o-mini / o-series. */
+    token_encoding?: TokenEncoding;
+    /** When true, emulate a mobile device (mobile UA + viewport). Default false (desktop). Part of the cache key, so mobile and desktop responses cache independently. */
+    mobile?: boolean;
+    /** When true (default), base64-encoded `data:` image sources are stripped before markdown conversion and from `html` output. Set false to preserve them. Does not affect `raw_html`. */
+    remove_base64_images?: boolean;
+    /** HTML element names (not CSS selectors) to keep. When non-empty, only content within these elements is included in `html`/`markdown` output. Applied before `exclude_tags`. Does not affect `raw_html`. */
+    include_tags?: string[];
+    /** HTML element names (not CSS selectors) to strip from `html`/`markdown` output. Applied after `include_tags`. Does not affect `raw_html`. */
+    exclude_tags?: string[];
+    /** When true and `markdown` is in `formats`, the converted markdown is sent to Groq for cleaning before return. Graceful degradation on any Groq failure. Billing: 3× credits and bytes applied only when cleaning succeeds. */
+    clean_markdown?: boolean;
     /**
      * How long a freshly fetched URL may be served from cache. `'0'`/`0` skips the
      * cache read (the result is still written), `'Nh'`/`'Nd'` set a TTL (capped at
@@ -70,7 +104,7 @@ export interface ScrapeOpts {
 export declare class ScrapeResource {
     private readonly client;
     readonly bulk: ScrapeBulkResource;
-    constructor(client: RapidCrawl);
+    constructor(client: ByteKit);
     /**
      * POST /v1/scrape — create a scrape job.
      *
@@ -102,10 +136,15 @@ export declare class ScrapeResource {
 }
 declare class ScrapeBulkResource {
     private readonly client;
-    constructor(client: RapidCrawl);
-    /** POST /v1/scrape/bulk — create a bulk scrape job */
-    create(opts: ScrapeBulkCreateRequest): Promise<ScrapeBulkCreateResponse>;
+    constructor(client: ByteKit);
+    /**
+     * POST /v1/scrape/bulk — create a bulk scrape job.
+     *
+     * `requestOptions` carries the CLIENT-side abort budget (`requestTimeoutMs`) and an
+     * optional caller `signal`; both override the constructor's `timeoutMs` default.
+     */
+    create(opts: ScrapeBulkCreateRequest, requestOptions?: RequestOptions): Promise<ScrapeBulkCreateResponse>;
     /** GET /v1/scrape/bulk/{id} — get a bulk scrape job */
-    get(id: BulkId): Promise<ScrapeBulkGetResponse>;
+    get(id: BulkId, requestOptions?: RequestOptions): Promise<ScrapeBulkGetResponse>;
 }
 export {};

package/dist/resources/scrape.js

@@ -43,12 +43,17 @@ class ScrapeBulkResource {
     constructor(client) {
         this.client = client;
     }
-    /** POST /v1/scrape/bulk — create a bulk scrape job */
-    create(opts) {
-        return this.client.request('POST', '/v1/scrape/bulk', opts);
+    /**
+     * POST /v1/scrape/bulk — create a bulk scrape job.
+     *
+     * `requestOptions` carries the CLIENT-side abort budget (`requestTimeoutMs`) and an
+     * optional caller `signal`; both override the constructor's `timeoutMs` default.
+     */
+    create(opts, requestOptions) {
+        return this.client.request('POST', '/v1/scrape/bulk', opts, requestOptions);
     }
     /** GET /v1/scrape/bulk/{id} — get a bulk scrape job */
-    get(id) {
-        return this.client.request('GET', `/v1/scrape/bulk/${id}`);
+    get(id, requestOptions) {
+        return this.client.request('GET', `/v1/scrape/bulk/${id}`, undefined, requestOptions);
     }
 }