@mendable/firecrawl 4.11.0 → 4.11.2

package/dist/{chunk-X3D7QXG6.js → chunk-GVCNL5KA.js}

@@ -8,7 +8,7 @@ var require_package = __commonJS({
   "package.json"(exports, module) {
     module.exports = {
       name: "@mendable/firecrawl-js",
-      version: "4.11.0",
+      version: "4.11.2",
       description: "JavaScript SDK for Firecrawl API",
       main: "dist/index.js",
       types: "dist/index.d.ts",
@@ -22,8 +22,8 @@ var require_package = __commonJS({
       type: "module",
       scripts: {
         build: "tsup",
-        "build-and-publish": "npm run build && npm publish --access public",
-        "publish-beta": "npm run build && npm publish --access public --tag beta",
+        "build-and-publish": "pnpm run build && pnpm publish --access public",
+        "publish-beta": "pnpm run build && pnpm publish --access public --tag beta",
         test: "NODE_OPTIONS=--experimental-vm-modules jest --verbose src/__tests__/e2e/v2/*.test.ts --detectOpenHandles",
         "test:unit": "NODE_OPTIONS=--experimental-vm-modules jest --verbose src/__tests__/unit/v2/*.test.ts"
       },

package/dist/index.cjs

@@ -35,7 +35,7 @@ var require_package = __commonJS({
   "package.json"(exports2, module2) {
     module2.exports = {
       name: "@mendable/firecrawl-js",
-      version: "4.11.0",
+      version: "4.11.2",
       description: "JavaScript SDK for Firecrawl API",
       main: "dist/index.js",
       types: "dist/index.d.ts",
@@ -49,8 +49,8 @@ var require_package = __commonJS({
       type: "module",
       scripts: {
         build: "tsup",
-        "build-and-publish": "npm run build && npm publish --access public",
-        "publish-beta": "npm run build && npm publish --access public --tag beta",
+        "build-and-publish": "pnpm run build && pnpm publish --access public",
+        "publish-beta": "pnpm run build && pnpm publish --access public --tag beta",
         test: "NODE_OPTIONS=--experimental-vm-modules jest --verbose src/__tests__/e2e/v2/*.test.ts --detectOpenHandles",
         "test:unit": "NODE_OPTIONS=--experimental-vm-modules jest --verbose src/__tests__/unit/v2/*.test.ts"
       },
@@ -251,6 +251,12 @@ var JobTimeoutError = class extends SdkError {
 
 // src/v2/utils/validation.ts
 var import_zod_to_json_schema = require("zod-to-json-schema");
+function looksLikeZodShape(obj) {
+  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._def && typeof v.safeParse === "function");
+}
 function ensureValidFormats(formats) {
   if (!formats) return;
   for (const fmt of formats) {
@@ -272,6 +278,10 @@ function ensureValidFormats(formats) {
           j.schema = (0, import_zod_to_json_schema.zodToJsonSchema)(maybeSchema);
         } catch {
         }
+      } 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."
+        );
       }
       continue;
     }
@@ -284,6 +294,10 @@ function ensureValidFormats(formats) {
           ct.schema = (0, import_zod_to_json_schema.zodToJsonSchema)(maybeSchema);
         } catch {
         }
+      } 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;
     }
@@ -841,6 +855,7 @@ function prepareAgentPayload(args) {
   if (args.maxCredits !== null && args.maxCredits !== void 0) body.maxCredits = args.maxCredits;
   if (args.strictConstrainToURLs !== null && args.strictConstrainToURLs !== void 0) body.strictConstrainToURLs = args.strictConstrainToURLs;
   if (args.model !== null && args.model !== void 0) body.model = args.model;
+  if (args.webhook != null) body.webhook = args.webhook;
   return body;
 }
 async function startAgent(http, args) {
@@ -1424,7 +1439,7 @@ var import_axios3 = __toESM(require("axios"), 1);
 var zt2 = require("zod");
 var import_zod_to_json_schema4 = require("zod-to-json-schema");
 
-// node_modules/typescript-event-target/dist/index.mjs
+// node_modules/.pnpm/typescript-event-target@1.1.1/node_modules/typescript-event-target/dist/index.mjs
 var e = class extends EventTarget {
   dispatchTypedEvent(s, t) {
     return super.dispatchEvent(t);

package/dist/index.d.cts

@@ -122,6 +122,13 @@ interface WebhookConfig {
     metadata?: Record<string, string>;
     events?: Array<'completed' | 'failed' | 'page' | 'started'>;
 }
+type AgentWebhookEvent = 'started' | 'action' | 'completed' | 'failed' | 'cancelled';
+interface AgentWebhookConfig {
+    url: string;
+    headers?: Record<string, string>;
+    metadata?: Record<string, string>;
+    events?: AgentWebhookEvent[];
+}
 interface BrandingProfile {
     colorScheme?: 'light' | 'dark';
     logo?: string | null;
@@ -594,6 +601,7 @@ declare function prepareAgentPayload(args: {
     maxCredits?: number;
     strictConstrainToURLs?: boolean;
     model?: "spark-1-pro" | "spark-1-mini";
+    webhook?: string | AgentWebhookConfig;
 }): Record<string, unknown>;
 declare function startAgent(http: HttpClient, args: Parameters<typeof prepareAgentPayload>[0]): Promise<AgentResponse>;
 
@@ -1727,4 +1735,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 AttributesFormat, type BatchScrapeJob, type BatchScrapeOptions, type BatchScrapeResponse$1 as BatchScrapeResponse, type BrandingProfile, 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 QueueStatusResponse$1 as QueueStatusResponse, type ScrapeAction, 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, 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 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 QueueStatusResponse$1 as QueueStatusResponse, type ScrapeAction, 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, type WebhookConfig, type WriteAction, Firecrawl as default };

package/dist/index.d.ts

@@ -122,6 +122,13 @@ interface WebhookConfig {
     metadata?: Record<string, string>;
     events?: Array<'completed' | 'failed' | 'page' | 'started'>;
 }
+type AgentWebhookEvent = 'started' | 'action' | 'completed' | 'failed' | 'cancelled';
+interface AgentWebhookConfig {
+    url: string;
+    headers?: Record<string, string>;
+    metadata?: Record<string, string>;
+    events?: AgentWebhookEvent[];
+}
 interface BrandingProfile {
     colorScheme?: 'light' | 'dark';
     logo?: string | null;
@@ -594,6 +601,7 @@ declare function prepareAgentPayload(args: {
     maxCredits?: number;
     strictConstrainToURLs?: boolean;
     model?: "spark-1-pro" | "spark-1-mini";
+    webhook?: string | AgentWebhookConfig;
 }): Record<string, unknown>;
 declare function startAgent(http: HttpClient, args: Parameters<typeof prepareAgentPayload>[0]): Promise<AgentResponse>;
 
@@ -1727,4 +1735,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 AttributesFormat, type BatchScrapeJob, type BatchScrapeOptions, type BatchScrapeResponse$1 as BatchScrapeResponse, type BrandingProfile, 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 QueueStatusResponse$1 as QueueStatusResponse, type ScrapeAction, 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, 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 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 QueueStatusResponse$1 as QueueStatusResponse, type ScrapeAction, 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, type WebhookConfig, type WriteAction, Firecrawl as default };

package/dist/index.js

@@ -1,6 +1,6 @@
 import {
   require_package
-} from "./chunk-X3D7QXG6.js";
+} from "./chunk-GVCNL5KA.js";
 
 // src/v2/utils/httpClient.ts
 import axios from "axios";
@@ -132,6 +132,12 @@ var JobTimeoutError = class extends SdkError {
 
 // src/v2/utils/validation.ts
 import { zodToJsonSchema } from "zod-to-json-schema";
+function looksLikeZodShape(obj) {
+  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._def && typeof v.safeParse === "function");
+}
 function ensureValidFormats(formats) {
   if (!formats) return;
   for (const fmt of formats) {
@@ -153,6 +159,10 @@ function ensureValidFormats(formats) {
           j.schema = zodToJsonSchema(maybeSchema);
         } catch {
         }
+      } 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."
+        );
       }
       continue;
     }
@@ -165,6 +175,10 @@ function ensureValidFormats(formats) {
           ct.schema = zodToJsonSchema(maybeSchema);
         } catch {
         }
+      } 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;
     }
@@ -722,6 +736,7 @@ function prepareAgentPayload(args) {
   if (args.maxCredits !== null && args.maxCredits !== void 0) body.maxCredits = args.maxCredits;
   if (args.strictConstrainToURLs !== null && args.strictConstrainToURLs !== void 0) body.strictConstrainToURLs = args.strictConstrainToURLs;
   if (args.model !== null && args.model !== void 0) body.model = args.model;
+  if (args.webhook != null) body.webhook = args.webhook;
   return body;
 }
 async function startAgent(http, args) {
@@ -1305,7 +1320,7 @@ import axios2, { AxiosError } from "axios";
 import "zod";
 import { zodToJsonSchema as zodToJsonSchema4 } from "zod-to-json-schema";
 
-// node_modules/typescript-event-target/dist/index.mjs
+// node_modules/.pnpm/typescript-event-target@1.1.1/node_modules/typescript-event-target/dist/index.mjs
 var e = class extends EventTarget {
   dispatchTypedEvent(s, t) {
     return super.dispatchEvent(t);
@@ -1334,7 +1349,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-A5RBY34U.js");
+      const packageJson = await import("./package-LU5XQZAL.js");
       return packageJson.default.version;
     } catch (error) {
       const isTest = typeof process !== "undefined" && (process.env.JEST_WORKER_ID != null || false);

package/dist/{package-A5RBY34U.js → package-LU5XQZAL.js}

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

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@mendable/firecrawl",
-  "version": "4.11.0",
+  "version": "4.11.2",
   "description": "JavaScript SDK for Firecrawl API",
   "main": "dist/index.js",
   "types": "dist/index.d.ts",
@@ -12,13 +12,6 @@
     }
   },
   "type": "module",
-  "scripts": {
-    "build": "tsup",
-    "build-and-publish": "npm run build && npm publish --access public",
-    "publish-beta": "npm run build && npm publish --access public --tag beta",
-    "test": "NODE_OPTIONS=--experimental-vm-modules jest --verbose src/__tests__/e2e/v2/*.test.ts --detectOpenHandles",
-    "test:unit": "NODE_OPTIONS=--experimental-vm-modules jest --verbose src/__tests__/unit/v2/*.test.ts"
-  },
   "repository": {
     "type": "git",
     "url": "git+https://github.com/firecrawl/firecrawl.git"
@@ -61,13 +54,11 @@
   "engines": {
     "node": ">=22.0.0"
   },
-  "pnpm": {
-    "overrides": {
-      "@babel/helpers@<7.26.10": ">=7.26.10",
-      "brace-expansion@>=1.0.0 <=1.1.11": ">=1.1.12",
-      "brace-expansion@>=2.0.0 <=2.0.1": ">=2.0.2",
-      "js-yaml@<3.14.2": ">=3.14.2",
-      "glob@>=10.2.0 <10.5.0": ">=10.5.0"
-    }
+  "scripts": {
+    "build": "tsup",
+    "build-and-publish": "pnpm run build && pnpm publish --access public",
+    "publish-beta": "pnpm run build && pnpm publish --access public --tag beta",
+    "test": "NODE_OPTIONS=--experimental-vm-modules jest --verbose src/__tests__/e2e/v2/*.test.ts --detectOpenHandles",
+    "test:unit": "NODE_OPTIONS=--experimental-vm-modules jest --verbose src/__tests__/unit/v2/*.test.ts"
   }
-}
+}

package/src/__tests__/unit/v2/agent.test.ts

@@ -0,0 +1,80 @@
+import { describe, test, expect } from "@jest/globals";
+
+// We need to test the prepareAgentPayload function, but it's not exported.
+// Since the function is internal, we'll test the behavior through type checking
+// and verify the types are properly exported.
+
+import type { AgentWebhookConfig, AgentWebhookEvent } from "../../../v2/types";
+
+describe("v2 types: Agent webhook types", () => {
+  test("AgentWebhookConfig accepts string webhook", () => {
+    // Type check - this should compile without errors
+    const webhook: string | AgentWebhookConfig = "https://example.com/webhook";
+    expect(typeof webhook).toBe("string");
+  });
+
+  test("AgentWebhookConfig accepts config object", () => {
+    const config: AgentWebhookConfig = {
+      url: "https://example.com/webhook",
+      headers: { Authorization: "Bearer token" },
+      events: ["completed", "failed"],
+    };
+    expect(config.url).toBe("https://example.com/webhook");
+    expect(config.headers).toEqual({ Authorization: "Bearer token" });
+    expect(config.events).toEqual(["completed", "failed"]);
+  });
+
+  test("AgentWebhookConfig accepts minimal config", () => {
+    const config: AgentWebhookConfig = {
+      url: "https://example.com/webhook",
+    };
+    expect(config.url).toBe("https://example.com/webhook");
+    expect(config.headers).toBeUndefined();
+    expect(config.metadata).toBeUndefined();
+    expect(config.events).toBeUndefined();
+  });
+
+  test("AgentWebhookEvent includes agent-specific events", () => {
+    const events: AgentWebhookEvent[] = [
+      "started",
+      "action",
+      "completed",
+      "failed",
+      "cancelled",
+    ];
+    expect(events).toContain("action");
+    expect(events).toContain("cancelled");
+    expect(events.length).toBe(5);
+  });
+
+  test("AgentWebhookConfig accepts all fields", () => {
+    const config: AgentWebhookConfig = {
+      url: "https://example.com/webhook",
+      headers: {
+        Authorization: "Bearer token",
+        "X-Custom-Header": "value",
+      },
+      metadata: {
+        project: "test",
+        environment: "staging",
+      },
+      events: ["started", "action", "completed", "failed", "cancelled"],
+    };
+    expect(config.url).toBe("https://example.com/webhook");
+    expect(Object.keys(config.headers!).length).toBe(2);
+    expect(config.metadata!.project).toBe("test");
+    expect(config.events!.length).toBe(5);
+  });
+
+  test("AgentWebhookConfig events are agent-specific (not crawl)", () => {
+    // Agent has 'action' and 'cancelled', but not 'page'
+    const config: AgentWebhookConfig = {
+      url: "https://example.com/webhook",
+      events: ["action", "cancelled"],
+    };
+    expect(config.events).toContain("action");
+    expect(config.events).toContain("cancelled");
+    // 'page' is a crawl-specific event, not valid for agent
+    // This is enforced at the type level
+  });
+});

package/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);
+  });
 });
 

package/src/v2/methods/agent.ts

@@ -1,4 +1,4 @@
-import { type AgentResponse, type AgentStatusResponse } from "../types";
+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";
@@ -12,6 +12,7 @@ function prepareAgentPayload(args: {
   maxCredits?: number;
   strictConstrainToURLs?: boolean;
   model?: "spark-1-pro" | "spark-1-mini";
+  webhook?: string | AgentWebhookConfig;
 }): Record<string, unknown> {
   const body: Record<string, unknown> = {};
   if (args.urls) body.urls = args.urls;
@@ -25,6 +26,7 @@ function prepareAgentPayload(args: {
   if (args.maxCredits !== null && args.maxCredits !== undefined) body.maxCredits = args.maxCredits;
   if (args.strictConstrainToURLs !== null && args.strictConstrainToURLs !== undefined) body.strictConstrainToURLs = args.strictConstrainToURLs;
   if (args.model !== null && args.model !== undefined) body.model = args.model;
+  if (args.webhook != null) body.webhook = args.webhook;
   return body;
 }
 

package/src/v2/types.ts

@@ -167,6 +167,16 @@ export interface WebhookConfig {
   events?: Array<'completed' | 'failed' | 'page' | 'started'>;
 }
 
+// Agent webhook events differ from crawl: has 'action' and 'cancelled', no 'page'
+export type AgentWebhookEvent = 'started' | 'action' | 'completed' | 'failed' | 'cancelled';
+
+export interface AgentWebhookConfig {
+  url: string;
+  headers?: Record<string, string>;
+  metadata?: Record<string, string>;
+  events?: AgentWebhookEvent[];
+}
+
 export interface BrandingProfile {
   colorScheme?: 'light' | 'dark';
   logo?: string | null;

package/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;
     }