solari-browserbase-compat 0.1.0__tar.gz

solari_browserbase_compat-0.1.0/.gitignore

@@ -0,0 +1,5 @@
+__pycache__/
+*.pyc
+target/
+node_modules/
+dist/

solari_browserbase_compat-0.1.0/COMPAT.md

@@ -0,0 +1,68 @@
+# Browserbase compatibility — what works, what differs, what raises
+
+`solari-browserbase-compat` gives Solari Browser the shape of the Browserbase Python SDK, so code written against
+`Browserbase(api_key=...)` runs against Solari with the import and the key changed. This page is the full list.
+
+```python
+from solari_browserbase import Browserbase
+from playwright.sync_api import sync_playwright
+
+bb = Browserbase(api_key=os.environ["SOLARI_API_KEY"])  # slr_… key
+session = bb.sessions.create(browser_settings={"recordSession": True})
+with sync_playwright() as p:
+    browser = p.chromium.connect_over_cdp(session.connect_url)
+    # … drive the page …
+    browser.close()
+bb.sessions.update(session.id, status="REQUEST_RELEASE")
+```
+
+`connect_url` is a raw CDP websocket URL, so any CDP client works and **nothing needs a pinned Playwright version**.
+Keep it private: the session id inside it is the credential. `AsyncBrowserbase` has the same methods (each call runs
+the sync client in a worker thread). Parameter names are snake_case at the top level (`keep_alive`, `user_metadata`,
+`browser_settings`); keys inside `browser_settings` stay camelCase, as in Browserbase's Python SDK.
+
+## Keys and endpoint
+| | |
+|---|---|
+| Key | `api_key` argument, else `SOLARI_API_KEY`, else `BROWSERBASE_API_KEY`. **A key that does not start with `slr_` is never used or sent** (it is probably a Browserbase secret): it is skipped with a warning that does not print it, and if no `slr_` key remains the constructor throws. |
+| Endpoint | `base_url` argument or `SOLARI_BASE_URL`; default `https://api.getsolari.com`. |
+| `project_id` | Accepted and ignored: Solari keys belong to an organisation, there are no projects. |
+
+## Works
+| Browserbase | Here |
+|---|---|
+| `sessions.create` | `POST /sessions`; returns `connect_url` (CDP), `id`, `status: "RUNNING"`, `expiresAt`, `region`, `keepAlive`, `contextId`. A create is retried safely (idempotency key). |
+| `sessions.retrieve`, `sessions.list(status=...)` | Solari `active/released/expired/unknown` map to `RUNNING/COMPLETED/TIMED_OUT/ERROR`. `proxyBytes` is `0`, `startedAt` is the create time. |
+| `sessions.update(id, status="REQUEST_RELEASE")` | Releases the session. |
+| `proxies: true`, `proxies: [{ type: "browserbase", geolocation }]` | A managed proxy; `geolocation.country/state/city` map across (a proxy needs the stealth browser, so `stealth` is switched on for you). `{ type: "none" }` means no proxy. |
+| `browserSettings.verified`, `advancedStealth` | Solari's stealth browser. |
+| `browserSettings.solveCaptchas: true` | Solari captcha solving (stealth browser, plan-gated). **Off unless you pass `true`**: Browserbase turns it on by default. |
+| `browserSettings.recordSession: true` | Session recording. **Off unless you pass `true`**: Browserbase records by default. Read it back with `sessions.recording.retrieve(id)` (rrweb events). |
+| `browserSettings.allowedDomains` | Egress allowlist (enterprise plan, stealth browser); a plan error comes back as an `APIError` with `code: "FeatureRequiresPlan"`. |
+| `browserSettings.context: { id, persist }`, `contexts.create/retrieve/delete` | A Context is a Solari **profile**. See [Contexts](#contexts). |
+| `sessions.debug(id, expires_in=...)` | A view-only live-view link (`debuggerUrl` and `debuggerFullscreenUrl` are the same link; `pages` is empty; `wsUrl` is the CDP URL). |
+
+## Differs (documented, not errors)
+- **Recording is a DOM-event log, not video.** `sessions.recording.retrieve(id)` returns rrweb events once the replay has been uploaded (a few seconds after release; until then it throws `APIError` with `code: "ReplayPending"`). There is no HLS playlist and no MP4.
+- **Contexts store cookies and localStorage only** (Playwright `storageState`), not IndexedDB, service workers or autofill data.
+- **No choice of operating system or viewport at create time.** Set the viewport from your automation client.
+- **`keepAlive`**: a disconnected session is released about 45 s after its socket closes (reconnect with the same `connect_url` inside that window). Sessions end at your plan's maximum session length.
+- **`timeout`, `userMetadata`, `keepAlive: true`, `viewport`, `blockAds: true`, `logSession: true`, `os`** are accepted with a one-line warning and have no effect. Pass `strict=True` to make them throw instead.
+
+## Contexts
+```python
+ctx = bb.contexts.create(name="shop-login")
+s = bb.sessions.create(browser_settings={"context": {"id": ctx.id, "persist": True}})
+browser = p.chromium.connect_over_cdp(s.connect_url)
+# First run: log in, then release; the context is saved when you release through this client.
+bb.sessions.update(s.id, status="REQUEST_RELEASE")
+
+# Later: the saved login comes back as `storage_state`. Create your browser context with it:
+s2 = bb.sessions.create(browser_settings={"context": {"id": ctx.id}})
+b2 = p.chromium.connect_over_cdp(s2.connect_url)
+page = b2.new_context(storage_state=s2.storage_state).new_page()
+```
+Two differences from Browserbase: Solari applies a saved context only to a browser context created *with* it (use `new_context(storage_state=...)`, not `browser.contexts[0]`), and `persist: True` saves when you release **through the same client object** (it is remembered in memory).
+
+## Raises `SolariCompatUnsupported`
+Extensions (`extension_id`), the Selenium endpoint (`seleniumRemoteUrl` is always empty), downloads (`sessions.downloads`) and uploads (`sessions.uploads`) APIs, video replays (`sessions.replays`), session logs (`sessions.logs`), external/bring-your-own proxies, per-domain proxy rules (`domainPattern`), custom CA certificates, `ignoreCertificateErrors: true`, custom captcha selectors, `os: "mobile" | "tablet"`, a `region` other than `us-west-2` (or `us-west`), `sessions.list(q=...)` (metadata queries), `contexts.update`, and the separate `projects`, `extensions`, `agents`, `fetch_api` and `search` resources.

solari_browserbase_compat-0.1.0/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Solari
+
+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.

solari_browserbase_compat-0.1.0/PKG-INFO

@@ -0,0 +1,44 @@
+Metadata-Version: 2.5
+Name: solari-browserbase-compat
+Version: 0.1.0
+Summary: Browserbase-style Python SDK surface for Solari Browser: sessions, connect_url (CDP), contexts, live view, replay events.
+Project-URL: Homepage, https://getsolari.com
+Author: Solari
+License: MIT
+License-File: LICENSE
+Keywords: browser,browserbase,cdp,compat,playwright,solari
+Requires-Python: >=3.9
+Requires-Dist: httpx>=0.24
+Provides-Extra: dev
+Requires-Dist: pytest>=7; extra == 'dev'
+Requires-Dist: ruff>=0.1; extra == 'dev'
+Description-Content-Type: text/markdown
+
+# solari-browserbase-compat
+
+A Browserbase-shaped Python SDK for [Solari Browser](https://getsolari.com): change the import and the key, keep your code.
+
+```bash
+pip install solari-browserbase-compat
+```
+
+```python
+import os
+from solari_browserbase import Browserbase
+from playwright.sync_api import sync_playwright
+
+bb = Browserbase(api_key=os.environ["SOLARI_API_KEY"])  # slr_… key
+session = bb.sessions.create()
+with sync_playwright() as p:
+    browser = p.chromium.connect_over_cdp(session.connect_url)
+    page = browser.contexts[0].pages[0] if browser.contexts[0].pages else browser.contexts[0].new_page()
+    page.goto("https://example.com")
+    browser.close()
+bb.sessions.update(session.id, status="REQUEST_RELEASE")
+```
+
+Sessions, contexts, live view and recording are supported; extensions, downloads/uploads APIs, video replays,
+bring-your-own proxies and Selenium raise `SolariCompatUnsupported`. See [COMPAT.md](./COMPAT.md) for the full list
+and every difference. Python 3.9+. No Playwright version pin is needed: `connect_url` is a plain CDP endpoint.
+
+Licence: MIT.

solari_browserbase_compat-0.1.0/README.md

@@ -0,0 +1,28 @@
+# solari-browserbase-compat
+
+A Browserbase-shaped Python SDK for [Solari Browser](https://getsolari.com): change the import and the key, keep your code.
+
+```bash
+pip install solari-browserbase-compat
+```
+
+```python
+import os
+from solari_browserbase import Browserbase
+from playwright.sync_api import sync_playwright
+
+bb = Browserbase(api_key=os.environ["SOLARI_API_KEY"])  # slr_… key
+session = bb.sessions.create()
+with sync_playwright() as p:
+    browser = p.chromium.connect_over_cdp(session.connect_url)
+    page = browser.contexts[0].pages[0] if browser.contexts[0].pages else browser.contexts[0].new_page()
+    page.goto("https://example.com")
+    browser.close()
+bb.sessions.update(session.id, status="REQUEST_RELEASE")
+```
+
+Sessions, contexts, live view and recording are supported; extensions, downloads/uploads APIs, video replays,
+bring-your-own proxies and Selenium raise `SolariCompatUnsupported`. See [COMPAT.md](./COMPAT.md) for the full list
+and every difference. Python 3.9+. No Playwright version pin is needed: `connect_url` is a plain CDP endpoint.
+
+Licence: MIT.

solari_browserbase_compat-0.1.0/pyproject.toml

@@ -0,0 +1,28 @@
+[build-system]
+requires = ["hatchling"]
+build-backend = "hatchling.build"
+
+[project]
+name = "solari-browserbase-compat"
+version = "0.1.0"
+description = "Browserbase-style Python SDK surface for Solari Browser: sessions, connect_url (CDP), contexts, live view, replay events."
+readme = "README.md"
+requires-python = ">=3.9"
+license = { text = "MIT" }
+authors = [{ name = "Solari" }]
+keywords = ["solari", "browserbase", "browser", "playwright", "cdp", "compat"]
+# Pure HTTP: no Playwright / patchright dependency. connect_url is a raw CDP endpoint, so any CDP client works
+# without a pinned version.
+dependencies = ["httpx>=0.24"]
+
+[project.optional-dependencies]
+dev = ["pytest>=7", "ruff>=0.1"]
+
+[project.urls]
+Homepage = "https://getsolari.com"
+
+[tool.hatch.build.targets.wheel]
+packages = ["solari_browserbase"]
+
+[tool.ruff]
+line-length = 110

solari_browserbase_compat-0.1.0/solari_browserbase/__init__.py

@@ -0,0 +1,22 @@
+"""Browserbase-style Python SDK surface for Solari Browser. See COMPAT.md for what is and is not supported."""
+from .client import (
+    AsyncBrowserbase,
+    Browserbase,
+    Context,
+    ContextCreateResponse,
+    DEFAULT_BASE_URL,
+    Session,
+    SessionCreateResponse,
+    SessionLiveURLs,
+    SessionRetrieveResponse,
+)
+from .errors import APIError, BrowserbaseError, SolariCompatUnsupported
+from .mapping import map_create_params, map_status
+
+__version__ = "0.1.0"
+
+__all__ = [
+    "AsyncBrowserbase", "Browserbase", "APIError", "BrowserbaseError", "SolariCompatUnsupported",
+    "Context", "ContextCreateResponse", "Session", "SessionCreateResponse", "SessionRetrieveResponse",
+    "SessionLiveURLs", "DEFAULT_BASE_URL", "map_create_params", "map_status",
+]

solari_browserbase_compat-0.1.0/solari_browserbase/client.py

@@ -0,0 +1,378 @@
+from __future__ import annotations
+
+import asyncio
+import gzip
+import json
+import os
+import time
+import uuid
+import warnings as _warnings
+from dataclasses import dataclass, field
+from typing import Any, Callable, Dict, List, Optional
+
+import httpx
+
+from .errors import APIError, BrowserbaseError, SolariCompatUnsupported
+from .mapping import map_create_params, map_status
+
+DEFAULT_BASE_URL = "https://api.getsolari.com"
+REGION = "us-west-2"  # reported on Browserbase-shaped objects; Solari's single region (us-west)
+
+
+@dataclass
+class Session:
+    id: str
+    created_at: str
+    updated_at: str
+    project_id: str
+    started_at: str
+    expires_at: str
+    status: str
+    proxy_bytes: int
+    keep_alive: bool
+    region: str
+    ended_at: Optional[str] = None
+    context_id: Optional[str] = None
+    user_metadata: Optional[Dict[str, Any]] = None
+
+
+@dataclass
+class SessionCreateResponse(Session):
+    # CDP websocket URL: playwright `connect_over_cdp(connect_url)` / any CDP client.
+    connect_url: str = ""
+    selenium_remote_url: str = ""  # always empty: no WebDriver endpoint
+    signing_key: str = ""  # always empty: the session id in the URL is the credential
+    # Solari extension. For a session created with browserSettings.context: the saved cookies/localStorage.
+    # Solari applies a saved context only to a browser context created with it, so create yours with
+    # browser.new_context(storage_state=session.storage_state). None when no context was requested.
+    storage_state: Optional[Dict[str, Any]] = None
+
+
+SessionRetrieveResponse = SessionCreateResponse
+
+
+@dataclass
+class SessionLiveURLs:
+    debugger_fullscreen_url: str
+    debugger_url: str
+    ws_url: str
+    pages: List[Dict[str, Any]] = field(default_factory=list)
+
+
+@dataclass
+class Context:
+    id: str
+    name: Optional[str] = None
+    created_at: Optional[str] = None
+
+
+@dataclass
+class ContextCreateResponse:
+    id: str
+    public_key: str = ""  # empty: Solari profiles are stored server-side
+    cipher_algorithm: str = ""
+    initialization_vector_size: int = 0
+
+
+class _Unsupported:
+    """Every attribute is a callable that raises SolariCompatUnsupported."""
+
+    def __init__(self, feature: str, hint: str) -> None:
+        self._feature = feature
+        self._hint = hint
+
+    def __getattr__(self, name: str) -> Callable[..., Any]:
+        if name.startswith("__"):
+            raise AttributeError(name)
+
+        def _raise(*_a: Any, **_k: Any) -> Any:
+            raise SolariCompatUnsupported(f"{self._feature}.{name}", self._hint)
+
+        return _raise
+
+
+def _resolve_api_key(explicit: Optional[str], warn: Callable[[str], None]) -> str:
+    for name, v in (
+        ("api_key", explicit),
+        ("SOLARI_API_KEY", os.environ.get("SOLARI_API_KEY")),
+        ("BROWSERBASE_API_KEY", os.environ.get("BROWSERBASE_API_KEY")),
+    ):
+        if not v:
+            continue
+        if v.startswith("slr_"):
+            return v
+        # Never echo any part of the value: it is probably a Browserbase secret.
+        warn(f"{name} does not look like a Solari key (expected the slr_ prefix); ignoring it. It was not sent anywhere.")
+    raise BrowserbaseError("No Solari API key: pass api_key or set SOLARI_API_KEY (keys start with slr_)")
+
+
+def _default_warn(msg: str) -> None:
+    _warnings.warn(f"[solari-browserbase-compat] {msg}", stacklevel=3)
+
+
+def _session(row: Dict[str, Any], *, status: Optional[str] = None, keep_alive: bool = False, context_id: Optional[str] = None) -> Session:
+    created = row.get("createdAt") or time.strftime("%Y-%m-%dT%H:%M:%SZ", time.gmtime())
+    st = status or map_status(row.get("status"))
+    return Session(
+        id=row["id"],
+        created_at=created,
+        updated_at=created,
+        project_id="",
+        started_at=created,
+        ended_at=time.strftime("%Y-%m-%dT%H:%M:%SZ", time.gmtime()) if st in ("COMPLETED", "TIMED_OUT") else None,
+        expires_at=row.get("expiresAt") or created,
+        status=st,
+        proxy_bytes=0,
+        keep_alive=keep_alive,
+        region=REGION,
+        context_id=context_id,
+    )
+
+
+class _Http:
+    def __init__(self, api_key: str, base_url: str, timeout: float, max_retries: int, transport: Optional[httpx.BaseTransport]) -> None:
+        self.api_key = api_key
+        self.base_url = base_url.rstrip("/")
+        self.max_retries = max_retries
+        self.client = httpx.Client(timeout=timeout, transport=transport)
+
+    def request(self, method: str, path: str, body: Any = None, idempotency_key: Optional[str] = None) -> httpx.Response:
+        headers = {"Authorization": f"Bearer {self.api_key}", "Content-Type": "application/json"}
+        if idempotency_key:
+            headers["Idempotency-Key"] = idempotency_key
+        replay_safe = method in ("GET", "DELETE") or idempotency_key is not None
+        last: Optional[Exception] = None
+        for attempt in range(self.max_retries + 1):
+            try:
+                res = self.client.request(method, f"{self.base_url}{path}", headers=headers, content=None if body is None else json.dumps(body))
+                if res.is_success or not replay_safe or res.status_code not in (502, 503, 504) or attempt == self.max_retries:
+                    return res
+            except httpx.TransportError as e:
+                if not replay_safe or attempt == self.max_retries:
+                    raise
+                last = e
+            time.sleep(0.3 * (attempt + 1))
+        raise last or BrowserbaseError("request failed")
+
+    def json(self, method: str, path: str, body: Any = None, idempotency_key: Optional[str] = None) -> Any:
+        res = self.request(method, path, body, idempotency_key)
+        if res.status_code == 204:
+            return None
+        text = res.text
+        try:
+            parsed = json.loads(text) if text else None
+        except ValueError:
+            parsed = None
+        if not res.is_success:
+            o = parsed if isinstance(parsed, dict) else {}
+            raise APIError(res.status_code, f"Solari {method} {path}: {res.status_code} {o.get('error') or text[:200]}", o.get("code"), parsed)
+        return parsed
+
+
+class _Recording:
+    def __init__(self, http: _Http) -> None:
+        self._http = http
+
+    def retrieve(self, id: str) -> List[Any]:
+        """The session's DOM recording as a list of rrweb events (needs ``recordSession: True``; available a few seconds after release)."""
+        meta = self._http.json("GET", f"/sessions/{id}/replay-url")
+        url = (meta or {}).get("url")
+        if not url:
+            raise BrowserbaseError("Solari returned no replay URL")
+        r = httpx.get(url, timeout=60)
+        if not r.is_success:
+            raise APIError(r.status_code, f"replay download failed: {r.status_code}")
+        data = r.content
+        if data[:2] == b"\x1f\x8b":
+            data = gzip.decompress(data)
+        return [json.loads(line) for line in data.decode("utf-8").split("\n") if line.strip()]
+
+
+class _Sessions:
+    def __init__(self, bb: "Browserbase") -> None:
+        self._bb = bb
+        self.recording = _Recording(bb._http)
+        self.replays = _Unsupported("sessions.replays", "Solari records DOM events, not video; use sessions.recording.retrieve")
+        self.logs = _Unsupported("sessions.logs", "session command logs are not available")
+        self.downloads = _Unsupported("sessions.downloads", "file downloads cannot be retrieved through the API")
+        self.uploads = _Unsupported("sessions.uploads", "use your automation client's set_input_files")
+
+    def create(
+        self,
+        *,
+        project_id: Optional[str] = None,
+        extension_id: Optional[str] = None,
+        browser_settings: Optional[Dict[str, Any]] = None,
+        timeout: Optional[int] = None,
+        keep_alive: Optional[bool] = None,
+        proxies: Any = None,
+        proxy_settings: Optional[Dict[str, Any]] = None,
+        region: Optional[str] = None,
+        user_metadata: Optional[Dict[str, Any]] = None,
+    ) -> SessionCreateResponse:
+        m = map_create_params(
+            extension_id=extension_id, browser_settings=browser_settings, timeout=timeout, keep_alive=keep_alive,
+            proxies=proxies, proxy_settings=proxy_settings, region=region, user_metadata=user_metadata, strict=self._bb._strict,
+        )
+        for w in m.warnings:
+            self._bb._warn(w)
+        data = self._bb._http.json("POST", "/sessions", m.body or None, idempotency_key=str(uuid.uuid4()))
+        if not data or not data.get("sessionId") or not data.get("cdpEndpoint"):
+            raise BrowserbaseError(f"Solari returned an unexpected session response: {data!r}")
+        if m.persist_profile_id:
+            self._bb._persist[data["sessionId"]] = m.persist_profile_id
+        ctx = ((browser_settings or {}).get("context") or {}).get("id")
+        base = _session(
+            {"id": data["sessionId"], "createdAt": None, "expiresAt": data.get("expiresAt")},
+            status="RUNNING", keep_alive=keep_alive is True, context_id=ctx,
+        )
+        out = SessionCreateResponse(**base.__dict__, connect_url=data["cdpEndpoint"])
+        if ctx:
+            state = data.get("storageState")
+            url = (data.get("storageStateUrl") or {}).get("url")
+            if state is None and url:
+                try:
+                    r = self._bb._http.client.get(url, timeout=15)
+                    state = r.json() if r.is_success else None
+                except (httpx.HTTPError, ValueError):
+                    state = None
+                if state is None:
+                    self._bb._warn("could not download the saved context; the session starts without it")
+            out.storage_state = state
+        return out
+
+    def retrieve(self, id: str) -> SessionRetrieveResponse:
+        row = self._bb._http.json("GET", f"/sessions/{id}") or {}
+        row.setdefault("id", id)
+        return SessionCreateResponse(**_session(row).__dict__, connect_url=row.get("cdpEndpoint") or "")
+
+    def list(self, *, status: Optional[str] = None, q: Optional[str] = None) -> List[Session]:
+        if q:
+            raise SolariCompatUnsupported("sessions.list q (user_metadata query)", "metadata is not stored")
+        data = self._bb._http.json("GET", "/sessions") or {}
+        out = [_session(r) for r in data.get("sessions", [])]
+        return [s for s in out if s.status == status] if status else out
+
+    def update(self, id: str, *, status: str, project_id: Optional[str] = None) -> Session:
+        """``status="REQUEST_RELEASE"`` releases the session (saving the context first when it was created with persist)."""
+        if status != "REQUEST_RELEASE":
+            raise SolariCompatUnsupported(f"sessions.update status {status}", "only REQUEST_RELEASE exists")
+        profile_id = self._bb._persist.get(id)
+        if profile_id:
+            self._bb._http.json("POST", f"/sessions/{id}/save-profile", {"profileId": profile_id})
+            self._bb._persist.pop(id, None)
+        self._bb._http.json("DELETE", f"/sessions/{id}")
+        return _session({"id": id, "status": "released"}, status="COMPLETED")
+
+    def debug(self, id: str, *, expires_in: Optional[int] = None) -> SessionLiveURLs:
+        """Live-view links. Both URLs are the same view-only share link; ``pages`` is empty."""
+        share = self._bb._http.json("POST", f"/sessions/{id}/shares", {} if expires_in is None else {"ttlSeconds": expires_in})
+        row = self._bb._http.json("GET", f"/sessions/{id}") or {}
+        return SessionLiveURLs(share["url"], share["url"], row.get("cdpEndpoint") or "", [])
+
+
+class _Contexts:
+    def __init__(self, http: _Http) -> None:
+        self._http = http
+
+    def create(self, *, project_id: Optional[str] = None, name: Optional[str] = None) -> ContextCreateResponse:
+        """A Context is a Solari profile (cookies + localStorage)."""
+        p = self._http.json("POST", "/profiles", {"name": name or f"context-{uuid.uuid4().hex[:8]}"})
+        return ContextCreateResponse(id=p["id"])
+
+    def retrieve(self, id: str) -> Context:
+        for p in self._http.json("GET", "/profiles") or []:
+            if p.get("id") == id:
+                return Context(id=p["id"], name=p.get("name"), created_at=p.get("createdAt"))
+        raise APIError(404, f"context {id} not found", "NotFound")
+
+    def update(self, *_a: Any, **_k: Any) -> Any:
+        raise SolariCompatUnsupported("contexts.update", "contexts are saved when a persist session is released")
+
+    def delete(self, id: str) -> None:
+        self._http.json("DELETE", f"/profiles/{id}")
+
+
+class Browserbase:
+    """Browserbase-shaped client for Solari Browser. ``connect_url`` is a raw CDP websocket URL."""
+
+    def __init__(
+        self,
+        *,
+        api_key: Optional[str] = None,
+        base_url: Optional[str] = None,
+        strict: bool = False,
+        on_warning: Optional[Callable[[str], None]] = None,
+        max_retries: int = 2,
+        timeout: float = 60.0,
+        transport: Optional[httpx.BaseTransport] = None,
+    ) -> None:
+        self._warn = on_warning or _default_warn
+        self._strict = strict
+        key = _resolve_api_key(api_key, self._warn)
+        self._http = _Http(key, base_url or os.environ.get("SOLARI_BASE_URL") or DEFAULT_BASE_URL, timeout, max_retries, transport)
+        self._persist: Dict[str, str] = {}  # session id -> profile to save on release (in-process only)
+        self._api_key = key
+        self.sessions = _Sessions(self)
+        self.contexts = _Contexts(self._http)
+        self.extensions = _Unsupported("extensions", "browser extensions cannot be loaded")
+        self.projects = _Unsupported("projects", "Solari keys are organisation-scoped; there are no projects")
+        self.agents = _Unsupported("agents", "Browserbase Agents is a separate product")
+        self.fetch_api = _Unsupported("fetch_api", "Browserbase Fetch is a separate product")
+        self.search = _Unsupported("search", "Browserbase Search is a separate product")
+
+    @property
+    def api_key(self) -> str:
+        return self._api_key
+
+    def __repr__(self) -> str:
+        return f"Browserbase(base_url={self._http.base_url!r})"
+
+    def close(self) -> None:
+        self._http.client.close()
+
+    def __enter__(self) -> "Browserbase":
+        return self
+
+    def __exit__(self, *_a: Any) -> None:
+        self.close()
+
+
+class _AsyncProxy:
+    def __init__(self, target: Any) -> None:
+        self._t = target
+
+    def __getattr__(self, name: str) -> Any:
+        v = getattr(self._t, name)
+        if callable(v):
+            async def _call(*a: Any, **k: Any) -> Any:
+                return await asyncio.to_thread(v, *a, **k)
+
+            return _call
+        if v.__class__.__module__.startswith("solari_browserbase") and not hasattr(v, "__dataclass_fields__"):
+            return _AsyncProxy(v)
+        return v
+
+
+class AsyncBrowserbase:
+    """Async twin: every call runs the sync client in a worker thread (no extra dependencies)."""
+
+    @property
+    def api_key(self) -> str:
+        return self._sync.api_key
+
+    def __repr__(self) -> str:
+        return repr(self._sync).replace("Browserbase(", "AsyncBrowserbase(", 1)
+
+    def __init__(self, **kwargs: Any) -> None:
+        self._sync = Browserbase(**kwargs)
+        self.sessions = _AsyncProxy(self._sync.sessions)
+        self.contexts = _AsyncProxy(self._sync.contexts)
+        self.extensions = self._sync.extensions
+        self.projects = self._sync.projects
+        self.agents = self._sync.agents
+        self.fetch_api = self._sync.fetch_api
+        self.search = self._sync.search
+
+    async def close(self) -> None:
+        await asyncio.to_thread(self._sync.close)

solari_browserbase_compat-0.1.0/solari_browserbase/errors.py

@@ -0,0 +1,27 @@
+from __future__ import annotations
+
+from typing import Any, Optional
+
+
+class BrowserbaseError(Exception):
+    """Base class for everything this package raises."""
+
+
+class APIError(BrowserbaseError):
+    """The gateway answered with a non-2xx status. ``code`` is Solari's machine-readable error code when present."""
+
+    def __init__(self, status: int, message: str, code: Optional[str] = None, body: Any = None) -> None:
+        super().__init__(message)
+        self.status = status
+        self.status_code = status
+        self.code = code
+        self.body = body
+
+
+class SolariCompatUnsupported(BrowserbaseError):
+    """A Browserbase feature Solari Browser does not offer (see COMPAT.md)."""
+
+    def __init__(self, feature: str, hint: Optional[str] = None) -> None:
+        super().__init__(f"Not supported by Solari Browser: {feature}" + (f" — {hint}" if hint else ""))
+        self.feature = feature
+        self.hint = hint

solari_browserbase_compat-0.1.0/solari_browserbase/mapping.py

@@ -0,0 +1,128 @@
+"""Browserbase ``sessions.create`` params -> Solari ``POST /sessions`` body. Pure functions, no I/O."""
+from __future__ import annotations
+
+from dataclasses import dataclass, field
+from typing import Any, Dict, List, Optional
+
+from .errors import SolariCompatUnsupported
+
+_REGIONS = {"us-west-2", "us-west"}
+
+
+@dataclass
+class MappedCreate:
+    body: Dict[str, Any]
+    persist_profile_id: Optional[str] = None
+    warnings: List[str] = field(default_factory=list)
+
+
+def _proxy_body(proxies: Any, ca_certs: Any) -> Any:
+    if ca_certs:
+        raise SolariCompatUnsupported("proxy_settings.caCertificates", "custom CA certificates are not supported")
+    if proxies is None or proxies is False:
+        return None
+    if proxies is True:
+        return {"country": "us"}
+    if not isinstance(proxies, (list, tuple)) or len(proxies) == 0:
+        return None
+    if len(proxies) > 1:
+        raise SolariCompatUnsupported(
+            "multiple proxies / domain routing rules",
+            "pass at most one managed proxy; per-domain routing is not supported",
+        )
+    p = proxies[0]
+    if p.get("domainPattern"):
+        raise SolariCompatUnsupported("proxies[].domainPattern", "per-domain proxy routing is not supported")
+    t = p.get("type")
+    if t == "external":
+        raise SolariCompatUnsupported(
+            "external proxy", "bring-your-own proxy servers are not supported; use a managed proxy"
+        )
+    if t == "none":
+        return None  # no proxy, same as not asking for one
+    if t != "browserbase":
+        raise SolariCompatUnsupported(f"proxy type {t!r}")
+    g = p.get("geolocation")
+    if not g:
+        return {"country": "us"}
+    out: Dict[str, Any] = {"country": str(g["country"]).lower()}
+    if g.get("state"):
+        out["state"] = str(g["state"]).lower()
+    if g.get("city"):
+        out["city"] = g["city"]
+    return out
+
+
+def map_create_params(
+    *,
+    extension_id: Optional[str] = None,
+    browser_settings: Optional[Dict[str, Any]] = None,
+    timeout: Optional[int] = None,
+    keep_alive: Optional[bool] = None,
+    proxies: Any = None,
+    proxy_settings: Optional[Dict[str, Any]] = None,
+    region: Optional[str] = None,
+    user_metadata: Optional[Dict[str, Any]] = None,
+    strict: bool = False,
+) -> MappedCreate:
+    bs = browser_settings or {}
+    warnings: List[str] = []
+
+    def soft(feature: str, why: str) -> None:
+        if strict:
+            raise SolariCompatUnsupported(feature, why)
+        warnings.append(f"{feature}: {why}")
+
+    # hard gaps
+    if extension_id or bs.get("extensionId"):
+        raise SolariCompatUnsupported("extensions", "browser extensions cannot be loaded")
+    if bs.get("ignoreCertificateErrors") is True:
+        raise SolariCompatUnsupported("browserSettings.ignoreCertificateErrors")
+    if bs.get("captchaImageSelector") or bs.get("captchaInputSelector"):
+        raise SolariCompatUnsupported("custom CAPTCHA selectors")
+    if bs.get("os") in ("mobile", "tablet"):
+        raise SolariCompatUnsupported(f"browserSettings.os={bs['os']}", "only desktop browsers")
+    if region is not None and region not in _REGIONS:
+        raise SolariCompatUnsupported(f"region {region}", "Solari Browser runs in one region (us-west)")
+
+    # soft gaps
+    if timeout is not None:
+        soft("timeout", "sessions end at your plan's maximum session length, not at this value; call sessions.update to release earlier")
+    if keep_alive is True:
+        soft("keep_alive", "a disconnected session is released about 45 s after the socket closes; reconnect inside that window or hold the connection")
+    if user_metadata is not None:
+        soft("user_metadata", "metadata is not stored or queryable")
+    if bs.get("viewport") is not None:
+        soft("browserSettings.viewport", "set the viewport from your automation client (page.set_viewport_size)")
+    if bs.get("blockAds") is True:
+        soft("browserSettings.blockAds", "ad blocking is not available")
+    if bs.get("logSession") is True:
+        soft("browserSettings.logSession", "session command logs are not available")
+    if bs.get("os") in ("windows", "mac", "linux"):
+        soft("browserSettings.os", "the operating system profile cannot be chosen")
+
+    proxy = _proxy_body(proxies, (proxy_settings or {}).get("caCertificates"))
+    allowed = bs.get("allowedDomains") or None
+    captcha = bs.get("solveCaptchas") is True
+    stealth = bool(bs.get("verified") is True or bs.get("advancedStealth") is True or captcha or proxy is not None or allowed)
+
+    body: Dict[str, Any] = {}
+    if stealth:
+        body["stealth"] = True
+    if captcha:
+        body["captcha"] = True
+    if bs.get("recordSession") is True:
+        body["recording"] = True
+    if proxy is not None:
+        body["proxy"] = proxy
+    if allowed:
+        body["allowedDomains"] = list(allowed)
+    ctx = bs.get("context") or {}
+    if ctx.get("id"):
+        body["profileId"] = ctx["id"]
+    persist = ctx["id"] if ctx.get("id") and ctx.get("persist") is True else None
+    return MappedCreate(body=body, persist_profile_id=persist, warnings=warnings)
+
+
+def map_status(s: Optional[str]) -> str:
+    return {"active": "RUNNING", "released": "COMPLETED", "expired": "TIMED_OUT"}.get(s or "", "ERROR")

solari_browserbase_compat-0.1.0/tests/live_staging.py

@@ -0,0 +1,52 @@
+"""Live check against a real gateway (NOT collected by pytest). Creates its own sessions and releases them.
+   SOLARI_API_KEY=slr_... SOLARI_BASE_URL=https://api-sta.getsolari.com python tests/live_staging.py
+"""
+import time
+
+from solari_browserbase import APIError, Browserbase, SolariCompatUnsupported
+
+bb = Browserbase()
+made = []
+try:
+    s = bb.sessions.create(browser_settings={"recordSession": True})
+    made.append(s.id)
+    print("create:", s.status, s.connect_url.split(":")[0])
+    assert s.status == "RUNNING" and s.connect_url.startswith("wss://")
+    assert bb.sessions.retrieve(s.id).status == "RUNNING"
+    assert any(x.id == s.id for x in bb.sessions.list(status="RUNNING"))
+    d = bb.sessions.debug(s.id, expires_in=300)
+    print("live view:", d.debugger_url.split("#")[0] + "#<redacted>")
+    assert d.debugger_url.startswith("https://")
+    assert bb.sessions.update(s.id, status="REQUEST_RELEASE").status == "COMPLETED"
+    made.remove(s.id)
+
+    # managed proxy + stealth mapping is accepted by the gateway
+    p = bb.sessions.create(proxies=[{"type": "browserbase", "geolocation": {"country": "US"}}])
+    made.append(p.id)
+    print("proxy session:", p.status)
+    assert p.status == "RUNNING"
+    bb.sessions.update(p.id, status="REQUEST_RELEASE")
+    made.remove(p.id)
+
+    c = bb.contexts.create(name=f"bbcompat-py-{int(time.time())}")
+    print("context:", bool(c.id), bb.contexts.retrieve(c.id).id == c.id)
+    cs = bb.sessions.create(browser_settings={"context": {"id": c.id, "persist": True}})
+    made.append(cs.id)
+    print("context session storage_state:", cs.storage_state)
+    bb.sessions.update(cs.id, status="REQUEST_RELEASE")
+    made.remove(cs.id)
+    bb.contexts.delete(c.id)
+
+    for fn in (lambda: bb.sessions.create(extension_id="e"), lambda: bb.extensions.create()):
+        try:
+            fn()
+            raise SystemExit("expected SolariCompatUnsupported")
+        except SolariCompatUnsupported:
+            pass
+    print("OK")
+finally:
+    for sid in made:
+        try:
+            bb.sessions.update(sid, status="REQUEST_RELEASE")
+        except APIError:
+            pass

solari_browserbase_compat-0.1.0/tests/test_compat.py

@@ -0,0 +1,273 @@
+import asyncio
+import gzip
+import json
+import os
+
+import httpx
+import pytest
+
+import solari_browserbase as sb
+from solari_browserbase import APIError, AsyncBrowserbase, Browserbase, SolariCompatUnsupported, map_create_params
+
+KEY = "slr_live_test_key"
+SESSION = {"sessionId": "sess.abc", "wsEndpoint": "wss://gw/ws/sess.abc", "cdpEndpoint": "wss://gw/cdp/sess.abc", "expiresAt": "2027-01-01T00:00:00.000Z"}
+
+
+class Gateway:
+    """Scripted fake gateway behind httpx.MockTransport; records every request."""
+
+    def __init__(self, routes):
+        self.routes = routes
+        self.calls = []
+
+    def __call__(self, request: httpx.Request) -> httpx.Response:
+        body = json.loads(request.content) if request.content else None
+        self.calls.append({"method": request.method, "path": request.url.path, "body": body, "headers": dict(request.headers)})
+        for method, path, reply in self.routes:
+            if method == request.method and path == request.url.path:
+                out = reply(len(self.calls)) if callable(reply) else reply
+                status, payload = out
+                if status == 204:
+                    return httpx.Response(204)
+                return httpx.Response(status, json=payload)
+        return httpx.Response(500, json={"error": f"no route {request.method} {request.url.path}"})
+
+
+def client(routes, **kw):
+    gw = Gateway(routes)
+    warnings = []
+    bb = Browserbase(api_key=KEY, base_url="https://gw.example", transport=httpx.MockTransport(gw), on_warning=warnings.append, **kw)
+    return bb, gw, warnings
+
+
+CREATE = ("POST", "/sessions", (201, SESSION))
+
+
+def test_api_key_only_slr_keys_and_never_echoed(monkeypatch):
+    warnings = []
+    monkeypatch.setenv("SOLARI_API_KEY", "")
+    monkeypatch.setenv("BROWSERBASE_API_KEY", "bb_live_SECRETSECRET")
+    with pytest.raises(sb.BrowserbaseError):
+        Browserbase(on_warning=warnings.append)
+    assert len(warnings) == 1 and "SECRETSECRET" not in warnings[0]
+    monkeypatch.setenv("SOLARI_API_KEY", "slr_from_env")
+    assert Browserbase(api_key="bb_wrong", on_warning=lambda m: None).api_key == "slr_from_env"
+    assert Browserbase(api_key=KEY, on_warning=lambda m: None).api_key == KEY
+
+
+def test_create_plain_returns_connect_url_is_cdp_endpoint():
+    bb, gw, _ = client([CREATE])
+    s = bb.sessions.create()
+    assert gw.calls[0]["path"] == "/sessions" and gw.calls[0]["body"] is None
+    assert gw.calls[0]["headers"]["idempotency-key"]
+    assert gw.calls[0]["headers"]["authorization"] == f"Bearer {KEY}"
+    assert s.id == "sess.abc" and s.status == "RUNNING"
+    assert s.connect_url == "wss://gw/cdp/sess.abc"  # CDP endpoint, never the patchright wire endpoint
+    assert s.selenium_remote_url == "" and s.keep_alive is False
+    assert s.expires_at == SESSION["expiresAt"]
+
+
+def test_context_session_returns_saved_storage_state(monkeypatch):
+    state = {"cookies": [{"name": "k", "value": "v"}], "origins": []}
+    created = {**SESSION, "storageStateUrl": {"url": "https://store.example/state.json", "expiresInSeconds": 60}}
+    bb, gw, warnings = client([("POST", "/sessions", (201, created))])
+    bb._http.client = httpx.Client(transport=httpx.MockTransport(lambda r: httpx.Response(200, json=state) if r.url.host == "store.example" else gw(r)))
+    s = bb.sessions.create(browser_settings={"context": {"id": "prof_1"}})
+    assert s.storage_state == state and s.context_id == "prof_1"
+    assert gw.calls[0]["body"] == {"profileId": "prof_1"}
+    plain, _, _ = client([CREATE])
+    assert plain.sessions.create().storage_state is None
+    bad, bgw, bwarn = client([("POST", "/sessions", (201, created))])
+    bad._http.client = httpx.Client(transport=httpx.MockTransport(lambda r: httpx.Response(500) if r.url.host == "store.example" else bgw(r)))
+    assert bad.sessions.create(browser_settings={"context": {"id": "p"}}).storage_state is None and bwarn
+
+
+def test_mapping_soft_and_default_behaviour():
+    m = lambda **k: map_create_params(**k).body  # noqa: E731
+    assert m(proxies=True) == {"stealth": True, "proxy": {"country": "us"}}
+    assert m(proxies=[{"type": "browserbase", "geolocation": {"country": "GB", "city": "London"}}]) == {"stealth": True, "proxy": {"country": "gb", "city": "London"}}
+    assert m(proxies=[{"type": "browserbase", "geolocation": {"country": "US", "state": "NY"}}])["proxy"] == {"country": "us", "state": "ny"}
+    assert m(proxies=[{"type": "none"}]) == {}
+    assert m(browser_settings={"verified": True}) == {"stealth": True}
+    assert m(browser_settings={"advancedStealth": True}) == {"stealth": True}
+    assert m(browser_settings={"solveCaptchas": True}) == {"stealth": True, "captcha": True}
+    assert m(browser_settings={"solveCaptchas": False}) == {}, "captcha is opt-in"
+    assert m(browser_settings={"recordSession": True}) == {"recording": True}
+    assert m(browser_settings={"recordSession": False}) == {}
+    assert m(browser_settings={"allowedDomains": ["a.com"]}) == {"stealth": True, "allowedDomains": ["a.com"]}
+    c = map_create_params(browser_settings={"context": {"id": "prof_1", "persist": True}})
+    assert c.body == {"profileId": "prof_1"} and c.persist_profile_id == "prof_1"
+    assert map_create_params(browser_settings={"context": {"id": "prof_1"}}).persist_profile_id is None
+
+
+@pytest.mark.parametrize("kw", [
+    {"extension_id": "e1"},
+    {"browser_settings": {"extensionId": "e1"}},
+    {"proxies": [{"type": "external", "server": "http://p:1"}]},
+    {"proxies": [{"type": "browserbase", "domainPattern": "*.x.com"}]},
+    {"proxies": [{"type": "browserbase"}, {"type": "none"}]},
+    {"proxy_settings": {"caCertificates": ["id"]}},
+    {"browser_settings": {"ignoreCertificateErrors": True}},
+    {"browser_settings": {"captchaImageSelector": "#a"}},
+    {"browser_settings": {"captchaInputSelector": "#b"}},
+    {"browser_settings": {"os": "mobile"}},
+    {"browser_settings": {"os": "tablet"}},
+    {"region": "eu-central-1"},
+])
+def test_hard_gaps_raise(kw):
+    with pytest.raises(SolariCompatUnsupported):
+        map_create_params(**kw)
+
+
+def test_one_region_accepted_even_strict():
+    map_create_params(region="us-west-2", strict=True)
+
+
+@pytest.mark.parametrize("kw", [
+    {"timeout": 600}, {"keep_alive": True}, {"user_metadata": {"a": 1}},
+    {"browser_settings": {"viewport": {"width": 1, "height": 1}}},
+    {"browser_settings": {"blockAds": True}}, {"browser_settings": {"os": "windows"}},
+])
+def test_soft_gaps_warn_and_strict_raises(kw):
+    assert len(map_create_params(**kw).warnings) == 1
+    with pytest.raises(SolariCompatUnsupported):
+        map_create_params(strict=True, **kw)
+
+
+def test_warnings_emitted_and_strict_sends_nothing():
+    bb, gw, warnings = client([CREATE])
+    bb.sessions.create(timeout=300, keep_alive=True)
+    assert len(warnings) == 2
+    sbb, sgw, _ = client([CREATE], )
+    sbb._strict = True
+    with pytest.raises(SolariCompatUnsupported):
+        sbb.sessions.create(timeout=300)
+    assert sgw.calls == []
+
+
+def test_retrieve_and_list_map_states():
+    rows = [
+        {"id": "a", "status": "active", "createdAt": "2026-01-01T00:00:00Z", "expiresAt": "2027-01-01T00:00:00Z"},
+        {"id": "b", "status": "released"}, {"id": "c", "status": "expired"}, {"id": "d", "status": "unknown"},
+    ]
+    bb, _, _ = client([
+        ("GET", "/sessions", (200, {"sessions": rows})),
+        ("GET", "/sessions/a", (200, {**rows[0], "cdpEndpoint": "wss://gw/cdp/a"})),
+    ])
+    assert [s.status for s in bb.sessions.list()] == ["RUNNING", "COMPLETED", "TIMED_OUT", "ERROR"]
+    assert [s.id for s in bb.sessions.list(status="COMPLETED")] == ["b"]
+    with pytest.raises(SolariCompatUnsupported):
+        bb.sessions.list(q="user_metadata['k']:'v'")
+    one = bb.sessions.retrieve("a")
+    assert one.status == "RUNNING" and one.connect_url == "wss://gw/cdp/a"
+
+
+def test_update_release_saves_profile_first_only_when_persist():
+    bb, gw, _ = client([CREATE, ("POST", "/sessions/sess.abc/save-profile", (200, {"ok": True})), ("DELETE", "/sessions/sess.abc", (204, None))])
+    bb.sessions.create(browser_settings={"context": {"id": "prof_9", "persist": True}})
+    out = bb.sessions.update("sess.abc", status="REQUEST_RELEASE")
+    assert out.status == "COMPLETED"
+    assert [f"{c['method']} {c['path']}" for c in gw.calls] == ["POST /sessions", "POST /sessions/sess.abc/save-profile", "DELETE /sessions/sess.abc"]
+    assert gw.calls[1]["body"] == {"profileId": "prof_9"}
+
+    bb2, gw2, _ = client([CREATE, ("DELETE", "/sessions/sess.abc", (204, None))])
+    bb2.sessions.create(browser_settings={"context": {"id": "prof_9"}})
+    bb2.sessions.update("sess.abc", status="REQUEST_RELEASE")
+    assert [c["method"] for c in gw2.calls] == ["POST", "DELETE"]
+    with pytest.raises(SolariCompatUnsupported):
+        bb2.sessions.update("x", status="NOPE")
+
+
+def test_debug_returns_share_link():
+    bb, gw, _ = client([
+        ("POST", "/sessions/s1/shares", (201, {"shareId": "vs_1", "url": "https://view.example/v#x"})),
+        ("GET", "/sessions/s1", (200, {"id": "s1", "status": "active", "cdpEndpoint": "wss://gw/cdp/s1"})),
+    ])
+    d = bb.sessions.debug("s1", expires_in=600)
+    assert d.debugger_url == d.debugger_fullscreen_url == "https://view.example/v#x"
+    assert d.ws_url == "wss://gw/cdp/s1" and d.pages == []
+    assert gw.calls[0]["body"] == {"ttlSeconds": 600}
+
+
+def test_recording_retrieve_parses_events(monkeypatch):
+    events = [{"type": 4, "data": {"href": "x"}}, {"type": 2, "data": {}}]
+    nd = ("\n".join(json.dumps(e) for e in events) + "\n").encode()
+    for payload in (gzip.compress(nd), nd):
+        monkeypatch.setattr(httpx, "get", lambda url, timeout=0, _p=payload: httpx.Response(200, content=_p, request=httpx.Request("GET", url)))
+        bb, _, _ = client([("GET", "/sessions/s1/replay-url", (200, {"url": "https://store.example/r", "expiresInSeconds": 60}))])
+        assert bb.sessions.recording.retrieve("s1") == events
+    bb, _, _ = client([("GET", "/sessions/s1/replay-url", (404, {"error": "Replay upload is still in flight", "code": "ReplayPending"}))])
+    with pytest.raises(APIError) as e:
+        bb.sessions.recording.retrieve("s1")
+    assert e.value.code == "ReplayPending" and e.value.status == 404
+
+
+def test_contexts_are_profiles():
+    bb, gw, _ = client([
+        ("POST", "/profiles", (201, {"id": "prof_1", "name": "n"})),
+        ("GET", "/profiles", (200, [{"id": "prof_1", "name": "n", "createdAt": "t"}])),
+        ("DELETE", "/profiles/prof_1", (204, None)),
+    ])
+    c = bb.contexts.create(name="n")
+    assert c.id == "prof_1" and c.public_key == "" and gw.calls[0]["body"] == {"name": "n"}
+    assert bb.contexts.retrieve("prof_1").name == "n"
+    with pytest.raises(APIError) as e:
+        bb.contexts.retrieve("nope")
+    assert e.value.status == 404
+    bb.contexts.delete("prof_1")
+    with pytest.raises(SolariCompatUnsupported):
+        bb.contexts.update()
+
+
+def test_unsupported_resources_raise():
+    bb, _, _ = client([])
+    for fn in (lambda: bb.extensions.create(), lambda: bb.projects.list(), lambda: bb.projects.usage("x"),
+               lambda: bb.agents.create(), lambda: bb.fetch_api.create(), lambda: bb.search.web(),
+               lambda: bb.sessions.replays.retrieve("s"), lambda: bb.sessions.logs.list("s"),
+               lambda: bb.sessions.downloads.list("s"), lambda: bb.sessions.uploads.create("s")):
+        with pytest.raises(SolariCompatUnsupported):
+            fn()
+
+
+def test_errors_and_idempotent_create_retry(monkeypatch):
+    monkeypatch.setattr("time.sleep", lambda s: None)
+    bb, gw, _ = client([("POST", "/sessions", lambda n: (503, {"error": "busy"}) if n < 2 else (201, SESSION))])
+    assert bb.sessions.create().id == "sess.abc"
+    assert len(gw.calls) == 2 and gw.calls[0]["headers"]["idempotency-key"] == gw.calls[1]["headers"]["idempotency-key"]
+    f, _, _ = client([("POST", "/sessions", (403, {"error": "Egress allowlisting requires an enterprise plan", "code": "FeatureRequiresPlan"}))])
+    with pytest.raises(APIError) as e:
+        f.sessions.create(browser_settings={"allowedDomains": ["a.com"]})
+    assert e.value.status == 403 and e.value.code == "FeatureRequiresPlan"
+
+
+def test_async_client_runs_calls():
+    gw = Gateway([CREATE, ("DELETE", "/sessions/sess.abc", (204, None))])
+
+    async def main():
+        bb = AsyncBrowserbase(api_key=KEY, base_url="https://gw.example", transport=httpx.MockTransport(gw), on_warning=lambda m: None)
+        s = await bb.sessions.create()
+        assert s.connect_url == "wss://gw/cdp/sess.abc"
+        done = await bb.sessions.update(s.id, status="REQUEST_RELEASE")
+        assert done.status == "COMPLETED"
+        with pytest.raises(SolariCompatUnsupported):
+            bb.extensions.create()
+        await bb.close()
+
+    asyncio.run(main())
+
+
+def test_client_never_prints_its_key():
+    bb, _, _ = client([])
+    assert KEY not in repr(bb) and KEY not in str(vars(bb.sessions)) and KEY not in repr(AsyncBrowserbase(api_key=KEY, on_warning=lambda m: None))
+
+
+def test_user_facing_refusal_messages_are_pinned():
+    def msg(**kw):
+        try:
+            map_create_params(**kw)
+        except SolariCompatUnsupported as e:
+            return str(e)
+    assert msg(extension_id="e") == "Not supported by Solari Browser: extensions — browser extensions cannot be loaded"
+    assert msg(proxies=[{"type": "external", "server": "s"}]) == "Not supported by Solari Browser: external proxy — bring-your-own proxy servers are not supported; use a managed proxy"
+    assert msg(region="eu-central-1") == "Not supported by Solari Browser: region eu-central-1 — Solari Browser runs in one region (us-west)"
+    assert msg(browser_settings={"os": "mobile"}) == "Not supported by Solari Browser: browserSettings.os=mobile — only desktop browsers"