@olib-ai/owl-browser-sdk 2.0.7 → 2.1.0

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.9"
+    "version": "1.1.2"
   },
   "servers": [
     {
-      "url": "http://127.0.0.1:8080",
+      "url": "http://localhost",
       "description": "Current server"
     }
   ],
@@ -120,6 +120,82 @@
         }
       }
     },
+    "/search": {
+      "get": {
+        "summary": "Browser Search",
+        "description": "One-shot web search tool. Creates a new context, navigates to the search engine, waits for results, extracts structured JSON search results (titles, URLs, snippets), and closes the context. Supports Google and DuckDuckGo with pagination.",
+        "tags": [
+          "Navigation"
+        ],
+        "parameters": [
+          {
+            "name": "query",
+            "in": "query",
+            "required": true,
+            "schema": {
+              "type": "string"
+            },
+            "description": "The search query string (e.g., 'best restaurants in NYC', 'python tutorial')"
+          },
+          {
+            "name": "provider",
+            "in": "query",
+            "required": false,
+            "schema": {
+              "type": "string",
+              "enum": [
+                "duckduckgo",
+                "google"
+              ]
+            },
+            "description": "Search engine provider. 'duckduckgo' uses DuckDuckGo HTML-lite, 'google' uses Google Search. Default: duckduckgo"
+          },
+          {
+            "name": "page",
+            "in": "query",
+            "required": false,
+            "schema": {
+              "type": "integer"
+            },
+            "description": "Page number for paginated results (1-based). Default: 1. For Google: appends &start=((page-1)*10). For DuckDuckGo: appends &s=((page-1)*10)"
+          },
+          {
+            "name": "os",
+            "in": "query",
+            "required": false,
+            "schema": {
+              "type": "string",
+              "enum": [
+                "windows",
+                "macos",
+                "linux"
+              ]
+            },
+            "description": "Filter profiles by operating system. Options: 'windows', 'macos', 'linux'"
+          },
+          {
+            "name": "use_tor",
+            "in": "query",
+            "required": false,
+            "schema": {
+              "type": "boolean"
+            },
+            "description": "Use TOR proxy for anonymous browsing. Each request gets a unique exit IP. Default: false"
+          }
+        ],
+        "responses": {
+          "200": {
+            "description": "Successful response with structured search results JSON"
+          },
+          "400": {
+            "description": "Bad request"
+          },
+          "401": {
+            "description": "Unauthorized"
+          }
+        }
+      }
+    },
     "/api/execute/browser_create_context": {
       "post": {
         "summary": "Browser Create Context",
@@ -134,29 +210,59 @@
               "schema": {
                 "type": "object",
                 "properties": {
-                  "llm_enabled": {
-                    "type": "boolean",
-                    "description": "Enable or disable LLM features for this context. When enabled, allows using AI-powered tools like browser_query_page, browser_summarize_page, and browser_nla. Default: true"
+                  "profile_path": {
+                    "type": "string",
+                    "description": "Path to a browser profile JSON file (or upload file via multipart/form-data). If the file exists, loads fingerprints, cookies, and settings. If not, creates a new profile and saves it to this path. Encrypted profiles (from browser_download_profile) are automatically detected and decrypted."
                   },
-                  "llm_use_builtin": {
-                    "type": "boolean",
-                    "description": "Use the built-in llama-server for LLM inference. When true, uses the bundled local model. Set to false to use an external LLM provider. Default: true"
+                  "os": {
+                    "type": "string",
+                    "description": "Filter profiles by operating system. If set, only profiles matching this OS will be used. Options: 'windows', 'macos', 'linux'",
+                    "enum": [
+                      "windows",
+                      "macos",
+                      "linux"
+                    ]
                   },
-                  "llm_endpoint": {
+                  "gpu": {
                     "type": "string",
-                    "description": "External LLM API endpoint URL (e.g., 'https://api.openai.com/v1' for OpenAI). Only used when llm_use_builtin is false"
+                    "description": "Filter profiles by GPU vendor/model. If set, only profiles with matching GPU will be used. Examples: 'nvidia', 'amd', 'intel'"
                   },
-                  "llm_model": {
+                  "screen_size": {
                     "type": "string",
-                    "description": "External LLM model name (e.g., 'gpt-4-vision-preview' for OpenAI). Only used when llm_use_builtin is false"
+                    "description": "Screen resolution for the browser context. Format: 'WIDTHxHEIGHT'. If not set, a random screen size is selected from the monitor catalog.",
+                    "enum": [
+                      "1920x1080",
+                      "2560x1440",
+                      "3440x1440",
+                      "3840x2160",
+                      "3840x1600",
+                      "5120x2160",
+                      "5120x1440"
+                    ]
                   },
-                  "llm_api_key": {
+                  "timezone": {
                     "type": "string",
-                    "description": "API key for the external LLM provider. Required when using external LLM endpoint"
+                    "description": "Override browser timezone. IANA timezone format (e.g., 'America/New_York', 'Europe/London', 'Asia/Tokyo'). If not set, falls back to: 1) proxy-detected timezone (if proxy configured with spoof_timezone), 2) VM profile timezone, 3) system default. This parameter works without proxy configuration."
                   },
-                  "profile_path": {
+                  "resource_blocking": {
+                    "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)"
+                  },
+                  "chrome_version_id": {
                     "type": "string",
-                    "description": "Path to a browser profile JSON file (or upload file via multipart/form-data). If the file exists, loads fingerprints, cookies, and settings. If not, creates a new profile and saves it to this path. Encrypted profiles (from browser_download_profile) are automatically detected and decrypted."
+                    "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' (current 6-major roster).",
+                    "enum": [
+                      "143",
+                      "144",
+                      "145",
+                      "146",
+                      "147",
+                      "148"
+                    ]
                   },
                   "proxy_type": {
                     "type": "string",
@@ -214,39 +320,25 @@
                     "type": "string",
                     "description": "Password for Tor control port authentication. Leave empty to use cookie authentication (default) or no auth"
                   },
-                  "resource_blocking": {
+                  "llm_enabled": {
                     "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)"
+                    "description": "Enable or disable LLM features for this context. When enabled, allows using AI-powered tools like browser_query_page, browser_summarize_page, and browser_nla. Default: true"
                   },
-                  "os": {
-                    "type": "string",
-                    "description": "Filter profiles by operating system. If set, only profiles matching this OS will be used. Options: 'windows', 'macos', 'linux'",
-                    "enum": [
-                      "windows",
-                      "macos",
-                      "linux"
-                    ]
+                  "llm_use_builtin": {
+                    "type": "boolean",
+                    "description": "Use the built-in llama-server for LLM inference. When true, uses the bundled local model. Set to false to use an external LLM provider. Default: true"
                   },
-                  "gpu": {
+                  "llm_endpoint": {
                     "type": "string",
-                    "description": "Filter profiles by GPU vendor/model. If set, only profiles with matching GPU will be used. Examples: 'nvidia', 'amd', 'intel'"
+                    "description": "External LLM API endpoint URL (e.g., 'https://api.openai.com/v1' for OpenAI). Only used when llm_use_builtin is false"
                   },
-                  "timezone": {
+                  "llm_model": {
                     "type": "string",
-                    "description": "Override browser timezone. IANA timezone format (e.g., 'America/New_York', 'Europe/London', 'Asia/Tokyo'). If not set, falls back to: 1) proxy-detected timezone (if proxy configured with spoof_timezone), 2) VM profile timezone, 3) system default. This parameter works without proxy configuration."
+                    "description": "External LLM model name (e.g., 'gpt-4-vision-preview' for OpenAI). Only used when llm_use_builtin is false"
                   },
-                  "screen_size": {
+                  "llm_api_key": {
                     "type": "string",
-                    "description": "Screen resolution for the browser context. Format: 'WIDTHxHEIGHT'. If not set, a random screen size is selected from the monitor catalog.",
-                    "enum": [
-                      "1920x1080",
-                      "2560x1440",
-                      "3440x1440",
-                      "3840x2160",
-                      "3840x1600",
-                      "5120x2160",
-                      "5120x1440"
-                    ]
+                    "description": "API key for the external LLM provider. Required when using external LLM endpoint"
                   }
                 }
               }
@@ -339,7 +431,7 @@
     "/api/execute/browser_navigate": {
       "post": {
         "summary": "Browser Navigate",
-        "description": "Navigate the browser to a specified URL. This is a non-blocking operation that starts navigation and returns immediately. Use browser_wait_for_network_idle or browser_wait_for_selector to wait for the page to fully load. Supports HTTP, HTTPS, file, and data URLs.",
+        "description": "Navigate the browser to a specified URL. This is a non-blocking operation that starts navigation and returns immediately. Use browser_wait_for_network_idle or browser_wait_for_selector to wait for the page to fully load. Supports HTTP, HTTPS, file, and data URLs. When wait_until is set (load, networkidle, fullscroll, domcontentloaded) and the page declares WebMCP tools, the response includes a webmcp_tools array containing the full tool definitions (name, description, inputSchema). Use browser_webmcp_call_tool to execute any of these tools directly.",
         "tags": [
           "General"
         ],
@@ -2747,7 +2839,7 @@
                   },
                   "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"
+                    "description": "Extraction template name for known site types. Available: 'google_search', 'duckduckgo_search', 'wikipedia', 'amazon_product', 'github_repo', 'twitter_feed', 'reddit_thread'. Leave empty for auto-detection based on URL"
                   },
                   "selector": {
                     "type": "string",
@@ -6248,11 +6340,12 @@
                   },
                   "action": {
                     "type": "string",
-                    "description": "How to automatically handle this dialog type: 'accept' clicks OK/Yes, 'dismiss' clicks Cancel/No, 'accept_with_text' accepts and provides text input (for prompts)",
+                    "description": "How to automatically handle this dialog type: 'accept' clicks OK/Yes, 'dismiss' clicks Cancel/No, 'accept_with_text' accepts and provides text input (for prompts), 'wait' holds the dialog for manual handling via browser_handle_dialog",
                     "enum": [
                       "accept",
                       "dismiss",
-                      "accept_with_text"
+                      "accept_with_text",
+                      "wait"
                     ]
                   },
                   "prompt_text": {
@@ -8414,6 +8507,163 @@
           }
         }
       }
+    },
+    "/api/execute/browser_webmcp_get_tools": {
+      "post": {
+        "summary": "Browser Webmcp Get Tools",
+        "description": "Get all WebMCP tools declared by the current page via navigator.modelContext.registerTool() or declarative <form toolname> elements. Returns a JSON array of tool definitions with name, description, and inputSchema. Use after navigating to a page to discover available page-level tools.",
+        "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')"
+                  }
+                },
+                "required": [
+                  "context_id"
+                ]
+              }
+            }
+          }
+        },
+        "responses": {
+          "200": {
+            "description": "Successful response"
+          },
+          "400": {
+            "description": "Bad request"
+          },
+          "401": {
+            "description": "Unauthorized"
+          }
+        }
+      }
+    },
+    "/api/execute/browser_webmcp_call_tool": {
+      "post": {
+        "summary": "Browser Webmcp Call Tool",
+        "description": "Execute a WebMCP tool that was declared by the page. The tool's execute callback runs in the page's JavaScript context. For declarative form tools, this fills form fields with the input values and submits. Returns the tool's result as JSON. Timeout: 30 seconds.",
+        "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')"
+                  },
+                  "tool_name": {
+                    "type": "string",
+                    "description": "The name of the WebMCP tool to execute (as registered by the page via navigator.modelContext.registerTool)"
+                  },
+                  "input": {
+                    "type": "string",
+                    "description": "JSON object containing input parameters for the tool, matching the tool's inputSchema"
+                  }
+                },
+                "required": [
+                  "context_id",
+                  "tool_name"
+                ]
+              }
+            }
+          }
+        },
+        "responses": {
+          "200": {
+            "description": "Successful response"
+          },
+          "400": {
+            "description": "Bad request"
+          },
+          "401": {
+            "description": "Unauthorized"
+          }
+        }
+      }
+    },
+    "/api/execute/browser_webmcp_refresh_tools": {
+      "post": {
+        "summary": "Browser Webmcp Refresh Tools",
+        "description": "Trigger a re-scan of the page for declarative <form toolname> elements and return the updated tool list. Useful after SPA navigation or dynamic content changes that may have added new form-based tools.",
+        "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')"
+                  }
+                },
+                "required": [
+                  "context_id"
+                ]
+              }
+            }
+          }
+        },
+        "responses": {
+          "200": {
+            "description": "Successful response"
+          },
+          "400": {
+            "description": "Bad request"
+          },
+          "401": {
+            "description": "Unauthorized"
+          }
+        }
+      }
+    },
+    "/api/execute/browser_webmcp_get_all_tools": {
+      "post": {
+        "summary": "Browser Webmcp Get All Tools",
+        "description": "Get all WebMCP tools across all browser contexts. Returns a JSON object keyed by context_id, with each value being an array of tool definitions. Useful for discovering which pages have registered tools without querying each context individually.",
+        "tags": [
+          "General"
+        ],
+        "requestBody": {
+          "required": true,
+          "content": {
+            "application/json": {
+              "schema": {
+                "type": "object",
+                "properties": {}
+              }
+            }
+          }
+        },
+        "responses": {
+          "200": {
+            "description": "Successful response"
+          },
+          "400": {
+            "description": "Bad request"
+          },
+          "401": {
+            "description": "Unauthorized"
+          }
+        }
+      }
     }
   }
 }

package/package.json

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