@crawlbrulee/sdk 0.7.0 → 0.8.0

package/dist/index.d.cts

@@ -1,30 +1,31 @@
+//#region src/http.d.ts
 /** HTTP methods used by the SDK. */
 type HttpMethod = 'GET' | 'POST';
 /** Options the SDK accepts at construction time for the HTTP layer. */
 interface HttpClientOptions {
-    /** API key sent as `Authorization: Bearer <key>`. */
-    apiKey: string;
-    /**
-     * Override the base URL. Trailing slashes are stripped. Falls back to
-     * {@link CwblInstrumentation.getBaseUrl} (which resolves to the production
-     * host) when unset.
-     */
-    baseUrl?: string;
-    /**
-     * Per-request timeout in milliseconds. Pass `0` (or omit) to disable the
-     * timeout entirely.
-     */
-    timeoutMs?: number;
+  /** API key sent as `Authorization: Bearer <key>`. */
+  apiKey: string;
+  /**
+   * Override the base URL. Trailing slashes are stripped. Falls back to
+   * {@link CwblInstrumentation.getBaseUrl} (which resolves to the production
+   * host) when unset.
+   */
+  baseUrl?: string;
+  /**
+   * Per-request timeout in milliseconds. Pass `0` (or omit) to disable the
+   * timeout entirely.
+   */
+  timeoutMs?: number;
 }
 /** Per-call overrides accepted on every resource method. */
 interface RequestOptions {
-    /** Abort the request when this signal fires. Composable with the timeout. */
-    signal?: AbortSignal;
-    /**
-     * Override the constructor-level `timeoutMs` for this call. Pass `0` to
-     * disable the timeout for this call.
-     */
-    timeoutMs?: number;
+  /** Abort the request when this signal fires. Composable with the timeout. */
+  signal?: AbortSignal;
+  /**
+   * Override the constructor-level `timeoutMs` for this call. Pass `0` to
+   * disable the timeout for this call.
+   */
+  timeoutMs?: number;
 }
 /**
  * Minimal `fetch`-based HTTP layer used by {@link Crawlbrulee}. Handles:
@@ -43,27 +44,28 @@ interface RequestOptions {
  * module.
  */
 declare class HttpClient {
-    readonly baseUrl: string;
-    private readonly apiKey;
-    private readonly fetch;
-    private readonly timeoutMs;
-    constructor(options: HttpClientOptions);
-    /** Send a `GET` request and parse the response as `T`. */
-    get<T>(path: string, options?: RequestOptions): Promise<T>;
-    /** Send a `POST` request with a JSON body and parse the response as `T`. */
-    post<T>(path: string, body: unknown, options?: RequestOptions): Promise<T>;
-    private send;
-    private buildUrl;
-    private buildHeaders;
-    /**
-     * Build a single `AbortSignal` that fires when either the caller-supplied
-     * signal aborts OR the per-request timeout elapses. The returned `cleanup`
-     * callback MUST be invoked on every exit path so we don't leak timers or
-     * dead listeners on long-lived caller signals.
-     */
-    private composeSignal;
+  readonly baseUrl: string;
+  private readonly apiKey;
+  private readonly fetch;
+  private readonly timeoutMs;
+  constructor(options: HttpClientOptions);
+  /** Send a `GET` request and parse the response as `T`. */
+  get<T>(path: string, options?: RequestOptions): Promise<T>;
+  /** Send a `POST` request with a JSON body and parse the response as `T`. */
+  post<T>(path: string, body: unknown, options?: RequestOptions): Promise<T>;
+  private send;
+  private buildUrl;
+  private buildHeaders;
+  /**
+   * Build a single `AbortSignal` that fires when either the caller-supplied
+   * signal aborts OR the per-request timeout elapses. The returned `cleanup`
+   * callback MUST be invoked on every exit path so we don't leak timers or
+   * dead listeners on long-lived caller signals.
+   */
+  private composeSignal;
 }
-
+//#endregion
+//#region src/types/common.d.ts
 /**
  * Shared primitive types used across crawlbrulee request and response shapes.
  */
@@ -89,15 +91,15 @@ type ResolvedProxyTier = 'basic' | 'advanced';
  * responses report this on `response_meta.usage`.
  */
 interface Usage {
-    /**
-     * Credits charged for this operation. `0` on a cache hit (no fresh fetch was
-     * performed).
-     */
-    credits: number;
-    /** The proxy tier the server resolved and used (never `auto`). */
-    proxy: ResolvedProxyTier;
-    /** Whether the result was served from cache (no fresh fetch). */
-    cache_hit: boolean;
+  /**
+   * Credits charged for this operation. `0` on a cache hit (no fresh fetch was
+   * performed).
+   */
+  credits: number;
+  /** The proxy tier the server resolved and used (never `auto`). */
+  proxy: ResolvedProxyTier;
+  /** Whether the result was served from cache (no fresh fetch). */
+  cache_hit: boolean;
 }
 /**
  * Response envelope `response_meta` carried by scrape responses and async-status
@@ -105,8 +107,8 @@ interface Usage {
  * responses extend this shape with `pagination` + `truncation`.
  */
 interface ResponseMeta {
-    /** Usage accounting for the operation. */
-    usage: Usage;
+  /** Usage accounting for the operation. */
+  usage: Usage;
 }
 /** Screenshot capture mode: visible viewport or the full scrollable page. */
 type ScreenshotType = 'viewport' | 'full_page';
@@ -114,23 +116,23 @@ type ScreenshotType = 'viewport' | 'full_page';
 type ScreenshotDeviceMode = 'desktop' | 'mobile';
 /** Pre-capture cleanup options applied to the page before the screenshot. */
 interface ScreenshotCleanup {
-    /**
-     * Remove ads, cookie banners, and popups before capturing. Defaults to
-     * `true` server-side.
-     */
-    ads_and_popups?: boolean;
+  /**
+   * Remove ads, cookie banners, and popups before capturing. Defaults to
+   * `true` server-side.
+   */
+  ads_and_popups?: boolean;
 }
 /** A `wait` action: pause for `ms` milliseconds before the next step. */
 interface ScreenshotWaitAction {
-    type: 'wait';
-    /** Milliseconds to wait. Must be a non-negative integer. */
-    ms: number;
+  type: 'wait';
+  /** Milliseconds to wait. Must be a non-negative integer. */
+  ms: number;
 }
 /** A `scroll` action: scroll the page by `pixels` (positive = down). */
 interface ScreenshotScrollAction {
-    type: 'scroll';
-    /** Pixels to scroll. Positive scrolls down, negative scrolls up. */
-    pixels: number;
+  type: 'scroll';
+  /** Pixels to scroll. Positive scrolls down, negative scrolls up. */
+  pixels: number;
 }
 /**
  * Actions performed before the screenshot is taken. The server caps the total
@@ -143,37 +145,37 @@ type ScreenshotBeforeAction = ScreenshotWaitAction | ScreenshotScrollAction;
  * supported — it cuts the screenshot into horizontal tiles of `height` px.
  */
 interface ScreenshotSliceAction {
-    type: 'slice';
-    /** Tile height in pixels. Minimum 500. */
-    height: number;
+  type: 'slice';
+  /** Tile height in pixels. Minimum 500. */
+  height: number;
 }
 type ScreenshotAfterAction = ScreenshotSliceAction;
 /** Custom browser viewport dimensions used during a screenshot capture. */
 interface ScreenshotViewport {
-    /** Viewport width in pixels. Integer in `[16, 10000]`; out-of-range values are rejected with a 400. */
-    width: number;
-    /** Viewport height in pixels. Integer in `[16, 10000]`; out-of-range values are rejected with a 400. */
-    height: number;
-    /**
-     * Device pixel ratio (e.g. 2 for retina). Fractional values are allowed;
-     * must be in `[1, 4]`. Defaults to 1 server-side.
-     */
-    device_scale_factor?: number;
+  /** Viewport width in pixels. Integer in `[16, 10000]`; out-of-range values are rejected with a 400. */
+  width: number;
+  /** Viewport height in pixels. Integer in `[16, 10000]`; out-of-range values are rejected with a 400. */
+  height: number;
+  /**
+   * Device pixel ratio (e.g. 2 for retina). Fractional values are allowed;
+   * must be in `[1, 4]`. Defaults to 1 server-side.
+   */
+  device_scale_factor?: number;
 }
 /** Screenshot capture configuration. Pass this on `extract.screenshot`. */
 interface ScreenshotRequest {
-    /** Capture mode: `viewport` (visible only) or `full_page`. */
-    type: ScreenshotType;
-    /** Custom viewport. If omitted, the `device_mode` defaults are used. */
-    viewport?: ScreenshotViewport;
-    /** Emulate desktop or mobile. Defaults to `desktop`. */
-    device_mode?: ScreenshotDeviceMode;
-    /** Page cleanup applied before capture. */
-    cleanup?: ScreenshotCleanup;
-    /** Pre-capture actions (waits and scrolls). Maximum 5 entries. */
-    actions_before?: ScreenshotBeforeAction[];
-    /** Post-capture actions (e.g. slice into tiles). Maximum 1 entry. */
-    actions_after?: ScreenshotAfterAction[];
+  /** Capture mode: `viewport` (visible only) or `full_page`. */
+  type: ScreenshotType;
+  /** Custom viewport. If omitted, the `device_mode` defaults are used. */
+  viewport?: ScreenshotViewport;
+  /** Emulate desktop or mobile. Defaults to `desktop`. */
+  device_mode?: ScreenshotDeviceMode;
+  /** Page cleanup applied before capture. */
+  cleanup?: ScreenshotCleanup;
+  /** Pre-capture actions (waits and scrolls). Maximum 5 entries. */
+  actions_before?: ScreenshotBeforeAction[];
+  /** Post-capture actions (e.g. slice into tiles). Maximum 1 entry. */
+  actions_after?: ScreenshotAfterAction[];
 }
 /**
  * Machine-readable error names returned by the crawlbrulee API. Stable
@@ -184,117 +186,118 @@ type ApiErrorName = 'usage_allocation_error' | 'request_timeout' | 'invalid_url'
 type UsageAllocationReason = 'credit_limit' | 'concurrency_limit' | 'overage_hard_cap' | 'duplicate_reservation' | 'internal_error';
 /** Snapshot of the org's current usage at the moment the error was raised. */
 interface UsageLimitDetails {
-    /** Current credit usage in the billing period. */
-    current_usage?: number;
-    /** Credits currently reserved by in-flight jobs. */
-    current_reserved?: number;
-    /** Maximum credits allowed in the billing period. */
-    max_credits?: number;
-    /** Number of currently running concurrent jobs. */
-    current_concurrent?: number;
-    /** Maximum concurrent jobs allowed. */
-    max_concurrent?: number;
+  /** Current credit usage in the billing period. */
+  current_usage?: number;
+  /** Credits currently reserved by in-flight jobs. */
+  current_reserved?: number;
+  /** Maximum credits allowed in the billing period. */
+  max_credits?: number;
+  /** Number of currently running concurrent jobs. */
+  current_concurrent?: number;
+  /** Maximum concurrent jobs allowed. */
+  max_concurrent?: number;
 }
 /** Discriminated detail for `error_name = usage_allocation_error`. */
 interface UsageAllocationErrorDetails {
-    error_name: 'usage_allocation_error';
-    reason: UsageAllocationReason;
-    details?: UsageLimitDetails;
+  error_name: 'usage_allocation_error';
+  reason: UsageAllocationReason;
+  details?: UsageLimitDetails;
 }
 /** Discriminated detail for `error_name = too_many_requests`. */
 interface RateLimitErrorDetails {
-    error_name: 'too_many_requests';
-    /** Suggested wait time before retrying. */
-    retry_after_ms?: number;
-    /** Which rate limit was exceeded (e.g. `org`, `ip`). */
-    limited_by?: string;
+  error_name: 'too_many_requests';
+  /** Suggested wait time before retrying. */
+  retry_after_ms?: number;
+  /** Which rate limit was exceeded (e.g. `org`, `ip`). */
+  limited_by?: string;
 }
 /** Union of all known `details` payloads on an `ApiErrorResponse`. */
 type ApiErrorDetails = UsageAllocationErrorDetails | RateLimitErrorDetails;
 /** Standard JSON error shape returned for any non-2xx response. */
 interface ApiErrorResponse {
-    /** Machine-readable identifier — safe to switch on. */
-    name: ApiErrorName;
-    /** Human-readable error message. */
-    message: string;
-    /** Error-specific structured detail; only present for some `name`s. */
-    details?: ApiErrorDetails;
+  /** Machine-readable identifier — safe to switch on. */
+  name: ApiErrorName;
+  /** Human-readable error message. */
+  message: string;
+  /** Error-specific structured detail; only present for some `name`s. */
+  details?: ApiErrorDetails;
 }
-
+//#endregion
+//#region src/types/scrape.d.ts
 /**
  * Which content formats to extract from the scraped page. Every field is
  * optional; the server defaults are noted on each field. The default request
  * extracts `{ metadata: true, cleaned_html: true }`.
  */
 interface ScrapeExtract {
-    /** Extract page metadata (title, description, OG/Twitter tags, etc.). Default `true`. */
-    metadata?: boolean;
-    /** Extract cleaned HTML (main content only). Default `true`. */
-    cleaned_html?: boolean;
-    /** Extract the page as clean Markdown. Default `false`. */
-    markdown?: boolean;
-    /** Return the raw, unprocessed HTML. Default `false`. */
-    raw_html?: boolean;
-    /** Extract all links found on the page. Default `false`. */
-    links?: boolean;
-    /**
-     * Extract all inline images found on the page. Default `false`. Image URLs
-     * preserve their query string, and document-relative `src`s are resolved
-     * against the full page URL (browser parity) — same rules as `links`.
-     */
-    images?: boolean;
-    /** Capture a screenshot. Omit to skip; set to a `ScreenshotRequest` to enable. */
-    screenshot?: ScreenshotRequest;
+  /** Extract page metadata (title, description, OG/Twitter tags, etc.). Default `true`. */
+  metadata?: boolean;
+  /** Extract cleaned HTML (main content only). Default `true`. */
+  cleaned_html?: boolean;
+  /** Extract the page as clean Markdown. Default `false`. */
+  markdown?: boolean;
+  /** Return the raw, unprocessed HTML. Default `false`. */
+  raw_html?: boolean;
+  /** Extract all links found on the page. Default `false`. */
+  links?: boolean;
+  /**
+   * Extract all inline images found on the page. Default `false`. Image URLs
+   * preserve their query string, and document-relative `src`s are resolved
+   * against the full page URL (browser parity) — same rules as `links`.
+   */
+  images?: boolean;
+  /** Capture a screenshot. Omit to skip; set to a `ScreenshotRequest` to enable. */
+  screenshot?: ScreenshotRequest;
 }
 /** Cache settings for a scrape request. */
 interface ScrapeCache {
-    /**
-     * Maximum cache age. Either a number of seconds (non-negative integer) or
-     * an ISO-8601 datetime cutoff — cached entries older than this are skipped.
-     * Defaults to 2 days when omitted.
-     */
-    max_age?: number | string;
-    /**
-     * Treat URLs with different query parameters as the same cache entry.
-     * Defaults to `false`.
-     */
-    ignore_query_params?: boolean;
+  /**
+   * Maximum cache age. Either a number of seconds (non-negative integer) or
+   * an ISO-8601 datetime cutoff — cached entries older than this are skipped.
+   * Defaults to 2 days when omitted.
+   */
+  max_age?: number | string;
 }
 /** Optional locale + country emulation for the scrape. */
 interface ScrapeLocation {
-    /**
-     * BCP-47 locale (e.g. `en-US`, `de-DE`, `pt-BR`). Sent as `Accept-Language`
-     * and reflected in `navigator.language` when JS rendering is requested.
-     */
-    locale?: string;
-    /**
-     * ISO 3166-1 alpha-2 country code (e.g. `US`, `DE`, `BR`). Drives the
-     * emulated browser timezone. Case-insensitive.
-     */
-    country?: string;
+  /**
+   * BCP-47 locale (e.g. `en-US`, `de-DE`, `pt-BR`). Sent as `Accept-Language`
+   * and reflected in `navigator.language` when JS rendering is requested.
+   */
+  locale?: string;
+  /**
+   * ISO 3166-1 alpha-2 country code (e.g. `US`, `DE`, `BR`). Drives the
+   * emulated browser timezone. Case-insensitive.
+   */
+  country?: string;
 }
 /** Request body for `POST /api/scrape` (and `POST /api/scrape/async`). */
 interface ScrapeRequest {
-    /** The URL to scrape. */
-    url: string;
-    /** Which content formats to extract. Defaults to `metadata + cleaned_html`. */
-    extract?: ScrapeExtract;
-    /** Cache settings for this request. */
-    cache?: ScrapeCache;
-    /**
-     * Use a headless browser to render JavaScript before scraping. Adds latency
-     * and credits — only enable when the page requires it. Default `false`.
-     */
-    require_js?: boolean;
-    /** CSS selectors to strip from the extracted content. */
-    exclude_selectors?: string[];
-    /**
-     * Proxy tier to use for fetching. Defaults to `auto` (tries the basic tier
-     * first, escalates to advanced on failure; billed at the delivered tier).
-     */
-    proxy?: ProxyTier;
-    /** Optional locale + country emulation. */
-    location?: ScrapeLocation;
+  /**
+   * The URL to scrape. Known tracking parameters (`utm_*`, `mtm_*`, `ga_*`, `pk_*`, `gclid`,
+   * `fbclid`, `msclkid`, and more) are removed before the page is fetched, so they reach
+   * neither the target site nor the cache key. Every other query parameter is kept verbatim
+   * and is part of the cache key.
+   */
+  url: string;
+  /** Which content formats to extract. Defaults to `metadata + cleaned_html`. */
+  extract?: ScrapeExtract;
+  /** Cache settings for this request. */
+  cache?: ScrapeCache;
+  /**
+   * Use a headless browser to render JavaScript before scraping. Adds latency
+   * and credits — only enable when the page requires it. Default `false`.
+   */
+  require_js?: boolean;
+  /** CSS selectors to strip from the extracted content. */
+  exclude_selectors?: string[];
+  /**
+   * Proxy tier to use for fetching. Defaults to `auto` (tries the basic tier
+   * first, escalates to advanced on failure; billed at the delivered tier).
+   */
+  proxy?: ProxyTier;
+  /** Optional locale + country emulation. */
+  location?: ScrapeLocation;
 }
 /**
  * Per-job completion webhook, attached when submitting an ASYNC scrape via
@@ -306,20 +309,20 @@ interface ScrapeRequest {
  * (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>;
+  /**
+   * 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
@@ -327,384 +330,365 @@ interface AsyncScrapeWebhook {
  * 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;
+  /** Optional completion webhook delivered when this job finishes. */
+  webhook?: AsyncScrapeWebhook;
 }
 /** Viewport metadata returned alongside a captured screenshot. */
 interface ScreenshotViewportInfo {
-    width: number;
-    height: number;
-    device_scale_factor: number;
+  width: number;
+  height: number;
+  device_scale_factor: number;
 }
 /** Image-level properties of a captured screenshot (or tile). */
 interface ScreenshotProperties {
-    /** File name of the image asset. */
-    file_name: string;
-    /** MIME type (e.g. `image/png`). */
-    mime: string;
-    /** Image width in pixels. */
-    width: number;
-    /** Image height in pixels. */
-    height: number;
-    /** Viewport dimensions used during capture. */
-    viewport: ScreenshotViewportInfo;
+  /** File name of the image asset. */
+  file_name: string;
+  /** MIME type (e.g. `image/png`). */
+  mime: string;
+  /** Image width in pixels. */
+  width: number;
+  /** Image height in pixels. */
+  height: number;
+  /** Viewport dimensions used during capture. */
+  viewport: ScreenshotViewportInfo;
 }
 /** One horizontal tile of a sliced full-page screenshot. */
 interface ScreenshotSlice {
-    /** 0-based row index of this slice. */
-    row_nr: number;
-    /** Signed URL to download this slice image. */
-    url: string;
-    type: 'slice';
-    /** Image-level properties of this slice. */
-    properties: ScreenshotProperties;
+  /** 0-based row index of this slice. */
+  row_nr: number;
+  /** Signed URL to download this slice image. */
+  url: string;
+  type: 'slice';
+  /** Image-level properties of this slice. */
+  properties: ScreenshotProperties;
 }
 /** Result block returned when a screenshot was requested. */
 interface ScreenshotResult {
-    /** Signed URL to download the full screenshot image. */
-    url: string;
-    /** Capture mode that was used. */
-    type: ScreenshotType;
-    /** Image-level properties of the full screenshot. */
-    properties: ScreenshotProperties;
-    /** Tile slices, present only when the `slice` `actions_after` was requested. */
-    slices?: ScreenshotSlice[];
+  /** Signed URL to download the full screenshot image. */
+  url: string;
+  /** Capture mode that was used. */
+  type: ScreenshotType;
+  /** Image-level properties of the full screenshot. */
+  properties: ScreenshotProperties;
+  /** Tile slices, present only when the `slice` `actions_after` was requested. */
+  slices?: ScreenshotSlice[];
 }
 /** A single inline image discovered on the page. */
 interface PageInlineImage {
-    /**
-     * Absolute URL of the image, query string preserved. Document-relative
-     * `src`s are resolved against the full page URL (browser parity).
-     */
-    url: string;
-    /** Alt text of the image, or `null` if not set. */
-    alt: string | null;
+  /**
+   * Absolute URL of the image, query string preserved. Document-relative
+   * `src`s are resolved against the full page URL (browser parity).
+   */
+  url: string;
+  /** Alt text of the image, or `null` if not set. */
+  alt: string | null;
 }
 /** A single link discovered on the page. */
 interface PageLink {
-    /** Anchor text of the link. */
-    text: string;
-    /** The link URL as it appears on the page (absolute or relative). */
-    href: string;
-    /** Whether the link points to the same domain as the scraped page. */
-    internal: boolean;
+  /** Anchor text of the link. */
+  text: string;
+  /** The link URL as it appears on the page (absolute or relative). */
+  href: string;
+  /** Whether the link points to the same domain as the scraped page. */
+  internal: boolean;
 }
 /** Structured page metadata extracted from `<head>`. */
 interface ScrapeMetadata {
-    title?: string;
-    description?: string;
-    keywords?: string[];
-    canonical?: string;
-    og_url?: string;
-    og_title?: string;
-    og_description?: string;
-    og_type?: string;
-    og_site_name?: string;
-    og_locale?: string;
-    og_locale_alternate?: string[];
-    og_image?: string;
-    author?: string;
-    date_modified?: string;
-    date_published?: string;
-    twitter_site?: string;
-    twitter_card?: string;
-    twitter_description?: string;
-    twitter_title?: string;
-    twitter_image?: string;
-    robots?: string;
-    favicon_url?: string | null;
+  title?: string;
+  description?: string;
+  keywords?: string[];
+  canonical?: string;
+  og_url?: string;
+  og_title?: string;
+  og_description?: string;
+  og_type?: string;
+  og_site_name?: string;
+  og_locale?: string;
+  og_locale_alternate?: string[];
+  og_image?: string;
+  author?: string;
+  date_modified?: string;
+  date_published?: string;
+  twitter_site?: string;
+  twitter_card?: string;
+  twitter_description?: string;
+  twitter_title?: string;
+  twitter_image?: string;
+  robots?: string;
+  favicon_url?: string | null;
 }
 /** Successful response from `POST /api/scrape` and `GET /api/scrape/result/:jobId`. */
 interface ScrapeResponse {
-    /** The URL that was actually scraped (after any redirects). */
-    url: string;
-    /** `Content-Type` header returned by the origin. */
-    content_type?: string;
-    /**
-     * Extract fields that were requested but aren't supported for this
-     * content type (e.g. asking for `markdown` of a PDF).
-     */
-    unsupported_fields?: string[];
-    /** Page content converted to clean Markdown (when `extract.markdown`). */
-    markdown?: string;
-    /** Cleaned HTML of the main page content (when `extract.cleaned_html`). */
-    cleaned_html?: string;
-    /** Raw, unprocessed HTML (when `extract.raw_html`). */
-    raw_html?: string;
-    /** Inline images discovered on the page (when `extract.images`). */
-    images?: PageInlineImage[];
-    /** Links discovered on the page (when `extract.links`). */
-    links?: PageLink[];
-    /**
-     * Captured screenshot (when `extract.screenshot`). In rare cases a screenshot
-     * can't be captured; when that happens the rest of your requested outputs are
-     * still returned and this field is simply left out (so it reads back as
-     * `undefined`). Guard with `page.screenshot?.url`.
-     */
-    screenshot?: ScreenshotResult;
-    /** Extracted page metadata (when `extract.metadata`, on by default). */
-    metadata?: ScrapeMetadata;
-    /**
-     * Non-error notices about the scrape (e.g. `screenshot_truncated` when a
-     * long page exceeded the scrolling-screenshot height cap). Stable codes —
-     * safe to switch on. Currently surfaced only on fresh scrapes; cache hits
-     * omit warnings.
-     */
-    warnings?: string[];
-    /**
-     * Response envelope metadata. Carries `usage` (credits charged, resolved
-     * proxy tier, and whether the result was a cache hit).
-     */
-    response_meta: ResponseMeta;
+  /** The URL that was actually scraped (after any redirects). */
+  url: string;
+  /** `Content-Type` header returned by the origin. */
+  content_type?: string;
+  /**
+   * Extract fields that were requested but aren't supported for this
+   * content type (e.g. asking for `markdown` of a PDF).
+   */
+  unsupported_fields?: string[];
+  /** Page content converted to clean Markdown (when `extract.markdown`). */
+  markdown?: string;
+  /** Cleaned HTML of the main page content (when `extract.cleaned_html`). */
+  cleaned_html?: string;
+  /** Raw, unprocessed HTML (when `extract.raw_html`). */
+  raw_html?: string;
+  /** Inline images discovered on the page (when `extract.images`). */
+  images?: PageInlineImage[];
+  /** Links discovered on the page (when `extract.links`). */
+  links?: PageLink[];
+  /**
+   * Captured screenshot (when `extract.screenshot`). In rare cases a screenshot
+   * can't be captured; when that happens the rest of your requested outputs are
+   * still returned and this field is simply left out (so it reads back as
+   * `undefined`). Guard with `page.screenshot?.url`.
+   */
+  screenshot?: ScreenshotResult;
+  /** Extracted page metadata (when `extract.metadata`, on by default). */
+  metadata?: ScrapeMetadata;
+  /**
+   * Non-error notices about the scrape (e.g. `screenshot_truncated` when a
+   * long page exceeded the scrolling-screenshot height cap). Stable codes —
+   * safe to switch on. Currently surfaced only on fresh scrapes; cache hits
+   * omit warnings.
+   */
+  warnings?: string[];
+  /**
+   * Response envelope metadata. Carries `usage` (credits charged, resolved
+   * proxy tier, and whether the result was a cache hit).
+   */
+  response_meta: ResponseMeta;
 }
-
+//#endregion
+//#region src/types/map.d.ts
 /** Filter which link types appear in the map result. */
 interface MapTypes {
-    /** Include internal links (same domain). Default `true`. */
-    internal?: boolean;
-    /** Include links to subdomains of the target. Default `true`. */
-    internal_subdomains?: boolean;
-    /** Include external links (different domains). Default `true`. */
-    external?: boolean;
+  /** Include internal links (same domain). Default `true`. */
+  internal?: boolean;
+  /** Include links to subdomains of the target. Default `true`. */
+  internal_subdomains?: boolean;
+  /** Include external links (different domains). Default `true`. */
+  external?: boolean;
 }
 /** Cache settings for a map request. */
 interface MapCache {
-    /**
-     * Maximum cache age — either seconds or an ISO-8601 datetime cutoff.
-     * Defaults to 7 days when omitted.
-     */
-    max_age?: number | string;
+  /**
+   * Maximum cache age — either seconds or an ISO-8601 datetime cutoff.
+   * Defaults to 7 days when omitted.
+   */
+  max_age?: number | string;
 }
 /** Country-only egress emulation (map requests have no locale knob). */
 interface MapLocation {
-    /** ISO 3166-1 alpha-2 country code (e.g. `US`). Case-insensitive. */
-    country?: string;
+  /** ISO 3166-1 alpha-2 country code (e.g. `US`). Case-insensitive. */
+  country?: string;
 }
 /** Request body for `POST /api/map`. */
 interface MapRequest {
-    /** The website URL to map. */
-    url: string;
-    /**
-     * Proxy tier to use for fetching. Defaults to `auto` (tries the basic tier
-     * first, escalates to advanced on failure; billed at the delivered tier).
-     */
-    proxy?: ProxyTier;
-    /** Only use sitemap.xml — skip homepage link extraction. Default `false`. */
-    sitemap_only?: boolean;
-    /** Filter which link types to include. */
-    types?: MapTypes;
-    /** Cache settings for this request. */
-    cache?: MapCache;
-    /**
-     * Maximum number of URLs to store in the map. Must be in `(0, 100 000]`.
-     * Defaults to 100 000.
-     */
-    max_urls?: number;
-    /** 1-based page number for paginated results. Defaults to 1. */
-    page?: number;
-    /**
-     * Number of URLs per page. Must be in `(0, 10 000]`. Defaults to 10 000.
-     */
-    limit?: number;
-    /** Optional country emulation. */
-    location?: MapLocation;
+  /** The website URL to map. */
+  url: string;
+  /**
+   * Proxy tier to use for fetching. Defaults to `auto` (tries the basic tier
+   * first, escalates to advanced on failure; billed at the delivered tier).
+   */
+  proxy?: ProxyTier;
+  /** Only use sitemap.xml — skip homepage link extraction. Default `false`. */
+  sitemap_only?: boolean;
+  /** Filter which link types to include. */
+  types?: MapTypes;
+  /** Cache settings for this request. */
+  cache?: MapCache;
+  /**
+   * Maximum number of URLs to store in the map. Must be in `(0, 100 000]`.
+   * Defaults to 100 000.
+   */
+  max_urls?: number;
+  /** 1-based page number for paginated results. Defaults to 1. */
+  page?: number;
+  /**
+   * Number of URLs per page. Must be in `(0, 10 000]`. Defaults to 10 000.
+   */
+  limit?: number;
+  /** Optional country emulation. */
+  location?: MapLocation;
 }
 /** Single discovered URL in a map result. */
 interface MapLinkItem {
-    /** The discovered URL. */
-    url: string;
+  /** The discovered URL. */
+  url: string;
 }
 /** Pagination details on a map response. */
 interface MapPagination {
-    page: number;
-    limit: number;
-    /** Total number of URLs in the stored map. */
-    total: number;
-    total_pages: number;
-    has_more: boolean;
+  page: number;
+  limit: number;
+  /** Total number of URLs in the stored map. */
+  total: number;
+  total_pages: number;
+  has_more: boolean;
 }
 /** Information about whether the stored or returned map was truncated. */
 interface MapTruncation {
-    /** Whether the stored map was capped by `max_urls`. */
-    storage_capped: boolean;
-    /** Whether the response was capped by pagination. */
-    response_capped: boolean;
-    /** Total URLs found before the `max_urls` cap was applied. */
-    total_before_max_urls: number;
-    /** Total URLs detected during discovery before the storage cap was applied. */
-    total_detected_before_storage_cap: number;
+  /** Whether the stored map was capped by `max_urls`. */
+  storage_capped: boolean;
+  /** Whether the response was capped by pagination. */
+  response_capped: boolean;
+  /** Total URLs found before the `max_urls` cap was applied. */
+  total_before_max_urls: number;
+  /** Total URLs detected during discovery before the storage cap was applied. */
+  total_detected_before_storage_cap: number;
 }
 /**
  * Response envelope for a map result: the shared {@link ResponseMeta} (`usage`)
  * plus the map-specific `pagination` and `truncation`.
  */
 interface MapResponseMeta extends ResponseMeta {
-    pagination: MapPagination;
-    truncation: MapTruncation;
+  pagination: MapPagination;
+  truncation: MapTruncation;
 }
 /** Success response from `POST /api/map`. */
 interface MapResponse {
-    /** The current page of discovered URLs. */
-    links: MapLinkItem[];
-    /** Usage, pagination, and truncation metadata for the result set. */
-    response_meta: MapResponseMeta;
+  /** The current page of discovered URLs. */
+  links: MapLinkItem[];
+  /** Usage, pagination, and truncation metadata for the result set. */
+  response_meta: MapResponseMeta;
 }
-
+//#endregion
+//#region src/types/async.d.ts
 /** Job lifecycle states for an async scrape. */
 type AsyncJobStatus = 'pending' | 'running' | 'done' | 'failed';
 /** Response body of `POST /api/scrape/async`. */
 interface AsyncScrapeResponse {
-    /** Job identifier — pass it to `getScrapeStatus` / `getScrapeResult`. */
-    job_id: string;
+  /** Job identifier — pass it to `getScrapeStatus` / `getScrapeResult`. */
+  job_id: string;
 }
 /** Response body of `GET /api/scrape/status/:jobId`. */
 interface AsyncJobStatusResponse {
-    /** The job identifier. */
-    job_id: string;
-    /** Current state of the job. */
-    status: AsyncJobStatus;
-    /** ISO-8601 UTC timestamp when the job was created. */
-    created_at: string;
-    /** Error message if the job ended in `failed`. */
-    error?: string;
-    /**
-     * Response envelope metadata — present only when the job has reached the
-     * terminal `done` state. Carries `usage` (credits charged, resolved proxy
-     * tier, and whether the result was a cache hit).
-     */
-    response_meta?: ResponseMeta;
+  /** The job identifier. */
+  job_id: string;
+  /** Current state of the job. */
+  status: AsyncJobStatus;
+  /** ISO-8601 UTC timestamp when the job was created. */
+  created_at: string;
+  /** Error message if the job ended in `failed`. */
+  error?: string;
+  /**
+   * Response envelope metadata — present only when the job has reached the
+   * terminal `done` state. Carries `usage` (credits charged, resolved proxy
+   * tier, and whether the result was a cache hit).
+   */
+  response_meta?: ResponseMeta;
 }
-
+//#endregion
+//#region src/types/account.d.ts
 /** Response from `GET /api/usage`. Current billing-cycle snapshot. */
 interface UsageResponse {
-    /**
-     * Total credits available for the current billing cycle
-     * (plan base + purchased + gifted).
-     */
-    total_credits: number;
-    /**
-     * Credits spent so far in the current billing cycle. May exceed
-     * `total_credits` on plans that allow overages.
-     */
-    used_credits: number;
-    /**
-     * Remaining credits, `max(0, total_credits - used_credits)`. Clamped to 0
-     * while in overage.
-     */
-    available_credits: number;
-    /**
-     * Percentage of `total_credits` used in the current cycle, rounded to one
-     * decimal. Not capped — values above 100 indicate overage.
-     */
-    used_quota_percent: number;
-    /**
-     * Maximum number of concurrent jobs allowed for the org
-     * (plan base + purchased + gifted extras).
-     */
-    max_concurrency: number;
-    /**
-     * ISO-8601 UTC timestamp when the current billing cycle ends and
-     * `used_credits` resets to 0.
-     */
-    usage_reset: string;
+  /**
+   * Total credits available for the current billing cycle
+   * (plan base + purchased + gifted).
+   */
+  total_credits: number;
+  /**
+   * Credits spent so far in the current billing cycle. May exceed
+   * `total_credits` on plans that allow overages.
+   */
+  used_credits: number;
+  /**
+   * Remaining credits, `max(0, total_credits - used_credits)`. Clamped to 0
+   * while in overage.
+   */
+  available_credits: number;
+  /**
+   * Percentage of `total_credits` used in the current cycle, rounded to one
+   * decimal. Not capped — values above 100 indicate overage.
+   */
+  used_quota_percent: number;
+  /**
+   * Maximum number of concurrent jobs allowed for the org
+   * (plan base + purchased + gifted extras).
+   */
+  max_concurrency: number;
+  /**
+   * ISO-8601 UTC timestamp when the current billing cycle ends and
+   * `used_credits` resets to 0.
+   */
+  usage_reset: string;
 }
 /** Response from `GET /api/whoami`. Identifies the calling API token. */
 interface WhoamiResponse {
-    /** Display name of the organization that owns the token. */
-    organization_name: string;
-    /** User-assigned name of the API token. */
-    token_name: string;
-    /** Truncated preview of the API token (e.g. `cwbl_…xyz`). Safe to display. */
-    token_preview: string;
+  /** Display name of the organization that owns the token. */
+  organization_name: string;
+  /** User-assigned name of the API token. */
+  token_name: string;
+  /** Truncated preview of the API token (e.g. `cwbl_…xyz`). Safe to display. */
+  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": "…",
- *     "metadata": { "tenant": "acme" },
- *     "response_meta": { "usage": { "credits": 1, "proxy": "basic", "cache_hit": false } }
- *   }
- * }
- * ```
- */
-
+//#endregion
+//#region src/types/webhooks.d.ts
 /** 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's
-     * `webhook.metadata`, if any.
-     */
-    metadata?: Record<string, unknown>;
-    /**
-     * Response envelope metadata — `usage` (credits charged, resolved proxy tier,
-     * and whether the result was a cache hit). Present only on `status: 'success'`
-     * deliveries; omitted for `failed` / `cancelled` (no usage was charged).
-     */
-    response_meta?: ResponseMeta;
+  /** 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's
+   * `webhook.metadata`, if any.
+   */
+  metadata?: Record<string, unknown>;
+  /**
+   * Response envelope metadata — `usage` (credits charged, resolved proxy tier,
+   * and whether the result was a cache hit). Present only on `status: 'success'`
+   * deliveries; omitted for `failed` / `cancelled` (no usage was charged).
+   */
+  response_meta?: ResponseMeta;
 }
 /**
  * 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;
+  /** 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;
 }
-
+//#endregion
+//#region src/client.d.ts
 /** Options accepted by the {@link Crawlbrulee} constructor. */
 interface CrawlbruleeOptions {
-    /**
-     * API key sent as `Authorization: Bearer <key>`. Required — to read from the
-     * environment instead, use {@link Crawlbrulee.fromEnv}. Leading and trailing
-     * whitespace is stripped; an empty / whitespace-only value is rejected.
-     */
-    apiKey: string;
-    /**
-     * Override the base URL the SDK targets. Defaults to the production host
-     * ({@link DEFAULT_BASE_URL}). Intended for local development and staging
-     * (e.g. `https://api.staging.crawlbrulee.com`) — production callers should
-     * leave it unset. Trailing slashes are stripped.
-     */
-    baseUrl?: string;
-    /**
-     * Per-request timeout in milliseconds. Defaults to `0` (no timeout). Set to a
-     * positive number to abort slow requests; a per-call `timeoutMs` override
-     * takes precedence. The timeout covers the WHOLE request, including the
-     * response body read.
-     */
-    timeoutMs?: number;
+  /**
+   * API key sent as `Authorization: Bearer <key>`. Required — to read from the
+   * environment instead, use {@link Crawlbrulee.fromEnv}. Leading and trailing
+   * whitespace is stripped; an empty / whitespace-only value is rejected.
+   */
+  apiKey: string;
+  /**
+   * Override the base URL the SDK targets. Defaults to the production host
+   * ({@link DEFAULT_BASE_URL}). Intended for local development and staging
+   * (e.g. `https://api.staging.crawlbrulee.com`) — production callers should
+   * leave it unset. Trailing slashes are stripped.
+   */
+  baseUrl?: string;
+  /**
+   * Per-request timeout in milliseconds. Defaults to `0` (no timeout). Set to a
+   * positive number to abort slow requests; a per-call `timeoutMs` override
+   * takes precedence. The timeout covers the WHOLE request, including the
+   * response body read.
+   */
+  timeoutMs?: number;
 }
 /**
  * Options accepted by {@link Crawlbrulee.waitForScrape}.
@@ -715,13 +699,13 @@ interface CrawlbruleeOptions {
  * the client with `timeoutMs` set.
  */
 interface WaitForScrapeOptions extends Omit<RequestOptions, 'timeoutMs'> {
-    /** Time between status polls in milliseconds. Default `2000`. */
-    intervalMs?: number;
-    /**
-     * Maximum total time to wait before giving up, in milliseconds. Default
-     * `300_000` (5 minutes). Pass `0` to wait indefinitely.
-     */
-    timeoutMs?: number;
+  /** Time between status polls in milliseconds. Default `2000`. */
+  intervalMs?: number;
+  /**
+   * Maximum total time to wait before giving up, in milliseconds. Default
+   * `300_000` (5 minutes). Pass `0` to wait indefinitely.
+   */
+  timeoutMs?: number;
 }
 /**
  * Official client for the crawlbrulee API.
@@ -742,102 +726,103 @@ interface WaitForScrapeOptions extends Omit<RequestOptions, 'timeoutMs'> {
  * ```
  */
 declare class Crawlbrulee {
-    /** Resolved base URL — trailing slash already stripped. */
-    readonly baseUrl: string;
-    /** Underlying HTTP layer. Exposed for advanced use cases (custom endpoints). */
-    readonly http: HttpClient;
-    constructor(options: CrawlbruleeOptions);
-    /**
-     * Build a {@link Crawlbrulee} reading the API key from
-     * `process.env.CRAWLBRULEE_API_KEY`. Throws if the variable is unset, empty,
-     * or whitespace.
-     *
-     * Any other constructor option can be passed via `overrides`.
-     *
-     * @example
-     * ```ts
-     * const crawlbrulee = Crawlbrulee.fromEnv()
-     * const crawlbrulee = Crawlbrulee.fromEnv({ timeoutMs: 30_000 })
-     * ```
-     */
-    static fromEnv(overrides?: Omit<CrawlbruleeOptions, 'apiKey'>): Crawlbrulee;
-    /**
-     * Scrape a URL synchronously and return the extracted content.
-     *
-     * The request blocks until the scrape is finished. For long-running jobs
-     * (heavy JS rendering, screenshots of long pages) prefer
-     * {@link Crawlbrulee.scrapeAsync} so the connection isn't held open.
-     *
-     * @param request — body for `POST /api/scrape`.
-     * @param options — per-call timeout and abort signal.
-     */
-    scrape(request: ScrapeRequest, options?: RequestOptions): Promise<ScrapeResponse>;
-    /**
-     * 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: AsyncScrapeRequest, options?: RequestOptions): Promise<AsyncScrapeResponse>;
-    /** Look up the current status of an async scrape job. */
-    getScrapeStatus(jobId: string, options?: RequestOptions): Promise<AsyncJobStatusResponse>;
-    /**
-     * Fetch the result of a completed async scrape job. Throws if the job is
-     * still pending/running — call {@link Crawlbrulee.getScrapeStatus}
-     * 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.
-     *
-     * Throws a {@link CrawlbruleeError} when:
-     * - the job ends in `failed` (`errorName: 'job_failed'`),
-     * - the server reports an unexpected status (`errorName: 'job_failed'`),
-     * - the overall wait exceeds `timeoutMs` (`errorName: 'request_timeout'`),
-     * - the caller's `signal` aborts (`errorName: 'client_closed_request'`).
-     */
-    waitForScrape(jobId: string, options?: WaitForScrapeOptions): Promise<ScrapeResponse>;
-    /**
-     * Build (or return a cached) site link-map for a domain. Combines sitemap
-     * discovery with the freshest cached homepage scrape when available.
-     */
-    map(request: MapRequest, options?: RequestOptions): Promise<MapResponse>;
-    /**
-     * Return the current billing-cycle usage: total/used/available credits,
-     * used quota percentage, max concurrency, and when the cycle resets.
-     */
-    usage(options?: RequestOptions): Promise<UsageResponse>;
-    /**
-     * Return the organization name and identifying details of the API token
-     * used to authenticate this request. Useful for confirming which key is in
-     * use before performing destructive operations.
-     */
-    whoami(options?: RequestOptions): Promise<WhoamiResponse>;
+  /** Resolved base URL — trailing slash already stripped. */
+  readonly baseUrl: string;
+  /** Underlying HTTP layer. Exposed for advanced use cases (custom endpoints). */
+  readonly http: HttpClient;
+  constructor(options: CrawlbruleeOptions);
+  /**
+   * Build a {@link Crawlbrulee} reading the API key from
+   * `process.env.CRAWLBRULEE_API_KEY`. Throws if the variable is unset, empty,
+   * or whitespace.
+   *
+   * Any other constructor option can be passed via `overrides`.
+   *
+   * @example
+   * ```ts
+   * const crawlbrulee = Crawlbrulee.fromEnv()
+   * const crawlbrulee = Crawlbrulee.fromEnv({ timeoutMs: 30_000 })
+   * ```
+   */
+  static fromEnv(overrides?: Omit<CrawlbruleeOptions, 'apiKey'>): Crawlbrulee;
+  /**
+   * Scrape a URL synchronously and return the extracted content.
+   *
+   * The request blocks until the scrape is finished. For long-running jobs
+   * (heavy JS rendering, screenshots of long pages) prefer
+   * {@link Crawlbrulee.scrapeAsync} so the connection isn't held open.
+   *
+   * @param request — body for `POST /api/scrape`.
+   * @param options — per-call timeout and abort signal.
+   */
+  scrape(request: ScrapeRequest, options?: RequestOptions): Promise<ScrapeResponse>;
+  /**
+   * 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: AsyncScrapeRequest, options?: RequestOptions): Promise<AsyncScrapeResponse>;
+  /** Look up the current status of an async scrape job. */
+  getScrapeStatus(jobId: string, options?: RequestOptions): Promise<AsyncJobStatusResponse>;
+  /**
+   * Fetch the result of a completed async scrape job. Throws if the job is
+   * still pending/running — call {@link Crawlbrulee.getScrapeStatus}
+   * 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.
+   *
+   * Throws a {@link CrawlbruleeError} when:
+   * - the job ends in `failed` (`errorName: 'job_failed'`),
+   * - the server reports an unexpected status (`errorName: 'job_failed'`),
+   * - the overall wait exceeds `timeoutMs` (`errorName: 'request_timeout'`),
+   * - the caller's `signal` aborts (`errorName: 'client_closed_request'`).
+   */
+  waitForScrape(jobId: string, options?: WaitForScrapeOptions): Promise<ScrapeResponse>;
+  /**
+   * Build (or return a cached) site link-map for a domain. Combines sitemap
+   * discovery with the freshest cached homepage scrape when available.
+   */
+  map(request: MapRequest, options?: RequestOptions): Promise<MapResponse>;
+  /**
+   * Return the current billing-cycle usage: total/used/available credits,
+   * used quota percentage, max concurrency, and when the cycle resets.
+   */
+  usage(options?: RequestOptions): Promise<UsageResponse>;
+  /**
+   * Return the organization name and identifying details of the API token
+   * used to authenticate this request. Useful for confirming which key is in
+   * use before performing destructive operations.
+   */
+  whoami(options?: RequestOptions): Promise<WhoamiResponse>;
 }
-
+//#endregion
+//#region src/errors.d.ts
 /**
  * Base error class for every failure raised by the SDK.
  *
@@ -856,29 +841,29 @@ declare class Crawlbrulee {
  * {@link isCrawlbruleeError} helper.
  */
 declare class CrawlbruleeError extends Error {
-    /** HTTP status code; `0` for transport-level failures with no response. */
-    readonly status: number;
-    /** The `name` field from the API error body, or `null` for transport errors. */
-    readonly errorName: ApiErrorName | null;
-    /** Structured detail block from the API error body, if any. */
-    readonly details?: ApiErrorDetails;
-    /** The original parsed error body, when one was received. */
-    readonly response?: ApiErrorResponse;
-    constructor(message: string, options: {
-        status: number;
-        errorName: ApiErrorName | null;
-        details?: ApiErrorDetails;
-        response?: ApiErrorResponse;
-        cause?: unknown;
-    });
+  /** HTTP status code; `0` for transport-level failures with no response. */
+  readonly status: number;
+  /** The `name` field from the API error body, or `null` for transport errors. */
+  readonly errorName: ApiErrorName | null;
+  /** Structured detail block from the API error body, if any. */
+  readonly details?: ApiErrorDetails;
+  /** The original parsed error body, when one was received. */
+  readonly response?: ApiErrorResponse;
+  constructor(message: string, options: {
+    status: number;
+    errorName: ApiErrorName | null;
+    details?: ApiErrorDetails;
+    response?: ApiErrorResponse;
+    cause?: unknown;
+  });
 }
 /** Raised for 401 / 403 responses (missing, invalid, or unauthorized API key). */
 declare class AuthenticationError extends CrawlbruleeError {
-    constructor(message: string, options: {
-        status: number;
-        errorName: ApiErrorName;
-        response?: ApiErrorResponse;
-    });
+  constructor(message: string, options: {
+    status: number;
+    errorName: ApiErrorName;
+    response?: ApiErrorResponse;
+  });
 }
 /**
  * Raised for HTTP 429 responses. When the server included a `retry_after_ms`
@@ -890,16 +875,16 @@ declare class AuthenticationError extends CrawlbruleeError {
  * available on `response`.
  */
 declare class RateLimitError extends CrawlbruleeError {
-    readonly errorName: 'too_many_requests';
-    /** Suggested delay (ms) before retrying, when the server provided one. */
-    readonly retryAfterMs?: number;
-    /** Which rate limit was tripped (e.g. `org`, `ip`), when provided. */
-    readonly limitedBy?: string;
-    constructor(message: string, options: {
-        status: number;
-        details?: RateLimitErrorDetails;
-        response?: ApiErrorResponse;
-    });
+  readonly errorName: 'too_many_requests';
+  /** Suggested delay (ms) before retrying, when the server provided one. */
+  readonly retryAfterMs?: number;
+  /** Which rate limit was tripped (e.g. `org`, `ip`), when provided. */
+  readonly limitedBy?: string;
+  constructor(message: string, options: {
+    status: number;
+    details?: RateLimitErrorDetails;
+    response?: ApiErrorResponse;
+  });
 }
 /**
  * Raised when the API rejects a request because the org's plan limits would
@@ -908,32 +893,32 @@ declare class RateLimitError extends CrawlbruleeError {
  * `errorName` is always the literal `'usage_allocation_error'`.
  */
 declare class UsageAllocationError extends CrawlbruleeError {
-    readonly errorName: 'usage_allocation_error';
-    /** Specific reason the allocation was denied. */
-    readonly reason: UsageAllocationErrorDetails['reason'];
-    /** Current usage / limit snapshot at the time of the rejection. */
-    readonly usage?: UsageAllocationErrorDetails['details'];
-    constructor(message: string, options: {
-        status: number;
-        details: UsageAllocationErrorDetails;
-        response?: ApiErrorResponse;
-    });
+  readonly errorName: 'usage_allocation_error';
+  /** Specific reason the allocation was denied. */
+  readonly reason: UsageAllocationErrorDetails['reason'];
+  /** Current usage / limit snapshot at the time of the rejection. */
+  readonly usage?: UsageAllocationErrorDetails['details'];
+  constructor(message: string, options: {
+    status: number;
+    details: UsageAllocationErrorDetails;
+    response?: ApiErrorResponse;
+  });
 }
 /** Raised for 4xx responses caused by an invalid request shape or arguments. */
 declare class ValidationError extends CrawlbruleeError {
-    constructor(message: string, options: {
-        status: number;
-        errorName: ApiErrorName;
-        response?: ApiErrorResponse;
-    });
+  constructor(message: string, options: {
+    status: number;
+    errorName: ApiErrorName;
+    response?: ApiErrorResponse;
+  });
 }
 /** Raised for 404 responses (e.g. unknown async job ID). */
 declare class NotFoundError extends CrawlbruleeError {
-    constructor(message: string, options: {
-        status: number;
-        errorName: ApiErrorName;
-        response?: ApiErrorResponse;
-    });
+  constructor(message: string, options: {
+    status: number;
+    errorName: ApiErrorName;
+    response?: ApiErrorResponse;
+  });
 }
 /**
  * Raised when a request cannot be sent or no structured response is parsed.
@@ -944,15 +929,16 @@ declare class NotFoundError extends CrawlbruleeError {
  * - `null` — generic transport failure (network error, non-JSON body, etc.).
  */
 declare class TransportError extends CrawlbruleeError {
-    constructor(message: string, options?: {
-        status?: number;
-        errorName?: 'request_timeout' | 'client_closed_request' | null;
-        cause?: unknown;
-    });
+  constructor(message: string, options?: {
+    status?: number;
+    errorName?: 'request_timeout' | 'client_closed_request' | null;
+    cause?: unknown;
+  });
 }
 /** Narrow `unknown` to the SDK's base error type. */
 declare function isCrawlbruleeError(err: unknown): err is CrawlbruleeError;
-
+//#endregion
+//#region src/config.d.ts
 /**
  * Production base URL of the crawlbrulee API. Used by default when the caller
  * doesn't pass a `baseUrl` to {@link Crawlbrulee}. Local development and
@@ -963,7 +949,8 @@ declare const DEFAULT_BASE_URL = "https://api.crawlbrulee.com";
 declare const DEFAULT_REQUEST_TIMEOUT_MS = 0;
 /** Environment variable read by `Crawlbrulee.fromEnv()` to source the API key. */
 declare const ENV_API_KEY = "CRAWLBRULEE_API_KEY";
-
+//#endregion
+//#region src/webhooks.d.ts
 /**
  * Verification for async scrape completion webhooks.
  *
@@ -999,33 +986,33 @@ type WebhookSignatureSource = 'primary' | 'rotated';
 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: true;
+  signedWith: WebhookSignatureSource;
 } | {
-    verified: false;
-    reason: WebhookVerificationFailureReason;
+  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;
+  /**
+   * 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
@@ -1055,5 +1042,6 @@ interface VerifyWebhookSignatureOptions {
  * ```
  */
 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 MapResponseMeta, type MapTruncation, type MapTypes, NotFoundError, type PageInlineImage, type PageLink, type ProxyTier, RateLimitError, type RateLimitErrorDetails, type RequestOptions, type ResolvedProxyTier, type ResponseMeta, 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, type Usage, 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 };
+//#endregion
+export { ApiErrorDetails, ApiErrorName, ApiErrorResponse, AsyncJobStatus, AsyncJobStatusResponse, AsyncScrapeRequest, AsyncScrapeResponse, AsyncScrapeWebhook, AuthenticationError, Crawlbrulee, CrawlbruleeError, type CrawlbruleeOptions, DEFAULT_BASE_URL, DEFAULT_REQUEST_TIMEOUT_MS, DEFAULT_WEBHOOK_TOLERANCE_SECONDS, ENV_API_KEY, type HttpMethod, MapCache, MapLinkItem, MapLocation, MapPagination, MapRequest, MapResponse, MapResponseMeta, MapTruncation, MapTypes, NotFoundError, PageInlineImage, PageLink, ProxyTier, RateLimitError, RateLimitErrorDetails, type RequestOptions, ResolvedProxyTier, ResponseMeta, ScrapeCache, ScrapeCompleteWebhook, ScrapeCompleteWebhookData, ScrapeExtract, ScrapeLocation, ScrapeMetadata, ScrapeRequest, ScrapeResponse, ScrapeWebhookStatus, ScreenshotAfterAction, ScreenshotBeforeAction, ScreenshotCleanup, ScreenshotDeviceMode, ScreenshotProperties, ScreenshotRequest, ScreenshotResult, ScreenshotScrollAction, ScreenshotSlice, ScreenshotSliceAction, ScreenshotType, ScreenshotViewport, ScreenshotViewportInfo, ScreenshotWaitAction, TransportError, Usage, UsageAllocationError, UsageAllocationErrorDetails, UsageAllocationReason, UsageLimitDetails, UsageResponse, ValidationError, type VerifyWebhookSignatureOptions, WEBHOOK_EVENT_ID_HEADER, WEBHOOK_SIGNATURE_HEADER, WEBHOOK_SIGNATURE_ROTATED_HEADER, type WaitForScrapeOptions, type WebhookSignatureSource, type WebhookVerificationFailureReason, type WebhookVerificationResult, WhoamiResponse, isCrawlbruleeError, verifyWebhookSignature };
+//# sourceMappingURL=index.d.cts.map