@olib-ai/owl-browser-sdk 1.2.1 → 1.2.3

package/README.md

@@ -267,6 +267,126 @@ await page.type('640x400', 'text here');  // Type at position
 await page.highlight('login button');
 ```
 
+#### Advanced Interactions
+
+```typescript
+// Hover over elements (for tooltips, dropdowns)
+await page.hover('menu item');
+await page.hover('.dropdown-trigger', 500);  // hover for 500ms
+
+// Double-click
+await page.doubleClick('editable cell');
+
+// Right-click (context menu)
+await page.rightClick('file item');
+
+// Clear input before typing
+await page.clearInput('search box');
+await page.type('search box', 'new search');
+
+// Focus and blur (trigger validation)
+await page.focus('email input');
+await page.blur('email input');
+
+// Select all text in input
+await page.selectAll('text area');
+
+// Keyboard combinations
+await page.keyboardCombo('a', ['ctrl']);       // Ctrl+A (select all)
+await page.keyboardCombo('c', ['ctrl']);       // Ctrl+C (copy)
+await page.keyboardCombo('v', ['ctrl']);       // Ctrl+V (paste)
+await page.keyboardCombo('z', ['ctrl']);       // Ctrl+Z (undo)
+await page.keyboardCombo('s', ['ctrl', 'shift']); // Ctrl+Shift+S
+
+// Human-like mouse movement (anti-bot detection)
+await page.mouseMove(100, 100, 500, 300);  // Move from (100,100) to (500,300)
+await page.mouseMove(100, 100, 500, 300, 50);  // With 50 intermediate steps
+await page.mouseMove(100, 100, 500, 300, 0, [  // With stop points
+  [200, 150],
+  [350, 250]
+]);
+```
+
+#### Element State Checks
+
+```typescript
+// Check visibility
+if (await page.isVisible('error message')) {
+  console.log('Error displayed');
+}
+
+// Check if enabled/disabled
+if (await page.isEnabled('submit button')) {
+  await page.click('submit button');
+}
+
+// Check checkbox/radio state
+const isChecked = await page.isChecked('remember me checkbox');
+
+// Get element attribute
+const href = await page.getAttribute('a.link', 'href');
+const placeholder = await page.getAttribute('input', 'placeholder');
+
+// Get element position and size
+const box = await page.getBoundingBox('header');
+console.log(`Position: ${box.x}, ${box.y}`);
+console.log(`Size: ${box.width} x ${box.height}`);
+```
+
+#### File Upload
+
+```typescript
+// Upload single file
+await page.uploadFile('input[type="file"]', ['/path/to/document.pdf']);
+
+// Upload multiple files
+await page.uploadFile('file input', [
+  '/path/to/image1.jpg',
+  '/path/to/image2.jpg'
+]);
+```
+
+#### Frame/Iframe Handling
+
+```typescript
+// List all frames on the page
+const frames = await page.listFrames();
+for (const frame of frames) {
+  console.log(`Frame: ${frame.name || frame.id} - ${frame.url}`);
+}
+
+// Switch to iframe by selector
+await page.switchToFrame('#payment-iframe');
+
+// Or by frame name/id
+await page.switchToFrame('checkout-frame');
+
+// Interact with elements inside iframe
+await page.type('card number input', '4111111111111111');
+await page.click('submit payment');
+
+// Switch back to main frame
+await page.switchToMainFrame();
+```
+
+#### JavaScript Evaluation
+
+```typescript
+// Execute JavaScript in page context
+const title = await page.evaluate<string>('document.title');
+
+// With arguments
+const text = await page.evaluate<string>(
+  '(selector) => document.querySelector(selector)?.textContent',
+  ['h1']
+);
+
+// Return complex objects
+const metrics = await page.evaluate<{width: number, height: number}>(
+  '() => ({ width: window.innerWidth, height: window.innerHeight })'
+);
+```
+
 #### Content Extraction
 
 ```typescript
@@ -573,6 +693,116 @@ const viewport: Viewport = await page.getViewport();
 | Built-in Ad Blocking | ✅ 72 domains | ❌ Manual setup |
 | Maintenance Overhead | ✅ Low (AI handles changes) | ⚠️ High (selectors break) |
 
+### Network Interception
+
+Block, mock, or redirect network requests:
+
+```typescript
+// Block ads
+const ruleId = await page.addNetworkRule({
+  urlPattern: 'https://ads.example.com/*',
+  action: 'block'
+});
+
+// Mock API response
+await page.addNetworkRule({
+  urlPattern: 'https://api.example.com/data',
+  action: 'mock',
+  mockBody: '{"status": "ok"}',
+  mockStatus: 200,
+  mockContentType: 'application/json'
+});
+
+// Redirect requests
+await page.addNetworkRule({
+  urlPattern: 'https://old-api.example.com/*',
+  action: 'redirect',
+  redirectUrl: 'https://new-api.example.com/'
+});
+
+// Enable interception
+await page.setNetworkInterception(true);
+
+// Get network log
+const log = await page.getNetworkLog();
+
+// Remove rule
+await page.removeNetworkRule(ruleId);
+```
+
+### File Downloads
+
+Handle file downloads:
+
+```typescript
+// Set download directory
+await page.setDownloadPath('/tmp/downloads');
+
+// Click a download link
+await page.click('a[download]');
+
+// Wait for download to complete
+const download = await page.waitForDownload();
+console.log(`Downloaded: ${download.filename} to ${download.path}`);
+
+// Or get all downloads
+const downloads = await page.getDownloads();
+
+// Cancel a download
+await page.cancelDownload(download.id);
+```
+
+### Dialog Handling
+
+Handle JavaScript dialogs (alert, confirm, prompt):
+
+```typescript
+// Auto-accept alerts
+await page.setDialogAction('alert', 'accept');
+
+// Auto-respond to prompts
+await page.setDialogAction('prompt', 'accept_with_text', 'My answer');
+
+// Dismiss confirms
+await page.setDialogAction('confirm', 'dismiss');
+
+// Or handle manually
+const dialog = await page.waitForDialog();
+console.log(`Dialog message: ${dialog.message}`);
+await page.handleDialog(dialog.id, true, 'response text');
+```
+
+### Multi-Tab Management
+
+Work with multiple tabs:
+
+```typescript
+// Create new tab
+const tab = await page.newTab('https://google.com');
+console.log(`Tab ID: ${tab.tabId}`);
+
+// List all tabs
+const tabs = await page.getTabs();
+
+// Switch to a tab
+await page.switchTab(tabs[0].tabId);
+
+// Get active tab
+const active = await page.getActiveTab();
+
+// Get tab count
+const count = await page.getTabCount();
+
+// Close a tab
+await page.closeTab(tab.tabId);
+
+// Configure popup handling
+await page.setPopupPolicy('block');  // 'allow', 'block', 'new_tab', 'background'
+
+// Get blocked popups
+const blocked = await page.getBlockedPopups();
+```
+
 ## Advanced Features
 
 ### Semantic Element Matching
@@ -622,7 +852,12 @@ import {
   RateLimitError,
   IPBlockedError,
   LicenseError,
-  BrowserInitializationError
+  BrowserInitializationError,
+  ActionError,
+  ActionStatus,
+  ElementNotFoundError,
+  NavigationError,
+  FirewallError
 } from '@olib-ai/owl-browser-sdk';
 
 async function withErrorHandling() {
@@ -641,9 +876,34 @@ async function withErrorHandling() {
     await page.goto('https://example.com');
 
     // Your automation code...
+    await page.click('non-existent button');
 
   } catch (error) {
-    if (error instanceof AuthenticationError) {
+    if (error instanceof ElementNotFoundError) {
+      // Element was not found on the page
+      console.error('Element not found:', error.message);
+    } else if (error instanceof NavigationError) {
+      // Navigation failed (timeout, page load error, etc.)
+      console.error('Navigation failed:', error.message);
+    } else if (error instanceof ActionError) {
+      // Generic action error with detailed status
+      console.error('Action failed:', error.message);
+      console.error('Status:', error.status);
+      console.error('Selector:', error.selector);
+      // Check specific error types
+      if (error.isElementNotFound()) {
+        console.error('Could not find element');
+      } else if (error.isNavigationError()) {
+        console.error('Navigation issue');
+      } else if (error.isTimeout()) {
+        console.error('Operation timed out');
+      }
+    } else if (error instanceof FirewallError) {
+      // Web firewall/bot protection detected
+      console.error('Firewall detected:', error.provider);
+      console.error('Challenge type:', error.challengeType);
+      console.error('URL:', error.url);
+    } else if (error instanceof AuthenticationError) {
       // 401 - Invalid or expired token
       console.error('Auth failed:', error.message);
       console.error('Reason:', error.reason);
@@ -665,17 +925,92 @@ async function withErrorHandling() {
 }
 ```
 
+### Action Result Validation
+
+The browser returns structured `ActionResult` responses for browser actions, providing detailed information about success or failure:
+
+```typescript
+import {
+  ActionStatus,
+  ActionResult,
+  ActionError,
+  isActionResult,
+  throwIfActionFailed
+} from '@olib-ai/owl-browser-sdk';
+
+// ActionStatus enum values
+ActionStatus.OK                    // Action succeeded
+ActionStatus.ELEMENT_NOT_FOUND     // Element not found on page
+ActionStatus.ELEMENT_NOT_VISIBLE   // Element exists but not visible
+ActionStatus.ELEMENT_NOT_INTERACTABLE // Element not interactable
+ActionStatus.NAVIGATION_FAILED     // Navigation failed
+ActionStatus.NAVIGATION_TIMEOUT    // Navigation timed out
+ActionStatus.PAGE_LOAD_ERROR       // Page failed to load
+ActionStatus.FIREWALL_DETECTED     // Web firewall/bot protection detected
+ActionStatus.CAPTCHA_DETECTED      // CAPTCHA challenge detected
+ActionStatus.CLICK_FAILED          // Click action failed
+ActionStatus.TYPE_FAILED           // Type action failed
+ActionStatus.CONTEXT_NOT_FOUND     // Browser context not found
+ActionStatus.INVALID_SELECTOR      // Invalid selector provided
+ActionStatus.TIMEOUT               // Operation timed out
+
+// ActionResult interface
+interface ActionResult {
+  success: boolean;
+  status: ActionStatus | string;
+  message: string;
+  selector?: string;      // The selector that failed (for element errors)
+  url?: string;           // URL involved (for navigation errors)
+  http_status?: number;   // HTTP status code (for navigation)
+  error_code?: string;    // Browser error code
+  element_count?: number; // Elements found (for multiple_elements error)
+}
+
+// Helper functions
+if (isActionResult(result)) {
+  if (!result.success) {
+    throwIfActionFailed(result); // Throws appropriate exception
+  }
+}
+```
+
 ### Exception Types
 
 | Exception | HTTP Code | Description |
 |-----------|-----------|-------------|
+| `ActionError` | - | Browser action failed with status code and details |
+| `ElementNotFoundError` | - | Element not found on page |
+| `NavigationError` | - | Navigation failed (timeout, load error) |
+| `FirewallError` | - | Web firewall/bot protection detected (Cloudflare, Akamai, etc.) |
+| `ContextError` | - | Browser context not found |
 | `AuthenticationError` | 401 | Invalid/expired token or JWT signature mismatch |
 | `RateLimitError` | 429 | Too many requests, includes `retryAfter` in seconds |
 | `IPBlockedError` | 403 | Client IP not in whitelist |
 | `LicenseError` | 503 | Browser license validation failed |
 | `BrowserInitializationError` | - | Failed to start/connect to browser |
 | `CommandTimeoutError` | - | Operation timed out |
-| `ElementNotFoundError` | - | Element not found on page |
+
+### FirewallError Properties
+
+| Property | Type | Description |
+|----------|------|-------------|
+| `url` | `string` | The URL where the firewall was detected |
+| `provider` | `string` | Firewall provider (Cloudflare, Akamai, Imperva, etc.) |
+| `challengeType` | `string?` | Type of challenge (JS Challenge, CAPTCHA, etc.) |
+
+The browser automatically detects web firewalls including Cloudflare, Akamai, Imperva, PerimeterX, DataDome, and AWS WAF.
+
+### ActionError Properties
+
+| Property | Type | Description |
+|----------|------|-------------|
+| `status` | `ActionStatus` | Status code (e.g., `element_not_found`) |
+| `message` | `string` | Human-readable error message |
+| `selector` | `string?` | The selector that failed |
+| `url` | `string?` | URL involved in navigation errors |
+| `httpStatus` | `number?` | HTTP status code |
+| `errorCode` | `string?` | Browser error code |
+| `elementCount` | `number?` | Number of elements found |
 
 ## Performance Tips
 

package/dist/connection.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"connection.d.ts","sourceRoot":"","sources":["../src/connection.ts"],"names":[],"mappings":"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"}
+{"version":3,"file":"connection.d.ts","sourceRoot":"","sources":["../src/connection.ts"],"names":[],"mappings":"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"}

package/dist/connection.js

@@ -350,7 +350,31 @@ class LocalConnection {
                     pending.reject(new Error(response.error));
                 }
                 else {
-                    pending.resolve(response.result);
+                    // Check for ActionResult format (has success property)
+                    // ActionResult: {"success": bool, "status": "code", "message": "...", ...}
+                    const result = response.result;
+                    if (result && typeof result === 'object' && 'success' in result) {
+                        if (!result.success) {
+                            // Create detailed error with status code and message
+                            const errorMsg = result.message || `Action failed: ${result.status || 'unknown'}`;
+                            const error = new Error(errorMsg);
+                            error.status = result.status;
+                            error.selector = result.selector;
+                            error.url = result.url;
+                            error.httpStatus = result.http_status;
+                            error.errorCode = result.error_code;
+                            error.elementCount = result.element_count;
+                            pending.reject(error);
+                        }
+                        else {
+                            // Success - resolve with the full result for detailed info
+                            pending.resolve(result);
+                        }
+                    }
+                    else {
+                        // Legacy format - resolve as-is
+                        pending.resolve(result);
+                    }
                 }
             }
         }
@@ -714,6 +738,11 @@ class HttpConnection {
             // Homepage is a local-only feature, return empty for HTTP mode
             return '';
         }
+        if (method === 'waitForNavigation') {
+            // waitForNavigation is not needed in HTTP mode - browser_navigate is synchronous
+            // Just return success
+            return;
+        }
         const tool = this.mapMethodToTool(method);
         const mappedParams = this.mapParams(method, params);
         if (this.verbose) {
@@ -725,17 +754,31 @@ class HttpConnection {
             if (!response.success) {
                 throw new Error(response.error || 'Unknown error');
             }
+            // Unwrap nested IPC response format
+            // HTTP server wraps browser IPC responses: {success: true, result: {id: N, result: value}}
+            // We need to extract the inner 'result' value
+            let result = response.result;
+            if (result && typeof result === 'object' && 'id' in result && 'result' in result) {
+                result = result.result;
+            }
             // Handle special return value transformations
+            if (method === 'createContext') {
+                // createContext result is the context ID string (e.g., 'ctx_000001')
+                return result;
+            }
             if (method === 'getCurrentURL' || method === 'getPageTitle') {
                 // These methods call getPageInfo but need specific fields
-                if (method === 'getCurrentURL') {
-                    return response.result?.url || response.result;
-                }
-                if (method === 'getPageTitle') {
-                    return response.result?.title || response.result;
+                if (typeof result === 'object' && result !== null) {
+                    if (method === 'getCurrentURL') {
+                        return result.url || result;
+                    }
+                    if (method === 'getPageTitle') {
+                        return result.title || result;
+                    }
                 }
+                return result;
             }
-            return response.result;
+            return result;
         }, this.retryConfig, (error, attempt, delayMs) => {
             if (this.verbose) {
                 console.error(`[HTTP] Retry ${attempt}/${this.retryConfig.maxRetries} for ${tool} after ${delayMs}ms: ${error.message}`);