@crawlbrulee/sdk 0.1.5 → 0.3.0

package/dist/index.d.cts

@@ -255,6 +255,40 @@ interface ScrapeRequest {
     /** Optional locale + country emulation. */
     location?: ScrapeLocation;
 }
+/**
+ * Per-job completion webhook, attached when submitting an ASYNC scrape via
+ * {@link Crawlbrulee.scrapeAsync}. Async-only: the synchronous `scrape()`
+ * response IS the notification, so {@link ScrapeRequest} deliberately omits
+ * this field and the sync `/api/scrape` endpoint rejects it.
+ *
+ * Configure the signing secret used for deliveries in the dashboard
+ * (Account → Webhooks) — there is no per-request secret.
+ */
+interface AsyncScrapeWebhook {
+    /**
+     * Endpoint that receives a single signed `POST` when the job reaches a
+     * terminal state. Must be an `http`/`https` URL (HTTPS is required in
+     * production) of at most 2048 characters. The body is a
+     * `scrape.complete` envelope signed with your organization webhook secret
+     * on the `X-Cwbl-Signature` header — verify it with `verifyWebhookSignature`.
+     */
+    url: string;
+    /**
+     * Opaque correlation object echoed verbatim in the webhook payload's
+     * `data.metadata`. Must serialize to at most 2048 bytes (UTF-8 JSON). Use it
+     * to route deliveries without keeping your own `job_id` mapping.
+     */
+    metadata?: Record<string, unknown>;
+}
+/**
+ * Request body for `POST /api/scrape/async`: a {@link ScrapeRequest} plus an
+ * optional per-job completion {@link AsyncScrapeWebhook}. The `webhook` field
+ * is async-only and is not accepted by the synchronous `scrape()` endpoint.
+ */
+interface AsyncScrapeRequest extends ScrapeRequest {
+    /** Optional completion webhook delivered when this job finishes. */
+    webhook?: AsyncScrapeWebhook;
+}
 /** Viewport metadata returned alongside a captured screenshot. */
 interface ScreenshotViewportInfo {
     width: number;
@@ -524,6 +558,54 @@ interface WhoamiResponse {
     token_preview: string;
 }
 
+/**
+ * Async scrape completion webhooks.
+ *
+ * When you submit a job with {@link Crawlbrulee.scrapeAsync} the API can deliver
+ * a `scrape.complete` webhook to your configured endpoint once the job reaches a
+ * terminal state. The envelope on the wire is exactly:
+ *
+ * ```json
+ * {
+ *   "event_id": "evt_…",
+ *   "timestamp": "2026-06-13T12:00:00.000Z",
+ *   "event": "scrape.complete",
+ *   "data": { "job_id": "job_…", "status": "success", "url": "https://…", "completed_at": "…" }
+ * }
+ * ```
+ */
+/** Terminal status carried by a {@link ScrapeCompleteWebhook}. */
+type ScrapeWebhookStatus = 'success' | 'failed' | 'cancelled';
+/** `data` block of a {@link ScrapeCompleteWebhook}. */
+interface ScrapeCompleteWebhookData {
+    /** The async job identifier — pass it to `getScrapeResult`. */
+    job_id: string;
+    /** Terminal state of the job. */
+    status: ScrapeWebhookStatus;
+    /** The URL that was scraped. */
+    url: string;
+    /** ISO-8601 UTC timestamp when the job reached its terminal state. */
+    completed_at: string;
+    /** Failure message — present only when `status === 'failed'`. */
+    error?: string;
+    /** Correlation data echoed back from the original scrape request, if any. */
+    metadata?: Record<string, unknown>;
+}
+/**
+ * Webhook envelope delivered when an async scrape job completes. The `event`
+ * discriminator is always the literal `'scrape.complete'`.
+ */
+interface ScrapeCompleteWebhook {
+    /** Unique event identifier — also delivered in the `X-Cwbl-Event-Id` header. */
+    event_id: string;
+    /** ISO-8601 UTC timestamp when the event was emitted. */
+    timestamp: string;
+    /** Event type discriminator. */
+    event: 'scrape.complete';
+    /** Event payload. */
+    data: ScrapeCompleteWebhookData;
+}
+
 /** Options accepted by the {@link Crawlbrulee} constructor. */
 interface CrawlbruleeOptions {
     /**
@@ -617,8 +699,12 @@ declare class Crawlbrulee {
      * Submit an asynchronous scrape job and return its `job_id`. Poll the job
      * with {@link Crawlbrulee.getScrapeStatus} or wait for completion with
      * {@link Crawlbrulee.waitForScrape}.
+     *
+     * Pass an optional `webhook` to have the API deliver a signed
+     * `scrape.complete` `POST` to your endpoint when the job finishes (see
+     * {@link AsyncScrapeWebhook}). This field is async-only.
      */
-    scrapeAsync(request: ScrapeRequest, options?: RequestOptions): Promise<AsyncScrapeResponse>;
+    scrapeAsync(request: AsyncScrapeRequest, options?: RequestOptions): Promise<AsyncScrapeResponse>;
     /** Look up the current status of an async scrape job. */
     getScrapeStatus(jobId: string, options?: RequestOptions): Promise<AsyncJobStatusResponse>;
     /**
@@ -627,6 +713,25 @@ declare class Crawlbrulee {
      * first, or use {@link Crawlbrulee.waitForScrape} to poll-then-fetch.
      */
     getScrapeResult(jobId: string, options?: RequestOptions): Promise<ScrapeResponse>;
+    /**
+     * Fetch the scrape result referenced by a `scrape.complete` webhook body.
+     *
+     * Always verify the webhook signature with `verifyWebhookSignature` before
+     * acting on it; this method trusts the parsed body it is handed.
+     *
+     * Behavior by `data.status`:
+     * - `success` — delegates to {@link Crawlbrulee.getScrapeResult} for the
+     *   webhook's `job_id` and returns the parsed result.
+     * - `failed` — throws a {@link CrawlbruleeError} carrying `data.error`
+     *   (`errorName: 'job_failed'`); there is no result to fetch.
+     * - `cancelled` — throws a {@link CrawlbruleeError}
+     *   (`errorName: 'client_closed_request'`).
+     *
+     * A non-`scrape.complete` envelope throws a {@link CrawlbruleeError}
+     * defensively. Any HTTP error from the underlying fetch propagates as the
+     * usual typed `CrawlbruleeError` subclass.
+     */
+    fetchScrapeResultFromWebhook(webhook: ScrapeCompleteWebhook, options?: RequestOptions): Promise<ScrapeResponse>;
     /**
      * Poll an async scrape job until it reaches a terminal state, then return
      * the scrape result.
@@ -782,4 +887,96 @@ declare const DEFAULT_REQUEST_TIMEOUT_MS = 60000;
 /** Environment variable read by `Crawlbrulee.fromEnv()` to source the API key. */
 declare const ENV_API_KEY = "CRAWLBRULEE_API_KEY";
 
-export { type ApiErrorDetails, type ApiErrorName, type ApiErrorResponse, type AsyncJobStatus, type AsyncJobStatusResponse, type AsyncScrapeResponse, AuthenticationError, Crawlbrulee, CrawlbruleeError, type CrawlbruleeOptions, DEFAULT_BASE_URL, DEFAULT_REQUEST_TIMEOUT_MS, ENV_API_KEY, type HttpMethod, type MapCache, type MapLinkItem, type MapLocation, type MapPagination, type MapRequest, type MapResponse, type MapTruncation, type MapTypes, NotFoundError, type PageInlineImage, type PageLink, type ProxyTier, RateLimitError, type RateLimitErrorDetails, type RequestOptions, type ScrapeCache, type ScrapeExtract, type ScrapeLocation, type ScrapeMetadata, type ScrapeRequest, type ScrapeResponse, type ScreenshotAfterAction, type ScreenshotBeforeAction, type ScreenshotCleanup, type ScreenshotDeviceMode, type ScreenshotProperties, type ScreenshotRequest, type ScreenshotResult, type ScreenshotScrollAction, type ScreenshotSlice, type ScreenshotSliceAction, type ScreenshotType, type ScreenshotViewport, type ScreenshotViewportInfo, type ScreenshotWaitAction, TransportError, UsageAllocationError, type UsageAllocationErrorDetails, type UsageAllocationReason, type UsageLimitDetails, type UsageResponse, ValidationError, type WaitForScrapeOptions, type WhoamiResponse, isCrawlbruleeError };
+/**
+ * Verification for async scrape completion webhooks.
+ *
+ * {@link verifyWebhookSignature} validates the signature crawlbrulee attaches to
+ * every webhook delivery. It is a standalone, network-free helper built on Web
+ * Crypto (`globalThis.crypto.subtle`) so it runs unchanged on Node.js 22+,
+ * browsers, Bun, Deno, and edge runtimes — it never touches `node:crypto`.
+ */
+/** HTTP header carrying the primary webhook signature (always present). */
+declare const WEBHOOK_SIGNATURE_HEADER = "X-Cwbl-Signature";
+/**
+ * HTTP header carrying a signature produced with the previous signing secret.
+ * Present only during a signing-secret rotation grace window.
+ */
+declare const WEBHOOK_SIGNATURE_ROTATED_HEADER = "X-Cwbl-Signature-Rotated";
+/** HTTP header carrying the unique event id, useful for delivery de-duplication. */
+declare const WEBHOOK_EVENT_ID_HEADER = "X-Cwbl-Event-Id";
+/** Default replay-protection window (seconds) applied to the signed timestamp. */
+declare const DEFAULT_WEBHOOK_TOLERANCE_SECONDS = 300;
+/** Which signature header satisfied verification. */
+type WebhookSignatureSource = 'primary' | 'rotated';
+/**
+ * Why a webhook signature failed to verify.
+ *
+ * - `missing_signature` — neither the primary nor the rotated header was present.
+ * - `malformed_signature` — a header was present but not in the expected
+ *   `t=<unix_seconds>,v1=<64_hex>` format.
+ * - `timestamp_out_of_tolerance` — the signed timestamp drifted further from now
+ *   than `toleranceSeconds` allows (replay protection).
+ * - `signature_mismatch` — a well-formed, in-tolerance signature did not match
+ *   the one computed from the payload and secret.
+ */
+type WebhookVerificationFailureReason = 'missing_signature' | 'malformed_signature' | 'timestamp_out_of_tolerance' | 'signature_mismatch';
+/** Result of {@link verifyWebhookSignature}. Verification failure is returned, not thrown. */
+type WebhookVerificationResult = {
+    verified: true;
+    signedWith: WebhookSignatureSource;
+} | {
+    verified: false;
+    reason: WebhookVerificationFailureReason;
+};
+/** Options for {@link verifyWebhookSignature}. */
+interface VerifyWebhookSignatureOptions {
+    /**
+     * The raw request body, exactly as received. Pass the bytes/string the server
+     * signed — do NOT re-serialize parsed JSON, or the signature will not match.
+     */
+    payload: string | Uint8Array;
+    /**
+     * The request headers. Accepts a fetch `Headers` instance or a plain object
+     * (Express/Node give lowercased keys, values possibly arrays). Lookup is
+     * case-insensitive.
+     */
+    headers: Headers | Record<string, string | string[] | undefined>;
+    /** The current signing secret (`whsec_…`). */
+    secret: string;
+    /**
+     * Replay-protection window in seconds. Defaults to
+     * {@link DEFAULT_WEBHOOK_TOLERANCE_SECONDS} (300). Pass `0` (or any falsy
+     * value) to disable the timestamp check entirely.
+     */
+    toleranceSeconds?: number;
+}
+/**
+ * Verify a crawlbrulee webhook signature against the primary and rotated
+ * headers.
+ *
+ * The signing scheme matches the backend:
+ * - the signed payload is `` `${t}.${rawBody}` `` where `t` is the unix-seconds
+ *   integer from the header and `rawBody` is the raw request body,
+ * - the signature is `HMAC-SHA256(secret, signedPayload)` as lowercase hex,
+ * - the header value is `t=<unix_seconds>,v1=<64_hex>`.
+ *
+ * The supplied `secret` is tried against the primary header first, then the
+ * rotated header (which the API emits during a signing-secret rotation grace
+ * window). Whichever matches wins, and the result reports which header it was.
+ *
+ * This NEVER throws on a verification failure — failures are normal control
+ * flow and are returned as `{ verified: false, reason }`.
+ *
+ * @example
+ * ```ts
+ * const result = await verifyWebhookSignature({
+ *   payload: rawBody,
+ *   headers: req.headers,
+ *   secret: process.env.CRAWLBRULEE_WEBHOOK_SECRET!,
+ * })
+ * if (!result.verified) return res.status(400).end()
+ * ```
+ */
+declare function verifyWebhookSignature(options: VerifyWebhookSignatureOptions): Promise<WebhookVerificationResult>;
+
+export { type ApiErrorDetails, type ApiErrorName, type ApiErrorResponse, type AsyncJobStatus, type AsyncJobStatusResponse, type AsyncScrapeRequest, type AsyncScrapeResponse, type AsyncScrapeWebhook, AuthenticationError, Crawlbrulee, CrawlbruleeError, type CrawlbruleeOptions, DEFAULT_BASE_URL, DEFAULT_REQUEST_TIMEOUT_MS, DEFAULT_WEBHOOK_TOLERANCE_SECONDS, ENV_API_KEY, type HttpMethod, type MapCache, type MapLinkItem, type MapLocation, type MapPagination, type MapRequest, type MapResponse, type MapTruncation, type MapTypes, NotFoundError, type PageInlineImage, type PageLink, type ProxyTier, RateLimitError, type RateLimitErrorDetails, type RequestOptions, type ScrapeCache, type ScrapeCompleteWebhook, type ScrapeCompleteWebhookData, type ScrapeExtract, type ScrapeLocation, type ScrapeMetadata, type ScrapeRequest, type ScrapeResponse, type ScrapeWebhookStatus, type ScreenshotAfterAction, type ScreenshotBeforeAction, type ScreenshotCleanup, type ScreenshotDeviceMode, type ScreenshotProperties, type ScreenshotRequest, type ScreenshotResult, type ScreenshotScrollAction, type ScreenshotSlice, type ScreenshotSliceAction, type ScreenshotType, type ScreenshotViewport, type ScreenshotViewportInfo, type ScreenshotWaitAction, TransportError, UsageAllocationError, type UsageAllocationErrorDetails, type UsageAllocationReason, type UsageLimitDetails, type UsageResponse, ValidationError, type VerifyWebhookSignatureOptions, WEBHOOK_EVENT_ID_HEADER, WEBHOOK_SIGNATURE_HEADER, WEBHOOK_SIGNATURE_ROTATED_HEADER, type WaitForScrapeOptions, type WebhookSignatureSource, type WebhookVerificationFailureReason, type WebhookVerificationResult, type WhoamiResponse, isCrawlbruleeError, verifyWebhookSignature };

package/dist/index.d.ts

@@ -255,6 +255,40 @@ interface ScrapeRequest {
     /** Optional locale + country emulation. */
     location?: ScrapeLocation;
 }
+/**
+ * Per-job completion webhook, attached when submitting an ASYNC scrape via
+ * {@link Crawlbrulee.scrapeAsync}. Async-only: the synchronous `scrape()`
+ * response IS the notification, so {@link ScrapeRequest} deliberately omits
+ * this field and the sync `/api/scrape` endpoint rejects it.
+ *
+ * Configure the signing secret used for deliveries in the dashboard
+ * (Account → Webhooks) — there is no per-request secret.
+ */
+interface AsyncScrapeWebhook {
+    /**
+     * Endpoint that receives a single signed `POST` when the job reaches a
+     * terminal state. Must be an `http`/`https` URL (HTTPS is required in
+     * production) of at most 2048 characters. The body is a
+     * `scrape.complete` envelope signed with your organization webhook secret
+     * on the `X-Cwbl-Signature` header — verify it with `verifyWebhookSignature`.
+     */
+    url: string;
+    /**
+     * Opaque correlation object echoed verbatim in the webhook payload's
+     * `data.metadata`. Must serialize to at most 2048 bytes (UTF-8 JSON). Use it
+     * to route deliveries without keeping your own `job_id` mapping.
+     */
+    metadata?: Record<string, unknown>;
+}
+/**
+ * Request body for `POST /api/scrape/async`: a {@link ScrapeRequest} plus an
+ * optional per-job completion {@link AsyncScrapeWebhook}. The `webhook` field
+ * is async-only and is not accepted by the synchronous `scrape()` endpoint.
+ */
+interface AsyncScrapeRequest extends ScrapeRequest {
+    /** Optional completion webhook delivered when this job finishes. */
+    webhook?: AsyncScrapeWebhook;
+}
 /** Viewport metadata returned alongside a captured screenshot. */
 interface ScreenshotViewportInfo {
     width: number;
@@ -524,6 +558,54 @@ interface WhoamiResponse {
     token_preview: string;
 }
 
+/**
+ * Async scrape completion webhooks.
+ *
+ * When you submit a job with {@link Crawlbrulee.scrapeAsync} the API can deliver
+ * a `scrape.complete` webhook to your configured endpoint once the job reaches a
+ * terminal state. The envelope on the wire is exactly:
+ *
+ * ```json
+ * {
+ *   "event_id": "evt_…",
+ *   "timestamp": "2026-06-13T12:00:00.000Z",
+ *   "event": "scrape.complete",
+ *   "data": { "job_id": "job_…", "status": "success", "url": "https://…", "completed_at": "…" }
+ * }
+ * ```
+ */
+/** Terminal status carried by a {@link ScrapeCompleteWebhook}. */
+type ScrapeWebhookStatus = 'success' | 'failed' | 'cancelled';
+/** `data` block of a {@link ScrapeCompleteWebhook}. */
+interface ScrapeCompleteWebhookData {
+    /** The async job identifier — pass it to `getScrapeResult`. */
+    job_id: string;
+    /** Terminal state of the job. */
+    status: ScrapeWebhookStatus;
+    /** The URL that was scraped. */
+    url: string;
+    /** ISO-8601 UTC timestamp when the job reached its terminal state. */
+    completed_at: string;
+    /** Failure message — present only when `status === 'failed'`. */
+    error?: string;
+    /** Correlation data echoed back from the original scrape request, if any. */
+    metadata?: Record<string, unknown>;
+}
+/**
+ * Webhook envelope delivered when an async scrape job completes. The `event`
+ * discriminator is always the literal `'scrape.complete'`.
+ */
+interface ScrapeCompleteWebhook {
+    /** Unique event identifier — also delivered in the `X-Cwbl-Event-Id` header. */
+    event_id: string;
+    /** ISO-8601 UTC timestamp when the event was emitted. */
+    timestamp: string;
+    /** Event type discriminator. */
+    event: 'scrape.complete';
+    /** Event payload. */
+    data: ScrapeCompleteWebhookData;
+}
+
 /** Options accepted by the {@link Crawlbrulee} constructor. */
 interface CrawlbruleeOptions {
     /**
@@ -617,8 +699,12 @@ declare class Crawlbrulee {
      * Submit an asynchronous scrape job and return its `job_id`. Poll the job
      * with {@link Crawlbrulee.getScrapeStatus} or wait for completion with
      * {@link Crawlbrulee.waitForScrape}.
+     *
+     * Pass an optional `webhook` to have the API deliver a signed
+     * `scrape.complete` `POST` to your endpoint when the job finishes (see
+     * {@link AsyncScrapeWebhook}). This field is async-only.
      */
-    scrapeAsync(request: ScrapeRequest, options?: RequestOptions): Promise<AsyncScrapeResponse>;
+    scrapeAsync(request: AsyncScrapeRequest, options?: RequestOptions): Promise<AsyncScrapeResponse>;
     /** Look up the current status of an async scrape job. */
     getScrapeStatus(jobId: string, options?: RequestOptions): Promise<AsyncJobStatusResponse>;
     /**
@@ -627,6 +713,25 @@ declare class Crawlbrulee {
      * first, or use {@link Crawlbrulee.waitForScrape} to poll-then-fetch.
      */
     getScrapeResult(jobId: string, options?: RequestOptions): Promise<ScrapeResponse>;
+    /**
+     * Fetch the scrape result referenced by a `scrape.complete` webhook body.
+     *
+     * Always verify the webhook signature with `verifyWebhookSignature` before
+     * acting on it; this method trusts the parsed body it is handed.
+     *
+     * Behavior by `data.status`:
+     * - `success` — delegates to {@link Crawlbrulee.getScrapeResult} for the
+     *   webhook's `job_id` and returns the parsed result.
+     * - `failed` — throws a {@link CrawlbruleeError} carrying `data.error`
+     *   (`errorName: 'job_failed'`); there is no result to fetch.
+     * - `cancelled` — throws a {@link CrawlbruleeError}
+     *   (`errorName: 'client_closed_request'`).
+     *
+     * A non-`scrape.complete` envelope throws a {@link CrawlbruleeError}
+     * defensively. Any HTTP error from the underlying fetch propagates as the
+     * usual typed `CrawlbruleeError` subclass.
+     */
+    fetchScrapeResultFromWebhook(webhook: ScrapeCompleteWebhook, options?: RequestOptions): Promise<ScrapeResponse>;
     /**
      * Poll an async scrape job until it reaches a terminal state, then return
      * the scrape result.
@@ -782,4 +887,96 @@ declare const DEFAULT_REQUEST_TIMEOUT_MS = 60000;
 /** Environment variable read by `Crawlbrulee.fromEnv()` to source the API key. */
 declare const ENV_API_KEY = "CRAWLBRULEE_API_KEY";
 
-export { type ApiErrorDetails, type ApiErrorName, type ApiErrorResponse, type AsyncJobStatus, type AsyncJobStatusResponse, type AsyncScrapeResponse, AuthenticationError, Crawlbrulee, CrawlbruleeError, type CrawlbruleeOptions, DEFAULT_BASE_URL, DEFAULT_REQUEST_TIMEOUT_MS, ENV_API_KEY, type HttpMethod, type MapCache, type MapLinkItem, type MapLocation, type MapPagination, type MapRequest, type MapResponse, type MapTruncation, type MapTypes, NotFoundError, type PageInlineImage, type PageLink, type ProxyTier, RateLimitError, type RateLimitErrorDetails, type RequestOptions, type ScrapeCache, type ScrapeExtract, type ScrapeLocation, type ScrapeMetadata, type ScrapeRequest, type ScrapeResponse, type ScreenshotAfterAction, type ScreenshotBeforeAction, type ScreenshotCleanup, type ScreenshotDeviceMode, type ScreenshotProperties, type ScreenshotRequest, type ScreenshotResult, type ScreenshotScrollAction, type ScreenshotSlice, type ScreenshotSliceAction, type ScreenshotType, type ScreenshotViewport, type ScreenshotViewportInfo, type ScreenshotWaitAction, TransportError, UsageAllocationError, type UsageAllocationErrorDetails, type UsageAllocationReason, type UsageLimitDetails, type UsageResponse, ValidationError, type WaitForScrapeOptions, type WhoamiResponse, isCrawlbruleeError };
+/**
+ * Verification for async scrape completion webhooks.
+ *
+ * {@link verifyWebhookSignature} validates the signature crawlbrulee attaches to
+ * every webhook delivery. It is a standalone, network-free helper built on Web
+ * Crypto (`globalThis.crypto.subtle`) so it runs unchanged on Node.js 22+,
+ * browsers, Bun, Deno, and edge runtimes — it never touches `node:crypto`.
+ */
+/** HTTP header carrying the primary webhook signature (always present). */
+declare const WEBHOOK_SIGNATURE_HEADER = "X-Cwbl-Signature";
+/**
+ * HTTP header carrying a signature produced with the previous signing secret.
+ * Present only during a signing-secret rotation grace window.
+ */
+declare const WEBHOOK_SIGNATURE_ROTATED_HEADER = "X-Cwbl-Signature-Rotated";
+/** HTTP header carrying the unique event id, useful for delivery de-duplication. */
+declare const WEBHOOK_EVENT_ID_HEADER = "X-Cwbl-Event-Id";
+/** Default replay-protection window (seconds) applied to the signed timestamp. */
+declare const DEFAULT_WEBHOOK_TOLERANCE_SECONDS = 300;
+/** Which signature header satisfied verification. */
+type WebhookSignatureSource = 'primary' | 'rotated';
+/**
+ * Why a webhook signature failed to verify.
+ *
+ * - `missing_signature` — neither the primary nor the rotated header was present.
+ * - `malformed_signature` — a header was present but not in the expected
+ *   `t=<unix_seconds>,v1=<64_hex>` format.
+ * - `timestamp_out_of_tolerance` — the signed timestamp drifted further from now
+ *   than `toleranceSeconds` allows (replay protection).
+ * - `signature_mismatch` — a well-formed, in-tolerance signature did not match
+ *   the one computed from the payload and secret.
+ */
+type WebhookVerificationFailureReason = 'missing_signature' | 'malformed_signature' | 'timestamp_out_of_tolerance' | 'signature_mismatch';
+/** Result of {@link verifyWebhookSignature}. Verification failure is returned, not thrown. */
+type WebhookVerificationResult = {
+    verified: true;
+    signedWith: WebhookSignatureSource;
+} | {
+    verified: false;
+    reason: WebhookVerificationFailureReason;
+};
+/** Options for {@link verifyWebhookSignature}. */
+interface VerifyWebhookSignatureOptions {
+    /**
+     * The raw request body, exactly as received. Pass the bytes/string the server
+     * signed — do NOT re-serialize parsed JSON, or the signature will not match.
+     */
+    payload: string | Uint8Array;
+    /**
+     * The request headers. Accepts a fetch `Headers` instance or a plain object
+     * (Express/Node give lowercased keys, values possibly arrays). Lookup is
+     * case-insensitive.
+     */
+    headers: Headers | Record<string, string | string[] | undefined>;
+    /** The current signing secret (`whsec_…`). */
+    secret: string;
+    /**
+     * Replay-protection window in seconds. Defaults to
+     * {@link DEFAULT_WEBHOOK_TOLERANCE_SECONDS} (300). Pass `0` (or any falsy
+     * value) to disable the timestamp check entirely.
+     */
+    toleranceSeconds?: number;
+}
+/**
+ * Verify a crawlbrulee webhook signature against the primary and rotated
+ * headers.
+ *
+ * The signing scheme matches the backend:
+ * - the signed payload is `` `${t}.${rawBody}` `` where `t` is the unix-seconds
+ *   integer from the header and `rawBody` is the raw request body,
+ * - the signature is `HMAC-SHA256(secret, signedPayload)` as lowercase hex,
+ * - the header value is `t=<unix_seconds>,v1=<64_hex>`.
+ *
+ * The supplied `secret` is tried against the primary header first, then the
+ * rotated header (which the API emits during a signing-secret rotation grace
+ * window). Whichever matches wins, and the result reports which header it was.
+ *
+ * This NEVER throws on a verification failure — failures are normal control
+ * flow and are returned as `{ verified: false, reason }`.
+ *
+ * @example
+ * ```ts
+ * const result = await verifyWebhookSignature({
+ *   payload: rawBody,
+ *   headers: req.headers,
+ *   secret: process.env.CRAWLBRULEE_WEBHOOK_SECRET!,
+ * })
+ * if (!result.verified) return res.status(400).end()
+ * ```
+ */
+declare function verifyWebhookSignature(options: VerifyWebhookSignatureOptions): Promise<WebhookVerificationResult>;
+
+export { type ApiErrorDetails, type ApiErrorName, type ApiErrorResponse, type AsyncJobStatus, type AsyncJobStatusResponse, type AsyncScrapeRequest, type AsyncScrapeResponse, type AsyncScrapeWebhook, AuthenticationError, Crawlbrulee, CrawlbruleeError, type CrawlbruleeOptions, DEFAULT_BASE_URL, DEFAULT_REQUEST_TIMEOUT_MS, DEFAULT_WEBHOOK_TOLERANCE_SECONDS, ENV_API_KEY, type HttpMethod, type MapCache, type MapLinkItem, type MapLocation, type MapPagination, type MapRequest, type MapResponse, type MapTruncation, type MapTypes, NotFoundError, type PageInlineImage, type PageLink, type ProxyTier, RateLimitError, type RateLimitErrorDetails, type RequestOptions, type ScrapeCache, type ScrapeCompleteWebhook, type ScrapeCompleteWebhookData, type ScrapeExtract, type ScrapeLocation, type ScrapeMetadata, type ScrapeRequest, type ScrapeResponse, type ScrapeWebhookStatus, type ScreenshotAfterAction, type ScreenshotBeforeAction, type ScreenshotCleanup, type ScreenshotDeviceMode, type ScreenshotProperties, type ScreenshotRequest, type ScreenshotResult, type ScreenshotScrollAction, type ScreenshotSlice, type ScreenshotSliceAction, type ScreenshotType, type ScreenshotViewport, type ScreenshotViewportInfo, type ScreenshotWaitAction, TransportError, UsageAllocationError, type UsageAllocationErrorDetails, type UsageAllocationReason, type UsageLimitDetails, type UsageResponse, ValidationError, type VerifyWebhookSignatureOptions, WEBHOOK_EVENT_ID_HEADER, WEBHOOK_SIGNATURE_HEADER, WEBHOOK_SIGNATURE_ROTATED_HEADER, type WaitForScrapeOptions, type WebhookSignatureSource, type WebhookVerificationFailureReason, type WebhookVerificationResult, type WhoamiResponse, isCrawlbruleeError, verifyWebhookSignature };

package/dist/index.js

@@ -375,6 +375,10 @@ var Crawlbrulee = class _Crawlbrulee {
    * Submit an asynchronous scrape job and return its `job_id`. Poll the job
    * with {@link Crawlbrulee.getScrapeStatus} or wait for completion with
    * {@link Crawlbrulee.waitForScrape}.
+   *
+   * Pass an optional `webhook` to have the API deliver a signed
+   * `scrape.complete` `POST` to your endpoint when the job finishes (see
+   * {@link AsyncScrapeWebhook}). This field is async-only.
    */
   scrapeAsync(request, options) {
     return this.http.post("/api/scrape/async", request, options);
@@ -396,6 +400,52 @@ var Crawlbrulee = class _Crawlbrulee {
     assertNonEmptyJobId(jobId);
     return this.http.get(`/api/scrape/result/${encodeURIComponent(jobId)}`, options);
   }
+  /**
+   * Fetch the scrape result referenced by a `scrape.complete` webhook body.
+   *
+   * Always verify the webhook signature with `verifyWebhookSignature` before
+   * acting on it; this method trusts the parsed body it is handed.
+   *
+   * Behavior by `data.status`:
+   * - `success` — delegates to {@link Crawlbrulee.getScrapeResult} for the
+   *   webhook's `job_id` and returns the parsed result.
+   * - `failed` — throws a {@link CrawlbruleeError} carrying `data.error`
+   *   (`errorName: 'job_failed'`); there is no result to fetch.
+   * - `cancelled` — throws a {@link CrawlbruleeError}
+   *   (`errorName: 'client_closed_request'`).
+   *
+   * A non-`scrape.complete` envelope throws a {@link CrawlbruleeError}
+   * defensively. Any HTTP error from the underlying fetch propagates as the
+   * usual typed `CrawlbruleeError` subclass.
+   */
+  async fetchScrapeResultFromWebhook(webhook, options) {
+    if (webhook?.event !== "scrape.complete") {
+      throw new CrawlbruleeError(
+        `Expected a 'scrape.complete' webhook but received '${String(webhook?.event)}'.`,
+        { status: 0, errorName: "validation_error" }
+      );
+    }
+    const { job_id: jobId, status, error } = webhook.data;
+    switch (status) {
+      case "success":
+        return this.getScrapeResult(jobId, options);
+      case "failed":
+        throw new CrawlbruleeError(error ?? `Async scrape job ${jobId} failed.`, {
+          status: 0,
+          errorName: "job_failed"
+        });
+      case "cancelled":
+        throw new CrawlbruleeError(`Async scrape job ${jobId} was cancelled.`, {
+          status: 0,
+          errorName: "client_closed_request"
+        });
+      default:
+        throw new CrawlbruleeError(
+          `Async scrape webhook for job ${jobId} carried an unexpected status '${String(status)}'.`,
+          { status: 0, errorName: "validation_error" }
+        );
+    }
+  }
   /**
    * Poll an async scrape job until it reaches a terminal state, then return
    * the scrape result.
@@ -522,6 +572,117 @@ function sleep(ms, signal) {
   });
 }
 
-export { AuthenticationError, Crawlbrulee, CrawlbruleeError, DEFAULT_BASE_URL, DEFAULT_REQUEST_TIMEOUT_MS, ENV_API_KEY, NotFoundError, RateLimitError, TransportError, UsageAllocationError, ValidationError, isCrawlbruleeError };
+// src/webhooks.ts
+var WEBHOOK_SIGNATURE_HEADER = "X-Cwbl-Signature";
+var WEBHOOK_SIGNATURE_ROTATED_HEADER = "X-Cwbl-Signature-Rotated";
+var WEBHOOK_EVENT_ID_HEADER = "X-Cwbl-Event-Id";
+var DEFAULT_WEBHOOK_TOLERANCE_SECONDS = 300;
+var SIGNATURE_FORMAT = /^t=(\d+),v1=([0-9a-f]{64})$/;
+async function verifyWebhookSignature(options) {
+  const { payload, headers, secret } = options;
+  const toleranceSeconds = options.toleranceSeconds ?? DEFAULT_WEBHOOK_TOLERANCE_SECONDS;
+  const primaryHeader = getHeader(headers, WEBHOOK_SIGNATURE_HEADER);
+  const rotatedHeader = getHeader(headers, WEBHOOK_SIGNATURE_ROTATED_HEADER);
+  if (primaryHeader === void 0 && rotatedHeader === void 0) {
+    return { verified: false, reason: "missing_signature" };
+  }
+  const nowSeconds = Math.floor(Date.now() / 1e3);
+  const body = toBytes(payload);
+  const key = await importHmacKey(secret);
+  let failure = "malformed_signature";
+  for (const source of ["primary", "rotated"]) {
+    const raw = source === "primary" ? primaryHeader : rotatedHeader;
+    if (raw === void 0) continue;
+    const parsed = parseSignatureHeader(raw);
+    if (!parsed) {
+      continue;
+    }
+    if (toleranceSeconds && Math.abs(nowSeconds - parsed.timestamp) > toleranceSeconds) {
+      failure = mostSpecificFailure(failure, "timestamp_out_of_tolerance");
+      continue;
+    }
+    const expected = await computeSignatureHex(key, parsed.timestamp, body);
+    if (constantTimeEqualHex(expected, parsed.signature)) {
+      return { verified: true, signedWith: source };
+    }
+    failure = mostSpecificFailure(failure, "signature_mismatch");
+  }
+  return { verified: false, reason: failure };
+}
+function mostSpecificFailure(current, candidate) {
+  const rank = {
+    missing_signature: 0,
+    malformed_signature: 1,
+    timestamp_out_of_tolerance: 2,
+    signature_mismatch: 3
+  };
+  return rank[candidate] > rank[current] ? candidate : current;
+}
+function getHeader(headers, name) {
+  if (typeof Headers !== "undefined" && headers instanceof Headers) {
+    return headers.get(name) ?? void 0;
+  }
+  const target = name.toLowerCase();
+  for (const key of Object.keys(headers)) {
+    if (key.toLowerCase() !== target) continue;
+    const value = headers[key];
+    if (Array.isArray(value)) return value[0];
+    return value ?? void 0;
+  }
+  return void 0;
+}
+function parseSignatureHeader(value) {
+  const match = SIGNATURE_FORMAT.exec(value.trim());
+  if (!match) return null;
+  const timestamp = Number(match[1]);
+  if (!Number.isSafeInteger(timestamp)) return null;
+  return { timestamp, signature: match[2] };
+}
+function toBytes(payload) {
+  return typeof payload === "string" ? new TextEncoder().encode(payload) : payload;
+}
+function importHmacKey(secret) {
+  return getSubtle().importKey(
+    "raw",
+    new TextEncoder().encode(secret),
+    { name: "HMAC", hash: "SHA-256" },
+    false,
+    ["sign"]
+  );
+}
+async function computeSignatureHex(key, timestamp, body) {
+  const prefix = new TextEncoder().encode(`${timestamp}.`);
+  const message = new Uint8Array(prefix.length + body.length);
+  message.set(prefix, 0);
+  message.set(body, prefix.length);
+  const digest = await getSubtle().sign("HMAC", key, message);
+  return toHex(new Uint8Array(digest));
+}
+function toHex(bytes) {
+  let hex = "";
+  for (const byte of bytes) {
+    hex += byte.toString(16).padStart(2, "0");
+  }
+  return hex;
+}
+function constantTimeEqualHex(a, b) {
+  if (a.length !== b.length) return false;
+  let diff = 0;
+  for (let i = 0; i < a.length; i++) {
+    diff |= a.charCodeAt(i) ^ b.charCodeAt(i);
+  }
+  return diff === 0;
+}
+function getSubtle() {
+  const subtle = globalThis.crypto?.subtle;
+  if (!subtle) {
+    throw new Error(
+      "Web Crypto (globalThis.crypto.subtle) is not available in this runtime. crawlbrulee webhook verification requires Node.js 20+, Bun, Deno, or a modern browser/edge runtime."
+    );
+  }
+  return subtle;
+}
+
+export { AuthenticationError, Crawlbrulee, CrawlbruleeError, DEFAULT_BASE_URL, DEFAULT_REQUEST_TIMEOUT_MS, DEFAULT_WEBHOOK_TOLERANCE_SECONDS, ENV_API_KEY, NotFoundError, RateLimitError, TransportError, UsageAllocationError, ValidationError, WEBHOOK_EVENT_ID_HEADER, WEBHOOK_SIGNATURE_HEADER, WEBHOOK_SIGNATURE_ROTATED_HEADER, isCrawlbruleeError, verifyWebhookSignature };
 //# sourceMappingURL=index.js.map
 //# sourceMappingURL=index.js.map