firecrawl 4.48.0 → 4.49.0

package/README.md

@@ -1,6 +1,6 @@
 # Firecrawl Node SDK
 
-The Firecrawl Node SDK is the JavaScript client for the Firecrawl API, the context API for AI agents. Search, scrape, parse, crawl, map, and interact with the web, and get back clean Markdown or structured data your agents can ship with.
+The Firecrawl Node SDK is the JavaScript client for the Firecrawl API, the context API for AI agents. Search, scrape, parse, crawl, map, and interact with the web, run Agent and Monitor jobs, and get back clean Markdown or structured data your agents can ship with.
 
 ## Installation
 

package/dist/{chunk-GD463K4D.js → chunk-JNLB66PW.js}

@@ -1,6 +1,6 @@
 // package.json
 var name = "@mendable/firecrawl-js";
-var version = "4.48.0";
+var version = "4.49.0";
 var description = "JavaScript SDK for the Firecrawl API: web scraping, crawling, web search, and scientific literature search over a research paper index of PubMed, bioRxiv, medRxiv and arXiv abstracts";
 var main = "dist/index.js";
 var types = "dist/index.d.ts";

package/dist/index.cjs

@@ -39,7 +39,7 @@ var require_package = __commonJS({
   "package.json"(exports2, module2) {
     module2.exports = {
       name: "@mendable/firecrawl-js",
-      version: "4.48.0",
+      version: "4.49.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",
@@ -2486,6 +2486,32 @@ var Watcher = class extends import_events.EventEmitter {
   }
 };
 
+// src/v2/utils/v1Compat.ts
+var warned = false;
+function warnV1Usage() {
+  if (warned) return;
+  warned = true;
+  const message = "firecrawl: v1-style methods (scrapeUrl, crawlUrl, batchScrapeUrls, ...) are deprecated and mapped to the v2 API. Use scrape(), crawl(), batchScrape() and the other v2 methods instead.";
+  if (typeof process !== "undefined" && typeof process.emitWarning === "function") {
+    process.emitWarning(message, { type: "DeprecationWarning", code: "FIRECRAWL_V1_METHOD" });
+  } else {
+    console.warn(message);
+  }
+}
+function toV2CrawlOptions(req) {
+  const { maxDepth, allowBackwardLinks, ignoreSitemap, ...rest } = req;
+  return {
+    ...maxDepth != null && { maxDiscoveryDepth: maxDepth },
+    ...allowBackwardLinks != null && { crawlEntireDomain: allowBackwardLinks },
+    ...ignoreSitemap != null && { sitemap: ignoreSitemap ? "skip" : "include" },
+    ...rest
+  };
+}
+async function callV1(call) {
+  warnV1Usage();
+  return { ...await call(), success: true };
+}
+
 // src/v2/client.ts
 var zt = require("zod");
 var FirecrawlClient = class {
@@ -2967,45 +2993,45 @@ var FirecrawlClient = class {
   watcher(jobId, opts = {}) {
     return new Watcher(this.http, jobId, opts);
   }
-  /** @deprecated V1 compatibility alias for agent recovery. Prefer scrape(). */
+  /** @deprecated v1 alias for scrape(); its result also carries v1's `success: true`. */
   async scrapeUrl(url, options) {
-    return this.scrape(url, options);
+    return callV1(() => this.scrape(url, options));
   }
-  /** @deprecated V1 compatibility alias for agent recovery. Prefer crawl(). */
+  /** @deprecated v1 alias for crawl(); its result also carries v1's `success: true`. */
   async crawlUrl(url, req = {}) {
-    return this.crawl(url, req);
+    return callV1(() => this.crawl(url, toV2CrawlOptions(req)));
   }
-  /** @deprecated V1 compatibility alias for agent recovery. Prefer startCrawl(). */
+  /** @deprecated v1 alias for startCrawl(); its result also carries v1's `success: true`. */
   async asyncCrawlUrl(url, req = {}) {
-    return this.startCrawl(url, req);
+    return callV1(() => this.startCrawl(url, toV2CrawlOptions(req)));
   }
-  /** @deprecated V1 compatibility alias for agent recovery. Prefer getCrawlStatus(). */
+  /** @deprecated v1 alias for getCrawlStatus(); its result also carries v1's `success: true`. */
   async checkCrawlStatus(jobId, pagination) {
-    return this.getCrawlStatus(jobId, pagination);
+    return callV1(() => this.getCrawlStatus(jobId, pagination));
   }
-  /** @deprecated V1 compatibility alias for agent recovery. Prefer getCrawlErrors(). */
+  /** @deprecated v1 alias for getCrawlErrors(); its result also carries v1's `success: true`. */
   async checkCrawlErrors(crawlId) {
-    return this.getCrawlErrors(crawlId);
+    return callV1(() => this.getCrawlErrors(crawlId));
   }
-  /** @deprecated V1 compatibility alias for agent recovery. Prefer map(). */
+  /** @deprecated v1 alias for map(); its result also carries v1's `success: true`. */
   async mapUrl(url, options) {
-    return this.map(url, options);
+    return callV1(() => this.map(url, options));
   }
-  /** @deprecated V1 compatibility alias for agent recovery. Prefer batchScrape(). */
+  /** @deprecated v1 alias for batchScrape(); its result also carries v1's `success: true`. */
   async batchScrapeUrls(urls, opts) {
-    return this.batchScrape(urls, opts);
+    return callV1(() => this.batchScrape(urls, opts));
   }
-  /** @deprecated V1 compatibility alias for agent recovery. Prefer startBatchScrape(). */
+  /** @deprecated v1 alias for startBatchScrape(); its result also carries v1's `success: true`. */
   async asyncBatchScrapeUrls(urls, opts) {
-    return this.startBatchScrape(urls, opts);
+    return callV1(() => this.startBatchScrape(urls, opts));
   }
-  /** @deprecated V1 compatibility alias for agent recovery. Prefer getBatchScrapeStatus(). */
+  /** @deprecated v1 alias for getBatchScrapeStatus(); its result also carries v1's `success: true`. */
   async checkBatchScrapeStatus(jobId, pagination) {
-    return this.getBatchScrapeStatus(jobId, pagination);
+    return callV1(() => this.getBatchScrapeStatus(jobId, pagination));
   }
-  /** @deprecated V1 compatibility alias for agent recovery. Prefer getBatchScrapeErrors(). */
+  /** @deprecated v1 alias for getBatchScrapeErrors(); its result also carries v1's `success: true`. */
   async checkBatchScrapeErrors(jobId) {
-    return this.getBatchScrapeErrors(jobId);
+    return callV1(() => this.getBatchScrapeErrors(jobId));
   }
 };
 

package/dist/index.d.cts

@@ -2248,6 +2248,17 @@ declare class Watcher extends EventEmitter {
     close(): void;
 }
 
+/** v1 crawl options that have a v2 equivalent. */
+type V1CrawlOptions = {
+    maxDepth?: number;
+    allowBackwardLinks?: boolean;
+    ignoreSitemap?: boolean;
+};
+/** A v2 result with the `success` flag v1 results carried. */
+type V1Result<T> = T & {
+    success: true;
+};
+
 type ExtractJsonSchemaFromFormats<Formats> = Formats extends readonly any[] ? Extract<Formats[number], {
     type: "json";
     schema?: unknown;
@@ -2639,33 +2650,33 @@ declare class FirecrawlClient {
      * @param opts Watcher options (kind, pollInterval, timeout seconds).
      */
     watcher(jobId: string, opts?: WatcherOptions): Watcher;
-    /** @deprecated V1 compatibility alias for agent recovery. Prefer scrape(). */
-    scrapeUrl(url: string, options?: ScrapeOptions): Promise<Document>;
-    /** @deprecated V1 compatibility alias for agent recovery. Prefer crawl(). */
-    crawlUrl(url: string, req?: CrawlOptions & {
+    /** @deprecated v1 alias for scrape(); its result also carries v1's `success: true`. */
+    scrapeUrl(url: string, options?: ScrapeOptions): Promise<V1Result<Document>>;
+    /** @deprecated v1 alias for crawl(); its result also carries v1's `success: true`. */
+    crawlUrl(url: string, req?: CrawlOptions & V1CrawlOptions & {
         pollInterval?: number;
         timeout?: number;
         signal?: AbortSignal;
-    }): Promise<CrawlJob>;
-    /** @deprecated V1 compatibility alias for agent recovery. Prefer startCrawl(). */
-    asyncCrawlUrl(url: string, req?: CrawlOptions): Promise<CrawlResponse$1>;
-    /** @deprecated V1 compatibility alias for agent recovery. Prefer getCrawlStatus(). */
-    checkCrawlStatus(jobId: string, pagination?: PaginationConfig): Promise<CrawlJob>;
-    /** @deprecated V1 compatibility alias for agent recovery. Prefer getCrawlErrors(). */
-    checkCrawlErrors(crawlId: string): Promise<CrawlErrorsResponse$1>;
-    /** @deprecated V1 compatibility alias for agent recovery. Prefer map(). */
-    mapUrl(url: string, options?: MapOptions): Promise<MapData>;
-    /** @deprecated V1 compatibility alias for agent recovery. Prefer batchScrape(). */
+    }): Promise<V1Result<CrawlJob>>;
+    /** @deprecated v1 alias for startCrawl(); its result also carries v1's `success: true`. */
+    asyncCrawlUrl(url: string, req?: CrawlOptions & V1CrawlOptions): Promise<V1Result<CrawlResponse$1>>;
+    /** @deprecated v1 alias for getCrawlStatus(); its result also carries v1's `success: true`. */
+    checkCrawlStatus(jobId: string, pagination?: PaginationConfig): Promise<V1Result<CrawlJob>>;
+    /** @deprecated v1 alias for getCrawlErrors(); its result also carries v1's `success: true`. */
+    checkCrawlErrors(crawlId: string): Promise<V1Result<CrawlErrorsResponse$1>>;
+    /** @deprecated v1 alias for map(); its result also carries v1's `success: true`. */
+    mapUrl(url: string, options?: MapOptions): Promise<V1Result<MapData>>;
+    /** @deprecated v1 alias for batchScrape(); its result also carries v1's `success: true`. */
     batchScrapeUrls(urls: string[], opts?: BatchScrapeOptions & {
         pollInterval?: number;
         timeout?: number;
-    }): Promise<BatchScrapeJob>;
-    /** @deprecated V1 compatibility alias for agent recovery. Prefer startBatchScrape(). */
-    asyncBatchScrapeUrls(urls: string[], opts?: BatchScrapeOptions): Promise<BatchScrapeResponse$1>;
-    /** @deprecated V1 compatibility alias for agent recovery. Prefer getBatchScrapeStatus(). */
-    checkBatchScrapeStatus(jobId: string, pagination?: PaginationConfig): Promise<BatchScrapeJob>;
-    /** @deprecated V1 compatibility alias for agent recovery. Prefer getBatchScrapeErrors(). */
-    checkBatchScrapeErrors(jobId: string): Promise<CrawlErrorsResponse$1>;
+    }): Promise<V1Result<BatchScrapeJob>>;
+    /** @deprecated v1 alias for startBatchScrape(); its result also carries v1's `success: true`. */
+    asyncBatchScrapeUrls(urls: string[], opts?: BatchScrapeOptions): Promise<V1Result<BatchScrapeResponse$1>>;
+    /** @deprecated v1 alias for getBatchScrapeStatus(); its result also carries v1's `success: true`. */
+    checkBatchScrapeStatus(jobId: string, pagination?: PaginationConfig): Promise<V1Result<BatchScrapeJob>>;
+    /** @deprecated v1 alias for getBatchScrapeErrors(); its result also carries v1's `success: true`. */
+    checkBatchScrapeErrors(jobId: string): Promise<V1Result<CrawlErrorsResponse$1>>;
 }
 
 /**

package/dist/index.d.ts

@@ -2248,6 +2248,17 @@ declare class Watcher extends EventEmitter {
     close(): void;
 }
 
+/** v1 crawl options that have a v2 equivalent. */
+type V1CrawlOptions = {
+    maxDepth?: number;
+    allowBackwardLinks?: boolean;
+    ignoreSitemap?: boolean;
+};
+/** A v2 result with the `success` flag v1 results carried. */
+type V1Result<T> = T & {
+    success: true;
+};
+
 type ExtractJsonSchemaFromFormats<Formats> = Formats extends readonly any[] ? Extract<Formats[number], {
     type: "json";
     schema?: unknown;
@@ -2639,33 +2650,33 @@ declare class FirecrawlClient {
      * @param opts Watcher options (kind, pollInterval, timeout seconds).
      */
     watcher(jobId: string, opts?: WatcherOptions): Watcher;
-    /** @deprecated V1 compatibility alias for agent recovery. Prefer scrape(). */
-    scrapeUrl(url: string, options?: ScrapeOptions): Promise<Document>;
-    /** @deprecated V1 compatibility alias for agent recovery. Prefer crawl(). */
-    crawlUrl(url: string, req?: CrawlOptions & {
+    /** @deprecated v1 alias for scrape(); its result also carries v1's `success: true`. */
+    scrapeUrl(url: string, options?: ScrapeOptions): Promise<V1Result<Document>>;
+    /** @deprecated v1 alias for crawl(); its result also carries v1's `success: true`. */
+    crawlUrl(url: string, req?: CrawlOptions & V1CrawlOptions & {
         pollInterval?: number;
         timeout?: number;
         signal?: AbortSignal;
-    }): Promise<CrawlJob>;
-    /** @deprecated V1 compatibility alias for agent recovery. Prefer startCrawl(). */
-    asyncCrawlUrl(url: string, req?: CrawlOptions): Promise<CrawlResponse$1>;
-    /** @deprecated V1 compatibility alias for agent recovery. Prefer getCrawlStatus(). */
-    checkCrawlStatus(jobId: string, pagination?: PaginationConfig): Promise<CrawlJob>;
-    /** @deprecated V1 compatibility alias for agent recovery. Prefer getCrawlErrors(). */
-    checkCrawlErrors(crawlId: string): Promise<CrawlErrorsResponse$1>;
-    /** @deprecated V1 compatibility alias for agent recovery. Prefer map(). */
-    mapUrl(url: string, options?: MapOptions): Promise<MapData>;
-    /** @deprecated V1 compatibility alias for agent recovery. Prefer batchScrape(). */
+    }): Promise<V1Result<CrawlJob>>;
+    /** @deprecated v1 alias for startCrawl(); its result also carries v1's `success: true`. */
+    asyncCrawlUrl(url: string, req?: CrawlOptions & V1CrawlOptions): Promise<V1Result<CrawlResponse$1>>;
+    /** @deprecated v1 alias for getCrawlStatus(); its result also carries v1's `success: true`. */
+    checkCrawlStatus(jobId: string, pagination?: PaginationConfig): Promise<V1Result<CrawlJob>>;
+    /** @deprecated v1 alias for getCrawlErrors(); its result also carries v1's `success: true`. */
+    checkCrawlErrors(crawlId: string): Promise<V1Result<CrawlErrorsResponse$1>>;
+    /** @deprecated v1 alias for map(); its result also carries v1's `success: true`. */
+    mapUrl(url: string, options?: MapOptions): Promise<V1Result<MapData>>;
+    /** @deprecated v1 alias for batchScrape(); its result also carries v1's `success: true`. */
     batchScrapeUrls(urls: string[], opts?: BatchScrapeOptions & {
         pollInterval?: number;
         timeout?: number;
-    }): Promise<BatchScrapeJob>;
-    /** @deprecated V1 compatibility alias for agent recovery. Prefer startBatchScrape(). */
-    asyncBatchScrapeUrls(urls: string[], opts?: BatchScrapeOptions): Promise<BatchScrapeResponse$1>;
-    /** @deprecated V1 compatibility alias for agent recovery. Prefer getBatchScrapeStatus(). */
-    checkBatchScrapeStatus(jobId: string, pagination?: PaginationConfig): Promise<BatchScrapeJob>;
-    /** @deprecated V1 compatibility alias for agent recovery. Prefer getBatchScrapeErrors(). */
-    checkBatchScrapeErrors(jobId: string): Promise<CrawlErrorsResponse$1>;
+    }): Promise<V1Result<BatchScrapeJob>>;
+    /** @deprecated v1 alias for startBatchScrape(); its result also carries v1's `success: true`. */
+    asyncBatchScrapeUrls(urls: string[], opts?: BatchScrapeOptions): Promise<V1Result<BatchScrapeResponse$1>>;
+    /** @deprecated v1 alias for getBatchScrapeStatus(); its result also carries v1's `success: true`. */
+    checkBatchScrapeStatus(jobId: string, pagination?: PaginationConfig): Promise<V1Result<BatchScrapeJob>>;
+    /** @deprecated v1 alias for getBatchScrapeErrors(); its result also carries v1's `success: true`. */
+    checkBatchScrapeErrors(jobId: string): Promise<V1Result<CrawlErrorsResponse$1>>;
 }
 
 /**

package/dist/index.js

@@ -1,6 +1,6 @@
 import {
   version
-} from "./chunk-GD463K4D.js";
+} from "./chunk-JNLB66PW.js";
 
 // src/v2/utils/httpClient.ts
 import axios from "axios";
@@ -2357,6 +2357,32 @@ var Watcher = class extends EventEmitter {
   }
 };
 
+// src/v2/utils/v1Compat.ts
+var warned = false;
+function warnV1Usage() {
+  if (warned) return;
+  warned = true;
+  const message = "firecrawl: v1-style methods (scrapeUrl, crawlUrl, batchScrapeUrls, ...) are deprecated and mapped to the v2 API. Use scrape(), crawl(), batchScrape() and the other v2 methods instead.";
+  if (typeof process !== "undefined" && typeof process.emitWarning === "function") {
+    process.emitWarning(message, { type: "DeprecationWarning", code: "FIRECRAWL_V1_METHOD" });
+  } else {
+    console.warn(message);
+  }
+}
+function toV2CrawlOptions(req) {
+  const { maxDepth, allowBackwardLinks, ignoreSitemap, ...rest } = req;
+  return {
+    ...maxDepth != null && { maxDiscoveryDepth: maxDepth },
+    ...allowBackwardLinks != null && { crawlEntireDomain: allowBackwardLinks },
+    ...ignoreSitemap != null && { sitemap: ignoreSitemap ? "skip" : "include" },
+    ...rest
+  };
+}
+async function callV1(call) {
+  warnV1Usage();
+  return { ...await call(), success: true };
+}
+
 // src/v2/client.ts
 import "zod";
 var FirecrawlClient = class {
@@ -2838,45 +2864,45 @@ var FirecrawlClient = class {
   watcher(jobId, opts = {}) {
     return new Watcher(this.http, jobId, opts);
   }
-  /** @deprecated V1 compatibility alias for agent recovery. Prefer scrape(). */
+  /** @deprecated v1 alias for scrape(); its result also carries v1's `success: true`. */
   async scrapeUrl(url, options) {
-    return this.scrape(url, options);
+    return callV1(() => this.scrape(url, options));
   }
-  /** @deprecated V1 compatibility alias for agent recovery. Prefer crawl(). */
+  /** @deprecated v1 alias for crawl(); its result also carries v1's `success: true`. */
   async crawlUrl(url, req = {}) {
-    return this.crawl(url, req);
+    return callV1(() => this.crawl(url, toV2CrawlOptions(req)));
   }
-  /** @deprecated V1 compatibility alias for agent recovery. Prefer startCrawl(). */
+  /** @deprecated v1 alias for startCrawl(); its result also carries v1's `success: true`. */
   async asyncCrawlUrl(url, req = {}) {
-    return this.startCrawl(url, req);
+    return callV1(() => this.startCrawl(url, toV2CrawlOptions(req)));
   }
-  /** @deprecated V1 compatibility alias for agent recovery. Prefer getCrawlStatus(). */
+  /** @deprecated v1 alias for getCrawlStatus(); its result also carries v1's `success: true`. */
   async checkCrawlStatus(jobId, pagination) {
-    return this.getCrawlStatus(jobId, pagination);
+    return callV1(() => this.getCrawlStatus(jobId, pagination));
   }
-  /** @deprecated V1 compatibility alias for agent recovery. Prefer getCrawlErrors(). */
+  /** @deprecated v1 alias for getCrawlErrors(); its result also carries v1's `success: true`. */
   async checkCrawlErrors(crawlId) {
-    return this.getCrawlErrors(crawlId);
+    return callV1(() => this.getCrawlErrors(crawlId));
   }
-  /** @deprecated V1 compatibility alias for agent recovery. Prefer map(). */
+  /** @deprecated v1 alias for map(); its result also carries v1's `success: true`. */
   async mapUrl(url, options) {
-    return this.map(url, options);
+    return callV1(() => this.map(url, options));
   }
-  /** @deprecated V1 compatibility alias for agent recovery. Prefer batchScrape(). */
+  /** @deprecated v1 alias for batchScrape(); its result also carries v1's `success: true`. */
   async batchScrapeUrls(urls, opts) {
-    return this.batchScrape(urls, opts);
+    return callV1(() => this.batchScrape(urls, opts));
   }
-  /** @deprecated V1 compatibility alias for agent recovery. Prefer startBatchScrape(). */
+  /** @deprecated v1 alias for startBatchScrape(); its result also carries v1's `success: true`. */
   async asyncBatchScrapeUrls(urls, opts) {
-    return this.startBatchScrape(urls, opts);
+    return callV1(() => this.startBatchScrape(urls, opts));
   }
-  /** @deprecated V1 compatibility alias for agent recovery. Prefer getBatchScrapeStatus(). */
+  /** @deprecated v1 alias for getBatchScrapeStatus(); its result also carries v1's `success: true`. */
   async checkBatchScrapeStatus(jobId, pagination) {
-    return this.getBatchScrapeStatus(jobId, pagination);
+    return callV1(() => this.getBatchScrapeStatus(jobId, pagination));
   }
-  /** @deprecated V1 compatibility alias for agent recovery. Prefer getBatchScrapeErrors(). */
+  /** @deprecated v1 alias for getBatchScrapeErrors(); its result also carries v1's `success: true`. */
   async checkBatchScrapeErrors(jobId) {
-    return this.getBatchScrapeErrors(jobId);
+    return callV1(() => this.getBatchScrapeErrors(jobId));
   }
 };
 
@@ -2915,7 +2941,7 @@ var FirecrawlApp = class {
       if (typeof process !== "undefined" && process.env && process.env.npm_package_version) {
         return process.env.npm_package_version;
       }
-      const packageJson = await import("./package-WONXBIJS.js");
+      const packageJson = await import("./package-7E5DZETG.js");
       return packageJson.default.version;
     } catch (error) {
       const isTest = typeof process !== "undefined" && false;

package/dist/{package-WONXBIJS.js → package-7E5DZETG.js}

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

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "firecrawl",
-  "version": "4.48.0",
+  "version": "4.49.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/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/v2/client.ts

@@ -104,6 +104,7 @@ import type {
 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";
 
@@ -730,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/utils/v1Compat.ts

@@ -0,0 +1,38 @@
+let warned = false;
+
+/** Emits the deprecation warning for v1-style method calls, once per process. */
+export function warnV1Usage(): void {
+  if (warned) return;
+  warned = true;
+  const message =
+    "firecrawl: v1-style methods (scrapeUrl, crawlUrl, batchScrapeUrls, ...) are deprecated and mapped to the v2 API. " +
+    "Use scrape(), crawl(), batchScrape() and the other v2 methods instead.";
+  if (typeof process !== "undefined" && typeof process.emitWarning === "function") {
+    process.emitWarning(message, { type: "DeprecationWarning", code: "FIRECRAWL_V1_METHOD" });
+  } else {
+    console.warn(message);
+  }
+}
+
+/** v1 crawl options that have a v2 equivalent. */
+export type V1CrawlOptions = { maxDepth?: number; allowBackwardLinks?: boolean; ignoreSitemap?: boolean };
+
+/** Renames v1 crawl options to their v2 names; v2 options given alongside win. */
+export function toV2CrawlOptions<T extends object>(req: T & V1CrawlOptions): T {
+  const { maxDepth, allowBackwardLinks, ignoreSitemap, ...rest } = req;
+  return {
+    ...(maxDepth != null && { maxDiscoveryDepth: maxDepth }),
+    ...(allowBackwardLinks != null && { crawlEntireDomain: allowBackwardLinks }),
+    ...(ignoreSitemap != null && { sitemap: ignoreSitemap ? "skip" : "include" }),
+    ...rest,
+  } as T;
+}
+
+/** A v2 result with the `success` flag v1 results carried. */
+export type V1Result<T> = T & { success: true };
+
+/** Warns once, then runs the v2 call and adds the v1 `success` flag to its result. */
+export async function callV1<T extends object>(call: () => Promise<T>): Promise<V1Result<T>> {
+  warnV1Usage();
+  return { ...(await call()), success: true };
+}