hyperbrowser 0.1.0__tar.gz → 0.2.0__tar.gz

{hyperbrowser-0.1.0 → hyperbrowser-0.2.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.1
 Name: hyperbrowser
-Version: 0.1.0
+Version: 0.2.0
 Summary: Python SDK for hyperbrowser
 Home-page: https://github.com/hyperbrowserai/python-sdk
 License: MIT
@@ -52,28 +52,28 @@ 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()
+    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)
+        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")
+        # Get pages
+        pages = await browser.pages()
+        if not pages:
+            raise Exception("No pages available")
 
-    page = pages[0]
+        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)
+        # 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!")
+        await page.close()
+        await browser.disconnect()
+        print("Session completed!")
 
 # Run the asyncio event loop
 asyncio.get_event_loop().run_until_complete(main())

{hyperbrowser-0.1.0 → hyperbrowser-0.2.0}/README.md

@@ -30,28 +30,28 @@ 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()
+    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)
+        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")
+        # Get pages
+        pages = await browser.pages()
+        if not pages:
+            raise Exception("No pages available")
 
-    page = pages[0]
+        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)
+        # 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!")
+        await page.close()
+        await browser.disconnect()
+        print("Session completed!")
 
 # Run the asyncio event loop
 asyncio.get_event_loop().run_until_complete(main())

{hyperbrowser-0.1.0 → hyperbrowser-0.2.0}/hyperbrowser/__init__.py

@@ -2,4 +2,4 @@ from .client.sync import Hyperbrowser
 from .client.async_client import AsyncHyperbrowser
 from .config import ClientConfig
 
-__all__ = ['Hyperbrowser', 'AsyncHyperbrowser', 'ClientConfig']
+__all__ = ["Hyperbrowser", "AsyncHyperbrowser", "ClientConfig"]

{hyperbrowser-0.1.0 → hyperbrowser-0.2.0}/hyperbrowser/client/async_client.py

@@ -1,11 +1,18 @@
 from typing import Optional
 from ..transport.async_transport import AsyncTransport
 from .base import HyperbrowserBase
-from ..models.session import SessionDetail, Session, SessionListParams, SessionListResponse
+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,
@@ -22,16 +29,23 @@ class AsyncHyperbrowser(HyperbrowserBase):
         response = await self.transport.get(self._build_url(f"/session/{id}"))
         return SessionDetail(**response.data)
 
-    async def stop_session(self, id: str) -> bool:
+    async def stop_session(self, id: str) -> BasicResponse:
         response = await self.transport.put(self._build_url(f"/session/{id}/stop"))
-        return response.is_success()
+        return BasicResponse(**response.data)
 
-    async def get_session_list(self, params: SessionListParams) -> SessionListResponse:
+    async def get_session_list(
+        self, params: SessionListParams = SessionListParams()
+    ) -> SessionListResponse:
         response = await self.transport.get(
-            self._build_url("/sessions"),
-            params=params.__dict__
+            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.1.0 → hyperbrowser-0.2.0}/hyperbrowser/client/base.py

@@ -1,10 +1,14 @@
 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,
@@ -14,15 +18,25 @@ class HyperbrowserBase:
     ):
         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")
+                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")
+            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}"
+        return f"{self.config.base_url}/api{path}"

{hyperbrowser-0.1.0 → hyperbrowser-0.2.0}/hyperbrowser/client/sync.py

@@ -1,11 +1,18 @@
 from typing import Optional
 from ..transport.sync import SyncTransport
 from .base import HyperbrowserBase
-from ..models.session import SessionDetail, Session, SessionListParams, SessionListResponse
+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,
@@ -22,16 +29,15 @@ class Hyperbrowser(HyperbrowserBase):
         response = self.transport.get(self._build_url(f"/session/{id}"))
         return SessionDetail(**response.data)
 
-    def stop_session(self, id: str) -> bool:
+    def stop_session(self, id: str) -> BasicResponse:
         response = self.transport.put(self._build_url(f"/session/{id}/stop"))
-        return response.is_success()
+        return BasicResponse(**response.data)
 
     def get_session_list(self, params: SessionListParams) -> SessionListResponse:
         response = self.transport.get(
-            self._build_url("/sessions"),
-            params=params.__dict__
+            self._build_url("/sessions"), params=params.__dict__
         )
         return SessionListResponse(**response.data)
 
     def close(self) -> None:
-        self.transport.close()
+        self.transport.close()

{hyperbrowser-0.1.0 → hyperbrowser-0.2.0}/hyperbrowser/config.py

@@ -2,17 +2,21 @@ 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':
+    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)
+
+        base_url = os.environ.get(
+            "HYPERBROWSER_BASE_URL", "https://api.hyperbrowser.com"
+        )
+        return cls(api_key=api_key, base_url=base_url)

hyperbrowser-0.2.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.1.0 → hyperbrowser-0.2.0}/hyperbrowser/models/session.py

@@ -4,10 +4,20 @@ 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,
     )
@@ -22,7 +32,7 @@ class Session(BaseModel):
     duration: Optional[int] = None
     session_url: str = Field(alias="sessionUrl")
 
-    @field_validator('start_time', 'end_time', mode='before')
+    @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."""
@@ -32,28 +42,33 @@ class Session(BaseModel):
             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
+    status: Optional[SessionStatus] = Field(default=None, exclude=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,
     )
@@ -71,4 +86,4 @@ class SessionListResponse(BaseModel):
     @property
     def total_pages(self) -> int:
         """Calculate the total number of pages."""
-        return -(-self.total_count // self.per_page)
+        return -(-self.total_count // self.per_page)

hyperbrowser-0.2.0/hyperbrowser/transport/async_transport.py

@@ -0,0 +1,97 @@
+import asyncio
+import aiohttp
+from typing import Optional
+
+from hyperbrowser.exceptions import HyperbrowserError
+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})
+        self._closed = False
+
+    async def close(self) -> None:
+        if not self._closed and not self.session.closed:
+            self._closed = True
+            await self.session.close()
+
+    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 and not self.session.closed:
+            try:
+                loop = asyncio.get_event_loop()
+                if loop.is_running():
+                    loop.create_task(self.session.close())
+                else:
+                    loop.run_until_complete(self.session.close())
+            except Exception:
+                pass
+
+    async def _handle_response(self, response: aiohttp.ClientResponse) -> APIResponse:
+        try:
+            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 as e:
+                if response.status >= 400:
+                    text = await response.text()
+                    raise HyperbrowserError(
+                        text or "Unknown error occurred",
+                        status_code=response.status,
+                        response=response,
+                        original_error=e,
+                    )
+                return APIResponse.from_status(response.status)
+        except aiohttp.ClientResponseError as e:
+            try:
+                error_data = await 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,
+                response=response,
+                original_error=e,
+            )
+        except aiohttp.ClientError as e:
+            raise HyperbrowserError("Request failed", original_error=e)
+
+    async def post(self, url: str) -> APIResponse:
+        try:
+            async with self.session.post(url) as response:
+                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:
+            async with self.session.get(url, params=params) as response:
+                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:
+            async with self.session.put(url) as response:
+                return await self._handle_response(response)
+        except HyperbrowserError:
+            raise
+        except Exception as e:
+            raise HyperbrowserError("Put request failed", original_error=e)

{hyperbrowser-0.1.0 → hyperbrowser-0.2.0}/hyperbrowser/transport/base.py

@@ -1,31 +1,30 @@
 from abc import ABC, abstractmethod
 from typing import Optional, TypeVar, Generic, Type, Union
 
-T = TypeVar('T')
+from hyperbrowser.exceptions import HyperbrowserError
+
+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
-    ):
+
+    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]':
+    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))
+        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]':
+    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)
 
@@ -33,8 +32,10 @@ class APIResponse(Generic[T]):
         """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
@@ -53,4 +54,4 @@ class TransportStrategy(ABC):
 
     @abstractmethod
     def put(self, url: str) -> APIResponse:
-        pass
+        pass

hyperbrowser-0.2.0/hyperbrowser/transport/sync.py

@@ -0,0 +1,76 @@
+import requests
+from typing import Optional
+
+from hyperbrowser.exceptions import HyperbrowserError
+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 _handle_response(self, response: requests.Response) -> APIResponse:
+        try:
+            response.raise_for_status()
+            try:
+                if not response.content:
+                    return APIResponse.from_status(response.status_code)
+                return APIResponse(response.json())
+            except requests.exceptions.JSONDecodeError 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 requests.exceptions.HTTPError 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 requests.RequestException as e:
+            raise HyperbrowserError("Request failed", original_error=e)
+
+    def close(self) -> None:
+        self.session.close()
+
+    def post(self, url: str) -> APIResponse:
+        try:
+            response = self.session.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.session.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.session.put(url)
+            return self._handle_response(response)
+        except HyperbrowserError:
+            raise
+        except Exception as e:
+            raise HyperbrowserError("Put request failed", original_error=e)

{hyperbrowser-0.1.0 → hyperbrowser-0.2.0}/pyproject.toml

@@ -1,6 +1,6 @@
 [tool.poetry]
 name = "hyperbrowser"
-version = "0.1.0"
+version = "0.2.0"
 description = "Python SDK for hyperbrowser"
 authors = ["Nikhil Shahi <nshahi1998@gmail.com>"]
 license = "MIT"
@@ -16,6 +16,9 @@ pydantic = "^2.10.0"
 aiohttp = "^3.11.7"
 
 
+[tool.poetry.group.dev.dependencies]
+black = "^24.10.0"
+
 [build-system]
 requires = ["poetry-core"]
 build-backend = "poetry.core.masonry.api"

hyperbrowser-0.1.0/hyperbrowser/transport/async_transport.py

@@ -1,41 +0,0 @@
-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-0.1.0/hyperbrowser/transport/sync.py

@@ -1,36 +0,0 @@
-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)