hyperbrowser-lite 1.0.0__tar.gz

hyperbrowser_lite-1.0.0/.gitignore

@@ -0,0 +1 @@
+/.pypirc

hyperbrowser_lite-1.0.0/PKG-INFO

@@ -0,0 +1,14 @@
+Metadata-Version: 2.4
+Name: hyperbrowser-lite
+Version: 1.0.0
+Summary: Minimal cloud browser SDK for Hyperbrowser — session lifecycle management via CDP.
+Project-URL: Homepage, https://github.com/ayanami-browser-pilot/hyperbrowser-lite
+Project-URL: Repository, https://github.com/ayanami-browser-pilot/hyperbrowser-lite
+Requires-Python: >=3.10
+Requires-Dist: httpx>=0.27.0
+Requires-Dist: pydantic<3,>=2.5.2
+Provides-Extra: dev
+Requires-Dist: pytest-asyncio>=0.24; extra == 'dev'
+Requires-Dist: pytest-cov>=5.0; extra == 'dev'
+Requires-Dist: pytest>=8.0; extra == 'dev'
+Requires-Dist: respx>=0.21; extra == 'dev'

hyperbrowser_lite-1.0.0/README.md

@@ -0,0 +1,234 @@
+# hyperbrowser-lite
+
+Minimal Python SDK for [Hyperbrowser](https://www.hyperbrowser.ai/) cloud browser sessions. Only does one thing: **create a cloud browser, return a CDP URL, clean up when done**.
+
+Part of the [cloud-browser-sdk-spec](https://github.com/ayanami-browser-pilot) unified interface for cloud browser providers.
+
+## Install
+
+```bash
+pip install hyperbrowser-lite
+```
+
+## Quick Start
+
+```python
+from hyperbrowser_lite import HyperbrowserCloud
+
+client = HyperbrowserCloud(api_key="hb-...")  # or set HYPERBROWSER_API_KEY env var
+
+# Create a cloud browser session
+session = client.sessions.create()
+print(session.cdp_url)      # wss://connect-us-west-2.hyperbrowser.ai/?token=...
+print(session.session_id)   # UUID
+
+# Connect with Playwright
+# Hyperbrowser CDP uses token-based URLs — no auth headers needed
+from playwright.sync_api import sync_playwright
+
+with sync_playwright() as pw:
+    browser = pw.chromium.connect_over_cdp(session.cdp_url)
+    page = browser.contexts[0].new_page()
+    page.goto("https://example.com")
+    print(page.title())
+
+# Clean up
+client.sessions.delete(session.session_id)
+```
+
+### Context Manager (auto-cleanup)
+
+```python
+with client.sessions.create() as session:
+    # use session.cdp_url ...
+    pass
+# session automatically deleted on exit
+```
+
+### Async
+
+```python
+from hyperbrowser_lite import AsyncHyperbrowserCloud
+
+async with AsyncHyperbrowserCloud(api_key="hb-...") as client:
+    session = await client.sessions.create()
+    print(session.cdp_url)
+    await client.sessions.delete(session.session_id)
+```
+
+## API
+
+### Client
+
+```python
+HyperbrowserCloud(api_key=None, *, base_url=None, timeout=60.0, max_retries=2)
+AsyncHyperbrowserCloud(api_key=None, *, base_url=None, timeout=60.0, max_retries=2)
+```
+
+- `api_key` — defaults to `HYPERBROWSER_API_KEY` env var
+- `base_url` — defaults to `https://api.hyperbrowser.ai`
+
+### Sessions (`client.sessions`)
+
+| Method | Description |
+|--------|-------------|
+| `create(**kwargs) -> SessionInfo` | Create cloud browser, returns CDP URL |
+| `get(session_id) -> SessionInfo` | Get session status |
+| `list(**filters) -> list[SessionInfo]` | List sessions |
+| `delete(session_id) -> None` | Stop session (idempotent) |
+
+### `create()` Parameters
+
+```python
+session = client.sessions.create(
+    # Browser mode — controls anti-detection
+    browser_mode="stealth",        # or "ultra_stealth" (enterprise), default "normal"
+
+    # Proxy — managed or custom
+    proxy=ManagedProxyConfig(country="US"),
+    # proxy=ProxyConfig(server="http://proxy:8080", username="u", password="p"),
+
+    # Recording — ON by default, explicitly enable/disable
+    recording=RecordingConfig(enabled=True),
+
+    # Fingerprint — locale and viewport
+    fingerprint=FingerprintConfig(locale="en-US", viewport=ViewportConfig(1920, 1080)),
+
+    # Vendor params
+    solve_captchas=True,     # paid plan required
+    adblock=True,            # block ads, faster page loads
+    trackers=True,           # block tracking scripts
+    annoyances=True,         # block cookie banners, newsletter popups
+    timeout_minutes=30,
+    extension_ids=["ext-123"],
+    region="us-central",
+)
+```
+
+### SessionInfo Fields
+
+| Field | Type | Description |
+|-------|------|-------------|
+| `session_id` | `str` | Unique identifier (UUID) |
+| `cdp_url` | `str \| None` | CDP WebSocket URL (`wss://connect-{region}.hyperbrowser.ai/?token=...`) |
+| `status` | `str` | `"active"`, `"closed"`, or `"error"` |
+| `created_at` | `datetime \| None` | Creation timestamp |
+| `inspect_url` | `str \| None` | Live view URL — open in browser to watch session in real-time |
+| `metadata` | `dict` | Vendor-specific data (see below) |
+
+#### Metadata Contents
+
+The `metadata` dict contains Hyperbrowser-specific fields from the API response:
+
+| Key | Description |
+|-----|-------------|
+| `teamId` | Team identifier |
+| `token` | JWT auth token (embedded in `cdp_url`) |
+| `sessionUrl` | Dashboard URL for this session |
+| `launchState` | Full launch configuration (see Feature Details below) |
+| `proxyDataConsumed` | Proxy bandwidth consumed |
+| `liveDomain` | WebSocket server domain |
+| `webdriverEndpoint` | WebDriver protocol endpoint |
+| `computerActionEndpoint` | Computer action API endpoint |
+
+### CDP WebSocket Authentication
+
+Hyperbrowser's CDP WebSocket endpoint uses **token-based URLs** — the `wsEndpoint` contains an embedded JWT token. **No additional headers are needed**:
+
+```python
+# Playwright — just connect directly
+browser = pw.chromium.connect_over_cdp(session.cdp_url)
+
+# Works with any CDP client (Playwright, Puppeteer, Selenium, raw websockets)
+```
+
+This is different from providers like Skyvern which require `x-api-key` headers on the WebSocket handshake.
+
+## Feature Details
+
+All features are verified against the live Hyperbrowser API. The `launchState` in `metadata` confirms which features are active.
+
+### Stealth Mode (`browser_mode="stealth"`)
+
+Hides browser automation fingerprints so anti-bot systems cannot easily detect the session:
+- `navigator.webdriver` returns `false`
+- Chrome DevTools Protocol detection signatures are masked
+- Other automation hints are suppressed
+
+**Verified**: `launchState.useStealth` changes from `false` to `true`. Available on free plan.
+
+### Ultra Stealth Mode (`browser_mode="ultra_stealth"`)
+
+Enhanced stealth with additional anti-detection measures beyond standard stealth.
+
+**Requires enterprise plan** — returns HTTP 402 on free plan.
+
+### Recording (`RecordingConfig`)
+
+Records DOM mutations during the session (similar to [rrweb](https://github.com/rrweb-io/rrweb)). After the session ends, the recording can be retrieved via the Hyperbrowser dashboard or API for playback.
+
+**Important**: Recording is **enabled by default** (`enableWebRecording: true`). Passing `RecordingConfig(enabled=True)` is redundant unless you previously disabled it. Video recording (`enableVideoWebRecording`) is a separate feature and is off by default.
+
+### Ad Blocking (`adblock=True`)
+
+Built-in ad blocker that removes ads (banners, popups, video ads) from pages:
+- Faster page loads — fewer network requests
+- Cleaner pages — no ad popups interfering with automation
+- Less bandwidth — reduces `proxyDataConsumed`
+
+Related options: `trackers=True` (blocks tracking scripts), `annoyances=True` (blocks cookie banners, newsletter popups).
+
+**Verified**: `launchState.adblock` changes to `true`. Available on free plan.
+
+### Captcha Solving (`solve_captchas=True`)
+
+Automatically solves CAPTCHAs encountered during browsing.
+
+**Requires paid plan** — returns HTTP 402 on free plan.
+
+### Feature Support Matrix
+
+| Feature | Free Plan | Paid Plan | Enterprise | Usage |
+|---------|-----------|-----------|------------|-------|
+| Custom proxy server | ? | ? | ? | `ProxyConfig(server=...)` |
+| Managed proxy (200+ countries) | ? | ? | ? | `ManagedProxyConfig(country="US")` |
+| Stealth mode | Yes | Yes | Yes | `browser_mode="stealth"` |
+| Ultra stealth mode | No | No | Yes | `browser_mode="ultra_stealth"` |
+| Browser fingerprint | Yes | Yes | Yes | `FingerprintConfig(locale=..., viewport=...)` |
+| Session recording (DOM) | Yes (default ON) | Yes | Yes | `RecordingConfig(enabled=True)` |
+| Video recording | ? | ? | ? | Vendor param: `enable_video_web_recording=True` |
+| Captcha solving | No | Yes | Yes | `solve_captchas=True` |
+| Ad blocking | Yes | Yes | Yes | `adblock=True` |
+| Tracker blocking | Yes | Yes | Yes | `trackers=True` |
+| Annoyance blocking | Yes | Yes | Yes | `annoyances=True` |
+| Extensions | Yes | Yes | Yes | `extension_ids=[...]` |
+| Region selection | Yes | Yes | Yes | `region="us-central"` |
+| Browser profiles | Yes | Yes | Yes | `profile={"id": "..."}` |
+| Context persistence | N/A | N/A | N/A | Use profiles instead |
+
+> `?` = not tested (requires proxy configuration / paid features)
+
+### Exceptions
+
+```
+CloudBrowserError
+├── AuthenticationError     # 401/403 — invalid or expired API key
+├── QuotaExceededError      # 429 — rate limit (has .retry_after)
+├── SessionNotFoundError    # 404 — session not found
+├── ProviderError           # 5xx — server error (has .status_code, .request_id)
+├── TimeoutError            # Operation timeout
+└── NetworkError            # Connection failure
+```
+
+Note: Plan-restricted features return **HTTP 402** (mapped to `CloudBrowserError`), not 403.
+
+### Backward Compatibility
+
+```python
+from hyperbrowser_lite import Hyperbrowser       # alias for HyperbrowserCloud
+from hyperbrowser_lite import AsyncHyperbrowser  # alias for AsyncHyperbrowserCloud
+```
+
+## License
+
+MIT

hyperbrowser_lite-1.0.0/pyproject.toml

@@ -0,0 +1,32 @@
+[build-system]
+requires = ["hatchling"]
+build-backend = "hatchling.build"
+
+[project]
+name = "hyperbrowser-lite"
+version = "1.0.0"
+description = "Minimal cloud browser SDK for Hyperbrowser — session lifecycle management via CDP."
+requires-python = ">=3.10"
+dependencies = [
+    "httpx>=0.27.0",
+    "pydantic>=2.5.2,<3",
+]
+
+[project.optional-dependencies]
+dev = [
+    "pytest>=8.0",
+    "pytest-asyncio>=0.24",
+    "pytest-cov>=5.0",
+    "respx>=0.21",
+]
+
+[project.urls]
+Homepage = "https://github.com/ayanami-browser-pilot/hyperbrowser-lite"
+Repository = "https://github.com/ayanami-browser-pilot/hyperbrowser-lite"
+
+[tool.hatch.build.targets.wheel]
+packages = ["src/hyperbrowser_lite"]
+
+[tool.pytest.ini_options]
+asyncio_mode = "auto"
+testpaths = ["tests"]

hyperbrowser_lite-1.0.0/src/hyperbrowser_lite/__init__.py

@@ -0,0 +1,182 @@
+"""Hyperbrowser Cloud Browser SDK — minimal interface for browser session lifecycle.
+
+Quick Start
+-----------
+::
+
+    from hyperbrowser_lite import HyperbrowserCloud
+
+    client = HyperbrowserCloud(api_key="hb-...")  # or set HYPERBROWSER_API_KEY env var
+
+    # Create a cloud browser session
+    session = client.sessions.create()
+    print(session.cdp_url)   # wss://...
+    print(session.session_id)
+
+    # Use with Playwright (or any CDP client)
+    # NOTE: Hyperbrowser CDP uses token-based wsEndpoint URLs — no auth headers needed.
+    from playwright.sync_api import sync_playwright
+    with sync_playwright() as pw:
+        browser = pw.chromium.connect_over_cdp(session.cdp_url)
+        page = browser.contexts[0].new_page()
+        page.goto("https://example.com")
+
+    # Cleanup
+    client.sessions.delete(session.session_id)
+
+    # Or use context manager for auto-cleanup:
+    with client.sessions.create() as session:
+        ...  # session auto-deleted on exit
+
+API Reference
+-------------
+
+Client Classes
+~~~~~~~~~~~~~~
+- ``HyperbrowserCloud(api_key, *, base_url, timeout, max_retries)``  — Sync client
+- ``AsyncHyperbrowserCloud(api_key, *, base_url, timeout, max_retries)`` — Async client
+- ``Hyperbrowser`` / ``AsyncHyperbrowser`` — Backward-compatible aliases
+
+Client Properties
+~~~~~~~~~~~~~~~~~
+- ``client.sessions``     — SessionsResource for CRUD operations
+- ``client.contexts``     — Always None (use profiles for persistence)
+- ``client.capabilities`` — Returns ``["proxy", "fingerprint", "recording"]``
+
+Session CRUD (``client.sessions``)
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+- ``create(*, browser_mode, proxy, recording, fingerprint, context, **vendor_params) -> SessionInfo``
+- ``get(session_id) -> SessionInfo``
+- ``list(**filters) -> list[SessionInfo]``
+- ``delete(session_id) -> None``  (idempotent, safe to call multiple times)
+
+Vendor Parameters (pass via ``**vendor_params`` in ``create()``)
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+- ``timeout_minutes: int``         — Session timeout in minutes
+- ``solve_captchas: bool``         — Enable captcha solving
+- ``adblock: bool``                — Enable ad blocking
+- ``trackers: bool``               — Block trackers
+- ``annoyances: bool``             — Block annoyances
+- ``profile: dict``                — Session profile (``{"id": "..."}`` for persistence)
+- ``extension_ids: list[str]``     — Browser extension IDs
+- ``region: str``                  — Deploy region (e.g. ``"us-central"``)
+- ``accept_cookies: bool``         — Auto-accept cookie banners
+- ``browser_args: list[str]``      — Extra browser CLI arguments
+- ``url_blocklist: list[str]``     — URLs to block
+- ``save_downloads: bool``         — Persist downloaded files
+
+Example with features::
+
+    session = client.sessions.create(
+        browser_mode="stealth",
+        proxy=ManagedProxyConfig(country="US"),
+        recording=RecordingConfig(enabled=True),
+        fingerprint=FingerprintConfig(locale="en-US"),
+        solve_captchas=True,
+        adblock=True,
+        timeout_minutes=30,
+    )
+
+Feature Support Matrix
+~~~~~~~~~~~~~~~~~~~~~~
+=========================  =========  ==================================================
+Feature                    Supported  Notes
+=========================  =========  ==================================================
+Custom proxy server        Yes        ``ProxyConfig(server, username, password)``
+Managed proxy (200+ ctry)  Yes        ``ManagedProxyConfig(country="US")``
+Stealth mode               Yes        ``browser_mode="stealth"``
+Ultra stealth mode         Yes        ``browser_mode="ultra_stealth"``
+Browser fingerprint        Yes        ``FingerprintConfig(locale=..., viewport=...)``
+Session recording          Yes        ``RecordingConfig(enabled=True)``
+Captcha solving            Yes        ``solve_captchas=True``
+Ad blocking                Yes        ``adblock=True``
+Extensions                 Yes        ``extension_ids=[...]``
+Region selection           Yes        ``region="us-central"``
+Browser profiles           Yes        ``profile={"id": "..."}`` (vendor param)
+Context persistence        No         Use profiles instead
+=========================  =========  ==================================================
+
+SessionInfo Fields
+~~~~~~~~~~~~~~~~~~
+- ``session_id: str``           — Unique session identifier
+- ``cdp_url: str | None``       — CDP WebSocket URL (wss://)
+- ``status: str``               — "active", "closed", or "error"
+- ``created_at: datetime | None``
+- ``inspect_url: str | None``   — Live view URL for debugging
+- ``metadata: dict``            — Vendor-specific data (teamId, token, proxyDataConsumed, etc.)
+
+Proxy Configuration
+~~~~~~~~~~~~~~~~~~~
+- ``ManagedProxyConfig(country="US")``                      — Managed proxy with country
+- ``ManagedProxyConfig(country="US", city="New York")``     — Managed proxy with city
+- ``ProxyConfig(server="http://proxy:8080")``               — Custom proxy server
+- ``ProxyConfig(server, username="u", password="p")``       — Custom proxy with auth
+
+CDP Authentication
+~~~~~~~~~~~~~~~~~~
+Hyperbrowser's CDP WebSocket endpoint uses token-based URLs (the ``wsEndpoint``
+contains an embedded auth token). **No additional headers are needed** for the
+WebSocket connection::
+
+    browser = pw.chromium.connect_over_cdp(session.cdp_url)  # No headers needed
+
+Exception Hierarchy
+~~~~~~~~~~~~~~~~~~~
+::
+
+    CloudBrowserError          # Base exception
+    ├── AuthenticationError    # 401/403 — invalid or expired API key
+    ├── QuotaExceededError     # 429 — rate limit (has .retry_after attribute)
+    ├── SessionNotFoundError   # 404 — session doesn't exist
+    ├── ProviderError          # 5xx — server error (has .status_code, .request_id)
+    ├── TimeoutError           # Operation timed out
+    └── NetworkError           # Connection failure
+"""
+
+from .client import AsyncHyperbrowserCloud, HyperbrowserCloud
+from .exceptions import (
+    AuthenticationError,
+    CloudBrowserError,
+    NetworkError,
+    ProviderError,
+    QuotaExceededError,
+    SessionNotFoundError,
+    TimeoutError,
+)
+from .models import (
+    ContextAttach,
+    FingerprintConfig,
+    ManagedProxyConfig,
+    ProxyConfig,
+    RecordingConfig,
+    SessionInfo,
+    ViewportConfig,
+)
+
+# Backward compatibility aliases
+Hyperbrowser = HyperbrowserCloud
+AsyncHyperbrowser = AsyncHyperbrowserCloud
+
+__all__ = [
+    # Clients
+    "HyperbrowserCloud",
+    "AsyncHyperbrowserCloud",
+    "Hyperbrowser",
+    "AsyncHyperbrowser",
+    # Models
+    "SessionInfo",
+    "ContextAttach",
+    "FingerprintConfig",
+    "ViewportConfig",
+    "ProxyConfig",
+    "ManagedProxyConfig",
+    "RecordingConfig",
+    # Exceptions
+    "CloudBrowserError",
+    "AuthenticationError",
+    "QuotaExceededError",
+    "SessionNotFoundError",
+    "ProviderError",
+    "TimeoutError",
+    "NetworkError",
+]

hyperbrowser_lite-1.0.0/src/hyperbrowser_lite/_http.py

@@ -0,0 +1,209 @@
+"""Internal HTTP client wrappers with retry and exception mapping."""
+
+from __future__ import annotations
+
+import time
+from typing import Any
+
+import httpx
+
+from .exceptions import (
+    AuthenticationError,
+    CloudBrowserError,
+    NetworkError,
+    ProviderError,
+    QuotaExceededError,
+    SessionNotFoundError,
+    TimeoutError,
+)
+
+_RETRYABLE_STATUS_CODES = {408, 429, 500, 502, 503, 504}
+_DEFAULT_BACKOFF_BASE = 0.5
+_DEFAULT_BACKOFF_MAX = 3.0
+
+
+def _parse_retry_after(response: httpx.Response) -> float | None:
+    """Parse Retry-After header value in seconds."""
+    value = response.headers.get("retry-after")
+    if value is None:
+        return None
+    try:
+        return float(value)
+    except (ValueError, TypeError):
+        return None
+
+
+def _raise_for_status(response: httpx.Response) -> None:
+    """Map HTTP status codes to SDK exceptions."""
+    status = response.status_code
+    if 200 <= status < 300:
+        return
+
+    try:
+        body = response.json()
+    except Exception:
+        body = {}
+
+    message = body.get("detail") or body.get("message") or response.text or f"HTTP {status}"
+    request_id = response.headers.get("x-request-id")
+
+    if status in (401, 403):
+        raise AuthenticationError(str(message))
+    if status == 404:
+        raise SessionNotFoundError(str(message))
+    if status == 429:
+        retry_after_val = _parse_retry_after(response)
+        retry_after_int = int(retry_after_val) if retry_after_val is not None else None
+        raise QuotaExceededError(str(message), retry_after=retry_after_int)
+    if status >= 500:
+        raise ProviderError(
+            str(message),
+            status_code=status,
+            request_id=request_id,
+        )
+    raise CloudBrowserError(f"HTTP {status}: {message}")
+
+
+class SyncHttpClient:
+    """Synchronous HTTP client with retry logic."""
+
+    def __init__(
+        self,
+        base_url: str,
+        api_key: str,
+        timeout: float = 60.0,
+        max_retries: int = 2,
+    ):
+        self._client = httpx.Client(
+            base_url=base_url,
+            headers={"x-api-key": api_key},
+            timeout=timeout,
+        )
+        self._max_retries = max_retries
+
+    def request(
+        self,
+        method: str,
+        path: str,
+        *,
+        json: Any = None,
+        params: dict[str, Any] | None = None,
+    ) -> dict[str, Any]:
+        """Send an HTTP request with retry on transient errors."""
+        last_exc: Exception | None = None
+
+        for attempt in range(self._max_retries + 1):
+            try:
+                response = self._client.request(
+                    method, path, json=json, params=params
+                )
+            except httpx.TimeoutException as exc:
+                last_exc = TimeoutError(str(exc))
+                if attempt < self._max_retries:
+                    self._backoff(attempt)
+                    continue
+                raise last_exc from exc
+            except httpx.ConnectError as exc:
+                last_exc = NetworkError(str(exc))
+                if attempt < self._max_retries:
+                    self._backoff(attempt)
+                    continue
+                raise last_exc from exc
+
+            if response.status_code in _RETRYABLE_STATUS_CODES and attempt < self._max_retries:
+                wait = _parse_retry_after(response) or self._backoff_delay(attempt)
+                time.sleep(wait)
+                continue
+
+            _raise_for_status(response)
+
+            if response.status_code == 204 or not response.content:
+                return {}
+            return response.json()  # type: ignore[no-any-return]
+
+        # Should not reach here, but just in case
+        if last_exc is not None:
+            raise last_exc
+        raise CloudBrowserError("Request failed after retries")
+
+    def close(self) -> None:
+        self._client.close()
+
+    @staticmethod
+    def _backoff_delay(attempt: int) -> float:
+        return min(_DEFAULT_BACKOFF_BASE * (2**attempt), _DEFAULT_BACKOFF_MAX)
+
+    @staticmethod
+    def _backoff(attempt: int) -> None:
+        time.sleep(min(_DEFAULT_BACKOFF_BASE * (2**attempt), _DEFAULT_BACKOFF_MAX))
+
+
+class AsyncHttpClient:
+    """Asynchronous HTTP client with retry logic."""
+
+    def __init__(
+        self,
+        base_url: str,
+        api_key: str,
+        timeout: float = 60.0,
+        max_retries: int = 2,
+    ):
+        self._client = httpx.AsyncClient(
+            base_url=base_url,
+            headers={"x-api-key": api_key},
+            timeout=timeout,
+        )
+        self._max_retries = max_retries
+
+    async def request(
+        self,
+        method: str,
+        path: str,
+        *,
+        json: Any = None,
+        params: dict[str, Any] | None = None,
+    ) -> dict[str, Any]:
+        """Send an async HTTP request with retry on transient errors."""
+        import asyncio
+
+        last_exc: Exception | None = None
+
+        for attempt in range(self._max_retries + 1):
+            try:
+                response = await self._client.request(
+                    method, path, json=json, params=params
+                )
+            except httpx.TimeoutException as exc:
+                last_exc = TimeoutError(str(exc))
+                if attempt < self._max_retries:
+                    await asyncio.sleep(self._backoff_delay(attempt))
+                    continue
+                raise last_exc from exc
+            except httpx.ConnectError as exc:
+                last_exc = NetworkError(str(exc))
+                if attempt < self._max_retries:
+                    await asyncio.sleep(self._backoff_delay(attempt))
+                    continue
+                raise last_exc from exc
+
+            if response.status_code in _RETRYABLE_STATUS_CODES and attempt < self._max_retries:
+                wait = _parse_retry_after(response) or self._backoff_delay(attempt)
+                await asyncio.sleep(wait)
+                continue
+
+            _raise_for_status(response)
+
+            if response.status_code == 204 or not response.content:
+                return {}
+            return response.json()  # type: ignore[no-any-return]
+
+        if last_exc is not None:
+            raise last_exc
+        raise CloudBrowserError("Request failed after retries")
+
+    async def close(self) -> None:
+        await self._client.aclose()
+
+    @staticmethod
+    def _backoff_delay(attempt: int) -> float:
+        return min(_DEFAULT_BACKOFF_BASE * (2**attempt), _DEFAULT_BACKOFF_MAX)