@mendable/firecrawl-js 4.49.2 → 4.50.1

package/README.md

@@ -15,7 +15,7 @@ npm install firecrawl
 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 the `apiKey` option to the `Firecrawl` class.
 
-Here's an example of how to use the SDK with error handling:
+Here's an example of how to use the SDK with error handling. It uses ES modules and top-level `await`, so save it as an `.mjs` file or set `"type": "module"` in your `package.json`:
 
 ```js
 import { Firecrawl } from 'firecrawl';

package/dist/{chunk-JRVJFY7G.js → chunk-UGAMW2BL.js}

@@ -1,6 +1,6 @@
 // package.json
 var name = "@mendable/firecrawl-js";
-var version = "4.49.2";
+var version = "4.50.1";
 var description = "JavaScript SDK for Firecrawl, the context API for AI agents: search, scrape, parse, crawl, map, and interact with the web, run Agent and Monitor jobs, and search scientific papers (PubMed, bioRxiv, medRxiv, arXiv)";
 var main = "dist/index.js";
 var types = "dist/index.d.ts";
@@ -44,7 +44,7 @@ var devDependencies = {
   tsup: "^8.5.0",
   typescript: "^5.4.5",
   uuid: "^14.0.0",
-  vitest: "^4.1.11"
+  vitest: "^4.1.12"
 };
 var keywords = [
   "firecrawl",
@@ -70,7 +70,7 @@ var keywords = [
   "bioinformatics"
 ];
 var engines = {
-  node: ">=22.0.0"
+  node: ">=18.0.0"
 };
 var package_default = {
   name,

package/dist/index.cjs

@@ -39,7 +39,7 @@ var require_package = __commonJS({
   "package.json"(exports2, module2) {
     module2.exports = {
       name: "@mendable/firecrawl-js",
-      version: "4.49.2",
+      version: "4.50.1",
       description: "JavaScript SDK for Firecrawl, the context API for AI agents: search, scrape, parse, crawl, map, and interact with the web, run Agent and Monitor jobs, and search scientific papers (PubMed, bioRxiv, medRxiv, arXiv)",
       main: "dist/index.js",
       types: "dist/index.d.ts",
@@ -83,7 +83,7 @@ var require_package = __commonJS({
         tsup: "^8.5.0",
         typescript: "^5.4.5",
         uuid: "^14.0.0",
-        vitest: "^4.1.11"
+        vitest: "^4.1.12"
       },
       keywords: [
         "firecrawl",
@@ -109,7 +109,7 @@ var require_package = __commonJS({
         "bioinformatics"
       ],
       engines: {
-        node: ">=22.0.0"
+        node: ">=18.0.0"
       }
     };
   }
@@ -155,6 +155,15 @@ function pinToApiOrigin(apiUrl, url) {
 }
 
 // src/v2/utils/httpClient.ts
+var rejectsDefaultCacheMode = () => {
+  if (typeof Request !== "function") return false;
+  try {
+    new Request("https://api.firecrawl.dev", { cache: "default" });
+    return false;
+  } catch {
+    return true;
+  }
+};
 var HttpClient = class {
   instance;
   apiKey;
@@ -177,7 +186,8 @@ var HttpClient = class {
         // grants it when no Authorization header is present).
         ...this.apiKey ? { Authorization: `Bearer ${this.apiKey}` } : {}
       },
-      transitional: { clarifyTimeoutError: true }
+      transitional: { clarifyTimeoutError: true },
+      ...rejectsDefaultCacheMode() ? { adapter: "fetch", env: { Request: null } } : {}
     });
   }
   getApiUrl() {
@@ -1664,6 +1674,8 @@ function prepareAgentPayload(args) {
   if (args.threadId != null) body.threadId = args.threadId;
   if (args.mode != null) body.mode = args.mode;
   if (args.exchange != null) body.exchange = args.exchange;
+  if (args.location != null) body.location = args.location;
+  if (args.zeroDataRetention != null) body.zeroDataRetention = args.zeroDataRetention;
   return body;
 }
 async function startAgent(http, args) {
@@ -2246,37 +2258,84 @@ function defaultOrigin(version2) {
 }
 
 // src/v2/watcher.ts
-var import_events = require("events");
-var hasGlobalWebSocket = () => {
-  if (typeof globalThis === "undefined") return void 0;
+var getWebSocketCtor = () => {
   const candidate = globalThis.WebSocket;
   return typeof candidate === "function" ? candidate : void 0;
 };
-var isNodeRuntime = () => typeof process !== "undefined" && !!process.versions?.node;
-var cachedWebSocket;
-var loadPromise;
-var loadNodeWebSocket = async () => {
-  if (!isNodeRuntime()) return void 0;
-  try {
-    const undici = await import("undici");
-    const ctor = undici.WebSocket ?? undici.default?.WebSocket;
-    return typeof ctor === "function" ? ctor : void 0;
-  } catch {
-    return void 0;
+var Emitter = class {
+  listenersByEvent = /* @__PURE__ */ new Map();
+  maxListeners = 10;
+  on(event, listener) {
+    this.listenersByEvent.set(event, [...this.listenersByEvent.get(event) ?? [], listener]);
+    return this;
+  }
+  prependListener(event, listener) {
+    this.listenersByEvent.set(event, [listener, ...this.listenersByEvent.get(event) ?? []]);
+    return this;
+  }
+  prependOnceListener(event, listener) {
+    return this.prependListener(event, this.onceWrapper(event, listener));
+  }
+  listeners(event) {
+    return (this.listenersByEvent.get(event) ?? []).map((entry) => entry.listener ?? entry);
+  }
+  rawListeners(event) {
+    return [...this.listenersByEvent.get(event) ?? []];
+  }
+  eventNames() {
+    return [...this.listenersByEvent.keys()].filter((event) => this.listenerCount(event) > 0);
+  }
+  setMaxListeners(n) {
+    this.maxListeners = n;
+    return this;
+  }
+  getMaxListeners() {
+    return this.maxListeners;
+  }
+  addListener(event, listener) {
+    return this.on(event, listener);
+  }
+  once(event, listener) {
+    return this.on(event, this.onceWrapper(event, listener));
+  }
+  onceWrapper(event, listener) {
+    const wrapped = (...args) => {
+      this.off(event, wrapped);
+      listener.apply(this, args);
+    };
+    wrapped.listener = listener;
+    return wrapped;
+  }
+  off(event, listener) {
+    const current = this.listenersByEvent.get(event);
+    if (!current) return this;
+    for (let index = current.length - 1; index >= 0; index--) {
+      if (current[index] !== listener && current[index].listener !== listener) continue;
+      this.listenersByEvent.set(event, current.filter((_, i) => i !== index));
+      break;
+    }
+    return this;
+  }
+  removeListener(event, listener) {
+    return this.off(event, listener);
+  }
+  removeAllListeners(event) {
+    if (event === void 0) this.listenersByEvent.clear();
+    else this.listenersByEvent.delete(event);
+    return this;
+  }
+  listenerCount(event) {
+    return this.listenersByEvent.get(event)?.length ?? 0;
+  }
+  emit(event, ...args) {
+    const current = this.listenersByEvent.get(event);
+    if (!current?.length) {
+      if (event === "error") throw args[0] instanceof Error ? args[0] : new Error(String(args[0]));
+      return false;
+    }
+    for (const listener of [...current]) listener.apply(this, args);
+    return true;
   }
-};
-var getWebSocketCtor = async () => {
-  if (cachedWebSocket) return cachedWebSocket;
-  const globalWs = hasGlobalWebSocket();
-  if (globalWs) {
-    cachedWebSocket = globalWs;
-    return cachedWebSocket;
-  }
-  if (!loadPromise) {
-    loadPromise = loadNodeWebSocket();
-  }
-  cachedWebSocket = await loadPromise;
-  return cachedWebSocket;
 };
 var decoder = typeof TextDecoder !== "undefined" ? new TextDecoder() : void 0;
 var ensureUtf8String = (data) => {
@@ -2298,7 +2357,7 @@ var ensureUtf8String = (data) => {
   }
   return void 0;
 };
-var Watcher = class extends import_events.EventEmitter {
+var Watcher = class extends Emitter {
   http;
   jobId;
   kind;
@@ -2340,7 +2399,7 @@ var Watcher = class extends import_events.EventEmitter {
       (async () => {
         try {
           const url = this.buildWsUrl();
-          const wsCtor = await getWebSocketCtor();
+          const wsCtor = getWebSocketCtor();
           if (!wsCtor) {
             this.pollLoop();
             return;
@@ -2526,8 +2585,9 @@ var FirecrawlClient = class {
    */
   constructor(options = {}) {
     const opts = typeof options === "string" ? { apiKey: options } : options;
-    const apiKey = (opts.apiKey ?? process.env.FIRECRAWL_API_KEY ?? "").trim();
-    const apiUrl = (opts.apiUrl ?? process.env.FIRECRAWL_API_URL ?? "https://api.firecrawl.dev").replace(/\/$/, "");
+    const hasEnv = typeof process !== "undefined" && !!process.env;
+    const apiKey = (opts.apiKey ?? (hasEnv ? process.env.FIRECRAWL_API_KEY : void 0) ?? "").trim();
+    const apiUrl = (opts.apiUrl ?? (hasEnv ? process.env.FIRECRAWL_API_URL : void 0) ?? "https://api.firecrawl.dev").replace(/\/$/, "");
     this.http = new HttpClient({
       apiKey,
       apiUrl,
@@ -3073,7 +3133,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" && false;
+      const isTest = typeof process !== "undefined" && !!process.env && false;
       if (!isTest) {
         console.error("Error getting version:", error);
       }
@@ -4362,6 +4422,9 @@ var CrawlWatcher = class extends e {
     super();
     this.id = id;
     const wsUrl = app.apiUrl.replace(/^http/, "ws");
+    if (typeof WebSocket === "undefined") {
+      throw new Error("Watching a crawl needs a global WebSocket (Node 22+, Bun, Deno or a browser). On older Node, use the v2 client's watcher(), which polls instead.");
+    }
     this.ws = new WebSocket(`${wsUrl}/v1/crawl/${id}`, app.apiKey);
     this.status = "scraping";
     this.data = [];

package/dist/index.d.cts

@@ -1,7 +1,6 @@
 import * as zt from 'zod';
 import { ZodTypeAny } from 'zod';
 import { AxiosResponse, AxiosRequestHeaders } from 'axios';
-import { EventEmitter } from 'events';
 import { TypedEventTarget } from 'typescript-event-target';
 
 type FormatString = "markdown" | "html" | "rawHtml" | "links" | "images" | "screenshot" | "summary" | "changeTracking" | "json" | "attributes" | "branding" | "product" | "menu" | "audio" | "video";
@@ -1553,7 +1552,7 @@ interface AgentTraceAgentIdentity {
     parentId?: string;
 }
 interface AgentTraceError {
-    code: "cancelled" | "credit_limit_reached" | "parent_finished" | "refused" | "internal";
+    code: "cancelled" | "credit_limit_reached" | "insufficient_credits" | "parent_finished" | "refused" | "internal";
     source: "agent" | "tool" | "billing" | "system";
     retryable: boolean;
     message: string;
@@ -1659,6 +1658,8 @@ interface AgentTraceResponse {
     creditsUsed?: number;
     /** Present only when the trace was requested with liveView: true. */
     activeBrowserSessions?: AgentTraceActiveBrowserSession[];
+    /** True for a zero data retention run: events are limited to content-free lifecycle events. */
+    zeroDataRetention?: boolean;
     error?: string;
 }
 interface AgentSnapshotResponse {
@@ -2110,6 +2111,14 @@ declare function prepareAgentPayload(args: {
     threadId?: string;
     mode?: AgentMode;
     exchange?: AgentExchangeOptions;
+    /**
+     * Country for the whole run (ISO 3166-1 alpha-2). Scrapes and browser sessions are proxied from it,
+     * and search results are localized to it without changing where requests come from. The agent cannot change it.
+     */
+    location?: {
+        country: string;
+    };
+    zeroDataRetention?: boolean;
 }): Record<string, unknown>;
 declare function startAgent(http: HttpClient, args: Parameters<typeof prepareAgentPayload>[0]): Promise<AgentResponse>;
 
@@ -2222,13 +2231,37 @@ declare class ResearchClient {
     searchGithub(query: string, options?: SearchGithubOptions): Promise<GitHubSearchResponse>;
 }
 
+type Listener = ((...args: any[]) => void) & {
+    listener?: Listener;
+};
+/** Node's EventEmitter API for the watcher, with no import of "events", so browser bundles load it. */
+declare class Emitter {
+    private readonly listenersByEvent;
+    private maxListeners;
+    on(event: string | symbol, listener: Listener): this;
+    prependListener(event: string | symbol, listener: Listener): this;
+    prependOnceListener(event: string | symbol, listener: Listener): this;
+    listeners(event: string | symbol): Listener[];
+    rawListeners(event: string | symbol): Listener[];
+    eventNames(): (string | symbol)[];
+    setMaxListeners(n: number): this;
+    getMaxListeners(): number;
+    addListener(event: string | symbol, listener: Listener): this;
+    once(event: string | symbol, listener: Listener): this;
+    private onceWrapper;
+    off(event: string | symbol, listener: Listener): this;
+    removeListener(event: string | symbol, listener: Listener): this;
+    removeAllListeners(event?: string | symbol): this;
+    listenerCount(event: string | symbol): number;
+    emit(event: string | symbol, ...args: any[]): boolean;
+}
 type JobKind = "crawl" | "batch";
 interface WatcherOptions {
     kind?: JobKind;
     pollInterval?: number;
     timeout?: number;
 }
-declare class Watcher extends EventEmitter {
+declare class Watcher extends Emitter {
     private readonly http;
     private readonly jobId;
     private readonly kind;

package/dist/index.d.ts

@@ -1,7 +1,6 @@
 import * as zt from 'zod';
 import { ZodTypeAny } from 'zod';
 import { AxiosResponse, AxiosRequestHeaders } from 'axios';
-import { EventEmitter } from 'events';
 import { TypedEventTarget } from 'typescript-event-target';
 
 type FormatString = "markdown" | "html" | "rawHtml" | "links" | "images" | "screenshot" | "summary" | "changeTracking" | "json" | "attributes" | "branding" | "product" | "menu" | "audio" | "video";
@@ -1553,7 +1552,7 @@ interface AgentTraceAgentIdentity {
     parentId?: string;
 }
 interface AgentTraceError {
-    code: "cancelled" | "credit_limit_reached" | "parent_finished" | "refused" | "internal";
+    code: "cancelled" | "credit_limit_reached" | "insufficient_credits" | "parent_finished" | "refused" | "internal";
     source: "agent" | "tool" | "billing" | "system";
     retryable: boolean;
     message: string;
@@ -1659,6 +1658,8 @@ interface AgentTraceResponse {
     creditsUsed?: number;
     /** Present only when the trace was requested with liveView: true. */
     activeBrowserSessions?: AgentTraceActiveBrowserSession[];
+    /** True for a zero data retention run: events are limited to content-free lifecycle events. */
+    zeroDataRetention?: boolean;
     error?: string;
 }
 interface AgentSnapshotResponse {
@@ -2110,6 +2111,14 @@ declare function prepareAgentPayload(args: {
     threadId?: string;
     mode?: AgentMode;
     exchange?: AgentExchangeOptions;
+    /**
+     * Country for the whole run (ISO 3166-1 alpha-2). Scrapes and browser sessions are proxied from it,
+     * and search results are localized to it without changing where requests come from. The agent cannot change it.
+     */
+    location?: {
+        country: string;
+    };
+    zeroDataRetention?: boolean;
 }): Record<string, unknown>;
 declare function startAgent(http: HttpClient, args: Parameters<typeof prepareAgentPayload>[0]): Promise<AgentResponse>;
 
@@ -2222,13 +2231,37 @@ declare class ResearchClient {
     searchGithub(query: string, options?: SearchGithubOptions): Promise<GitHubSearchResponse>;
 }
 
+type Listener = ((...args: any[]) => void) & {
+    listener?: Listener;
+};
+/** Node's EventEmitter API for the watcher, with no import of "events", so browser bundles load it. */
+declare class Emitter {
+    private readonly listenersByEvent;
+    private maxListeners;
+    on(event: string | symbol, listener: Listener): this;
+    prependListener(event: string | symbol, listener: Listener): this;
+    prependOnceListener(event: string | symbol, listener: Listener): this;
+    listeners(event: string | symbol): Listener[];
+    rawListeners(event: string | symbol): Listener[];
+    eventNames(): (string | symbol)[];
+    setMaxListeners(n: number): this;
+    getMaxListeners(): number;
+    addListener(event: string | symbol, listener: Listener): this;
+    once(event: string | symbol, listener: Listener): this;
+    private onceWrapper;
+    off(event: string | symbol, listener: Listener): this;
+    removeListener(event: string | symbol, listener: Listener): this;
+    removeAllListeners(event?: string | symbol): this;
+    listenerCount(event: string | symbol): number;
+    emit(event: string | symbol, ...args: any[]): boolean;
+}
 type JobKind = "crawl" | "batch";
 interface WatcherOptions {
     kind?: JobKind;
     pollInterval?: number;
     timeout?: number;
 }
-declare class Watcher extends EventEmitter {
+declare class Watcher extends Emitter {
     private readonly http;
     private readonly jobId;
     private readonly kind;

package/dist/index.js

@@ -1,6 +1,6 @@
 import {
   version
-} from "./chunk-JRVJFY7G.js";
+} from "./chunk-UGAMW2BL.js";
 
 // src/v2/utils/httpClient.ts
 import axios from "axios";
@@ -26,6 +26,15 @@ function pinToApiOrigin(apiUrl, url) {
 }
 
 // src/v2/utils/httpClient.ts
+var rejectsDefaultCacheMode = () => {
+  if (typeof Request !== "function") return false;
+  try {
+    new Request("https://api.firecrawl.dev", { cache: "default" });
+    return false;
+  } catch {
+    return true;
+  }
+};
 var HttpClient = class {
   instance;
   apiKey;
@@ -48,7 +57,8 @@ var HttpClient = class {
         // grants it when no Authorization header is present).
         ...this.apiKey ? { Authorization: `Bearer ${this.apiKey}` } : {}
       },
-      transitional: { clarifyTimeoutError: true }
+      transitional: { clarifyTimeoutError: true },
+      ...rejectsDefaultCacheMode() ? { adapter: "fetch", env: { Request: null } } : {}
     });
   }
   getApiUrl() {
@@ -1535,6 +1545,8 @@ function prepareAgentPayload(args) {
   if (args.threadId != null) body.threadId = args.threadId;
   if (args.mode != null) body.mode = args.mode;
   if (args.exchange != null) body.exchange = args.exchange;
+  if (args.location != null) body.location = args.location;
+  if (args.zeroDataRetention != null) body.zeroDataRetention = args.zeroDataRetention;
   return body;
 }
 async function startAgent(http, args) {
@@ -2117,37 +2129,84 @@ function defaultOrigin(version2) {
 }
 
 // src/v2/watcher.ts
-import { EventEmitter } from "events";
-var hasGlobalWebSocket = () => {
-  if (typeof globalThis === "undefined") return void 0;
+var getWebSocketCtor = () => {
   const candidate = globalThis.WebSocket;
   return typeof candidate === "function" ? candidate : void 0;
 };
-var isNodeRuntime = () => typeof process !== "undefined" && !!process.versions?.node;
-var cachedWebSocket;
-var loadPromise;
-var loadNodeWebSocket = async () => {
-  if (!isNodeRuntime()) return void 0;
-  try {
-    const undici = await import("undici");
-    const ctor = undici.WebSocket ?? undici.default?.WebSocket;
-    return typeof ctor === "function" ? ctor : void 0;
-  } catch {
-    return void 0;
+var Emitter = class {
+  listenersByEvent = /* @__PURE__ */ new Map();
+  maxListeners = 10;
+  on(event, listener) {
+    this.listenersByEvent.set(event, [...this.listenersByEvent.get(event) ?? [], listener]);
+    return this;
+  }
+  prependListener(event, listener) {
+    this.listenersByEvent.set(event, [listener, ...this.listenersByEvent.get(event) ?? []]);
+    return this;
+  }
+  prependOnceListener(event, listener) {
+    return this.prependListener(event, this.onceWrapper(event, listener));
+  }
+  listeners(event) {
+    return (this.listenersByEvent.get(event) ?? []).map((entry) => entry.listener ?? entry);
+  }
+  rawListeners(event) {
+    return [...this.listenersByEvent.get(event) ?? []];
+  }
+  eventNames() {
+    return [...this.listenersByEvent.keys()].filter((event) => this.listenerCount(event) > 0);
+  }
+  setMaxListeners(n) {
+    this.maxListeners = n;
+    return this;
+  }
+  getMaxListeners() {
+    return this.maxListeners;
+  }
+  addListener(event, listener) {
+    return this.on(event, listener);
+  }
+  once(event, listener) {
+    return this.on(event, this.onceWrapper(event, listener));
+  }
+  onceWrapper(event, listener) {
+    const wrapped = (...args) => {
+      this.off(event, wrapped);
+      listener.apply(this, args);
+    };
+    wrapped.listener = listener;
+    return wrapped;
+  }
+  off(event, listener) {
+    const current = this.listenersByEvent.get(event);
+    if (!current) return this;
+    for (let index = current.length - 1; index >= 0; index--) {
+      if (current[index] !== listener && current[index].listener !== listener) continue;
+      this.listenersByEvent.set(event, current.filter((_, i) => i !== index));
+      break;
+    }
+    return this;
+  }
+  removeListener(event, listener) {
+    return this.off(event, listener);
+  }
+  removeAllListeners(event) {
+    if (event === void 0) this.listenersByEvent.clear();
+    else this.listenersByEvent.delete(event);
+    return this;
+  }
+  listenerCount(event) {
+    return this.listenersByEvent.get(event)?.length ?? 0;
+  }
+  emit(event, ...args) {
+    const current = this.listenersByEvent.get(event);
+    if (!current?.length) {
+      if (event === "error") throw args[0] instanceof Error ? args[0] : new Error(String(args[0]));
+      return false;
+    }
+    for (const listener of [...current]) listener.apply(this, args);
+    return true;
   }
-};
-var getWebSocketCtor = async () => {
-  if (cachedWebSocket) return cachedWebSocket;
-  const globalWs = hasGlobalWebSocket();
-  if (globalWs) {
-    cachedWebSocket = globalWs;
-    return cachedWebSocket;
-  }
-  if (!loadPromise) {
-    loadPromise = loadNodeWebSocket();
-  }
-  cachedWebSocket = await loadPromise;
-  return cachedWebSocket;
 };
 var decoder = typeof TextDecoder !== "undefined" ? new TextDecoder() : void 0;
 var ensureUtf8String = (data) => {
@@ -2169,7 +2228,7 @@ var ensureUtf8String = (data) => {
   }
   return void 0;
 };
-var Watcher = class extends EventEmitter {
+var Watcher = class extends Emitter {
   http;
   jobId;
   kind;
@@ -2211,7 +2270,7 @@ var Watcher = class extends EventEmitter {
       (async () => {
         try {
           const url = this.buildWsUrl();
-          const wsCtor = await getWebSocketCtor();
+          const wsCtor = getWebSocketCtor();
           if (!wsCtor) {
             this.pollLoop();
             return;
@@ -2397,8 +2456,9 @@ var FirecrawlClient = class {
    */
   constructor(options = {}) {
     const opts = typeof options === "string" ? { apiKey: options } : options;
-    const apiKey = (opts.apiKey ?? process.env.FIRECRAWL_API_KEY ?? "").trim();
-    const apiUrl = (opts.apiUrl ?? process.env.FIRECRAWL_API_URL ?? "https://api.firecrawl.dev").replace(/\/$/, "");
+    const hasEnv = typeof process !== "undefined" && !!process.env;
+    const apiKey = (opts.apiKey ?? (hasEnv ? process.env.FIRECRAWL_API_KEY : void 0) ?? "").trim();
+    const apiUrl = (opts.apiUrl ?? (hasEnv ? process.env.FIRECRAWL_API_URL : void 0) ?? "https://api.firecrawl.dev").replace(/\/$/, "");
     this.http = new HttpClient({
       apiKey,
       apiUrl,
@@ -2941,10 +3001,10 @@ 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-DW3K6CBX.js");
+      const packageJson = await import("./package-TFTOUFDX.js");
       return packageJson.default.version;
     } catch (error) {
-      const isTest = typeof process !== "undefined" && false;
+      const isTest = typeof process !== "undefined" && !!process.env && false;
       if (!isTest) {
         console.error("Error getting version:", error);
       }
@@ -4233,6 +4293,9 @@ var CrawlWatcher = class extends e {
     super();
     this.id = id;
     const wsUrl = app.apiUrl.replace(/^http/, "ws");
+    if (typeof WebSocket === "undefined") {
+      throw new Error("Watching a crawl needs a global WebSocket (Node 22+, Bun, Deno or a browser). On older Node, use the v2 client's watcher(), which polls instead.");
+    }
     this.ws = new WebSocket(`${wsUrl}/v1/crawl/${id}`, app.apiKey);
     this.status = "scraping";
     this.data = [];

package/dist/{package-DW3K6CBX.js → package-TFTOUFDX.js}

@@ -17,7 +17,7 @@ import {
   type,
   types,
   version
-} from "./chunk-JRVJFY7G.js";
+} from "./chunk-UGAMW2BL.js";
 export {
   author,
   bugs,

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@mendable/firecrawl-js",
-  "version": "4.49.2",
+  "version": "4.50.1",
   "description": "JavaScript SDK for Firecrawl, the context API for AI agents: search, scrape, parse, crawl, map, and interact with the web, run Agent and Monitor jobs, and search scientific papers (PubMed, bioRxiv, medRxiv, arXiv)",
   "main": "dist/index.js",
   "types": "dist/index.d.ts",
@@ -20,7 +20,7 @@
   "license": "MIT",
   "dependencies": {
     "axios": "1.20.0",
-    "firecrawl": "4.49.2",
+    "firecrawl": "4.50.1",
     "typescript-event-target": "^1.1.1",
     "zod": "^3.23.8",
     "zod-to-json-schema": "^3.23.0"
@@ -37,7 +37,7 @@
     "tsup": "^8.5.0",
     "typescript": "^5.4.5",
     "uuid": "^14.0.0",
-    "vitest": "^4.1.11"
+    "vitest": "^4.1.12"
   },
   "keywords": [
     "firecrawl",
@@ -63,7 +63,7 @@
     "bioinformatics"
   ],
   "engines": {
-    "node": ">=22.0.0"
+    "node": ">=18.0.0"
   },
   "scripts": {
     "build": "tsup",

package/pnpm-workspace.yaml

@@ -14,6 +14,8 @@ overrides:
   # GHSA-m8m8-qj5v-23w3 / GHSA-44g4-m2mj-wpvx / GHSA-r4gj-5m52-g5wh:
   # pin the 1.x line only. Exact 1.20.0 cannot resolve to 2.x.
   "axios@>=1.0.0 <1.20.0": "1.20.0"
-  "follow-redirects@<1.16.0": ">=1.16.0 <2.0.0"
+  # GHSA-Q3JH-WRC6-JGQ8 / GHSA-8R9P-F939-6H3C: fixed in 1.16.1.
+  # Replacement is bounded <2.0.0; cannot resolve to follow-redirects 2.x.
+  "follow-redirects@<1.16.1": ">=1.16.1 <2.0.0"
   "form-data@>=4.0.0 <4.0.6": "4.0.6"
   "esbuild@>=0.17.0 <0.28.1": "0.28.1"

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

@@ -0,0 +1,34 @@
+import { describe, test, expect, vi } from "vitest";
+import { startAgent } from "../../../v2/methods/agent";
+
+describe("JS SDK v2 agent location", () => {
+  const post = () =>
+    vi.fn(async () => ({
+      status: 200,
+      data: { success: true, id: "agent-1" },
+    }));
+
+  test("sends location when starting an agent", async () => {
+    const http = { post: post() };
+
+    await startAgent(http as any, {
+      prompt: "Find the pricing page",
+      location: { country: "DE" },
+    });
+
+    expect(http.post).toHaveBeenCalledWith("/v2/agent", {
+      prompt: "Find the pricing page",
+      location: { country: "DE" },
+    });
+  });
+
+  test("omits location by default", async () => {
+    const http = { post: post() };
+
+    await startAgent(http as any, { prompt: "Find the pricing page" });
+
+    expect(http.post).toHaveBeenCalledWith("/v2/agent", {
+      prompt: "Find the pricing page",
+    });
+  });
+});

package/src/v1/index.ts

@@ -686,7 +686,7 @@ export default class FirecrawlApp {
       return packageJson.default.version;
     } catch (error) {
       // Suppress noisy logs under test environments
-      const isTest = typeof process !== 'undefined' && process.env.NODE_ENV === 'test';
+      const isTest = typeof process !== 'undefined' && !!process.env && process.env.NODE_ENV === 'test';
       if (!isTest) {
         // eslint-disable-next-line no-console
         console.error("Error getting version:", error);
@@ -2220,6 +2220,9 @@ export class CrawlWatcher extends TypedEventTarget<CrawlWatcherEvents> {
     this.id = id;
     // replace `http` with `ws` (`http://` -> `ws://` and `https://` -> `wss://`)
     const wsUrl = app.apiUrl.replace(/^http/, "ws");
+    if (typeof WebSocket === "undefined") {
+      throw new Error("Watching a crawl needs a global WebSocket (Node 22+, Bun, Deno or a browser). On older Node, use the v2 client's watcher(), which polls instead.");
+    }
     this.ws = new WebSocket(`${wsUrl}/v1/crawl/${id}`, app.apiKey);
     this.status = "scraping";
     this.data = [];

package/src/v2/client.ts

@@ -164,8 +164,9 @@ export class FirecrawlClient {
     const opts: FirecrawlClientOptions =
       typeof options === "string" ? { apiKey: options } : options;
 
-    const apiKey = (opts.apiKey ?? process.env.FIRECRAWL_API_KEY ?? "").trim();
-    const apiUrl = (opts.apiUrl ?? process.env.FIRECRAWL_API_URL ?? "https://api.firecrawl.dev").replace(/\/$/, "");
+    const hasEnv = typeof process !== "undefined" && !!process.env;
+    const apiKey = (opts.apiKey ?? (hasEnv ? process.env.FIRECRAWL_API_KEY : undefined) ?? "").trim();
+    const apiUrl = (opts.apiUrl ?? (hasEnv ? process.env.FIRECRAWL_API_URL : undefined) ?? "https://api.firecrawl.dev").replace(/\/$/, "");
 
     // No API key is allowed: scrape, search, and interact fall back to the
     // keyless free tier (rate-limited per IP). Other methods will return 401

package/src/v2/methods/agent.ts

@@ -21,6 +21,12 @@ function prepareAgentPayload(args: {
   threadId?: string;
   mode?: AgentMode;
   exchange?: AgentExchangeOptions;
+  /**
+   * Country for the whole run (ISO 3166-1 alpha-2). Scrapes and browser sessions are proxied from it,
+   * and search results are localized to it without changing where requests come from. The agent cannot change it.
+   */
+  location?: { country: string };
+  zeroDataRetention?: boolean;
 }): Record<string, unknown> {
   const body: Record<string, unknown> = {};
   if (args.urls) body.urls = args.urls;
@@ -42,6 +48,8 @@ function prepareAgentPayload(args: {
   if (args.threadId != null) body.threadId = args.threadId;
   if (args.mode != null) body.mode = args.mode;
   if (args.exchange != null) body.exchange = args.exchange;
+  if (args.location != null) body.location = args.location;
+  if (args.zeroDataRetention != null) body.zeroDataRetention = args.zeroDataRetention;
   return body;
 }
 

package/src/v2/types.ts

@@ -300,7 +300,12 @@ export interface ScrapeOptions {
 }
 
 export type RedactPIIEntity =
-  "PERSON" | "EMAIL" | "PHONE" | "LOCATION" | "FINANCIAL" | "SECRET";
+  | "PERSON"
+  | "EMAIL"
+  | "PHONE"
+  | "LOCATION"
+  | "FINANCIAL"
+  | "SECRET";
 
 export interface RedactPIIOptions {
   /**
@@ -347,7 +352,12 @@ export interface ThreatProtectionOptions {
 }
 
 export type ParseFileData =
-  Blob | File | Buffer | Uint8Array | ArrayBuffer | string;
+  | Blob
+  | File
+  | Buffer
+  | Uint8Array
+  | ArrayBuffer
+  | string;
 
 export interface ParseFile {
   data: ParseFileData;
@@ -395,7 +405,11 @@ export interface WebhookConfig {
 
 // Agent webhook events differ from crawl: has 'action' and 'cancelled', no 'page'
 export type AgentWebhookEvent =
-  "started" | "action" | "completed" | "failed" | "cancelled";
+  | "started"
+  | "action"
+  | "completed"
+  | "failed"
+  | "cancelled";
 
 export interface AgentWebhookConfig {
   url: string;
@@ -516,7 +530,10 @@ export interface BrandingProfile {
     headerHeight?: string;
     footerHeight?: string;
     [key: string]:
-      number | string | Record<string, number | string | undefined> | undefined;
+      | number
+      | string
+      | Record<string, number | string | undefined>
+      | undefined;
   };
   tone?: {
     voice?: string;
@@ -1014,7 +1031,10 @@ export interface SearchRequest {
   /** Compact by default; summary adds metadata, full includes contracts. */
   toolDetail?: "compact" | "summary" | "full";
   sources?: Array<
-    "web" | "news" | "images" | "alexandria"
+    | "web"
+    | "news"
+    | "images"
+    | "alexandria"
     | { type: "web" | "news" | "images" | "alexandria" }
   >;
   /**
@@ -1265,7 +1285,9 @@ export interface MonitorSearchTarget {
 }
 
 export type MonitorTarget =
-  MonitorScrapeTarget | MonitorCrawlTarget | MonitorSearchTarget;
+  | MonitorScrapeTarget
+  | MonitorCrawlTarget
+  | MonitorSearchTarget;
 
 export interface CreateMonitorRequest {
   name: string;
@@ -1388,7 +1410,11 @@ export interface MonitorCheck {
   reservedCredits?: number | null;
   actualCredits?: number | null;
   billingStatus:
-    "not_applicable" | "reserved" | "confirmed" | "released" | "failed";
+    | "not_applicable"
+    | "reserved"
+    | "confirmed"
+    | "released"
+    | "failed";
   summary: MonitorSummary;
   targetResults?: MonitorTargetResult[];
   notificationStatus?: unknown;
@@ -1779,7 +1805,10 @@ export interface AgentListOptions {
 }
 
 export type AgentTraceAgentRole =
-  "orchestrator" | "subagent" | "browser" | "system";
+  | "orchestrator"
+  | "subagent"
+  | "browser"
+  | "system";
 
 export interface AgentTraceAgentIdentity {
   id: string;
@@ -1792,6 +1821,7 @@ export interface AgentTraceError {
   code:
     | "cancelled"
     | "credit_limit_reached"
+    | "insufficient_credits"
     | "parent_finished"
     | "refused"
     | "internal";
@@ -1833,7 +1863,11 @@ export interface AgentTraceRunCancelRequestedEvent extends AgentTraceEventBase {
 export interface AgentTraceRunFinishedEvent extends AgentTraceEventBase {
   type: "run.finished";
   outcome:
-    "succeeded" | "failed" | "cancelled" | "refused" | "credit_limit_reached";
+    | "succeeded"
+    | "failed"
+    | "cancelled"
+    | "refused"
+    | "credit_limit_reached";
   /** The canonical schema always writes this key (nullable), but older rows may omit it. */
   error?: AgentTraceError | null;
 }
@@ -1850,12 +1884,14 @@ export interface AgentTraceAgentFinishedEvent extends AgentTraceEventBase {
   error?: AgentTraceError | null;
 }
 
-export interface AgentTraceBrowserSessionStartedEvent extends AgentTraceEventBase {
+export interface AgentTraceBrowserSessionStartedEvent
+  extends AgentTraceEventBase {
   type: "browser.session.started";
   sessionId: string;
 }
 
-export interface AgentTraceBrowserSessionFinishedEvent extends AgentTraceEventBase {
+export interface AgentTraceBrowserSessionFinishedEvent
+  extends AgentTraceEventBase {
   type: "browser.session.finished";
   sessionId: string;
   durationMs: number;
@@ -1929,6 +1965,8 @@ export interface AgentTraceResponse {
   creditsUsed?: number;
   /** Present only when the trace was requested with liveView: true. */
   activeBrowserSessions?: AgentTraceActiveBrowserSession[];
+  /** True for a zero data retention run: events are limited to content-free lifecycle events. */
+  zeroDataRetention?: boolean;
   error?: string;
 }
 
@@ -2028,7 +2066,9 @@ export interface RequiresAction {
   url?: string;
 }
 
-export function parseRequiresAction(value: unknown): RequiresAction | undefined {
+export function parseRequiresAction(
+  value: unknown,
+): RequiresAction | undefined {
   if (!value || typeof value !== "object") return undefined;
   const record = value as Record<string, unknown>;
   if (typeof record.type !== "string") return undefined;

package/src/v2/utils/httpClient.ts

@@ -6,6 +6,18 @@ import axios, {
 import { getVersion } from "./getVersion";
 import { pinToApiOrigin } from "../../utils/apiOrigin";
 
+// Runtimes such as Cloudflare Workers reject the Request `cache: "default"` that
+// axios's fetch adapter always sets; there axios calls fetch(url, init) without it.
+const rejectsDefaultCacheMode = (): boolean => {
+  if (typeof Request !== "function") return false;
+  try {
+    new Request("https://api.firecrawl.dev", { cache: "default" });
+    return false;
+  } catch {
+    return true;
+  }
+};
+
 export interface HttpClientOptions {
   apiKey: string;
   apiUrl: string;
@@ -44,6 +56,7 @@ export class HttpClient {
         ...(this.apiKey ? { Authorization: `Bearer ${this.apiKey}` } : {}),
       },
       transitional: { clarifyTimeoutError: true },
+      ...(rejectsDefaultCacheMode() ? { adapter: "fetch", env: { Request: null as any } } : {}),
     });
   }
 

package/src/v2/watcher.ts

@@ -1,48 +1,110 @@
-import { EventEmitter } from "events";
 import type { BatchScrapeJob, CrawlJob, Document } from "./types";
 import type { HttpClient } from "./utils/httpClient";
 import { getBatchScrapeStatus } from "./methods/batch";
 import { getCrawlStatus } from "./methods/crawl";
-// Note: browsers/Deno expose globalThis.WebSocket, but many Node runtimes (<22.4 or without
-// experimental flags) do not. We lazily fall back to node:undici.
 
 type WebSocketConstructor = new (url: string, protocols?: string | string[]) => WebSocket;
 
-const hasGlobalWebSocket = (): WebSocketConstructor | undefined => {
-  if (typeof globalThis === "undefined") return undefined;
+// Runtimes without a global WebSocket (Node before 22) poll instead.
+const getWebSocketCtor = (): WebSocketConstructor | undefined => {
   const candidate = (globalThis as any).WebSocket;
   return typeof candidate === "function" ? (candidate as WebSocketConstructor) : undefined;
 };
 
-const isNodeRuntime = () => typeof process !== "undefined" && !!process.versions?.node;
+type Listener = ((...args: any[]) => void) & { listener?: Listener };
 
-let cachedWebSocket: WebSocketConstructor | undefined;
-let loadPromise: Promise<WebSocketConstructor | undefined> | undefined;
+/** Node's EventEmitter API for the watcher, with no import of "events", so browser bundles load it. */
+class Emitter {
+  private readonly listenersByEvent = new Map<string | symbol, Listener[]>();
+  private maxListeners = 10;
 
-const loadNodeWebSocket = async (): Promise<WebSocketConstructor | undefined> => {
-  if (!isNodeRuntime()) return undefined;
-  try {
-    const undici = await import("node:undici");
-    const ctor = (undici as any).WebSocket ?? (undici as any).default?.WebSocket;
-    return typeof ctor === "function" ? (ctor as WebSocketConstructor) : undefined;
-  } catch {
-    return undefined;
+  on(event: string | symbol, listener: Listener): this {
+    this.listenersByEvent.set(event, [...(this.listenersByEvent.get(event) ?? []), listener]);
+    return this;
   }
-};
 
-const getWebSocketCtor = async (): Promise<WebSocketConstructor | undefined> => {
-  if (cachedWebSocket) return cachedWebSocket;
-  const globalWs = hasGlobalWebSocket();
-  if (globalWs) {
-    cachedWebSocket = globalWs;
-    return cachedWebSocket;
+  prependListener(event: string | symbol, listener: Listener): this {
+    this.listenersByEvent.set(event, [listener, ...(this.listenersByEvent.get(event) ?? [])]);
+    return this;
   }
-  if (!loadPromise) {
-    loadPromise = loadNodeWebSocket();
+
+  prependOnceListener(event: string | symbol, listener: Listener): this {
+    return this.prependListener(event, this.onceWrapper(event, listener));
   }
-  cachedWebSocket = await loadPromise;
-  return cachedWebSocket;
-};
+
+  listeners(event: string | symbol): Listener[] {
+    return (this.listenersByEvent.get(event) ?? []).map((entry) => entry.listener ?? entry);
+  }
+
+  rawListeners(event: string | symbol): Listener[] {
+    return [...(this.listenersByEvent.get(event) ?? [])];
+  }
+
+  eventNames(): (string | symbol)[] {
+    return [...this.listenersByEvent.keys()].filter((event) => this.listenerCount(event) > 0);
+  }
+
+  setMaxListeners(n: number): this {
+    this.maxListeners = n;
+    return this;
+  }
+
+  getMaxListeners(): number {
+    return this.maxListeners;
+  }
+
+  addListener(event: string | symbol, listener: Listener): this {
+    return this.on(event, listener);
+  }
+
+  once(event: string | symbol, listener: Listener): this {
+    return this.on(event, this.onceWrapper(event, listener));
+  }
+
+  private onceWrapper(event: string | symbol, listener: Listener): Listener {
+    const wrapped: Listener = (...args) => {
+      this.off(event, wrapped);
+      listener.apply(this, args);
+    };
+    wrapped.listener = listener;
+    return wrapped;
+  }
+
+  off(event: string | symbol, listener: Listener): this {
+    const current = this.listenersByEvent.get(event);
+    if (!current) return this;
+    for (let index = current.length - 1; index >= 0; index--) {
+      if (current[index] !== listener && current[index]!.listener !== listener) continue;
+      this.listenersByEvent.set(event, current.filter((_, i) => i !== index));
+      break;
+    }
+    return this;
+  }
+
+  removeListener(event: string | symbol, listener: Listener): this {
+    return this.off(event, listener);
+  }
+
+  removeAllListeners(event?: string | symbol): this {
+    if (event === undefined) this.listenersByEvent.clear();
+    else this.listenersByEvent.delete(event);
+    return this;
+  }
+
+  listenerCount(event: string | symbol): number {
+    return this.listenersByEvent.get(event)?.length ?? 0;
+  }
+
+  emit(event: string | symbol, ...args: any[]): boolean {
+    const current = this.listenersByEvent.get(event);
+    if (!current?.length) {
+      if (event === "error") throw args[0] instanceof Error ? args[0] : new Error(String(args[0]));
+      return false;
+    }
+    for (const listener of [...current]) listener.apply(this, args);
+    return true;
+  }
+}
 
 const decoder = typeof TextDecoder !== "undefined" ? new TextDecoder() : undefined;
 
@@ -81,7 +143,7 @@ export interface WatcherOptions {
 
 type Snapshot = CrawlJob | BatchScrapeJob;
 
-export class Watcher extends EventEmitter {
+export class Watcher extends Emitter {
   private readonly http: HttpClient;
   private readonly jobId: string;
   private readonly kind: JobKind;
@@ -122,7 +184,7 @@ export class Watcher extends EventEmitter {
       (async () => {
         try {
           const url = this.buildWsUrl();
-          const wsCtor = await getWebSocketCtor();
+          const wsCtor = getWebSocketCtor();
           if (!wsCtor) {
             this.pollLoop();
             return;

package/src/types/node-undici.d.ts

@@ -1,10 +0,0 @@
-type WebSocketCtor = typeof globalThis.WebSocket;
-
-declare module "node:undici" {
-  export const WebSocket: WebSocketCtor;
-  const _default: {
-    WebSocket: WebSocketCtor;
-  };
-  export default _default;
-}
-