oculr 0.1.0__tar.gz

oculr-0.1.0/.gitignore

@@ -0,0 +1,5 @@
+node_modules/
+dist/
+__pycache__/
+*.egg-info/
+.DS_Store

oculr-0.1.0/PKG-INFO

@@ -0,0 +1,68 @@
+Metadata-Version: 2.4
+Name: oculr
+Version: 0.1.0
+Summary: Client for the Oculr local Automation API: launch real browser profiles, pick a per-launch stealth level, and connect over CDP.
+Project-URL: Homepage, https://oculr.ai
+Project-URL: Documentation, https://oculr.ai/developers
+Project-URL: Repository, https://github.com/oculr-ai/oculr-sdk
+License: MIT
+Keywords: ai-agent,ai-agents,anti-detect,antidetect,antidetect-browser,automation,browser,browser-automation,cdp,fingerprint,mcp,model-context-protocol,oculr,playwright,puppeteer,stealth
+Requires-Python: >=3.9
+Provides-Extra: playwright
+Requires-Dist: playwright; extra == 'playwright'
+Description-Content-Type: text/markdown
+
+# oculr (Python)
+
+Thin Python client for the **Oculr local Automation API**. Launch real browser
+profiles on your own machine, choose a per-launch stealth level, and connect over
+CDP with Playwright or Selenium.
+
+Zero runtime dependencies (stdlib only). Playwright is optional, for the
+`connect_playwright()` helper.
+
+## Install
+
+```bash
+pip install oculr
+# optional, for connect_playwright():
+pip install playwright
+```
+
+## Usage
+
+```python
+import os
+from oculr import OculrClient
+from playwright.sync_api import sync_playwright
+
+# The desktop app shows the port and token under Settings.
+oculr = OculrClient("http://127.0.0.1:8378", token=os.environ["OCULR_TOKEN"])
+
+# Low-level: launch and get a ready CDP endpoint + driver recipes.
+res = oculr.launch("de-store-01", stealth="balanced", headless=False)
+print(res["ws_endpoint"])
+
+# High-level: launch and connect a Playwright browser in one call.
+with sync_playwright() as p:
+    browser, _ = oculr.connect_playwright(p, "de-store-01", stealth="max")
+    page = browser.contexts[0].pages[0]
+    page.goto("https://example.com")
+    oculr.stop("de-store-01")
+```
+
+### Stealth dial
+
+`stealth` is chosen per launch: `"off"` (clean Chromium, no fingerprint
+injection), `"balanced"` (native fingerprints, the default) or `"max"` (strongest
+noise). Overrides apply to that launch only and are never written back to the
+profile.
+
+## API
+
+`list_profiles()`, `create_profile(**body)`, `get_profile(id)`,
+`update_profile(id, **body)`, `delete_profile(id)`, `generate_profile(**body)`,
+`launch(id, **options)`, `stop(id)`, `status()`,
+`connect_playwright(playwright, id, **options)`.
+
+Errors raise `OculrError` with `.status` and `.body`.

oculr-0.1.0/README.md

@@ -0,0 +1,54 @@
+# oculr (Python)
+
+Thin Python client for the **Oculr local Automation API**. Launch real browser
+profiles on your own machine, choose a per-launch stealth level, and connect over
+CDP with Playwright or Selenium.
+
+Zero runtime dependencies (stdlib only). Playwright is optional, for the
+`connect_playwright()` helper.
+
+## Install
+
+```bash
+pip install oculr
+# optional, for connect_playwright():
+pip install playwright
+```
+
+## Usage
+
+```python
+import os
+from oculr import OculrClient
+from playwright.sync_api import sync_playwright
+
+# The desktop app shows the port and token under Settings.
+oculr = OculrClient("http://127.0.0.1:8378", token=os.environ["OCULR_TOKEN"])
+
+# Low-level: launch and get a ready CDP endpoint + driver recipes.
+res = oculr.launch("de-store-01", stealth="balanced", headless=False)
+print(res["ws_endpoint"])
+
+# High-level: launch and connect a Playwright browser in one call.
+with sync_playwright() as p:
+    browser, _ = oculr.connect_playwright(p, "de-store-01", stealth="max")
+    page = browser.contexts[0].pages[0]
+    page.goto("https://example.com")
+    oculr.stop("de-store-01")
+```
+
+### Stealth dial
+
+`stealth` is chosen per launch: `"off"` (clean Chromium, no fingerprint
+injection), `"balanced"` (native fingerprints, the default) or `"max"` (strongest
+noise). Overrides apply to that launch only and are never written back to the
+profile.
+
+## API
+
+`list_profiles()`, `create_profile(**body)`, `get_profile(id)`,
+`update_profile(id, **body)`, `delete_profile(id)`, `generate_profile(**body)`,
+`launch(id, **options)`, `stop(id)`, `status()`,
+`connect_playwright(playwright, id, **options)`.
+
+Errors raise `OculrError` with `.status` and `.body`.

oculr-0.1.0/pyproject.toml

@@ -0,0 +1,24 @@
+[build-system]
+requires = ["hatchling"]
+build-backend = "hatchling.build"
+
+[project]
+name = "oculr"
+version = "0.1.0"
+description = "Client for the Oculr local Automation API: launch real browser profiles, pick a per-launch stealth level, and connect over CDP."
+readme = "README.md"
+requires-python = ">=3.9"
+license = { text = "MIT" }
+keywords = ["oculr", "browser", "automation", "browser-automation", "antidetect", "anti-detect", "antidetect-browser", "fingerprint", "stealth", "playwright", "puppeteer", "cdp", "mcp", "model-context-protocol", "ai-agent", "ai-agents"]
+dependencies = []
+
+[project.urls]
+Homepage = "https://oculr.ai"
+Documentation = "https://oculr.ai/developers"
+Repository = "https://github.com/oculr-ai/oculr-sdk"
+
+[project.optional-dependencies]
+playwright = ["playwright"]
+
+[tool.hatch.build.targets.wheel]
+packages = ["src/oculr"]

oculr-0.1.0/src/oculr/__init__.py

@@ -0,0 +1,145 @@
+"""oculr — a thin client for the Oculr local Automation API.
+
+Zero runtime dependencies (stdlib ``urllib``). Point it at your local agent (the
+desktop app shows the port and token under Settings) and you get a ready CDP
+endpoint back, which any driver can attach to.
+
+    from oculr import OculrClient
+    from playwright.sync_api import sync_playwright
+
+    oculr = OculrClient.from_agent_file()  # auto-discovers base_url + token
+    res = oculr.launch("de-store-01", stealth="balanced", headless=False)
+
+    with sync_playwright() as p:
+        browser, _ = oculr.connect_playwright(p, "de-store-01", stealth="max")
+        page = browser.contexts[0].pages[0]
+        page.goto("https://example.com")
+"""
+
+from __future__ import annotations
+
+import json
+import os
+import urllib.error
+import urllib.request
+from typing import Any, Optional
+
+__all__ = ["OculrClient", "OculrError"]
+__version__ = "0.1.0"
+
+
+class OculrError(Exception):
+    """Raised on a non-2xx response from the Oculr API."""
+
+    def __init__(self, status: int, body: Any, message: str) -> None:
+        super().__init__(message)
+        self.status = status
+        self.body = body
+
+
+class OculrClient:
+    """Client for the Oculr local Automation API.
+
+    :param base_url: Base URL of the local agent, e.g. ``http://127.0.0.1:8765``.
+    :param token: Bearer token from the desktop app Settings (omit if auth is off).
+    """
+
+    def __init__(self, base_url: str, token: Optional[str] = None, timeout: float = 30.0) -> None:
+        if not base_url:
+            raise ValueError("OculrClient: base_url is required")
+        self.base_url = base_url.rstrip("/")
+        self.token = token
+        self.timeout = timeout
+
+    @classmethod
+    def from_agent_file(cls, path: Optional[str] = None, timeout: float = 30.0) -> "OculrClient":
+        """Build a client from the running agent's 0600 runtime descriptor.
+
+        The desktop app (and ``oculr-agent serve``) writes an ``agent.json`` with
+        the agent's ``base_url`` and — when token publishing is on — its auth
+        ``token``, so you don't have to copy them from Settings. Searches
+        ``$OCULR_RUNTIME_FILE``, then ``$OCULR_DATA_DIR/agent.json``, then
+        ``~/.oculr/data/agent.json``. Raises :class:`OculrError` if none is found.
+        """
+        candidates = []
+        if path:
+            candidates.append(path)
+        if os.environ.get("OCULR_RUNTIME_FILE"):
+            candidates.append(os.environ["OCULR_RUNTIME_FILE"])
+        if os.environ.get("OCULR_DATA_DIR"):
+            candidates.append(os.path.join(os.environ["OCULR_DATA_DIR"], "agent.json"))
+        candidates.append(os.path.expanduser("~/.oculr/data/agent.json"))
+        for candidate in candidates:
+            try:
+                with open(candidate, encoding="utf-8") as fh:
+                    desc = json.load(fh)
+            except (OSError, ValueError):
+                continue
+            base = desc.get("base_url")
+            if base:
+                return cls(base, token=desc.get("token"), timeout=timeout)
+        raise OculrError(0, None, "no Oculr agent descriptor found (is the app running?)")
+
+    def _request(self, method: str, path: str, body: Any = None) -> Any:
+        data = json.dumps(body).encode() if body is not None else None
+        req = urllib.request.Request(self.base_url + path, data=data, method=method)
+        req.add_header("Content-Type", "application/json")
+        if self.token:
+            req.add_header("Authorization", f"Bearer {self.token}")
+        try:
+            with urllib.request.urlopen(req, timeout=self.timeout) as resp:
+                text = resp.read().decode()
+                return json.loads(text) if text else None
+        except urllib.error.HTTPError as e:  # pragma: no cover - exercised via mock
+            text = e.read().decode()
+            parsed = json.loads(text) if text else None
+            raise OculrError(e.code, parsed, f"Oculr {method} {path} failed: {e.code}") from None
+
+    # ── Profiles ────────────────────────────────────────────────────────────
+    def list_profiles(self) -> Any:
+        return self._request("GET", "/api/profiles")
+
+    def create_profile(self, **body: Any) -> Any:
+        return self._request("POST", "/api/profiles", body)
+
+    def get_profile(self, profile_id: str) -> Any:
+        return self._request("GET", f"/api/profiles/{profile_id}")
+
+    def update_profile(self, profile_id: str, **body: Any) -> Any:
+        return self._request("PUT", f"/api/profiles/{profile_id}", body)
+
+    def delete_profile(self, profile_id: str) -> Any:
+        return self._request("DELETE", f"/api/profiles/{profile_id}")
+
+    def generate_profile(self, **body: Any) -> Any:
+        """Generate a coherent random fingerprint."""
+        return self._request("POST", "/api/profiles/generate", body or {})
+
+    # ── Lifecycle ───────────────────────────────────────────────────────────
+    def launch(self, profile_id: str, **options: Any) -> Any:
+        """Launch a profile. With no options the stored profile defaults are used.
+
+        Options (all per-launch, never written back): ``stealth`` ("off" |
+        "balanced" | "max"), ``headless``, ``proxy``, ``args``, ``window``,
+        ``automation``, ``ephemeral``.
+        """
+        return self._request("POST", f"/api/profiles/{profile_id}/launch", options or None)
+
+    def stop(self, profile_id: str) -> Any:
+        return self._request("POST", f"/api/profiles/{profile_id}/stop")
+
+    def status(self) -> Any:
+        return self._request("GET", "/api/status")
+
+    # ── High-level ──────────────────────────────────────────────────────────
+    def connect_playwright(self, playwright: Any, profile_id: str, **options: Any):
+        """Launch a profile and connect a Playwright browser over CDP.
+
+        Pass the value from ``sync_playwright()``. Returns ``(browser, response)``.
+        """
+        res = self.launch(profile_id, **options)
+        ws = (res or {}).get("ws_endpoint")
+        if not ws:
+            raise OculrError(0, res, "launch did not return a ws_endpoint")
+        browser = playwright.chromium.connect_over_cdp(ws)
+        return browser, res

oculr-0.1.0/tests/test_client.py

@@ -0,0 +1,76 @@
+import json
+
+import urllib.error
+import urllib.request
+
+import pytest
+
+from oculr import OculrClient, OculrError
+
+
+class _FakeResp:
+    def __init__(self, text: str):
+        self._t = text
+
+    def read(self):
+        return self._t.encode()
+
+    def __enter__(self):
+        return self
+
+    def __exit__(self, *a):
+        return False
+
+
+def test_launch_posts_options_and_parses(monkeypatch):
+    captured = {}
+
+    def fake_urlopen(req, timeout=None):
+        captured["req"] = req
+        return _FakeResp(json.dumps({
+            "profile_id": "p1",
+            "status": "running",
+            "ws_endpoint": "ws://127.0.0.1:8378/api/profiles/p1/cdp",
+        }))
+
+    monkeypatch.setattr(urllib.request, "urlopen", fake_urlopen)
+    client = OculrClient("http://127.0.0.1:8378/", token="tok")
+    res = client.launch("p1", stealth="max", headless=True)
+
+    assert res["ws_endpoint"].endswith("/cdp")
+    req = captured["req"]
+    assert req.full_url == "http://127.0.0.1:8378/api/profiles/p1/launch"
+    assert req.get_method() == "POST"
+    assert req.headers["Authorization"] == "Bearer tok"
+    assert json.loads(req.data.decode()) == {"stealth": "max", "headless": True}
+
+
+def test_launch_without_options_sends_no_body(monkeypatch):
+    captured = {}
+
+    def fake_urlopen(req, timeout=None):
+        captured["req"] = req
+        return _FakeResp(json.dumps({"profile_id": "p1", "status": "running"}))
+
+    monkeypatch.setattr(urllib.request, "urlopen", fake_urlopen)
+    client = OculrClient("http://127.0.0.1:8378")
+    client.launch("p1")
+    assert captured["req"].data is None
+
+
+def test_http_error_raises_oculr_error(monkeypatch):
+    def fake_urlopen(req, timeout=None):
+        raise urllib.error.HTTPError(req.full_url, 404, "Not Found", {}, _io_bytes(b'{"detail":"nope"}'))
+
+    monkeypatch.setattr(urllib.request, "urlopen", fake_urlopen)
+    client = OculrClient("http://127.0.0.1:8378")
+    with pytest.raises(OculrError) as ei:
+        client.get_profile("nope")
+    assert ei.value.status == 404
+    assert ei.value.body == {"detail": "nope"}
+
+
+def _io_bytes(b: bytes):
+    import io
+
+    return io.BytesIO(b)