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

linkedin_cli/api/messaging/conversations.py

@@ -0,0 +1,56 @@
+# linkedin/api/messaging/conversations.py
+"""Retrieve conversations and messages via Voyager Messaging GraphQL API."""
+import logging
+
+from tenacity import retry, stop_after_attempt, wait_exponential, retry_if_exception_type
+
+from linkedin_cli.api.client import PlaywrightLinkedinAPI
+from linkedin_cli.api.messaging.utils import encode_urn, check_response
+
+logger = logging.getLogger(__name__)
+
+_GRAPHQL_BASE = "https://www.linkedin.com/voyager/api/voyagerMessagingGraphQL/graphql"
+_CONVERSATIONS_QUERY_ID = "messengerConversations.0d5e6781bbee71c3e51c8843c6519f48"
+_MESSAGES_QUERY_ID = "messengerMessages.5846eeb71c981f11e0134cb6626cc314"
+
+
+def _graphql_headers(api: PlaywrightLinkedinAPI) -> dict:
+    headers = {**api.headers}
+    headers["accept"] = "application/graphql"
+    return headers
+
+
+@retry(
+    stop=stop_after_attempt(3),
+    wait=wait_exponential(multiplier=2, min=2, max=30),
+    retry=retry_if_exception_type(IOError),
+    reraise=True,
+)
+def fetch_conversations(api: PlaywrightLinkedinAPI, mailbox_urn: str) -> dict:
+    """Fetch recent conversations list. Returns raw API response."""
+    url = (
+        f"{_GRAPHQL_BASE}"
+        f"?queryId={_CONVERSATIONS_QUERY_ID}"
+        f"&variables=(mailboxUrn:{encode_urn(mailbox_urn)})"
+    )
+    res = api.get(url, headers=_graphql_headers(api))
+    check_response(res, "fetch_conversations")
+    return res.json()
+
+
+@retry(
+    stop=stop_after_attempt(3),
+    wait=wait_exponential(multiplier=2, min=2, max=30),
+    retry=retry_if_exception_type(IOError),
+    reraise=True,
+)
+def fetch_messages(api: PlaywrightLinkedinAPI, conversation_urn: str) -> dict:
+    """Fetch messages for a conversation. Returns raw API response."""
+    url = (
+        f"{_GRAPHQL_BASE}"
+        f"?queryId={_MESSAGES_QUERY_ID}"
+        f"&variables=(conversationUrn:{encode_urn(conversation_urn)})"
+    )
+    res = api.get(url, headers=_graphql_headers(api))
+    check_response(res, "fetch_messages")
+    return res.json()

linkedin_cli/api/messaging/send.py

@@ -0,0 +1,74 @@
+# linkedin/api/messaging/send.py
+"""Send messages via Voyager Messaging API."""
+import json
+import logging
+import os
+import uuid
+from tenacity import retry, stop_after_attempt, wait_exponential, retry_if_exception_type
+
+from linkedin_cli.api.client import PlaywrightLinkedinAPI
+from linkedin_cli.api.messaging.utils import check_response
+
+logger = logging.getLogger(__name__)
+
+
+@retry(
+    stop=stop_after_attempt(3),
+    wait=wait_exponential(multiplier=2, min=2, max=30),
+    retry=retry_if_exception_type(IOError),
+    reraise=True,
+)
+def send_message(
+        api: PlaywrightLinkedinAPI,
+        conversation_urn: str,
+        message_text: str,
+        mailbox_urn: str,
+) -> dict:
+    """Send a message via Voyager Messaging API.
+
+    Args:
+        api: Authenticated PlaywrightLinkedinAPI instance.
+        conversation_urn: e.g. "urn:li:msg_conversation:(urn:li:fsd_profile:XXX,2-threadId)"
+        message_text: The message body.
+        mailbox_urn: Sender's profile URN.
+
+    Returns:
+        API response dict with delivery confirmation.
+    """
+
+    origin_token = str(uuid.uuid4())
+    tracking_id = os.urandom(16).hex()
+
+    payload = {
+        "message": {
+            "body": {
+                "attributes": [],
+                "text": message_text,
+            },
+            "renderContentUnions": [],
+            "conversationUrn": conversation_urn,
+            "originToken": origin_token,
+        },
+        "mailboxUrn": mailbox_urn,
+        "trackingId": tracking_id,
+        "dedupeByClientGeneratedToken": False,
+    }
+
+    url = (
+        "https://www.linkedin.com/voyager/api"
+        "/voyagerMessagingDashMessengerMessages?action=createMessage"
+    )
+
+    headers = {**api.headers}
+    headers["accept"] = "application/json"
+    headers["content-type"] = "text/plain;charset=UTF-8"
+
+    logger.debug("Voyager send_message → %s", conversation_urn)
+
+    res = api.post(url, headers=headers, data=json.dumps(payload))
+    check_response(res, "send_message")
+
+    data = res.json()
+    delivered_at = data.get("value", {}).get("deliveredAt")
+    logger.info("Message delivered → %s (at %s)", conversation_urn, delivered_at)
+    return data

linkedin_cli/api/messaging/utils.py

@@ -0,0 +1,24 @@
+# linkedin/api/messaging/utils.py
+"""Shared helpers for messaging API modules."""
+import logging
+from urllib.parse import quote
+
+from linkedin_cli.exceptions import AuthenticationError
+
+logger = logging.getLogger(__name__)
+
+
+def encode_urn(urn: str) -> str:
+    """Percent-encode a URN for use inside Voyager GraphQL variables."""
+    return quote(urn, safe="")
+
+
+def check_response(res, context: str) -> None:
+    """Check a Voyager messaging API response, raising on errors."""
+    match res.status:
+        case 401:
+            raise AuthenticationError(f"Messaging API 401 ({context})")
+        case 403 | 404:
+            raise IOError(f"Messaging API {res.status} ({context})")
+    if not res.ok:
+        raise IOError(f"Messaging API {res.status} ({context}): {res.text()[:500]}")

linkedin_cli/api/voyager.py

@@ -0,0 +1,319 @@
+# linkedin/api/voyager.py
+from __future__ import annotations
+
+from dataclasses import dataclass, field, asdict
+from typing import List, Optional, Dict, Literal, Any
+
+ConnectionDistance = Literal["DISTANCE_1", "DISTANCE_2", "DISTANCE_3", "OUT_OF_NETWORK", None]
+
+DISTANCE_TO_DEGREE: Dict[str, Optional[int]] = {
+    "DISTANCE_1": 1,
+    "DISTANCE_2": 2,
+    "DISTANCE_3": 3,
+    "OUT_OF_NETWORK": None,
+}
+
+
+# ======================
+# Internal dataclasses (only used for validation & structure)
+# ======================
+
+@dataclass
+class Date:
+    year: Optional[int] = None
+    month: Optional[int] = None
+
+
+@dataclass
+class DateRange:
+    start: Optional[Date] = None
+    end: Optional[Date] = None
+
+
+@dataclass
+class Position:
+    title: str
+    company_name: str
+    company_urn: Optional[str] = None
+    location: Optional[str] = None
+    date_range: Optional[DateRange] = None
+    description: Optional[str] = None
+    urn: Optional[str] = None
+
+
+@dataclass
+class Education:
+    school_name: str
+    degree_name: Optional[str] = None
+    field_of_study: Optional[str] = None
+    date_range: Optional[DateRange] = None
+    urn: Optional[str] = None
+
+
+@dataclass
+class LinkedInProfile:
+    url: str
+    urn: str
+    full_name: str
+    first_name: str
+    last_name: str
+
+    headline: Optional[str] = None
+    summary: Optional[str] = None
+    public_identifier: Optional[str] = None
+    location_name: Optional[str] = None
+    geo: Optional[Dict[str, Any]] = None
+    industry: Optional[Dict[str, Any]] = None
+
+    positions: List[Position] = field(default_factory=list)
+    educations: List[Education] = field(default_factory=list)
+
+    country_code: Optional[str] = None
+    supported_locales: List[str] = field(default_factory=list)
+
+    connection_distance: Optional[ConnectionDistance] = None
+    connection_degree: Optional[int] = None
+
+
+# ======================
+# Private helpers
+# ======================
+
+def _resolve_references(data: dict) -> Dict[str, dict]:
+    """Build urn → entity lookup from 'included' array."""
+    return {
+        entity.get("entityUrn"): entity
+        for entity in data.get("included", [])
+        if entity.get("entityUrn")
+    }
+
+
+def _resolve_star_field(entity: dict, urn_map: Dict[str, dict], field_name: str) -> Any:
+    """Resolve *company, *school, *elements, etc."""
+    value = entity.get(field_name)
+    if not value:
+        return None
+    if isinstance(value, list):
+        return [urn_map.get(urn) for urn in value if urn_map.get(urn)]
+    return urn_map.get(value)
+
+
+def _date_from_raw(raw: Optional[dict]) -> Optional[Date]:
+    if not raw:
+        return None
+    return Date(year=raw.get("year"), month=raw.get("month"))
+
+
+def _date_range_from_raw(raw: Optional[dict]) -> Optional[DateRange]:
+    if not raw:
+        return None
+    return DateRange(
+        start=_date_from_raw(raw.get("start")),
+        end=_date_from_raw(raw.get("end")),
+    )
+
+
+def _enrich_position(pos: dict, urn_map: Dict[str, dict]) -> Position:
+    company = _resolve_star_field(pos, urn_map, "*company")
+
+    return Position(
+        title=pos.get("title") or "Unknown Title",
+        company_name=company.get("name") if company else pos.get("companyName", "Unknown Company"),
+        company_urn=company.get("entityUrn") if company else pos.get("companyUrn"),
+        location=pos.get("locationName"),
+        date_range=_date_range_from_raw(pos.get("dateRange")),
+        description=pos.get("description"),
+        urn=pos.get("entityUrn"),
+    )
+
+
+def _enrich_education(edu: dict, urn_map: Dict[str, dict]) -> Education:
+    school = _resolve_star_field(edu, urn_map, "*school")
+
+    return Education(
+        school_name=school.get("name") if school else edu.get("schoolName", "Unknown School"),
+        degree_name=edu.get("degreeName"),
+        field_of_study=edu.get("fieldOfStudy"),
+        date_range=_date_range_from_raw(edu.get("dateRange")),
+        urn=edu.get("entityUrn"),
+    )
+
+
+def _degree_from_union(union: dict) -> tuple[Optional[str], Optional[int]]:
+    """Extract (distance_str, degree) from a memberRelationshipUnion/Data dict."""
+    if any(k in union for k in ("connectedMember", "connected", "*connection", "connection")):
+        return "DISTANCE_1", 1
+
+    if "noConnection" in union:
+        distance_str = union["noConnection"].get("memberDistance")
+        degree = DISTANCE_TO_DEGREE.get(distance_str)
+        return distance_str, degree
+
+    return None, None
+
+
+def _extract_connection_info(profile_entity: dict, urn_map: Dict[str, dict]) -> tuple[Optional[str], Optional[int]]:
+    member_rel_urn = profile_entity.get("*memberRelationship")
+    if not member_rel_urn:
+        return None, None
+
+    rel = urn_map.get(member_rel_urn)
+    if not rel:
+        return None, None
+
+    union = rel.get("memberRelationshipUnion") or rel.get("memberRelationshipData")
+    if not union:
+        return None, None
+
+    return _degree_from_union(union)
+
+
+def parse_connection_degree(json_response: dict) -> Optional[int]:
+    """Extract connection degree by scanning included entities directly.
+
+    Works with any Voyager decoration that includes MemberRelationship
+    entities (e.g. TopCardSupplementary-120).  Does not depend on the
+    profile entity linking via *memberRelationship.
+    """
+    for entity in json_response.get("included", []):
+        if entity.get("$type") != "com.linkedin.voyager.dash.relationships.MemberRelationship":
+            continue
+        union = entity.get("memberRelationshipUnion") or entity.get("memberRelationshipData")
+        if not union:
+            continue
+        _, degree = _degree_from_union(union)
+        if degree is not None:
+            return degree
+    return None
+
+
+# ======================
+# Public function – returns plain dict
+# ======================
+
+def parse_linkedin_voyager_response(
+        json_response: dict,
+        public_identifier: Optional[str] = None,
+) -> dict:
+    """
+    Parse a full LinkedIn Voyager profile response and return a clean dictionary.
+
+    Uses dataclasses internally for validation and structure,
+    but returns a plain, JSON-serializable dict (no dataclass leakage).
+
+    Args:
+        json_response: Raw JSON from Voyager API (with "data" and "included")
+        public_identifier: Optional filter – only parse profile with this public ID
+
+    Returns:
+        dict with clean, structured LinkedIn profile data
+    """
+    urn_map = _resolve_references(json_response)
+
+    # Find the main Profile entity
+    profile_entity = None
+    for entity in json_response.get("included", []):
+        if entity.get("$type") == "com.linkedin.voyager.dash.identity.profile.Profile":
+            entity_id = entity.get("publicIdentifier")
+            if public_identifier is not None and entity_id == public_identifier:
+                profile_entity = entity
+                break
+            if public_identifier is None:
+                recipes = entity.get("$recipeTypes", [])
+                is_full = any("FullProfile" in r for r in recipes)
+                if is_full:
+                    profile_entity = entity
+                    break
+                if profile_entity is None:
+                    profile_entity = entity
+
+    # Fallback if not found via $type
+    if not profile_entity:
+        main_urn = json_response.get("data", {}).get("*elements", [None])[0]
+        profile_entity = urn_map.get(main_urn)
+
+    if not profile_entity:
+        raise ValueError("Could not find profile entity in the Voyager response")
+
+    first_name = profile_entity.get("firstName", "")
+    last_name = profile_entity.get("lastName", "")
+
+    # Extract connection info
+    connection_distance, connection_degree = _extract_connection_info(profile_entity, urn_map)
+
+    # Build positions
+    positions: List[Position] = []
+    pos_groups_urn = profile_entity.get("*profilePositionGroups")
+    if pos_groups_urn:
+        pos_groups_resp = urn_map.get(pos_groups_urn)
+        if pos_groups_resp and pos_groups_resp.get("*elements"):
+            for group_urn in pos_groups_resp["*elements"]:
+                group = urn_map.get(group_urn)
+                if not group:
+                    continue
+                positions_coll_urn = group.get("*profilePositionInPositionGroup")
+                if positions_coll_urn:
+                    positions_coll = urn_map.get(positions_coll_urn)
+                    if positions_coll and positions_coll.get("*elements"):
+                        for pos_urn in positions_coll["*elements"]:
+                            pos = urn_map.get(pos_urn)
+                            if pos:
+                                positions.append(_enrich_position(pos, urn_map))
+
+    # Build educations
+    educations: List[Education] = []
+    educations_urn = profile_entity.get("*profileEducations")
+    if educations_urn:
+        edu_coll = urn_map.get(educations_urn)
+        if edu_coll and edu_coll.get("*elements"):
+            for edu_urn in edu_coll["*elements"]:
+                edu = urn_map.get(edu_urn)
+                if edu:
+                    educations.append(_enrich_education(edu, urn_map))
+
+    # Resolve geo — try direct *geo first, then nested geoLocation.*geo
+    geo_entity = _resolve_star_field(profile_entity, urn_map, "*geo")
+    if not geo_entity:
+        geo_location = profile_entity.get("geoLocation")
+        if geo_location:
+            geo_urn = geo_location.get("*geo") or geo_location.get("geoUrn")
+            if geo_urn:
+                geo_entity = urn_map.get(geo_urn)
+
+    location_name = profile_entity.get("locationName")
+    if not location_name and geo_entity:
+        location_name = geo_entity.get("defaultLocalizedName")
+
+    # Extract country code from profile location
+    country_code = profile_entity.get("location", {}).get("countryCode")
+
+    # Extract supported languages from profile locales
+    supported_raw = profile_entity.get("supportedLocales") or []
+    supported_locales = [loc.get("language") for loc in supported_raw if loc.get("language")]
+
+    # Assemble data for dataclass validation
+    profile_data = {
+        "urn": profile_entity["entityUrn"],
+        "first_name": first_name,
+        "last_name": last_name,
+        "full_name": f"{first_name} {last_name}".strip() or None,
+        "headline": profile_entity.get("headline"),
+        "summary": profile_entity.get("summary"),
+        "public_identifier": profile_entity.get("publicIdentifier"),
+        "location_name": location_name,
+        "geo": geo_entity,
+        "industry": _resolve_star_field(profile_entity, urn_map, "*industry"),
+        "country_code": country_code,
+        "supported_locales": supported_locales,
+        "url": f"https://www.linkedin.com/in/{profile_entity.get('publicIdentifier', '')}/",
+        "positions": positions,
+        "educations": educations,
+        "connection_distance": connection_distance,
+        "connection_degree": connection_degree,
+    }
+
+    # Validate with dataclass (will raise if something is wrong)
+    profile_obj = LinkedInProfile(**profile_data)
+
+    # Return clean dictionary – perfect for JSON, APIs, logging, etc.
+    return asdict(profile_obj)

linkedin_cli/auth.py

@@ -0,0 +1,98 @@
+"""Drive a LinkedIn browser session to the authenticated feed.
+
+The auth flow is declared, not coded: each step is a ``@auth_flow.transition``
+action annotated with the page state it runs *from* and the states it may legally
+*produce*. The generic :meth:`PageFlow.run` loop (in ``page_state``) does the
+driving — observe the live page, dispatch to the action for that state, repeat
+until the feed. There is no hand-written loop or dispatch table here.
+
+Both the standalone CLI (``linkedin-cli login``) and the daemon
+(``linkedin/browser/launch.py``) call :func:`authenticate`, so the two share one
+enforced flow instead of hand-rolling their own login sequences.
+"""
+from __future__ import annotations
+
+import logging
+
+from termcolor import colored
+
+from linkedin_cli.browser.login import (
+    LINKEDIN_LOGIN_URL,
+    await_checkpoint_clear,
+    submit_login_form,
+)
+from linkedin_cli.exceptions import (
+    AuthenticationError,
+    CheckpointChallengeError,
+    IllegalPageTransition,
+)
+from linkedin_cli.page_state import PageFlow, PageState
+
+logger = logging.getLogger(__name__)
+
+LINKEDIN_FEED_URL = "https://www.linkedin.com/feed/"
+
+auth_flow = PageFlow("auth", goal=PageState.FEED)
+
+
+@auth_flow.transition(
+    when=PageState.UNKNOWN,
+    then={PageState.LOGIN, PageState.FEED, PageState.AUTHWALL, PageState.CHECKPOINT},
+)
+def _from_unknown(session) -> None:
+    """Blank/unknown page → head to the feed and let LinkedIn route us."""
+    session.page.goto(LINKEDIN_FEED_URL)
+    session.page.wait_for_load_state("domcontentloaded")
+
+
+@auth_flow.transition(when=PageState.AUTHWALL, then={PageState.LOGIN})
+def _from_authwall(session) -> None:
+    """Guest authwall → go to the login form."""
+    session.page.goto(LINKEDIN_LOGIN_URL)
+    session.page.wait_for_load_state("domcontentloaded")
+
+
+@auth_flow.transition(when=PageState.LOGIN, then={PageState.FEED, PageState.CHECKPOINT})
+def _from_login(session) -> None:
+    """Login form → submit credentials.
+
+    Landing back on the login page (rejected credentials) is outside the declared
+    ``then`` and so raises — which also enforces the never-resubmit rule: every
+    credential resubmit hardens LinkedIn's block, so we try exactly once.
+    """
+    if not getattr(session, "username", None):
+        raise AuthenticationError(
+            "Not logged in and no LINKEDIN_USERNAME/LINKEDIN_PASSWORD provided"
+        )
+    submit_login_form(session, session.username, session.password)
+
+
+@auth_flow.transition(when=PageState.CHECKPOINT, then={PageState.FEED})
+def _from_checkpoint(session) -> None:
+    """Checkpoint challenge → wait for a human to clear it in the live browser."""
+    if not await_checkpoint_clear(session.page):
+        raise CheckpointChallengeError(session.page.url)
+
+
+def authenticate(session, *, username=None, password=None) -> None:
+    """Drive *session* to the authenticated feed, or raise.
+
+    Credentials, when given, are stamped onto the session (the daemon passes them
+    explicitly; the standalone CLI lets the session carry them from the
+    environment), then the ``auth_flow`` drives to the feed.
+
+    Raises :class:`AuthenticationError` if the feed can't be reached (no action
+    for the current page, rejected credentials, or too many hops) and
+    :class:`CheckpointChallengeError` if a challenge can't be cleared in time.
+    """
+    if username is not None:
+        session.username = username
+    if password is not None:
+        session.password = password
+
+    try:
+        auth_flow.run(session)
+    except IllegalPageTransition as exc:
+        raise AuthenticationError(str(exc)) from exc
+
+    logger.info(colored("Authenticated — on the feed", "green", attrs=["bold"]))