firecrawl 4.39.0 → 4.41.0

package/src/v2/types.ts

@@ -188,6 +188,16 @@ export interface AuditMetadata {
   username: string;
 }
 
+/**
+ * OCR raster images (PNG, JPEG, JPEG 2000, TIFF, GIF, BMP, WebP, AVIF) as
+ * one-page documents. Part of the default parsers list next to "pdf"; takes
+ * no options, so the string "image" is equivalent. Omit it from an explicit
+ * list to keep image URLs failing as unsupported files.
+ */
+export type ImageParser = {
+  type: "image";
+};
+
 export type PDFParser = {
   type: "pdf";
   mode?: "fast" | "auto" | "ocr";
@@ -249,7 +259,7 @@ export interface ScrapeOptions {
   timeout?: number;
   waitFor?: number;
   mobile?: boolean;
-  parsers?: Array<string | PDFParser>;
+  parsers?: Array<string | PDFParser | ImageParser>;
   actions?: ActionOption[];
   location?: LocationConfig;
   skipTlsVerification?: boolean;
@@ -275,6 +285,10 @@ export interface ScrapeOptions {
   };
   integration?: string;
   origin?: string;
+  /** Include domain-matched Alexandria tools for this URL in `tools`. Default off. */
+  domainTools?: boolean;
+  /** Summary by default; compact returns identity and description, full includes contracts. */
+  toolDetail?: "compact" | "summary" | "full";
 }
 
 export type RedactPIIEntity =
@@ -304,8 +318,14 @@ export interface RedactPIIOptions {
  * fields you provide replace the team policy's values.
  */
 export interface ThreatProtectionOptions {
-  /** "off" disables scanning for this request; "normal" applies the policy. */
-  mode?: "off" | "normal";
+  /**
+   * "off" disables scanning for this request; "manual-only" enforces only the
+   * blacklist / whitelist / blocked TLDs (no provider scan, no scan fee);
+   * "normal" scans with Google Web Risk; "zscaler" classifies through your
+   * organization's Zscaler connection. Enforced teams may raise the mode per
+   * request but never lower it.
+   */
+  mode?: "off" | "manual-only" | "normal" | "zscaler";
   /** Block verdicts at or above this risk score (integer 0-100). */
   riskScoreThreshold?: number;
   /** Exact domains or globs like "*.example.com" to always block (max 1000). */
@@ -340,6 +360,7 @@ export type ParseOptions = Omit<
   | "lockdown"
   | "proxy"
   | "threatProtection"
+  | "toolDetail"
 > & {
   formats?: ParseFormatOption[];
   proxy?: "basic" | "auto";
@@ -685,6 +706,8 @@ export interface Document {
   pages?: PdfPage[];
   /** Typed PDF layout blocks, present only when `parsers[].blocks` is true. */
   blocks?: PdfPageBlocks[];
+  /** Present when `domainTools` discovered contracts matching this URL. */
+  tools?: DiscoveredTool[];
 }
 
 // Pagination configuration for auto-fetching pages from v2 endpoints that return a `next` URL
@@ -797,9 +820,130 @@ export interface SearchResultImages {
 }
 
 export interface SearchData {
+  warning?: string;
   web?: Array<SearchResultWeb | Document>;
   news?: Array<SearchResultNews | Document>;
   images?: Array<SearchResultImages | Document>;
+  tools?: DiscoveredTool[];
+}
+
+/** A complete tool contract returned by semantic or contextual discovery. */
+export interface DiscoveredTool {
+  next?: AlexandriaCall;
+  id?: string;
+  provider: string;
+  capability: string;
+  name?: string;
+  description: string;
+  creditsCost?: number;
+  perRecord?: boolean;
+  options?: Array<{
+    name: string;
+    type: string;
+    required?: boolean;
+    [key: string]: unknown;
+  }>;
+  requiresOneOf?: string[][];
+  response?: {
+    about?: string;
+    key?: string;
+    fields?: Array<{ name: string; type: string; [key: string]: unknown }>;
+    [key: string]: unknown;
+  };
+  examples?: Partial<Record<"javascript" | "python" | "curl", string>> &
+    Record<string, string>;
+  example?: {
+    recordedAt: string;
+    request: Record<string, unknown>;
+    response: unknown;
+  };
+  label?: string;
+  whenToUse?: string;
+  returns?: unknown;
+  discovery?: unknown;
+  attribution?: unknown;
+  matchedBy?: Array<"semantic" | "domain">;
+  matchedUrls?: string[];
+  concept?: string;
+  cohorts?: string[];
+  similarity?: number;
+}
+
+export interface FindToolsOptions {
+  urls?: string[];
+  providers?: string[];
+  categories?: string[];
+  groups?: string[];
+  capabilities?: string[];
+  level?: "providers" | "groups" | "tools";
+  expand?: Array<"options" | "response" | "examples">;
+  limit?: number;
+  offset?: number;
+}
+
+export interface FindToolsData {
+  level: "providers" | "groups" | "tools";
+  items: Array<{
+    id: string;
+    name: string;
+    next?: AlexandriaCall;
+    execute?: Pick<AlexandriaCall, "provider" | "capability">;
+    [key: string]: unknown;
+  }>;
+  total: number;
+  next: AlexandriaCall | null;
+}
+
+export interface AlexandriaScrapeRequest extends AlexandriaOptions {
+  alexandria: AlexandriaCall | AlexandriaCall[];
+}
+
+export interface AlexandriaCall {
+  provider: string;
+  capability: string;
+  options?: Record<string, unknown>;
+}
+
+export interface AlexandriaScrapeError {
+  code: string;
+  message: string;
+  status?: number;
+  /** Present when credits were captured before the failure. */
+  chargeId?: string;
+}
+
+export type AlexandriaScrapeResult =
+  | {
+      provider: string;
+      capability: string;
+      creditsCost: number;
+      data: unknown;
+      records?: number;
+      upstreamStatus?: number;
+      recordedAt?: string;
+      error?: undefined;
+      [key: string]: unknown;
+    }
+  | {
+      provider?: string;
+      capability?: string;
+      error: AlexandriaScrapeError;
+      [key: string]: unknown;
+    };
+
+export interface AlexandriaScrapeData {
+  scrapeId: string;
+  requestId: string;
+  alexandria: AlexandriaScrapeResult[];
+  creditsCost: number;
+}
+
+export interface AlexandriaOptions {
+  /** Reuse this ID with the identical payload when retrying an execution. */
+  requestId?: string;
+  timeout?: number;
+  integration?: string;
+  origin?: string;
 }
 
 /**
@@ -830,8 +974,13 @@ export interface CategoryOption {
 
 export interface SearchRequest {
   query: string;
+  /** Include domain-matched tools in tools alongside semantic matches. */
+  domainTools?: boolean;
+  /** Compact by default; summary adds metadata, full includes contracts. */
+  toolDetail?: "compact" | "summary" | "full";
   sources?: Array<
-    "web" | "news" | "images" | { type: "web" | "news" | "images" }
+    "web" | "news" | "images" | "alexandria"
+    | { type: "web" | "news" | "images" | "alexandria" }
   >;
   /**
    * Narrow web search by category. See {@link CategoryOption}.
@@ -855,7 +1004,7 @@ export interface SearchRequest {
   timeout?: number; // ms
   /** Generate query-relevant highlights for search results. Defaults to true. */
   highlights?: boolean;
-  scrapeOptions?: ScrapeOptions;
+  scrapeOptions?: Omit<ScrapeOptions, "toolDetail">;
   /**
    * Enterprise search options. Use `["zdr"]` for end-to-end Zero Data
    * Retention or `["anon"]` for anonymized search. Must be enabled for
@@ -884,7 +1033,7 @@ export interface CrawlOptions {
   delay?: number | null;
   maxConcurrency?: number | null;
   webhook?: string | WebhookConfig | null;
-  scrapeOptions?: ScrapeOptions | null;
+  scrapeOptions?: Omit<ScrapeOptions, "toolDetail"> | null;
   regexOnFullURL?: boolean;
   zeroDataRetention?: boolean;
   integration?: string;
@@ -908,7 +1057,7 @@ export interface CrawlJob {
 }
 
 export interface BatchScrapeOptions {
-  options?: ScrapeOptions;
+  options?: Omit<ScrapeOptions, "toolDetail">;
   webhook?: string | WebhookConfig;
   appendToId?: string;
   ignoreInvalidURLs?: boolean;
@@ -1058,7 +1207,7 @@ export interface MonitorScrapeTarget {
   id?: string;
   type: "scrape";
   urls: string[];
-  scrapeOptions?: ScrapeOptions;
+  scrapeOptions?: Omit<ScrapeOptions, "toolDetail">;
 }
 
 export interface MonitorCrawlTarget {
@@ -1066,7 +1215,7 @@ export interface MonitorCrawlTarget {
   type: "crawl";
   url: string;
   crawlOptions?: CrawlOptions;
-  scrapeOptions?: ScrapeOptions;
+  scrapeOptions?: Omit<ScrapeOptions, "toolDetail">;
 }
 
 export interface MonitorSearchTarget {
@@ -1707,17 +1856,43 @@ export interface ErrorDetails {
   status?: number;
 }
 
+/** An out-of-band step the API requires before the request can succeed. */
+export interface RequiresAction {
+  type: "accept_terms" | (string & {});
+  terms?: string;
+  version?: string;
+  url?: string;
+}
+
+export function parseRequiresAction(value: unknown): RequiresAction | undefined {
+  if (!value || typeof value !== "object") return undefined;
+  const record = value as Record<string, unknown>;
+  if (typeof record.type !== "string") return undefined;
+  const action: RequiresAction = { type: record.type };
+  if (typeof record.terms === "string") action.terms = record.terms;
+  if (typeof record.version === "string") action.version = record.version;
+  if (typeof record.url === "string") action.url = record.url;
+  return action;
+}
+
 export class SdkError extends Error {
+  requestId?: string;
   status?: number;
   code?: string;
   details?: unknown;
   jobId?: string;
+  /** Present on exchange-mediated scrape failures that already captured credits. */
+  chargeId?: string;
+  /** Present when the API needs an out-of-band step first, such as accepting provider terms. */
+  requiresAction?: RequiresAction;
   constructor(
     message: string,
     status?: number,
     code?: string,
     details?: unknown,
     jobId?: string,
+    chargeId?: string,
+    requiresAction?: RequiresAction,
   ) {
     super(message);
     this.name = "FirecrawlSdkError";
@@ -1725,6 +1900,8 @@ export class SdkError extends Error {
     this.code = code;
     this.details = details;
     this.jobId = jobId;
+    this.chargeId = chargeId;
+    this.requiresAction = requiresAction;
   }
 }
 

package/src/v2/utils/errorHandler.ts

@@ -1,11 +1,19 @@
 import { type AxiosError, type AxiosResponse } from "axios";
-import { SdkError, JobTimeoutError } from "../types";
+import { SdkError, JobTimeoutError, parseRequiresAction } from "../types";
 
 export function throwForBadResponse(resp: AxiosResponse, action: string): never {
   const status = resp.status;
   const body = resp.data || {};
   const msg = body?.error || body?.message || `Request failed (${status}) while trying to ${action}`;
-  throw new SdkError(msg, status, undefined, body?.details);
+  throw new SdkError(
+    msg,
+    status,
+    body?.code,
+    body?.details,
+    undefined,
+    body?.chargeId,
+    parseRequiresAction(body?.requiresAction),
+  );
 }
 
 export function normalizeAxiosError(err: AxiosError, action: string): never {
@@ -13,7 +21,15 @@ export function normalizeAxiosError(err: AxiosError, action: string): never {
   const body: any = err.response?.data;
   const message = body?.error || err.message || `Request failed${status ? ` (${status})` : ""} while trying to ${action}`;
   const code = (body?.code as string) || err.code;
-  throw new SdkError(message, status, code, body?.details ?? body);
+  throw new SdkError(
+    message,
+    status,
+    code,
+    body?.details ?? body,
+    undefined,
+    body?.chargeId,
+    parseRequiresAction(body?.requiresAction),
+  );
 }
 
 export function isRetryableError(err: any): boolean {