@monostate/node-scraper 2.0.0 → 2.2.0

package/computer-use-provider.js

@@ -0,0 +1,168 @@
+/**
+ * Abstract base class for computer-use providers.
+ *
+ * A provider manages a display server (e.g. Xvfb), a browser (Chrome),
+ * and optionally a VNC server. It exposes coordinate-based actions
+ * (mouse, keyboard) and screenshots for AI computer-use agents.
+ *
+ * Open-source implementations:
+ *   - LocalProvider: spawns Xvfb + Chrome + xdotool on the local machine
+ *
+ * To build your own provider (Docker, Kubernetes, cloud VMs, etc.),
+ * extend this class and implement all methods.
+ *
+ * @example
+ * import { ComputerUseProvider } from '@monostate/node-scraper';
+ *
+ * class MyCloudProvider extends ComputerUseProvider {
+ *   async start() {
+ *     // spin up a VM, return CDP URL
+ *     return { cdpUrl: 'ws://...', vncUrl: 'https://...', screenSize: { width: 1280, height: 800 } };
+ *   }
+ *   // ... implement all other methods ...
+ * }
+ */
+
+/**
+ * @typedef {Object} ProviderInfo
+ * @property {string} cdpUrl - WebSocket URL for Chrome DevTools Protocol (ws://...)
+ * @property {string|null} vncUrl - noVNC URL for live browser view (null if unavailable)
+ * @property {{width: number, height: number}} screenSize - Virtual display dimensions
+ */
+
+/**
+ * @typedef {Object} CoordinateActionResult
+ * @property {boolean} success
+ * @property {string} [screenshot] - base64 data URL of screenshot after action (optional)
+ * @property {string} [error] - error message if failed
+ */
+
+export class ComputerUseProvider {
+  /**
+   * Start the environment: display server, browser, VNC, etc.
+   * @returns {Promise<ProviderInfo>}
+   */
+  async start() {
+    throw new Error('ComputerUseProvider.start() not implemented');
+  }
+
+  /**
+   * Stop the environment and release all resources.
+   * @returns {Promise<void>}
+   */
+  async stop() {
+    throw new Error('ComputerUseProvider.stop() not implemented');
+  }
+
+  /**
+   * Capture a screenshot of the full virtual display.
+   * @returns {Promise<{screenshot: string}>} base64 data URL (data:image/png;base64,...)
+   */
+  async screenshot() {
+    throw new Error('ComputerUseProvider.screenshot() not implemented');
+  }
+
+  // ── Coordinate-based actions ──────────────────────────────
+
+  /**
+   * Move the mouse cursor to (x, y).
+   * @param {number} x
+   * @param {number} y
+   * @returns {Promise<CoordinateActionResult>}
+   */
+  async mouseMove(x, y) {
+    throw new Error('ComputerUseProvider.mouseMove() not implemented');
+  }
+
+  /**
+   * Click at (x, y).
+   * @param {number} x
+   * @param {number} y
+   * @param {'left'|'right'|'middle'} [button='left']
+   * @returns {Promise<CoordinateActionResult>}
+   */
+  async mouseClick(x, y, button = 'left') {
+    throw new Error('ComputerUseProvider.mouseClick() not implemented');
+  }
+
+  /**
+   * Double-click at (x, y).
+   * @param {number} x
+   * @param {number} y
+   * @param {'left'|'right'|'middle'} [button='left']
+   * @returns {Promise<CoordinateActionResult>}
+   */
+  async mouseDoubleClick(x, y, button = 'left') {
+    throw new Error('ComputerUseProvider.mouseDoubleClick() not implemented');
+  }
+
+  /**
+   * Drag from (startX, startY) to (endX, endY).
+   * @param {number} startX
+   * @param {number} startY
+   * @param {number} endX
+   * @param {number} endY
+   * @returns {Promise<CoordinateActionResult>}
+   */
+  async mouseDrag(startX, startY, endX, endY) {
+    throw new Error('ComputerUseProvider.mouseDrag() not implemented');
+  }
+
+  /**
+   * Scroll at (x, y) in a direction.
+   * @param {number} x
+   * @param {number} y
+   * @param {'up'|'down'} direction
+   * @param {number} [amount=3] - number of scroll steps
+   * @returns {Promise<CoordinateActionResult>}
+   */
+  async scroll(x, y, direction, amount = 3) {
+    throw new Error('ComputerUseProvider.scroll() not implemented');
+  }
+
+  /**
+   * Press a key or key combination (e.g. 'Return', 'ctrl+c', 'alt+Tab').
+   * @param {string} key - xdotool-compatible key name
+   * @returns {Promise<CoordinateActionResult>}
+   */
+  async pressKey(key) {
+    throw new Error('ComputerUseProvider.pressKey() not implemented');
+  }
+
+  /**
+   * Type text character by character.
+   * @param {string} text
+   * @returns {Promise<CoordinateActionResult>}
+   */
+  async typeText(text) {
+    throw new Error('ComputerUseProvider.typeText() not implemented');
+  }
+
+  /**
+   * Wait for a duration.
+   * @param {number} ms - milliseconds to wait
+   * @returns {Promise<CoordinateActionResult>}
+   */
+  async wait(ms) {
+    await new Promise(resolve => setTimeout(resolve, ms));
+    return { success: true };
+  }
+
+  /**
+   * Get the current cursor position.
+   * @returns {Promise<{x: number, y: number}>}
+   */
+  async getCursorPosition() {
+    throw new Error('ComputerUseProvider.getCursorPosition() not implemented');
+  }
+
+  /**
+   * Get the virtual display dimensions.
+   * @returns {Promise<{width: number, height: number}>}
+   */
+  async getScreenSize() {
+    throw new Error('ComputerUseProvider.getScreenSize() not implemented');
+  }
+}
+
+export default ComputerUseProvider;

package/index.d.ts

@@ -455,6 +455,165 @@ export function bulkScrape(urls: string[], options?: BulkScrapeOptions): Promise
  */
 export function bulkScrapeStream(urls: string[], options: BulkScrapeStreamOptions): Promise<BulkScrapeStreamStats>;
 
+// ── Computer Use Provider ─────────────────────────────────────
+
+export interface ProviderInfo {
+  cdpUrl: string;
+  vncUrl: string | null;
+  screenSize: { width: number; height: number };
+}
+
+export interface CoordinateActionResult {
+  success: boolean;
+  screenshot?: string | null;
+  error?: string | null;
+}
+
+export declare class ComputerUseProvider {
+  start(): Promise<ProviderInfo>;
+  stop(): Promise<void>;
+  screenshot(): Promise<{ screenshot: string }>;
+  mouseMove(x: number, y: number): Promise<CoordinateActionResult>;
+  mouseClick(x: number, y: number, button?: 'left' | 'right' | 'middle'): Promise<CoordinateActionResult>;
+  mouseDoubleClick(x: number, y: number, button?: 'left' | 'right' | 'middle'): Promise<CoordinateActionResult>;
+  mouseDrag(startX: number, startY: number, endX: number, endY: number): Promise<CoordinateActionResult>;
+  scroll(x: number, y: number, direction: 'up' | 'down', amount?: number): Promise<CoordinateActionResult>;
+  pressKey(key: string): Promise<CoordinateActionResult>;
+  typeText(text: string): Promise<CoordinateActionResult>;
+  wait(ms: number): Promise<CoordinateActionResult>;
+  getCursorPosition(): Promise<{ x: number; y: number }>;
+  getScreenSize(): Promise<{ width: number; height: number }>;
+}
+
+export interface LocalProviderOptions {
+  screenWidth?: number;
+  screenHeight?: number;
+  enableVnc?: boolean;
+  chromePath?: string;
+  chromeArgs?: string[];
+}
+
+export declare class LocalProvider extends ComputerUseProvider {
+  constructor(options?: LocalProviderOptions);
+}
+
+// ── Browser Session ───────────────────────────────────────────
+
+export interface BrowserSessionOptions {
+  mode?: 'headless' | 'visual' | 'auto' | 'computer-use';
+  timeout?: number;
+  userAgent?: string;
+  lightpandaPath?: string;
+  verbose?: boolean;
+  provider?: ComputerUseProvider;
+}
+
+export interface PageState {
+  url: string;
+  title: string;
+  text: string;
+  interactiveElements: Array<{
+    type: 'button' | 'link' | 'input' | 'select';
+    text?: string;
+    label?: string;
+    href?: string;
+    selector: string;
+    tag?: string;
+    inputType?: string;
+    value?: string;
+  }>;
+  screenshot?: string;
+  backend: 'lightpanda' | 'chrome' | 'computer-use';
+  sessionHistory: Array<{ type: string; timestamp: number; backend: string }>;
+}
+
+export interface ActionResult {
+  success: boolean;
+  url?: string;
+  screenshot?: string;
+  backend?: string;
+}
+
+export interface BrowserAction {
+  type: 'goto' | 'click' | 'type' | 'scroll' | 'hover' | 'select' | 'pressKey' | 'goBack' | 'goForward' | 'screenshot' | 'extractContent' | 'waitFor' | 'mouseMove' | 'clickAt' | 'doubleClickAt' | 'drag' | 'scrollAt' | 'typeText' | 'getCursorPosition' | 'getScreenSize';
+  url?: string;
+  selector?: string;
+  text?: string;
+  key?: string;
+  direction?: 'up' | 'down';
+  amount?: number;
+  values?: string[];
+  timeout?: number;
+  expectNavigation?: boolean;
+  waitForNavigation?: boolean;
+  clear?: boolean;
+  delay?: number;
+  fullPage?: boolean;
+  type_?: 'png' | 'jpeg' | 'webp';
+  includeScreenshot?: boolean;
+  /** Coordinate-based action fields */
+  x?: number;
+  y?: number;
+  button?: 'left' | 'right' | 'middle';
+  startX?: number;
+  startY?: number;
+  endX?: number;
+  endY?: number;
+}
+
+export declare class BrowserSession {
+  constructor(options?: BrowserSessionOptions);
+
+  readonly activeBackend: 'lightpanda' | 'chrome' | 'computer-use' | null;
+  readonly mode: 'headless' | 'visual' | 'auto' | 'computer-use';
+
+  connect(): Promise<BrowserSession>;
+  goto(url: string): Promise<ActionResult>;
+  goBack(): Promise<void>;
+  goForward(): Promise<void>;
+  click(selector: string, options?: { timeout?: number; expectNavigation?: boolean; waitForNavigation?: boolean }): Promise<ActionResult>;
+  type(selector: string, text: string, options?: { timeout?: number; clear?: boolean; delay?: number }): Promise<ActionResult>;
+  scroll(direction?: 'up' | 'down', amount?: number): Promise<ActionResult>;
+  hover(selector: string): Promise<ActionResult>;
+  select(selector: string, ...values: string[]): Promise<ActionResult>;
+  pressKey(key: string): Promise<ActionResult>;
+  screenshot(options?: { type?: 'png' | 'jpeg' | 'webp'; fullPage?: boolean }): Promise<{ success: boolean; screenshot: string; backend: string }>;
+  extractContent(): Promise<{ title: string; metaDescription: string; headings: any[]; paragraphs: string[]; links: any[]; bodyText: string; url: string }>;
+  evaluate<T>(fn: (...args: any[]) => T, ...args: any[]): Promise<T>;
+  waitFor(selector: string, timeout?: number): Promise<ActionResult>;
+  getPageState(options?: { includeScreenshot?: boolean }): Promise<PageState>;
+  executeAction(action: BrowserAction): Promise<ActionResult>;
+  getCookies(): Promise<any[]>;
+  setCookies(cookies: any[]): Promise<void>;
+  getHistory(): Array<{ type: string; timestamp: number; backend: string }>;
+  getBackend(): 'lightpanda' | 'chrome' | 'computer-use' | null;
+  close(): Promise<void>;
+
+  /** Coordinate-based actions (computer-use mode only) */
+  mouseMove(x: number, y: number): Promise<CoordinateActionResult>;
+  clickAt(x: number, y: number, button?: 'left' | 'right' | 'middle'): Promise<CoordinateActionResult>;
+  doubleClickAt(x: number, y: number, button?: 'left' | 'right' | 'middle'): Promise<CoordinateActionResult>;
+  drag(startX: number, startY: number, endX: number, endY: number): Promise<CoordinateActionResult>;
+  scrollAt(x: number, y: number, direction: 'up' | 'down', amount?: number): Promise<CoordinateActionResult>;
+  typeText(text: string): Promise<CoordinateActionResult>;
+  getCursorPosition(): Promise<{ x: number; y: number }>;
+  getScreenSize(): Promise<{ width: number; height: number }>;
+  getVncUrl(): string | null;
+}
+
+export function createSession(options?: BrowserSessionOptions): Promise<BrowserSession>;
+
+export declare class LightPandaServer {
+  constructor(binaryPath?: string);
+  start(port?: number): Promise<string>;
+  getEndpoint(): string;
+  isRunning(): boolean;
+  stop(): void;
+}
+
+export function getLightPandaServer(binaryPath?: string): LightPandaServer;
+export function stopLightPandaServer(): void;
+
 /**
  * Default export - same as BNCASmartScraper class
  */

package/index.js

@@ -1795,4 +1795,10 @@ export async function bulkScrapeStream(urls, options = {}) {
   }
 }
 
+// Browser session exports
+export { BrowserSession, createSession } from './browser-session.js';
+export { default as LightPandaServer, getLightPandaServer, stopLightPandaServer } from './lightpanda-server.js';
+export { ComputerUseProvider } from './computer-use-provider.js';
+export { LocalProvider } from './providers/local-provider.js';
+
 export default BNCASmartScraper;

package/lightpanda-server.js

@@ -0,0 +1,151 @@
+import { spawn } from 'child_process';
+import { createServer } from 'net';
+import path from 'path';
+import fs from 'fs';
+
+class LightPandaServer {
+  constructor(binaryPath) {
+    this.binaryPath = binaryPath || this._findBinary();
+    this.process = null;
+    this.host = '127.0.0.1';
+    this.port = null;
+    this.ready = false;
+  }
+
+  async start(port) {
+    if (this.process && this.ready) return this.getEndpoint();
+
+    this.port = port || await this._findAvailablePort();
+
+    return new Promise((resolve, reject) => {
+      const args = [
+        'serve',
+        '--host', this.host,
+        '--port', String(this.port),
+        '--cdp_max_connections', '16',
+      ];
+
+      this.process = spawn(this.binaryPath, args, {
+        stdio: ['ignore', 'pipe', 'pipe'],
+      });
+
+      let stderr = '';
+
+      const onReady = () => {
+        this.ready = true;
+        resolve(this.getEndpoint());
+      };
+
+      // LP prints to stderr when ready — wait for it or poll /json/version
+      this.process.stderr.on('data', (data) => {
+        stderr += data.toString();
+        // LightPanda logs server start to stderr
+        if (stderr.includes('Listening on') || stderr.includes('server started')) {
+          onReady();
+        }
+      });
+
+      this.process.on('error', (err) => {
+        this.ready = false;
+        reject(new Error(`Failed to start LightPanda: ${err.message}`));
+      });
+
+      this.process.on('exit', (code) => {
+        this.ready = false;
+        this.process = null;
+        if (!this.ready) {
+          reject(new Error(`LightPanda exited with code ${code}: ${stderr}`));
+        }
+      });
+
+      // Fallback: poll /json/version if no stderr signal within 3s
+      setTimeout(async () => {
+        if (this.ready) return;
+        try {
+          const res = await fetch(`http://${this.host}:${this.port}/json/version`);
+          if (res.ok) onReady();
+        } catch {
+          // Still starting up, give it more time
+        }
+      }, 1500);
+
+      // Hard timeout
+      setTimeout(() => {
+        if (!this.ready) {
+          this.stop();
+          reject(new Error(`LightPanda failed to start within 5s. stderr: ${stderr}`));
+        }
+      }, 5000);
+    });
+  }
+
+  getEndpoint() {
+    return `ws://${this.host}:${this.port}`;
+  }
+
+  isRunning() {
+    return this.ready && this.process !== null;
+  }
+
+  stop() {
+    if (this.process) {
+      try {
+        this.process.kill('SIGTERM');
+      } catch {
+        // already dead
+      }
+      this.process = null;
+    }
+    this.ready = false;
+    this.port = null;
+  }
+
+  async _findAvailablePort() {
+    return new Promise((resolve, reject) => {
+      const server = createServer();
+      server.listen(0, '127.0.0.1', () => {
+        const port = server.address().port;
+        server.close(() => resolve(port));
+      });
+      server.on('error', reject);
+    });
+  }
+
+  _findBinary() {
+    // Check common locations
+    const candidates = [
+      path.join(path.dirname(new URL(import.meta.url).pathname), 'bin', 'lightpanda'),
+      '/usr/local/bin/lightpanda',
+      '/usr/bin/lightpanda',
+    ];
+
+    for (const p of candidates) {
+      if (fs.existsSync(p)) return p;
+    }
+
+    return 'lightpanda'; // hope it's on PATH
+  }
+}
+
+// Singleton instance — shared across all sessions
+let _instance = null;
+
+export function getLightPandaServer(binaryPath) {
+  if (!_instance) {
+    _instance = new LightPandaServer(binaryPath);
+  }
+  return _instance;
+}
+
+export function stopLightPandaServer() {
+  if (_instance) {
+    _instance.stop();
+    _instance = null;
+  }
+}
+
+process.on('SIGTERM', stopLightPandaServer);
+process.on('SIGINT', stopLightPandaServer);
+process.on('beforeExit', stopLightPandaServer);
+
+export default LightPandaServer;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@monostate/node-scraper",
-  "version": "2.0.0",
+  "version": "2.2.0",
   "description": "Intelligent web scraping with AI Q&A, PDF support and multi-level fallback system - 11x faster than traditional scrapers",
   "type": "module",
   "main": "index.js",
@@ -15,6 +15,10 @@
     "index.js",
     "index.d.ts",
     "browser-pool.js",
+    "browser-session.js",
+    "lightpanda-server.js",
+    "computer-use-provider.js",
+    "providers/",
     "README.md",
     "BULK_SCRAPING.md",
     "package.json",
@@ -34,6 +38,9 @@
     "data-extraction",
     "automation",
     "browser",
+    "browser-use",
+    "cdp",
+    "ai-agent",
     "ai-powered",
     "question-answering",
     "pdf-parsing",