@hunt-labs/bytekit-sdk 0.2.2 → 0.3.0

package/CHANGELOG.md

@@ -8,6 +8,56 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 This file records only the delta between versions. For how to use the package
 today, see [README.md](./README.md), which remains the authoritative usage guide.
 
+## [0.3.0] - 2026-07-21
+
+### Removed (**BREAKING**)
+
+- The deprecated `RapidCrawl`, `RapidCrawlError`, and `RapidCrawlConnectionError`
+  exports and the `RapidCrawlOptions` type alias (kept as a one-minor-version
+  bridge in #2421) are removed. Import the `ByteKit*` names instead. (#2473)
+- The `RecordingId` type export is removed. Recordings are deactivated
+  (`/v1/recordings` returns 410), so the branded id had no reachable use.
+  Breaking in theory only — unused in practice. (#2481)
+
+### Fixed
+
+- `fetch.create` / `fetch.get` no longer throw a bare `SyntaxError` on every
+  non-JSON body. `/v1/fetch` returns the fetched content AS the response body
+  (metadata in `X-Fetch-*` headers), but both methods routed through the
+  JSON-parsing transport. They now use a raw-capable transport and resolve to a
+  typed `FetchResult` — raw `body`, byte-exact `bytes`, plus `id`,
+  `creditsCharged`, `cache`, `custom`, `contentType`, and `headers` parsed from
+  the `X-Fetch-*` metadata. (#2466)
+- A trailing slash on the constructor `baseUrl` (e.g. `"https://api.bytekit.com/"`)
+  no longer produces double-slash request URLs — it is normalized once, preserving
+  a path-carrying baseUrl. (#2481)
+- `SearchResult.date` is now optional (`string | null | undefined`): `images`
+  search results omit the field entirely. (#2481)
+
+### Added
+
+- New `usage` resource (`get`, `daily`, `byEndpoint` — `GET /v1/usage`,
+  `/v1/usage/daily`, `/v1/usage/by-endpoint`) and `webhooks` resource (`list`,
+  `retry` — `GET /v1/webhook-deliveries`, `POST /v1/webhook-deliveries/{id}/retry`),
+  with their request/response types exported. (#2471)
+- `ScrapeOpts` and `FetchOpts` now cover the full documented request field set
+  (10 previously missing `ScrapeRequest` fields; 11 markdown-tuning
+  `FetchRequest` fields), plus the `'text'` markdown-links mode. A compile-time
+  drift guard keeps them aligned with the generated OpenAPI schema. (#2475)
+- `monitors`, `sitemap`, `bulk`, and `fetch.bulk` methods are now fully typed from
+  the generated OpenAPI `operations` (previously `Record<string, unknown>` in /
+  `Promise<unknown>` out); their request/response types are re-exported. (#2481)
+- `monitors.list` accepts typed query params and returns a typed response
+  (`ListMonitorsParams` / `ListMonitorsResponse`, both exported). (#2480)
+
+### Changed (**BREAKING**)
+
+- `fetch.get` now rejects a `custom` option at compile time: `GET /v1/fetch` has
+  no `custom` query param, so the value was silently dropped before. Use
+  `fetch.create` (POST) to echo a `custom` payload. (#2481)
+- `FetchOpts.format` is narrowed from `string` to the spec union
+  `'markdown' | 'html'`; off-spec values now fail to compile. (#2475)
+
 ## [0.2.2] - 2026-07-16
 
 ### Changed
@@ -85,6 +135,7 @@ against 0.1.0 — read each one before upgrading.
   (scrape, screenshot, search, and related endpoints), published under the original
   `@rapidcrawl/sdk` name.
 
+[0.3.0]: https://github.com/Hunt-Labs-Inc/ByteKit/tree/main/packages/sdk-typescript
 [0.2.2]: https://github.com/Hunt-Labs-Inc/ByteKit/tree/main/packages/sdk-typescript
 [0.2.1]: https://github.com/Hunt-Labs-Inc/ByteKit/tree/main/packages/sdk-typescript
 [0.2.0]: https://github.com/Hunt-Labs-Inc/ByteKit/tree/main/packages/sdk-typescript

package/README.md

@@ -27,16 +27,15 @@ Create an API key at [app.bytekit.com](https://app.bytekit.com) (keys are
 prefixed `sk_live_`) and pass it to the client constructor:
 
 ```ts
-import { RapidCrawl } from '@hunt-labs/bytekit-sdk';
+import { ByteKit } from '@hunt-labs/bytekit-sdk';
 
-const client = new RapidCrawl({ apiKey: process.env.BYTEKIT_API_KEY! }); // sk_live_...
+const client = new ByteKit({ apiKey: process.env.BYTEKIT_API_KEY! }); // sk_live_...
 ```
 
 The key is sent as `Authorization: Bearer <apiKey>` on every request. Keep it
 server-side — it is not safe to ship in a browser bundle.
 
-> The client class is named `RapidCrawl` for historical reasons (ByteKit's
-> previous product name). It is the SDK's only entrypoint class.
+> `ByteKit` is the SDK's only entrypoint class.
 
 ## Base-URL override
 
@@ -44,7 +43,7 @@ Requests go to `https://api.bytekit.com` by default. Point the client at
 staging, a local gateway, or a proxy with the `baseUrl` option:
 
 ```ts
-const client = new RapidCrawl({
+const client = new ByteKit({
   apiKey: process.env.BYTEKIT_API_KEY!,
   baseUrl: 'https://api-stg.bytekit.com', // default: https://api.bytekit.com
 });
@@ -69,8 +68,27 @@ const scrape = await client.scrape.get('sc_123abc');
 
 ### Raw fetch (unprocessed response body)
 
+`/v1/fetch` returns the fetched content **as the body**, with metadata in
+`X-Fetch-*` response headers. `fetch.create` / `fetch.get` resolve a
+`FetchResult` — `body` is the raw content string (a JSON-serving upstream
+comes back as the raw JSON string, never a parsed object), and the named
+fields decode the metadata headers. `body` is UTF-8-decoded, so for true
+binary content (images, PDFs, etc. — `/v1/fetch` supports raw passthrough)
+use `bytes` instead, which is byte-for-byte identical to the wire content:
+
 ```ts
-const raw = await client.fetch.create({ url: 'https://example.com' });
+const res = await client.fetch.create({ url: 'https://example.com' });
+
+console.log(res.body); // raw content (e.g. "<!doctype html>…") — UTF-8 decoded
+console.log(res.bytes); // Uint8Array — byte-exact, safe for binary content
+console.log(res.id); // X-Fetch-ID, e.g. "ft_0123abcd…"
+console.log(res.creditsCharged); // X-Fetch-Credits-Charged, as a number
+console.log(res.cache); // "hit" | "miss" | "bypass"
+console.log(res.custom); // base64 X-Fetch-Custom echo, or null
+console.log(res.contentType); // response Content-Type, e.g. "text/html"
+
+// Anything not surfaced as a named field is on res.headers:
+console.log(res.headers.get('X-Fetch-Waf-Vendor'));
 ```
 
 ### Web search
@@ -124,7 +142,10 @@ await client.bulk.screenshots.list('bulk_123abc');
 ```ts
 const monitor = await client.monitors.create({
   url: 'https://example.com/pricing',
+  type: 'screenshot',
   interval_type: 'daily',
+  change_threshold: 5,
+  notify_on: 'change',
   webhook_url: 'https://your.app/hooks/bytekit',
 });
 await client.monitors.list();
@@ -134,7 +155,16 @@ await client.monitors.delete('mon_123abc');
 ### Sitemap crawl
 
 ```ts
-const crawl = await client.sitemap.create({ url: 'https://example.com' });
+const crawl = await client.sitemap.create({
+  url: 'https://example.com',
+  strategy: 'standard',
+  max_depth: 2,
+  max_urls: 5000,
+  process: null,
+  webhook_secret: null,
+  cache_ttl: '30d',
+  compact: false,
+});
 const sitemap = await client.sitemap.get('sm_123abc');
 ```
 
@@ -143,20 +173,36 @@ const sitemap = await client.sitemap.get('sm_123abc');
 ```ts
 const account = await client.account.get();
 const keys = await client.account.apiKeys.list();
+
+// Usage (Bearer API key auth)
+const usage = await client.usage.get();
+const daily = await client.usage.daily({ from: '2026-01-01', to: '2026-01-31' });
+const byEndpoint = await client.usage.byEndpoint();
+
+// Webhook deliveries
+const deliveries = await client.webhooks.list();
+await client.webhooks.retry('whd_123abc');
 ```
 
+> **Note:** `client.account.*` (including `client.account.apiKeys.*`) targets the
+> `/v1/account/*` endpoints, which authenticate with a Clerk dashboard session —
+> **not** a Bearer API key. Calling them with an API-key client will fail auth.
+> They remain on the SDK surface for dashboard/session consumers and are marked
+> `x-sdk-scope: internal` in the spec, so they are intentionally excluded from the
+> v0.1 Bearer-key parity guarantee.
+
 ## Error handling
 
-Any 4xx/5xx response throws a `RapidCrawlError` carrying the HTTP status and
+Any 4xx/5xx response throws a `ByteKitError` carrying the HTTP status and
 the API's error code:
 
 ```ts
-import { RapidCrawl, RapidCrawlError } from '@hunt-labs/bytekit-sdk';
+import { ByteKit, ByteKitError } from '@hunt-labs/bytekit-sdk';
 
 try {
   await client.scrape.create({ url: 'https://example.com' });
 } catch (err) {
-  if (err instanceof RapidCrawlError) {
+  if (err instanceof ByteKitError) {
     console.error(err.status, err.code, err.message);
   }
 }

package/dist/allowlist.d.ts

@@ -8,5 +8,5 @@
  *
  * To add a method: annotate the operation in the spec first, then add it here.
  */
-export declare const V01_METHODS: readonly ["scrape.create", "scrape.get", "screenshots.create", "screenshots.get", "bulk.create", "bulk.get", "bulk.cancel", "bulk.screenshots.list", "scrape.bulk.create", "scrape.bulk.get", "fetch.create", "fetch.get", "fetch.bulk.create", "fetch.bulk.get", "monitors.create", "monitors.list", "monitors.get", "monitors.update", "monitors.delete", "monitors.captures.list", "sitemap.create", "sitemap.get", "search.query", "account.get"];
+export declare const V01_METHODS: readonly ["scrape.create", "scrape.get", "screenshots.create", "screenshots.get", "bulk.create", "bulk.get", "bulk.cancel", "bulk.screenshots.list", "scrape.bulk.create", "scrape.bulk.get", "fetch.create", "fetch.get", "fetch.bulk.create", "fetch.bulk.get", "monitors.create", "monitors.list", "monitors.get", "monitors.update", "monitors.delete", "monitors.captures.list", "sitemap.create", "sitemap.get", "search.query", "account.get", "usage.get", "usage.daily", "usage.byEndpoint", "webhooks.list", "webhooks.retry"];
 export type V01Method = (typeof V01_METHODS)[number];

package/dist/allowlist.js

@@ -34,4 +34,11 @@ export const V01_METHODS = [
     'sitemap.get',
     'search.query',
     'account.get',
+    // usage + webhook-delivery ops — resource surface shipped in #2471, brought
+    // under the parity guard in #2476.
+    'usage.get',
+    'usage.daily',
+    'usage.byEndpoint',
+    'webhooks.list',
+    'webhooks.retry',
 ];

package/dist/client.d.ts

@@ -6,6 +6,8 @@ import { MonitorsResource } from './resources/monitors.js';
 import { SitemapResource } from './resources/sitemap.js';
 import { SearchResource } from './resources/search.js';
 import { AccountResource } from './resources/account.js';
+import { UsageResource } from './resources/usage.js';
+import { WebhooksResource } from './resources/webhooks.js';
 export interface ByteKitOptions {
     apiKey: string;
     baseUrl?: string;
@@ -71,6 +73,8 @@ export declare class ByteKit {
     readonly sitemap: SitemapResource;
     readonly search: SearchResource;
     readonly account: AccountResource;
+    readonly usage: UsageResource;
+    readonly webhooks: WebhooksResource;
     constructor(options: ByteKitOptions);
     /**
      * Resolve the abort budget for one request from the caller's options and the
@@ -86,6 +90,20 @@ export declare class ByteKit {
      * A timeout of `0` (either level) means "no SDK-side timeout".
      */
     private resolveSignal;
+    /**
+     * Perform the authenticated round-trip and return the raw `Response`, having
+     * already thrown for the two non-body failure modes:
+     *
+     * - `ByteKitConnectionError` when no HTTP response was produced at all
+     *   (DNS/socket/TLS failure, client-side timeout, or caller abort).
+     * - `ByteKitError` on any 4xx/5xx, carrying the API's `code`/`message`.
+     *
+     * The body is left unread so each caller can decode it as it needs — JSON for
+     * `request()`, raw text + headers for `requestRaw()`. This is the single place
+     * that owns auth, the abort budget, and the error taxonomy; the two public
+     * transports differ only in how they read a successful body.
+     */
+    private send;
     /**
      * Make an authenticated JSON request to the ByteKit API.
      *
@@ -94,6 +112,27 @@ export declare class ByteKit {
      * timeout, or caller abort).
      */
     request<T>(method: string, path: string, body?: unknown, options?: RequestOptions): Promise<T>;
+    /**
+     * Make an authenticated request whose response body IS the content, not a JSON
+     * envelope — the `/v1/fetch` contract, where metadata rides in `X-Fetch-*`
+     * response headers.
+     *
+     * Returns BOTH a UTF-8-decoded string AND the raw, byte-for-byte body, plus the
+     * response `Headers` and status, WITHOUT ever calling `JSON.parse`. This is
+     * deliberately a separate transport from `request()`: the generic JSON parse
+     * there is shared by every other resource and must not change (#2466).
+     *
+     * `/v1/fetch` supports true binary passthrough (images, PDFs, etc.) as a
+     * first-class mode, and UTF-8 decoding a non-UTF-8 byte stream is lossy — any
+     * invalid byte sequence gets silently replaced with U+FFFD. Reading the body
+     * once via `arrayBuffer()` lets both forms be derived from the same bytes: `bytes`
+     * is always byte-exact, `body` is a best-effort string for callers who know the
+     * content is text.
+     */
+    requestRaw(method: string, path: string, body?: unknown, options?: RequestOptions): Promise<{
+        body: string;
+        bytes: Uint8Array;
+        headers: Headers;
+        status: number;
+    }>;
 }
-export { ByteKit as RapidCrawl, ByteKitError as RapidCrawlError, ByteKitConnectionError as RapidCrawlConnectionError, };
-export type { ByteKitOptions as RapidCrawlOptions };

package/dist/client.js

@@ -6,6 +6,8 @@ import { MonitorsResource } from './resources/monitors.js';
 import { SitemapResource } from './resources/sitemap.js';
 import { SearchResource } from './resources/search.js';
 import { AccountResource } from './resources/account.js';
+import { UsageResource } from './resources/usage.js';
+import { WebhooksResource } from './resources/webhooks.js';
 const DEFAULT_BASE_URL = 'https://api.bytekit.com';
 /**
  * Default client-side request timeout (2 minutes).
@@ -162,12 +164,18 @@ export class ByteKit {
     sitemap;
     search;
     account;
+    usage;
+    webhooks;
     constructor(options) {
         if (!options?.apiKey) {
             throw new TypeError('ByteKit: `apiKey` is required — got an empty value. Pass options.apiKey (e.g. from process.env.BYTEKIT_API_KEY).');
         }
         this.apiKey = options.apiKey;
-        this.baseUrl = options.baseUrl ?? DEFAULT_BASE_URL;
+        // Normalize once: strip any trailing slash so `baseUrl + path` (path always
+        // starts with `/`) never yields a double-slash URL (#2481). Only the trailing
+        // slash is removed, so a path-carrying baseUrl (e.g. a reverse-proxy prefix
+        // `…/bytekit`) is preserved (E2).
+        this.baseUrl = (options.baseUrl ?? DEFAULT_BASE_URL).replace(/\/+$/, '');
         this.defaultTimeoutMs = validateTimeout(options.timeoutMs, '"timeoutMs"') ?? DEFAULT_TIMEOUT_MS;
         this.scrape = new ScrapeResource(this);
         this.screenshots = new ScreenshotsResource(this);
@@ -177,6 +185,8 @@ export class ByteKit {
         this.sitemap = new SitemapResource(this);
         this.search = new SearchResource(this);
         this.account = new AccountResource(this);
+        this.usage = new UsageResource(this);
+        this.webhooks = new WebhooksResource(this);
     }
     /**
      * Resolve the abort budget for one request from the caller's options and the
@@ -215,13 +225,19 @@ export class ByteKit {
         };
     }
     /**
-     * Make an authenticated JSON request to the ByteKit API.
+     * Perform the authenticated round-trip and return the raw `Response`, having
+     * already thrown for the two non-body failure modes:
      *
-     * Throws `ByteKitError` on 4xx/5xx responses, and `ByteKitConnectionError`
-     * when no HTTP response was produced at all (DNS/socket/TLS failure, client-side
-     * timeout, or caller abort).
+     * - `ByteKitConnectionError` when no HTTP response was produced at all
+     *   (DNS/socket/TLS failure, client-side timeout, or caller abort).
+     * - `ByteKitError` on any 4xx/5xx, carrying the API's `code`/`message`.
+     *
+     * The body is left unread so each caller can decode it as it needs — JSON for
+     * `request()`, raw text + headers for `requestRaw()`. This is the single place
+     * that owns auth, the abort budget, and the error taxonomy; the two public
+     * transports differ only in how they read a successful body.
      */
-    async request(method, path, body, options) {
+    async send(method, path, body, options) {
         const url = `${this.baseUrl}${path}`;
         const { signal, timeoutSignal, cleanup } = this.resolveSignal(options);
         const init = {
@@ -263,6 +279,17 @@ export class ByteKit {
             }
             throw new ByteKitError(response.status, code, message);
         }
+        return response;
+    }
+    /**
+     * Make an authenticated JSON request to the ByteKit API.
+     *
+     * Throws `ByteKitError` on 4xx/5xx responses, and `ByteKitConnectionError`
+     * when no HTTP response was produced at all (DNS/socket/TLS failure, client-side
+     * timeout, or caller abort).
+     */
+    async request(method, path, body, options) {
+        const response = await this.send(method, path, body, options);
         // A 204 No Content has an empty body, and a genuinely empty body can arrive on
         // other success codes too (defensive). Calling response.json() on an empty body
         // rejects with a SyntaxError — which is how a successful revoke() (DELETE → 204)
@@ -278,15 +305,27 @@ export class ByteKit {
         }
         return JSON.parse(text);
     }
+    /**
+     * Make an authenticated request whose response body IS the content, not a JSON
+     * envelope — the `/v1/fetch` contract, where metadata rides in `X-Fetch-*`
+     * response headers.
+     *
+     * Returns BOTH a UTF-8-decoded string AND the raw, byte-for-byte body, plus the
+     * response `Headers` and status, WITHOUT ever calling `JSON.parse`. This is
+     * deliberately a separate transport from `request()`: the generic JSON parse
+     * there is shared by every other resource and must not change (#2466).
+     *
+     * `/v1/fetch` supports true binary passthrough (images, PDFs, etc.) as a
+     * first-class mode, and UTF-8 decoding a non-UTF-8 byte stream is lossy — any
+     * invalid byte sequence gets silently replaced with U+FFFD. Reading the body
+     * once via `arrayBuffer()` lets both forms be derived from the same bytes: `bytes`
+     * is always byte-exact, `body` is a best-effort string for callers who know the
+     * content is text.
+     */
+    async requestRaw(method, path, body, options) {
+        const response = await this.send(method, path, body, options);
+        const bytes = new Uint8Array(await response.arrayBuffer());
+        const text = new TextDecoder('utf-8').decode(bytes);
+        return { body: text, bytes, headers: response.headers, status: response.status };
+    }
 }
-// ---------------------------------------------------------------------------
-// Deprecated RapidCrawl* aliases (#2421).
-//
-// The public surface renamed from RapidCrawl to ByteKit. These aliases point at
-// the SAME implementations (identity preserved: `RapidCrawl === ByteKit`), so an
-// existing consumer's `instanceof` / error-shape contract keeps holding for one
-// minor version. Exported here — not only from index.ts — so the SDK's own
-// resource files can keep importing the legacy type name from './client.js'
-// without churn. Re-exported (with @deprecated JSDoc) from index.ts.
-// ---------------------------------------------------------------------------
-export { ByteKit as RapidCrawl, ByteKitError as RapidCrawlError, ByteKitConnectionError as RapidCrawlConnectionError, };

package/dist/index.d.ts

@@ -1,12 +1,14 @@
 export { ByteKit, ByteKitError, ByteKitConnectionError } from './client.js';
 export type { ByteKitOptions, RequestOptions, ConnectionErrorCode } from './client.js';
-/** @deprecated Renamed to ByteKit / ByteKitError / ByteKitConnectionError — kept as aliases for one minor version. */
-export { RapidCrawl, RapidCrawlError, RapidCrawlConnectionError } from './client.js';
-/** @deprecated Renamed to ByteKitOptions — kept as an alias for one minor version. */
-export type { RapidCrawlOptions } from './client.js';
 export { V01_METHODS } from './allowlist.js';
 export type { V01Method } from './allowlist.js';
-export type { ScrapeId, ScreenshotId, RecordingId, BulkId, MonitorId, SitemapId, ApiKeyId, SearchType, SearchDateRange, SearchOpts, SearchResult, SearchResultImage, SearchResponse, } from './types.js';
+export type { ScrapeId, ScreenshotId, BulkId, MonitorId, SitemapId, ApiKeyId, WebhookDeliveryId, SearchType, SearchDateRange, SearchOpts, SearchResult, SearchResultImage, SearchResponse, } from './types.js';
 export type { 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, ListMonitorsResponse, MonitorResponse, MonitorUpdateRequest, UpdateMonitorResponse, ListMonitorCapturesResponse, } from './resources/monitors.js';
+export type { SitemapCreateRequest, SitemapCreateResponse, SitemapGetResponse, } from './resources/sitemap.js';
+export type { BulkCreateRequest, BulkCreateResponse, BulkGetResponse, BulkCancelResponse, ListBulkScreenshotsResponse, } from './resources/bulk.js';
 export type { GetAccountResponse, ListApiKeysResponse, CreateApiKeyRequest, CreateApiKeyResponse, GetApiKeyResponse, UpdateApiKeyRequest, UpdateApiKeyResponse, RevealApiKeyResponse, } from './resources/account.js';
+export type { GetUsageResponse, GetUsageDailyParams, GetUsageDailyResponse, GetUsageByEndpointParams, GetUsageByEndpointResponse, } from './resources/usage.js';
+export type { ListWebhookDeliveriesParams, ListWebhookDeliveriesResponse, RetryWebhookDeliveryResponse, } from './resources/webhooks.js';

package/dist/index.js

@@ -1,4 +1,2 @@
 export { ByteKit, ByteKitError, ByteKitConnectionError } from './client.js';
-/** @deprecated Renamed to ByteKit / ByteKitError / ByteKitConnectionError — kept as aliases for one minor version. */
-export { RapidCrawl, RapidCrawlError, RapidCrawlConnectionError } from './client.js';
 export { V01_METHODS } from './allowlist.js';

package/dist/resources/account.d.ts

@@ -1,4 +1,4 @@
-import type { RapidCrawl } from '../client.js';
+import type { ByteKit } from '../client.js';
 import type { operations } from '../generated/api.js';
 import type { ApiKeyId } from '../types.js';
 /**
@@ -36,13 +36,13 @@ export type UpdateApiKeyResponse = operations['updateApiKey']['responses'][200][
 export declare class AccountResource {
     private readonly client;
     readonly apiKeys: ApiKeysResource;
-    constructor(client: RapidCrawl);
+    constructor(client: ByteKit);
     /** GET /v1/account — get the authenticated account */
     get(): Promise<GetAccountResponse>;
 }
 declare class ApiKeysResource {
     private readonly client;
-    constructor(client: RapidCrawl);
+    constructor(client: ByteKit);
     /**
      * POST /v1/account/api-keys — create a new API key.
      *

package/dist/resources/bulk.d.ts

@@ -1,20 +1,31 @@
-import type { RapidCrawl } from '../client.js';
+import type { ByteKit } from '../client.js';
+import type { operations } from '../generated/api.js';
 import type { BulkId } from '../types.js';
+/** Body of POST /v1/bulk. */
+export type BulkCreateRequest = operations['createBulk']['requestBody']['content']['application/json'];
+/** 202 payload of POST /v1/bulk — bulk jobs are always async. */
+export type BulkCreateResponse = operations['createBulk']['responses'][202]['content']['application/json'];
+/** 200 payload of GET /v1/bulk/{id}. */
+export type BulkGetResponse = operations['getBulk']['responses'][200]['content']['application/json'];
+/** 200 payload of DELETE /v1/bulk/{id} — cancels an in-flight job. */
+export type BulkCancelResponse = operations['deleteBulk']['responses'][200]['content']['application/json'];
+/** 200 payload of GET /v1/bulk/{id}/screenshots. */
+export type ListBulkScreenshotsResponse = operations['listBulkScreenshots']['responses'][200]['content']['application/json'];
 export declare class BulkResource {
     private readonly client;
     readonly screenshots: BulkScreenshotsResource;
-    constructor(client: RapidCrawl);
+    constructor(client: ByteKit);
     /** POST /v1/bulk — create a bulk screenshots job */
-    create(opts: Record<string, unknown>): Promise<unknown>;
+    create(opts: BulkCreateRequest): Promise<BulkCreateResponse>;
     /** GET /v1/bulk/{id} — get a bulk job status */
-    get(id: BulkId): Promise<unknown>;
+    get(id: BulkId): Promise<BulkGetResponse>;
     /** DELETE /v1/bulk/{id} — cancel an in-flight bulk job */
-    cancel(id: BulkId): Promise<unknown>;
+    cancel(id: BulkId): Promise<BulkCancelResponse>;
 }
 declare class BulkScreenshotsResource {
     private readonly client;
-    constructor(client: RapidCrawl);
+    constructor(client: ByteKit);
     /** GET /v1/bulk/{id}/screenshots — list screenshots in a bulk job */
-    list(id: BulkId): Promise<unknown>;
+    list(id: BulkId): Promise<ListBulkScreenshotsResponse>;
 }
 export {};

package/dist/resources/fetch.d.ts

@@ -1,5 +1,12 @@
-import type { RapidCrawl } from '../client.js';
+import type { ByteKit } 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,87 @@ export interface FetchOpts {
      */
     custom?: Record<string, unknown>;
 }
+/**
+ * Options accepted by `fetch.get` (GET /v1/fetch).
+ *
+ * Identical to {@link FetchOpts} minus `custom`: the spec's `GET /v1/fetch` has
+ * no `custom` query param, so it is excluded here — passing it is a compile
+ * error rather than a silently-dropped option (#2481).
+ */
+export type FetchGetOpts = Omit<FetchOpts, 'custom'>;
+/** 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-*`
+ * response headers — 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 response headers, 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.
      */
-    create(opts: FetchOpts): Promise<unknown>;
+    create(opts: FetchOpts): 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.
+     *
+     * `custom` is intentionally absent from the accepted opts: the spec's
+     * `GET /v1/fetch` has no `custom` query param and the value was never
+     * serialized, so passing it is a compile error rather than a silent drop
+     * (#2481). Use `create()` (POST) when you need to echo a `custom` payload.
      */
-    get(opts: FetchOpts): Promise<unknown>;
+    get(opts: FetchGetOpts): 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): Promise<FetchBulkCreateResponse>;
     /** GET /v1/fetch/bulk/{id} — get a bulk fetch job */
-    get(id: BulkId): Promise<unknown>;
+    get(id: BulkId): Promise<FetchBulkGetResponse>;
 }
 export {};

package/dist/resources/fetch.js

@@ -1,3 +1,23 @@
+const CACHE_STATUSES = ['hit', 'miss', 'bypass'];
+/** Build a typed {@link FetchResult} from a raw body + response headers. */
+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,17 +28,24 @@ 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.
      */
-    create(opts) {
-        return this.client.request('POST', '/v1/fetch', opts);
+    async create(opts) {
+        return toFetchResult(await this.client.requestRaw('POST', '/v1/fetch', opts));
     }
     /**
      * 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.
+     *
+     * `custom` is intentionally absent from the accepted opts: the spec's
+     * `GET /v1/fetch` has no `custom` query param and the value was never
+     * serialized, so passing it is a compile error rather than a silent drop
+     * (#2481). Use `create()` (POST) when you need to echo a `custom` payload.
      */
-    get(opts) {
+    async get(opts) {
         const params = new URLSearchParams();
         params.set('url', opts.url);
         if (opts.format !== undefined)
@@ -29,7 +56,7 @@ export class FetchResource {
             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()}`);
+        return toFetchResult(await this.client.requestRaw('GET', `/v1/fetch?${params.toString()}`));
     }
 }
 class FetchBulkResource {

package/dist/resources/monitors.d.ts

@@ -1,27 +1,66 @@
-import type { RapidCrawl } from '../client.js';
+import type { ByteKit } 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.
+ *
+ * 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 = {
+    limit?: number;
+    cursor?: string;
+    status?: string;
+};
+/** Body of POST /v1/monitors. */
+export type MonitorCreateRequest = operations['createMonitor']['requestBody']['content']['application/json'];
+/** 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): 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): Promise<ListMonitorsResponse>;
     /** GET /v1/monitors/{id} — get a monitor by ID */
-    get(id: MonitorId): Promise<unknown>;
+    get(id: MonitorId): 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): 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): 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): Promise<ListMonitorCapturesResponse>;
 }
 export {};

package/dist/resources/monitors.js

@@ -1,3 +1,4 @@
+import { toQueryString } from './query-string.js';
 export class MonitorsResource {
     client;
     captures;
@@ -12,9 +13,14 @@ export class MonitorsResource {
     create(opts) {
         return this.client.request('POST', '/v1/monitors', opts);
     }
-    /** 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) {
+        return this.client.request('GET', `/v1/monitors${toQueryString(params)}`);
     }
     /** GET /v1/monitors/{id} — get a monitor by ID */
     get(id) {
@@ -24,7 +30,14 @@ export class MonitorsResource {
     update(id, opts) {
         return this.client.request('PATCH', `/v1/monitors/${id}`, opts);
     }
-    /** DELETE /v1/monitors/{id} — delete a monitor */
+    /**
+     * 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) {
         return this.client.request('DELETE', `/v1/monitors/${id}`);
     }

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,4 +1,4 @@
-import type { RapidCrawl, RequestOptions } from '../client.js';
+import type { ByteKit, RequestOptions } from '../client.js';
 import type { operations } from '../generated/api.js';
 import type { ScrapeId, BulkId } from '../types.js';
 /**
@@ -21,7 +21,11 @@ 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';
 /** Options for POST /v1/scrape. */
 export interface ScrapeOpts {
     url: string;
@@ -41,6 +45,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 +61,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 +94,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,7 +126,7 @@ export declare class ScrapeResource {
 }
 declare class ScrapeBulkResource {
     private readonly client;
-    constructor(client: RapidCrawl);
+    constructor(client: ByteKit);
     /** POST /v1/scrape/bulk — create a bulk scrape job */
     create(opts: ScrapeBulkCreateRequest): Promise<ScrapeBulkCreateResponse>;
     /** GET /v1/scrape/bulk/{id} — get a bulk scrape job */

package/dist/resources/screenshots.d.ts

@@ -1,4 +1,4 @@
-import type { RapidCrawl } from '../client.js';
+import type { ByteKit } from '../client.js';
 import type { operations } from '../generated/api.js';
 import type { ScreenshotId } from '../types.js';
 /** The `createScreenshot` request body exactly as the OpenAPI spec declares it. */
@@ -47,9 +47,18 @@ export type ScreenshotCreateResponse = operations['createScreenshot']['responses
 export type ScreenshotGetResponse = operations['getScreenshot']['responses'][200]['content']['application/json'] | operations['getScreenshot']['responses'][202]['content']['application/json'];
 export declare class ScreenshotsResource {
     private readonly client;
-    constructor(client: RapidCrawl);
-    /** POST /v1/screenshots — capture a screenshot */
-    create(opts: ScreenshotCreateRequest): Promise<ScreenshotCreateResponse>;
+    constructor(client: ByteKit);
+    /**
+     * POST /v1/screenshots — capture a screenshot.
+     *
+     * `params.async` maps to the `?async=true` query param (queued 202 capture). It is a QUERY
+     * param on `createScreenshot`, distinct from scrape where `async` is a body field. `params` is
+     * optional and `async` omitted-when-absent: `create(opts)` with no second argument posts to the
+     * bare `/v1/screenshots` URL unchanged — existing single-arg callers are unaffected.
+     */
+    create(opts: ScreenshotCreateRequest, params?: {
+        async?: boolean;
+    }): Promise<ScreenshotCreateResponse>;
     /**
      * GET /v1/screenshots/{id} — poll a screenshot by ID.
      *

package/dist/resources/screenshots.js

@@ -3,9 +3,17 @@ export class ScreenshotsResource {
     constructor(client) {
         this.client = client;
     }
-    /** POST /v1/screenshots — capture a screenshot */
-    create(opts) {
-        return this.client.request('POST', '/v1/screenshots', opts);
+    /**
+     * POST /v1/screenshots — capture a screenshot.
+     *
+     * `params.async` maps to the `?async=true` query param (queued 202 capture). It is a QUERY
+     * param on `createScreenshot`, distinct from scrape where `async` is a body field. `params` is
+     * optional and `async` omitted-when-absent: `create(opts)` with no second argument posts to the
+     * bare `/v1/screenshots` URL unchanged — existing single-arg callers are unaffected.
+     */
+    create(opts, params) {
+        const suffix = params?.async === true ? '?async=true' : '';
+        return this.client.request('POST', `/v1/screenshots${suffix}`, opts);
     }
     /**
      * GET /v1/screenshots/{id} — poll a screenshot by ID.

package/dist/resources/search.d.ts

@@ -1,8 +1,8 @@
-import type { RapidCrawl } from '../client.js';
+import type { ByteKit } from '../client.js';
 import type { SearchOpts, SearchResponse } from '../types.js';
 export declare class SearchResource {
     private readonly client;
-    constructor(client: RapidCrawl);
+    constructor(client: ByteKit);
     /** POST /v1/search — run a web search and return ranked organic results. */
     query(opts: SearchOpts): Promise<SearchResponse>;
 }

package/dist/resources/sitemap.d.ts

@@ -1,10 +1,17 @@
-import type { RapidCrawl } from '../client.js';
+import type { ByteKit } from '../client.js';
+import type { operations } from '../generated/api.js';
 import type { SitemapId } from '../types.js';
+/** Body of POST /v1/sitemap. */
+export type SitemapCreateRequest = operations['createSitemap']['requestBody']['content']['application/json'];
+/** 202 payload of POST /v1/sitemap — sitemap crawls are always async. */
+export type SitemapCreateResponse = operations['createSitemap']['responses'][202]['content']['application/json'];
+/** 200 payload of GET /v1/sitemap/{id}. */
+export type SitemapGetResponse = operations['getSitemap']['responses'][200]['content']['application/json'];
 export declare class SitemapResource {
     private readonly client;
-    constructor(client: RapidCrawl);
+    constructor(client: ByteKit);
     /** POST /v1/sitemap — start a sitemap crawl */
-    create(opts: Record<string, unknown>): Promise<unknown>;
+    create(opts: SitemapCreateRequest): Promise<SitemapCreateResponse>;
     /** GET /v1/sitemap/{id} — get a sitemap job by ID */
-    get(id: SitemapId): Promise<unknown>;
+    get(id: SitemapId): Promise<SitemapGetResponse>;
 }

package/dist/resources/usage.d.ts

@@ -0,0 +1,31 @@
+import type { ByteKit } from '../client.js';
+import type { operations } from '../generated/api.js';
+/** 200 payload of GET /v1/usage — current billing period usage summary. */
+export type GetUsageResponse = operations['getUsage']['responses'][200]['content']['application/json'];
+/**
+ * Query params of GET /v1/usage/daily.
+ * Derived from the generated OpenAPI types so it stays in sync with the spec.
+ */
+export type GetUsageDailyParams = NonNullable<operations['getUsageDaily']['parameters']['query']>;
+/** 200 payload of GET /v1/usage/daily — per-day usage breakdown. */
+export type GetUsageDailyResponse = operations['getUsageDaily']['responses'][200]['content']['application/json'];
+/** Query params of GET /v1/usage/by-endpoint. */
+export type GetUsageByEndpointParams = NonNullable<operations['getUsageByEndpoint']['parameters']['query']>;
+/** 200 payload of GET /v1/usage/by-endpoint — per-endpoint bandwidth breakdown. */
+export type GetUsageByEndpointResponse = operations['getUsageByEndpoint']['responses'][200]['content']['application/json'];
+export declare class UsageResource {
+    private readonly client;
+    constructor(client: ByteKit);
+    /** GET /v1/usage — get current billing period usage. */
+    get(): Promise<GetUsageResponse>;
+    /**
+     * GET /v1/usage/daily — get daily usage breakdown.
+     * Default range is the last 30 days; max range is 366 days.
+     */
+    daily(params?: GetUsageDailyParams): Promise<GetUsageDailyResponse>;
+    /**
+     * GET /v1/usage/by-endpoint — get per-endpoint bandwidth breakdown.
+     * Default range is the last 30 days; max range is 366 days.
+     */
+    byEndpoint(params?: GetUsageByEndpointParams): Promise<GetUsageByEndpointResponse>;
+}

package/dist/resources/usage.js

@@ -0,0 +1,25 @@
+import { toQueryString } from './query-string.js';
+export class UsageResource {
+    client;
+    constructor(client) {
+        this.client = client;
+    }
+    /** GET /v1/usage — get current billing period usage. */
+    get() {
+        return this.client.request('GET', '/v1/usage');
+    }
+    /**
+     * GET /v1/usage/daily — get daily usage breakdown.
+     * Default range is the last 30 days; max range is 366 days.
+     */
+    daily(params) {
+        return this.client.request('GET', `/v1/usage/daily${toQueryString(params)}`);
+    }
+    /**
+     * GET /v1/usage/by-endpoint — get per-endpoint bandwidth breakdown.
+     * Default range is the last 30 days; max range is 366 days.
+     */
+    byEndpoint(params) {
+        return this.client.request('GET', `/v1/usage/by-endpoint${toQueryString(params)}`);
+    }
+}

package/dist/resources/webhooks.d.ts

@@ -0,0 +1,20 @@
+import type { ByteKit } from '../client.js';
+import type { operations } from '../generated/api.js';
+import type { WebhookDeliveryId } from '../types.js';
+/**
+ * Query params of GET /v1/webhook-deliveries.
+ * Derived from the generated OpenAPI types so it stays in sync with the spec.
+ */
+export type ListWebhookDeliveriesParams = NonNullable<operations['listWebhookDeliveries']['parameters']['query']>;
+/** 200 payload of GET /v1/webhook-deliveries. */
+export type ListWebhookDeliveriesResponse = operations['listWebhookDeliveries']['responses'][200]['content']['application/json'];
+/** 200 payload of POST /v1/webhook-deliveries/{id}/retry. */
+export type RetryWebhookDeliveryResponse = operations['retryWebhookDelivery']['responses'][200]['content']['application/json'];
+export declare class WebhooksResource {
+    private readonly client;
+    constructor(client: ByteKit);
+    /** GET /v1/webhook-deliveries — list webhook deliveries. */
+    list(params?: ListWebhookDeliveriesParams): Promise<ListWebhookDeliveriesResponse>;
+    /** POST /v1/webhook-deliveries/{id}/retry — requeue a failed or exhausted delivery. */
+    retry(id: WebhookDeliveryId): Promise<RetryWebhookDeliveryResponse>;
+}

package/dist/resources/webhooks.js

@@ -0,0 +1,15 @@
+import { toQueryString } from './query-string.js';
+export class WebhooksResource {
+    client;
+    constructor(client) {
+        this.client = client;
+    }
+    /** GET /v1/webhook-deliveries — list webhook deliveries. */
+    list(params) {
+        return this.client.request('GET', `/v1/webhook-deliveries${toQueryString(params)}`);
+    }
+    /** POST /v1/webhook-deliveries/{id}/retry — requeue a failed or exhausted delivery. */
+    retry(id) {
+        return this.client.request('POST', `/v1/webhook-deliveries/${id}/retry`);
+    }
+}

package/dist/types.d.ts

@@ -1,16 +1,16 @@
 /**
- * Prefixed-ID branded types for all RapidCrawl resource identifiers.
+ * Prefixed-ID branded types for all ByteKit resource identifiers.
  *
  * These mirror the `ss_`, `rec_`, `bulk_`, etc. prefixes used at the API
  * boundary (internal rows use raw UUIDs).
  */
 export type ScrapeId = `sc_${string}`;
 export type ScreenshotId = `ss_${string}`;
-export type RecordingId = `rec_${string}`;
 export type BulkId = `bulk_${string}`;
 export type MonitorId = `mon_${string}`;
 export type SitemapId = `sm_${string}`;
 export type ApiKeyId = `ak_${string}`;
+export type WebhookDeliveryId = `wh_${string}`;
 /** Which search index to query. `web` (default), `news`, or `images`. */
 export type SearchType = 'web' | 'news' | 'images';
 /** Recency window for search results (maps to the upstream time filter). */
@@ -66,8 +66,11 @@ export interface SearchResult {
     url: string;
     /** Short text excerpt for the result. Omitted for `images` results. */
     snippet: string;
-    /** Published date when the provider reports one, else `null`. */
-    date: string | null;
+    /**
+     * Published date when the provider reports one, else `null`. Present for
+     * `web`/`news` results; omitted entirely (`undefined`) for `images` results.
+     */
+    date?: string | null;
     /** Publisher / source name. Present for `news` and `images` results. */
     source?: string;
     /** Hosting-page domain of the result. Present only for `images` results. */

package/dist/types.js

@@ -1,5 +1,5 @@
 /**
- * Prefixed-ID branded types for all RapidCrawl resource identifiers.
+ * Prefixed-ID branded types for all ByteKit resource identifiers.
  *
  * These mirror the `ss_`, `rec_`, `bulk_`, etc. prefixes used at the API
  * boundary (internal rows use raw UUIDs).

package/package.json

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