firecrawl 4.22.0 → 4.22.1

package/dist/{chunk-XWPH5FOQ.js → chunk-WTZQ5IMF.js}

@@ -8,7 +8,7 @@ var require_package = __commonJS({
   "package.json"(exports, module) {
     module.exports = {
       name: "@mendable/firecrawl-js",
-      version: "4.22.0",
+      version: "4.22.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.22.0",
+      version: "4.22.1",
       description: "JavaScript SDK for Firecrawl API",
       main: "dist/index.js",
       types: "dist/index.d.ts",
@@ -368,6 +368,30 @@ function ensureValidFormats(formats) {
       }
       continue;
     }
+    if (fmt.type === "question") {
+      const q = fmt;
+      if (typeof q.question !== "string" || q.question.trim().length === 0) {
+        throw new Error("question format requires a non-empty 'question' string");
+      }
+      continue;
+    }
+    if (fmt.type === "highlights") {
+      const h = fmt;
+      if (typeof h.query !== "string" || h.query.trim().length === 0) {
+        throw new Error("highlights format requires a non-empty 'query' string");
+      }
+      continue;
+    }
+    if (fmt.type === "query") {
+      const q = fmt;
+      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.type === "screenshot") {
       const s = fmt;
       if (s.quality != null && (typeof s.quality !== "number" || s.quality < 0)) {
@@ -427,6 +451,30 @@ function ensureValidParseFormats(formats) {
           "json format schema appears to be a Zod schema's .shape property. Pass the Zod schema directly (e.g., `schema: MySchema`) instead of `schema: MySchema.shape`. The SDK will automatically convert Zod schemas to JSON Schema format."
         );
       }
+      continue;
+    }
+    if (fmt.type === "question") {
+      const q = fmt;
+      if (typeof q.question !== "string" || q.question.trim().length === 0) {
+        throw new Error("question format requires a non-empty 'question' string");
+      }
+      continue;
+    }
+    if (fmt.type === "highlights") {
+      const h = fmt;
+      if (typeof h.query !== "string" || h.query.trim().length === 0) {
+        throw new Error("highlights format requires a non-empty 'query' string");
+      }
+      continue;
+    }
+    if (fmt.type === "query") {
+      const q = fmt;
+      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'");
+      }
     }
   }
 }

package/dist/index.d.cts

@@ -40,17 +40,26 @@ interface AttributesFormat extends Format {
         attribute: string;
     }>;
 }
+interface QuestionFormat {
+    type: 'question';
+    question: string;
+}
+interface HighlightsFormat {
+    type: 'highlights';
+    query: string;
+}
+/** @deprecated Use QuestionFormat or HighlightsFormat instead. */
 interface QueryFormat {
     type: 'query';
     prompt: string;
     mode?: 'freeform' | 'directQuote';
 }
-type FormatOption = FormatString | Format | JsonFormat | ChangeTrackingFormat | ScreenshotFormat | AttributesFormat | QueryFormat;
+type FormatOption = FormatString | Format | JsonFormat | ChangeTrackingFormat | ScreenshotFormat | AttributesFormat | QuestionFormat | HighlightsFormat | QueryFormat;
 type ParseFormatString = Exclude<FormatString, 'screenshot' | 'changeTracking' | 'branding'>;
 interface ParseFormat {
     type: ParseFormatString;
 }
-type ParseFormatOption = ParseFormatString | ParseFormat | JsonFormat | AttributesFormat | QueryFormat;
+type ParseFormatOption = ParseFormatString | ParseFormat | JsonFormat | AttributesFormat | QuestionFormat | HighlightsFormat | QueryFormat;
 interface LocationConfig$1 {
     country?: string;
     languages?: string[];
@@ -345,6 +354,7 @@ interface Document {
     }>;
     actions?: Record<string, unknown>;
     answer?: string;
+    highlights?: string;
     warning?: string;
     changeTracking?: Record<string, unknown>;
     branding?: BrandingProfile;
@@ -2081,4 +2091,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, 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 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 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 };

package/dist/index.d.ts

@@ -40,17 +40,26 @@ interface AttributesFormat extends Format {
         attribute: string;
     }>;
 }
+interface QuestionFormat {
+    type: 'question';
+    question: string;
+}
+interface HighlightsFormat {
+    type: 'highlights';
+    query: string;
+}
+/** @deprecated Use QuestionFormat or HighlightsFormat instead. */
 interface QueryFormat {
     type: 'query';
     prompt: string;
     mode?: 'freeform' | 'directQuote';
 }
-type FormatOption = FormatString | Format | JsonFormat | ChangeTrackingFormat | ScreenshotFormat | AttributesFormat | QueryFormat;
+type FormatOption = FormatString | Format | JsonFormat | ChangeTrackingFormat | ScreenshotFormat | AttributesFormat | QuestionFormat | HighlightsFormat | QueryFormat;
 type ParseFormatString = Exclude<FormatString, 'screenshot' | 'changeTracking' | 'branding'>;
 interface ParseFormat {
     type: ParseFormatString;
 }
-type ParseFormatOption = ParseFormatString | ParseFormat | JsonFormat | AttributesFormat | QueryFormat;
+type ParseFormatOption = ParseFormatString | ParseFormat | JsonFormat | AttributesFormat | QuestionFormat | HighlightsFormat | QueryFormat;
 interface LocationConfig$1 {
     country?: string;
     languages?: string[];
@@ -345,6 +354,7 @@ interface Document {
     }>;
     actions?: Record<string, unknown>;
     answer?: string;
+    highlights?: string;
     warning?: string;
     changeTracking?: Record<string, unknown>;
     branding?: BrandingProfile;
@@ -2081,4 +2091,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, 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 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 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 };

package/dist/index.js

@@ -1,6 +1,6 @@
 import {
   require_package
-} from "./chunk-XWPH5FOQ.js";
+} from "./chunk-WTZQ5IMF.js";
 
 // src/v2/utils/httpClient.ts
 import axios from "axios";
@@ -244,6 +244,30 @@ function ensureValidFormats(formats) {
       }
       continue;
     }
+    if (fmt.type === "question") {
+      const q = fmt;
+      if (typeof q.question !== "string" || q.question.trim().length === 0) {
+        throw new Error("question format requires a non-empty 'question' string");
+      }
+      continue;
+    }
+    if (fmt.type === "highlights") {
+      const h = fmt;
+      if (typeof h.query !== "string" || h.query.trim().length === 0) {
+        throw new Error("highlights format requires a non-empty 'query' string");
+      }
+      continue;
+    }
+    if (fmt.type === "query") {
+      const q = fmt;
+      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.type === "screenshot") {
       const s = fmt;
       if (s.quality != null && (typeof s.quality !== "number" || s.quality < 0)) {
@@ -303,6 +327,30 @@ function ensureValidParseFormats(formats) {
           "json format schema appears to be a Zod schema's .shape property. Pass the Zod schema directly (e.g., `schema: MySchema`) instead of `schema: MySchema.shape`. The SDK will automatically convert Zod schemas to JSON Schema format."
         );
       }
+      continue;
+    }
+    if (fmt.type === "question") {
+      const q = fmt;
+      if (typeof q.question !== "string" || q.question.trim().length === 0) {
+        throw new Error("question format requires a non-empty 'question' string");
+      }
+      continue;
+    }
+    if (fmt.type === "highlights") {
+      const h = fmt;
+      if (typeof h.query !== "string" || h.query.trim().length === 0) {
+        throw new Error("highlights format requires a non-empty 'query' string");
+      }
+      continue;
+    }
+    if (fmt.type === "query") {
+      const q = fmt;
+      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'");
+      }
     }
   }
 }
@@ -1988,7 +2036,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-VALCXP74.js");
+      const packageJson = await import("./package-YDTOLYXI.js");
       return packageJson.default.version;
     } catch (error) {
       const isTest = typeof process !== "undefined" && (process.env.JEST_WORKER_ID != null || false);

package/dist/{package-VALCXP74.js → package-YDTOLYXI.js}

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

package/package.json

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

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

@@ -56,6 +56,27 @@ describe("v2 utils: validation", () => {
     expect((formats[0] as any).viewport).toEqual({ width: 800, height: 600 });
   });
 
+  test("ensureValidFormats: accepts question, highlights, and deprecated query formats", () => {
+    const formats: FormatOption[] = [
+      { type: "question", question: "What is Firecrawl?" },
+      { type: "highlights", query: "What is Firecrawl?" },
+      { type: "query", prompt: "What is Firecrawl?", mode: "directQuote" },
+    ];
+    expect(() => ensureValidFormats(formats)).not.toThrow();
+  });
+
+  test("ensureValidFormats: validates question, highlights, and deprecated query fields", () => {
+    expect(() =>
+      ensureValidFormats([{ type: "question", question: "" } as any]),
+    ).toThrow(/question format requires/i);
+    expect(() =>
+      ensureValidFormats([{ type: "highlights", query: "" } as any]),
+    ).toThrow(/highlights format requires/i);
+    expect(() =>
+      ensureValidFormats([{ type: "query", prompt: "p", mode: "quoted" } as any]),
+    ).toThrow(/query format mode/i);
+  });
+
   test("ensureValidScrapeOptions: leaves parsers untouched", () => {
     const options = { parsers: ["pdf", "images"] as string[] } as any;
     const before = [...options.parsers];

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;

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'");
+      }
     }
   }
 }