@mendable/firecrawl-js 4.46.0 → 4.48.0

package/dist/package-WONXBIJS.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-GD463K4D.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": "@mendable/firecrawl-js",
-  "version": "4.46.0",
+  "version": "4.48.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/agent-hints.test.ts

@@ -14,6 +14,7 @@ const hints = [
 ];
 function httpFor(body: object) {
   return {
+    getOrigin: () => "js-sdk@test",
     post: vi.fn<any>().mockResolvedValue({ status: 200, data: body }),
     postMultipart: vi
       .fn<any>()

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/origin.test.ts

@@ -0,0 +1,132 @@
+import { afterEach, beforeEach, describe, test, expect } from "vitest";
+import type { AxiosAdapter } from "axios";
+import { FirecrawlClient } from "../../../v2/client";
+import { Firecrawl } from "../../../index";
+import { getVersion } from "../../../v2/utils/getVersion";
+import { detectCallerPackage } from "../../../utils/callerOrigin";
+
+function withCapture<T extends { http: any }>(client: T) {
+  const bodies: Array<Record<string, unknown>> = [];
+  const adapter: AxiosAdapter = async config => {
+    bodies.push(JSON.parse(config.data));
+    return {
+      data: { success: true, data: { markdown: "# hello" } },
+      status: 200,
+      statusText: "OK",
+      headers: {},
+      config,
+    };
+  };
+  client.http.instance.defaults.adapter = adapter;
+  return { client, bodies };
+}
+
+describe("v2 request origin", () => {
+  const previousOptOut = process.env.FIRECRAWL_DISABLE_CALLER_ORIGIN;
+  afterEach(() => {
+    if (previousOptOut === undefined) {
+      delete process.env.FIRECRAWL_DISABLE_CALLER_ORIGIN;
+    } else {
+      process.env.FIRECRAWL_DISABLE_CALLER_ORIGIN = previousOptOut;
+    }
+  });
+
+  test("defaults to the plain SDK origin when application code creates the client", async () => {
+    const { client, bodies } = withCapture(new FirecrawlClient({ apiKey: "fc-test" }));
+    await client.scrape("https://example.com");
+    expect(bodies[0]!.origin).toBe(`js-sdk@${getVersion()}`);
+  });
+
+  test("the origin client option is stamped into request bodies", async () => {
+    const { client, bodies } = withCapture(
+      new FirecrawlClient({ apiKey: "fc-test", origin: "js-sdk.example@1.0.0" }),
+    );
+    await client.scrape("https://example.com");
+    expect(bodies[0]!.origin).toBe("js-sdk.example@1.0.0");
+  });
+
+  test("a per-call origin wins over the client origin", async () => {
+    const { client, bodies } = withCapture(
+      new FirecrawlClient({ apiKey: "fc-test", origin: "js-sdk.example@1.0.0" }),
+    );
+    await client.scrape("https://example.com", { origin: "per-call" } as any);
+    await client.scrape("https://example.com", { origin: "mcp-server" } as any);
+    expect(bodies.map(b => b.origin)).toEqual(["per-call", "mcp-server"]);
+  });
+
+  test("the unified client forwards the origin option to v1", () => {
+    const app = new Firecrawl({ apiKey: "fc-test", origin: "js-sdk.example@1.0.0" });
+    expect((app.v1 as any).clientOrigin).toBe("js-sdk.example@1.0.0");
+  });
+
+});
+
+describe("detectCallerPackage", () => {
+  const sdkFrames = [
+    "Error",
+    "    at detectCallerPackage (file:///srv/app/node_modules/@mendable/firecrawl-js/dist/index.js:10:5)",
+    "    at new FirecrawlClient (file:///srv/app/node_modules/@mendable/firecrawl-js/dist/index.js:20:9)",
+  ];
+  const stackFrom = (...callers: string[]) =>
+    [...sdkFrames, ...callers.map(c => `    at ${c}`)].join("\n");
+  const previousOptOut = process.env.FIRECRAWL_DISABLE_CALLER_ORIGIN;
+
+  beforeEach(() => {
+    delete process.env.FIRECRAWL_DISABLE_CALLER_ORIGIN;
+  });
+
+  afterEach(() => {
+    if (previousOptOut === undefined) {
+      delete process.env.FIRECRAWL_DISABLE_CALLER_ORIGIN;
+    } else {
+      process.env.FIRECRAWL_DISABLE_CALLER_ORIGIN = previousOptOut;
+    }
+  });
+
+  test("names the scoped package that created the client", () => {
+    const stack = stackFrom(
+      "make (file:///srv/app/node_modules/@Scope/Some_Agent/dist/index.js:3:12)",
+      "main (file:///srv/app/src/main.js:1:1)",
+    );
+    expect(detectCallerPackage(stack)).toBe("scope-some-agent");
+  });
+
+  test("uses the last node_modules segment of a nested install", () => {
+    const stack = stackFrom(
+      "make (/srv/app/node_modules/.pnpm/outer@1.0.0/node_modules/inner-pkg/lib/index.cjs:3:12)",
+    );
+    expect(detectCallerPackage(stack)).toBe("inner-pkg");
+  });
+
+  test("handles windows paths with parentheses and anonymous frames", () => {
+    const stack = stackFrom(
+      "Array.map (<anonymous>)",
+      "C:\\Program Files (x86)\\app\\node_modules\\wrapper\\index.js:4:2",
+    );
+    expect(detectCallerPackage(stack)).toBe("wrapper");
+  });
+
+  test("returns null when application code created the client", () => {
+    const stack = stackFrom(
+      "main (file:///srv/app/src/main.js:1:1)",
+      "make (file:///srv/app/node_modules/wrapper/index.js:3:12)",
+    );
+    expect(detectCallerPackage(stack)).toBeNull();
+  });
+
+  test("returns null for a package whose slug would read as another traffic class", () => {
+    const stack = stackFrom("make (/srv/app/node_modules/my-playground-kit/index.js:3:12)");
+    expect(detectCallerPackage(stack)).toBeNull();
+  });
+
+  test("returns null for a bundle without node_modules in its path", () => {
+    expect(detectCallerPackage(stackFrom("make (/srv/app/dist/bundle.js:1:1)"))).toBeNull();
+  });
+
+  test("FIRECRAWL_DISABLE_CALLER_ORIGIN turns detection off", () => {
+    const stack = stackFrom("make (/srv/app/node_modules/wrapper/index.js:3:12)");
+    expect(detectCallerPackage(stack)).toBe("wrapper");
+    process.env.FIRECRAWL_DISABLE_CALLER_ORIGIN = "1";
+    expect(detectCallerPackage(stack)).toBeNull();
+  });
+});

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/research.test.ts

@@ -12,6 +12,7 @@ function makeClient(
 ) {
   const calls: string[] = [];
   const http = {
+    getOrigin: () => "js-sdk@test",
     get: async (url: string) => {
       calls.push(url);
       return responder(url);

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/index.ts

@@ -37,6 +37,7 @@ export class Firecrawl extends V2 {
     this._v1Opts = {
       apiKey: resolved.apiKey,
       apiUrl: resolved.apiUrl,
+      origin: this.http.getOrigin(),
     };
   }
 

package/src/utils/callerOrigin.ts

@@ -0,0 +1,74 @@
+const NODE_MODULES = "/node_modules/";
+
+function packageOf(file: string): string | null {
+  let path = file.replace(/^file:\/\//, "").replace(/\\/g, "/");
+  try {
+    path = decodeURIComponent(path);
+  } catch {}
+  const at = path.lastIndexOf(NODE_MODULES);
+  if (at < 0) return null;
+  const [first, second] = path.slice(at + NODE_MODULES.length).split("/");
+  const name = first?.startsWith("@") ? (second ? `${first}/${second}` : "") : first;
+  return name && !name.startsWith(".") ? name : null;
+}
+
+/** File of a V8 stack line, or null for frames without one (native, anonymous, runtime internals). */
+function frameFile(line: string): string | null {
+  const text = line.trim().replace(/^at /, "");
+  const open = text.indexOf(" (");
+  const location = open >= 0 && text.endsWith(")") ? text.slice(open + 2, -1) : text;
+  const match = /^(.*):\d+:\d+$/.exec(location);
+  return match && !match[1]!.startsWith("node:") ? match[1]! : null;
+}
+
+// Downstream surface classification matches "playground" anywhere in an origin.
+function slugify(name: string): string {
+  return name
+    .toLowerCase()
+    .replace(/[^a-z0-9]+/g, "-")
+    .replace(/^-+|-+$/g, "")
+    .slice(0, 48)
+    .replace(/-+$/, "");
+}
+
+/**
+ * Slug of the installed package that created the client, or null when the
+ * caller is application code or detection is disabled. Never throws.
+ */
+export function detectCallerPackage(stack?: string): string | null {
+  try {
+    if (process.env.FIRECRAWL_DISABLE_CALLER_ORIGIN === "1") return null;
+    if (stack === undefined) {
+      const limit = Error.stackTraceLimit;
+      Error.stackTraceLimit = 50;
+      try {
+        stack = new Error().stack ?? "";
+      } finally {
+        Error.stackTraceLimit = limit;
+      }
+    }
+    let ownFile: string | null = null;
+    let ownPackage: string | null = null;
+    for (const line of stack.split("\n")) {
+      if (!/^\s*at /.test(line)) continue;
+      const file = frameFile(line);
+      if (!file) continue;
+      if (ownFile === null) {
+        ownFile = file;
+        ownPackage = packageOf(file);
+      }
+      if (file === ownFile) continue;
+      const name = packageOf(file);
+      if (name && name === ownPackage) continue;
+      const slug = name ? slugify(name) : "";
+      return slug && !slug.includes("playground") ? slug : null;
+    }
+  } catch {}
+  return null;
+}
+
+/** Origin sent with requests: `js-sdk@<version>`, or `js-sdk.<package>@<version>` for wrapper libraries. */
+export function defaultOrigin(version: string): string {
+  const caller = detectCallerPackage();
+  return caller ? `js-sdk.${caller}@${version}` : `js-sdk@${version}`;
+}

package/src/v1/index.ts

@@ -4,15 +4,18 @@ import { zodSchemaToJsonSchema } from "../utils/zodSchemaToJson";
 import { TypedEventTarget } from "typescript-event-target";
 import type { RequiresAction } from "../v2/types";
 import { pinToApiOrigin } from "../utils/apiOrigin";
+import { detectCallerPackage } from "../utils/callerOrigin";
 
 /**
  * Configuration interface for FirecrawlApp.
  * @param apiKey - Optional API key for authentication.
  * @param apiUrl - Optional base URL of the API; defaults to 'https://api.firecrawl.dev'.
+ * @param origin - Optional attribution tag stamped into request bodies.
  */
 export interface FirecrawlAppConfig {
   apiKey?: string | null;
   apiUrl?: string | null;
+  origin?: string;
 }
 
 /**
@@ -666,6 +669,8 @@ export default class FirecrawlApp {
   public apiKey: string;
   public apiUrl: string;
   public version: string =  "1.25.1";
+  private readonly clientOrigin?: string;
+  private readonly callerPackage: string | null;
   
   private isCloudService(url: string): boolean {
     return url.includes('api.firecrawl.dev');
@@ -698,7 +703,7 @@ export default class FirecrawlApp {
    * Initializes a new instance of the FirecrawlApp class.
    * @param config - Configuration options for the FirecrawlApp instance.
    */
-  constructor({ apiKey = null, apiUrl = null }: FirecrawlAppConfig) {
+  constructor({ apiKey = null, apiUrl = null, origin }: FirecrawlAppConfig) {
     const baseUrl = apiUrl || "https://api.firecrawl.dev";
     
     if (this.isCloudService(baseUrl) && typeof apiKey !== "string") {
@@ -707,9 +712,19 @@ export default class FirecrawlApp {
 
     this.apiKey = apiKey || '';
     this.apiUrl = baseUrl;
+    this.clientOrigin = origin || undefined;
+    this.callerPackage = this.clientOrigin ? null : detectCallerPackage();
     this.init();
   }
 
+  private resolveOrigin(params?: any): string {
+    if (typeof params?.origin === "string" && params.origin) return params.origin;
+    if (this.clientOrigin) return this.clientOrigin;
+    return this.callerPackage
+      ? `js-sdk.${this.callerPackage}@${this.version}`
+      : `js-sdk@${this.version}`;
+  }
+
   /**
    * Scrapes a URL using the Firecrawl API.
    * @param url - The URL to scrape.
@@ -724,7 +739,7 @@ export default class FirecrawlApp {
       "Content-Type": "application/json",
       Authorization: `Bearer ${this.apiKey}`,
     } as AxiosRequestHeaders;
-    let jsonData: any = { url, ...params, origin: typeof (params as any)?.origin === "string" && (params as any).origin.includes("mcp") ? (params as any).origin : `js-sdk@${this.version}` };
+    let jsonData: any = { url, ...params, origin: this.resolveOrigin(params) };
     if (jsonData?.extract?.schema) {
       jsonData = {
         ...jsonData,
@@ -791,7 +806,7 @@ export default class FirecrawlApp {
       lang: params?.lang ?? "en",
       country: params?.country ?? "us",
       location: params?.location,
-      origin: typeof (params as any)?.origin === "string" && (params as any).origin.includes("mcp") ? (params as any).origin : `js-sdk@${this.version}`,
+      origin: this.resolveOrigin(params),
       timeout: params?.timeout ?? 60000,
       scrapeOptions: params?.scrapeOptions ?? { formats: [] },
     };
@@ -855,7 +870,7 @@ export default class FirecrawlApp {
     idempotencyKey?: string
   ): Promise<CrawlStatusResponse | ErrorResponse> {
     const headers = this.prepareHeaders(idempotencyKey);
-    let jsonData: any = { url, ...params, origin: typeof (params as any)?.origin === "string" && (params as any).origin.includes("mcp") ? (params as any).origin : `js-sdk@${this.version}` };
+    let jsonData: any = { url, ...params, origin: this.resolveOrigin(params) };
     try {
       const response: AxiosResponse = await this.postRequest(
         this.apiUrl + `/v1/crawl`,
@@ -884,7 +899,7 @@ export default class FirecrawlApp {
     idempotencyKey?: string
   ): Promise<CrawlResponse | ErrorResponse> {
     const headers = this.prepareHeaders(idempotencyKey);
-    let jsonData: any = { url, ...params, origin: typeof (params as any)?.origin === "string" && (params as any).origin.includes("mcp") ? (params as any).origin : `js-sdk@${this.version}` };
+    let jsonData: any = { url, ...params, origin: this.resolveOrigin(params) };
     try {
       const response: AxiosResponse = await this.postRequest(
         this.apiUrl + `/v1/crawl`,
@@ -1060,7 +1075,7 @@ export default class FirecrawlApp {
    */
   async mapUrl(url: string, params?: MapParams): Promise<MapResponse | ErrorResponse> {
     const headers = this.prepareHeaders();
-    let jsonData: any = { url, ...params, origin: typeof (params as any)?.origin === "string" && (params as any).origin.includes("mcp") ? (params as any).origin : `js-sdk@${this.version}` };
+    let jsonData: any = { url, ...params, origin: this.resolveOrigin(params) };
 
     try {
       const response: AxiosResponse = await this.postRequest(
@@ -1099,7 +1114,7 @@ export default class FirecrawlApp {
     maxConcurrency?: number,
   ): Promise<BatchScrapeStatusResponse | ErrorResponse> {
     const headers = this.prepareHeaders(idempotencyKey);
-    let jsonData: any = { urls, webhook, ignoreInvalidURLs, maxConcurrency, ...params, origin: typeof (params as any)?.origin === "string" && (params as any).origin.includes("mcp") ? (params as any).origin : `js-sdk@${this.version}` };
+    let jsonData: any = { urls, webhook, ignoreInvalidURLs, maxConcurrency, ...params, origin: this.resolveOrigin(params) };
     if (jsonData?.extract?.schema) {
       jsonData = {
         ...jsonData,
@@ -1148,7 +1163,7 @@ export default class FirecrawlApp {
     ignoreInvalidURLs?: boolean,
   ): Promise<BatchScrapeResponse | ErrorResponse> {
     const headers = this.prepareHeaders(idempotencyKey);
-    let jsonData: any = { urls, webhook, ignoreInvalidURLs, ...params, origin: typeof (params as any)?.origin === "string" && (params as any).origin.includes("mcp") ? (params as any).origin : `js-sdk@${this.version}` };
+    let jsonData: any = { urls, webhook, ignoreInvalidURLs, ...params, origin: this.resolveOrigin(params) };
     try {
       const response: AxiosResponse = await this.postRequest(
         this.apiUrl + `/v1/batch/scrape`,
@@ -1312,7 +1327,7 @@ export default class FirecrawlApp {
     try {
       const response: AxiosResponse = await this.postRequest(
         this.apiUrl + `/v1/extract`,
-        { ...jsonData, schema: jsonSchema, origin: typeof (params as any)?.origin === "string" && (params as any).origin.includes("mcp") ? (params as any).origin : `js-sdk@${this.version}` },
+        { ...jsonData, schema: jsonSchema, origin: this.resolveOrigin(params) },
         headers
       );
 
@@ -1372,7 +1387,7 @@ export default class FirecrawlApp {
     try {
       const response: AxiosResponse = await this.postRequest(
         this.apiUrl + `/v1/extract`,
-        { ...jsonData, schema: jsonSchema, origin: typeof (params as any)?.origin === "string" && (params as any).origin.includes("mcp") ? (params as any).origin : `js-sdk@${this.version}` },
+        { ...jsonData, schema: jsonSchema, origin: this.resolveOrigin(params) },
         headers
       );
 
@@ -1740,7 +1755,7 @@ export default class FirecrawlApp {
    */
   async asyncDeepResearch(query: string, params: DeepResearchParams<zt.ZodSchema>): Promise<DeepResearchResponse | ErrorResponse> {
     const headers = this.prepareHeaders();
-    let jsonData: any = { query, ...params, origin: typeof (params as any)?.origin === "string" && (params as any).origin.includes("mcp") ? (params as any).origin : `js-sdk@${this.version}` };
+    let jsonData: any = { query, ...params, origin: this.resolveOrigin(params) };
 
     if (jsonData?.jsonOptions?.schema) {
       jsonData = {
@@ -1888,7 +1903,7 @@ export default class FirecrawlApp {
   async __asyncDeepResearch(topic: string, params: DeepResearchParams): Promise<DeepResearchResponse | ErrorResponse> {
     const headers = this.prepareHeaders();
     try {
-      let jsonData: any = { topic, ...params, origin: typeof (params as any)?.origin === "string" && (params as any).origin.includes("mcp") ? (params as any).origin : `js-sdk@${this.version}` };
+      let jsonData: any = { topic, ...params, origin: this.resolveOrigin(params) };
       const response: AxiosResponse = await this.postRequest(
         `${this.apiUrl}/v1/deep-research`,
         jsonData,
@@ -2003,7 +2018,7 @@ export default class FirecrawlApp {
    */
   async asyncGenerateLLMsText(url: string, params?: GenerateLLMsTextParams): Promise<GenerateLLMsTextResponse | ErrorResponse> {
     const headers = this.prepareHeaders();
-    let jsonData: any = { url, ...params, origin: typeof (params as any)?.origin === "string" && (params as any).origin.includes("mcp") ? (params as any).origin : `js-sdk@${this.version}` };
+    let jsonData: any = { url, ...params, origin: this.resolveOrigin(params) };
     try {
       const response: AxiosResponse = await this.postRequest(
         `${this.apiUrl}/v1/llmstxt`,

package/src/v2/client.ts

@@ -101,6 +101,8 @@ import type {
   GetMonitorCheckOptions,
   UpdateMonitorRequest,
 } from "./types";
+import { defaultOrigin } from "../utils/callerOrigin";
+import { getVersion } from "./utils/getVersion";
 import { Watcher } from "./watcher";
 import type { WatcherOptions } from "./watcher";
 import * as zt from "zod";
@@ -130,6 +132,12 @@ export interface FirecrawlClientOptions {
   maxRetries?: number;
   /** Exponential backoff factor for retries (optional). */
   backoffFactor?: number;
+  /**
+   * Attribution tag stamped into request bodies. Defaults to `js-sdk@<version>`,
+   * or `js-sdk.<package>@<version>` when an installed package creates the client
+   * (set FIRECRAWL_DISABLE_CALLER_ORIGIN=1 to keep the plain default).
+   */
+  origin?: string;
 }
 
 /** Accepts a plain API key string or a full options object. */
@@ -140,7 +148,7 @@ export type FirecrawlClientInput = FirecrawlClientOptions | string;
  */
 
 export class FirecrawlClient {
-  private readonly http: HttpClient;
+  protected readonly http: HttpClient;
   private _research?: ResearchClient;
 
   private isCloudService(url: string): boolean {
@@ -168,6 +176,7 @@ export class FirecrawlClient {
       timeoutMs: opts.timeoutMs,
       maxRetries: opts.maxRetries,
       backoffFactor: opts.backoffFactor,
+      origin: opts.origin || defaultOrigin(getVersion()),
     });
   }
 
@@ -644,7 +653,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;