@mendable/firecrawl-js 0.0.35 → 1.0.0

package/tsconfig.json

@@ -11,7 +11,7 @@
     // "disableReferencedProjectLoad": true,             /* Reduce the number of projects loaded automatically by TypeScript. */
 
     /* Language and Environment */
-    "target": "es2016",                                  /* Set the JavaScript language version for emitted JavaScript and include compatible library declarations. */
+    "target": "es2020",                                  /* Set the JavaScript language version for emitted JavaScript and include compatible library declarations. */
     // "lib": [],                                        /* Specify a set of bundled library declaration files that describe the target runtime environment. */
     // "jsx": "preserve",                                /* Specify what JSX code is generated. */
     // "experimentalDecorators": true,                   /* Enable experimental support for legacy experimental decorators. */
@@ -25,9 +25,9 @@
     // "moduleDetection": "auto",                        /* Control what method is used to detect module-format JS files. */
 
     /* Modules */
-    "module": "NodeNext",                                /* Specify what module code is generated. */
+    "module": "commonjs",                                /* Specify what module code is generated. */
     "rootDir": "./src",                                  /* Specify the root folder within your source files. */
-    "moduleResolution": "nodenext",                     /* Specify how TypeScript looks up a file from a given module specifier. */
+    "moduleResolution": "node",                     /* Specify how TypeScript looks up a file from a given module specifier. */
     // "baseUrl": "./",                                  /* Specify the base directory to resolve non-relative module names. */
     // "paths": {},                                      /* Specify a set of entries that re-map imports to additional lookup locations. */
     // "rootDirs": [],                                   /* Allow multiple folders to be treated as one when resolving modules. */

package/types/index.d.ts

@@ -2,13 +2,18 @@ import { AxiosResponse, AxiosRequestHeaders } from "axios";
 import { z } from "zod";
 /**
  * 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 version - API version, either 'v0' or 'v1'.
  */
 export interface FirecrawlAppConfig {
     apiKey?: string | null;
     apiUrl?: string | null;
+    version?: "v0" | "v1";
 }
 /**
  * Metadata for a Firecrawl document.
+ * Includes various optional properties for document metadata.
  */
 export interface FirecrawlDocumentMetadata {
     title?: string;
@@ -41,14 +46,37 @@ export interface FirecrawlDocumentMetadata {
     articleTag?: string;
     articleSection?: string;
     sourceURL?: string;
+    statusCode?: number;
+    error?: string;
+    [key: string]: any;
+}
+/**
+ * Metadata for a Firecrawl document on v0.
+ * Similar to FirecrawlDocumentMetadata but includes properties specific to API version v0.
+ */
+export interface FirecrawlDocumentMetadataV0 {
     pageStatusCode?: number;
     pageError?: string;
     [key: string]: any;
 }
 /**
  * Document interface for Firecrawl.
+ * Represents a document retrieved or processed by Firecrawl.
  */
 export interface FirecrawlDocument {
+    url?: string;
+    markdown?: string;
+    html?: string;
+    rawHtml?: string;
+    links?: string[];
+    screenshot?: string;
+    metadata: FirecrawlDocumentMetadata;
+}
+/**
+ * Document interface for Firecrawl on v0.
+ * Represents a document specifically for API version v0 with additional properties.
+ */
+export interface FirecrawlDocumentV0 {
     id?: string;
     url?: string;
     content: string;
@@ -58,132 +86,283 @@ export interface FirecrawlDocument {
     createdAt?: Date;
     updatedAt?: Date;
     type?: string;
-    metadata: FirecrawlDocumentMetadata;
+    metadata: FirecrawlDocumentMetadataV0;
     childrenLinks?: string[];
     provider?: string;
     warning?: string;
     index?: number;
 }
+/**
+ * Parameters for scraping operations.
+ * Defines the options and configurations available for scraping web content.
+ */
+export interface ScrapeParams {
+    formats: ("markdown" | "html" | "rawHtml" | "content" | "links" | "screenshot")[];
+    headers?: Record<string, string>;
+    includeTags?: string[];
+    excludeTags?: string[];
+    onlyMainContent?: boolean;
+    screenshotMode?: "desktop" | "full-desktop" | "mobile" | "full-mobile";
+    waitFor?: number;
+    timeout?: number;
+}
+/**
+ * Parameters for scraping operations on v0.
+ * Includes page and extractor options specific to API version v0.
+ */
+export interface ScrapeParamsV0 {
+    pageOptions?: {
+        headers?: Record<string, string>;
+        includeHtml?: boolean;
+        includeRawHtml?: boolean;
+        onlyIncludeTags?: string[];
+        onlyMainContent?: boolean;
+        removeTags?: string[];
+        replaceAllPathsWithAbsolutePaths?: boolean;
+        screenshot?: boolean;
+        fullPageScreenshot?: boolean;
+        waitFor?: number;
+    };
+    extractorOptions?: {
+        mode?: "markdown" | "llm-extraction" | "llm-extraction-from-raw-html" | "llm-extraction-from-markdown";
+        extractionPrompt?: string;
+        extractionSchema?: Record<string, any> | z.ZodSchema | any;
+    };
+    timeout?: number;
+}
 /**
  * Response interface for scraping operations.
+ * Defines the structure of the response received after a scraping operation.
  */
-export interface ScrapeResponse {
+export interface ScrapeResponse extends FirecrawlDocument {
     success: boolean;
-    data?: FirecrawlDocument;
+    warning?: string;
     error?: string;
 }
 /**
- * Response interface for searching operations.
+ * Response interface for scraping operations on v0.
+ * Similar to ScrapeResponse but tailored for responses from API version v0.
  */
-export interface SearchResponse {
+export interface ScrapeResponseV0 {
     success: boolean;
-    data?: FirecrawlDocument[];
+    data?: FirecrawlDocumentV0;
     error?: string;
 }
+/**
+ * Parameters for crawling operations.
+ * Includes options for both scraping and mapping during a crawl.
+ */
+export interface CrawlParams {
+    scrapeOptions?: ScrapeParams;
+    crawlerOptions?: {
+        includePaths?: string[];
+        excludePaths?: string[];
+        maxDepth?: number;
+        limit?: number;
+        allowBackwardLinks?: boolean;
+        allowExternalLinks?: boolean;
+        ignoreSitemap?: boolean;
+    };
+}
+/**
+ * Parameters for crawling operations on v0.
+ * Tailored for API version v0, includes specific options for crawling.
+ */
+export interface CrawlParamsV0 {
+    crawlerOptions?: {
+        includes?: string[];
+        excludes?: string[];
+        generateImgAltText?: boolean;
+        returnOnlyUrls?: boolean;
+        maxDepth?: number;
+        mode?: "default" | "fast";
+        ignoreSitemap?: boolean;
+        limit?: number;
+        allowBackwardCrawling?: boolean;
+        allowExternalContentLinks?: boolean;
+    };
+    pageOptions?: {
+        headers?: Record<string, string>;
+        includeHtml?: boolean;
+        includeRawHtml?: boolean;
+        onlyIncludeTags?: string[];
+        onlyMainContent?: boolean;
+        removeTags?: string[];
+        replaceAllPathsWithAbsolutePaths?: boolean;
+        screenshot?: boolean;
+        fullPageScreenshot?: boolean;
+        waitFor?: number;
+    };
+}
 /**
  * Response interface for crawling operations.
+ * Defines the structure of the response received after initiating a crawl.
  */
 export interface CrawlResponse {
+    id?: string;
+    url?: string;
     success: boolean;
+    error?: string;
+}
+/**
+ * Response interface for crawling operations on v0.
+ * Similar to CrawlResponse but tailored for responses from API version v0.
+ */
+export interface CrawlResponseV0 {
     jobId?: string;
-    data?: FirecrawlDocument[];
+    success: boolean;
     error?: string;
 }
 /**
  * Response interface for job status checks.
+ * Provides detailed status of a crawl job including progress and results.
  */
-export interface JobStatusResponse {
+export interface CrawlStatusResponse {
+    success: boolean;
+    total: number;
+    completed: number;
+    creditsUsed: number;
+    expiresAt: Date;
+    status: "scraping" | "completed" | "failed";
+    next: string;
+    data?: FirecrawlDocument[];
+    error?: string;
+}
+/**
+ * Response interface for job status checks on v0.
+ * Tailored for API version v0, provides status and partial data of a crawl job.
+ */
+export interface CrawlStatusResponseV0 {
     success: boolean;
     status: string;
     current?: number;
     current_url?: string;
     current_step?: string;
     total?: number;
-    jobId?: string;
-    data?: FirecrawlDocument[];
-    partial_data?: FirecrawlDocument[];
+    data?: FirecrawlDocumentV0[];
+    partial_data?: FirecrawlDocumentV0[];
     error?: string;
 }
 /**
- * Generic parameter interface.
+ * Parameters for mapping operations.
+ * Defines options for mapping URLs during a crawl.
  */
-export interface Params {
-    [key: string]: any;
-    extractorOptions?: {
-        extractionSchema: z.ZodSchema | any;
-        mode?: "llm-extraction";
-        extractionPrompt?: string;
+export interface MapParams {
+    includePaths?: string[];
+    excludePaths?: string[];
+    maxDepth?: number;
+    limit?: number;
+    allowBackwardLinks?: boolean;
+    allowExternalLinks?: boolean;
+    ignoreSitemap?: boolean;
+}
+/**
+ * Response interface for mapping operations.
+ * Defines the structure of the response received after a mapping operation.
+ */
+export interface MapResponse {
+    success: boolean;
+    links?: string[];
+    error?: string;
+}
+/**
+ * Parameters for searching operations on v0.
+ * Tailored for API version v0, includes specific options for searching content.
+ */
+export interface SearchParamsV0 {
+    pageOptions?: {
+        onlyMainContent?: boolean;
+        fetchPageContent?: boolean;
+        includeHtml?: boolean;
+        includeRawHtml?: boolean;
     };
+    searchOptions?: {
+        limit?: number;
+    };
+}
+/**
+ * Response interface for searching operations on v0.
+ * Defines the structure of the response received after a search operation on v0.
+ */
+export interface SearchResponseV0 {
+    success: boolean;
+    data?: FirecrawlDocumentV0[];
+    error?: string;
 }
 /**
  * Main class for interacting with the Firecrawl API.
+ * Provides methods for scraping, searching, crawling, and mapping web content.
  */
-export default class FirecrawlApp {
+export default class FirecrawlApp<T extends "v0" | "v1"> {
     private apiKey;
     private apiUrl;
+    version: T;
     /**
      * Initializes a new instance of the FirecrawlApp class.
-     * @param {FirecrawlAppConfig} config - Configuration options for the FirecrawlApp instance.
+     * @param config - Configuration options for the FirecrawlApp instance.
      */
-    constructor({ apiKey, apiUrl }: FirecrawlAppConfig);
+    constructor({ apiKey, apiUrl, version }: FirecrawlAppConfig);
     /**
      * Scrapes a URL using the Firecrawl API.
-     * @param {string} url - The URL to scrape.
-     * @param {Params | null} params - Additional parameters for the scrape request.
-     * @returns {Promise<ScrapeResponse>} The response from the scrape operation.
+     * @param url - The URL to scrape.
+     * @param params - Additional parameters for the scrape request.
+     * @returns The response from the scrape operation.
      */
-    scrapeUrl(url: string, params?: Params | null): Promise<ScrapeResponse>;
+    scrapeUrl(url: string, params?: ScrapeParams | ScrapeParamsV0): Promise<this['version'] extends 'v0' ? ScrapeResponseV0 : ScrapeResponse>;
     /**
      * Searches for a query using the Firecrawl API.
-     * @param {string} query - The query to search for.
-     * @param {Params | null} params - Additional parameters for the search request.
-     * @returns {Promise<SearchResponse>} The response from the search operation.
+     * @param query - The query to search for.
+     * @param params - Additional parameters for the search request.
+     * @returns The response from the search operation.
      */
-    search(query: string, params?: Params | null): Promise<SearchResponse>;
+    search(query: string, params?: SearchParamsV0): Promise<SearchResponseV0>;
     /**
      * Initiates a crawl job for a URL using the Firecrawl API.
-     * @param {string} url - The URL to crawl.
-     * @param {Params | null} params - Additional parameters for the crawl request.
-     * @param {boolean} waitUntilDone - Whether to wait for the crawl job to complete.
-     * @param {number} pollInterval - Time in seconds for job status checks.
-     * @param {string} idempotencyKey - Optional idempotency key for the request.
-     * @returns {Promise<CrawlResponse | any>} The response from the crawl operation.
+     * @param url - The URL to crawl.
+     * @param params - Additional parameters for the crawl request.
+     * @param waitUntilDone - Whether to wait for the crawl job to complete.
+     * @param pollInterval - Time in seconds for job status checks.
+     * @param idempotencyKey - Optional idempotency key for the request.
+     * @returns The response from the crawl operation.
      */
-    crawlUrl(url: string, params?: Params | null, waitUntilDone?: boolean, pollInterval?: number, idempotencyKey?: string): Promise<CrawlResponse | any>;
+    crawlUrl(url: string, params?: this['version'] extends 'v0' ? CrawlParamsV0 : CrawlParams, waitUntilDone?: boolean, pollInterval?: number, idempotencyKey?: string): Promise<this['version'] extends 'v0' ? CrawlResponseV0 | CrawlStatusResponseV0 | FirecrawlDocumentV0[] : CrawlResponse | CrawlStatusResponse>;
     /**
      * Checks the status of a crawl job using the Firecrawl API.
-     * @param {string} jobId - The job ID of the crawl operation.
-     * @returns {Promise<JobStatusResponse>} The response containing the job status.
+     * @param id - The ID of the crawl operation.
+     * @returns The response containing the job status.
      */
-    checkCrawlStatus(jobId: string): Promise<JobStatusResponse>;
+    checkCrawlStatus(id?: string): Promise<this['version'] extends 'v0' ? CrawlStatusResponseV0 : CrawlStatusResponse>;
+    mapUrl(url: string, params?: MapParams): Promise<MapResponse>;
     /**
      * Prepares the headers for an API request.
-     * @returns {AxiosRequestHeaders} The prepared headers.
+     * @param idempotencyKey - Optional key to ensure idempotency.
+     * @returns The prepared headers.
      */
     prepareHeaders(idempotencyKey?: string): AxiosRequestHeaders;
     /**
      * Sends a POST request to the specified URL.
-     * @param {string} url - The URL to send the request to.
-     * @param {Params} data - The data to send in the request.
-     * @param {AxiosRequestHeaders} headers - The headers for the request.
-     * @returns {Promise<AxiosResponse>} The response from the POST request.
+     * @param url - The URL to send the request to.
+     * @param data - The data to send in the request.
+     * @param headers - The headers for the request.
+     * @returns The response from the POST request.
      */
-    postRequest(url: string, data: Params, headers: AxiosRequestHeaders): Promise<AxiosResponse>;
+    postRequest(url: string, data: any, headers: AxiosRequestHeaders): Promise<AxiosResponse>;
     /**
      * Sends a GET request to the specified URL.
-     * @param {string} url - The URL to send the request to.
-     * @param {AxiosRequestHeaders} headers - The headers for the request.
-     * @returns {Promise<AxiosResponse>} The response from the GET request.
+     * @param url - The URL to send the request to.
+     * @param headers - The headers for the request.
+     * @returns The response from the GET request.
      */
     getRequest(url: string, headers: AxiosRequestHeaders): Promise<AxiosResponse>;
     /**
      * Monitors the status of a crawl job until completion or failure.
-     * @param {string} jobId - The job ID of the crawl operation.
-     * @param {AxiosRequestHeaders} headers - The headers for the request.
-     * @param {number} timeout - Timeout in seconds for job status checks.
-     * @returns {Promise<any>} The final job status or data.
+     * @param id - The ID of the crawl operation.
+     * @param headers - The headers for the request.
+     * @param checkInterval - Interval in seconds for job status checks.
+     * @param checkUrl - Optional URL to check the status (used for v1 API)
+     * @returns The final job status or data.
      */
-    monitorJobStatus(jobId: string, headers: AxiosRequestHeaders, checkInterval: number): Promise<any>;
+    monitorJobStatus(id: string, headers: AxiosRequestHeaders, checkInterval: number, checkUrl?: string): Promise<this['version'] extends 'v0' ? CrawlStatusResponseV0 | FirecrawlDocumentV0[] : CrawlStatusResponse>;
     /**
      * Handles errors from API responses.
      * @param {AxiosResponse} response - The response from the API.