custom headers via --headers (#30)

* add custom headers via --headers

* add tests

* better parsing

src/actions.ts

@@ -411,6 +411,12 @@ async function handleNavigate(
   browser: BrowserManager
 ): Promise<Response<NavigateData>> {
   const page = browser.getPage();
+
+  // If headers are provided, set up scoped headers for this origin
+  if (command.headers && Object.keys(command.headers).length > 0) {
+    await browser.setScopedHeaders(command.url, command.headers);
+  }
+
   await page.goto(command.url, {
     waitUntil: command.waitUntil ?? 'load',
   });

src/browser.test.ts

@@ -304,4 +304,59 @@ describe('BrowserManager', () => {
       expect(h1).toBe('Example Domain');
     });
   });
+
+  describe('scoped headers', () => {
+    it('should register route for scoped headers', async () => {
+      // Test that setScopedHeaders doesn't throw and completes successfully
+      await browser.clearScopedHeaders();
+      await expect(
+        browser.setScopedHeaders('https://example.com', { 'X-Test': 'value' })
+      ).resolves.not.toThrow();
+      await browser.clearScopedHeaders();
+    });
+
+    it('should handle full URL origin', async () => {
+      await browser.clearScopedHeaders();
+      await expect(
+        browser.setScopedHeaders('https://api.example.com/path', { Authorization: 'Bearer token' })
+      ).resolves.not.toThrow();
+      await browser.clearScopedHeaders();
+    });
+
+    it('should handle hostname-only origin', async () => {
+      await browser.clearScopedHeaders();
+      await expect(
+        browser.setScopedHeaders('example.com', { 'X-Custom': 'value' })
+      ).resolves.not.toThrow();
+      await browser.clearScopedHeaders();
+    });
+
+    it('should clear scoped headers for specific origin', async () => {
+      await browser.clearScopedHeaders();
+      await browser.setScopedHeaders('https://example.com', { 'X-Test': 'value' });
+      await expect(browser.clearScopedHeaders('https://example.com')).resolves.not.toThrow();
+    });
+
+    it('should clear all scoped headers', async () => {
+      await browser.setScopedHeaders('https://example.com', { 'X-Test-1': 'value1' });
+      await browser.setScopedHeaders('https://example.org', { 'X-Test-2': 'value2' });
+      await expect(browser.clearScopedHeaders()).resolves.not.toThrow();
+    });
+
+    it('should replace headers when called twice for same origin', async () => {
+      await browser.clearScopedHeaders();
+      await browser.setScopedHeaders('https://example.com', { 'X-First': 'first' });
+      // Second call should replace, not add
+      await expect(
+        browser.setScopedHeaders('https://example.com', { 'X-Second': 'second' })
+      ).resolves.not.toThrow();
+      await browser.clearScopedHeaders();
+    });
+
+    it('should handle clearing non-existent origin gracefully', async () => {
+      await browser.clearScopedHeaders();
+      // Should not throw when clearing headers that were never set
+      await expect(browser.clearScopedHeaders('https://never-set.com')).resolves.not.toThrow();
+    });
+  });
 });

src/browser.ts

@@ -51,6 +51,7 @@ export class BrowserManager {
   private isRecordingHar: boolean = false;
   private refMap: RefMap = {};
   private lastSnapshot: string = '';
+  private scopedHeaderRoutes: Map<string, (route: Route) => Promise<void>> = new Map();
 
   /**
    * Check if browser is launched
@@ -439,7 +440,7 @@ export class BrowserManager {
   }
 
   /**
-   * Set extra HTTP headers
+   * Set extra HTTP headers (global - all requests)
    */
   async setExtraHeaders(headers: Record<string, string>): Promise<void> {
     const context = this.contexts[0];
@@ -448,6 +449,76 @@ export class BrowserManager {
     }
   }
 
+  /**
+   * Set scoped HTTP headers (only for requests matching the origin)
+   * Uses route interception to add headers only to matching requests
+   */
+  async setScopedHeaders(origin: string, headers: Record<string, string>): Promise<void> {
+    const page = this.getPage();
+
+    // Build URL pattern from origin (e.g., "api.example.com" -> "**://api.example.com/**")
+    // Handle both full URLs and just hostnames
+    let urlPattern: string;
+    try {
+      const url = new URL(origin.startsWith('http') ? origin : `https://${origin}`);
+      // Match any protocol, the host, and any path
+      urlPattern = `**://${url.host}/**`;
+    } catch {
+      // If parsing fails, treat as hostname pattern
+      urlPattern = `**://${origin}/**`;
+    }
+
+    // Remove existing route for this origin if any
+    const existingHandler = this.scopedHeaderRoutes.get(urlPattern);
+    if (existingHandler) {
+      await page.unroute(urlPattern, existingHandler);
+    }
+
+    // Create handler that adds headers to matching requests
+    const handler = async (route: Route) => {
+      const requestHeaders = route.request().headers();
+      await route.continue({
+        headers: {
+          ...requestHeaders,
+          ...headers,
+        },
+      });
+    };
+
+    // Store and register the route
+    this.scopedHeaderRoutes.set(urlPattern, handler);
+    await page.route(urlPattern, handler);
+  }
+
+  /**
+   * Clear scoped headers for an origin (or all if no origin specified)
+   */
+  async clearScopedHeaders(origin?: string): Promise<void> {
+    const page = this.getPage();
+
+    if (origin) {
+      let urlPattern: string;
+      try {
+        const url = new URL(origin.startsWith('http') ? origin : `https://${origin}`);
+        urlPattern = `**://${url.host}/**`;
+      } catch {
+        urlPattern = `**://${origin}/**`;
+      }
+
+      const handler = this.scopedHeaderRoutes.get(urlPattern);
+      if (handler) {
+        await page.unroute(urlPattern, handler);
+        this.scopedHeaderRoutes.delete(urlPattern);
+      }
+    } else {
+      // Clear all scoped header routes
+      for (const [pattern, handler] of this.scopedHeaderRoutes) {
+        await page.unroute(pattern, handler);
+      }
+      this.scopedHeaderRoutes.clear();
+    }
+  }
+
   /**
    * Start tracing
    */
@@ -523,9 +594,10 @@ export class BrowserManager {
       executablePath: options.executablePath,
     });
 
-    // Create context with viewport
+    // Create context with viewport and optional headers
     const context = await this.browser.newContext({
       viewport: options.viewport ?? { width: 1280, height: 720 },
+      extraHTTPHeaders: options.headers,
     });
 
     // Set default timeout to 10 seconds (Playwright default is 30s)

src/types.ts

@@ -12,6 +12,7 @@ export interface LaunchCommand extends BaseCommand {
   headless?: boolean;
   viewport?: { width: number; height: number };
   browser?: 'chromium' | 'firefox' | 'webkit';
+  headers?: Record<string, string>;
   executablePath?: string;
 }
 
@@ -19,6 +20,7 @@ export interface NavigateCommand extends BaseCommand {
   action: 'navigate';
   url: string;
   waitUntil?: 'load' | 'domcontentloaded' | 'networkidle';
+  headers?: Record<string, string>;
 }
 
 export interface ClickCommand extends BaseCommand {