firecrawl 4.4.1 → 4.5.1

package/dist/{chunk-J3BEBX3Y.js → chunk-TNGVHCPH.js}

@@ -8,7 +8,7 @@ var require_package = __commonJS({
   "package.json"(exports, module) {
     module.exports = {
       name: "@mendable/firecrawl-js",
-      version: "4.4.1",
+      version: "4.5.1",
       description: "JavaScript SDK for Firecrawl API",
       main: "dist/index.js",
       types: "dist/index.d.ts",
@@ -36,6 +36,7 @@ var require_package = __commonJS({
       dependencies: {
         axios: "^1.12.2",
         "typescript-event-target": "^1.1.1",
+        ws: "^8.18.3",
         zod: "^3.23.8",
         "zod-to-json-schema": "^3.23.0"
       },
@@ -50,6 +51,7 @@ var require_package = __commonJS({
         "@types/mocha": "^10.0.6",
         "@types/node": "^20.12.12",
         "@types/uuid": "^9.0.8",
+        "@types/ws": "^8.18.1",
         dotenv: "^16.4.5",
         jest: "^30.0.5",
         "ts-jest": "^29.4.0",

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.1",
+      version: "4.5.1",
       description: "JavaScript SDK for Firecrawl API",
       main: "dist/index.js",
       types: "dist/index.d.ts",
@@ -63,6 +63,7 @@ var require_package = __commonJS({
       dependencies: {
         axios: "^1.12.2",
         "typescript-event-target": "^1.1.1",
+        ws: "^8.18.3",
         zod: "^3.23.8",
         "zod-to-json-schema": "^3.23.0"
       },
@@ -77,6 +78,7 @@ var require_package = __commonJS({
         "@types/mocha": "^10.0.6",
         "@types/node": "^20.12.12",
         "@types/uuid": "^9.0.8",
+        "@types/ws": "^8.18.1",
         dotenv: "^16.4.5",
         jest: "^30.0.5",
         "ts-jest": "^29.4.0",
@@ -823,6 +825,7 @@ async function getTokenUsageHistorical(http, byApiKey) {
 
 // src/v2/watcher.ts
 var import_events = require("events");
+var import_ws = require("ws");
 var Watcher = class extends import_events.EventEmitter {
   http;
   jobId;
@@ -848,9 +851,15 @@ var Watcher = class extends import_events.EventEmitter {
   async start() {
     try {
       const url = this.buildWsUrl();
-      this.ws = new WebSocket(url, this.http.getApiKey());
-      this.attachWsHandlers(this.ws);
-    } catch {
+      if (typeof WebSocket !== "undefined") {
+        this.ws = new WebSocket(url, this.http.getApiKey());
+      } else {
+        this.ws = new import_ws.WebSocket(url, this.http.getApiKey());
+      }
+      if (this.ws) {
+        this.attachWsHandlers(this.ws);
+      }
+    } catch (err) {
       this.pollLoop();
     }
   }
@@ -878,7 +887,9 @@ var Watcher = class extends import_events.EventEmitter {
           return;
         }
         if (type === "done") {
-          this.emit("done", { status: "completed", data: [], id: this.jobId });
+          const payload2 = body.data || body;
+          const data = payload2.data || [];
+          this.emit("done", { status: "completed", data, id: this.jobId });
           this.close();
           return;
         }

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. */
@@ -1532,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. */
@@ -1532,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-J3BEBX3Y.js";
+} from "./chunk-TNGVHCPH.js";
 
 // src/v2/utils/httpClient.ts
 import axios from "axios";
@@ -707,6 +707,7 @@ async function getTokenUsageHistorical(http, byApiKey) {
 
 // src/v2/watcher.ts
 import { EventEmitter } from "events";
+import { WebSocket as WS } from "ws";
 var Watcher = class extends EventEmitter {
   http;
   jobId;
@@ -732,9 +733,15 @@ var Watcher = class extends EventEmitter {
   async start() {
     try {
       const url = this.buildWsUrl();
-      this.ws = new WebSocket(url, this.http.getApiKey());
-      this.attachWsHandlers(this.ws);
-    } catch {
+      if (typeof WebSocket !== "undefined") {
+        this.ws = new WebSocket(url, this.http.getApiKey());
+      } else {
+        this.ws = new WS(url, this.http.getApiKey());
+      }
+      if (this.ws) {
+        this.attachWsHandlers(this.ws);
+      }
+    } catch (err) {
       this.pollLoop();
     }
   }
@@ -762,7 +769,9 @@ var Watcher = class extends EventEmitter {
           return;
         }
         if (type === "done") {
-          this.emit("done", { status: "completed", data: [], id: this.jobId });
+          const payload2 = body.data || body;
+          const data = payload2.data || [];
+          this.emit("done", { status: "completed", data, id: this.jobId });
           this.close();
           return;
         }
@@ -1071,7 +1080,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-SYKCM5JT.js");
+      const packageJson = await import("./package-SV2UYR6U.js");
       return packageJson.default.version;
     } catch (error) {
       const isTest = typeof process !== "undefined" && (process.env.JEST_WORKER_ID != null || false);

package/dist/{package-SYKCM5JT.js → package-SV2UYR6U.js}

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

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "firecrawl",
-  "version": "4.4.1",
+  "version": "4.5.1",
   "description": "JavaScript SDK for Firecrawl API",
   "main": "dist/index.js",
   "types": "dist/index.d.ts",
@@ -28,6 +28,7 @@
   "dependencies": {
     "axios": "^1.12.2",
     "typescript-event-target": "^1.1.1",
+    "ws": "^8.18.3",
     "zod": "^3.23.8",
     "zod-to-json-schema": "^3.23.0"
   },
@@ -42,6 +43,7 @@
     "@types/mocha": "^10.0.6",
     "@types/node": "^20.12.12",
     "@types/uuid": "^9.0.8",
+    "@types/ws": "^8.18.1",
     "dotenv": "^16.4.5",
     "jest": "^30.0.5",
     "ts-jest": "^29.4.0",

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/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

package/src/v2/watcher.ts

@@ -3,6 +3,7 @@ import type { BatchScrapeJob, CrawlJob, Document } from "./types";
 import type { HttpClient } from "./utils/httpClient";
 import { getBatchScrapeStatus } from "./methods/batch";
 import { getCrawlStatus } from "./methods/crawl";
+import { WebSocket as WS } from "ws";
 
 type JobKind = "crawl" | "batch";
 
@@ -43,11 +44,17 @@ export class Watcher extends EventEmitter {
   async start(): Promise<void> {
     try {
       const url = this.buildWsUrl();
-      // Pass API key as subprotocol for browser compatibility
-      this.ws = new WebSocket(url, this.http.getApiKey());
-      this.attachWsHandlers(this.ws);
-    } catch {
-      // Fallback to polling immediately
+      
+      if (typeof WebSocket !== 'undefined') {
+        this.ws = new WebSocket(url, this.http.getApiKey()) as any;
+      } else {
+        this.ws = new WS(url, this.http.getApiKey()) as any;
+      }
+      
+      if (this.ws) {
+        this.attachWsHandlers(this.ws);
+      }
+    } catch (err) {
       this.pollLoop();
     }
   }
@@ -76,7 +83,9 @@ export class Watcher extends EventEmitter {
           return;
         }
         if (type === "done") {
-          this.emit("done", { status: "completed", data: [], id: this.jobId });
+          const payload = body.data || body;
+          const data = (payload.data || []) as Document[];
+          this.emit("done", { status: "completed", data, id: this.jobId });
           this.close();
           return;
         }

package/tsup.config.ts

@@ -8,6 +8,7 @@ export default defineConfig({
   clean: true,
   platform: "node",
   target: "node22",
+  external: ["ws"],
   noExternal: ["typescript-event-target"],
   esbuildOptions(options) {
     options.define = {