firecrawl 4.23.0 → 4.24.1

package/README.md

@@ -1,6 +1,6 @@
 # Firecrawl Node SDK
 
-The Firecrawl Node SDK is a library that allows you to easily search, scrape, and interact with the web, and output the data in a format ready for use with language models (LLMs). It provides a simple and intuitive interface for the Firecrawl API.
+The Firecrawl Node SDK is a library that lets you easily search, scrape, and interact with the web for AI agents — returning clean Markdown or structured data your agents can ship with. It provides a simple and intuitive interface for the Firecrawl API.
 
 ## Installation
 

package/dist/{chunk-ZR3KTUEQ.js → chunk-F3RFBUTZ.js}

@@ -8,7 +8,7 @@ var require_package = __commonJS({
   "package.json"(exports, module) {
     module.exports = {
       name: "@mendable/firecrawl-js",
-      version: "4.23.0",
+      version: "4.24.1",
       description: "JavaScript SDK for Firecrawl API",
       main: "dist/index.js",
       types: "dist/index.d.ts",

package/dist/index.cjs

@@ -35,7 +35,7 @@ var require_package = __commonJS({
   "package.json"(exports2, module2) {
     module2.exports = {
       name: "@mendable/firecrawl-js",
-      version: "4.23.0",
+      version: "4.24.1",
       description: "JavaScript SDK for Firecrawl API",
       main: "dist/index.js",
       types: "dist/index.d.ts",

package/dist/index.d.cts

@@ -4,7 +4,7 @@ import { AxiosResponse, AxiosRequestHeaders } from 'axios';
 import { EventEmitter } from 'events';
 import { TypedEventTarget } from 'typescript-event-target';
 
-type FormatString = 'markdown' | 'html' | 'rawHtml' | 'links' | 'images' | 'screenshot' | 'summary' | 'changeTracking' | 'json' | 'attributes' | 'branding' | 'audio' | 'video';
+type FormatString = "markdown" | "html" | "rawHtml" | "links" | "images" | "screenshot" | "summary" | "changeTracking" | "json" | "attributes" | "branding" | "audio" | "video";
 interface Viewport {
     width: number;
     height: number;
@@ -13,12 +13,12 @@ interface Format {
     type: FormatString;
 }
 interface JsonFormat extends Format {
-    type: 'json';
+    type: "json";
     prompt?: string;
     schema?: Record<string, unknown> | ZodTypeAny;
 }
 interface ScreenshotFormat {
-    type: 'screenshot';
+    type: "screenshot";
     fullPage?: boolean;
     quality?: number;
     viewport?: Viewport | {
@@ -27,35 +27,40 @@ interface ScreenshotFormat {
     };
 }
 interface ChangeTrackingFormat extends Format {
-    type: 'changeTracking';
-    modes: ('git-diff' | 'json')[];
-    schema?: Record<string, unknown>;
+    type: "changeTracking";
+    modes: ("git-diff" | "json")[];
+    /**
+     * Either a JSON Schema object or a Zod schema. Zod schemas are
+     * auto-converted to JSON Schema by the SDK before being sent — see
+     * `utils/validation.ts`.
+     */
+    schema?: Record<string, unknown> | ZodTypeAny;
     prompt?: string;
     tag?: string;
 }
 interface AttributesFormat extends Format {
-    type: 'attributes';
+    type: "attributes";
     selectors: Array<{
         selector: string;
         attribute: string;
     }>;
 }
 interface QuestionFormat {
-    type: 'question';
+    type: "question";
     question: string;
 }
 interface HighlightsFormat {
-    type: 'highlights';
+    type: "highlights";
     query: string;
 }
 /** @deprecated Use QuestionFormat or HighlightsFormat instead. */
 interface QueryFormat {
-    type: 'query';
+    type: "query";
     prompt: string;
-    mode?: 'freeform' | 'directQuote';
+    mode?: "freeform" | "directQuote";
 }
 type FormatOption = FormatString | Format | JsonFormat | ChangeTrackingFormat | ScreenshotFormat | AttributesFormat | QuestionFormat | HighlightsFormat | QueryFormat;
-type ParseFormatString = Exclude<FormatString, 'screenshot' | 'changeTracking' | 'branding' | 'audio' | 'video'>;
+type ParseFormatString = Exclude<FormatString, "screenshot" | "changeTracking" | "branding" | "audio" | "video">;
 interface ParseFormat {
     type: ParseFormatString;
 }
@@ -65,12 +70,12 @@ interface LocationConfig$1 {
     languages?: string[];
 }
 interface WaitAction {
-    type: 'wait';
+    type: "wait";
     milliseconds?: number;
     selector?: string;
 }
 interface ScreenshotAction {
-    type: 'screenshot';
+    type: "screenshot";
     fullPage?: boolean;
     quality?: number;
     viewport?: Viewport | {
@@ -79,32 +84,32 @@ interface ScreenshotAction {
     };
 }
 interface ClickAction {
-    type: 'click';
+    type: "click";
     selector: string;
 }
 interface WriteAction {
-    type: 'write';
+    type: "write";
     text: string;
 }
 interface PressAction {
-    type: 'press';
+    type: "press";
     key: string;
 }
 interface ScrollAction {
-    type: 'scroll';
-    direction: 'up' | 'down';
+    type: "scroll";
+    direction: "up" | "down";
     selector?: string;
 }
 interface ScrapeAction {
-    type: 'scrape';
+    type: "scrape";
 }
 interface ExecuteJavascriptAction {
-    type: 'executeJavascript';
+    type: "executeJavascript";
     script: string;
 }
 interface PDFAction {
-    type: 'pdf';
-    format?: 'A0' | 'A1' | 'A2' | 'A3' | 'A4' | 'A5' | 'A6' | 'Letter' | 'Legal' | 'Tabloid' | 'Ledger';
+    type: "pdf";
+    format?: "A0" | "A1" | "A2" | "A3" | "A4" | "A5" | "A6" | "Letter" | "Legal" | "Tabloid" | "Ledger";
     landscape?: boolean;
     scale?: number;
 }
@@ -119,8 +124,8 @@ interface ScrapeOptions {
     waitFor?: number;
     mobile?: boolean;
     parsers?: Array<string | {
-        type: 'pdf';
-        mode?: 'fast' | 'auto' | 'ocr';
+        type: "pdf";
+        mode?: "fast" | "auto" | "ocr";
         maxPages?: number;
     }>;
     actions?: ActionOption[];
@@ -130,7 +135,7 @@ interface ScrapeOptions {
     fastMode?: boolean;
     useMock?: string;
     blockAds?: boolean;
-    proxy?: 'basic' | 'stealth' | 'enhanced' | 'auto' | string;
+    proxy?: "basic" | "stealth" | "enhanced" | "auto" | string;
     maxAge?: number;
     minAge?: number;
     storeInCache?: boolean;
@@ -148,17 +153,17 @@ interface ParseFile {
     filename: string;
     contentType?: string;
 }
-type ParseOptions = Omit<ScrapeOptions, 'formats' | 'waitFor' | 'mobile' | 'actions' | 'location' | 'maxAge' | 'minAge' | 'storeInCache' | 'lockdown' | 'proxy'> & {
+type ParseOptions = Omit<ScrapeOptions, "formats" | "waitFor" | "mobile" | "actions" | "location" | "maxAge" | "minAge" | "storeInCache" | "lockdown" | "proxy"> & {
     formats?: ParseFormatOption[];
-    proxy?: 'basic' | 'auto';
+    proxy?: "basic" | "auto";
 };
 interface WebhookConfig {
     url: string;
     headers?: Record<string, string>;
     metadata?: Record<string, string>;
-    events?: Array<'completed' | 'failed' | 'page' | 'started'>;
+    events?: Array<"completed" | "failed" | "page" | "started">;
 }
-type AgentWebhookEvent = 'started' | 'action' | 'completed' | 'failed' | 'cancelled';
+type AgentWebhookEvent = "started" | "action" | "completed" | "failed" | "cancelled";
 interface AgentWebhookConfig {
     url: string;
     headers?: Record<string, string>;
@@ -166,7 +171,7 @@ interface AgentWebhookConfig {
     events?: AgentWebhookEvent[];
 }
 interface BrandingProfile {
-    colorScheme?: 'light' | 'dark';
+    colorScheme?: "light" | "dark";
     logo?: string | null;
     fonts?: Array<{
         family: string;
@@ -283,8 +288,8 @@ interface BrandingProfile {
         [key: string]: string | undefined;
     };
     personality?: {
-        tone: 'professional' | 'playful' | 'modern' | 'traditional' | 'minimalist' | 'bold';
-        energy: 'low' | 'medium' | 'high';
+        tone: "professional" | "playful" | "modern" | "traditional" | "minimalist" | "bold";
+        energy: "low" | "medium" | "high";
         targetAudience: string;
     };
     [key: string]: unknown;
@@ -327,8 +332,8 @@ interface DocumentMetadata {
     numPages?: number;
     contentType?: string;
     timezone?: string;
-    proxyUsed?: 'basic' | 'stealth';
-    cacheState?: 'hit' | 'miss';
+    proxyUsed?: "basic" | "stealth";
+    cacheState?: "hit" | "miss";
     cachedAt?: string;
     creditsUsed?: number;
     concurrencyLimited?: boolean;
@@ -399,14 +404,14 @@ interface SearchData {
     images?: Array<SearchResultImages | Document>;
 }
 interface CategoryOption {
-    type: 'github' | 'research' | 'pdf';
+    type: "github" | "research" | "pdf";
 }
 interface SearchRequest {
     query: string;
-    sources?: Array<'web' | 'news' | 'images' | {
-        type: 'web' | 'news' | 'images';
+    sources?: Array<"web" | "news" | "images" | {
+        type: "web" | "news" | "images";
     }>;
-    categories?: Array<'github' | 'research' | 'pdf' | CategoryOption>;
+    categories?: Array<"github" | "research" | "pdf" | CategoryOption>;
     includeDomains?: string[];
     excludeDomains?: string[];
     limit?: number;
@@ -423,7 +428,7 @@ interface CrawlOptions {
     excludePaths?: string[] | null;
     includePaths?: string[] | null;
     maxDiscoveryDepth?: number | null;
-    sitemap?: 'skip' | 'include' | 'only';
+    sitemap?: "skip" | "include" | "only";
     ignoreQueryParameters?: boolean;
     deduplicateSimilarURLs?: boolean;
     limit?: number | null;
@@ -447,7 +452,7 @@ interface CrawlResponse$1 {
 }
 interface CrawlJob {
     id: string;
-    status: 'scraping' | 'completed' | 'failed' | 'cancelled';
+    status: "scraping" | "completed" | "failed" | "cancelled";
     total: number;
     completed: number;
     creditsUsed?: number;
@@ -473,7 +478,7 @@ interface BatchScrapeResponse$1 {
 }
 interface BatchScrapeJob {
     id: string;
-    status: 'scraping' | 'completed' | 'failed' | 'cancelled';
+    status: "scraping" | "completed" | "failed" | "cancelled";
     completed: number;
     total: number;
     creditsUsed?: number;
@@ -486,7 +491,7 @@ interface MapData {
 }
 interface MapOptions {
     search?: string;
-    sitemap?: 'only' | 'include' | 'skip';
+    sitemap?: "only" | "include" | "skip";
     includeSubdomains?: boolean;
     ignoreQueryParameters?: boolean;
     limit?: number;
@@ -495,8 +500,21 @@ interface MapOptions {
     origin?: string;
     location?: LocationConfig$1;
 }
+/**
+ * Schedule for a monitor.
+ *
+ * On create/update, provide exactly one of `cron` or `text`:
+ *  - `cron`: a 5-field cron expression (e.g. `"*\u002F30 * * * *"`).
+ *  - `text`: a natural-language schedule (e.g. `"every 30 minutes"`,
+ *    `"hourly"`, `"daily at 9:00"`). Firecrawl normalizes this to a cron
+ *    expression server-side.
+ *
+ * On read, the API always returns the normalized `cron` value, so `cron`
+ * is populated in responses even when the monitor was created with `text`.
+ */
 interface MonitorSchedule {
-    cron: string;
+    cron?: string;
+    text?: string;
     timezone?: string;
 }
 interface MonitorEmailNotification {
@@ -515,13 +533,13 @@ interface MonitorWebhookConfig {
 }
 interface MonitorScrapeTarget {
     id?: string;
-    type: 'scrape';
+    type: "scrape";
     urls: string[];
     scrapeOptions?: ScrapeOptions;
 }
 interface MonitorCrawlTarget {
     id?: string;
-    type: 'crawl';
+    type: "crawl";
     url: string;
     crawlOptions?: CrawlOptions;
     scrapeOptions?: ScrapeOptions;
@@ -537,7 +555,7 @@ interface CreateMonitorRequest {
 }
 interface UpdateMonitorRequest {
     name?: string;
-    status?: 'active' | 'paused';
+    status?: "active" | "paused";
     schedule?: MonitorSchedule;
     webhook?: MonitorWebhookConfig | null;
     notification?: MonitorNotification | null;
@@ -555,7 +573,7 @@ interface MonitorSummary {
 interface Monitor {
     id: string;
     name: string;
-    status: 'active' | 'paused' | 'deleted';
+    status: "active" | "paused" | "deleted";
     schedule: MonitorSchedule;
     nextRunAt?: string | null;
     lastRunAt?: string | null;
@@ -572,15 +590,15 @@ interface Monitor {
 interface MonitorCheck {
     id: string;
     monitorId: string;
-    status: 'queued' | 'running' | 'completed' | 'failed' | 'partial' | 'skipped_overlap';
-    trigger: 'scheduled' | 'manual';
+    status: "queued" | "running" | "completed" | "failed" | "partial" | "skipped_overlap";
+    trigger: "scheduled" | "manual";
     scheduledFor?: string | null;
     startedAt?: string | null;
     finishedAt?: string | null;
     estimatedCredits?: number | null;
     reservedCredits?: number | null;
     actualCredits?: number | null;
-    billingStatus: 'not_applicable' | 'reserved' | 'confirmed' | 'released' | 'failed';
+    billingStatus: "not_applicable" | "reserved" | "confirmed" | "released" | "failed";
     summary: MonitorSummary;
     targetResults?: unknown;
     notificationStatus?: unknown;
@@ -588,17 +606,50 @@ interface MonitorCheck {
     createdAt: string;
     updatedAt: string;
 }
+/** Per-field diff for monitors that requested JSON extraction. */
+interface MonitorJsonFieldDiff {
+    [field: string]: {
+        previous: unknown;
+        current: unknown;
+    };
+}
+/**
+ * Diff payload returned alongside a monitor page when its scrape produced
+ * a change. The shape depends on what the monitor's formats asked for:
+ *
+ *  - markdown-only monitors  → `{ text, json }` where `json` is the
+ *    `parseDiff` AST (a `{ files: [...] }` object).
+ *  - JSON-extraction monitors → `{ json }` where `json` is the per-field
+ *    `{ previous, current }` map.
+ *  - Mixed (JSON + git-diff) monitors → both `text` (markdown sidecar)
+ *    and `json` (field-level diff) are present.
+ */
+interface MonitorPageDiff {
+    text?: string;
+    /** Markdown variants: parseDiff AST. JSON variants: per-field diff. */
+    json?: MonitorJsonFieldDiff | {
+        files: unknown[];
+    };
+}
+/**
+ * Snapshot of the current JSON extraction at this run. Present on JSON
+ * and mixed-mode monitors; absent for markdown-only.
+ */
+interface MonitorPageSnapshot {
+    json?: Record<string, unknown>;
+}
 interface MonitorCheckPage {
     id: string;
     targetId: string;
     url: string;
-    status: 'same' | 'new' | 'changed' | 'removed' | 'error';
+    status: "same" | "new" | "changed" | "removed" | "error";
     previousScrapeId?: string | null;
     currentScrapeId?: string | null;
     statusCode?: number | null;
     error?: string | null;
     metadata?: unknown;
-    diff?: unknown;
+    diff?: MonitorPageDiff | null;
+    snapshot?: MonitorPageSnapshot | null;
     createdAt: string;
 }
 interface MonitorCheckDetail extends MonitorCheck {
@@ -618,7 +669,7 @@ type GetMonitorCheckOptions = PaginationConfig & {
 interface ExtractResponse$1 {
     success?: boolean;
     id?: string;
-    status?: 'processing' | 'completed' | 'failed' | 'cancelled';
+    status?: "processing" | "completed" | "failed" | "cancelled";
     data?: unknown;
     error?: string;
     warning?: string;
@@ -635,15 +686,15 @@ interface AgentResponse {
 }
 interface AgentStatusResponse {
     success: boolean;
-    status: 'processing' | 'completed' | 'failed';
+    status: "processing" | "completed" | "failed";
     error?: string;
     data?: unknown;
-    model?: 'spark-1-pro' | 'spark-1-mini';
+    model?: "spark-1-pro" | "spark-1-mini";
     expiresAt: string;
     creditsUsed?: number;
 }
 interface AgentOptions$1 {
-    model: 'FIRE-1' | 'v3-beta';
+    model: "FIRE-1" | "v3-beta";
 }
 interface ConcurrencyCheck {
     concurrency: number;
@@ -716,7 +767,7 @@ declare class SdkError extends Error {
 }
 declare class JobTimeoutError extends SdkError {
     timeoutSeconds: number;
-    constructor(jobId: string, timeoutSeconds: number, jobType?: 'batch' | 'crawl');
+    constructor(jobId: string, timeoutSeconds: number, jobType?: "batch" | "crawl");
 }
 interface QueueStatusResponse$1 {
     success: boolean;
@@ -2111,4 +2162,4 @@ declare class Firecrawl extends FirecrawlClient {
     get v1(): FirecrawlApp;
 }
 
-export { type ActionOption, type ActiveCrawl, type ActiveCrawlsResponse, type AgentOptions$1 as AgentOptions, type AgentResponse, type AgentStatusResponse, type AgentWebhookConfig, type AgentWebhookEvent, type AttributesFormat, type BatchScrapeJob, type BatchScrapeOptions, type BatchScrapeResponse$1 as BatchScrapeResponse, type BrandingProfile, type BrowserCreateResponse, type BrowserDeleteResponse, type BrowserExecuteResponse, type BrowserListResponse, type BrowserSession, type CategoryOption, type ChangeTrackingFormat, type ClickAction, type ConcurrencyCheck, type CrawlErrorsResponse$1 as CrawlErrorsResponse, type CrawlJob, type CrawlOptions, type CrawlResponse$1 as CrawlResponse, type CreateMonitorRequest, type CreditUsage, type CreditUsageHistoricalPeriod, type CreditUsageHistoricalResponse, type Document, type DocumentMetadata, type ErrorDetails, type ExecuteJavascriptAction, type ExtractResponse$1 as ExtractResponse, Firecrawl, FirecrawlApp as FirecrawlAppV1, FirecrawlClient, type FirecrawlClientOptions, type Format, type FormatOption, type FormatString, type GetMonitorCheckOptions, type HighlightsFormat, JobTimeoutError, type JsonFormat, type ListMonitorChecksOptions, type ListMonitorsOptions, type LocationConfig$1 as LocationConfig, type MapData, type MapOptions, type Monitor, type MonitorCheck, type MonitorCheckDetail, type MonitorCheckPage, type MonitorCrawlTarget, type MonitorEmailNotification, type MonitorNotification, type MonitorSchedule, type MonitorScrapeTarget, type MonitorSummary, type MonitorTarget, type MonitorWebhookConfig, type PDFAction, type PaginationConfig, type ParseFile, type ParseFileData, type ParseFormat, type ParseFormatOption, type ParseFormatString, type ParseOptions, type PressAction, type QueryFormat, type QuestionFormat, type QueueStatusResponse$1 as QueueStatusResponse, type ScrapeAction, type ScrapeBrowserDeleteResponse, type ScrapeExecuteRequest, type ScrapeExecuteResponse, type ScrapeOptions, type ScreenshotAction, type ScreenshotFormat, type ScrollAction, SdkError, type SearchData, type SearchRequest, type SearchResultImages, type SearchResultNews, type SearchResultWeb, type TokenUsage, type TokenUsageHistoricalPeriod, type TokenUsageHistoricalResponse, type UpdateMonitorRequest, type Viewport, type WaitAction, Watcher, type WatcherOptions, type WebhookConfig, type WriteAction, Firecrawl as default };
+export { type ActionOption, type ActiveCrawl, type ActiveCrawlsResponse, type AgentOptions$1 as AgentOptions, type AgentResponse, type AgentStatusResponse, type AgentWebhookConfig, type AgentWebhookEvent, type AttributesFormat, type BatchScrapeJob, type BatchScrapeOptions, type BatchScrapeResponse$1 as BatchScrapeResponse, type BrandingProfile, type BrowserCreateResponse, type BrowserDeleteResponse, type BrowserExecuteResponse, type BrowserListResponse, type BrowserSession, type CategoryOption, type ChangeTrackingFormat, type ClickAction, type ConcurrencyCheck, type CrawlErrorsResponse$1 as CrawlErrorsResponse, type CrawlJob, type CrawlOptions, type CrawlResponse$1 as CrawlResponse, type CreateMonitorRequest, type CreditUsage, type CreditUsageHistoricalPeriod, type CreditUsageHistoricalResponse, type Document, type DocumentMetadata, type ErrorDetails, type ExecuteJavascriptAction, type ExtractResponse$1 as ExtractResponse, Firecrawl, FirecrawlApp as FirecrawlAppV1, FirecrawlClient, type FirecrawlClientOptions, type Format, type FormatOption, type FormatString, type GetMonitorCheckOptions, type HighlightsFormat, JobTimeoutError, type JsonFormat, type ListMonitorChecksOptions, type ListMonitorsOptions, type LocationConfig$1 as LocationConfig, type MapData, type MapOptions, type Monitor, type MonitorCheck, type MonitorCheckDetail, type MonitorCheckPage, type MonitorCrawlTarget, type MonitorEmailNotification, type MonitorJsonFieldDiff, type MonitorNotification, type MonitorPageDiff, type MonitorPageSnapshot, type MonitorSchedule, type MonitorScrapeTarget, type MonitorSummary, type MonitorTarget, type MonitorWebhookConfig, type PDFAction, type PaginationConfig, type ParseFile, type ParseFileData, type ParseFormat, type ParseFormatOption, type ParseFormatString, type ParseOptions, type PressAction, type QueryFormat, type QuestionFormat, type QueueStatusResponse$1 as QueueStatusResponse, type ScrapeAction, type ScrapeBrowserDeleteResponse, type ScrapeExecuteRequest, type ScrapeExecuteResponse, type ScrapeOptions, type ScreenshotAction, type ScreenshotFormat, type ScrollAction, SdkError, type SearchData, type SearchRequest, type SearchResultImages, type SearchResultNews, type SearchResultWeb, type TokenUsage, type TokenUsageHistoricalPeriod, type TokenUsageHistoricalResponse, type UpdateMonitorRequest, type Viewport, type WaitAction, Watcher, type WatcherOptions, type WebhookConfig, type WriteAction, Firecrawl as default };