firecrawl 4.22.2 → 4.24.0

package/dist/index.d.ts

@@ -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';
+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,35 @@ interface ScreenshotFormat {
     };
 }
 interface ChangeTrackingFormat extends Format {
-    type: 'changeTracking';
-    modes: ('git-diff' | 'json')[];
+    type: "changeTracking";
+    modes: ("git-diff" | "json")[];
     schema?: Record<string, unknown>;
     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'>;
+type ParseFormatString = Exclude<FormatString, "screenshot" | "changeTracking" | "branding" | "audio" | "video">;
 interface ParseFormat {
     type: ParseFormatString;
 }
@@ -65,12 +65,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 +79,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 +119,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 +130,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 +148,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 +166,7 @@ interface AgentWebhookConfig {
     events?: AgentWebhookEvent[];
 }
 interface BrandingProfile {
-    colorScheme?: 'light' | 'dark';
+    colorScheme?: "light" | "dark";
     logo?: string | null;
     fonts?: Array<{
         family: string;
@@ -283,8 +283,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 +327,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;
@@ -347,6 +347,7 @@ interface Document {
     images?: string[];
     screenshot?: string;
     audio?: string;
+    video?: string;
     attributes?: Array<{
         selector: string;
         attribute: string;
@@ -398,14 +399,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;
@@ -422,7 +423,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;
@@ -446,7 +447,7 @@ interface CrawlResponse$1 {
 }
 interface CrawlJob {
     id: string;
-    status: 'scraping' | 'completed' | 'failed' | 'cancelled';
+    status: "scraping" | "completed" | "failed" | "cancelled";
     total: number;
     completed: number;
     creditsUsed?: number;
@@ -472,7 +473,7 @@ interface BatchScrapeResponse$1 {
 }
 interface BatchScrapeJob {
     id: string;
-    status: 'scraping' | 'completed' | 'failed' | 'cancelled';
+    status: "scraping" | "completed" | "failed" | "cancelled";
     completed: number;
     total: number;
     creditsUsed?: number;
@@ -485,7 +486,7 @@ interface MapData {
 }
 interface MapOptions {
     search?: string;
-    sitemap?: 'only' | 'include' | 'skip';
+    sitemap?: "only" | "include" | "skip";
     includeSubdomains?: boolean;
     ignoreQueryParameters?: boolean;
     limit?: number;
@@ -514,13 +515,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;
@@ -536,7 +537,7 @@ interface CreateMonitorRequest {
 }
 interface UpdateMonitorRequest {
     name?: string;
-    status?: 'active' | 'paused';
+    status?: "active" | "paused";
     schedule?: MonitorSchedule;
     webhook?: MonitorWebhookConfig | null;
     notification?: MonitorNotification | null;
@@ -554,7 +555,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;
@@ -571,15 +572,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;
@@ -587,17 +588,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 {
@@ -617,7 +651,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;
@@ -634,15 +668,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;
@@ -715,7 +749,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;
@@ -958,6 +992,7 @@ declare class FirecrawlClient {
      * @param file File payload (data, filename, optional contentType).
      * @param options Optional parse options (formats, parsers, etc.).
      *                Note: parse does not support changeTracking, screenshot, branding,
+     *                audio, video,
      *                actions, waitFor, location, or mobile options.
      * @returns Parsed document with requested formats.
      */
@@ -2109,4 +2144,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 };

package/dist/index.js

@@ -1,6 +1,6 @@
 import {
   require_package
-} from "./chunk-HGRZHWZU.js";
+} from "./chunk-C6HAA76K.js";
 
 // src/v2/utils/httpClient.ts
 import axios from "axios";
@@ -302,6 +302,9 @@ function ensureValidParseFormats(formats) {
       if (fmt === "branding") {
         throw new Error("parse does not support branding format");
       }
+      if (fmt === "audio" || fmt === "video") {
+        throw new Error(`parse does not support ${fmt} format`);
+      }
       continue;
     }
     const type = fmt.type;
@@ -314,6 +317,9 @@ function ensureValidParseFormats(formats) {
     if (type === "branding") {
       throw new Error("parse does not support branding format");
     }
+    if (type === "audio" || type === "video") {
+      throw new Error(`parse does not support ${type} format`);
+    }
     if (fmt.type === "json") {
       const j = fmt;
       if (!j.prompt && !j.schema) {
@@ -2036,7 +2042,7 @@ var FirecrawlApp = class {
       if (typeof process !== "undefined" && process.env && process.env.npm_package_version) {
         return process.env.npm_package_version;
       }
-      const packageJson = await import("./package-WSP46L7M.js");
+      const packageJson = await import("./package-7NEHWGT6.js");
       return packageJson.default.version;
     } catch (error) {
       const isTest = typeof process !== "undefined" && (process.env.JEST_WORKER_ID != null || false);

package/dist/{package-WSP46L7M.js → package-7NEHWGT6.js}

@@ -1,4 +1,4 @@
 import {
   require_package
-} from "./chunk-HGRZHWZU.js";
+} from "./chunk-C6HAA76K.js";
 export default require_package();

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "firecrawl",
-  "version": "4.22.2",
+  "version": "4.24.0",
   "description": "JavaScript SDK for Firecrawl API",
   "main": "dist/index.js",
   "types": "dist/index.d.ts",

package/src/__tests__/unit/v2/parse.unit.test.ts

@@ -38,6 +38,24 @@ describe("v2.parse unit", () => {
     ).rejects.toThrow("parse does not support changeTracking format");
   });
 
+  test("rejects video format before making requests", async () => {
+    const client = new FirecrawlClient({
+      apiKey: "test-key",
+      apiUrl: "https://localhost:3002",
+    });
+
+    await expect(
+      client.parse(
+        {
+          data: Buffer.from("<html></html>"),
+          filename: "upload.html",
+          contentType: "text/html",
+        },
+        { formats: ["video" as any] },
+      ),
+    ).rejects.toThrow("parse does not support video format");
+  });
+
   test("rejects lockdown option before making requests", async () => {
     const client = new FirecrawlClient({
       apiKey: "test-key",

package/src/__tests__/unit/v2/validation.test.ts

@@ -9,6 +9,11 @@ describe("v2 utils: validation", () => {
     expect(() => ensureValidFormats(formats)).toThrow(/json format must be an object/i);
   });
 
+  test("ensureValidFormats: accepts video string format", () => {
+    const formats: FormatOption[] = ["markdown", "video"];
+    expect(() => ensureValidFormats(formats)).not.toThrow();
+  });
+
   test("ensureValidFormats: json format requires prompt or schema", () => {
     // Valid cases - should not throw
     const valid1: FormatOption[] = [{ type: "json", prompt: "p" } as any];

package/src/v2/client.ts

@@ -204,6 +204,7 @@ export class FirecrawlClient {
    * @param file File payload (data, filename, optional contentType).
    * @param options Optional parse options (formats, parsers, etc.).
    *                Note: parse does not support changeTracking, screenshot, branding,
+   *                audio, video,
    *                actions, waitFor, location, or mobile options.
    * @returns Parsed document with requested formats.
    */