@monostate/browsernative-client 2.0.0 → 2.2.0

package/README.md

@@ -112,6 +112,50 @@ const client = new BrowserNativeClient(apiKey, {
 }
 ```
 
+### Browser sessions
+
+Persistent browser sessions with real-time control over WebSocket:
+
+```javascript
+const session = await client.createSession({ mode: 'auto' });
+
+await session.goto('https://example.com');
+await session.click('#login');
+await session.type('#email', 'user@example.com');
+const state = await session.getPageState({ includeScreenshot: true });
+await session.screenshot();
+
+// Listen for backend fallback events
+session.on('fallback', (e) => console.log(`${e.from} -> ${e.to}: ${e.reason}`));
+
+session.close();
+```
+
+Modes: `auto` (LightPanda + Chrome fallback), `headless`, `visual`, `computer-use`.
+
+#### Computer use mode
+
+For AI agents that control the browser by pixel coordinates:
+
+```javascript
+const session = await client.createSession({ mode: 'computer-use', screenWidth: 1280, screenHeight: 800 });
+
+await session.goto('https://example.com');
+await session.clickAt(640, 400);
+await session.typeText('hello world');
+await session.mouseMove(100, 200);
+await session.drag(10, 20, 300, 400);
+await session.scrollAt(640, 400, 'down', 5);
+const pos = await session.getCursorPosition();
+const size = await session.getScreenSize();
+const screenshot = await session.screenshot();
+
+// VNC streaming URL
+console.log(session.vncUrl);
+
+session.close();
+```
+
 ## TypeScript
 
 Full type definitions included.

package/index.d.ts

@@ -168,6 +168,114 @@ export interface HealthResult {
   responseTime: number;
 }
 
+export interface SessionOptions {
+  /** Browser mode (default: 'auto') */
+  mode?: 'auto' | 'headless' | 'visual' | 'computer-use';
+  /** Screen width for computer-use mode */
+  screenWidth?: number;
+  /** Screen height for computer-use mode */
+  screenHeight?: number;
+}
+
+export interface PageState {
+  url: string;
+  title: string;
+  content?: string;
+  screenshot?: string;
+  interactiveElements?: Array<{
+    tag: string;
+    text?: string;
+    selector: string;
+    type?: string;
+    href?: string;
+  }>;
+}
+
+export interface FallbackEvent {
+  type: 'fallback';
+  from: string;
+  to: string;
+  reason: string;
+}
+
+export interface ClosedEvent {
+  type: 'closed';
+  reason: string;
+}
+
+export interface Cookie {
+  name: string;
+  value: string;
+  domain?: string;
+  path?: string;
+  expires?: number;
+  httpOnly?: boolean;
+  secure?: boolean;
+  sameSite?: 'Strict' | 'Lax' | 'None';
+}
+
+/**
+ * Persistent browser session over WebSocket
+ */
+export declare class BrowserSession {
+  /** Session ID assigned by the server */
+  sessionId: string | null;
+  /** Current browser backend ('lightpanda', 'chrome', or 'computer-use') */
+  backend: string | null;
+  /** VNC URL for computer-use mode (null otherwise) */
+  vncUrl: string | null;
+
+  /** Navigate to a URL */
+  goto(url: string): Promise<any>;
+  /** Click an element */
+  click(selector: string, options?: { timeout?: number }): Promise<any>;
+  /** Type text into an element */
+  type(selector: string, text: string, options?: { clear?: boolean; delay?: number }): Promise<any>;
+  /** Scroll the page */
+  scroll(direction?: 'up' | 'down', amount?: number): Promise<any>;
+  /** Hover over an element */
+  hover(selector: string): Promise<any>;
+  /** Select option(s) in a dropdown */
+  select(selector: string, ...values: string[]): Promise<any>;
+  /** Press a keyboard key */
+  pressKey(key: string): Promise<any>;
+  /** Navigate back */
+  goBack(): Promise<any>;
+  /** Navigate forward */
+  goForward(): Promise<any>;
+  /** Take a screenshot */
+  screenshot(options?: { fullPage?: boolean; type?: 'png' | 'jpeg' | 'webp'; quality?: number }): Promise<any>;
+  /** Get current page state with interactive elements */
+  getPageState(options?: { includeScreenshot?: boolean }): Promise<PageState>;
+  /** Extract page content as structured data */
+  extractContent(): Promise<any>;
+  /** Wait for a selector to appear */
+  waitFor(selector: string, timeout?: number): Promise<any>;
+  /** Evaluate JavaScript in the page context */
+  evaluate(fn: string): Promise<any>;
+  /** Get all cookies */
+  getCookies(): Promise<Cookie[]>;
+  /** Set cookies */
+  setCookies(cookies: Cookie[]): Promise<any>;
+
+  /** Coordinate-based actions (computer-use mode) */
+  mouseMove(x: number, y: number): Promise<any>;
+  clickAt(x: number, y: number, button?: 'left' | 'right' | 'middle'): Promise<any>;
+  doubleClickAt(x: number, y: number, button?: 'left' | 'right' | 'middle'): Promise<any>;
+  drag(startX: number, startY: number, endX: number, endY: number): Promise<any>;
+  scrollAt(x: number, y: number, direction: 'up' | 'down', amount?: number): Promise<any>;
+  typeText(text: string): Promise<any>;
+  getCursorPosition(): Promise<{ x: number; y: number }>;
+  getScreenSize(): Promise<{ width: number; height: number }>;
+
+  /** Listen for session events */
+  on(event: 'fallback', handler: (event: FallbackEvent) => void): this;
+  on(event: 'closed', handler: (event: ClosedEvent) => void): this;
+
+  /** Close the session */
+  close(): void;
+}
+
 /**
  * Browser Native API Client
  */
@@ -204,6 +312,11 @@ export declare class BrowserNativeClient {
    */
   getUsage(days?: number): Promise<UsageResult>;
 
+  /**
+   * Create a persistent browser session via WebSocket
+   */
+  createSession(options?: SessionOptions): Promise<BrowserSession>;
+
   /**
    * Check API health and your account status
    */

package/index.js

@@ -143,6 +143,30 @@ export class BrowserNativeClient {
     return this._makeRequest('/stats', {}, 'GET');
   }
 
+  /**
+   * Create a persistent browser session via WebSocket
+   * @param {object} options - Session options
+   * @param {'auto'|'headless'|'visual'|'computer-use'} options.mode - Browser mode (default: 'auto')
+   * @param {number} [options.screenWidth] - Screen width for computer-use mode
+   * @param {number} [options.screenHeight] - Screen height for computer-use mode
+   * @returns {Promise<BrowserSession>} Connected browser session
+   */
+  async createSession(options = {}) {
+    const wsUrl = this.baseUrl.replace(/^http/, 'ws');
+    const mode = options.mode || 'auto';
+    const params = new URLSearchParams({
+      apiKey: this.apiKey,
+      mode,
+    });
+    if (options.screenWidth) params.set('screenWidth', String(options.screenWidth));
+    if (options.screenHeight) params.set('screenHeight', String(options.screenHeight));
+    const url = `${wsUrl}/session?${params}`;
+
+    const session = new BrowserSession(url, { verbose: this.verbose });
+    await session.connect();
+    return session;
+  }
+
   /**
    * Check API health and your account status
    * @returns {Promise<object>} Health check result
@@ -294,5 +318,149 @@ export async function bulkScrape(urls, apiKey, options = {}) {
   return client.bulkScrape(urls, options);
 }
 
+// ── Browser Session (WebSocket) ──────────────────────────────────────────────
+
+class BrowserSession {
+  constructor(url, options = {}) {
+    this._url = url;
+    this._ws = null;
+    this._nextId = 1;
+    this._pending = new Map(); // id → { resolve, reject }
+    this._verbose = options.verbose || false;
+    this._eventHandlers = {};
+    this.sessionId = null;
+    this.backend = null;
+    this.vncUrl = null;
+  }
+
+  async connect() {
+    return new Promise((resolve, reject) => {
+      const WebSocketImpl = typeof WebSocket !== 'undefined'
+        ? WebSocket
+        : null;
+
+      if (!WebSocketImpl) {
+        // Node.js — try dynamic import
+        import('ws').then(ws => {
+          this._ws = new ws.default(this._url);
+          this._wireEvents(resolve, reject);
+        }).catch(() => {
+          reject(new Error('WebSocket not available. Install "ws" package for Node.js: npm install ws'));
+        });
+        return;
+      }
+
+      this._ws = new WebSocketImpl(this._url);
+      this._wireEvents(resolve, reject);
+    });
+  }
+
+  _wireEvents(onConnected, onError) {
+    this._ws.onmessage = (event) => {
+      const data = typeof event.data === 'string' ? event.data : event.data.toString();
+      let msg;
+      try { msg = JSON.parse(data); } catch { return; }
+
+      if (msg.type === 'connected') {
+        this.sessionId = msg.sessionId;
+        this.backend = msg.backend;
+        this.vncUrl = msg.vncUrl || null;
+        if (this._verbose) console.log(`Browser Native: Session ${msg.sessionId} connected (${msg.backend})`);
+        onConnected(this);
+        return;
+      }
+
+      if (msg.type === 'fallback') {
+        this.backend = msg.to;
+        if (this._verbose) console.log(`Browser Native: Fallback ${msg.from} → ${msg.to} (${msg.reason})`);
+        if (this._eventHandlers.fallback) this._eventHandlers.fallback(msg);
+        return;
+      }
+
+      if (msg.type === 'closed') {
+        if (this._verbose) console.log(`Browser Native: Session closed (${msg.reason})`);
+        if (this._eventHandlers.closed) this._eventHandlers.closed(msg);
+        return;
+      }
+
+      // Match response to pending request by id
+      if (msg.id != null && this._pending.has(msg.id)) {
+        const { resolve, reject } = this._pending.get(msg.id);
+        this._pending.delete(msg.id);
+        if (msg.type === 'error') {
+          reject(new Error(msg.message));
+        } else {
+          if (msg.backend) this.backend = msg.backend;
+          resolve(msg.data);
+        }
+      }
+    };
+
+    this._ws.onerror = (err) => {
+      onError(new Error(err.message || 'WebSocket connection failed'));
+    };
+
+    this._ws.onclose = (event) => {
+      // Reject all pending requests
+      for (const [, { reject }] of this._pending) {
+        reject(new Error(`Session closed: ${event.reason || 'unknown'}`));
+      }
+      this._pending.clear();
+    };
+  }
+
+  _send(action, params = {}) {
+    return new Promise((resolve, reject) => {
+      if (!this._ws || this._ws.readyState !== 1) {
+        return reject(new Error('Session not connected'));
+      }
+      const id = this._nextId++;
+      this._pending.set(id, { resolve, reject });
+      this._ws.send(JSON.stringify({ id, action, ...params }));
+    });
+  }
+
+  on(event, handler) {
+    this._eventHandlers[event] = handler;
+    return this;
+  }
+
+  async goto(url) { return this._send('goto', { url }); }
+  async click(selector, options = {}) { return this._send('click', { selector, ...options }); }
+  async type(selector, text, options = {}) { return this._send('type', { selector, text, ...options }); }
+  async scroll(direction = 'down', amount = 500) { return this._send('scroll', { direction, amount }); }
+  async hover(selector) { return this._send('hover', { selector }); }
+  async select(selector, ...values) { return this._send('select', { selector, values }); }
+  async pressKey(key) { return this._send('pressKey', { key }); }
+  async goBack() { return this._send('goBack'); }
+  async goForward() { return this._send('goForward'); }
+  async screenshot(options = {}) { return this._send('screenshot', options); }
+  async getPageState(options = {}) { return this._send('getPageState', options); }
+  async extractContent() { return this._send('extractContent'); }
+  async waitFor(selector, timeout) { return this._send('waitFor', { selector, timeout }); }
+  async evaluate(fn) { return this._send('evaluate', { fn }); }
+  async getCookies() { return this._send('getCookies'); }
+  async setCookies(cookies) { return this._send('setCookies', { cookies }); }
+
+  // Coordinate-based actions (computer-use mode)
+  async mouseMove(x, y) { return this._send('mouseMove', { x, y }); }
+  async clickAt(x, y, button = 'left') { return this._send('clickAt', { x, y, button }); }
+  async doubleClickAt(x, y, button = 'left') { return this._send('doubleClickAt', { x, y, button }); }
+  async drag(startX, startY, endX, endY) { return this._send('drag', { startX, startY, endX, endY }); }
+  async scrollAt(x, y, direction, amount) { return this._send('scrollAt', { x, y, direction, amount }); }
+  async typeText(text) { return this._send('typeText', { text }); }
+  async getCursorPosition() { return this._send('getCursorPosition'); }
+  async getScreenSize() { return this._send('getScreenSize'); }
+
+  close() {
+    if (this._ws) {
+      this._ws.close();
+      this._ws = null;
+    }
+  }
+}
+
+export { BrowserSession };
+
 // Default export for CommonJS compatibility
 export default BrowserNativeClient;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@monostate/browsernative-client",
-  "version": "2.0.0",
+  "version": "2.2.0",
   "description": "Browser Native client SDK for web scraping and content extraction API",
   "type": "module",
   "main": "index.js",