@mendable/firecrawl-js 1.17.0 → 1.18.0-beta.2

package/dist/index.cjs

@@ -851,6 +851,93 @@ var FirecrawlApp = class {
       );
     }
   }
+  /**
+   * Initiates a deep research operation on a given topic and polls until completion.
+   * @param params - Parameters for the deep research operation.
+   * @returns The final research results.
+   */
+  async __deepResearch(params) {
+    try {
+      const response = await this.__asyncDeepResearch(params);
+      if (!response.success || "error" in response) {
+        return { success: false, error: "error" in response ? response.error : "Unknown error" };
+      }
+      if (response.id) {
+        const jobId = response.id;
+        let researchStatus;
+        do {
+          researchStatus = await this.__checkDeepResearchStatus(jobId);
+          if ("error" in researchStatus && !researchStatus.success) {
+            return researchStatus;
+          }
+          if (researchStatus.status === "completed") {
+            return researchStatus;
+          } else if (researchStatus.status === "failed") {
+            throw new FirecrawlError(`Research job failed. Error: ${researchStatus.error}`, 500);
+          }
+          await new Promise((resolve) => setTimeout(resolve, 1e3));
+        } while (researchStatus.status === "processing");
+      }
+      throw new FirecrawlError(`Failed to start research. No job ID returned.`, 500);
+    } catch (error) {
+      throw new FirecrawlError(error.message, 500, error.response?.data?.details);
+    }
+  }
+  /**
+   * Initiates a deep research operation on a given topic without polling.
+   * @param params - Parameters for the deep research operation.
+   * @returns The response containing the research job ID.
+   */
+  async __asyncDeepResearch(params) {
+    const headers = this.prepareHeaders();
+    try {
+      const response = await this.postRequest(
+        `${this.apiUrl}/v1/deep-research`,
+        params,
+        headers
+      );
+      if (response.status === 200) {
+        return response.data;
+      } else {
+        this.handleError(response, "start deep research");
+      }
+    } catch (error) {
+      if (error.response?.data?.error) {
+        throw new FirecrawlError(`Request failed with status code ${error.response.status}. Error: ${error.response.data.error} ${error.response.data.details ? ` - ${JSON.stringify(error.response.data.details)}` : ""}`, error.response.status);
+      } else {
+        throw new FirecrawlError(error.message, 500);
+      }
+    }
+    return { success: false, error: "Internal server error." };
+  }
+  /**
+   * Checks the status of a deep research operation.
+   * @param id - The ID of the deep research operation.
+   * @returns The current status and results of the research operation.
+   */
+  async __checkDeepResearchStatus(id) {
+    const headers = this.prepareHeaders();
+    try {
+      const response = await this.getRequest(
+        `${this.apiUrl}/v1/deep-research/${id}`,
+        headers
+      );
+      if (response.status === 200) {
+        return response.data;
+      } else if (response.status === 404) {
+        throw new FirecrawlError("Deep research job not found", 404);
+      } else {
+        this.handleError(response, "check deep research status");
+      }
+    } catch (error) {
+      if (error.response?.data?.error) {
+        throw new FirecrawlError(`Request failed with status code ${error.response.status}. Error: ${error.response.data.error} ${error.response.data.details ? ` - ${JSON.stringify(error.response.data.details)}` : ""}`, error.response.status);
+      } else {
+        throw new FirecrawlError(error.message, 500);
+      }
+    }
+    return { success: false, error: "Internal server error." };
+  }
 };
 var CrawlWatcher = class extends import_typescript_event_target.TypedEventTarget {
   ws;

package/dist/index.d.cts

@@ -317,6 +317,71 @@ interface CrawlErrorsResponse {
      */
     robotsBlocked: string[];
 }
+/**
+ * Parameters for deep research operations.
+ * Defines options for conducting deep research on a topic.
+ */
+interface DeepResearchParams {
+    /**
+     * The topic or question to research
+     */
+    topic: string;
+    /**
+     * Maximum depth of research iterations (1-10)
+     * @default 7
+     */
+    maxDepth?: number;
+    /**
+     * Time limit in seconds (30-300)
+     * @default 270
+     */
+    timeLimit?: number;
+    /**
+     * Experimental flag for streaming steps
+     */
+    __experimental_streamSteps?: boolean;
+}
+/**
+ * Response interface for deep research operations.
+ */
+interface DeepResearchResponse {
+    success: boolean;
+    id: string;
+}
+/**
+ * Status response interface for deep research operations.
+ */
+interface DeepResearchStatusResponse {
+    success: boolean;
+    data: {
+        findings: Array<{
+            text: string;
+            source: string;
+        }>;
+        finalAnalysis: string;
+        analysis: string;
+        completedSteps: number;
+        totalSteps: number;
+    };
+    status: "processing" | "completed" | "failed";
+    error?: string;
+    expiresAt: string;
+    currentDepth: number;
+    maxDepth: number;
+    activities: Array<{
+        type: string;
+        status: string;
+        message: string;
+        timestamp: string;
+        depth: number;
+    }>;
+    sources: Array<{
+        url: string;
+        title: string;
+        description: string;
+    }>;
+    summaries: string[];
+}
 /**
  * Main class for interacting with the Firecrawl API.
  * Provides methods for scraping, searching, crawling, and mapping web content.
@@ -491,6 +556,24 @@ declare class FirecrawlApp {
      * @param {string} action - The action being performed when the error occurred.
      */
     handleError(response: AxiosResponse, action: string): void;
+    /**
+     * Initiates a deep research operation on a given topic and polls until completion.
+     * @param params - Parameters for the deep research operation.
+     * @returns The final research results.
+     */
+    __deepResearch(params: DeepResearchParams): Promise<DeepResearchStatusResponse | ErrorResponse>;
+    /**
+     * Initiates a deep research operation on a given topic without polling.
+     * @param params - Parameters for the deep research operation.
+     * @returns The response containing the research job ID.
+     */
+    __asyncDeepResearch(params: DeepResearchParams): Promise<DeepResearchResponse | ErrorResponse>;
+    /**
+     * Checks the status of a deep research operation.
+     * @param id - The ID of the deep research operation.
+     * @returns The current status and results of the research operation.
+     */
+    __checkDeepResearchStatus(id: string): Promise<DeepResearchStatusResponse | ErrorResponse>;
 }
 interface CrawlWatcherEvents {
     document: CustomEvent<FirecrawlDocument<undefined>>;
@@ -513,4 +596,4 @@ declare class CrawlWatcher extends TypedEventTarget<CrawlWatcherEvents> {
     close(): void;
 }
 
-export { type Action, type ActionsResult, type BatchScrapeResponse, type BatchScrapeStatusResponse, type CrawlErrorsResponse, type CrawlParams, type CrawlResponse, type CrawlScrapeOptions, type CrawlStatusResponse, CrawlWatcher, type ErrorResponse, type ExtractParams, type ExtractResponse, type FirecrawlAppConfig, type FirecrawlDocument, type FirecrawlDocumentMetadata, FirecrawlError, type MapParams, type MapResponse, type ScrapeParams, type ScrapeResponse, type SearchParams, type SearchResponse, FirecrawlApp as default };
+export { type Action, type ActionsResult, type BatchScrapeResponse, type BatchScrapeStatusResponse, type CrawlErrorsResponse, type CrawlParams, type CrawlResponse, type CrawlScrapeOptions, type CrawlStatusResponse, CrawlWatcher, type DeepResearchParams, type DeepResearchResponse, type DeepResearchStatusResponse, type ErrorResponse, type ExtractParams, type ExtractResponse, type FirecrawlAppConfig, type FirecrawlDocument, type FirecrawlDocumentMetadata, FirecrawlError, type MapParams, type MapResponse, type ScrapeParams, type ScrapeResponse, type SearchParams, type SearchResponse, FirecrawlApp as default };

package/dist/index.d.ts

@@ -317,6 +317,71 @@ interface CrawlErrorsResponse {
      */
     robotsBlocked: string[];
 }
+/**
+ * Parameters for deep research operations.
+ * Defines options for conducting deep research on a topic.
+ */
+interface DeepResearchParams {
+    /**
+     * The topic or question to research
+     */
+    topic: string;
+    /**
+     * Maximum depth of research iterations (1-10)
+     * @default 7
+     */
+    maxDepth?: number;
+    /**
+     * Time limit in seconds (30-300)
+     * @default 270
+     */
+    timeLimit?: number;
+    /**
+     * Experimental flag for streaming steps
+     */
+    __experimental_streamSteps?: boolean;
+}
+/**
+ * Response interface for deep research operations.
+ */
+interface DeepResearchResponse {
+    success: boolean;
+    id: string;
+}
+/**
+ * Status response interface for deep research operations.
+ */
+interface DeepResearchStatusResponse {
+    success: boolean;
+    data: {
+        findings: Array<{
+            text: string;
+            source: string;
+        }>;
+        finalAnalysis: string;
+        analysis: string;
+        completedSteps: number;
+        totalSteps: number;
+    };
+    status: "processing" | "completed" | "failed";
+    error?: string;
+    expiresAt: string;
+    currentDepth: number;
+    maxDepth: number;
+    activities: Array<{
+        type: string;
+        status: string;
+        message: string;
+        timestamp: string;
+        depth: number;
+    }>;
+    sources: Array<{
+        url: string;
+        title: string;
+        description: string;
+    }>;
+    summaries: string[];
+}
 /**
  * Main class for interacting with the Firecrawl API.
  * Provides methods for scraping, searching, crawling, and mapping web content.
@@ -491,6 +556,24 @@ declare class FirecrawlApp {
      * @param {string} action - The action being performed when the error occurred.
      */
     handleError(response: AxiosResponse, action: string): void;
+    /**
+     * Initiates a deep research operation on a given topic and polls until completion.
+     * @param params - Parameters for the deep research operation.
+     * @returns The final research results.
+     */
+    __deepResearch(params: DeepResearchParams): Promise<DeepResearchStatusResponse | ErrorResponse>;
+    /**
+     * Initiates a deep research operation on a given topic without polling.
+     * @param params - Parameters for the deep research operation.
+     * @returns The response containing the research job ID.
+     */
+    __asyncDeepResearch(params: DeepResearchParams): Promise<DeepResearchResponse | ErrorResponse>;
+    /**
+     * Checks the status of a deep research operation.
+     * @param id - The ID of the deep research operation.
+     * @returns The current status and results of the research operation.
+     */
+    __checkDeepResearchStatus(id: string): Promise<DeepResearchStatusResponse | ErrorResponse>;
 }
 interface CrawlWatcherEvents {
     document: CustomEvent<FirecrawlDocument<undefined>>;
@@ -513,4 +596,4 @@ declare class CrawlWatcher extends TypedEventTarget<CrawlWatcherEvents> {
     close(): void;
 }
 
-export { type Action, type ActionsResult, type BatchScrapeResponse, type BatchScrapeStatusResponse, type CrawlErrorsResponse, type CrawlParams, type CrawlResponse, type CrawlScrapeOptions, type CrawlStatusResponse, CrawlWatcher, type ErrorResponse, type ExtractParams, type ExtractResponse, type FirecrawlAppConfig, type FirecrawlDocument, type FirecrawlDocumentMetadata, FirecrawlError, type MapParams, type MapResponse, type ScrapeParams, type ScrapeResponse, type SearchParams, type SearchResponse, FirecrawlApp as default };
+export { type Action, type ActionsResult, type BatchScrapeResponse, type BatchScrapeStatusResponse, type CrawlErrorsResponse, type CrawlParams, type CrawlResponse, type CrawlScrapeOptions, type CrawlStatusResponse, CrawlWatcher, type DeepResearchParams, type DeepResearchResponse, type DeepResearchStatusResponse, type ErrorResponse, type ExtractParams, type ExtractResponse, type FirecrawlAppConfig, type FirecrawlDocument, type FirecrawlDocumentMetadata, FirecrawlError, type MapParams, type MapResponse, type ScrapeParams, type ScrapeResponse, type SearchParams, type SearchResponse, FirecrawlApp as default };

package/dist/index.js

@@ -815,6 +815,93 @@ var FirecrawlApp = class {
       );
     }
   }
+  /**
+   * Initiates a deep research operation on a given topic and polls until completion.
+   * @param params - Parameters for the deep research operation.
+   * @returns The final research results.
+   */
+  async __deepResearch(params) {
+    try {
+      const response = await this.__asyncDeepResearch(params);
+      if (!response.success || "error" in response) {
+        return { success: false, error: "error" in response ? response.error : "Unknown error" };
+      }
+      if (response.id) {
+        const jobId = response.id;
+        let researchStatus;
+        do {
+          researchStatus = await this.__checkDeepResearchStatus(jobId);
+          if ("error" in researchStatus && !researchStatus.success) {
+            return researchStatus;
+          }
+          if (researchStatus.status === "completed") {
+            return researchStatus;
+          } else if (researchStatus.status === "failed") {
+            throw new FirecrawlError(`Research job failed. Error: ${researchStatus.error}`, 500);
+          }
+          await new Promise((resolve) => setTimeout(resolve, 1e3));
+        } while (researchStatus.status === "processing");
+      }
+      throw new FirecrawlError(`Failed to start research. No job ID returned.`, 500);
+    } catch (error) {
+      throw new FirecrawlError(error.message, 500, error.response?.data?.details);
+    }
+  }
+  /**
+   * Initiates a deep research operation on a given topic without polling.
+   * @param params - Parameters for the deep research operation.
+   * @returns The response containing the research job ID.
+   */
+  async __asyncDeepResearch(params) {
+    const headers = this.prepareHeaders();
+    try {
+      const response = await this.postRequest(
+        `${this.apiUrl}/v1/deep-research`,
+        params,
+        headers
+      );
+      if (response.status === 200) {
+        return response.data;
+      } else {
+        this.handleError(response, "start deep research");
+      }
+    } catch (error) {
+      if (error.response?.data?.error) {
+        throw new FirecrawlError(`Request failed with status code ${error.response.status}. Error: ${error.response.data.error} ${error.response.data.details ? ` - ${JSON.stringify(error.response.data.details)}` : ""}`, error.response.status);
+      } else {
+        throw new FirecrawlError(error.message, 500);
+      }
+    }
+    return { success: false, error: "Internal server error." };
+  }
+  /**
+   * Checks the status of a deep research operation.
+   * @param id - The ID of the deep research operation.
+   * @returns The current status and results of the research operation.
+   */
+  async __checkDeepResearchStatus(id) {
+    const headers = this.prepareHeaders();
+    try {
+      const response = await this.getRequest(
+        `${this.apiUrl}/v1/deep-research/${id}`,
+        headers
+      );
+      if (response.status === 200) {
+        return response.data;
+      } else if (response.status === 404) {
+        throw new FirecrawlError("Deep research job not found", 404);
+      } else {
+        this.handleError(response, "check deep research status");
+      }
+    } catch (error) {
+      if (error.response?.data?.error) {
+        throw new FirecrawlError(`Request failed with status code ${error.response.status}. Error: ${error.response.data.error} ${error.response.data.details ? ` - ${JSON.stringify(error.response.data.details)}` : ""}`, error.response.status);
+      } else {
+        throw new FirecrawlError(error.message, 500);
+      }
+    }
+    return { success: false, error: "Internal server error." };
+  }
 };
 var CrawlWatcher = class extends TypedEventTarget {
   ws;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@mendable/firecrawl-js",
-  "version": "1.17.0",
+  "version": "1.18.0-beta.2",
   "description": "JavaScript SDK for Firecrawl API",
   "main": "dist/index.js",
   "types": "dist/index.d.ts",

package/src/index.ts

@@ -347,6 +347,74 @@ export interface CrawlErrorsResponse {
   robotsBlocked: string[];
 };
 
+/**
+ * Parameters for deep research operations.
+ * Defines options for conducting deep research on a topic.
+ */
+export interface DeepResearchParams {
+  /**
+   * The topic or question to research
+   */
+  topic: string;
+  /**
+   * Maximum depth of research iterations (1-10)
+   * @default 7
+   */
+  maxDepth?: number;
+  /**
+   * Time limit in seconds (30-300)
+   * @default 270
+   */
+  timeLimit?: number;
+  /**
+   * Experimental flag for streaming steps
+   */
+  __experimental_streamSteps?: boolean;
+}
+
+/**
+ * Response interface for deep research operations.
+ */
+export interface DeepResearchResponse {
+  success: boolean;
+  id: string;
+}
+
+/**
+ * Status response interface for deep research operations.
+ */
+export interface DeepResearchStatusResponse {
+  success: boolean;
+  data: {
+    findings: Array<{
+      text: string;
+      source: string;
+    }>;
+    finalAnalysis: string;
+    analysis: string;
+    completedSteps: number;
+    totalSteps: number;
+  };
+  status: "processing" | "completed" | "failed";
+  error?: string;
+  expiresAt: string;
+  currentDepth: number;
+  maxDepth: number;
+  activities: Array<{
+    type: string;
+    status: string;
+    message: string;
+    timestamp: string;
+    depth: number;
+  }>;
+  sources: Array<{
+    url: string;
+    title: string;
+    description: string;
+  }>;
+  summaries: string[];
+}
+
 /**
  * Main class for interacting with the Firecrawl API.
  * Provides methods for scraping, searching, crawling, and mapping web content.
@@ -1280,6 +1348,102 @@ export default class FirecrawlApp {
       );
     }
   }
+
+  /**
+   * Initiates a deep research operation on a given topic and polls until completion.
+   * @param params - Parameters for the deep research operation.
+   * @returns The final research results.
+   */
+  async __deepResearch(params: DeepResearchParams): Promise<DeepResearchStatusResponse | ErrorResponse> {
+    try {
+      const response = await this.__asyncDeepResearch(params);
+      
+      if (!response.success || 'error' in response) {
+        return { success: false, error: 'error' in response ? response.error : 'Unknown error' };
+      }
+
+      if (response.id) {
+        const jobId = response.id;
+        let researchStatus;
+        do {
+          researchStatus = await this.__checkDeepResearchStatus(jobId);
+          
+          if ('error' in researchStatus && !researchStatus.success) {
+            return researchStatus;
+          }
+
+          if (researchStatus.status === "completed") {
+            return researchStatus;
+          } else if (researchStatus.status === "failed") {
+            throw new FirecrawlError(`Research job failed. Error: ${researchStatus.error}`, 500);
+          }
+          await new Promise(resolve => setTimeout(resolve, 1000)); // Polling interval
+        } while (researchStatus.status === "processing");
+      }
+      throw new FirecrawlError(`Failed to start research. No job ID returned.`, 500);
+    } catch (error: any) {
+      throw new FirecrawlError(error.message, 500, error.response?.data?.details);
+    }
+  }
+
+  /**
+   * Initiates a deep research operation on a given topic without polling.
+   * @param params - Parameters for the deep research operation.
+   * @returns The response containing the research job ID.
+   */
+  async __asyncDeepResearch(params: DeepResearchParams): Promise<DeepResearchResponse | ErrorResponse> {
+    const headers = this.prepareHeaders();
+    try {
+      const response: AxiosResponse = await this.postRequest(
+        `${this.apiUrl}/v1/deep-research`,
+        params,
+        headers
+      );
+
+      if (response.status === 200) {
+        return response.data;
+      } else {
+        this.handleError(response, "start deep research");
+      }
+    } catch (error: any) {
+      if (error.response?.data?.error) {
+        throw new FirecrawlError(`Request failed with status code ${error.response.status}. Error: ${error.response.data.error} ${error.response.data.details ? ` - ${JSON.stringify(error.response.data.details)}` : ''}`, error.response.status);
+      } else {
+        throw new FirecrawlError(error.message, 500);
+      }
+    }
+    return { success: false, error: "Internal server error." };
+  }
+
+  /**
+   * Checks the status of a deep research operation.
+   * @param id - The ID of the deep research operation.
+   * @returns The current status and results of the research operation.
+   */
+  async __checkDeepResearchStatus(id: string): Promise<DeepResearchStatusResponse | ErrorResponse> {
+    const headers = this.prepareHeaders();
+    try {
+      const response: AxiosResponse = await this.getRequest(
+        `${this.apiUrl}/v1/deep-research/${id}`,
+        headers
+      );
+
+      if (response.status === 200) {
+        return response.data;
+      } else if (response.status === 404) {
+        throw new FirecrawlError("Deep research job not found", 404);
+      } else {
+        this.handleError(response, "check deep research status");
+      }
+    } catch (error: any) {
+      if (error.response?.data?.error) {
+        throw new FirecrawlError(`Request failed with status code ${error.response.status}. Error: ${error.response.data.error} ${error.response.data.details ? ` - ${JSON.stringify(error.response.data.details)}` : ''}`, error.response.status);
+      } else {
+        throw new FirecrawlError(error.message, 500);
+      }
+    }
+    return { success: false, error: "Internal server error." };
+  }
 }
 
 interface CrawlWatcherEvents {