scalebrowser 0.2.0__py3-none-any.whl

scalebrowser/__init__.py

@@ -0,0 +1,234 @@
+"""Scalebrowser — official Python SDK.
+
+Typed REST client + a direct-CDP driver (nodriver-style, **not** Playwright) for
+the self-hosted Scalebrowser daemon.
+
+    from scalebrowser import ScalebrowserClient            # synchronous
+    from scalebrowser import AsyncScalebrowserClient       # asyncio
+
+    sb = ScalebrowserClient(base_url="http://127.0.0.1:8787", token="…")
+    with sb.launch(profile_id, headless=True) as page:     # start → CDP → stop
+        page.navigate("https://example.com")
+        page.humanize_click(120, 240)
+"""
+
+from __future__ import annotations
+
+from ._sync import ScalebrowserClient, SyncCdpSession
+from ._version import __version__
+from .cdp import CdpSession, connect_cdp
+from .client import (
+    DEFAULT_BASE_URL,
+    DEFAULT_CAPACITY_MAX_CONCURRENT,
+    DEFAULT_CAPACITY_RAM_BUDGET_MB,
+    AsyncScalebrowserClient,
+)
+from .errors import ApiError, CdpError, ErrorCode, NetworkError, ScalebrowserError
+from .events import parse_sse_frame
+from .models_control import (
+    Account,
+    ArtifactBytes,
+    ArtifactPutResult,
+    EffectiveInterruptionLock,
+    HealthStatus,
+    InterruptionAuthor,
+    InterruptionChoice,
+    InterruptionLock,
+    InterruptionLockRow,
+    InterruptionLockView,
+    InterruptionRuleRow,
+    ReadyStatus,
+    SetInterruptionLockBody,
+    SetInterruptionRuleBody,
+)
+from .models_identity import (
+    BindInboxBody,
+    Inbox,
+    InboxBinding,
+    InboxBindings,
+    InboxChannel,
+    PasskeyRetiredReason,
+    PasskeyRow,
+    PutInboxBody,
+    RevealCookiesBody,
+    RevealCookiesResult,
+    RevealedCookie,
+)
+from .models_runs import ActivitySnapshot, AgentRun, GoalSource, OutcomeSource
+from .models import (
+    AudioProps,
+    Brand,
+    BulkAssignProxyBody,
+    BulkCreateBody,
+    BulkIdsBody,
+    CheckProxyConfigBody,
+    ClientHints,
+    CreateGroupBody,
+    CreateProfileBody,
+    CreateProxyBody,
+    Event,
+    AuditReport,
+    AuditStatus,
+    Extension,
+    ExtensionPolicy,
+    CredentialBundle,
+    CredentialImportResult,
+    CredentialMeta,
+    ExtensionsResult,
+    RevealedCredential,
+    VaultStatus,
+    GeoMode,
+    GpuPersona,
+    Group,
+    HostMode,
+    Locale,
+    MediaDevice,
+    Metrics,
+    MetricsAvailability,
+    OsFamily,
+    PermissionDefaults,
+    ProfileResource,
+    Persona,
+    PersonaMisc,
+    PersonaConstraintOptions,
+    Preset,
+    PresetConfig,
+    PresetConstraints,
+    CreatePresetBody,
+    UpdatePresetBody,
+    Profile,
+    Proxy,
+    ProxyCheckResult,
+    ProxyKind,
+    Rotation,
+    RuntimeState,
+    Screen,
+    SessionExportBody,
+    SessionExportResult,
+    SessionImportBody,
+    SessionKind,
+    SpeechVoice,
+    StartProfileBody,
+    StartProfileResult,
+    StopProfileResult,
+    UpdateProfileBody,
+    UpdateProxyBody,
+    WebGl,
+    WebGpu,
+)
+
+__all__ = [
+    "__version__",
+    # runs + activity
+    "AgentRun",
+    "ActivitySnapshot",
+    "GoalSource",
+    "OutcomeSource",
+    # mailboxes, passkeys, cookies
+    "Inbox",
+    "InboxBinding",
+    "InboxBindings",
+    "InboxChannel",
+    "PutInboxBody",
+    "BindInboxBody",
+    "PasskeyRow",
+    "PasskeyRetiredReason",
+    "RevealedCookie",
+    "RevealCookiesBody",
+    "RevealCookiesResult",
+    # interruptions, artifacts, account, health
+    "InterruptionLock",
+    "InterruptionChoice",
+    "InterruptionAuthor",
+    "InterruptionLockRow",
+    "InterruptionLockView",
+    "InterruptionRuleRow",
+    "EffectiveInterruptionLock",
+    "SetInterruptionLockBody",
+    "SetInterruptionRuleBody",
+    "ArtifactBytes",
+    "ArtifactPutResult",
+    "Account",
+    "HealthStatus",
+    "ReadyStatus",
+    # clients
+    "ScalebrowserClient",
+    "AsyncScalebrowserClient",
+    "SyncCdpSession",
+    "CdpSession",
+    "connect_cdp",
+    "DEFAULT_BASE_URL",
+    "DEFAULT_CAPACITY_MAX_CONCURRENT",
+    "DEFAULT_CAPACITY_RAM_BUDGET_MB",
+    # errors
+    "ScalebrowserError",
+    "ApiError",
+    "NetworkError",
+    "CdpError",
+    "ErrorCode",
+    # events
+    "Event",
+    "parse_sse_frame",
+    # enums
+    "RuntimeState",
+    "HostMode",
+    "GeoMode",
+    "ProxyKind",
+    "Rotation",
+    "SessionKind",
+    "OsFamily",
+    # persona
+    "Persona",
+    "Screen",
+    "Locale",
+    "WebGl",
+    "WebGpu",
+    "AudioProps",
+    "SpeechVoice",
+    "GpuPersona",
+    "Brand",
+    "ClientHints",
+    "PermissionDefaults",
+    "MediaDevice",
+    "PersonaMisc",
+    # resources
+    "Profile",
+    "Group",
+    "PersonaConstraintOptions",
+    "Preset",
+    "PresetConfig",
+    "PresetConstraints",
+    "CreatePresetBody",
+    "UpdatePresetBody",
+    "Proxy",
+    # payloads
+    "CreateProfileBody",
+    "UpdateProfileBody",
+    "StartProfileBody",
+    "StartProfileResult",
+    "StopProfileResult",
+    "BulkCreateBody",
+    "BulkIdsBody",
+    "BulkAssignProxyBody",
+    "CreateProxyBody",
+    "UpdateProxyBody",
+    "ProxyCheckResult",
+    "CheckProxyConfigBody",
+    "AuditReport",
+    "AuditStatus",
+    "Extension",
+    "ExtensionPolicy",
+    "CredentialBundle",
+    "CredentialImportResult",
+    "CredentialMeta",
+    "ExtensionsResult",
+    "RevealedCredential",
+    "VaultStatus",
+    "CreateGroupBody",
+    "SessionExportBody",
+    "SessionExportResult",
+    "SessionImportBody",
+    "Metrics",
+    "MetricsAvailability",
+    "ProfileResource",
+]

scalebrowser/_http.py

@@ -0,0 +1,180 @@
+"""The low-level async HTTP transport. Every REST call goes through here, so
+Bearer auth, query-string building, JSON (de)serialisation and error mapping
+(``{ code, message }`` → :class:`ApiError`) live in exactly one place.
+"""
+
+from __future__ import annotations
+
+import re
+from typing import Any, AsyncIterator, Mapping, Optional
+
+import httpx
+
+from .errors import ApiError, NetworkError
+
+JsonValue = Any
+"""A decoded JSON document (dict / list / scalar / None)."""
+
+
+def _clean_params(params: Optional[Mapping[str, Any]]) -> Optional[dict[str, Any]]:
+    if not params:
+        return None
+    return {k: v for k, v in params.items() if v is not None and v != ""}
+
+
+def _filename_of(disposition: Optional[str]) -> Optional[str]:
+    """``attachment; filename="shot.jpg"`` → ``shot.jpg``."""
+    if not disposition:
+        return None
+    match = re.search(r'filename="([^"]*)"', disposition) or re.search(
+        r"filename=([^;]+)", disposition
+    )
+    name = match.group(1).strip() if match else ""
+    return name or None
+
+
+def _safe_json(response: httpx.Response) -> Optional[dict[str, Any]]:
+    try:
+        data = response.json()
+    except ValueError:
+        return None
+    return data if isinstance(data, dict) else {"message": str(data)}
+
+
+class AsyncTransport:
+    """Wraps an :class:`httpx.AsyncClient` with the daemon's auth + error contract."""
+
+    def __init__(
+        self,
+        base_url: str,
+        token: Optional[str] = None,
+        *,
+        timeout: float = 30.0,
+        transport: Optional[httpx.AsyncBaseTransport] = None,
+        http_client: Optional[httpx.AsyncClient] = None,
+        headers: Optional[Mapping[str, str]] = None,
+    ) -> None:
+        self.base_url = base_url.rstrip("/")
+        self._token = token
+        if http_client is not None:
+            self._client = http_client
+            self._owns_client = False
+        else:
+            self._client = httpx.AsyncClient(
+                base_url=self.base_url,
+                timeout=timeout,
+                transport=transport,
+                headers=dict(headers) if headers else None,
+            )
+            self._owns_client = True
+
+    @property
+    def token(self) -> Optional[str]:
+        return self._token
+
+    def _auth_headers(self, extra: Optional[Mapping[str, str]] = None) -> dict[str, str]:
+        headers: dict[str, str] = dict(extra) if extra else {}
+        if self._token:
+            headers["Authorization"] = f"Bearer {self._token}"
+        return headers
+
+    # ── core request ─────────────────────────────────────────────────────────
+
+    async def request(
+        self,
+        method: str,
+        path: str,
+        *,
+        json: JsonValue = None,
+        content: Optional[bytes] = None,
+        params: Optional[Mapping[str, Any]] = None,
+    ) -> JsonValue:
+        headers = self._auth_headers()
+        if content is not None:
+            # A ``.crx`` upload is the file itself, not JSON around it.
+            headers["Content-Type"] = "application/octet-stream"
+        try:
+            response = await self._client.request(
+                method,
+                path,
+                json=json if json is not None else None,
+                content=content,
+                params=_clean_params(params),
+                headers=headers,
+            )
+        except httpx.HTTPError as exc:
+            raise NetworkError("Could not reach the Scalebrowser daemon. Is it running?", exc) from exc
+        return self._handle(response)
+
+    def _handle(self, response: httpx.Response) -> JsonValue:
+        if response.status_code >= 400:
+            body = _safe_json(response)
+            code = body.get("code") if body else None
+            message = body.get("message") if body else None
+            raise ApiError(response.status_code, code, message, body)
+        if response.status_code == 204 or not response.content:
+            return None
+        return response.json()
+
+    async def get(self, path: str, *, params: Optional[Mapping[str, Any]] = None) -> JsonValue:
+        return await self.request("GET", path, params=params)
+
+    async def post(self, path: str, body: JsonValue = None) -> JsonValue:
+        return await self.request("POST", path, json=body if body is not None else {})
+
+    async def patch(self, path: str, body: JsonValue = None) -> JsonValue:
+        return await self.request("PATCH", path, json=body if body is not None else {})
+
+    async def put(self, path: str, body: JsonValue = None) -> JsonValue:
+        return await self.request("PUT", path, json=body if body is not None else {})
+
+    async def get_bytes(self, path: str) -> tuple[bytes, Optional[str], Optional[str]]:
+        """Fetch a route that answers with bytes: ``(body, content_type, filename)``.
+
+        Separate from :meth:`get` rather than a flag on it, because the error
+        path differs: a failed byte fetch still answers JSON, so the mapping to
+        :class:`ApiError` has to happen before the body is read as binary.
+        """
+        try:
+            response = await self._client.request("GET", path, headers=self._auth_headers())
+        except httpx.HTTPError as exc:
+            raise NetworkError(
+                "Could not reach the Scalebrowser daemon. Is it running?", exc
+            ) from exc
+        if response.status_code >= 400:
+            body = _safe_json(response)
+            code = body.get("code") if body else None
+            message = body.get("message") if body else None
+            raise ApiError(response.status_code, code, message, body)
+        return (
+            response.content,
+            response.headers.get("content-type"),
+            _filename_of(response.headers.get("content-disposition")),
+        )
+
+    async def delete(self, path: str, body: JsonValue = None) -> JsonValue:
+        # A body stays opt-in: most DELETEs carry none, but the extensions
+        # endpoint identifies the ref to detach in one (`{ext_ref}`).
+        return await self.request("DELETE", path, json=body)
+
+    # ── server-sent events ───────────────────────────────────────────────────
+
+    async def stream_sse(self, path: str) -> AsyncIterator[str]:
+        """Yield raw lines of a ``text/event-stream`` body (Bearer attached)."""
+        headers = self._auth_headers({"Accept": "text/event-stream"})
+        try:
+            async with self._client.stream("GET", path, headers=headers) as response:
+                if response.status_code >= 400:
+                    await response.aread()
+                    body = _safe_json(response)
+                    code = body.get("code") if body else None
+                    message = body.get("message") if body else None
+                    raise ApiError(response.status_code, code, message, body)
+                async for line in response.aiter_lines():
+                    yield line
+        except httpx.HTTPError as exc:
+            raise NetworkError("Event stream connection failed.", exc) from exc
+
+    async def aclose(self) -> None:
+        if self._owns_client:
+            await self._client.aclose()