@mendable/firecrawl 3.1.0 → 3.3.0

package/dist/{chunk-WNGXI3ZW.js → chunk-Y3QF4XAJ.js}

@@ -8,7 +8,7 @@ var require_package = __commonJS({
   "package.json"(exports, module) {
     module.exports = {
       name: "@mendable/firecrawl-js",
-      version: "3.1.0",
+      version: "3.3.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: "3.1.0",
+      version: "3.3.0",
       description: "JavaScript SDK for Firecrawl API",
       main: "dist/index.js",
       types: "dist/index.d.ts",
@@ -316,6 +316,7 @@ function prepareSearchPayload(req) {
     query: req.query
   };
   if (req.sources) payload.sources = req.sources;
+  if (req.categories) payload.categories = req.categories;
   if (req.limit != null) payload.limit = req.limit;
   if (req.tbs != null) payload.tbs = req.tbs;
   if (req.location != null) payload.location = req.location;
@@ -2347,7 +2348,10 @@ var Firecrawl = class extends FirecrawlClient {
   /** @param opts API credentials and base URL. */
   constructor(opts = {}) {
     super(opts);
-    this._v1Opts = opts;
+    this._v1Opts = {
+      apiKey: opts.apiKey,
+      apiUrl: opts.apiUrl
+    };
   }
   /** Access the legacy v1 client (instantiated on first access). */
   get v1() {

package/dist/index.d.cts

@@ -4,7 +4,7 @@ import { AxiosResponse, AxiosRequestHeaders } from 'axios';
 import { EventEmitter } from 'events';
 import { TypedEventTarget } from 'typescript-event-target';
 
-type FormatString = "markdown" | "html" | "rawHtml" | "links" | "screenshot" | "summary" | "changeTracking" | "json";
+type FormatString = "markdown" | "html" | "rawHtml" | "links" | "images" | "screenshot" | "summary" | "changeTracking" | "json" | "attributes";
 interface Viewport {
     width: number;
     height: number;
@@ -33,7 +33,14 @@ interface ChangeTrackingFormat extends Format {
     prompt?: string;
     tag?: string;
 }
-type FormatOption = FormatString | Format | JsonFormat | ChangeTrackingFormat | ScreenshotFormat;
+interface AttributesFormat extends Format {
+    type: "attributes";
+    selectors: Array<{
+        selector: string;
+        attribute: string;
+    }>;
+}
+type FormatOption = FormatString | Format | JsonFormat | ChangeTrackingFormat | ScreenshotFormat | AttributesFormat;
 interface LocationConfig {
     country?: string;
     languages?: string[];
@@ -133,7 +140,13 @@ interface Document {
     summary?: string;
     metadata?: DocumentMetadata;
     links?: string[];
+    images?: string[];
     screenshot?: string;
+    attributes?: Array<{
+        selector: string;
+        attribute: string;
+        values: string[];
+    }>;
     actions?: Record<string, unknown>;
     warning?: string;
     changeTracking?: Record<string, unknown>;
@@ -142,6 +155,7 @@ interface SearchResultWeb {
     url: string;
     title?: string;
     description?: string;
+    category?: string;
 }
 interface SearchResultNews {
     title?: string;
@@ -150,6 +164,7 @@ interface SearchResultNews {
     date?: string;
     imageUrl?: string;
     position?: number;
+    category?: string;
 }
 interface SearchResultImages {
     title?: string;
@@ -164,11 +179,15 @@ interface SearchData {
     news?: Array<SearchResultNews | Document>;
     images?: Array<SearchResultImages | Document>;
 }
+interface CategoryOption {
+    type: "github" | "research";
+}
 interface SearchRequest {
     query: string;
     sources?: Array<"web" | "news" | "images" | {
         type: "web" | "news" | "images";
     }>;
+    categories?: Array<"github" | "research" | CategoryOption>;
     limit?: number;
     tbs?: string;
     location?: string;
@@ -1337,9 +1356,9 @@ declare class Firecrawl extends FirecrawlClient {
     private _v1?;
     private _v1Opts;
     /** @param opts API credentials and base URL. */
-    constructor(opts?: FirecrawlAppConfig);
+    constructor(opts?: FirecrawlClientOptions);
     /** Access the legacy v1 client (instantiated on first access). */
     get v1(): FirecrawlApp;
 }
 
-export { type ActionOption, type ActiveCrawl, type ActiveCrawlsResponse, type BatchScrapeJob, type BatchScrapeOptions, type BatchScrapeResponse$1 as BatchScrapeResponse, type ChangeTrackingFormat, type ClickAction, type ConcurrencyCheck, type CrawlErrorsResponse$1 as CrawlErrorsResponse, type CrawlJob, type CrawlOptions, type CrawlResponse$1 as CrawlResponse, type CreditUsage, type Document, type DocumentMetadata, type ErrorDetails, type ExecuteJavascriptAction, type ExtractResponse$1 as ExtractResponse, Firecrawl, FirecrawlApp as FirecrawlAppV1, FirecrawlClient, type Format, type FormatOption, type FormatString, type JsonFormat, type LocationConfig, type MapData, type MapOptions, type PDFAction, type PressAction, type ScrapeAction, type ScrapeOptions, type ScreenshotAction, type ScreenshotFormat, type ScrollAction, SdkError, type SearchData, type SearchRequest, type SearchResultImages, type SearchResultNews, type SearchResultWeb, type TokenUsage, type Viewport, type WaitAction, type WebhookConfig, type WriteAction, Firecrawl as default };
+export { type ActionOption, type ActiveCrawl, type ActiveCrawlsResponse, type AttributesFormat, type BatchScrapeJob, type BatchScrapeOptions, type BatchScrapeResponse$1 as BatchScrapeResponse, 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 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, type MapData, type MapOptions, type PDFAction, type PressAction, type ScrapeAction, type ScrapeOptions, type ScreenshotAction, type ScreenshotFormat, type ScrollAction, SdkError, type SearchData, type SearchRequest, type SearchResultImages, type SearchResultNews, type SearchResultWeb, type TokenUsage, type Viewport, type WaitAction, type WebhookConfig, type WriteAction, Firecrawl as default };

package/dist/index.d.ts

@@ -4,7 +4,7 @@ import { AxiosResponse, AxiosRequestHeaders } from 'axios';
 import { EventEmitter } from 'events';
 import { TypedEventTarget } from 'typescript-event-target';
 
-type FormatString = "markdown" | "html" | "rawHtml" | "links" | "screenshot" | "summary" | "changeTracking" | "json";
+type FormatString = "markdown" | "html" | "rawHtml" | "links" | "images" | "screenshot" | "summary" | "changeTracking" | "json" | "attributes";
 interface Viewport {
     width: number;
     height: number;
@@ -33,7 +33,14 @@ interface ChangeTrackingFormat extends Format {
     prompt?: string;
     tag?: string;
 }
-type FormatOption = FormatString | Format | JsonFormat | ChangeTrackingFormat | ScreenshotFormat;
+interface AttributesFormat extends Format {
+    type: "attributes";
+    selectors: Array<{
+        selector: string;
+        attribute: string;
+    }>;
+}
+type FormatOption = FormatString | Format | JsonFormat | ChangeTrackingFormat | ScreenshotFormat | AttributesFormat;
 interface LocationConfig {
     country?: string;
     languages?: string[];
@@ -133,7 +140,13 @@ interface Document {
     summary?: string;
     metadata?: DocumentMetadata;
     links?: string[];
+    images?: string[];
     screenshot?: string;
+    attributes?: Array<{
+        selector: string;
+        attribute: string;
+        values: string[];
+    }>;
     actions?: Record<string, unknown>;
     warning?: string;
     changeTracking?: Record<string, unknown>;
@@ -142,6 +155,7 @@ interface SearchResultWeb {
     url: string;
     title?: string;
     description?: string;
+    category?: string;
 }
 interface SearchResultNews {
     title?: string;
@@ -150,6 +164,7 @@ interface SearchResultNews {
     date?: string;
     imageUrl?: string;
     position?: number;
+    category?: string;
 }
 interface SearchResultImages {
     title?: string;
@@ -164,11 +179,15 @@ interface SearchData {
     news?: Array<SearchResultNews | Document>;
     images?: Array<SearchResultImages | Document>;
 }
+interface CategoryOption {
+    type: "github" | "research";
+}
 interface SearchRequest {
     query: string;
     sources?: Array<"web" | "news" | "images" | {
         type: "web" | "news" | "images";
     }>;
+    categories?: Array<"github" | "research" | CategoryOption>;
     limit?: number;
     tbs?: string;
     location?: string;
@@ -1337,9 +1356,9 @@ declare class Firecrawl extends FirecrawlClient {
     private _v1?;
     private _v1Opts;
     /** @param opts API credentials and base URL. */
-    constructor(opts?: FirecrawlAppConfig);
+    constructor(opts?: FirecrawlClientOptions);
     /** Access the legacy v1 client (instantiated on first access). */
     get v1(): FirecrawlApp;
 }
 
-export { type ActionOption, type ActiveCrawl, type ActiveCrawlsResponse, type BatchScrapeJob, type BatchScrapeOptions, type BatchScrapeResponse$1 as BatchScrapeResponse, type ChangeTrackingFormat, type ClickAction, type ConcurrencyCheck, type CrawlErrorsResponse$1 as CrawlErrorsResponse, type CrawlJob, type CrawlOptions, type CrawlResponse$1 as CrawlResponse, type CreditUsage, type Document, type DocumentMetadata, type ErrorDetails, type ExecuteJavascriptAction, type ExtractResponse$1 as ExtractResponse, Firecrawl, FirecrawlApp as FirecrawlAppV1, FirecrawlClient, type Format, type FormatOption, type FormatString, type JsonFormat, type LocationConfig, type MapData, type MapOptions, type PDFAction, type PressAction, type ScrapeAction, type ScrapeOptions, type ScreenshotAction, type ScreenshotFormat, type ScrollAction, SdkError, type SearchData, type SearchRequest, type SearchResultImages, type SearchResultNews, type SearchResultWeb, type TokenUsage, type Viewport, type WaitAction, type WebhookConfig, type WriteAction, Firecrawl as default };
+export { type ActionOption, type ActiveCrawl, type ActiveCrawlsResponse, type AttributesFormat, type BatchScrapeJob, type BatchScrapeOptions, type BatchScrapeResponse$1 as BatchScrapeResponse, 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 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, type MapData, type MapOptions, type PDFAction, type PressAction, type ScrapeAction, type ScrapeOptions, type ScreenshotAction, type ScreenshotFormat, type ScrollAction, SdkError, type SearchData, type SearchRequest, type SearchResultImages, type SearchResultNews, type SearchResultWeb, type TokenUsage, type Viewport, type WaitAction, type WebhookConfig, type WriteAction, Firecrawl as default };

package/dist/index.js

@@ -1,6 +1,6 @@
 import {
   require_package
-} from "./chunk-WNGXI3ZW.js";
+} from "./chunk-Y3QF4XAJ.js";
 
 // src/v2/utils/httpClient.ts
 import axios from "axios";
@@ -200,6 +200,7 @@ function prepareSearchPayload(req) {
     query: req.query
   };
   if (req.sources) payload.sources = req.sources;
+  if (req.categories) payload.categories = req.categories;
   if (req.limit != null) payload.limit = req.limit;
   if (req.tbs != null) payload.tbs = req.tbs;
   if (req.location != null) payload.location = req.location;
@@ -932,7 +933,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-KMFB7KZD.js");
+      const packageJson = await import("./package-LI2S3JCZ.js");
       return packageJson.default.version;
     } catch (error) {
       const isTest = typeof process !== "undefined" && (process.env.JEST_WORKER_ID != null || false);
@@ -2231,7 +2232,10 @@ var Firecrawl = class extends FirecrawlClient {
   /** @param opts API credentials and base URL. */
   constructor(opts = {}) {
     super(opts);
-    this._v1Opts = opts;
+    this._v1Opts = {
+      apiKey: opts.apiKey,
+      apiUrl: opts.apiUrl
+    };
   }
   /** Access the legacy v1 client (instantiated on first access). */
   get v1() {

package/dist/{package-KMFB7KZD.js → package-LI2S3JCZ.js}

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

package/package.json

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

package/src/__tests__/e2e/v2/scrape.test.ts

@@ -121,6 +121,39 @@ describe("v2.scrape e2e", () => {
     }
   }, 90_000);
 
+  test("images format: extract all images from webpage", async () => {
+    if (!client) throw new Error();
+    const doc = await client.scrape("https://firecrawl.dev", {
+      formats: ["images"],
+    });
+    expect(doc.images).toBeTruthy();
+    expect(Array.isArray(doc.images)).toBe(true);
+    expect(doc.images.length).toBeGreaterThan(0);
+    // Should find firecrawl logo/branding images
+    expect(doc.images.some(img => img.includes("firecrawl") || img.includes("logo"))).toBe(true);
+  }, 60_000);
+
+  test("images format: works with multiple formats", async () => {
+    if (!client) throw new Error();
+    const doc = await client.scrape("https://github.com", {
+      formats: ["markdown", "links", "images"],
+    });
+    expect(doc.markdown).toBeTruthy();
+    expect(doc.links).toBeTruthy();
+    expect(doc.images).toBeTruthy();
+    expect(Array.isArray(doc.images)).toBe(true);
+    expect(doc.images.length).toBeGreaterThan(0);
+    
+    // Images should find things not available in links format
+    const imageExtensions = ['.jpg', '.jpeg', '.png', '.gif', '.webp', '.svg', '.ico'];
+    const linkImages = doc.links?.filter(link => 
+      imageExtensions.some(ext => link.toLowerCase().includes(ext))
+    ) || [];
+    
+    // Should discover additional images beyond those with obvious extensions
+    expect(doc.images.length).toBeGreaterThanOrEqual(linkImages.length);
+  }, 60_000);
+
   test("invalid url should throw", async () => {
     if (!client) throw new Error();
     await expect(client.scrape("")).rejects.toThrow("URL cannot be empty");

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

@@ -0,0 +1,55 @@
+import { Firecrawl, type FirecrawlClientOptions } from '../../../index';
+
+describe('Firecrawl v2 Client Options', () => {
+  it('should accept v2 options including timeoutMs, maxRetries, and backoffFactor', () => {
+    const options: FirecrawlClientOptions = {
+      apiKey: 'test-key',
+      timeoutMs: 300,
+      maxRetries: 5,
+      backoffFactor: 0.5,
+    };
+
+    // Should not throw any type errors
+    const client = new Firecrawl(options);
+    
+    expect(client).toBeDefined();
+    expect(client).toBeInstanceOf(Firecrawl);
+  });
+
+  it('should work with minimal options', () => {
+    const options: FirecrawlClientOptions = {
+      apiKey: 'test-key',
+    };
+
+    const client = new Firecrawl(options);
+    
+    expect(client).toBeDefined();
+    expect(client).toBeInstanceOf(Firecrawl);
+  });
+
+  it('should work with all v2 options', () => {
+    const options: FirecrawlClientOptions = {
+      apiKey: 'test-key',
+      apiUrl: 'https://custom-api.firecrawl.dev',
+      timeoutMs: 60000,
+      maxRetries: 3,
+      backoffFactor: 1.0,
+    };
+
+    const client = new Firecrawl(options);
+    
+    expect(client).toBeDefined();
+    expect(client).toBeInstanceOf(Firecrawl);
+  });
+
+  it('should export FirecrawlClientOptions type', () => {
+    // This test ensures the type is properly exported
+    const options: FirecrawlClientOptions = {
+      apiKey: 'test-key',
+      timeoutMs: 300,
+    };
+
+    expect(options.timeoutMs).toBe(300);
+    expect(options.apiKey).toBe('test-key');
+  });
+});

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

@@ -9,11 +9,18 @@ describe("v2 utils: validation", () => {
     expect(() => ensureValidFormats(formats)).toThrow(/json format must be an object/i);
   });
 
-  test("ensureValidFormats: json format requires prompt and schema", () => {
-    const bad1: FormatOption[] = [{ type: "json", prompt: "p" } as any];
-    const bad2: FormatOption[] = [{ type: "json", schema: {} } as any];
-    expect(() => ensureValidFormats(bad1)).toThrow(/requires 'prompt' and 'schema'/i);
-    expect(() => ensureValidFormats(bad2)).toThrow(/requires 'prompt' and 'schema'/i);
+  test("ensureValidFormats: json format requires prompt or schema", () => {
+    // Valid cases - should not throw
+    const valid1: FormatOption[] = [{ type: "json", prompt: "p" } as any];
+    const valid2: FormatOption[] = [{ type: "json", schema: {} } as any];
+    const valid3: FormatOption[] = [{ type: "json", prompt: "p", schema: {} } as any];
+    expect(() => ensureValidFormats(valid1)).not.toThrow();
+    expect(() => ensureValidFormats(valid2)).not.toThrow();
+    expect(() => ensureValidFormats(valid3)).not.toThrow();
+
+    // Invalid case - should throw when both are missing
+    const bad: FormatOption[] = [{ type: "json" } as any];
+    expect(() => ensureValidFormats(bad)).toThrow(/requires either 'prompt' or 'schema'/i);
   });
 
   test("ensureValidFormats: converts zod schema to JSON schema", () => {

package/src/index.ts

@@ -13,9 +13,12 @@ export * from "./v2/types";
 export { default as FirecrawlAppV1 } from "./v1";
 
 import V1 from "./v1";
-import { FirecrawlClient as V2 } from "./v2/client";
+import { FirecrawlClient as V2, type FirecrawlClientOptions } from "./v2/client";
 import type { FirecrawlAppConfig } from "./v1";
 
+// Re-export v2 client options for convenience
+export type { FirecrawlClientOptions } from "./v2/client";
+
 /** Unified client: extends v2 and adds `.v1` for backward compatibility. */
 export class Firecrawl extends V2 {
   /** Feature‑frozen v1 client (lazy). */
@@ -23,9 +26,12 @@ export class Firecrawl extends V2 {
   private _v1Opts: FirecrawlAppConfig;
 
   /** @param opts API credentials and base URL. */
-  constructor(opts: FirecrawlAppConfig = {}) {
-    super(opts as any);
-    this._v1Opts = opts;
+  constructor(opts: FirecrawlClientOptions = {}) {
+    super(opts);
+    this._v1Opts = {
+      apiKey: opts.apiKey,
+      apiUrl: opts.apiUrl,
+    };
   }
 
   /** Access the legacy v1 client (instantiated on first access). */

package/src/v2/methods/search.ts

@@ -11,6 +11,7 @@ function prepareSearchPayload(req: SearchRequest): Record<string, unknown> {
     query: req.query,
   };
   if (req.sources) payload.sources = req.sources;
+  if (req.categories) payload.categories = req.categories;
   if (req.limit != null) payload.limit = req.limit;
   if (req.tbs != null) payload.tbs = req.tbs;
   if (req.location != null) payload.location = req.location;

package/src/v2/types.ts

@@ -6,10 +6,12 @@ export type FormatString =
   | "html"
   | "rawHtml"
   | "links"
+  | "images"
   | "screenshot"
   | "summary"
   | "changeTracking"
-  | "json";
+  | "json"
+  | "attributes";
 
 export interface Viewport {
   width: number;
@@ -40,13 +42,21 @@ export interface ChangeTrackingFormat extends Format {
   prompt?: string;
   tag?: string;
 }
+export interface AttributesFormat extends Format {
+  type: "attributes";
+  selectors: Array<{
+    selector: string;
+    attribute: string;
+  }>;
+}
 
 export type FormatOption =
   | FormatString
   | Format
   | JsonFormat
   | ChangeTrackingFormat
-  | ScreenshotFormat;
+  | ScreenshotFormat
+  | AttributesFormat;
 
 export interface LocationConfig {
   country?: string;
@@ -167,7 +177,13 @@ export interface Document {
   summary?: string;
   metadata?: DocumentMetadata;
   links?: string[];
+  images?: string[];
   screenshot?: string;
+  attributes?: Array<{
+    selector: string;
+    attribute: string;
+    values: string[];
+  }>;
   actions?: Record<string, unknown>;
   warning?: string;
   changeTracking?: Record<string, unknown>;
@@ -177,6 +193,7 @@ export interface SearchResultWeb {
   url: string;
   title?: string;
   description?: string;
+  category?: string;
 }
 
 export interface SearchResultNews {
@@ -186,6 +203,7 @@ export interface SearchResultNews {
   date?: string;
   imageUrl?: string;
   position?: number;
+  category?: string;
 }
 
 export interface SearchResultImages {
@@ -203,9 +221,14 @@ export interface SearchData {
   images?: Array<SearchResultImages | Document>;
 }
 
+export interface CategoryOption {
+  type: "github" | "research";
+}
+
 export interface SearchRequest {
   query: string;
   sources?: Array<"web" | "news" | "images" | { type: "web" | "news" | "images" }>;
+  categories?: Array<"github" | "research" | CategoryOption>;
   limit?: number;
   tbs?: string;
   location?: string;