firecrawl 4.25.2 → 4.25.3

package/dist/index.js

@@ -1,6 +1,6 @@
 import {
   require_package
-} from "./chunk-XCQC2QCZ.js";
+} from "./chunk-5D4KXCYO.js";
 
 // src/v2/utils/httpClient.ts
 import axios from "axios";
@@ -1301,6 +1301,142 @@ async function getTokenUsageHistorical(http, byApiKey) {
   }
 }
 
+// src/v2/methods/research.ts
+var BASE = "/v2/research";
+function appendParam(params, key, value) {
+  if (value == null) return;
+  if (Array.isArray(value)) {
+    for (const v of value) {
+      if (v != null && String(v).length > 0) params.append(key, String(v));
+    }
+  } else {
+    params.append(key, String(value));
+  }
+}
+function withQuery(path, params) {
+  const qs = params.toString();
+  return qs ? `${path}?${qs}` : path;
+}
+function normalizeResearchError(err, action) {
+  if (err?.isAxiosError) {
+    const status = err.response?.status;
+    const body = err.response?.data;
+    if (body && (body.detail || body.title)) {
+      const message = body.detail || body.title;
+      throw new SdkError(message, status, body.type, body);
+    }
+    throw new SdkError(
+      err.message || `Request failed while trying to ${action}`,
+      status,
+      err.code,
+      body
+    );
+  }
+  throw err;
+}
+var ResearchClient = class {
+  constructor(http) {
+    this.http = http;
+  }
+  /**
+   * Search papers by abstract relevance.
+   * @param query Natural-language search query.
+   * @param options Optional filters (k, authors, categories, from, to).
+   */
+  async searchPapers(query, options = {}) {
+    if (!query || !query.trim()) throw new Error("query cannot be empty");
+    if (options.k != null && options.k <= 0)
+      throw new Error("k must be positive");
+    const params = new URLSearchParams();
+    appendParam(params, "query", query);
+    appendParam(params, "k", options.k);
+    appendParam(params, "authors", options.authors);
+    appendParam(params, "categories", options.categories);
+    appendParam(params, "from", options.from);
+    appendParam(params, "to", options.to);
+    try {
+      const res = await this.http.get(
+        withQuery(`${BASE}/papers`, params)
+      );
+      if (res.status !== 200) throwForBadResponse(res, "search papers");
+      return res.data;
+    } catch (err) {
+      return normalizeResearchError(err, "search papers");
+    }
+  }
+  async getPaper(id, options = {}) {
+    if (!id || !id.trim()) throw new Error("id cannot be empty");
+    if (options.k != null && options.query == null)
+      throw new Error("k is only valid together with query");
+    if (options.k != null && options.k <= 0)
+      throw new Error("k must be positive");
+    const params = new URLSearchParams();
+    appendParam(params, "query", options.query);
+    appendParam(params, "k", options.k);
+    try {
+      const res = await this.http.get(
+        withQuery(`${BASE}/papers/${encodeURIComponent(id)}`, params)
+      );
+      if (res.status !== 200) throwForBadResponse(res, "get paper");
+      return res.data;
+    } catch (err) {
+      return normalizeResearchError(err, "get paper");
+    }
+  }
+  /**
+   * Find related papers via the citation graph.
+   * @param id Primary seed paper reference.
+   * @param options Required `intent` plus optional mode, k, rerank, anchor.
+   */
+  async similarPapers(id, options) {
+    if (!id || !id.trim()) throw new Error("id cannot be empty");
+    if (!options?.intent || !options.intent.trim())
+      throw new Error("intent cannot be empty");
+    if (options.k != null && options.k <= 0)
+      throw new Error("k must be positive");
+    const params = new URLSearchParams();
+    appendParam(params, "intent", options.intent);
+    appendParam(params, "mode", options.mode);
+    appendParam(params, "k", options.k);
+    if (options.rerank != null) appendParam(params, "rerank", options.rerank);
+    appendParam(params, "anchor", options.anchor);
+    try {
+      const res = await this.http.get(
+        withQuery(
+          `${BASE}/papers/${encodeURIComponent(id)}/similar`,
+          params
+        )
+      );
+      if (res.status !== 200) throwForBadResponse(res, "find similar papers");
+      return res.data;
+    } catch (err) {
+      return normalizeResearchError(err, "find similar papers");
+    }
+  }
+  /**
+   * Search GitHub issue/PR history and repository readmes.
+   * @param query Search query.
+   * @param options Optional `k`.
+   */
+  async searchGithub(query, options = {}) {
+    if (!query || !query.trim()) throw new Error("query cannot be empty");
+    if (options.k != null && options.k <= 0)
+      throw new Error("k must be positive");
+    const params = new URLSearchParams();
+    appendParam(params, "query", query);
+    appendParam(params, "k", options.k);
+    try {
+      const res = await this.http.get(
+        withQuery(`${BASE}/github`, params)
+      );
+      if (res.status !== 200) throwForBadResponse(res, "search github");
+      return res.data;
+    } catch (err) {
+      return normalizeResearchError(err, "search github");
+    }
+  }
+};
+
 // src/v2/methods/monitor.ts
 function queryString(params) {
   if (!params) return "";
@@ -1666,6 +1802,7 @@ var Watcher = class extends EventEmitter {
 import "zod";
 var FirecrawlClient = class {
   http;
+  _research;
   isCloudService(url) {
     return url.includes("api.firecrawl.dev");
   }
@@ -1738,6 +1875,15 @@ var FirecrawlClient = class {
   async search(query, req = {}) {
     return search(this.http, { query, ...req });
   }
+  // Research
+  /**
+   * Access the v2 research endpoints (arXiv papers + GitHub history/readmes).
+   * Example: `firecrawl.research.searchPapers("diffusion models")`.
+   */
+  get research() {
+    if (!this._research) this._research = new ResearchClient(this.http);
+    return this._research;
+  }
   // Map
   /**
    * Map a site to discover URLs (sitemap-aware).
@@ -2097,7 +2243,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-D6422PQU.js");
+      const packageJson = await import("./package-HESILIET.js");
       return packageJson.default.version;
     } catch (error) {
       const isTest = typeof process !== "undefined" && (process.env.JEST_WORKER_ID != null || false);
@@ -3494,6 +3640,7 @@ export {
   FirecrawlApp as FirecrawlAppV1,
   FirecrawlClient,
   JobTimeoutError,
+  ResearchClient,
   SdkError,
   Watcher,
   index_default as default

package/dist/{package-D6422PQU.js → package-HESILIET.js}

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

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "firecrawl",
-  "version": "4.25.2",
+  "version": "4.25.3",
   "description": "JavaScript SDK for Firecrawl API",
   "main": "dist/index.js",
   "types": "dist/index.d.ts",
@@ -40,7 +40,7 @@
     "ts-jest": "^29.4.5",
     "tsup": "^8.5.0",
     "typescript": "^5.4.5",
-    "uuid": "^9.0.1"
+    "uuid": "^14.0.0"
   },
   "keywords": [
     "firecrawl",

package/pnpm-workspace.yaml

@@ -0,0 +1,3 @@
+allowBuilds:
+  esbuild: true
+  unrs-resolver: true

package/src/__tests__/e2e/v1/index.test.ts

@@ -26,10 +26,10 @@ describe('FirecrawlApp E2E Tests', () => {
   test.concurrent('should throw error for invalid API key on scrape', async () => {
     if (API_URL.includes('api.firecrawl.dev')) {
       const invalidApp = new FirecrawlApp({ apiKey: "invalid_api_key", apiUrl: API_URL });
-      await expect(invalidApp.scrapeUrl('https://roastmywebsite.ai')).rejects.toThrow("Unexpected error occurred while trying to scrape URL. Status code: 401");
+      await expect(invalidApp.scrapeUrl('https://firecrawl-test-site.vercel.app')).rejects.toThrow("Unexpected error occurred while trying to scrape URL. Status code: 401");
     } else {
       const invalidApp = new FirecrawlApp({ apiKey: "invalid_api_key", apiUrl: API_URL });
-      await expect(invalidApp.scrapeUrl('https://roastmywebsite.ai')).resolves.not.toThrow();
+      await expect(invalidApp.scrapeUrl('https://firecrawl-test-site.vercel.app')).resolves.not.toThrow();
     }
   });
 
@@ -42,7 +42,7 @@ describe('FirecrawlApp E2E Tests', () => {
   test.concurrent('should return successful response for valid scrape', async () => {
     const app = new FirecrawlApp({ apiKey: TEST_API_KEY, apiUrl: API_URL });
 
-    const response = await app.scrapeUrl('https://roastmywebsite.ai');
+    const response = await app.scrapeUrl('https://firecrawl-test-site.vercel.app');
     if (!response.success) {
       throw new Error(response.error);
     }
@@ -51,7 +51,7 @@ describe('FirecrawlApp E2E Tests', () => {
   test.concurrent('should return successful response with valid API key and options', async () => {
     const app = new FirecrawlApp({ apiKey: TEST_API_KEY, apiUrl: API_URL });
     const response = await app.scrapeUrl(
-      'https://roastmywebsite.ai', {
+      'https://firecrawl-test-site.vercel.app', {
       formats: ['markdown', 'html', 'rawHtml', 'screenshot', 'links'],
       headers: { "x-key": "test" },
       includeTags: ['h1'],
@@ -69,7 +69,7 @@ describe('FirecrawlApp E2E Tests', () => {
   test.concurrent('should return successful response with valid API key and screenshot fullPage', async () => {
     const app = new FirecrawlApp({ apiKey: TEST_API_KEY, apiUrl: API_URL });
     const response = await app.scrapeUrl(
-      'https://roastmywebsite.ai', {
+      'https://firecrawl-test-site.vercel.app', {
       formats: ['screenshot@fullPage'],
     });
     if (!response.success) {
@@ -132,16 +132,16 @@ describe('FirecrawlApp E2E Tests', () => {
   test.concurrent('should throw error for invalid API key on crawl', async () => {
     if (API_URL.includes('api.firecrawl.dev')) {
       const invalidApp = new FirecrawlApp({ apiKey: "invalid_api_key", apiUrl: API_URL });
-      await expect(invalidApp.crawlUrl('https://roastmywebsite.ai')).rejects.toThrow("Request failed with status code 401");
+      await expect(invalidApp.crawlUrl('https://firecrawl-test-site.vercel.app')).rejects.toThrow("Request failed with status code 401");
     } else {
       const invalidApp = new FirecrawlApp({ apiKey: "invalid_api_key", apiUrl: API_URL });
-      await expect(invalidApp.crawlUrl('https://roastmywebsite.ai')).resolves.not.toThrow();
+      await expect(invalidApp.crawlUrl('https://firecrawl-test-site.vercel.app')).resolves.not.toThrow();
     }
   });
 
   test.concurrent('should return successful response for crawl and wait for completion', async () => {
     const app = new FirecrawlApp({ apiKey: TEST_API_KEY, apiUrl: API_URL });
-    const response = await app.crawlUrl('https://roastmywebsite.ai', {}, 30) as CrawlStatusResponse;
+    const response = await app.crawlUrl('https://firecrawl-test-site.vercel.app', {}, 30) as CrawlStatusResponse;
     expect(response).not.toHaveProperty("next"); // wait until done
     expect(response.data.length).toBeGreaterThan(0);
     if (response.data[0]) {
@@ -151,7 +151,7 @@ describe('FirecrawlApp E2E Tests', () => {
 
   test.concurrent('should return successful response for crawl with options and wait for completion', async () => {
     const app = new FirecrawlApp({ apiKey: TEST_API_KEY, apiUrl: API_URL });
-    const response = await app.crawlUrl('https://roastmywebsite.ai', {
+    const response = await app.crawlUrl('https://firecrawl-test-site.vercel.app', {
       excludePaths: ['blog/*'],
       includePaths: ['/'],
       maxDepth: 2,
@@ -183,11 +183,11 @@ describe('FirecrawlApp E2E Tests', () => {
   test.concurrent('should handle idempotency key for crawl', async () => {
     const app = new FirecrawlApp({ apiKey: TEST_API_KEY, apiUrl: API_URL });
     const uniqueIdempotencyKey = uuidv4();
-    const response = await app.asyncCrawlUrl('https://roastmywebsite.ai', {}, uniqueIdempotencyKey) as CrawlResponse;
+    const response = await app.asyncCrawlUrl('https://firecrawl-test-site.vercel.app', {}, uniqueIdempotencyKey) as CrawlResponse;
     expect(response).not.toBeNull();
     expect(response.id).toBeDefined();
 
-    await expect(app.crawlUrl('https://roastmywebsite.ai', {}, 2, uniqueIdempotencyKey)).rejects.toThrow("Request failed with status code 409");
+    await expect(app.crawlUrl('https://firecrawl-test-site.vercel.app', {}, 2, uniqueIdempotencyKey)).rejects.toThrow("Request failed with status code 409");
   });
 
   test.concurrent('should check crawl status', async () => {
@@ -236,10 +236,10 @@ describe('FirecrawlApp E2E Tests', () => {
   test.concurrent('should throw error for invalid API key on map', async () => {
     if (API_URL.includes('api.firecrawl.dev')) {
       const invalidApp = new FirecrawlApp({ apiKey: "invalid_api_key", apiUrl: API_URL });
-      await expect(invalidApp.mapUrl('https://roastmywebsite.ai')).rejects.toThrow("Request failed with status code 401");
+      await expect(invalidApp.mapUrl('https://firecrawl-test-site.vercel.app')).rejects.toThrow("Request failed with status code 401");
     } else {
       const invalidApp = new FirecrawlApp({ apiKey: "invalid_api_key", apiUrl: API_URL });
-      await expect(invalidApp.mapUrl('https://roastmywebsite.ai')).resolves.not.toThrow();
+      await expect(invalidApp.mapUrl('https://firecrawl-test-site.vercel.app')).resolves.not.toThrow();
     }
   });
 
@@ -250,12 +250,12 @@ describe('FirecrawlApp E2E Tests', () => {
   });
 
   test.concurrent('should return successful response for valid map', async () => {
-    const app = new FirecrawlApp({ apiKey: TEST_API_KEY, apiUrl: API_URL }); const response = await app.mapUrl('https://roastmywebsite.ai') as MapResponse;
+    const app = new FirecrawlApp({ apiKey: TEST_API_KEY, apiUrl: API_URL }); const response = await app.mapUrl('https://firecrawl-test-site.vercel.app') as MapResponse;
     expect(response).not.toBeNull();
 
     expect(response.links?.length).toBeGreaterThan(0);
     expect(response.links?.[0]).toContain("https://");
-    const filteredLinks = response.links?.filter((link: string) => link.includes("roastmywebsite.ai"));
+    const filteredLinks = response.links?.filter((link: string) => link.includes("firecrawl-test-site.vercel.app"));
     expect(filteredLinks?.length).toBeGreaterThan(0);
   }, 30000); // 30 seconds timeout
 

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

@@ -0,0 +1,168 @@
+import { describe, test, expect } from "@jest/globals";
+import { ResearchClient } from "../../../v2/methods/research";
+import { SdkError } from "../../../v2/types";
+import type { HttpClient } from "../../../v2/utils/httpClient";
+
+/** Build a ResearchClient whose http.get records the requested URL. */
+function makeClient(
+  responder: (url: string) => { status: number; data: any } = () => ({
+    status: 200,
+    data: {},
+  }),
+) {
+  const calls: string[] = [];
+  const http = {
+    get: async (url: string) => {
+      calls.push(url);
+      return responder(url);
+    },
+  } as unknown as HttpClient;
+  return { client: new ResearchClient(http), calls };
+}
+
+/** Make an axios-like error carrying an RFC 7807 Problem body. */
+function problemError(status: number, body: any) {
+  return { isAxiosError: true, response: { status, data: body }, message: "req failed" };
+}
+
+describe("research.searchPapers", () => {
+  test("builds query string with explode arrays", async () => {
+    const { client, calls } = makeClient(() => ({
+      status: 200,
+      data: { results: [] },
+    }));
+    await client.searchPapers("diffusion models", {
+      k: 10,
+      authors: ["Ho", "Abbeel"],
+      categories: ["cs.LG", "stat.ML"],
+      from: "2020-01-01",
+      to: "2024-12-31",
+    });
+    const url = calls[0];
+    expect(url.startsWith("/v2/research/papers?")).toBe(true);
+    const qs = new URLSearchParams(url.split("?")[1]);
+    expect(qs.get("query")).toBe("diffusion models");
+    expect(qs.get("k")).toBe("10");
+    expect(qs.getAll("authors")).toEqual(["Ho", "Abbeel"]);
+    expect(qs.getAll("categories")).toEqual(["cs.LG", "stat.ML"]);
+    expect(qs.get("from")).toBe("2020-01-01");
+    expect(qs.get("to")).toBe("2024-12-31");
+  });
+
+  test("omits absent options", async () => {
+    const { client, calls } = makeClient(() => ({ status: 200, data: { results: [] } }));
+    await client.searchPapers("q");
+    const qs = new URLSearchParams(calls[0].split("?")[1]);
+    expect([...qs.keys()]).toEqual(["query"]);
+  });
+
+  test("rejects empty query", async () => {
+    const { client } = makeClient();
+    await expect(client.searchPapers("  ")).rejects.toThrow(/query cannot be empty/i);
+  });
+
+  test("rejects non-positive k", async () => {
+    const { client } = makeClient();
+    await expect(client.searchPapers("q", { k: 0 })).rejects.toThrow(/k must be positive/i);
+  });
+
+  test("returns the response body verbatim", async () => {
+    const payload = { results: [{ paper_id: "1", title: "t", abstract: "a", score: 0.1 }] };
+    const { client } = makeClient(() => ({ status: 200, data: payload }));
+    await expect(client.searchPapers("q")).resolves.toEqual(payload);
+  });
+});
+
+describe("research.getPaper", () => {
+  test("detail mode encodes the id and sends no query params", async () => {
+    const { client, calls } = makeClient(() => ({ status: 200, data: { paper: {} } }));
+    await client.getPaper("arxiv:2105.05233");
+    expect(calls[0]).toBe("/v2/research/papers/arxiv%3A2105.05233");
+  });
+
+  test("read mode adds query and k", async () => {
+    const { client, calls } = makeClient(() => ({
+      status: 200,
+      data: { paper: {}, paper_id: "1", query: "q", passages: [] },
+    }));
+    await client.getPaper("123", { query: "noise schedule", k: 4 });
+    const [path, query] = calls[0].split("?");
+    expect(path).toBe("/v2/research/papers/123");
+    const qs = new URLSearchParams(query);
+    expect(qs.get("query")).toBe("noise schedule");
+    expect(qs.get("k")).toBe("4");
+  });
+
+  test("rejects k without query", async () => {
+    const { client } = makeClient();
+    await expect(client.getPaper("123", { k: 4 } as any)).rejects.toThrow(
+      /k is only valid together with query/i,
+    );
+  });
+});
+
+describe("research.similarPapers", () => {
+  test("requires intent", async () => {
+    const { client } = makeClient();
+    await expect(
+      client.similarPapers("123", { intent: "" }),
+    ).rejects.toThrow(/intent cannot be empty/i);
+  });
+
+  test("builds path and query with repeated anchors and rerank", async () => {
+    const { client, calls } = makeClient(() => ({
+      status: 200,
+      data: { results: [], pool_size: 0, truncated: false },
+    }));
+    await client.similarPapers("2105.05233", {
+      intent: "diffusion image synthesis",
+      mode: "citers",
+      k: 20,
+      rerank: false,
+      anchor: ["arxiv:2006.11239", "1503.03585"],
+    });
+    const [path, query] = calls[0].split("?");
+    expect(path).toBe("/v2/research/papers/2105.05233/similar");
+    const qs = new URLSearchParams(query);
+    expect(qs.get("intent")).toBe("diffusion image synthesis");
+    expect(qs.get("mode")).toBe("citers");
+    expect(qs.get("k")).toBe("20");
+    expect(qs.get("rerank")).toBe("false");
+    expect(qs.getAll("anchor")).toEqual(["arxiv:2006.11239", "1503.03585"]);
+  });
+});
+
+describe("research.searchGithub", () => {
+  test("builds query string", async () => {
+    const { client, calls } = makeClient(() => ({ status: 200, data: { results: [] } }));
+    await client.searchGithub("milvus hybrid search", { k: 10 });
+    const qs = new URLSearchParams(calls[0].split("?")[1]);
+    expect(calls[0].startsWith("/v2/research/github?")).toBe(true);
+    expect(qs.get("query")).toBe("milvus hybrid search");
+    expect(qs.get("k")).toBe("10");
+  });
+});
+
+describe("research error mapping", () => {
+  test("maps RFC 7807 Problem detail to SdkError", async () => {
+    const { client } = makeClient(() => {
+      throw problemError(400, {
+        type: "urn:search-pipeline:invalid_request",
+        title: "Bad Request",
+        status: 400,
+        detail: "query is required",
+      });
+    });
+    await expect(client.searchPapers("q")).rejects.toMatchObject({
+      message: "query is required",
+      status: 400,
+    } as Partial<SdkError>);
+  });
+
+  test("falls back to title when detail is absent", async () => {
+    const { client } = makeClient(() => {
+      throw problemError(404, { title: "Not Found", status: 404 });
+    });
+    await expect(client.getPaper("999")).rejects.toThrow(/Not Found/);
+  });
+});

package/src/index.ts

@@ -11,6 +11,8 @@ export { FirecrawlClient } from "./v2/client";
 export * from "./v2/types";
 /** Watcher class and options for crawl/batch job monitoring. */
 export { Watcher, type WatcherOptions } from "./v2/watcher";
+/** Research sub-client (accessed via `firecrawl.research`). */
+export { ResearchClient } from "./v2/methods/research";
 /** Legacy v1 client (feature‑frozen). */
 export { default as FirecrawlAppV1 } from "./v1";
 

package/src/v2/client.ts

@@ -32,6 +32,7 @@ import {
   listBrowsers,
 } from "./methods/browser";
 import { getConcurrency, getCreditUsage, getQueueStatus, getTokenUsage, getCreditUsageHistorical, getTokenUsageHistorical } from "./methods/usage";
+import { ResearchClient } from "./methods/research";
 import {
   createMonitor as createMonitorMethod,
   deleteMonitor as deleteMonitorMethod,
@@ -119,6 +120,7 @@ export type FirecrawlClientInput = FirecrawlClientOptions | string;
 
 export class FirecrawlClient {
   private readonly http: HttpClient;
+  private _research?: ResearchClient;
 
   private isCloudService(url: string): boolean {
     return url.includes('api.firecrawl.dev');
@@ -234,6 +236,16 @@ export class FirecrawlClient {
     return search(this.http, { query, ...req });
   }
 
+  // Research
+  /**
+   * Access the v2 research endpoints (arXiv papers + GitHub history/readmes).
+   * Example: `firecrawl.research.searchPapers("diffusion models")`.
+   */
+  get research(): ResearchClient {
+    if (!this._research) this._research = new ResearchClient(this.http);
+    return this._research;
+  }
+
   // Map
   /**
    * Map a site to discover URLs (sitemap-aware).