@mendable/firecrawl-js 4.38.0 → 4.40.0

package/dist/index.js

@@ -1,6 +1,6 @@
 import {
   require_package
-} from "./chunk-KSTNOGOD.js";
+} from "./chunk-OJ4YJQ4J.js";
 
 // src/v2/utils/httpClient.ts
 import axios from "axios";
@@ -138,18 +138,35 @@ var HttpClient = class {
 };
 
 // src/v2/types.ts
+function parseRequiresAction(value) {
+  if (!value || typeof value !== "object") return void 0;
+  const record = value;
+  if (typeof record.type !== "string") return void 0;
+  const action = { type: record.type };
+  if (typeof record.terms === "string") action.terms = record.terms;
+  if (typeof record.version === "string") action.version = record.version;
+  if (typeof record.url === "string") action.url = record.url;
+  return action;
+}
 var SdkError = class extends Error {
+  requestId;
   status;
   code;
   details;
   jobId;
-  constructor(message, status, code, details, jobId) {
+  /** Present on exchange-mediated scrape failures that already captured credits. */
+  chargeId;
+  /** Present when the API needs an out-of-band step first, such as accepting provider terms. */
+  requiresAction;
+  constructor(message, status, code, details, jobId, chargeId, requiresAction) {
     super(message);
     this.name = "FirecrawlSdkError";
     this.status = status;
     this.code = code;
     this.details = details;
     this.jobId = jobId;
+    this.chargeId = chargeId;
+    this.requiresAction = requiresAction;
   }
 };
 var JobTimeoutError = class extends SdkError {
@@ -401,14 +418,30 @@ function throwForBadResponse(resp, action) {
   const status = resp.status;
   const body = resp.data || {};
   const msg = body?.error || body?.message || `Request failed (${status}) while trying to ${action}`;
-  throw new SdkError(msg, status, void 0, body?.details);
+  throw new SdkError(
+    msg,
+    status,
+    body?.code,
+    body?.details,
+    void 0,
+    body?.chargeId,
+    parseRequiresAction(body?.requiresAction)
+  );
 }
 function normalizeAxiosError(err, action) {
   const status = err.response?.status;
   const body = err.response?.data;
   const message = body?.error || err.message || `Request failed${status ? ` (${status})` : ""} while trying to ${action}`;
   const code = body?.code || err.code;
-  throw new SdkError(message, status, code, body?.details ?? body);
+  throw new SdkError(
+    message,
+    status,
+    code,
+    body?.details ?? body,
+    void 0,
+    body?.chargeId,
+    parseRequiresAction(body?.requiresAction)
+  );
 }
 function isRetryableError(err) {
   if (err instanceof JobTimeoutError) {
@@ -454,9 +487,10 @@ async function scrape(http, url, options, deps = {}) {
     throw new Error("URL cannot be empty");
   }
   if (options) ensureValidScrapeOptions(options);
-  const { autoResume, ...requestOptions } = options ?? {};
+  const { autoResume, domainTools, ...requestOptions } = options ?? {};
   const payload = { url: url.trim() };
   Object.assign(payload, requestOptions);
+  if (domainTools) payload.domainTools = domainTools;
   const requestTimeout = autoResume === false ? typeof options?.timeout === "number" ? { timeoutMs: options.timeout + 5e3 } : {} : {
     timeoutMs: Math.max(
       typeof options?.timeout === "number" ? options.timeout : 3e5,
@@ -613,6 +647,7 @@ function prepareSearchPayload(req) {
   const payload = {
     query: req.query
   };
+  if (req.domainTools != null) payload.domainTools = req.domainTools;
   if (req.sources) payload.sources = req.sources;
   if (req.categories) payload.categories = req.categories;
   if (req.includeDomains) payload.includeDomains = req.includeDomains;
@@ -620,6 +655,7 @@ function prepareSearchPayload(req) {
   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;
@@ -664,10 +700,12 @@ async function search(http, request) {
     }
     const data = res.data.data || {};
     const out = {};
+    if (res.data.warning) out.warning = res.data.warning;
     if (data.web) out.web = transformArray(data.web);
     if (data.news) out.news = transformArray(data.news);
     if (data.images)
       out.images = transformArray(data.images);
+    if (data.tools) out.tools = data.tools;
     Object.defineProperty(out, "data", {
       get() {
         const parts = [];
@@ -675,7 +713,9 @@ async function search(http, request) {
         if (out.news?.length) parts.push(`.news (${out.news.length} results)`);
         if (out.images?.length)
           parts.push(`.images (${out.images.length} results)`);
-        const available = parts.length ? parts.join(", ") : ".web, .news, or .images";
+        if (out.tools?.length)
+          parts.push(`.tools (${out.tools.length} results)`);
+        const available = parts.length ? parts.join(", ") : ".web, .news, .images, or .tools";
         throw new Error(
           `SearchData has no '.data'. Results are grouped by source: ${available}`
         );
@@ -690,6 +730,101 @@ async function search(http, request) {
   }
 }
 
+// src/v2/methods/tools.ts
+var ALEXANDRIA_MAX_CALLS = 10;
+function prepareAlexandriaPayload(calls, opts) {
+  if (!Array.isArray(calls) || calls.length === 0) {
+    throw new Error("alexandria requires at least one call");
+  }
+  if (calls.length > ALEXANDRIA_MAX_CALLS) {
+    throw new Error(`alexandria accepts at most ${ALEXANDRIA_MAX_CALLS} calls`);
+  }
+  const alexandria = calls.map((call, index) => {
+    if (!call || typeof call.provider !== "string" || !call.provider.trim()) {
+      throw new Error(`alexandria[${index}].provider cannot be empty`);
+    }
+    if (typeof call.capability !== "string" || !call.capability.trim()) {
+      throw new Error(`alexandria[${index}].capability cannot be empty`);
+    }
+    if (Object.keys(call).some(
+      (key) => !["provider", "capability", "options"].includes(key)
+    ))
+      throw new Error("Unknown alexandria call option");
+    const item = {
+      provider: call.provider.trim(),
+      capability: call.capability.trim()
+    };
+    if (call.options != null) {
+      if (typeof call.options !== "object" || Array.isArray(call.options)) {
+        throw new Error(`alexandria[${index}].options must be an object`);
+      }
+      item.options = call.options;
+    }
+    return item;
+  });
+  if (opts.timeout != null && (!Number.isInteger(opts.timeout) || opts.timeout <= 0)) {
+    throw new Error("timeout must be a positive integer");
+  }
+  const payload = { alexandria };
+  if (opts.timeout != null) payload.timeout = opts.timeout;
+  if (opts.integration && opts.integration.trim())
+    payload.integration = opts.integration.trim();
+  if (opts.origin) payload.origin = opts.origin;
+  return payload;
+}
+async function scrapeAlexandria(http, calls, opts = {}) {
+  const payload = prepareAlexandriaPayload(calls, opts);
+  const requestId = opts.requestId ?? crypto.randomUUID();
+  if (!/^[A-Za-z0-9._:-]{1,128}$/.test(requestId))
+    throw new Error("Invalid requestId");
+  try {
+    const res = await http.post("/v2/scrape", payload, {
+      headers: { "x-request-id": requestId },
+      // Allow response delivery after the API's capped execution deadline.
+      timeoutMs: Math.min(opts.timeout ?? 5e4, 5e4) + 3e4
+    });
+    if (res.status !== 200 || !res.data?.success) {
+      throwForBadResponse(res, "alexandria");
+    }
+    const data = res.data.data;
+    if (!data || !Array.isArray(data.alexandria) || typeof data.creditsCost !== "number" || !Number.isInteger(data.creditsCost) || data.creditsCost < 0) {
+      throw new SdkError("Invalid alexandria response");
+    }
+    return {
+      scrapeId: res.data.scrape_id ?? "",
+      requestId,
+      alexandria: data.alexandria,
+      creditsCost: data.creditsCost
+    };
+  } catch (err) {
+    try {
+      if (err?.isAxiosError) normalizeAxiosError(err, "alexandria");
+      throw err;
+    } catch (error) {
+      if (error && typeof error === "object")
+        Object.assign(error, { requestId });
+      throw error;
+    }
+  }
+}
+async function findTools(http, options = {}) {
+  const result = await scrapeAlexandria(http, [
+    {
+      provider: "firecrawl",
+      capability: "find-tools",
+      options: { ...options }
+    }
+  ]);
+  const item = result.alexandria[0];
+  if (!item) throw new SdkError("Missing Find Tools result");
+  if (item.error)
+    throw Object.assign(
+      new SdkError(item.error.message, item.error.status, item.error.code),
+      { requestId: result.requestId }
+    );
+  return item.data;
+}
+
 // src/v2/methods/developer.ts
 var ENDPOINT = "/v2/search/developer";
 async function developerSearch(http, query, options = {}) {
@@ -1240,6 +1375,9 @@ function prepareAgentPayload(args) {
     body.threatProtection = args.threatProtection;
   if (args.auditMetadata != null)
     body.auditMetadata = args.auditMetadata;
+  if (args.threadId != null) body.threadId = args.threadId;
+  if (args.mode != null) body.mode = args.mode;
+  if (args.exchange != null) body.exchange = args.exchange;
   return body;
 }
 async function startAgent(http, args) {
@@ -1310,6 +1448,17 @@ async function getAgentSnapshot(http, jobId, snapshotId) {
     throw err;
   }
 }
+async function getAgentThread(http, threadId, options) {
+  try {
+    const query = options?.includeData ? "?includeData=true" : "";
+    const res = await http.get(`/v2/agent/threads/${threadId}${query}`);
+    if (res.status !== 200) throwForBadResponse(res, "agent thread");
+    return res.data;
+  } catch (err) {
+    if (err?.isAxiosError) return normalizeAxiosError(err, "agent thread");
+    throw err;
+  }
+}
 async function cancelAgent(http, jobId) {
   try {
     const res = await http.delete(`/v2/agent/${jobId}`);
@@ -1550,9 +1699,7 @@ var ResearchClient = class {
     appendParam(params, "query", options.query);
     appendParam(params, "k", options.k);
     try {
-      const res = await this.http.get(
-        withQuery(`${BASE}/papers/${encodeURIComponent(id)}`, params)
-      );
+      const res = await this.http.get(withQuery(`${BASE}/papers/${encodeURIComponent(id)}`, params));
       if (res.status !== 200) throwForBadResponse(res, "get paper");
       return res.data;
     } catch (err) {
@@ -1578,10 +1725,7 @@ var ResearchClient = class {
     appendParam(params, "anchor", options.anchor);
     try {
       const res = await this.http.get(
-        withQuery(
-          `${BASE}/papers/${encodeURIComponent(id)}/similar`,
-          params
-        )
+        withQuery(`${BASE}/papers/${encodeURIComponent(id)}/similar`, params)
       );
       if (res.status !== 200) throwForBadResponse(res, "find similar papers");
       return res.data;
@@ -1590,7 +1734,16 @@ var ResearchClient = class {
     }
   }
   /**
-   * Search GitHub issue/PR history and repository readmes.
+   * Search the research index GitHub slice: issue/PR history and repository
+   * readmes.
+   *
+   * @deprecated Use `developerSearch()` on the client instead. This
+   * endpoint stops responding after 2026-11-03. The developer index searches
+   * GitHub issues, pull requests and readmes plus curated documentation
+   * sources, returns matched passages, and adds filters for repo, language,
+   * license and stars. It does not carry over the `scores` breakdown or the
+   * `resultType: "web"` fallback results. See
+   * https://docs.firecrawl.dev/features/developer.
    * @param query Search query.
    * @param options Optional `k`.
    */
@@ -1999,7 +2152,28 @@ var FirecrawlClient = class {
     });
   }
   async scrape(url, options) {
-    return scrape(this.http, url, options);
+    if (typeof url === "string") return scrape(this.http, url, options);
+    if (!url || options !== void 0 || Object.keys(url).some(
+      (key) => ![
+        "alexandria",
+        "requestId",
+        "timeout",
+        "integration",
+        "origin"
+      ].includes(key)
+    )) {
+      throw new Error("Provide an alexandria request without URL scrape options");
+    }
+    const { alexandria, ...opts } = url;
+    return scrapeAlexandria(
+      this.http,
+      Array.isArray(alexandria) ? alexandria : [alexandria],
+      opts
+    );
+  }
+  /** Explore the catalogue without executing the tools it returns. */
+  async findTools(options) {
+    return findTools(this.http, options);
   }
   /**
    * Interact with the browser session associated with a scrape job.
@@ -2079,6 +2253,9 @@ var FirecrawlClient = class {
    * Access the v2 research endpoints — Firecrawl's **research paper index**
    * (~43M paper abstracts) plus GitHub history/readmes.
    *
+   * `research.searchGithub()` is deprecated and stops responding after
+   * 2026-11-03. Use `developerSearch()` instead.
+   *
    * The paper corpus is roughly 90% biomedical and life sciences — PubMed,
    * bioRxiv and medRxiv — with arXiv covering physics, mathematics and
    * computer science.
@@ -2338,6 +2515,14 @@ var FirecrawlClient = class {
   async getAgentSnapshot(jobId, snapshotId) {
     return getAgentSnapshot(this.http, jobId, snapshotId);
   }
+  /**
+   * Get a thread and its runs, oldest turn first.
+   * @param threadId Thread id, as returned by startAgent or getAgentStatus.
+   * @param options.includeData Inline each succeeded run's data.
+   */
+  async getAgentThread(threadId, options) {
+    return getAgentThread(this.http, threadId, options);
+  }
   // Browser
   /**
    * Create a new browser session.
@@ -2480,7 +2665,7 @@ var FirecrawlApp = class {
       if (typeof process !== "undefined" && process.env && process.env.npm_package_version) {
         return process.env.npm_package_version;
       }
-      const packageJson = await import("./package-OS7RONXY.js");
+      const packageJson = await import("./package-F6O7J2XI.js");
       return packageJson.default.version;
     } catch (error) {
       const isTest = typeof process !== "undefined" && (process.env.JEST_WORKER_ID != null || false);
@@ -3880,5 +4065,6 @@ export {
   ResearchClient,
   SdkError,
   Watcher,
-  index_default as default
+  index_default as default,
+  parseRequiresAction
 };

package/dist/{package-OS7RONXY.js → package-F6O7J2XI.js}

@@ -1,4 +1,4 @@
 import {
   require_package
-} from "./chunk-KSTNOGOD.js";
+} from "./chunk-OJ4YJQ4J.js";
 export default require_package();

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@mendable/firecrawl-js",
-  "version": "4.38.0",
+  "version": "4.40.0",
   "description": "JavaScript SDK for the Firecrawl API: web scraping, crawling, web search, and scientific literature search over a research paper index of PubMed, bioRxiv, medRxiv and arXiv abstracts",
   "main": "dist/index.js",
   "types": "dist/index.d.ts",

package/pnpm-workspace.yaml

@@ -8,10 +8,11 @@ overrides:
   "picomatch@<4.0.4": ">=4.0.4"
   handlebars: ">=4.7.9"
   "brace-expansion@>=5.0.0 <5.0.9": "5.0.9"
-  "js-yaml@>=3.0.0 <3.15.1": "3.15.1"
-  "js-yaml@>=4.0.0 <4.3.1": "4.3.1"
+  "js-yaml@>=3.0.0 <3.15.2": "3.15.2"
+  "js-yaml@>=4.0.0 <4.3.2": "4.3.2"
   "axios@>=1.0.0 <1.16.0": "1.16.1"
   "follow-redirects@<1.16.0": ">=1.16.0 <2.0.0"
   "form-data@>=4.0.0 <4.0.6": "4.0.6"
   "@babel/core@>=7.0.0 <7.29.6": "7.29.7"
   "esbuild@>=0.17.0 <0.28.1": "0.28.1"
+  "browserslist@<=4.28.6": ">=4.28.7 <5.0.0"

package/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 field
     expect(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 field
     expect(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));
 });
 

package/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 shape
     expect(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 field
     expect(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));
 });