Supercharge your AI agents with data from the web and beyond. Building the library for superintelligence. 🔥
TypeScript aiai-agentsai-crawlerai-scrapingai-searchcrawlerdata-extractionhtml-to-markdownllmmarkdownscraperscrapingweb-crawlerweb-dataweb-data-extractionweb-scraperweb-scrapingweb-searchwebscraping
fix(js-sdk): add Zod v4 compatibility for schema conversion (#2724)
firecrawl-spring[bot]3f4536a10e49
diff --git a/apps/js-sdk/firecrawl/package.json b/apps/js-sdk/firecrawl/package.jsonindex 1c0eeeb37..9357ae19f 100644--- a/apps/js-sdk/firecrawl/package.json+++ b/apps/js-sdk/firecrawl/package.json@@ -1,6 +1,6 @@{"name": "@mendable/firecrawl-js",- "version": "4.11.2",+ "version": "4.11.3","description": "JavaScript SDK for Firecrawl API","main": "dist/index.js","types": "dist/index.d.ts",diff --git a/apps/js-sdk/firecrawl/src/__tests__/unit/v2/zodSchemaToJson.test.ts b/apps/js-sdk/firecrawl/src/__tests__/unit/v2/zodSchemaToJson.test.tsnew file mode 100644index 000000000..6a20b236d--- /dev/null+++ b/apps/js-sdk/firecrawl/src/__tests__/unit/v2/zodSchemaToJson.test.ts@@ -0,0 +1,107 @@+import { describe, test, expect } from "@jest/globals";+import { z } from "zod";+import {+ isZodSchema,+ zodSchemaToJsonSchema,+ looksLikeZodShape,+} from "../../../utils/zodSchemaToJson";++describe("zodSchemaToJson utility", () => {+ test("isZodSchema detects Zod schemas and rejects non-Zod values", () => {+ expect(isZodSchema(z.object({ name: z.string() }))).toBe(true);+ expect(isZodSchema(z.string())).toBe(true);+ expect(isZodSchema(z.number())).toBe(true);+ expect(isZodSchema(z.array(z.string()))).toBe(true);+ expect(isZodSchema(z.enum(["A", "B"]))).toBe(true);+ expect(isZodSchema(z.union([z.string(), z.number()]))).toBe(true);+ expect(isZodSchema(z.string().optional())).toBe(true);+ expect(isZodSchema(z.string().nullable())).toBe(true);++ expect(isZodSchema(null)).toBe(false);+ expect(isZodSchema(undefined)).toBe(false);+ expect(isZodSchema({ name: "test" })).toBe(false);+ expect(isZodSchema({ type: "object", properties: {} })).toBe(false);+ expect(isZodSchema("string")).toBe(false);+ expect(isZodSchema(42)).toBe(false);+ expect(isZodSchema([1, 2, 3])).toBe(false);+ });++ test("zodSchemaToJsonSchema converts Zod schemas to JSON Schema", () => {+ const simpleSchema = z.object({ name: z.string() });+ const simpleResult = zodSchemaToJsonSchema(simpleSchema) as Record<string, unknown>;+ expect(simpleResult.type).toBe("object");+ expect(simpleResult.properties).toBeDefined();+ expect((simpleResult.properties as Record<string, unknown>).name).toBeDefined();++ const complexSchema = z.object({+ id: z.string().uuid(),+ name: z.string().min(1).max(100),+ age: z.number().min(0).max(150).optional(),+ tags: z.array(z.string()),+ status: z.enum(["active", "inactive"]),+ metadata: z.object({+ createdAt: z.string(),+ nested: z.object({ value: z.number() }),+ }),+ });+ const complexResult = zodSchemaToJsonSchema(complexSchema) as Record<string, unknown>;+ expect(complexResult.type).toBe("object");+ expect(complexResult.properties).toBeDefined();+ expect(complexResult.required).toContain("id");+ expect(complexResult.required).not.toContain("age");++ const enumResult = zodSchemaToJsonSchema(z.enum(["a", "b", "c"])) as Record<string, unknown>;+ expect(enumResult.enum).toEqual(["a", "b", "c"]);++ const arrayResult = zodSchemaToJsonSchema(z.array(z.number())) as Record<string, unknown>;+ expect(arrayResult.type).toBe("array");+ expect(arrayResult.items).toBeDefined();+ });++ test("zodSchemaToJsonSchema passes through non-Zod values unchanged", () => {+ const jsonSchema = { type: "object", properties: { name: { type: "string" } } };+ expect(zodSchemaToJsonSchema(jsonSchema)).toEqual(jsonSchema);+ expect(zodSchemaToJsonSchema(null)).toBe(null);+ expect(zodSchemaToJsonSchema(undefined)).toBe(undefined);+ expect(zodSchemaToJsonSchema("string")).toBe("string");+ expect(zodSchemaToJsonSchema(42)).toBe(42);+ expect(zodSchemaToJsonSchema({ foo: "bar" })).toEqual({ foo: "bar" });+ });++ test("looksLikeZodShape detects .shape property misuse", () => {+ const schema = z.object({ title: z.string(), count: z.number() });+ expect(looksLikeZodShape(schema.shape)).toBe(true);+ expect(looksLikeZodShape(schema)).toBe(false);+ expect(looksLikeZodShape(null)).toBe(false);+ expect(looksLikeZodShape(undefined)).toBe(false);+ expect(looksLikeZodShape({ name: "test" })).toBe(false);+ expect(looksLikeZodShape({})).toBe(false);+ expect(looksLikeZodShape([1, 2, 3])).toBe(false);+ expect(looksLikeZodShape({ type: "object", properties: {} })).toBe(false);+ });++ test("SDK-like usage: convert Zod schema or pass through JSON schema", () => {+ const zodSchema = z.object({+ name: z.string(),+ email: z.string().email(),+ age: z.number().min(0),+ });++ if (isZodSchema(zodSchema)) {+ const result = zodSchemaToJsonSchema(zodSchema) as Record<string, unknown>;+ expect(result.type).toBe("object");+ expect(result.properties).toBeDefined();+ } else {+ throw new Error("Should detect Zod schema");+ }++ const existingJsonSchema = {+ type: "object" as const,+ properties: { title: { type: "string" as const } },+ required: ["title"] as string[],+ };++ expect(isZodSchema(existingJsonSchema)).toBe(false);+ expect(zodSchemaToJsonSchema(existingJsonSchema)).toEqual(existingJsonSchema);+ });+});diff --git a/apps/js-sdk/firecrawl/src/utils/zodSchemaToJson.ts b/apps/js-sdk/firecrawl/src/utils/zodSchemaToJson.tsnew file mode 100644index 000000000..8f1dc70e2--- /dev/null+++ b/apps/js-sdk/firecrawl/src/utils/zodSchemaToJson.ts@@ -0,0 +1,67 @@+import { zodToJsonSchema as zodToJsonSchemaLib } from "zod-to-json-schema";++type SchemaConverter = (schema: unknown) => unknown;++export function isZodSchema(value: unknown): boolean {+ if (!value || typeof value !== "object") return false;+ const schema = value as Record<string, unknown>;++ const hasV3Markers =+ "_def" in schema &&+ (typeof schema.safeParse === "function" ||+ typeof schema.parse === "function");++ const hasV4Markers = "_zod" in schema && typeof schema._zod === "object";++ return hasV3Markers || hasV4Markers;+}++function isZodV4Schema(schema: unknown): boolean {+ if (!schema || typeof schema !== "object") return false;+ return "_zod" in schema && typeof (schema as Record<string, unknown>)._zod === "object";+}++function tryZodV4Conversion(schema: unknown): Record<string, unknown> | null {+ if (!isZodV4Schema(schema)) return null;++ try {+ const zodModule = (schema as Record<string, unknown>).constructor?.prototype?.constructor;+ if (zodModule && typeof (zodModule as Record<string, unknown>).toJSONSchema === "function") {+ return (zodModule as { toJSONSchema: SchemaConverter }).toJSONSchema(schema) as Record<string, unknown>;+ }+ } catch {+ // V4 conversion not available+ }++ return null;+}++export function zodSchemaToJsonSchema(schema: unknown): Record<string, unknown> | unknown {+ if (!isZodSchema(schema)) {+ return schema;+ }++ const v4Result = tryZodV4Conversion(schema);+ if (v4Result) {+ return v4Result;+ }++ try {+ return zodToJsonSchemaLib(schema as Parameters<typeof zodToJsonSchemaLib>[0]) as Record<string, unknown>;+ } catch {+ return schema;+ }+}++export function looksLikeZodShape(obj: unknown): boolean {+ if (!obj || typeof obj !== "object" || Array.isArray(obj)) return false;+ const values = Object.values(obj);+ if (values.length === 0) return false;+ return values.some(+ (v) =>+ v &&+ typeof v === "object" &&+ (v as Record<string, unknown>)._def &&+ typeof (v as Record<string, unknown>).safeParse === "function"+ );+}diff --git a/apps/js-sdk/firecrawl/src/v1/index.ts b/apps/js-sdk/firecrawl/src/v1/index.tsindex 21e935f65..ed72cb763 100644--- a/apps/js-sdk/firecrawl/src/v1/index.ts+++ b/apps/js-sdk/firecrawl/src/v1/index.ts@@ -1,6 +1,6 @@import axios, { type AxiosResponse, type AxiosRequestHeaders, AxiosError } from "axios";import * as zt from "zod";-import { zodToJsonSchema } from "zod-to-json-schema";+import { zodSchemaToJsonSchema } from "../utils/zodSchemaToJson";import { TypedEventTarget } from "typescript-event-target";/**@@ -707,36 +707,21 @@ export default class FirecrawlApp {} as AxiosRequestHeaders;let jsonData: any = { url, ...params, origin: typeof (params as any).origin === "string" && (params as any).origin.includes("mcp") ? (params as any).origin : `js-sdk@${this.version}` };if (jsonData?.extract?.schema) {- let schema = jsonData.extract.schema;-- // Try parsing the schema as a Zod schema- try {- schema = zodToJsonSchema(schema);- } catch (error) {-- }jsonData = {...jsonData,extract: {...jsonData.extract,- schema: schema,+ schema: zodSchemaToJsonSchema(jsonData.extract.schema),},};}if (jsonData?.jsonOptions?.schema) {- let schema = jsonData.jsonOptions.schema;- // Try parsing the schema as a Zod schema- try {- schema = zodToJsonSchema(schema);- } catch (error) {-- }jsonData = {...jsonData,jsonOptions: {...jsonData.jsonOptions,- schema: schema,+ schema: zodSchemaToJsonSchema(jsonData.jsonOptions.schema),},};}@@ -793,21 +778,13 @@ export default class FirecrawlApp {};if (jsonData?.scrapeOptions?.extract?.schema) {- let schema = jsonData.scrapeOptions.extract.schema;-- // Try parsing the schema as a Zod schema- try {- schema = zodToJsonSchema(schema);- } catch (error) {-- }jsonData = {...jsonData,scrapeOptions: {...jsonData.scrapeOptions,extract: {...jsonData.scrapeOptions.extract,- schema: schema,+ schema: zodSchemaToJsonSchema(jsonData.scrapeOptions.extract.schema),},},};@@ -1105,36 +1082,20 @@ export default class FirecrawlApp {const headers = this.prepareHeaders(idempotencyKey);let jsonData: any = { urls, webhook, ignoreInvalidURLs, maxConcurrency, ...params, origin: typeof (params as any).origin === "string" && (params as any).origin.includes("mcp") ? (params as any).origin : `js-sdk@${this.version}` };if (jsonData?.extract?.schema) {- let schema = jsonData.extract.schema;-- // Try parsing the schema as a Zod schema- try {- schema = zodToJsonSchema(schema);- } catch (error) {-- }jsonData = {...jsonData,extract: {...jsonData.extract,- schema: schema,+ schema: zodSchemaToJsonSchema(jsonData.extract.schema),},};}if (jsonData?.jsonOptions?.schema) {- let schema = jsonData.jsonOptions.schema;-- // Try parsing the schema as a Zod schema- try {- schema = zodToJsonSchema(schema);- } catch (error) {-- }jsonData = {...jsonData,jsonOptions: {...jsonData.jsonOptions,- schema: schema,+ schema: zodSchemaToJsonSchema(jsonData.jsonOptions.schema),},};}@@ -1326,20 +1287,7 @@ export default class FirecrawlApp {const headers = this.prepareHeaders();let jsonData: { urls?: string[] } & ExtractParams<T> = { urls: urls, ...params };- let jsonSchema: any;- try {- if (!params?.schema) {- jsonSchema = undefined;- } else {- try {- jsonSchema = zodToJsonSchema(params.schema as zt.ZodType);- } catch (_) {- jsonSchema = params.schema;- }- }- } catch (error: any) {- throw new FirecrawlError("Invalid schema. Schema must be either a valid Zod schema or JSON schema object.", 400);- }+ const jsonSchema = params?.schema ? zodSchemaToJsonSchema(params.schema) : undefined;try {const response: AxiosResponse = await this.postRequest(@@ -1396,22 +1344,8 @@ export default class FirecrawlApp {idempotencyKey?: string): Promise<ExtractResponse | ErrorResponse> {const headers = this.prepareHeaders(idempotencyKey);- let jsonData: any = { urls, ...params };- let jsonSchema: any;-- try {- if (!params?.schema) {- jsonSchema = undefined;- } else {- try {- jsonSchema = zodToJsonSchema(params.schema as zt.ZodType);- } catch (_) {- jsonSchema = params.schema;- }- }- } catch (error: any) {- throw new FirecrawlError("Invalid schema. Schema must be either a valid Zod schema or JSON schema object.", 400);- }+ const jsonData: any = { urls, ...params };+ const jsonSchema = params?.schema ? zodSchemaToJsonSchema(params.schema) : undefined;try {const response: AxiosResponse = await this.postRequest(@@ -1780,18 +1714,11 @@ export default class FirecrawlApp {let jsonData: any = { query, ...params, origin: typeof (params as any).origin === "string" && (params as any).origin.includes("mcp") ? (params as any).origin : `js-sdk@${this.version}` };if (jsonData?.jsonOptions?.schema) {- let schema = jsonData.jsonOptions.schema;- // Try parsing the schema as a Zod schema- try {- schema = zodToJsonSchema(schema);- } catch (error) {- // Ignore error if schema can't be parsed as Zod- }jsonData = {...jsonData,jsonOptions: {...jsonData.jsonOptions,- schema: schema,+ schema: zodSchemaToJsonSchema(jsonData.jsonOptions.schema),},};}diff --git a/apps/js-sdk/firecrawl/src/v2/methods/agent.ts b/apps/js-sdk/firecrawl/src/v2/methods/agent.tsindex 9200cfce2..ad7b4c482 100644--- a/apps/js-sdk/firecrawl/src/v2/methods/agent.ts+++ b/apps/js-sdk/firecrawl/src/v2/methods/agent.ts@@ -1,7 +1,7 @@import { type AgentResponse, type AgentStatusResponse, type AgentWebhookConfig } from "../types";import { HttpClient } from "../utils/httpClient";import { normalizeAxiosError, throwForBadResponse } from "../utils/errorHandler";-import { zodToJsonSchema } from "zod-to-json-schema";+import { isZodSchema, zodSchemaToJsonSchema } from "../../utils/zodSchemaToJson";import type { ZodTypeAny } from "zod";function prepareAgentPayload(args: {@@ -18,9 +18,7 @@ function prepareAgentPayload(args: {if (args.urls) body.urls = args.urls;body.prompt = args.prompt;if (args.schema != null) {- const s: any = args.schema;- const isZod = s && (typeof s.safeParse === "function" || typeof s.parse === "function") && s._def;- body.schema = isZod ? zodToJsonSchema(s) : args.schema;+ body.schema = isZodSchema(args.schema) ? zodSchemaToJsonSchema(args.schema) : args.schema;}if (args.integration && args.integration.trim()) body.integration = args.integration.trim();if (args.maxCredits !== null && args.maxCredits !== undefined) body.maxCredits = args.maxCredits;diff --git a/apps/js-sdk/firecrawl/src/v2/methods/extract.ts b/apps/js-sdk/firecrawl/src/v2/methods/extract.tsindex bf9bca09f..11e523dca 100644--- a/apps/js-sdk/firecrawl/src/v2/methods/extract.ts+++ b/apps/js-sdk/firecrawl/src/v2/methods/extract.ts@@ -2,7 +2,7 @@ import { type ExtractResponse, type ScrapeOptions, type AgentOptions } from "../import { HttpClient } from "../utils/httpClient";import { ensureValidScrapeOptions } from "../utils/validation";import { normalizeAxiosError, throwForBadResponse } from "../utils/errorHandler";-import { zodToJsonSchema } from "zod-to-json-schema";+import { isZodSchema, zodSchemaToJsonSchema } from "../../utils/zodSchemaToJson";import type { ZodTypeAny } from "zod";function prepareExtractPayload(args: {@@ -22,9 +22,7 @@ function prepareExtractPayload(args: {if (args.urls) body.urls = args.urls;if (args.prompt != null) body.prompt = args.prompt;if (args.schema != null) {- const s: any = args.schema;- const isZod = s && (typeof s.safeParse === "function" || typeof s.parse === "function") && s._def;- body.schema = isZod ? zodToJsonSchema(s) : args.schema;+ body.schema = isZodSchema(args.schema) ? zodSchemaToJsonSchema(args.schema) : args.schema;}if (args.systemPrompt != null) body.systemPrompt = args.systemPrompt;if (args.allowExternalLinks != null) body.allowExternalLinks = args.allowExternalLinks;diff --git a/apps/js-sdk/firecrawl/src/v2/utils/validation.ts b/apps/js-sdk/firecrawl/src/v2/utils/validation.tsindex c154a0938..bfb1ab1ae 100644--- a/apps/js-sdk/firecrawl/src/v2/utils/validation.ts+++ b/apps/js-sdk/firecrawl/src/v2/utils/validation.ts@@ -1,18 +1,5 @@import { type FormatOption, type JsonFormat, type ScrapeOptions, type ScreenshotFormat, type ChangeTrackingFormat } from "../types";-import { zodToJsonSchema } from "zod-to-json-schema";--/**- * Detects if an object looks like a Zod schema's `.shape` property.- * When users mistakenly pass `schema.shape` instead of `schema`, the object- * will have Zod types as values but won't be a Zod schema itself.- */-function looksLikeZodShape(obj: unknown): boolean {- if (!obj || typeof obj !== "object" || Array.isArray(obj)) return false;- const values = Object.values(obj);- if (values.length === 0) return false;- // Check if at least one value looks like a Zod type- return values.some((v: any) => v && typeof v === "object" && v._def && typeof v.safeParse === "function");-}+import { isZodSchema, zodSchemaToJsonSchema, looksLikeZodShape } from "../../utils/zodSchemaToJson";export function ensureValidFormats(formats?: FormatOption[]): void {if (!formats) return;@@ -28,17 +15,10 @@ export function ensureValidFormats(formats?: FormatOption[]): void {if (!j.prompt && !j.schema) {throw new Error("json format requires either 'prompt' or 'schema' (or both)");}- // Flexibility: allow passing a Zod schema. Convert to JSON schema internally.- const maybeSchema: any = j.schema as any;- const isZod = !!maybeSchema && (typeof maybeSchema.safeParse === "function" || typeof maybeSchema.parse === "function") && !!maybeSchema._def;- if (isZod) {- try {- (j as any).schema = zodToJsonSchema(maybeSchema);- } catch {- // If conversion fails, leave as-is; server-side may still handle, or request will fail explicitly- }+ const maybeSchema = j.schema;+ if (isZodSchema(maybeSchema)) {+ (j as any).schema = zodSchemaToJsonSchema(maybeSchema);} else if (looksLikeZodShape(maybeSchema)) {- // User likely passed schema.shape instead of the schema itselfthrow 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`. " +@@ -49,14 +29,9 @@ export function ensureValidFormats(formats?: FormatOption[]): void {}if ((fmt as ChangeTrackingFormat).type === "changeTracking") {const ct = fmt as ChangeTrackingFormat;- const maybeSchema: any = ct.schema as any;- const isZod = !!maybeSchema && (typeof maybeSchema.safeParse === "function" || typeof maybeSchema.parse === "function") && !!maybeSchema._def;- if (isZod) {- try {- (ct as any).schema = zodToJsonSchema(maybeSchema);- } catch {- // Best-effort conversion; if it fails, leave original value- }+ const maybeSchema = ct.schema;+ if (isZodSchema(maybeSchema)) {+ (ct as any).schema = zodSchemaToJsonSchema(maybeSchema);} else if (looksLikeZodShape(maybeSchema)) {throw new Error("changeTracking format schema appears to be a Zod schema's .shape property. " +