firecrawl 4.4.0 → 4.5.0

package/dist/{chunk-GWA53VW4.js → chunk-MVAMVUST.js}

@@ -8,7 +8,7 @@ var require_package = __commonJS({
   "package.json"(exports, module) {
     module.exports = {
       name: "@mendable/firecrawl-js",
-      version: "4.4.0",
+      version: "4.5.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.4.0",
+      version: "4.5.0",
       description: "JavaScript SDK for Firecrawl API",
       main: "dist/index.js",
       types: "dist/index.d.ts",
@@ -953,6 +953,9 @@ var Watcher = class extends import_events.EventEmitter {
 var zt = require("zod");
 var FirecrawlClient = class {
   http;
+  isCloudService(url) {
+    return url.includes("api.firecrawl.dev");
+  }
   /**
    * Create a v2 client.
    * @param options Transport configuration (API key, base URL, timeouts, retries).
@@ -960,8 +963,8 @@ var FirecrawlClient = class {
   constructor(options = {}) {
     const apiKey = options.apiKey ?? process.env.FIRECRAWL_API_KEY ?? "";
     const apiUrl = (options.apiUrl ?? process.env.FIRECRAWL_API_URL ?? "https://api.firecrawl.dev").replace(/\/$/, "");
-    if (!apiKey) {
-      throw new Error("API key is required. Set FIRECRAWL_API_KEY env or pass apiKey.");
+    if (this.isCloudService(apiUrl) && !apiKey) {
+      throw new Error("API key is required for the cloud API. Set FIRECRAWL_API_KEY env or pass apiKey.");
     }
     this.http = new HttpClient({
       apiKey,

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' | 'images' | 'screenshot' | 'summary' | 'changeTracking' | 'json' | 'attributes';
+type FormatString = 'markdown' | 'html' | 'rawHtml' | 'links' | 'images' | 'screenshot' | 'summary' | 'changeTracking' | 'json' | 'attributes' | 'branding';
 interface Viewport {
     width: number;
     height: number;
@@ -121,6 +121,130 @@ interface WebhookConfig {
     metadata?: Record<string, string>;
     events?: Array<'completed' | 'failed' | 'page' | 'started'>;
 }
+interface BrandingProfile {
+    colorScheme?: 'light' | 'dark';
+    logo?: string | null;
+    fonts?: Array<{
+        family: string;
+        [key: string]: unknown;
+    }>;
+    colors?: {
+        primary?: string;
+        secondary?: string;
+        accent?: string;
+        background?: string;
+        textPrimary?: string;
+        textSecondary?: string;
+        link?: string;
+        success?: string;
+        warning?: string;
+        error?: string;
+        [key: string]: string | undefined;
+    };
+    typography?: {
+        fontFamilies?: {
+            primary?: string;
+            heading?: string;
+            code?: string;
+            [key: string]: string | undefined;
+        };
+        fontStacks?: {
+            primary?: string[];
+            heading?: string[];
+            body?: string[];
+            paragraph?: string[];
+            [key: string]: string[] | undefined;
+        };
+        fontSizes?: {
+            h1?: string;
+            h2?: string;
+            h3?: string;
+            body?: string;
+            small?: string;
+            [key: string]: string | undefined;
+        };
+        lineHeights?: {
+            heading?: number;
+            body?: number;
+            [key: string]: number | undefined;
+        };
+        fontWeights?: {
+            light?: number;
+            regular?: number;
+            medium?: number;
+            bold?: number;
+            [key: string]: number | undefined;
+        };
+    };
+    spacing?: {
+        baseUnit?: number;
+        padding?: Record<string, number>;
+        margins?: Record<string, number>;
+        gridGutter?: number;
+        borderRadius?: string;
+        [key: string]: number | string | Record<string, number> | undefined;
+    };
+    components?: {
+        buttonPrimary?: {
+            background?: string;
+            textColor?: string;
+            borderColor?: string;
+            borderRadius?: string;
+            [key: string]: string | undefined;
+        };
+        buttonSecondary?: {
+            background?: string;
+            textColor?: string;
+            borderColor?: string;
+            borderRadius?: string;
+            [key: string]: string | undefined;
+        };
+        input?: {
+            borderColor?: string;
+            focusBorderColor?: string;
+            borderRadius?: string;
+            [key: string]: string | undefined;
+        };
+        [key: string]: unknown;
+    };
+    icons?: {
+        style?: string;
+        primaryColor?: string;
+        [key: string]: string | undefined;
+    };
+    images?: {
+        logo?: string | null;
+        favicon?: string | null;
+        ogImage?: string | null;
+        [key: string]: string | null | undefined;
+    };
+    animations?: {
+        transitionDuration?: string;
+        easing?: string;
+        [key: string]: string | undefined;
+    };
+    layout?: {
+        grid?: {
+            columns?: number;
+            maxWidth?: string;
+            [key: string]: number | string | undefined;
+        };
+        headerHeight?: string;
+        footerHeight?: string;
+        [key: string]: number | string | Record<string, number | string | undefined> | undefined;
+    };
+    tone?: {
+        voice?: string;
+        emojiUsage?: string;
+        [key: string]: string | undefined;
+    };
+    personality?: {
+        tone: 'professional' | 'playful' | 'modern' | 'traditional' | 'minimalist' | 'bold';
+        energy: 'low' | 'medium' | 'high';
+        targetAudience: string;
+    };
+    [key: string]: unknown;
+}
 interface DocumentMetadata {
     title?: string;
     description?: string;
@@ -183,6 +307,7 @@ interface Document {
     actions?: Record<string, unknown>;
     warning?: string;
     changeTracking?: Record<string, unknown>;
+    branding?: BrandingProfile;
 }
 interface PaginationConfig {
     /** When true (default), automatically follow `next` links and aggregate all documents. */
@@ -486,6 +611,7 @@ interface FirecrawlClientOptions {
  */
 declare class FirecrawlClient {
     private readonly http;
+    private isCloudService;
     /**
      * Create a v2 client.
      * @param options Transport configuration (API key, base URL, timeouts, retries).
@@ -1531,4 +1657,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 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 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

@@ -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' | 'images' | 'screenshot' | 'summary' | 'changeTracking' | 'json' | 'attributes';
+type FormatString = 'markdown' | 'html' | 'rawHtml' | 'links' | 'images' | 'screenshot' | 'summary' | 'changeTracking' | 'json' | 'attributes' | 'branding';
 interface Viewport {
     width: number;
     height: number;
@@ -121,6 +121,130 @@ interface WebhookConfig {
     metadata?: Record<string, string>;
     events?: Array<'completed' | 'failed' | 'page' | 'started'>;
 }
+interface BrandingProfile {
+    colorScheme?: 'light' | 'dark';
+    logo?: string | null;
+    fonts?: Array<{
+        family: string;
+        [key: string]: unknown;
+    }>;
+    colors?: {
+        primary?: string;
+        secondary?: string;
+        accent?: string;
+        background?: string;
+        textPrimary?: string;
+        textSecondary?: string;
+        link?: string;
+        success?: string;
+        warning?: string;
+        error?: string;
+        [key: string]: string | undefined;
+    };
+    typography?: {
+        fontFamilies?: {
+            primary?: string;
+            heading?: string;
+            code?: string;
+            [key: string]: string | undefined;
+        };
+        fontStacks?: {
+            primary?: string[];
+            heading?: string[];
+            body?: string[];
+            paragraph?: string[];
+            [key: string]: string[] | undefined;
+        };
+        fontSizes?: {
+            h1?: string;
+            h2?: string;
+            h3?: string;
+            body?: string;
+            small?: string;
+            [key: string]: string | undefined;
+        };
+        lineHeights?: {
+            heading?: number;
+            body?: number;
+            [key: string]: number | undefined;
+        };
+        fontWeights?: {
+            light?: number;
+            regular?: number;
+            medium?: number;
+            bold?: number;
+            [key: string]: number | undefined;
+        };
+    };
+    spacing?: {
+        baseUnit?: number;
+        padding?: Record<string, number>;
+        margins?: Record<string, number>;
+        gridGutter?: number;
+        borderRadius?: string;
+        [key: string]: number | string | Record<string, number> | undefined;
+    };
+    components?: {
+        buttonPrimary?: {
+            background?: string;
+            textColor?: string;
+            borderColor?: string;
+            borderRadius?: string;
+            [key: string]: string | undefined;
+        };
+        buttonSecondary?: {
+            background?: string;
+            textColor?: string;
+            borderColor?: string;
+            borderRadius?: string;
+            [key: string]: string | undefined;
+        };
+        input?: {
+            borderColor?: string;
+            focusBorderColor?: string;
+            borderRadius?: string;
+            [key: string]: string | undefined;
+        };
+        [key: string]: unknown;
+    };
+    icons?: {
+        style?: string;
+        primaryColor?: string;
+        [key: string]: string | undefined;
+    };
+    images?: {
+        logo?: string | null;
+        favicon?: string | null;
+        ogImage?: string | null;
+        [key: string]: string | null | undefined;
+    };
+    animations?: {
+        transitionDuration?: string;
+        easing?: string;
+        [key: string]: string | undefined;
+    };
+    layout?: {
+        grid?: {
+            columns?: number;
+            maxWidth?: string;
+            [key: string]: number | string | undefined;
+        };
+        headerHeight?: string;
+        footerHeight?: string;
+        [key: string]: number | string | Record<string, number | string | undefined> | undefined;
+    };
+    tone?: {
+        voice?: string;
+        emojiUsage?: string;
+        [key: string]: string | undefined;
+    };
+    personality?: {
+        tone: 'professional' | 'playful' | 'modern' | 'traditional' | 'minimalist' | 'bold';
+        energy: 'low' | 'medium' | 'high';
+        targetAudience: string;
+    };
+    [key: string]: unknown;
+}
 interface DocumentMetadata {
     title?: string;
     description?: string;
@@ -183,6 +307,7 @@ interface Document {
     actions?: Record<string, unknown>;
     warning?: string;
     changeTracking?: Record<string, unknown>;
+    branding?: BrandingProfile;
 }
 interface PaginationConfig {
     /** When true (default), automatically follow `next` links and aggregate all documents. */
@@ -486,6 +611,7 @@ interface FirecrawlClientOptions {
  */
 declare class FirecrawlClient {
     private readonly http;
+    private isCloudService;
     /**
      * Create a v2 client.
      * @param options Transport configuration (API key, base URL, timeouts, retries).
@@ -1531,4 +1657,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 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 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-GWA53VW4.js";
+} from "./chunk-MVAMVUST.js";
 
 // src/v2/utils/httpClient.ts
 import axios from "axios";
@@ -837,6 +837,9 @@ var Watcher = class extends EventEmitter {
 import "zod";
 var FirecrawlClient = class {
   http;
+  isCloudService(url) {
+    return url.includes("api.firecrawl.dev");
+  }
   /**
    * Create a v2 client.
    * @param options Transport configuration (API key, base URL, timeouts, retries).
@@ -844,8 +847,8 @@ var FirecrawlClient = class {
   constructor(options = {}) {
     const apiKey = options.apiKey ?? process.env.FIRECRAWL_API_KEY ?? "";
     const apiUrl = (options.apiUrl ?? process.env.FIRECRAWL_API_URL ?? "https://api.firecrawl.dev").replace(/\/$/, "");
-    if (!apiKey) {
-      throw new Error("API key is required. Set FIRECRAWL_API_KEY env or pass apiKey.");
+    if (this.isCloudService(apiUrl) && !apiKey) {
+      throw new Error("API key is required for the cloud API. Set FIRECRAWL_API_KEY env or pass apiKey.");
     }
     this.http = new HttpClient({
       apiKey,
@@ -1068,7 +1071,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-G6W4FIEC.js");
+      const packageJson = await import("./package-O4UQBIGU.js");
       return packageJson.default.version;
     } catch (error) {
       const isTest = typeof process !== "undefined" && (process.env.JEST_WORKER_ID != null || false);

package/dist/{package-G6W4FIEC.js → package-O4UQBIGU.js}

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

package/package.json

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

package/src/__tests__/e2e/v1/index.test.ts

@@ -36,7 +36,7 @@ describe('FirecrawlApp E2E Tests', () => {
   test.concurrent('should throw error for blocklisted URL on scrape', async () => {
     const app = new FirecrawlApp({ apiKey: TEST_API_KEY, apiUrl: API_URL });
     const blocklistedUrl = "https://facebook.com/fake-test";
-    await expect(app.scrapeUrl(blocklistedUrl)).rejects.toThrow("This website is no longer supported");
+    await expect(app.scrapeUrl(blocklistedUrl)).rejects.toThrow("This website is not currently supported");
   });
 
   test.concurrent('should return successful response for valid scrape', async () => {
@@ -52,13 +52,13 @@ describe('FirecrawlApp E2E Tests', () => {
     const app = new FirecrawlApp({ apiKey: TEST_API_KEY, apiUrl: API_URL });
     const response = await app.scrapeUrl(
       'https://roastmywebsite.ai', {
-        formats: ['markdown', 'html', 'rawHtml', 'screenshot', 'links'],
-        headers: { "x-key": "test" },
-        includeTags: ['h1'],
-        excludeTags: ['h2'],
-        onlyMainContent: true,
-        timeout: 30000,
-        waitFor: 1000
+      formats: ['markdown', 'html', 'rawHtml', 'screenshot', 'links'],
+      headers: { "x-key": "test" },
+      includeTags: ['h1'],
+      excludeTags: ['h2'],
+      onlyMainContent: true,
+      timeout: 30000,
+      waitFor: 1000
     });
 
     if (!response.success) {
@@ -70,7 +70,7 @@ describe('FirecrawlApp E2E Tests', () => {
     const app = new FirecrawlApp({ apiKey: TEST_API_KEY, apiUrl: API_URL });
     const response = await app.scrapeUrl(
       'https://roastmywebsite.ai', {
-        formats: ['screenshot@fullPage'],
+      formats: ['screenshot@fullPage'],
     });
     if (!response.success) {
       throw new Error(response.error);
@@ -149,7 +149,7 @@ describe('FirecrawlApp E2E Tests', () => {
     }
   }, 60000); // 60 seconds timeout
 
-  test.concurrent('should return successful response for crawl with options and wait for completion', async () => {    
+  test.concurrent('should return successful response for crawl with options and wait for completion', async () => {
     const app = new FirecrawlApp({ apiKey: TEST_API_KEY, apiUrl: API_URL });
     const response = await app.crawlUrl('https://roastmywebsite.ai', {
       excludePaths: ['blog/*'],
@@ -192,7 +192,7 @@ describe('FirecrawlApp E2E Tests', () => {
 
   test.concurrent('should check crawl status', async () => {
     const app = new FirecrawlApp({ apiKey: TEST_API_KEY, apiUrl: API_URL });
-    const response = await app.asyncCrawlUrl('https://firecrawl.dev', { limit: 20, scrapeOptions: { formats: ['markdown', 'html', 'rawHtml', 'screenshot', 'links']}} as CrawlParams) as CrawlResponse;
+    const response = await app.asyncCrawlUrl('https://firecrawl.dev', { limit: 20, scrapeOptions: { formats: ['markdown', 'html', 'rawHtml', 'screenshot', 'links'] } } as CrawlParams) as CrawlResponse;
     expect(response).not.toBeNull();
     expect(response.id).toBeDefined();
 
@@ -250,16 +250,16 @@ describe('FirecrawlApp E2E Tests', () => {
   });
 
   test.concurrent('should return successful response for valid map', async () => {
-    const app = new FirecrawlApp({ apiKey: TEST_API_KEY, apiUrl: API_URL });    const response = await app.mapUrl('https://roastmywebsite.ai') as MapResponse;
+    const app = new FirecrawlApp({ apiKey: TEST_API_KEY, apiUrl: API_URL }); const response = await app.mapUrl('https://roastmywebsite.ai') as MapResponse;
     expect(response).not.toBeNull();
-    
+
     expect(response.links?.length).toBeGreaterThan(0);
     expect(response.links?.[0]).toContain("https://");
     const filteredLinks = response.links?.filter((link: string) => link.includes("roastmywebsite.ai"));
     expect(filteredLinks?.length).toBeGreaterThan(0);
   }, 30000); // 30 seconds timeout
 
-  
+
 
   test('should search with string query', async () => {
     const app = new FirecrawlApp({ apiUrl: API_URL, apiKey: TEST_API_KEY });

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

@@ -0,0 +1,186 @@
+import { describe, test, expect, jest } from "@jest/globals";
+import { scrape } from "../../../v2/methods/scrape";
+
+describe("JS SDK v2 branding format", () => {
+  function makeHttp(postImpl: (url: string, data: any) => any) {
+    return { post: jest.fn(async (u: string, d: any) => postImpl(u, d)) } as any;
+  }
+
+  test("scrape with branding format returns branding data", async () => {
+    const mockResponse = {
+      status: 200,
+      data: {
+        success: true,
+        data: {
+          markdown: "# Example",
+          branding: {
+            colorScheme: "light",
+            colors: {
+              primary: "#E11D48",
+              secondary: "#3B82F6",
+              accent: "#F59E0B"
+            },
+            typography: {
+              fontFamilies: {
+                primary: "Inter",
+                heading: "Poppins"
+              },
+              fontSizes: {
+                h1: "2.5rem",
+                body: "1rem"
+              }
+            },
+            spacing: {
+              baseUnit: 8
+            },
+            components: {
+              buttonPrimary: {
+                background: "#E11D48",
+                textColor: "#FFFFFF",
+                borderRadius: "0.5rem"
+              }
+            }
+          }
+        }
+      }
+    };
+
+    const http = makeHttp(() => mockResponse);
+    const result = await scrape(http, "https://example.com", { formats: ["branding"] });
+
+    expect(result.branding).toBeDefined();
+    expect(result.branding?.colorScheme).toBe("light");
+    expect(result.branding?.colors?.primary).toBe("#E11D48");
+    expect(result.branding?.typography?.fontFamilies?.primary).toBe("Inter");
+    expect(result.branding?.spacing?.baseUnit).toBe(8);
+    expect(result.branding?.components?.buttonPrimary?.background).toBe("#E11D48");
+  });
+
+  test("scrape with branding and markdown formats returns both", async () => {
+    const mockResponse = {
+      status: 200,
+      data: {
+        success: true,
+        data: {
+          markdown: "# Example Content",
+          branding: {
+            colorScheme: "dark",
+            colors: {
+              primary: "#10B981"
+            },
+            typography: {
+              fontFamilies: {
+                primary: "Roboto"
+              }
+            }
+          }
+        }
+      }
+    };
+
+    const http = makeHttp(() => mockResponse);
+    const result = await scrape(http, "https://example.com", { formats: ["markdown", "branding"] });
+
+    expect(result.markdown).toBe("# Example Content");
+    expect(result.branding).toBeDefined();
+    expect(result.branding?.colorScheme).toBe("dark");
+    expect(result.branding?.colors?.primary).toBe("#10B981");
+  });
+
+  test("scrape without branding format does not return branding", async () => {
+    const mockResponse = {
+      status: 200,
+      data: {
+        success: true,
+        data: {
+          markdown: "# Example"
+        }
+      }
+    };
+
+    const http = makeHttp(() => mockResponse);
+    const result = await scrape(http, "https://example.com", { formats: ["markdown"] });
+
+    expect(result.markdown).toBe("# Example");
+    expect(result.branding).toBeUndefined();
+  });
+
+  test("branding format with all nested fields", async () => {
+    const mockResponse = {
+      status: 200,
+      data: {
+        success: true,
+        data: {
+          branding: {
+            colorScheme: "light",
+            logo: "https://example.com/logo.png",
+            fonts: [
+              { family: "Inter", weight: 400 },
+              { family: "Poppins", weight: 700 }
+            ],
+            colors: {
+              primary: "#E11D48",
+              background: "#FFFFFF"
+            },
+            typography: {
+              fontFamilies: { primary: "Inter" },
+              fontStacks: { body: ["Inter", "sans-serif"] },
+              fontSizes: { h1: "2.5rem" },
+              lineHeights: { body: 1.5 },
+              fontWeights: { regular: 400 }
+            },
+            spacing: {
+              baseUnit: 8,
+              padding: { sm: 8, md: 16 }
+            },
+            components: {
+              buttonPrimary: {
+                background: "#E11D48",
+                textColor: "#FFFFFF"
+              }
+            },
+            icons: {
+              style: "outline",
+              primaryColor: "#E11D48"
+            },
+            images: {
+              logo: "https://example.com/logo.png",
+              favicon: "https://example.com/favicon.ico"
+            },
+            animations: {
+              transitionDuration: "200ms",
+              easing: "ease-in-out"
+            },
+            layout: {
+              grid: { columns: 12, maxWidth: "1200px" },
+              headerHeight: "64px"
+            },
+            tone: {
+              voice: "professional",
+              emojiUsage: "minimal"
+            },
+            personality: {
+              tone: "professional",
+              energy: "medium",
+              targetAudience: "developers"
+            }
+          }
+        }
+      }
+    };
+
+    const http = makeHttp(() => mockResponse);
+    const result = await scrape(http, "https://example.com", { formats: ["branding"] });
+
+    expect(result.branding).toBeDefined();
+    expect(result.branding?.logo).toBe("https://example.com/logo.png");
+    expect(result.branding?.fonts).toHaveLength(2);
+    expect(result.branding?.typography?.fontStacks?.body).toEqual(["Inter", "sans-serif"]);
+    expect(result.branding?.spacing?.padding).toEqual({ sm: 8, md: 16 });
+    expect(result.branding?.icons?.style).toBe("outline");
+    expect(result.branding?.images?.favicon).toBe("https://example.com/favicon.ico");
+    expect(result.branding?.animations?.easing).toBe("ease-in-out");
+    expect(result.branding?.layout?.grid?.columns).toBe(12);
+    expect(result.branding?.personality?.tone).toBe("professional");
+  });
+});

package/src/v2/client.ts

@@ -72,9 +72,14 @@ export interface FirecrawlClientOptions {
 /**
  * Firecrawl v2 client. Provides typed access to all v2 endpoints and utilities.
  */
+
 export class FirecrawlClient {
   private readonly http: HttpClient;
 
+  private isCloudService(url: string): boolean {
+    return url.includes('api.firecrawl.dev');
+  }
+
   /**
    * Create a v2 client.
    * @param options Transport configuration (API key, base URL, timeouts, retries).
@@ -82,9 +87,11 @@ export class FirecrawlClient {
   constructor(options: FirecrawlClientOptions = {}) {
     const apiKey = options.apiKey ?? process.env.FIRECRAWL_API_KEY ?? "";
     const apiUrl = (options.apiUrl ?? process.env.FIRECRAWL_API_URL ?? "https://api.firecrawl.dev").replace(/\/$/, "");
-    if (!apiKey) {
-      throw new Error("API key is required. Set FIRECRAWL_API_KEY env or pass apiKey.");
+
+    if (this.isCloudService(apiUrl) && !apiKey) {
+      throw new Error("API key is required for the cloud API. Set FIRECRAWL_API_KEY env or pass apiKey.");
     }
+
     this.http = new HttpClient({
       apiKey,
       apiUrl,

package/src/v2/types.ts

@@ -11,7 +11,8 @@ export type FormatString =
   | 'summary'
   | 'changeTracking'
   | 'json'
-  | 'attributes';
+  | 'attributes'
+  | 'branding';
 
 export interface Viewport {
   width: number;
@@ -165,6 +166,141 @@ export interface WebhookConfig {
   events?: Array<'completed' | 'failed' | 'page' | 'started'>;
 }
 
+export interface BrandingProfile {
+  colorScheme?: 'light' | 'dark';
+  logo?: string | null;
+  fonts?: Array<{
+    family: string;
+    [key: string]: unknown;
+  }>;
+  colors?: {
+    primary?: string;
+    secondary?: string;
+    accent?: string;
+    background?: string;
+    textPrimary?: string;
+    textSecondary?: string;
+    link?: string;
+    success?: string;
+    warning?: string;
+    error?: string;
+    [key: string]: string | undefined;
+  };
+  typography?: {
+    fontFamilies?: {
+      primary?: string;
+      heading?: string;
+      code?: string;
+      [key: string]: string | undefined;
+    };
+    fontStacks?: {
+      primary?: string[];
+      heading?: string[];
+      body?: string[];
+      paragraph?: string[];
+      [key: string]: string[] | undefined;
+    };
+    fontSizes?: {
+      h1?: string;
+      h2?: string;
+      h3?: string;
+      body?: string;
+      small?: string;
+      [key: string]: string | undefined;
+    };
+    lineHeights?: {
+      heading?: number;
+      body?: number;
+      [key: string]: number | undefined;
+    };
+    fontWeights?: {
+      light?: number;
+      regular?: number;
+      medium?: number;
+      bold?: number;
+      [key: string]: number | undefined;
+    };
+  };
+  spacing?: {
+    baseUnit?: number;
+    padding?: Record<string, number>;
+    margins?: Record<string, number>;
+    gridGutter?: number;
+    borderRadius?: string;
+    [key: string]: number | string | Record<string, number> | undefined;
+  };
+  components?: {
+    buttonPrimary?: {
+      background?: string;
+      textColor?: string;
+      borderColor?: string;
+      borderRadius?: string;
+      [key: string]: string | undefined;
+    };
+    buttonSecondary?: {
+      background?: string;
+      textColor?: string;
+      borderColor?: string;
+      borderRadius?: string;
+      [key: string]: string | undefined;
+    };
+    input?: {
+      borderColor?: string;
+      focusBorderColor?: string;
+      borderRadius?: string;
+      [key: string]: string | undefined;
+    };
+    [key: string]: unknown;
+  };
+  icons?: {
+    style?: string;
+    primaryColor?: string;
+    [key: string]: string | undefined;
+  };
+  images?: {
+    logo?: string | null;
+    favicon?: string | null;
+    ogImage?: string | null;
+    [key: string]: string | null | undefined;
+  };
+  animations?: {
+    transitionDuration?: string;
+    easing?: string;
+    [key: string]: string | undefined;
+  };
+  layout?: {
+    grid?: {
+      columns?: number;
+      maxWidth?: string;
+      [key: string]: number | string | undefined;
+    };
+    headerHeight?: string;
+    footerHeight?: string;
+    [key: string]:
+      | number
+      | string
+      | Record<string, number | string | undefined>
+      | undefined;
+  };
+  tone?: {
+    voice?: string;
+    emojiUsage?: string;
+    [key: string]: string | undefined;
+  };
+  personality?: {
+    tone:
+      | 'professional'
+      | 'playful'
+      | 'modern'
+      | 'traditional'
+      | 'minimalist'
+      | 'bold';
+    energy: 'low' | 'medium' | 'high';
+    targetAudience: string;
+  };
+  [key: string]: unknown;
+}
+
 export interface DocumentMetadata {
   // Common metadata fields
   title?: string;
@@ -239,6 +375,7 @@ export interface Document {
   actions?: Record<string, unknown>;
   warning?: string;
   changeTracking?: Record<string, unknown>;
+  branding?: BrandingProfile;
 }
 
 // Pagination configuration for auto-fetching pages from v2 endpoints that return a `next` URL