browsercli 1.0.0__py3-none-any.whl

browsercli/__init__.py

@@ -0,0 +1,26 @@
+"""browsercli Python client — zero-dependency wrapper for the Unix socket RPC API."""
+
+from browsercli.client import BrowserCLI
+from browsercli.exceptions import (
+    BrowserCLIError,
+    AuthenticationError,
+    BadRequestError,
+    ConnectionError,
+    NotFoundError,
+    RPCError,
+    ServerError,
+    SessionError,
+)
+
+__all__ = [
+    "BrowserCLI",
+    "BrowserCLIError",
+    "AuthenticationError",
+    "BadRequestError",
+    "ConnectionError",
+    "NotFoundError",
+    "RPCError",
+    "ServerError",
+    "SessionError",
+]
+__version__ = "0.4.0"

browsercli/client.py

@@ -0,0 +1,630 @@
+"""Core client that talks to the browsercli daemon over its RPC API.
+
+On macOS/Linux the daemon listens on a Unix socket; on Windows it uses
+TCP localhost.  The transport is chosen automatically based on the session
+file contents.
+"""
+
+from __future__ import annotations
+
+import base64
+import http.client
+import json
+import logging
+import os
+import socket
+import sys
+from pathlib import Path
+from typing import Any, Dict, List, Optional, Union
+
+from browsercli.exceptions import (
+    BrowserCLIError,
+    AuthenticationError,
+    BadRequestError,
+    ConnectionError,
+    NotFoundError,
+    RPCError,
+    ServerError,
+    SessionError,
+)
+
+logger = logging.getLogger("browsercli")
+
+# Valid values for dom_query / dom_all ``mode`` parameter.
+DOM_MODES = frozenset({"outer_html", "text"})
+
+# Valid values for dom_wait ``state`` parameter.
+WAIT_STATES = frozenset({"visible", "hidden", "attached", "detached"})
+
+# Valid values for console ``level`` filter.
+CONSOLE_LEVELS = frozenset({"", "log", "warn", "error", "info"})
+
+
+class _UnixHTTPConnection(http.client.HTTPConnection):
+    """HTTPConnection subclass that connects to a Unix domain socket."""
+
+    def __init__(self, socket_path: str, timeout: float = 30.0) -> None:
+        # host is unused but required by HTTPConnection
+        super().__init__("localhost", timeout=timeout)
+        self._socket_path = socket_path
+
+    def connect(self) -> None:
+        self.sock = socket.socket(socket.AF_UNIX, socket.SOCK_STREAM)
+        self.sock.settimeout(self.timeout)
+        self.sock.connect(self._socket_path)
+
+
+class BrowserCLI:
+    """Client for a running browsercli daemon.
+
+    Usage::
+
+        from browsercli import BrowserCLI
+
+        ac = BrowserCLI.connect()       # reads ~/.browsercli/session.json
+        print(ac.status())
+        ac.goto("/")
+        text = ac.dom_query("h1", mode="text")
+        ac.stop()
+
+    All methods are synchronous and block until the daemon responds.
+    """
+
+    def __init__(
+        self,
+        socket_path: str = "",
+        token: str = "",
+        timeout: float = 30.0,
+        *,
+        rpc_port: int = 0,
+    ) -> None:
+        if not socket_path and not rpc_port:
+            raise ValueError("must provide either socket_path or rpc_port")
+        if not token:
+            raise ValueError("token must be a non-empty string")
+        if timeout <= 0:
+            raise ValueError("timeout must be positive")
+        self._socket_path = socket_path
+        self._rpc_port = rpc_port
+        self._token = token
+        self._timeout = timeout
+
+    # ------------------------------------------------------------------
+    # Factory
+    # ------------------------------------------------------------------
+
+    @classmethod
+    def connect(
+        cls,
+        session_path: Optional[str] = None,
+        timeout: float = 30.0,
+    ) -> BrowserCLI:
+        """Create a client by reading the daemon's session file.
+
+        Args:
+            session_path: Explicit path to ``session.json``.  Defaults to
+                ``~/.browsercli/session.json`` on macOS/Linux, or
+                ``%LOCALAPPDATA%\\browsercli\\session.json`` on Windows.
+            timeout: Socket timeout in seconds (must be positive).
+
+        Returns:
+            A connected :class:`BrowserCLI` instance.
+
+        Raises:
+            SessionError: If the session file is missing, unreadable, or
+                contains invalid data.
+        """
+        if session_path is None:
+            if sys.platform == "win32":
+                app_data = os.environ.get("LOCALAPPDATA", str(Path.home()))
+                session_path = str(
+                    Path(app_data) / "browsercli" / "session.json"
+                )
+            else:
+                session_path = str(
+                    Path.home() / ".browsercli" / "session.json"
+                )
+
+        try:
+            with open(session_path) as f:
+                sess = json.load(f)
+        except FileNotFoundError:
+            raise SessionError(
+                f"Session file not found: {session_path} — "
+                "is the daemon running? (browsercli start)"
+            )
+        except (json.JSONDecodeError, OSError) as exc:
+            raise SessionError(
+                f"Cannot read session file {session_path}: {exc}"
+            ) from exc
+
+        if not isinstance(sess, dict):
+            raise SessionError(
+                f"Session file {session_path} does not contain a JSON object"
+            )
+
+        socket_path_val = sess.get("socket_path", "")
+        rpc_port_val = sess.get("rpc_port", 0)
+        token = sess.get("token", "")
+        if not token:
+            raise SessionError(
+                "session.json is missing token; is the daemon running?"
+            )
+        if not socket_path_val and not rpc_port_val:
+            raise SessionError(
+                "session.json is missing socket_path and rpc_port; "
+                "is the daemon running?"
+            )
+        return cls(
+            socket_path_val,
+            token,
+            timeout=timeout,
+            rpc_port=rpc_port_val,
+        )
+
+    # ------------------------------------------------------------------
+    # Low-level RPC
+    # ------------------------------------------------------------------
+
+    def _request(
+        self,
+        method: str,
+        path: str,
+        body: Optional[Dict[str, Any]] = None,
+    ) -> Any:
+        """Send an RPC request and return the parsed JSON response.
+
+        Raises:
+            ConnectionError: Socket connection failed.
+            AuthenticationError: HTTP 401 (token rejected).
+            BadRequestError: HTTP 400 (malformed request).
+            NotFoundError: HTTP 404 (unknown endpoint or element).
+            ServerError: HTTP 5xx (daemon internal error).
+            RPCError: Any other non-2xx status.
+        """
+        logger.debug("RPC %s %s body=%s", method, path, body)
+
+        try:
+            if self._socket_path:
+                conn = _UnixHTTPConnection(
+                    self._socket_path, timeout=self._timeout
+                )
+            else:
+                conn = http.client.HTTPConnection(
+                    "127.0.0.1", port=self._rpc_port, timeout=self._timeout
+                )
+        except OSError as exc:
+            addr_desc = self._socket_path or f"127.0.0.1:{self._rpc_port}"
+            raise ConnectionError(
+                f"Cannot create connection to {addr_desc}: {exc}"
+            ) from exc
+
+        try:
+            headers = {
+                "Authorization": f"Bearer {self._token}",
+                "Content-Type": "application/json",
+            }
+            payload = json.dumps(body).encode() if body else b""
+
+            try:
+                conn.request(method, path, body=payload, headers=headers)
+                resp = conn.getresponse()
+            except (OSError, socket.timeout) as exc:
+                addr_desc = self._socket_path or f"127.0.0.1:{self._rpc_port}"
+                raise ConnectionError(
+                    f"Failed to communicate with daemon at "
+                    f"{addr_desc}: {exc}"
+                ) from exc
+
+            raw_data = resp.read().decode("utf-8", errors="replace")
+            status = resp.status
+
+            logger.debug("RPC response status=%d body=%s", status, raw_data[:200])
+
+            if status == 401:
+                raise AuthenticationError(
+                    "Daemon rejected the bearer token. "
+                    "The daemon may have restarted — try BrowserCLI.connect() again."
+                )
+
+            if status >= 400:
+                # Try to extract the structured error message.
+                error_msg = raw_data.strip()
+                try:
+                    error_json = json.loads(raw_data)
+                    if isinstance(error_json, dict) and "error" in error_json:
+                        error_msg = error_json["error"]
+                except (json.JSONDecodeError, ValueError):
+                    pass  # Use raw_data as-is
+
+                if status == 400:
+                    raise BadRequestError(error_msg)
+                elif status == 404:
+                    raise NotFoundError(error_msg)
+                elif status >= 500:
+                    raise ServerError(status, error_msg)
+                else:
+                    raise RPCError(status, error_msg)
+
+            # Success: parse JSON.
+            if not raw_data.strip():
+                return {}
+            try:
+                return json.loads(raw_data)
+            except json.JSONDecodeError as exc:
+                raise RPCError(
+                    status,
+                    f"Daemon returned invalid JSON (HTTP {status}): {exc}",
+                ) from exc
+        finally:
+            conn.close()
+
+    # ------------------------------------------------------------------
+    # High-level API
+    # ------------------------------------------------------------------
+
+    def status(self) -> Dict[str, Any]:
+        """Return daemon and browser status.
+
+        Response keys include ``running``, ``browser_alive``, ``pid``,
+        ``dir``, ``http_addr``, ``http_port``, ``current_url``, ``title``,
+        ``headless``, ``browser_pid``, ``devtools_port``, ``browser_bin``.
+        """
+        return self._request("GET", "/status")
+
+    def version(self) -> Dict[str, Any]:
+        """Return RPC and schema version info.
+
+        Response keys: ``rpc_version``, ``schema_version``.
+        """
+        return self._request("GET", "/version")
+
+    def goto(self, url: str) -> Dict[str, Any]:
+        """Navigate the browser to *url* (path or full URL).
+
+        Args:
+            url: Absolute URL (``http://...``) or path (``/page``).
+                Paths are resolved relative to the daemon's serve directory.
+
+        Returns:
+            Dict with ``url`` (final URL after navigation) and ``title``.
+        """
+        if not isinstance(url, str):
+            raise TypeError(f"url must be a string, got {type(url).__name__}")
+        return self._request("POST", "/goto", {"url": url})
+
+    def eval(self, expression: str) -> Any:
+        """Evaluate a JavaScript expression and return the result value.
+
+        Args:
+            expression: JavaScript code to evaluate in the page context.
+
+        Returns:
+            The evaluated result (any JSON-serializable type, or None).
+        """
+        if not isinstance(expression, str) or not expression.strip():
+            raise ValueError("expression must be a non-empty string")
+        resp = self._request("POST", "/eval", {"expression": expression})
+        return resp.get("value")
+
+    def reload(self) -> bool:
+        """Reload the current page.
+
+        Returns:
+            True on success.
+        """
+        resp = self._request("POST", "/reload")
+        return resp.get("ok", False)
+
+    def dom_query(
+        self,
+        selector: str,
+        mode: str = "outer_html",
+    ) -> str:
+        """Query a single DOM element and return its content.
+
+        Args:
+            selector: CSS selector string.
+            mode: ``"outer_html"`` (default) or ``"text"``.
+
+        Returns:
+            The element content as a string.
+
+        Raises:
+            ValueError: If *mode* is not a recognized value.
+        """
+        if not isinstance(selector, str) or not selector.strip():
+            raise ValueError("selector must be a non-empty string")
+        if mode not in DOM_MODES:
+            raise ValueError(
+                f"mode must be one of {sorted(DOM_MODES)}, got {mode!r}"
+            )
+        resp = self._request(
+            "POST", "/dom", {"selector": selector, "mode": mode}
+        )
+        return resp.get("value", "")
+
+    def dom_all(
+        self,
+        selector: str,
+        mode: str = "outer_html",
+    ) -> List[str]:
+        """Query all matching DOM elements.
+
+        Args:
+            selector: CSS selector string.
+            mode: ``"outer_html"`` (default) or ``"text"``.
+
+        Returns:
+            List of content strings for each matching element.
+
+        Raises:
+            ValueError: If *mode* is not a recognized value.
+        """
+        if not isinstance(selector, str) or not selector.strip():
+            raise ValueError("selector must be a non-empty string")
+        if mode not in DOM_MODES:
+            raise ValueError(
+                f"mode must be one of {sorted(DOM_MODES)}, got {mode!r}"
+            )
+        resp = self._request(
+            "POST", "/dom/all", {"selector": selector, "mode": mode}
+        )
+        return resp.get("values", [])
+
+    def dom_attr(self, selector: str, name: str) -> Optional[str]:
+        """Get an attribute value from an element.
+
+        Args:
+            selector: CSS selector for the target element.
+            name: Attribute name (e.g. ``"href"``, ``"class"``).
+
+        Returns:
+            Attribute value, or ``None`` if the attribute doesn't exist.
+        """
+        if not isinstance(selector, str) or not selector.strip():
+            raise ValueError("selector must be a non-empty string")
+        if not isinstance(name, str) or not name.strip():
+            raise ValueError("name must be a non-empty string")
+        resp = self._request(
+            "POST", "/dom/attr", {"selector": selector, "name": name}
+        )
+        return resp.get("value")
+
+    def dom_click(self, selector: str) -> bool:
+        """Click an element.
+
+        Args:
+            selector: CSS selector for the element to click.
+
+        Returns:
+            True on success.
+        """
+        if not isinstance(selector, str) or not selector.strip():
+            raise ValueError("selector must be a non-empty string")
+        resp = self._request(
+            "POST", "/dom/click", {"selector": selector}
+        )
+        return resp.get("ok", False)
+
+    def dom_type(
+        self,
+        selector: str,
+        text: str,
+        clear: bool = False,
+    ) -> bool:
+        """Type text into an input element.
+
+        Args:
+            selector: CSS selector for the input element.
+            text: Text to type.
+            clear: If True, clear the field before typing.
+
+        Returns:
+            True on success.
+        """
+        if not isinstance(selector, str) or not selector.strip():
+            raise ValueError("selector must be a non-empty string")
+        if not isinstance(text, str):
+            raise TypeError(f"text must be a string, got {type(text).__name__}")
+        resp = self._request(
+            "POST",
+            "/dom/type",
+            {"selector": selector, "text": text, "clear": clear},
+        )
+        return resp.get("ok", False)
+
+    def dom_wait(
+        self,
+        selector: str,
+        state: str = "visible",
+        timeout_ms: int = 10000,
+    ) -> bool:
+        """Wait for an element to reach a given state.
+
+        Args:
+            selector: CSS selector for the target element.
+            state: ``"visible"`` (default), ``"hidden"``, ``"attached"``,
+                or ``"detached"``.
+            timeout_ms: Maximum wait time in milliseconds (default 10000).
+
+        Returns:
+            True if the element reached the desired state.
+
+        Raises:
+            ValueError: If *state* is not a recognized value.
+        """
+        if not isinstance(selector, str) or not selector.strip():
+            raise ValueError("selector must be a non-empty string")
+        if state not in WAIT_STATES:
+            raise ValueError(
+                f"state must be one of {sorted(WAIT_STATES)}, got {state!r}"
+            )
+        if not isinstance(timeout_ms, int) or timeout_ms <= 0:
+            raise ValueError("timeout_ms must be a positive integer")
+        resp = self._request(
+            "POST",
+            "/dom/wait",
+            {
+                "selector": selector,
+                "state": state,
+                "timeout_ms": timeout_ms,
+            },
+        )
+        return resp.get("ok", False)
+
+    def screenshot(
+        self,
+        selector: str = "",
+        out: Optional[Union[str, Path]] = None,
+    ) -> bytes:
+        """Take a screenshot.  Returns raw PNG bytes.
+
+        Args:
+            selector: Optional CSS selector to screenshot a specific element.
+                Empty string (default) captures the full page.
+            out: If given, the PNG is also written to this file path.
+
+        Returns:
+            Raw PNG image bytes.
+        """
+        if not isinstance(selector, str):
+            raise TypeError(f"selector must be a string, got {type(selector).__name__}")
+        resp = self._request(
+            "POST",
+            "/screenshot",
+            {"selector": selector, "format": "png"},
+        )
+        b64_data = resp.get("base64", "")
+        if not b64_data:
+            return b""
+        raw = base64.b64decode(b64_data)
+        if out:
+            Path(out).write_bytes(raw)
+        return raw
+
+    def console(
+        self,
+        level: str = "",
+        limit: int = 0,
+        clear: bool = False,
+    ) -> List[Dict[str, Any]]:
+        """Fetch console entries.
+
+        Args:
+            level: Filter by level: ``"log"``, ``"warn"``, ``"error"``,
+                ``"info"``, or ``""`` (all).
+            limit: Maximum number of entries to return (0 = unlimited).
+            clear: If True, drain (delete) entries after reading.
+
+        Returns:
+            List of dicts with keys ``level``, ``text``, ``timestamp``.
+
+        Raises:
+            ValueError: If *level* is not a recognized value.
+        """
+        if level not in CONSOLE_LEVELS:
+            raise ValueError(
+                f"level must be one of {sorted(CONSOLE_LEVELS)}, got {level!r}"
+            )
+        if not isinstance(limit, int) or limit < 0:
+            raise ValueError("limit must be a non-negative integer")
+        resp = self._request(
+            "POST",
+            "/console",
+            {"level": level, "limit": limit, "clear": clear},
+        )
+        return resp.get("entries", [])
+
+    def network(
+        self,
+        limit: int = 0,
+        clear: bool = False,
+    ) -> List[Dict[str, Any]]:
+        """Fetch network log entries.
+
+        Args:
+            limit: Maximum number of entries to return (0 = unlimited).
+            clear: If True, drain (delete) entries after reading.
+
+        Returns:
+            List of dicts with keys ``method``, ``url``, ``status``,
+            ``resource_type``, ``mime_type``, ``size``, ``duration_ms``,
+            ``timestamp``.
+        """
+        if not isinstance(limit, int) or limit < 0:
+            raise ValueError("limit must be a non-negative integer")
+        resp = self._request(
+            "POST",
+            "/network",
+            {"limit": limit, "clear": clear},
+        )
+        return resp.get("entries", [])
+
+    def perf(self) -> Dict[str, float]:
+        """Return page performance metrics.
+
+        Returns:
+            Dict with ``dom_content_loaded_ms`` and ``load_event_ms``.
+        """
+        return self._request("GET", "/perf")
+
+    def stop(self) -> bool:
+        """Stop the daemon.
+
+        Returns:
+            True on success.
+        """
+        resp = self._request("POST", "/stop")
+        return resp.get("ok", False)
+
+    def plugin_list(self) -> List[Dict[str, Any]]:
+        """List all installed plugins.
+
+        Returns:
+            List of dicts with keys ``name``, ``version``, ``description``,
+            ``templates``, ``hooks``, ``rpc_endpoints``.
+        """
+        resp = self._request("GET", "/plugins")
+        return resp.get("plugins", [])
+
+    def plugin_rpc(
+        self,
+        rpc_path: str,
+        body: Optional[Dict[str, Any]] = None,
+    ) -> Any:
+        """Call a custom plugin RPC endpoint.
+
+        Args:
+            rpc_path: The endpoint path (must start with ``/x/``).
+            body: Optional JSON request body for the handler.
+
+        Returns:
+            The parsed JSON response from the plugin handler.
+
+        Raises:
+            ValueError: If *rpc_path* doesn't start with ``/x/``.
+        """
+        if not isinstance(rpc_path, str) or not rpc_path.startswith("/x/"):
+            raise ValueError(
+                f"rpc_path must be a string starting with '/x/', got {rpc_path!r}"
+            )
+        return self._request("POST", rpc_path, body)
+
+    # ------------------------------------------------------------------
+    # Context manager
+    # ------------------------------------------------------------------
+
+    def __enter__(self) -> BrowserCLI:
+        return self
+
+    def __exit__(self, *exc: Any) -> None:
+        pass  # does NOT auto-stop; caller decides
+
+    # ------------------------------------------------------------------
+    # repr
+    # ------------------------------------------------------------------
+
+    def __repr__(self) -> str:
+        addr = self._socket_path or f"127.0.0.1:{self._rpc_port}"
+        return f"BrowserCLI(addr={addr!r}, timeout={self._timeout})"

browsercli/exceptions.py

@@ -0,0 +1,69 @@
+"""Exception hierarchy for the browsercli Python client.
+
+All public exceptions inherit from :class:`BrowserCLIError` so callers
+can catch the whole family with a single ``except BrowserCLIError``.
+"""
+
+from __future__ import annotations
+
+
+class BrowserCLIError(Exception):
+    """Base exception for all browsercli client errors."""
+
+
+class ConnectionError(BrowserCLIError):
+    """The client could not connect to the daemon Unix socket.
+
+    Common causes:
+    - The daemon is not running (``browsercli start`` not called).
+    - The socket file was deleted or has wrong permissions.
+    - The session file points to a stale socket.
+    """
+
+
+class AuthenticationError(BrowserCLIError):
+    """The daemon rejected the bearer token (HTTP 401).
+
+    Common causes:
+    - The daemon was restarted and generated a new token.
+    - The session file is stale.  Re-read it with ``BrowserCLI.connect()``.
+    """
+
+
+class RPCError(BrowserCLIError):
+    """The daemon returned an HTTP error with a JSON ``{"error": "..."}`` body.
+
+    Attributes:
+        status_code: HTTP status code (e.g. 400, 404, 500).
+        error_message: Human-readable error message from the daemon.
+    """
+
+    def __init__(self, status_code: int, error_message: str) -> None:
+        self.status_code = status_code
+        self.error_message = error_message
+        super().__init__(f"RPC error {status_code}: {error_message}")
+
+
+class BadRequestError(RPCError):
+    """The daemon returned HTTP 400 — the request body was malformed."""
+
+    def __init__(self, error_message: str) -> None:
+        super().__init__(400, error_message)
+
+
+class NotFoundError(RPCError):
+    """The daemon returned HTTP 404 — unknown endpoint or missing element."""
+
+    def __init__(self, error_message: str) -> None:
+        super().__init__(404, error_message)
+
+
+class ServerError(RPCError):
+    """The daemon returned HTTP 5xx — an internal error occurred."""
+
+    def __init__(self, status_code: int, error_message: str) -> None:
+        super().__init__(status_code, error_message)
+
+
+class SessionError(BrowserCLIError):
+    """The session file is missing, unreadable, or has invalid content."""

browsercli-1.0.0.dist-info/METADATA

@@ -0,0 +1,191 @@
+Metadata-Version: 2.4
+Name: browsercli
+Version: 1.0.0
+Summary: Python client for the browsercli browser workspace daemon
+License: MIT
+Project-URL: Homepage, https://github.com/justinhuangcode/browsercli
+Project-URL: Repository, https://github.com/justinhuangcode/browsercli
+Project-URL: Documentation, https://github.com/justinhuangcode/browsercli#readme
+Project-URL: Bug Reports, https://github.com/justinhuangcode/browsercli/issues
+Keywords: browser,automation,rpc,cdp,devtools
+Classifier: Development Status :: 5 - Production/Stable
+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 :: Software Development :: Testing
+Classifier: Typing :: Typed
+Requires-Python: >=3.9
+Description-Content-Type: text/markdown
+
+# browsercli Python Client
+
+Zero-dependency Python client for the [browsercli](https://github.com/justinhuangcode/browsercli) browser workspace daemon.
+
+## Installation
+
+```bash
+pip install -e clients/python   # from the repo root
+```
+
+## Platform Support
+
+The client auto-detects the RPC transport from the session file:
+
+- **macOS / Linux** — connects via Unix socket (`socket_path` in session.json)
+- **Windows** — connects via TCP localhost (`rpc_port` in session.json)
+
+No code changes are needed — `BrowserCLI.connect()` handles both transports.
+
+## Quick Start
+
+```python
+from browsercli import BrowserCLI
+
+# Connect to a running daemon
+# macOS/Linux: reads ~/.browsercli/session.json
+# Windows: reads %LOCALAPPDATA%\browsercli\session.json
+ac = BrowserCLI.connect()
+
+# Navigate and inspect
+ac.goto("/")
+title = ac.dom_query("h1", mode="text")
+print(f"Title: {title}")
+
+# Evaluate JavaScript
+result = ac.eval("1 + 1")
+print(f"Result: {result}")
+
+# Screenshot
+ac.screenshot(out="page.png")
+
+# Stop the daemon
+ac.stop()
+```
+
+## Error Handling
+
+All exceptions inherit from `BrowserCLIError`, so you can catch the whole family or handle specific cases:
+
+```python
+from browsercli import (
+    BrowserCLI,
+    BrowserCLIError,
+    ConnectionError,
+    AuthenticationError,
+    SessionError,
+    NotFoundError,
+    ServerError,
+)
+
+try:
+    ac = BrowserCLI.connect()
+    ac.dom_query("#missing-element", mode="text")
+except SessionError:
+    print("Daemon not running — start it with: browsercli start")
+except ConnectionError:
+    print("Cannot reach daemon — is the socket file valid?")
+except AuthenticationError:
+    print("Token rejected — daemon may have restarted, reconnect")
+except NotFoundError as e:
+    print(f"Element or endpoint not found: {e}")
+except ServerError as e:
+    print(f"Daemon internal error (HTTP {e.status_code}): {e.error_message}")
+except BrowserCLIError as e:
+    print(f"Unexpected client error: {e}")
+```
+
+### Exception Hierarchy
+
+```
+BrowserCLIError            # Base — catch-all
+├── SessionError            # session.json missing/invalid
+├── ConnectionError         # RPC endpoint unreachable (socket or TCP)
+├── AuthenticationError     # HTTP 401 (bad token)
+└── RPCError                # Any HTTP 4xx/5xx with status_code + error_message
+    ├── BadRequestError     # HTTP 400
+    ├── NotFoundError       # HTTP 404
+    └── ServerError         # HTTP 5xx
+```
+
+## Constructor
+
+```python
+BrowserCLI(socket_path="", token="", timeout=30.0, *, rpc_port=0)
+```
+
+| Parameter | Type | Description |
+| --- | --- | --- |
+| `socket_path` | `str` | Unix socket path (macOS/Linux). Mutually exclusive with `rpc_port`. |
+| `token` | `str` | Bearer token for daemon authentication |
+| `timeout` | `float` | Request timeout in seconds (default `30.0`) |
+| `rpc_port` | `int` | TCP port on localhost (Windows). Keyword-only. |
+
+You must provide either `socket_path` or `rpc_port`. In most cases, use the `connect()` factory instead of calling the constructor directly.
+
+## API Reference
+
+| Method | Description |
+| --- | --- |
+| `BrowserCLI.connect(session_path=None, timeout=30.0)` | Create client from session file (auto-detects Unix socket or TCP) |
+| `status()` | Daemon and browser status |
+| `version()` | RPC and schema version info |
+| `goto(url)` | Navigate to a path or URL |
+| `eval(expression)` | Evaluate JavaScript |
+| `reload()` | Reload the page |
+| `dom_query(selector, mode)` | Query a single DOM element |
+| `dom_all(selector, mode)` | Query all matching elements |
+| `dom_attr(selector, name)` | Get an element attribute |
+| `dom_click(selector)` | Click an element |
+| `dom_type(selector, text, clear)` | Type text into an input |
+| `dom_wait(selector, state, timeout_ms)` | Wait for element state |
+| `screenshot(selector, out)` | Capture screenshot (PNG bytes) |
+| `console(level, limit, clear)` | Fetch console entries |
+| `network(limit, clear)` | Fetch network log entries |
+| `perf()` | Page performance metrics |
+| `stop()` | Stop the daemon |
+| `plugin_list()` | List installed plugins |
+| `plugin_rpc(rpc_path, body=None)` | Call a custom plugin RPC endpoint (`/x/...`) |
+
+### Valid Parameter Values
+
+| Parameter | Valid Values | Default |
+| --- | --- | --- |
+| `dom_query` / `dom_all` `mode` | `"outer_html"`, `"text"` | `"outer_html"` |
+| `dom_wait` `state` | `"visible"`, `"hidden"`, `"attached"`, `"detached"` | `"visible"` |
+| `console` `level` | `""` (all), `"log"`, `"warn"`, `"error"`, `"info"` | `""` |
+
+Invalid values raise `ValueError` before any RPC call is made.
+
+## Logging
+
+The client uses Python's `logging` module under the logger name `browsercli`:
+
+```python
+import logging
+logging.basicConfig(level=logging.DEBUG)
+# Now all RPC requests and responses are logged.
+```
+
+## Running Tests
+
+```bash
+cd clients/python
+python -m unittest tests.test_client -v
+```
+
+Tests include:
+- **Session parsing**: valid/invalid/missing session files (including `rpc_port` for Windows)
+- **Parameter validation**: client-side checks for all method arguments
+- **Contract tests**: mock server (Unix socket on macOS/Linux, TCP on Windows) emulating the Rust daemon
+- **Error handling**: auth failures, 400/404/500 errors, connection errors
+- **Exception hierarchy**: inheritance and attribute verification
+
+## Requirements
+
+- Python 3.9+
+- A running `browsercli` daemon (`browsercli start`)
+- No external dependencies (stdlib only)

browsercli-1.0.0.dist-info/RECORD

@@ -0,0 +1,7 @@
+browsercli/__init__.py,sha256=C9SmYcUwetW7IXnKUz5B9fjNEzm6Ov_-sfTpuvAkD18,551
+browsercli/client.py,sha256=976D8nJ0VdKFqG12RlfSR0EiMsROKaPCOjlBqHPQ7VA,20943
+browsercli/exceptions.py,sha256=tLWFrP1gAiSEO6VwCLdZg4bqUUg8FnfxO0cUIGFPUlE,2157
+browsercli-1.0.0.dist-info/METADATA,sha256=TTtXiCe3evs8LlcWqJqatc8b48963WtrXroheAOIFe4,6472
+browsercli-1.0.0.dist-info/WHEEL,sha256=YCfwYGOYMi5Jhw2fU4yNgwErybb2IX5PEwBKV4ZbdBo,91
+browsercli-1.0.0.dist-info/top_level.txt,sha256=S0RLonnqiDdQWflgQnN_p1V5hM9f275oVDChwW2rsKg,11
+browsercli-1.0.0.dist-info/RECORD,,

browsercli-1.0.0.dist-info/WHEEL

@@ -0,0 +1,5 @@
+Wheel-Version: 1.0
+Generator: setuptools (82.0.0)
+Root-Is-Purelib: true
+Tag: py3-none-any
+

browsercli-1.0.0.dist-info/top_level.txt

@@ -0,0 +1 @@
+browsercli