@hunt-labs/bytekit-sdk 0.2.0 → 0.3.0

package/CHANGELOG.md

@@ -0,0 +1,142 @@
+# Changelog
+
+All notable changes to `@hunt-labs/bytekit-sdk` are documented here.
+
+The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.1.0/),
+and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
+
+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
+
+- Re-release of 0.2.1. The 0.2.1 artifacts never reached npm — the prod publish's
+  `publish-sdk` step failed on a CI test-isolation flake (`cjs-require.test.ts`
+  rebuilding the shared `dist`), which is now fixed. No consumer-facing changes
+  beyond 0.2.1.
+
+## [0.2.1] - 2026-07-16
+
+### Changed
+
+- Primary exports renamed `RapidCrawl`→`ByteKit`, `RapidCrawlError`→`ByteKitError`,
+  `RapidCrawlOptions`→`ByteKitOptions`. The old names remain as deprecated,
+  identity-preserving aliases (`RapidCrawl === ByteKit`), so existing imports keep
+  working. (#2421)
+
+### Fixed
+
+- `request()` now returns `undefined` on `204 No Content` / empty-body responses
+  instead of throwing a JSON-parse error — `account.apiKeys.revoke()` now resolves
+  as its `Promise<void>` contract declares. (#2450)
+
+### Removed
+
+- `client.recordings` (the `/v1/recordings` endpoint is permanently `410`
+  deactivated). (#2421)
+
+## [0.2.0] - 2026-07-15
+
+This is a breaking release. Four runtime behavior changes affect code written
+against 0.1.0 — read each one before upgrading.
+
+### Changed (breaking)
+
+- **Default client-side timeout (120s).** Requests now abort after 120000 ms by
+  default (`DEFAULT_TIMEOUT_MS` in `src/client.ts`); 0.1.0 had no client-side
+  timeout and would hang indefinitely. A slow request now rejects with
+  `RapidCrawlConnectionError` carrying `code: 'timeout'`. Override per client via
+  `new RapidCrawl({ apiKey, timeoutMs })`.
+- **Network failures throw `RapidCrawlConnectionError`.** Every `fetch()` rejection
+  is now wrapped by `toConnectionError()` and re-thrown as `RapidCrawlConnectionError`.
+  0.1.0 surfaced undici's bare `TypeError: fetch failed`. Code that matched on a bare
+  `TypeError` to detect a network failure will no longer match — catch
+  `RapidCrawlConnectionError` instead.
+- **Constructor throws on an empty `apiKey`.** `new RapidCrawl({ apiKey: '' })` (or a
+  missing key) now throws a `TypeError` immediately instead of silently sending
+  `Authorization: Bearer undefined`. Ensure `apiKey` is populated (e.g. from
+  `process.env.BYTEKIT_API_KEY`) before constructing the client.
+- **Request-body types narrowed to the OpenAPI schema.** Request payloads are now
+  typed from spec-derived types generated from the OpenAPI schema
+  (`src/generated/api.d.ts`) rather than `Record<string, unknown>`. Payloads that
+  previously compiled by virtue of the loose index type may now be rejected by the
+  type checker; align them with the documented request shape.
+
+### Changed
+
+- Package renamed to `@hunt-labs/bytekit-sdk` (the `@bytekit` npm scope was
+  unobtainable). The prior `rapidcrawl`/`@rapidcrawl/sdk` name remains installable at
+  its last version but is deprecated.
+- Generated API types (`dist/generated/api.d.ts`) are now shipped in the tarball so
+  consumers get the typed request/response surface without regenerating from the spec.
+
+### Added
+
+- Publish-ready packaging metadata: types-first `exports`, `engines`, `keywords`,
+  `homepage`, `bugs`, `README.md`, `LICENSE`, and an MIT `license` field.
+
+## [0.1.0] - 2026
+
+### Added
+
+- Initial release of the ByteKit TypeScript SDK — a typed client for the ByteKit API
+  (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
+[0.1.0]: https://github.com/Hunt-Labs-Inc/ByteKit/tree/main/packages/sdk-typescript

package/README.md

@@ -10,11 +10,14 @@ screenshots, sitemaps, page monitors, and web search.
 npm install @hunt-labs/bytekit-sdk
 ```
 
-> **ESM-only.** This package ships as ESM (`"type": "module"`) and has no
-> CommonJS build. Use it from an ESM project (`"type": "module"` in your
-> `package.json`, or a `.mjs` entrypoint), or load it from CommonJS with a
-> dynamic `await import('@hunt-labs/bytekit-sdk')`. A top-level
-> `require('@hunt-labs/bytekit-sdk')` will not work.
+> **ESM-only.** This package ships a single ESM build (`"type": "module"`) with
+> no separate CommonJS bundle. Use it from an ESM project (`"type": "module"` in
+> your `package.json`, or a `.mjs` entrypoint). From CommonJS you can either load
+> it with a dynamic `await import('@hunt-labs/bytekit-sdk')`, or — on **Node
+> ≥20.19 / ≥22.12**, which resolve `require()` of ESM — call a top-level
+> `require('@hunt-labs/bytekit-sdk')` directly (the package's `exports` map
+> carries a `default` condition for exactly this). On older Node, a top-level
+> `require()` throws `ERR_REQUIRE_ESM`; use the dynamic `import()` there.
 
 Requires Node.js 18+ (the client uses the global `fetch`).
 
@@ -24,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
 
@@ -41,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
 });
@@ -66,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
@@ -121,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();
@@ -131,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');
 ```
 
@@ -140,23 +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');
 ```
 
-> `client.recordings.*` targets the `/v1/recordings` endpoints, which are
-> deactivated server-side and return HTTP 410.
+> **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

@@ -1,13 +1,14 @@
 import { ScrapeResource } from './resources/scrape.js';
 import { ScreenshotsResource } from './resources/screenshots.js';
-import { RecordingsResource } from './resources/recordings.js';
 import { BulkResource } from './resources/bulk.js';
 import { FetchResource } from './resources/fetch.js';
 import { MonitorsResource } from './resources/monitors.js';
 import { SitemapResource } from './resources/sitemap.js';
 import { SearchResource } from './resources/search.js';
 import { AccountResource } from './resources/account.js';
-export interface RapidCrawlOptions {
+import { UsageResource } from './resources/usage.js';
+import { WebhooksResource } from './resources/webhooks.js';
+export interface ByteKitOptions {
     apiKey: string;
     baseUrl?: string;
     /**
@@ -42,38 +43,39 @@ export interface RequestOptions {
 /** Why a request never produced an HTTP response. */
 export type ConnectionErrorCode = 'timeout' | 'aborted' | 'connection';
 /** Thrown when the API responds with a 4xx or 5xx status code. */
-export declare class RapidCrawlError extends Error {
+export declare class ByteKitError extends Error {
     readonly status: number;
     readonly code: string;
     constructor(status: number, code: string, message: string);
 }
 /**
  * Thrown when the request never produced an HTTP response at all — DNS, socket, TLS,
- * a client-side timeout, or a caller-initiated abort. Distinct from `RapidCrawlError`,
+ * a client-side timeout, or a caller-initiated abort. Distinct from `ByteKitError`,
  * which always carries a real HTTP status: catch both to cover every failure.
  *
  * The original failure is preserved on `.cause`.
  */
-export declare class RapidCrawlConnectionError extends Error {
+export declare class ByteKitConnectionError extends Error {
     readonly code: ConnectionErrorCode;
     constructor(code: ConnectionErrorCode, message: string, options?: {
         cause?: unknown;
     });
 }
-export declare class RapidCrawl {
+export declare class ByteKit {
     private readonly apiKey;
     private readonly baseUrl;
     private readonly defaultTimeoutMs;
     readonly scrape: ScrapeResource;
     readonly screenshots: ScreenshotsResource;
-    readonly recordings: RecordingsResource;
     readonly bulk: BulkResource;
     readonly fetch: FetchResource;
     readonly monitors: MonitorsResource;
     readonly sitemap: SitemapResource;
     readonly search: SearchResource;
     readonly account: AccountResource;
-    constructor(options: RapidCrawlOptions);
+    readonly usage: UsageResource;
+    readonly webhooks: WebhooksResource;
+    constructor(options: ByteKitOptions);
     /**
      * Resolve the abort budget for one request from the caller's options and the
      * constructor default. Precedence:
@@ -89,11 +91,48 @@ export declare class RapidCrawl {
      */
     private resolveSignal;
     /**
-     * Make an authenticated JSON request to the RapidCrawl API.
+     * Perform the authenticated round-trip and return the raw `Response`, having
+     * already thrown for the two non-body failure modes:
      *
-     * Throws `RapidCrawlError` on 4xx/5xx responses, and `RapidCrawlConnectionError`
+     * - `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.
+     *
+     * 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).
      */
     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;
+    }>;
 }

package/dist/client.js

@@ -1,12 +1,13 @@
 import { ScrapeResource } from './resources/scrape.js';
 import { ScreenshotsResource } from './resources/screenshots.js';
-import { RecordingsResource } from './resources/recordings.js';
 import { BulkResource } from './resources/bulk.js';
 import { FetchResource } from './resources/fetch.js';
 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).
@@ -17,28 +18,28 @@ const DEFAULT_BASE_URL = 'https://api.bytekit.com';
  */
 const DEFAULT_TIMEOUT_MS = 120_000;
 /** Thrown when the API responds with a 4xx or 5xx status code. */
-export class RapidCrawlError extends Error {
+export class ByteKitError extends Error {
     status;
     code;
     constructor(status, code, message) {
         super(message);
-        this.name = 'RapidCrawlError';
+        this.name = 'ByteKitError';
         this.status = status;
         this.code = code;
     }
 }
 /**
  * Thrown when the request never produced an HTTP response at all — DNS, socket, TLS,
- * a client-side timeout, or a caller-initiated abort. Distinct from `RapidCrawlError`,
+ * a client-side timeout, or a caller-initiated abort. Distinct from `ByteKitError`,
  * which always carries a real HTTP status: catch both to cover every failure.
  *
  * The original failure is preserved on `.cause`.
  */
-export class RapidCrawlConnectionError extends Error {
+export class ByteKitConnectionError extends Error {
     code;
     constructor(code, message, options) {
         super(message, options);
-        this.name = 'RapidCrawlConnectionError';
+        this.name = 'ByteKitConnectionError';
         this.code = code;
     }
 }
@@ -52,7 +53,7 @@ function validateTimeout(value, optionName) {
     if (value === undefined)
         return undefined;
     if (typeof value !== 'number' || !Number.isFinite(value) || value < 0) {
-        throw new TypeError(`RapidCrawl: ${optionName} must be a non-negative finite number (got ${describe(value)})`);
+        throw new TypeError(`ByteKit: ${optionName} must be a non-negative finite number (got ${describe(value)})`);
     }
     return value;
 }
@@ -69,7 +70,7 @@ function describe(value) {
 }
 /** The abort reason used by the `setTimeout` fallback; named so it maps to `code: 'timeout'`. */
 function timeoutReason(ms) {
-    const reason = new Error(`RapidCrawl: request timed out after ${ms}ms`);
+    const reason = new Error(`ByteKit: request timed out after ${ms}ms`);
     reason.name = 'TimeoutError';
     return reason;
 }
@@ -147,39 +148,45 @@ function toConnectionError(err, method, url, timeoutSignal) {
         : code === 'aborted'
             ? 'request aborted by the caller'
             : 'connection failed before a response was received';
-    return new RapidCrawlConnectionError(code, `RapidCrawl: ${method} ${url} — ${detail}`, {
+    return new ByteKitConnectionError(code, `ByteKit: ${method} ${url} — ${detail}`, {
         cause: err,
     });
 }
-export class RapidCrawl {
+export class ByteKit {
     apiKey;
     baseUrl;
     defaultTimeoutMs;
     scrape;
     screenshots;
-    recordings;
     bulk;
     fetch;
     monitors;
     sitemap;
     search;
     account;
+    usage;
+    webhooks;
     constructor(options) {
         if (!options?.apiKey) {
-            throw new TypeError('RapidCrawl: `apiKey` is required — got an empty value. Pass options.apiKey (e.g. from process.env.BYTEKIT_API_KEY).');
+            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);
-        this.recordings = new RecordingsResource(this);
         this.bulk = new BulkResource(this);
         this.fetch = new FetchResource(this);
         this.monitors = new MonitorsResource(this);
         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
@@ -218,13 +225,19 @@ export class RapidCrawl {
         };
     }
     /**
-     * Make an authenticated JSON request to the RapidCrawl API.
+     * Perform the authenticated round-trip and return the raw `Response`, having
+     * already thrown for the two non-body failure modes:
      *
-     * Throws `RapidCrawlError` on 4xx/5xx responses, and `RapidCrawlConnectionError`
-     * 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 = {
@@ -264,8 +277,55 @@ export class RapidCrawl {
             catch {
                 // leave defaults
             }
-            throw new RapidCrawlError(response.status, code, message);
+            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)
+        // used to throw instead of resolving. Read the body once as text and short-circuit
+        // to `undefined` when it is empty; a JSON-bearing response (scrape.create,
+        // apiKeys.create/get, …) still parses and returns unchanged.
+        if (response.status === 204) {
+            return undefined;
         }
-        return response.json();
+        const text = await response.text();
+        if (text.trim().length === 0) {
+            return undefined;
+        }
+        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 };
     }
 }

package/dist/index.d.ts

@@ -1,8 +1,14 @@
-export { RapidCrawl, RapidCrawlError, RapidCrawlConnectionError } from './client.js';
-export type { RapidCrawlOptions, RequestOptions, ConnectionErrorCode } from './client.js';
+export { ByteKit, ByteKitError, ByteKitConnectionError } from './client.js';
+export type { ByteKitOptions, RequestOptions, ConnectionErrorCode } 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,2 +1,2 @@
-export { RapidCrawl, RapidCrawlError, RapidCrawlConnectionError } from './client.js';
+export { ByteKit, ByteKitError, ByteKitConnectionError } from './client.js';
 export { V01_METHODS } from './allowlist.js';