cbrowser 2.3.0 → 2.4.0

package/dist/browser.d.ts

@@ -4,7 +4,7 @@
  * AI-powered browser automation with constitutional safety.
  */
 import { type CBrowserConfig } from "./config.js";
-import type { NavigationResult, ClickResult, ExtractResult, JourneyResult, CleanupOptions, CleanupResult, JourneyOptions } from "./types.js";
+import type { SavedSession, NavigationResult, ClickResult, ExtractResult, JourneyResult, CleanupOptions, CleanupResult, JourneyOptions, NetworkMock, NetworkRequest, PerformanceMetrics, PerformanceAuditResult } from "./types.js";
 export declare class CBrowser {
     private config;
     private paths;
@@ -12,6 +12,10 @@ export declare class CBrowser {
     private context;
     private page;
     private currentPersona;
+    private networkRequests;
+    private networkResponses;
+    private harEntries;
+    private isRecordingHar;
     constructor(userConfig?: Partial<CBrowserConfig>);
     /**
      * Launch the browser.
@@ -25,6 +29,98 @@ export declare class CBrowser {
      * Get the current page, launching if needed.
      */
     private getPage;
+    /**
+     * Set up network mocks for API interception.
+     */
+    private setupNetworkMocks;
+    /**
+     * Add a network mock at runtime.
+     */
+    addNetworkMock(mock: NetworkMock): Promise<void>;
+    /**
+     * Clear all network mocks.
+     */
+    clearNetworkMocks(): Promise<void>;
+    /**
+     * Set up network request/response tracking for HAR.
+     */
+    private setupNetworkTracking;
+    /**
+     * Start recording HAR.
+     */
+    startHarRecording(): void;
+    /**
+     * Stop recording and export HAR.
+     */
+    exportHar(outputPath?: string): Promise<string>;
+    /**
+     * Get all captured network requests.
+     */
+    getNetworkRequests(): NetworkRequest[];
+    /**
+     * Clear network request history.
+     */
+    clearNetworkHistory(): void;
+    /**
+     * Collect Core Web Vitals and performance metrics.
+     */
+    getPerformanceMetrics(): Promise<PerformanceMetrics>;
+    /**
+     * Run a performance audit against a budget.
+     */
+    auditPerformance(url?: string): Promise<PerformanceAuditResult>;
+    /**
+     * Get all cookies for the current context.
+     */
+    getCookies(urls?: string[]): Promise<SavedSession["cookies"]>;
+    /**
+     * Set cookies.
+     */
+    setCookies(cookies: SavedSession["cookies"]): Promise<void>;
+    /**
+     * Clear all cookies.
+     */
+    clearCookies(): Promise<void>;
+    /**
+     * Delete specific cookies by name.
+     */
+    deleteCookie(name: string, domain?: string): Promise<void>;
+    /**
+     * Get the path to the video file (after browser closes).
+     */
+    getVideoPath(): Promise<string | null>;
+    /**
+     * Save the video with a custom filename.
+     */
+    saveVideo(outputPath: string): Promise<string | null>;
+    /**
+     * Set device emulation (requires browser restart).
+     */
+    setDevice(deviceName: string): boolean;
+    /**
+     * List available device presets.
+     */
+    static listDevices(): string[];
+    /**
+     * Set geolocation (requires browser restart or use setGeolocationRuntime).
+     */
+    setGeolocation(location: string | {
+        latitude: number;
+        longitude: number;
+        accuracy?: number;
+    }): boolean;
+    /**
+     * Set geolocation at runtime without restarting.
+     */
+    setGeolocationRuntime(location: string | {
+        latitude: number;
+        longitude: number;
+        accuracy?: number;
+    }): Promise<boolean>;
+    /**
+     * List available location presets.
+     */
+    static listLocations(): string[];
     /**
      * Navigate to a URL.
      */

package/dist/browser.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"browser.d.ts","sourceRoot":"","sources":["../src/browser.ts"],"names":[],"mappings":"AAAA;;;;GAIG;AAMH,OAAO,EAAE,KAAK,cAAc,EAAgE,MAAM,aAAa,CAAC;AAEhH,OAAO,KAAK,EAEV,gBAAgB,EAChB,WAAW,EACX,aAAa,EACb,aAAa,EAKb,cAAc,EACd,aAAa,EACb,cAAc,EAEf,MAAM,YAAY,CAAC;AAEpB,qBAAa,QAAQ;IACnB,OAAO,CAAC,MAAM,CAAiB;IAC/B,OAAO,CAAC,KAAK,CAAgB;IAC7B,OAAO,CAAC,OAAO,CAAwB;IACvC,OAAO,CAAC,OAAO,CAA+B;IAC9C,OAAO,CAAC,IAAI,CAAqB;IACjC,OAAO,CAAC,cAAc,CAAwB;gBAElC,UAAU,GAAE,OAAO,CAAC,cAAc,CAAM;IASpD;;OAEG;IACG,MAAM,IAAI,OAAO,CAAC,IAAI,CAAC;IAwB7B;;OAEG;IACG,KAAK,IAAI,OAAO,CAAC,IAAI,CAAC;IAS5B;;OAEG;YACW,OAAO;IAWrB;;OAEG;IACG,QAAQ,CAAC,GAAG,EAAE,MAAM,GAAG,OAAO,CAAC,gBAAgB,CAAC;IAsCtD;;OAEG;IACG,KAAK,CAAC,QAAQ,EAAE,MAAM,EAAE,OAAO,GAAE;QAAE,KAAK,CAAC,EAAE,OAAO,CAAA;KAAO,GAAG,OAAO,CAAC,WAAW,CAAC;IA+CtF;;OAEG;IACG,IAAI,CAAC,QAAQ,EAAE,MAAM,EAAE,KAAK,EAAE,MAAM,GAAG,OAAO,CAAC,WAAW,CAAC;IAiCjE;;OAEG;YACW,WAAW;IAuDzB;;OAEG;IACG,OAAO,CAAC,IAAI,EAAE,MAAM,GAAG,OAAO,CAAC,aAAa,CAAC;IA8DnD;;OAEG;IACG,UAAU,CAAC,IAAI,CAAC,EAAE,MAAM,GAAG,OAAO,CAAC,MAAM,CAAC;IAYhD;;OAEG;IACG,WAAW,CAAC,IAAI,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC;IA6C9C;;OAEG;IACG,WAAW,CAAC,IAAI,EAAE,MAAM,GAAG,OAAO,CAAC,OAAO,CAAC;IA2CjD;;OAEG;IACH,YAAY,IAAI,MAAM,EAAE;IAKxB;;OAEG;IACH,aAAa,CAAC,IAAI,EAAE,MAAM,GAAG,OAAO;IAapC;;OAEG;IACG,OAAO,CAAC,OAAO,EAAE,cAAc,GAAG,OAAO,CAAC,aAAa,CAAC;IAqH9D;;OAEG;IACH,OAAO,CAAC,aAAa;IAarB;;OAEG;IACH,OAAO,CAAC,cAAc;IAkCtB;;OAEG;IACH,OAAO,CAAC,KAAK;IA8Bb;;OAEG;IACH,OAAO,CAAC,OAAO,GAAE,cAAmB,GAAG,aAAa;IA4DpD;;OAEG;IACH,eAAe,IAAI,MAAM,CAAC,MAAM,EAAE;QAAE,KAAK,EAAE,MAAM,CAAC;QAAC,IAAI,EAAE,MAAM,CAAA;KAAE,CAAC;CAqBnE"}
+{"version":3,"file":"browser.d.ts","sourceRoot":"","sources":["../src/browser.ts"],"names":[],"mappings":"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"}

package/dist/browser.js

@@ -11,6 +11,7 @@ const fs_1 = require("fs");
 const path_1 = require("path");
 const config_js_1 = require("./config.js");
 const personas_js_1 = require("./personas.js");
+const types_js_1 = require("./types.js");
 class CBrowser {
     config;
     paths;
@@ -18,6 +19,10 @@ class CBrowser {
     context = null;
     page = null;
     currentPersona = null;
+    networkRequests = [];
+    networkResponses = new Map();
+    harEntries = [];
+    isRecordingHar = false;
     constructor(userConfig = {}) {
         this.config = (0, config_js_1.mergeConfig)(userConfig);
         this.paths = (0, config_js_1.ensureDirectories)((0, config_js_1.getPaths)(this.config.dataDir));
@@ -40,13 +45,77 @@ class CBrowser {
         this.browser = await browserType.launch({
             headless: this.config.headless,
         });
-        this.context = await this.browser.newContext({
+        // Build context options
+        const contextOptions = {
             viewport: {
                 width: this.config.viewportWidth,
                 height: this.config.viewportHeight,
             },
-        });
+        };
+        // Apply device emulation if configured
+        if (this.config.device && types_js_1.DEVICE_PRESETS[this.config.device]) {
+            const device = types_js_1.DEVICE_PRESETS[this.config.device];
+            contextOptions.viewport = device.viewport;
+            contextOptions.userAgent = device.userAgent;
+            contextOptions.deviceScaleFactor = device.deviceScaleFactor;
+            contextOptions.isMobile = device.isMobile;
+            contextOptions.hasTouch = device.hasTouch;
+        }
+        else if (this.config.deviceDescriptor) {
+            const device = this.config.deviceDescriptor;
+            contextOptions.viewport = device.viewport;
+            contextOptions.userAgent = device.userAgent;
+            contextOptions.deviceScaleFactor = device.deviceScaleFactor;
+            contextOptions.isMobile = device.isMobile;
+            contextOptions.hasTouch = device.hasTouch;
+        }
+        // Apply custom user agent if set (overrides device)
+        if (this.config.userAgent) {
+            contextOptions.userAgent = this.config.userAgent;
+        }
+        // Apply geolocation if configured
+        if (this.config.geolocation) {
+            contextOptions.geolocation = {
+                latitude: this.config.geolocation.latitude,
+                longitude: this.config.geolocation.longitude,
+                accuracy: this.config.geolocation.accuracy,
+            };
+            contextOptions.permissions = ["geolocation"];
+        }
+        // Apply locale if configured
+        if (this.config.locale) {
+            contextOptions.locale = this.config.locale;
+        }
+        // Apply timezone if configured
+        if (this.config.timezone) {
+            contextOptions.timezoneId = this.config.timezone;
+        }
+        // Apply color scheme if configured
+        if (this.config.colorScheme) {
+            contextOptions.colorScheme = this.config.colorScheme;
+        }
+        // Enable video recording if configured
+        if (this.config.recordVideo) {
+            const videoDir = this.config.videoDir || (0, path_1.join)(this.paths.dataDir, "videos");
+            if (!(0, fs_1.existsSync)(videoDir)) {
+                (0, fs_1.mkdirSync)(videoDir, { recursive: true });
+            }
+            contextOptions.recordVideo = {
+                dir: videoDir,
+                size: {
+                    width: contextOptions.viewport?.width || 1280,
+                    height: contextOptions.viewport?.height || 800,
+                },
+            };
+        }
+        this.context = await this.browser.newContext(contextOptions);
         this.page = await this.context.newPage();
+        // Apply network mocks if configured
+        if (this.config.networkMocks && this.config.networkMocks.length > 0) {
+            await this.setupNetworkMocks(this.config.networkMocks);
+        }
+        // Set up network request/response tracking for HAR
+        this.setupNetworkTracking();
     }
     /**
      * Close the browser.
@@ -69,6 +138,423 @@ class CBrowser {
         return this.page;
     }
     // =========================================================================
+    // Network Mocking
+    // =========================================================================
+    /**
+     * Set up network mocks for API interception.
+     */
+    async setupNetworkMocks(mocks) {
+        const page = this.page;
+        for (const mock of mocks) {
+            const pattern = typeof mock.urlPattern === "string"
+                ? new RegExp(mock.urlPattern.replace(/[.*+?^${}()|[\]\\]/g, "\\$&"))
+                : mock.urlPattern;
+            await page.route(pattern, async (route) => {
+                const request = route.request();
+                // Check method match if specified
+                if (mock.method && request.method() !== mock.method.toUpperCase()) {
+                    await route.continue();
+                    return;
+                }
+                // Handle abort
+                if (mock.abort) {
+                    await route.abort();
+                    return;
+                }
+                // Apply delay if specified
+                if (mock.delay) {
+                    await new Promise((r) => setTimeout(r, mock.delay));
+                }
+                // Fulfill with mock response
+                const body = typeof mock.body === "object"
+                    ? JSON.stringify(mock.body)
+                    : mock.body || "";
+                await route.fulfill({
+                    status: mock.status || 200,
+                    headers: mock.headers || { "Content-Type": "application/json" },
+                    body,
+                });
+            });
+        }
+    }
+    /**
+     * Add a network mock at runtime.
+     */
+    async addNetworkMock(mock) {
+        const page = await this.getPage();
+        await this.setupNetworkMocks([mock]);
+    }
+    /**
+     * Clear all network mocks.
+     */
+    async clearNetworkMocks() {
+        const page = await this.getPage();
+        await page.unrouteAll();
+    }
+    // =========================================================================
+    // Network Tracking & HAR Export
+    // =========================================================================
+    /**
+     * Set up network request/response tracking for HAR.
+     */
+    setupNetworkTracking() {
+        if (!this.page)
+            return;
+        this.page.on("request", (request) => {
+            const networkRequest = {
+                url: request.url(),
+                method: request.method(),
+                headers: request.headers(),
+                postData: request.postData() || undefined,
+                resourceType: request.resourceType(),
+                timestamp: new Date().toISOString(),
+            };
+            this.networkRequests.push(networkRequest);
+            if (this.isRecordingHar) {
+                // Start HAR entry
+                const harEntry = {
+                    startedDateTime: new Date().toISOString(),
+                    request: {
+                        method: request.method(),
+                        url: request.url(),
+                        httpVersion: "HTTP/1.1",
+                        headers: Object.entries(request.headers()).map(([name, value]) => ({ name, value })),
+                        queryString: [],
+                        headersSize: -1,
+                        bodySize: request.postData()?.length || 0,
+                    },
+                };
+                this.networkResponses.set(request.url() + request.method(), harEntry);
+            }
+        });
+        this.page.on("response", async (response) => {
+            const key = response.url() + response.request().method();
+            const networkResponse = {
+                url: response.url(),
+                status: response.status(),
+                statusText: response.statusText(),
+                headers: response.headers(),
+            };
+            if (this.isRecordingHar && this.networkResponses.has(key)) {
+                const partial = this.networkResponses.get(key);
+                const startTime = new Date(partial.startedDateTime).getTime();
+                const endTime = Date.now();
+                const harEntry = {
+                    ...partial,
+                    time: endTime - startTime,
+                    response: {
+                        status: response.status(),
+                        statusText: response.statusText(),
+                        httpVersion: "HTTP/1.1",
+                        headers: Object.entries(response.headers()).map(([name, value]) => ({ name, value })),
+                        content: {
+                            size: parseInt(response.headers()["content-length"] || "0"),
+                            mimeType: response.headers()["content-type"] || "application/octet-stream",
+                        },
+                        redirectURL: response.headers()["location"] || "",
+                        headersSize: -1,
+                        bodySize: parseInt(response.headers()["content-length"] || "-1"),
+                    },
+                    cache: {},
+                    timings: {
+                        blocked: 0,
+                        dns: -1,
+                        connect: -1,
+                        send: 0,
+                        wait: endTime - startTime,
+                        receive: 0,
+                        ssl: -1,
+                    },
+                };
+                this.harEntries.push(harEntry);
+                this.networkResponses.delete(key);
+            }
+        });
+    }
+    /**
+     * Start recording HAR.
+     */
+    startHarRecording() {
+        this.isRecordingHar = true;
+        this.harEntries = [];
+    }
+    /**
+     * Stop recording and export HAR.
+     */
+    async exportHar(outputPath) {
+        this.isRecordingHar = false;
+        const harLog = {
+            version: "1.2",
+            creator: { name: "CBrowser", version: "2.4.0" },
+            entries: this.harEntries,
+        };
+        const har = { log: harLog };
+        const harDir = (0, path_1.join)(this.paths.dataDir, "har");
+        if (!(0, fs_1.existsSync)(harDir)) {
+            (0, fs_1.mkdirSync)(harDir, { recursive: true });
+        }
+        const filename = outputPath || (0, path_1.join)(harDir, `har-${Date.now()}.har`);
+        (0, fs_1.writeFileSync)(filename, JSON.stringify(har, null, 2));
+        return filename;
+    }
+    /**
+     * Get all captured network requests.
+     */
+    getNetworkRequests() {
+        return [...this.networkRequests];
+    }
+    /**
+     * Clear network request history.
+     */
+    clearNetworkHistory() {
+        this.networkRequests = [];
+        this.harEntries = [];
+    }
+    // =========================================================================
+    // Performance Metrics
+    // =========================================================================
+    /**
+     * Collect Core Web Vitals and performance metrics.
+     */
+    async getPerformanceMetrics() {
+        const page = await this.getPage();
+        const metrics = await page.evaluate(() => {
+            const result = {};
+            // Navigation timing
+            const navTiming = performance.getEntriesByType("navigation")[0];
+            if (navTiming) {
+                result.ttfb = navTiming.responseStart - navTiming.requestStart;
+                result.domContentLoaded = navTiming.domContentLoadedEventEnd - navTiming.startTime;
+                result.load = navTiming.loadEventEnd - navTiming.startTime;
+            }
+            // Paint timing
+            const paintEntries = performance.getEntriesByType("paint");
+            for (const entry of paintEntries) {
+                if (entry.name === "first-contentful-paint") {
+                    result.fcp = entry.startTime;
+                }
+            }
+            // LCP from PerformanceObserver (if available)
+            const lcpEntries = performance.getEntriesByType("largest-contentful-paint");
+            if (lcpEntries.length > 0) {
+                result.lcp = lcpEntries[lcpEntries.length - 1].startTime;
+            }
+            // CLS from layout-shift entries
+            const clsEntries = performance.getEntriesByType("layout-shift");
+            let clsScore = 0;
+            for (const entry of clsEntries) {
+                if (!entry.hadRecentInput) {
+                    clsScore += entry.value || 0;
+                }
+            }
+            result.cls = clsScore;
+            // Resource counts
+            const resources = performance.getEntriesByType("resource");
+            result.resourceCount = resources.length;
+            result.transferSize = resources.reduce((sum, r) => sum + (r.transferSize || 0), 0);
+            return result;
+        });
+        // Rate the metrics
+        const lcpRating = metrics.lcp
+            ? metrics.lcp <= 2500 ? "good" : metrics.lcp <= 4000 ? "needs-improvement" : "poor"
+            : undefined;
+        const clsRating = metrics.cls !== undefined
+            ? metrics.cls <= 0.1 ? "good" : metrics.cls <= 0.25 ? "needs-improvement" : "poor"
+            : undefined;
+        return {
+            lcp: metrics.lcp,
+            cls: metrics.cls,
+            fcp: metrics.fcp,
+            ttfb: metrics.ttfb,
+            domContentLoaded: metrics.domContentLoaded,
+            load: metrics.load,
+            resourceCount: metrics.resourceCount,
+            transferSize: metrics.transferSize,
+            lcpRating: lcpRating,
+            clsRating: clsRating,
+        };
+    }
+    /**
+     * Run a performance audit against a budget.
+     */
+    async auditPerformance(url) {
+        if (url) {
+            await this.navigate(url);
+        }
+        const page = await this.getPage();
+        const metrics = await this.getPerformanceMetrics();
+        const budget = this.config.performanceBudget;
+        const violations = [];
+        let passed = true;
+        if (budget) {
+            if (budget.lcp && metrics.lcp && metrics.lcp > budget.lcp) {
+                violations.push(`LCP ${metrics.lcp}ms exceeds budget ${budget.lcp}ms`);
+                passed = false;
+            }
+            if (budget.fcp && metrics.fcp && metrics.fcp > budget.fcp) {
+                violations.push(`FCP ${metrics.fcp}ms exceeds budget ${budget.fcp}ms`);
+                passed = false;
+            }
+            if (budget.cls && metrics.cls && metrics.cls > budget.cls) {
+                violations.push(`CLS ${metrics.cls} exceeds budget ${budget.cls}`);
+                passed = false;
+            }
+            if (budget.ttfb && metrics.ttfb && metrics.ttfb > budget.ttfb) {
+                violations.push(`TTFB ${metrics.ttfb}ms exceeds budget ${budget.ttfb}ms`);
+                passed = false;
+            }
+            if (budget.transferSize && metrics.transferSize && metrics.transferSize > budget.transferSize) {
+                violations.push(`Transfer size ${metrics.transferSize}B exceeds budget ${budget.transferSize}B`);
+                passed = false;
+            }
+            if (budget.resourceCount && metrics.resourceCount && metrics.resourceCount > budget.resourceCount) {
+                violations.push(`Resource count ${metrics.resourceCount} exceeds budget ${budget.resourceCount}`);
+                passed = false;
+            }
+        }
+        return {
+            url: page.url(),
+            timestamp: new Date().toISOString(),
+            metrics,
+            budget,
+            passed,
+            violations,
+        };
+    }
+    // =========================================================================
+    // Cookie Management
+    // =========================================================================
+    /**
+     * Get all cookies for the current context.
+     */
+    async getCookies(urls) {
+        if (!this.context) {
+            await this.launch();
+        }
+        return await this.context.cookies(urls);
+    }
+    /**
+     * Set cookies.
+     */
+    async setCookies(cookies) {
+        if (!this.context) {
+            await this.launch();
+        }
+        await this.context.addCookies(cookies);
+    }
+    /**
+     * Clear all cookies.
+     */
+    async clearCookies() {
+        if (!this.context)
+            return;
+        await this.context.clearCookies();
+    }
+    /**
+     * Delete specific cookies by name.
+     */
+    async deleteCookie(name, domain) {
+        const cookies = await this.getCookies();
+        const filtered = cookies.filter((c) => {
+            if (c.name !== name)
+                return true;
+            if (domain && c.domain !== domain)
+                return true;
+            return false;
+        });
+        await this.clearCookies();
+        if (filtered.length > 0) {
+            await this.setCookies(filtered);
+        }
+    }
+    // =========================================================================
+    // Video Recording
+    // =========================================================================
+    /**
+     * Get the path to the video file (after browser closes).
+     */
+    async getVideoPath() {
+        if (!this.page)
+            return null;
+        const video = this.page.video();
+        if (!video)
+            return null;
+        return await video.path();
+    }
+    /**
+     * Save the video with a custom filename.
+     */
+    async saveVideo(outputPath) {
+        if (!this.page)
+            return null;
+        const video = this.page.video();
+        if (!video)
+            return null;
+        await video.saveAs(outputPath);
+        return outputPath;
+    }
+    // =========================================================================
+    // Device Emulation
+    // =========================================================================
+    /**
+     * Set device emulation (requires browser restart).
+     */
+    setDevice(deviceName) {
+        if (types_js_1.DEVICE_PRESETS[deviceName]) {
+            this.config.device = deviceName;
+            return true;
+        }
+        return false;
+    }
+    /**
+     * List available device presets.
+     */
+    static listDevices() {
+        return Object.keys(types_js_1.DEVICE_PRESETS);
+    }
+    // =========================================================================
+    // Geolocation
+    // =========================================================================
+    /**
+     * Set geolocation (requires browser restart or use setGeolocationRuntime).
+     */
+    setGeolocation(location) {
+        if (typeof location === "string") {
+            if (types_js_1.LOCATION_PRESETS[location]) {
+                this.config.geolocation = types_js_1.LOCATION_PRESETS[location];
+                return true;
+            }
+            return false;
+        }
+        this.config.geolocation = location;
+        return true;
+    }
+    /**
+     * Set geolocation at runtime without restarting.
+     */
+    async setGeolocationRuntime(location) {
+        if (!this.context)
+            return false;
+        let geo;
+        if (typeof location === "string") {
+            if (!types_js_1.LOCATION_PRESETS[location])
+                return false;
+            geo = types_js_1.LOCATION_PRESETS[location];
+        }
+        else {
+            geo = location;
+        }
+        await this.context.setGeolocation(geo);
+        await this.context.grantPermissions(["geolocation"]);
+        return true;
+    }
+    /**
+     * List available location presets.
+     */
+    static listLocations() {
+        return Object.keys(types_js_1.LOCATION_PRESETS);
+    }
+    // =========================================================================
     // Navigation
     // =========================================================================
     /**