hyperbrowser 0.3.0__tar.gz

hyperbrowser-0.3.0/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2024 hyperbrowserai
+
+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.3.0/PKG-INFO

@@ -0,0 +1,117 @@
+Metadata-Version: 2.1
+Name: hyperbrowser
+Version: 0.3.0
+Summary: Python SDK for hyperbrowser
+Home-page: https://github.com/hyperbrowserai/python-sdk
+License: MIT
+Author: Nikhil Shahi
+Author-email: nshahi1998@gmail.com
+Requires-Python: >=3.9,<4.0
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Programming Language :: Python :: 3
+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
+Requires-Dist: httpx (>=0.28.0,<0.29.0)
+Requires-Dist: pydantic (>=2.10.0,<3.0.0)
+Project-URL: Repository, https://github.com/hyperbrowserai/python-sdk
+Description-Content-Type: text/markdown
+
+## 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.client.async_client import AsyncHyperbrowser as Hyperbrowser
+
+HYPERBROWSER_API_KEY = "test-key"
+
+async def main():
+    async with Hyperbrowser(api_key=HYPERBROWSER_API_KEY) as client:
+        session = await client.create_session()
+
+        ws_endpoint = f"{session.websocket_url}&apiKey={HYPERBROWSER_API_KEY}"
+        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()
+        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.client.sync import Hyperbrowser
+
+HYPERBROWSER_API_KEY = "test-key"
+
+def main():
+    client = Hyperbrowser(api_key=HYPERBROWSER_API_KEY)
+    session = client.create_session()
+
+    ws_endpoint = f"{session.websocket_url}&apiKey={HYPERBROWSER_API_KEY}"
+
+    # 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!")
+
+# Run the asyncio event loop
+main()
+```

hyperbrowser-0.3.0/README.md

@@ -0,0 +1,96 @@
+## 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.client.async_client import AsyncHyperbrowser as Hyperbrowser
+
+HYPERBROWSER_API_KEY = "test-key"
+
+async def main():
+    async with Hyperbrowser(api_key=HYPERBROWSER_API_KEY) as client:
+        session = await client.create_session()
+
+        ws_endpoint = f"{session.websocket_url}&apiKey={HYPERBROWSER_API_KEY}"
+        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()
+        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.client.sync import Hyperbrowser
+
+HYPERBROWSER_API_KEY = "test-key"
+
+def main():
+    client = Hyperbrowser(api_key=HYPERBROWSER_API_KEY)
+    session = client.create_session()
+
+    ws_endpoint = f"{session.websocket_url}&apiKey={HYPERBROWSER_API_KEY}"
+
+    # 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!")
+
+# Run the asyncio event loop
+main()
+```

hyperbrowser-0.3.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.3.0/hyperbrowser/client/async_client.py

@@ -0,0 +1,51 @@
+from typing import Optional
+from ..transport.async_transport import AsyncTransport
+from .base import HyperbrowserBase
+from ..models.session import (
+    BasicResponse,
+    SessionDetail,
+    SessionListParams,
+    SessionListResponse,
+)
+from ..config import ClientConfig
+
+
+class AsyncHyperbrowser(HyperbrowserBase):
+    """Asynchronous Hyperbrowser client"""
+
+    def __init__(
+        self,
+        config: Optional[ClientConfig] = None,
+        api_key: Optional[str] = None,
+        base_url: Optional[str] = None,
+    ):
+        super().__init__(AsyncTransport, config, api_key, base_url)
+
+    async def create_session(self) -> SessionDetail:
+        response = await self.transport.post(self._build_url("/session"))
+        return SessionDetail(**response.data)
+
+    async def get_session(self, id: str) -> SessionDetail:
+        response = await self.transport.get(self._build_url(f"/session/{id}"))
+        return SessionDetail(**response.data)
+
+    async def stop_session(self, id: str) -> BasicResponse:
+        response = await self.transport.put(self._build_url(f"/session/{id}/stop"))
+        return BasicResponse(**response.data)
+
+    async def get_session_list(
+        self, params: SessionListParams = SessionListParams()
+    ) -> SessionListResponse:
+        response = await self.transport.get(
+            self._build_url("/sessions"), params=params.__dict__
+        )
+        return SessionListResponse(**response.data)
+
+    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.3.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://app.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.3.0/hyperbrowser/client/sync.py

@@ -0,0 +1,43 @@
+from typing import Optional
+from ..transport.sync import SyncTransport
+from .base import HyperbrowserBase
+from ..models.session import (
+    BasicResponse,
+    SessionDetail,
+    SessionListParams,
+    SessionListResponse,
+)
+from ..config import ClientConfig
+
+
+class Hyperbrowser(HyperbrowserBase):
+    """Synchronous Hyperbrowser client"""
+
+    def __init__(
+        self,
+        config: Optional[ClientConfig] = None,
+        api_key: Optional[str] = None,
+        base_url: Optional[str] = None,
+    ):
+        super().__init__(SyncTransport, config, api_key, base_url)
+
+    def create_session(self) -> SessionDetail:
+        response = self.transport.post(self._build_url("/session"))
+        return SessionDetail(**response.data)
+
+    def get_session(self, id: str) -> SessionDetail:
+        response = self.transport.get(self._build_url(f"/session/{id}"))
+        return SessionDetail(**response.data)
+
+    def stop_session(self, id: str) -> BasicResponse:
+        response = self.transport.put(self._build_url(f"/session/{id}/stop"))
+        return BasicResponse(**response.data)
+
+    def get_session_list(self, params: SessionListParams) -> SessionListResponse:
+        response = self.transport.get(
+            self._build_url("/sessions"), params=params.__dict__
+        )
+        return SessionListResponse(**response.data)
+
+    def close(self) -> None:
+        self.transport.close()

hyperbrowser-0.3.0/hyperbrowser/config.py

@@ -0,0 +1,22 @@
+from dataclasses import dataclass
+from typing import Optional
+import os
+
+
+@dataclass
+class ClientConfig:
+    """Configuration for the Hyperbrowser client"""
+
+    api_key: str
+    base_url: str = "https://api.hyperbrowser.com"
+
+    @classmethod
+    def from_env(cls) -> "ClientConfig":
+        api_key = os.environ.get("HYPERBROWSER_API_KEY")
+        if api_key is None:
+            raise ValueError("HYPERBROWSER_API_KEY environment variable is required")
+
+        base_url = os.environ.get(
+            "HYPERBROWSER_BASE_URL", "https://api.hyperbrowser.com"
+        )
+        return cls(api_key=api_key, base_url=base_url)

hyperbrowser-0.3.0/hyperbrowser/exceptions.py

@@ -0,0 +1,38 @@
+# exceptions.py
+from typing import Optional, Any
+
+
+class HyperbrowserError(Exception):
+    """Base exception class for Hyperbrowser SDK errors"""
+
+    def __init__(
+        self,
+        message: str,
+        status_code: Optional[int] = None,
+        response: Optional[Any] = None,
+        original_error: Optional[Exception] = None,
+    ):
+        super().__init__(message)
+        self.status_code = status_code
+        self.response = response
+        self.original_error = original_error
+
+    def __str__(self) -> str:
+        """Custom string representation to show a cleaner error message"""
+        parts = [f"{self.args[0]}"]
+
+        if self.status_code:
+            parts.append(f"Status: {self.status_code}")
+
+        if self.original_error and not isinstance(
+            self.original_error, HyperbrowserError
+        ):
+            error_type = type(self.original_error).__name__
+            error_msg = str(self.original_error)
+            if error_msg and error_msg != str(self.args[0]):
+                parts.append(f"Caused by {error_type}: {error_msg}")
+
+        return " - ".join(parts)
+
+    def __repr__(self) -> str:
+        return self.__str__()

hyperbrowser-0.3.0/hyperbrowser/models/session.py

@@ -0,0 +1,89 @@
+from typing import List, Literal, Optional, Union
+from datetime import datetime
+from pydantic import BaseModel, Field, ConfigDict, field_validator
+
+SessionStatus = Literal["active", "closed", "error"]
+
+
+class BasicResponse(BaseModel):
+    """
+    Represents a basic Hyperbrowser response.
+    """
+
+    success: bool
+
+
+class Session(BaseModel):
+    """
+    Represents a basic session in the Hyperbrowser system.
+    """
+
+    model_config = ConfigDict(
+        populate_by_alias=True,
+    )
+
+    id: str
+    team_id: str = Field(alias="teamId")
+    status: SessionStatus
+    created_at: datetime = Field(alias="createdAt")
+    updated_at: datetime = Field(alias="updatedAt")
+    start_time: Optional[int] = Field(default=None, alias="startTime")
+    end_time: Optional[int] = Field(default=None, alias="endTime")
+    duration: Optional[int] = None
+    session_url: str = Field(alias="sessionUrl")
+
+    @field_validator("start_time", "end_time", mode="before")
+    @classmethod
+    def parse_timestamp(cls, value: Optional[Union[str, int]]) -> Optional[int]:
+        """Convert string timestamps to integers."""
+        if value is None:
+            return None
+        if isinstance(value, str):
+            return int(value)
+        return value
+
+
+class SessionDetail(Session):
+    """
+    Detailed session information including websocket endpoint.
+    """
+
+    websocket_url: Optional[str] = Field(alias="wsEndpoint", default=None)
+
+
+class SessionListParams(BaseModel):
+    """
+    Parameters for listing sessions.
+    """
+
+    model_config = ConfigDict(
+        populate_by_alias=True,
+    )
+
+    status: Optional[SessionStatus] = Field(default=None, exclude=None)
+    page: int = Field(default=1, ge=1)
+
+
+class SessionListResponse(BaseModel):
+    """
+    Response containing a list of sessions with pagination information.
+    """
+
+    model_config = ConfigDict(
+        populate_by_alias=True,
+    )
+
+    sessions: List[Session]
+    total_count: int = Field(alias="totalCount")
+    page: int
+    per_page: int = Field(alias="perPage")
+
+    @property
+    def has_more(self) -> bool:
+        """Check if there are more pages available."""
+        return self.total_count > (self.page * self.per_page)
+
+    @property
+    def total_pages(self) -> int:
+        """Calculate the total number of pages."""
+        return -(-self.total_count // self.per_page)

hyperbrowser-0.3.0/hyperbrowser/transport/async_transport.py

@@ -0,0 +1,96 @@
+import asyncio
+import httpx
+from typing import Optional
+
+from hyperbrowser.exceptions import HyperbrowserError
+from .base import TransportStrategy, APIResponse
+
+
+class AsyncTransport(TransportStrategy):
+    """Asynchronous transport implementation using httpx"""
+
+    def __init__(self, api_key: str):
+        self.client = httpx.AsyncClient(headers={"x-api-key": api_key})
+        self._closed = False
+
+    async def close(self) -> None:
+        if not self._closed:
+            self._closed = True
+            await self.client.aclose()
+
+    async def __aenter__(self):
+        return self
+
+    async def __aexit__(self, exc_type, exc_val, exc_tb):
+        await self.close()
+
+    def __del__(self):
+        if not self._closed:
+            try:
+                loop = asyncio.get_event_loop()
+                if loop.is_running():
+                    loop.create_task(self.client.aclose())
+                else:
+                    loop.run_until_complete(self.client.aclose())
+            except Exception:
+                pass
+
+    async def _handle_response(self, response: httpx.Response) -> APIResponse:
+        try:
+            response.raise_for_status()
+            try:
+                if not response.content:
+                    return APIResponse.from_status(response.status_code)
+                return APIResponse(response.json())
+            except httpx.DecodingError as e:
+                if response.status_code >= 400:
+                    raise HyperbrowserError(
+                        response.text or "Unknown error occurred",
+                        status_code=response.status_code,
+                        response=response,
+                        original_error=e,
+                    )
+                return APIResponse.from_status(response.status_code)
+        except httpx.HTTPStatusError as e:
+            try:
+                error_data = response.json()
+                message = error_data.get("message") or error_data.get("error") or str(e)
+            except:
+                message = str(e)
+            raise HyperbrowserError(
+                message,
+                status_code=response.status_code,
+                response=response,
+                original_error=e,
+            )
+        except httpx.RequestError as e:
+            raise HyperbrowserError("Request failed", original_error=e)
+
+    async def post(self, url: str) -> APIResponse:
+        try:
+            response = await self.client.post(url)
+            return await self._handle_response(response)
+        except HyperbrowserError:
+            raise
+        except Exception as e:
+            raise HyperbrowserError("Post request failed", original_error=e)
+
+    async def get(self, url: str, params: Optional[dict] = None) -> APIResponse:
+        if params:
+            params = {k: v for k, v in params.items() if v is not None}
+        try:
+            response = await self.client.get(url, params=params)
+            return await self._handle_response(response)
+        except HyperbrowserError:
+            raise
+        except Exception as e:
+            raise HyperbrowserError("Get request failed", original_error=e)
+
+    async def put(self, url: str) -> APIResponse:
+        try:
+            response = await self.client.put(url)
+            return await self._handle_response(response)
+        except HyperbrowserError:
+            raise
+        except Exception as e:
+            raise HyperbrowserError("Put request failed", original_error=e)

hyperbrowser-0.3.0/hyperbrowser/transport/base.py

@@ -0,0 +1,57 @@
+from abc import ABC, abstractmethod
+from typing import Optional, TypeVar, Generic, Type, Union
+
+from hyperbrowser.exceptions import HyperbrowserError
+
+T = TypeVar("T")
+
+
+class APIResponse(Generic[T]):
+    """
+    Wrapper for API responses to standardize sync/async handling.
+    """
+
+    def __init__(self, data: Optional[Union[dict, T]] = None, status_code: int = 200):
+        self.data = data
+        self.status_code = status_code
+
+    @classmethod
+    def from_json(cls, json_data: dict, model: Type[T]) -> "APIResponse[T]":
+        """Create an APIResponse from JSON data with a specific model."""
+        try:
+            return cls(data=model(**json_data))
+        except Exception as e:
+            raise HyperbrowserError("Failed to parse response data", original_error=e)
+
+    @classmethod
+    def from_status(cls, status_code: int) -> "APIResponse[None]":
+        """Create an APIResponse from just a status code."""
+        return cls(data=None, status_code=status_code)
+
+    def is_success(self) -> bool:
+        """Check if the response indicates success."""
+        return 200 <= self.status_code < 300
+
+
+class TransportStrategy(ABC):
+    """Abstract base class for different transport implementations"""
+
+    @abstractmethod
+    def __init__(self, api_key: str):
+        pass
+
+    @abstractmethod
+    def close(self) -> None:
+        pass
+
+    @abstractmethod
+    def post(self, url: str) -> APIResponse:
+        pass
+
+    @abstractmethod
+    def get(self, url: str, params: Optional[dict] = None) -> APIResponse:
+        pass
+
+    @abstractmethod
+    def put(self, url: str) -> APIResponse:
+        pass

hyperbrowser-0.3.0/hyperbrowser/transport/sync.py

@@ -0,0 +1,75 @@
+import httpx
+from typing import Optional
+
+from hyperbrowser.exceptions import HyperbrowserError
+from .base import TransportStrategy, APIResponse
+
+
+class SyncTransport(TransportStrategy):
+    """Synchronous transport implementation using httpx"""
+
+    def __init__(self, api_key: str):
+        self.client = httpx.Client(headers={"x-api-key": api_key})
+
+    def _handle_response(self, response: httpx.Response) -> APIResponse:
+        try:
+            response.raise_for_status()
+            try:
+                if not response.content:
+                    return APIResponse.from_status(response.status_code)
+                return APIResponse(response.json())
+            except httpx.DecodingError as e:
+                if response.status_code >= 400:
+                    raise HyperbrowserError(
+                        response.text or "Unknown error occurred",
+                        status_code=response.status_code,
+                        response=response,
+                        original_error=e,
+                    )
+                return APIResponse.from_status(response.status_code)
+        except httpx.HTTPStatusError as e:
+            try:
+                error_data = response.json()
+                message = error_data.get("message") or error_data.get("error") or str(e)
+            except:
+                message = str(e)
+            raise HyperbrowserError(
+                message,
+                status_code=response.status_code,
+                response=response,
+                original_error=e,
+            )
+        except httpx.RequestError as e:
+            raise HyperbrowserError("Request failed", original_error=e)
+
+    def close(self) -> None:
+        self.client.close()
+
+    def post(self, url: str) -> APIResponse:
+        try:
+            response = self.client.post(url)
+            return self._handle_response(response)
+        except HyperbrowserError:
+            raise
+        except Exception as e:
+            raise HyperbrowserError("Post request failed", original_error=e)
+
+    def get(self, url: str, params: Optional[dict] = None) -> APIResponse:
+        if params:
+            params = {k: v for k, v in params.items() if v is not None}
+        try:
+            response = self.client.get(url, params=params)
+            return self._handle_response(response)
+        except HyperbrowserError:
+            raise
+        except Exception as e:
+            raise HyperbrowserError("Get request failed", original_error=e)
+
+    def put(self, url: str) -> APIResponse:
+        try:
+            response = self.client.put(url)
+            return self._handle_response(response)
+        except HyperbrowserError:
+            raise
+        except Exception as e:
+            raise HyperbrowserError("Put request failed", original_error=e)

hyperbrowser-0.3.0/pyproject.toml

@@ -0,0 +1,23 @@
+[tool.poetry]
+name = "hyperbrowser"
+version = "0.3.0"
+description = "Python SDK for hyperbrowser"
+authors = ["Nikhil Shahi <nshahi1998@gmail.com>"]
+license = "MIT"
+readme = "README.md"
+include = ["LICENSE"]
+homepage = "https://github.com/hyperbrowserai/python-sdk"
+repository = "https://github.com/hyperbrowserai/python-sdk"
+
+[tool.poetry.dependencies]
+python = "^3.9"
+pydantic = "^2.10.0"
+httpx = "^0.28.0"
+
+
+[tool.poetry.group.dev.dependencies]
+black = "^24.10.0"
+
+[build-system]
+requires = ["poetry-core"]
+build-backend = "poetry.core.masonry.api"