@hunt-labs/bytekit-sdk 0.1.0 → 0.2.2

package/dist/client.js

@@ -1,6 +1,5 @@
 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';
@@ -8,23 +7,155 @@ import { SitemapResource } from './resources/sitemap.js';
 import { SearchResource } from './resources/search.js';
 import { AccountResource } from './resources/account.js';
 const DEFAULT_BASE_URL = 'https://api.bytekit.com';
+/**
+ * Default client-side request timeout (2 minutes).
+ *
+ * Above the slowest expected synchronous scrape, and well below undici's ~5-minute
+ * headers timeout, so the SDK is always the tighter bound and a hung upstream can
+ * never hang the caller indefinitely.
+ */
+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;
     }
 }
-export 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 class ByteKitConnectionError extends Error {
+    code;
+    constructor(code, message, options) {
+        super(message, options);
+        this.name = 'ByteKitConnectionError';
+        this.code = code;
+    }
+}
+const NOOP = () => { };
+/**
+ * Validate a timeout option. `undefined` passes through; anything that is not a
+ * non-negative finite number throws a `TypeError` naming the option as the caller
+ * spelled it (`"timeoutMs"` at the constructor, `"requestTimeoutMs"` per call).
+ */
+function validateTimeout(value, optionName) {
+    if (value === undefined)
+        return undefined;
+    if (typeof value !== 'number' || !Number.isFinite(value) || value < 0) {
+        throw new TypeError(`ByteKit: ${optionName} must be a non-negative finite number (got ${describe(value)})`);
+    }
+    return value;
+}
+/** Render a rejected option value for an error message without ever stringifying an object. */
+function describe(value) {
+    if (typeof value === 'number' || typeof value === 'boolean' || typeof value === 'bigint') {
+        return String(value);
+    }
+    if (typeof value === 'string')
+        return JSON.stringify(value);
+    if (value === null)
+        return 'null';
+    return typeof value;
+}
+/** The abort reason used by the `setTimeout` fallback; named so it maps to `code: 'timeout'`. */
+function timeoutReason(ms) {
+    const reason = new Error(`ByteKit: request timed out after ${ms}ms`);
+    reason.name = 'TimeoutError';
+    return reason;
+}
+/** `AbortSignal.timeout(ms)` where available, else an `AbortController` + `setTimeout`. */
+function createTimeoutSignal(ms) {
+    if (typeof AbortSignal.timeout === 'function') {
+        return { signal: AbortSignal.timeout(ms), cleanup: NOOP };
+    }
+    const controller = new AbortController();
+    const timer = setTimeout(() => controller.abort(timeoutReason(ms)), ms);
+    timer.unref?.();
+    return {
+        signal: controller.signal,
+        cleanup: () => clearTimeout(timer),
+    };
+}
+/**
+ * Abort on whichever source fires first.
+ *
+ * Prefers `AbortSignal.any`, whose sources hold only WEAK references to the composed
+ * signal — so nothing has to be (and nothing must be) retained to keep it collectable.
+ * The manual fallback is the path that has to clean up after itself: it attaches a real
+ * listener to the CALLER's signal, which typically outlives the request (one long-lived
+ * `AbortController` reused across many calls), so `cleanup()` removes it again.
+ */
+function composeSignals(caller, timeout) {
+    const anyFn = AbortSignal.any?.bind(AbortSignal);
+    if (typeof anyFn === 'function') {
+        return { signal: anyFn([caller, timeout]), cleanup: NOOP };
+    }
+    const controller = new AbortController();
+    const sources = [caller, timeout];
+    const onAbort = (event) => {
+        controller.abort(event.target.reason);
+    };
+    let done = false;
+    const cleanup = () => {
+        if (done)
+            return;
+        done = true;
+        for (const source of sources)
+            source.removeEventListener('abort', onAbort);
+    };
+    for (const source of sources)
+        source.addEventListener('abort', onAbort);
+    for (const source of sources) {
+        if (source.aborted) {
+            controller.abort(source.reason);
+            break;
+        }
+    }
+    return { signal: controller.signal, cleanup };
+}
+/** Map a `fetch` rejection onto the connection-error taxonomy. Never leaks the API key. */
+function toConnectionError(err, method, url, timeoutSignal) {
+    // undici rejects an aborted fetch with the signal's own reason, so the thrown value's
+    // `name` is the primary discriminator (`TimeoutError` / `AbortError`).
+    const rawName = typeof err === 'object' && err !== null && 'name' in err ? err.name : undefined;
+    const name = typeof rawName === 'string' ? rawName : '';
+    let code;
+    if (name === 'TimeoutError') {
+        code = 'timeout';
+    }
+    else if (name === 'AbortError') {
+        code = 'aborted';
+    }
+    else if (timeoutSignal?.aborted === true) {
+        code = 'timeout';
+    }
+    else {
+        code = 'connection';
+    }
+    const detail = code === 'timeout'
+        ? 'request timed out'
+        : code === 'aborted'
+            ? 'request aborted by the caller'
+            : 'connection failed before a response was received';
+    return new ByteKitConnectionError(code, `ByteKit: ${method} ${url} — ${detail}`, {
+        cause: err,
+    });
+}
+export class ByteKit {
     apiKey;
     baseUrl;
+    defaultTimeoutMs;
     scrape;
     screenshots;
-    recordings;
     bulk;
     fetch;
     monitors;
@@ -32,11 +163,14 @@ export class RapidCrawl {
     search;
     account;
     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;
+        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);
@@ -45,12 +179,51 @@ export class RapidCrawl {
         this.account = new AccountResource(this);
     }
     /**
-     * Make an authenticated JSON request to the RapidCrawl API.
+     * 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".
+     */
+    resolveSignal(options) {
+        const callerSignal = options?.signal;
+        const perCallMs = validateTimeout(options?.requestTimeoutMs, '"requestTimeoutMs"');
+        // A caller-supplied signal suppresses the constructor default (it does not
+        // suppress an explicit per-call budget, which composes with it instead).
+        const effectiveMs = perCallMs ?? (callerSignal !== undefined ? 0 : this.defaultTimeoutMs);
+        if (effectiveMs === 0) {
+            return { signal: callerSignal, timeoutSignal: undefined, cleanup: NOOP };
+        }
+        const timeout = createTimeoutSignal(effectiveMs);
+        if (callerSignal === undefined) {
+            return { signal: timeout.signal, timeoutSignal: timeout.signal, cleanup: timeout.cleanup };
+        }
+        const composed = composeSignals(callerSignal, timeout.signal);
+        return {
+            signal: composed.signal,
+            timeoutSignal: timeout.signal,
+            cleanup: () => {
+                composed.cleanup();
+                timeout.cleanup();
+            },
+        };
+    }
+    /**
+     * 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).
      */
-    async request(method, path, body) {
+    async request(method, path, body, options) {
         const url = `${this.baseUrl}${path}`;
+        const { signal, timeoutSignal, cleanup } = this.resolveSignal(options);
         const init = {
             method,
             headers: {
@@ -61,7 +234,22 @@ export class RapidCrawl {
         if (body !== undefined) {
             init.body = JSON.stringify(body);
         }
-        const response = await fetch(url, init);
+        // `exactOptionalPropertyTypes` — assign only when we actually have a signal.
+        if (signal !== undefined) {
+            init.signal = signal;
+        }
+        let response;
+        try {
+            response = await fetch(url, init);
+        }
+        catch (err) {
+            throw toConnectionError(err, method, url, timeoutSignal);
+        }
+        finally {
+            // Runs on success, on HTTP error, and on abort alike — no dangling timer,
+            // no listener left behind on the caller's (long-lived) signal.
+            cleanup();
+        }
         if (!response.ok) {
             let code = 'internal_error';
             let message = response.statusText;
@@ -73,9 +261,32 @@ export class RapidCrawl {
             catch {
                 // leave defaults
             }
-            throw new RapidCrawlError(response.status, code, message);
+            throw new ByteKitError(response.status, code, message);
+        }
+        // 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;
+        }
+        const text = await response.text();
+        if (text.trim().length === 0) {
+            return undefined;
         }
-        return response.json();
+        return JSON.parse(text);
     }
 }
-//# sourceMappingURL=client.js.map
+// ---------------------------------------------------------------------------
+// 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, };