firecrawl 4.41.0 → 4.42.1

package/src/v2/methods/batch.ts

@@ -152,7 +152,7 @@ export async function getBatchScrapeErrors(
   try {
     const res = await http.get<{
       success?: boolean;
-      data?: { errors: Array<Record<string, string>>; robotsBlocked: string[] };
+      data?: CrawlErrorsResponse;
     }>(`/v2/batch/scrape/${jobId}/errors`);
     if (res.status !== 200) throwForBadResponse(res, "get batch scrape errors");
     const payload = res.data?.data ?? (res.data as any);

package/src/v2/methods/crawl.ts

@@ -162,7 +162,7 @@ export async function crawl(http: HttpClient, request: CrawlRequest, pollInterva
 
 export async function getCrawlErrors(http: HttpClient, crawlId: string): Promise<CrawlErrorsResponse> {
   try {
-    const res = await http.get<{ success?: boolean; data?: { errors: Array<Record<string, string>>; robotsBlocked: string[] } }>(`/v2/crawl/${crawlId}/errors`);
+    const res = await http.get<{ success?: boolean; data?: CrawlErrorsResponse }>(`/v2/crawl/${crawlId}/errors`);
     if (res.status !== 200) throwForBadResponse(res, "get crawl errors");
     const payload = res.data?.data ?? (res.data as any);
     return { errors: payload.errors || [], robotsBlocked: payload.robotsBlocked || [] };

package/src/v2/methods/map.ts

@@ -1,5 +1,6 @@
 import { type MapData, type MapOptions, type SearchResultWeb } from "../types";
 import { HttpClient } from "../utils/httpClient";
+import { agentHintMetadata } from "../utils/agentHints";
 import {
   throwForBadResponse,
   normalizeAxiosError,
@@ -65,7 +66,7 @@ export async function map(
           description: (item as any).description,
         });
     }
-    return { id: res.data.id, links };
+    return { id: res.data.id, links, ...agentHintMetadata(res.data) };
   } catch (err: any) {
     if (err?.isAxiosError) return normalizeAxiosError(err, "map");
     throw err;

package/src/v2/methods/parse.ts

@@ -1,5 +1,6 @@
 import { type Document, type ParseFile, type ParseOptions } from "../types";
 import { HttpClient } from "../utils/httpClient";
+import { agentHintMetadata } from "../utils/agentHints";
 import { ensureValidParseOptions } from "../utils/validation";
 import {
   throwForBadResponse,
@@ -88,7 +89,7 @@ export async function parse(
     if (res.status !== 200 || !res.data?.success) {
       throwForBadResponse(res, "parse");
     }
-    return (res.data.data || {}) as Document;
+    return { ...res.data.data, ...agentHintMetadata(res.data) };
   } catch (err: any) {
     if (err?.isAxiosError) return normalizeAxiosError(err, "parse");
     throw err;

package/src/v2/methods/scrape.ts

@@ -6,6 +6,7 @@ import {
   type ScrapeOptions,
 } from "../types";
 import { HttpClient } from "../utils/httpClient";
+import { agentHintMetadata } from "../utils/agentHints";
 import { ensureValidScrapeOptions } from "../utils/validation";
 import {
   throwForBadResponse,
@@ -131,7 +132,7 @@ export async function scrape(
       if (res.status !== 200 || !res.data?.success) {
         throwForBadResponse(res, "scrape");
       }
-      return (res.data.data || {}) as Document;
+      return { ...res.data.data, ...agentHintMetadata(res.data) };
     } catch (err: any) {
       const delayMs = autoResume !== false ? processingContinuesDelayMs(err) : undefined;
       if (

package/src/v2/methods/search.ts

@@ -8,6 +8,7 @@ import {
   type SearchResultImages,
 } from "../types";
 import { HttpClient } from "../utils/httpClient";
+import { agentHintMetadata } from "../utils/agentHints";
 import { ensureValidScrapeOptions } from "../utils/validation";
 import {
   throwForBadResponse,
@@ -101,7 +102,7 @@ export async function search(
       throwForBadResponse(res, "search");
     }
     const data = (res.data.data || {}) as Record<string, any>;
-    const out: SearchData = {};
+    const out: SearchData = { ...agentHintMetadata(res.data) };
     if (res.data.warning) out.warning = res.data.warning;
     if (data.web) out.web = transformArray<SearchResultWeb>(data.web);
     if (data.news) out.news = transformArray<SearchResultNews>(data.news);

package/src/v2/types.ts

@@ -678,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;
@@ -820,6 +822,7 @@ export interface SearchResultImages {
 }
 
 export interface SearchData {
+  agent_hints?: string[];
   warning?: string;
   web?: Array<SearchResultWeb | Document>;
   news?: Array<SearchResultNews | Document>;
@@ -1086,6 +1089,7 @@ export interface BatchScrapeJob {
 }
 
 export interface MapData {
+  agent_hints?: string[];
   id?: string;
   links: SearchResultWeb[];
 }
@@ -1449,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. */
@@ -1460,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. */
@@ -1470,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;
@@ -1833,6 +1955,8 @@ export interface CrawlErrorsResponse {
     url: string;
     code?: string;
     error: string;
+    /** Present when the page needs provider terms accepted first. */
+    requiresAction?: RequiresAction;
   }[];
   robotsBlocked: string[];
 }
@@ -1876,6 +2000,7 @@ export function parseRequiresAction(value: unknown): RequiresAction | undefined
 }
 
 export class SdkError extends Error {
+  declare agent_hints?: string[];
   requestId?: string;
   status?: number;
   code?: string;
@@ -1956,11 +2081,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;
 }
-

package/src/v2/utils/httpClient.ts

@@ -4,6 +4,7 @@ import axios, {
   type AxiosResponse,
 } from "axios";
 import { getVersion } from "./getVersion";
+import { pinToApiOrigin } from "../../utils/apiOrigin";
 
 export interface HttpClientOptions {
   apiKey: string;
@@ -64,6 +65,7 @@ export class HttpClient {
     config.headers = {
       ...(config.headers || {}),
     };
+    if (config.url) config.url = pinToApiOrigin(this.apiUrl, config.url);
 
     let lastError: any;
     for (let attempt = 0; attempt < this.maxRetries; attempt++) {