steerpane-sdk 0.1.0__py3-none-any.whl

steerpane/__init__.py

@@ -0,0 +1,20 @@
+"""Steerpane: remote browsers for AI agents, with human takeover."""
+from ._async_client import AsyncSteerpane
+from ._client import DEFAULT_BASE_URL, Steerpane
+from ._version import __version__
+from .errors import APIError, HumanInControlError, SteerpaneError, ToolError
+from .webhooks import WebhookSignatureError, construct_event, verify_signature
+
+__all__ = [
+    "APIError",
+    "AsyncSteerpane",
+    "DEFAULT_BASE_URL",
+    "HumanInControlError",
+    "Steerpane",
+    "SteerpaneError",
+    "ToolError",
+    "WebhookSignatureError",
+    "__version__",
+    "construct_event",
+    "verify_signature",
+]

steerpane/_async_client.py

@@ -0,0 +1,506 @@
+"""GENERATED by scripts/gen_async.py from _client.py. Do not edit."""
+from __future__ import annotations
+
+import asyncio
+import json
+import time
+import uuid
+from collections.abc import AsyncIterator, Callable
+from pathlib import Path
+from typing import Any
+
+import httpx
+
+from ._client import DictList, ENDED_CRAWL_STATUSES, ENDED_RUN_STATUSES, ENDED_SESSION_STATUSES, MCP_PROTOCOL, RETRY_STATUSES, StrList, _clean, _parse, _rate_limited, _resolve_config, _retry_after, _seg
+from ._version import __version__
+from .errors import SteerpaneError, ToolError, from_response
+from .types import AgentRun, Capture, Credential, CrawlJob, EmbedLink, FetchResult, HumanResult, Page, Profile, SearchResponse, Session, StoredFile, UploadUrl, Webhook
+
+
+class _AsyncActions:
+    """Browser actions, `POST /v1/sessions/{id}/actions`. While a human holds control, acting calls raise `HumanInControlError` and queue."""
+
+    def __init__(self, client: AsyncSteerpane) -> None:
+        self._c = client
+
+    async def run(self, session_id: str, type: str, *, wait_s: float | None = None, **args: Any) -> dict[str, Any]:
+        """Run any action type. `wait_s` holds the call until a takeover ends instead of raising, up to 600 seconds."""
+        headers = {"Steerpane-Wait": str(wait_s)} if wait_s is not None else None
+        return await self._c.request("POST", f"/v1/sessions/{_seg(session_id)}/actions", json={"type": type, **_clean(args)}, headers=headers,
+                               timeout=max(self._c.timeout, (wait_s or 0) + 30))
+
+    async def navigate(self, session_id: str, url: str, **args: Any) -> dict[str, Any]:
+        return await self.run(session_id, "navigate", url=url, **args)
+
+    async def click(self, session_id: str, selector: str, **args: Any) -> dict[str, Any]:
+        return await self.run(session_id, "click", selector=selector, **args)
+
+    async def type(self, session_id: str, selector: str, text: str, **args: Any) -> dict[str, Any]:
+        return await self.run(session_id, "type", selector=selector, text=text, **args)
+
+    async def press_key(self, session_id: str, key: str, **args: Any) -> dict[str, Any]:
+        return await self.run(session_id, "press_key", key=key, **args)
+
+    async def select_option(self, session_id: str, selector: str, option: str, **args: Any) -> dict[str, Any]:
+        return await self.run(session_id, "select_option", selector=selector, option=option, **args)
+
+    async def scroll(self, session_id: str, **args: Any) -> dict[str, Any]:
+        return await self.run(session_id, "scroll", **args)
+
+    async def wait_for(self, session_id: str, **args: Any) -> dict[str, Any]:
+        """Exactly one of `selector` (+ `state`), `text`, `url`, `load_state` or `ms`. `timeout_ms` defaults to 10000."""
+        return await self.run(session_id, "wait_for", **args)
+
+    async def snapshot(self, session_id: str, **args: Any) -> dict[str, Any]:
+        return await self.run(session_id, "snapshot", **args)
+
+    async def get_page_text(self, session_id: str, **args: Any) -> dict[str, Any]:
+        return await self.run(session_id, "get_page_text", **args)
+
+    async def element_state(self, session_id: str, selector: str, **args: Any) -> dict[str, Any]:
+        return await self.run(session_id, "element_state", selector=selector, **args)
+
+    async def form_fields(self, session_id: str, **args: Any) -> dict[str, Any]:
+        return await self.run(session_id, "form_fields", **args)
+
+    async def screenshot(self, session_id: str, **args: Any) -> dict[str, Any]:
+        return await self.run(session_id, "screenshot", **args)
+
+    async def execute(self, session_id: str, code: str, **args: Any) -> dict[str, Any]:
+        """Run JavaScript in the page. `code` is a function body, so use `return` to get a value back as `result`."""
+        return await self.run(session_id, "execute", code=code, **args)
+
+    async def extract(self, session_id: str, instruction: str, **args: Any) -> dict[str, Any]:
+        """Needs a model key on the organization."""
+        return await self.run(session_id, "extract", instruction=instruction, **args)
+
+    async def download(self, session_id: str, **args: Any) -> dict[str, Any]:
+        return await self.run(session_id, "download", **args)
+
+    async def upload_file(self, session_id: str, **args: Any) -> dict[str, Any]:
+        return await self.run(session_id, "upload_file", **args)
+
+    async def vault_fill(self, session_id: str, credential_id: str, **args: Any) -> dict[str, Any]:
+        """Type a stored credential into the page. The secret never comes back. Refused off the credential's site."""
+        return await self.run(session_id, "vault_fill", credential_id=credential_id, **args)
+
+
+class _AsyncSessions:
+    def __init__(self, client: AsyncSteerpane) -> None:
+        self._c = client
+
+    async def list(self, *, status: str | None = None, profile_id: str | None = None, q: str | None = None, project_id: str | None = None,
+             limit: int | None = None, cursor: str | None = None) -> Page[Session]:
+        return await self._c.request("GET", "/v1/sessions", params=_clean({"status": status, "profile_id": profile_id, "q": q, "project_id": project_id, "limit": limit, "cursor": cursor}))
+
+    async def create(self, *, idempotency_key: str | None = None, **config: Any) -> Session:
+        """Start a browser. `config` takes the session fields in the API docs, such as `initial_url`, `profile_id`, `auto_close`, `timeout_min`."""
+        return await self._c.request("POST", "/v1/sessions", json=_clean(config), headers={"Idempotency-Key": idempotency_key or str(uuid.uuid4())})
+
+    async def get(self, session_id: str) -> Session:
+        return await self._c.request("GET", f"/v1/sessions/{_seg(session_id)}")
+
+    async def wait_until_ready(self, session_id: str, *, timeout_s: float = 90, poll_s: float = 0.5) -> Session:
+        """Wait for the browser to leave `starting`. Raises if it ends instead, or doesn't start in time."""
+        deadline = time.monotonic() + timeout_s
+        while True:
+            session = await self.get(session_id)
+            status = session.get("status")
+            if status in ENDED_SESSION_STATUSES:
+                raise SteerpaneError(f"Session {session_id} ended before it was ready: {session.get('error_message') or status}")
+            if status != "starting":
+                return session
+            if time.monotonic() >= deadline:
+                raise SteerpaneError(f"Session {session_id} was still starting after {timeout_s:.0f} s")
+            await asyncio.sleep(poll_s)
+
+    async def stop(self, session_id: str) -> Session:
+        return await self._c.request("POST", f"/v1/sessions/{_seg(session_id)}/stop")
+
+    async def delete(self, session_id: str) -> None:
+        await self._c.request("DELETE", f"/v1/sessions/{_seg(session_id)}")
+
+    async def keepalive(self, session_id: str) -> Session:
+        return await self._c.request("POST", f"/v1/sessions/{_seg(session_id)}/keepalive")
+
+    async def takeover(self, session_id: str) -> Session:
+        return await self._c.request("POST", f"/v1/sessions/{_seg(session_id)}/takeover")
+
+    async def handback(self, session_id: str, *, outcome: str | None = None, note: str | None = None) -> Session:
+        """Give control back. `outcome` is `done` or `not_done`, and the waiting agent receives it with the note."""
+        return await self._c.request("POST", f"/v1/sessions/{_seg(session_id)}/handback", json=_clean({"outcome": outcome, "note": note}))
+
+    async def request_help(self, session_id: str, *, reason: str, message: str = "") -> dict[str, Any]:
+        """Ask a person for help. The agent goes on hold, and `agent.human_help_requested` fires."""
+        return await self._c.request("POST", f"/v1/sessions/{_seg(session_id)}/help-requests", json={"reason": reason, "message": message})
+
+    async def wait_for_human(self, session_id: str, request_id: str = "latest", *, timeout_s: float = 30) -> HumanResult:
+        """Long-poll until the human hands back. `status` is `handed_back`, `timeout` (call again) or `stopped`."""
+        return await self._c.request("GET", f"/v1/sessions/{_seg(session_id)}/help-requests/{_seg(request_id)}/wait", params={"timeout_s": timeout_s},
+                               timeout=max(self._c.timeout, timeout_s + 30))
+
+    async def events(self, session_id: str, *, limit: int | None = None, cursor: str | None = None) -> Page[dict[str, Any]]:
+        return await self._c.request("GET", f"/v1/sessions/{_seg(session_id)}/events", params=_clean({"limit": limit, "cursor": cursor}))
+
+    async def files(self, session_id: str) -> Any:
+        return await self._c.request("GET", f"/v1/sessions/{_seg(session_id)}/files")
+
+    async def zip_files(self, session_id: str) -> dict[str, Any]:
+        """Pack what the session downloaded into one ZIP in the file store."""
+        return await self._c.request("POST", f"/v1/sessions/{_seg(session_id)}/files/zip")
+
+
+class _AsyncProfiles:
+    def __init__(self, client: AsyncSteerpane) -> None:
+        self._c = client
+
+    async def list(self, *, tag: str | None = None, q: str | None = None, limit: int | None = None, cursor: str | None = None) -> Page[Profile]:
+        return await self._c.request("GET", "/v1/profiles", params=_clean({"tag": tag, "q": q, "limit": limit, "cursor": cursor}))
+
+    async def get(self, profile_id: str) -> Profile:
+        return await self._c.request("GET", f"/v1/profiles/{_seg(profile_id)}")
+
+    async def create(self, name: str, **fields: Any) -> Profile:
+        return await self._c.request("POST", "/v1/profiles", json={"name": name, **_clean(fields)})
+
+    async def update(self, profile_id: str, **fields: Any) -> Profile:
+        return await self._c.request("PATCH", f"/v1/profiles/{_seg(profile_id)}", json=fields)
+
+    async def delete(self, profile_id: str) -> None:
+        await self._c.request("DELETE", f"/v1/profiles/{_seg(profile_id)}")
+
+    async def clone(self, profile_id: str) -> Profile:
+        return await self._c.request("POST", f"/v1/profiles/{_seg(profile_id)}/clone")
+
+    async def verify(self, profile_id: str, *, domains: StrList | None = None) -> dict[str, Any]:
+        """Really load each signed-in site with the profile's state, and report whether it is still signed in."""
+        return await self._c.request("POST", f"/v1/profiles/{_seg(profile_id)}/verify", json=_clean({"domains": domains}), timeout=max(self._c.timeout, 90))
+
+    async def lock(self, profile_id: str) -> dict[str, Any]:
+        return await self._c.request("GET", f"/v1/profiles/{_seg(profile_id)}/lock")
+
+    async def import_cookies(self, profile_id: str, cookies: DictList) -> dict[str, Any]:
+        return await self._c.request("POST", f"/v1/profiles/{_seg(profile_id)}/cookies/import", json={"cookies": cookies})
+
+
+class _AsyncRuns:
+    """Hosted agent runs. These use your organization's own model key."""
+
+    def __init__(self, client: AsyncSteerpane) -> None:
+        self._c = client
+
+    async def create(self, task: str, *, idempotency_key: str | None = None, **fields: Any) -> AgentRun:
+        """`fields`: `profile_id`, `agent_id`, `model`, `max_steps`, `max_cost_usd`, `max_duration_s`, `result_schema`, `variables`, `project_id`."""
+        return await self._c.request("POST", "/v1/agents/runs", json={"task": task, **_clean(fields)}, headers={"Idempotency-Key": idempotency_key or str(uuid.uuid4())})
+
+    async def get(self, run_id: str) -> AgentRun:
+        return await self._c.request("GET", f"/v1/agents/runs/{_seg(run_id)}")
+
+    async def list(self, *, status: str | None = None, agent_id: str | None = None, project_id: str | None = None, limit: int | None = None, cursor: str | None = None) -> Page[AgentRun]:
+        return await self._c.request("GET", "/v1/agents/runs", params=_clean({"status": status, "agent_id": agent_id, "project_id": project_id, "limit": limit, "cursor": cursor}))
+
+    async def messages(self, run_id: str) -> Page[dict[str, Any]]:
+        return await self._c.request("GET", f"/v1/agents/runs/{_seg(run_id)}/messages")
+
+    async def cancel(self, run_id: str) -> AgentRun:
+        return await self._c.request("POST", f"/v1/agents/runs/{_seg(run_id)}/cancel")
+
+    async def wait(self, run_id: str, *, timeout_s: float = 600, poll_s: float = 2) -> AgentRun:
+        """Poll until the run finishes. Returns the run whatever its outcome, so check `status`."""
+        deadline = time.monotonic() + timeout_s
+        while True:
+            run = await self.get(run_id)
+            if run.get("status") in ENDED_RUN_STATUSES:
+                return run
+            if time.monotonic() >= deadline:
+                raise SteerpaneError(f"Run {run_id} had not finished after {timeout_s:.0f} s (status {run.get('status')})")
+            await asyncio.sleep(poll_s)
+
+
+class _AsyncFiles:
+    def __init__(self, client: AsyncSteerpane) -> None:
+        self._c = client
+
+    async def upload(self, file: str | Path | bytes, *, name: str | None = None, mime: str | None = None, ttl_hours: int | None = None) -> StoredFile:
+        """Store a file. The result's `id` goes straight into `actions.upload_file(session_id, file_id=...)`."""
+        if isinstance(file, bytes):
+            content, filename = file, name or "file"
+        else:
+            content, filename = Path(file).read_bytes(), name or Path(file).name
+        form = _clean({"name": name, "ttl_hours": ttl_hours})
+        return await self._c.request("POST", "/v1/files", data={k: str(v) for k, v in form.items()},
+                               files={"file": (filename, content, mime or "application/octet-stream")})
+
+    async def create_upload_url(self, name: str, *, mime: str | None = None, size_bytes: int | None = None, ttl_hours: int | None = None) -> UploadUrl:
+        return await self._c.request("POST", "/v1/files/uploads", json=_clean({"name": name, "mime": mime, "size_bytes": size_bytes, "ttl_hours": ttl_hours}))
+
+    async def list(self, *, source: str | None = None, session_id: str | None = None, q: str | None = None, limit: int | None = None, cursor: str | None = None) -> Page[StoredFile]:
+        return await self._c.request("GET", "/v1/files", params=_clean({"source": source, "session_id": session_id, "q": q, "limit": limit, "cursor": cursor}))
+
+    async def get(self, file_id: str) -> StoredFile:
+        return await self._c.request("GET", f"/v1/files/{_seg(file_id)}")
+
+    async def download(self, file_id: str) -> bytes:
+        """The file's bytes. On S3 storage the API redirects to a presigned URL, which is fetched without your token."""
+        return await self._c.request_bytes(f"/v1/files/{_seg(file_id)}/content")
+
+    async def delete(self, file_id: str) -> None:
+        await self._c.request("DELETE", f"/v1/files/{_seg(file_id)}")
+
+
+class _AsyncEmbeds:
+    """Links that show a session inside your own product. Scale and Enterprise plans. The URL is a credential: keep it out of logs."""
+
+    def __init__(self, client: AsyncSteerpane) -> None:
+        self._c = client
+
+    async def create(self, session_id: str, *, allow_takeover: bool = False, allowed_origins: StrList | None = None, expires_in_min: int | None = 30,
+               hide_toolbar: bool = False, show_control: bool = False, theme: str = "auto", end_user: dict[str, Any] | None = None, mode: str | None = None) -> EmbedLink:
+        return await self._c.request("POST", f"/v1/sessions/{_seg(session_id)}/embed", json=_clean({
+            "allow_takeover": allow_takeover, "allowed_origins": allowed_origins, "expires_in_min": expires_in_min, "hide_toolbar": hide_toolbar,
+            "show_control": show_control, "theme": theme, "end_user": end_user, "mode": mode}))
+
+    async def list(self, *, session_id: str | None = None, limit: int | None = None, cursor: str | None = None) -> Page[EmbedLink]:
+        return await self._c.request("GET", "/v1/embed-links", params=_clean({"session_id": session_id, "limit": limit, "cursor": cursor}))
+
+    async def revoke(self, link_id: str) -> EmbedLink:
+        """Closes open iframes at once, and returns control to the agent if this link held it."""
+        return await self._c.request("POST", f"/v1/embed-links/{_seg(link_id)}/revoke")
+
+
+class _AsyncWebhooks:
+    """Endpoint management. To check a delivery's signature use `steerpane.webhooks.verify_signature`, which needs no client."""
+
+    def __init__(self, client: AsyncSteerpane) -> None:
+        self._c = client
+
+    async def list(self) -> Page[Webhook]:
+        return await self._c.request("GET", "/v1/webhooks")
+
+    async def create(self, url: str, events: StrList, **fields: Any) -> Webhook:
+        return await self._c.request("POST", "/v1/webhooks", json={"url": url, "events": events, **_clean(fields)})
+
+    async def get(self, webhook_id: str) -> Webhook:
+        return await self._c.request("GET", f"/v1/webhooks/{_seg(webhook_id)}")
+
+    async def delete(self, webhook_id: str) -> None:
+        await self._c.request("DELETE", f"/v1/webhooks/{_seg(webhook_id)}")
+
+    async def send_test(self, webhook_id: str, *, event: str | None = None) -> dict[str, Any]:
+        return await self._c.request("POST", f"/v1/webhooks/{_seg(webhook_id)}/test", json=_clean({"event": event}))
+
+
+class _AsyncVault:
+    """Stored logins. Passwords and TOTP secrets go in and never come back to an API token."""
+
+    def __init__(self, client: AsyncSteerpane) -> None:
+        self._c = client
+
+    async def list(self) -> Page[Credential]:
+        return await self._c.request("GET", "/v1/vault/credentials")
+
+    async def create(self, *, domain: str, username: str, password: str, name: str | None = None, totp_secret: str | None = None, **fields: Any) -> Credential:
+        return await self._c.request("POST", "/v1/vault/credentials", json=_clean({"domain": domain, "username": username, "password": password, "name": name, "totp_secret": totp_secret, **fields}))
+
+    async def delete(self, credential_id: str) -> None:
+        await self._c.request("DELETE", f"/v1/vault/credentials/{_seg(credential_id)}")
+
+
+class _AsyncCrawls:
+    def __init__(self, client: AsyncSteerpane) -> None:
+        self._c = client
+
+    async def start(self, url: str, **options: Any) -> CrawlJob:
+        """`options`: `limit`, `max_depth`, `mode`, `formats`, `include_paths`, `exclude_paths`, `check_links`, `same_site`, ..."""
+        return await self._c.request("POST", "/v1/crawl", json={"url": url, **_clean(options)})
+
+    async def get(self, job_id: str, *, cursor: str | None = None, limit: int | None = None, include_content: bool | None = None) -> CrawlJob:
+        params = _clean({"cursor": cursor, "limit": limit, "include_content": None if include_content is None else str(include_content).lower()})
+        return await self._c.request("GET", f"/v1/crawl/{_seg(job_id)}", params=params)
+
+    async def cancel(self, job_id: str) -> CrawlJob:
+        return await self._c.request("DELETE", f"/v1/crawl/{_seg(job_id)}")
+
+    async def wait(self, job_id: str, *, timeout_s: float = 300, poll_s: float = 2) -> CrawlJob:
+        deadline = time.monotonic() + timeout_s
+        while True:
+            job = await self.get(job_id, include_content=False)
+            if job.get("status") in ENDED_CRAWL_STATUSES:
+                return job
+            if time.monotonic() >= deadline:
+                raise SteerpaneError(f"Crawl {job_id} had not finished after {timeout_s:.0f} s")
+            await asyncio.sleep(poll_s)
+
+
+class _AsyncMcp:
+    """Call MCP tools over the API's Streamable HTTP endpoint. A few tools are MCP only, such as `act`, `observe` and `wait_for_code`."""
+
+    def __init__(self, client: AsyncSteerpane) -> None:
+        self._c = client
+        self._session_id: str | None = None
+        self._next_id = 0
+
+    async def _post(self, method: str, params: dict[str, Any], *, notify: bool = False, timeout: float | None = None) -> Any:
+        message: dict[str, Any] = {"jsonrpc": "2.0", "method": method, "params": params}
+        if not notify:
+            self._next_id += 1
+            message["id"] = self._next_id
+        headers = {"Accept": "application/json, text/event-stream", "Mcp-Protocol-Version": MCP_PROTOCOL}
+        if self._session_id:
+            headers["Mcp-Session-Id"] = self._session_id
+        response = await self._c.raw_request("POST", "/mcp", json=message, headers=headers, timeout=timeout)
+        if response.status_code >= 400:
+            raise from_response(response.status_code, _parse(response), _retry_after(response))
+        self._session_id = response.headers.get("mcp-session-id") or self._session_id
+        if notify:
+            return None
+        body = response.text
+        if "event-stream" in response.headers.get("content-type", ""):
+            frames = [line[5:].strip() for line in body.splitlines() if line.startswith("data:")]
+            replies = [json.loads(f) for f in frames if f]
+            reply = next((m for m in replies if m.get("id") == message["id"]), None)
+        else:
+            reply = json.loads(body)
+        if not reply:
+            raise SteerpaneError(f"MCP {method}: the server sent no reply")
+        if reply.get("error"):
+            raise SteerpaneError(f"MCP {method}: {reply['error'].get('message')}")
+        return reply.get("result")
+
+    async def _ensure_session(self) -> None:
+        if self._session_id:
+            return
+        await self._post("initialize", {"protocolVersion": MCP_PROTOCOL, "capabilities": {}, "clientInfo": {"name": "steerpane-sdk-python-async", "version": __version__}})
+        await self._post("notifications/initialized", {}, notify=True)
+
+    async def list_tools(self) -> DictList:
+        """The default list: core tools plus `search_tools` and `call_tool`. Any tool still runs by name with `call`."""
+        await self._ensure_session()
+        return (await self._post("tools/list", {}))["tools"]
+
+    async def call(self, tool: str, *, timeout_s: float = 120, **arguments: Any) -> Any:
+        """Run a tool and return its JSON result. A tool failure raises `ToolError` with the API's error code."""
+        await self._ensure_session()
+        result = await self._post("tools/call", {"name": tool, "arguments": _clean(arguments)}, timeout=timeout_s)
+        text = next((c.get("text") for c in result.get("content", []) if c.get("type") == "text"), None)
+        try:
+            payload = result.get("structuredContent") or (json.loads(text) if text else None)
+        except ValueError:
+            payload = text
+        if result.get("isError"):
+            err = payload.get("error", {}) if isinstance(payload, dict) else {}
+            raise ToolError(tool, str(err.get("code") or "tool_error"), str(err.get("message") or text or "Tool failed"), err.get("details"))
+        return payload
+
+
+class AsyncSteerpane:
+    """Client for the AsyncSteerpane API.
+
+    `token` falls back to `STEERPANE_API_TOKEN`, and `base_url` to `STEERPANE_API_URL`. Results are plain dicts, typed for your editor.
+    """
+
+    def __init__(self, token: str | None = None, *, base_url: str | None = None, timeout: float = 60, max_retries: int = 2,
+                 allow_insecure_http: bool = False, http_client: httpx.AsyncClient | None = None) -> None:
+        self.token, self.base_url = _resolve_config(token, base_url, allow_insecure_http)
+        self.timeout = timeout
+        self.max_retries = max_retries
+        self._http = http_client or httpx.AsyncClient(follow_redirects=False)
+        self.sessions = _AsyncSessions(self)
+        self.actions = _AsyncActions(self)
+        self.profiles = _AsyncProfiles(self)
+        self.runs = _AsyncRuns(self)
+        self.files = _AsyncFiles(self)
+        self.embeds = _AsyncEmbeds(self)
+        self.webhooks = _AsyncWebhooks(self)
+        self.vault = _AsyncVault(self)
+        self.crawls = _AsyncCrawls(self)
+        self.mcp = _AsyncMcp(self)
+
+    def __repr__(self) -> str:  # the token stays out of logs and tracebacks
+        return f"{type(self).__name__}(base_url={self.base_url!r})"
+
+    async def aclose(self) -> None:
+        await self._http.aclose()
+
+    async def __aenter__(self) -> AsyncSteerpane:
+        return self
+
+    async def __aexit__(self, *exc: object) -> None:
+        await self.aclose()
+
+    # ---- transport
+
+    async def raw_request(self, method: str, path: str, *, json: Any = None, params: dict[str, Any] | None = None, headers: dict[str, str] | None = None,
+                    data: dict[str, str] | None = None, files: Any = None, timeout: float | None = None) -> httpx.Response:
+        """One HTTP call with your token and the retry rules. Doesn't raise on an error status."""
+        merged = {"Authorization": f"Bearer {self.token}", "User-Agent": f"steerpane-sdk-python-async/{__version__}", **(headers or {})}
+        idempotent = method in ("GET", "HEAD", "DELETE") or "Idempotency-Key" in merged
+        attempt = 0
+        while True:
+            try:
+                response = await self._http.request(method, self.base_url + path, json=json, params=params, headers=merged, data=data, files=files, timeout=timeout or self.timeout)
+            except httpx.TransportError:
+                if not idempotent or attempt >= self.max_retries:
+                    raise
+                delay = 0.5 * 2**attempt
+            else:
+                rate_limited = response.status_code == 429 and _rate_limited(response)
+                # A stored 429 replays under an Idempotency-Key, so a keyed POST isn't retried on it. A rate-limited request never ran.
+                retryable = (idempotent and response.status_code in RETRY_STATUSES) or (rate_limited and "Idempotency-Key" not in merged)
+                if not retryable or attempt >= self.max_retries:
+                    return response
+                delay = _retry_after(response) or 0.5 * 2**attempt
+            attempt += 1
+            await asyncio.sleep(min(delay, 30))
+
+    async def request(self, method: str, path: str, *, json: Any = None, params: dict[str, Any] | None = None, headers: dict[str, str] | None = None,
+                data: dict[str, str] | None = None, files: Any = None, timeout: float | None = None) -> Any:
+        """Call any endpoint, for what this client has no method for. Returns the parsed body, or raises `APIError`."""
+        response = await self.raw_request(method, path, json=json, params=params, headers=headers, data=data, files=files, timeout=timeout)
+        if response.status_code >= 300:
+            raise from_response(response.status_code, _parse(response), _retry_after(response))
+        return _parse(response)
+
+    async def request_bytes(self, path: str) -> bytes:
+        response = await self.raw_request("GET", path)
+        if response.is_redirect and response.headers.get("location"):
+            response = await self._http.request("GET", response.headers["location"], timeout=self.timeout)  # presigned: no token
+        if response.status_code >= 300:
+            raise from_response(response.status_code, _parse(response), _retry_after(response))
+        return response.content
+
+    async def paginate(self, list_call: Callable[..., Any], **params: Any) -> AsyncIterator[Any]:
+        """Every item across pages: `async for s in client.paginate(client.sessions.list, status="live")`."""
+        cursor = params.pop("cursor", None)
+        while True:
+            page = await list_call(cursor=cursor, **params)
+            for item in page.get("data", []):
+                yield item
+            cursor = page.get("next_cursor")
+            if not cursor:
+                return
+
+    # ---- one-call tools: no session to manage
+
+    async def fetch(self, url: str, *, format: str | None = None, mode: str | None = None, formats: StrList | None = None, **fields: Any) -> FetchResult:
+        """Fetch a page without a browser session. `mode` is `fast`, `deep` or `auto`. The site's own status is in the result's `status`."""
+        return await self.request("POST", "/v1/fetch", json=_clean({"url": url, "format": format, "mode": mode, "formats": formats, **fields}))
+
+    async def fetch_batch(self, urls: StrList, **fields: Any) -> dict[str, Any]:
+        return await self.request("POST", "/v1/fetch/batch", json={"urls": urls, **_clean(fields)}, timeout=max(self.timeout, 180))
+
+    async def search(self, query: str, *, limit: int | None = None) -> SearchResponse:
+        return await self.request("POST", "/v1/search", json=_clean({"query": query, "limit": limit}))
+
+    async def screenshot(self, url: str, **options: Any) -> Capture:
+        return await self.request("POST", "/v1/screenshot", json={"url": url, **_clean(options)}, timeout=max(self.timeout, 120))
+
+    async def pdf(self, url: str, **options: Any) -> Capture:
+        return await self.request("POST", "/v1/pdf", json={"url": url, **_clean(options)}, timeout=max(self.timeout, 120))
+
+    async def map(self, url: str, **options: Any) -> dict[str, Any]:
+        return await self.request("POST", "/v1/map", json={"url": url, **_clean(options)}, timeout=max(self.timeout, 120))
+
+    async def extract(self, *, instruction: str, url: str | None = None, urls: StrList | None = None, schema: dict[str, Any] | None = None, **options: Any) -> dict[str, Any]:
+        """Structured data from up to 10 URLs. Needs a model key on the organization."""
+        return await self.request("POST", "/v1/extract", json=_clean({"instruction": instruction, "url": url, "urls": urls, "schema": schema, **options}), timeout=max(self.timeout, 180))