linkedin-agent-cli 0.1.0__py3-none-any.whl

linkedin_cli/enums.py

@@ -0,0 +1,11 @@
+from enum import StrEnum
+
+
+class ProfileState(StrEnum):
+    QUALIFIED = "Qualified"
+    READY_TO_CONNECT = "Ready to Connect"
+    PENDING = "Pending"
+    CONNECTED = "Connected"
+    COMPLETED = "Completed"
+    FAILED = "Failed"
+

linkedin_cli/exceptions.py

@@ -0,0 +1,47 @@
+class AuthenticationError(Exception):
+    """Custom exception for 401 Unauthorized errors."""
+    pass
+
+
+class TerminalStateError(Exception):
+    """Profile is already done or dead — caller must skip it"""
+    pass
+
+
+class SkipProfile(Exception):
+    """Profile must be skipped."""
+    pass
+
+
+class ProfileInaccessibleError(Exception):
+    """Profile is private, deleted, or restricted (HTTP 403/404)."""
+    pass
+
+
+class ReachedConnectionLimit(Exception):
+    """ Weekly connection limit reached. """
+    pass
+
+
+class IllegalPageTransition(Exception):
+    """An action ran from, or produced, a page state its @transition contract forbids.
+
+    Raised by the ``transition`` decorator (see ``page_state``) when the live
+    page violates the action's declared precondition (``when``) or postcondition
+    (``then``) — e.g. submitting credentials and landing back on the login page
+    (rejected creds) instead of the feed or a checkpoint.
+    """
+    pass
+
+
+class CheckpointChallengeError(Exception):
+    """LinkedIn flagged the account with a security checkpoint.
+
+    Carries the challenge URL so the user knows where to go to clear it.
+    Raised from the login flow; the daemon must NOT call reauthenticate()
+    when it sees this — that just hardens the block.
+    """
+    def __init__(self, url: str):
+        self.url = url
+        super().__init__(f"LinkedIn checkpoint challenge: {url}")
+

linkedin_cli/launcher.py

@@ -0,0 +1,60 @@
+"""Launch the persistent, bound LinkedIn browser that verb processes connect to.
+
+This is the session *owner*: it launches a persistent browser (auth/cookies live
+in its on-disk profile), `browser.bind()`s it to a websocket, records the endpoint
+in the session registry, and stays alive. Verb processes attach as clients via
+``PlaywrightCliSession``; `playwright-cli attach <name>` can attach too (e.g. for a
+human to clear a checkpoint in the live browser).
+"""
+from __future__ import annotations
+
+import logging
+import os
+import signal
+
+from playwright.sync_api import sync_playwright
+from playwright_stealth import Stealth
+
+from linkedin_cli.conf import BROWSER_DEFAULT_TIMEOUT_MS, BROWSER_HEADLESS, BROWSER_SLOW_MO
+from linkedin_cli.session import clear_session, write_session
+
+logger = logging.getLogger(__name__)
+
+LINKEDIN_FEED_URL = "https://www.linkedin.com/feed/"
+
+
+def open_bound_session(name: str, *, profile_dir: str,
+                       host: str = "127.0.0.1", port: int = 0) -> None:
+    """Launch a persistent browser, bind it, register the endpoint, and block.
+
+    Runs until interrupted (SIGINT/SIGTERM), then deregisters and closes the
+    browser. The websocket endpoint is also printed to stdout for convenience.
+    Browser-launch knobs (headed/slow-mo/timeouts) come from ``conf``; ``host``/
+    ``port`` default to a localhost OS-picked port (right for many sessions in
+    one container — no cross-container exposure needed).
+    """
+    os.makedirs(profile_dir, exist_ok=True)
+    with sync_playwright() as pw:
+        context = pw.chromium.launch_persistent_context(
+            profile_dir, headless=BROWSER_HEADLESS, slow_mo=BROWSER_SLOW_MO,
+        )
+        context.set_default_timeout(BROWSER_DEFAULT_TIMEOUT_MS)
+        context.set_default_navigation_timeout(BROWSER_DEFAULT_TIMEOUT_MS)
+        Stealth().apply_stealth_sync(context)
+
+        endpoint = context.browser.bind(name, host=host, port=port)["endpoint"]
+        page = context.pages[0] if context.pages else context.new_page()
+        page.goto(LINKEDIN_FEED_URL)
+
+        write_session(name, endpoint, os.getpid())
+        logger.info("Session %r bound at %s (profile=%s)", name, endpoint, profile_dir)
+        print(endpoint, flush=True)
+
+        try:
+            signal.pause()  # block until a termination signal
+        except (KeyboardInterrupt, SystemExit):
+            pass
+        finally:
+            clear_session(name)
+            context.close()
+            logger.info("Session %r closed", name)

linkedin_cli/page_state.py

@@ -0,0 +1,148 @@
+"""Classify the live LinkedIn page into a :class:`PageState`.
+
+The browser is the source of truth: LinkedIn can bounce us to a login, an
+authwall, or a checkpoint at any moment, so control loops re-read the page
+rather than trust a remembered state. This module is that single, pure
+classifier. It reads only the URL *path* — never the query string, whose
+``?session_redirect=…%2Ffeed%2F`` once fooled a whole-URL substring check into
+thinking an unauthenticated login page was the feed.
+"""
+from __future__ import annotations
+
+import functools
+from enum import Enum
+from urllib.parse import urlsplit
+
+from playwright.sync_api import Page
+
+from linkedin_cli.exceptions import IllegalPageTransition
+
+
+class PageState(str, Enum):
+    """Where the browser currently is. Values match the auth machine's state ids."""
+
+    CHECKPOINT = "checkpoint"
+    LOGIN = "login"
+    AUTHWALL = "authwall"
+    FEED = "feed"
+    PROFILE = "profile"
+    MESSAGING = "messaging"
+    NOT_FOUND = "not_found"
+    UNKNOWN = "unknown"
+
+
+# Path prefix → state, in match order. Checkpoint is first: it can surface under
+# any flow and must win over whatever path it decorates.
+_ROUTES: list[tuple[str, PageState]] = [
+    ("/checkpoint", PageState.CHECKPOINT),
+    ("/login", PageState.LOGIN),
+    ("/authwall", PageState.AUTHWALL),
+    ("/feed", PageState.FEED),
+    ("/in/", PageState.PROFILE),
+    ("/messaging", PageState.MESSAGING),
+    ("/404", PageState.NOT_FOUND),
+]
+
+
+def classify_page(page: Page) -> PageState:
+    """Return the :class:`PageState` of the live page, judged by URL path only."""
+    path = urlsplit(page.url).path
+    for prefix, state in _ROUTES:
+        if path.startswith(prefix):
+            return state
+    return PageState.UNKNOWN
+
+
+def transition(*, when: PageState, then: PageState | set[PageState]):
+    """Declare a page-state transition as a contract on the action that performs it.
+
+    The decorated action takes a session (anything exposing a live ``page``) and
+    drives the browser. The wrapper enforces, against the *live* page:
+
+    - **precondition** — the page must be in ``when`` before the action runs;
+    - **postcondition** — the action must leave the page in one of ``then``.
+
+    Either violation raises :class:`IllegalPageTransition`. Enforcing the
+    postcondition *after* the action (re-reading the page) is what a held-state
+    FSM cannot do: the destination is observed, not declared up front, and may be
+    one of several (login → feed *or* checkpoint). Returns the resulting state.
+
+    The action's contract is introspectable as ``fn.when`` / ``fn.then`` so a
+    driver can build its dispatch table from the decorated actions themselves.
+    """
+    targets = frozenset({then} if isinstance(then, PageState) else then)
+
+    def decorator(fn):
+        @functools.wraps(fn)
+        def wrapper(session, *args, **kwargs) -> PageState:
+            before = classify_page(session.page)
+            if before is not when:
+                raise IllegalPageTransition(
+                    f"{fn.__name__}() requires page state {when.value!r}, "
+                    f"but page is {before.value!r} ({session.page.url})"
+                )
+            fn(session, *args, **kwargs)
+            after = classify_page(session.page)
+            if after not in targets:
+                expected = sorted(t.value for t in targets)
+                raise IllegalPageTransition(
+                    f"{fn.__name__}() from {when.value!r} produced {after.value!r}; "
+                    f"expected one of {expected} ({session.page.url})"
+                )
+            return after
+
+        wrapper.when = when
+        wrapper.then = targets
+        return wrapper
+
+    return decorator
+
+
+class PageFlow:
+    """A page-state flow: a set of ``@transition`` actions plus one generic driver.
+
+    Declare a flow with a goal state, then attach its transitions as decorated
+    actions — each registers under its precondition (``when``). :meth:`run` is the
+    observe→act loop, written once for every flow: re-read the live page, dispatch
+    to the action for that state, repeat until the goal. There is no per-flow loop
+    and no hand-built dispatch table — a flow *is* its annotated transitions.
+    """
+
+    def __init__(self, name: str, *, goal: PageState):
+        self.name = name
+        self.goal = goal
+        self._actions: dict[PageState, object] = {}
+
+    def transition(self, *, when: PageState, then: PageState | set[PageState]):
+        """Decorator: enforce the action's contract (via :func:`transition`) and
+        register it under ``when`` so :meth:`run` can dispatch to it."""
+        contract = transition(when=when, then=then)  # the module-level contract decorator
+
+        def register(fn):
+            if when in self._actions:
+                raise ValueError(
+                    f"{self.name!r} flow already has a transition from {when.value!r}"
+                )
+            self._actions[when] = contract(fn)
+            return self._actions[when]
+
+        return register
+
+    def run(self, session, *, max_hops: int = 8) -> PageState:
+        """Drive *session* to :attr:`goal`. Raise :class:`IllegalPageTransition`
+        if a page has no registered action or the goal isn't reached in time."""
+        for _ in range(max_hops):
+            state = classify_page(session.page)
+            if state is self.goal:
+                return state
+            action = self._actions.get(state)
+            if action is None:
+                raise IllegalPageTransition(
+                    f"{self.name!r} flow: no transition from {state.value!r} "
+                    f"({session.page.url})"
+                )
+            action(session)
+        raise IllegalPageTransition(
+            f"{self.name!r} flow: did not reach {self.goal.value!r} within "
+            f"{max_hops} hops (stuck at {classify_page(session.page).value!r})"
+        )

linkedin_cli/session.py

@@ -0,0 +1,169 @@
+"""The session contract every linkedin_cli verb runs against.
+
+linkedin_cli owns no browser lifecycle and no persistence. Each verb is handed
+a *session* — an object that exposes a live Playwright page/context plus a few
+lifecycle hooks — and drives LinkedIn through it. The concrete session is the
+caller's job: OpenOutreach's daemon backs it with its Django ``AccountSession``;
+the standalone CLI backs it with a Playwright CLI session adapter.
+
+``LinkedInSession`` is the typed boundary between the two — it lists exactly what
+the platform code touches, and nothing about campaigns, leads, or the DB.
+"""
+from __future__ import annotations
+
+import json
+import logging
+import os
+import random
+import time
+from pathlib import Path
+from typing import Protocol, runtime_checkable
+
+from playwright.sync_api import BrowserContext, Page, sync_playwright
+
+logger = logging.getLogger(__name__)
+
+
+@runtime_checkable
+class LinkedInSession(Protocol):
+    """Browser session a linkedin_cli verb attaches to.
+
+    Implementations own browser launch, the persistent profile, auth/cookies,
+    and fingerprint — none of which live here. The verbs only ever read
+    ``page``/``context``, resolve their own identity via ``self_profile``, and
+    call the lifecycle hooks below.
+    """
+
+    #: Live Playwright page for the authenticated session.
+    page: Page
+    #: Browser context owning the page (cookies, response listeners, storage).
+    context: BrowserContext
+
+    @property
+    def self_profile(self) -> dict:
+        """The logged-in member's own profile dict (the messaging mailbox).
+
+        Resolved once and kept warm for the session; carries at least
+        ``urn``, ``first_name``, ``last_name``.
+        """
+        ...
+
+    def ensure_browser(self) -> None:
+        """Launch or recover the browser so ``page`` is usable. Idempotent."""
+        ...
+
+    def wait(self, min_delay: float = ..., max_delay: float = ...) -> None:
+        """Human-paced pause, then block until the page reaches DOM-ready."""
+        ...
+
+    def close(self) -> None:
+        """Release browser resources held by the session."""
+        ...
+
+
+# ── Session registry ──────────────────────────────────────────────
+#
+# The launcher (``linkedin-cli session open``) owns the bound browser and
+# records its websocket endpoint here; verb processes look it up by name. This
+# is the only on-disk state linkedin_cli keeps — a pointer to a running browser,
+# not auth/cookies (those live in the launcher's persistent profile).
+
+def linkedin_cli_home() -> Path:
+    """Root dir for linkedin-cli's on-disk state (override via $LINKEDIN_CLI_HOME)."""
+    return Path(os.environ.get("LINKEDIN_CLI_HOME") or Path.home() / ".linkedin-cli")
+
+
+def _sessions_dir() -> Path:
+    return linkedin_cli_home() / "sessions"
+
+
+def _session_file(name: str) -> Path:
+    return _sessions_dir() / f"{name}.json"
+
+
+def write_session(name: str, endpoint: str, pid: int) -> Path:
+    """Record a bound browser's endpoint + launcher pid under *name* (atomic)."""
+    path = _session_file(name)
+    path.parent.mkdir(parents=True, exist_ok=True)
+    tmp = path.with_suffix(".json.tmp")
+    tmp.write_text(json.dumps({"name": name, "endpoint": endpoint, "pid": pid}))
+    tmp.replace(path)
+    return path
+
+
+def read_session(name: str) -> dict | None:
+    """Return the recorded ``{name, endpoint, pid}`` for *name*, or None."""
+    path = _session_file(name)
+    if not path.exists():
+        return None
+    return json.loads(path.read_text())
+
+
+def clear_session(name: str) -> None:
+    """Remove the registry entry for *name* if present."""
+    _session_file(name).unlink(missing_ok=True)
+
+
+# ── Playwright-CLI-backed session (connect to a bound browser) ─────
+
+class PlaywrightCliSession:
+    """A `LinkedInSession` that drives a launcher-owned bound browser over `connect`.
+
+    The launcher (`linkedin-cli session open`) launches the persistent browser
+    and `browser.bind()`s it; this attaches with `chromium.connect(endpoint)`,
+    yielding a real `page`/`context` shared with the launcher (and with any
+    `playwright-cli attach`). It owns no browser lifecycle and no persistence —
+    `close()` only disconnects this client; the launcher's browser keeps running.
+
+    Pacing (``min_pace``/``max_pace``) is injected by the caller (the CLI), not
+    read from config here.
+    """
+
+    def __init__(self, endpoint: str, *, min_pace: float, max_pace: float,
+                 username: str | None = None, password: str | None = None,
+                 name: str | None = None):
+        self.endpoint = endpoint
+        self.min_pace = min_pace
+        self.max_pace = max_pace
+        self.username = username
+        self.password = password
+        self.name = name
+        self.page = None
+        self.context = None
+        self._playwright = None
+        self._browser = None
+        self._self_profile = None
+
+    def ensure_browser(self) -> None:
+        if self.page is not None and not self.page.is_closed():
+            return
+        self._playwright = sync_playwright().start()
+        self._browser = self._playwright.chromium.connect(self.endpoint)
+        self.context = self._browser.contexts[0] if self._browser.contexts else self._browser.new_context()
+        self.page = self.context.pages[0] if self.context.pages else self.context.new_page()
+        logger.debug("Connected to bound browser at %s", self.endpoint)
+
+    @property
+    def self_profile(self) -> dict:
+        if self._self_profile is None:
+            from linkedin_cli.setup.self_profile import discover_self_profile
+            self._self_profile = discover_self_profile(self)
+        return self._self_profile
+
+    def wait(self, min_delay: float | None = None, max_delay: float | None = None) -> None:
+        time.sleep(random.uniform(min_delay or self.min_pace, max_delay or self.max_pace))
+        if self.page:
+            self.page.wait_for_load_state("domcontentloaded")
+
+    def close(self) -> None:
+        # Disconnect this client only — the launcher owns the browser/profile.
+        try:
+            if self._browser:
+                self._browser.close()
+            if self._playwright:
+                self._playwright.stop()
+        finally:
+            self.page = self.context = self._browser = self._playwright = None
+
+    def __repr__(self) -> str:
+        return f"linkedin-cli-session:{self.name or self.endpoint}"

linkedin_cli/setup/self_profile.py

@@ -0,0 +1,25 @@
+"""Discover the logged-in member's own LinkedIn profile (the messaging mailbox)."""
+from __future__ import annotations
+
+import logging
+
+from linkedin_cli.api.client import PlaywrightLinkedinAPI
+from linkedin_cli.exceptions import AuthenticationError
+
+logger = logging.getLogger(__name__)
+
+
+def discover_self_profile(session) -> dict:
+    """Scrape the logged-in member's own profile via Voyager (``me``).
+
+    Pure platform read — no persistence. Returns the parsed profile dict,
+    which carries at least ``public_identifier``, ``urn``, and ``full_name``.
+    Raises ``AuthenticationError`` if the API call fails (expired/blocked session).
+    """
+    session.ensure_browser()
+    api = PlaywrightLinkedinAPI(session=session)
+    profile, _raw = api.get_profile(public_identifier="me")
+    if not profile:
+        raise AuthenticationError("Could not fetch own profile via Voyager API")
+    logger.info("Self-profile discovered: %s", profile.get("public_identifier"))
+    return profile

linkedin_cli/url_utils.py

@@ -0,0 +1,30 @@
+from typing import Optional
+from urllib.parse import quote, urlparse, unquote
+
+
+def url_to_public_id(url: str) -> Optional[str]:
+    """
+    Strict LinkedIn public ID extractor:
+    - Path MUST start with /in/
+    - Returns the second segment, percent-decoded
+    - Returns None for empty or non-profile URLs
+    """
+    if not url:
+        return None
+
+    path = urlparse(url.strip()).path
+    parts = path.strip("/").split("/")
+
+    if len(parts) < 2 or parts[0] != "in":
+        return None
+
+    public_id = parts[1]
+    return unquote(public_id)
+
+
+def public_id_to_url(public_id: str) -> str:
+    """Convert public_identifier back to a clean LinkedIn profile URL."""
+    if not public_id:
+        return ""
+    public_id = public_id.strip("/")
+    return f"https://www.linkedin.com/in/{quote(public_id, safe='')}/"