hyperbrowser 0.1.0__py3-none-any.whl

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/__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/client/async_client.py

@@ -0,0 +1,37 @@
+from typing import Optional
+from ..transport.async_transport import AsyncTransport
+from .base import HyperbrowserBase
+from ..models.session import SessionDetail, Session, 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) -> bool:
+        response = await self.transport.put(self._build_url(f"/session/{id}/stop"))
+        return response.is_success()
+
+    async def get_session_list(self, params: 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()

hyperbrowser/client/base.py

@@ -0,0 +1,28 @@
+from typing import Optional
+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 ValueError("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/client/sync.py

@@ -0,0 +1,37 @@
+from typing import Optional
+from ..transport.sync import SyncTransport
+from .base import HyperbrowserBase
+from ..models.session import SessionDetail, Session, 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) -> bool:
+        response = self.transport.put(self._build_url(f"/session/{id}/stop"))
+        return response.is_success()
+
+    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/config.py

@@ -0,0 +1,18 @@
+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/models/session.py

@@ -0,0 +1,74 @@
+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 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] = None
+    page: int = Field(default=1, ge=1)
+    per_page: int = Field(alias="perPage", default=20, ge=1, le=100)
+
+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/transport/async_transport.py

@@ -0,0 +1,41 @@
+import aiohttp
+from typing import Optional
+from .base import TransportStrategy, APIResponse
+
+class AsyncTransport(TransportStrategy):
+    """Asynchronous transport implementation using aiohttp"""
+    def __init__(self, api_key: str):
+        self.session = aiohttp.ClientSession(headers={"x-api-key": api_key})
+
+    async def close(self) -> None:
+        await self.session.close()
+
+    async def post(self, url: str) -> APIResponse:
+        async with self.session.post(url) as response:
+            response.raise_for_status()
+            try:
+                if response.content_length is None or response.content_length == 0:
+                    return APIResponse.from_status(response.status)
+                return APIResponse(await response.json())
+            except aiohttp.ContentTypeError:
+                return APIResponse.from_status(response.status)
+
+    async def get(self, url: str, params: Optional[dict] = None) -> APIResponse:
+        async with self.session.get(url, params=params) as response:
+            response.raise_for_status()
+            try:
+                if response.content_length is None or response.content_length == 0:
+                    return APIResponse.from_status(response.status)
+                return APIResponse(await response.json())
+            except aiohttp.ContentTypeError:
+                return APIResponse.from_status(response.status)
+
+    async def put(self, url: str) -> APIResponse:
+        async with self.session.put(url) as response:
+            response.raise_for_status()
+            try:
+                if response.content_length is None or response.content_length == 0:
+                    return APIResponse.from_status(response.status)
+                return APIResponse(await response.json())
+            except aiohttp.ContentTypeError:
+                return APIResponse.from_status(response.status)

hyperbrowser/transport/base.py

@@ -0,0 +1,56 @@
+from abc import ABC, abstractmethod
+from typing import Optional, TypeVar, Generic, Type, Union
+
+T = TypeVar('T')
+
+class APIResponse(Generic[T]):
+    """
+    Wrapper for API responses to standardize sync/async handling.
+    
+    Attributes:
+        data: The parsed response data, if any
+        status_code: HTTP status code of the response
+    """
+    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."""
+        return cls(data=model(**json_data))
+
+    @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/transport/sync.py

@@ -0,0 +1,36 @@
+import requests
+from typing import Optional
+from .base import TransportStrategy, APIResponse
+
+class SyncTransport(TransportStrategy):
+    """Synchronous transport implementation using requests"""
+    def __init__(self, api_key: str):
+        self.session = requests.Session()
+        self.session.headers.update({"x-api-key": api_key})
+
+    def close(self) -> None:
+        self.session.close()
+
+    def post(self, url: str) -> APIResponse:
+        response = self.session.post(url)
+        response.raise_for_status()
+        try:
+            return APIResponse(response.json()) if response.content else APIResponse.from_status(response.status_code)
+        except requests.exceptions.JSONDecodeError:
+            return APIResponse.from_status(response.status_code)
+
+    def get(self, url: str, params: Optional[dict] = None) -> APIResponse:
+        response = self.session.get(url, params=params)
+        response.raise_for_status()
+        try:
+            return APIResponse(response.json()) if response.content else APIResponse.from_status(response.status_code)
+        except requests.exceptions.JSONDecodeError:
+            return APIResponse.from_status(response.status_code)
+
+    def put(self, url: str) -> APIResponse:
+        response = self.session.put(url)
+        response.raise_for_status()
+        try:
+            return APIResponse(response.json()) if response.content else APIResponse.from_status(response.status_code)
+        except requests.exceptions.JSONDecodeError:
+            return APIResponse.from_status(response.status_code)

hyperbrowser-0.1.0.dist-info/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.1.0.dist-info/METADATA

@@ -0,0 +1,118 @@
+Metadata-Version: 2.1
+Name: hyperbrowser
+Version: 0.1.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: aiohttp (>=3.11.7,<4.0.0)
+Requires-Dist: pydantic (>=2.10.0,<3.0.0)
+Requires-Dist: requests (>=2.32.3,<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():
+    client = Hyperbrowser(api_key=HYPERBROWSER_API_KEY)
+    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.1.0.dist-info/RECORD

@@ -0,0 +1,14 @@
+LICENSE,sha256=6rUGKlyKb_1ZAH7h7YITYAAUNFN3MNGGKCyfrw49NLE,1071
+hyperbrowser/__init__.py,sha256=cQiqqEJ18tN7L1a6B_ZysI0NuKZwwUjG5r4NOye4z9Y,187
+hyperbrowser/client/async_client.py,sha256=2ftnenY8Qth9BW2GLSFk7OsQQF3lulSrJPymgct3TOY,1442
+hyperbrowser/client/base.py,sha256=eOw_K_TgKyJMb9E4RH65bBS-Uw7fIkdD92-wufw3kVM,1004
+hyperbrowser/client/sync.py,sha256=cVoErVoXIisp555J0vA5K7yyFExB5qBfU4SjVTk5vPk,1362
+hyperbrowser/config.py,sha256=HK35QfVMkt82nbEzYJdf1nuWVLs71HP2vjquzSaD_0w,608
+hyperbrowser/models/session.py,sha256=oxJ7uW1oN_0IoOD8kQEKW790cCyQvS0klz5_W5B4DXw,2271
+hyperbrowser/transport/async_transport.py,sha256=iP2ctyeui0tVgm6Ej4qDlPu1zLhLPQ7XKZ9JmUqOOFw,1872
+hyperbrowser/transport/base.py,sha256=u4eIToyBtzAT8lk3Q-11sHS0xImllafc1QT_FdZos4A,1581
+hyperbrowser/transport/sync.py,sha256=IkZcmmdairQTLJbKQOoNU4sKN2cRYgSL5r0Fx37O6jo,1555
+hyperbrowser-0.1.0.dist-info/LICENSE,sha256=6rUGKlyKb_1ZAH7h7YITYAAUNFN3MNGGKCyfrw49NLE,1071
+hyperbrowser-0.1.0.dist-info/METADATA,sha256=ODvwG95cLhoPa4sV8ueVJodRcBAYiFp3IDwSg_oR1sA,3286
+hyperbrowser-0.1.0.dist-info/WHEEL,sha256=Nq82e9rUAnEjt98J6MlVmMCZb-t9cYE2Ir1kpBmnWfs,88
+hyperbrowser-0.1.0.dist-info/RECORD,,

hyperbrowser-0.1.0.dist-info/WHEEL

@@ -0,0 +1,4 @@
+Wheel-Version: 1.0
+Generator: poetry-core 1.9.1
+Root-Is-Purelib: true
+Tag: py3-none-any