firecrawl 4.47.0 → 4.49.0

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

@@ -1,4 +1,5 @@
-import { describe, expect, it, vi } from "vitest";
+import { afterEach, describe, expect, it, vi } from "vitest";
+import type { AxiosAdapter } from "axios";
 import { FirecrawlClient } from "../../../v2/client";
 
 const ALIAS_MAP: Record<string, string> = {
@@ -20,14 +21,98 @@ describe("V1 deprecated aliases", () => {
     apiUrl: "http://localhost:9",
   });
 
+  afterEach(() => {
+    vi.restoreAllMocks();
+  });
+
   for (const [alias, target] of Object.entries(ALIAS_MAP)) {
-    it(`${alias} delegates to ${target}`, async () => {
+    it(`${alias} delegates to ${target} and adds success: true`, async () => {
       const spy = vi
         .spyOn(app, target as any)
         .mockResolvedValue({ ok: true } as any);
-      await (app as any)[alias]("https://example.com");
+      const result = await (app as any)[alias]("https://example.com");
       expect(spy).toHaveBeenCalled();
-      spy.mockRestore();
+      expect(result).toEqual({ ok: true, success: true });
     });
   }
+
+  it("scrapeUrl keeps the document fields beside success, as v1 did", async () => {
+    vi.spyOn(app, "scrape").mockResolvedValue({ markdown: "# hi", metadata: { sourceURL: "https://example.com" } } as any);
+    const result = await app.scrapeUrl("https://example.com", { formats: ["markdown"] });
+    expect(app.scrape).toHaveBeenCalledWith("https://example.com", { formats: ["markdown"] });
+    expect(result.success).toBe(true);
+    expect(result.markdown).toBe("# hi");
+  });
+
+  it("crawlUrl and asyncCrawlUrl rename v1 crawl options to their v2 names", async () => {
+    vi.spyOn(app, "crawl").mockResolvedValue({ status: "completed", data: [] } as any);
+    vi.spyOn(app, "startCrawl").mockResolvedValue({ id: "job-1", url: "u" } as any);
+    const v1Options = { limit: 2, maxDepth: 3, allowBackwardLinks: true, ignoreSitemap: true, scrapeOptions: { formats: ["markdown" as const] } };
+    const expected = { limit: 2, maxDiscoveryDepth: 3, crawlEntireDomain: true, sitemap: "skip", scrapeOptions: { formats: ["markdown"] } };
+
+    await app.crawlUrl("https://example.com", v1Options);
+    await app.asyncCrawlUrl("https://example.com", v1Options);
+
+    expect(app.crawl).toHaveBeenCalledWith("https://example.com", expected);
+    expect(app.startCrawl).toHaveBeenCalledWith("https://example.com", expected);
+  });
+
+  it("v2 methods return results without success", async () => {
+    const client = new FirecrawlClient({ apiKey: "fc-test", apiUrl: "http://localhost:9" });
+    const adapter: AxiosAdapter = async config => ({
+      data: { success: true, data: { markdown: "# hi" } },
+      status: 200,
+      statusText: "OK",
+      headers: {},
+      config,
+    });
+    (client as any).http.instance.defaults.adapter = adapter;
+    const result = await client.scrape("https://example.com", { formats: ["markdown"] });
+    expect(result).toEqual({ markdown: "# hi" });
+    expect("success" in result).toBe(false);
+  });
+});
+
+describe("V1 deprecation warning", () => {
+  afterEach(() => {
+    vi.restoreAllMocks();
+  });
+
+  async function freshClient() {
+    vi.resetModules();
+    const emitWarning = vi.spyOn(process, "emitWarning").mockImplementation(() => {});
+    const { FirecrawlClient: FreshClient } = await import("../../../v2/client");
+    const app = new FreshClient({ apiKey: "fc-test", apiUrl: "http://localhost:9" });
+    const v1Warnings = () => emitWarning.mock.calls.filter(([, opts]) => (opts as any)?.code === "FIRECRAWL_V1_METHOD");
+    return { app, v1Warnings };
+  }
+
+  it("is emitted once per process", async () => {
+    const { app, v1Warnings } = await freshClient();
+    vi.spyOn(app, "scrape").mockResolvedValue({ markdown: "# hi" } as any);
+    vi.spyOn(app, "map").mockResolvedValue({ links: [] } as any);
+
+    await app.scrapeUrl("https://example.com");
+    await app.scrapeUrl("https://example.com");
+    await app.mapUrl("https://example.com");
+
+    expect(v1Warnings()).toHaveLength(1);
+    expect((v1Warnings()[0]![1] as any).type).toBe("DeprecationWarning");
+  });
+
+  it("is not emitted by v2 methods", async () => {
+    const { app, v1Warnings } = await freshClient();
+    const adapter: AxiosAdapter = async config => ({
+      data: { success: true, data: { markdown: "# hi" } },
+      status: 200,
+      statusText: "OK",
+      headers: {},
+      config,
+    });
+    (app as any).http.instance.defaults.adapter = adapter;
+
+    await app.scrape("https://example.com", { formats: ["markdown"] });
+
+    expect(v1Warnings()).toHaveLength(0);
+  });
 });

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,7 +101,10 @@ import type {
   GetMonitorCheckOptions,
   UpdateMonitorRequest,
 } from "./types";
+import { defaultOrigin } from "../utils/callerOrigin";
+import { getVersion } from "./utils/getVersion";
 import { Watcher } from "./watcher";
+import { callV1, toV2CrawlOptions, type V1CrawlOptions, type V1Result } from "./utils/v1Compat";
 import type { WatcherOptions } from "./watcher";
 import * as zt from "zod";
 
@@ -130,6 +133,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 +149,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 +177,7 @@ export class FirecrawlClient {
       timeoutMs: opts.timeoutMs,
       maxRetries: opts.maxRetries,
       backoffFactor: opts.backoffFactor,
+      origin: opts.origin || defaultOrigin(getVersion()),
     });
   }
 
@@ -721,54 +731,54 @@ export class FirecrawlClient {
     return new Watcher(this.http, jobId, opts);
   }
 
-  /** @deprecated V1 compatibility alias for agent recovery. Prefer scrape(). */
-  async scrapeUrl(url: string, options?: ScrapeOptions): Promise<Document> {
-    return this.scrape(url, options);
+  /** @deprecated v1 alias for scrape(); its result also carries v1's `success: true`. */
+  async scrapeUrl(url: string, options?: ScrapeOptions): Promise<V1Result<Document>> {
+    return callV1(() => this.scrape(url, options));
   }
 
-  /** @deprecated V1 compatibility alias for agent recovery. Prefer crawl(). */
-  async crawlUrl(url: string, req: CrawlOptions & { pollInterval?: number; timeout?: number; signal?: AbortSignal } = {}): Promise<CrawlJob> {
-    return this.crawl(url, req);
+  /** @deprecated v1 alias for crawl(); its result also carries v1's `success: true`. */
+  async crawlUrl(url: string, req: CrawlOptions & V1CrawlOptions & { pollInterval?: number; timeout?: number; signal?: AbortSignal } = {}): Promise<V1Result<CrawlJob>> {
+    return callV1(() => this.crawl(url, toV2CrawlOptions(req)));
   }
 
-  /** @deprecated V1 compatibility alias for agent recovery. Prefer startCrawl(). */
-  async asyncCrawlUrl(url: string, req: CrawlOptions = {}): Promise<CrawlResponse> {
-    return this.startCrawl(url, req);
+  /** @deprecated v1 alias for startCrawl(); its result also carries v1's `success: true`. */
+  async asyncCrawlUrl(url: string, req: CrawlOptions & V1CrawlOptions = {}): Promise<V1Result<CrawlResponse>> {
+    return callV1(() => this.startCrawl(url, toV2CrawlOptions(req)));
   }
 
-  /** @deprecated V1 compatibility alias for agent recovery. Prefer getCrawlStatus(). */
-  async checkCrawlStatus(jobId: string, pagination?: PaginationConfig): Promise<CrawlJob> {
-    return this.getCrawlStatus(jobId, pagination);
+  /** @deprecated v1 alias for getCrawlStatus(); its result also carries v1's `success: true`. */
+  async checkCrawlStatus(jobId: string, pagination?: PaginationConfig): Promise<V1Result<CrawlJob>> {
+    return callV1(() => this.getCrawlStatus(jobId, pagination));
   }
 
-  /** @deprecated V1 compatibility alias for agent recovery. Prefer getCrawlErrors(). */
-  async checkCrawlErrors(crawlId: string): Promise<CrawlErrorsResponse> {
-    return this.getCrawlErrors(crawlId);
+  /** @deprecated v1 alias for getCrawlErrors(); its result also carries v1's `success: true`. */
+  async checkCrawlErrors(crawlId: string): Promise<V1Result<CrawlErrorsResponse>> {
+    return callV1(() => this.getCrawlErrors(crawlId));
   }
 
-  /** @deprecated V1 compatibility alias for agent recovery. Prefer map(). */
-  async mapUrl(url: string, options?: MapOptions): Promise<MapData> {
-    return this.map(url, options);
+  /** @deprecated v1 alias for map(); its result also carries v1's `success: true`. */
+  async mapUrl(url: string, options?: MapOptions): Promise<V1Result<MapData>> {
+    return callV1(() => this.map(url, options));
   }
 
-  /** @deprecated V1 compatibility alias for agent recovery. Prefer batchScrape(). */
-  async batchScrapeUrls(urls: string[], opts?: BatchScrapeOptions & { pollInterval?: number; timeout?: number }): Promise<BatchScrapeJob> {
-    return this.batchScrape(urls, opts);
+  /** @deprecated v1 alias for batchScrape(); its result also carries v1's `success: true`. */
+  async batchScrapeUrls(urls: string[], opts?: BatchScrapeOptions & { pollInterval?: number; timeout?: number }): Promise<V1Result<BatchScrapeJob>> {
+    return callV1(() => this.batchScrape(urls, opts));
   }
 
-  /** @deprecated V1 compatibility alias for agent recovery. Prefer startBatchScrape(). */
-  async asyncBatchScrapeUrls(urls: string[], opts?: BatchScrapeOptions): Promise<BatchScrapeResponse> {
-    return this.startBatchScrape(urls, opts);
+  /** @deprecated v1 alias for startBatchScrape(); its result also carries v1's `success: true`. */
+  async asyncBatchScrapeUrls(urls: string[], opts?: BatchScrapeOptions): Promise<V1Result<BatchScrapeResponse>> {
+    return callV1(() => this.startBatchScrape(urls, opts));
   }
 
-  /** @deprecated V1 compatibility alias for agent recovery. Prefer getBatchScrapeStatus(). */
-  async checkBatchScrapeStatus(jobId: string, pagination?: PaginationConfig): Promise<BatchScrapeJob> {
-    return this.getBatchScrapeStatus(jobId, pagination);
+  /** @deprecated v1 alias for getBatchScrapeStatus(); its result also carries v1's `success: true`. */
+  async checkBatchScrapeStatus(jobId: string, pagination?: PaginationConfig): Promise<V1Result<BatchScrapeJob>> {
+    return callV1(() => this.getBatchScrapeStatus(jobId, pagination));
   }
 
-  /** @deprecated V1 compatibility alias for agent recovery. Prefer getBatchScrapeErrors(). */
-  async checkBatchScrapeErrors(jobId: string): Promise<CrawlErrorsResponse> {
-    return this.getBatchScrapeErrors(jobId);
+  /** @deprecated v1 alias for getBatchScrapeErrors(); its result also carries v1's `success: true`. */
+  async checkBatchScrapeErrors(jobId: string): Promise<V1Result<CrawlErrorsResponse>> {
+    return callV1(() => this.getBatchScrapeErrors(jobId));
   }
 }
 

package/src/v2/methods/parse.ts

@@ -6,7 +6,6 @@ import {
   throwForBadResponse,
   normalizeAxiosError,
 } from "../utils/errorHandler";
-import { getVersion } from "../utils/getVersion";
 
 function toUploadBlob(input: ParseFile["data"], contentType?: string): Blob {
   if (typeof Blob !== "undefined" && input instanceof Blob) {
@@ -57,13 +56,9 @@ export async function parse(
 
   if (options) ensureValidParseOptions(options);
 
-  const version = getVersion();
   const normalizedOptions: ParseOptions = {
     ...(options ?? {}),
-    origin:
-      typeof options?.origin === "string" && options.origin.includes("mcp")
-        ? options.origin
-        : (options?.origin ?? `js-sdk@${version}`),
+    origin: options?.origin || http.getOrigin(),
   };
 
   const formData = new FormData();