firecrawl 4.21.1 → 4.22.1

package/src/v2/client.ts

@@ -32,6 +32,16 @@ import {
   listBrowsers,
 } from "./methods/browser";
 import { getConcurrency, getCreditUsage, getQueueStatus, getTokenUsage, getCreditUsageHistorical, getTokenUsageHistorical } from "./methods/usage";
+import {
+  createMonitor as createMonitorMethod,
+  deleteMonitor as deleteMonitorMethod,
+  getMonitor as getMonitorMethod,
+  getMonitorCheck as getMonitorCheckMethod,
+  listMonitorChecks as listMonitorChecksMethod,
+  listMonitors as listMonitorsMethod,
+  runMonitor as runMonitorMethod,
+  updateMonitor as updateMonitorMethod,
+} from "./methods/monitor";
 import type {
   Document,
   ParseFile,
@@ -60,6 +70,14 @@ import type {
   ScrapeExecuteRequest,
   ScrapeExecuteResponse,
   ScrapeBrowserDeleteResponse,
+  CreateMonitorRequest,
+  ListMonitorChecksOptions,
+  ListMonitorsOptions,
+  Monitor,
+  MonitorCheck,
+  MonitorCheckDetail,
+  GetMonitorCheckOptions,
+  UpdateMonitorRequest,
 } from "./types";
 import { Watcher } from "./watcher";
 import type { WatcherOptions } from "./watcher";
@@ -276,6 +294,73 @@ export class FirecrawlClient {
     return crawlParamsPreview(this.http, url, prompt);
   }
 
+  // Monitor
+  /**
+   * Create a scheduled monitor.
+   */
+  async createMonitor(request: CreateMonitorRequest): Promise<Monitor> {
+    return createMonitorMethod(this.http, request);
+  }
+
+  /**
+   * List monitors for the authenticated team.
+   */
+  async listMonitors(options?: ListMonitorsOptions): Promise<Monitor[]> {
+    return listMonitorsMethod(this.http, options);
+  }
+
+  /**
+   * Get a monitor by id.
+   */
+  async getMonitor(monitorId: string): Promise<Monitor> {
+    return getMonitorMethod(this.http, monitorId);
+  }
+
+  /**
+   * Update a monitor.
+   */
+  async updateMonitor(
+    monitorId: string,
+    request: UpdateMonitorRequest,
+  ): Promise<Monitor> {
+    return updateMonitorMethod(this.http, monitorId, request);
+  }
+
+  /**
+   * Delete a monitor.
+   */
+  async deleteMonitor(monitorId: string): Promise<boolean> {
+    return deleteMonitorMethod(this.http, monitorId);
+  }
+
+  /**
+   * Trigger a manual monitor check.
+   */
+  async runMonitor(monitorId: string): Promise<MonitorCheck> {
+    return runMonitorMethod(this.http, monitorId);
+  }
+
+  /**
+   * List checks for a monitor.
+   */
+  async listMonitorChecks(
+    monitorId: string,
+    options?: ListMonitorChecksOptions,
+  ): Promise<MonitorCheck[]> {
+    return listMonitorChecksMethod(this.http, monitorId, options);
+  }
+
+  /**
+   * Get a monitor check with paginated page results and inline diffs.
+   */
+  async getMonitorCheck(
+    monitorId: string,
+    checkId: string,
+    options?: GetMonitorCheckOptions,
+  ): Promise<MonitorCheckDetail> {
+    return getMonitorCheckMethod(this.http, monitorId, checkId, options);
+  }
+
   // Batch
   /**
    * Start a batch scrape job for multiple URLs (async).

package/src/v2/methods/monitor.ts

@@ -0,0 +1,181 @@
+import {
+  type CreateMonitorRequest,
+  type ListMonitorsOptions,
+  type ListMonitorChecksOptions,
+  type Monitor,
+  type MonitorCheck,
+  type MonitorCheckDetail,
+  type MonitorCheckPage,
+  type GetMonitorCheckOptions,
+  type UpdateMonitorRequest,
+} from "../types";
+import { HttpClient } from "../utils/httpClient";
+import {
+  throwForBadResponse,
+  normalizeAxiosError,
+} from "../utils/errorHandler";
+import { fetchAllPages } from "../utils/pagination";
+
+type ApiResponse<T> = {
+  success: boolean;
+  data?: T;
+  id?: string;
+  error?: string;
+};
+
+function queryString(params?: Record<string, unknown>): string {
+  if (!params) return "";
+  const query = new URLSearchParams();
+  for (const [key, value] of Object.entries(params)) {
+    if (value !== undefined && value !== null) query.set(key, String(value));
+  }
+  const str = query.toString();
+  return str ? `?${str}` : "";
+}
+
+function dataOrThrow<T>(res: { status: number; data?: ApiResponse<T> }, action: string): T {
+  if (res.status !== 200 || !res.data?.success || res.data.data == null) {
+    throwForBadResponse(res as any, action);
+  }
+  return res.data.data;
+}
+
+export async function createMonitor(
+  http: HttpClient,
+  request: CreateMonitorRequest,
+): Promise<Monitor> {
+  try {
+    const res = await http.post<ApiResponse<Monitor>>("/v2/monitor", request as any);
+    return dataOrThrow(res, "create monitor");
+  } catch (err: any) {
+    if (err?.isAxiosError) return normalizeAxiosError(err, "create monitor");
+    throw err;
+  }
+}
+
+export async function listMonitors(
+  http: HttpClient,
+  options?: ListMonitorsOptions,
+): Promise<Monitor[]> {
+  try {
+    const res = await http.get<ApiResponse<Monitor[]>>(
+      `/v2/monitor${queryString(options as Record<string, unknown>)}`,
+    );
+    return dataOrThrow(res, "list monitors");
+  } catch (err: any) {
+    if (err?.isAxiosError) return normalizeAxiosError(err, "list monitors");
+    throw err;
+  }
+}
+
+export async function getMonitor(
+  http: HttpClient,
+  monitorId: string,
+): Promise<Monitor> {
+  try {
+    const res = await http.get<ApiResponse<Monitor>>(`/v2/monitor/${monitorId}`);
+    return dataOrThrow(res, "get monitor");
+  } catch (err: any) {
+    if (err?.isAxiosError) return normalizeAxiosError(err, "get monitor");
+    throw err;
+  }
+}
+
+export async function updateMonitor(
+  http: HttpClient,
+  monitorId: string,
+  request: UpdateMonitorRequest,
+): Promise<Monitor> {
+  try {
+    const res = await http.patch<ApiResponse<Monitor>>(
+      `/v2/monitor/${monitorId}`,
+      request as any,
+    );
+    return dataOrThrow(res, "update monitor");
+  } catch (err: any) {
+    if (err?.isAxiosError) return normalizeAxiosError(err, "update monitor");
+    throw err;
+  }
+}
+
+export async function deleteMonitor(
+  http: HttpClient,
+  monitorId: string,
+): Promise<boolean> {
+  try {
+    const res = await http.delete<ApiResponse<unknown>>(`/v2/monitor/${monitorId}`);
+    if (res.status !== 200 || !res.data?.success) {
+      throwForBadResponse(res, "delete monitor");
+    }
+    return true;
+  } catch (err: any) {
+    if (err?.isAxiosError) return normalizeAxiosError(err, "delete monitor");
+    throw err;
+  }
+}
+
+export async function runMonitor(
+  http: HttpClient,
+  monitorId: string,
+): Promise<MonitorCheck> {
+  try {
+    const res = await http.post<ApiResponse<MonitorCheck>>(
+      `/v2/monitor/${monitorId}/run`,
+      {},
+    );
+    return dataOrThrow(res, "run monitor");
+  } catch (err: any) {
+    if (err?.isAxiosError) return normalizeAxiosError(err, "run monitor");
+    throw err;
+  }
+}
+
+export async function listMonitorChecks(
+  http: HttpClient,
+  monitorId: string,
+  options?: ListMonitorChecksOptions,
+): Promise<MonitorCheck[]> {
+  try {
+    const res = await http.get<ApiResponse<MonitorCheck[]>>(
+      `/v2/monitor/${monitorId}/checks${queryString(options as Record<string, unknown>)}`,
+    );
+    return dataOrThrow(res, "list monitor checks");
+  } catch (err: any) {
+    if (err?.isAxiosError) return normalizeAxiosError(err, "list monitor checks");
+    throw err;
+  }
+}
+
+export async function getMonitorCheck(
+  http: HttpClient,
+  monitorId: string,
+  checkId: string,
+  options?: GetMonitorCheckOptions,
+): Promise<MonitorCheckDetail> {
+  try {
+    const { autoPaginate: _autoPaginate, maxPages: _maxPages, maxResults: _maxResults, maxWaitTime: _maxWaitTime, ...query } = options ?? {};
+    const res = await http.get<ApiResponse<MonitorCheckDetail>>(
+      `/v2/monitor/${monitorId}/checks/${checkId}${queryString(query as Record<string, unknown>)}`,
+    );
+    const detail = dataOrThrow(res, "get monitor check");
+    const next = res.data?.next ?? detail.next ?? null;
+    const auto = options?.autoPaginate ?? true;
+    if (!auto || !next) {
+      return { ...detail, next };
+    }
+
+    return {
+      ...detail,
+      pages: await fetchAllPages<MonitorCheckPage>(
+        http,
+        next,
+        detail.pages || [],
+        options,
+      ),
+      next: null,
+    };
+  } catch (err: any) {
+    if (err?.isAxiosError) return normalizeAxiosError(err, "get monitor check");
+    throw err;
+  }
+}

package/src/v2/types.ts

@@ -52,6 +52,17 @@ export interface AttributesFormat extends Format {
   }>;
 }
 
+export interface QuestionFormat {
+  type: 'question';
+  question: string;
+}
+
+export interface HighlightsFormat {
+  type: 'highlights';
+  query: string;
+}
+
+/** @deprecated Use QuestionFormat or HighlightsFormat instead. */
 export interface QueryFormat {
   type: 'query';
   prompt: string;
@@ -65,6 +76,8 @@ export type FormatOption =
   | ChangeTrackingFormat
   | ScreenshotFormat
   | AttributesFormat
+  | QuestionFormat
+  | HighlightsFormat
   | QueryFormat;
 
 export type ParseFormatString = Exclude<
@@ -81,6 +94,8 @@ export type ParseFormatOption =
   | ParseFormat
   | JsonFormat
   | AttributesFormat
+  | QuestionFormat
+  | HighlightsFormat
   | QueryFormat;
 
 export interface LocationConfig {
@@ -450,6 +465,7 @@ export interface Document {
   }>;
   actions?: Record<string, unknown>;
   answer?: string;
+  highlights?: string;
   warning?: string;
   changeTracking?: Record<string, unknown>;
   branding?: BrandingProfile;
@@ -606,6 +622,154 @@ export interface MapOptions {
   location?: LocationConfig;
 }
 
+export interface MonitorSchedule {
+  cron: string;
+  timezone?: string;
+}
+
+export interface MonitorEmailNotification {
+  enabled?: boolean;
+  recipients?: string[];
+  includeDiffs?: boolean;
+}
+
+export interface MonitorNotification {
+  email?: MonitorEmailNotification;
+}
+
+export interface MonitorWebhookConfig {
+  url: string;
+  headers?: Record<string, string>;
+  metadata?: Record<string, string>;
+  events?: string[];
+}
+
+export interface MonitorScrapeTarget {
+  id?: string;
+  type: 'scrape';
+  urls: string[];
+  scrapeOptions?: ScrapeOptions;
+}
+
+export interface MonitorCrawlTarget {
+  id?: string;
+  type: 'crawl';
+  url: string;
+  crawlOptions?: CrawlOptions;
+  scrapeOptions?: ScrapeOptions;
+}
+
+export type MonitorTarget = MonitorScrapeTarget | MonitorCrawlTarget;
+
+export interface CreateMonitorRequest {
+  name: string;
+  schedule: MonitorSchedule;
+  webhook?: MonitorWebhookConfig;
+  notification?: MonitorNotification;
+  targets: MonitorTarget[];
+  retentionDays?: number;
+}
+
+export interface UpdateMonitorRequest {
+  name?: string;
+  status?: 'active' | 'paused';
+  schedule?: MonitorSchedule;
+  webhook?: MonitorWebhookConfig | null;
+  notification?: MonitorNotification | null;
+  targets?: MonitorTarget[];
+  retentionDays?: number;
+}
+
+export interface MonitorSummary {
+  totalPages: number;
+  same: number;
+  changed: number;
+  new: number;
+  removed: number;
+  error: number;
+}
+
+export interface Monitor {
+  id: string;
+  name: string;
+  status: 'active' | 'paused' | 'deleted';
+  schedule: MonitorSchedule;
+  nextRunAt?: string | null;
+  lastRunAt?: string | null;
+  currentCheckId?: string | null;
+  targets: MonitorTarget[];
+  webhook?: MonitorWebhookConfig | null;
+  notification?: MonitorNotification | null;
+  retentionDays: number;
+  estimatedCreditsPerMonth?: number | null;
+  lastCheckSummary?: MonitorSummary | null;
+  createdAt: string;
+  updatedAt: string;
+}
+
+export interface MonitorCheck {
+  id: string;
+  monitorId: string;
+  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';
+  summary: MonitorSummary;
+  targetResults?: unknown;
+  notificationStatus?: unknown;
+  error?: string | null;
+  createdAt: string;
+  updatedAt: string;
+}
+
+export interface MonitorCheckPage {
+  id: string;
+  targetId: string;
+  url: string;
+  status: 'same' | 'new' | 'changed' | 'removed' | 'error';
+  previousScrapeId?: string | null;
+  currentScrapeId?: string | null;
+  statusCode?: number | null;
+  error?: string | null;
+  metadata?: unknown;
+  diff?: unknown;
+  createdAt: string;
+}
+
+export interface MonitorCheckDetail extends MonitorCheck {
+  pages: MonitorCheckPage[];
+  next?: string | null;
+}
+
+export interface ListMonitorsOptions {
+  limit?: number;
+  offset?: number;
+}
+
+export type ListMonitorChecksOptions = ListMonitorsOptions;
+
+export type GetMonitorCheckOptions = PaginationConfig & {
+  limit?: number;
+  skip?: number;
+  status?: MonitorCheckPage["status"];
+};
+
 export interface ExtractResponse {
   success?: boolean;
   id?: string;

package/src/v2/utils/httpClient.ts

@@ -149,6 +149,20 @@ export class HttpClient {
     return this.request<T>({ method: "delete", url: endpoint, headers });
   }
 
+  patch<T = any>(
+    endpoint: string,
+    body: Record<string, unknown>,
+    options?: RequestOptions,
+  ) {
+    return this.request<T>({
+      method: "patch",
+      url: endpoint,
+      data: body,
+      headers: options?.headers,
+      timeout: options?.timeoutMs,
+    });
+  }
+
   prepareHeaders(idempotencyKey?: string): Record<string, string> {
     const headers: Record<string, string> = {};
     if (idempotencyKey) headers["x-idempotency-key"] = idempotencyKey;

package/src/v2/utils/pagination.ts

@@ -2,14 +2,14 @@ import type { HttpClient } from "../utils/httpClient";
 import type { Document, PaginationConfig } from "../types";
 
 /**
- * Shared helper to follow `next` cursors and aggregate documents with limits.
+ * Shared helper to follow `next` URLs and aggregate paginated result arrays.
  */
-export async function fetchAllPages(
+export async function fetchAllPages<T = Document>(
   http: HttpClient,
   nextUrl: string,
-  initial: Document[],
+  initial: T[],
   pagination?: PaginationConfig
-): Promise<Document[]> {
+): Promise<T[]> {
   const docs = initial.slice();
   let current: string | null = nextUrl;
   let pageCount = 0;
@@ -22,21 +22,24 @@ export async function fetchAllPages(
     if (maxPages != null && pageCount >= maxPages) break;
     if (maxWaitTime != null && (Date.now() - started) / 1000 > maxWaitTime) break;
 
-    let payload: { success: boolean; next?: string | null; data?: Document[] } | null = null;
+    let payload: { success: boolean; next?: string | null; data?: T[] | { pages?: T[]; next?: string | null } } | null = null;
     try {
-      const res = await http.get<{ success: boolean; next?: string | null; data?: Document[] }>(current);
+      const res = await http.get<{ success: boolean; next?: string | null; data?: T[] | { pages?: T[]; next?: string | null } }>(current);
       payload = res.data;
     } catch {
       break; // axios rejects on non-2xx; stop pagination gracefully
     }
     if (!payload?.success) break;
 
-    for (const d of payload.data || []) {
+    const pageData = Array.isArray(payload.data)
+      ? payload.data
+      : payload.data?.pages || [];
+    for (const d of pageData) {
       if (maxResults != null && docs.length >= maxResults) break;
-      docs.push(d as Document);
+      docs.push(d as T);
     }
     if (maxResults != null && docs.length >= maxResults) break;
-    current = (payload.next ?? null) as string | null;
+    current = (payload.next ?? (Array.isArray(payload.data) ? null : payload.data?.next) ?? null) as string | null;
     pageCount += 1;
   }
   return docs;

package/src/v2/utils/validation.ts

@@ -4,6 +4,9 @@ import {
   type JsonFormat,
   type ParseFormatOption,
   type ParseOptions,
+  type QuestionFormat,
+  type HighlightsFormat,
+  type QueryFormat,
   type ScrapeOptions,
   type ScreenshotFormat,
 } from "../types";
@@ -49,6 +52,30 @@ export function ensureValidFormats(formats?: FormatOption[]): void {
       }
       continue;
     }
+    if ((fmt as QuestionFormat).type === "question") {
+      const q = fmt as QuestionFormat;
+      if (typeof q.question !== "string" || q.question.trim().length === 0) {
+        throw new Error("question format requires a non-empty 'question' string");
+      }
+      continue;
+    }
+    if ((fmt as HighlightsFormat).type === "highlights") {
+      const h = fmt as HighlightsFormat;
+      if (typeof h.query !== "string" || h.query.trim().length === 0) {
+        throw new Error("highlights format requires a non-empty 'query' string");
+      }
+      continue;
+    }
+    if ((fmt as QueryFormat).type === "query") {
+      const q = fmt as QueryFormat;
+      if (typeof q.prompt !== "string" || q.prompt.trim().length === 0) {
+        throw new Error("query format requires a non-empty 'prompt' string");
+      }
+      if (q.mode != null && q.mode !== "freeform" && q.mode !== "directQuote") {
+        throw new Error("query format mode must be 'freeform' or 'directQuote'");
+      }
+      continue;
+    }
     if ((fmt as ScreenshotFormat).type === "screenshot") {
       // no-op; already camelCase; validate numeric fields if present
       const s = fmt as ScreenshotFormat;
@@ -116,6 +143,31 @@ export function ensureValidParseFormats(formats?: ParseFormatOption[]): void {
           "The SDK will automatically convert Zod schemas to JSON Schema format."
         );
       }
+      continue;
+    }
+
+    if ((fmt as QuestionFormat).type === "question") {
+      const q = fmt as QuestionFormat;
+      if (typeof q.question !== "string" || q.question.trim().length === 0) {
+        throw new Error("question format requires a non-empty 'question' string");
+      }
+      continue;
+    }
+    if ((fmt as HighlightsFormat).type === "highlights") {
+      const h = fmt as HighlightsFormat;
+      if (typeof h.query !== "string" || h.query.trim().length === 0) {
+        throw new Error("highlights format requires a non-empty 'query' string");
+      }
+      continue;
+    }
+    if ((fmt as QueryFormat).type === "query") {
+      const q = fmt as QueryFormat;
+      if (typeof q.prompt !== "string" || q.prompt.trim().length === 0) {
+        throw new Error("query format requires a non-empty 'prompt' string");
+      }
+      if (q.mode != null && q.mode !== "freeform" && q.mode !== "directQuote") {
+        throw new Error("query format mode must be 'freeform' or 'directQuote'");
+      }
     }
   }
 }