spider-browser 0.1.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Spider Contributors
+
+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.

package/README.md

@@ -0,0 +1,354 @@
+# spider-browser (TypeScript)
+
+TypeScript client for [Spider's](https://spider.cloud) pre-warmed browser fleet. Full stealth browsers with smart retry, browser switching, and AI automation.
+
+## Installation
+
+```bash
+npm install spider-browser
+```
+
+## Quick Start
+
+```typescript
+import { SpiderBrowser } from 'spider-browser';
+
+const browser = new SpiderBrowser({
+  apiKey: process.env.SPIDER_API_KEY!,
+  browser: 'auto',  // auto-selects best browser
+});
+
+await browser.init();
+
+// Navigate
+await browser.page.goto('https://example.com');
+
+// Get page info
+const title = await browser.page.title();
+const url = await browser.page.url();
+const html = await browser.page.content();
+const screenshot = await browser.page.screenshot(); // base64 PNG
+
+// Interact
+await browser.page.click('a');
+await browser.page.fill('input[name=q]', 'spider browser');
+await browser.page.press('Enter');
+
+// Evaluate JavaScript
+const result = await browser.page.evaluate('document.title');
+
+await browser.close();
+```
+
+## Browser Types
+
+| Browser | Value | Description |
+|---|---|---|
+| Auto | `'auto'` | Server picks the best browser (default) |
+| Chrome | `'chrome'` | Full stealth Chrome with CDP |
+| Chrome-H | `'chrome-h'` | Chrome with enhanced headless rendering |
+| Chrome-New | `'chrome-new'` | Chrome headless new mode |
+| Firefox | `'firefox'` | Full stealth Firefox with BiDi |
+| Servo | `'servo'` | Servo engine for edge cases |
+| LightPanda | `'lightpanda'` | LightPanda for edge cases |
+
+```typescript
+// Auto-select best browser (default)
+new SpiderBrowser({ apiKey: 'sk-xxx', browser: 'auto' });
+
+// Specific browsers
+new SpiderBrowser({ apiKey: 'sk-xxx', browser: 'chrome' });
+new SpiderBrowser({ apiKey: 'sk-xxx', browser: 'chrome-h' });
+new SpiderBrowser({ apiKey: 'sk-xxx', browser: 'chrome-new' });
+new SpiderBrowser({ apiKey: 'sk-xxx', browser: 'firefox' });
+new SpiderBrowser({ apiKey: 'sk-xxx', browser: 'servo' });
+new SpiderBrowser({ apiKey: 'sk-xxx', browser: 'lightpanda' });
+```
+
+## Configuration
+
+```typescript
+const browser = new SpiderBrowser({
+  apiKey: 'sk-xxx',                    // Required: Spider API key
+  serverUrl: 'wss://browser.spider.cloud', // WebSocket server URL
+  browser: 'auto',                     // Browser type
+  url: 'https://example.com',          // Target URL hint for smart routing
+  captcha: 'solve',                    // 'off' | 'detect' | 'solve'
+  smartRetry: true,                    // Auto-retry & browser switching
+  maxRetries: 12,                      // Max retry attempts
+  stealth: 0,                          // Stealth level (0=auto, 1-3=explicit)
+  maxStealthLevels: 3,                 // Max stealth level for auto-escalation
+  connectTimeoutMs: 30000,             // WebSocket connect timeout
+  commandTimeoutMs: 30000,             // CDP/BiDi command timeout
+  retryTimeoutMs: 15000,               // Shorter timeout for retries
+  hedge: false,                        // Hedge session for parallel racing
+  record: false,                       // Enable screencast recording
+  logLevel: 'info',                    // 'debug' | 'info' | 'warn' | 'error' | 'none'
+  llm: { ... },                        // LLM config for AI methods
+});
+```
+
+## Page API
+
+### Navigation
+
+| Method | Description |
+|---|---|
+| `goto(url)` | Navigate to URL and wait for load |
+| `gotoFast(url)` | Navigate with 5s max wait (for SPAs) |
+| `goBack()` | Browser back |
+| `goForward()` | Browser forward |
+| `reload()` | Reload page |
+
+### Content
+
+| Method | Description |
+|---|---|
+| `content(waitMs?, minLength?)` | Full HTML with readiness checks |
+| `rawContent()` | Immediate HTML without waiting |
+| `contentWithEarlyReturn(maxWaitMs?, minLength?, pollMs?)` | Poll for content with early return (SPAs) |
+| `title()` | Page title |
+| `url()` | Current URL |
+| `screenshot()` | Base64 PNG |
+| `evaluate(expression)` | Execute JS and return result |
+
+### Click Actions
+
+| Method | Description |
+|---|---|
+| `click(selector)` | Click element |
+| `clickAt(x, y)` | Click at coordinates |
+| `clickAndHold(selector, holdMs?)` | Click and hold element (default 1000ms) |
+| `clickAndHoldAt(x, y, holdMs?)` | Click and hold at coordinates (default 1000ms) |
+| `dblclick(selector)` | Double-click element |
+| `rightClick(selector)` | Right-click element |
+| `clickAll(selector)` | Click all matching elements |
+
+```typescript
+// Long press for mobile gestures or drag triggers
+await browser.page.clickAndHold('#hold-button', 2000);
+
+// Long press at coordinates
+await browser.page.clickAndHoldAt(100, 200, 1500);
+```
+
+### Input
+
+| Method | Description |
+|---|---|
+| `fill(selector, value)` | Focus, clear, and type into element |
+| `type(value)` | Type into currently focused element |
+| `press(key)` | Press a named key (Enter, Tab, etc.) |
+| `clear(selector)` | Clear input field |
+| `select(selector, value)` | Select dropdown option |
+
+### Focus & Hover
+
+| Method | Description |
+|---|---|
+| `focus(selector)` | Focus element |
+| `blur(selector)` | Unfocus element |
+| `hover(selector)` | Hover over element |
+| `drag(fromSelector, toSelector)` | Drag between elements |
+
+### Scroll
+
+| Method | Description |
+|---|---|
+| `scrollY(pixels)` | Scroll vertically (positive = down) |
+| `scrollX(pixels)` | Scroll horizontally (positive = right) |
+| `scrollTo(selector)` | Scroll element into view |
+| `scrollToPoint(x, y)` | Scroll to absolute page coordinates |
+
+### Wait
+
+| Method | Description |
+|---|---|
+| `waitForSelector(selector, timeoutMs?)` | Wait for element (default 5s) |
+| `waitForNavigation(timeoutMs?)` | Wait for page load (default 5s) |
+| `waitForReady(timeoutMs?)` | Wait for readyState + DOM stability (default 10s) |
+| `waitForContent(minLength?, timeoutMs?)` | Wait for content to exceed length (default 8s) |
+| `waitForNetworkIdle(timeoutMs?)` | Wait for network idle + DOM stability (default 8s) |
+
+### DOM
+
+| Method | Description |
+|---|---|
+| `querySelector(selector)` | Get element outer HTML |
+| `querySelectorAll(selector)` | Get all matching elements |
+| `textContent(selector)` | Get element text content |
+
+### Viewport
+
+| Method | Description |
+|---|---|
+| `setViewport(w, h, dpr?, mobile?)` | Set viewport dimensions |
+
+## observe() — Element Discovery
+
+Discover interactive elements on any page without an LLM:
+
+```typescript
+await browser.page.goto('https://example.com');
+
+const elements = await browser.observe();
+for (const el of elements) {
+  console.log(`<${el.tag}> selector=${el.selector} text=${el.text}`);
+}
+
+// With LLM: rank elements by relevance
+const relevant = await browser.observe('Find the login button');
+```
+
+Each element includes: `selector`, `tag`, `type`, `text`, `ariaLabel`, `placeholder`, `href`, `value`, `rect`, and optionally `score` (with LLM).
+
+## AI Automation
+
+### Setup
+
+```typescript
+const browser = new SpiderBrowser({
+  apiKey: process.env.SPIDER_API_KEY!,
+  llm: {
+    provider: 'openai',       // or 'anthropic', 'openrouter'
+    model: 'gpt-4o',
+    apiKey: process.env.OPENAI_API_KEY!,
+  },
+});
+```
+
+### act() — Single Action
+
+```typescript
+await browser.page.goto('https://example.com');
+await browser.act('Click the "More information" link');
+```
+
+### extract() — Structured Data
+
+```typescript
+import { z } from 'zod';
+
+const data = await browser.extract('Get the page heading and all links');
+
+// With Zod schema validation
+const PageInfo = z.object({
+  title: z.string(),
+  linkCount: z.number(),
+});
+const info = await browser.extract('Get page title and number of links', {
+  schema: PageInfo,
+});
+```
+
+### agent() — Autonomous Multi-Step
+
+```typescript
+const agent = browser.agent({
+  maxRounds: 20,
+  stepDelayMs: 1500,
+});
+const result = await agent.execute('Find and click every link on this page');
+console.log(`Done: ${result.done}, Rounds: ${result.rounds}`);
+```
+
+## Smart Retry & Browser Switching
+
+Enabled by default. On failure, the engine classifies errors and automatically switches browsers:
+
+```typescript
+const browser = new SpiderBrowser({
+  apiKey: 'sk-xxx',
+  smartRetry: true,   // default
+  maxRetries: 3,
+});
+
+// Wrap any operation with retry
+const html = await browser.withRetry(async () => {
+  await browser.page.goto('https://target.com');
+  return browser.page.content();
+});
+
+browser.on('browser.switching', (e) => {
+  console.log(`Switching: ${e.from} -> ${e.to} (reason: ${e.reason})`);
+});
+```
+
+**Rotation order:** Chrome -> Chrome-H -> Firefox -> LightPanda
+
+## Session Recording
+
+Enable screencast recording to capture browser sessions:
+
+```typescript
+const browser = new SpiderBrowser({
+  apiKey: 'sk-xxx',
+  record: true,
+});
+
+browser.on('recording.started', (e) => console.log('Recording:', e.sessionId));
+browser.on('screencast.frame', (e) => console.log('Frame:', e.frameIndex));
+browser.on('recording.completed', (e) => {
+  console.log(`Done: ${e.frameCount} frames, ${e.durationMs}ms`);
+});
+```
+
+## Events
+
+```typescript
+// Connection
+browser.on('ws.open', () => { });
+browser.on('ws.close', (e) => { /* e.code, e.reason */ });
+browser.on('ws.error', (e) => { /* e.error */ });
+
+// Captcha
+browser.on('captcha.detected', (e) => { /* e.types, e.url */ });
+browser.on('captcha.solving', (e) => { /* e.types, e.round */ });
+browser.on('captcha.solved', () => { });
+browser.on('captcha.failed', (e) => { /* e.reason */ });
+
+// Browser switching
+browser.on('browser.switching', (e) => { /* e.from, e.to, e.reason */ });
+browser.on('browser.switched', (e) => { /* e.browser */ });
+browser.on('retry.attempt', (e) => { /* e.attempt, e.maxRetries, e.error */ });
+
+// Stealth
+browser.on('stealth.escalated', (e) => { /* e.from, e.to, e.reason */ });
+
+// Metering
+browser.on('metering', (e) => { /* e.credits, e.session_credits_used */ });
+
+// Page
+browser.on('page.navigated', (e) => { /* e.url */ });
+browser.on('page.loaded', (e) => { /* e.url */ });
+
+// Agent
+browser.on('agent.step', (e) => { /* e.round, e.label */ });
+browser.on('agent.done', (e) => { /* e.rounds, e.result */ });
+browser.on('agent.error', (e) => { /* e.error, e.round */ });
+
+// Recording
+browser.on('recording.started', (e) => { /* e.sessionId */ });
+browser.on('recording.completed', (e) => { /* e.sessionId, e.frameCount, e.durationMs */ });
+browser.on('screencast.frame', (e) => { /* e.data, e.timestamp, e.frameIndex */ });
+browser.on('screencast.rrwebEvents', (e) => { /* e.events */ });
+```
+
+## Supported LLM Providers
+
+| Provider | Config | Notes |
+|---|---|---|
+| OpenAI | `provider: 'openai'` | GPT-4o, GPT-4-turbo |
+| Anthropic | `provider: 'anthropic'` | Claude 4.5, Claude Opus |
+| OpenRouter | `provider: 'openrouter'` | Any model via OpenRouter |
+| Custom | `provider: 'openai', baseUrl: '...'` | Any OpenAI-compatible endpoint |
+
+## Requirements
+
+- Node.js 18+
+- `ws` >= 8.18.0
+- `zod` >= 3.23.0 (for schema validation in extract)
+
+## License
+
+MIT