@crawlbrulee/sdk 0.1.0

package/dist/index.d.ts

@@ -0,0 +1,781 @@
+/** HTTP methods used by the SDK. */
+type HttpMethod = 'GET' | 'POST';
+/** Options the SDK accepts at construction time for the HTTP layer. */
+interface HttpClientOptions {
+    /** Base URL of the API (trailing slash is stripped). */
+    baseUrl: string;
+    /** API key sent as `Authorization: Bearer <key>`. */
+    apiKey: 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;
+}
+/**
+ * Minimal `fetch`-based HTTP layer used by {@link Crawlbrulee}. Handles:
+ *
+ * - URL composition (joining `baseUrl` and path safely).
+ * - JSON serialization and parsing.
+ * - The `Authorization: Bearer …` header.
+ * - Composing the caller's `AbortSignal` with an internal timeout signal. The
+ *   timeout covers the WHOLE request, including the response body read — not
+ *   just the time-to-headers.
+ * - Mapping non-2xx responses to typed `CrawlbruleeError` subclasses via
+ *   {@link createApiError}.
+ *
+ * The `fetch` implementation is sourced from {@link CwblInstrumentation} at
+ * construction time so tests can stub the module.
+ */
+declare class HttpClient {
+    private readonly baseUrl;
+    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;
+}
+
+/**
+ * Shared primitive types used across crawlbrulee request and response shapes.
+ */
+/**
+ * Proxy tier used to route the fetch.
+ *
+ * - `basic` — datacenter proxy, lowest cost (default).
+ * - `advanced` — residential proxy, higher success rate on protected sites.
+ * - `auto` — let crawlbrulee pick the right tier per target.
+ * - `none` — skip the proxy entirely. Rejected in production; available on
+ *   staging only as a debug/perf-test toggle.
+ */
+type ProxyTier = 'basic' | 'advanced' | 'auto' | 'none';
+/** Screenshot capture mode: visible viewport or the full scrollable page. */
+type ScreenshotType = 'viewport' | 'full_page';
+/** Emulated device class for the viewport (drives default width/height). */
+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;
+}
+/** 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;
+}
+/** 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;
+}
+/**
+ * Actions performed before the screenshot is taken. The server caps the total
+ * wait time (~20 s) and total absolute scroll distance (~50 000 px) across
+ * the array; at most 5 actions are accepted.
+ */
+type ScreenshotBeforeAction = ScreenshotWaitAction | ScreenshotScrollAction;
+/**
+ * Action performed after the screenshot is taken. Currently only `slice` is
+ * supported — it cuts the screenshot into horizontal tiles of `height` px.
+ */
+interface ScreenshotSliceAction {
+    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. */
+    width: number;
+    /** Viewport height in pixels. */
+    height: number;
+    /** Device pixel ratio (e.g. 2 for retina). 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[];
+}
+/**
+ * Machine-readable error names returned by the crawlbrulee API. Stable
+ * identifiers — clients can switch on them.
+ */
+type ApiErrorName = 'usage_allocation_error' | 'request_timeout' | 'invalid_url' | 'url_too_long' | 'client_closed_request' | 'reset_password_token_expired' | 'user_not_found' | 'unsupported_url_schema' | 'url_credentials_not_supported' | 'blocked_url' | 'scrape_error' | 'job_failed' | 'incorrect_login_method_used' | 'not_found' | 'invalid_credentials' | 'resource_already_exists' | 'access_denied' | 'internal_server_error' | 'too_many_requests' | 'unsupported_content' | 'validation_error' | 'antibot_blocked';
+/** Reason a usage allocation was denied (when `error_name = usage_allocation_error`). */
+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;
+}
+/** Discriminated detail for `error_name = usage_allocation_error`. */
+interface UsageAllocationErrorDetails {
+    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;
+}
+/** 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;
+}
+
+/**
+ * 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`. */
+    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;
+}
+/** 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;
+}
+/** 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 `basic`. */
+    proxy?: ProxyTier;
+    /** Optional locale + country emulation. */
+    location?: ScrapeLocation;
+}
+/** Viewport metadata returned alongside a captured screenshot. */
+interface ScreenshotViewportInfo {
+    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;
+}
+/** 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;
+}
+/** 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[];
+}
+/** A single inline image discovered on the page. */
+interface PageInlineImage {
+    /** Absolute URL of the image. */
+    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;
+}
+/** 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;
+}
+/** 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`). */
+    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[];
+}
+
+/** 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;
+}
+/** 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;
+}
+/** 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;
+}
+/** Request body for `POST /api/map`. */
+interface MapRequest {
+    /** The website URL to map. */
+    url: string;
+    /** Proxy tier to use for fetching. Defaults to `basic`. */
+    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;
+}
+/** 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;
+}
+/** 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;
+}
+/** Success response from `POST /api/map`. */
+interface MapResponse {
+    /** The current page of discovered URLs. */
+    links: MapLinkItem[];
+    /** Pagination + truncation metadata for the result set. */
+    meta: {
+        pagination: MapPagination;
+        truncation: MapTruncation;
+    };
+}
+
+/** 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;
+}
+/**
+ * Response body of `GET /api/scrape/status/:jobId`.
+ *
+ * Note: this response uses camelCase field names (`jobId`, `createdAt`) while
+ * most other crawlbrulee responses use snake_case (e.g. `job_id` on
+ * {@link AsyncScrapeResponse}, `total_credits` on `UsageResponse`). The SDK
+ * mirrors the wire format faithfully — if the inconsistency trips you up,
+ * destructure with explicit names.
+ */
+interface AsyncJobStatusResponse {
+    /** The job identifier. */
+    jobId: string;
+    /** Current state of the job. */
+    status: AsyncJobStatus;
+    /** ISO-8601 UTC timestamp when the job was created. */
+    createdAt: string;
+    /** Error message if the job ended in `failed`. */
+    error?: string;
+}
+
+/** 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;
+}
+/** 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. `cble_…xyz`). Safe to display. */
+    token_preview: string;
+}
+
+/** 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;
+    /**
+     * @internal
+     * Override the base URL. Reserved for local development and tests — production
+     * always uses the burned-in {@link DEFAULT_BASE_URL}. 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}.
+ *
+ * Note: `timeoutMs` here is the OVERALL wait budget across all polls — not the
+ * per-HTTP-request timeout. The per-poll HTTP timeout is whatever the client
+ * was constructed with; if you want to bound each individual poll, construct
+ * 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;
+}
+/**
+ * Official client for the crawlbrulee API.
+ *
+ * @example
+ * ```ts
+ * import { Crawlbrulee } from '@crawlbrulee/sdk'
+ *
+ * const crawlbrulee = new Crawlbrulee({ apiKey: 'cble_…' })
+ * // or read CRAWLBRULEE_API_KEY from the environment:
+ * const crawlbrulee = Crawlbrulee.fromEnv()
+ *
+ * const page = await crawlbrulee.scrape({
+ *   url: 'https://example.com',
+ *   extract: { markdown: true, links: true },
+ * })
+ * console.log(page.markdown)
+ * ```
+ */
+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}.
+     */
+    scrapeAsync(request: ScrapeRequest, 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>;
+    /**
+     * 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>;
+}
+
+/**
+ * Base error class for every failure raised by the SDK.
+ *
+ * Two kinds of failures end up here:
+ *
+ * 1. **API errors** — the server returned a non-2xx response with a well-formed
+ *    JSON body. In that case `status`, `errorName` and (sometimes) `details`
+ *    are populated.
+ * 2. **Transport errors** — the request never produced a structured response
+ *    (network failure, abort, timeout, non-JSON body, etc.). In that case
+ *    `status` may be `0` and `errorName` is one of the synthetic transport
+ *    names (`request_timeout`, `client_closed_request`) or `null`.
+ *
+ * Typed subclasses are exported for the most common cases. To branch on more
+ * specific server-side errors, switch on `err.errorName` or use the
+ * {@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;
+    });
+}
+/** 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;
+    });
+}
+/**
+ * Raised for HTTP 429 responses. When the server included a `retry_after_ms`
+ * hint in `details` it is surfaced directly on the instance.
+ *
+ * `errorName` is always the literal `'too_many_requests'` — the SDK normalizes
+ * this even when the server returns a 429 with a different `name` field
+ * (e.g. a CDN coalescing upstream rate limiting). The original body is still
+ * 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;
+    });
+}
+/**
+ * Raised when the API rejects a request because the org's plan limits would
+ * be exceeded (credit limit, concurrency cap, overage hard cap, etc.).
+ *
+ * `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;
+    });
+}
+/** 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;
+    });
+}
+/** 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;
+    });
+}
+/**
+ * Raised when a request cannot be sent or no structured response is parsed.
+ *
+ * The `errorName` discriminates the cause:
+ * - `'request_timeout'` — the per-request timeout fired.
+ * - `'client_closed_request'` — the caller's `AbortSignal` fired.
+ * - `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;
+    });
+}
+/** Narrow `unknown` to the SDK's base error type. */
+declare function isCrawlbruleeError(err: unknown): err is CrawlbruleeError;
+
+/**
+ * Production base URL of the crawlbrulee API. Burned in at build time —
+ * customers always hit production. The base URL is intentionally not
+ * configurable via env var; tests and local development override it through
+ * the `baseUrl` constructor option (marked `@internal`).
+ */
+declare const DEFAULT_BASE_URL = "https://api.crawlbrulee.com";
+/** Default request timeout (60 s) when the caller doesn't specify one. */
+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 };