@olib-ai/owl-browser-sdk 2.0.9 → 2.1.1

package/openapi.json

@@ -3,7 +3,7 @@
   "info": {
     "title": "Owl Browser API",
     "description": "REST API for browser automation with anti-detection capabilities",
-    "version": "1.0.11"
+    "version": "1.1.2"
   },
   "servers": [
     {
@@ -28,7 +28,7 @@
     "/go": {
       "get": {
         "summary": "Browser Go",
-        "description": "One-shot browser navigation tool. Creates a new context, navigates to the URL, waits for page load, extracts the HTML, and closes the context. Optimized for single-page scraping or rendering tasks. Supports both GET and POST requests.",
+        "description": "One-shot browser navigation tool. Creates a new context, navigates to the URL, waits for page load, extracts the HTML, and closes the context. Optimized for single-page scraping or rendering tasks. Callable as POST /execute/browser_go or the GET /go?url=... convenience endpoint (page requests are always GET).",
         "tags": [
           "Navigation"
         ],
@@ -56,7 +56,7 @@
                 "fullscroll"
               ]
             },
-            "description": "When to consider navigation complete: '' (return immediately), 'load' (wait for load event), 'domcontentloaded' (wait for DOMContentLoaded), 'networkidle' (wait for network to be idle, default), 'fullscroll' (scroll full page to trigger lazy loading, then scroll back to top)"
+            "description": "When to consider navigation complete: 'load' (wait for load event, default; '' is treated as 'load'), 'domcontentloaded' (wait for DOMContentLoaded), 'networkidle' (wait for network to be idle), 'fullscroll' (scroll full page to trigger lazy loading, then scroll back to top)"
           },
           {
             "name": "timeout",
@@ -248,9 +248,22 @@
                     "type": "boolean",
                     "description": "Enable or disable resource blocking (ads, trackers, analytics). When enabled, blocks requests to known ad networks, trackers, and analytics services. Default: true (enabled)"
                   },
-                  "agent_signature": {
-                    "type": "boolean",
-                    "description": "Enable Web Bot Auth (RFC 9421) request signing for this context. When enabled, every outgoing HTTP request is signed with Ed25519 Signature, Signature-Input, and Signature-Agent headers. Requires OWL_WBA_ENABLED=true and OWL_WBA_CONTACTS set. Default: false"
+                  "chrome_version_id": {
+                    "type": "string",
+                    "description": "Pin this context to a specific row in the chrome_versions table (FK by id, 1..N matching INSERT order sorted by major). Use chrome_version_major instead if you'd rather think in terms of '147'. Mutually exclusive with chrome_version_major; chrome_version_id wins when both are set. 0 / unset = random selection across all chrome_version_ids matching the os/gpu/screen filters."
+                  },
+                  "chrome_version_major": {
+                    "type": "string",
+                    "description": "Pin this context to a specific Chrome major. Resolved to chrome_version_id by looking up the chrome_versions row whose major matches. Options: '143', '144', '145', '146', '147', '148', '149' (current 7-major roster).",
+                    "enum": [
+                      "143",
+                      "144",
+                      "145",
+                      "146",
+                      "147",
+                      "148",
+                      "149"
+                    ]
                   },
                   "proxy_type": {
                     "type": "string",
@@ -280,9 +293,13 @@
                     "type": "string",
                     "description": "Password for proxy authentication. Only required if the proxy server requires credentials"
                   },
-                  "proxy_stealth": {
+                  "proxy_spoof_timezone": {
                     "type": "boolean",
-                    "description": "Enable stealth mode to prevent proxy/VPN detection. Blocks WebRTC leaks and other detection vectors. Default: true when proxy is configured"
+                    "description": "Automatically spoof browser timezone to match proxy location (detected via IP geolocation). Default: true when proxy is configured"
+                  },
+                  "proxy_timezone_override": {
+                    "type": "string",
+                    "description": "Manually set timezone instead of proxy auto-detection. IANA format like 'America/New_York', 'Europe/London'. Takes precedence over proxy_spoof_timezone. The top-level 'timezone' parameter takes precedence over both"
                   },
                   "proxy_ca_cert_path": {
                     "type": "string",
@@ -327,6 +344,10 @@
                   "llm_api_key": {
                     "type": "string",
                     "description": "API key for the external LLM provider. Required when using external LLM endpoint"
+                  },
+                  "llm_is_third_party": {
+                    "type": "boolean",
+                    "description": "Mark the LLM as a third-party provider (OpenAI-compatible API). Automatically inferred as true when llm_endpoint is set. Default: false"
                   }
                 }
               }
@@ -499,7 +520,7 @@
                   },
                   "wait_until": {
                     "type": "string",
-                    "description": "When to consider reload complete: '' (return immediately), 'load' (wait for load event, default), 'domcontentloaded' (wait for DOMContentLoaded), 'networkidle' (wait for network to be idle), 'fullscroll' (scroll full page to trigger lazy loading, then scroll back to top)",
+                    "description": "When to consider reload complete: 'load' (wait for load event, default; '' is treated as 'load'), 'domcontentloaded' (wait for DOMContentLoaded), 'networkidle' (wait for network to be idle), 'fullscroll' (scroll full page to trigger lazy loading, then scroll back to top)",
                     "enum": [
                       "",
                       "load",
@@ -553,7 +574,7 @@
                   },
                   "wait_until": {
                     "type": "string",
-                    "description": "When to consider navigation complete: '' (return immediately), 'load' (wait for load event, default), 'domcontentloaded' (wait for DOMContentLoaded), 'networkidle' (wait for network to be idle), 'fullscroll' (scroll full page to trigger lazy loading, then scroll back to top)",
+                    "description": "When to consider navigation complete: 'load' (wait for load event, default; '' is treated as 'load'), 'domcontentloaded' (wait for DOMContentLoaded), 'networkidle' (wait for network to be idle), 'fullscroll' (scroll full page to trigger lazy loading, then scroll back to top)",
                     "enum": [
                       "",
                       "load",
@@ -607,7 +628,7 @@
                   },
                   "wait_until": {
                     "type": "string",
-                    "description": "When to consider navigation complete: '' (return immediately), 'load' (wait for load event, default), 'domcontentloaded' (wait for DOMContentLoaded), 'networkidle' (wait for network to be idle), 'fullscroll' (scroll full page to trigger lazy loading, then scroll back to top)",
+                    "description": "When to consider navigation complete: 'load' (wait for load event, default; '' is treated as 'load'), 'domcontentloaded' (wait for DOMContentLoaded), 'networkidle' (wait for network to be idle), 'fullscroll' (scroll full page to trigger lazy loading, then scroll back to top)",
                     "enum": [
                       "",
                       "load",
@@ -791,7 +812,11 @@
                   },
                   "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)"
+                    "description": "When multiple elements match the selector, click the Nth element (0-based). Uses querySelectorAll()[index] instead of querySelector(). Omit for the first match (querySelector). Use -1 to target the LAST matching element"
+                  },
+                  "verification_level": {
+                    "type": "string",
+                    "description": "How thoroughly to verify the click took effect: 'none', 'basic', 'standard', 'strict'. Default: 'standard'"
                   }
                 },
                 "required": [
@@ -843,7 +868,11 @@
                   },
                   "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)"
+                    "description": "When multiple elements match the selector, target the Nth element (0-based). Uses querySelectorAll()[index] instead of querySelector(). Omit for the first match (querySelector). Use -1 to target the LAST matching element"
+                  },
+                  "verification_level": {
+                    "type": "string",
+                    "description": "How thoroughly to verify the typed text took effect: 'none', 'basic', 'standard', 'strict'. Default: 'standard'"
                   }
                 },
                 "required": [
@@ -892,6 +921,10 @@
                   "value": {
                     "type": "string",
                     "description": "The option to select. Can be the option's value attribute OR the visible display text. Works with both native select elements and dynamic dropdowns (select2, etc.)"
+                  },
+                  "verification_level": {
+                    "type": "string",
+                    "description": "How thoroughly to verify the selection took effect: 'none', 'basic', 'standard', 'strict'. Default: 'standard'"
                   }
                 },
                 "required": [
@@ -1202,7 +1235,7 @@
                   },
                   "index": {
                     "type": "string",
-                    "description": "When multiple elements match the selector, target the Nth element (0-based). Default: -1 (first match)"
+                    "description": "When multiple elements match the selector, target the Nth element (0-based). Omit for the first match (querySelector). Use -1 to target the LAST matching element"
                   }
                 },
                 "required": [
@@ -1250,7 +1283,7 @@
                   },
                   "index": {
                     "type": "string",
-                    "description": "When multiple elements match the selector, target the Nth element (0-based). Default: -1 (first match)"
+                    "description": "When multiple elements match the selector, target the Nth element (0-based). Omit for the first match (querySelector). Use -1 to target the LAST matching element"
                   }
                 },
                 "required": [
@@ -1298,7 +1331,7 @@
                   },
                   "index": {
                     "type": "string",
-                    "description": "When multiple elements match the selector, target the Nth element (0-based). Default: -1 (first match)"
+                    "description": "When multiple elements match the selector, target the Nth element (0-based). Omit for the first match (querySelector). Use -1 to target the LAST matching element"
                   }
                 },
                 "required": [
@@ -1346,7 +1379,7 @@
                   },
                   "index": {
                     "type": "string",
-                    "description": "When multiple elements match the selector, target the Nth element (0-based). Default: -1 (first match)"
+                    "description": "When multiple elements match the selector, target the Nth element (0-based). Omit for the first match (querySelector). Use -1 to target the LAST matching element"
                   }
                 },
                 "required": [
@@ -1394,7 +1427,7 @@
                   },
                   "index": {
                     "type": "string",
-                    "description": "When multiple elements match the selector, target the Nth element (0-based). Default: -1 (first match)"
+                    "description": "When multiple elements match the selector, target the Nth element (0-based). Omit for the first match (querySelector). Use -1 to target the LAST matching element"
                   }
                 },
                 "required": [
@@ -1623,7 +1656,7 @@
                   },
                   "index": {
                     "type": "string",
-                    "description": "When multiple elements match the selector, check the Nth element (0-based). Default: -1 (first match)"
+                    "description": "When multiple elements match the selector, check the Nth element (0-based). Omit for the first match (querySelector). Use -1 to target the LAST matching element"
                   }
                 },
                 "required": [
@@ -1671,7 +1704,7 @@
                   },
                   "index": {
                     "type": "string",
-                    "description": "When multiple elements match the selector, check the Nth element (0-based). Default: -1 (first match)"
+                    "description": "When multiple elements match the selector, check the Nth element (0-based). Omit for the first match (querySelector). Use -1 to target the LAST matching element"
                   }
                 },
                 "required": [
@@ -1719,7 +1752,7 @@
                   },
                   "index": {
                     "type": "string",
-                    "description": "When multiple elements match the selector, check the Nth element (0-based). Default: -1 (first match)"
+                    "description": "When multiple elements match the selector, check the Nth element (0-based). Omit for the first match (querySelector). Use -1 to target the LAST matching element"
                   }
                 },
                 "required": [
@@ -1767,7 +1800,7 @@
                   },
                   "index": {
                     "type": "string",
-                    "description": "When multiple elements match the selector, check the Nth element (0-based). Default: -1 (first match)"
+                    "description": "When multiple elements match the selector, check the Nth element (0-based). Omit for the first match (querySelector). Use -1 to target the LAST matching element"
                   }
                 },
                 "required": [
@@ -1891,7 +1924,7 @@
     "/api/execute/browser_get_attribute": {
       "post": {
         "summary": "Browser Get Attribute",
-        "description": "Get the value of an HTML attribute from an element. Can retrieve any attribute including 'href', 'src', 'value', 'data-*' attributes, 'class', 'id', etc. Returns null if attribute doesn't exist.",
+        "description": "Get the value of an HTML attribute from an element. Can retrieve any attribute including 'href', 'src', 'value', 'data-*' attributes, 'class', 'id', etc. Returns an empty string if the attribute doesn't exist or the element is not found.",
         "tags": [
           "General"
         ],
@@ -1916,7 +1949,7 @@
                   },
                   "index": {
                     "type": "string",
-                    "description": "When multiple elements match the selector, get attribute from the Nth element (0-based). Default: -1 (first match)"
+                    "description": "When multiple elements match the selector, get attribute from the Nth element (0-based). Omit for the first match (querySelector). Use -1 to target the LAST matching element"
                   }
                 },
                 "required": [
@@ -1965,7 +1998,7 @@
                   },
                   "index": {
                     "type": "string",
-                    "description": "When multiple elements match the selector, get bounding box of the Nth element (0-based). Default: -1 (first match)"
+                    "description": "When multiple elements match the selector, get bounding box of the Nth element (0-based). Omit for the first match (querySelector). Use -1 to target the LAST matching element"
                   }
                 },
                 "required": [
@@ -2427,7 +2460,7 @@
                   },
                   "index": {
                     "type": "string",
-                    "description": "When multiple elements match the selector, highlight the Nth element (0-based). Default: -1 (first match)"
+                    "description": "When multiple elements match the selector, highlight the Nth element (0-based). Omit for the first match (querySelector). Use -1 to target the LAST matching element"
                   }
                 },
                 "required": [
@@ -3335,7 +3368,7 @@
                   },
                   "max_results": {
                     "type": "string",
-                    "description": "Maximum number of results to return (default: 10)"
+                    "description": "Maximum number of results to return (default: 5)"
                   }
                 },
                 "required": [
@@ -3435,7 +3468,7 @@
                   },
                   "index": {
                     "type": "string",
-                    "description": "When multiple elements match the selector, scroll to the Nth element (0-based). Default: -1 (first match)"
+                    "description": "When multiple elements match the selector, scroll to the Nth element (0-based). Omit for the first match (querySelector). Use -1 to target the LAST matching element"
                   }
                 },
                 "required": [
@@ -3565,7 +3598,7 @@
                   },
                   "index": {
                     "type": "string",
-                    "description": "When multiple elements match the selector, wait for the Nth element (0-based). Default: -1 (first match)"
+                    "description": "When multiple elements match the selector, wait for the Nth element (0-based). Omit for the first match (querySelector). Use -1 to target the LAST matching element"
                   }
                 },
                 "required": [
@@ -3843,11 +3876,11 @@
                   },
                   "width": {
                     "type": "string",
-                    "description": "Viewport width in pixels. Common sizes: 1920 (desktop), 1366 (laptop), 768 (tablet), 375 (mobile)"
+                    "description": "Viewport width in pixels. Common sizes: 1920 (desktop), 1366 (laptop), 768 (tablet), 375 (mobile). Minimum 100 (values below are clamped). On Linux/Docker each dimension is capped at 2048 and total area at 4,000,000 px (requests above are scaled down proportionally)"
                   },
                   "height": {
                     "type": "string",
-                    "description": "Viewport height in pixels. Common sizes: 1080 (desktop), 768 (laptop), 1024 (tablet), 812 (mobile)"
+                    "description": "Viewport height in pixels. Common sizes: 1080 (desktop), 768 (laptop), 1024 (tablet), 812 (mobile). Minimum 100 (values below are clamped). On Linux/Docker each dimension is capped at 2048 and total area at 4,000,000 px (requests above are scaled down proportionally)"
                   }
                 },
                 "required": [
@@ -4142,7 +4175,7 @@
                   },
                   "codec": {
                     "type": "string",
-                    "description": "Video codec for encoding. Default: 'libx264' (H.264, widely compatible). Options depend on system FFmpeg installation"
+                    "description": "Video codec for encoding. Default: 'libx264' (H.264, widely compatible). Accepted values: 'libx264', 'libx265', 'h264', 'hevc', 'vp8', 'vp9', 'libvpx', 'libvpx-vp9', 'mpeg4', 'copy'. Any other value is rejected and recording fails to start. The codec must also be supported by the system FFmpeg"
                   }
                 },
                 "required": [
@@ -5170,29 +5203,13 @@
                     "type": "string",
                     "description": "Password for proxy authentication. Only required if the proxy server requires credentials"
                   },
-                  "stealth": {
-                    "type": "boolean",
-                    "description": "Enable stealth mode to prevent proxy/VPN detection. Blocks WebRTC leaks, DNS leaks, and other fingerprinting vectors. Default: true"
-                  },
-                  "block_webrtc": {
-                    "type": "boolean",
-                    "description": "Block WebRTC to prevent real IP address leaking through STUN/TURN requests. Essential for privacy. Default: true (enabled when stealth mode is on)"
-                  },
                   "spoof_timezone": {
                     "type": "boolean",
-                    "description": "Automatically spoof browser timezone to match proxy location (detected via IP geolocation). Default: false"
-                  },
-                  "spoof_language": {
-                    "type": "boolean",
-                    "description": "Automatically spoof browser language preferences to match proxy location. Default: false"
+                    "description": "Automatically spoof browser timezone to match proxy location (detected via IP geolocation). Applied to the live context immediately. Default: true"
                   },
                   "timezone_override": {
                     "type": "string",
-                    "description": "Manually set timezone instead of auto-detection. IANA format like 'America/New_York', 'Europe/London'. Takes precedence over spoof_timezone"
-                  },
-                  "language_override": {
-                    "type": "string",
-                    "description": "Manually set browser language instead of auto-detection. BCP47 format like 'en-US', 'de-DE'. Takes precedence over spoof_language"
+                    "description": "Manually set timezone instead of auto-detection. IANA format like 'America/New_York', 'Europe/London'. Takes precedence over spoof_timezone. Applied to the live context immediately"
                   },
                   "ca_cert_path": {
                     "type": "string",
@@ -5419,7 +5436,7 @@
                 "properties": {
                   "context_id": {
                     "type": "string",
-                    "description": "Optional browser context ID. If provided, associates the created profile with this context. If omitted, creates a standalone profile that can be applied to any context later."
+                    "description": "Optional browser context ID. If provided, the returned profile snapshots this context's live state (fingerprint, cookies, LLM/proxy config) — use browser_save_profile to persist it to disk. If omitted, creates a standalone profile with a freshly generated random fingerprint."
                   },
                   "name": {
                     "type": "string",
@@ -6219,7 +6236,7 @@
     "/api/execute/browser_wait_for_download": {
       "post": {
         "summary": "Browser Wait For Download",
-        "description": "Block until a specific download completes or times out. Returns the final download status and file path on success. Use after triggering a download to ensure it finishes before proceeding.",
+        "description": "Block until a specific download completes or times out. Returns true on completion; call browser_get_downloads afterwards for the file path and final status. Use after triggering a download to ensure it finishes before proceeding.",
         "tags": [
           "General"
         ],

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@olib-ai/owl-browser-sdk",
-  "version": "2.0.9",
+  "version": "2.1.1",
   "description": "Node.js SDK for Owl Browser automation - Async-first with dynamic OpenAPI method generation",
   "main": "dist/index.js",
   "module": "dist/index.js",