@crawlbrulee/sdk 0.6.0 → 0.7.1

package/dist/index.cjs

@@ -1,690 +1,852 @@
-'use strict';
+Object.defineProperty(exports, Symbol.toStringTag, { value: 'Module' });
 
-// src/config.ts
-var DEFAULT_BASE_URL = "https://api.crawlbrulee.com";
-var DEFAULT_REQUEST_TIMEOUT_MS = 0;
-var ENV_API_KEY = "CRAWLBRULEE_API_KEY";
-var USER_AGENT = "@crawlbrulee/sdk/0.4.0 (node)";
+//#region src/config.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
+* staging callers point at their own host via that option.
+*/
+const DEFAULT_BASE_URL = "https://api.crawlbrulee.com";
+/** Default request timeout when the caller doesn't specify one (0 disables the timeout). */
+const DEFAULT_REQUEST_TIMEOUT_MS = 0;
+/** Environment variable read by `Crawlbrulee.fromEnv()` to source the API key. */
+const ENV_API_KEY = "CRAWLBRULEE_API_KEY";
+/** Identifies the SDK in the `User-Agent` header. Kept in one place for easy bumping. */
+const USER_AGENT = "@crawlbrulee/sdk/0.7.0 (node)";
 
-// src/errors.ts
+//#endregion
+//#region src/errors.ts
+/**
+* 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.
+*/
 var CrawlbruleeError = class extends Error {
-  /** HTTP status code; `0` for transport-level failures with no response. */
-  status;
-  /** The `name` field from the API error body, or `null` for transport errors. */
-  errorName;
-  /** Structured detail block from the API error body, if any. */
-  details;
-  /** The original parsed error body, when one was received. */
-  response;
-  constructor(message, options) {
-    super(message, options.cause !== void 0 ? { cause: options.cause } : void 0);
-    this.name = "CrawlbruleeError";
-    this.status = options.status;
-    this.errorName = options.errorName;
-    this.details = options.details;
-    this.response = options.response;
-  }
+	/** HTTP status code; `0` for transport-level failures with no response. */
+	status;
+	/** The `name` field from the API error body, or `null` for transport errors. */
+	errorName;
+	/** Structured detail block from the API error body, if any. */
+	details;
+	/** The original parsed error body, when one was received. */
+	response;
+	constructor(message, options) {
+		super(message, options.cause !== void 0 ? { cause: options.cause } : void 0);
+		this.name = "CrawlbruleeError";
+		this.status = options.status;
+		this.errorName = options.errorName;
+		this.details = options.details;
+		this.response = options.response;
+	}
 };
+/** Raised for 401 / 403 responses (missing, invalid, or unauthorized API key). */
 var AuthenticationError = class extends CrawlbruleeError {
-  constructor(message, options) {
-    super(message, options);
-    this.name = "AuthenticationError";
-  }
+	constructor(message, options) {
+		super(message, options);
+		this.name = "AuthenticationError";
+	}
 };
+/**
+* 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`.
+*/
 var RateLimitError = class extends CrawlbruleeError {
-  errorName;
-  /** Suggested delay (ms) before retrying, when the server provided one. */
-  retryAfterMs;
-  /** Which rate limit was tripped (e.g. `org`, `ip`), when provided. */
-  limitedBy;
-  constructor(message, options) {
-    super(message, { ...options, errorName: "too_many_requests", details: options.details });
-    this.name = "RateLimitError";
-    this.errorName = "too_many_requests";
-    this.retryAfterMs = options.details?.retry_after_ms;
-    this.limitedBy = options.details?.limited_by;
-  }
+	errorName;
+	/** Suggested delay (ms) before retrying, when the server provided one. */
+	retryAfterMs;
+	/** Which rate limit was tripped (e.g. `org`, `ip`), when provided. */
+	limitedBy;
+	constructor(message, options) {
+		super(message, {
+			...options,
+			errorName: "too_many_requests",
+			details: options.details
+		});
+		this.name = "RateLimitError";
+		this.errorName = "too_many_requests";
+		this.retryAfterMs = options.details?.retry_after_ms;
+		this.limitedBy = options.details?.limited_by;
+	}
 };
+/**
+* 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'`.
+*/
 var UsageAllocationError = class extends CrawlbruleeError {
-  errorName;
-  /** Specific reason the allocation was denied. */
-  reason;
-  /** Current usage / limit snapshot at the time of the rejection. */
-  usage;
-  constructor(message, options) {
-    super(message, { ...options, errorName: "usage_allocation_error" });
-    this.name = "UsageAllocationError";
-    this.errorName = "usage_allocation_error";
-    this.reason = options.details.reason;
-    this.usage = options.details.details;
-  }
+	errorName;
+	/** Specific reason the allocation was denied. */
+	reason;
+	/** Current usage / limit snapshot at the time of the rejection. */
+	usage;
+	constructor(message, options) {
+		super(message, {
+			...options,
+			errorName: "usage_allocation_error"
+		});
+		this.name = "UsageAllocationError";
+		this.errorName = "usage_allocation_error";
+		this.reason = options.details.reason;
+		this.usage = options.details.details;
+	}
 };
+/** Raised for 4xx responses caused by an invalid request shape or arguments. */
 var ValidationError = class extends CrawlbruleeError {
-  constructor(message, options) {
-    super(message, options);
-    this.name = "ValidationError";
-  }
+	constructor(message, options) {
+		super(message, options);
+		this.name = "ValidationError";
+	}
 };
+/** Raised for 404 responses (e.g. unknown async job ID). */
 var NotFoundError = class extends CrawlbruleeError {
-  constructor(message, options) {
-    super(message, options);
-    this.name = "NotFoundError";
-  }
+	constructor(message, options) {
+		super(message, options);
+		this.name = "NotFoundError";
+	}
 };
+/**
+* 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.).
+*/
 var TransportError = class extends CrawlbruleeError {
-  constructor(message, options = {}) {
-    super(message, {
-      status: options.status ?? 0,
-      errorName: options.errorName ?? null,
-      cause: options.cause
-    });
-    this.name = "TransportError";
-  }
+	constructor(message, options = {}) {
+		super(message, {
+			status: options.status ?? 0,
+			errorName: options.errorName ?? null,
+			cause: options.cause
+		});
+		this.name = "TransportError";
+	}
 };
+/** Narrow `unknown` to the SDK's base error type. */
 function isCrawlbruleeError(err) {
-  return err instanceof CrawlbruleeError;
+	return err instanceof CrawlbruleeError;
 }
+/**
+* Map an API error body + HTTP status to the most specific error class.
+*
+* Dispatch is **name-first**: the body's `name` field is the most reliable
+* signal of what went wrong. Status code is used only as a fallback when the
+* name is unrecognized (e.g. a CDN-synthesized error). This avoids
+* miscategorizing things like a 403 with `name: 'not_found'` as an auth error.
+*
+* Internal — used by the HTTP layer.
+*/
 function createApiError(body, status) {
-  const { name, message, details } = body;
-  const response = body;
-  switch (name) {
-    case "too_many_requests":
-      return new RateLimitError(message, {
-        status,
-        details: details?.error_name === "too_many_requests" ? details : void 0,
-        response
-      });
-    case "usage_allocation_error": {
-      const usageDetails = details?.error_name === "usage_allocation_error" ? details : { error_name: "usage_allocation_error", reason: "internal_error" };
-      return new UsageAllocationError(message, { status, details: usageDetails, response });
-    }
-    case "invalid_credentials":
-    case "access_denied":
-      return new AuthenticationError(message, { status, errorName: name, response });
-    case "not_found":
-      return new NotFoundError(message, { status, errorName: name, response });
-    case "validation_error":
-    case "invalid_url":
-    case "url_too_long":
-    case "unsupported_url_schema":
-    case "url_credentials_not_supported":
-    case "blocked_url":
-    case "unsupported_content":
-      return new ValidationError(message, { status, errorName: name, response });
-  }
-  if (status === 429) {
-    return new RateLimitError(message, { status, response });
-  }
-  if (status === 401 || status === 403) {
-    return new AuthenticationError(message, { status, errorName: name, response });
-  }
-  if (status === 404) {
-    return new NotFoundError(message, { status, errorName: name, response });
-  }
-  return new CrawlbruleeError(message, { status, errorName: name, details, response });
+	const { name, message, details } = body;
+	const response = body;
+	switch (name) {
+		case "too_many_requests": return new RateLimitError(message, {
+			status,
+			details: details?.error_name === "too_many_requests" ? details : void 0,
+			response
+		});
+		case "usage_allocation_error": {
+			const usageDetails = details?.error_name === "usage_allocation_error" ? details : {
+				error_name: "usage_allocation_error",
+				reason: "internal_error"
+			};
+			return new UsageAllocationError(message, {
+				status,
+				details: usageDetails,
+				response
+			});
+		}
+		case "invalid_credentials":
+		case "access_denied": return new AuthenticationError(message, {
+			status,
+			errorName: name,
+			response
+		});
+		case "not_found": return new NotFoundError(message, {
+			status,
+			errorName: name,
+			response
+		});
+		case "validation_error":
+		case "invalid_url":
+		case "url_too_long":
+		case "unsupported_url_schema":
+		case "url_credentials_not_supported":
+		case "blocked_url":
+		case "unsupported_content": return new ValidationError(message, {
+			status,
+			errorName: name,
+			response
+		});
+	}
+	if (status === 429) return new RateLimitError(message, {
+		status,
+		response
+	});
+	if (status === 401 || status === 403) return new AuthenticationError(message, {
+		status,
+		errorName: name,
+		response
+	});
+	if (status === 404) return new NotFoundError(message, {
+		status,
+		errorName: name,
+		response
+	});
+	return new CrawlbruleeError(message, {
+		status,
+		errorName: name,
+		details,
+		response
+	});
 }
 
-// src/instrumentation.ts
-var CwblInstrumentation = {
-  /**
-   * Resolve the `fetch` implementation the SDK should use. Throws a
-   * {@link CrawlbruleeError} if the runtime does not expose a global `fetch`.
-   */
-  getFetch() {
-    const g = globalThis;
-    if (typeof g.fetch !== "function") {
-      throw new CrawlbruleeError(
-        "No global fetch is available in this runtime. crawlbrulee requires Node.js 20+, Bun, Deno, or a modern browser/edge runtime.",
-        { status: 0, errorName: null }
-      );
-    }
-    return g.fetch.bind(globalThis);
-  },
-  /**
-   * Resolve the base URL the SDK should target. Returns the production host by
-   * default; tests stub this to point at a mock origin.
-   */
-  getBaseUrl() {
-    return DEFAULT_BASE_URL;
-  }
+//#endregion
+//#region src/instrumentation.ts
+/**
+* Centralized factory for the low-level dependencies the SDK injects into its
+* HTTP layer. Production code resolves these to the runtime's global `fetch`
+* and the burned-in production base URL; tests stub this module to swap in
+* mocks and alternate hosts.
+*
+* This is internal — it is not exported from the package's public entry. Tests
+* import it from `src/instrumentation.js` directly and use `vi.spyOn` to
+* substitute behavior.
+*/
+const CwblInstrumentation = {
+	/**
+	* Resolve the `fetch` implementation the SDK should use. Throws a
+	* {@link CrawlbruleeError} if the runtime does not expose a global `fetch`.
+	*/
+	getFetch() {
+		const g = globalThis;
+		if (typeof g.fetch !== "function") throw new CrawlbruleeError("No global fetch is available in this runtime. crawlbrulee requires Node.js 22+, Bun, Deno, or a modern browser/edge runtime.", {
+			status: 0,
+			errorName: null
+		});
+		return g.fetch.bind(globalThis);
+	},
+	/**
+	* Resolve the base URL the SDK should target. Returns the production host by
+	* default; tests stub this to point at a mock origin.
+	*/
+	getBaseUrl() {
+		return DEFAULT_BASE_URL;
+	}
 };
 
-// src/http.ts
+//#endregion
+//#region src/http.ts
+/**
+* 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 base URL and `fetch` implementation are sourced from
+* {@link CwblInstrumentation} at construction time so tests can stub the
+* module.
+*/
 var HttpClient = class {
-  baseUrl;
-  apiKey;
-  fetch;
-  timeoutMs;
-  constructor(options) {
-    this.baseUrl = stripTrailingSlash(options.baseUrl ?? CwblInstrumentation.getBaseUrl());
-    this.apiKey = options.apiKey;
-    this.fetch = CwblInstrumentation.getFetch();
-    this.timeoutMs = options.timeoutMs ?? DEFAULT_REQUEST_TIMEOUT_MS;
-  }
-  /** Send a `GET` request and parse the response as `T`. */
-  get(path, options) {
-    return this.send({ method: "GET", path, ...options });
-  }
-  /** Send a `POST` request with a JSON body and parse the response as `T`. */
-  post(path, body, options) {
-    return this.send({ method: "POST", path, body, ...options });
-  }
-  async send(args) {
-    const url = this.buildUrl(args.path);
-    const headers = this.buildHeaders(args);
-    const body = args.body === void 0 ? void 0 : JSON.stringify(args.body);
-    const composed = this.composeSignal(args.signal, args.timeoutMs);
-    try {
-      let res;
-      try {
-        res = await this.fetch(url, {
-          method: args.method,
-          headers,
-          body,
-          signal: composed.signal
-        });
-      } catch (cause) {
-        throw abortOrNetworkError(cause, composed.timedOut(), args.timeoutMs ?? this.timeoutMs);
-      }
-      let text;
-      try {
-        text = await res.text();
-      } catch (cause) {
-        if (isAbortError(cause)) {
-          throw abortOrNetworkError(cause, composed.timedOut(), args.timeoutMs ?? this.timeoutMs);
-        }
-        throw new TransportError(`Failed to read response body (status ${res.status}).`, {
-          status: res.status,
-          cause
-        });
-      }
-      const parsed = parseJsonOrThrow(text, res.status);
-      if (!res.ok) throw toApiError(parsed, res.status, text);
-      return parsed;
-    } finally {
-      composed.cleanup();
-    }
-  }
-  buildUrl(path) {
-    if (!path.startsWith("/")) {
-      throw new TypeError(`crawlbrulee SDK: path must start with '/' (received '${path}')`);
-    }
-    return `${this.baseUrl}${path}`;
-  }
-  buildHeaders(args) {
-    const headers = {
-      accept: "application/json",
-      "user-agent": USER_AGENT,
-      authorization: `Bearer ${this.apiKey}`
-    };
-    if (args.body !== void 0) headers["content-type"] = "application/json";
-    return headers;
-  }
-  /**
-   * 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.
-   */
-  composeSignal(callerSignal, overrideTimeoutMs) {
-    const timeoutMs = overrideTimeoutMs ?? this.timeoutMs;
-    const hasTimeout = Number.isFinite(timeoutMs) && timeoutMs > 0;
-    if (!hasTimeout && !callerSignal) {
-      return { signal: void 0, timedOut: () => false, cleanup: () => {
-      } };
-    }
-    if (!hasTimeout) {
-      return { signal: callerSignal, timedOut: () => false, cleanup: () => {
-      } };
-    }
-    const controller = new AbortController();
-    let didTimeout = false;
-    const timer = setTimeout(() => {
-      didTimeout = true;
-      controller.abort(new Error("request_timeout"));
-    }, timeoutMs);
-    let onCallerAbort;
-    if (callerSignal) {
-      if (callerSignal.aborted) {
-        clearTimeout(timer);
-        controller.abort(callerSignal.reason);
-      } else {
-        onCallerAbort = () => {
-          clearTimeout(timer);
-          controller.abort(callerSignal.reason);
-        };
-        callerSignal.addEventListener("abort", onCallerAbort, { once: true });
-      }
-    }
-    const cleanup = () => {
-      clearTimeout(timer);
-      if (onCallerAbort && callerSignal) {
-        callerSignal.removeEventListener("abort", onCallerAbort);
-      }
-    };
-    return { signal: controller.signal, timedOut: () => didTimeout, cleanup };
-  }
+	baseUrl;
+	apiKey;
+	fetch;
+	timeoutMs;
+	constructor(options) {
+		this.baseUrl = stripTrailingSlash(options.baseUrl ?? CwblInstrumentation.getBaseUrl());
+		this.apiKey = options.apiKey;
+		this.fetch = CwblInstrumentation.getFetch();
+		this.timeoutMs = options.timeoutMs ?? 0;
+	}
+	/** Send a `GET` request and parse the response as `T`. */
+	get(path, options) {
+		return this.send({
+			method: "GET",
+			path,
+			...options
+		});
+	}
+	/** Send a `POST` request with a JSON body and parse the response as `T`. */
+	post(path, body, options) {
+		return this.send({
+			method: "POST",
+			path,
+			body,
+			...options
+		});
+	}
+	async send(args) {
+		const url = this.buildUrl(args.path);
+		const headers = this.buildHeaders(args);
+		const body = args.body === void 0 ? void 0 : JSON.stringify(args.body);
+		const composed = this.composeSignal(args.signal, args.timeoutMs);
+		try {
+			let res;
+			try {
+				res = await this.fetch(url, {
+					method: args.method,
+					headers,
+					body,
+					signal: composed.signal
+				});
+			} catch (cause) {
+				throw abortOrNetworkError(cause, composed.timedOut(), args.timeoutMs ?? this.timeoutMs);
+			}
+			let text;
+			try {
+				text = await res.text();
+			} catch (cause) {
+				if (isAbortError(cause)) throw abortOrNetworkError(cause, composed.timedOut(), args.timeoutMs ?? this.timeoutMs);
+				throw new TransportError(`Failed to read response body (status ${res.status}).`, {
+					status: res.status,
+					cause
+				});
+			}
+			const parsed = parseJsonOrThrow(text, res.status);
+			if (!res.ok) throw toApiError(parsed, res.status, text);
+			return parsed;
+		} finally {
+			composed.cleanup();
+		}
+	}
+	buildUrl(path) {
+		if (!path.startsWith("/")) throw new TypeError(`crawlbrulee SDK: path must start with '/' (received '${path}')`);
+		return `${this.baseUrl}${path}`;
+	}
+	buildHeaders(args) {
+		const headers = {
+			accept: "application/json",
+			"user-agent": USER_AGENT,
+			authorization: `Bearer ${this.apiKey}`
+		};
+		if (args.body !== void 0) headers["content-type"] = "application/json";
+		return headers;
+	}
+	/**
+	* 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.
+	*/
+	composeSignal(callerSignal, overrideTimeoutMs) {
+		const timeoutMs = overrideTimeoutMs ?? this.timeoutMs;
+		const hasTimeout = Number.isFinite(timeoutMs) && timeoutMs > 0;
+		if (!hasTimeout && !callerSignal) return {
+			signal: void 0,
+			timedOut: () => false,
+			cleanup: () => {}
+		};
+		if (!hasTimeout) return {
+			signal: callerSignal,
+			timedOut: () => false,
+			cleanup: () => {}
+		};
+		const controller = new AbortController();
+		let didTimeout = false;
+		const timer = setTimeout(() => {
+			didTimeout = true;
+			controller.abort(/* @__PURE__ */ new Error("request_timeout"));
+		}, timeoutMs);
+		let onCallerAbort;
+		if (callerSignal) if (callerSignal.aborted) {
+			clearTimeout(timer);
+			controller.abort(callerSignal.reason);
+		} else {
+			onCallerAbort = () => {
+				clearTimeout(timer);
+				controller.abort(callerSignal.reason);
+			};
+			callerSignal.addEventListener("abort", onCallerAbort, { once: true });
+		}
+		const cleanup = () => {
+			clearTimeout(timer);
+			if (onCallerAbort && callerSignal) callerSignal.removeEventListener("abort", onCallerAbort);
+		};
+		return {
+			signal: controller.signal,
+			timedOut: () => didTimeout,
+			cleanup
+		};
+	}
 };
 function stripTrailingSlash(url) {
-  return url.replace(/\/+$/, "");
+	return url.replace(/\/+$/, "");
 }
 function isAbortError(err) {
-  return err instanceof Error && err.name === "AbortError";
+	return err instanceof Error && err.name === "AbortError";
 }
 function abortOrNetworkError(cause, timedOut, timeoutMs) {
-  if (isAbortError(cause)) {
-    if (timedOut) {
-      return new TransportError(`Request timed out after ${timeoutMs}ms.`, {
-        errorName: "request_timeout",
-        cause
-      });
-    }
-    return new TransportError("Request aborted by caller.", {
-      errorName: "client_closed_request",
-      cause
-    });
-  }
-  return new TransportError(formatNetworkErrorMessage(cause), { cause });
+	if (isAbortError(cause)) {
+		if (timedOut) return new TransportError(`Request timed out after ${timeoutMs}ms.`, {
+			errorName: "request_timeout",
+			cause
+		});
+		return new TransportError("Request aborted by caller.", {
+			errorName: "client_closed_request",
+			cause
+		});
+	}
+	return new TransportError(formatNetworkErrorMessage(cause), { cause });
 }
 function formatNetworkErrorMessage(cause) {
-  if (cause instanceof Error) {
-    return `Network error: ${cause.message}`;
-  }
-  return "Network error: unknown failure while sending the request.";
+	if (cause instanceof Error) return `Network error: ${cause.message}`;
+	return "Network error: unknown failure while sending the request.";
 }
 function parseJsonOrThrow(text, status) {
-  if (text === "") return {};
-  try {
-    return JSON.parse(text);
-  } catch (cause) {
-    const preview = text.length > 200 ? `${text.slice(0, 200)}\u2026` : text;
-    throw new TransportError(`Unexpected non-JSON response (status ${status}): ${preview}`, {
-      status,
-      cause
-    });
-  }
+	if (text === "") return {};
+	try {
+		return JSON.parse(text);
+	} catch (cause) {
+		throw new TransportError(`Unexpected non-JSON response (status ${status}): ${text.length > 200 ? `${text.slice(0, 200)}…` : text}`, {
+			status,
+			cause
+		});
+	}
 }
 function toApiError(parsed, status, rawText) {
-  if (isApiErrorResponse(parsed)) {
-    return createApiError(parsed, status);
-  }
-  const preview = rawText.length > 200 ? `${rawText.slice(0, 200)}\u2026` : rawText;
-  return new TransportError(`HTTP ${status}: ${preview || "(empty body)"}`, { status });
+	if (isApiErrorResponse(parsed)) return createApiError(parsed, status);
+	return new TransportError(`HTTP ${status}: ${(rawText.length > 200 ? `${rawText.slice(0, 200)}…` : rawText) || "(empty body)"}`, { status });
 }
 function isApiErrorResponse(value) {
-  if (value === null || typeof value !== "object") return false;
-  const v = value;
-  return typeof v.name === "string" && typeof v.message === "string";
+	if (value === null || typeof value !== "object") return false;
+	const v = value;
+	return typeof v.name === "string" && typeof v.message === "string";
 }
 
-// src/client.ts
-var Crawlbrulee = class _Crawlbrulee {
-  /** Resolved base URL — trailing slash already stripped. */
-  baseUrl;
-  /** Underlying HTTP layer. Exposed for advanced use cases (custom endpoints). */
-  http;
-  constructor(options) {
-    const apiKey = options.apiKey?.trim();
-    if (!apiKey) {
-      throw new CrawlbruleeError(
-        `Missing API key. Pass { apiKey } to Crawlbrulee or call Crawlbrulee.fromEnv() to read ${ENV_API_KEY}.`,
-        { status: 0, errorName: null }
-      );
-    }
-    this.http = new HttpClient({ apiKey, baseUrl: options.baseUrl, timeoutMs: options.timeoutMs });
-    this.baseUrl = this.http.baseUrl;
-  }
-  /**
-   * 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 = {}) {
-    const apiKey = readEnv(ENV_API_KEY);
-    if (!apiKey) {
-      throw new CrawlbruleeError(
-        `${ENV_API_KEY} is not set. Export it in your shell, or pass apiKey to new Crawlbrulee({ apiKey }).`,
-        { status: 0, errorName: null }
-      );
-    }
-    return new _Crawlbrulee({ ...overrides, apiKey });
-  }
-  // ------------------------------------------------------------------
-  // Scraping
-  // ------------------------------------------------------------------
-  /**
-   * 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, options) {
-    return this.http.post("/api/scrape", request, options);
-  }
-  /**
-   * Submit an asynchronous scrape job and return its `job_id`. Poll the job
-   * with {@link Crawlbrulee.getScrapeStatus} or wait for completion with
-   * {@link Crawlbrulee.waitForScrape}.
-   *
-   * Pass an optional `webhook` to have the API deliver a signed
-   * `scrape.complete` `POST` to your endpoint when the job finishes (see
-   * {@link AsyncScrapeWebhook}). This field is async-only.
-   */
-  scrapeAsync(request, options) {
-    return this.http.post("/api/scrape/async", request, options);
-  }
-  /** Look up the current status of an async scrape job. */
-  getScrapeStatus(jobId, options) {
-    assertNonEmptyJobId(jobId);
-    return this.http.get(
-      `/api/scrape/status/${encodeURIComponent(jobId)}`,
-      options
-    );
-  }
-  /**
-   * 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, options) {
-    assertNonEmptyJobId(jobId);
-    return this.http.get(`/api/scrape/result/${encodeURIComponent(jobId)}`, options);
-  }
-  /**
-   * Fetch the scrape result referenced by a `scrape.complete` webhook body.
-   *
-   * Always verify the webhook signature with `verifyWebhookSignature` before
-   * acting on it; this method trusts the parsed body it is handed.
-   *
-   * Behavior by `data.status`:
-   * - `success` — delegates to {@link Crawlbrulee.getScrapeResult} for the
-   *   webhook's `job_id` and returns the parsed result.
-   * - `failed` — throws a {@link CrawlbruleeError} carrying `data.error`
-   *   (`errorName: 'job_failed'`); there is no result to fetch.
-   * - `cancelled` — throws a {@link CrawlbruleeError}
-   *   (`errorName: 'client_closed_request'`).
-   *
-   * A non-`scrape.complete` envelope throws a {@link CrawlbruleeError}
-   * defensively. Any HTTP error from the underlying fetch propagates as the
-   * usual typed `CrawlbruleeError` subclass.
-   */
-  async fetchScrapeResultFromWebhook(webhook, options) {
-    if (webhook?.event !== "scrape.complete") {
-      throw new CrawlbruleeError(
-        `Expected a 'scrape.complete' webhook but received '${String(webhook?.event)}'.`,
-        { status: 0, errorName: "validation_error" }
-      );
-    }
-    const { job_id: jobId, status, error } = webhook.data;
-    switch (status) {
-      case "success":
-        return this.getScrapeResult(jobId, options);
-      case "failed":
-        throw new CrawlbruleeError(error ?? `Async scrape job ${jobId} failed.`, {
-          status: 0,
-          errorName: "job_failed"
-        });
-      case "cancelled":
-        throw new CrawlbruleeError(`Async scrape job ${jobId} was cancelled.`, {
-          status: 0,
-          errorName: "client_closed_request"
-        });
-      default:
-        throw new CrawlbruleeError(
-          `Async scrape webhook for job ${jobId} carried an unexpected status '${String(status)}'.`,
-          { status: 0, errorName: "validation_error" }
-        );
-    }
-  }
-  /**
-   * Poll an async scrape job until it reaches a terminal state, then return
-   * the scrape result.
-   *
-   * 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'`).
-   */
-  async waitForScrape(jobId, options = {}) {
-    assertNonEmptyJobId(jobId);
-    const intervalMs = options.intervalMs ?? 2e3;
-    const timeoutMs = options.timeoutMs ?? 3e5;
-    const deadline = timeoutMs > 0 ? Date.now() + timeoutMs : Number.POSITIVE_INFINITY;
-    while (true) {
-      throwIfAborted(options.signal);
-      if (Date.now() >= deadline) {
-        throw new CrawlbruleeError(
-          `Timed out after ${timeoutMs}ms waiting for async scrape job ${jobId}.`,
-          { status: 0, errorName: "request_timeout" }
-        );
-      }
-      const status = await this.getScrapeStatus(jobId, { signal: options.signal });
-      switch (status.status) {
-        case "done":
-          return this.getScrapeResult(jobId, { signal: options.signal });
-        case "failed":
-          throw new CrawlbruleeError(status.error ?? `Async scrape job ${jobId} failed.`, {
-            status: 0,
-            errorName: "job_failed"
-          });
-        case "pending":
-        case "running":
-          break;
-        default:
-          throw new CrawlbruleeError(
-            `Async scrape job ${jobId} returned unexpected status '${String(status.status)}'.`,
-            { status: 0, errorName: "job_failed" }
-          );
-      }
-      await sleep(intervalMs, options.signal);
-    }
-  }
-  // ------------------------------------------------------------------
-  // Mapping
-  // ------------------------------------------------------------------
-  /**
-   * Build (or return a cached) site link-map for a domain. Combines sitemap
-   * discovery with the freshest cached homepage scrape when available.
-   */
-  map(request, options) {
-    return this.http.post("/api/map", request, options);
-  }
-  // ------------------------------------------------------------------
-  // Account
-  // ------------------------------------------------------------------
-  /**
-   * Return the current billing-cycle usage: total/used/available credits,
-   * used quota percentage, max concurrency, and when the cycle resets.
-   */
-  usage(options) {
-    return this.http.get("/api/usage", options);
-  }
-  /**
-   * 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) {
-    return this.http.get("/api/whoami", options);
-  }
+//#endregion
+//#region src/client.ts
+/**
+* Official client for the crawlbrulee API.
+*
+* @example
+* ```ts
+* import { Crawlbrulee } from '@crawlbrulee/sdk'
+*
+* const crawlbrulee = new Crawlbrulee({ apiKey: 'cwbl_…' })
+* // 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)
+* ```
+*/
+var Crawlbrulee = class Crawlbrulee {
+	/** Resolved base URL — trailing slash already stripped. */
+	baseUrl;
+	/** Underlying HTTP layer. Exposed for advanced use cases (custom endpoints). */
+	http;
+	constructor(options) {
+		const apiKey = options.apiKey?.trim();
+		if (!apiKey) throw new CrawlbruleeError(`Missing API key. Pass { apiKey } to Crawlbrulee or call Crawlbrulee.fromEnv() to read ${ENV_API_KEY}.`, {
+			status: 0,
+			errorName: null
+		});
+		this.http = new HttpClient({
+			apiKey,
+			baseUrl: options.baseUrl,
+			timeoutMs: options.timeoutMs
+		});
+		this.baseUrl = this.http.baseUrl;
+	}
+	/**
+	* 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 = {}) {
+		const apiKey = readEnv(ENV_API_KEY);
+		if (!apiKey) throw new CrawlbruleeError(`${ENV_API_KEY} is not set. Export it in your shell, or pass apiKey to new Crawlbrulee({ apiKey }).`, {
+			status: 0,
+			errorName: null
+		});
+		return new Crawlbrulee({
+			...overrides,
+			apiKey
+		});
+	}
+	/**
+	* 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, options) {
+		return this.http.post("/api/scrape", request, options);
+	}
+	/**
+	* Submit an asynchronous scrape job and return its `job_id`. Poll the job
+	* with {@link Crawlbrulee.getScrapeStatus} or wait for completion with
+	* {@link Crawlbrulee.waitForScrape}.
+	*
+	* Pass an optional `webhook` to have the API deliver a signed
+	* `scrape.complete` `POST` to your endpoint when the job finishes (see
+	* {@link AsyncScrapeWebhook}). This field is async-only.
+	*/
+	scrapeAsync(request, options) {
+		return this.http.post("/api/scrape/async", request, options);
+	}
+	/** Look up the current status of an async scrape job. */
+	getScrapeStatus(jobId, options) {
+		assertNonEmptyJobId(jobId);
+		return this.http.get(`/api/scrape/status/${encodeURIComponent(jobId)}`, options);
+	}
+	/**
+	* 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, options) {
+		assertNonEmptyJobId(jobId);
+		return this.http.get(`/api/scrape/result/${encodeURIComponent(jobId)}`, options);
+	}
+	/**
+	* Fetch the scrape result referenced by a `scrape.complete` webhook body.
+	*
+	* Always verify the webhook signature with `verifyWebhookSignature` before
+	* acting on it; this method trusts the parsed body it is handed.
+	*
+	* Behavior by `data.status`:
+	* - `success` — delegates to {@link Crawlbrulee.getScrapeResult} for the
+	*   webhook's `job_id` and returns the parsed result.
+	* - `failed` — throws a {@link CrawlbruleeError} carrying `data.error`
+	*   (`errorName: 'job_failed'`); there is no result to fetch.
+	* - `cancelled` — throws a {@link CrawlbruleeError}
+	*   (`errorName: 'client_closed_request'`).
+	*
+	* A non-`scrape.complete` envelope throws a {@link CrawlbruleeError}
+	* defensively. Any HTTP error from the underlying fetch propagates as the
+	* usual typed `CrawlbruleeError` subclass.
+	*/
+	async fetchScrapeResultFromWebhook(webhook, options) {
+		if (webhook?.event !== "scrape.complete") throw new CrawlbruleeError(`Expected a 'scrape.complete' webhook but received '${String(webhook?.event)}'.`, {
+			status: 0,
+			errorName: "validation_error"
+		});
+		const { job_id: jobId, status, error } = webhook.data;
+		switch (status) {
+			case "success": return this.getScrapeResult(jobId, options);
+			case "failed": throw new CrawlbruleeError(error ?? `Async scrape job ${jobId} failed.`, {
+				status: 0,
+				errorName: "job_failed"
+			});
+			case "cancelled": throw new CrawlbruleeError(`Async scrape job ${jobId} was cancelled.`, {
+				status: 0,
+				errorName: "client_closed_request"
+			});
+			default: throw new CrawlbruleeError(`Async scrape webhook for job ${jobId} carried an unexpected status '${String(status)}'.`, {
+				status: 0,
+				errorName: "validation_error"
+			});
+		}
+	}
+	/**
+	* Poll an async scrape job until it reaches a terminal state, then return
+	* the scrape result.
+	*
+	* 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'`).
+	*/
+	async waitForScrape(jobId, options = {}) {
+		assertNonEmptyJobId(jobId);
+		const intervalMs = options.intervalMs ?? 2e3;
+		const timeoutMs = options.timeoutMs ?? 3e5;
+		const deadline = timeoutMs > 0 ? Date.now() + timeoutMs : Number.POSITIVE_INFINITY;
+		while (true) {
+			throwIfAborted(options.signal);
+			if (Date.now() >= deadline) throw new CrawlbruleeError(`Timed out after ${timeoutMs}ms waiting for async scrape job ${jobId}.`, {
+				status: 0,
+				errorName: "request_timeout"
+			});
+			const status = await this.getScrapeStatus(jobId, { signal: options.signal });
+			switch (status.status) {
+				case "done": return this.getScrapeResult(jobId, { signal: options.signal });
+				case "failed": throw new CrawlbruleeError(status.error ?? `Async scrape job ${jobId} failed.`, {
+					status: 0,
+					errorName: "job_failed"
+				});
+				case "pending":
+				case "running": break;
+				default: throw new CrawlbruleeError(`Async scrape job ${jobId} returned unexpected status '${String(status.status)}'.`, {
+					status: 0,
+					errorName: "job_failed"
+				});
+			}
+			await sleep(intervalMs, options.signal);
+		}
+	}
+	/**
+	* Build (or return a cached) site link-map for a domain. Combines sitemap
+	* discovery with the freshest cached homepage scrape when available.
+	*/
+	map(request, options) {
+		return this.http.post("/api/map", request, options);
+	}
+	/**
+	* Return the current billing-cycle usage: total/used/available credits,
+	* used quota percentage, max concurrency, and when the cycle resets.
+	*/
+	usage(options) {
+		return this.http.get("/api/usage", options);
+	}
+	/**
+	* 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) {
+		return this.http.get("/api/whoami", options);
+	}
 };
+/**
+* Defensive read of `process.env[name]`. Guards both the absence of `process`
+* (browser / edge runtimes) and Deno's permission throw on env access without
+* `--allow-env`.
+*/
 function readEnv(name) {
-  try {
-    if (typeof process === "undefined" || !process.env) return void 0;
-    const v = process.env[name];
-    return typeof v === "string" && v.trim().length > 0 ? v.trim() : void 0;
-  } catch {
-    return void 0;
-  }
+	try {
+		if (typeof process === "undefined" || !process.env) return void 0;
+		const v = process.env[name];
+		return typeof v === "string" && v.trim().length > 0 ? v.trim() : void 0;
+	} catch {
+		return;
+	}
 }
 function assertNonEmptyJobId(jobId) {
-  if (typeof jobId !== "string" || jobId.trim().length === 0) {
-    throw new CrawlbruleeError("jobId must be a non-empty string.", {
-      status: 0,
-      errorName: null
-    });
-  }
+	if (typeof jobId !== "string" || jobId.trim().length === 0) throw new CrawlbruleeError("jobId must be a non-empty string.", {
+		status: 0,
+		errorName: null
+	});
 }
 function throwIfAborted(signal) {
-  if (signal?.aborted) {
-    throw new CrawlbruleeError("Request aborted by caller.", {
-      status: 0,
-      errorName: "client_closed_request",
-      cause: signal.reason
-    });
-  }
+	if (signal?.aborted) throw new CrawlbruleeError("Request aborted by caller.", {
+		status: 0,
+		errorName: "client_closed_request",
+		cause: signal.reason
+	});
 }
 function sleep(ms, signal) {
-  return new Promise((resolve, reject) => {
-    const onAbort = () => {
-      clearTimeout(timer);
-      reject(
-        new CrawlbruleeError("Request aborted by caller.", {
-          status: 0,
-          errorName: "client_closed_request",
-          cause: signal?.reason
-        })
-      );
-    };
-    const timer = setTimeout(() => {
-      signal?.removeEventListener("abort", onAbort);
-      resolve();
-    }, ms);
-    if (signal) {
-      if (signal.aborted) {
-        clearTimeout(timer);
-        onAbort();
-        return;
-      }
-      signal.addEventListener("abort", onAbort, { once: true });
-    }
-  });
+	return new Promise((resolve, reject) => {
+		const onAbort = () => {
+			clearTimeout(timer);
+			reject(new CrawlbruleeError("Request aborted by caller.", {
+				status: 0,
+				errorName: "client_closed_request",
+				cause: signal?.reason
+			}));
+		};
+		const timer = setTimeout(() => {
+			signal?.removeEventListener("abort", onAbort);
+			resolve();
+		}, ms);
+		if (signal) {
+			if (signal.aborted) {
+				clearTimeout(timer);
+				onAbort();
+				return;
+			}
+			signal.addEventListener("abort", onAbort, { once: true });
+		}
+	});
 }
 
-// src/webhooks.ts
-var WEBHOOK_SIGNATURE_HEADER = "X-Cwbl-Signature";
-var WEBHOOK_SIGNATURE_ROTATED_HEADER = "X-Cwbl-Signature-Rotated";
-var WEBHOOK_EVENT_ID_HEADER = "X-Cwbl-Event-Id";
-var DEFAULT_WEBHOOK_TOLERANCE_SECONDS = 300;
-var SIGNATURE_FORMAT = /^t=(\d+),v1=([0-9a-f]{64})$/;
+//#endregion
+//#region src/webhooks.ts
+/**
+* Verification for async scrape completion webhooks.
+*
+* {@link verifyWebhookSignature} validates the signature crawlbrulee attaches to
+* every webhook delivery. It is a standalone, network-free helper built on Web
+* Crypto (`globalThis.crypto.subtle`) so it runs unchanged on Node.js 22+,
+* browsers, Bun, Deno, and edge runtimes — it never touches `node:crypto`.
+*/
+/** HTTP header carrying the primary webhook signature (always present). */
+const WEBHOOK_SIGNATURE_HEADER = "X-Cwbl-Signature";
+/**
+* HTTP header carrying a signature produced with the previous signing secret.
+* Present only during a signing-secret rotation grace window.
+*/
+const WEBHOOK_SIGNATURE_ROTATED_HEADER = "X-Cwbl-Signature-Rotated";
+/** HTTP header carrying the unique event id, useful for delivery de-duplication. */
+const WEBHOOK_EVENT_ID_HEADER = "X-Cwbl-Event-Id";
+/** Default replay-protection window (seconds) applied to the signed timestamp. */
+const DEFAULT_WEBHOOK_TOLERANCE_SECONDS = 300;
+const SIGNATURE_FORMAT = /^t=(\d+),v1=([0-9a-f]{64})$/;
+/**
+* Verify a crawlbrulee webhook signature against the primary and rotated
+* headers.
+*
+* The signing scheme matches the backend:
+* - the signed payload is `` `${t}.${rawBody}` `` where `t` is the unix-seconds
+*   integer from the header and `rawBody` is the raw request body,
+* - the signature is `HMAC-SHA256(secret, signedPayload)` as lowercase hex,
+* - the header value is `t=<unix_seconds>,v1=<64_hex>`.
+*
+* The supplied `secret` is tried against the primary header first, then the
+* rotated header (which the API emits during a signing-secret rotation grace
+* window). Whichever matches wins, and the result reports which header it was.
+*
+* This NEVER throws on a verification failure — failures are normal control
+* flow and are returned as `{ verified: false, reason }`.
+*
+* @example
+* ```ts
+* const result = await verifyWebhookSignature({
+*   payload: rawBody,
+*   headers: req.headers,
+*   secret: process.env.CRAWLBRULEE_WEBHOOK_SECRET!,
+* })
+* if (!result.verified) return res.status(400).end()
+* ```
+*/
 async function verifyWebhookSignature(options) {
-  const { payload, headers, secret } = options;
-  const toleranceSeconds = options.toleranceSeconds ?? DEFAULT_WEBHOOK_TOLERANCE_SECONDS;
-  const primaryHeader = getHeader(headers, WEBHOOK_SIGNATURE_HEADER);
-  const rotatedHeader = getHeader(headers, WEBHOOK_SIGNATURE_ROTATED_HEADER);
-  if (primaryHeader === void 0 && rotatedHeader === void 0) {
-    return { verified: false, reason: "missing_signature" };
-  }
-  const nowSeconds = Math.floor(Date.now() / 1e3);
-  const body = toBytes(payload);
-  const key = await importHmacKey(secret);
-  let failure = "malformed_signature";
-  for (const source of ["primary", "rotated"]) {
-    const raw = source === "primary" ? primaryHeader : rotatedHeader;
-    if (raw === void 0) continue;
-    const parsed = parseSignatureHeader(raw);
-    if (!parsed) {
-      continue;
-    }
-    if (toleranceSeconds && Math.abs(nowSeconds - parsed.timestamp) > toleranceSeconds) {
-      failure = mostSpecificFailure(failure, "timestamp_out_of_tolerance");
-      continue;
-    }
-    const expected = await computeSignatureHex(key, parsed.timestamp, body);
-    if (constantTimeEqualHex(expected, parsed.signature)) {
-      return { verified: true, signedWith: source };
-    }
-    failure = mostSpecificFailure(failure, "signature_mismatch");
-  }
-  return { verified: false, reason: failure };
+	const { payload, headers, secret } = options;
+	const toleranceSeconds = options.toleranceSeconds ?? 300;
+	const primaryHeader = getHeader(headers, WEBHOOK_SIGNATURE_HEADER);
+	const rotatedHeader = getHeader(headers, WEBHOOK_SIGNATURE_ROTATED_HEADER);
+	if (primaryHeader === void 0 && rotatedHeader === void 0) return {
+		verified: false,
+		reason: "missing_signature"
+	};
+	const nowSeconds = Math.floor(Date.now() / 1e3);
+	const body = toBytes(payload);
+	const key = await importHmacKey(secret);
+	let failure = "malformed_signature";
+	for (const source of ["primary", "rotated"]) {
+		const raw = source === "primary" ? primaryHeader : rotatedHeader;
+		if (raw === void 0) continue;
+		const parsed = parseSignatureHeader(raw);
+		if (!parsed) continue;
+		if (toleranceSeconds && Math.abs(nowSeconds - parsed.timestamp) > toleranceSeconds) {
+			failure = mostSpecificFailure(failure, "timestamp_out_of_tolerance");
+			continue;
+		}
+		if (constantTimeEqualHex(await computeSignatureHex(key, parsed.timestamp, body), parsed.signature)) return {
+			verified: true,
+			signedWith: source
+		};
+		failure = mostSpecificFailure(failure, "signature_mismatch");
+	}
+	return {
+		verified: false,
+		reason: failure
+	};
 }
+/**
+* Rank verification failures so the returned reason reflects the most
+* actionable problem encountered across the two headers.
+*/
 function mostSpecificFailure(current, candidate) {
-  const rank = {
-    missing_signature: 0,
-    malformed_signature: 1,
-    timestamp_out_of_tolerance: 2,
-    signature_mismatch: 3
-  };
-  return rank[candidate] > rank[current] ? candidate : current;
+	const rank = {
+		missing_signature: 0,
+		malformed_signature: 1,
+		timestamp_out_of_tolerance: 2,
+		signature_mismatch: 3
+	};
+	return rank[candidate] > rank[current] ? candidate : current;
 }
+/** Case-insensitive header lookup over `Headers` or a plain object. */
 function getHeader(headers, name) {
-  if (typeof Headers !== "undefined" && headers instanceof Headers) {
-    return headers.get(name) ?? void 0;
-  }
-  const target = name.toLowerCase();
-  for (const key of Object.keys(headers)) {
-    if (key.toLowerCase() !== target) continue;
-    const value = headers[key];
-    if (Array.isArray(value)) return value[0];
-    return value ?? void 0;
-  }
-  return void 0;
+	if (typeof Headers !== "undefined" && headers instanceof Headers) return headers.get(name) ?? void 0;
+	const target = name.toLowerCase();
+	for (const key of Object.keys(headers)) {
+		if (key.toLowerCase() !== target) continue;
+		const value = headers[key];
+		if (Array.isArray(value)) return value[0];
+		return value ?? void 0;
+	}
 }
 function parseSignatureHeader(value) {
-  const match = SIGNATURE_FORMAT.exec(value.trim());
-  if (!match) return null;
-  const timestamp = Number(match[1]);
-  if (!Number.isSafeInteger(timestamp)) return null;
-  return { timestamp, signature: match[2] };
+	const match = SIGNATURE_FORMAT.exec(value.trim());
+	if (!match) return null;
+	const timestamp = Number(match[1]);
+	if (!Number.isSafeInteger(timestamp)) return null;
+	return {
+		timestamp,
+		signature: match[2]
+	};
 }
 function toBytes(payload) {
-  return typeof payload === "string" ? new TextEncoder().encode(payload) : payload;
+	return typeof payload === "string" ? new TextEncoder().encode(payload) : payload;
 }
 function importHmacKey(secret) {
-  return getSubtle().importKey(
-    "raw",
-    new TextEncoder().encode(secret),
-    { name: "HMAC", hash: "SHA-256" },
-    false,
-    ["sign"]
-  );
+	return getSubtle().importKey("raw", new TextEncoder().encode(secret), {
+		name: "HMAC",
+		hash: "SHA-256"
+	}, false, ["sign"]);
 }
 async function computeSignatureHex(key, timestamp, body) {
-  const prefix = new TextEncoder().encode(`${timestamp}.`);
-  const message = new Uint8Array(prefix.length + body.length);
-  message.set(prefix, 0);
-  message.set(body, prefix.length);
-  const digest = await getSubtle().sign("HMAC", key, message);
-  return toHex(new Uint8Array(digest));
+	const prefix = new TextEncoder().encode(`${timestamp}.`);
+	const message = new Uint8Array(prefix.length + body.length);
+	message.set(prefix, 0);
+	message.set(body, prefix.length);
+	const digest = await getSubtle().sign("HMAC", key, message);
+	return toHex(new Uint8Array(digest));
 }
 function toHex(bytes) {
-  let hex = "";
-  for (const byte of bytes) {
-    hex += byte.toString(16).padStart(2, "0");
-  }
-  return hex;
+	let hex = "";
+	for (const byte of bytes) hex += byte.toString(16).padStart(2, "0");
+	return hex;
 }
+/**
+* Length-checked, constant-time comparison of two lowercase hex strings. Folds
+* every byte into an accumulator with XOR — never early-returns on the first
+* mismatch — so timing does not leak how much of the signature matched.
+*/
 function constantTimeEqualHex(a, b) {
-  if (a.length !== b.length) return false;
-  let diff = 0;
-  for (let i = 0; i < a.length; i++) {
-    diff |= a.charCodeAt(i) ^ b.charCodeAt(i);
-  }
-  return diff === 0;
+	if (a.length !== b.length) return false;
+	let diff = 0;
+	for (let i = 0; i < a.length; i++) diff |= a.charCodeAt(i) ^ b.charCodeAt(i);
+	return diff === 0;
 }
 function getSubtle() {
-  const subtle = globalThis.crypto?.subtle;
-  if (!subtle) {
-    throw new Error(
-      "Web Crypto (globalThis.crypto.subtle) is not available in this runtime. crawlbrulee webhook verification requires Node.js 20+, Bun, Deno, or a modern browser/edge runtime."
-    );
-  }
-  return subtle;
+	const subtle = globalThis.crypto?.subtle;
+	if (!subtle) throw new Error("Web Crypto (globalThis.crypto.subtle) is not available in this runtime. crawlbrulee webhook verification requires Node.js 22+, Bun, Deno, or a modern browser/edge runtime.");
+	return subtle;
 }
 
+//#endregion
 exports.AuthenticationError = AuthenticationError;
 exports.Crawlbrulee = Crawlbrulee;
 exports.CrawlbruleeError = CrawlbruleeError;
@@ -702,5 +864,4 @@ exports.WEBHOOK_SIGNATURE_HEADER = WEBHOOK_SIGNATURE_HEADER;
 exports.WEBHOOK_SIGNATURE_ROTATED_HEADER = WEBHOOK_SIGNATURE_ROTATED_HEADER;
 exports.isCrawlbruleeError = isCrawlbruleeError;
 exports.verifyWebhookSignature = verifyWebhookSignature;
-//# sourceMappingURL=index.cjs.map
 //# sourceMappingURL=index.cjs.map