firecrawl 4.46.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/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.46.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",
@@ -134,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
@@ -197,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 || {}
     };
@@ -212,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) {
@@ -451,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) {
@@ -564,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,
@@ -584,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,
@@ -755,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));
@@ -796,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)
@@ -1163,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;
@@ -1172,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;
@@ -1723,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 {
@@ -2789,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 = {}) {

package/dist/index.d.cts

@@ -765,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;
@@ -2119,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>;
@@ -2585,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

@@ -765,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;
@@ -2119,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>;
@@ -2585,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.js

@@ -1,21 +1,13 @@
 import {
-  require_package
-} from "./chunk-R4XT7PME.js";
+  version
+} from "./chunk-H75FJ6LW.js";
 
 // src/v2/utils/httpClient.ts
 import axios from "axios";
 
 // src/v2/utils/getVersion.ts
 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 version;
 }
 
 // src/utils/apiOrigin.ts
@@ -69,7 +61,7 @@ var HttpClient = class {
     return this.instance.defaults.timeout ?? 3e5;
   }
   async request(config) {
-    const version = getVersion();
+    const version2 = getVersion();
     config.headers = {
       ...config.headers || {}
     };
@@ -84,7 +76,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) {
@@ -323,6 +315,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) {
@@ -436,12 +452,28 @@ function ensureValidParseOptions(options) {
 
 // src/v2/utils/errorHandler.ts
 import "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,
@@ -456,7 +488,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,
@@ -627,10 +659,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));
@@ -668,6 +700,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)
@@ -1035,7 +1068,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;
@@ -1044,6 +1079,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;
@@ -1595,6 +1631,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 {
@@ -2661,7 +2698,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 = {}) {
@@ -2800,7 +2837,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-EI4Q33HD.js");
+      const packageJson = await import("./package-NZI5TDUV.js");
       return packageJson.default.version;
     } catch (error) {
       const isTest = typeof process !== "undefined" && false;

package/dist/package-NZI5TDUV.js

@@ -0,0 +1,40 @@
+import {
+  author,
+  bugs,
+  dependencies,
+  description,
+  devDependencies,
+  engines,
+  exports,
+  homepage,
+  keywords,
+  license,
+  main,
+  name,
+  package_default,
+  repository,
+  scripts,
+  type,
+  types,
+  version
+} from "./chunk-H75FJ6LW.js";
+export {
+  author,
+  bugs,
+  package_default as default,
+  dependencies,
+  description,
+  devDependencies,
+  engines,
+  exports,
+  homepage,
+  keywords,
+  license,
+  main,
+  name,
+  repository,
+  scripts,
+  type,
+  types,
+  version
+};

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "firecrawl",
-  "version": "4.46.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",

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

@@ -0,0 +1,28 @@
+import { describe, test, expect, vi } from "vitest";
+import { browser } from "../../../v2/methods/browser";
+
+describe("JS SDK v2 browser", () => {
+  test("sends location when creating a session", async () => {
+    const post = vi.fn(async () => ({
+      status: 200,
+      data: { success: true, id: "session-1" },
+    }));
+
+    await browser({ post } as any, { location: { country: "GB" } });
+
+    expect(post).toHaveBeenCalledWith("/v2/browser", {
+      location: { country: "GB" },
+    });
+  });
+
+  test("omits location by default", async () => {
+    const post = vi.fn(async () => ({
+      status: 200,
+      data: { success: true, id: "session-1" },
+    }));
+
+    await browser({ post } as any);
+
+    expect(post).toHaveBeenCalledWith("/v2/browser", {});
+  });
+});

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

@@ -15,5 +15,28 @@ describe("v2 utils: errorHandler", () => {
     };
     expect(() => normalizeAxiosError(err, "action")).toThrow(/payment required/);
   });
+
+  test("normalizeAxiosError: names the fields a 400 validation error rejected", () => {
+    const err: any = {
+      isAxiosError: true,
+      response: {
+        status: 400,
+        data: {
+          error: "Unrecognized key in body -- please review the v2 API documentation for request body changes",
+          details: [{ code: "unrecognized_keys", keys: ["parsePDF"], path: [], message: "Unrecognized key(s) in object: 'parsePDF'" }],
+        },
+      },
+      message: "Request failed with status code 400",
+    };
+    expect(() => normalizeAxiosError(err, "scrape")).toThrow(/unrecognized key\(s\) parsePDF/);
+  });
+
+  test("throwForBadResponse: appends the path and message of each issue", () => {
+    const resp: any = {
+      status: 400,
+      data: { error: "Bad Request", details: [{ code: "invalid_union", path: ["formats", 0], message: "Invalid input" }] },
+    };
+    expect(() => throwForBadResponse(resp, "scrape")).toThrow("Bad Request (formats.0: Invalid input)");
+  });
 });
 

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

@@ -107,6 +107,26 @@ describe("JS SDK v2 pagination", () => {
     }
   });
 
+  test("crawl: stops when a running job's cursor does not advance", async () => {
+    const next = "https://api/v2/crawl/jobR?skip=2";
+    const first = { status: 200, data: { success: true, status: "scraping", completed: 2, total: 2, next, data: [{ markdown: "a" }, { markdown: "b" }] } };
+    const stalled = { status: 200, data: { success: true, status: "scraping", next, data: [] } };
+    const http = makeHttp((url) => (url === next ? stalled : first));
+    const res = await getCrawlStatus(http, "jobR");
+    expect(res.data.length).toBe(2);
+    expect((http.get as Mock).mock.calls.length).toBe(2);
+  });
+
+  test("batch: stops when a running job's cursor does not advance", async () => {
+    const next = "https://api/v2/batch/scrape/jobR?skip=2";
+    const first = { status: 200, data: { success: true, status: "scraping", completed: 2, total: 2, next, data: [{ markdown: "a" }, { markdown: "b" }] } };
+    const stalled = { status: 200, data: { success: true, status: "scraping", next, data: [] } };
+    const http = makeHttp((url) => (url === next ? stalled : first));
+    const res = await getBatchScrapeStatus(http, "jobR");
+    expect(res.data.length).toBe(2);
+    expect((http.get as Mock).mock.calls.length).toBe(2);
+  });
+
   test("batch: maxWaitTime stops pagination after first page", async () => {
     const first = { status: 200, data: { success: true, status: "completed", completed: 1, total: 5, next: "https://api/b1", data: [{ markdown: "a" }] } };
     const p1 = { status: 200, data: { success: true, next: "https://api/b2", data: [{ markdown: "b" }] } };

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

@@ -1,9 +1,47 @@
 import { describe, test, expect } from "vitest";
-import { ensureValidFormats, ensureValidScrapeOptions } from "../../../v2/utils/validation";
+import { ensureNoV1Options, ensureValidFormats, ensureValidScrapeOptions } from "../../../v2/utils/validation";
 import type { FormatOption } from "../../../v2/types";
 import { z } from "zod";
 
 describe("v2 utils: validation", () => {
+  const scrapeLevel = {
+    pageOptions: "use scrapeOptions",
+    includeLinks: "add 'links' to scrapeOptions.formats",
+    parsePDF: "use scrapeOptions.parsers",
+  };
+  const crawlOnly = {
+    crawlerOptions: "move its fields to the top level",
+    maxDepth: "use maxDiscoveryDepth",
+    allowBackwardLinks: "use crawlEntireDomain",
+    ignoreSitemap: "use sitemap: 'skip'",
+  };
+
+  test.each(Object.entries({ ...crawlOnly, ...scrapeLevel }))("ensureNoV1Options: crawl names %s and its replacement", (option, replacement) => {
+    expect(() => ensureNoV1Options({ url: "https://a.dev", [option]: true }, "crawl")).toThrow(
+      `crawl: ${option} is a v1 option, ${replacement}`,
+    );
+  });
+
+  test.each(Object.entries(scrapeLevel))("ensureNoV1Options: search names %s and its replacement", (option, replacement) => {
+    expect(() => ensureNoV1Options({ query: "q", [option]: true }, "search")).toThrow(
+      `search: ${option} is a v1 option, ${replacement}`,
+    );
+  });
+
+  test("ensureNoV1Options: search does not apply crawl-only hints", () => {
+    expect(() => ensureNoV1Options({ query: "q", maxDepth: 2, crawlerOptions: {} }, "search")).not.toThrow();
+  });
+
+  test("ensureNoV1Options: lists every v1 option found", () => {
+    expect(() => ensureNoV1Options({ maxDepth: 2, allowBackwardLinks: true }, "crawl")).toThrow(/maxDepth.*maxDiscoveryDepth.*allowBackwardLinks.*crawlEntireDomain/);
+  });
+
+  test("ensureNoV1Options: accepts v2 options and unset v1 keys", () => {
+    expect(() => ensureNoV1Options({ url: "https://a.dev", limit: 2, maxDiscoveryDepth: 1 }, "crawl")).not.toThrow();
+    expect(() => ensureNoV1Options({ url: "https://a.dev", maxDepth: undefined }, "crawl")).not.toThrow();
+    expect(() => ensureNoV1Options(undefined, "search")).not.toThrow();
+  });
+
   test("ensureValidFormats: plain 'json' string is invalid", () => {
     const formats: FormatOption[] = ["markdown", "json"] as unknown as FormatOption[];
     expect(() => ensureValidFormats(formats)).toThrow(/json format must be an object/i);

package/src/v2/client.ts

@@ -644,7 +644,7 @@ export class FirecrawlClient {
   // 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(

package/src/v2/methods/browser.ts

@@ -22,6 +22,8 @@ export async function browser(
       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;
   } = {},
@@ -32,6 +34,7 @@ export async function browser(
   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;
 

package/src/v2/methods/crawl.ts

@@ -10,7 +10,7 @@ import {
   SdkError,
 } from "../types";
 import { HttpClient } from "../utils/httpClient";
-import { ensureValidScrapeOptions } from "../utils/validation";
+import { ensureNoV1Options, ensureValidScrapeOptions } from "../utils/validation";
 import { normalizeAxiosError, throwForBadResponse, isRetryableError } from "../utils/errorHandler";
 import type { HttpClient as _Http } from "../utils/httpClient";
 import { fetchAllPages } from "../utils/pagination";
@@ -21,6 +21,7 @@ export type CrawlRequest = CrawlOptions & {
 
 function prepareCrawlPayload(request: CrawlRequest): Record<string, unknown> {
   if (!request.url || !request.url.trim()) throw new Error("URL cannot be empty");
+  ensureNoV1Options(request, "crawl");
   const data: Record<string, unknown> = { url: request.url.trim() };
   if (request.prompt) data.prompt = request.prompt;
   if (request.excludePaths) data.excludePaths = request.excludePaths;

package/src/v2/methods/search.ts

@@ -9,7 +9,7 @@ import {
 } from "../types";
 import { HttpClient } from "../utils/httpClient";
 import { agentHintMetadata } from "../utils/agentHints";
-import { ensureValidScrapeOptions } from "../utils/validation";
+import { ensureNoV1Options, ensureValidScrapeOptions } from "../utils/validation";
 import {
   throwForBadResponse,
   normalizeAxiosError,
@@ -17,6 +17,7 @@ import {
 
 function prepareSearchPayload(req: SearchRequest): Record<string, unknown> {
   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)

package/src/v2/types.ts

@@ -915,10 +915,10 @@ export interface FindToolsOptions {
 }
 
 export 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;

package/src/v2/utils/errorHandler.ts

@@ -2,12 +2,33 @@ import { type AxiosError, type AxiosResponse } from "axios";
 import { SdkError, JobTimeoutError, parseRequiresAction } from "../types";
 import { agentHintMetadata } from "./agentHints";
 
+/** Names the fields a validation error rejected, so a bare "Bad Request" says what to change. */
+function describeValidationIssues(details: unknown): string | undefined {
+  if (!Array.isArray(details)) return undefined;
+  const parts = details.slice(0, 3).flatMap((issue) => {
+    if (!issue || typeof issue !== "object") return [];
+    const { path, message, keys } = issue as { path?: unknown; message?: unknown; keys?: unknown };
+    const what = Array.isArray(keys) && keys.length > 0
+      ? `unrecognized key(s) ${keys.join(", ")}`
+      : typeof message === "string" ? message : undefined;
+    if (!what) return [];
+    return Array.isArray(path) && path.length > 0 ? [`${path.join(".")}: ${what}`] : [what];
+  });
+  return parts.length > 0 ? parts.join("; ") : undefined;
+}
+
+function withIssues(message: unknown, details: unknown): string {
+  const text = typeof message === "string" ? message : JSON.stringify(message);
+  const issues = describeValidationIssues(details);
+  return issues && !text.includes(issues) ? `${text} (${issues})` : text;
+}
+
 export function throwForBadResponse(resp: AxiosResponse, action: string): never {
   const status = resp.status;
   const body = resp.data || {};
   const msg = body?.error || body?.message || `Request failed (${status}) while trying to ${action}`;
   throw Object.assign(new SdkError(
-    msg,
+    withIssues(msg, body?.details),
     status,
     body?.code,
     body?.details,
@@ -23,7 +44,7 @@ export function normalizeAxiosError(err: AxiosError, action: string): never {
   const message = body?.error || err.message || `Request failed${status ? ` (${status})` : ""} while trying to ${action}`;
   const code = (body?.code as string) || err.code;
   throw Object.assign(new SdkError(
-    message,
+    withIssues(message, body?.details),
     status,
     code,
     body?.details ?? body,

package/src/v2/utils/getVersion.ts

@@ -1,14 +1,6 @@
-export function getVersion(): string {
-  try {
-    if (typeof process !== "undefined" && process.env && process.env.npm_package_version) {
-      return process.env.npm_package_version as string;
-    }
+import { version } from "../../../package.json";
 
-    // eslint-disable-next-line @typescript-eslint/no-var-requires
-    const pkg = require("../../../package.json");
-    return (pkg?.version as string) || "3.x.x";
-  } catch {
-    return "3.x.x";
-  }
+/** The SDK's own version, inlined at build time so a host app's npm_package_version never replaces it. */
+export function getVersion(): string {
+  return version;
 }
-

package/src/v2/utils/pagination.ts

@@ -39,7 +39,10 @@ export async function fetchAllPages<T = Document>(
       docs.push(d as T);
     }
     if (maxResults != null && docs.length >= maxResults) break;
-    current = (payload.next ?? (Array.isArray(payload.data) ? null : payload.data?.next) ?? null) as string | null;
+    const next = (payload.next ?? (Array.isArray(payload.data) ? null : payload.data?.next) ?? null) as string | null;
+    // A running job's cursor can point back at itself until new documents land; re-requesting it here only spins.
+    if (next === current) break;
+    current = next;
     pageCount += 1;
   }
   return docs;

package/src/v2/utils/validation.ts

@@ -86,6 +86,34 @@ export function ensureValidFormats(formats?: FormatOption[]): void {
   }
 }
 
+const V1_SCRAPE_OPTION_REPLACEMENTS: Record<string, string> = {
+  pageOptions: "use scrapeOptions",
+  includeLinks: "add 'links' to scrapeOptions.formats",
+  parsePDF: "use scrapeOptions.parsers",
+};
+
+const V1_OPTION_REPLACEMENTS: Record<"crawl" | "search", Record<string, string>> = {
+  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,
+};
+
+/** Throws on v1 option names, which the v2 payload builders would otherwise drop without a word. */
+export function ensureNoV1Options(options: object | undefined, method: "crawl" | "search"): void {
+  if (!options) return;
+  const replacements = V1_OPTION_REPLACEMENTS[method];
+  const found = Object.keys(replacements).filter((key) => (options as Record<string, unknown>)[key] != null);
+  if (found.length === 0) return;
+  throw new Error(
+    `${method}: ${found.map((key) => `${key} is a v1 option, ${replacements[key]}`).join("; ")}`,
+  );
+}
+
 export function ensureValidScrapeOptions(options?: ScrapeOptions): void {
   if (!options) return;
   if (options.timeout != null && options.timeout <= 0) {

package/dist/chunk-R4XT7PME.js

@@ -1,93 +0,0 @@
-var __getOwnPropNames = Object.getOwnPropertyNames;
-var __commonJS = (cb, mod) => function __require() {
-  try {
-    return mod || (0, cb[__getOwnPropNames(cb)[0]])((mod = { exports: {} }).exports, mod), mod.exports;
-  } catch (e) {
-    throw mod = 0, e;
-  }
-};
-
-// package.json
-var require_package = __commonJS({
-  "package.json"(exports, module) {
-    module.exports = {
-      name: "@mendable/firecrawl-js",
-      version: "4.46.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",
-      exports: {
-        "./package.json": "./package.json",
-        ".": {
-          import: "./dist/index.js",
-          default: "./dist/index.cjs"
-        }
-      },
-      type: "module",
-      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"
-      },
-      repository: {
-        type: "git",
-        url: "git+https://github.com/firecrawl/firecrawl.git"
-      },
-      author: "Mendable.ai",
-      license: "MIT",
-      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"
-      },
-      bugs: {
-        url: "https://github.com/firecrawl/firecrawl/issues"
-      },
-      homepage: "https://github.com/firecrawl/firecrawl#readme",
-      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"
-      },
-      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"
-      ],
-      engines: {
-        node: ">=22.0.0"
-      }
-    };
-  }
-});
-
-export {
-  require_package
-};

package/dist/package-EI4Q33HD.js

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