@olib-ai/owl-browser-sdk 2.0.5 → 2.0.6

package/openapi.json

@@ -3,11 +3,11 @@
   "info": {
     "title": "Owl Browser API",
     "description": "REST API for browser automation with anti-detection capabilities",
-    "version": "1.0.8"
+    "version": "1.0.9"
   },
   "servers": [
     {
-      "url": "http://localhost",
+      "url": "http://127.0.0.1:8080",
       "description": "Current server"
     }
   ],
@@ -639,10 +639,54 @@
         }
       }
     },
+    "/api/execute/browser_set_content": {
+      "post": {
+        "summary": "Browser Set Content",
+        "description": "Set the page's HTML content directly. Replaces the current page content with the provided HTML. The page URL will be 'about:blank'. Useful for rendering HTML templates, testing, or injecting content without making a network request.",
+        "tags": [
+          "General"
+        ],
+        "requestBody": {
+          "required": true,
+          "content": {
+            "application/json": {
+              "schema": {
+                "type": "object",
+                "properties": {
+                  "context_id": {
+                    "type": "string",
+                    "description": "The unique identifier of the browser context (e.g., 'ctx_000001')"
+                  },
+                  "html": {
+                    "type": "string",
+                    "description": "The HTML content to set as the page body. Can be a full HTML document or a fragment. The page URL will be set to 'about:blank'"
+                  }
+                },
+                "required": [
+                  "context_id",
+                  "html"
+                ]
+              }
+            }
+          }
+        },
+        "responses": {
+          "200": {
+            "description": "Successful response"
+          },
+          "400": {
+            "description": "Bad request"
+          },
+          "401": {
+            "description": "Unauthorized"
+          }
+        }
+      }
+    },
     "/api/execute/browser_click": {
       "post": {
         "summary": "Browser Click",
-        "description": "Click on an element using CSS selector, XY coordinates, or natural language description. Supports semantic element finding using AI - describe what you want to click (e.g., 'login button', 'search icon') and the system will locate the right element. Simulates a real mouse click with proper event dispatch.",
+        "description": "Click on an element using CSS selector, XY coordinates, or natural language description. Supports semantic element finding using AI - describe what you want to click (e.g., 'login button', 'search icon') and the system will locate the right element. Simulates a real mouse click with proper event dispatch. Optionally hold the mouse button for press-and-hold interactions using hold_ms.",
         "tags": [
           "General"
         ],
@@ -660,6 +704,14 @@
                   "selector": {
                     "type": "string",
                     "description": "Target element to click. Accepts: CSS selector (e.g., '#submit-btn', '.nav-link'), XY coordinates as 'Xx Y' (e.g., '100x200'), or natural language description (e.g., 'login button', 'search icon'). Semantic descriptions use AI to find the element"
+                  },
+                  "hold_ms": {
+                    "type": "string",
+                    "description": "Duration in milliseconds to hold the mouse button down before releasing. Use for press-and-hold interactions (e.g., long press menus, drag initiation). Default: 0 (immediate click)"
+                  },
+                  "index": {
+                    "type": "string",
+                    "description": "When multiple elements match the selector, click the Nth element (0-based). Uses querySelectorAll()[index] instead of querySelector(). Default: -1 (first match)"
                   }
                 },
                 "required": [
@@ -686,7 +738,7 @@
     "/api/execute/browser_type": {
       "post": {
         "summary": "Browser Type",
-        "description": "Type text into an input field with human-like keystroke simulation. Target the field using CSS selector, coordinates, or natural language (e.g., 'email field'). Note: Does NOT clear existing content - use browser_clear_input first if you need to replace text rather than append.",
+        "description": "Type text into an input field with human-like keystroke simulation. Target the field using CSS selector, coordinates, or natural language (e.g., 'email field'). When selector is omitted, types into the currently focused element. Note: Does NOT clear existing content - use browser_clear_input first if you need to replace text rather than append.",
         "tags": [
           "General"
         ],
@@ -703,16 +755,19 @@
                   },
                   "selector": {
                     "type": "string",
-                    "description": "Target input field. Accepts: CSS selector (e.g., '#email', 'input[name=\"username\"]'), XY coordinates (e.g., '100x200'), or natural language description (e.g., 'email field', 'search box')"
+                    "description": "Target input field. Accepts: CSS selector (e.g., '#email', 'input[name=\"username\"]'), XY coordinates (e.g., '100x200'), or natural language description (e.g., 'email field', 'search box'). When omitted, types into the currently focused element (document.activeElement)"
                   },
                   "text": {
                     "type": "string",
                     "description": "The text to type into the input field. Simulates real keystrokes with human-like timing. Existing content is NOT cleared - use browser_clear_input first if needed"
+                  },
+                  "index": {
+                    "type": "string",
+                    "description": "When multiple elements match the selector, target the Nth element (0-based). Uses querySelectorAll()[index] instead of querySelector(). Default: -1 (first match)"
                   }
                 },
                 "required": [
                   "context_id",
-                  "selector",
                   "text"
                 ]
               }
@@ -784,7 +839,7 @@
     "/api/execute/browser_press_key": {
       "post": {
         "summary": "Browser Press Key",
-        "description": "Press a special keyboard key like Enter, Tab, Escape, or arrow keys. The key is sent to the currently focused element. Common uses: Enter to submit forms, Tab to move between fields, Escape to close modals, Arrow keys for navigation in menus or sliders.",
+        "description": "Press a keyboard key. Supports special keys (Enter, Tab, Escape, arrow keys, etc.) and single characters (a-z, A-Z, 0-9). The key is sent to the currently focused element. Common uses: Enter to submit forms, Tab to move between fields, Escape to close modals, Arrow keys for navigation in menus or sliders, or single characters for keyboard shortcuts.",
         "tags": [
           "General"
         ],
@@ -801,30 +856,7 @@
                   },
                   "key": {
                     "type": "string",
-                    "description": "Special key to press. Common uses: 'Enter' to submit forms, 'Tab' to move focus, 'Escape' to close modals, 'ArrowDown/Up' for navigation. The key is sent to the currently focused element",
-                    "enum": [
-                      "Enter",
-                      "Return",
-                      "Tab",
-                      "Escape",
-                      "Esc",
-                      "Backspace",
-                      "Delete",
-                      "Del",
-                      "ArrowUp",
-                      "Up",
-                      "ArrowDown",
-                      "Down",
-                      "ArrowLeft",
-                      "Left",
-                      "ArrowRight",
-                      "Right",
-                      "Space",
-                      "Home",
-                      "End",
-                      "PageUp",
-                      "PageDown"
-                    ]
+                    "description": "Key to press. Supports special keys: 'Enter', 'Tab', 'Escape', 'Backspace', 'Delete', 'ArrowUp', 'ArrowDown', 'ArrowLeft', 'ArrowRight', 'Space', 'Home', 'End', 'PageUp', 'PageDown'. Also supports single characters: 'a'-'z', 'A'-'Z', '0'-'9'. The key is sent to the currently focused element"
                   }
                 },
                 "required": [
@@ -1087,6 +1119,10 @@
                   "selector": {
                     "type": "string",
                     "description": "CSS selector, position coordinates (e.g., '100x200'), or natural language description of the element to hover over"
+                  },
+                  "index": {
+                    "type": "string",
+                    "description": "When multiple elements match the selector, target the Nth element (0-based). Default: -1 (first match)"
                   }
                 },
                 "required": [
@@ -1131,6 +1167,10 @@
                   "selector": {
                     "type": "string",
                     "description": "CSS selector, position coordinates (e.g., '100x200'), or natural language description of the element to double-click"
+                  },
+                  "index": {
+                    "type": "string",
+                    "description": "When multiple elements match the selector, target the Nth element (0-based). Default: -1 (first match)"
                   }
                 },
                 "required": [
@@ -1175,6 +1215,10 @@
                   "selector": {
                     "type": "string",
                     "description": "CSS selector, position coordinates (e.g., '100x200'), or natural language description of the element to right-click"
+                  },
+                  "index": {
+                    "type": "string",
+                    "description": "When multiple elements match the selector, target the Nth element (0-based). Default: -1 (first match)"
                   }
                 },
                 "required": [
@@ -1219,6 +1263,10 @@
                   "selector": {
                     "type": "string",
                     "description": "CSS selector or natural language description of the input element to clear"
+                  },
+                  "index": {
+                    "type": "string",
+                    "description": "When multiple elements match the selector, target the Nth element (0-based). Default: -1 (first match)"
                   }
                 },
                 "required": [
@@ -1263,6 +1311,10 @@
                   "selector": {
                     "type": "string",
                     "description": "CSS selector or natural language description of the element to focus"
+                  },
+                  "index": {
+                    "type": "string",
+                    "description": "When multiple elements match the selector, target the Nth element (0-based). Default: -1 (first match)"
                   }
                 },
                 "required": [
@@ -1488,6 +1540,10 @@
                   "selector": {
                     "type": "string",
                     "description": "CSS selector or natural language description of the element to check visibility for"
+                  },
+                  "index": {
+                    "type": "string",
+                    "description": "When multiple elements match the selector, check the Nth element (0-based). Default: -1 (first match)"
                   }
                 },
                 "required": [
@@ -1532,6 +1588,10 @@
                   "selector": {
                     "type": "string",
                     "description": "CSS selector or natural language description of the element to check enabled state for"
+                  },
+                  "index": {
+                    "type": "string",
+                    "description": "When multiple elements match the selector, check the Nth element (0-based). Default: -1 (first match)"
                   }
                 },
                 "required": [
@@ -1576,6 +1636,10 @@
                   "selector": {
                     "type": "string",
                     "description": "CSS selector or natural language description of the checkbox or radio button to check"
+                  },
+                  "index": {
+                    "type": "string",
+                    "description": "When multiple elements match the selector, check the Nth element (0-based). Default: -1 (first match)"
                   }
                 },
                 "required": [
@@ -1599,6 +1663,151 @@
         }
       }
     },
+    "/api/execute/browser_is_editable": {
+      "post": {
+        "summary": "Browser Is Editable",
+        "description": "Check if an element is editable (not disabled AND not readOnly). Returns 'editable' if the element can accept user input, 'not_editable' if it is disabled or read-only. More comprehensive than browser_is_enabled which only checks the disabled attribute.",
+        "tags": [
+          "General"
+        ],
+        "requestBody": {
+          "required": true,
+          "content": {
+            "application/json": {
+              "schema": {
+                "type": "object",
+                "properties": {
+                  "context_id": {
+                    "type": "string",
+                    "description": "The unique identifier of the browser context (e.g., 'ctx_000001')"
+                  },
+                  "selector": {
+                    "type": "string",
+                    "description": "CSS selector or natural language description of the element to check editability for"
+                  },
+                  "index": {
+                    "type": "string",
+                    "description": "When multiple elements match the selector, check the Nth element (0-based). Default: -1 (first match)"
+                  }
+                },
+                "required": [
+                  "context_id",
+                  "selector"
+                ]
+              }
+            }
+          }
+        },
+        "responses": {
+          "200": {
+            "description": "Successful response"
+          },
+          "400": {
+            "description": "Bad request"
+          },
+          "401": {
+            "description": "Unauthorized"
+          }
+        }
+      }
+    },
+    "/api/execute/browser_count_elements": {
+      "post": {
+        "summary": "Browser Count Elements",
+        "description": "Count the number of elements matching a CSS selector. Returns the count as an integer. Useful for checking how many items exist (e.g., list items, search results, table rows) without extracting full element data.",
+        "tags": [
+          "General"
+        ],
+        "requestBody": {
+          "required": true,
+          "content": {
+            "application/json": {
+              "schema": {
+                "type": "object",
+                "properties": {
+                  "context_id": {
+                    "type": "string",
+                    "description": "The unique identifier of the browser context (e.g., 'ctx_000001')"
+                  },
+                  "selector": {
+                    "type": "string",
+                    "description": "CSS selector to count matching elements (e.g., 'li.item', 'input[type=\"text\"]', 'table tr')"
+                  }
+                },
+                "required": [
+                  "context_id",
+                  "selector"
+                ]
+              }
+            }
+          }
+        },
+        "responses": {
+          "200": {
+            "description": "Successful response"
+          },
+          "400": {
+            "description": "Bad request"
+          },
+          "401": {
+            "description": "Unauthorized"
+          }
+        }
+      }
+    },
+    "/api/execute/browser_dispatch_event": {
+      "post": {
+        "summary": "Browser Dispatch Event",
+        "description": "Dispatch a DOM event on an element. Programmatically triggers events like 'input', 'change', 'focus', 'blur', 'submit', etc. Useful for triggering event handlers after programmatic value changes, or for simulating user interactions that don't involve mouse/keyboard input.",
+        "tags": [
+          "General"
+        ],
+        "requestBody": {
+          "required": true,
+          "content": {
+            "application/json": {
+              "schema": {
+                "type": "object",
+                "properties": {
+                  "context_id": {
+                    "type": "string",
+                    "description": "The unique identifier of the browser context (e.g., 'ctx_000001')"
+                  },
+                  "selector": {
+                    "type": "string",
+                    "description": "CSS selector or natural language description of the element to dispatch the event on"
+                  },
+                  "event_type": {
+                    "type": "string",
+                    "description": "The DOM event type to dispatch (e.g., 'click', 'input', 'change', 'focus', 'blur', 'submit', 'mouseenter', 'mouseleave'). Any valid DOM event name is accepted"
+                  },
+                  "bubbles": {
+                    "type": "boolean",
+                    "description": "Whether the event should bubble up through the DOM tree. Default: true"
+                  }
+                },
+                "required": [
+                  "context_id",
+                  "selector",
+                  "event_type"
+                ]
+              }
+            }
+          }
+        },
+        "responses": {
+          "200": {
+            "description": "Successful response"
+          },
+          "400": {
+            "description": "Bad request"
+          },
+          "401": {
+            "description": "Unauthorized"
+          }
+        }
+      }
+    },
     "/api/execute/browser_get_attribute": {
       "post": {
         "summary": "Browser Get Attribute",
@@ -1624,6 +1833,10 @@
                   "attribute": {
                     "type": "string",
                     "description": "The attribute name to retrieve (e.g., 'href', 'src', 'value', 'data-id', 'class')"
+                  },
+                  "index": {
+                    "type": "string",
+                    "description": "When multiple elements match the selector, get attribute from the Nth element (0-based). Default: -1 (first match)"
                   }
                 },
                 "required": [
@@ -1669,6 +1882,10 @@
                   "selector": {
                     "type": "string",
                     "description": "CSS selector or natural language description of the element to get position and size for"
+                  },
+                  "index": {
+                    "type": "string",
+                    "description": "When multiple elements match the selector, get bounding box of the Nth element (0-based). Default: -1 (first match)"
                   }
                 },
                 "required": [
@@ -1990,7 +2207,7 @@
     "/api/execute/browser_extract_text": {
       "post": {
         "summary": "Browser Extract Text",
-        "description": "Extract visible text content from the page or a specific element. Returns plain text stripped of HTML tags. Optionally target a specific element using CSS selector or natural language description. Optionally apply a regex pattern to filter/extract specific content from the text. Useful for reading page content, extracting article text, getting form values, or extracting specific data like numbers, emails, or prices.",
+        "description": "Extract visible text content from the page or a specific element. Returns plain text stripped of HTML tags. Optionally target a specific element using CSS selector or natural language description. When the selector matches multiple elements, returns a JSON array of text strings. Optionally apply a regex pattern to filter/extract specific content from the text (applied per-element when multiple matches). Useful for reading page content, extracting article text, getting form values, or extracting specific data like numbers, emails, or prices.",
         "tags": [
           "General"
         ],
@@ -2007,7 +2224,7 @@
                   },
                   "selector": {
                     "type": "string",
-                    "description": "Optional CSS selector or natural language description to extract text from a specific element. If omitted, extracts all visible text from the entire page. Examples: '#main-content', 'article', 'the product description'"
+                    "description": "Optional CSS selector or natural language description to extract text from a specific element. If omitted, extracts all visible text from the entire page. When the selector matches multiple elements, returns a JSON array of text strings (one per element). Examples: '#main-content', '.product-name', 'article'"
                   },
                   "regex": {
                     "type": "string",
@@ -2016,6 +2233,10 @@
                   "regex_group": {
                     "type": "string",
                     "description": "Which capture group to return from the regex match. 0 returns the full match (default), 1 returns the first capture group, 2 returns the second, etc. Example: with regex 'FP ID:\\\\s*(\\\\S+)' and regex_group=1, only the ID value is returned."
+                  },
+                  "index": {
+                    "type": "string",
+                    "description": "When multiple elements match the selector, extract text from the Nth element (0-based) instead of returning all. Default: not set (returns all matches as array). Set to 0 for first, 1 for second, -1 for last."
                   }
                 },
                 "required": [
@@ -2123,6 +2344,10 @@
                   "background_color": {
                     "type": "string",
                     "description": "CSS color for the highlight background (use alpha for transparency). Default: 'rgba(255, 0, 0, 0.2)'. Examples: 'rgba(0, 255, 0, 0.3)', 'transparent'"
+                  },
+                  "index": {
+                    "type": "string",
+                    "description": "When multiple elements match the selector, highlight the Nth element (0-based). Default: -1 (first match)"
                   }
                 },
                 "required": [
@@ -2204,7 +2429,7 @@
     "/api/execute/browser_get_html": {
       "post": {
         "summary": "Browser Get Html",
-        "description": "Extract the page's HTML with configurable cleaning levels. 'minimal' preserves most structure, 'basic' removes scripts and styles, 'aggressive' strips to essential content. Useful for page analysis, content extraction, and feeding HTML to other processing tools.",
+        "description": "Extract HTML content with configurable cleaning levels. Optionally target a specific element using a CSS selector to get its innerHTML instead of the full page. When the selector matches multiple elements, returns a JSON array of HTML strings. 'minimal' preserves most structure, 'basic' removes scripts and styles, 'aggressive' strips to essential content. Useful for page analysis, content extraction, and feeding HTML to other processing tools.",
         "tags": [
           "General"
         ],
@@ -2219,6 +2444,10 @@
                     "type": "string",
                     "description": "The unique identifier of the browser context (e.g., 'ctx_000001')"
                   },
+                  "selector": {
+                    "type": "string",
+                    "description": "Optional CSS selector to get innerHTML of a specific element (e.g., '#content', '.article-body'). When the selector matches multiple elements, returns a JSON array of HTML strings (one per element). When omitted, returns the full page HTML"
+                  },
                   "clean_level": {
                     "type": "string",
                     "description": "Level of HTML cleaning to apply. 'minimal': preserves most structure, 'basic': removes scripts/styles (default), 'aggressive': strips to essential content only. Choose based on how much structure you need",
@@ -2501,7 +2730,7 @@
     "/api/execute/browser_extract_json": {
       "post": {
         "summary": "Browser Extract Json",
-        "description": "Extract structured data from the page using predefined templates or auto-detection. Templates available for Google Search results, Wikipedia articles, Amazon products, GitHub repos, and more. Returns consistently structured JSON regardless of page layout changes.",
+        "description": "Extract structured data from the page as JSON. For known sites (Google, Amazon, Wikipedia, etc.) uses predefined templates. For unknown sites, uses smart DOM analysis to detect repeating items (products, posts, search results) and extract fields (title, link, image, price, rating, date, description). Use 'selector' to scope extraction to a specific container. Returns page type, items array, structured LD+JSON data, and meta tags.",
         "tags": [
           "General"
         ],
@@ -2519,6 +2748,10 @@
                   "template": {
                     "type": "string",
                     "description": "Extraction template name for known site types. Available: 'google_search', 'wikipedia', 'amazon_product', 'github_repo', 'twitter_feed', 'reddit_thread'. Leave empty for auto-detection based on URL"
+                  },
+                  "selector": {
+                    "type": "string",
+                    "description": "CSS selector to scope extraction to a specific container (e.g., 'div.product-grid', '#results'). When set, only elements within this container are analyzed for repeating patterns"
                   }
                 },
                 "required": [
@@ -3119,6 +3352,10 @@
                   "selector": {
                     "type": "string",
                     "description": "CSS selector or natural language description of the element to scroll into view. Examples: '#footer', '.product-reviews', 'the comments section'"
+                  },
+                  "index": {
+                    "type": "string",
+                    "description": "When multiple elements match the selector, scroll to the Nth element (0-based). Default: -1 (first match)"
                   }
                 },
                 "required": [
@@ -3245,6 +3482,10 @@
                   "timeout": {
                     "type": "string",
                     "description": "Maximum time to wait in milliseconds. Returns error if element doesn't appear within this time. Default: 5000 (5 seconds)"
+                  },
+                  "index": {
+                    "type": "string",
+                    "description": "When multiple elements match the selector, wait for the Nth element (0-based). Default: -1 (first match)"
                   }
                 },
                 "required": [
@@ -6798,6 +7039,57 @@
         }
       }
     },
+    "/api/execute/browser_get_page_map": {
+      "post": {
+        "summary": "Browser Get Page Map",
+        "description": "Get a compact structured map of all interactive elements on the page, grouped by sections. Returns a markdown table with numbered references, types, descriptions, current values, and selectors. Use element numbers as selectors in browser_click and browser_type (e.g., selector '5'). 10x cheaper than screenshots for AI agent page understanding.",
+        "tags": [
+          "General"
+        ],
+        "requestBody": {
+          "required": true,
+          "content": {
+            "application/json": {
+              "schema": {
+                "type": "object",
+                "properties": {
+                  "context_id": {
+                    "type": "string",
+                    "description": "The unique identifier of the browser context (e.g., 'ctx_000001')"
+                  },
+                  "intent": {
+                    "type": "string",
+                    "description": "Task description to boost matching elements (e.g., 'buy nvidia jetson')"
+                  },
+                  "max_elements": {
+                    "type": "string",
+                    "description": "Maximum number of elements to return (0 = unlimited). Returns top N by importance score"
+                  },
+                  "region": {
+                    "type": "string",
+                    "description": "Filter to specific page region: 'main', 'nav', 'header', 'footer', 'sidebar', 'article', 'form', 'dialog'. Empty = all regions"
+                  }
+                },
+                "required": [
+                  "context_id"
+                ]
+              }
+            }
+          }
+        },
+        "responses": {
+          "200": {
+            "description": "Successful response"
+          },
+          "400": {
+            "description": "Bad request"
+          },
+          "401": {
+            "description": "Unauthorized"
+          }
+        }
+      }
+    },
     "/api/execute/browser_get_blocker_stats": {
       "post": {
         "summary": "Browser Get Blocker Stats",

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@olib-ai/owl-browser-sdk",
-  "version": "2.0.5",
+  "version": "2.0.6",
   "description": "Node.js SDK for Owl Browser automation - Async-first with dynamic OpenAPI method generation",
   "main": "dist/index.js",
   "module": "dist/index.js",
@@ -22,6 +22,14 @@
     "./auth": {
       "import": "./dist/auth/index.js",
       "types": "./dist/auth/index.d.ts"
+    },
+    "./playwright": {
+      "import": "./dist/playwright/index.js",
+      "types": "./dist/playwright/index.d.ts"
+    },
+    "./extraction": {
+      "import": "./dist/extraction/index.js",
+      "types": "./dist/extraction/index.d.ts"
     }
   },
   "files": [
@@ -63,6 +71,7 @@
     "node": ">=18.0.0"
   },
   "dependencies": {
+    "cheerio": "^1.2.0",
     "jsonwebtoken": "^9.0.2",
     "ws": "^8.18.0"
   },