firecrawl 4.40.0 → 4.42.0

package/src/__tests__/unit/v2/agent-thread.unit.test.ts

@@ -161,4 +161,126 @@ describe("v2.agent threads unit", () => {
       "/v2/agent/threads/thread-1?includeData=true",
     );
   });
+  test("startAgent forwards exchange.onTermsRequired and a terms approve", async () => {
+    const post = okPost();
+    const exchange = {
+      onTermsRequired: "ask" as const,
+      approve: { approvalId: "0199aaaa-0000-7000-8000-000000000000" },
+    };
+
+    await startAgent({ post } as any, {
+      prompt: "Continue",
+      threadId: "thread-1",
+      exchange,
+    });
+
+    expect(post).toHaveBeenCalledWith("/v2/agent", {
+      prompt: "Continue",
+      threadId: "thread-1",
+      exchange,
+    });
+  });
+
+  test("startAgent forwards exchange.onTermsRequired skip", async () => {
+    const post = okPost();
+
+    await startAgent({ post } as any, {
+      prompt: "Find the key business contact at exa.ai",
+      exchange: { onTermsRequired: "skip" },
+    });
+
+    expect(post).toHaveBeenCalledWith("/v2/agent", {
+      prompt: "Find the key business contact at exa.ai",
+      exchange: { onTermsRequired: "skip" },
+    });
+  });
+
+  test("getAgentStatus parses skippedProviders, requiresAction and a terms approval", async () => {
+    const approvalId = "0199aaaa-0000-7000-8000-000000000000";
+    const get = jest.fn().mockResolvedValue({
+      status: 200,
+      data: {
+        success: true,
+        status: "completed",
+        data: null,
+        model: "spark-2",
+        expiresAt: "2026-09-02T00:00:00.000Z",
+        exchange: {
+          enabled: true,
+          onTermsRequired: "ask",
+          paidCalls: 0,
+          creditsUsed: null,
+          skippedProviders: [
+            {
+              provider: "apollo",
+              name: "Apollo",
+              capability: "people/search",
+              adds: "verified work emails",
+              reason: "terms_required",
+              version: "F-1.0.0",
+              termsUrl: "https://www.firecrawl.dev/app/alexandria/apollo",
+            },
+          ],
+          requiresAction: {
+            type: "accept_terms",
+            approvalId,
+            providers: [
+              {
+                provider: "apollo",
+                name: "Apollo",
+                version: "F-1.0.0",
+                digest: null,
+                url: "https://www.firecrawl.dev/app/alexandria/apollo",
+                show: {
+                  provider: "firecrawl",
+                  capability: "terms/show",
+                  options: { provider: "apollo" },
+                },
+                accept: {
+                  provider: "firecrawl",
+                  capability: "terms/accept",
+                  options: {
+                    provider: "apollo",
+                    version: "F-1.0.0",
+                    digest: null,
+                    confirmed: true,
+                  },
+                },
+              },
+            ],
+          },
+        },
+        pendingApproval: {
+          id: approvalId,
+          kind: "terms",
+          reason: "Apollo could add verified work emails.",
+          calls: [],
+          terms: [
+            {
+              provider: "apollo",
+              name: "Apollo",
+              version: "F-1.0.0",
+              digest: null,
+              url: "https://www.firecrawl.dev/app/alexandria/apollo",
+            },
+          ],
+          resolution: null,
+        },
+      },
+    });
+
+    const status = await getAgentStatus({ get } as any, "agent-job");
+
+    expect(status.exchange!.onTermsRequired).toBe("ask");
+    expect(status.exchange!.skippedProviders![0].reason).toBe("terms_required");
+    const action = status.exchange!.requiresAction!;
+    expect(action.approvalId).toBe(approvalId);
+    expect(action.providers[0].accept.capability).toBe("terms/accept");
+    expect(action.providers[0].accept.options.digest).toBeNull();
+    const pending = status.pendingApproval!;
+    expect(pending.kind).toBe("terms");
+    if (pending.kind !== "terms") throw new Error("expected a terms approval");
+    expect(pending.calls).toEqual([]);
+    expect(pending.terms[0].provider).toBe("apollo");
+  });
 });

package/src/__tests__/unit/v2/extract.unit.test.ts

@@ -3,6 +3,29 @@ import { startExtract } from "../../../v2/methods/extract";
 import type { WebhookConfig } from "../../../v2/types";
 
 describe("v2.extract unit", () => {
+  test("omits discovery options from extract without mutating shared options", async () => {
+    const post = jest
+      .fn()
+      .mockResolvedValue({ status: 200, data: { id: "extract-job" } });
+    const scrapeOptions = {
+      toolDetail: "compact" as const,
+      domainTools: true,
+      onlyMainContent: true,
+    };
+    await startExtract({ post } as any, {
+      urls: ["https://example.com"],
+      scrapeOptions,
+    });
+    expect(post).toHaveBeenCalledWith("/v2/extract", {
+      urls: ["https://example.com"],
+      scrapeOptions: { onlyMainContent: true },
+    });
+    expect(scrapeOptions).toEqual({
+      toolDetail: "compact",
+      domainTools: true,
+      onlyMainContent: true,
+    });
+  });
   test("startExtract forwards string webhook in request payload", async () => {
     const post = jest.fn().mockResolvedValue({
       status: 200,

package/src/__tests__/unit/v2/tools.unit.test.ts

@@ -1,4 +1,12 @@
-import { afterAll, beforeAll, beforeEach, describe, expect, jest, test } from "@jest/globals";
+import {
+  afterAll,
+  beforeAll,
+  beforeEach,
+  describe,
+  expect,
+  jest,
+  test,
+} from "@jest/globals";
 import { createServer, type Server } from "node:http";
 import { FirecrawlClient } from "../../../v2/client";
 
@@ -52,6 +60,13 @@ const next = {
   capability: "find-tools",
   options: { providers: ["particle"], level: "tools" },
 };
+const compactTools = [tool, productionTool].map(
+  ({ provider, capability, description }) => ({
+    provider,
+    capability,
+    description,
+  }),
+);
 let server: Server;
 let client: FirecrawlClient;
 const sent: Array<{ body: any; id: string | undefined }> = [];
@@ -76,10 +91,20 @@ beforeAll(async () => {
           warning: "Example warning",
           data: {
             web: [{ url: "https://podcasts.apple.com" }],
-            tools: [tool, productionTool],
+            tools:
+              body.toolDetail === "compact"
+                ? compactTools
+                : [tool, productionTool],
           },
         }),
       );
+    if (req.url === "/v2/scrape" && body.url)
+      return res.end(
+        JSON.stringify({
+          success: true,
+          data: { markdown: "Example", tools: compactTools },
+        }),
+      );
     if (body.alexandria[0].provider === "retry" && attempts++ === 0) {
       res.statusCode = 502;
       return res.end("{}");
@@ -150,6 +175,26 @@ afterAll(async () => {
 });
 
 describe("Alexandria contracts and execution", () => {
+  test.each(["compact", "summary", "full"] as const)(
+    "forwards %s discovery detail",
+    async (toolDetail) => {
+      const result = await client.search("records", { toolDetail });
+      if (toolDetail === "compact") expect(result.tools).toEqual(compactTools);
+      expect(sent.at(-1)?.body).toMatchObject({ toolDetail });
+    },
+  );
+  test("URL scrape forwards compact detail and preserves tools", async () => {
+    const result = await client.scrape("https://example.com", {
+      domainTools: true,
+      toolDetail: "compact",
+    });
+    expect(sent.at(-1)?.body).toMatchObject({
+      url: "https://example.com",
+      domainTools: true,
+      toolDetail: "compact",
+    });
+    expect(result.tools).toEqual(compactTools);
+  });
   test("returns complete unified tools and warning beside web results", async () => {
     const result = await client.search("podcasts", {
       sources: ["web", { type: "alexandria" }],
@@ -226,15 +271,27 @@ describe("Alexandria contracts and execution", () => {
   });
 });
 
-
-test.each([[undefined, 80000], [1000, 31000], [100000, 80000]])(
+test.each([
+  [undefined, 80000],
+  [1000, 31000],
+  [100000, 80000],
+])(
   "Alexandria timeout %s allows response delivery (%s ms)",
   async (timeout, timeoutMs) => {
-    const http = { post: jest.fn(async () => ({ status: 200, data: {
-      success: true, data: { alexandria: [], creditsCost: 0 },
-    } })) };
+    const http = {
+      post: jest.fn(async () => ({
+        status: 200,
+        data: {
+          success: true,
+          data: { alexandria: [], creditsCost: 0 },
+        },
+      })),
+    };
     await scrapeAlexandria(http as any, [next], { timeout });
-    expect(http.post).toHaveBeenCalledWith("/v2/scrape", expect.anything(),
-      expect.objectContaining({ timeoutMs }));
+    expect(http.post).toHaveBeenCalledWith(
+      "/v2/scrape",
+      expect.anything(),
+      expect.objectContaining({ timeoutMs }),
+    );
   },
 );

package/src/v2/methods/extract.ts

@@ -40,7 +40,8 @@ function prepareExtractPayload(args: {
     body.threatProtection = args.threatProtection;
   if (args.scrapeOptions) {
     ensureValidScrapeOptions(args.scrapeOptions);
-    body.scrapeOptions = args.scrapeOptions;
+    const { toolDetail, domainTools, ...scrapeOptions } = args.scrapeOptions;
+    body.scrapeOptions = scrapeOptions;
   }
   return body;
 }

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,
@@ -27,6 +28,7 @@ function prepareSearchPayload(req: SearchRequest): Record<string, unknown> {
   const payload: Record<string, unknown> = {
     query: req.query,
   };
+  if (req.toolDetail != null) payload.toolDetail = req.toolDetail;
   if (req.domainTools != null) payload.domainTools = req.domainTools;
   if (req.sources) payload.sources = req.sources;
   if (req.categories) payload.categories = req.categories;
@@ -100,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);