firecrawl 4.40.0 → 4.42.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,8 +285,10 @@ export interface ScrapeOptions {
   };
   integration?: string;
   origin?: string;
-  /** Include domain-matched Alexandria contracts for this URL in `tools`. Default off. */
+  /** 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 =
@@ -306,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). */
@@ -342,6 +360,7 @@ export type ParseOptions = Omit<
   | "lockdown"
   | "proxy"
   | "threatProtection"
+  | "toolDetail"
 > & {
   formats?: ParseFormatOption[];
   proxy?: "basic" | "auto";
@@ -659,6 +678,8 @@ export interface DocumentMetadata {
 }
 
 export interface Document {
+  /** API guidance, separate from extracted page content. */
+  agent_hints?: string[];
   markdown?: string;
   html?: string;
   rawHtml?: string;
@@ -801,6 +822,7 @@ export interface SearchResultImages {
 }
 
 export interface SearchData {
+  agent_hints?: string[];
   warning?: string;
   web?: Array<SearchResultWeb | Document>;
   news?: Array<SearchResultNews | Document>;
@@ -810,14 +832,15 @@ export interface SearchData {
 
 /** A complete tool contract returned by semantic or contextual discovery. */
 export interface DiscoveredTool {
+  next?: AlexandriaCall;
   id?: string;
   provider: string;
   capability: string;
-  name: string;
+  name?: string;
   description: string;
-  creditsCost: number;
-  perRecord: boolean;
-  options: Array<{
+  creditsCost?: number;
+  perRecord?: boolean;
+  options?: Array<{
     name: string;
     type: string;
     required?: boolean;
@@ -954,8 +977,10 @@ export interface CategoryOption {
 
 export interface SearchRequest {
   query: string;
-  /** Include domain-matched contracts in tools alongside semantic matches. */
+  /** 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" | "alexandria"
     | { type: "web" | "news" | "images" | "alexandria" }
@@ -982,7 +1007,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
@@ -1011,7 +1036,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;
@@ -1035,7 +1060,7 @@ export interface CrawlJob {
 }
 
 export interface BatchScrapeOptions {
-  options?: ScrapeOptions;
+  options?: Omit<ScrapeOptions, "toolDetail">;
   webhook?: string | WebhookConfig;
   appendToId?: string;
   ignoreInvalidURLs?: boolean;
@@ -1064,6 +1089,7 @@ export interface BatchScrapeJob {
 }
 
 export interface MapData {
+  agent_hints?: string[];
   id?: string;
   links: SearchResultWeb[];
 }
@@ -1185,7 +1211,7 @@ export interface MonitorScrapeTarget {
   id?: string;
   type: "scrape";
   urls: string[];
-  scrapeOptions?: ScrapeOptions;
+  scrapeOptions?: Omit<ScrapeOptions, "toolDetail">;
 }
 
 export interface MonitorCrawlTarget {
@@ -1193,7 +1219,7 @@ export interface MonitorCrawlTarget {
   type: "crawl";
   url: string;
   crawlOptions?: CrawlOptions;
-  scrapeOptions?: ScrapeOptions;
+  scrapeOptions?: Omit<ScrapeOptions, "toolDetail">;
 }
 
 export interface MonitorSearchTarget {
@@ -1427,9 +1453,83 @@ export interface AgentExchangeOptions {
   toolkits?: string[];
   maxCalls?: number;
   requireApproval?: boolean;
-  /** Answers a pendingApproval from the previous turn of the thread. */
+  /**
+   * Answers a pendingApproval from the previous turn of the thread. A `terms`
+   * approval is accepted or declined as a whole: `callIds` and `always` are
+   * ignored on it.
+   */
   approve?: { approvalId: string; callIds?: string[]; always?: boolean };
   decline?: { approvalId: string };
+  /**
+   * What to do when a provider the agent would use needs data terms the team
+   * has not accepted. Gated providers are never called in any mode:
+   * - "skip" (server default): answer with accepted providers only and list
+   *   the gated ones in `exchange.skippedProviders`.
+   * - "ask": the same, plus `exchange.requiresAction` and a `terms`
+   *   pendingApproval. Get your user's explicit consent, call terms/accept,
+   *   then continue the thread with `approve: { approvalId }`.
+   * Terms gating is rolling out: until it is on for a thread, none of the
+   * terms fields appear. There is no auto-accept mode. Omitted on a follow-up turn inherits the
+   * previous turn's value.
+   */
+  onTermsRequired?: AgentOnTermsRequired;
+}
+
+export type AgentOnTermsRequired = "skip" | "ask";
+
+/** A gated provider the run would have used but did not. */
+export interface AgentSkippedProvider {
+  provider: string;
+  name: string;
+  capability?: string;
+  /** What it would have added, in the agent's words. */
+  adds?: string;
+  reason: "terms_required";
+  /** The gating terms version. */
+  version: string;
+  /** Where a person accepts the terms in the dashboard. */
+  termsUrl: string;
+}
+
+/**
+ * The exact Exchange calls to view and accept a provider's terms. Nothing here
+ * is executed for you, and terms/accept must only be called after the user
+ * has explicitly agreed to that provider's terms.
+ */
+export interface AgentTermsRequiredAction {
+  type: "accept_terms";
+  /**
+   * The `terms` pendingApproval that answers this. After the user agrees and
+   * terms/accept succeeds, continue the thread with
+   * `exchange.approve: { approvalId }`, or refuse with `decline`.
+   */
+  approvalId: string;
+  providers: {
+    provider: string;
+    name: string;
+    capability?: string;
+    adds?: string;
+    version: string;
+    /** null when the catalog published no digest; terms/show returns it. */
+    digest: string | null;
+    url: string;
+    show: {
+      provider: "firecrawl";
+      capability: "terms/show";
+      options: { provider: string };
+    };
+    accept: {
+      provider: "firecrawl";
+      capability: "terms/accept";
+      options: {
+        provider: string;
+        version: string;
+        /** null when the catalog published no digest; terms/show returns it. */
+        digest: string | null;
+        confirmed: true;
+      };
+    };
+  }[];
 }
 
 /** Per-run summary reported on a status response. */
@@ -1438,8 +1538,26 @@ export interface AgentExchangeSummary {
   /** What the run resolved to after thread inheritance, not what it requested. */
   toolkits?: string[];
   requireApproval?: boolean;
+  onTermsRequired?: AgentOnTermsRequired;
   paidCalls: number;
   creditsUsed: number | null;
+  /** Gated providers that would have helped and were not used. Any mode. */
+  skippedProviders?: AgentSkippedProvider[];
+  /** "ask" mode, when a terms offer ended the turn. */
+  requiresAction?: AgentTermsRequiredAction;
+}
+
+/** A provider in a `terms` pendingApproval. */
+export interface AgentTermsGate {
+  provider: string;
+  name: string;
+  logo?: string;
+  capability?: string;
+  adds?: string;
+  version: string;
+  /** null when the catalog published no digest; terms/show returns it. */
+  digest: string | null;
+  url: string;
 }
 
 /** A follow-up the agent offers for the next turn of the thread. */
@@ -1448,26 +1566,52 @@ export interface AgentSuggestion {
   prompt: string;
 }
 
-/** A turn that ended waiting for the caller to allow or refuse paid calls. */
-export interface PendingApproval {
+/** A paid call a `calls` pendingApproval is holding back. */
+export interface PendingApprovalCall {
+  id: string;
+  provider: string;
+  capability: string;
+  input: Record<string, unknown>;
+  more?: Record<string, unknown>[];
+  creditsEstimate: number | null;
+}
+
+interface PendingApprovalBase {
   id: string;
   reason: string;
-  calls: {
-    id: string;
-    provider: string;
-    capability: string;
-    input: Record<string, unknown>;
-    more?: Record<string, unknown>[];
-    creditsEstimate: number | null;
-  }[];
   resolution: null | {
     approved: boolean;
+    /** Calls approved. Ignored on terms offers. */
     callIds: string[];
     always: boolean;
     byRunId: string;
   };
 }
 
+/**
+ * A turn that ended waiting for the caller to allow or refuse paid calls.
+ * `kind` is absent on items written before terms offers existed.
+ */
+export interface PendingCallsApproval extends PendingApprovalBase {
+  kind?: "calls";
+  calls: PendingApprovalCall[];
+  terms?: never;
+}
+
+/**
+ * A turn that ended waiting for the caller to accept providers' data terms
+ * ("ask" mode). `calls` is always empty (typed `never[]` rather
+ * than `[]` so existing `pendingApproval.calls[0]` code still compiles).
+ */
+export interface PendingTermsApproval extends PendingApprovalBase {
+  kind: "terms";
+  calls: never[];
+  terms: AgentTermsGate[];
+}
+
+/** Narrow on `kind === "terms"`. */
+export type PendingApproval = PendingCallsApproval | PendingTermsApproval;
+
 export interface AgentResponse {
   success: boolean;
   id: string;
@@ -1854,6 +1998,7 @@ export function parseRequiresAction(value: unknown): RequiresAction | undefined
 }
 
 export class SdkError extends Error {
+  declare agent_hints?: string[];
   requestId?: string;
   status?: number;
   code?: string;
@@ -1934,11 +2079,13 @@ export interface BrowserExecuteResponse {
   stderr?: string;
   exitCode?: number;
   killed?: boolean;
+  truncated?: boolean;
   error?: string;
 }
 
 export interface BrowserDeleteResponse {
   success: boolean;
+  status?: string;
   sessionDurationMs?: number;
   creditsBilled?: number;
   error?: string;

package/src/v2/utils/agentHints.ts

@@ -0,0 +1,7 @@
+/** Keep response guidance as metadata when convenience methods unwrap data. */
+export function agentHintMetadata(body: unknown): { agent_hints?: string[] } {
+  const hints = (body as { agent_hints?: unknown } | null)?.agent_hints;
+  return Array.isArray(hints) && hints.every((hint) => typeof hint === "string")
+    ? { agent_hints: [...hints] }
+    : {};
+}

package/src/v2/utils/errorHandler.ts

@@ -1,11 +1,12 @@
 import { type AxiosError, type AxiosResponse } from "axios";
 import { SdkError, JobTimeoutError, parseRequiresAction } from "../types";
+import { agentHintMetadata } from "./agentHints";
 
 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(
+  throw Object.assign(new SdkError(
     msg,
     status,
     body?.code,
@@ -13,7 +14,7 @@ export function throwForBadResponse(resp: AxiosResponse, action: string): never
     undefined,
     body?.chargeId,
     parseRequiresAction(body?.requiresAction),
-  );
+  ), agentHintMetadata(body));
 }
 
 export function normalizeAxiosError(err: AxiosError, action: string): never {
@@ -21,7 +22,7 @@ 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(
+  throw Object.assign(new SdkError(
     message,
     status,
     code,
@@ -29,7 +30,7 @@ export function normalizeAxiosError(err: AxiosError, action: string): never {
     undefined,
     body?.chargeId,
     parseRequiresAction(body?.requiresAction),
-  );
+  ), agentHintMetadata(body));
 }
 
 export function isRetryableError(err: any): boolean {
@@ -64,4 +65,3 @@ export function isRetryableError(err: any): boolean {
   // Default: retry on unknown errors (safer than not retrying)
   return true;
 }
-