npm - firecrawl - Versions diffs - 4.18.3 → 4.18.5 - Mend

firecrawl 4.18.3 → 4.18.5

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.

Files changed (16) hide show

package/README.md +20 -0
package/dist/{chunk-XC6YCBFX.js → chunk-SEIHZPTI.js} +3 -2
package/dist/index.cjs +153 -4
package/dist/index.d.cts +29 -1
package/dist/index.d.ts +29 -1
package/dist/index.js +152 -4
package/dist/{package-PW6FMSAE.js → package-ASKBBK6V.js} +1 -1
package/package.json +1 -1
package/src/__tests__/e2e/v2/parse.test.ts +67 -0
package/src/__tests__/unit/v2/parse.unit.test.ts +40 -0
package/src/v2/client.ts +21 -0
package/src/v2/methods/crawl.ts +1 -0
package/src/v2/methods/parse.ts +90 -0
package/src/v2/types.ts +46 -0
package/src/v2/utils/httpClient.ts +37 -4
package/src/v2/utils/validation.ts +88 -1

package/README.md CHANGED Viewed

@@ -46,6 +46,26 @@ const url = 'https://example.com';
 const scrapedData = await app.scrape(url);
 ```
+### Parsing uploaded files
+Use `parse` to upload a file (`html`, `pdf`, `docx`, etc.) as multipart form data and process it through the same parsing pipeline.
+Parse does not support browser-only formats/options like `changeTracking`, `screenshot`, `branding`, `actions`, `waitFor`, `location`, or `mobile`.
+```js
+const parsed = await app.parse(
+  {
+    data: '<html><body><h1>Hello parse</h1></body></html>',
+    filename: 'upload.html',
+    contentType: 'text/html',
+  },
+  {
+    formats: ['markdown'],
+  }
+);
+console.log(parsed.markdown);
+```
 ### Crawling a Website
 To crawl a website with error handling, use the `crawl` method. It takes the starting URL and optional parameters, including limits and per‑page `scrapeOptions`.

package/dist/{chunk-XC6YCBFX.js → chunk-SEIHZPTI.js} RENAMED Viewed

@@ -8,7 +8,7 @@ var require_package = __commonJS({
   "package.json"(exports, module) {
     module.exports = {
       name: "@mendable/firecrawl-js",
-      version: "4.18.3",
+      version: "4.18.5",
       description: "JavaScript SDK for Firecrawl API",
       main: "dist/index.js",
       types: "dist/index.d.ts",
@@ -78,7 +78,8 @@ var require_package = __commonJS({
           "picomatch@<4.0.4": ">=4.0.4",
           handlebars: ">=4.7.9",
           "brace-expansion": ">=5.0.5",
-          "axios@<1.15.0": "1.15.0"
+          "axios@<1.15.0": "1.15.0",
+          "follow-redirects@<1.16.0": ">=1.16.0 <2.0.0"
         }
       }
     };

package/dist/index.cjs CHANGED Viewed

@@ -35,7 +35,7 @@ var require_package = __commonJS({
   "package.json"(exports2, module2) {
     module2.exports = {
       name: "@mendable/firecrawl-js",
-      version: "4.18.3",
+      version: "4.18.5",
       description: "JavaScript SDK for Firecrawl API",
       main: "dist/index.js",
       types: "dist/index.d.ts",
@@ -105,7 +105,8 @@ var require_package = __commonJS({
           "picomatch@<4.0.4": ">=4.0.4",
           handlebars: ">=4.7.9",
           "brace-expansion": ">=5.0.5",
-          "axios@<1.15.0": "1.15.0"
+          "axios@<1.15.0": "1.15.0",
+          "follow-redirects@<1.16.0": ">=1.16.0 <2.0.0"
         }
       }
     };
@@ -157,7 +158,6 @@ var HttpClient = class {
       baseURL: this.apiUrl,
       timeout: options.timeoutMs ?? 3e5,
       headers: {
-        "Content-Type": "application/json",
         Authorization: `Bearer ${this.apiKey}`
       },
       transitional: { clarifyTimeoutError: true }
@@ -178,13 +178,20 @@ var HttpClient = class {
     for (let attempt = 0; attempt < this.maxRetries; attempt++) {
       try {
         const cfg = { ...config };
-        if (cfg.method && ["post", "put", "patch"].includes(cfg.method.toLowerCase())) {
+        const isFormDataBody = typeof FormData !== "undefined" && cfg.data instanceof FormData;
+        const isPlainObjectBody = !isFormDataBody && cfg.data != null && typeof cfg.data === "object" && !Array.isArray(cfg.data);
+        if (isPlainObjectBody && cfg.method && ["post", "put", "patch"].includes(cfg.method.toLowerCase())) {
           const data = cfg.data ?? {};
           cfg.data = { ...data, origin: typeof data.origin === "string" && data.origin.includes("mcp") ? data.origin : `js-sdk@${version}` };
           if (typeof data.timeout === "number") {
             cfg.timeout = data.timeout + 5e3;
           }
         }
+        if (isFormDataBody) {
+          cfg.headers = { ...cfg.headers || {} };
+          delete cfg.headers["Content-Type"];
+          delete cfg.headers["content-type"];
+        }
         const res = await this.instance.request(cfg);
         if (res.status === 502 && attempt < this.maxRetries - 1) {
           await this.sleep(this.backoffFactor * Math.pow(2, attempt));
@@ -209,6 +216,15 @@ var HttpClient = class {
   post(endpoint, body, headers) {
     return this.request({ method: "post", url: endpoint, data: body, headers });
   }
+  postMultipart(endpoint, formData, headers, timeoutMs) {
+    return this.request({
+      method: "post",
+      url: endpoint,
+      data: formData,
+      headers,
+      timeout: timeoutMs
+    });
+  }
   get(endpoint, headers) {
     return this.request({ method: "get", url: endpoint, headers });
   }
@@ -355,6 +371,76 @@ function ensureValidScrapeOptions(options) {
   }
   ensureValidFormats(options.formats);
 }
+function ensureValidParseFormats(formats) {
+  if (!formats) return;
+  for (const fmt of formats) {
+    if (typeof fmt === "string") {
+      if (fmt === "json") {
+        throw new Error("json format must be an object with { type: 'json', prompt, schema }");
+      }
+      if (fmt === "screenshot") {
+        throw new Error("parse does not support screenshot format");
+      }
+      if (fmt === "changeTracking") {
+        throw new Error("parse does not support changeTracking format");
+      }
+      if (fmt === "branding") {
+        throw new Error("parse does not support branding format");
+      }
+      continue;
+    }
+    const type = fmt.type;
+    if (type === "changeTracking") {
+      throw new Error("parse does not support changeTracking format");
+    }
+    if (type === "screenshot") {
+      throw new Error("parse does not support screenshot format");
+    }
+    if (type === "branding") {
+      throw new Error("parse does not support branding format");
+    }
+    if (fmt.type === "json") {
+      const j = fmt;
+      if (!j.prompt && !j.schema) {
+        throw new Error("json format requires either 'prompt' or 'schema' (or both)");
+      }
+      const maybeSchema = j.schema;
+      if (isZodSchema(maybeSchema)) {
+        j.schema = zodSchemaToJsonSchema(maybeSchema);
+      } else if (looksLikeZodShape(maybeSchema)) {
+        throw new Error(
+          "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."
+        );
+      }
+    }
+  }
+}
+function ensureValidParseOptions(options) {
+  if (!options) return;
+  if (options.timeout != null && options.timeout <= 0) {
+    throw new Error("timeout must be positive");
+  }
+  const raw = options;
+  if (raw.waitFor !== void 0) {
+    throw new Error("parse does not support waitFor");
+  }
+  if (raw.actions !== void 0) {
+    throw new Error("parse does not support actions");
+  }
+  if (raw.location !== void 0) {
+    throw new Error("parse does not support location overrides");
+  }
+  if (raw.mobile !== void 0) {
+    throw new Error("parse does not support mobile rendering");
+  }
+  if (raw.maxAge !== void 0 || raw.minAge !== void 0 || raw.storeInCache !== void 0) {
+    throw new Error("parse does not support cache/index options");
+  }
+  if (raw.proxy !== void 0 && raw.proxy !== "basic" && raw.proxy !== "auto") {
+    throw new Error("parse only supports proxy values of 'basic' or 'auto'");
+  }
+  ensureValidParseFormats(options.formats);
+}
 // src/v2/utils/errorHandler.ts
 var import_axios2 = require("axios");
@@ -455,6 +541,65 @@ async function stopInteraction(http, jobId) {
   }
 }
+// src/v2/methods/parse.ts
+function toUploadBlob(input, contentType) {
+  if (typeof Blob !== "undefined" && input instanceof Blob) {
+    if (contentType && input.type !== contentType) {
+      return new Blob([input], { type: contentType });
+    }
+    return input;
+  }
+  if (typeof Buffer !== "undefined" && Buffer.isBuffer(input)) {
+    return new Blob([input], { type: contentType });
+  }
+  if (input instanceof ArrayBuffer) {
+    return new Blob([input], { type: contentType });
+  }
+  if (ArrayBuffer.isView(input)) {
+    return new Blob([input], { type: contentType });
+  }
+  if (typeof input === "string") {
+    return new Blob([input], { type: contentType ?? "text/plain; charset=utf-8" });
+  }
+  throw new Error("Unsupported parse file data type");
+}
+async function parse(http, file, options) {
+  if (!file || !file.filename || !file.filename.trim()) {
+    throw new Error("filename cannot be empty");
+  }
+  if (file.data == null) {
+    throw new Error("file data cannot be empty");
+  }
+  const blob = toUploadBlob(file.data, file.contentType);
+  if (blob.size === 0) {
+    throw new Error("file data cannot be empty");
+  }
+  if (options) ensureValidParseOptions(options);
+  const version = getVersion();
+  const normalizedOptions = {
+    ...options ?? {},
+    origin: typeof options?.origin === "string" && options.origin.includes("mcp") ? options.origin : options?.origin ?? `js-sdk@${version}`
+  };
+  const formData = new FormData();
+  formData.append("options", JSON.stringify(normalizedOptions));
+  formData.append(
+    "file",
+    toUploadBlob(file.data, file.contentType),
+    file.filename.trim()
+  );
+  const requestTimeoutMs = typeof normalizedOptions.timeout === "number" ? normalizedOptions.timeout + 5e3 : void 0;
+  try {
+    const res = await http.postMultipart("/v2/parse", formData, void 0, requestTimeoutMs);
+    if (res.status !== 200 || !res.data?.success) {
+      throwForBadResponse(res, "parse");
+    }
+    return res.data.data || {};
+  } catch (err) {
+    if (err?.isAxiosError) return normalizeAxiosError(err, "parse");
+    throw err;
+  }
+}
 // src/v2/methods/search.ts
 function prepareSearchPayload(req) {
   if (!req.query || !req.query.trim()) throw new Error("Query cannot be empty");
@@ -589,6 +734,7 @@ function prepareCrawlPayload(request) {
   if (request.includePaths) data.includePaths = request.includePaths;
   if (request.maxDiscoveryDepth != null) data.maxDiscoveryDepth = request.maxDiscoveryDepth;
   if (request.sitemap != null) data.sitemap = request.sitemap;
+  if (request.robotsUserAgent != null) data.robotsUserAgent = request.robotsUserAgent;
   if (request.ignoreQueryParameters != null) data.ignoreQueryParameters = request.ignoreQueryParameters;
   if (request.deduplicateSimilarURLs != null) data.deduplicateSimilarURLs = request.deduplicateSimilarURLs;
   if (request.limit != null) data.limit = request.limit;
@@ -1402,6 +1548,9 @@ var FirecrawlClient = class {
   async deleteScrapeBrowser(jobId) {
     return this.stopInteraction(jobId);
   }
+  async parse(file, options) {
+    return parse(this.http, file, options);
+  }
   // Search
   /**
    * Search the web and optionally scrape each result.

package/dist/index.d.cts CHANGED Viewed

@@ -45,6 +45,11 @@ interface QueryFormat {
     prompt: string;
 }
 type FormatOption = FormatString | Format | JsonFormat | ChangeTrackingFormat | ScreenshotFormat | AttributesFormat | QueryFormat;
+type ParseFormatString = Exclude<FormatString, 'screenshot' | 'changeTracking' | 'branding'>;
+interface ParseFormat {
+    type: ParseFormatString;
+}
+type ParseFormatOption = ParseFormatString | ParseFormat | JsonFormat | AttributesFormat | QueryFormat;
 interface LocationConfig$1 {
     country?: string;
     languages?: string[];
@@ -126,6 +131,16 @@ interface ScrapeOptions {
     integration?: string;
     origin?: string;
 }
+type ParseFileData = Blob | File | Buffer | Uint8Array | ArrayBuffer | string;
+interface ParseFile {
+    data: ParseFileData;
+    filename: string;
+    contentType?: string;
+}
+type ParseOptions = Omit<ScrapeOptions, 'formats' | 'waitFor' | 'mobile' | 'actions' | 'location' | 'maxAge' | 'minAge' | 'storeInCache' | 'proxy'> & {
+    formats?: ParseFormatOption[];
+    proxy?: 'basic' | 'auto';
+};
 interface WebhookConfig {
     url: string;
     headers?: Record<string, string>;
@@ -645,6 +660,7 @@ declare class HttpClient {
     private request;
     private sleep;
     post<T = any>(endpoint: string, body: Record<string, unknown>, headers?: Record<string, string>): Promise<AxiosResponse<T, any, {}>>;
+    postMultipart<T = any>(endpoint: string, formData: FormData, headers?: Record<string, string>, timeoutMs?: number): Promise<AxiosResponse<T, any, {}>>;
     get<T = any>(endpoint: string, headers?: Record<string, string>): Promise<AxiosResponse<T, any, {}>>;
     delete<T = any>(endpoint: string, headers?: Record<string, string>): Promise<AxiosResponse<T, any, {}>>;
     prepareHeaders(idempotencyKey?: string): Record<string, string>;
@@ -796,6 +812,18 @@ declare class FirecrawlClient {
      * @deprecated Use stopInteraction().
      */
     deleteScrapeBrowser(jobId: string): Promise<ScrapeBrowserDeleteResponse>;
+    /**
+     * Parse an uploaded file via the v2 parse endpoint.
+     * @param file File payload (data, filename, optional contentType).
+     * @param options Optional parse options (formats, parsers, etc.).
+     *                Note: parse does not support changeTracking, screenshot, branding,
+     *                actions, waitFor, location, or mobile options.
+     * @returns Parsed document with requested formats.
+     */
+    parse<Opts extends ParseOptions>(file: ParseFile, options: Opts): Promise<Omit<Document, "json"> & {
+        json?: InferredJsonFromOptions<Opts>;
+    }>;
+    parse(file: ParseFile, options?: ParseOptions): Promise<Document>;
     /**
      * Search the web and optionally scrape each result.
      * @param query Search query string.
@@ -1892,4 +1920,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 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, JobTimeoutError, type JsonFormat, type LocationConfig$1 as LocationConfig, type MapData, type MapOptions, type PDFAction, type PaginationConfig, 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 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 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, JobTimeoutError, type JsonFormat, type LocationConfig$1 as LocationConfig, type MapData, type MapOptions, 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 Viewport, type WaitAction, Watcher, type WatcherOptions, type WebhookConfig, type WriteAction, Firecrawl as default };

package/dist/index.d.ts CHANGED Viewed

@@ -45,6 +45,11 @@ interface QueryFormat {
     prompt: string;
 }
 type FormatOption = FormatString | Format | JsonFormat | ChangeTrackingFormat | ScreenshotFormat | AttributesFormat | QueryFormat;
+type ParseFormatString = Exclude<FormatString, 'screenshot' | 'changeTracking' | 'branding'>;
+interface ParseFormat {
+    type: ParseFormatString;
+}
+type ParseFormatOption = ParseFormatString | ParseFormat | JsonFormat | AttributesFormat | QueryFormat;
 interface LocationConfig$1 {
     country?: string;
     languages?: string[];
@@ -126,6 +131,16 @@ interface ScrapeOptions {
     integration?: string;
     origin?: string;
 }
+type ParseFileData = Blob | File | Buffer | Uint8Array | ArrayBuffer | string;
+interface ParseFile {
+    data: ParseFileData;
+    filename: string;
+    contentType?: string;
+}
+type ParseOptions = Omit<ScrapeOptions, 'formats' | 'waitFor' | 'mobile' | 'actions' | 'location' | 'maxAge' | 'minAge' | 'storeInCache' | 'proxy'> & {
+    formats?: ParseFormatOption[];
+    proxy?: 'basic' | 'auto';
+};
 interface WebhookConfig {
     url: string;
     headers?: Record<string, string>;
@@ -645,6 +660,7 @@ declare class HttpClient {
     private request;
     private sleep;
     post<T = any>(endpoint: string, body: Record<string, unknown>, headers?: Record<string, string>): Promise<AxiosResponse<T, any, {}>>;
+    postMultipart<T = any>(endpoint: string, formData: FormData, headers?: Record<string, string>, timeoutMs?: number): Promise<AxiosResponse<T, any, {}>>;
     get<T = any>(endpoint: string, headers?: Record<string, string>): Promise<AxiosResponse<T, any, {}>>;
     delete<T = any>(endpoint: string, headers?: Record<string, string>): Promise<AxiosResponse<T, any, {}>>;
     prepareHeaders(idempotencyKey?: string): Record<string, string>;
@@ -796,6 +812,18 @@ declare class FirecrawlClient {
      * @deprecated Use stopInteraction().
      */
     deleteScrapeBrowser(jobId: string): Promise<ScrapeBrowserDeleteResponse>;
+    /**
+     * Parse an uploaded file via the v2 parse endpoint.
+     * @param file File payload (data, filename, optional contentType).
+     * @param options Optional parse options (formats, parsers, etc.).
+     *                Note: parse does not support changeTracking, screenshot, branding,
+     *                actions, waitFor, location, or mobile options.
+     * @returns Parsed document with requested formats.
+     */
+    parse<Opts extends ParseOptions>(file: ParseFile, options: Opts): Promise<Omit<Document, "json"> & {
+        json?: InferredJsonFromOptions<Opts>;
+    }>;
+    parse(file: ParseFile, options?: ParseOptions): Promise<Document>;
     /**
      * Search the web and optionally scrape each result.
      * @param query Search query string.
@@ -1892,4 +1920,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 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, JobTimeoutError, type JsonFormat, type LocationConfig$1 as LocationConfig, type MapData, type MapOptions, type PDFAction, type PaginationConfig, 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 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 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, JobTimeoutError, type JsonFormat, type LocationConfig$1 as LocationConfig, type MapData, type MapOptions, 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 Viewport, type WaitAction, Watcher, type WatcherOptions, type WebhookConfig, type WriteAction, Firecrawl as default };

package/dist/index.js CHANGED Viewed

@@ -1,6 +1,6 @@
 import {
   require_package
-} from "./chunk-XC6YCBFX.js";
+} from "./chunk-SEIHZPTI.js";
 // src/v2/utils/httpClient.ts
 import axios from "axios";
@@ -34,7 +34,6 @@ var HttpClient = class {
       baseURL: this.apiUrl,
       timeout: options.timeoutMs ?? 3e5,
       headers: {
-        "Content-Type": "application/json",
         Authorization: `Bearer ${this.apiKey}`
       },
       transitional: { clarifyTimeoutError: true }
@@ -55,13 +54,20 @@ var HttpClient = class {
     for (let attempt = 0; attempt < this.maxRetries; attempt++) {
       try {
         const cfg = { ...config };
-        if (cfg.method && ["post", "put", "patch"].includes(cfg.method.toLowerCase())) {
+        const isFormDataBody = typeof FormData !== "undefined" && cfg.data instanceof FormData;
+        const isPlainObjectBody = !isFormDataBody && cfg.data != null && typeof cfg.data === "object" && !Array.isArray(cfg.data);
+        if (isPlainObjectBody && cfg.method && ["post", "put", "patch"].includes(cfg.method.toLowerCase())) {
           const data = cfg.data ?? {};
           cfg.data = { ...data, origin: typeof data.origin === "string" && data.origin.includes("mcp") ? data.origin : `js-sdk@${version}` };
           if (typeof data.timeout === "number") {
             cfg.timeout = data.timeout + 5e3;
           }
         }
+        if (isFormDataBody) {
+          cfg.headers = { ...cfg.headers || {} };
+          delete cfg.headers["Content-Type"];
+          delete cfg.headers["content-type"];
+        }
         const res = await this.instance.request(cfg);
         if (res.status === 502 && attempt < this.maxRetries - 1) {
           await this.sleep(this.backoffFactor * Math.pow(2, attempt));
@@ -86,6 +92,15 @@ var HttpClient = class {
   post(endpoint, body, headers) {
     return this.request({ method: "post", url: endpoint, data: body, headers });
   }
+  postMultipart(endpoint, formData, headers, timeoutMs) {
+    return this.request({
+      method: "post",
+      url: endpoint,
+      data: formData,
+      headers,
+      timeout: timeoutMs
+    });
+  }
   get(endpoint, headers) {
     return this.request({ method: "get", url: endpoint, headers });
   }
@@ -232,6 +247,76 @@ function ensureValidScrapeOptions(options) {
   }
   ensureValidFormats(options.formats);
 }
+function ensureValidParseFormats(formats) {
+  if (!formats) return;
+  for (const fmt of formats) {
+    if (typeof fmt === "string") {
+      if (fmt === "json") {
+        throw new Error("json format must be an object with { type: 'json', prompt, schema }");
+      }
+      if (fmt === "screenshot") {
+        throw new Error("parse does not support screenshot format");
+      }
+      if (fmt === "changeTracking") {
+        throw new Error("parse does not support changeTracking format");
+      }
+      if (fmt === "branding") {
+        throw new Error("parse does not support branding format");
+      }
+      continue;
+    }
+    const type = fmt.type;
+    if (type === "changeTracking") {
+      throw new Error("parse does not support changeTracking format");
+    }
+    if (type === "screenshot") {
+      throw new Error("parse does not support screenshot format");
+    }
+    if (type === "branding") {
+      throw new Error("parse does not support branding format");
+    }
+    if (fmt.type === "json") {
+      const j = fmt;
+      if (!j.prompt && !j.schema) {
+        throw new Error("json format requires either 'prompt' or 'schema' (or both)");
+      }
+      const maybeSchema = j.schema;
+      if (isZodSchema(maybeSchema)) {
+        j.schema = zodSchemaToJsonSchema(maybeSchema);
+      } else if (looksLikeZodShape(maybeSchema)) {
+        throw new Error(
+          "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."
+        );
+      }
+    }
+  }
+}
+function ensureValidParseOptions(options) {
+  if (!options) return;
+  if (options.timeout != null && options.timeout <= 0) {
+    throw new Error("timeout must be positive");
+  }
+  const raw = options;
+  if (raw.waitFor !== void 0) {
+    throw new Error("parse does not support waitFor");
+  }
+  if (raw.actions !== void 0) {
+    throw new Error("parse does not support actions");
+  }
+  if (raw.location !== void 0) {
+    throw new Error("parse does not support location overrides");
+  }
+  if (raw.mobile !== void 0) {
+    throw new Error("parse does not support mobile rendering");
+  }
+  if (raw.maxAge !== void 0 || raw.minAge !== void 0 || raw.storeInCache !== void 0) {
+    throw new Error("parse does not support cache/index options");
+  }
+  if (raw.proxy !== void 0 && raw.proxy !== "basic" && raw.proxy !== "auto") {
+    throw new Error("parse only supports proxy values of 'basic' or 'auto'");
+  }
+  ensureValidParseFormats(options.formats);
+}
 // src/v2/utils/errorHandler.ts
 import "axios";
@@ -332,6 +417,65 @@ async function stopInteraction(http, jobId) {
   }
 }
+// src/v2/methods/parse.ts
+function toUploadBlob(input, contentType) {
+  if (typeof Blob !== "undefined" && input instanceof Blob) {
+    if (contentType && input.type !== contentType) {
+      return new Blob([input], { type: contentType });
+    }
+    return input;
+  }
+  if (typeof Buffer !== "undefined" && Buffer.isBuffer(input)) {
+    return new Blob([input], { type: contentType });
+  }
+  if (input instanceof ArrayBuffer) {
+    return new Blob([input], { type: contentType });
+  }
+  if (ArrayBuffer.isView(input)) {
+    return new Blob([input], { type: contentType });
+  }
+  if (typeof input === "string") {
+    return new Blob([input], { type: contentType ?? "text/plain; charset=utf-8" });
+  }
+  throw new Error("Unsupported parse file data type");
+}
+async function parse(http, file, options) {
+  if (!file || !file.filename || !file.filename.trim()) {
+    throw new Error("filename cannot be empty");
+  }
+  if (file.data == null) {
+    throw new Error("file data cannot be empty");
+  }
+  const blob = toUploadBlob(file.data, file.contentType);
+  if (blob.size === 0) {
+    throw new Error("file data cannot be empty");
+  }
+  if (options) ensureValidParseOptions(options);
+  const version = getVersion();
+  const normalizedOptions = {
+    ...options ?? {},
+    origin: typeof options?.origin === "string" && options.origin.includes("mcp") ? options.origin : options?.origin ?? `js-sdk@${version}`
+  };
+  const formData = new FormData();
+  formData.append("options", JSON.stringify(normalizedOptions));
+  formData.append(
+    "file",
+    toUploadBlob(file.data, file.contentType),
+    file.filename.trim()
+  );
+  const requestTimeoutMs = typeof normalizedOptions.timeout === "number" ? normalizedOptions.timeout + 5e3 : void 0;
+  try {
+    const res = await http.postMultipart("/v2/parse", formData, void 0, requestTimeoutMs);
+    if (res.status !== 200 || !res.data?.success) {
+      throwForBadResponse(res, "parse");
+    }
+    return res.data.data || {};
+  } catch (err) {
+    if (err?.isAxiosError) return normalizeAxiosError(err, "parse");
+    throw err;
+  }
+}
 // src/v2/methods/search.ts
 function prepareSearchPayload(req) {
   if (!req.query || !req.query.trim()) throw new Error("Query cannot be empty");
@@ -466,6 +610,7 @@ function prepareCrawlPayload(request) {
   if (request.includePaths) data.includePaths = request.includePaths;
   if (request.maxDiscoveryDepth != null) data.maxDiscoveryDepth = request.maxDiscoveryDepth;
   if (request.sitemap != null) data.sitemap = request.sitemap;
+  if (request.robotsUserAgent != null) data.robotsUserAgent = request.robotsUserAgent;
   if (request.ignoreQueryParameters != null) data.ignoreQueryParameters = request.ignoreQueryParameters;
   if (request.deduplicateSimilarURLs != null) data.deduplicateSimilarURLs = request.deduplicateSimilarURLs;
   if (request.limit != null) data.limit = request.limit;
@@ -1279,6 +1424,9 @@ var FirecrawlClient = class {
   async deleteScrapeBrowser(jobId) {
     return this.stopInteraction(jobId);
   }
+  async parse(file, options) {
+    return parse(this.http, file, options);
+  }
   // Search
   /**
    * Search the web and optionally scrape each result.
@@ -1559,7 +1707,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-PW6FMSAE.js");
+      const packageJson = await import("./package-ASKBBK6V.js");
       return packageJson.default.version;
     } catch (error) {
       const isTest = typeof process !== "undefined" && (process.env.JEST_WORKER_ID != null || false);

package/dist/{package-PW6FMSAE.js → package-ASKBBK6V.js} RENAMED Viewed

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

package/package.json CHANGED Viewed

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

package/src/__tests__/e2e/v2/parse.test.ts ADDED Viewed

@@ -0,0 +1,67 @@
+import Firecrawl from "../../../index";
+import { config } from "dotenv";
+import { getIdentity, getApiUrl } from "./utils/idmux";
+import { describe, test, expect, beforeAll } from "@jest/globals";
+config();
+const API_URL = getApiUrl();
+let client: Firecrawl;
+beforeAll(async () => {
+  const { apiKey } = await getIdentity({ name: "js-e2e-parse" });
+  client = new Firecrawl({ apiKey, apiUrl: API_URL });
+});
+describe("v2.parse e2e", () => {
+  test(
+    "parses uploaded HTML files",
+    async () => {
+      if (!client) throw new Error();
+      const doc = await client.parse(
+        {
+          data: `
+            <!DOCTYPE html>
+            <html>
+              <body>
+                <h1>JS SDK Parse E2E</h1>
+                <p>multipart upload body</p>
+              </body>
+            </html>
+          `,
+          filename: "parse-e2e.html",
+          contentType: "text/html",
+        },
+        {
+          formats: ["markdown"],
+        },
+      );
+      expect(doc.markdown).toContain("JS SDK Parse E2E");
+      expect(doc.metadata?.creditsUsed).toBe(1);
+    },
+    60_000,
+  );
+  test(
+    "returns errors for unsupported file types",
+    async () => {
+      if (!client) throw new Error();
+      await expect(
+        client.parse(
+          {
+            data: Buffer.from("image-data"),
+            filename: "parse-e2e.png",
+            contentType: "image/png",
+          },
+          {
+            formats: ["markdown"],
+          },
+        ),
+      ).rejects.toThrow();
+    },
+    60_000,
+  );
+});

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

@@ -0,0 +1,40 @@
+import { describe, test, expect } from "@jest/globals";
+import { FirecrawlClient } from "../../../v2/client";
+describe("v2.parse unit", () => {
+  test("rejects empty filenames before making requests", async () => {
+    const client = new FirecrawlClient({
+      apiKey: "test-key",
+      apiUrl: "https://localhost:3002",
+    });
+    await expect(
+      client.parse(
+        {
+          data: "<html><body>test</body></html>",
+          filename: "   ",
+          contentType: "text/html",
+        },
+        { formats: ["markdown"] },
+      ),
+    ).rejects.toThrow("filename cannot be empty");
+  });
+  test("rejects changeTracking format before making requests", async () => {
+    const client = new FirecrawlClient({
+      apiKey: "test-key",
+      apiUrl: "https://localhost:3002",
+    });
+    await expect(
+      client.parse(
+        {
+          data: "<html><body>test</body></html>",
+          filename: "upload.html",
+          contentType: "text/html",
+        },
+        { formats: ["markdown", { type: "changeTracking" } as any] },
+      ),
+    ).rejects.toThrow("parse does not support changeTracking format");
+  });
+});

package/src/v2/client.ts CHANGED Viewed

@@ -4,6 +4,7 @@ import {
   interact as interactMethod,
   stopInteraction as stopInteractionMethod,
 } from "./methods/scrape";
+import { parse as parseMethod } from "./methods/parse";
 import { search } from "./methods/search";
 import { map as mapMethod } from "./methods/map";
 import {
@@ -33,6 +34,8 @@ import {
 import { getConcurrency, getCreditUsage, getQueueStatus, getTokenUsage, getCreditUsageHistorical, getTokenUsageHistorical } from "./methods/usage";
 import type {
   Document,
+  ParseFile,
+  ParseOptions,
   ScrapeOptions,
   SearchData,
   SearchRequest,
@@ -177,6 +180,24 @@ export class FirecrawlClient {
     return this.stopInteraction(jobId);
   }
+  // Parse
+  /**
+   * Parse an uploaded file via the v2 parse endpoint.
+   * @param file File payload (data, filename, optional contentType).
+   * @param options Optional parse options (formats, parsers, etc.).
+   *                Note: parse does not support changeTracking, screenshot, branding,
+   *                actions, waitFor, location, or mobile options.
+   * @returns Parsed document with requested formats.
+   */
+  async parse<Opts extends ParseOptions>(
+    file: ParseFile,
+    options: Opts
+  ): Promise<Omit<Document, "json"> & { json?: InferredJsonFromOptions<Opts> }>;
+  async parse(file: ParseFile, options?: ParseOptions): Promise<Document>;
+  async parse(file: ParseFile, options?: ParseOptions): Promise<Document> {
+    return parseMethod(this.http, file, options);
+  }
   // Search
   /**
    * Search the web and optionally scrape each result.

package/src/v2/methods/crawl.ts CHANGED Viewed

@@ -27,6 +27,7 @@ function prepareCrawlPayload(request: CrawlRequest): Record<string, unknown> {
   if (request.includePaths) data.includePaths = request.includePaths;
   if (request.maxDiscoveryDepth != null) data.maxDiscoveryDepth = request.maxDiscoveryDepth;
   if (request.sitemap != null) data.sitemap = request.sitemap;
+  if (request.robotsUserAgent != null) data.robotsUserAgent = request.robotsUserAgent;
   if (request.ignoreQueryParameters != null) data.ignoreQueryParameters = request.ignoreQueryParameters;
   if (request.deduplicateSimilarURLs != null) data.deduplicateSimilarURLs = request.deduplicateSimilarURLs;
   if (request.limit != null) data.limit = request.limit;

package/src/v2/methods/parse.ts ADDED Viewed

@@ -0,0 +1,90 @@
+import { type Document, type ParseFile, type ParseOptions } from "../types";
+import { HttpClient } from "../utils/httpClient";
+import { ensureValidParseOptions } from "../utils/validation";
+import { throwForBadResponse, normalizeAxiosError } from "../utils/errorHandler";
+import { getVersion } from "../utils/getVersion";
+function toUploadBlob(input: ParseFile["data"], contentType?: string): Blob {
+  if (typeof Blob !== "undefined" && input instanceof Blob) {
+    if (contentType && input.type !== contentType) {
+      return new Blob([input], { type: contentType });
+    }
+    return input;
+  }
+  if (typeof Buffer !== "undefined" && Buffer.isBuffer(input)) {
+    return new Blob([input], { type: contentType });
+  }
+  if (input instanceof ArrayBuffer) {
+    return new Blob([input], { type: contentType });
+  }
+  if (ArrayBuffer.isView(input)) {
+    return new Blob([input], { type: contentType });
+  }
+  if (typeof input === "string") {
+    return new Blob([input], { type: contentType ?? "text/plain; charset=utf-8" });
+  }
+  throw new Error("Unsupported parse file data type");
+}
+export async function parse(
+  http: HttpClient,
+  file: ParseFile,
+  options?: ParseOptions,
+): Promise<Document> {
+  if (!file || !file.filename || !file.filename.trim()) {
+    throw new Error("filename cannot be empty");
+  }
+  if (file.data == null) {
+    throw new Error("file data cannot be empty");
+  }
+  const blob = toUploadBlob(file.data, file.contentType);
+  if (blob.size === 0) {
+    throw new Error("file data cannot be empty");
+  }
+  if (options) ensureValidParseOptions(options);
+  const version = getVersion();
+  const normalizedOptions: ParseOptions = {
+    ...(options ?? {}),
+    origin:
+      typeof options?.origin === "string" && options.origin.includes("mcp")
+        ? options.origin
+        : options?.origin ?? `js-sdk@${version}`,
+  };
+  const formData = new FormData();
+  formData.append("options", JSON.stringify(normalizedOptions));
+  formData.append(
+    "file",
+    toUploadBlob(file.data, file.contentType),
+    file.filename.trim(),
+  );
+  const requestTimeoutMs =
+    typeof normalizedOptions.timeout === "number"
+      ? normalizedOptions.timeout + 5000
+      : undefined;
+  try {
+    const res = await http.postMultipart<{
+      success: boolean;
+      data?: Document;
+      error?: string;
+    }>("/v2/parse", formData, undefined, requestTimeoutMs);
+    if (res.status !== 200 || !res.data?.success) {
+      throwForBadResponse(res, "parse");
+    }
+    return (res.data.data || {}) as Document;
+  } catch (err: any) {
+    if (err?.isAxiosError) return normalizeAxiosError(err, "parse");
+    throw err;
+  }
+}

package/src/v2/types.ts CHANGED Viewed

@@ -66,6 +66,22 @@ export type FormatOption =
   | AttributesFormat
   | QueryFormat;
+export type ParseFormatString = Exclude<
+  FormatString,
+  'screenshot' | 'changeTracking' | 'branding'
+>;
+export interface ParseFormat {
+  type: ParseFormatString;
+}
+export type ParseFormatOption =
+  | ParseFormatString
+  | ParseFormat
+  | JsonFormat
+  | AttributesFormat
+  | QueryFormat;
 export interface LocationConfig {
   country?: string;
   languages?: string[];
@@ -172,6 +188,36 @@ export interface ScrapeOptions {
   origin?: string;
 }
+export type ParseFileData =
+  | Blob
+  | File
+  | Buffer
+  | Uint8Array
+  | ArrayBuffer
+  | string;
+export interface ParseFile {
+  data: ParseFileData;
+  filename: string;
+  contentType?: string;
+}
+export type ParseOptions = Omit<
+  ScrapeOptions,
+  | 'formats'
+  | 'waitFor'
+  | 'mobile'
+  | 'actions'
+  | 'location'
+  | 'maxAge'
+  | 'minAge'
+  | 'storeInCache'
+  | 'proxy'
+> & {
+  formats?: ParseFormatOption[];
+  proxy?: 'basic' | 'auto';
+};
 export interface WebhookConfig {
   url: string;
   headers?: Record<string, string>;

package/src/v2/utils/httpClient.ts CHANGED Viewed

@@ -25,7 +25,6 @@ export class HttpClient {
       baseURL: this.apiUrl,
       timeout: options.timeoutMs ?? 300000,
       headers: {
-        "Content-Type": "application/json",
         Authorization: `Bearer ${this.apiKey}`,
       },
       transitional: { clarifyTimeoutError: true },
@@ -50,16 +49,35 @@ export class HttpClient {
     for (let attempt = 0; attempt < this.maxRetries; attempt++) {
       try {
         const cfg: AxiosRequestConfig = { ...config };
-        // For POST/PUT, ensure origin is present in JSON body too
-        if (cfg.method && ["post", "put", "patch"].includes(cfg.method.toLowerCase())) {
+        const isFormDataBody =
+          typeof FormData !== "undefined" && cfg.data instanceof FormData;
+        const isPlainObjectBody =
+          !isFormDataBody &&
+          cfg.data != null &&
+          typeof cfg.data === "object" &&
+          !Array.isArray(cfg.data);
+        // For JSON POST/PUT/PATCH, ensure origin is present in body
+        if (
+          isPlainObjectBody &&
+          cfg.method &&
+          ["post", "put", "patch"].includes(cfg.method.toLowerCase())
+        ) {
           const data = (cfg.data ?? {}) as Record<string, unknown>;
           cfg.data = { ...data, origin: typeof data.origin === "string" && data.origin.includes("mcp") ? data.origin : `js-sdk@${version}` };
           // If timeout is specified in the body, use it to override the request timeout
           if (typeof data.timeout === "number") {
             cfg.timeout = data.timeout + 5000;
           }
         }
+        if (isFormDataBody) {
+          cfg.headers = { ...(cfg.headers || {}) };
+          delete (cfg.headers as Record<string, unknown>)["Content-Type"];
+          delete (cfg.headers as Record<string, unknown>)["content-type"];
+        }
         const res = await this.instance.request<T>(cfg);
         if (res.status === 502 && attempt < this.maxRetries - 1) {
           await this.sleep(this.backoffFactor * Math.pow(2, attempt));
@@ -87,6 +105,21 @@ export class HttpClient {
     return this.request<T>({ method: "post", url: endpoint, data: body, headers });
   }
+  postMultipart<T = any>(
+    endpoint: string,
+    formData: FormData,
+    headers?: Record<string, string>,
+    timeoutMs?: number,
+  ) {
+    return this.request<T>({
+      method: "post",
+      url: endpoint,
+      data: formData,
+      headers,
+      timeout: timeoutMs,
+    });
+  }
   get<T = any>(endpoint: string, headers?: Record<string, string>) {
     return this.request<T>({ method: "get", url: endpoint, headers });
   }

package/src/v2/utils/validation.ts CHANGED Viewed

@@ -1,4 +1,12 @@
-import { type FormatOption, type JsonFormat, type ScrapeOptions, type ScreenshotFormat, type ChangeTrackingFormat } from "../types";
+import {
+  type ChangeTrackingFormat,
+  type FormatOption,
+  type JsonFormat,
+  type ParseFormatOption,
+  type ParseOptions,
+  type ScrapeOptions,
+  type ScreenshotFormat,
+} from "../types";
 import { isZodSchema, zodSchemaToJsonSchema, looksLikeZodShape } from "../../utils/zodSchemaToJson";
 export function ensureValidFormats(formats?: FormatOption[]): void {
@@ -62,3 +70,82 @@ export function ensureValidScrapeOptions(options?: ScrapeOptions): void {
   ensureValidFormats(options.formats);
 }
+export function ensureValidParseFormats(formats?: ParseFormatOption[]): void {
+  if (!formats) return;
+  for (const fmt of formats) {
+    if (typeof fmt === "string") {
+      if (fmt === "json") {
+        throw new Error("json format must be an object with { type: 'json', prompt, schema }");
+      }
+      if (fmt === "screenshot") {
+        throw new Error("parse does not support screenshot format");
+      }
+      if (fmt === "changeTracking") {
+        throw new Error("parse does not support changeTracking format");
+      }
+      if (fmt === "branding") {
+        throw new Error("parse does not support branding format");
+      }
+      continue;
+    }
+    const type = (fmt as any).type;
+    if (type === "changeTracking") {
+      throw new Error("parse does not support changeTracking format");
+    }
+    if (type === "screenshot") {
+      throw new Error("parse does not support screenshot format");
+    }
+    if (type === "branding") {
+      throw new Error("parse does not support branding format");
+    }
+    if ((fmt as JsonFormat).type === "json") {
+      const j = fmt as JsonFormat;
+      if (!j.prompt && !j.schema) {
+        throw new Error("json format requires either 'prompt' or 'schema' (or both)");
+      }
+      const maybeSchema = j.schema;
+      if (isZodSchema(maybeSchema)) {
+        (j as any).schema = zodSchemaToJsonSchema(maybeSchema);
+      } else if (looksLikeZodShape(maybeSchema)) {
+        throw new Error(
+          "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."
+        );
+      }
+    }
+  }
+}
+export function ensureValidParseOptions(options?: ParseOptions): void {
+  if (!options) return;
+  if (options.timeout != null && options.timeout <= 0) {
+    throw new Error("timeout must be positive");
+  }
+  const raw = options as Record<string, unknown>;
+  if (raw.waitFor !== undefined) {
+    throw new Error("parse does not support waitFor");
+  }
+  if (raw.actions !== undefined) {
+    throw new Error("parse does not support actions");
+  }
+  if (raw.location !== undefined) {
+    throw new Error("parse does not support location overrides");
+  }
+  if (raw.mobile !== undefined) {
+    throw new Error("parse does not support mobile rendering");
+  }
+  if (raw.maxAge !== undefined || raw.minAge !== undefined || raw.storeInCache !== undefined) {
+    throw new Error("parse does not support cache/index options");
+  }
+  if (raw.proxy !== undefined && raw.proxy !== "basic" && raw.proxy !== "auto") {
+    throw new Error("parse only supports proxy values of 'basic' or 'auto'");
+  }
+  ensureValidParseFormats(options.formats);
+}