@mendable/firecrawl-js 1.16.0 → 1.18.0-beta.1

package/dist/index.cjs

@@ -647,7 +647,8 @@ var FirecrawlApp = class {
                 success: true,
                 data: extractStatus.data,
                 warning: extractStatus.warning,
-                error: extractStatus.error
+                error: extractStatus.error,
+                sources: extractStatus?.sources || void 0
               };
             } else {
               throw new FirecrawlError(`Failed to extract data. Error: ${extractStatus.error}`, statusResponse.status);
@@ -850,6 +851,61 @@ var FirecrawlApp = class {
       );
     }
   }
+  /**
+   * Initiates a deep research operation on a given topic.
+   * @param params - Parameters for the deep research operation.
+   * @returns The response containing the research job ID.
+   */
+  async __deepResearch(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

@@ -244,6 +244,7 @@ interface ExtractParams<LLMSchema extends zt.ZodSchema = any> {
     enableWebSearch?: boolean;
     includeSubdomains?: boolean;
     origin?: string;
+    showSources?: boolean;
 }
 /**
  * Response interface for extracting information from URLs.
@@ -254,6 +255,7 @@ interface ExtractResponse<LLMSchema extends zt.ZodSchema = any> {
     data: LLMSchema;
     error?: string;
     warning?: string;
+    sources?: string[];
 }
 /**
  * Error response interface.
@@ -315,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.
@@ -489,6 +556,18 @@ 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.
+     * @param params - Parameters for the deep research operation.
+     * @returns The response containing the research job ID.
+     */
+    __deepResearch(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>>;
@@ -511,4 +590,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

@@ -244,6 +244,7 @@ interface ExtractParams<LLMSchema extends zt.ZodSchema = any> {
     enableWebSearch?: boolean;
     includeSubdomains?: boolean;
     origin?: string;
+    showSources?: boolean;
 }
 /**
  * Response interface for extracting information from URLs.
@@ -254,6 +255,7 @@ interface ExtractResponse<LLMSchema extends zt.ZodSchema = any> {
     data: LLMSchema;
     error?: string;
     warning?: string;
+    sources?: string[];
 }
 /**
  * Error response interface.
@@ -315,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.
@@ -489,6 +556,18 @@ 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.
+     * @param params - Parameters for the deep research operation.
+     * @returns The response containing the research job ID.
+     */
+    __deepResearch(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>>;
@@ -511,4 +590,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

@@ -611,7 +611,8 @@ var FirecrawlApp = class {
                 success: true,
                 data: extractStatus.data,
                 warning: extractStatus.warning,
-                error: extractStatus.error
+                error: extractStatus.error,
+                sources: extractStatus?.sources || void 0
               };
             } else {
               throw new FirecrawlError(`Failed to extract data. Error: ${extractStatus.error}`, statusResponse.status);
@@ -814,6 +815,61 @@ var FirecrawlApp = class {
       );
     }
   }
+  /**
+   * Initiates a deep research operation on a given topic.
+   * @param params - Parameters for the deep research operation.
+   * @returns The response containing the research job ID.
+   */
+  async __deepResearch(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.16.0",
+  "version": "1.18.0-beta.1",
   "description": "JavaScript SDK for Firecrawl API",
   "main": "dist/index.js",
   "types": "dist/index.d.ts",

package/src/index.ts

@@ -262,6 +262,7 @@ export interface ExtractParams<LLMSchema extends zt.ZodSchema = any> {
   enableWebSearch?: boolean;
   includeSubdomains?: boolean;
   origin?: string;
+  showSources?: boolean;
 }
 
 /**
@@ -273,6 +274,7 @@ export interface ExtractResponse<LLMSchema extends zt.ZodSchema = any> {
   data: LLMSchema;
   error?: string;
   warning?: string;
+  sources?: string[];
 }
 
 /**
@@ -345,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.
@@ -1041,7 +1111,8 @@ export default class FirecrawlApp {
                 success: true,
                 data: extractStatus.data,
                 warning: extractStatus.warning,
-                error: extractStatus.error
+                error: extractStatus.error,
+                sources: extractStatus?.sources || undefined,
               };
             } else {
               throw new FirecrawlError(`Failed to extract data. Error: ${extractStatus.error}`, statusResponse.status);
@@ -1277,6 +1348,65 @@ export default class FirecrawlApp {
       );
     }
   }
+
+  /**
+   * Initiates a deep research operation on a given topic.
+   * @param params - Parameters for the deep research operation.
+   * @returns The response containing the research job ID.
+   */
+  async __deepResearch(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 {