sprntrl 0.1.0__py3-none-any.whl

sprntrl/__init__.py

@@ -0,0 +1,37 @@
+"""Sprntrl Python SDK — stealth browser-as-a-service client."""
+
+from ._client import Sprntrl, AsyncSprntrl
+from ._errors import (
+    SprntrlError,
+    APIError,
+    BadRequestError,
+    AuthenticationError,
+    PermissionDeniedError,
+    NotFoundError,
+    ConflictError,
+    UnprocessableEntityError,
+    RateLimitError,
+    InternalServerError,
+    APIConnectionError,
+    APIConnectionTimeoutError,
+)
+
+__version__ = "0.1.0"
+
+__all__ = [
+    "Sprntrl",
+    "AsyncSprntrl",
+    "SprntrlError",
+    "APIError",
+    "BadRequestError",
+    "AuthenticationError",
+    "PermissionDeniedError",
+    "NotFoundError",
+    "ConflictError",
+    "UnprocessableEntityError",
+    "RateLimitError",
+    "InternalServerError",
+    "APIConnectionError",
+    "APIConnectionTimeoutError",
+    "__version__",
+]

sprntrl/_base_client.py

@@ -0,0 +1,232 @@
+from __future__ import annotations
+
+import os
+import time
+import asyncio
+import random
+from typing import Any, Mapping, Union
+from urllib.parse import urljoin
+
+import httpx
+
+from ._errors import (
+    APIConnectionError,
+    APIConnectionTimeoutError,
+    error_for_status,
+    SprntrlError,
+)
+
+
+DEFAULT_BASE_URL = "https://api.supernatural.sh"
+DEFAULT_TIMEOUT = 60.0
+DEFAULT_MAX_RETRIES = 2
+_USER_AGENT = "sprntrl-python/0.1.0"
+
+JSONLike = Union[Mapping[str, Any], list, str, int, float, bool, None]
+
+
+class _BaseClient:
+    """Shared config and helpers for sync and async clients."""
+
+    def __init__(
+        self,
+        *,
+        api_key: str | None = None,
+        base_url: str | None = None,
+        timeout: float = DEFAULT_TIMEOUT,
+        max_retries: int = DEFAULT_MAX_RETRIES,
+        default_headers: Mapping[str, str] | None = None,
+    ) -> None:
+        api_key = api_key or os.environ.get("SPRNTRL_API_KEY")
+        if not api_key:
+            raise SprntrlError(
+                "No API key provided. Pass api_key= or set SPRNTRL_API_KEY."
+            )
+        base_url = base_url or os.environ.get("SPRNTRL_BASE_URL") or DEFAULT_BASE_URL
+        self.api_key = api_key
+        self.base_url = base_url.rstrip("/")
+        self.timeout = timeout
+        self.max_retries = max_retries
+        self._default_headers = dict(default_headers or {})
+
+    def _headers(self, extra: Mapping[str, str] | None = None) -> dict[str, str]:
+        h = {
+            "Authorization": f"ApiKey {self.api_key}",
+            "Accept": "application/json",
+            "User-Agent": _USER_AGENT,
+            **self._default_headers,
+        }
+        if extra:
+            h.update(extra)
+        return h
+
+    def _url(self, path: str) -> str:
+        if path.startswith("http://") or path.startswith("https://"):
+            return path
+        if not path.startswith("/"):
+            path = "/" + path
+        return self.base_url + path
+
+    @staticmethod
+    def _should_retry(exc: Exception | None, status: int | None) -> bool:
+        if exc is not None:
+            return True  # connection-level errors
+        if status is None:
+            return False
+        return status == 408 or status == 409 or status == 429 or status >= 500
+
+    @staticmethod
+    def _backoff(attempt: int) -> float:
+        # 0.5s, 1s, 2s + jitter
+        base = 0.5 * (2 ** attempt)
+        return base + random.uniform(0, 0.25)
+
+    @staticmethod
+    def _parse_error(response: httpx.Response) -> tuple[str, Any]:
+        body: Any = None
+        try:
+            body = response.json()
+        except Exception:
+            body = response.text
+        msg = None
+        if isinstance(body, dict):
+            msg = body.get("error") or body.get("message") or body.get("detail")
+        if not msg:
+            msg = f"HTTP {response.status_code}"
+        return msg, body
+
+
+class SyncClient(_BaseClient):
+    def __init__(self, **kwargs: Any) -> None:
+        super().__init__(**kwargs)
+        self._http = httpx.Client(timeout=self.timeout)
+
+    def close(self) -> None:
+        self._http.close()
+
+    def __enter__(self) -> "SyncClient":
+        return self
+
+    def __exit__(self, *exc: Any) -> None:
+        self.close()
+
+    def _request(
+        self,
+        method: str,
+        path: str,
+        *,
+        json: JSONLike = None,
+        params: Mapping[str, Any] | None = None,
+        headers: Mapping[str, str] | None = None,
+        files: Any = None,
+        data: Any = None,
+        stream: bool = False,
+    ) -> Any:
+        url = self._url(path)
+        h = self._headers(headers)
+        last_exc: Exception | None = None
+        for attempt in range(self.max_retries + 1):
+            try:
+                response = self._http.request(
+                    method,
+                    url,
+                    json=json if files is None and data is None else None,
+                    params=params,
+                    headers=h,
+                    files=files,
+                    data=data,
+                )
+            except httpx.TimeoutException as exc:
+                last_exc = APIConnectionTimeoutError(str(exc))
+            except httpx.RequestError as exc:
+                last_exc = APIConnectionError(str(exc), cause=exc)
+            else:
+                status = response.status_code
+                if 200 <= status < 300:
+                    if stream:
+                        return response
+                    if not response.content:
+                        return None
+                    ctype = response.headers.get("content-type", "")
+                    if "application/json" in ctype:
+                        return response.json()
+                    return response.content
+                if self._should_retry(None, status) and attempt < self.max_retries:
+                    time.sleep(self._backoff(attempt))
+                    continue
+                msg, body = self._parse_error(response)
+                raise error_for_status(status, msg, body=body)
+            if attempt < self.max_retries:
+                time.sleep(self._backoff(attempt))
+                continue
+            raise last_exc
+        assert last_exc is not None
+        raise last_exc
+
+
+class AsyncClient(_BaseClient):
+    def __init__(self, **kwargs: Any) -> None:
+        super().__init__(**kwargs)
+        self._http = httpx.AsyncClient(timeout=self.timeout)
+
+    async def close(self) -> None:
+        await self._http.aclose()
+
+    async def __aenter__(self) -> "AsyncClient":
+        return self
+
+    async def __aexit__(self, *exc: Any) -> None:
+        await self.close()
+
+    async def _request(
+        self,
+        method: str,
+        path: str,
+        *,
+        json: JSONLike = None,
+        params: Mapping[str, Any] | None = None,
+        headers: Mapping[str, str] | None = None,
+        files: Any = None,
+        data: Any = None,
+        stream: bool = False,
+    ) -> Any:
+        url = self._url(path)
+        h = self._headers(headers)
+        last_exc: Exception | None = None
+        for attempt in range(self.max_retries + 1):
+            try:
+                response = await self._http.request(
+                    method,
+                    url,
+                    json=json if files is None and data is None else None,
+                    params=params,
+                    headers=h,
+                    files=files,
+                    data=data,
+                )
+            except httpx.TimeoutException as exc:
+                last_exc = APIConnectionTimeoutError(str(exc))
+            except httpx.RequestError as exc:
+                last_exc = APIConnectionError(str(exc), cause=exc)
+            else:
+                status = response.status_code
+                if 200 <= status < 300:
+                    if stream:
+                        return response
+                    if not response.content:
+                        return None
+                    ctype = response.headers.get("content-type", "")
+                    if "application/json" in ctype:
+                        return response.json()
+                    return response.content
+                if self._should_retry(None, status) and attempt < self.max_retries:
+                    await asyncio.sleep(self._backoff(attempt))
+                    continue
+                msg, body = self._parse_error(response)
+                raise error_for_status(status, msg, body=body)
+            if attempt < self.max_retries:
+                await asyncio.sleep(self._backoff(attempt))
+                continue
+            raise last_exc
+        assert last_exc is not None
+        raise last_exc

sprntrl/_client.py

@@ -0,0 +1,59 @@
+from __future__ import annotations
+
+from ._base_client import SyncClient, AsyncClient
+from .resources import (
+    Sessions,
+    AsyncSessions,
+    Profiles,
+    AsyncProfiles,
+    Templates,
+    AsyncTemplates,
+    IPWhitelist,
+    AsyncIPWhitelist,
+    Usage,
+    AsyncUsage,
+    User,
+    AsyncUser,
+    APIKeys,
+    AsyncAPIKeys,
+)
+
+
+class Sprntrl(SyncClient):
+    """Sync Sprntrl SDK client.
+
+    Usage:
+        with Sprntrl() as client:
+            session = client.sessions.create(os="macos", location="us-east")
+            client.sessions.wait_until_ready(session["id"])
+    """
+
+    def __init__(self, **kwargs) -> None:
+        super().__init__(**kwargs)
+        self.sessions = Sessions(self)
+        self.profiles = Profiles(self)
+        self.templates = Templates(self)
+        self.ip_whitelist = IPWhitelist(self)
+        self.usage = Usage(self)
+        self.user = User(self)
+        self.api_keys = APIKeys(self)
+
+
+class AsyncSprntrl(AsyncClient):
+    """Async Sprntrl SDK client.
+
+    Usage:
+        async with AsyncSprntrl() as client:
+            session = await client.sessions.create(os="macos", location="us-east")
+            await client.sessions.wait_until_ready(session["id"])
+    """
+
+    def __init__(self, **kwargs) -> None:
+        super().__init__(**kwargs)
+        self.sessions = AsyncSessions(self)
+        self.profiles = AsyncProfiles(self)
+        self.templates = AsyncTemplates(self)
+        self.ip_whitelist = AsyncIPWhitelist(self)
+        self.usage = AsyncUsage(self)
+        self.user = AsyncUser(self)
+        self.api_keys = AsyncAPIKeys(self)

sprntrl/_errors.py

@@ -0,0 +1,65 @@
+from __future__ import annotations
+
+from typing import Any
+
+
+class SprntrlError(Exception):
+    pass
+
+
+class APIError(SprntrlError):
+    def __init__(
+        self,
+        message: str,
+        *,
+        status: int | None = None,
+        body: Any = None,
+    ) -> None:
+        super().__init__(message)
+        self.status = status
+        # NOTE: the live httpx.Response is deliberately NOT retained. Its
+        # `.request.headers` carries `Authorization: ApiKey <key>`, so keeping
+        # it here would leak the API key into any log/Sentry capture of the
+        # exception. Only the status code and the parsed (server-controlled)
+        # error body are exposed.
+        self.body = body
+
+
+class BadRequestError(APIError): pass
+class AuthenticationError(APIError): pass
+class PermissionDeniedError(APIError): pass
+class NotFoundError(APIError): pass
+class ConflictError(APIError): pass
+class UnprocessableEntityError(APIError): pass
+class RateLimitError(APIError): pass
+class InternalServerError(APIError): pass
+
+
+class APIConnectionError(APIError):
+    def __init__(self, message: str = "Connection error", *, cause: BaseException | None = None) -> None:
+        super().__init__(message)
+        self.__cause__ = cause
+
+
+class APIConnectionTimeoutError(APIConnectionError):
+    def __init__(self, message: str = "Request timed out") -> None:
+        super().__init__(message)
+
+
+_STATUS_MAP: dict[int, type[APIError]] = {
+    400: BadRequestError,
+    401: AuthenticationError,
+    403: PermissionDeniedError,
+    404: NotFoundError,
+    409: ConflictError,
+    422: UnprocessableEntityError,
+    429: RateLimitError,
+}
+
+
+def error_for_status(status: int, message: str, *, body: Any = None) -> APIError:
+    if status >= 500:
+        cls = InternalServerError
+    else:
+        cls = _STATUS_MAP.get(status, APIError)
+    return cls(message, status=status, body=body)

sprntrl/_types.py

@@ -0,0 +1,161 @@
+from __future__ import annotations
+
+from typing import Any, Literal, TypedDict
+
+
+ProxyProtocol = Literal["HTTP", "HTTPS", "SOCKS5"]
+SessionStatus = Literal["creating", "running", "stopping", "stopped", "failed", "archiving"]
+OS = Literal["macos", "windows"]
+
+
+class ProxyConfig(TypedDict, total=False):
+    protocol: ProxyProtocol
+    host: str
+    port: int
+    username: str
+    password: str
+
+
+class ProxySummary(TypedDict, total=False):
+    """Display-friendly view of a session's proxy. Present only for BYO
+    (bring-your-own) proxies — pool proxies are shared infra and the API
+    deliberately hides their host/port. The password is never returned."""
+
+    protocol: str
+    host: str
+    port: int
+    username: str
+    address: str  # convenience form: protocol://host:port
+
+
+class Session(TypedDict, total=False):
+    id: str
+    user_id: str
+    profile_id: str | None
+    container_id: str | None
+    chrome_port: int | None
+    status: SessionStatus
+    persistent: bool
+    captcha_solver: bool
+    session_name: str | None
+    data_dir_path: str | None
+    data_dir_size: int
+    storage_status: str
+    os: OS
+    location: str
+    started_at: str | None
+    stopped_at: str | None
+    created_at: str
+    cdp_url: str
+    uptime_seconds: int
+    sidecar_port: int
+    proxy: ProxySummary  # present only for BYO-proxy sessions
+
+
+class PaginatedSessions(TypedDict):
+    sessions: list[Session]
+    total: int
+    page: int
+    per_page: int
+
+
+class Profile(TypedDict, total=False):
+    id: str
+    user_id: str
+    name: str
+    description: str | None
+    os: str | None
+    location: str | None
+    persona: str | None
+    config_json: Any
+    template_id: str | None
+    created_at: str
+    updated_at: str
+
+
+class Template(TypedDict, total=False):
+    id: str
+    name: str
+    os: str
+    config: Any
+
+
+class IPWhitelistEntry(TypedDict, total=False):
+    id: str
+    user_id: str
+    ip_address: str
+    label: str | None
+    created_at: str
+
+
+class APIKey(TypedDict, total=False):
+    id: str
+    name: str
+    key_prefix: str
+    last_used_at: str | None
+    created_at: str
+    revoked_at: str | None
+
+
+class APIKeyCreated(APIKey, total=False):
+    key: str  # Only present once at creation time
+
+
+class Usage(TypedDict, total=False):
+    total_minutes: int
+    plan_minutes: int
+    overage_minutes: int
+    month: str
+    plan: str
+    usage_percentage: float
+    allow_hours_overage: bool
+    profile_count: int
+    max_profiles: int
+    bandwidth_rate_cents: int  # pool-proxy bandwidth, cents per GB
+    hours_overage_rate_cents: int  # cents per hour over plan minutes
+    bandwidth_bytes: int  # pool-proxy bytes consumed this period
+    bandwidth_charge_amount_cents: int  # accrued bandwidth overage, cents
+    hours_overage_minutes: int  # minutes used beyond plan allowance
+    hours_overage_amount_cents: int  # accrued hours-overage charge, cents
+
+
+class UsageMonth(TypedDict):
+    month: str
+    total_minutes: int
+    plan_minutes: int
+    overage_minutes: int
+
+
+AccountStatus = Literal["pending_verification", "pending_payment", "active"]
+
+
+class User(TypedDict, total=False):
+    id: str
+    email: str
+    name: str | None
+    plan: str
+    role: str
+    allow_hours_overage: bool
+    byo_proxy_only: bool  # account may only use BYO proxies (no pool proxy)
+    bandwidth_rate_cents: int  # pool-proxy bandwidth, cents per GB
+    hours_overage_rate_cents: int  # cents per hour over plan minutes
+    must_change_password: bool
+    email_verified: bool
+    account_status: AccountStatus
+    oauth_provider: str  # "google" | "github"; absent for password accounts
+    created_at: str
+
+
+class ChangePasswordResult(TypedDict, total=False):
+    message: str
+    # Fresh tokens — issued so a programmatic client can swap credentials
+    # without a re-login. Absent for cookie/session-only flows.
+    access_token: str
+    refresh_token: str
+    token_type: str
+
+
+class FileInfo(TypedDict, total=False):
+    name: str
+    size: int
+    modified: str

sprntrl/_utils.py

@@ -0,0 +1,16 @@
+from __future__ import annotations
+
+from urllib.parse import quote
+
+
+def seg(value: object) -> str:
+    """Percent-encode a single URL path segment.
+
+    Caller- or server-supplied values (session ids, filenames, profile ids,
+    etc.) are interpolated into request paths. Without encoding, a value
+    containing ``/``, ``..``, ``?`` or ``#`` could traverse to a different
+    authenticated endpoint or inject a query/fragment — all with the API key
+    attached. ``safe=""`` ensures even ``/`` is escaped so the value can only
+    ever be a single segment. Mirrors the Node SDK's ``encodeURIComponent``.
+    """
+    return quote(str(value), safe="")

sprntrl/lib/browser.py

@@ -0,0 +1,105 @@
+from __future__ import annotations
+
+from typing import TYPE_CHECKING, Any, Mapping
+from urllib.parse import urlparse, urlunparse
+
+from .._errors import SprntrlError
+from .._utils import seg
+
+if TYPE_CHECKING:
+    from .._base_client import SyncClient, AsyncClient
+
+
+def _cdp_url_for(client: "SyncClient | AsyncClient", session: Mapping[str, Any]) -> str:
+    """Build the CDP WebSocket URL from the client's base URL. The API proxies
+    the WebSocket through /api/v1/sessions/:id/cdp with an IP-whitelist check —
+    this path is what external callers must use. (The server also returns a
+    cdp_url field, but that's an internal host:port that isn't reachable from
+    outside the API host.)"""
+    session_id = session["id"]
+    parsed = urlparse(client.base_url)
+    scheme = "wss" if parsed.scheme == "https" else "ws"
+    return urlunparse((
+        scheme, parsed.netloc, f"/api/v1/sessions/{seg(session_id)}/cdp", "", "", "",
+    ))
+
+
+def _ensure_playwright() -> Any:
+    try:
+        from playwright.sync_api import sync_playwright  # type: ignore
+    except ImportError as exc:
+        raise SprntrlError(
+            "Playwright is not installed. Run `pip install playwright` "
+            "(and `playwright install chromium` once)."
+        ) from exc
+    return sync_playwright
+
+
+def _ensure_playwright_async() -> Any:
+    try:
+        from playwright.async_api import async_playwright  # type: ignore
+    except ImportError as exc:
+        raise SprntrlError(
+            "Playwright is not installed. Run `pip install playwright` "
+            "(and `playwright install chromium` once)."
+        ) from exc
+    return async_playwright
+
+
+def connect_sync(
+    client: "SyncClient",
+    session: Mapping[str, Any],
+    *,
+    framework: str = "playwright",
+    auto_whitelist: bool = False,
+) -> Any:
+    if framework != "playwright":
+        raise SprntrlError(
+            f"Unsupported framework {framework!r}. Only 'playwright' is supported in Python."
+        )
+    if auto_whitelist:
+        try:
+            client._request(
+                "POST", "/api/v1/settings/ip-whitelist", json={"ip": "current"}
+            )
+        except Exception:
+            # Already-whitelisted or race; ignore — connect attempt will surface the real problem.
+            pass
+
+    cdp_url = _cdp_url_for(client, session)
+    sync_playwright = _ensure_playwright()
+    pw = sync_playwright().start()
+    try:
+        return pw.chromium.connect_over_cdp(cdp_url)
+    except Exception:
+        pw.stop()
+        raise
+
+
+async def connect_async(
+    client: "AsyncClient",
+    session: Mapping[str, Any],
+    *,
+    framework: str = "playwright",
+    auto_whitelist: bool = False,
+) -> Any:
+    if framework != "playwright":
+        raise SprntrlError(
+            f"Unsupported framework {framework!r}. Only 'playwright' is supported in Python."
+        )
+    if auto_whitelist:
+        try:
+            await client._request(
+                "POST", "/api/v1/settings/ip-whitelist", json={"ip": "current"}
+            )
+        except Exception:
+            pass
+
+    cdp_url = _cdp_url_for(client, session)
+    async_playwright = _ensure_playwright_async()
+    pw = await async_playwright().start()
+    try:
+        return await pw.chromium.connect_over_cdp(cdp_url)
+    except Exception:
+        await pw.stop()
+        raise

sprntrl/resources/__init__.py

@@ -0,0 +1,24 @@
+from .sessions import Sessions, AsyncSessions
+from .profiles import Profiles, AsyncProfiles
+from .templates import Templates, AsyncTemplates
+from .ip_whitelist import IPWhitelist, AsyncIPWhitelist
+from .usage import Usage, AsyncUsage
+from .user import User, AsyncUser
+from .api_keys import APIKeys, AsyncAPIKeys
+
+__all__ = [
+    "Sessions",
+    "AsyncSessions",
+    "Profiles",
+    "AsyncProfiles",
+    "Templates",
+    "AsyncTemplates",
+    "IPWhitelist",
+    "AsyncIPWhitelist",
+    "Usage",
+    "AsyncUsage",
+    "User",
+    "AsyncUser",
+    "APIKeys",
+    "AsyncAPIKeys",
+]