x-browser 0.1.2__py3-none-any.whl

x_browser/__init__.py

@@ -0,0 +1 @@
+"""x-browser: Browser-based X/Twitter automation using Playwright."""

x_browser/actions.py

@@ -0,0 +1,389 @@
+"""Write actions for X: post, like, retweet, reply, quote, delete, bookmark.
+
+Every action calls politeness_wait() before executing.
+"""
+
+from __future__ import annotations
+
+import re
+import sys
+from typing import Optional
+
+from playwright.async_api import Page
+
+from .config import Config
+
+
+def _normalize_tweet_url(id_or_url: str) -> str:
+    """Turn a tweet ID or URL into a canonical x.com URL."""
+    id_or_url = id_or_url.strip()
+    # Already a URL
+    if id_or_url.startswith("http"):
+        return id_or_url.split("?")[0]  # strip query params
+    # Bare numeric ID — we need a placeholder username, but X redirects anyway
+    if id_or_url.isdigit():
+        return f"https://x.com/i/status/{id_or_url}"
+    return id_or_url
+
+
+async def _goto_tweet(page: Page, id_or_url: str) -> None:
+    """Navigate to a tweet page and wait for it to load."""
+    url = _normalize_tweet_url(id_or_url)
+    await page.goto(url, wait_until="domcontentloaded")
+    # Wait for the tweet article to appear
+    await page.wait_for_selector('article[data-testid="tweet"]', timeout=15_000)
+
+
+# ---------------------------------------------------------------------------
+# Post a tweet
+# ---------------------------------------------------------------------------
+
+async def tweet_post(
+    page: Page,
+    text: str,
+    *,
+    config: Config | None = None,
+    min_delay: float | None = None,
+    max_delay: float | None = None,
+    poll_options: list[str] | None = None,
+    poll_duration: int = 1440,
+) -> dict:
+    """Compose and post a new tweet.
+
+    Returns {"ok": True, "text": <posted text>} on success.
+    """
+    cfg = config or Config.load()
+    await cfg.politeness_wait(min_delay=min_delay, max_delay=max_delay)
+
+    await page.goto("https://x.com/compose/post", wait_until="domcontentloaded")
+    # Wait for the compose box
+    editor = await page.wait_for_selector(
+        'div[data-testid="tweetTextarea_0"]', timeout=10_000
+    )
+    await editor.click()
+    await page.keyboard.type(text, delay=30)
+
+    # Optional: add poll
+    if poll_options and len(poll_options) >= 2:
+        # Click the poll icon
+        poll_btn = await page.wait_for_selector(
+            'button[data-testid="pollButton"]', timeout=5_000
+        )
+        await poll_btn.click()
+        await page.wait_for_timeout(500)
+        # Fill poll options
+        poll_inputs = await page.query_selector_all('input[placeholder*="Choice"]')
+        for i, opt in enumerate(poll_options[:4]):  # max 4 options
+            if i < len(poll_inputs):
+                await poll_inputs[i].fill(opt)
+            elif i >= 2:
+                # Click "Add" to add more options (3rd, 4th)
+                add_btn = await page.query_selector('button[data-testid="addPollOptionButton"]')
+                if add_btn:
+                    await add_btn.click()
+                    await page.wait_for_timeout(300)
+                    poll_inputs = await page.query_selector_all('input[placeholder*="Choice"]')
+                    if i < len(poll_inputs):
+                        await poll_inputs[i].fill(opt)
+
+    # Click Post button
+    post_btn = await page.wait_for_selector(
+        'button[data-testid="tweetButton"]', timeout=5_000
+    )
+    await post_btn.click()
+
+    # Wait for navigation or confirmation
+    await page.wait_for_timeout(3000)
+
+    return {"ok": True, "text": text}
+
+
+# ---------------------------------------------------------------------------
+# Delete a tweet
+# ---------------------------------------------------------------------------
+
+async def tweet_delete(
+    page: Page,
+    id_or_url: str,
+    *,
+    config: Config | None = None,
+    min_delay: float | None = None,
+    max_delay: float | None = None,
+) -> dict:
+    """Delete a tweet you own."""
+    cfg = config or Config.load()
+    await cfg.politeness_wait(min_delay=min_delay, max_delay=max_delay)
+
+    await _goto_tweet(page, id_or_url)
+
+    # Click the "..." (more) menu on the tweet
+    more_btn = await page.wait_for_selector(
+        'article[data-testid="tweet"] button[data-testid="caret"]', timeout=5_000
+    )
+    await more_btn.click()
+    await page.wait_for_timeout(500)
+
+    # Click "Delete"
+    delete_item = await page.wait_for_selector(
+        'div[data-testid="Dropdown"] [role="menuitem"]:has-text("Delete")',
+        timeout=5_000,
+    )
+    await delete_item.click()
+    await page.wait_for_timeout(500)
+
+    # Confirm deletion
+    confirm_btn = await page.wait_for_selector(
+        'button[data-testid="confirmationSheetConfirm"]', timeout=5_000
+    )
+    await confirm_btn.click()
+    await page.wait_for_timeout(2000)
+
+    return {"ok": True, "deleted": id_or_url}
+
+
+# ---------------------------------------------------------------------------
+# Reply to a tweet
+# ---------------------------------------------------------------------------
+
+async def tweet_reply(
+    page: Page,
+    id_or_url: str,
+    text: str,
+    *,
+    config: Config | None = None,
+    min_delay: float | None = None,
+    max_delay: float | None = None,
+) -> dict:
+    """Reply to a tweet."""
+    cfg = config or Config.load()
+    await cfg.politeness_wait(min_delay=min_delay, max_delay=max_delay)
+
+    await _goto_tweet(page, id_or_url)
+
+    # Click the reply button on the tweet
+    reply_btn = await page.wait_for_selector(
+        'article[data-testid="tweet"] button[data-testid="reply"]', timeout=5_000
+    )
+    await reply_btn.click()
+    await page.wait_for_timeout(1000)
+
+    # Type in the reply compose box
+    editor = await page.wait_for_selector(
+        'div[data-testid="tweetTextarea_0"]', timeout=5_000
+    )
+    await editor.click()
+    await page.keyboard.type(text, delay=30)
+
+    # Click Reply/Post button
+    post_btn = await page.wait_for_selector(
+        'button[data-testid="tweetButton"]', timeout=5_000
+    )
+    await post_btn.click()
+    await page.wait_for_timeout(3000)
+
+    return {"ok": True, "replied_to": id_or_url, "text": text}
+
+
+# ---------------------------------------------------------------------------
+# Quote tweet
+# ---------------------------------------------------------------------------
+
+async def tweet_quote(
+    page: Page,
+    id_or_url: str,
+    text: str,
+    *,
+    config: Config | None = None,
+    min_delay: float | None = None,
+    max_delay: float | None = None,
+) -> dict:
+    """Quote a tweet with your own commentary."""
+    cfg = config or Config.load()
+    await cfg.politeness_wait(min_delay=min_delay, max_delay=max_delay)
+
+    await _goto_tweet(page, id_or_url)
+
+    # Click the retweet/repost button
+    repost_btn = await page.wait_for_selector(
+        'article[data-testid="tweet"] button[data-testid="retweet"]', timeout=5_000
+    )
+    await repost_btn.click()
+    await page.wait_for_timeout(500)
+
+    # Click "Quote" from the dropdown
+    quote_item = await page.wait_for_selector(
+        '[role="menuitem"]:has-text("Quote")', timeout=5_000
+    )
+    await quote_item.click()
+    await page.wait_for_timeout(1000)
+
+    # Type in the quote compose box
+    editor = await page.wait_for_selector(
+        'div[data-testid="tweetTextarea_0"]', timeout=5_000
+    )
+    await editor.click()
+    await page.keyboard.type(text, delay=30)
+
+    # Click Post button
+    post_btn = await page.wait_for_selector(
+        'button[data-testid="tweetButton"]', timeout=5_000
+    )
+    await post_btn.click()
+    await page.wait_for_timeout(3000)
+
+    return {"ok": True, "quoted": id_or_url, "text": text}
+
+
+# ---------------------------------------------------------------------------
+# Like a tweet
+# ---------------------------------------------------------------------------
+
+async def like(
+    page: Page,
+    id_or_url: str,
+    *,
+    config: Config | None = None,
+    min_delay: float | None = None,
+    max_delay: float | None = None,
+) -> dict:
+    """Like a tweet."""
+    cfg = config or Config.load()
+    await cfg.politeness_wait(min_delay=min_delay, max_delay=max_delay)
+
+    await _goto_tweet(page, id_or_url)
+
+    like_btn = await page.wait_for_selector(
+        'article[data-testid="tweet"] button[data-testid="like"]', timeout=5_000
+    )
+    await like_btn.click()
+    await page.wait_for_timeout(1000)
+
+    return {"ok": True, "liked": id_or_url}
+
+
+# ---------------------------------------------------------------------------
+# Retweet
+# ---------------------------------------------------------------------------
+
+async def retweet(
+    page: Page,
+    id_or_url: str,
+    *,
+    config: Config | None = None,
+    min_delay: float | None = None,
+    max_delay: float | None = None,
+) -> dict:
+    """Retweet (repost) a tweet."""
+    cfg = config or Config.load()
+    await cfg.politeness_wait(min_delay=min_delay, max_delay=max_delay)
+
+    await _goto_tweet(page, id_or_url)
+
+    repost_btn = await page.wait_for_selector(
+        'article[data-testid="tweet"] button[data-testid="retweet"]', timeout=5_000
+    )
+    await repost_btn.click()
+    await page.wait_for_timeout(500)
+
+    # Click "Repost" from the dropdown
+    repost_item = await page.wait_for_selector(
+        '[role="menuitem"]:has-text("Repost")', timeout=5_000
+    )
+    await repost_item.click()
+    await page.wait_for_timeout(2000)
+
+    return {"ok": True, "retweeted": id_or_url}
+
+
+# ---------------------------------------------------------------------------
+# Bookmark / Unbookmark
+# ---------------------------------------------------------------------------
+
+async def bookmark(
+    page: Page,
+    id_or_url: str,
+    *,
+    config: Config | None = None,
+    min_delay: float | None = None,
+    max_delay: float | None = None,
+) -> dict:
+    """Bookmark a tweet."""
+    cfg = config or Config.load()
+    await cfg.politeness_wait(min_delay=min_delay, max_delay=max_delay)
+
+    await _goto_tweet(page, id_or_url)
+
+    bookmark_btn = await page.wait_for_selector(
+        'article[data-testid="tweet"] button[data-testid="bookmark"]', timeout=5_000
+    )
+    await bookmark_btn.click()
+    await page.wait_for_timeout(1000)
+
+    return {"ok": True, "bookmarked": id_or_url}
+
+
+async def unbookmark(
+    page: Page,
+    id_or_url: str,
+    *,
+    config: Config | None = None,
+    min_delay: float | None = None,
+    max_delay: float | None = None,
+) -> dict:
+    """Remove bookmark from a tweet."""
+    cfg = config or Config.load()
+    await cfg.politeness_wait(min_delay=min_delay, max_delay=max_delay)
+
+    await _goto_tweet(page, id_or_url)
+
+    # If already bookmarked, the testid is "removeBookmark"
+    unbookmark_btn = await page.wait_for_selector(
+        'article[data-testid="tweet"] button[data-testid="removeBookmark"]',
+        timeout=5_000,
+    )
+    await unbookmark_btn.click()
+    await page.wait_for_timeout(1000)
+
+    return {"ok": True, "unbookmarked": id_or_url}
+
+
+# ---------------------------------------------------------------------------
+# Follow a user
+# ---------------------------------------------------------------------------
+
+async def follow(
+    page: Page,
+    username: str,
+    *,
+    config: Config | None = None,
+    min_delay: float | None = None,
+    max_delay: float | None = None,
+) -> dict:
+    """Follow a user by username."""
+    cfg = config or Config.load()
+    await cfg.politeness_wait(min_delay=min_delay, max_delay=max_delay)
+
+    username = username.lstrip("@").strip()
+    await page.goto(f"https://x.com/{username}", wait_until="domcontentloaded")
+    await page.wait_for_timeout(2000)
+
+    # Look for the Follow button (not Following — that means already followed)
+    follow_btn = await page.query_selector(
+        f'button[data-testid="{username}-follow"]'
+    )
+    if not follow_btn:
+        # Try generic follow button
+        follow_btn = await page.query_selector(
+            'div[data-testid="placementTracking"] button:not([data-testid*="unfollow"])'
+        )
+
+    if follow_btn:
+        label = (await follow_btn.inner_text()).strip()
+        if label == "Follow":
+            await follow_btn.click()
+            await page.wait_for_timeout(1500)
+            return {"ok": True, "followed": username}
+        else:
+            return {"ok": True, "already_following": username}
+    else:
+        return {"ok": False, "error": f"Could not find follow button for @{username}"}

x_browser/browser.py

@@ -0,0 +1,174 @@
+"""Browser session management for x-browser.
+
+Launches Chrome as a normal subprocess (zero automation flags) with
+--remote-debugging-port, then connects via CDP.  X cannot distinguish
+this from a human-opened Chrome window.
+"""
+
+from __future__ import annotations
+
+import asyncio
+import json
+import socket
+import subprocess
+import sys
+import time
+from pathlib import Path
+
+import httpx
+from playwright.async_api import Browser, BrowserContext, Page, async_playwright
+
+from .config import CONFIG_DIR
+
+USER_DATA_DIR = CONFIG_DIR / "chrome-data"
+
+# Where Chrome lives on macOS
+CHROME_PATHS = [
+    "/Applications/Google Chrome.app/Contents/MacOS/Google Chrome",
+    "/Applications/Google Chrome Canary.app/Contents/MacOS/Google Chrome Canary",
+    "/Applications/Chromium.app/Contents/MacOS/Chromium",
+]
+
+
+def _find_chrome() -> str:
+    for p in CHROME_PATHS:
+        if Path(p).exists():
+            return p
+    raise FileNotFoundError(
+        "Google Chrome not found. Install it or set CHROME_PATH env var."
+    )
+
+
+def _free_port() -> int:
+    """Find a free TCP port."""
+    with socket.socket(socket.AF_INET, socket.SOCK_STREAM) as s:
+        s.bind(("127.0.0.1", 0))
+        return s.getsockname()[1]
+
+
+async def _wait_for_devtools(port: int, timeout: float = 15) -> str:
+    """Poll the DevTools JSON endpoint until Chrome is ready.
+    Returns the WebSocket debugger URL.
+    """
+    url = f"http://127.0.0.1:{port}/json/version"
+    deadline = time.monotonic() + timeout
+    async with httpx.AsyncClient() as client:
+        while time.monotonic() < deadline:
+            try:
+                resp = await client.get(url, timeout=2)
+                data = resp.json()
+                return data["webSocketDebuggerUrl"]
+            except Exception:
+                await asyncio.sleep(0.3)
+    raise TimeoutError(f"Chrome DevTools did not start on port {port}")
+
+
+class XBrowser:
+    """Launches real Chrome and connects via CDP — fully undetectable."""
+
+    def __init__(self, *, headless: bool = True) -> None:
+        self._headless = headless
+        self._chrome_proc: subprocess.Popen | None = None
+        self._pw = None
+        self._browser: Browser | None = None
+        self._ctx: BrowserContext | None = None
+        self.page: Page | None = None
+
+    async def launch(self) -> Page:
+        USER_DATA_DIR.mkdir(parents=True, exist_ok=True)
+        chrome = _find_chrome()
+        port = _free_port()
+
+        cmd = [
+            chrome,
+            f"--user-data-dir={USER_DATA_DIR}",
+            f"--remote-debugging-port={port}",
+            "--no-first-run",
+            "--no-default-browser-check",
+            "--disable-default-apps",
+            f"--window-size=1280,900",
+        ]
+        if self._headless:
+            cmd.append("--headless=new")
+
+        # Launch Chrome as a regular process — no automation flags at all
+        self._chrome_proc = subprocess.Popen(
+            cmd,
+            stdout=subprocess.DEVNULL,
+            stderr=subprocess.DEVNULL,
+        )
+
+        # Wait for DevTools to be ready and get the WS URL
+        ws_url = await _wait_for_devtools(port)
+
+        # Connect Playwright over CDP (read-only — no automation flags injected)
+        self._pw = await async_playwright().start()
+        self._browser = await self._pw.chromium.connect_over_cdp(ws_url)
+        self._ctx = self._browser.contexts[0]
+
+        # Grab the first page or open one
+        if self._ctx.pages:
+            self.page = self._ctx.pages[0]
+        else:
+            self.page = await self._ctx.new_page()
+
+        return self.page
+
+    async def close(self) -> None:
+        if self._browser:
+            await self._browser.close()
+        if self._pw:
+            await self._pw.stop()
+        if self._chrome_proc:
+            self._chrome_proc.terminate()
+            try:
+                self._chrome_proc.wait(timeout=5)
+            except subprocess.TimeoutExpired:
+                self._chrome_proc.kill()
+
+    async def __aenter__(self) -> "XBrowser":
+        await self.launch()
+        return self
+
+    async def __aexit__(self, *exc) -> None:
+        await self.close()
+
+
+async def ensure_logged_in(page: Page) -> bool:
+    """Navigate to X and check if we're logged in."""
+    await page.goto("https://x.com/home", wait_until="domcontentloaded")
+    await page.wait_for_timeout(3000)
+    url = page.url
+    if "/login" in url or "/i/flow/login" in url:
+        return False
+    try:
+        await page.wait_for_selector('a[href="/compose/post"]', timeout=5000)
+        return True
+    except Exception:
+        return False
+
+
+async def login_interactive() -> None:
+    """Open a headed Chrome window for the user to log in manually."""
+    print("Opening Chrome for manual login...", file=sys.stderr)
+    print(
+        "Log in to X, then wait — session saves automatically.",
+        file=sys.stderr,
+    )
+
+    async with XBrowser(headless=False) as xb:
+        page = xb.page
+        await page.goto("https://x.com/login", wait_until="domcontentloaded")
+        print(
+            "Waiting for login... (navigate to your home timeline)",
+            file=sys.stderr,
+        )
+        try:
+            await page.wait_for_url("**/home**", timeout=300_000)
+            await page.wait_for_timeout(3000)
+            print("Login successful! Session saved.", file=sys.stderr)
+        except Exception:
+            print(
+                "Login timed out. Run `x-browser login` again.",
+                file=sys.stderr,
+            )