@crawlbrulee/sdk 0.3.0 → 0.6.0

package/dist/index.d.cts

@@ -70,13 +70,46 @@ declare class HttpClient {
 /**
  * Proxy tier used to route the fetch.
  *
- * - `basic` — datacenter proxy, lowest cost (default).
+ * - `basic` — datacenter proxy, lowest cost.
  * - `advanced` — residential proxy, higher success rate on protected sites.
- * - `auto` — let crawlbrulee pick the right tier per target.
+ * - `auto` — start at the basic tier and escalate to advanced on failure;
+ *   billed at the delivered tier. This is the default when `proxy` is omitted.
  * - `none` — skip the proxy entirely. Rejected in production; available on
  *   staging only as a debug/perf-test toggle.
  */
 type ProxyTier = 'basic' | 'advanced' | 'auto' | 'none';
+/**
+ * Proxy tier the server actually used to route a fetch, as reported back in
+ * {@link Usage.proxy}. Unlike the request-side {@link ProxyTier}, this never
+ * includes `auto` — when a request asks for `auto`, the server resolves it to a
+ * concrete tier and echoes the resolved value here.
+ */
+type ResolvedProxyTier = 'none' | 'basic' | 'advanced';
+/**
+ * Usage accounting for a single billable operation, returned on the response
+ * envelope of scrape, map, and async-status (when terminal). All crawlbrulee
+ * 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;
+}
+/**
+ * Response envelope `response_meta` carried by scrape responses and async-status
+ * responses (terminal state only). Currently exposes {@link Usage}; map
+ * responses extend this shape with `pagination` + `truncation`.
+ */
+interface ResponseMeta {
+    /** Usage accounting for the operation. */
+    usage: Usage;
+}
 /** 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). */
@@ -119,11 +152,14 @@ interface ScreenshotSliceAction {
 type ScreenshotAfterAction = ScreenshotSliceAction;
 /** Custom browser viewport dimensions used during a screenshot capture. */
 interface ScreenshotViewport {
-    /** Viewport width in pixels. */
+    /** Viewport width in pixels. Integer in `[16, 10000]`; out-of-range values are rejected with a 400. */
     width: number;
-    /** Viewport height in pixels. */
+    /** 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). Defaults to 1 server-side. */
+    /**
+     * 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`. */
@@ -203,7 +239,11 @@ interface ScrapeExtract {
     raw_html?: boolean;
     /** Extract all links found on the page. Default `false`. */
     links?: boolean;
-    /** Extract all inline images found on the page. Default `false`. */
+    /**
+     * 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;
@@ -250,7 +290,10 @@ interface ScrapeRequest {
     require_js?: boolean;
     /** CSS selectors to strip from the extracted content. */
     exclude_selectors?: string[];
-    /** Proxy tier to use for fetching. Defaults to `basic`. */
+    /**
+     * 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;
@@ -331,7 +374,10 @@ interface ScreenshotResult {
 }
 /** A single inline image discovered on the page. */
 interface PageInlineImage {
-    /** Absolute URL of the image. */
+    /**
+     * 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;
@@ -391,7 +437,12 @@ interface ScrapeResponse {
     images?: PageInlineImage[];
     /** Links discovered on the page (when `extract.links`). */
     links?: PageLink[];
-    /** Captured screenshot (when `extract.screenshot`). */
+    /**
+     * 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;
@@ -402,6 +453,11 @@ interface ScrapeResponse {
      * 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;
 }
 
 /** Filter which link types appear in the map result. */
@@ -430,7 +486,10 @@ interface MapLocation {
 interface MapRequest {
     /** The website URL to map. */
     url: string;
-    /** Proxy tier to use for fetching. Defaults to `basic`. */
+    /**
+     * 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;
@@ -477,15 +536,20 @@ interface MapTruncation {
     /** 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;
+}
 /** 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;
-    };
+    /** Usage, pagination, and truncation metadata for the result set. */
+    response_meta: MapResponseMeta;
 }
 
 /** Job lifecycle states for an async scrape. */
@@ -495,24 +559,22 @@ 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.
- */
+/** Response body of `GET /api/scrape/status/:jobId`. */
 interface AsyncJobStatusResponse {
     /** The job identifier. */
-    jobId: string;
+    job_id: string;
     /** Current state of the job. */
     status: AsyncJobStatus;
     /** ISO-8601 UTC timestamp when the job was created. */
-    createdAt: string;
+    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;
 }
 
 /** Response from `GET /api/usage`. Current billing-cycle snapshot. */
@@ -554,7 +616,7 @@ interface WhoamiResponse {
     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. */
+    /** Truncated preview of the API token (e.g. `cwbl_…xyz`). Safe to display. */
     token_preview: string;
 }
 
@@ -570,10 +632,18 @@ interface WhoamiResponse {
  *   "event_id": "evt_…",
  *   "timestamp": "2026-06-13T12:00:00.000Z",
  *   "event": "scrape.complete",
- *   "data": { "job_id": "job_…", "status": "success", "url": "https://…", "completed_at": "…" }
+ *   "data": {
+ *     "job_id": "job_…",
+ *     "status": "success",
+ *     "url": "https://…",
+ *     "completed_at": "…",
+ *     "metadata": { "tenant": "acme" },
+ *     "response_meta": { "usage": { "credits": 1, "proxy": "basic", "cache_hit": false } }
+ *   }
  * }
  * ```
  */
+
 /** Terminal status carried by a {@link ScrapeCompleteWebhook}. */
 type ScrapeWebhookStatus = 'success' | 'failed' | 'cancelled';
 /** `data` block of a {@link ScrapeCompleteWebhook}. */
@@ -588,8 +658,17 @@ interface ScrapeCompleteWebhookData {
     completed_at: string;
     /** Failure message — present only when `status === 'failed'`. */
     error?: string;
-    /** Correlation data echoed back from the original scrape request, if any. */
+    /**
+     * 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`
@@ -653,7 +732,7 @@ interface WaitForScrapeOptions extends Omit<RequestOptions, 'timeoutMs'> {
  * ```ts
  * import { Crawlbrulee } from '@crawlbrulee/sdk'
  *
- * const crawlbrulee = new Crawlbrulee({ apiKey: 'cble_…' })
+ * const crawlbrulee = new Crawlbrulee({ apiKey: 'cwbl_…' })
  * // or read CRAWLBRULEE_API_KEY from the environment:
  * const crawlbrulee = Crawlbrulee.fromEnv()
  *
@@ -882,8 +961,8 @@ declare function isCrawlbruleeError(err: unknown): err is CrawlbruleeError;
  * staging callers point at their own host via that option.
  */
 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;
+/** Default request timeout when the caller doesn't specify one (0 disables the timeout). */
+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";
 
@@ -979,4 +1058,4 @@ 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 MapTruncation, type MapTypes, NotFoundError, type PageInlineImage, type PageLink, type ProxyTier, RateLimitError, type RateLimitErrorDetails, type RequestOptions, type ScrapeCache, type ScrapeCompleteWebhook, type ScrapeCompleteWebhookData, type ScrapeExtract, type ScrapeLocation, type ScrapeMetadata, type ScrapeRequest, type ScrapeResponse, type ScrapeWebhookStatus, type ScreenshotAfterAction, type ScreenshotBeforeAction, type ScreenshotCleanup, type ScreenshotDeviceMode, type ScreenshotProperties, type ScreenshotRequest, type ScreenshotResult, type ScreenshotScrollAction, type ScreenshotSlice, type ScreenshotSliceAction, type ScreenshotType, type ScreenshotViewport, type ScreenshotViewportInfo, type ScreenshotWaitAction, TransportError, UsageAllocationError, type UsageAllocationErrorDetails, type UsageAllocationReason, type UsageLimitDetails, type UsageResponse, ValidationError, type VerifyWebhookSignatureOptions, WEBHOOK_EVENT_ID_HEADER, WEBHOOK_SIGNATURE_HEADER, WEBHOOK_SIGNATURE_ROTATED_HEADER, type WaitForScrapeOptions, type WebhookSignatureSource, type WebhookVerificationFailureReason, type WebhookVerificationResult, type WhoamiResponse, isCrawlbruleeError, verifyWebhookSignature };
+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 };

package/dist/index.d.ts

@@ -70,13 +70,46 @@ declare class HttpClient {
 /**
  * Proxy tier used to route the fetch.
  *
- * - `basic` — datacenter proxy, lowest cost (default).
+ * - `basic` — datacenter proxy, lowest cost.
  * - `advanced` — residential proxy, higher success rate on protected sites.
- * - `auto` — let crawlbrulee pick the right tier per target.
+ * - `auto` — start at the basic tier and escalate to advanced on failure;
+ *   billed at the delivered tier. This is the default when `proxy` is omitted.
  * - `none` — skip the proxy entirely. Rejected in production; available on
  *   staging only as a debug/perf-test toggle.
  */
 type ProxyTier = 'basic' | 'advanced' | 'auto' | 'none';
+/**
+ * Proxy tier the server actually used to route a fetch, as reported back in
+ * {@link Usage.proxy}. Unlike the request-side {@link ProxyTier}, this never
+ * includes `auto` — when a request asks for `auto`, the server resolves it to a
+ * concrete tier and echoes the resolved value here.
+ */
+type ResolvedProxyTier = 'none' | 'basic' | 'advanced';
+/**
+ * Usage accounting for a single billable operation, returned on the response
+ * envelope of scrape, map, and async-status (when terminal). All crawlbrulee
+ * 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;
+}
+/**
+ * Response envelope `response_meta` carried by scrape responses and async-status
+ * responses (terminal state only). Currently exposes {@link Usage}; map
+ * responses extend this shape with `pagination` + `truncation`.
+ */
+interface ResponseMeta {
+    /** Usage accounting for the operation. */
+    usage: Usage;
+}
 /** 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). */
@@ -119,11 +152,14 @@ interface ScreenshotSliceAction {
 type ScreenshotAfterAction = ScreenshotSliceAction;
 /** Custom browser viewport dimensions used during a screenshot capture. */
 interface ScreenshotViewport {
-    /** Viewport width in pixels. */
+    /** Viewport width in pixels. Integer in `[16, 10000]`; out-of-range values are rejected with a 400. */
     width: number;
-    /** Viewport height in pixels. */
+    /** 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). Defaults to 1 server-side. */
+    /**
+     * 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`. */
@@ -203,7 +239,11 @@ interface ScrapeExtract {
     raw_html?: boolean;
     /** Extract all links found on the page. Default `false`. */
     links?: boolean;
-    /** Extract all inline images found on the page. Default `false`. */
+    /**
+     * 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;
@@ -250,7 +290,10 @@ interface ScrapeRequest {
     require_js?: boolean;
     /** CSS selectors to strip from the extracted content. */
     exclude_selectors?: string[];
-    /** Proxy tier to use for fetching. Defaults to `basic`. */
+    /**
+     * 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;
@@ -331,7 +374,10 @@ interface ScreenshotResult {
 }
 /** A single inline image discovered on the page. */
 interface PageInlineImage {
-    /** Absolute URL of the image. */
+    /**
+     * 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;
@@ -391,7 +437,12 @@ interface ScrapeResponse {
     images?: PageInlineImage[];
     /** Links discovered on the page (when `extract.links`). */
     links?: PageLink[];
-    /** Captured screenshot (when `extract.screenshot`). */
+    /**
+     * 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;
@@ -402,6 +453,11 @@ interface ScrapeResponse {
      * 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;
 }
 
 /** Filter which link types appear in the map result. */
@@ -430,7 +486,10 @@ interface MapLocation {
 interface MapRequest {
     /** The website URL to map. */
     url: string;
-    /** Proxy tier to use for fetching. Defaults to `basic`. */
+    /**
+     * 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;
@@ -477,15 +536,20 @@ interface MapTruncation {
     /** 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;
+}
 /** 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;
-    };
+    /** Usage, pagination, and truncation metadata for the result set. */
+    response_meta: MapResponseMeta;
 }
 
 /** Job lifecycle states for an async scrape. */
@@ -495,24 +559,22 @@ 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.
- */
+/** Response body of `GET /api/scrape/status/:jobId`. */
 interface AsyncJobStatusResponse {
     /** The job identifier. */
-    jobId: string;
+    job_id: string;
     /** Current state of the job. */
     status: AsyncJobStatus;
     /** ISO-8601 UTC timestamp when the job was created. */
-    createdAt: string;
+    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;
 }
 
 /** Response from `GET /api/usage`. Current billing-cycle snapshot. */
@@ -554,7 +616,7 @@ interface WhoamiResponse {
     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. */
+    /** Truncated preview of the API token (e.g. `cwbl_…xyz`). Safe to display. */
     token_preview: string;
 }
 
@@ -570,10 +632,18 @@ interface WhoamiResponse {
  *   "event_id": "evt_…",
  *   "timestamp": "2026-06-13T12:00:00.000Z",
  *   "event": "scrape.complete",
- *   "data": { "job_id": "job_…", "status": "success", "url": "https://…", "completed_at": "…" }
+ *   "data": {
+ *     "job_id": "job_…",
+ *     "status": "success",
+ *     "url": "https://…",
+ *     "completed_at": "…",
+ *     "metadata": { "tenant": "acme" },
+ *     "response_meta": { "usage": { "credits": 1, "proxy": "basic", "cache_hit": false } }
+ *   }
  * }
  * ```
  */
+
 /** Terminal status carried by a {@link ScrapeCompleteWebhook}. */
 type ScrapeWebhookStatus = 'success' | 'failed' | 'cancelled';
 /** `data` block of a {@link ScrapeCompleteWebhook}. */
@@ -588,8 +658,17 @@ interface ScrapeCompleteWebhookData {
     completed_at: string;
     /** Failure message — present only when `status === 'failed'`. */
     error?: string;
-    /** Correlation data echoed back from the original scrape request, if any. */
+    /**
+     * 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`
@@ -653,7 +732,7 @@ interface WaitForScrapeOptions extends Omit<RequestOptions, 'timeoutMs'> {
  * ```ts
  * import { Crawlbrulee } from '@crawlbrulee/sdk'
  *
- * const crawlbrulee = new Crawlbrulee({ apiKey: 'cble_…' })
+ * const crawlbrulee = new Crawlbrulee({ apiKey: 'cwbl_…' })
  * // or read CRAWLBRULEE_API_KEY from the environment:
  * const crawlbrulee = Crawlbrulee.fromEnv()
  *
@@ -882,8 +961,8 @@ declare function isCrawlbruleeError(err: unknown): err is CrawlbruleeError;
  * staging callers point at their own host via that option.
  */
 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;
+/** Default request timeout when the caller doesn't specify one (0 disables the timeout). */
+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";
 
@@ -979,4 +1058,4 @@ 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 MapTruncation, type MapTypes, NotFoundError, type PageInlineImage, type PageLink, type ProxyTier, RateLimitError, type RateLimitErrorDetails, type RequestOptions, type ScrapeCache, type ScrapeCompleteWebhook, type ScrapeCompleteWebhookData, type ScrapeExtract, type ScrapeLocation, type ScrapeMetadata, type ScrapeRequest, type ScrapeResponse, type ScrapeWebhookStatus, type ScreenshotAfterAction, type ScreenshotBeforeAction, type ScreenshotCleanup, type ScreenshotDeviceMode, type ScreenshotProperties, type ScreenshotRequest, type ScreenshotResult, type ScreenshotScrollAction, type ScreenshotSlice, type ScreenshotSliceAction, type ScreenshotType, type ScreenshotViewport, type ScreenshotViewportInfo, type ScreenshotWaitAction, TransportError, UsageAllocationError, type UsageAllocationErrorDetails, type UsageAllocationReason, type UsageLimitDetails, type UsageResponse, ValidationError, type VerifyWebhookSignatureOptions, WEBHOOK_EVENT_ID_HEADER, WEBHOOK_SIGNATURE_HEADER, WEBHOOK_SIGNATURE_ROTATED_HEADER, type WaitForScrapeOptions, type WebhookSignatureSource, type WebhookVerificationFailureReason, type WebhookVerificationResult, type WhoamiResponse, isCrawlbruleeError, verifyWebhookSignature };
+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 };

package/dist/index.js

@@ -1,8 +1,8 @@
 // src/config.ts
 var DEFAULT_BASE_URL = "https://api.crawlbrulee.com";
-var DEFAULT_REQUEST_TIMEOUT_MS = 6e4;
+var DEFAULT_REQUEST_TIMEOUT_MS = 0;
 var ENV_API_KEY = "CRAWLBRULEE_API_KEY";
-var USER_AGENT = "@crawlbrulee/sdk/0.1.2 (node)";
+var USER_AGENT = "@crawlbrulee/sdk/0.4.0 (node)";
 
 // src/errors.ts
 var CrawlbruleeError = class extends Error {
@@ -157,7 +157,7 @@ var HttpClient = class {
     this.baseUrl = stripTrailingSlash(options.baseUrl ?? CwblInstrumentation.getBaseUrl());
     this.apiKey = options.apiKey;
     this.fetch = CwblInstrumentation.getFetch();
-    this.timeoutMs = options.timeoutMs ?? 0;
+    this.timeoutMs = options.timeoutMs ?? DEFAULT_REQUEST_TIMEOUT_MS;
   }
   /** Send a `GET` request and parse the response as `T`. */
   get(path, options) {