@mendable/firecrawl-js 4.47.0 → 4.49.0

package/src/v2/methods/research.ts

@@ -12,7 +12,6 @@ import type {
 import { SdkError } from "../types";
 import { HttpClient } from "../utils/httpClient";
 import { throwForBadResponse } from "../utils/errorHandler";
-import { getVersion } from "../utils/getVersion";
 
 const BASE = "/v2/search/research";
 
@@ -32,10 +31,14 @@ function appendParam(
   }
 }
 
-function withQuery(path: string, params: URLSearchParams): string {
+function withQuery(
+  origin: string,
+  path: string,
+  params: URLSearchParams,
+): string {
   // Research endpoints are GETs, so the POST-body origin injection in
   // HttpClient never applies — attach it as a query param instead.
-  params.append("origin", `js-sdk@${getVersion()}`);
+  params.append("origin", origin);
   const qs = params.toString();
   return qs ? `${path}?${qs}` : path;
 }
@@ -121,7 +124,7 @@ export class ResearchClient {
     appendParam(params, "to", options.to);
     try {
       const res = await this.http.get<SearchPapersResponse>(
-        withQuery(`${BASE}/papers`, params),
+        withQuery(this.http.getOrigin(), `${BASE}/papers`, params),
       );
       if (res.status !== 200) throwForBadResponse(res, "search papers");
       return res.data;
@@ -161,7 +164,13 @@ export class ResearchClient {
     try {
       const res = await this.http.get<
         PaperMetadataResponse | ReadPaperResponse
-      >(withQuery(`${BASE}/papers/${encodeURIComponent(id)}`, params));
+      >(
+        withQuery(
+          this.http.getOrigin(),
+          `${BASE}/papers/${encodeURIComponent(id)}`,
+          params,
+        ),
+      );
       if (res.status !== 200) throwForBadResponse(res, "get paper");
       return res.data;
     } catch (err) {
@@ -191,7 +200,11 @@ export class ResearchClient {
     appendParam(params, "anchor", options.anchor);
     try {
       const res = await this.http.get<SimilarPapersResponse>(
-        withQuery(`${BASE}/papers/${encodeURIComponent(id)}/similar`, params),
+        withQuery(
+          this.http.getOrigin(),
+          `${BASE}/papers/${encodeURIComponent(id)}/similar`,
+          params,
+        ),
       );
       if (res.status !== 200) throwForBadResponse(res, "find similar papers");
       return res.data;
@@ -226,7 +239,7 @@ export class ResearchClient {
     appendParam(params, "k", options.k);
     try {
       const res = await this.http.get<GitHubSearchResponse>(
-        withQuery(`${BASE}/github`, params),
+        withQuery(this.http.getOrigin(), `${BASE}/github`, params),
       );
       if (res.status !== 200) throwForBadResponse(res, "search github");
       return res.data;

package/src/v2/utils/httpClient.ts

@@ -12,6 +12,7 @@ export interface HttpClientOptions {
   timeoutMs?: number;
   maxRetries?: number;
   backoffFactor?: number; // seconds factor for 0.5, 1, 2...
+  origin?: string;
 }
 
 export interface RequestOptions {
@@ -25,12 +26,14 @@ export class HttpClient {
   private readonly apiUrl: string;
   private readonly maxRetries: number;
   private readonly backoffFactor: number;
+  private readonly origin: string;
 
   constructor(options: HttpClientOptions) {
     this.apiKey = options.apiKey;
     this.apiUrl = options.apiUrl.replace(/\/$/, "");
     this.maxRetries = options.maxRetries ?? 3;
     this.backoffFactor = options.backoffFactor ?? 0.5;
+    this.origin = options.origin || `js-sdk@${getVersion()}`;
     this.instance = axios.create({
       baseURL: this.apiUrl,
       timeout: options.timeoutMs ?? 300000,
@@ -52,6 +55,11 @@ export class HttpClient {
     return this.apiKey;
   }
 
+  /** The attribution origin stamped into requests that do not set their own. */
+  getOrigin(): string {
+    return this.origin;
+  }
+
   /** The client-wide default request timeout, for callers that need to
    * extend a specific request beyond it (e.g. scrape auto-resume). */
   getTimeoutMs(): number {
@@ -61,7 +69,6 @@ export class HttpClient {
   private async request<T = any>(
     config: AxiosRequestConfig,
   ): Promise<AxiosResponse<T>> {
-    const version = getVersion();
     config.headers = {
       ...(config.headers || {}),
     };
@@ -89,9 +96,9 @@ export class HttpClient {
           cfg.data = {
             ...data,
             origin:
-              typeof data.origin === "string" && data.origin.includes("mcp")
+              typeof data.origin === "string" && data.origin
                 ? data.origin
-                : `js-sdk@${version}`,
+                : this.origin,
           };
         }
 

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 };
+}