Skip to content

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

fix(js-sdk): detect mistaken use of Zod schema.shape and provide helpful error (#2684)

firecrawl-spring[bot]3a30784b1c66
diff --git a/apps/js-sdk/firecrawl/package.json b/apps/js-sdk/firecrawl/package.json
index 55145d200..0728afccb 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.0",
+ "version": "4.11.1",
"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/validation.test.ts b/apps/js-sdk/firecrawl/src/__tests__/unit/v2/validation.test.ts
index ba0b55112..83a35546a 100644
--- a/apps/js-sdk/firecrawl/src/__tests__/unit/v2/validation.test.ts
+++ b/apps/js-sdk/firecrawl/src/__tests__/unit/v2/validation.test.ts
@@ -62,5 +62,23 @@ describe("v2 utils: validation", () => {
expect(() => ensureValidScrapeOptions(options)).not.toThrow();
expect(options.parsers).toEqual(before);
});
+
+ test("ensureValidFormats: detects mistaken use of zod schema.shape", () => {
+ const schema = z.object({ title: z.string(), count: z.number() });
+ // User mistakenly passes schema.shape instead of schema
+ const formats: FormatOption[] = [
+ { type: "json", prompt: "extract", schema: schema.shape } as any,
+ ];
+ expect(() => ensureValidFormats(formats)).toThrow(/\.shape property/i);
+ expect(() => ensureValidFormats(formats)).toThrow(/Pass the Zod schema directly/i);
+ });
+
+ test("ensureValidFormats: detects mistaken use of zod schema.shape in changeTracking", () => {
+ const schema = z.object({ title: z.string() });
+ const formats: FormatOption[] = [
+ { type: "changeTracking", modes: ["json"], schema: schema.shape } as any,
+ ];
+ expect(() => ensureValidFormats(formats)).toThrow(/\.shape property/i);
+ });
});
diff --git a/apps/js-sdk/firecrawl/src/v2/utils/validation.ts b/apps/js-sdk/firecrawl/src/v2/utils/validation.ts
index 09e65735b..c154a0938 100644
--- a/apps/js-sdk/firecrawl/src/v2/utils/validation.ts
+++ b/apps/js-sdk/firecrawl/src/v2/utils/validation.ts
@@ -1,6 +1,19 @@
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");
+}
+
export function ensureValidFormats(formats?: FormatOption[]): void {
if (!formats) return;
for (const fmt of formats) {
@@ -24,6 +37,13 @@ export function ensureValidFormats(formats?: FormatOption[]): void {
} catch {
// If conversion fails, leave as-is; server-side may still handle, or request will fail explicitly
}
+ } 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`. " +
+ "The SDK will automatically convert Zod schemas to JSON Schema format."
+ );
}
continue;
}
@@ -37,6 +57,12 @@ export function ensureValidFormats(formats?: FormatOption[]): void {
} catch {
// Best-effort conversion; if it fails, leave original value
}
+ } else if (looksLikeZodShape(maybeSchema)) {
+ throw new Error(
+ "changeTracking 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;
}