Supercharge your AI agents with data from the web and beyond. Building the library for superintelligence. 🔥
TypeScript aiai-agentsai-crawlerai-scrapingai-searchcrawlerdata-extractionhtml-to-markdownllmmarkdownscraperscrapingweb-crawlerweb-dataweb-data-extractionweb-scraperweb-scrapingweb-searchwebscraping
feat(sdk): type MonitorCheckPage.diff and add snapshot field
Developers Digest0a34d9f40fc7
diff --git a/apps/js-sdk/firecrawl/src/v2/types.ts b/apps/js-sdk/firecrawl/src/v2/types.tsindex 14f5cc322..0558253ec 100644--- a/apps/js-sdk/firecrawl/src/v2/types.ts+++ b/apps/js-sdk/firecrawl/src/v2/types.ts@@ -1,19 +1,19 @@-import type { ZodTypeAny } from 'zod';+import type { ZodTypeAny } from "zod";// Public types for Firecrawl JS/TS SDK v2 (camelCase only)export type FormatString =- | 'markdown'- | 'html'- | 'rawHtml'- | 'links'- | 'images'- | 'screenshot'- | 'summary'- | 'changeTracking'- | 'json'- | 'attributes'- | 'branding'- | 'audio';+ | "markdown"+ | "html"+ | "rawHtml"+ | "links"+ | "images"+ | "screenshot"+ | "summary"+ | "changeTracking"+ | "json"+ | "attributes"+ | "branding"+ | "audio";export interface Viewport {width: number;@@ -25,27 +25,27 @@ export interface Format {}export interface JsonFormat extends Format {- type: 'json';+ type: "json";prompt?: string;schema?: Record<string, unknown> | ZodTypeAny;}export interface ScreenshotFormat {- type: 'screenshot';+ type: "screenshot";fullPage?: boolean;quality?: number;viewport?: Viewport | { width: number; height: number };}export interface ChangeTrackingFormat extends Format {- type: 'changeTracking';- modes: ('git-diff' | 'json')[];+ type: "changeTracking";+ modes: ("git-diff" | "json")[];schema?: Record<string, unknown>;prompt?: string;tag?: string;}export interface AttributesFormat extends Format {- type: 'attributes';+ type: "attributes";selectors: Array<{selector: string;attribute: string;@@ -53,20 +53,20 @@ export interface AttributesFormat extends Format {}export interface QuestionFormat {- type: 'question';+ type: "question";question: string;}export interface HighlightsFormat {- type: 'highlights';+ type: "highlights";query: string;}/** @deprecated Use QuestionFormat or HighlightsFormat instead. */export interface QueryFormat {- type: 'query';+ type: "query";prompt: string;- mode?: 'freeform' | 'directQuote';+ mode?: "freeform" | "directQuote";}export type FormatOption =@@ -82,7 +82,7 @@ export type FormatOption =export type ParseFormatString = Exclude<FormatString,- 'screenshot' | 'changeTracking' | 'branding'+ "screenshot" | "changeTracking" | "branding">;export interface ParseFormat {@@ -104,62 +104,62 @@ export interface LocationConfig {}export interface WaitAction {- type: 'wait';+ type: "wait";milliseconds?: number;selector?: string;}export interface ScreenshotAction {- type: 'screenshot';+ type: "screenshot";fullPage?: boolean;quality?: number;viewport?: Viewport | { width: number; height: number };}export interface ClickAction {- type: 'click';+ type: "click";selector: string;}export interface WriteAction {- type: 'write';+ type: "write";text: string;}export interface PressAction {- type: 'press';+ type: "press";key: string;}export interface ScrollAction {- type: 'scroll';- direction: 'up' | 'down';+ type: "scroll";+ direction: "up" | "down";selector?: string;}export interface ScrapeAction {- type: 'scrape';+ type: "scrape";}export interface ExecuteJavascriptAction {- type: 'executeJavascript';+ type: "executeJavascript";script: string;}export interface PDFAction {- type: 'pdf';+ type: "pdf";format?:- | 'A0'- | 'A1'- | 'A2'- | 'A3'- | 'A4'- | 'A5'- | 'A6'- | 'Letter'- | 'Legal'- | 'Tabloid'- | 'Ledger';+ | "A0"+ | "A1"+ | "A2"+ | "A3"+ | "A4"+ | "A5"+ | "A6"+ | "Letter"+ | "Legal"+ | "Tabloid"+ | "Ledger";landscape?: boolean;scale?: number;}@@ -184,7 +184,9 @@ export interface ScrapeOptions {timeout?: number;waitFor?: number;mobile?: boolean;- parsers?: Array<string | { type: 'pdf'; mode?: 'fast' | 'auto' | 'ocr'; maxPages?: number }>;+ parsers?: Array<+ string | { type: "pdf"; mode?: "fast" | "auto" | "ocr"; maxPages?: number }+ >;actions?: ActionOption[];location?: LocationConfig;skipTlsVerification?: boolean;@@ -192,7 +194,7 @@ export 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;@@ -221,30 +223,35 @@ export interface ParseFile {export type ParseOptions = Omit<ScrapeOptions,- | 'formats'- | 'waitFor'- | 'mobile'- | 'actions'- | 'location'- | 'maxAge'- | 'minAge'- | 'storeInCache'- | 'lockdown'- | 'proxy'+ | "formats"+ | "waitFor"+ | "mobile"+ | "actions"+ | "location"+ | "maxAge"+ | "minAge"+ | "storeInCache"+ | "lockdown"+ | "proxy"> & {formats?: ParseFormatOption[];- proxy?: 'basic' | 'auto';+ proxy?: "basic" | "auto";};export interface WebhookConfig {url: string;headers?: Record<string, string>;metadata?: Record<string, string>;- events?: Array<'completed' | 'failed' | 'page' | 'started'>;+ events?: Array<"completed" | "failed" | "page" | "started">;}// Agent webhook events differ from crawl: has 'action' and 'cancelled', no 'page'-export type AgentWebhookEvent = 'started' | 'action' | 'completed' | 'failed' | 'cancelled';+export type AgentWebhookEvent =+ | "started"+ | "action"+ | "completed"+ | "failed"+ | "cancelled";export interface AgentWebhookConfig {url: string;@@ -254,7 +261,7 @@ export interface AgentWebhookConfig {}export interface BrandingProfile {- colorScheme?: 'light' | 'dark';+ colorScheme?: "light" | "dark";logo?: string | null;fonts?: Array<{family: string;@@ -376,13 +383,13 @@ export interface BrandingProfile {};personality?: {tone:- | 'professional'- | 'playful'- | 'modern'- | 'traditional'- | 'minimalist'- | 'bold';- energy: 'low' | 'medium' | 'high';+ | "professional"+ | "playful"+ | "modern"+ | "traditional"+ | "minimalist"+ | "bold";+ energy: "low" | "medium" | "high";targetAudience: string;};[key: string]: unknown;@@ -434,8 +441,8 @@ export 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;@@ -516,15 +523,15 @@ export interface SearchData {}export interface CategoryOption {- type: 'github' | 'research' | 'pdf';+ type: "github" | "research" | "pdf";}export interface SearchRequest {query: string;sources?: Array<- 'web' | 'news' | 'images' | { type: 'web' | 'news' | 'images' }+ "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;@@ -542,7 +549,7 @@ export 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;@@ -568,7 +575,7 @@ export interface CrawlResponse {export interface CrawlJob {id: string;- status: 'scraping' | 'completed' | 'failed' | 'cancelled';+ status: "scraping" | "completed" | "failed" | "cancelled";total: number;completed: number;creditsUsed?: number;@@ -597,7 +604,7 @@ export interface BatchScrapeResponse {export interface BatchScrapeJob {id: string;- status: 'scraping' | 'completed' | 'failed' | 'cancelled';+ status: "scraping" | "completed" | "failed" | "cancelled";completed: number;total: number;creditsUsed?: number;@@ -612,7 +619,7 @@ export interface MapData {export interface MapOptions {search?: string;- sitemap?: 'only' | 'include' | 'skip';+ sitemap?: "only" | "include" | "skip";includeSubdomains?: boolean;ignoreQueryParameters?: boolean;limit?: number;@@ -646,14 +653,14 @@ export interface MonitorWebhookConfig {export interface MonitorScrapeTarget {id?: string;- type: 'scrape';+ type: "scrape";urls: string[];scrapeOptions?: ScrapeOptions;}export interface MonitorCrawlTarget {id?: string;- type: 'crawl';+ type: "crawl";url: string;crawlOptions?: CrawlOptions;scrapeOptions?: ScrapeOptions;@@ -672,7 +679,7 @@ export interface CreateMonitorRequest {export interface UpdateMonitorRequest {name?: string;- status?: 'active' | 'paused';+ status?: "active" | "paused";schedule?: MonitorSchedule;webhook?: MonitorWebhookConfig | null;notification?: MonitorNotification | null;@@ -692,7 +699,7 @@ export interface MonitorSummary {export interface Monitor {id: string;name: string;- status: 'active' | 'paused' | 'deleted';+ status: "active" | "paused" | "deleted";schedule: MonitorSchedule;nextRunAt?: string | null;lastRunAt?: string | null;@@ -711,13 +718,13 @@ export interface MonitorCheck {id: string;monitorId: string;status:- | 'queued'- | 'running'- | 'completed'- | 'failed'- | 'partial'- | 'skipped_overlap';- trigger: 'scheduled' | 'manual';+ | "queued"+ | "running"+ | "completed"+ | "failed"+ | "partial"+ | "skipped_overlap";+ trigger: "scheduled" | "manual";scheduledFor?: string | null;startedAt?: string | null;finishedAt?: string | null;@@ -725,11 +732,11 @@ export interface MonitorCheck {reservedCredits?: number | null;actualCredits?: number | null;billingStatus:- | 'not_applicable'- | 'reserved'- | 'confirmed'- | 'released'- | 'failed';+ | "not_applicable"+ | "reserved"+ | "confirmed"+ | "released"+ | "failed";summary: MonitorSummary;targetResults?: unknown;notificationStatus?: unknown;@@ -738,17 +745,48 @@ export interface MonitorCheck {updatedAt: string;}+/** Per-field diff for monitors that requested JSON extraction. */+export 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.+ */+export 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.+ */+export interface MonitorPageSnapshot {+ json?: Record<string, unknown>;+}+export 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;}@@ -773,7 +811,7 @@ export type GetMonitorCheckOptions = PaginationConfig & {export interface ExtractResponse {success?: boolean;id?: string;- status?: 'processing' | 'completed' | 'failed' | 'cancelled';+ status?: "processing" | "completed" | "failed" | "cancelled";data?: unknown;error?: string;warning?: string;@@ -792,16 +830,16 @@ export interface AgentResponse {export 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;}export interface AgentOptions {- model: 'FIRE-1' | 'v3-beta';+ model: "FIRE-1" | "v3-beta";}export interface ConcurrencyCheck {@@ -887,10 +925,10 @@ export class SdkError extends Error {status?: number,code?: string,details?: unknown,- jobId?: string+ jobId?: string,) {super(message);- this.name = 'FirecrawlSdkError';+ this.name = "FirecrawlSdkError";this.status = status;this.code = code;this.details = details;@@ -900,16 +938,20 @@ export class SdkError extends Error {export class JobTimeoutError extends SdkError {timeoutSeconds: number;- constructor(jobId: string, timeoutSeconds: number, jobType: 'batch' | 'crawl' = 'batch') {- const jobTypeLabel = jobType === 'batch' ? 'batch scrape' : 'crawl';+ constructor(+ jobId: string,+ timeoutSeconds: number,+ jobType: "batch" | "crawl" = "batch",+ ) {+ const jobTypeLabel = jobType === "batch" ? "batch scrape" : "crawl";super(`${jobTypeLabel.charAt(0).toUpperCase() + jobTypeLabel.slice(1)} job ${jobId} did not complete within ${timeoutSeconds} seconds`,undefined,- 'JOB_TIMEOUT',+ "JOB_TIMEOUT",undefined,- jobId+ jobId,);- this.name = 'JobTimeoutError';+ this.name = "JobTimeoutError";this.timeoutSeconds = timeoutSeconds;}}diff --git a/apps/python-sdk/firecrawl/v2/types.py b/apps/python-sdk/firecrawl/v2/types.pyindex 00fde19a7..c83e6419b 100644--- a/apps/python-sdk/firecrawl/v2/types.py+++ b/apps/python-sdk/firecrawl/v2/types.py@@ -929,6 +929,28 @@ class MonitorCheck(BaseModel):updated_at: str = Field(alias="updatedAt")+class MonitorPageDiff(BaseModel):+ """Diff payload returned alongside a monitor page.++ Markdown-only monitors populate both `text` (unified diff) and `json`+ (the parseDiff AST). JSON-extraction monitors populate `json` only,+ where `json` is the per-field `{previous, current}` map. Mixed-mode+ monitors (JSON + git-diff) populate both `json` (field diff) and+ `text` (markdown sidecar).+ """+ model_config = {"populate_by_name": True, "extra": "allow"}++ text: Optional[str] = None+ json: Optional[Any] = None # markdown→parseDiff AST | json→field diff+++class MonitorPageSnapshot(BaseModel):+ """Current JSON extraction at this run. JSON / mixed mode only."""+ model_config = {"populate_by_name": True, "extra": "allow"}++ json: Optional[Dict[str, Any]] = None++class MonitorCheckPage(BaseModel):model_config = {"populate_by_name": True, "extra": "allow"}@@ -941,7 +963,8 @@ class MonitorCheckPage(BaseModel):status_code: Optional[int] = Field(default=None, alias="statusCode")error: Optional[str] = Nonemetadata: Optional[Any] = None- diff: Optional[Any] = None+ diff: Optional[MonitorPageDiff] = None+ snapshot: Optional[MonitorPageSnapshot] = Nonecreated_at: str = Field(alias="createdAt")