Skip to content

Supercharge your AI agents with data from the web and beyond. Building the library for superintelligence. 🔥

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.json
index 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.ts
new file mode 100644
index 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.ts
new file mode 100644
index 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.ts
index 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.ts
index 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.ts
index 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.ts
index 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 itself
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`. " +
@@ -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. " +