hyperbrowser 0.76.0__tar.gz

hyperbrowser-0.76.0/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2025 S2 Labs Inc.
+
+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.

hyperbrowser-0.76.0/PKG-INFO

@@ -0,0 +1,131 @@
+Metadata-Version: 2.4
+Name: hyperbrowser
+Version: 0.76.0
+Summary: Python SDK for hyperbrowser
+License: MIT
+License-File: LICENSE
+Author: Nikhil Shahi
+Author-email: nshahi1998@gmail.com
+Requires-Python: >=3.8,<4.0
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.8
+Classifier: Programming Language :: Python :: 3.9
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Programming Language :: Python :: 3.14
+Requires-Dist: httpx (>=0.23.0,<1)
+Requires-Dist: jsonref (>=1.1.0)
+Requires-Dist: pydantic (>=2.0,<3)
+Project-URL: Homepage, https://github.com/hyperbrowserai/python-sdk
+Project-URL: Repository, https://github.com/hyperbrowserai/python-sdk
+Description-Content-Type: text/markdown
+
+# Hyperbrowser Python SDK
+
+Checkout the full documentation [here](https://docs.hyperbrowser.ai/)
+
+## Installation
+
+Currently Hyperbrowser supports creating a browser session in two ways:
+
+- Async Client
+- Sync Client
+
+It can be installed from `pypi` by running :
+
+```shell
+pip install hyperbrowser
+```
+
+## Configuration
+
+Both the sync and async client follow similar configuration params
+
+### API Key
+The API key can be configured either from the constructor arguments or environment variables using `HYPERBROWSER_API_KEY`
+
+## Usage
+
+### Async
+
+```python
+import asyncio
+from pyppeteer import connect
+from hyperbrowser import AsyncHyperbrowser
+
+HYPERBROWSER_API_KEY = "test-key"
+
+async def main():
+    async with AsyncHyperbrowser(api_key=HYPERBROWSER_API_KEY) as client:
+        session = await client.sessions.create()
+
+        ws_endpoint = session.ws_endpoint
+        browser = await connect(browserWSEndpoint=ws_endpoint, defaultViewport=None)
+
+        # Get pages
+        pages = await browser.pages()
+        if not pages:
+            raise Exception("No pages available")
+
+        page = pages[0]
+
+        # Navigate to a website
+        print("Navigating to Hacker News...")
+        await page.goto("https://news.ycombinator.com/")
+        page_title = await page.title()
+        print("Page title:", page_title)
+
+        await page.close()
+        await browser.disconnect()
+        await client.sessions.stop(session.id)
+        print("Session completed!")
+
+# Run the asyncio event loop
+asyncio.get_event_loop().run_until_complete(main())
+```
+### Sync
+
+```python
+from playwright.sync_api import sync_playwright
+from hyperbrowser import Hyperbrowser
+
+HYPERBROWSER_API_KEY = "test-key"
+
+def main():
+    client = Hyperbrowser(api_key=HYPERBROWSER_API_KEY)
+    session = client.sessions.create()
+
+    ws_endpoint = session.ws_endpoint
+
+    # Launch Playwright and connect to the remote browser
+    with sync_playwright() as p:
+        browser = p.chromium.connect_over_cdp(ws_endpoint)
+        context = browser.new_context()
+        
+        # Get the first page or create a new one
+        if len(context.pages) == 0:
+            page = context.new_page()
+        else:
+            page = context.pages[0]
+        
+        # Navigate to a website
+        print("Navigating to Hacker News...")
+        page.goto("https://news.ycombinator.com/")
+        page_title = page.title()
+        print("Page title:", page_title)
+        
+        page.close()
+        browser.close()
+        print("Session completed!")
+    client.sessions.stop(session.id)
+
+# Run the asyncio event loop
+main()
+```
+## License
+
+This project is licensed under the MIT License - see the [LICENSE](LICENSE) file for details.
+

hyperbrowser-0.76.0/README.md

@@ -0,0 +1,105 @@
+# Hyperbrowser Python SDK
+
+Checkout the full documentation [here](https://docs.hyperbrowser.ai/)
+
+## Installation
+
+Currently Hyperbrowser supports creating a browser session in two ways:
+
+- Async Client
+- Sync Client
+
+It can be installed from `pypi` by running :
+
+```shell
+pip install hyperbrowser
+```
+
+## Configuration
+
+Both the sync and async client follow similar configuration params
+
+### API Key
+The API key can be configured either from the constructor arguments or environment variables using `HYPERBROWSER_API_KEY`
+
+## Usage
+
+### Async
+
+```python
+import asyncio
+from pyppeteer import connect
+from hyperbrowser import AsyncHyperbrowser
+
+HYPERBROWSER_API_KEY = "test-key"
+
+async def main():
+    async with AsyncHyperbrowser(api_key=HYPERBROWSER_API_KEY) as client:
+        session = await client.sessions.create()
+
+        ws_endpoint = session.ws_endpoint
+        browser = await connect(browserWSEndpoint=ws_endpoint, defaultViewport=None)
+
+        # Get pages
+        pages = await browser.pages()
+        if not pages:
+            raise Exception("No pages available")
+
+        page = pages[0]
+
+        # Navigate to a website
+        print("Navigating to Hacker News...")
+        await page.goto("https://news.ycombinator.com/")
+        page_title = await page.title()
+        print("Page title:", page_title)
+
+        await page.close()
+        await browser.disconnect()
+        await client.sessions.stop(session.id)
+        print("Session completed!")
+
+# Run the asyncio event loop
+asyncio.get_event_loop().run_until_complete(main())
+```
+### Sync
+
+```python
+from playwright.sync_api import sync_playwright
+from hyperbrowser import Hyperbrowser
+
+HYPERBROWSER_API_KEY = "test-key"
+
+def main():
+    client = Hyperbrowser(api_key=HYPERBROWSER_API_KEY)
+    session = client.sessions.create()
+
+    ws_endpoint = session.ws_endpoint
+
+    # Launch Playwright and connect to the remote browser
+    with sync_playwright() as p:
+        browser = p.chromium.connect_over_cdp(ws_endpoint)
+        context = browser.new_context()
+        
+        # Get the first page or create a new one
+        if len(context.pages) == 0:
+            page = context.new_page()
+        else:
+            page = context.pages[0]
+        
+        # Navigate to a website
+        print("Navigating to Hacker News...")
+        page.goto("https://news.ycombinator.com/")
+        page_title = page.title()
+        print("Page title:", page_title)
+        
+        page.close()
+        browser.close()
+        print("Session completed!")
+    client.sessions.stop(session.id)
+
+# Run the asyncio event loop
+main()
+```
+## License
+
+This project is licensed under the MIT License - see the [LICENSE](LICENSE) file for details.

hyperbrowser-0.76.0/hyperbrowser/__init__.py

@@ -0,0 +1,5 @@
+from .client.sync import Hyperbrowser
+from .client.async_client import AsyncHyperbrowser
+from .config import ClientConfig
+
+__all__ = ["Hyperbrowser", "AsyncHyperbrowser", "ClientConfig"]

hyperbrowser-0.76.0/hyperbrowser/client/async_client.py

@@ -0,0 +1,46 @@
+from typing import Optional
+
+from ..config import ClientConfig
+from ..transport.async_transport import AsyncTransport
+from .base import HyperbrowserBase
+from .managers.async_manager.agents import Agents
+from .managers.async_manager.crawl import CrawlManager
+from .managers.async_manager.extension import ExtensionManager
+from .managers.async_manager.extract import ExtractManager
+from .managers.async_manager.profile import ProfileManager
+from .managers.async_manager.scrape import ScrapeManager
+from .managers.async_manager.session import SessionManager
+from .managers.async_manager.team import TeamManager
+from .managers.async_manager.computer_action import ComputerActionManager
+
+
+class AsyncHyperbrowser(HyperbrowserBase):
+    """Asynchronous Hyperbrowser client"""
+
+    def __init__(
+        self,
+        config: Optional[ClientConfig] = None,
+        api_key: Optional[str] = None,
+        base_url: Optional[str] = None,
+        timeout: Optional[int] = 30,
+    ):
+        super().__init__(AsyncTransport, config, api_key, base_url)
+        self.transport.client.timeout = timeout
+        self.sessions = SessionManager(self)
+        self.scrape = ScrapeManager(self)
+        self.crawl = CrawlManager(self)
+        self.extract = ExtractManager(self)
+        self.profiles = ProfileManager(self)
+        self.extensions = ExtensionManager(self)
+        self.agents = Agents(self)
+        self.team = TeamManager(self)
+        self.computer_action = ComputerActionManager(self)
+
+    async def close(self) -> None:
+        await self.transport.close()
+
+    async def __aenter__(self):
+        return self
+
+    async def __aexit__(self, exc_type, exc_val, exc_tb):
+        await self.close()

hyperbrowser-0.76.0/hyperbrowser/client/base.py

@@ -0,0 +1,42 @@
+from typing import Optional
+
+from hyperbrowser.exceptions import HyperbrowserError
+from ..config import ClientConfig
+from ..transport.base import TransportStrategy
+import os
+
+
+class HyperbrowserBase:
+    """Base class with shared functionality for sync/async clients"""
+
+    def __init__(
+        self,
+        transport: TransportStrategy,
+        config: Optional[ClientConfig] = None,
+        api_key: Optional[str] = None,
+        base_url: Optional[str] = None,
+    ):
+        if config is None:
+            config = ClientConfig(
+                api_key=(
+                    api_key
+                    if api_key is not None
+                    else os.environ.get("HYPERBROWSER_API_KEY", "")
+                ),
+                base_url=(
+                    base_url
+                    if base_url is not None
+                    else os.environ.get(
+                        "HYPERBROWSER_BASE_URL", "https://api.hyperbrowser.ai"
+                    )
+                ),
+            )
+
+        if not config.api_key:
+            raise HyperbrowserError("API key must be provided")
+
+        self.config = config
+        self.transport = transport(config.api_key)
+
+    def _build_url(self, path: str) -> str:
+        return f"{self.config.base_url}/api{path}"

hyperbrowser-0.76.0/hyperbrowser/client/managers/async_manager/agents/__init__.py

@@ -0,0 +1,14 @@
+from .browser_use import BrowserUseManager
+from .cua import CuaManager
+from .claude_computer_use import ClaudeComputerUseManager
+from .hyper_agent import HyperAgentManager
+from .gemini_computer_use import GeminiComputerUseManager
+
+
+class Agents:
+    def __init__(self, client):
+        self.browser_use = BrowserUseManager(client)
+        self.cua = CuaManager(client)
+        self.claude_computer_use = ClaudeComputerUseManager(client)
+        self.hyper_agent = HyperAgentManager(client)
+        self.gemini_computer_use = GeminiComputerUseManager(client)

hyperbrowser-0.76.0/hyperbrowser/client/managers/async_manager/agents/browser_use.py

@@ -0,0 +1,79 @@
+import asyncio
+import jsonref
+
+from hyperbrowser.exceptions import HyperbrowserError
+
+from .....models import (
+    POLLING_ATTEMPTS,
+    BasicResponse,
+    BrowserUseTaskResponse,
+    BrowserUseTaskStatusResponse,
+    StartBrowserUseTaskParams,
+    StartBrowserUseTaskResponse,
+)
+
+
+class BrowserUseManager:
+    def __init__(self, client):
+        self._client = client
+
+    async def start(
+        self, params: StartBrowserUseTaskParams
+    ) -> StartBrowserUseTaskResponse:
+        if params.output_model_schema:
+            if hasattr(params.output_model_schema, "model_json_schema"):
+                params.output_model_schema = jsonref.replace_refs(
+                    params.output_model_schema.model_json_schema(),
+                    proxies=False,
+                    lazy_load=False,
+                )
+        response = await self._client.transport.post(
+            self._client._build_url("/task/browser-use"),
+            data=params.model_dump(exclude_none=True, by_alias=True),
+        )
+        return StartBrowserUseTaskResponse(**response.data)
+
+    async def get(self, job_id: str) -> BrowserUseTaskResponse:
+        response = await self._client.transport.get(
+            self._client._build_url(f"/task/browser-use/{job_id}")
+        )
+        return BrowserUseTaskResponse(**response.data)
+
+    async def get_status(self, job_id: str) -> BrowserUseTaskStatusResponse:
+        response = await self._client.transport.get(
+            self._client._build_url(f"/task/browser-use/{job_id}/status")
+        )
+        return BrowserUseTaskStatusResponse(**response.data)
+
+    async def stop(self, job_id: str) -> BasicResponse:
+        response = await self._client.transport.put(
+            self._client._build_url(f"/task/browser-use/{job_id}/stop")
+        )
+        return BasicResponse(**response.data)
+
+    async def start_and_wait(
+        self, params: StartBrowserUseTaskParams
+    ) -> BrowserUseTaskResponse:
+        job_start_resp = await self.start(params)
+        job_id = job_start_resp.job_id
+        if not job_id:
+            raise HyperbrowserError("Failed to start browser-use task job")
+
+        failures = 0
+        while True:
+            try:
+                job_response = await self.get_status(job_id)
+                if (
+                    job_response.status == "completed"
+                    or job_response.status == "failed"
+                    or job_response.status == "stopped"
+                ):
+                    return await self.get(job_id)
+                failures = 0
+            except Exception as e:
+                failures += 1
+                if failures >= POLLING_ATTEMPTS:
+                    raise HyperbrowserError(
+                        f"Failed to poll browser-use task job {job_id} after {POLLING_ATTEMPTS} attempts: {e}"
+                    )
+            await asyncio.sleep(2)

hyperbrowser-0.76.0/hyperbrowser/client/managers/async_manager/agents/claude_computer_use.py

@@ -0,0 +1,71 @@
+import asyncio
+
+from hyperbrowser.exceptions import HyperbrowserError
+
+from .....models import (
+    POLLING_ATTEMPTS,
+    BasicResponse,
+    ClaudeComputerUseTaskResponse,
+    ClaudeComputerUseTaskStatusResponse,
+    StartClaudeComputerUseTaskParams,
+    StartClaudeComputerUseTaskResponse,
+)
+
+
+class ClaudeComputerUseManager:
+    def __init__(self, client):
+        self._client = client
+
+    async def start(
+        self, params: StartClaudeComputerUseTaskParams
+    ) -> StartClaudeComputerUseTaskResponse:
+        response = await self._client.transport.post(
+            self._client._build_url("/task/claude-computer-use"),
+            data=params.model_dump(exclude_none=True, by_alias=True),
+        )
+        return StartClaudeComputerUseTaskResponse(**response.data)
+
+    async def get(self, job_id: str) -> ClaudeComputerUseTaskResponse:
+        response = await self._client.transport.get(
+            self._client._build_url(f"/task/claude-computer-use/{job_id}")
+        )
+        return ClaudeComputerUseTaskResponse(**response.data)
+
+    async def get_status(self, job_id: str) -> ClaudeComputerUseTaskStatusResponse:
+        response = await self._client.transport.get(
+            self._client._build_url(f"/task/claude-computer-use/{job_id}/status")
+        )
+        return ClaudeComputerUseTaskStatusResponse(**response.data)
+
+    async def stop(self, job_id: str) -> BasicResponse:
+        response = await self._client.transport.put(
+            self._client._build_url(f"/task/claude-computer-use/{job_id}/stop")
+        )
+        return BasicResponse(**response.data)
+
+    async def start_and_wait(
+        self, params: StartClaudeComputerUseTaskParams
+    ) -> ClaudeComputerUseTaskResponse:
+        job_start_resp = await self.start(params)
+        job_id = job_start_resp.job_id
+        if not job_id:
+            raise HyperbrowserError("Failed to start Claude Computer Use task job")
+
+        failures = 0
+        while True:
+            try:
+                job_response = await self.get_status(job_id)
+                if (
+                    job_response.status == "completed"
+                    or job_response.status == "failed"
+                    or job_response.status == "stopped"
+                ):
+                    return await self.get(job_id)
+                failures = 0
+            except Exception as e:
+                failures += 1
+                if failures >= POLLING_ATTEMPTS:
+                    raise HyperbrowserError(
+                        f"Failed to poll Claude Computer Use task job {job_id} after {POLLING_ATTEMPTS} attempts: {e}"
+                    )
+            await asyncio.sleep(2)

hyperbrowser-0.76.0/hyperbrowser/client/managers/async_manager/agents/cua.py

@@ -0,0 +1,67 @@
+import asyncio
+
+from hyperbrowser.exceptions import HyperbrowserError
+
+from .....models import (
+    POLLING_ATTEMPTS,
+    BasicResponse,
+    CuaTaskResponse,
+    CuaTaskStatusResponse,
+    StartCuaTaskParams,
+    StartCuaTaskResponse,
+)
+
+
+class CuaManager:
+    def __init__(self, client):
+        self._client = client
+
+    async def start(self, params: StartCuaTaskParams) -> StartCuaTaskResponse:
+        response = await self._client.transport.post(
+            self._client._build_url("/task/cua"),
+            data=params.model_dump(exclude_none=True, by_alias=True),
+        )
+        return StartCuaTaskResponse(**response.data)
+
+    async def get(self, job_id: str) -> CuaTaskResponse:
+        response = await self._client.transport.get(
+            self._client._build_url(f"/task/cua/{job_id}")
+        )
+        return CuaTaskResponse(**response.data)
+
+    async def get_status(self, job_id: str) -> CuaTaskStatusResponse:
+        response = await self._client.transport.get(
+            self._client._build_url(f"/task/cua/{job_id}/status")
+        )
+        return CuaTaskStatusResponse(**response.data)
+
+    async def stop(self, job_id: str) -> BasicResponse:
+        response = await self._client.transport.put(
+            self._client._build_url(f"/task/cua/{job_id}/stop")
+        )
+        return BasicResponse(**response.data)
+
+    async def start_and_wait(self, params: StartCuaTaskParams) -> CuaTaskResponse:
+        job_start_resp = await self.start(params)
+        job_id = job_start_resp.job_id
+        if not job_id:
+            raise HyperbrowserError("Failed to start CUA task job")
+
+        failures = 0
+        while True:
+            try:
+                job_response = await self.get_status(job_id)
+                if (
+                    job_response.status == "completed"
+                    or job_response.status == "failed"
+                    or job_response.status == "stopped"
+                ):
+                    return await self.get(job_id)
+                failures = 0
+            except Exception as e:
+                failures += 1
+                if failures >= POLLING_ATTEMPTS:
+                    raise HyperbrowserError(
+                        f"Failed to poll CUA task job {job_id} after {POLLING_ATTEMPTS} attempts: {e}"
+                    )
+            await asyncio.sleep(2)

hyperbrowser-0.76.0/hyperbrowser/client/managers/async_manager/agents/gemini_computer_use.py

@@ -0,0 +1,71 @@
+import asyncio
+
+from hyperbrowser.exceptions import HyperbrowserError
+
+from .....models import (
+    POLLING_ATTEMPTS,
+    BasicResponse,
+    GeminiComputerUseTaskResponse,
+    GeminiComputerUseTaskStatusResponse,
+    StartGeminiComputerUseTaskParams,
+    StartGeminiComputerUseTaskResponse,
+)
+
+
+class GeminiComputerUseManager:
+    def __init__(self, client):
+        self._client = client
+
+    async def start(
+        self, params: StartGeminiComputerUseTaskParams
+    ) -> StartGeminiComputerUseTaskResponse:
+        response = await self._client.transport.post(
+            self._client._build_url("/task/gemini-computer-use"),
+            data=params.model_dump(exclude_none=True, by_alias=True),
+        )
+        return StartGeminiComputerUseTaskResponse(**response.data)
+
+    async def get(self, job_id: str) -> GeminiComputerUseTaskResponse:
+        response = await self._client.transport.get(
+            self._client._build_url(f"/task/gemini-computer-use/{job_id}")
+        )
+        return GeminiComputerUseTaskResponse(**response.data)
+
+    async def get_status(self, job_id: str) -> GeminiComputerUseTaskStatusResponse:
+        response = await self._client.transport.get(
+            self._client._build_url(f"/task/gemini-computer-use/{job_id}/status")
+        )
+        return GeminiComputerUseTaskStatusResponse(**response.data)
+
+    async def stop(self, job_id: str) -> BasicResponse:
+        response = await self._client.transport.put(
+            self._client._build_url(f"/task/gemini-computer-use/{job_id}/stop")
+        )
+        return BasicResponse(**response.data)
+
+    async def start_and_wait(
+        self, params: StartGeminiComputerUseTaskParams
+    ) -> GeminiComputerUseTaskResponse:
+        job_start_resp = await self.start(params)
+        job_id = job_start_resp.job_id
+        if not job_id:
+            raise HyperbrowserError("Failed to start Gemini Computer Use task job")
+
+        failures = 0
+        while True:
+            try:
+                job_response = await self.get_status(job_id)
+                if (
+                    job_response.status == "completed"
+                    or job_response.status == "failed"
+                    or job_response.status == "stopped"
+                ):
+                    return await self.get(job_id)
+                failures = 0
+            except Exception as e:
+                failures += 1
+                if failures >= POLLING_ATTEMPTS:
+                    raise HyperbrowserError(
+                        f"Failed to poll Gemini Computer Use task job {job_id} after {POLLING_ATTEMPTS} attempts: {e}"
+                    )
+            await asyncio.sleep(2)