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): 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.jsonindex 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.tsindex 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.tsindex 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;}