Supercharge your AI agents with data from the web and beyond. Building the library for superintelligence. 🔥
TypeScript aiai-agentsai-crawlerai-scrapingai-searchcrawlerdata-extractionhtml-to-markdownllmmarkdownscraperscrapingweb-crawlerweb-dataweb-data-extractionweb-scraperweb-scrapingweb-searchwebscraping
Add country option to v2 search in seven SDKs (#4574)
claude[bot]b09eef415506
diff --git a/apps/go-sdk/options.go b/apps/go-sdk/options.goindex b9533aa4c..c1bd481b4 100644--- a/apps/go-sdk/options.go+++ b/apps/go-sdk/options.go@@ -171,6 +171,7 @@ type SearchOptions struct {Limit *int `json:"limit,omitempty"`TBS *string `json:"tbs,omitempty"`Location *string `json:"location,omitempty"`+ Country *string `json:"country,omitempty"`IgnoreInvalidURLs *bool `json:"ignoreInvalidURLs,omitempty"`Timeout *int `json:"timeout,omitempty"`Highlights *bool `json:"highlights,omitempty"`diff --git a/apps/go-sdk/options_test.go b/apps/go-sdk/options_test.goindex 40c80df09..5a2774d3e 100644--- a/apps/go-sdk/options_test.go+++ b/apps/go-sdk/options_test.go@@ -173,6 +173,26 @@ func TestSearchOptionsSerializesHighlights(t *testing.T) {}}+func TestSearchOptionsSerializesCountry(t *testing.T) {+ payload, err := json.Marshal(SearchOptions{Country: String("de")})+ if err != nil {+ t.Fatalf("Marshal SearchOptions: %v", err)+ }++ if !strings.Contains(string(payload), `"country":"de"`) {+ t.Fatalf("serialized search options = %s", payload)+ }++ payload, err = json.Marshal(SearchOptions{})+ if err != nil {+ t.Fatalf("Marshal SearchOptions: %v", err)+ }++ if strings.Contains(string(payload), `"country"`) {+ t.Fatalf("serialized search options without country = %s", payload)+ }+}+func TestAuditMetadataSerializesAcrossRequestOptions(t *testing.T) {metadata := &AuditMetadata{Username: "[email protected]"}for name, options := range map[string]interface{}{diff --git a/apps/java-sdk/src/main/java/com/firecrawl/models/SearchOptions.java b/apps/java-sdk/src/main/java/com/firecrawl/models/SearchOptions.javaindex 1553d4f65..585203b8b 100644--- a/apps/java-sdk/src/main/java/com/firecrawl/models/SearchOptions.java+++ b/apps/java-sdk/src/main/java/com/firecrawl/models/SearchOptions.java@@ -16,6 +16,7 @@ public class SearchOptions {private Integer limit;private String tbs;private String location;+ private String country;private Boolean ignoreInvalidURLs;private Integer timeout;private Boolean highlights;@@ -31,6 +32,7 @@ public class SearchOptions {public Integer getLimit() { return limit; }public String getTbs() { return tbs; }public String getLocation() { return location; }+ public String getCountry() { return country; }public Boolean getIgnoreInvalidURLs() { return ignoreInvalidURLs; }public Integer getTimeout() { return timeout; }public Boolean getHighlights() { return highlights; }@@ -47,6 +49,7 @@ public class SearchOptions {private Integer limit;private String tbs;private String location;+ private String country;private Boolean ignoreInvalidURLs;private Integer timeout;private Boolean highlights;@@ -69,6 +72,8 @@ public class SearchOptions {public Builder tbs(String tbs) { this.tbs = tbs; return this; }/** Location for search results (e.g., "US"). */public Builder location(String location) { this.location = location; return this; }+ /** Country code to geo-target search results (e.g., "us"). */+ public Builder country(String country) { this.country = country; return this; }/** Ignore invalid URLs in results. */public Builder ignoreInvalidURLs(Boolean ignoreInvalidURLs) { this.ignoreInvalidURLs = ignoreInvalidURLs; return this; }/** Timeout in milliseconds. */@@ -89,6 +94,7 @@ public class SearchOptions {o.limit = this.limit;o.tbs = this.tbs;o.location = this.location;+ o.country = this.country;o.ignoreInvalidURLs = this.ignoreInvalidURLs;o.timeout = this.timeout;o.highlights = this.highlights;diff --git a/apps/java-sdk/src/test/java/com/firecrawl/SearchOptionsTest.java b/apps/java-sdk/src/test/java/com/firecrawl/SearchOptionsTest.javaindex 7b8f1dc54..0e991dc76 100644--- a/apps/java-sdk/src/test/java/com/firecrawl/SearchOptionsTest.java+++ b/apps/java-sdk/src/test/java/com/firecrawl/SearchOptionsTest.java@@ -5,6 +5,7 @@ import com.fasterxml.jackson.databind.ObjectMapper;import com.firecrawl.models.SearchOptions;import org.junit.jupiter.api.Test;+import static org.junit.jupiter.api.Assertions.assertEquals;import static org.junit.jupiter.api.Assertions.assertFalse;import static org.junit.jupiter.api.Assertions.assertTrue;@@ -22,4 +23,15 @@ class SearchOptionsTest {assertFalse(disabled.get("highlights").asBoolean());assertFalse(omitted.has("highlights"));}++ @Test+ void serializesCountryOption() {+ ObjectMapper mapper = new ObjectMapper();+ JsonNode set = mapper.valueToTree(+ SearchOptions.builder().country("de").build());+ JsonNode omitted = mapper.valueToTree(SearchOptions.builder().build());++ assertEquals("de", set.get("country").asText());+ assertFalse(omitted.has("country"));+ }}diff --git a/apps/java-sdk/src/test/java/com/firecrawl/SearchTest.java b/apps/java-sdk/src/test/java/com/firecrawl/SearchTest.javaindex 46c977f79..dfb0d5ade 100644--- a/apps/java-sdk/src/test/java/com/firecrawl/SearchTest.java+++ b/apps/java-sdk/src/test/java/com/firecrawl/SearchTest.java@@ -153,6 +153,24 @@ class SearchTest {System.out.println(" Results: " + results.getWeb().size());}+ @Test+ @EnabledIfEnvironmentVariable(named = "FIRECRAWL_API_KEY", matches = ".*\\S.*")+ void testSearchWithCountry() {+ System.out.println("\n=== Test: Search with Country ===");++ SearchData results = client.search("best coffee shops",+ SearchOptions.builder()+ .country("de")+ .limit(5)+ .build());++ assertNotNull(results.getWeb(), "Web results should not be null");++ System.out.println("✓ Search with country completed");+ System.out.println(" Country: de");+ System.out.println(" Results: " + results.getWeb().size());+ }+@Test@EnabledIfEnvironmentVariable(named = "FIRECRAWL_API_KEY", matches = ".*\\S.*")void testSearchWithTimeFilter() {diff --git a/apps/js-sdk/firecrawl/src/__tests__/e2e/v2/batch.test.ts b/apps/js-sdk/firecrawl/src/__tests__/e2e/v2/batch.test.tsindex df09e1746..ffc07eaec 100644--- a/apps/js-sdk/firecrawl/src/__tests__/e2e/v2/batch.test.ts+++ b/apps/js-sdk/firecrawl/src/__tests__/e2e/v2/batch.test.ts@@ -4,6 +4,7 @@import Firecrawl from "../../../index";import { config } from "dotenv";import { getIdentity, getApiUrl } from "./utils/idmux";+import { testTimeoutMs, waitForJob, withRateLimitRetry } from "./utils/rateLimit";import { describe, test, expect, beforeAll } from "@jest/globals";config();@@ -13,7 +14,7 @@ let client: Firecrawl;beforeAll(async () => {const { apiKey } = await getIdentity({ name: "js-e2e-batch" });- client = new Firecrawl({ apiKey, apiUrl: API_URL });+ client = withRateLimitRetry(new Firecrawl({ apiKey, apiUrl: API_URL }));});describe("v2.batch e2e", () => {@@ -22,19 +23,21 @@ describe("v2.batch e2e", () => {"https://docs.firecrawl.dev","https://firecrawl.dev",];- const job = await client.batchScrape(urls, { options: { formats: ["markdown"] }, pollInterval: 1, timeout: 180 });+ const start = await client.startBatchScrape(urls, { options: { formats: ["markdown"] } });+ const job = await waitForJob(() => client.getBatchScrapeStatus(start.id), { pollInterval: 1, timeout: 210 });expect(["completed", "failed"]).toContain(job.status);expect(job.completed).toBeGreaterThanOrEqual(0);expect(job.total).toBeGreaterThanOrEqual(0);expect(Array.isArray(job.data)).toBe(true);- }, 240_000);+ }, testTimeoutMs(362_000));test("batch scrape with wait returns job id for error retrieval", async () => {const urls = ["https://docs.firecrawl.dev","https://firecrawl.dev",];- const job = await client.batchScrape(urls, { options: { formats: ["markdown"] }, pollInterval: 1, timeout: 180 });+ const start = await client.startBatchScrape(urls, { options: { formats: ["markdown"] } });+ const job = await waitForJob(() => client.getBatchScrapeStatus(start.id), { pollInterval: 1, timeout: 210 });// Verify job has id fieldexpect(job.id).toBeDefined();expect(typeof job.id).toBe("string");@@ -44,7 +47,7 @@ describe("v2.batch e2e", () => {expect(errors).toHaveProperty("robotsBlocked");expect(Array.isArray(errors.errors)).toBe(true);expect(Array.isArray(errors.robotsBlocked)).toBe(true);- }, 240_000);+ }, testTimeoutMs(512_000));test("start batch minimal and status", async () => {const urls = ["https://docs.firecrawl.dev", "https://firecrawl.dev"];@@ -57,11 +60,11 @@ describe("v2.batch e2e", () => {// Verify status includes id fieldexpect(status.id).toBeDefined();expect(status.id).toBe(start.id);- }, 120_000);+ }, testTimeoutMs(151_000));test("wait batch with all params", async () => {const urls = ["https://docs.firecrawl.dev", "https://firecrawl.dev"];- const job = await client.batchScrape(urls, {+ const start = await client.startBatchScrape(urls, {options: {formats: ["markdown",@@ -74,14 +77,13 @@ describe("v2.batch e2e", () => {ignoreInvalidURLs: true,maxConcurrency: 2,zeroDataRetention: false,- pollInterval: 1,- timeout: 180,});+ const job = await waitForJob(() => client.getBatchScrapeStatus(start.id), { pollInterval: 1, timeout: 210 });expect(["completed", "failed", "cancelled"]).toContain(job.status);expect(job.completed).toBeGreaterThanOrEqual(0);expect(job.total).toBeGreaterThanOrEqual(0);expect(Array.isArray(job.data)).toBe(true);- }, 300_000);+ }, testTimeoutMs(362_000));test("cancel batch", async () => {const urls = ["https://docs.firecrawl.dev", "https://firecrawl.dev"];@@ -89,6 +91,6 @@ describe("v2.batch e2e", () => {expect(typeof start.id).toBe("string");const cancelled = await client.cancelBatchScrape(start.id);expect(cancelled).toBe(true);- }, 120_000);+ }, testTimeoutMs(151_000));});diff --git a/apps/js-sdk/firecrawl/src/__tests__/e2e/v2/crawl.test.ts b/apps/js-sdk/firecrawl/src/__tests__/e2e/v2/crawl.test.tsindex 97f36b5d8..4be07ed3f 100644--- a/apps/js-sdk/firecrawl/src/__tests__/e2e/v2/crawl.test.ts+++ b/apps/js-sdk/firecrawl/src/__tests__/e2e/v2/crawl.test.ts@@ -4,6 +4,7 @@import Firecrawl from "../../../index";import { config } from "dotenv";import { getIdentity, getApiUrl } from "./utils/idmux";+import { testTimeoutMs, waitForJob, withRateLimitRetry } from "./utils/rateLimit";import { describe, test, expect, beforeAll } from "@jest/globals";config();@@ -13,7 +14,7 @@ let client: Firecrawl;beforeAll(async () => {const { apiKey } = await getIdentity({ name: "js-e2e-crawl" });- client = new Firecrawl({ apiKey, apiUrl: API_URL });+ client = withRateLimitRetry(new Firecrawl({ apiKey, apiUrl: API_URL }));});describe("v2.crawl e2e", () => {@@ -23,21 +24,21 @@ describe("v2.crawl e2e", () => {const job = await client.startCrawl("https://docs.firecrawl.dev", { limit: 3 });expect(typeof job.id).toBe("string");expect(typeof job.url).toBe("string");- }, 90_000);+ }, testTimeoutMs(90_000));test("start crawl with options", async () => {if (!client) throw new Error();const job = await client.startCrawl("https://docs.firecrawl.dev", { limit: 5, maxDiscoveryDepth: 2 });expect(typeof job.id).toBe("string");expect(typeof job.url).toBe("string");- }, 90_000);+ }, testTimeoutMs(90_000));test("start crawl with prompt", async () => {if (!client) throw new Error();const job = await client.startCrawl("https://firecrawl.dev", { prompt: "Extract all blog posts", limit: 3 });expect(typeof job.id).toBe("string");expect(typeof job.url).toBe("string");- }, 90_000);+ }, testTimeoutMs(90_000));test("get crawl status", async () => {if (!client) throw new Error();@@ -50,14 +51,14 @@ describe("v2.crawl e2e", () => {expect(status.id).toBe(start.id);// next/expiresAt may be null/undefined depending on state; check shapeexpect(Array.isArray(status.data)).toBe(true);- }, 120_000);+ }, testTimeoutMs(151_000));test("cancel crawl", async () => {if (!client) throw new Error();const start = await client.startCrawl("https://docs.firecrawl.dev", { limit: 3 });const ok = await client.cancelCrawl(start.id);expect(ok).toBe(true);- }, 120_000);+ }, testTimeoutMs(151_000));test("get crawl errors", async () => {if (!client) throw new Error();@@ -73,12 +74,12 @@ describe("v2.crawl e2e", () => {expect(typeof e.url === "string" || e.url == null).toBe(true);expect(typeof e.error === "string" || e.error == null).toBe(true);}- }, 120_000);+ }, testTimeoutMs(151_000));test("get crawl errors with invalid id should throw", async () => {if (!client) throw new Error();await expect(client.getCrawlErrors("invalid-job-id-12345")).rejects.toThrow();- }, 60_000);+ }, testTimeoutMs(60_000));test("get active crawls", async () => {if (!client) throw new Error();@@ -93,7 +94,7 @@ describe("v2.crawl e2e", () => {expect(typeof c.options === "object").toBe(true);}}- }, 90_000);+ }, testTimeoutMs(90_000));test("get active crawls with running crawl", async () => {if (!client) throw new Error();@@ -104,20 +105,22 @@ describe("v2.crawl e2e", () => {const ids = active.crawls.map(c => c.id);expect(ids.includes(start.id)).toBe(true);await client.cancelCrawl(start.id);- }, 120_000);+ }, testTimeoutMs(301_000));test("crawl with wait", async () => {if (!client) throw new Error();- const job = await client.crawl("https://docs.firecrawl.dev", { limit: 3, maxDiscoveryDepth: 2, pollInterval: 1, timeout: 120 });+ const start = await client.startCrawl("https://docs.firecrawl.dev", { limit: 3, maxDiscoveryDepth: 2 });+ const job = await waitForJob(() => client.getCrawlStatus(start.id), { pollInterval: 1, timeout: 120 });expect(["completed", "failed"]).toContain(job.status);expect(job.completed).toBeGreaterThanOrEqual(0);expect(job.total).toBeGreaterThanOrEqual(0);expect(Array.isArray(job.data)).toBe(true);- }, 180_000);+ }, testTimeoutMs(272_000));test("crawl with wait returns job id for error retrieval", async () => {if (!client) throw new Error();- const job = await client.crawl("https://docs.firecrawl.dev", { limit: 3, maxDiscoveryDepth: 2, pollInterval: 1, timeout: 120 });+ const start = await client.startCrawl("https://docs.firecrawl.dev", { limit: 3, maxDiscoveryDepth: 2 });+ const job = await waitForJob(() => client.getCrawlStatus(start.id), { pollInterval: 1, timeout: 120 });// Verify job has id fieldexpect(job.id).toBeDefined();expect(typeof job.id).toBe("string");@@ -127,16 +130,17 @@ describe("v2.crawl e2e", () => {expect(errors).toHaveProperty("robotsBlocked");expect(Array.isArray(errors.errors)).toBe(true);expect(Array.isArray(errors.robotsBlocked)).toBe(true);- }, 180_000);+ }, testTimeoutMs(422_000));test("crawl with prompt and wait", async () => {if (!client) throw new Error();- const job = await client.crawl("https://docs.firecrawl.dev", { prompt: "Extract all blog posts", limit: 3, pollInterval: 1, timeout: 120 });+ const start = await client.startCrawl("https://docs.firecrawl.dev", { prompt: "Extract all blog posts", limit: 3 });+ const job = await waitForJob(() => client.getCrawlStatus(start.id), { pollInterval: 1, timeout: 120 });expect(["completed", "failed"]).toContain(job.status);expect(job.completed).toBeGreaterThanOrEqual(0);expect(job.total).toBeGreaterThanOrEqual(0);expect(Array.isArray(job.data)).toBe(true);- }, 180_000);+ }, testTimeoutMs(272_000));test("crawl with scrape options", async () => {if (!client) throw new Error();@@ -145,7 +149,7 @@ describe("v2.crawl e2e", () => {scrapeOptions: { formats: ["markdown", "links"], onlyMainContent: false, mobile: true },});expect(typeof job.id).toBe("string");- }, 120_000);+ }, testTimeoutMs(120_000));test("crawl with json format object", async () => {if (!client) throw new Error();@@ -154,7 +158,7 @@ describe("v2.crawl e2e", () => {scrapeOptions: { formats: [{ type: "json", prompt: "Extract page title", schema: { type: "object", properties: { title: { type: "string" } }, required: ["title"] } }] },});expect(typeof job.id).toBe("string");- }, 120_000);+ }, testTimeoutMs(120_000));test("crawl all parameters", async () => {if (!client) throw new Error();@@ -187,13 +191,13 @@ describe("v2.crawl e2e", () => {zeroDataRetention: false,});expect(typeof job.id).toBe("string");- }, 180_000);+ }, testTimeoutMs(180_000));test("crawl params preview", async () => {if (!client) throw new Error();const params = await client.crawlParamsPreview("https://docs.firecrawl.dev", "Extract all blog posts and documentation");expect(params && typeof params === "object").toBe(true);// Optional fields may or may not be present; just assert object shape- }, 60_000);+ }, testTimeoutMs(60_000));});diff --git a/apps/js-sdk/firecrawl/src/__tests__/e2e/v2/extract.test.ts b/apps/js-sdk/firecrawl/src/__tests__/e2e/v2/extract.test.tsindex 2ad2d0424..3ff4279bc 100644--- a/apps/js-sdk/firecrawl/src/__tests__/e2e/v2/extract.test.ts+++ b/apps/js-sdk/firecrawl/src/__tests__/e2e/v2/extract.test.ts@@ -4,6 +4,7 @@import Firecrawl from "../../../index";import { config } from "dotenv";import { getIdentity, getApiUrl } from "./utils/idmux";+import { testTimeoutMs, waitForJob, withRateLimitRetry } from "./utils/rateLimit";import { describe, test, expect, beforeAll } from "@jest/globals";import { z } from "zod";@@ -14,14 +15,38 @@ let client: Firecrawl;beforeAll(async () => {const { apiKey } = await getIdentity({ name: "js-e2e-extract" });- client = new Firecrawl({ apiKey, apiUrl: API_URL });+ client = withRateLimitRetry(new Firecrawl({ apiKey, apiUrl: API_URL }));});describe("v2.extract e2e", () => {+ /**+ * Starts an extract, then polls it. Mirrors client.extract, but keeps every+ * request retryable: the wrapper cannot run client.extract again, because a+ * second run would start a second job.+ *+ * The bound is 180s, the time an extract needs, and the same bound batch+ * uses.+ *+ * The bound is not the whole cost of the test. startExtract goes through+ * the wrapper too, so it can spend the retry budget before the poll starts:+ * 150s for the start, plus 180 + 2 + 150 = 332s for the poll, so 482s. Each+ * test below therefore carries a 333_000 ms base, which gives 483s. The+ * unit test "every wrapped call in a test fits its budget" holds that sum.+ */+ async function extractAndWait(+ args: Parameters<typeof client.startExtract>[0],+ ) {+ const started = await client.startExtract(args);+ if (!started.id) return started;+ return waitForJob(() => client.getExtractStatus(started.id!), {+ timeout: 180,+ });+ }+test("extract minimal with prompt", async () => {- const resp = await client.extract({ urls: ["https://docs.firecrawl.dev"], prompt: "Extract the main page title" });+ const resp = await extractAndWait({ urls: ["https://docs.firecrawl.dev"], prompt: "Extract the main page title" });expect(typeof resp.success === "boolean" || resp.success == null).toBe(true);- }, 120_000);+ }, testTimeoutMs(333_000));test("extract with schema", async () => {const schema = {@@ -29,7 +54,7 @@ describe("v2.extract e2e", () => {properties: { title: { type: "string" } },required: ["title"],} as const;- const resp = await client.extract({+ const resp = await extractAndWait({urls: ["https://docs.firecrawl.dev"],schema,prompt: "Extract the main page title",@@ -44,13 +69,13 @@ describe("v2.extract e2e", () => {expect(typeof resp.data).toBe("object");expect((resp.data as any).title).toBeTruthy();}- }, 180_000);+ }, testTimeoutMs(333_000));test("extract with zod schema", async () => {const schema = z.object({title: z.string(),});- const resp = await client.extract({+ const resp = await extractAndWait({urls: ["https://docs.firecrawl.dev"],schema: schema,prompt: "Extract the main page title",@@ -65,6 +90,6 @@ describe("v2.extract e2e", () => {expect(typeof resp.data).toBe("object");expect(schema.safeParse(resp.data).success).toBe(true);}- }, 180_000);+ }, testTimeoutMs(333_000));});diff --git a/apps/js-sdk/firecrawl/src/__tests__/e2e/v2/map.test.ts b/apps/js-sdk/firecrawl/src/__tests__/e2e/v2/map.test.tsindex 560b4e16f..2845b5cdc 100644--- a/apps/js-sdk/firecrawl/src/__tests__/e2e/v2/map.test.ts+++ b/apps/js-sdk/firecrawl/src/__tests__/e2e/v2/map.test.ts@@ -4,6 +4,7 @@import Firecrawl from "../../../index";import { config } from "dotenv";import { getIdentity, getApiUrl } from "./utils/idmux";+import { testTimeoutMs, withRateLimitRetry } from "./utils/rateLimit";import { describe, test, expect, beforeAll } from "@jest/globals";config();@@ -13,7 +14,7 @@ let client: Firecrawl;beforeAll(async () => {const { apiKey } = await getIdentity({ name: "js-e2e-map" });- client = new Firecrawl({ apiKey, apiUrl: API_URL });+ client = withRateLimitRetry(new Firecrawl({ apiKey, apiUrl: API_URL }));});describe("v2.map e2e", () => {@@ -30,7 +31,7 @@ describe("v2.map e2e", () => {expect(typeof first.url).toBe("string");expect(first.url.startsWith("http")).toBe(true);}- }, 90_000);+ }, testTimeoutMs(90_000));test.each(["only", "skip", "include"]) ("with options sitemap=%s", async (sitemap) => {if (!client) throw new Error();@@ -50,6 +51,6 @@ describe("v2.map e2e", () => {expect(typeof link.url).toBe("string");expect(link.url.startsWith("http")).toBe(true);}- }, 120_000);+ }, testTimeoutMs(120_000));});diff --git a/apps/js-sdk/firecrawl/src/__tests__/e2e/v2/parse.test.ts b/apps/js-sdk/firecrawl/src/__tests__/e2e/v2/parse.test.tsindex 11c327356..21d54e199 100644--- a/apps/js-sdk/firecrawl/src/__tests__/e2e/v2/parse.test.ts+++ b/apps/js-sdk/firecrawl/src/__tests__/e2e/v2/parse.test.ts@@ -1,6 +1,7 @@import Firecrawl from "../../../index";import { config } from "dotenv";import { getIdentity, getApiUrl } from "./utils/idmux";+import { testTimeoutMs, withRateLimitRetry } from "./utils/rateLimit";import { describe, test, expect, beforeAll } from "@jest/globals";config();@@ -10,7 +11,7 @@ let client: Firecrawl;beforeAll(async () => {const { apiKey } = await getIdentity({ name: "js-e2e-parse" });- client = new Firecrawl({ apiKey, apiUrl: API_URL });+ client = withRateLimitRetry(new Firecrawl({ apiKey, apiUrl: API_URL }));});describe("v2.parse e2e", () => {@@ -41,7 +42,7 @@ describe("v2.parse e2e", () => {expect(doc.markdown).toContain("JS SDK Parse E2E");expect(doc.metadata?.creditsUsed).toBe(1);},- 60_000,+ testTimeoutMs(60_000),);test(@@ -62,6 +63,6 @@ describe("v2.parse e2e", () => {),).rejects.toThrow();},- 60_000,+ testTimeoutMs(60_000),);});diff --git a/apps/js-sdk/firecrawl/src/__tests__/e2e/v2/scrape.test.ts b/apps/js-sdk/firecrawl/src/__tests__/e2e/v2/scrape.test.tsindex e44663768..2edb21f83 100644--- a/apps/js-sdk/firecrawl/src/__tests__/e2e/v2/scrape.test.ts+++ b/apps/js-sdk/firecrawl/src/__tests__/e2e/v2/scrape.test.ts@@ -5,6 +5,7 @@ import Firecrawl from "../../../index";import { z } from "zod";import { config } from "dotenv";import { getIdentity, getApiUrl } from "./utils/idmux";+import { testTimeoutMs, withRateLimitRetry } from "./utils/rateLimit";import { describe, test, expect, beforeAll } from "@jest/globals";config();@@ -14,7 +15,7 @@ let client: Firecrawl;beforeAll(async () => {const { apiKey } = await getIdentity({ name: "js-e2e-scrape" });- client = new Firecrawl({ apiKey, apiUrl: API_URL });+ client = withRateLimitRetry(new Firecrawl({ apiKey, apiUrl: API_URL }));});describe("v2.scrape e2e", () => {@@ -30,7 +31,7 @@ describe("v2.scrape e2e", () => {if (!client) throw new Error();const doc = await client.scrape("https://docs.firecrawl.dev");assertValidDocument(doc);- }, 60_000);+ }, testTimeoutMs(60_000));test("maximal: scrape with all options", async () => {if (!client) throw new Error();@@ -71,7 +72,7 @@ describe("v2.scrape e2e", () => {maxAge: 60_000,});assertValidDocument(doc);- }, 90_000);+ }, testTimeoutMs(90_000));test("json format with zod schema (auto-converted internally)", async () => {if (!client) throw new Error();@@ -90,14 +91,14 @@ describe("v2.scrape e2e", () => {],});expect(doc).toBeTruthy();- }, 90_000);+ }, testTimeoutMs(90_000));test("summary format returns summary string", async () => {if (!client) throw new Error();const doc = await client.scrape("https://firecrawl.dev", { formats: ["summary"] });expect(typeof doc.summary).toBe("string");expect((doc.summary || "").length).toBeGreaterThan(10);- }, 90_000);+ }, testTimeoutMs(90_000));test.each([["markdown", "markdown"],@@ -119,7 +120,7 @@ describe("v2.scrape e2e", () => {expect(Array.isArray(doc.links)).toBe(true);expect((doc.links || []).length).toBeGreaterThan(0);}- }, 90_000);+ }, testTimeoutMs(90_000));test("images format: extract all images from webpage", async () => {if (!client) throw new Error();@@ -131,7 +132,7 @@ describe("v2.scrape e2e", () => {expect(doc.images?.length).toBeGreaterThan(0);// Should find firecrawl logo/branding imagesexpect(doc.images?.some(img => img.includes("firecrawl") || img.includes("logo"))).toBe(true);- }, 60_000);+ }, testTimeoutMs(60_000));test("images format: works with multiple formats", async () => {if (!client) throw new Error();@@ -152,12 +153,12 @@ describe("v2.scrape e2e", () => {// Should discover additional images beyond those with obvious extensionsexpect(doc.images?.length).toBeGreaterThanOrEqual(linkImages.length);- }, 60_000);+ }, testTimeoutMs(60_000));test("invalid url should throw", async () => {if (!client) throw new Error();await expect(client.scrape("")).rejects.toThrow("URL cannot be empty");await expect(client.scrape(" ")).rejects.toThrow("URL cannot be empty");- });+ }, testTimeoutMs(151_000));});diff --git a/apps/js-sdk/firecrawl/src/__tests__/e2e/v2/search.test.ts b/apps/js-sdk/firecrawl/src/__tests__/e2e/v2/search.test.tsindex b1b31ffd2..68e9becc3 100644--- a/apps/js-sdk/firecrawl/src/__tests__/e2e/v2/search.test.ts+++ b/apps/js-sdk/firecrawl/src/__tests__/e2e/v2/search.test.ts@@ -5,6 +5,7 @@ import Firecrawl from "../../../index";import type { Document, SearchResultWeb, SearchResultNews, SearchResultImages } from "../../../index";import { config } from "dotenv";import { getIdentity, getApiUrl } from "./utils/idmux";+import { testTimeoutMs, withRateLimitRetry } from "./utils/rateLimit";import { describe, test, expect, beforeAll } from "@jest/globals";config();@@ -14,7 +15,7 @@ let client: Firecrawl;beforeAll(async () => {const { apiKey } = await getIdentity({ name: "js-e2e-search" });- client = new Firecrawl({ apiKey, apiUrl: API_URL });+ client = withRateLimitRetry(new Firecrawl({ apiKey, apiUrl: API_URL }));});function collectTexts(entries: any[] | undefined): string[] {@@ -72,7 +73,7 @@ describe("v2.search e2e", () => {expect(results.news == null).toBe(true);expect(results.images == null).toBe(true);- }, 90_000);+ }, testTimeoutMs(90_000));test("with sources web+news and limit", async () => {if (!client) throw new Error();@@ -93,7 +94,7 @@ describe("v2.search e2e", () => {.map(r => (r.description || "").toString().toLowerCase());const allWebText = (webTitles.concat(webDescriptions)).join(" ");expect(allWebText.includes("firecrawl")).toBe(true);- }, 90_000);+ }, testTimeoutMs(90_000));test("result structure", async () => {if (!client) throw new Error();@@ -108,7 +109,7 @@ describe("v2.search e2e", () => {expect(typeof result.description === "string" || result.description == null).toBe(true);expect(result.url.startsWith("http")).toBe(true);}- }, 90_000);+ }, testTimeoutMs(90_000));test("all parameters (comprehensive)", async () => {if (!client) throw new Error();@@ -196,7 +197,7 @@ describe("v2.search e2e", () => {expect(result.url?.startsWith("http")).toBe(true);}}- }, 120_000);+ }, testTimeoutMs(120_000));test("formats flexibility: list vs object", async () => {if (!client) throw new Error();@@ -212,7 +213,7 @@ describe("v2.search e2e", () => {expect(results2).toBeTruthy();expect(results1.web).toBeTruthy();expect(results2.web).toBeTruthy();- }, 90_000);+ }, testTimeoutMs(151_000));test("with json format object", async () => {if (!client) throw new Error();@@ -229,7 +230,7 @@ describe("v2.search e2e", () => {});expect(results).toBeTruthy();expect(Array.isArray(results.web) || results.web == null).toBe(true);- }, 90_000);+ }, testTimeoutMs(90_000));test("with summary format, documents include summary when present", async () => {if (!client) throw new Error();@@ -242,6 +243,6 @@ describe("v2.search e2e", () => {expect(typeof docs[0].summary).toBe("string");expect((docs[0].summary || "").length).toBeGreaterThan(5);}- }, 90_000);+ }, testTimeoutMs(90_000));});diff --git a/apps/js-sdk/firecrawl/src/__tests__/e2e/v2/usage.test.ts b/apps/js-sdk/firecrawl/src/__tests__/e2e/v2/usage.test.tsindex e11d7527e..0d1a7e1b7 100644--- a/apps/js-sdk/firecrawl/src/__tests__/e2e/v2/usage.test.ts+++ b/apps/js-sdk/firecrawl/src/__tests__/e2e/v2/usage.test.ts@@ -4,6 +4,7 @@import Firecrawl from "../../../index";import { config } from "dotenv";import { getIdentity, getApiUrl } from "./utils/idmux";+import { testTimeoutMs, withRateLimitRetry } from "./utils/rateLimit";import { describe, test, expect, beforeAll } from "@jest/globals";config();@@ -13,7 +14,7 @@ let client: Firecrawl;beforeAll(async () => {const { apiKey } = await getIdentity({ name: "js-e2e-usage" });- client = new Firecrawl({ apiKey, apiUrl: API_URL });+ client = withRateLimitRetry(new Firecrawl({ apiKey, apiUrl: API_URL }));});describe("v2.usage e2e", () => {@@ -21,17 +22,17 @@ describe("v2.usage e2e", () => {const resp = await client.getConcurrency();expect(typeof resp.concurrency).toBe("number");expect(typeof resp.maxConcurrency).toBe("number");- }, 60_000);+ }, testTimeoutMs(60_000));test("get_credit_usage", async () => {const resp = await client.getCreditUsage();expect(typeof resp.remainingCredits).toBe("number");- }, 60_000);+ }, testTimeoutMs(60_000));test("get_token_usage", async () => {const resp = await client.getTokenUsage();expect(typeof resp.remainingTokens).toBe("number");- }, 60_000);+ }, testTimeoutMs(60_000));test("get_queue_status", async () => {const resp = await client.getQueueStatus();@@ -39,6 +40,6 @@ describe("v2.usage e2e", () => {expect(typeof resp.activeJobsInQueue).toBe("number");expect(typeof resp.waitingJobsInQueue).toBe("number");expect(typeof resp.maxConcurrency).toBe("number");- }, 60_000);+ }, testTimeoutMs(60_000));});diff --git a/apps/js-sdk/firecrawl/src/__tests__/e2e/v2/utils/rateLimit.ts b/apps/js-sdk/firecrawl/src/__tests__/e2e/v2/utils/rateLimit.tsnew file mode 100644index 000000000..979ec8279--- /dev/null+++ b/apps/js-sdk/firecrawl/src/__tests__/e2e/v2/utils/rateLimit.ts@@ -0,0 +1,257 @@+/**+ * Rate-limit retry for the v2 e2e suites.+ *+ * The e2e suites run against a live API. Each suite mints a CI identity through+ * idmux, and that identity gets the base per-minute limits: 2/min for crawl and+ * extract, 10/min for scrape, search and map, 500/min for job status. Several+ * suites send more calls than that in one minute, so the API answers 429 and the+ * suite fails.+ *+ * This helper wraps a client so every call waits for the limit window to reset+ * and then runs again. It is test-only code. The shipped SDK keeps its own retry+ * behaviour.+ *+ * Batch scrape creation counts against the scrape limit, not a limit of its+ * own. Job status reads use the 500/min limit, so they almost never wait.+ *+ * The wrapper only runs a call again when the refused request created nothing.+ * A single request is safe: the API rejected it, so no job exists. A composite+ * method is not safe. It starts a job, then polls that job. The poll can hit+ * the limit after the job exists, and a second run of the method would start a+ * second job. The wrapper passes these methods straight through, so they get no+ * retry. See COMPOSITE_METHODS.+ *+ * A suite that needs a job therefore does the two steps itself: it calls the+ * start method, then waitForJob. Both calls go through the wrapper, so both+ * retry, and the job starts once.+ */++/** Attempts per call, including the first one. */+const MAX_ATTEMPTS = 3;++/** Wait used when the error carries no reset time. */+const FALLBACK_WAIT_MS = 30_000;++/** Upper bound for one wait. The API window is 60 seconds. */+const MAX_WAIT_MS = 75_000;++/** Added to the reset time so the retry lands after the window, not on it. */+const WAIT_BUFFER_MS = 1_000;++/**+ * Worst-case time the retry adds to one call.+ *+ * The first attempt does not wait. Every later attempt waits first, and one+ * wait is never longer than MAX_WAIT_MS. The value comes from the two bounds+ * above, so it cannot drift from them.+ */+export const RETRY_BUDGET_MS = (MAX_ATTEMPTS - 1) * MAX_WAIT_MS;++/**+ * Time waitForJob allows when the caller passes no timeout.+ *+ * Every caller now passes its own timeout, sized to the work it waits for.+ * This value is only a backstop for a new caller that forgets one. Without a+ * bound the poll loop runs until the jest timeout, which hides the reason.+ *+ * The value stays short because it cannot know the work. It fits the smallest+ * base any suite passes to testTimeoutMs, which is 60_000 ms:+ * 45_000 + 2_000 + RETRY_BUDGET_MS = 197_000 ms, inside the 210_000 ms of+ * testTimeoutMs(60_000). So a forgotten timeout still reports "job did not+ * finish" in every test the suites have today.+ *+ * A caller that waits for real work must pass a timeout. Size it to the work,+ * not to the budget, then set the budget from the sum of the calls the test+ * makes. The unit test "every wrapped call in a test fits its budget" holds+ * that rule: it counts this bound, one poll interval, and the retry budget of+ * every wrapped call in the test, and requires the sum to fit.+ */+export const DEFAULT_JOB_TIMEOUT_MS = 45_000;++/**+ * Jest timeout for a test that calls a wrapped client.+ *+ * Pass the base: the time the test needs when the API answers at once. The+ * result adds one retry budget on top, so a test whose single call hits the+ * limit still finishes inside its own timeout instead of failing on it.+ *+ * One retry budget covers one call. A test that makes several wrapped calls+ * can spend the budget once per call, so the base must carry the rest. Do not+ * pick the base by hand: take the number the unit test "every wrapped call in+ * a test fits its budget" computes, which sums every call in the test.+ */+export function testTimeoutMs(baseMs: number): number {+ return baseMs + RETRY_BUDGET_MS;+}++/**+ * Client methods that start a job and then poll it.+ *+ * These never run again after a rate-limit error. A retry would call the whole+ * method, which starts a second job. The single-request methods that the job+ * waiters use inside, such as startCrawl and getCrawlStatus, keep their retry+ * when a test calls them directly.+ */+export const COMPOSITE_METHODS: ReadonlySet<string> = new Set([+ "crawl",+ "crawlUrl",+ "batchScrape",+ "batchScrapeUrls",+ "extract",+ "agent",+]);++function sleep(ms: number): Promise<void> {+ return new Promise(resolve => setTimeout(resolve, ms));+}++/** States a job stops in. Matches the waiters in src/v2/methods. */+const TERMINAL_STATES = ["completed", "failed", "cancelled"];++/** The part of a job snapshot this module reads. */+interface JobSnapshot {+ status?: string;+}++/**+ * Polls a job that a test already started.+ *+ * The composite client methods, such as crawl, start a job and then poll it in+ * one call, so the wrapper cannot run them again. A test uses this instead: it+ * starts the job with the start method, then polls with the status method. Both+ * calls go through the wrapper, so both keep their retry, and the job starts+ * once. Compare waitForCrawlCompletion in src/v2/methods/crawl.ts, which this+ * mirrors.+ *+ * @param getStatus Reads the job state. Call the wrapped client here.+ * @param opts.pollInterval Seconds between reads. Least value is 1.+ * @param opts.timeout Seconds to allow. Throws when the job runs longer.+ * Defaults to DEFAULT_JOB_TIMEOUT_MS, so the loop always has a bound.+ */+export async function waitForJob<T extends JobSnapshot>(+ getStatus: () => Promise<T>,+ opts: { pollInterval?: number; timeout?: number } = {},+): Promise<T> {+ const pollIntervalMs = Math.max(1000, (opts.pollInterval ?? 2) * 1000);+ const timeoutMs =+ opts.timeout != null ? opts.timeout * 1000 : DEFAULT_JOB_TIMEOUT_MS;+ const startedAt = Date.now();++ let snapshot = await getStatus();+ while (!TERMINAL_STATES.includes(snapshot.status ?? "")) {+ if (Date.now() - startedAt > timeoutMs) {+ throw new Error(+ `job did not finish in ${timeoutMs / 1000}s. Last status: ${+ snapshot.status+ }`,+ );+ }+ await sleep(pollIntervalMs);+ snapshot = await getStatus();+ }+ return snapshot;+}++function isPromiseLike(value: unknown): value is Promise<unknown> {+ return (+ typeof value === "object" &&+ value !== null &&+ typeof (value as { then?: unknown }).then === "function"+ );+}++/** True when the API refused the call because the per-minute limit is spent. */+export function isRateLimitError(err: unknown): boolean {+ if (typeof err !== "object" || err === null) return false;+ const candidate = err as { status?: unknown; message?: unknown };+ if (candidate.status === 429) return true;+ return (+ typeof candidate.message === "string" &&+ /rate limit exceeded/i.test(candidate.message)+ );+}++/** Milliseconds to wait before the next attempt. */+export function rateLimitWaitMs(err: unknown): number {+ let seconds: number | undefined;++ const details = (err as { details?: Record<string, unknown> })?.details;+ for (const key of ["retryAfter", "retryAfterSeconds"]) {+ const value = details?.[key];+ if (typeof value === "number" && Number.isFinite(value) && value > 0) {+ seconds = value;+ break;+ }+ }++ if (seconds === undefined) {+ const message = (err as { message?: unknown })?.message;+ const match =+ typeof message === "string"+ ? message.match(/retry after (\d+)\s*s/i)+ : null;+ if (match) seconds = Number(match[1]);+ }++ const waitMs =+ seconds !== undefined && seconds > 0+ ? seconds * 1000 + WAIT_BUFFER_MS+ : FALLBACK_WAIT_MS;+ return Math.min(waitMs, MAX_WAIT_MS);+}++async function runWithRetry<T>(+ first: Promise<T>,+ again: () => Promise<T>,+ label: string,+): Promise<T> {+ let pending = first;++ for (let attempt = 1; ; attempt++) {+ try {+ return await pending;+ } catch (err) {+ if (attempt >= MAX_ATTEMPTS || !isRateLimitError(err)) throw err;+ const waitMs = rateLimitWaitMs(err);+ console.warn(+ `[e2e] ${label} hit the API rate limit. Waiting ${Math.round(+ waitMs / 1000,+ )}s, then attempt ${attempt + 1} of ${MAX_ATTEMPTS}.`,+ );+ await sleep(waitMs);+ pending = again();+ }+ }+}++/**+ * Wraps a client so each method call retries after a rate-limit error.+ *+ * The wrapper only covers the calls the test makes. Methods that return a value+ * other than a promise pass through unchanged, and so do the composite methods+ * listed in COMPOSITE_METHODS.+ */+export function withRateLimitRetry<T extends object>(client: T): T {+ return new Proxy(client, {+ get(target, prop) {+ const value = (target as Record<string | symbol, unknown>)[prop];+ if (typeof value !== "function") return value;++ const name = String(prop);++ return (...args: unknown[]) => {+ const call = () =>+ (value as (...a: unknown[]) => unknown).apply(target, args);+ const result = call();+ // A composite method already created a job, so never run it again.+ if (COMPOSITE_METHODS.has(name)) return result;+ if (!isPromiseLike(result)) return result;+ return runWithRetry(+ result,+ call as () => Promise<unknown>,+ name,+ );+ };+ },+ });+}diff --git a/apps/js-sdk/firecrawl/src/__tests__/e2e/v2/watcher.test.ts b/apps/js-sdk/firecrawl/src/__tests__/e2e/v2/watcher.test.tsindex cb55f21bc..9bb9ea7f7 100644--- a/apps/js-sdk/firecrawl/src/__tests__/e2e/v2/watcher.test.ts+++ b/apps/js-sdk/firecrawl/src/__tests__/e2e/v2/watcher.test.ts@@ -2,6 +2,7 @@ import Firecrawl from "../../../index";import { config } from "dotenv";import { describe, test, expect, beforeAll } from "@jest/globals";import { getIdentity } from "./utils/idmux";+import { testTimeoutMs, withRateLimitRetry } from "./utils/rateLimit";config();@@ -10,7 +11,7 @@ let client: Firecrawl;beforeAll(async () => {const { apiKey } = await getIdentity({ name: "js-e2e-watcher" });- client = new Firecrawl({ apiKey, apiUrl: API_URL });+ client = withRateLimitRetry(new Firecrawl({ apiKey, apiUrl: API_URL }));});describe("v2.watcher e2e", () => {@@ -52,7 +53,7 @@ describe("v2.watcher e2e", () => {expect(snapshots).toBeGreaterThanOrEqual(1);expect(documents).toBeGreaterThanOrEqual(0);watcher.close();- }, 240_000);+ }, testTimeoutMs(240_000));test("batch watcher with options (kind, pollInterval, timeout)", async () => {// client is initialized in beforeAll@@ -91,6 +92,6 @@ describe("v2.watcher e2e", () => {expect(snapshots).toBeGreaterThanOrEqual(1);expect(gotCompleted || final.status !== "completed").toBe(true);watcher.close();- }, 300_000);+ }, testTimeoutMs(300_000));});diff --git a/apps/js-sdk/firecrawl/src/__tests__/unit/v2/e2eRateLimitRetry.test.ts b/apps/js-sdk/firecrawl/src/__tests__/unit/v2/e2eRateLimitRetry.test.tsnew file mode 100644index 000000000..900f8668a--- /dev/null+++ b/apps/js-sdk/firecrawl/src/__tests__/unit/v2/e2eRateLimitRetry.test.ts@@ -0,0 +1,501 @@+import { describe, expect, jest, test } from "@jest/globals";+import { readFileSync, readdirSync } from "node:fs";+import path from "node:path";+import Firecrawl from "../../../index";+import {+ COMPOSITE_METHODS,+ DEFAULT_JOB_TIMEOUT_MS,+ RETRY_BUDGET_MS,+ isRateLimitError,+ rateLimitWaitMs,+ testTimeoutMs,+ waitForJob,+ withRateLimitRetry,+} from "../../e2e/v2/utils/rateLimit";++type AsyncCall = () => Promise<string>;++/** Reproduces the error the API returns when the per-minute limit is spent. */+function rateLimitError(seconds: number): Error & { status: number } {+ const err = new Error(+ `Rate limit exceeded. Consumed (req/min): 3, Remaining (req/min): 0. ` ++ `Upgrade your plan at https://firecrawl.dev/pricing for increased rate ` ++ `limits or please retry after ${seconds}s, resets at Tue Sep 08 2026`,+ ) as Error & { status: number };+ err.status = 429;+ return err;+}++/**+ * Source with comments blanked out, newlines kept.+ *+ * The scans below count brackets and calls. A comment holding `waitForJob(`,+ * a client call or a lone brace would corrupt both, so drop comments first.+ * Strings are not comments: a suite passes paths such as "/blog/*", and a+ * scan that took that for a comment would swallow the rest of the file.+ */+function stripComments(source: string): string {+ let out = "";+ let quote: string | undefined;++ for (let i = 0; i < source.length; i++) {+ const c = source[i];++ if (quote !== undefined) {+ out += c;+ if (c === "\\") {+ out += source[i + 1] ?? "";+ i += 1;+ } else if (c === quote) {+ quote = undefined;+ }+ continue;+ }++ if (c === "'" || c === '"' || c === "`") {+ quote = c;+ out += c;+ continue;+ }++ if (source.startsWith("/*", i)) {+ const close = source.indexOf("*/", i + 2);+ const end = close < 0 ? source.length : close + 2;+ // Keep the newlines so line structure survives.+ out += source.slice(i, end).replace(/[^\n]/g, "");+ i = end - 1;+ continue;+ }++ if (source.startsWith("//", i)) {+ const line = source.indexOf("\n", i);+ if (line < 0) break;+ i = line - 1;+ continue;+ }++ out += c;+ }++ return out;+}++/**+ * Text of each `name(...)` call in source, by matching parentheses.+ *+ * A regex cannot do this. The calls hold arrow functions, objects and+ * template strings, so the closing bracket is not the first one.+ *+ * Pass source that stripComments has already cleaned.+ */+function callsOf(source: string, name: string): string[] {+ const found: string[] = [];++ for (const match of source.matchAll(new RegExp(`\\b${name}\\(`, "g"))) {+ const from = match.index!;+ let i = from + match[0].length - 1;+ let depth = 0;+ let quote: string | undefined;++ for (; i < source.length; i++) {+ const c = source[i];+ if (quote !== undefined) {+ if (c === "\\") i += 1;+ else if (c === quote) quote = undefined;+ continue;+ }+ if (c === "'" || c === '"' || c === "`") {+ quote = c;+ continue;+ }+ if (c === "(" || c === "[" || c === "{") depth += 1;+ else if (c === ")" || c === "]" || c === "}") {+ depth -= 1;+ if (depth === 0) break;+ }+ }+ found.push(source.slice(from, i + 1));+ }++ return found;+}++/**+ * Body of each test in a suite, including the test.each form.+ *+ * test.each takes the cases first and the test second, so the test body is+ * the group after the cases.+ */+function testBodies(source: string): string[] {+ const found: string[] = [];++ for (const match of source.matchAll(/\btest(\.each)?\s*\(/g)) {+ if (!match[1]) {+ found.push(callsOf(source.slice(match.index!), "test")[0]);+ continue;+ }+ const cases = callsOf(source.slice(match.index!), "test.each")[0];+ const rest = source.slice(match.index! + cases.length);+ const open = rest.indexOf("(");+ // Reuse the matcher by giving it a name to anchor on.+ const group = callsOf(`each${rest.slice(open)}`, "each")[0];+ found.push(group);+ }++ return found;+}++/** Local async helpers in a suite, by name, with the body each one runs. */+function localHelpers(source: string): Map<string, string> {+ const found = new Map<string, string>();++ for (const match of source.matchAll(/\n(\s*)async function (\w+)\(/g)) {+ const start = match.index! + 1;+ const close = source.indexOf(`\n${match[1]}}`, start);+ found.set(match[2], source.slice(start, close < 0 ? undefined : close));+ }++ return found;+}++/**+ * Worst case of one test body, and the wrapped calls it counts.+ *+ * Each waitForJob costs its bound, one poll interval and the retry budget of+ * the status read. Each other wrapped client call costs the retry budget on+ * its own. A local helper runs inside the test, so its calls count too.+ */+function worstCaseMs(+ body: string,+ helpers: Map<string, string>,+): { calls: number; ms: number } {+ let calls = 0;+ let ms = 0;++ const waits = callsOf(body, "waitForJob");+ for (const wait of waits) {+ const timeout = wait.match(/timeout:\s*(\d+)/);+ const poll = wait.match(/pollInterval:\s*(\d+)/);+ const bound = timeout+ ? Number(timeout[1]) * 1000+ : DEFAULT_JOB_TIMEOUT_MS;+ ms +=+ bound ++ Math.max(1000, (poll ? Number(poll[1]) : 2) * 1000) ++ RETRY_BUDGET_MS;+ calls += 1;+ }++ // The status read sits inside waitForJob, so drop those calls before+ // counting the rest. Longest first, so a shorter call is not cut twice.+ let rest = body;+ for (const wait of [...waits].sort((a, b) => b.length - a.length)) {+ rest = rest.split(wait).join("");+ }++ const direct = rest.match(/client\.\w+\s*\(/g) ?? [];+ ms += direct.length * RETRY_BUDGET_MS;+ calls += direct.length;++ for (const [name, helperBody] of helpers) {+ const uses = rest.match(new RegExp(`\\b${name}\\s*\\(`, "g")) ?? [];+ if (uses.length === 0) continue;+ const inner = worstCaseMs(helperBody, new Map());+ ms += uses.length * inner.ms;+ calls += uses.length * inner.calls;+ }++ return { calls, ms };+}++describe("e2e rate-limit retry helper", () => {+ test("recognises the rate-limit error and reads its reset time", () => {+ expect(isRateLimitError(rateLimitError(1))).toBe(true);+ expect(isRateLimitError({ status: 429 })).toBe(true);+ expect(isRateLimitError(new Error("Bad request"))).toBe(false);+ expect(isRateLimitError(undefined)).toBe(false);++ // 1s reset plus the 1s buffer.+ expect(rateLimitWaitMs(rateLimitError(1))).toBe(2000);+ // A reset longer than the window is capped.+ expect(rateLimitWaitMs(rateLimitError(600))).toBe(75_000);+ // No reset time in the error, so the fallback applies.+ expect(rateLimitWaitMs(new Error("Rate limit exceeded."))).toBe(30_000);+ expect(rateLimitWaitMs({ details: { retryAfter: 2 } })).toBe(3000);+ });++ test("runs the call again after a rate-limit error", async () => {+ const scrape = jest+ .fn<() => Promise<string>>()+ .mockRejectedValueOnce(rateLimitError(1))+ .mockResolvedValueOnce("ok");+ const client = withRateLimitRetry({ scrape });++ await expect(client.scrape()).resolves.toBe("ok");+ expect(scrape).toHaveBeenCalledTimes(2);+ }, 30_000);++ test("stops after the attempt bound and surfaces the error", async () => {+ const scrape = jest+ .fn<() => Promise<string>>()+ .mockRejectedValue(rateLimitError(1));+ const client = withRateLimitRetry({ scrape });++ await expect(client.scrape()).rejects.toThrow(/Rate limit exceeded/);+ expect(scrape).toHaveBeenCalledTimes(3);+ }, 30_000);++ test("passes other errors through without waiting", async () => {+ const scrape = jest+ .fn<() => Promise<string>>()+ .mockRejectedValue(new Error("invalid url"));+ const client = withRateLimitRetry({ scrape });++ await expect(client.scrape()).rejects.toThrow("invalid url");+ expect(scrape).toHaveBeenCalledTimes(1);+ });++ test("never runs a composite method again after a rate-limit error", async () => {+ for (const name of COMPOSITE_METHODS) {+ const method = jest.fn<AsyncCall>().mockRejectedValue(rateLimitError(1));+ const client = withRateLimitRetry<Record<string, AsyncCall>>({+ [name]: method,+ });++ const startedAt = Date.now();+ await expect(client[name]()).rejects.toThrow(/Rate limit exceeded/);++ // One call only. A second call would start a second job.+ expect(method).toHaveBeenCalledTimes(1);+ // The error surfaces at once, so no wait ran either.+ expect(Date.now() - startedAt).toBeLessThan(1_000);+ }+ });++ test("returns the result of a composite method that succeeds", async () => {+ const crawl = jest.fn<AsyncCall>().mockResolvedValue("job");+ const client = withRateLimitRetry({ crawl });++ await expect(client.crawl()).resolves.toBe("job");+ expect(crawl).toHaveBeenCalledTimes(1);+ });++ test("every composite name is a method on the client", () => {+ const client = new Firecrawl({ apiKey: "test-key" }) as unknown as Record<+ string,+ unknown+ >;++ for (const name of COMPOSITE_METHODS) {+ expect(typeof client[name]).toBe("function");+ }+ });++ test("the client has no composite method the list misses", () => {+ // Guard for a new waiter method. A composite starts a job through a+ // *Waiter call, or forwards to another composite on this.+ const source = readFileSync(+ path.resolve(process.cwd(), "src/v2/client.ts"),+ "utf-8",+ );++ const found = new Set<string>();+ let current: string | undefined;+ for (const line of source.split("\n")) {+ const signature = line.match(/^\s{2}(?:async\s+)?([A-Za-z_$][\w$]*)\s*\(/);+ if (signature) current = signature[1];+ if (!current) continue;+ const startsJob =+ /\b\w+Waiter\s*\(/.test(line) ||+ new RegExp(`this\\.(${[...COMPOSITE_METHODS].join("|")})\\s*\\(`).test(+ line,+ );+ if (startsJob) found.add(current);+ }++ // The scan must see the known composites, or it stopped working.+ expect([...found].sort()).toEqual([...COMPOSITE_METHODS].sort());+ });++ test("no e2e suite calls a composite method", () => {+ // A composite call in a suite has no retry, so a rate limit fails the test+ // at once. The suites start the job and poll it instead.+ const dir = path.resolve(process.cwd(), "src/__tests__/e2e/v2");+ const suites = readdirSync(dir).filter(name => name.endsWith(".test.ts"));+ expect(suites.length).toBeGreaterThan(0);++ const calls = new RegExp(+ `client\\.(${[...COMPOSITE_METHODS].join("|")})\\s*\\(`,+ );+ const offenders = suites.filter(name =>+ calls.test(readFileSync(path.join(dir, name), "utf-8")),+ );++ expect(offenders).toEqual([]);+ });++ test("waitForJob polls until the job reaches a terminal state", async () => {+ const getStatus = jest+ .fn<() => Promise<{ status: string }>>()+ .mockResolvedValueOnce({ status: "scraping" })+ .mockResolvedValueOnce({ status: "scraping" })+ .mockResolvedValueOnce({ status: "completed" });++ // pollInterval floors at 1s, so three reads take about two seconds.+ await expect(+ waitForJob(getStatus, { pollInterval: 1, timeout: 30 }),+ ).resolves.toEqual({ status: "completed" });+ expect(getStatus).toHaveBeenCalledTimes(3);+ }, 30_000);++ test("waitForJob gives up when the job outlives its timeout", async () => {+ const getStatus = jest+ .fn<() => Promise<{ status: string }>>()+ .mockResolvedValue({ status: "scraping" });++ await expect(+ waitForJob(getStatus, { pollInterval: 1, timeout: 1 }),+ ).rejects.toThrow(/did not finish in 1s/);+ }, 30_000);++ test("waitForJob bounds a caller that passes no timeout", async () => {+ const getStatus = jest+ .fn<() => Promise<{ status: string }>>()+ .mockResolvedValue({ status: "scraping" });++ // The default is a backstop for a caller that forgets a timeout, not a+ // work allowance. A caller that waits for real work passes its own bound.+ // So the default only has to fit the smallest base any suite uses, which+ // is 60_000 ms. The last read can start just inside the bound and then+ // spend the whole retry budget, so count both.+ expect(DEFAULT_JOB_TIMEOUT_MS + 2_000 + RETRY_BUDGET_MS).toBeLessThan(+ testTimeoutMs(60_000),+ );++ // Fake timers run the whole bound without waiting for it.+ jest.useFakeTimers();+ try {+ const settled = expect(waitForJob(getStatus)).rejects.toThrow(+ new RegExp(`did not finish in ${DEFAULT_JOB_TIMEOUT_MS / 1000}s`),+ );+ await jest.advanceTimersByTimeAsync(DEFAULT_JOB_TIMEOUT_MS + 5_000);+ await settled;+ } finally {+ jest.useRealTimers();+ }++ expect(getStatus).toHaveBeenCalled();+ }, 30_000);++ test("the scan reads past comments and strings", () => {+ // The guard is only as good as its parser, so hold the parser too. Each+ // trap below broke an earlier version: a block comment with a call and a+ // lone brace, a commented-out call, and a path that starts with "/*".+ const suite = [+ 'describe("fixture", () => {',+ ' test("one start and one wait", async () => {',+ ' /* waitForJob( here, with an unbalanced { brace */',+ ' // client.notCounted(',+ ' const started = await client.startThing({',+ ' includePaths: ["/blog/*", "/docs/*"],',+ ' });',+ ' const job = await waitForJob(() => client.getThing(started.id), {',+ ' pollInterval: 1,',+ ' timeout: 60,',+ ' });',+ ' expect(job.status).toBe("completed");',+ ' }, testTimeoutMs(220_000));',+ "});",+ ].join("\n");++ const source = stripComments(suite);++ // The traps are gone, and the code around them survived.+ expect(source).not.toMatch(/waitForJob\( here/);+ expect(source).not.toMatch(/notCounted/);+ expect(source).toContain('includePaths: ["/blog/*", "/docs/*"]');+ expect(source).toContain("timeout: 60,");++ const bodies = testBodies(source);+ expect(bodies).toHaveLength(1);++ // One start call at the retry budget, and one wait at bound plus poll+ // plus the retry budget of its status read.+ const { calls, ms } = worstCaseMs(bodies[0], new Map());+ expect(calls).toBe(2);+ expect(ms).toBe(RETRY_BUDGET_MS + 60_000 + 1_000 + RETRY_BUDGET_MS);+ expect(ms).toBeLessThan(testTimeoutMs(220_000));+ });++ test("every wrapped call in a test fits its budget", () => {+ // Guard for the whole class of budget faults. A test spends the retry+ // budget once per wrapped call, not once in total, so the budget has to+ // cover the sum. Otherwise jest fires first and hides the specific+ // message this helper exists to surface.+ const dir = path.resolve(process.cwd(), "src/__tests__/e2e/v2");+ const suites = readdirSync(dir).filter(name => name.endsWith(".test.ts"));+ expect(suites.length).toBeGreaterThan(0);++ let checked = 0;+ let widest = 0;++ for (const name of suites) {+ const source = stripComments(+ readFileSync(path.join(dir, name), "utf-8"),+ );+ const helpers = localHelpers(source);++ // A helper that calls another helper would hide calls from the sum.+ for (const [self, body] of helpers) {+ for (const other of helpers.keys()) {+ if (other === self) continue;+ expect(body).not.toMatch(new RegExp(`\\b${other}\\s*\\(`));+ }+ }++ const bodies = testBodies(source);+ // The scan must see every test, or a budget goes unchecked.+ expect(bodies.length).toBe(+ (source.match(/\btest(?:\.each)?\s*\(/g) ?? []).length,+ );++ for (const body of bodies) {+ const { calls, ms } = worstCaseMs(body, helpers);+ if (calls === 0) continue;++ // A test that calls the wrapped client needs a budget of its own.+ // Without one jest allows 5s, which any single wait outlasts.+ const budgets = body.match(/testTimeoutMs\((\d[\d_]*)\)/g);+ expect(budgets).not.toBeNull();++ const base = Number(budgets![budgets!.length - 1].replace(/\D/g, ""));+ expect(ms).toBeLessThan(testTimeoutMs(base));++ checked += 1;+ widest = Math.max(widest, calls);+ }+ }++ // The scan must see the known tests, or it stopped working.+ expect(checked).toBeGreaterThanOrEqual(45);+ expect(widest).toBeGreaterThanOrEqual(3);+ });++ test("the test timeout fits the worst-case serial retry", () => {+ // Two waits at the 75s cap follow the first attempt.+ expect(RETRY_BUDGET_MS).toBe(150_000);+ expect(testTimeoutMs(60_000)).toBe(210_000);++ // No pair of waits the helper can ask for exceeds the budget.+ const longestWait = rateLimitWaitMs(rateLimitError(600));+ expect(longestWait * 2).toBeLessThanOrEqual(RETRY_BUDGET_MS);+ });++ test("leaves values that are not promises alone", () => {+ const watcher = jest.fn(() => ({ kind: "crawl" }));+ const client = withRateLimitRetry({ watcher, apiUrl: "https://example.com" });++ expect(client.watcher()).toEqual({ kind: "crawl" });+ expect(client.apiUrl).toBe("https://example.com");+ });+});diff --git a/apps/js-sdk/firecrawl/src/__tests__/unit/v2/extract.unit.test.ts b/apps/js-sdk/firecrawl/src/__tests__/unit/v2/extract.unit.test.tsindex d292c3e4a..95be255e6 100644--- a/apps/js-sdk/firecrawl/src/__tests__/unit/v2/extract.unit.test.ts+++ b/apps/js-sdk/firecrawl/src/__tests__/unit/v2/extract.unit.test.ts@@ -1,4 +1,4 @@-import { describe, expect, test } from "@jest/globals";+import { describe, expect, jest, test } from "@jest/globals";import { startExtract } from "../../../v2/methods/extract";import type { WebhookConfig } from "../../../v2/types";diff --git a/apps/js-sdk/firecrawl/src/__tests__/unit/v2/scrapeAutoResume.test.ts b/apps/js-sdk/firecrawl/src/__tests__/unit/v2/scrapeAutoResume.test.tsindex 6ca30ba46..3c48f9b8b 100644--- a/apps/js-sdk/firecrawl/src/__tests__/unit/v2/scrapeAutoResume.test.ts+++ b/apps/js-sdk/firecrawl/src/__tests__/unit/v2/scrapeAutoResume.test.ts@@ -1,4 +1,4 @@-import { describe, expect, test } from "@jest/globals";+import { describe, expect, jest, test } from "@jest/globals";import {processingContinuesDelayMs,scrape,diff --git a/apps/js-sdk/firecrawl/src/__tests__/unit/v2/search-country.unit.test.ts b/apps/js-sdk/firecrawl/src/__tests__/unit/v2/search-country.unit.test.tsnew file mode 100644index 000000000..c206175e9--- /dev/null+++ b/apps/js-sdk/firecrawl/src/__tests__/unit/v2/search-country.unit.test.ts@@ -0,0 +1,32 @@+import { describe, expect, jest, test } from "@jest/globals";+import { search } from "../../../v2/methods/search";++function httpMock() {+ return {+ post: jest.fn(async () => ({ status: 200, data: { success: true } })),+ } as any;+}++describe("v2 search country", () => {+ test("forwards the country option", async () => {+ const http = httpMock();++ await search(http, { query: "firecrawl", country: "de" });++ expect(http.post).toHaveBeenCalledWith(+ "/v2/search",+ { query: "firecrawl", country: "de" },+ {},+ );+ });++ test("omits country when the caller does not set it", async () => {+ const http = httpMock();++ await search(http, { query: "firecrawl" });++ expect(http.post).toHaveBeenCalledWith("/v2/search", { query: "firecrawl" }, {});+ const payload = http.post.mock.calls[0][1] as Record<string, unknown>;+ expect(payload).not.toHaveProperty("country");+ });+});diff --git a/apps/js-sdk/firecrawl/src/__tests__/unit/v2/search-data-property.test.ts b/apps/js-sdk/firecrawl/src/__tests__/unit/v2/search-data-property.test.tsindex 966728b6c..f1a280b89 100644--- a/apps/js-sdk/firecrawl/src/__tests__/unit/v2/search-data-property.test.ts+++ b/apps/js-sdk/firecrawl/src/__tests__/unit/v2/search-data-property.test.ts@@ -1,3 +1,4 @@+import { jest } from "@jest/globals";import { search } from "../../../v2/methods/search";const fakeHttp = {diff --git a/apps/js-sdk/firecrawl/src/__tests__/unit/v2/v1-aliases.test.ts b/apps/js-sdk/firecrawl/src/__tests__/unit/v2/v1-aliases.test.tsindex 3747d9031..9212d479a 100644--- a/apps/js-sdk/firecrawl/src/__tests__/unit/v2/v1-aliases.test.ts+++ b/apps/js-sdk/firecrawl/src/__tests__/unit/v2/v1-aliases.test.ts@@ -1,3 +1,4 @@+import { jest } from "@jest/globals";import { FirecrawlClient } from "../../../v2/client";const ALIAS_MAP: Record<string, string> = {diff --git a/apps/js-sdk/firecrawl/src/v2/methods/search.ts b/apps/js-sdk/firecrawl/src/v2/methods/search.tsindex 9dc82c4c4..76a3c0e31 100644--- a/apps/js-sdk/firecrawl/src/v2/methods/search.ts+++ b/apps/js-sdk/firecrawl/src/v2/methods/search.ts@@ -34,6 +34,7 @@ function prepareSearchPayload(req: SearchRequest): Record<string, unknown> {if (req.limit != null) payload.limit = req.limit;if (req.tbs != null) payload.tbs = req.tbs;if (req.location != null) payload.location = req.location;+ if (req.country != null) payload.country = req.country;if (req.ignoreInvalidURLs != null)payload.ignoreInvalidURLs = req.ignoreInvalidURLs;if (req.timeout != null) payload.timeout = req.timeout;diff --git a/apps/js-sdk/firecrawl/src/v2/types.ts b/apps/js-sdk/firecrawl/src/v2/types.tsindex a7d16d490..375269d45 100644--- a/apps/js-sdk/firecrawl/src/v2/types.ts+++ b/apps/js-sdk/firecrawl/src/v2/types.ts@@ -849,6 +849,8 @@ export interface SearchRequest {limit?: number;tbs?: string;location?: string;+ /** ISO 3166-1 alpha-2 country code used to geo-target the search results. */+ country?: string;ignoreInvalidURLs?: boolean;timeout?: number; // ms/** Generate query-relevant highlights for search results. Defaults to true. */diff --git a/apps/php-sdk/src/Models/SearchOptions.php b/apps/php-sdk/src/Models/SearchOptions.phpindex bc413f3a7..b08340aa4 100644--- a/apps/php-sdk/src/Models/SearchOptions.php+++ b/apps/php-sdk/src/Models/SearchOptions.php@@ -25,6 +25,7 @@ final class SearchOptionsprivate readonly ?array $includeDomains = null,private readonly ?array $excludeDomains = null,private readonly ?bool $highlights = null,+ private readonly ?string $country = null,) {}/**@@ -46,11 +47,12 @@ final class SearchOptions?array $includeDomains = null,?array $excludeDomains = null,?bool $highlights = null,+ ?string $country = null,): self {return new self($sources, $categories, $limit, $tbs, $location, $ignoreInvalidURLs,$timeout, $scrapeOptions, $integration, $includeDomains, $excludeDomains,- $highlights,+ $highlights, $country,);}@@ -65,6 +67,7 @@ final class SearchOptions'limit' => $this->limit,'tbs' => $this->tbs,'location' => $this->location,+ 'country' => $this->country,'ignoreInvalidURLs' => $this->ignoreInvalidURLs,'timeout' => $this->timeout,'highlights' => $this->highlights,diff --git a/apps/php-sdk/tests/Unit/SearchCountryTest.php b/apps/php-sdk/tests/Unit/SearchCountryTest.phpnew file mode 100644index 000000000..8d8cbf1c8--- /dev/null+++ b/apps/php-sdk/tests/Unit/SearchCountryTest.php@@ -0,0 +1,38 @@+<?php++declare(strict_types=1);++use Firecrawl\Models\SearchOptions;+use GuzzleHttp\Psr7\Response;++it('sends the search country option in the request body', function (): void {+ $history = new ArrayObject();+ $client = fakeFirecrawlClient([+ new Response(200, [], json_encode(['success' => true, 'data' => ['web' => []]])),+ ], $history);++ $client->search('firecrawl', SearchOptions::with(country: 'de'));++ $body = json_decode((string) $history[0]['request']->getBody(), true);+ expect($body['query'])->toBe('firecrawl');+ expect($body['country'])->toBe('de');+});++it('omits the search country option when it is unset', function (): void {+ $history = new ArrayObject();+ $client = fakeFirecrawlClient([+ new Response(200, [], json_encode(['success' => true, 'data' => ['web' => []]])),+ ], $history);++ $client->search('firecrawl', SearchOptions::with(limit: 5));++ $body = json_decode((string) $history[0]['request']->getBody(), true);+ expect($body['limit'])->toBe(5);+ expect(array_key_exists('country', $body))->toBeFalse();+});++it('serializes the search country option', function (): void {+ $options = SearchOptions::with(country: 'de');++ expect($options->toArray())->toBe(['country' => 'de']);+});diff --git a/apps/python-sdk/firecrawl/__tests__/unit/v2/methods/aio/test_aio_search_request_preparation.py b/apps/python-sdk/firecrawl/__tests__/unit/v2/methods/aio/test_aio_search_request_preparation.pyindex bddf6dc23..e429c810c 100644--- a/apps/python-sdk/firecrawl/__tests__/unit/v2/methods/aio/test_aio_search_request_preparation.py+++ b/apps/python-sdk/firecrawl/__tests__/unit/v2/methods/aio/test_aio_search_request_preparation.py@@ -1,6 +1,10 @@+from unittest.mock import AsyncMock, Mock+import pytest+from firecrawl.v2.client_async import AsyncFirecrawlClientfrom firecrawl.v2.types import SearchRequest, ScrapeOptionsfrom firecrawl.v2.methods.aio.search import _prepare_search_request+from firecrawl.v2.methods.aio.search import search as search_asyncclass TestAsyncSearchRequestPreparation:@@ -31,6 +35,7 @@ class TestAsyncSearchRequestPreparation:limit=10,tbs="qdr:w",location="US",+ country="de",ignore_invalid_urls=False,timeout=30000,scrape_options=scrape_opts,@@ -38,6 +43,7 @@ class TestAsyncSearchRequestPreparation:)data = _prepare_search_request(request)assert data["ignoreInvalidURLs"] is False+ assert data["country"] == "de"assert data["excludeDomains"] == ["example.com"]assert "exclude_domains" not in dataassert "scrapeOptions" in data@@ -58,6 +64,18 @@ class TestAsyncSearchRequestPreparation:assert "query" in dataassert len(data) == 1+ def test_country_is_included_when_set(self):+ """Test that country reaches the prepared body."""+ request = SearchRequest(query="test", country="de")+ data = _prepare_search_request(request)+ assert data["country"] == "de"++ def test_country_is_omitted_when_unset(self):+ """Test that the body omits country when it is not set."""+ request = SearchRequest(query="test")+ data = _prepare_search_request(request)+ assert "country" not in data+def test_domain_filters_are_mutually_exclusive(self):with pytest.raises(ValueError,@@ -75,4 +93,54 @@ class TestAsyncSearchRequestPreparation:assert "scrapeOptions" in datascrape_data = data["scrapeOptions"]assert "onlyMainContent" in scrape_data- assert "mobile" in scrape_data\ No newline at end of file+ assert "mobile" in scrape_data+++def _ok_response():+ """Minimal successful search response."""+ response = Mock()+ response.status_code = 200+ response.json.return_value = {"success": True, "data": {}}+ return response+++def _mock_client():+ client = Mock()+ client.post = AsyncMock(return_value=_ok_response())+ return client+++class TestAsyncSearchPostsCountry:+ """The async client accepted country and dropped it. Pin the body."""++ @pytest.mark.asyncio+ async def test_country_reaches_the_posted_body(self):+ """Test that the async search posts country."""+ client = _mock_client()++ await search_async(client, SearchRequest(query="test", country="de"))++ path, body = client.post.call_args[0]+ assert path == "/v2/search"+ assert body["country"] == "de"++ @pytest.mark.asyncio+ async def test_posted_body_omits_country_when_unset(self):+ """Test that the async search omits country when it is not set."""+ client = _mock_client()++ await search_async(client, SearchRequest(query="test"))++ _path, body = client.post.call_args[0]+ assert "country" not in body++ @pytest.mark.asyncio+ async def test_async_client_forwards_country_kwarg(self):+ """AsyncFirecrawlClient.search takes **kwargs. Pin the passthrough."""+ client = AsyncFirecrawlClient(api_key="fc-test")+ client.async_http_client.post = AsyncMock(return_value=_ok_response())++ await client.search("test", country="de")++ _path, body = client.async_http_client.post.call_args[0]+ assert body["country"] == "de"diff --git a/apps/python-sdk/firecrawl/__tests__/unit/v2/methods/test_search_request_preparation.py b/apps/python-sdk/firecrawl/__tests__/unit/v2/methods/test_search_request_preparation.pyindex 221f2e2d0..0a7bcfe8f 100644--- a/apps/python-sdk/firecrawl/__tests__/unit/v2/methods/test_search_request_preparation.py+++ b/apps/python-sdk/firecrawl/__tests__/unit/v2/methods/test_search_request_preparation.py@@ -1,4 +1,7 @@+from unittest.mock import Mock+import pytest+from firecrawl.v2.client import FirecrawlClientfrom firecrawl.v2.types import SearchRequest, ScrapeOptions, Sourcefrom firecrawl.v2.methods.search import _prepare_search_request@@ -42,6 +45,7 @@ class TestSearchRequestPreparation:limit=10,tbs="qdr:w",location="US",+ country="de",ignore_invalid_urls=False,timeout=30000,highlights=False,@@ -56,6 +60,7 @@ class TestSearchRequestPreparation:assert data["limit"] == 10assert data["tbs"] == "qdr:w"assert data["location"] == "US"+ assert data["country"] == "de"assert data["timeout"] == 30000assert data["highlights"] is False@@ -110,6 +115,35 @@ class TestSearchRequestPreparation:assert "query" in dataassert len(data) == 1 # Only query should be present+ def test_country_is_included_when_set(self):+ """Test that country reaches the prepared body."""+ request = SearchRequest(query="test", country="de")+ data = _prepare_search_request(request)++ assert data["country"] == "de"++ def test_country_is_omitted_when_unset(self):+ """Test that the body omits country when it is not set."""+ request = SearchRequest(query="test")+ data = _prepare_search_request(request)++ assert "country" not in data++ def test_client_search_forwards_country(self):+ """Test that the sync client puts country in the posted body."""+ response = Mock()+ response.status_code = 200+ response.json.return_value = {"success": True, "data": {}}++ client = FirecrawlClient(api_key="fc-test")+ client.http_client.post = Mock(return_value=response)++ client.search("test", country="de")++ path, body = client.http_client.post.call_args[0]+ assert path == "/v2/search"+ assert body["country"] == "de"+def test_domain_filters_are_mutually_exclusive(self):"""Test that include_domains and exclude_domains cannot both be set."""with pytest.raises(diff --git a/apps/python-sdk/firecrawl/v2/client.py b/apps/python-sdk/firecrawl/v2/client.pyindex a975f05c6..f0e82a5d9 100644--- a/apps/python-sdk/firecrawl/v2/client.py+++ b/apps/python-sdk/firecrawl/v2/client.py@@ -416,6 +416,7 @@ class FirecrawlClient:limit: Optional[int] = None,tbs: Optional[str] = None,location: Optional[str] = None,+ country: Optional[str] = None,ignore_invalid_urls: Optional[bool] = None,timeout: Optional[int] = None,highlights: Optional[bool] = None,@@ -432,6 +433,7 @@ class FirecrawlClient:limit: Maximum number of results to return (default: 5)tbs: Time-based search filterlocation: Location string for search+ country: Country code that geo-targets the search resultstimeout: Request timeout in milliseconds (default: 300000)highlights: Generate query-relevant highlights for search results(default: true)@@ -454,6 +456,7 @@ class FirecrawlClient:limit=limit,tbs=tbs,location=location,+ country=country,ignore_invalid_urls=ignore_invalid_urls,timeout=timeout,highlights=highlights,diff --git a/apps/python-sdk/firecrawl/v2/types.py b/apps/python-sdk/firecrawl/v2/types.pyindex 6f101c2bb..8d0af50ee 100644--- a/apps/python-sdk/firecrawl/v2/types.py+++ b/apps/python-sdk/firecrawl/v2/types.py@@ -2175,6 +2175,7 @@ class SearchRequest(BaseModel):limit: Optional[int] = 5tbs: Optional[str] = Nonelocation: Optional[str] = None+ country: Optional[str] = Noneignore_invalid_urls: Optional[bool] = Nonetimeout: Optional[int] = 300000highlights: Optional[bool] = Nonediff --git a/apps/ruby-sdk/lib/firecrawl/models/search_options.rb b/apps/ruby-sdk/lib/firecrawl/models/search_options.rbindex 4df9bb4ad..c8070d7e1 100644--- a/apps/ruby-sdk/lib/firecrawl/models/search_options.rb+++ b/apps/ruby-sdk/lib/firecrawl/models/search_options.rb@@ -5,7 +5,7 @@ module Firecrawl# Options for a web search request.class SearchOptionsFIELDS = %i[- sources categories include_domains exclude_domains limit tbs location+ sources categories include_domains exclude_domains limit tbs location countryignore_invalid_urls timeout highlights scrape_options integration enterprise].freeze@@ -24,6 +24,7 @@ module Firecrawl"limit" => limit,"tbs" => tbs,"location" => location,+ "country" => country,"ignoreInvalidURLs" => ignore_invalid_urls,"timeout" => timeout,"highlights" => highlights,diff --git a/apps/ruby-sdk/test/firecrawl/client_test.rb b/apps/ruby-sdk/test/firecrawl/client_test.rbindex dca97e9ed..eda8d3630 100644--- a/apps/ruby-sdk/test/firecrawl/client_test.rb+++ b/apps/ruby-sdk/test/firecrawl/client_test.rb@@ -592,6 +592,34 @@ class ClientTest < Minitest::Testassert_equal 0, result.web.sizeend+ def test_search_with_country+ stub_request(:post, "#{BASE_URL}/v2/search")+ .with { |req| body = JSON.parse(req.body); body["country"] == "de" }+ .to_return(+ status: 200,+ body: JSON.generate(data: { web: [], news: [], images: [] }),+ headers: { "Content-Type" => "application/json" }+ )++ options = Firecrawl::Models::SearchOptions.new(limit: 5, country: "de")+ result = @client.search("test query", options)+ assert_equal 0, result.web.size+ end++ def test_search_omits_country_when_unset+ stub_request(:post, "#{BASE_URL}/v2/search")+ .with { |req| body = JSON.parse(req.body); !body.key?("country") }+ .to_return(+ status: 200,+ body: JSON.generate(data: { web: [], news: [], images: [] }),+ headers: { "Content-Type" => "application/json" }+ )++ options = Firecrawl::Models::SearchOptions.new(limit: 5)+ result = @client.search("test query", options)+ assert_equal 0, result.web.size+ end+# ================================================================# AGENT# ================================================================diff --git a/apps/rust-sdk/src/search.rs b/apps/rust-sdk/src/search.rsindex 9a7a328b9..001f4ac0d 100644--- a/apps/rust-sdk/src/search.rs+++ b/apps/rust-sdk/src/search.rs@@ -35,6 +35,9 @@ pub struct SearchOptions {/// Geographic location string for local search results.pub location: Option<String>,+ /// Country code to geo-target search results (e.g., "de").+ pub country: Option<String>,+/// Whether to ignore invalid URLs in results.pub ignore_invalid_urls: Option<bool>,@@ -281,6 +284,22 @@ mod tests {);}+ #[test]+ fn serializes_country_option() {+ let options = SearchOptions {+ country: Some("de".to_string()),+ ..Default::default()+ };++ assert_eq!(+ serde_json::to_value(options).unwrap(),+ json!({ "country": "de" })+ );++ let default_value = serde_json::to_value(SearchOptions::default()).unwrap();+ assert!(default_value.get("country").is_none());+ }+#[tokio::test]async fn test_search_with_mock() {let mut server = mockito::Server::new_async().await;