@monostate/browsernative-client 1.2.1 → 2.2.0

package/README.md

@@ -1,461 +1,173 @@
 # @monostate/browsernative-client
 
-> **Official JavaScript/TypeScript client for Browser Native API**
+> JavaScript/TypeScript client for the Browser Native web scraping API
 
-[![npm version](https://badge.fury.io/js/%40monostate%2Fbrowsernative-client.svg)](https://badge.fury.io/js/%40monostate%2Fbrowsernative-client)
+[![npm](https://img.shields.io/npm/v/@monostate/browsernative-client.svg)](https://www.npmjs.com/package/@monostate/browsernative-client)
+[![License](https://img.shields.io/badge/License-MIT-yellow.svg)](https://github.com/monostate/browsernative-client/blob/main/LICENSE)
 [![TypeScript](https://img.shields.io/badge/TypeScript-Ready-blue.svg)](https://www.typescriptlang.org/)
-[![License](https://img.shields.io/badge/License-MIT-yellow.svg)](../../LICENSE)
 
-A lightweight, fast, and reliable client for the Browser Native web scraping and content extraction API. Works in browsers, Node.js, Deno, and edge environments.
+Zero-dependency client for scraping, screenshots, and AI analysis. Works in Node.js, browsers, and edge environments.
 
-## 🚀 Quick Start
-
-### Installation
+## Install
 
 ```bash
 npm install @monostate/browsernative-client
-# or
-yarn add @monostate/browsernative-client
-# or  
-pnpm add @monostate/browsernative-client
 ```
 
-### Get Your API Key
-
-1. Sign up at [bnca.monostate.ai](https://bnca.monostate.ai)
-2. Get your API key from the dashboard
-3. Start scraping!
+Get an API key at [bnca.monostate.ai](https://bnca.monostate.ai).
 
-### Basic Usage
+## Usage
 
 ```javascript
 import { BrowserNativeClient } from '@monostate/browsernative-client';
 
 const client = new BrowserNativeClient('your-api-key');
 
-// Scrape any website
+// Scrape
 const result = await client.scrape('https://example.com');
-console.log(result.data.title);
-console.log(result.data.content);
-
-// Quick screenshot capture (optimized for speed)
-const screenshot = await client.quickshot('https://example.com');
-console.log(screenshot.screenshot); // Base64 image
-```
-
-### Quick Functions
-
-```javascript
-import { quickScrape, quickScreenshot, quickShot, quickAnalyze } from '@monostate/browsernative-client';
-
-// One-line scraping
-const content = await quickScrape('https://example.com', 'your-api-key');
 
-// Take a screenshot (with content extraction)
-const screenshot = await quickScreenshot('https://example.com', 'your-api-key');
-
-// Quick screenshot only (fastest option)
-const quickScreenshot = await quickShot('https://example.com', 'your-api-key');
-
-// AI-powered analysis
-const analysis = await quickAnalyze(
-  'https://news.ycombinator.com', 
-  'What are the top 3 trending topics?',
-  'your-api-key'
-);
-```
+// Force a specific scraping method
+const result = await client.scrape('https://example.com', { method: 'lightpanda' });
 
-## 📋 API Reference
+// Screenshot
+const screenshot = await client.screenshot('https://example.com');
 
-### Client Initialization
+// Quick screenshot (faster, no content extraction)
+const quick = await client.quickshot('https://example.com');
 
-```javascript
-const client = new BrowserNativeClient(apiKey, options);
+// AI Q&A
+const analysis = await client.analyze('https://example.com', 'What is this site about?');
 ```
 
-**Options:**
-- `baseUrl` (string): API base URL (default: `https://bnca-api.fly.dev`)
-- `timeout` (number): Request timeout in ms (default: `30000`)
-- `retries` (number): Number of retry attempts (default: `2`)
-- `verbose` (boolean): Enable logging (default: `false`)
-
-### Methods
-
-#### `client.scrape(url, options)`
-
-Extract structured content from any webpage.
+### Convenience functions
 
 ```javascript
-const result = await client.scrape('https://example.com', {
-  includeScreenshot: true,
-  waitForSelector: '.main-content',
-  extractMetadata: true,
-  userAgent: 'Custom Bot 1.0'
-});
-
-console.log(result.data.title);      // Page title
-console.log(result.data.content);   // Main content
-console.log(result.data.metadata);  // Meta tags, etc.
-console.log(result.screenshot);     // Base64 image (if requested)
-console.log(result.method);         // Scraping method used
-```
-
-**Options:**
-- `includeScreenshot` (boolean): Include page screenshot
-- `waitForSelector` (string): CSS selector to wait for
-- `userAgent` (string): Custom user agent
-- `viewport` (object): `{ width: number, height: number }`
-- `extractMetadata` (boolean): Extract meta tags and structured data
-
-#### `client.screenshot(url, options)`
-
-Take high-quality screenshots of webpages with content extraction.
+import { quickScrape, quickScreenshot, quickShot, quickAnalyze, bulkScrape } from '@monostate/browsernative-client';
 
-```javascript
-const result = await client.screenshot('https://example.com', {
-  fullPage: true,
-  format: 'png',
-  viewport: { width: 1920, height: 1080 }
-});
-
-// Use the base64 image
-const img = `data:image/png;base64,${result.screenshot}`;
+const content = await quickScrape('https://example.com', 'your-api-key');
+const shot = await quickShot('https://example.com', 'your-api-key');
+const answer = await quickAnalyze('https://example.com', 'What is this?', 'your-api-key');
 ```
 
-**Options:**
-- `fullPage` (boolean): Capture full page scroll
-- `format` (string): `'png'`, `'jpeg'`, or `'webp'`
-- `quality` (number): JPEG quality (1-100)
-- All scrape options are also available
-
-#### `client.quickshot(url, options)`
-
-Optimized screenshot capture for maximum speed (no content extraction).
+### Bulk scraping
 
 ```javascript
-const result = await client.quickshot('https://example.com');
-
-// Returns screenshot immediately
-if (result.success && result.screenshot) {
-  const img = result.screenshot; // Already includes data:image/png;base64,
-}
-```
-
-**Benefits:**
-- 2-3x faster than regular screenshot
-- Optimized for visual capture only
-- Perfect for thumbnails and previews
-
-#### `client.analyze(url, question, options)`
-
-AI-powered content analysis and question answering.
-
-```javascript
-const result = await client.analyze(
-  'https://techcrunch.com',
-  'What are the latest AI developments mentioned?',
-  {
-    language: 'en',
-    style: 'detailed'
-  }
-);
-
-console.log(result.analysis.answer);     // AI response
-console.log(result.analysis.confidence); // Confidence score
-```
-
-**Options:**
-- `language` (string): Response language (`'en'`, `'pt'`, `'es'`, `'fr'`, `'de'`, `'auto'`)
-- `style` (string): Response style (`'concise'`, `'detailed'`, `'technical'`)
-- All scrape options are also available
-
-#### `client.getUsage(days)`
-
-Get your account usage statistics.
+const urls = ['https://site1.com', 'https://site2.com', 'https://site3.com'];
 
-```javascript
-const usage = await client.getUsage(30); // Last 30 days
+const { results, stats } = await client.bulkScrape(urls, {
+  concurrency: 5,
+  continueOnError: true,
+  progressCallback: (p) => console.log(`${p.percentage.toFixed(1)}%`),
+});
 
-console.log(usage.data.monthlyTotal.totalRequests);
-console.log(usage.data.currentUsage);
-console.log(usage.data.usageLimit);
+console.log(`${stats.successful}/${stats.total} succeeded in ${stats.totalTime}ms`);
 ```
 
-#### `client.healthCheck()`
+## API Reference
 
-Check API status and your account health.
+### Client options
 
 ```javascript
-const health = await client.healthCheck();
-
-console.log(health.data.status);   // 'healthy', 'degraded', or 'unhealthy'
-console.log(health.data.services); // Service status breakdown
+const client = new BrowserNativeClient(apiKey, {
+  baseUrl: 'https://bnca-api.fly.dev', // API endpoint
+  timeout: 30000,                       // Request timeout (ms)
+  retries: 2,                           // Retry attempts
+  verbose: false,                       // Debug logging
+});
 ```
 
-## 🌐 Framework Integration
-
-### React Hook
-
-```javascript
-// hooks/useBrowserNative.js
-import { useState } from 'react';
-import { BrowserNativeClient } from '@monostate/browsernative-client';
+### Methods
 
-export function useBrowserNative(apiKey) {
-  const [loading, setLoading] = useState(false);
-  const [data, setData] = useState(null);
-  const [error, setError] = useState(null);
-
-  const client = new BrowserNativeClient(apiKey);
-
-  const scrape = async (url, options = {}) => {
-    setLoading(true);
-    setError(null);
-    
-    try {
-      const result = await client.scrape(url, options);
-      if (result.success) {
-        setData(result.data);
-      } else {
-        setError(result.error);
-      }
-    } catch (err) {
-      setError(err.message);
-    } finally {
-      setLoading(false);
-    }
-  };
-
-  return { scrape, loading, data, error };
+| Method | Description |
+|--------|-------------|
+| `scrape(url, opts?)` | Extract structured content |
+| `screenshot(url, opts?)` | Screenshot with content extraction |
+| `quickshot(url, opts?)` | Fast screenshot only |
+| `analyze(url, question, opts?)` | AI-powered Q&A |
+| `bulkScrape(urls, opts?)` | Scrape multiple URLs concurrently |
+| `getUsage(days?)` | Account usage statistics |
+| `healthCheck()` | API health status |
+
+### Scrape options
+
+```javascript
+{
+  method: 'auto',            // 'auto' | 'direct' | 'lightpanda' | 'puppeteer'
+  includeScreenshot: false,
+  waitForSelector: '.content',
+  userAgent: 'Custom Bot',
+  viewport: { width: 1920, height: 1080 },
+  extractMetadata: true,
 }
 ```
 
-### Vue Composable
+### Response shape
 
 ```javascript
-// composables/useBrowserNative.js
-import { ref } from 'vue';
-import { BrowserNativeClient } from '@monostate/browsernative-client';
-
-export function useBrowserNative(apiKey) {
-  const loading = ref(false);
-  const data = ref(null);
-  const error = ref(null);
-
-  const client = new BrowserNativeClient(apiKey);
-
-  const scrape = async (url, options = {}) => {
-    loading.value = true;
-    error.value = null;
-    
-    try {
-      const result = await client.scrape(url, options);
-      if (result.success) {
-        data.value = result.data;
-      } else {
-        error.value = result.error;
-      }
-    } catch (err) {
-      error.value = err.message;
-    } finally {
-      loading.value = false;
-    }
-  };
-
-  return { scrape, loading, data, error };
+{
+  success: true,
+  data: { title, content, metadata, ... },
+  responseTime: 1234,
+  attempt: 1,
 }
 ```
 
-### Next.js API Route
+### Browser sessions
 
-```javascript
-// pages/api/scrape.js
-import { BrowserNativeClient } from '@monostate/browsernative-client';
-
-const client = new BrowserNativeClient(process.env.BROWSER_NATIVE_API_KEY);
-
-export default async function handler(req, res) {
-  if (req.method !== 'POST') {
-    return res.status(405).json({ error: 'Method not allowed' });
-  }
-
-  try {
-    const { url, question } = req.body;
-    
-    let result;
-    if (question) {
-      result = await client.analyze(url, question);
-    } else {
-      result = await client.scrape(url);
-    }
-    
-    res.status(200).json(result);
-  } catch (error) {
-    res.status(500).json({ error: error.message });
-  }
-}
-```
-
-### Express.js
+Persistent browser sessions with real-time control over WebSocket:
 
 ```javascript
-import express from 'express';
-import { BrowserNativeClient } from '@monostate/browsernative-client';
-
-const app = express();
-const client = new BrowserNativeClient(process.env.BROWSER_NATIVE_API_KEY);
-
-app.post('/scrape', async (req, res) => {
-  try {
-    const { url } = req.body;
-    const result = await client.scrape(url);
-    res.json(result);
-  } catch (error) {
-    res.status(500).json({ error: error.message });
-  }
-});
-```
-
-## 🔒 Environment Variables
-
-Create a `.env` file:
-
-```bash
-BROWSER_NATIVE_API_KEY=your_api_key_here
-```
+const session = await client.createSession({ mode: 'auto' });
 
-Then use in your code:
+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();
 
-```javascript
-const client = new BrowserNativeClient(process.env.BROWSER_NATIVE_API_KEY);
-```
+// Listen for backend fallback events
+session.on('fallback', (e) => console.log(`${e.from} -> ${e.to}: ${e.reason}`));
 
-## 📱 Browser Usage
-
-You can use this client directly in browsers, but be careful with API keys:
-
-```html
-<!DOCTYPE html>
-<html>
-<head>
-    <title>Browser Native Demo</title>
-</head>
-<body>
-    <script type="module">
-        import { BrowserNativeClient } from 'https://cdn.skypack.dev/@monostate/browsernative-client';
-        
-        // ⚠️ Never expose your API key in client-side code!
-        // Use a proxy server or environment variables
-        const client = new BrowserNativeClient(await getApiKeyFromServer());
-        
-        const result = await client.scrape('https://example.com');
-        console.log(result);
-    </script>
-</body>
-</html>
+session.close();
 ```
 
-**Security Note**: Never expose your API key in client-side code. Use a backend proxy or server-side rendering.
+Modes: `auto` (LightPanda + Chrome fallback), `headless`, `visual`, `computer-use`.
 
-## ⚡ Performance Tips
+#### Computer use mode
 
-1. **Reuse Client Instances**: Create one client instance and reuse it
-2. **Enable Retries**: The client automatically retries failed requests
-3. **Use Appropriate Timeouts**: Adjust timeout based on your use case
-4. **Batch Requests**: Process multiple URLs concurrently
+For AI agents that control the browser by pixel coordinates:
 
 ```javascript
-const client = new BrowserNativeClient(apiKey, {
-  timeout: 45000,  // Longer timeout for complex sites
-  retries: 3,      // More retries for reliability
-  verbose: true    // Enable logging for debugging
-});
+const session = await client.createSession({ mode: 'computer-use', screenWidth: 1280, screenHeight: 800 });
 
-// Concurrent scraping
-const urls = ['https://site1.com', 'https://site2.com', 'https://site3.com'];
-const results = await Promise.all(
-  urls.map(url => client.scrape(url))
-);
-```
+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();
 
-## 🔧 Error Handling
+// VNC streaming URL
+console.log(session.vncUrl);
 
-```javascript
-try {
-  const result = await client.scrape(url);
-  
-  if (result.success) {
-    console.log('Success:', result.data);
-  } else {
-    console.error('Scraping failed:', result.error);
-  }
-} catch (error) {
-  console.error('Request failed:', error.message);
-}
+session.close();
 ```
 
-Common error scenarios:
-- **Invalid API Key**: Check your API key and account status
-- **Rate Limited**: Upgrade your plan or reduce request frequency
-- **Timeout**: Increase timeout or try a simpler extraction method
-- **Invalid URL**: Ensure the URL is accessible and properly formatted
+## TypeScript
 
-## 🚀 TypeScript Support
-
-Full TypeScript support with comprehensive type definitions:
+Full type definitions included.
 
 ```typescript
-import { BrowserNativeClient, ScrapeResult, AnalyzeResult } from '@monostate/browsernative-client';
-
-const client: BrowserNativeClient = new BrowserNativeClient('your-api-key');
-
-const result: ScrapeResult = await client.scrape('https://example.com');
-const analysis: AnalyzeResult = await client.analyze(url, question);
+import { BrowserNativeClient, ScrapeResult, BulkScrapeResult } from '@monostate/browsernative-client';
 ```
 
-## 📊 Rate Limits
-
-| Plan | Requests/Month | Rate Limit |
-|------|----------------|------------|
-| **Free** | 1,000 | 10/minute |
-| **Starter** | 10,000 | 60/minute |
-| **Pro** | 100,000 | 300/minute |
-| **Enterprise** | Unlimited | Custom |
-
-## 📋 Changelog
-
-### v1.2.0 (Latest)
-- 🔧 **Timeout Improvements**: Enhanced timeout handling and request reliability
-- 📝 **Documentation Updates**: Comprehensive API documentation and examples
-- 🏷️ **Package Naming**: Proper package name consistency across all imports
-- ⚡ **Performance Optimizations**: Better error handling and response processing
-- 🌐 **Framework Integration**: Improved React, Vue, and Next.js examples
-
-### v1.1.2
-- Bug fixes and stability improvements
-- Enhanced error handling
-
-### v1.1.1
-- Initial TypeScript support
-- Basic API client functionality
-
-## 🤝 Support
-
-- 📧 **Email**: [support@bnca.monostate.ai](mailto:support@bnca.monostate.ai)
-- 📖 **Documentation**: [bnca.monostate.ai/docs](https://bnca.monostate.ai/docs)
-- 🐛 **Issues**: [GitHub Issues](https://github.com/browsernative/client-sdk/issues)
-- 💬 **Discord**: [Join our community](https://discord.gg/browsernative)
-
-## 📄 License
-
-MIT License - see [LICENSE](../../LICENSE) file for details.
-
----
-
-<div align="center">
+## Changelog
 
-**Built with ❤️ for developers who value speed and reliability**
+See [CHANGELOG.md](./CHANGELOG.md).
 
-[🌐 Website](https://bnca.monostate.ai) | [📖 Docs](https://bnca.monostate.ai/docs) | [🚀 Get API Key](https://bnca.monostate.ai/signup)
+## License
 
-</div>
+MIT

package/index.d.ts

@@ -14,6 +14,8 @@ export interface ClientOptions {
 }
 
 export interface ScrapeOptions {
+  /** Force a specific scraping method */
+  method?: 'auto' | 'direct' | 'lightpanda' | 'puppeteer';
   /** Include screenshot in the response */
   includeScreenshot?: boolean;
   /** Wait for specific selector before extracting content */
@@ -29,6 +31,26 @@ export interface ScrapeOptions {
   extractMetadata?: boolean;
 }
 
+export interface BulkScrapeOptions extends ScrapeOptions {
+  /** Number of concurrent requests (default: 5) */
+  concurrency?: number;
+  /** Continue on error (default: true) */
+  continueOnError?: boolean;
+  /** Progress callback */
+  progressCallback?: (progress: { processed: number; total: number; percentage: number }) => void;
+}
+
+export interface BulkScrapeResult {
+  results: Array<ScrapeResult & { url: string }>;
+  stats: {
+    total: number;
+    successful: number;
+    failed: number;
+    totalTime: number;
+    averageTime: number;
+  };
+}
+
 export interface ScreenshotOptions extends ScrapeOptions {
   /** Force full page screenshot */
   fullPage?: boolean;
@@ -74,14 +96,33 @@ export interface ScrapeResult {
   attempt?: number;
 }
 
-export interface AnalyzeResult extends ScrapeResult {
-  /** AI analysis response */
-  analysis?: {
-    answer: string;
-    confidence: number;
-    processingTime: number;
-    language: string;
+export interface AnalyzeResult {
+  /** Whether the request was successful */
+  success: boolean;
+  /** API response data */
+  data?: {
+    /** Whether the inner request was successful */
+    success?: boolean;
+    /** The answer from AI analysis */
+    answer?: string;
+    /** Metadata about the request */
+    metadata?: {
+      url: string;
+      question: string;
+      method: string;
+      timestamp: string;
+      performance: {
+        totalTime: number;
+      };
+      screenshot?: string | null;
+    };
   };
+  /** Error message (if failed) */
+  error?: string;
+  /** Response time in milliseconds */
+  responseTime: number;
+  /** Attempt number that succeeded */
+  attempt?: number;
 }
 
 export interface UsageResult {
@@ -127,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
  */
@@ -153,11 +302,21 @@ export declare class BrowserNativeClient {
    */
   analyze(url: string, question: string, options?: AnalyzeOptions): Promise<AnalyzeResult>;
 
+  /**
+   * Scrape multiple URLs with concurrency control
+   */
+  bulkScrape(urls: string[], options?: BulkScrapeOptions): Promise<BulkScrapeResult>;
+
   /**
    * Get account usage statistics
    */
   getUsage(days?: number): Promise<UsageResult>;
 
+  /**
+   * Create a persistent browser session via WebSocket
+   */
+  createSession(options?: SessionOptions): Promise<BrowserSession>;
+
   /**
    * Check API health and your account status
    */
@@ -201,4 +360,13 @@ export declare function quickShot(
   options?: ScreenshotOptions
 ): Promise<ScrapeResult>;
 
+/**
+ * Convenience function for bulk scraping multiple URLs
+ */
+export declare function bulkScrape(
+  urls: string[],
+  apiKey: string,
+  options?: BulkScrapeOptions
+): Promise<BulkScrapeResult>;
+
 export default BrowserNativeClient;

package/index.js

@@ -83,6 +83,57 @@ export class BrowserNativeClient {
     return this._makeRequest('/aireply', payload);
   }
 
+  /**
+   * Scrape multiple URLs with concurrency control
+   * @param {string[]} urls - URLs to scrape
+   * @param {object} options - Bulk scraping options
+   * @returns {Promise<object>} Aggregated results
+   */
+  async bulkScrape(urls, options = {}) {
+    const concurrency = options.concurrency || 5;
+    const continueOnError = options.continueOnError !== false;
+    const results = [];
+    const startTime = Date.now();
+    let processed = 0;
+
+    const queue = [...urls];
+    const workers = Array.from({ length: Math.min(concurrency, urls.length) }, async () => {
+      while (queue.length > 0) {
+        const url = queue.shift();
+        if (!url) break;
+        try {
+          const result = await this.scrape(url, options);
+          results.push({ url, ...result });
+        } catch (error) {
+          results.push({ url, success: false, error: error.message });
+          if (!continueOnError) throw error;
+        }
+        processed++;
+        if (options.progressCallback) {
+          options.progressCallback({
+            processed,
+            total: urls.length,
+            percentage: (processed / urls.length) * 100,
+          });
+        }
+      }
+    });
+
+    await Promise.all(workers);
+
+    const successful = results.filter(r => r.success).length;
+    return {
+      results,
+      stats: {
+        total: urls.length,
+        successful,
+        failed: urls.length - successful,
+        totalTime: Date.now() - startTime,
+        averageTime: Math.round((Date.now() - startTime) / urls.length),
+      },
+    };
+  }
+
   /**
    * Get account usage statistics
    * @param {number} days - Number of days to fetch (max 30)
@@ -92,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
@@ -121,7 +196,7 @@ export class BrowserNativeClient {
           headers: {
             'x-api-key': this.apiKey,
             'Content-Type': 'application/json',
-            'User-Agent': 'Browser Native Client SDK/1.2.1'
+            'User-Agent': 'Browser Native Client SDK/2.0.0'
           }
         };
 
@@ -231,5 +306,161 @@ export async function quickShot(url, apiKey, options = {}) {
   return client.quickshot(url, options);
 }
 
+/**
+ * Convenience function for bulk scraping multiple URLs
+ * @param {string[]} urls - URLs to scrape
+ * @param {string} apiKey - Your API key
+ * @param {object} options - Bulk options (concurrency, continueOnError, progressCallback)
+ * @returns {Promise<object>} Aggregated results
+ */
+export async function bulkScrape(urls, apiKey, options = {}) {
+  const client = new BrowserNativeClient(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": "1.2.1",
+  "version": "2.2.0",
   "description": "Browser Native client SDK for web scraping and content extraction API",
   "type": "module",
   "main": "index.js",
@@ -33,7 +33,7 @@
   "license": "MIT",
   "dependencies": {},
   "engines": {
-    "node": ">=16.0.0"
+    "node": ">=18.0.0"
   },
   "repository": {
     "type": "git",

package/LICENSE

@@ -1,21 +0,0 @@
-MIT License
-
-Copyright (c) 2025 BNCA Team
-
-Permission is hereby granted, free of charge, to any person obtaining a copy
-of this software and associated documentation files (the "Software"), to deal
-in the Software without restriction, including without limitation the rights
-to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
-copies of the Software, and to permit persons to whom the Software is
-furnished to do so, subject to the following conditions:
-
-The above copyright notice and this permission notice shall be included in all
-copies or substantial portions of the Software.
-
-THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
-IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
-FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
-AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
-LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
-OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
-SOFTWARE.