firecrawl 4.45.0 → 4.47.0

package/README.md

@@ -1,6 +1,6 @@
 # Firecrawl Node SDK
 
-The Firecrawl Node SDK is a library that lets you easily search, scrape, and interact with the web for AI agents — returning clean Markdown or structured data your agents can ship with. It provides a simple and intuitive interface for the Firecrawl API.
+The Firecrawl Node SDK is the JavaScript client for the Firecrawl API, the context API for AI agents. Search, scrape, parse, crawl, map, and interact with the web, and get back clean Markdown or structured data your agents can ship with.
 
 ## Installation
 
@@ -13,7 +13,7 @@ npm install firecrawl
 ## Usage
 
 1. Get an API key from [firecrawl.dev](https://firecrawl.dev)
-2. Set the API key as an environment variable named `FIRECRAWL_API_KEY` or pass it as a parameter to the `FirecrawlApp` class.
+2. Set the API key as an environment variable named `FIRECRAWL_API_KEY` or pass it as the `apiKey` option to the `Firecrawl` class.
 
 Here's an example of how to use the SDK with error handling:
 
@@ -126,7 +126,7 @@ const crawlResponse = await app.crawl('https://firecrawl.dev', {
 To start an asynchronous crawl, use `startCrawl`. It returns a job ID you can poll with `getCrawlStatus`.
 
 ```js
-const start = await app.startCrawl('https://mendable.ai', {
+const start = await app.startCrawl('https://firecrawl.dev', {
   excludePaths: ['blog/*'],
   limit: 5,
 });
@@ -137,7 +137,7 @@ const start = await app.startCrawl('https://mendable.ai', {
 To check the status of a crawl job with error handling, use the `getCrawlStatus` method. It takes the job ID as a parameter and returns the current status.
 
 ```js
-const status = await app.getCrawlStatus(id);
+const status = await app.getCrawlStatus(start.id);
 ```
 
 ### Extracting structured data from URLs
@@ -323,7 +323,7 @@ await app.stopInteraction(scrapeJobId);
 To receive real‑time updates, start a crawl and attach a watcher.
 
 ```js
-const start = await app.startCrawl('https://mendable.ai', { excludePaths: ['blog/*'], limit: 5 });
+const start = await app.startCrawl('https://firecrawl.dev', { excludePaths: ['blog/*'], limit: 5 });
 const watch = app.watcher(start.id, { kind: 'crawl', pollInterval: 2 });
 
 watch.on('document', (doc) => {
@@ -346,7 +346,7 @@ await watch.start();
 To batch scrape multiple URLs with error handling, use the `batchScrape` method.
 
 ```js
-const batchScrapeResponse = await app.batchScrape(['https://firecrawl.dev', 'https://mendable.ai'], {
+const batchScrapeResponse = await app.batchScrape(['https://firecrawl.dev', 'https://docs.firecrawl.dev'], {
   formats: ['markdown', 'html'],
 });
 ```
@@ -357,7 +357,7 @@ const batchScrapeResponse = await app.batchScrape(['https://firecrawl.dev', 'htt
 To start an asynchronous batch scrape, use `startBatchScrape` and poll with `getBatchScrapeStatus`.
 
 ```js
-const asyncBatchScrapeResult = await app.startBatchScrape(['https://firecrawl.dev', 'https://mendable.ai'], {
+const asyncBatchScrapeResult = await app.startBatchScrape(['https://firecrawl.dev', 'https://docs.firecrawl.dev'], {
   formats: ['markdown', 'html'],
 });
 ```
@@ -367,7 +367,7 @@ const asyncBatchScrapeResult = await app.startBatchScrape(['https://firecrawl.de
 To use batch scrape with real‑time updates, start the job and watch it using the watcher.
 
 ```js
-const start = await app.startBatchScrape(['https://firecrawl.dev', 'https://mendable.ai'], { formats: ['markdown', 'html'] });
+const start = await app.startBatchScrape(['https://firecrawl.dev', 'https://docs.firecrawl.dev'], { formats: ['markdown', 'html'] });
 const watch = app.watcher(start.id, { kind: 'batch', pollInterval: 2 });
 
 watch.on('document', (doc) => {

package/audit-ci.jsonc

@@ -1,19 +1,5 @@
 {
     "$schema": "https://github.com/IBM/audit-ci/raw/main/docs/schema.json",
     "low": true,
-    "allowlist": [
-        // GHSA-vfj7-8cjw-p6xm (braces):
-        // Latest published braces is 3.0.3; advisory range is <=3.0.3 and
-        // no 3.0.4+ exists on npm. Same-major jest 30.x still resolves
-        // 3.0.3 via micromatch. Cannot override to a non-existent version.
-        // Owner: team-engineering-reviewers. Tracking: create internal ticket.
-        // Expires: 2026-10-17.
-        "GHSA-vfj7-8cjw-p6xm",
-        // GHSA-hp3w-g68c-fv3c (sprintf-js):
-        // Advisory asks for >=1.1.4; latest published sprintf-js is
-        // 1.1.3. Cannot override to a non-existent version.
-        // Owner: team-engineering-reviewers. Tracking: create internal ticket.
-        // Expires: 2026-10-20.
-        "GHSA-hp3w-g68c-fv3c"
-    ]
+    "allowlist": []
 }

package/dist/chunk-H75FJ6LW.js

@@ -0,0 +1,114 @@
+// package.json
+var name = "@mendable/firecrawl-js";
+var version = "4.47.0";
+var 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";
+var main = "dist/index.js";
+var types = "dist/index.d.ts";
+var exports = {
+  "./package.json": "./package.json",
+  ".": {
+    import: "./dist/index.js",
+    default: "./dist/index.cjs"
+  }
+};
+var type = "module";
+var scripts = {
+  build: "tsup",
+  "build-and-publish": "pnpm run build && pnpm publish --access public",
+  "publish-beta": "pnpm run build && pnpm publish --access public --tag beta",
+  test: "vitest run --reporter=verbose src/__tests__/e2e/v2",
+  "test:unit": "vitest run --reporter=verbose src/__tests__/unit"
+};
+var repository = {
+  type: "git",
+  url: "git+https://github.com/firecrawl/firecrawl.git"
+};
+var author = "Mendable.ai";
+var license = "MIT";
+var dependencies = {
+  axios: "1.20.0",
+  firecrawl: "4.30.1",
+  "typescript-event-target": "^1.1.1",
+  zod: "^3.23.8",
+  "zod-to-json-schema": "^3.23.0"
+};
+var bugs = {
+  url: "https://github.com/firecrawl/firecrawl/issues"
+};
+var homepage = "https://github.com/firecrawl/firecrawl#readme";
+var devDependencies = {
+  "@types/dotenv": "^8.2.0",
+  "@types/node": "^20.12.12",
+  "@types/uuid": "^9.0.8",
+  dotenv: "^16.4.5",
+  tsup: "^8.5.0",
+  typescript: "^5.4.5",
+  uuid: "^14.0.0",
+  vitest: "^4.1.11"
+};
+var keywords = [
+  "firecrawl",
+  "mendable",
+  "crawler",
+  "web",
+  "scraper",
+  "api",
+  "sdk",
+  "web-search",
+  "literature-search",
+  "research",
+  "scientific-papers",
+  "academic-search",
+  "biomedical",
+  "life-sciences",
+  "pubmed",
+  "biorxiv",
+  "medrxiv",
+  "arxiv",
+  "preprints",
+  "citations",
+  "bioinformatics"
+];
+var engines = {
+  node: ">=22.0.0"
+};
+var package_default = {
+  name,
+  version,
+  description,
+  main,
+  types,
+  exports,
+  type,
+  scripts,
+  repository,
+  author,
+  license,
+  dependencies,
+  bugs,
+  homepage,
+  devDependencies,
+  keywords,
+  engines
+};
+
+export {
+  name,
+  version,
+  description,
+  main,
+  types,
+  exports,
+  type,
+  scripts,
+  repository,
+  author,
+  license,
+  dependencies,
+  bugs,
+  homepage,
+  devDependencies,
+  keywords,
+  engines,
+  package_default
+};

package/dist/index.cjs

@@ -39,7 +39,7 @@ var require_package = __commonJS({
   "package.json"(exports2, module2) {
     module2.exports = {
       name: "@mendable/firecrawl-js",
-      version: "4.45.0",
+      version: "4.47.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",
@@ -55,8 +55,8 @@ var require_package = __commonJS({
         build: "tsup",
         "build-and-publish": "pnpm run build && pnpm publish --access public",
         "publish-beta": "pnpm run build && pnpm publish --access public --tag beta",
-        test: "NODE_OPTIONS=--experimental-vm-modules jest --verbose src/__tests__/e2e/v2/*.test.ts --detectOpenHandles",
-        "test:unit": "NODE_OPTIONS=--experimental-vm-modules jest --verbose src/__tests__/unit"
+        test: "vitest run --reporter=verbose src/__tests__/e2e/v2",
+        "test:unit": "vitest run --reporter=verbose src/__tests__/unit"
       },
       repository: {
         type: "git",
@@ -76,18 +76,14 @@ var require_package = __commonJS({
       },
       homepage: "https://github.com/firecrawl/firecrawl#readme",
       devDependencies: {
-        "@jest/globals": "^30.2.0",
         "@types/dotenv": "^8.2.0",
-        "@types/jest": "^30.0.0",
-        "@types/mocha": "^10.0.6",
         "@types/node": "^20.12.12",
         "@types/uuid": "^9.0.8",
         dotenv: "^16.4.5",
-        jest: "^30.2.0",
-        "ts-jest": "^29.4.5",
         tsup: "^8.5.0",
         typescript: "^5.4.5",
-        uuid: "^14.0.0"
+        uuid: "^14.0.0",
+        vitest: "^4.1.11"
       },
       keywords: [
         "firecrawl",
@@ -138,16 +134,9 @@ module.exports = __toCommonJS(index_exports);
 var import_axios = __toESM(require("axios"), 1);
 
 // src/v2/utils/getVersion.ts
+var import_package = __toESM(require_package(), 1);
 function getVersion() {
-  try {
-    if (typeof process !== "undefined" && process.env && process.env.npm_package_version) {
-      return process.env.npm_package_version;
-    }
-    const pkg = require_package();
-    return pkg?.version || "3.x.x";
-  } catch {
-    return "3.x.x";
-  }
+  return import_package.version;
 }
 
 // src/utils/apiOrigin.ts
@@ -201,7 +190,7 @@ var HttpClient = class {
     return this.instance.defaults.timeout ?? 3e5;
   }
   async request(config) {
-    const version = getVersion();
+    const version2 = getVersion();
     config.headers = {
       ...config.headers || {}
     };
@@ -216,7 +205,7 @@ var HttpClient = class {
           const data = cfg.data ?? {};
           cfg.data = {
             ...data,
-            origin: typeof data.origin === "string" && data.origin.includes("mcp") ? data.origin : `js-sdk@${version}`
+            origin: typeof data.origin === "string" && data.origin.includes("mcp") ? data.origin : `js-sdk@${version2}`
           };
         }
         if (isFormDataBody) {
@@ -455,6 +444,30 @@ function ensureValidFormats(formats) {
     }
   }
 }
+var V1_SCRAPE_OPTION_REPLACEMENTS = {
+  pageOptions: "use scrapeOptions",
+  includeLinks: "add 'links' to scrapeOptions.formats",
+  parsePDF: "use scrapeOptions.parsers"
+};
+var V1_OPTION_REPLACEMENTS = {
+  crawl: {
+    crawlerOptions: "move its fields to the top level",
+    maxDepth: "use maxDiscoveryDepth",
+    allowBackwardLinks: "use crawlEntireDomain",
+    ignoreSitemap: "use sitemap: 'skip'",
+    ...V1_SCRAPE_OPTION_REPLACEMENTS
+  },
+  search: V1_SCRAPE_OPTION_REPLACEMENTS
+};
+function ensureNoV1Options(options, method) {
+  if (!options) return;
+  const replacements = V1_OPTION_REPLACEMENTS[method];
+  const found = Object.keys(replacements).filter((key) => options[key] != null);
+  if (found.length === 0) return;
+  throw new Error(
+    `${method}: ${found.map((key) => `${key} is a v1 option, ${replacements[key]}`).join("; ")}`
+  );
+}
 function ensureValidScrapeOptions(options) {
   if (!options) return;
   if (options.timeout != null && options.timeout <= 0) {
@@ -568,12 +581,28 @@ function ensureValidParseOptions(options) {
 
 // src/v2/utils/errorHandler.ts
 var import_axios2 = require("axios");
+function describeValidationIssues(details) {
+  if (!Array.isArray(details)) return void 0;
+  const parts = details.slice(0, 3).flatMap((issue) => {
+    if (!issue || typeof issue !== "object") return [];
+    const { path, message, keys } = issue;
+    const what = Array.isArray(keys) && keys.length > 0 ? `unrecognized key(s) ${keys.join(", ")}` : typeof message === "string" ? message : void 0;
+    if (!what) return [];
+    return Array.isArray(path) && path.length > 0 ? [`${path.join(".")}: ${what}`] : [what];
+  });
+  return parts.length > 0 ? parts.join("; ") : void 0;
+}
+function withIssues(message, details) {
+  const text = typeof message === "string" ? message : JSON.stringify(message);
+  const issues = describeValidationIssues(details);
+  return issues && !text.includes(issues) ? `${text} (${issues})` : text;
+}
 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 Object.assign(new SdkError(
-    msg,
+    withIssues(msg, body?.details),
     status,
     body?.code,
     body?.details,
@@ -588,7 +617,7 @@ function normalizeAxiosError(err, action) {
   const message = body?.error || err.message || `Request failed${status ? ` (${status})` : ""} while trying to ${action}`;
   const code = body?.code || err.code;
   throw Object.assign(new SdkError(
-    message,
+    withIssues(message, body?.details),
     status,
     code,
     body?.details ?? body,
@@ -759,10 +788,10 @@ async function parse(http, file, options) {
     throw new Error("file data cannot be empty");
   }
   if (options) ensureValidParseOptions(options);
-  const version = getVersion();
+  const version2 = getVersion();
   const normalizedOptions = {
     ...options ?? {},
-    origin: typeof options?.origin === "string" && options.origin.includes("mcp") ? options.origin : options?.origin ?? `js-sdk@${version}`
+    origin: typeof options?.origin === "string" && options.origin.includes("mcp") ? options.origin : options?.origin ?? `js-sdk@${version2}`
   };
   const formData = new FormData();
   formData.append("options", JSON.stringify(normalizedOptions));
@@ -800,6 +829,7 @@ async function getParseFormats(http) {
 // src/v2/methods/search.ts
 function prepareSearchPayload(req) {
   if (!req.query || !req.query.trim()) throw new Error("Query cannot be empty");
+  ensureNoV1Options(req, "search");
   if (req.limit != null && req.limit <= 0)
     throw new Error("limit must be positive");
   if (req.timeout != null && req.timeout <= 0)
@@ -1167,7 +1197,9 @@ async function fetchAllPages(http, nextUrl, initial, pagination) {
       docs.push(d);
     }
     if (maxResults != null && docs.length >= maxResults) break;
-    current = payload.next ?? (Array.isArray(payload.data) ? null : payload.data?.next) ?? null;
+    const next = payload.next ?? (Array.isArray(payload.data) ? null : payload.data?.next) ?? null;
+    if (next === current) break;
+    current = next;
     pageCount += 1;
   }
   return docs;
@@ -1176,6 +1208,7 @@ async function fetchAllPages(http, nextUrl, initial, pagination) {
 // src/v2/methods/crawl.ts
 function prepareCrawlPayload(request) {
   if (!request.url || !request.url.trim()) throw new Error("URL cannot be empty");
+  ensureNoV1Options(request, "crawl");
   const data = { url: request.url.trim() };
   if (request.prompt) data.prompt = request.prompt;
   if (request.excludePaths) data.excludePaths = request.excludePaths;
@@ -1727,6 +1760,7 @@ async function browser(http, args = {}) {
   if (args.streamWebView != null) body.streamWebView = args.streamWebView;
   if (args.blockAds != null) body.blockAds = args.blockAds;
   if (args.profile != null) body.profile = args.profile;
+  if (args.location != null) body.location = args.location;
   if (args.integration != null) body.integration = args.integration;
   if (args.origin) body.origin = args.origin;
   try {
@@ -2793,7 +2827,7 @@ var FirecrawlClient = class {
   // Browser
   /**
    * Create a new browser session.
-   * @param args Session options (ttl, activityTtl, streamWebView, blockAds, profile).
+   * @param args Session options (ttl, activityTtl, streamWebView, blockAds, profile, location).
    * @returns Session id, CDP URL, live view URL, and expiration time.
    */
   async browser(args = {}) {
@@ -2935,7 +2969,7 @@ var FirecrawlApp = class {
       const packageJson = await Promise.resolve().then(() => __toESM(require_package(), 1));
       return packageJson.default.version;
     } catch (error) {
-      const isTest = typeof process !== "undefined" && (process.env.JEST_WORKER_ID != null || false);
+      const isTest = typeof process !== "undefined" && false;
       if (!isTest) {
         console.error("Error getting version:", error);
       }

package/dist/index.d.cts

@@ -16,6 +16,7 @@ interface JsonFormat extends Format {
     type: "json";
     prompt?: string;
     schema?: Record<string, unknown> | ZodTypeAny;
+    /** @deprecated Use the top-level `checkPromptInjection` scrape option. */
     checkPromptInjection?: boolean;
 }
 interface ScreenshotFormat {
@@ -200,6 +201,13 @@ interface ScrapeOptions {
     minAge?: number;
     storeInCache?: boolean;
     lockdown?: boolean;
+    /**
+     * Scans the page content for prompt injection with any format except
+     * rawBase64, before LLM-backed formats run. A detection fails the scrape
+     * with SCRAPE_PROMPT_INJECTION_DETECTED.
+     * Adds 4 credits when the check scans the whole page.
+     */
+    checkPromptInjection?: boolean;
     redactPII?: boolean | RedactPIIOptions;
     threatProtection?: ThreatProtectionOptions;
     auditMetadata?: AuditMetadata$1;
@@ -757,10 +765,10 @@ interface FindToolsOptions {
     offset?: number;
 }
 interface FindToolsData {
-    level: "providers" | "groups" | "tools";
+    level: "categories" | "providers" | "groups" | "tools";
     items: Array<{
         id: string;
-        name: string;
+        name?: string;
         next?: AlexandriaCall;
         execute?: Pick<AlexandriaCall, "provider" | "capability">;
         [key: string]: unknown;
@@ -2111,6 +2119,10 @@ declare function browser(http: HttpClient, args?: {
         name: string;
         saveChanges?: boolean;
     };
+    /** Country the session browses from, as an ISO 3166-1 alpha-2 code (default US). */
+    location?: {
+        country: string;
+    };
     integration?: string;
     origin?: string;
 }): Promise<BrowserCreateResponse>;
@@ -2577,7 +2589,7 @@ declare class FirecrawlClient {
     }): Promise<AgentThreadResponse>;
     /**
      * Create a new browser session.
-     * @param args Session options (ttl, activityTtl, streamWebView, blockAds, profile).
+     * @param args Session options (ttl, activityTtl, streamWebView, blockAds, profile, location).
      * @returns Session id, CDP URL, live view URL, and expiration time.
      */
     browser(args?: Parameters<typeof browser>[1]): Promise<BrowserCreateResponse>;

package/dist/index.d.ts

@@ -16,6 +16,7 @@ interface JsonFormat extends Format {
     type: "json";
     prompt?: string;
     schema?: Record<string, unknown> | ZodTypeAny;
+    /** @deprecated Use the top-level `checkPromptInjection` scrape option. */
     checkPromptInjection?: boolean;
 }
 interface ScreenshotFormat {
@@ -200,6 +201,13 @@ interface ScrapeOptions {
     minAge?: number;
     storeInCache?: boolean;
     lockdown?: boolean;
+    /**
+     * Scans the page content for prompt injection with any format except
+     * rawBase64, before LLM-backed formats run. A detection fails the scrape
+     * with SCRAPE_PROMPT_INJECTION_DETECTED.
+     * Adds 4 credits when the check scans the whole page.
+     */
+    checkPromptInjection?: boolean;
     redactPII?: boolean | RedactPIIOptions;
     threatProtection?: ThreatProtectionOptions;
     auditMetadata?: AuditMetadata$1;
@@ -757,10 +765,10 @@ interface FindToolsOptions {
     offset?: number;
 }
 interface FindToolsData {
-    level: "providers" | "groups" | "tools";
+    level: "categories" | "providers" | "groups" | "tools";
     items: Array<{
         id: string;
-        name: string;
+        name?: string;
         next?: AlexandriaCall;
         execute?: Pick<AlexandriaCall, "provider" | "capability">;
         [key: string]: unknown;
@@ -2111,6 +2119,10 @@ declare function browser(http: HttpClient, args?: {
         name: string;
         saveChanges?: boolean;
     };
+    /** Country the session browses from, as an ISO 3166-1 alpha-2 code (default US). */
+    location?: {
+        country: string;
+    };
     integration?: string;
     origin?: string;
 }): Promise<BrowserCreateResponse>;
@@ -2577,7 +2589,7 @@ declare class FirecrawlClient {
     }): Promise<AgentThreadResponse>;
     /**
      * Create a new browser session.
-     * @param args Session options (ttl, activityTtl, streamWebView, blockAds, profile).
+     * @param args Session options (ttl, activityTtl, streamWebView, blockAds, profile, location).
      * @returns Session id, CDP URL, live view URL, and expiration time.
      */
     browser(args?: Parameters<typeof browser>[1]): Promise<BrowserCreateResponse>;