cdp-connect-kit 0.3.1__py3-none-any.whl

cdp_connect_kit/__init__.py

@@ -0,0 +1,15 @@
+"""CDP connection toolkit with Playwright integration."""
+
+from cdp_connect_kit.cdp.client import CdpClient, CdpError
+from cdp_connect_kit.cdp.url import CdpEndpoint, parse_endpoint
+from cdp_connect_kit.connect import ConnectMetrics, connect_playwright
+
+__all__ = [
+    "CdpClient",
+    "CdpEndpoint",
+    "CdpError",
+    "ConnectMetrics",
+    "connect_playwright",
+    "parse_endpoint",
+]
+__version__ = "0.3.1"

cdp_connect_kit/cdp/__init__.py

@@ -0,0 +1,14 @@
+"""CDP HTTP discovery."""
+
+from cdp_connect_kit.cdp.client import CdpClient, CdpError
+from cdp_connect_kit.cdp.models import BrowserInfo, HealthSnapshot
+from cdp_connect_kit.cdp.url import CdpEndpoint, parse_endpoint
+
+__all__ = [
+    "BrowserInfo",
+    "CdpClient",
+    "CdpEndpoint",
+    "CdpError",
+    "HealthSnapshot",
+    "parse_endpoint",
+]

cdp_connect_kit/cdp/client.py

@@ -0,0 +1,105 @@
+"""CDP HTTP client (stdlib)."""
+
+from __future__ import annotations
+
+import json
+import time
+import urllib.error
+import urllib.request
+from typing import Any
+
+from cdp_connect_kit.cdp.models import BrowserInfo, HealthSnapshot
+from cdp_connect_kit.cdp.url import CdpEndpoint, parse_endpoint
+from cdp_connect_kit.retry import backoff_delay
+
+
+class CdpError(Exception):
+    """Raised when CDP HTTP discovery fails."""
+
+
+class CdpClient:
+    def __init__(self, endpoint: str | CdpEndpoint, *, timeout: float = 10.0) -> None:
+        self.endpoint = endpoint if isinstance(endpoint, CdpEndpoint) else parse_endpoint(endpoint)
+        self.timeout = timeout
+
+    def _fetch_json(self, url: str) -> Any:
+        request = urllib.request.Request(url, headers={"Accept": "application/json"})
+        try:
+            with urllib.request.urlopen(request, timeout=self.timeout) as response:
+                return json.loads(response.read().decode("utf-8"))
+        except (urllib.error.URLError, OSError) as exc:
+            raise CdpError(f"Failed to reach {url}: {exc}") from exc
+        except json.JSONDecodeError as exc:
+            raise CdpError(f"Invalid JSON from {url}") from exc
+
+    def get_version(self) -> BrowserInfo:
+        payload = self._fetch_json(self.endpoint.version_url)
+        if not isinstance(payload, dict):
+            raise CdpError("Unexpected /json/version payload")
+        return BrowserInfo.from_json(payload)
+
+    def list_targets(self) -> list[dict[str, Any]]:
+        payload = self._fetch_json(self.endpoint.list_url)
+        if not isinstance(payload, list):
+            raise CdpError("Unexpected /json/list payload")
+        return [item for item in payload if isinstance(item, dict)]
+
+    def ping(self) -> bool:
+        try:
+            self.get_version()
+        except CdpError:
+            return False
+        return True
+
+    def wait_until_ready(
+        self,
+        *,
+        timeout: float = 30.0,
+        max_retries: int | None = None,
+        retry_base: float = 0.5,
+    ) -> BrowserInfo:
+        """Poll /json/version until ready or timeout (exponential backoff)."""
+        deadline = time.monotonic() + timeout
+        last_error: CdpError | None = None
+        attempt = 0
+        while time.monotonic() < deadline:
+            attempt += 1
+            try:
+                return self.get_version()
+            except CdpError as exc:
+                last_error = exc
+                if max_retries is not None and attempt >= max_retries:
+                    break
+                delay = backoff_delay(attempt, base=retry_base)
+                if time.monotonic() + delay > deadline:
+                    break
+                time.sleep(delay)
+        detail = f"after {attempt} attempts" if max_retries is not None else f"after {timeout}s"
+        raise CdpError(
+            f"CDP endpoint not ready {detail}: {self.endpoint.http_base}"
+        ) from last_error
+
+    def resolve_websocket_url(self) -> str:
+        if self.endpoint.websocket_hint:
+            return self.endpoint.websocket_hint
+        info = self.get_version()
+        if not info.web_socket_debugger_url:
+            raise CdpError("Browser did not return webSocketDebuggerUrl")
+        return info.web_socket_debugger_url
+
+    def health_snapshot(self) -> HealthSnapshot:
+        start = time.perf_counter()
+        try:
+            info = self.get_version()
+            targets = self.list_targets()
+            latency = (time.perf_counter() - start) * 1000.0
+            return HealthSnapshot(
+                reachable=True,
+                latency_ms=latency,
+                browser=info.browser,
+                web_socket_debugger_url=info.web_socket_debugger_url,
+                target_count=len(targets),
+            )
+        except CdpError as exc:
+            latency = (time.perf_counter() - start) * 1000.0
+            return HealthSnapshot(reachable=False, latency_ms=latency, error=str(exc))

cdp_connect_kit/cdp/models.py

@@ -0,0 +1,43 @@
+"""CDP discovery models."""
+
+from __future__ import annotations
+
+from dataclasses import dataclass
+from typing import Any
+
+
+@dataclass(frozen=True, slots=True)
+class BrowserInfo:
+    browser: str
+    protocol_version: str
+    user_agent: str
+    web_socket_debugger_url: str
+
+    @classmethod
+    def from_json(cls, payload: dict[str, Any]) -> BrowserInfo:
+        return cls(
+            browser=str(payload.get("Browser", "")),
+            protocol_version=str(payload.get("Protocol-Version", "")),
+            user_agent=str(payload.get("User-Agent", "")),
+            web_socket_debugger_url=str(payload.get("webSocketDebuggerUrl", "")),
+        )
+
+
+@dataclass(slots=True)
+class HealthSnapshot:
+    reachable: bool
+    latency_ms: float | None
+    browser: str | None = None
+    web_socket_debugger_url: str | None = None
+    target_count: int | None = None
+    error: str | None = None
+
+    def to_dict(self) -> dict[str, Any]:
+        return {
+            "reachable": self.reachable,
+            "latency_ms": self.latency_ms,
+            "browser": self.browser,
+            "web_socket_debugger_url": self.web_socket_debugger_url,
+            "target_count": self.target_count,
+            "error": self.error,
+        }

cdp_connect_kit/cdp/url.py

@@ -0,0 +1,77 @@
+"""Parse CDP HTTP and WebSocket endpoints."""
+
+from __future__ import annotations
+
+import re
+from dataclasses import dataclass
+from urllib.parse import urlparse, urlunparse
+
+_WS_RE = re.compile(r"^wss?$", re.IGNORECASE)
+_HTTP_RE = re.compile(r"^https?$", re.IGNORECASE)
+
+CDP_DEFAULT_PORT = 9222
+
+
+@dataclass(frozen=True, slots=True)
+class CdpEndpoint:
+    http_base: str
+    host: str
+    port: int
+    websocket_hint: str | None = None
+
+    @property
+    def version_url(self) -> str:
+        return f"{self.http_base}/json/version"
+
+    @property
+    def list_url(self) -> str:
+        return f"{self.http_base}/json/list"
+
+
+def _host_port_netloc(host: str, port: int) -> str:
+    if ":" in host and not host.startswith("["):
+        return f"[{host}]:{port}"
+    return f"{host}:{port}"
+
+
+def _default_port(scheme: str, explicit: int | None) -> int:
+    if explicit is not None:
+        return explicit
+    if scheme in {"https", "wss"}:
+        return 443
+    return CDP_DEFAULT_PORT
+
+
+def parse_endpoint(raw: str) -> CdpEndpoint:
+    """Normalize CDP endpoint from HTTP URL, WebSocket URL, or host:port shorthand."""
+    value = raw.strip()
+    if not value:
+        raise ValueError("Endpoint cannot be empty")
+
+    ws_hint: str | None = None
+    if "://" not in value:
+        value = f"http://{value}"
+
+    parsed = urlparse(value)
+    scheme = parsed.scheme.lower()
+
+    if _WS_RE.match(scheme):
+        ws_hint = value
+        http_scheme = "https" if scheme == "wss" else "http"
+        path = ""
+        scheme = http_scheme
+    elif _HTTP_RE.match(scheme):
+        http_scheme = scheme
+        path = ""
+        scheme = http_scheme
+    else:
+        raise ValueError(f"Unsupported URL scheme: {parsed.scheme!r}")
+
+    host = parsed.hostname
+    if not host:
+        raise ValueError(f"Could not determine host from {raw!r}")
+
+    port = _default_port(scheme, parsed.port)
+    netloc = _host_port_netloc(host, port)
+    http_base = urlunparse((scheme, netloc, path or "", "", "", ""))
+    return CdpEndpoint(http_base=http_base, host=host, port=port, websocket_hint=ws_hint)

cdp_connect_kit/cli.py

@@ -0,0 +1,211 @@
+"""Click CLI for cdp-connect."""
+
+from __future__ import annotations
+
+import asyncio
+import json
+import sys
+from pathlib import Path
+
+import click
+
+from cdp_connect_kit.cdp.client import CdpClient, CdpError
+from cdp_connect_kit.connect import connect_playwright
+from cdp_connect_kit.watch import format_sample_line, watch_endpoint
+
+EXIT_OK = 0
+EXIT_FAIL = 1
+EXIT_ERROR = 2
+
+
+@click.group(invoke_without_command=True)
+@click.version_option(package_name="cdp-connect-kit", prog_name="cdp-connect")
+@click.option("--show-deal", is_flag=True, help="Print Multilogin coupon info and exit.")
+@click.pass_context
+def main(ctx: click.Context, show_deal: bool) -> None:
+    """CDP connect toolkit — ping, Playwright connect, watch, MLX launcher."""
+    if show_deal:
+        from cdp_connect_kit.deal import print_show_deal
+
+        print_show_deal()
+        ctx.exit(0)
+
+
+@main.command("ping")
+@click.argument("endpoint")
+@click.option("--timeout", default=10.0, show_default=True)
+def ping_cmd(endpoint: str, timeout: float) -> None:
+    """Validate CDP HTTP endpoint and print WebSocket URL."""
+    client = CdpClient(endpoint, timeout=timeout)
+    try:
+        info = client.get_version()
+        ws = client.resolve_websocket_url()
+    except CdpError as exc:
+        click.echo(f"unreachable: {client.endpoint.http_base} ({exc})", err=True)
+        sys.exit(EXIT_FAIL)
+    click.echo(f"ok: {client.endpoint.http_base}")
+    click.echo(f"browser: {info.browser}")
+    click.echo(f"websocket: {ws}")
+    sys.exit(EXIT_OK)
+
+
+@main.command("playwright")
+@click.option("--endpoint", required=True, help="CDP HTTP, WebSocket URL, or host:port.")
+@click.option("--screenshot", "screenshot_path", type=click.Path(path_type=Path), default=None)
+@click.option("--timeout", default=30.0, show_default=True)
+@click.option("--max-retries", default=3, show_default=True, help="Max connect attempts.")
+def playwright_cmd(
+    endpoint: str,
+    screenshot_path: Path | None,
+    timeout: float,
+    max_retries: int,
+) -> None:
+    """Connect Playwright over CDP and optionally capture a screenshot."""
+
+    async def _run() -> None:
+        browser, playwright, metrics = await connect_playwright(
+            endpoint,
+            timeout=timeout,
+            max_retries=max_retries,
+        )
+        try:
+            context = browser.contexts[0] if browser.contexts else await browser.new_context()
+            page = context.pages[0] if context.pages else await context.new_page()
+            if screenshot_path:
+                await page.screenshot(path=str(screenshot_path))
+            click.echo(json.dumps(metrics.to_dict(), indent=2))
+            if screenshot_path:
+                click.echo(f"screenshot: {screenshot_path}", err=True)
+        finally:
+            await browser.close()
+            await playwright.stop()
+
+    try:
+        asyncio.run(_run())
+    except Exception as exc:
+        raise click.ClickException(str(exc)) from exc
+
+
+@main.command("watch")
+@click.option("--endpoint", required=True)
+@click.option("--interval", default=5.0, show_default=True)
+@click.option("--count", default=0, show_default=True, help="Stop after N samples (0 = infinite).")
+@click.option(
+    "--format",
+    "fmt",
+    type=click.Choice(["jsonl", "plain"]),
+    default="jsonl",
+    show_default=True,
+    help="jsonl = one JSON object per line (farm-runner); plain = human text.",
+)
+def watch_cmd(endpoint: str, interval: float, count: int, fmt: str) -> None:
+    """Poll CDP health metrics at an interval (JSONL for piping)."""
+
+    async def _run() -> None:
+        iterations = None if count == 0 else count
+
+        def _print(sample: dict) -> None:
+            click.echo(format_sample_line(sample, fmt=fmt), nl=fmt == "plain")
+
+        await watch_endpoint(
+            endpoint,
+            interval=interval,
+            iterations=iterations,
+            on_sample=_print,
+        )
+
+    try:
+        asyncio.run(_run())
+    except KeyboardInterrupt:
+        click.echo("stopped", err=True)
+
+
+@main.command("mlx-start")
+@click.option("--profile-id", required=True, help="MLX profile UUID.")
+@click.option("--folder-id", envvar="MLX_FOLDER_ID", help="MLX folder UUID.")
+@click.option("--token", envvar="MLX_TOKEN", help="Bearer token (or MLX_TOKEN).")
+@click.option(
+    "--launcher-url",
+    "launcher_url",
+    default=None,
+    help="Launcher base URL (MLX_LAUNCHER_URL / MLX_LAUNCHER_HOST).",
+)
+@click.option("--wait-timeout", default=120.0, show_default=True, help="Seconds to wait for CDP.")
+@click.option(
+    "--print-cdp-url",
+    is_flag=True,
+    help="Print CDP HTTP URL to stdout only (for shell scripts).",
+)
+@click.option(
+    "--connect",
+    is_flag=True,
+    help="Connect Playwright and emit ConnectMetrics JSON to stdout.",
+)
+@click.option("--headed", is_flag=True, help="Launcher headless_mode=false.")
+def mlx_start_cmd(
+    profile_id: str,
+    folder_id: str | None,
+    token: str | None,
+    launcher_url: str | None,
+    wait_timeout: float,
+    print_cdp_url: bool,
+    connect: bool,
+    headed: bool,
+) -> None:
+    """Start MLX profile via Launcher, wait for CDP, optionally connect Playwright."""
+    from cdp_connect_kit.mlx_cli import mlx_start
+
+    if print_cdp_url and connect:
+        raise click.ClickException("Use either --print-cdp-url or --connect, not both.")
+
+    mlx_start(
+        profile_id=profile_id,
+        folder_id=folder_id,
+        token=token,
+        launcher_url=launcher_url,
+        wait_timeout=wait_timeout,
+        headless=not headed,
+        print_cdp_url=print_cdp_url,
+        connect=connect,
+    )
+
+
+@main.command("mlx-stop")
+@click.option("--profile-id", required=True, help="MLX profile UUID.")
+@click.option("--token", envvar="MLX_TOKEN")
+@click.option("--launcher-url", "launcher_url", default=None)
+@click.option(
+    "--idempotent/--strict",
+    default=True,
+    show_default=True,
+    help="Idempotent: treat not-running as success.",
+)
+def mlx_stop_cmd(
+    profile_id: str,
+    token: str | None,
+    launcher_url: str | None,
+    idempotent: bool,
+) -> None:
+    """Stop an MLX profile via Launcher API."""
+    from cdp_connect_kit.mlx_cli import mlx_stop
+
+    mlx_stop(
+        profile_id=profile_id,
+        token=token,
+        launcher_url=launcher_url,
+        idempotent=idempotent,
+    )
+
+
+@main.command("mlx-list")
+@click.option("--token", envvar="MLX_TOKEN")
+@click.option("--launcher-url", "launcher_url", default=None)
+def mlx_list_cmd(token: str | None, launcher_url: str | None) -> None:
+    """List running MLX profiles from the local Launcher."""
+    from cdp_connect_kit.mlx_cli import mlx_list
+
+    mlx_list(token=token, launcher_url=launcher_url)
+
+
+if __name__ == "__main__":
+    main()

cdp_connect_kit/connect.py

@@ -0,0 +1,97 @@
+"""Playwright connect_over_cdp with retry and metrics."""
+
+from __future__ import annotations
+
+import asyncio
+import time
+from dataclasses import dataclass, field
+from typing import Any
+
+from playwright.async_api import Browser, async_playwright
+
+from cdp_connect_kit.cdp.client import CdpClient, CdpError
+from cdp_connect_kit.retry import backoff_delay
+
+
+@dataclass(slots=True)
+class ConnectMetrics:
+    endpoint: str
+    http_base: str
+    web_socket_url: str | None = None
+    attempts: int = 0
+    connect_ms: float | None = None
+    ready_ms: float | None = None
+    target_count: int | None = None
+    errors: list[str] = field(default_factory=list)
+
+    def to_dict(self) -> dict[str, Any]:
+        return {
+            "endpoint": self.endpoint,
+            "http_base": self.http_base,
+            "web_socket_url": self.web_socket_url,
+            "attempts": self.attempts,
+            "connect_ms": self.connect_ms,
+            "ready_ms": self.ready_ms,
+            "target_count": self.target_count,
+            "errors": self.errors,
+        }
+
+
+async def connect_playwright(
+    endpoint: str,
+    *,
+    timeout: float = 30.0,
+    max_retries: int = 3,
+    retry_base: float = 0.5,
+    wait_ready: bool = True,
+    retries: int | None = None,
+) -> tuple[Browser, Any, ConnectMetrics]:
+    """Connect Playwright to a CDP endpoint with exponential-backoff retry."""
+    attempts_limit = max_retries if retries is None else retries
+    client = CdpClient(endpoint, timeout=min(timeout, 10.0))
+    metrics = ConnectMetrics(endpoint=endpoint, http_base=client.endpoint.http_base)
+    playwright = await async_playwright().start()
+    browser: Browser | None = None
+
+    try:
+        ready_start = time.perf_counter()
+        if wait_ready:
+            loop = asyncio.get_event_loop()
+            await loop.run_in_executor(
+                None,
+                lambda: client.wait_until_ready(
+                    timeout=timeout,
+                    max_retries=attempts_limit,
+                    retry_base=retry_base,
+                ),
+            )
+            metrics.ready_ms = (time.perf_counter() - ready_start) * 1000.0
+
+        ws_url = client.resolve_websocket_url()
+        metrics.web_socket_url = ws_url
+        http_endpoint = client.endpoint.http_base
+
+        last_error: Exception | None = None
+        for attempt in range(1, attempts_limit + 1):
+            metrics.attempts = attempt
+            connect_start = time.perf_counter()
+            try:
+                browser = await playwright.chromium.connect_over_cdp(
+                    http_endpoint,
+                    timeout=timeout * 1000,
+                )
+                metrics.connect_ms = (time.perf_counter() - connect_start) * 1000.0
+                metrics.target_count = len(client.list_targets())
+                return browser, playwright, metrics
+            except Exception as exc:
+                last_error = exc
+                metrics.errors.append(str(exc))
+                if attempt < attempts_limit:
+                    await asyncio.sleep(backoff_delay(attempt, base=retry_base))
+
+        raise CdpError(f"connect_over_cdp failed after {attempts_limit} attempts") from last_error
+    except Exception:
+        if browser:
+            await browser.close()
+        await playwright.stop()
+        raise

cdp_connect_kit/deal.py

@@ -0,0 +1,25 @@
+"""Multilogin partner coupon output for --show-deal."""
+
+from __future__ import annotations
+
+import click
+
+SHOW_DEAL_TEXT = """Partner info (affiliate links — optional, not required for cdp-connect)
+
+Need a stable CDP port from Multilogin Launcher for connect_over_cdp?
+This kit starts profiles and normalizes endpoints — MLX desktop agent required.
+
+Multilogin X — antidetect browser & cloud phone (verify eligibility before checkout)
+
+  SAAS50  — browser plans (eligible new purchases)
+  MIN50   — cloud phone (eligible new purchases)
+
+  https://multilogin.com/?ref=SAAS50
+  Coupons: https://anti-detect.github.io/
+  Scripts: https://t.me/Multilogin_Scripts_Bot
+
+Disclosure: we may earn a commission. Offers change; confirm on vendor site."""
+
+
+def print_show_deal() -> None:
+    click.echo(SHOW_DEAL_TEXT)