oculr 0.1.0__py3-none-any.whl

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.dist-info/METADATA

@@ -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.dist-info/RECORD

@@ -0,0 +1,4 @@
+oculr/__init__.py,sha256=sggVeMW7icBNKWc1TDPRr8iwKvsXxAzsR3dCOxsq5Xg,6531
+oculr-0.1.0.dist-info/METADATA,sha256=9uvso9X_nSPb5AuDyLVmL6u8DgnGn-b93EoNgZBxUP0,2366
+oculr-0.1.0.dist-info/WHEEL,sha256=lCkmxWfQsSc9CfIClYeavTdQeEX2toPqufh9gI35EQA,87
+oculr-0.1.0.dist-info/RECORD,,

oculr-0.1.0.dist-info/WHEEL

@@ -0,0 +1,4 @@
+Wheel-Version: 1.0
+Generator: hatchling 1.31.0
+Root-Is-Purelib: true
+Tag: py3-none-any