roveapi 1.0.0__tar.gz

roveapi-1.0.0/.gitignore

@@ -0,0 +1,8 @@
+node_modules/
+dist/
+.env
+.env.local
+*.log
+.DS_Store
+.turbo
+coverage/

roveapi-1.0.0/PKG-INFO

@@ -0,0 +1,72 @@
+Metadata-Version: 2.4
+Name: roveapi
+Version: 1.0.0
+Summary: Browser automation SDK for AI agents — Playwright-as-a-Service with accessibility trees
+Project-URL: Homepage, https://roveapi.com
+Project-URL: Documentation, https://roveapi.com/docs
+Project-URL: Repository, https://github.com/roveapi/roveapi-python
+License-Expression: MIT
+Keywords: a11y,accessibility,ai-agent,automation,browser,mcp,playwright
+Requires-Python: >=3.9
+Requires-Dist: httpx>=0.27
+Description-Content-Type: text/markdown
+
+# roveapi
+
+Python SDK for the [Rove](https://roveapi.com) browser automation API — Playwright-as-a-Service with accessibility trees for 77% fewer tokens.
+
+## Install
+
+```bash
+pip install roveapi
+```
+
+## Quickstart
+
+```python
+from roveapi import BrowserClient
+
+client = BrowserClient(api_key="rvp_live_...")
+
+# One-shot screenshot
+screenshot = client.screenshot(url="https://example.com")
+print(screenshot["url"])  # signed S3 URL
+
+# Session with context manager (auto-close)
+with client.session() as session:
+    session.navigate("https://example.com")
+    tree = session.get_a11y_tree()
+    print(tree["result"]["tree"])  # ~26K tokens vs ~114K for screenshot
+
+    session.click(label="Get Started")
+    session.fill(selector="#email", value="user@example.com")
+```
+
+## Error Handling
+
+```python
+from roveapi import BrowserClient, InsufficientCreditsError, RateLimitError
+
+try:
+    with client.session() as session:
+        session.navigate("https://example.com")
+except InsufficientCreditsError:
+    print("Top up credits at roveapi.com")
+except RateLimitError as e:
+    print(f"Retry after {e.retry_after} seconds")
+```
+
+## API
+
+### `BrowserClient(api_key, base_url?, retries?, retry_delay?)`
+
+- `client.session(**options)` → `Session` (context manager)
+- `client.screenshot(url, **options)` → dict
+- `client.extract(url, schema, **options)` → dict
+- `client.usage()` → dict
+
+### `Session`
+
+All 12 browser actions: `navigate()`, `get_a11y_tree()`, `click()`, `fill()`, `select()`, `scroll()`, `wait_for()`, `screenshot()`, `get_text()`, `get_attribute()`, `evaluate()`, `close()`.
+
+Auto-retry on 503 with exponential backoff. No retry on 402 or 410.

roveapi-1.0.0/README.md

@@ -0,0 +1,59 @@
+# roveapi
+
+Python SDK for the [Rove](https://roveapi.com) browser automation API — Playwright-as-a-Service with accessibility trees for 77% fewer tokens.
+
+## Install
+
+```bash
+pip install roveapi
+```
+
+## Quickstart
+
+```python
+from roveapi import BrowserClient
+
+client = BrowserClient(api_key="rvp_live_...")
+
+# One-shot screenshot
+screenshot = client.screenshot(url="https://example.com")
+print(screenshot["url"])  # signed S3 URL
+
+# Session with context manager (auto-close)
+with client.session() as session:
+    session.navigate("https://example.com")
+    tree = session.get_a11y_tree()
+    print(tree["result"]["tree"])  # ~26K tokens vs ~114K for screenshot
+
+    session.click(label="Get Started")
+    session.fill(selector="#email", value="user@example.com")
+```
+
+## Error Handling
+
+```python
+from roveapi import BrowserClient, InsufficientCreditsError, RateLimitError
+
+try:
+    with client.session() as session:
+        session.navigate("https://example.com")
+except InsufficientCreditsError:
+    print("Top up credits at roveapi.com")
+except RateLimitError as e:
+    print(f"Retry after {e.retry_after} seconds")
+```
+
+## API
+
+### `BrowserClient(api_key, base_url?, retries?, retry_delay?)`
+
+- `client.session(**options)` → `Session` (context manager)
+- `client.screenshot(url, **options)` → dict
+- `client.extract(url, schema, **options)` → dict
+- `client.usage()` → dict
+
+### `Session`
+
+All 12 browser actions: `navigate()`, `get_a11y_tree()`, `click()`, `fill()`, `select()`, `scroll()`, `wait_for()`, `screenshot()`, `get_text()`, `get_attribute()`, `evaluate()`, `close()`.
+
+Auto-retry on 503 with exponential backoff. No retry on 402 or 410.

roveapi-1.0.0/pyproject.toml

@@ -0,0 +1,18 @@
+[build-system]
+requires = ["hatchling"]
+build-backend = "hatchling.build"
+
+[project]
+name = "roveapi"
+version = "1.0.0"
+description = "Browser automation SDK for AI agents — Playwright-as-a-Service with accessibility trees"
+readme = "README.md"
+license = "MIT"
+requires-python = ">=3.9"
+dependencies = ["httpx>=0.27"]
+keywords = ["browser", "automation", "playwright", "a11y", "accessibility", "mcp", "ai-agent"]
+
+[project.urls]
+Homepage = "https://roveapi.com"
+Documentation = "https://roveapi.com/docs"
+Repository = "https://github.com/roveapi/roveapi-python"

roveapi-1.0.0/src/roveapi/__init__.py

@@ -0,0 +1,23 @@
+from .client import BrowserClient
+from .session import Session
+from .errors import (
+    RoveError,
+    InsufficientCreditsError,
+    SessionExpiredError,
+    RateLimitError,
+    BrowserCrashError,
+    PoolExhaustedError,
+    InvalidParamsError,
+)
+
+__all__ = [
+    "BrowserClient",
+    "Session",
+    "RoveError",
+    "InsufficientCreditsError",
+    "SessionExpiredError",
+    "RateLimitError",
+    "BrowserCrashError",
+    "PoolExhaustedError",
+    "InvalidParamsError",
+]

roveapi-1.0.0/src/roveapi/client.py

@@ -0,0 +1,161 @@
+from __future__ import annotations
+
+import time
+import random
+from typing import Any
+
+import httpx
+
+from .errors import (
+    RoveError,
+    InsufficientCreditsError,
+    SessionExpiredError,
+    RateLimitError,
+    BrowserCrashError,
+    PoolExhaustedError,
+    InvalidParamsError,
+)
+from .session import Session
+
+
+def _map_error(response: httpx.Response) -> RoveError:
+    try:
+        body = response.json()
+    except Exception:
+        body = {}
+
+    detail = body.get("detail", response.reason_phrase)
+    code = (body.get("type", "") or "").rsplit("/", 1)[-1] or "unknown"
+
+    match response.status_code:
+        case 400:
+            return InvalidParamsError(detail)
+        case 402:
+            return InsufficientCreditsError(detail)
+        case 410:
+            return SessionExpiredError(detail)
+        case 429:
+            retry_after = int(response.headers.get("retry-after", "60"))
+            return RateLimitError(retry_after, detail)
+        case 503:
+            if code == "pool-exhausted":
+                return PoolExhaustedError(detail)
+            return BrowserCrashError(detail)
+        case _:
+            return RoveError(detail, response.status_code, code, detail)
+
+
+class BrowserClient:
+    """Rove browser automation client."""
+
+    def __init__(
+        self,
+        api_key: str,
+        base_url: str = "https://api.roveapi.com",
+        retries: int = 3,
+        retry_delay: float = 1.0,
+    ):
+        self.api_key = api_key
+        self.base_url = base_url
+        self.retries = retries
+        self.retry_delay = retry_delay
+        self._client = httpx.Client(
+            base_url=base_url,
+            headers={
+                "authorization": f"Bearer {api_key}",
+                "content-type": "application/json",
+            },
+            timeout=60.0,
+        )
+
+    def __enter__(self):
+        return self
+
+    def __exit__(self, *_: Any):
+        self._client.close()
+
+    def close(self):
+        self._client.close()
+
+    def _request(self, method: str, path: str, json: dict[str, Any] | None = None) -> dict[str, Any]:
+        last_error: Exception | None = None
+        for attempt in range(self.retries + 1):
+            try:
+                response = self._client.request(method, path, json=json)
+                if response.is_success:
+                    return response.json()
+                error = _map_error(response)
+                if isinstance(error, (InsufficientCreditsError, SessionExpiredError, InvalidParamsError)):
+                    raise error
+                raise error
+            except (InsufficientCreditsError, SessionExpiredError, InvalidParamsError):
+                raise
+            except Exception as e:
+                last_error = e
+                if attempt < self.retries:
+                    jitter = random.uniform(0.85, 1.15)
+                    delay = self.retry_delay * (2**attempt) * jitter
+                    time.sleep(delay)
+        raise last_error  # type: ignore[misc]
+
+    def session(
+        self,
+        *,
+        viewport: dict[str, int] | None = None,
+        record_video: bool = False,
+        locale: str | None = None,
+        timezone: str | None = None,
+        user_agent: str | None = None,
+        block_resources: list[str] | None = None,
+    ) -> Session:
+        """Create a persistent browser session."""
+        body: dict[str, Any] = {}
+        if viewport:
+            body["viewport"] = viewport
+        if record_video:
+            body["record_video"] = True
+        if locale:
+            body["locale"] = locale
+        if timezone:
+            body["timezone"] = timezone
+        if user_agent:
+            body["user_agent"] = user_agent
+        if block_resources:
+            body["block_resources"] = block_resources
+
+        data = self._request("POST", "/v1/browser/session", json=body)
+        return Session(data["session_id"], self)
+
+    def screenshot(
+        self,
+        url: str,
+        *,
+        selector: str | None = None,
+        full_page: bool = False,
+        format: str = "png",
+        viewport: dict[str, int] | None = None,
+    ) -> dict[str, Any]:
+        """One-shot screenshot (no persistent session)."""
+        body: dict[str, Any] = {"url": url, "full_page": full_page, "format": format}
+        if selector:
+            body["selector"] = selector
+        if viewport:
+            body["viewport"] = viewport
+        return self._request("POST", "/v1/browser/screenshot", json=body)
+
+    def extract(
+        self,
+        url: str,
+        schema: dict[str, str],
+        *,
+        wait_for_selector: str | None = None,
+    ) -> dict[str, Any]:
+        """One-shot structured data extraction."""
+        body: dict[str, Any] = {"url": url, "schema": schema}
+        if wait_for_selector:
+            body["wait_for_selector"] = wait_for_selector
+        return self._request("POST", "/v1/browser/extract", json=body)
+
+    def usage(self) -> dict[str, Any]:
+        """Get usage and credit balance."""
+        return self._request("GET", "/v1/account/usage")

roveapi-1.0.0/src/roveapi/errors.py

@@ -0,0 +1,37 @@
+class RoveError(Exception):
+    def __init__(self, message: str, status: int, code: str, detail: str | None = None):
+        super().__init__(message)
+        self.status = status
+        self.code = code
+        self.detail = detail
+
+
+class InsufficientCreditsError(RoveError):
+    def __init__(self, detail: str | None = None):
+        super().__init__("Insufficient credits", 402, "insufficient-credits", detail)
+
+
+class SessionExpiredError(RoveError):
+    def __init__(self, detail: str | None = None):
+        super().__init__("Session expired", 410, "session-expired", detail)
+
+
+class RateLimitError(RoveError):
+    def __init__(self, retry_after: int, detail: str | None = None):
+        super().__init__("Rate limit exceeded", 429, "rate-limit-exceeded", detail)
+        self.retry_after = retry_after
+
+
+class BrowserCrashError(RoveError):
+    def __init__(self, detail: str | None = None):
+        super().__init__("Browser crash", 503, "browser-crash", detail)
+
+
+class PoolExhaustedError(RoveError):
+    def __init__(self, detail: str | None = None):
+        super().__init__("Pool exhausted", 503, "pool-exhausted", detail)
+
+
+class InvalidParamsError(RoveError):
+    def __init__(self, detail: str | None = None):
+        super().__init__("Invalid parameters", 400, "invalid-params", detail)

roveapi-1.0.0/src/roveapi/session.py

@@ -0,0 +1,92 @@
+from __future__ import annotations
+
+from typing import Any, TYPE_CHECKING
+
+if TYPE_CHECKING:
+    from .client import BrowserClient
+
+
+class Session:
+    """A persistent browser session. Use as a context manager for auto-close."""
+
+    def __init__(self, session_id: str, client: BrowserClient):
+        self.id = session_id
+        self._client = client
+
+    def __enter__(self):
+        return self
+
+    def __exit__(self, *_: Any):
+        self.close()
+
+    def _action(self, action: str, params: dict[str, Any] | None = None) -> dict[str, Any]:
+        return self._client._request("POST", "/v1/browser/action", json={
+            "session_id": self.id,
+            "action": action,
+            "params": params or {},
+        })
+
+    def navigate(self, url: str, *, wait_until: str = "networkidle", timeout_ms: int = 30000) -> dict[str, Any]:
+        return self._action("navigate", {"url": url, "wait_until": wait_until, "timeout_ms": timeout_ms})
+
+    def get_a11y_tree(self, *, include_hidden: bool = False, root_selector: str | None = None) -> dict[str, Any]:
+        params: dict[str, Any] = {"include_hidden": include_hidden}
+        if root_selector:
+            params["root_selector"] = root_selector
+        return self._action("get_a11y_tree", params)
+
+    def click(self, *, selector: str | None = None, label: str | None = None, button: str = "left") -> dict[str, Any]:
+        params: dict[str, Any] = {"button": button}
+        if selector:
+            params["selector"] = selector
+        if label:
+            params["label"] = label
+        return self._action("click", params)
+
+    def fill(self, *, selector: str | None = None, label: str | None = None, value: str, clear_first: bool = True) -> dict[str, Any]:
+        params: dict[str, Any] = {"value": value, "clear_first": clear_first}
+        if selector:
+            params["selector"] = selector
+        if label:
+            params["label"] = label
+        return self._action("fill", params)
+
+    def select(self, *, selector: str | None = None, value: str | None = None, label_text: str | None = None) -> dict[str, Any]:
+        params: dict[str, Any] = {}
+        if selector:
+            params["selector"] = selector
+        if value:
+            params["value"] = value
+        if label_text:
+            params["label_text"] = label_text
+        return self._action("select", params)
+
+    def scroll(self, *, direction: str = "down", amount: int = 500, selector: str | None = None) -> dict[str, Any]:
+        params: dict[str, Any] = {"direction": direction, "amount": amount}
+        if selector:
+            params["selector"] = selector
+        return self._action("scroll", params)
+
+    def wait_for(self, type: str, value: str, *, state: str | None = None, timeout_ms: int = 10000) -> dict[str, Any]:
+        params: dict[str, Any] = {"type": type, "value": value, "timeout_ms": timeout_ms}
+        if state:
+            params["state"] = state
+        return self._action("wait_for", params)
+
+    def screenshot(self, *, selector: str | None = None, full_page: bool = False, format: str = "png") -> dict[str, Any]:
+        params: dict[str, Any] = {"full_page": full_page, "format": format}
+        if selector:
+            params["selector"] = selector
+        return self._action("screenshot", params)
+
+    def get_text(self, selector: str, *, trim: bool = True) -> dict[str, Any]:
+        return self._action("get_text", {"selector": selector, "trim": trim})
+
+    def get_attribute(self, selector: str, attribute: str) -> dict[str, Any]:
+        return self._action("get_attribute", {"selector": selector, "attribute": attribute})
+
+    def evaluate(self, expression: str) -> dict[str, Any]:
+        return self._action("evaluate", {"expression": expression})
+
+    def close(self) -> dict[str, Any]:
+        return self._action("close_session")