firecrawl 4.8.2 → 4.9.0

package/dist/{chunk-3IN25WJ7.js → chunk-KS6E546Q.js}

@@ -8,7 +8,7 @@ var require_package = __commonJS({
   "package.json"(exports, module) {
     module.exports = {
       name: "@mendable/firecrawl-js",
-      version: "4.8.2",
+      version: "4.9.0",
       description: "JavaScript SDK for Firecrawl API",
       main: "dist/index.js",
       types: "dist/index.d.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.8.2",
+      version: "4.9.0",
       description: "JavaScript SDK for Firecrawl API",
       main: "dist/index.js",
       types: "dist/index.d.ts",
@@ -150,7 +150,7 @@ var HttpClient = class {
     this.backoffFactor = options.backoffFactor ?? 0.5;
     this.instance = import_axios.default.create({
       baseURL: this.apiUrl,
-      timeout: options.timeoutMs ?? 6e4,
+      timeout: options.timeoutMs ?? 3e5,
       headers: {
         "Content-Type": "application/json",
         Authorization: `Bearer ${this.apiKey}`
@@ -751,6 +751,57 @@ async function extract(http, args) {
   return waitExtract(http, jobId, args.pollInterval ?? 2, args.timeout);
 }
 
+// src/v2/methods/agent.ts
+var import_zod_to_json_schema3 = require("zod-to-json-schema");
+function prepareAgentPayload(args) {
+  const body = {};
+  if (args.urls) body.urls = args.urls;
+  body.prompt = args.prompt;
+  if (args.schema != null) {
+    const s = args.schema;
+    const isZod = s && (typeof s.safeParse === "function" || typeof s.parse === "function") && s._def;
+    body.schema = isZod ? (0, import_zod_to_json_schema3.zodToJsonSchema)(s) : args.schema;
+  }
+  if (args.integration && args.integration.trim()) body.integration = args.integration.trim();
+  return body;
+}
+async function startAgent(http, args) {
+  const payload = prepareAgentPayload(args);
+  try {
+    const res = await http.post("/v2/agent", payload);
+    if (res.status !== 200) throwForBadResponse(res, "agent");
+    return res.data;
+  } catch (err) {
+    if (err?.isAxiosError) return normalizeAxiosError(err, "agent");
+    throw err;
+  }
+}
+async function getAgentStatus(http, jobId) {
+  try {
+    const res = await http.get(`/v2/agent/${jobId}`);
+    if (res.status !== 200) throwForBadResponse(res, "agent status");
+    return res.data;
+  } catch (err) {
+    if (err?.isAxiosError) return normalizeAxiosError(err, "agent status");
+    throw err;
+  }
+}
+async function waitAgent(http, jobId, pollInterval = 2, timeout) {
+  const start = Date.now();
+  while (true) {
+    const status = await getAgentStatus(http, jobId);
+    if (["completed", "failed", "cancelled"].includes(status.status || "")) return status;
+    if (timeout != null && Date.now() - start > timeout * 1e3) return status;
+    await new Promise((r) => setTimeout(r, Math.max(1e3, pollInterval * 1e3)));
+  }
+}
+async function agent(http, args) {
+  const started = await startAgent(http, args);
+  const jobId = started.id;
+  if (!jobId) return started;
+  return waitAgent(http, jobId, args.pollInterval ?? 2, args.timeout);
+}
+
 // src/v2/methods/usage.ts
 async function getConcurrency(http) {
   try {
@@ -1212,6 +1263,30 @@ var FirecrawlClient = class {
   async extract(args) {
     return extract(this.http, args);
   }
+  // Agent
+  /**
+   * Start an agent job (async).
+   * @param args Agent request (urls, prompt, schema).
+   * @returns Job id or processing state.
+   */
+  async startAgent(args) {
+    return startAgent(this.http, args);
+  }
+  /**
+   * Get agent job status/data.
+   * @param jobId Agent job id.
+   */
+  async getAgentStatus(jobId) {
+    return getAgentStatus(this.http, jobId);
+  }
+  /**
+   * Convenience waiter: start an agent and poll until it finishes.
+   * @param args Agent request plus waiter controls (pollInterval, timeout seconds).
+   * @returns Final agent response.
+   */
+  async agent(args) {
+    return agent(this.http, args);
+  }
   // Usage
   /** Current concurrency usage. */
   async getConcurrency() {
@@ -1251,7 +1326,7 @@ var FirecrawlClient = class {
 // src/v1/index.ts
 var import_axios3 = __toESM(require("axios"), 1);
 var zt2 = require("zod");
-var import_zod_to_json_schema3 = require("zod-to-json-schema");
+var import_zod_to_json_schema4 = require("zod-to-json-schema");
 
 // node_modules/typescript-event-target/dist/index.mjs
 var e = class extends EventTarget {
@@ -1323,7 +1398,7 @@ var FirecrawlApp = class {
     if (jsonData?.extract?.schema) {
       let schema = jsonData.extract.schema;
       try {
-        schema = (0, import_zod_to_json_schema3.zodToJsonSchema)(schema);
+        schema = (0, import_zod_to_json_schema4.zodToJsonSchema)(schema);
       } catch (error) {
       }
       jsonData = {
@@ -1337,7 +1412,7 @@ var FirecrawlApp = class {
     if (jsonData?.jsonOptions?.schema) {
       let schema = jsonData.jsonOptions.schema;
       try {
-        schema = (0, import_zod_to_json_schema3.zodToJsonSchema)(schema);
+        schema = (0, import_zod_to_json_schema4.zodToJsonSchema)(schema);
       } catch (error) {
       }
       jsonData = {
@@ -1400,7 +1475,7 @@ var FirecrawlApp = class {
     if (jsonData?.scrapeOptions?.extract?.schema) {
       let schema = jsonData.scrapeOptions.extract.schema;
       try {
-        schema = (0, import_zod_to_json_schema3.zodToJsonSchema)(schema);
+        schema = (0, import_zod_to_json_schema4.zodToJsonSchema)(schema);
       } catch (error) {
       }
       jsonData = {
@@ -1669,7 +1744,7 @@ var FirecrawlApp = class {
     if (jsonData?.extract?.schema) {
       let schema = jsonData.extract.schema;
       try {
-        schema = (0, import_zod_to_json_schema3.zodToJsonSchema)(schema);
+        schema = (0, import_zod_to_json_schema4.zodToJsonSchema)(schema);
       } catch (error) {
       }
       jsonData = {
@@ -1683,7 +1758,7 @@ var FirecrawlApp = class {
     if (jsonData?.jsonOptions?.schema) {
       let schema = jsonData.jsonOptions.schema;
       try {
-        schema = (0, import_zod_to_json_schema3.zodToJsonSchema)(schema);
+        schema = (0, import_zod_to_json_schema4.zodToJsonSchema)(schema);
       } catch (error) {
       }
       jsonData = {
@@ -1862,7 +1937,7 @@ var FirecrawlApp = class {
         jsonSchema = void 0;
       } else {
         try {
-          jsonSchema = (0, import_zod_to_json_schema3.zodToJsonSchema)(params.schema);
+          jsonSchema = (0, import_zod_to_json_schema4.zodToJsonSchema)(params.schema);
         } catch (_) {
           jsonSchema = params.schema;
         }
@@ -1926,7 +2001,7 @@ var FirecrawlApp = class {
         jsonSchema = void 0;
       } else {
         try {
-          jsonSchema = (0, import_zod_to_json_schema3.zodToJsonSchema)(params.schema);
+          jsonSchema = (0, import_zod_to_json_schema4.zodToJsonSchema)(params.schema);
         } catch (_) {
           jsonSchema = params.schema;
         }
@@ -2217,7 +2292,7 @@ var FirecrawlApp = class {
     if (jsonData?.jsonOptions?.schema) {
       let schema = jsonData.jsonOptions.schema;
       try {
-        schema = (0, import_zod_to_json_schema3.zodToJsonSchema)(schema);
+        schema = (0, import_zod_to_json_schema4.zodToJsonSchema)(schema);
       } catch (error) {
       }
       jsonData = {

package/dist/index.d.cts

@@ -283,10 +283,13 @@ interface DocumentMetadata {
     scrapeId?: string;
     numPages?: number;
     contentType?: string;
+    timezone?: string;
     proxyUsed?: 'basic' | 'stealth';
     cacheState?: 'hit' | 'miss';
     cachedAt?: string;
     creditsUsed?: number;
+    concurrencyLimited?: boolean;
+    concurrencyQueueDurationMs?: number;
     error?: string;
     [key: string]: unknown;
 }
@@ -446,8 +449,21 @@ interface ExtractResponse$1 {
     expiresAt?: string;
     creditsUsed?: number;
 }
+interface AgentResponse {
+    success: boolean;
+    id: string;
+    error?: string;
+}
+interface AgentStatusResponse {
+    success: boolean;
+    status: 'processing' | 'completed' | 'failed';
+    error?: string;
+    data?: unknown;
+    expiresAt: string;
+    creditsUsed?: number;
+}
 interface AgentOptions$1 {
-    model: 'FIRE-1';
+    model: 'FIRE-1' | 'v3-beta';
 }
 interface ConcurrencyCheck {
     concurrency: number;
@@ -565,6 +581,14 @@ declare function prepareExtractPayload(args: {
 }): Record<string, unknown>;
 declare function startExtract(http: HttpClient, args: Parameters<typeof prepareExtractPayload>[0]): Promise<ExtractResponse$1>;
 
+declare function prepareAgentPayload(args: {
+    urls?: string[];
+    prompt: string;
+    schema?: Record<string, unknown> | ZodTypeAny;
+    integration?: string;
+}): Record<string, unknown>;
+declare function startAgent(http: HttpClient, args: Parameters<typeof prepareAgentPayload>[0]): Promise<AgentResponse>;
+
 type JobKind = "crawl" | "batch";
 interface WatcherOptions {
     kind?: JobKind;
@@ -744,6 +768,26 @@ declare class FirecrawlClient {
         pollInterval?: number;
         timeout?: number;
     }): Promise<ExtractResponse$1>;
+    /**
+     * Start an agent job (async).
+     * @param args Agent request (urls, prompt, schema).
+     * @returns Job id or processing state.
+     */
+    startAgent(args: Parameters<typeof startAgent>[1]): Promise<AgentResponse>;
+    /**
+     * Get agent job status/data.
+     * @param jobId Agent job id.
+     */
+    getAgentStatus(jobId: string): Promise<AgentStatusResponse>;
+    /**
+     * Convenience waiter: start an agent and poll until it finishes.
+     * @param args Agent request plus waiter controls (pollInterval, timeout seconds).
+     * @returns Final agent response.
+     */
+    agent(args: Parameters<typeof startAgent>[1] & {
+        pollInterval?: number;
+        timeout?: number;
+    }): Promise<AgentStatusResponse>;
     /** Current concurrency usage. */
     getConcurrency(): Promise<ConcurrencyCheck>;
     /** Current credit usage. */
@@ -809,10 +853,14 @@ interface FirecrawlDocumentMetadata {
     articleSection?: string;
     sourceURL?: string;
     statusCode?: number;
+    timezone?: string;
     error?: string;
     proxyUsed?: "basic" | "stealth";
     cacheState?: "miss" | "hit";
     cachedAt?: string;
+    creditsUsed?: number;
+    concurrencyLimited?: boolean;
+    concurrencyQueueDurationMs?: number;
     [key: string]: any;
 }
 /**
@@ -1665,4 +1713,4 @@ declare class Firecrawl extends FirecrawlClient {
     get v1(): FirecrawlApp;
 }
 
-export { type ActionOption, type ActiveCrawl, type ActiveCrawlsResponse, type AgentOptions$1 as AgentOptions, 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, 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 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, 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

@@ -283,10 +283,13 @@ interface DocumentMetadata {
     scrapeId?: string;
     numPages?: number;
     contentType?: string;
+    timezone?: string;
     proxyUsed?: 'basic' | 'stealth';
     cacheState?: 'hit' | 'miss';
     cachedAt?: string;
     creditsUsed?: number;
+    concurrencyLimited?: boolean;
+    concurrencyQueueDurationMs?: number;
     error?: string;
     [key: string]: unknown;
 }
@@ -446,8 +449,21 @@ interface ExtractResponse$1 {
     expiresAt?: string;
     creditsUsed?: number;
 }
+interface AgentResponse {
+    success: boolean;
+    id: string;
+    error?: string;
+}
+interface AgentStatusResponse {
+    success: boolean;
+    status: 'processing' | 'completed' | 'failed';
+    error?: string;
+    data?: unknown;
+    expiresAt: string;
+    creditsUsed?: number;
+}
 interface AgentOptions$1 {
-    model: 'FIRE-1';
+    model: 'FIRE-1' | 'v3-beta';
 }
 interface ConcurrencyCheck {
     concurrency: number;
@@ -565,6 +581,14 @@ declare function prepareExtractPayload(args: {
 }): Record<string, unknown>;
 declare function startExtract(http: HttpClient, args: Parameters<typeof prepareExtractPayload>[0]): Promise<ExtractResponse$1>;
 
+declare function prepareAgentPayload(args: {
+    urls?: string[];
+    prompt: string;
+    schema?: Record<string, unknown> | ZodTypeAny;
+    integration?: string;
+}): Record<string, unknown>;
+declare function startAgent(http: HttpClient, args: Parameters<typeof prepareAgentPayload>[0]): Promise<AgentResponse>;
+
 type JobKind = "crawl" | "batch";
 interface WatcherOptions {
     kind?: JobKind;
@@ -744,6 +768,26 @@ declare class FirecrawlClient {
         pollInterval?: number;
         timeout?: number;
     }): Promise<ExtractResponse$1>;
+    /**
+     * Start an agent job (async).
+     * @param args Agent request (urls, prompt, schema).
+     * @returns Job id or processing state.
+     */
+    startAgent(args: Parameters<typeof startAgent>[1]): Promise<AgentResponse>;
+    /**
+     * Get agent job status/data.
+     * @param jobId Agent job id.
+     */
+    getAgentStatus(jobId: string): Promise<AgentStatusResponse>;
+    /**
+     * Convenience waiter: start an agent and poll until it finishes.
+     * @param args Agent request plus waiter controls (pollInterval, timeout seconds).
+     * @returns Final agent response.
+     */
+    agent(args: Parameters<typeof startAgent>[1] & {
+        pollInterval?: number;
+        timeout?: number;
+    }): Promise<AgentStatusResponse>;
     /** Current concurrency usage. */
     getConcurrency(): Promise<ConcurrencyCheck>;
     /** Current credit usage. */
@@ -809,10 +853,14 @@ interface FirecrawlDocumentMetadata {
     articleSection?: string;
     sourceURL?: string;
     statusCode?: number;
+    timezone?: string;
     error?: string;
     proxyUsed?: "basic" | "stealth";
     cacheState?: "miss" | "hit";
     cachedAt?: string;
+    creditsUsed?: number;
+    concurrencyLimited?: boolean;
+    concurrencyQueueDurationMs?: number;
     [key: string]: any;
 }
 /**
@@ -1665,4 +1713,4 @@ declare class Firecrawl extends FirecrawlClient {
     get v1(): FirecrawlApp;
 }
 
-export { type ActionOption, type ActiveCrawl, type ActiveCrawlsResponse, type AgentOptions$1 as AgentOptions, 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, 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 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, 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-3IN25WJ7.js";
+} from "./chunk-KS6E546Q.js";
 
 // src/v2/utils/httpClient.ts
 import axios from "axios";
@@ -32,7 +32,7 @@ var HttpClient = class {
     this.backoffFactor = options.backoffFactor ?? 0.5;
     this.instance = axios.create({
       baseURL: this.apiUrl,
-      timeout: options.timeoutMs ?? 6e4,
+      timeout: options.timeoutMs ?? 3e5,
       headers: {
         "Content-Type": "application/json",
         Authorization: `Bearer ${this.apiKey}`
@@ -633,6 +633,57 @@ async function extract(http, args) {
   return waitExtract(http, jobId, args.pollInterval ?? 2, args.timeout);
 }
 
+// src/v2/methods/agent.ts
+import { zodToJsonSchema as zodToJsonSchema3 } from "zod-to-json-schema";
+function prepareAgentPayload(args) {
+  const body = {};
+  if (args.urls) body.urls = args.urls;
+  body.prompt = args.prompt;
+  if (args.schema != null) {
+    const s = args.schema;
+    const isZod = s && (typeof s.safeParse === "function" || typeof s.parse === "function") && s._def;
+    body.schema = isZod ? zodToJsonSchema3(s) : args.schema;
+  }
+  if (args.integration && args.integration.trim()) body.integration = args.integration.trim();
+  return body;
+}
+async function startAgent(http, args) {
+  const payload = prepareAgentPayload(args);
+  try {
+    const res = await http.post("/v2/agent", payload);
+    if (res.status !== 200) throwForBadResponse(res, "agent");
+    return res.data;
+  } catch (err) {
+    if (err?.isAxiosError) return normalizeAxiosError(err, "agent");
+    throw err;
+  }
+}
+async function getAgentStatus(http, jobId) {
+  try {
+    const res = await http.get(`/v2/agent/${jobId}`);
+    if (res.status !== 200) throwForBadResponse(res, "agent status");
+    return res.data;
+  } catch (err) {
+    if (err?.isAxiosError) return normalizeAxiosError(err, "agent status");
+    throw err;
+  }
+}
+async function waitAgent(http, jobId, pollInterval = 2, timeout) {
+  const start = Date.now();
+  while (true) {
+    const status = await getAgentStatus(http, jobId);
+    if (["completed", "failed", "cancelled"].includes(status.status || "")) return status;
+    if (timeout != null && Date.now() - start > timeout * 1e3) return status;
+    await new Promise((r) => setTimeout(r, Math.max(1e3, pollInterval * 1e3)));
+  }
+}
+async function agent(http, args) {
+  const started = await startAgent(http, args);
+  const jobId = started.id;
+  if (!jobId) return started;
+  return waitAgent(http, jobId, args.pollInterval ?? 2, args.timeout);
+}
+
 // src/v2/methods/usage.ts
 async function getConcurrency(http) {
   try {
@@ -1094,6 +1145,30 @@ var FirecrawlClient = class {
   async extract(args) {
     return extract(this.http, args);
   }
+  // Agent
+  /**
+   * Start an agent job (async).
+   * @param args Agent request (urls, prompt, schema).
+   * @returns Job id or processing state.
+   */
+  async startAgent(args) {
+    return startAgent(this.http, args);
+  }
+  /**
+   * Get agent job status/data.
+   * @param jobId Agent job id.
+   */
+  async getAgentStatus(jobId) {
+    return getAgentStatus(this.http, jobId);
+  }
+  /**
+   * Convenience waiter: start an agent and poll until it finishes.
+   * @param args Agent request plus waiter controls (pollInterval, timeout seconds).
+   * @returns Final agent response.
+   */
+  async agent(args) {
+    return agent(this.http, args);
+  }
   // Usage
   /** Current concurrency usage. */
   async getConcurrency() {
@@ -1133,7 +1208,7 @@ var FirecrawlClient = class {
 // src/v1/index.ts
 import axios2, { AxiosError } from "axios";
 import "zod";
-import { zodToJsonSchema as zodToJsonSchema3 } from "zod-to-json-schema";
+import { zodToJsonSchema as zodToJsonSchema4 } from "zod-to-json-schema";
 
 // node_modules/typescript-event-target/dist/index.mjs
 var e = class extends EventTarget {
@@ -1164,7 +1239,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-UXOZB356.js");
+      const packageJson = await import("./package-F4K5ZEVR.js");
       return packageJson.default.version;
     } catch (error) {
       const isTest = typeof process !== "undefined" && (process.env.JEST_WORKER_ID != null || false);
@@ -1205,7 +1280,7 @@ var FirecrawlApp = class {
     if (jsonData?.extract?.schema) {
       let schema = jsonData.extract.schema;
       try {
-        schema = zodToJsonSchema3(schema);
+        schema = zodToJsonSchema4(schema);
       } catch (error) {
       }
       jsonData = {
@@ -1219,7 +1294,7 @@ var FirecrawlApp = class {
     if (jsonData?.jsonOptions?.schema) {
       let schema = jsonData.jsonOptions.schema;
       try {
-        schema = zodToJsonSchema3(schema);
+        schema = zodToJsonSchema4(schema);
       } catch (error) {
       }
       jsonData = {
@@ -1282,7 +1357,7 @@ var FirecrawlApp = class {
     if (jsonData?.scrapeOptions?.extract?.schema) {
       let schema = jsonData.scrapeOptions.extract.schema;
       try {
-        schema = zodToJsonSchema3(schema);
+        schema = zodToJsonSchema4(schema);
       } catch (error) {
       }
       jsonData = {
@@ -1551,7 +1626,7 @@ var FirecrawlApp = class {
     if (jsonData?.extract?.schema) {
       let schema = jsonData.extract.schema;
       try {
-        schema = zodToJsonSchema3(schema);
+        schema = zodToJsonSchema4(schema);
       } catch (error) {
       }
       jsonData = {
@@ -1565,7 +1640,7 @@ var FirecrawlApp = class {
     if (jsonData?.jsonOptions?.schema) {
       let schema = jsonData.jsonOptions.schema;
       try {
-        schema = zodToJsonSchema3(schema);
+        schema = zodToJsonSchema4(schema);
       } catch (error) {
       }
       jsonData = {
@@ -1744,7 +1819,7 @@ var FirecrawlApp = class {
         jsonSchema = void 0;
       } else {
         try {
-          jsonSchema = zodToJsonSchema3(params.schema);
+          jsonSchema = zodToJsonSchema4(params.schema);
         } catch (_) {
           jsonSchema = params.schema;
         }
@@ -1808,7 +1883,7 @@ var FirecrawlApp = class {
         jsonSchema = void 0;
       } else {
         try {
-          jsonSchema = zodToJsonSchema3(params.schema);
+          jsonSchema = zodToJsonSchema4(params.schema);
         } catch (_) {
           jsonSchema = params.schema;
         }
@@ -2099,7 +2174,7 @@ var FirecrawlApp = class {
     if (jsonData?.jsonOptions?.schema) {
       let schema = jsonData.jsonOptions.schema;
       try {
-        schema = zodToJsonSchema3(schema);
+        schema = zodToJsonSchema4(schema);
       } catch (error) {
       }
       jsonData = {

package/dist/{package-UXOZB356.js → package-F4K5ZEVR.js}

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

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "firecrawl",
-  "version": "4.8.2",
+  "version": "4.9.0",
   "description": "JavaScript SDK for Firecrawl API",
   "main": "dist/index.js",
   "types": "dist/index.d.ts",

package/src/v1/index.ts

@@ -49,10 +49,14 @@ export interface FirecrawlDocumentMetadata {
   articleSection?: string;
   sourceURL?: string;
   statusCode?: number;
+  timezone?: string;
   error?: string;
   proxyUsed?: "basic" | "stealth";
   cacheState?: "miss" | "hit";
   cachedAt?: string;
+  creditsUsed?: number;
+  concurrencyLimited?: boolean;
+  concurrencyQueueDurationMs?: number;
   [key: string]: any; // Allows for additional metadata properties not explicitly defined.
 }
 

package/src/v2/client.ts

@@ -19,6 +19,7 @@ import {
   batchScrape as batchWaiter,
 } from "./methods/batch";
 import { startExtract, getExtractStatus, extract as extractWaiter } from "./methods/extract";
+import { startAgent, getAgentStatus, agent as agentWaiter } from "./methods/agent";
 import { getConcurrency, getCreditUsage, getQueueStatus, getTokenUsage, getCreditUsageHistorical, getTokenUsageHistorical } from "./methods/usage";
 import type {
   Document,
@@ -34,6 +35,8 @@ import type {
   BatchScrapeResponse,
   BatchScrapeJob,
   ExtractResponse,
+  AgentResponse,
+  AgentStatusResponse,
   CrawlOptions,
   BatchScrapeOptions,
   PaginationConfig,
@@ -262,6 +265,31 @@ export class FirecrawlClient {
     return extractWaiter(this.http, args);
   }
 
+  // Agent
+  /**
+   * Start an agent job (async).
+   * @param args Agent request (urls, prompt, schema).
+   * @returns Job id or processing state.
+   */
+  async startAgent(args: Parameters<typeof startAgent>[1]): Promise<AgentResponse> {
+    return startAgent(this.http, args);
+  }
+  /**
+   * Get agent job status/data.
+   * @param jobId Agent job id.
+   */
+  async getAgentStatus(jobId: string): Promise<AgentStatusResponse> {
+    return getAgentStatus(this.http, jobId);
+  }
+  /**
+   * Convenience waiter: start an agent and poll until it finishes.
+   * @param args Agent request plus waiter controls (pollInterval, timeout seconds).
+   * @returns Final agent response.
+   */
+  async agent(args: Parameters<typeof startAgent>[1] & { pollInterval?: number; timeout?: number }): Promise<AgentStatusResponse> {
+    return agentWaiter(this.http, args);
+  }
+
   // Usage
   /** Current concurrency usage. */
   async getConcurrency() {

package/src/v2/methods/agent.ts

@@ -0,0 +1,71 @@
+import { type AgentResponse, type AgentStatusResponse } from "../types";
+import { HttpClient } from "../utils/httpClient";
+import { normalizeAxiosError, throwForBadResponse } from "../utils/errorHandler";
+import { zodToJsonSchema } from "zod-to-json-schema";
+import type { ZodTypeAny } from "zod";
+
+function prepareAgentPayload(args: {
+  urls?: string[];
+  prompt: string;
+  schema?: Record<string, unknown> | ZodTypeAny;
+  integration?: string;
+}): Record<string, unknown> {
+  const body: Record<string, unknown> = {};
+  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;
+  }
+  if (args.integration && args.integration.trim()) body.integration = args.integration.trim();
+  return body;
+}
+
+export async function startAgent(http: HttpClient, args: Parameters<typeof prepareAgentPayload>[0]): Promise<AgentResponse> {
+  const payload = prepareAgentPayload(args);
+  try {
+    const res = await http.post<AgentResponse>("/v2/agent", payload);
+    if (res.status !== 200) throwForBadResponse(res, "agent");
+    return res.data;
+  } catch (err: any) {
+    if (err?.isAxiosError) return normalizeAxiosError(err, "agent");
+    throw err;
+  }
+}
+
+export async function getAgentStatus(http: HttpClient, jobId: string): Promise<AgentStatusResponse> {
+  try {
+    const res = await http.get<AgentStatusResponse>(`/v2/agent/${jobId}`);
+    if (res.status !== 200) throwForBadResponse(res, "agent status");
+    return res.data;
+  } catch (err: any) {
+    if (err?.isAxiosError) return normalizeAxiosError(err, "agent status");
+    throw err;
+  }
+}
+
+export async function waitAgent(
+  http: HttpClient,
+  jobId: string,
+  pollInterval = 2,
+  timeout?: number
+): Promise<AgentStatusResponse> {
+  const start = Date.now();
+  while (true) {
+    const status = await getAgentStatus(http, jobId);
+    if (["completed", "failed", "cancelled"].includes(status.status || "")) return status;
+    if (timeout != null && Date.now() - start > timeout * 1000) return status;
+    await new Promise((r) => setTimeout(r, Math.max(1000, pollInterval * 1000)));
+  }
+}
+
+export async function agent(
+  http: HttpClient,
+  args: Parameters<typeof prepareAgentPayload>[0] & { pollInterval?: number; timeout?: number }
+): Promise<AgentStatusResponse> {
+  const started = await startAgent(http, args);
+  const jobId = started.id;
+  if (!jobId) return started as unknown as AgentStatusResponse;
+  return waitAgent(http, jobId, args.pollInterval ?? 2, args.timeout);
+}

package/src/v2/types.ts

@@ -347,10 +347,13 @@ export interface DocumentMetadata {
   scrapeId?: string;
   numPages?: number;
   contentType?: string;
+  timezone?: string;
   proxyUsed?: 'basic' | 'stealth';
   cacheState?: 'hit' | 'miss';
   cachedAt?: string;
   creditsUsed?: number;
+  concurrencyLimited?: boolean;
+  concurrencyQueueDurationMs?: number;
 
   // Error information
   error?: string;
@@ -532,8 +535,23 @@ export interface ExtractResponse {
   creditsUsed?: number;
 }
 
+export interface AgentResponse {
+  success: boolean;
+  id: string;
+  error?: string;
+}
+
+export interface AgentStatusResponse {
+  success: boolean;
+  status: 'processing' | 'completed' | 'failed';
+  error?: string;
+  data?: unknown;
+  expiresAt: string;
+  creditsUsed?: number;
+}
+
 export interface AgentOptions {
-  model: 'FIRE-1';
+  model: 'FIRE-1' | 'v3-beta';
 }
 
 export interface ConcurrencyCheck {

package/src/v2/utils/httpClient.ts

@@ -23,7 +23,7 @@ export class HttpClient {
     this.backoffFactor = options.backoffFactor ?? 0.5;
     this.instance = axios.create({
       baseURL: this.apiUrl,
-      timeout: options.timeoutMs ?? 60000,
+      timeout: options.timeoutMs ?? 300000,
       headers: {
         "Content-Type": "application/json",
         Authorization: `Bearer ${this.apiKey}`,