sprntrl 0.1.0__tar.gz

sprntrl-0.1.0/.gitignore

@@ -0,0 +1,12 @@
+__pycache__/
+*.py[cod]
+*.egg-info/
+.venv/
+venv/
+dist/
+build/
+.pytest_cache/
+.mypy_cache/
+.ruff_cache/
+.DS_Store
+*.png

sprntrl-0.1.0/LICENSE

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

sprntrl-0.1.0/PKG-INFO

@@ -0,0 +1,152 @@
+Metadata-Version: 2.4
+Name: sprntrl
+Version: 0.1.0
+Summary: Supernatural Python SDK — stealth browser-as-a-service client.
+Project-URL: Homepage, https://supernatural.sh
+Project-URL: Repository, https://github.com/supernatural-browser/sprntrl-python
+Project-URL: Documentation, https://app.supernatural.sh/docs
+Project-URL: Bug Tracker, https://github.com/supernatural-browser/sprntrl-python/issues
+Author: Supernatural
+License: MIT
+License-File: LICENSE
+Keywords: automation,browser,cdp,playwright,scraping,stealth
+Classifier: Development Status :: 3 - Alpha
+Classifier: Intended Audience :: Developers
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.9
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Topic :: Internet :: WWW/HTTP :: Browsers
+Classifier: Topic :: Software Development :: Libraries :: Python Modules
+Requires-Python: >=3.9
+Requires-Dist: httpx>=0.25
+Provides-Extra: dev
+Requires-Dist: mypy>=1.8; extra == 'dev'
+Requires-Dist: pytest-asyncio>=0.23; extra == 'dev'
+Requires-Dist: pytest>=7; extra == 'dev'
+Requires-Dist: respx>=0.20; extra == 'dev'
+Requires-Dist: ruff>=0.5; extra == 'dev'
+Provides-Extra: playwright
+Requires-Dist: playwright>=1.40; extra == 'playwright'
+Description-Content-Type: text/markdown
+
+# Supernatural Python SDK
+
+Official Python client for the [Supernatural](https://supernatural.sh) stealth browser-as-a-service API.
+
+## Installation
+
+```bash
+pip install sprntrl
+# Optional: Playwright integration
+pip install 'sprntrl[playwright]' && playwright install chromium
+```
+
+## Quick start
+
+```python
+from sprntrl import Sprntrl
+
+client = Sprntrl()  # reads SPRNTRL_API_KEY from env
+
+session = client.sessions.create(os="macos", location="us-east")
+
+# browser_session is a context manager that waits for the session,
+# connects Playwright, and closes the browser + Playwright on exit.
+# auto_whitelist=True registers your IP (CDP access is IP-gated).
+with client.sessions.browser_session(session["id"], auto_whitelist=True) as browser:
+    page = browser.contexts[0].new_page()
+    page.goto("https://bot.sannysoft.com")
+    page.screenshot(path="out.png")
+
+client.sessions.stop(session["id"])
+```
+
+### Async
+
+```python
+import asyncio
+from sprntrl import AsyncSprntrl
+
+async def main():
+    async with AsyncSprntrl() as client:
+        session = await client.sessions.create(os="macos", location="us-east")
+        async with client.sessions.browser_session(session["id"], auto_whitelist=True) as browser:
+            page = await browser.contexts[0].new_page()
+            await page.goto("https://example.com")
+        await client.sessions.stop(session["id"])
+
+asyncio.run(main())
+```
+
+### Lower-level `connect()` and `cdp_url()`
+
+If you want to manage the browser lifecycle yourself:
+
+```python
+browser = client.sessions.connect(session_id, auto_whitelist=True)
+# ... your code ...
+browser.close()
+```
+
+Or to hand the raw WebSocket URL to any CDP client (chrome-remote-interface-python, raw `websockets`, etc.):
+
+```python
+url = client.sessions.cdp_url(session_id)
+# url = "wss://api.supernatural.sh/api/v1/sessions/<id>/cdp"
+```
+
+## Configuration
+
+| Env var            | Default                    |
+|--------------------|----------------------------|
+| `SPRNTRL_API_KEY`  | —                          |
+| `SPRNTRL_BASE_URL` | `https://api.supernatural.sh`   |
+
+Or override per client:
+
+```python
+client = Sprntrl(api_key="sk_...", base_url="https://api.supernatural.sh", timeout=30, max_retries=2)
+```
+
+## Resources
+
+- `client.sessions` — create, list, list_active, list_history, list_resumable, list_locations, get, stop, resume, delete_persistent, wait_until_ready, connect, browser_session, cdp_url
+- `client.sessions.files` — list, download, upload
+- `client.profiles` — create, list, get, update, duplicate, delete
+- `client.templates.list()`
+- `client.ip_whitelist` — list, add, remove
+- `client.usage` — current, history
+- `client.user` — me, update, update_settings, change_password
+- `client.api_keys` — list, create (full key returned ONCE), revoke
+
+## Error handling
+
+```python
+from sprntrl import Sprntrl, APIError, RateLimitError, AuthenticationError
+
+client = Sprntrl()
+try:
+    client.sessions.create(os="macos", location="us-east")
+except RateLimitError as e:
+    print("rate limited:", e.status, e.body)
+except AuthenticationError:
+    print("bad API key")
+except APIError as e:
+    print("api error:", e.status, e)
+```
+
+Transient errors (5xx, 429, 408, connection errors) are retried automatically up to `max_retries` times with exponential backoff.
+
+## Gotchas
+
+- **CDP access is IP-whitelist gated.** The WebSocket at `/api/v1/sessions/:id/cdp` does not accept bearer auth — instead, your public IP (as Cloudflare sees it) must be in your account's whitelist. Use `client.ip_whitelist.add("current")` or pass `auto_whitelist=True` to `sessions.connect`.
+- **Sessions start async.** `sessions.create` returns immediately with `status: "creating"`. Call `sessions.wait_until_ready(id)` before connecting, or just use `sessions.connect()` which waits for you.
+- **API key is shown only once.** `api_keys.create()` returns the full `key` field exactly once — store it immediately.
+
+## License
+
+MIT

sprntrl-0.1.0/README.md

@@ -0,0 +1,117 @@
+# Supernatural Python SDK
+
+Official Python client for the [Supernatural](https://supernatural.sh) stealth browser-as-a-service API.
+
+## Installation
+
+```bash
+pip install sprntrl
+# Optional: Playwright integration
+pip install 'sprntrl[playwright]' && playwright install chromium
+```
+
+## Quick start
+
+```python
+from sprntrl import Sprntrl
+
+client = Sprntrl()  # reads SPRNTRL_API_KEY from env
+
+session = client.sessions.create(os="macos", location="us-east")
+
+# browser_session is a context manager that waits for the session,
+# connects Playwright, and closes the browser + Playwright on exit.
+# auto_whitelist=True registers your IP (CDP access is IP-gated).
+with client.sessions.browser_session(session["id"], auto_whitelist=True) as browser:
+    page = browser.contexts[0].new_page()
+    page.goto("https://bot.sannysoft.com")
+    page.screenshot(path="out.png")
+
+client.sessions.stop(session["id"])
+```
+
+### Async
+
+```python
+import asyncio
+from sprntrl import AsyncSprntrl
+
+async def main():
+    async with AsyncSprntrl() as client:
+        session = await client.sessions.create(os="macos", location="us-east")
+        async with client.sessions.browser_session(session["id"], auto_whitelist=True) as browser:
+            page = await browser.contexts[0].new_page()
+            await page.goto("https://example.com")
+        await client.sessions.stop(session["id"])
+
+asyncio.run(main())
+```
+
+### Lower-level `connect()` and `cdp_url()`
+
+If you want to manage the browser lifecycle yourself:
+
+```python
+browser = client.sessions.connect(session_id, auto_whitelist=True)
+# ... your code ...
+browser.close()
+```
+
+Or to hand the raw WebSocket URL to any CDP client (chrome-remote-interface-python, raw `websockets`, etc.):
+
+```python
+url = client.sessions.cdp_url(session_id)
+# url = "wss://api.supernatural.sh/api/v1/sessions/<id>/cdp"
+```
+
+## Configuration
+
+| Env var            | Default                    |
+|--------------------|----------------------------|
+| `SPRNTRL_API_KEY`  | —                          |
+| `SPRNTRL_BASE_URL` | `https://api.supernatural.sh`   |
+
+Or override per client:
+
+```python
+client = Sprntrl(api_key="sk_...", base_url="https://api.supernatural.sh", timeout=30, max_retries=2)
+```
+
+## Resources
+
+- `client.sessions` — create, list, list_active, list_history, list_resumable, list_locations, get, stop, resume, delete_persistent, wait_until_ready, connect, browser_session, cdp_url
+- `client.sessions.files` — list, download, upload
+- `client.profiles` — create, list, get, update, duplicate, delete
+- `client.templates.list()`
+- `client.ip_whitelist` — list, add, remove
+- `client.usage` — current, history
+- `client.user` — me, update, update_settings, change_password
+- `client.api_keys` — list, create (full key returned ONCE), revoke
+
+## Error handling
+
+```python
+from sprntrl import Sprntrl, APIError, RateLimitError, AuthenticationError
+
+client = Sprntrl()
+try:
+    client.sessions.create(os="macos", location="us-east")
+except RateLimitError as e:
+    print("rate limited:", e.status, e.body)
+except AuthenticationError:
+    print("bad API key")
+except APIError as e:
+    print("api error:", e.status, e)
+```
+
+Transient errors (5xx, 429, 408, connection errors) are retried automatically up to `max_retries` times with exponential backoff.
+
+## Gotchas
+
+- **CDP access is IP-whitelist gated.** The WebSocket at `/api/v1/sessions/:id/cdp` does not accept bearer auth — instead, your public IP (as Cloudflare sees it) must be in your account's whitelist. Use `client.ip_whitelist.add("current")` or pass `auto_whitelist=True` to `sessions.connect`.
+- **Sessions start async.** `sessions.create` returns immediately with `status: "creating"`. Call `sessions.wait_until_ready(id)` before connecting, or just use `sessions.connect()` which waits for you.
+- **API key is shown only once.** `api_keys.create()` returns the full `key` field exactly once — store it immediately.
+
+## License
+
+MIT

sprntrl-0.1.0/pyproject.toml

@@ -0,0 +1,64 @@
+[build-system]
+requires = ["hatchling"]
+build-backend = "hatchling.build"
+
+[project]
+name = "sprntrl"
+version = "0.1.0"
+description = "Supernatural Python SDK — stealth browser-as-a-service client."
+readme = "README.md"
+requires-python = ">=3.9"
+license = { text = "MIT" }
+authors = [{ name = "Supernatural" }]
+keywords = ["browser", "automation", "playwright", "cdp", "stealth", "scraping"]
+classifiers = [
+    "Development Status :: 3 - Alpha",
+    "Intended Audience :: Developers",
+    "License :: OSI Approved :: MIT License",
+    "Programming Language :: Python :: 3",
+    "Programming Language :: Python :: 3.9",
+    "Programming Language :: Python :: 3.10",
+    "Programming Language :: Python :: 3.11",
+    "Programming Language :: Python :: 3.12",
+    "Programming Language :: Python :: 3.13",
+    "Topic :: Internet :: WWW/HTTP :: Browsers",
+    "Topic :: Software Development :: Libraries :: Python Modules",
+]
+dependencies = [
+    "httpx>=0.25",
+]
+
+[project.optional-dependencies]
+playwright = ["playwright>=1.40"]
+dev = [
+    "pytest>=7",
+    "pytest-asyncio>=0.23",
+    "respx>=0.20",
+    "ruff>=0.5",
+    "mypy>=1.8",
+]
+
+[project.urls]
+Homepage = "https://supernatural.sh"
+Repository = "https://github.com/supernatural-browser/sprntrl-python"
+Documentation = "https://app.supernatural.sh/docs"
+"Bug Tracker" = "https://github.com/supernatural-browser/sprntrl-python/issues"
+
+[tool.hatch.build.targets.wheel]
+packages = ["sprntrl"]
+# sprntrl/py.typed (PEP 561) is under the package dir, so hatchling ships it
+# in the wheel automatically alongside the .py sources.
+
+[tool.hatch.build.targets.sdist]
+# Default sdist is VCS-driven; list explicitly so LICENSE + py.typed ship even
+# before they're committed and the sdist stays reproducible.
+include = ["sprntrl", "README.md", "LICENSE", "pyproject.toml"]
+
+[tool.ruff]
+line-length = 100
+target-version = "py39"
+
+[tool.mypy]
+python_version = "3.9"
+strict = false
+warn_unused_ignores = true

sprntrl-0.1.0/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-0.1.0/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-0.1.0/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)