@hunt-labs/bytekit-sdk 0.1.0 → 0.2.2

package/CHANGELOG.md

@@ -0,0 +1,91 @@
+# 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.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.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/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Hunt Labs, Inc.
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,171 @@
+# @hunt-labs/bytekit-sdk
+
+Official TypeScript SDK for the [ByteKit](https://bytekit.com) API — web data
+infrastructure for AI agents and training pipelines: scraping, raw fetch,
+screenshots, sitemaps, page monitors, and web search.
+
+## Install
+
+```bash
+npm install @hunt-labs/bytekit-sdk
+```
+
+> **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`).
+
+## Authentication
+
+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';
+
+const client = new RapidCrawl({ 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.
+
+## Base-URL override
+
+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({
+  apiKey: process.env.BYTEKIT_API_KEY!,
+  baseUrl: 'https://api-stg.bytekit.com', // default: https://api.bytekit.com
+});
+```
+
+## Usage
+
+### Scrape a page
+
+```ts
+const result = await client.scrape.create({
+  url: 'https://example.com',
+  formats: ['markdown', 'html'],
+});
+```
+
+### Fetch an async scrape by id
+
+```ts
+const scrape = await client.scrape.get('sc_123abc');
+```
+
+### Raw fetch (unprocessed response body)
+
+```ts
+const raw = await client.fetch.create({ url: 'https://example.com' });
+```
+
+### Web search
+
+```ts
+const results = await client.search.query({ query: 'ai web scraping', limit: 10 });
+for (const hit of results.results) {
+  console.log(hit.position, hit.title, hit.url);
+}
+```
+
+### Screenshot a page
+
+```ts
+const shot = await client.screenshots.create({
+  url: 'https://example.com',
+  full_page: true,
+});
+const ready = await client.screenshots.get('ss_123abc');
+```
+
+### Bulk jobs
+
+`scrape` and `fetch` each expose a `bulk` sub-resource that takes a URL list
+and a webhook to notify on completion:
+
+```ts
+const job = await client.scrape.bulk.create({
+  urls: ['https://example.com', 'https://example.org'],
+  webhook_url: 'https://your.app/hooks/bytekit',
+});
+const status = await client.scrape.bulk.get('bulk_123abc');
+```
+
+`client.fetch.bulk.create()` / `client.fetch.bulk.get()` follow the same shape.
+
+Bulk **screenshots** are not a `screenshots.bulk` sub-resource — they go
+through the separate top-level `client.bulk` resource instead:
+
+```ts
+const shots = await client.bulk.create({
+  urls: ['https://example.com', 'https://example.org'],
+  webhook_url: 'https://your.app/hooks/bytekit',
+});
+const shotStatus = await client.bulk.get('bulk_123abc');
+await client.bulk.screenshots.list('bulk_123abc');
+```
+
+### Page monitors
+
+```ts
+const monitor = await client.monitors.create({
+  url: 'https://example.com/pricing',
+  interval_type: 'daily',
+  webhook_url: 'https://your.app/hooks/bytekit',
+});
+await client.monitors.list();
+await client.monitors.delete('mon_123abc');
+```
+
+### Sitemap crawl
+
+```ts
+const crawl = await client.sitemap.create({ url: 'https://example.com' });
+const sitemap = await client.sitemap.get('sm_123abc');
+```
+
+### Account, usage, and API keys
+
+```ts
+const account = await client.account.get();
+const keys = await client.account.apiKeys.list();
+```
+
+## Error handling
+
+Any 4xx/5xx response throws a `RapidCrawlError` carrying the HTTP status and
+the API's error code:
+
+```ts
+import { RapidCrawl, RapidCrawlError } from '@hunt-labs/bytekit-sdk';
+
+try {
+  await client.scrape.create({ url: 'https://example.com' });
+} catch (err) {
+  if (err instanceof RapidCrawlError) {
+    console.error(err.status, err.code, err.message);
+  }
+}
+```
+
+## Documentation
+
+Full API reference: [bytekit.com/docs](https://bytekit.com/docs).
+
+## License
+
+MIT — see [LICENSE](./LICENSE).

package/dist/allowlist.d.ts

@@ -10,4 +10,3 @@
  */
 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 type V01Method = (typeof V01_METHODS)[number];
-//# sourceMappingURL=allowlist.d.ts.map

package/dist/allowlist.js

@@ -35,4 +35,3 @@ export const V01_METHODS = [
     'search.query',
     'account.get',
 ];
-//# sourceMappingURL=allowlist.js.map

package/dist/client.d.ts

@@ -1,40 +1,99 @@
 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 {
+export interface ByteKitOptions {
     apiKey: string;
     baseUrl?: string;
+    /**
+     * Default CLIENT-SIDE request timeout in ms — the abort budget for the whole HTTP
+     * round-trip made by this SDK. `0` disables the SDK-side timeout. Default 120000.
+     *
+     * NOT the same thing as `ScrapeOpts.timeout_ms`, which is the SERVER-side budget the
+     * gateway applies to the scrape itself. Override per call with
+     * `RequestOptions.requestTimeoutMs`.
+     */
+    timeoutMs?: number;
+}
+/** Per-call overrides accepted by `request()` and by resource methods that opt in. */
+export interface RequestOptions {
+    /**
+     * Caller-owned abort signal. When supplied WITHOUT a per-call `requestTimeoutMs`, it
+     * fully replaces the constructor timeout — supply `requestTimeoutMs` alongside it to
+     * keep a bound (the request then aborts on whichever fires first).
+     */
+    signal?: AbortSignal;
+    /**
+     * Per-call CLIENT-SIDE abort budget in ms. Wins over the constructor's `timeoutMs`.
+     * `0` disables the SDK-side timeout for this call.
+     *
+     * Deliberately NOT named `timeoutMs`: it rides on the same call as `ScrapeOpts.timeout_ms`
+     * (the SERVER-side scrape budget), and the two mean different things —
+     * `scrape.create({ timeout_ms: 30_000 }, { requestTimeoutMs: 5_000 })` says "let the
+     * server spend up to 30 s scraping, but give up on the wire after 5 s".
+     */
+    requestTimeoutMs?: number;
 }
+/** 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);
 }
-export declare class RapidCrawl {
+/**
+ * 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 `ByteKitError`,
+ * which always carries a real HTTP status: catch both to cover every failure.
+ *
+ * The original failure is preserved on `.cause`.
+ */
+export declare class ByteKitConnectionError extends Error {
+    readonly code: ConnectionErrorCode;
+    constructor(code: ConnectionErrorCode, message: string, options?: {
+        cause?: unknown;
+    });
+}
+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);
+    constructor(options: ByteKitOptions);
+    /**
+     * Resolve the abort budget for one request from the caller's options and the
+     * constructor default. Precedence:
+     *
+     * | caller `signal` | per-call `requestTimeoutMs` | signal attached to `fetch`            |
+     * |-----------------|----------------------------|---------------------------------------|
+     * | absent          | absent                     | timeout from the constructor default   |
+     * | absent          | present                    | timeout from the per-call value        |
+     * | present         | absent                     | the caller's signal, verbatim          |
+     * | present         | present                    | composition — aborts on either         |
+     *
+     * A timeout of `0` (either level) means "no SDK-side timeout".
+     */
+    private resolveSignal;
     /**
-     * Make an authenticated JSON request to the RapidCrawl API.
+     * Make an authenticated JSON request to the ByteKit API.
      *
-     * Throws `RapidCrawlError` on 4xx/5xx responses.
+     * 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): Promise<T>;
+    request<T>(method: string, path: string, body?: unknown, options?: RequestOptions): Promise<T>;
 }
-//# sourceMappingURL=client.d.ts.map
+export { ByteKit as RapidCrawl, ByteKitError as RapidCrawlError, ByteKitConnectionError as RapidCrawlConnectionError, };
+export type { ByteKitOptions as RapidCrawlOptions };