@mendable/firecrawl-js 4.47.0 → 4.48.0

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()),
     });
   }
 

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();

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