solari-browser 0.1.1__py3-none-any.whl

solari_browser/__init__.py

@@ -0,0 +1,60 @@
+"""Solari Browser — Python SDK.
+
+Managed, stealthy remote Chromium over the Playwright wire protocol / raw CDP.
+
+    import asyncio
+    from solari_browser import Solari
+
+    async def main():
+        async with Solari(api_key="slr_live_...") as solari:
+            async with await solari.launch(stealth=True) as browser:
+                page = await browser.new_page()
+                await page.goto("https://example.com")
+                print(await page.title())
+
+    asyncio.run(main())
+"""
+
+from .browser_session import BrowserSession
+from .client import Solari, derive_cdp_from_ws
+from .errors import (
+    BROWSER_UNHEALTHY,
+    CONCURRENCY_LIMIT_EXCEEDED,
+    FEATURE_REQUIRES_PLAN,
+    PLAN_LIMIT_EXCEEDED,
+    SolariError,
+)
+from .types import (
+    DEFAULT_REGION,
+    REGION_URLS,
+    UNSET,
+    Profile,
+    ProxyRequest,
+    ReplayUrl,
+    ResolvedProxyConfig,
+    SaveResult,
+    Session,
+)
+
+__version__ = "0.1.0"
+
+__all__ = [
+    "Solari",
+    "BrowserSession",
+    "SolariError",
+    "Session",
+    "Profile",
+    "ProxyRequest",
+    "ResolvedProxyConfig",
+    "ReplayUrl",
+    "SaveResult",
+    "UNSET",
+    "REGION_URLS",
+    "DEFAULT_REGION",
+    "derive_cdp_from_ws",
+    "FEATURE_REQUIRES_PLAN",
+    "CONCURRENCY_LIMIT_EXCEEDED",
+    "PLAN_LIMIT_EXCEEDED",
+    "BROWSER_UNHEALTHY",
+    "__version__",
+]

solari_browser/browser_session.py

@@ -0,0 +1,94 @@
+"""BrowserSession — a connected browser + its Solari session. Mirrors sdk/src/browser-session.ts."""
+
+from __future__ import annotations
+
+from typing import TYPE_CHECKING, Any, List, Optional
+
+from .types import ResolvedProxyConfig, Session
+
+if TYPE_CHECKING:  # pragma: no cover
+    from .client import Solari
+
+
+class BrowserSession:
+    """Wraps a patchright `Browser` and the Solari session backing it.
+
+    `close()` closes the browser AND releases the session — a browser close alone
+    would leave the slot held until its plan deadline.
+    """
+
+    def __init__(self, client: "Solari", session: Session, browser: Any) -> None:
+        self._client = client
+        self._session = session
+        self._browser = browser
+        self._closed = False
+
+    @property
+    def id(self) -> str:
+        return self._session.id
+
+    @property
+    def expires_at(self) -> str:
+        """ISO 8601 UTC deadline; the session auto-releases at this point."""
+        return self._session.expires_at
+
+    @property
+    def proxy(self) -> Optional[ResolvedProxyConfig]:
+        return self._session.proxy
+
+    @property
+    def ws_endpoint(self) -> str:
+        """Upstream Playwright wire-protocol endpoint."""
+        return self._session.ws_endpoint
+
+    @property
+    def cdp_endpoint(self) -> str:
+        """Upstream raw-CDP endpoint.
+
+        NOTE: driving the browser over raw CDP bypasses the pool's Playwright-path
+        input humanization (see CLAUDE.md) — relevant if you care about stealth.
+        """
+        return self._session.cdp_endpoint
+
+    @property
+    def session(self) -> Session:
+        return self._session
+
+    @property
+    def raw(self) -> Any:
+        """The underlying patchright `Browser`."""
+        return self._browser
+
+    def is_connected(self) -> bool:
+        return bool(self._browser.is_connected())
+
+    @property
+    def version(self) -> str:
+        return str(self._browser.version)
+
+    def contexts(self) -> List[Any]:
+        """Existing browser contexts. The default context is `contexts()[0]`."""
+        return list(self._browser.contexts)
+
+    async def new_context(self, **kwargs: Any) -> Any:
+        return await self._browser.new_context(**kwargs)
+
+    async def new_page(self) -> Any:
+        return await self._browser.new_page()
+
+    async def close(self) -> None:
+        """Close the browser and release the session. Idempotent."""
+        if self._closed:
+            return
+        self._closed = True
+        try:
+            await self._browser.close()
+        except Exception:  # noqa: BLE001 - releasing the slot matters more
+            pass
+        await self._client.sessions.release_and_wait(self._session.id)
+
+    async def __aenter__(self) -> "BrowserSession":
+        return self
+
+    async def __aexit__(self, *_exc: Any) -> None:
+        await self.close()

solari_browser/client.py

@@ -0,0 +1,521 @@
+"""Solari Browser client — the async Python port of sdk/src/index.ts."""
+
+from __future__ import annotations
+
+import asyncio
+import json
+import logging
+import re
+from typing import Any, Dict, List, Optional, Union
+from urllib.parse import urlsplit, urlunsplit
+
+import httpx
+
+from .errors import BROWSER_UNHEALTHY, SolariError, code_from_body
+from .types import (
+    DEFAULT_REGION,
+    REGION_URLS,
+    UNSET,
+    Profile,
+    ProxyRequest,
+    ProxySpec,
+    ReplayUrl,
+    ResolvedProxyConfig,
+    SaveResult,
+    Session,
+    StorageState,
+)
+
+log = logging.getLogger("solari_browser")
+
+DEFAULT_MAX_ATTEMPTS = 2
+DEFAULT_BACKOFF_MS = 500
+DEFAULT_TIMEOUT_MS = 90_000
+_STORAGE_STATE_TIMEOUT_S = 8.0
+
+# Only these are retried. Mirrors `isRetryableStatus` — note this is a FIXED backoff
+# and a short attempt count, unlike the desktop SDK's exponential+jitter.
+_RETRYABLE_STATUS = frozenset({502, 503, 504})
+
+# Mirrors `isLikelyTransientConnect`: which connect failures are worth relaunching.
+_TRANSIENT_CONNECT = re.compile(
+    r"ECONNRESET|ECONNREFUSED|ETIMEDOUT|EPIPE|socket hang up|WebSocket|connect|"
+    r"handshake|Browser closed|Target page, context or browser has been closed",
+    re.IGNORECASE,
+)
+
+
+def derive_cdp_from_ws(ws_endpoint: str) -> str:
+    """`/ws/<id>` -> `/cdp/<id>`. Mirrors `deriveCdpFromWs`.
+
+    The gateway usually returns cdpEndpoint explicitly; this is the fallback for
+    older gateways. Returns the input unchanged if it isn't a parseable /ws/ URL.
+    """
+    try:
+        parts = urlsplit(ws_endpoint)
+        if parts.path.startswith("/ws/"):
+            new_path = "/cdp/" + parts.path[len("/ws/") :]
+            return urlunsplit((parts.scheme, parts.netloc, new_path, parts.query, parts.fragment))
+    except Exception:
+        pass
+    return ws_endpoint
+
+
+class _Sessions:
+    """`solari.sessions` — mirrors SessionsResource."""
+
+    def __init__(self, client: "Solari") -> None:
+        self._client = client
+
+    async def create(
+        self,
+        *,
+        profile_id: Optional[str] = None,
+        recording: bool = False,
+        stealth: bool = False,
+        captcha: bool = False,
+        web_bot_auth: bool = False,
+        proxy: Optional[ProxySpec] = None,
+    ) -> Session:
+        """Create a browser session.
+
+        captcha and proxy require stealth=True (enforced gateway-side).
+        """
+        body: Dict[str, Any] = {}
+        if profile_id:
+            body["profileId"] = profile_id
+        if recording:
+            body["recording"] = True
+        if stealth:
+            body["stealth"] = True
+        if captcha:
+            body["captcha"] = True
+        if web_bot_auth:
+            body["webBotAuth"] = True
+        if proxy is not None:
+            body["proxy"] = proxy.to_wire() if isinstance(proxy, ProxyRequest) else proxy
+
+        # An empty body is sent as no body at all, matching the TS SDK.
+        res = await self._client.request("POST", "/sessions", body if body else None)
+        if res.status_code >= 400:
+            text = res.text
+            raise SolariError(
+                f"Solari POST /sessions failed: {res.status_code} {text}",
+                res.status_code,
+                None,
+                code_from_body(text),
+            )
+
+        data = _json(res, "/sessions")
+        session_id = data.get("sessionId")
+        ws_endpoint = data.get("wsEndpoint")
+        if not session_id or not ws_endpoint:
+            raise SolariError(f"Solari: unexpected session response: {json.dumps(data)}")
+
+        cdp_endpoint = data.get("cdpEndpoint") or derive_cdp_from_ws(ws_endpoint)
+        expires_at = data.get("expiresAt")
+        if not expires_at:
+            # Mirrors the TS fallback: assume the plan's 60m default rather than
+            # leaving callers with an unusable empty deadline.
+            import datetime as _dt
+
+            expires_at = (
+                _dt.datetime.now(_dt.timezone.utc) + _dt.timedelta(minutes=60)
+            ).isoformat().replace("+00:00", "Z")
+
+        session = Session(
+            id=session_id,
+            ws_endpoint=ws_endpoint,
+            cdp_endpoint=cdp_endpoint,
+            expires_at=expires_at,
+        )
+
+        # storage_state is only populated when a profile was requested. UNSET means
+        # "no profile attached"; None means "profile exists but is empty".
+        if profile_id is not None:
+            url_obj = data.get("storageStateUrl")
+            if url_obj is not None:
+                session.storage_state = await _fetch_presigned_storage_state(url_obj.get("url"))
+            else:
+                session.storage_state = data.get("storageState")
+
+        if data.get("proxy"):
+            session.proxy = ResolvedProxyConfig.from_wire(data["proxy"])
+        return session
+
+    async def release(self, session_id: str) -> None:
+        """Best-effort release. Never raises — use `release_and_wait` for confirmation."""
+        try:
+            res = await self._client.request(
+                "DELETE", f"/sessions/{_q(session_id)}"
+            )
+            if res.status_code >= 400 and res.status_code != 404:
+                log.warning(
+                    "[Solari] DELETE /sessions/%s returned %s: %s",
+                    session_id,
+                    res.status_code,
+                    res.text[:256],
+                )
+        except Exception as err:  # noqa: BLE001 - fire-and-forget by contract
+            log.warning("[Solari] DELETE /sessions/%s failed (best-effort): %s", session_id, err)
+
+    async def release_and_wait(self, session_id: str) -> None:
+        """Release and confirm. A 404 is success — the session is already gone."""
+        res = await self._client.request("DELETE", f"/sessions/{_q(session_id)}")
+        if res.status_code >= 400 and res.status_code != 404:
+            raise SolariError(
+                f"Solari DELETE /sessions/{session_id} failed: {res.status_code} {res.text}",
+                res.status_code,
+            )
+
+    async def get(self, session_id: str) -> Dict[str, Any]:
+        """Raw session view from the gateway."""
+        res = await self._client.request("GET", f"/sessions/{_q(session_id)}")
+        if res.status_code >= 400:
+            raise SolariError(
+                f"Solari GET /sessions/{session_id} failed: {res.status_code} {res.text}",
+                res.status_code,
+            )
+        return _json(res, f"/sessions/{session_id}")
+
+    async def get_replay_url(self, session_id: str) -> ReplayUrl:
+        """Presigned replay URL. Available ~1-3s after `release_and_wait`."""
+        res = await self._client.request("GET", f"/sessions/{_q(session_id)}/replay-url")
+        if res.status_code >= 400:
+            raise SolariError(
+                f"Solari GET /sessions/{session_id}/replay-url failed: "
+                f"{res.status_code} {res.text}",
+                res.status_code,
+            )
+        data = _json(res, "replay-url")
+        if not data.get("url"):
+            raise SolariError(f"Solari: unexpected replay-url response: {json.dumps(data)}")
+        return ReplayUrl(
+            url=data["url"],
+            expires_in_seconds=data.get("expiresInSeconds") or 0,
+            content_encoding=data.get("contentEncoding") or "gzip",
+        )
+
+    async def download_replay(self, session_id: str) -> bytes:
+        """Download the replay as NDJSON bytes (gzip-encoded per `content_encoding`)."""
+        replay = await self.get_replay_url(session_id)
+        async with httpx.AsyncClient(timeout=self._client._timeout_s) as http:
+            res = await http.get(replay.url)
+        if res.status_code >= 400:
+            raise SolariError(
+                f"Solari: replay download failed: {res.status_code}", res.status_code
+            )
+        return res.content
+
+
+class _Profiles:
+    """`solari.profiles` — mirrors ProfilesResource."""
+
+    def __init__(self, client: "Solari") -> None:
+        self._client = client
+
+    async def create(self, name: str) -> Profile:
+        res = await self._client.request("POST", "/profiles", {"name": name})
+        if res.status_code >= 400:
+            text = res.text
+            raise SolariError(
+                f"Solari POST /profiles failed: {res.status_code} {text}",
+                res.status_code,
+                None,
+                code_from_body(text),
+            )
+        return Profile.from_wire(_json(res, "/profiles"))
+
+    async def list(self) -> List[Profile]:
+        res = await self._client.request("GET", "/profiles")
+        if res.status_code >= 400:
+            raise SolariError(
+                f"Solari GET /profiles failed: {res.status_code} {res.text}", res.status_code
+            )
+        data = _json(res, "/profiles")
+        items = data if isinstance(data, list) else data.get("profiles", [])
+        return [Profile.from_wire(p) for p in items]
+
+    async def delete(self, profile_id: str) -> None:
+        """Delete a profile. A 404 is success — it's already gone."""
+        res = await self._client.request("DELETE", f"/profiles/{_q(profile_id)}")
+        if res.status_code >= 400 and res.status_code != 404:
+            raise SolariError(
+                f"Solari DELETE /profiles/{profile_id} failed: {res.status_code} {res.text}",
+                res.status_code,
+            )
+
+    async def save(self, profile_id: str, storage_state: StorageState) -> SaveResult:
+        """Persist a Playwright storage state into the profile."""
+        res = await self._client.request(
+            "POST", f"/profiles/{_q(profile_id)}/save", {"storageState": storage_state}
+        )
+        if res.status_code >= 400:
+            raise SolariError(
+                f"Solari POST /profiles/{profile_id}/save failed: {res.status_code} {res.text}",
+                res.status_code,
+            )
+        data = _json(res, "profiles/save")
+        return SaveResult(
+            version=data.get("version") or 0,
+            size_bytes=data.get("sizeBytes") or 0,
+        )
+
+
+class Solari:
+    """Solari Browser client.
+
+        solari = Solari(api_key="slr_live_...")
+        browser = await solari.launch(stealth=True)
+        page = await browser.new_page()
+        await page.goto("https://example.com")
+        await browser.close()
+        await solari.close()
+
+    Or as an async context manager:
+
+        async with Solari(api_key="slr_live_...") as solari:
+            async with await solari.launch(stealth=True) as browser:
+                ...
+    """
+
+    def __init__(
+        self,
+        api_key: str,
+        *,
+        region: str = DEFAULT_REGION,
+        base_url: Optional[str] = None,
+        max_attempts: int = DEFAULT_MAX_ATTEMPTS,
+        backoff_ms: int = DEFAULT_BACKOFF_MS,
+        timeout_ms: int = DEFAULT_TIMEOUT_MS,
+    ) -> None:
+        if not api_key:
+            raise SolariError("Solari: api_key is required")
+        region_url = REGION_URLS.get(region)
+        if not region_url:
+            raise SolariError(
+                f'Solari: unsupported region "{region}". '
+                f"Supported: {', '.join(REGION_URLS)}."
+            )
+        self._api_key = api_key
+        # base_url wins over region entirely — that's how you point at staging or a
+        # self-hosted gateway.
+        self._base_url = (base_url or region_url).rstrip("/")
+        self._max_attempts = max_attempts
+        self._backoff_ms = backoff_ms
+        self._timeout_s = timeout_ms / 1000.0
+
+        self.sessions = _Sessions(self)
+        self.profiles = _Profiles(self)
+
+        self._http: Optional[httpx.AsyncClient] = None
+        self._playwright: Any = None  # lazily started; only for launch()
+
+    @property
+    def base_url(self) -> str:
+        return self._base_url
+
+    async def __aenter__(self) -> "Solari":
+        return self
+
+    async def __aexit__(self, *_exc: Any) -> None:
+        await self.close()
+
+    async def close(self) -> None:
+        """Release the HTTP client and (if launch() was used) the patchright driver."""
+        if self._http is not None:
+            await self._http.aclose()
+            self._http = None
+        if self._playwright is not None:
+            await self._playwright.stop()
+            self._playwright = None
+
+    async def request(
+        self, method: str, path: str, body: Optional[Any] = None
+    ) -> httpx.Response:
+        """Authenticated request with the SDK's retry policy.
+
+        Retries ONLY 502/503/504 and transport errors, with a FIXED backoff. A
+        non-retryable error status is RETURNED, not raised — callers parse `code`
+        out of the body themselves (mirrors the TS SDK).
+        """
+        if self._http is None:
+            self._http = httpx.AsyncClient(timeout=self._timeout_s)
+        url = f"{self._base_url}{path}"
+        headers = {
+            "Authorization": f"Bearer {self._api_key}",
+            "Content-Type": "application/json",
+        }
+        payload = None if body is None else json.dumps(body)
+
+        last_err: Optional[BaseException] = None
+        for attempt in range(1, self._max_attempts + 1):
+            try:
+                res = await self._http.request(
+                    method, url, headers=headers, content=payload
+                )
+                if res.status_code < 400 or res.status_code not in _RETRYABLE_STATUS:
+                    return res
+                last_err = SolariError(f"Solari {method} {path}: {res.status_code}", res.status_code)
+            except Exception as err:  # noqa: BLE001 - all transport errors are retryable
+                last_err = err
+
+            if attempt < self._max_attempts:
+                await asyncio.sleep(self._backoff_ms / 1000.0)
+
+        raise SolariError(
+            f"Solari {method} {path}: exhausted {self._max_attempts} attempts",
+            None,
+            last_err,
+        )
+
+    async def launch(
+        self,
+        *,
+        profile_id: Optional[str] = None,
+        recording: bool = False,
+        stealth: bool = False,
+        captcha: bool = False,
+        web_bot_auth: bool = False,
+        proxy: Optional[ProxySpec] = None,
+        retries: int = 0,
+        probe: Optional[bool] = None,
+        probe_timeout_ms: int = 2_000,
+    ) -> "BrowserSession":
+        """Create a session and return a connected browser.
+
+        This is the full-parity path: it connects over the Playwright wire protocol
+        via patchright, exactly like the TS SDK. Go/Rust/C++ cannot do this — there
+        is no Playwright client for them.
+        """
+        from .browser_session import BrowserSession  # local import: avoids cycle
+
+        retries = max(0, retries)
+        probe_enabled = (retries > 0) if probe is None else probe
+        probe_timeout_ms = max(1, probe_timeout_ms)
+        total_attempts = retries + 1
+
+        chromium = await self._chromium()
+
+        last_err: Optional[BaseException] = None
+        for attempt in range(1, total_attempts + 1):
+            session = await self.sessions.create(
+                profile_id=profile_id,
+                recording=recording,
+                stealth=stealth,
+                captcha=captcha,
+                web_bot_auth=web_bot_auth,
+                proxy=proxy,
+            )
+            browser = None
+            try:
+                browser = await chromium.connect(session.ws_endpoint)
+                if probe_enabled:
+                    await self._probe_browser_health(browser, probe_timeout_ms)
+                return BrowserSession(self, session, browser)
+            except Exception as err:  # noqa: BLE001
+                if browser is not None:
+                    try:
+                        await browser.close()
+                    except Exception:  # noqa: BLE001
+                        pass
+                await self.sessions.release(session.id)
+
+                last_err = err
+                is_health = isinstance(err, SolariError) and err.code == BROWSER_UNHEALTHY
+                transient = (not is_health) and bool(_TRANSIENT_CONNECT.search(str(err)))
+                if attempt < total_attempts and (is_health or transient):
+                    await asyncio.sleep(0.1 * attempt)
+                    continue
+                raise
+
+        raise last_err or SolariError("Solari.launch: exhausted attempts")
+
+    async def _chromium(self) -> Any:
+        """Start the patchright driver once and reuse it across launches."""
+        if self._playwright is None:
+            try:
+                from patchright.async_api import async_playwright
+            except ImportError as err:  # pragma: no cover - depends on install extras
+                raise SolariError(
+                    "Solari: launch() needs patchright. Install it with "
+                    "`pip install 'solari-browser'` (it is a declared dependency) — "
+                    "then `patchright install chromium` is NOT required, since the "
+                    "browser runs remotely.",
+                    None,
+                    err,
+                ) from err
+            self._playwright = await async_playwright().start()
+        return self._playwright.chromium
+
+    async def _probe_browser_health(self, browser: Any, timeout_ms: int) -> None:
+        """Prove the browser actually works before handing it back.
+
+        A slot can accept the WS connect and still be wedged; without this, launch()
+        returns a browser that fails on first use. Any failure is normalised to
+        BROWSER_UNHEALTHY so launch()'s retry loop can act on it.
+        """
+
+        async def probe() -> None:
+            ctx = await browser.new_context()
+            try:
+                page = await ctx.new_page()
+                await page.evaluate("1")
+            finally:
+                try:
+                    await ctx.close()
+                except Exception:  # noqa: BLE001
+                    pass
+
+        try:
+            await asyncio.wait_for(probe(), timeout=timeout_ms / 1000.0)
+        except asyncio.TimeoutError as err:
+            raise SolariError(
+                f"Solari: browser health probe timed out after {timeout_ms}ms",
+                None,
+                err,
+                BROWSER_UNHEALTHY,
+            ) from err
+        except Exception as err:  # noqa: BLE001
+            if isinstance(err, SolariError) and err.code == BROWSER_UNHEALTHY:
+                raise
+            raise SolariError(
+                f"Solari: browser health probe failed: {err}", None, err, BROWSER_UNHEALTHY
+            ) from err
+
+
+def _q(v: str) -> str:
+    from urllib.parse import quote
+
+    return quote(v, safe="")
+
+
+def _json(res: httpx.Response, what: str) -> Any:
+    try:
+        return res.json()
+    except Exception as err:  # noqa: BLE001
+        raise SolariError(
+            f"Solari: {what} response was not valid JSON: {res.text[:256]}", res.status_code, err
+        ) from err
+
+
+async def _fetch_presigned_storage_state(url: Optional[str]) -> Optional[StorageState]:
+    """GET the presigned storage-state object. `None` url means an empty profile."""
+    if not url:
+        return None
+    try:
+        async with httpx.AsyncClient(timeout=_STORAGE_STATE_TIMEOUT_S) as http:
+            res = await http.get(url)
+    except Exception as err:  # noqa: BLE001
+        raise SolariError(f"Solari: failed to fetch storageState: {err}", None, err) from err
+    if res.status_code >= 400:
+        raise SolariError(
+            f"Solari: storageState fetch returned {res.status_code}: {res.text[:256]}",
+            res.status_code,
+        )
+    try:
+        return res.json()
+    except Exception as err:  # noqa: BLE001
+        raise SolariError(
+            f"Solari: storageState response was not valid JSON: {err}", None, err
+        ) from err

solari_browser/errors.py

@@ -0,0 +1,68 @@
+"""Errors for the Solari Browser SDK. Mirrors `SolariError` in sdk/src/index.ts."""
+
+from __future__ import annotations
+
+from typing import Any, Optional
+
+# Codes the gateway returns in the `code` field of an error body. Mirrors
+# `SolariErrorCode` (sdk/src/index.ts). Kept as plain strings, not an Enum: the
+# gateway may add codes we don't know yet, and an Enum would raise on those
+# rather than pass them through to the caller.
+FEATURE_REQUIRES_PLAN = "FeatureRequiresPlan"
+CONCURRENCY_LIMIT_EXCEEDED = "ConcurrencyLimitExceeded"
+PLAN_LIMIT_EXCEEDED = "PlanLimitExceeded"
+BROWSER_UNHEALTHY = "BrowserUnhealthy"
+
+
+class SolariError(Exception):
+    """Raised for every Solari failure.
+
+    Attributes:
+        status: HTTP status, when the failure came from an HTTP response.
+        cause:  The underlying exception, when there was one.
+        code:   Gateway error code (see the constants above), when the response
+                body carried one. `code == BROWSER_UNHEALTHY` is what makes
+                `launch(retries=...)` retry.
+    """
+
+    def __init__(
+        self,
+        message: str,
+        status: Optional[int] = None,
+        cause: Optional[BaseException] = None,
+        code: Optional[str] = None,
+    ) -> None:
+        super().__init__(message)
+        self.status = status
+        self.cause = cause
+        self.code = code
+
+    def __str__(self) -> str:  # pragma: no cover - trivial
+        base = super().__str__()
+        bits = []
+        if self.status is not None:
+            bits.append(f"status={self.status}")
+        if self.code:
+            bits.append(f"code={self.code}")
+        return f"{base} ({', '.join(bits)})" if bits else base
+
+
+def code_from_body(text: str) -> Optional[str]:
+    """Best-effort extract of `{"code": "..."}` from an error body.
+
+    The gateway returns a JSON body with a `code` on plan/concurrency errors, but
+    error bodies are not guaranteed to be JSON at all (proxies, 502 HTML pages),
+    so every failure here is swallowed — a missing code must never mask the real
+    HTTP error.
+    """
+    import json
+
+    try:
+        parsed: Any = json.loads(text)
+    except Exception:
+        return None
+    if isinstance(parsed, dict):
+        code = parsed.get("code")
+        if isinstance(code, str):
+            return code
+    return None

solari_browser/types.py

@@ -0,0 +1,141 @@
+"""Wire types for the Solari Browser SDK. Mirrors the interfaces in sdk/src/index.ts.
+
+Dataclasses (not TypedDicts) so callers get attribute access + IDE completion, with
+`from_wire` classmethods doing the camelCase→snake_case mapping in one place.
+"""
+
+from __future__ import annotations
+
+from dataclasses import dataclass, field
+from typing import Any, Dict, List, Literal, Optional, Union
+
+# Supported regions. More coming soon. Mirrors `SolariRegion`.
+Region = Literal["us-west"]
+REGION_URLS: Dict[str, str] = {
+    "us-west": "https://api.getsolari.com",
+}
+DEFAULT_REGION: str = "us-west"
+
+ProxyTier = Literal["residential", "static", "mobile"]
+
+# A Playwright storage state (cookies + origins/localStorage). Left as a plain dict:
+# it is passed straight through to patchright's `storage_state`, so imposing our own
+# schema would only risk drifting from Playwright's.
+StorageState = Dict[str, Any]
+
+
+@dataclass
+class ProxyRequest:
+    """Managed proxy egress request. Mirrors `ProxyRequest`."""
+
+    country: Optional[str] = None  # ISO-3166-1 alpha-2, lowercase. Defaults to "us".
+    tier: Optional[ProxyTier] = None  # residential (default, rotating) | static | mobile
+    asn: Optional[str] = None  # pin egress ASN, e.g. "20057" (AT&T Mobility)
+    session: Optional[str] = None  # sticky id, alnum + dash, <=32 chars
+    session_duration: Optional[int] = None  # sticky lifetime, minutes (1-30, default 10)
+    state: Optional[str] = None  # US-only, e.g. "california"
+    city: Optional[str] = None  # US-only, e.g. "los_angeles"
+
+    def to_wire(self) -> Dict[str, Any]:
+        """Only non-None keys are sent — the gateway distinguishes absent from null."""
+        wire: Dict[str, Any] = {}
+        if self.country is not None:
+            wire["country"] = self.country
+        if self.tier is not None:
+            wire["tier"] = self.tier
+        if self.asn is not None:
+            wire["asn"] = self.asn
+        if self.session is not None:
+            wire["session"] = self.session
+        if self.session_duration is not None:
+            wire["sessionDuration"] = self.session_duration
+        if self.state is not None:
+            wire["state"] = self.state
+        if self.city is not None:
+            wire["city"] = self.city
+        return wire
+
+
+# `proxy=` accepts the same shapes as the TS SDK: a country string ("us"), a
+# ProxyRequest, or the "off"/"smart" sentinels.
+ProxySpec = Union[str, ProxyRequest]
+
+
+@dataclass
+class ResolvedProxyConfig:
+    """Resolved proxy credentials returned on the session response."""
+
+    server: str
+    username: str
+    password: str
+    timezone_id: str
+    country: str
+    tier: Optional[ProxyTier] = None
+
+    @classmethod
+    def from_wire(cls, d: Dict[str, Any]) -> "ResolvedProxyConfig":
+        return cls(
+            server=d.get("server", ""),
+            username=d.get("username", ""),
+            password=d.get("password", ""),
+            timezone_id=d.get("timezoneId", ""),
+            country=d.get("country", ""),
+            tier=d.get("tier"),
+        )
+
+
+# Sentinel distinguishing "no profile attached" from "profile exists but empty".
+# The TS SDK encodes this as undefined vs null on `Session.storageState`; Python has
+# only None, so absence is this sentinel and empty-profile is None.
+class _Unset:
+    def __repr__(self) -> str:  # pragma: no cover - trivial
+        return "UNSET"
+
+    def __bool__(self) -> bool:
+        return False
+
+
+UNSET = _Unset()
+
+
+@dataclass
+class Session:
+    """A live browser session.
+
+    NOTE: unlike the TS SDK, `ws_endpoint`/`cdp_endpoint` are the UPSTREAM gateway
+    URLs. The TS SDK rewrites them to a loopback LocalProxy for connect-retry
+    purposes; that is a Node-specific device and is deliberately not reproduced here.
+    """
+
+    id: str
+    ws_endpoint: str  # Playwright wire protocol — for chromium.connect()
+    cdp_endpoint: str  # raw CDP — for connect_over_cdp() / other CDP clients
+    expires_at: str  # ISO 8601 UTC; session auto-releases at this point
+    storage_state: Union[StorageState, None, _Unset] = UNSET
+    proxy: Optional[ResolvedProxyConfig] = None
+
+
+@dataclass
+class Profile:
+    """A stored browser profile (cookies + localStorage)."""
+
+    id: str
+    name: str
+    raw: Dict[str, Any] = field(default_factory=dict)  # full wire object, forward-compatible
+
+    @classmethod
+    def from_wire(cls, d: Dict[str, Any]) -> "Profile":
+        return cls(id=d.get("id", ""), name=d.get("name", ""), raw=d)
+
+
+@dataclass
+class ReplayUrl:
+    url: str
+    expires_in_seconds: int = 0
+    content_encoding: str = "gzip"
+
+
+@dataclass
+class SaveResult:
+    version: int = 0
+    size_bytes: int = 0

solari_browser-0.1.1.dist-info/METADATA

@@ -0,0 +1,66 @@
+Metadata-Version: 2.4
+Name: solari-browser
+Version: 0.1.1
+Summary: Python SDK for Solari Browser — managed, stealthy remote Chromium over the Playwright wire protocol / raw CDP.
+Project-URL: Homepage, https://getsolari.com
+Author: Solari
+License: Apache-2.0
+Keywords: automation,browser,cdp,playwright,scraping,solari,stealth
+Requires-Python: >=3.9
+Requires-Dist: httpx>=0.24
+Requires-Dist: patchright<1.60,>=1.59
+Provides-Extra: dev
+Requires-Dist: pytest>=7; extra == 'dev'
+Requires-Dist: ruff>=0.1; extra == 'dev'
+Description-Content-Type: text/markdown
+
+# solari-browser (Python)
+
+Python SDK for **Solari Browser** — managed, stealth-hardened remote Chromium as
+an API, driven over the Playwright wire protocol (or raw CDP). A faithful port of
+the TypeScript `@solarisdk/browser` package; class, method, and field names match
+it one-for-one (snake_case where TS uses camelCase).
+
+The browser runs remotely on Solari's pool — `pip install` pulls the driver only;
+you do **not** run `patchright install chromium` locally.
+
+## Install
+
+```sh
+pip install solari-browser
+```
+
+## Quickstart
+
+```python
+import asyncio, os
+from solari_browser import Solari
+
+async def main():
+    solari = Solari(api_key=os.environ["SOLARI_API_KEY"])
+    browser = await solari.launch(stealth=True)   # managed, stealth-hardened Chromium
+    page = await browser.new_page()
+    await page.goto("https://example.com")
+    print(await page.title())
+    await browser.close()
+
+asyncio.run(main())
+```
+
+## Sessions
+
+Drive a session yourself instead of `launch()`:
+
+```python
+solari = Solari(api_key=os.environ["SOLARI_API_KEY"])
+session = await solari.sessions.create(stealth=True, proxy="smart")
+# ... connect over the session's CDP/WS endpoint ...
+await solari.close()
+```
+
+`Solari(...)` accepts `api_key`, `region` (default `us-west`), and `base_url`
+(default `https://api.getsolari.com`).
+
+## Docs
+
+Full reference and language guides: <https://getsolari.com>

solari_browser-0.1.1.dist-info/RECORD

@@ -0,0 +1,8 @@
+solari_browser/__init__.py,sha256=GjqnjKtFeqZFVVz63cXAKoWvgCHIooLcoP-BFWhbUgw,1329
+solari_browser/browser_session.py,sha256=Dfm-4t-yU_wdRdlDD7cwxc5_ax0x2qsxf8KsdWsmf-o,2840
+solari_browser/client.py,sha256=XMRiUeLG_oYGStRFlsZ13P3xYTheBQUi-snYQ2ub9NE,19674
+solari_browser/errors.py,sha256=56M753QaLnV_pKaV_Tg18tllJpWoyXwzbPkx-0Izug4,2319
+solari_browser/types.py,sha256=CVY9vXlIbGLbpZa2-ILpZ75W_uXx0gxIBiEhLKnCfCk,4664
+solari_browser-0.1.1.dist-info/METADATA,sha256=LwWa8ip1jkmu-qg3JfFd7LaAKTsxv0qjumcKEhsunLU,1943
+solari_browser-0.1.1.dist-info/WHEEL,sha256=lCkmxWfQsSc9CfIClYeavTdQeEX2toPqufh9gI35EQA,87
+solari_browser-0.1.1.dist-info/RECORD,,

solari_browser-0.1.1.dist-info/WHEEL

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