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

linkedin_agent_cli-0.1.0.dist-info/METADATA

@@ -0,0 +1,197 @@
+Metadata-Version: 2.4
+Name: linkedin-agent-cli
+Version: 0.1.0
+Summary: Django-free library and CLI for LinkedIn platform mechanics over a bound browser session (Voyager API + Playwright).
+Project-URL: Homepage, https://github.com/eracle/linkedin-cli
+Project-URL: Repository, https://github.com/eracle/linkedin-cli
+Project-URL: Issues, https://github.com/eracle/linkedin-cli/issues
+Author-email: eracle <eracle@posteo.eu>
+License-Expression: MIT
+License-File: LICENSE
+Keywords: agent-tools,ai-agent,browser-automation,cli,lead-generation,linkedin,linkedin-api,linkedin-automation,linkedin-scraper,llm,outreach,playwright,voyager,web-scraping
+Classifier: Development Status :: 4 - Beta
+Classifier: Environment :: Console
+Classifier: Intended Audience :: Developers
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Programming Language :: Python :: 3
+Classifier: Topic :: Internet :: WWW/HTTP :: Browsers
+Classifier: Topic :: Office/Business
+Classifier: Topic :: Software Development :: Libraries
+Requires-Python: >=3.10
+Requires-Dist: playwright-stealth
+Requires-Dist: playwright>=1.59
+Requires-Dist: tenacity<10,>=8
+Requires-Dist: termcolor
+Description-Content-Type: text/markdown
+
+# linkedin-cli
+
+**Drive LinkedIn from the command line or any program** — search people, scrape
+profiles, check connection status, send connection requests, and read or send
+messages. One small, dependency-light Python tool that talks to LinkedIn's
+private **Voyager API** through a **real, logged-in browser** (Playwright), so
+it behaves like a human session instead of a cookie-only scraper.
+
+![Python](https://img.shields.io/badge/python-3.10%2B-blue)
+![License](https://img.shields.io/badge/license-MIT-green)
+![Playwright](https://img.shields.io/badge/browser-Playwright-2EAD33)
+
+> No SaaS, no API key, no database. Your browser, your LinkedIn account, your machine.
+
+---
+
+## ✨ Why linkedin-cli
+
+- **Real browser session, not raw cookies.** A persistent Chromium window is
+  launched once and shared; requests ride your live, authenticated session —
+  far more resilient than header/cookie replay.
+- **Structured JSON out of every command.** Pipe it into `jq`, a script, or an
+  LLM agent. Human-readable summaries by default; `--json` for the full record.
+- **Robust login.** Authentication is a small **page-state machine** that
+  understands LinkedIn's login, authwall, and security-checkpoint redirects —
+  not a brittle one-shot form fill.
+- **Language-agnostic.** Anything that can run a subprocess and parse JSON can
+  drive LinkedIn — Python, Node, Go, shell, or an AI agent. No SDK lock-in.
+- **Tiny surface.** Eight verbs, four dependencies, zero web framework. It knows
+  about *a LinkedIn page and a browser* — nothing else.
+
+## 📦 Install
+
+```bash
+pip install linkedin-agent-cli
+python -m playwright install chromium
+```
+
+This installs the `linkedin-cli` command (equivalent to `python -m linkedin_cli.cli`).
+The PyPI package is `linkedin-agent-cli`; the import name is `linkedin_cli`. For the
+latest unreleased code, install from git:
+`pip install "linkedin-agent-cli @ git+https://github.com/eracle/linkedin-cli.git@main"`.
+
+## 🚀 Quickstart
+
+linkedin-cli uses a **bind + connect** model: one long-lived process owns the
+browser; every command is a short client that connects to it.
+
+```bash
+# 1. Open + bind a session once (this process owns the browser window).
+linkedin-cli session open --session work
+
+# 2. From any other shell, drive it. Set the session once via env:
+export LINKEDIN_CLI_SESSION=work
+export LINKEDIN_USERNAME="you@example.com"
+export LINKEDIN_PASSWORD="••••••••"
+
+linkedin-cli login                                    # authenticate the session
+linkedin-cli search "head of growth" --network first  # discover → handles
+linkedin-cli profile alice-smith                      # scrape a profile
+linkedin-cli profile alice-smith --json > alice.json  # save the full record
+linkedin-cli status  alice-smith                      # Connected / Pending / Qualified
+linkedin-cli connect alice-smith                      # send a connection request
+linkedin-cli message alice-smith --text "Hi Alice 👋"
+linkedin-cli thread  alice-smith                      # read the conversation
+
+linkedin-cli session close
+```
+
+Hit a security checkpoint? `playwright-cli attach work` opens the *same* browser
+so you can clear it by hand, then carry on.
+
+## 🧰 Commands
+
+`--session <name>` (or `$LINKEDIN_CLI_SESSION`) and `--json` apply to every command.
+
+| Command | What it does | `--json` result |
+|---|---|---|
+| `login` | Authenticate the session (creds from env), clear checkpoints, discover your own profile | `{account, self}` |
+| `whoami` | Who is this session logged in as (no login flow) | `{self}` |
+| `search <kw> [--network first/second/third] [--page N]` | People search → matching profile handles | `{query, page, network, profiles[]}` |
+| `profile <id>` | Scrape a profile (positions, education, location, …); `--raw` adds the raw Voyager blob | full `LinkedInProfile` |
+| `status <id>` | Connection state | `{public_identifier, state}` |
+| `connect <id>` | Send a connection request (no note) | `{public_identifier, state}` |
+| `message <id> --text …` | Send a direct message | `{public_identifier, sent}` |
+| `thread <id>` | Read a conversation's messages | `{public_identifier, messages[]}` |
+
+An `<id>` is a public handle (`alice-smith`) or a full profile URL. Commands that
+need the internal member `urn` (`message`/`thread`/`status`) resolve it for you —
+every command is independent and takes only a handle.
+
+## 🤖 Built for AI agents (and any language)
+
+linkedin-cli is designed to be driven by an LLM as a **deterministic tool**. The
+properties that make it agent-friendly:
+
+- **Stable, typed JSON contract** — every verb returns one documented dict;
+  maps directly onto a function-calling / tool-use schema.
+- **id-only, stateless commands** — a public handle is the only argument an agent
+  threads between steps; no session tokens, urns, or cursors to carry.
+- **Predictable error taxonomy** — failures surface as `error: <type>: <message>`
+  on stderr with a non-zero exit, so an agent can branch on `type`
+  (`checkpoint_challenge`, `authentication`, `connection_limit`, …).
+- **No hidden state or side effects** — stdout is result-only; logs go to stderr.
+- **Self-describing** — see [`llms.txt`](llms.txt) for a compact spec an LLM can
+  load directly, and `linkedin-cli <verb> --help` for per-verb usage.
+
+Because every command emits JSON on stdout, you can drive LinkedIn from anything —
+Python, Node, Go, shell, or an agent loop — no SDK and no Python import required:
+
+```python
+import subprocess, json
+
+def li(*args):
+    out = subprocess.run(["linkedin-cli", *args, "--json"],
+                         capture_output=True, text=True, check=True)
+    return json.loads(out.stdout)
+
+for hit in li("search", "head of growth", "--network", "first")["profiles"]:
+    handle = hit["public_identifier"]
+    if li("status", handle)["state"] == "Qualified":
+        li("message", handle, "--text", "Hi — loved your recent post!")
+```
+
+The discovery → outreach loop an agent runs: **`search` → `profile` / `status` →
+`message` / `thread`.**
+
+## 🧠 How it works
+
+- **bind + connect** — `linkedin-cli session open` launches a persistent Chromium
+  with `Browser.bind()` (Playwright ≥ 1.59) and registers a local `ws://`
+  endpoint under the session name. Each command `chromium.connect()`s to that same
+  browser and drives a *real* page. Auth, cookies, and fingerprint live in the
+  owner's on-disk profile; the CLI keeps only a name→endpoint registry — **no
+  database**. One session = one LinkedIn account.
+- **Voyager API** — reads (`profile`, `thread`, `status`) call LinkedIn's private
+  Voyager endpoints from inside the authenticated page (`fetch`), then parse the
+  JSON — fast and structured, no DOM scraping where an API exists.
+- **Page-state auth machine** — `classify_page()` judges the live page by URL
+  *path* only (so a `/login?...redirect=/feed/` URL never reads as the feed), and
+  each transition asserts its pre/post state, raising on an illegal jump. Login,
+  authwall, and checkpoint flows are modeled explicitly.
+
+## 📤 Output contract
+
+- Every command produces one result **dict** — that dict is both the `--json`
+  payload and the source the human summary is rendered from, so the two never drift.
+- **Human-readable by default; `--json` for the full dict.**
+- **No `--out` flag** — print to stdout, redirect to save (`… --json > out.json`).
+- **stdout is result-only; logs and errors go to stderr** as
+  `error: <type>: <message>` with a non-zero exit. Error types are stable:
+  `checkpoint_challenge`, `authentication`, `profile_inaccessible`,
+  `skip_profile`, `connection_limit`.
+
+## ⚠️ Responsible use
+
+This tool automates **your own** LinkedIn account from **your own** machine.
+Automating LinkedIn may conflict with its Terms of Service, and aggressive use
+can get an account restricted. Respect rate limits, only contact people for
+legitimate reasons, follow applicable laws (GDPR/CAN-SPAM), and use it at your
+own risk. You are responsible for how you use it.
+
+## 📄 License
+
+[MIT](LICENSE) © eracle
+
+---
+
+linkedin-cli was extracted from [**OpenOutreach**](https://github.com/eracle/OpenOutreach),
+an open-source AI outreach tool, where it powers the LinkedIn discovery and
+interaction layer. It is fully standalone and reusable on its own.

linkedin_agent_cli-0.1.0.dist-info/RECORD

@@ -0,0 +1,34 @@
+linkedin_cli/__init__.py,sha256=IdOL1XgI1gAR1WmguOT5MwNe9LgQIug9kx63B6_gT-k,414
+linkedin_cli/auth.py,sha256=aC6sfZC5WqapA4yUZqdIQ_78Tx5rLTK1v5PGzT9kG3s,3693
+linkedin_cli/cli.py,sha256=DTqjgq9zi1gUIqxvxvMkNlGSkmq-KIBqXlR1ZNXLYfc,15143
+linkedin_cli/conf.py,sha256=kGj1l9_8cQaK110sbvnEYDH5P5QKIEm-mCEIuZwFUw8,1298
+linkedin_cli/enums.py,sha256=hRNr0vSlTm-w6BeF9wLLtxbobzVqzXNQsmCPuaCWTzY,229
+linkedin_cli/exceptions.py,sha256=QI7anLCNUo3ebMb6GQEUk4HX-mD-pJOkUQhPbatsm4c,1403
+linkedin_cli/launcher.py,sha256=8f9o4FbrtcxBj97CXPIrvnHvo-X4wjX8Lyvbr6pwsyY,2509
+linkedin_cli/page_state.py,sha256=-QovkqQFlh49cLkKmoubCqCASAURjzJJCqoGy-h04Tk,5906
+linkedin_cli/session.py,sha256=2ZLHM8S4Ry8gz1m90RX8ztXmAFDTvmo0Gzg344zZ1Jc,6509
+linkedin_cli/url_utils.py,sha256=rYfyWFqLfHluJMv7BfzUqlM_VEuWzC9n1QqswxKXIp8,820
+linkedin_cli/actions/__init__.py,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
+linkedin_cli/actions/connect.py,sha256=mHI3GATmogQ0psqiyxBbE25oGZaESn5rYoarcsoFtNE,4043
+linkedin_cli/actions/conversations.py,sha256=KHptMUHbmjIxZjhWZzy2b7rUNYBEdsTYLzUVZUW8wPc,4778
+linkedin_cli/actions/message.py,sha256=yqIks2TRlBhBlgvW-WeXlRS_-uNpE6rv5GoPWL3YOZU,5810
+linkedin_cli/actions/profile.py,sha256=H-zQk4lCOhZq7nIeKlZMjokbS_URuuzPhiwLRrpm3X0,529
+linkedin_cli/actions/search.py,sha256=uXPdQfsuI46ig2fsd78I2girpy1uEuuI2baIIkCRLGo,6777
+linkedin_cli/actions/status.py,sha256=BNvSDoWr5Ml0gZm3lM9jNRw7jYHc3jqDD-l7avfOtrM,4207
+linkedin_cli/api/__init__.py,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
+linkedin_cli/api/client.py,sha256=u303hFM5rYeS_p7pJmjw2OEp4pASnrYw6rR7nOgLKPg,6928
+linkedin_cli/api/voyager.py,sha256=GkKZPYiV5sf-lOay6ORnZgZFXsRYmkGoErJhevEZfK8,11118
+linkedin_cli/api/messaging/__init__.py,sha256=pduj6tsma0IS5MqsgPp6Yk_Ncs8aOrvFQBvkWW4xY9U,381
+linkedin_cli/api/messaging/conversations.py,sha256=tOCgGOnwdv1ZBXiSLn4bmJZa6NWJoIBuVtUsvNpE7nA,1967
+linkedin_cli/api/messaging/send.py,sha256=YpTUhj0pFMRdPZiyNTZps0Jk4Onkws7MnOcPwWg3b8Y,2170
+linkedin_cli/api/messaging/utils.py,sha256=gmTHWPrZOJ3MlhiVtTIYXVCrQw3vpM28bbQU1faW2-I,789
+linkedin_cli/browser/__init__.py,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
+linkedin_cli/browser/login.py,sha256=tAmXzeWJFmIDGpTCUmRAnF71q7_3v7of8nDshV-45RE,5298
+linkedin_cli/browser/nav.py,sha256=QVr-jpn3qISH_JRzw-hDSe5gffWDUS0RIMOfOaIunOg,4011
+linkedin_cli/setup/__init__.py,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
+linkedin_cli/setup/self_profile.py,sha256=wqE9_jgzzsccQLqWpme4amKArMo9QOMvQMv0q5zhW28,991
+linkedin_agent_cli-0.1.0.dist-info/METADATA,sha256=ILWkI7gnbqmoY4U-ex1KUTZsvUrABwU-E46fGoiyxuU,9522
+linkedin_agent_cli-0.1.0.dist-info/WHEEL,sha256=mffPy8wBnZQn2VnJUU5jE99KsxaSfiyMHV9Yt0aLVxs,87
+linkedin_agent_cli-0.1.0.dist-info/entry_points.txt,sha256=kO1MrBzrciaqNkJH3b3rxotzsqiTCJJhWZ0ypxqrgAQ,55
+linkedin_agent_cli-0.1.0.dist-info/licenses/LICENSE,sha256=evnow1KJu1sfcM-e106GjsnOY0pr4NmgcWxMLdsCbNA,1063
+linkedin_agent_cli-0.1.0.dist-info/RECORD,,

linkedin_agent_cli-0.1.0.dist-info/WHEEL

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

linkedin_agent_cli-0.1.0.dist-info/entry_points.txt

@@ -0,0 +1,2 @@
+[console_scripts]
+linkedin-cli = linkedin_cli.cli:main

linkedin_agent_cli-0.1.0.dist-info/licenses/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 eracle
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

linkedin_cli/__init__.py

@@ -0,0 +1,9 @@
+"""linkedin_cli — standalone, Django-free LinkedIn interaction library.
+
+Owns the LinkedIn *platform* mechanics — navigation, login, the Voyager API
+client, profile/conversation scraping, and the connect/message/status/thread
+verbs. It holds no database and no campaign/CRM context: every verb runs
+against a browser session supplied by the caller (see ``session.LinkedInSession``).
+"""
+
+__version__ = "0.1.0"

linkedin_cli/actions/connect.py

@@ -0,0 +1,118 @@
+# linkedin/actions/connect.py
+import logging
+from typing import Dict, Any
+
+from linkedin_cli.enums import ProfileState
+from linkedin_cli.exceptions import SkipProfile, ReachedConnectionLimit
+from linkedin_cli.browser.nav import find_top_card, dump_page_html
+
+logger = logging.getLogger(__name__)
+
+SELECTORS = {
+    "weekly_limit": 'div[class*="ip-fuse-limit-alert__warning"]',
+    "invite_to_connect": (
+        '[aria-label*="Invite"][aria-label*="to connect"]:visible, '
+        'a:has(span:text-is("Connect")):visible, '
+        'button:has(span:text-is("Connect")):visible'
+    ),
+    "error_toast": 'div[data-test-artdeco-toast-item-type="error"]',
+    "more_button": (
+        'button[aria-label="More"]:visible, '
+        'button[id*="overflow"]:visible, '
+        'button[aria-label*="More actions"]:visible, '
+        'button:has(span:text-is("More")):visible'
+    ),
+    "connect_option": (
+        'div[role="button"][aria-label^="Invite"][aria-label*=" to connect"], '
+        'div[role="button"]:text-is("Connect"), '
+        '[role="menuitem"][aria-label*="Connect"], '
+        '[role="menuitem"]:has-text("Connect"), '
+        'li:text-is("Connect"), '
+        'span[role="button"]:text-is("Connect")'
+    ),
+    "send_now": 'button:has-text("Send now"), button[aria-label*="Send without"], button[aria-label*="Send invitation"]',
+}
+
+
+def send_connection_request(
+        session: "LinkedInSession",
+        profile: Dict[str, Any],
+) -> ProfileState:
+    """
+    Sends a LinkedIn connection request WITHOUT a note (fastest & safest).
+
+    Assumes the profile page is already loaded (caller navigates via
+    ``get_connection_status`` or ``visit_profile`` beforehand).
+    """
+    public_identifier = profile.get('public_identifier')
+
+    # Send invitation WITHOUT note (current active flow)
+    if not _connect_direct(session) and not _connect_via_more(session):
+        logger.debug("Connect button not found for %s — staying at current stage", public_identifier)
+        dump_page_html(session, profile)
+        return ProfileState.QUALIFIED
+
+    _click_without_note(session)
+    _check_weekly_invitation_limit(session)
+
+    logger.debug("Connection request submitted for %s", public_identifier)
+    return ProfileState.PENDING
+
+
+def _check_weekly_invitation_limit(session):
+    weekly_invitation_limit = session.page.locator(SELECTORS["weekly_limit"])
+    if weekly_invitation_limit.count() > 0:
+        raise ReachedConnectionLimit("Weekly connection limit pop up appeared")
+
+
+def _connect_direct(session):
+    session.wait()
+    top_card = find_top_card(session)
+    direct = top_card.locator(SELECTORS["invite_to_connect"])
+    if direct.count() == 0:
+        return False
+
+    direct.first.click()
+    logger.debug("Clicked direct 'Connect' button")
+
+    error = session.page.locator(SELECTORS["error_toast"])
+    if error.count() > 0:
+        raise SkipProfile(f"{error.inner_text().strip()}")
+
+    return True
+
+
+def _connect_via_more(session):
+    session.wait()
+    top_card = find_top_card(session)
+    page = session.page
+
+    # Dropdown may render as a portal outside top_card, so search page-wide
+    connect_option = page.locator(SELECTORS["connect_option"])
+
+    # Connect option may already be visible (More dropdown opened by status check)
+    if connect_option.count() == 0:
+        more = top_card.locator(SELECTORS["more_button"])
+        if more.count() == 0:
+            return False
+        more.first.click()
+        session.wait()
+
+    connect_option = page.locator(SELECTORS["connect_option"])
+    if connect_option.count() == 0:
+        return False
+    connect_option.first.click()
+    logger.debug("Used 'More → Connect' flow")
+
+    return True
+
+
+def _click_without_note(session):
+    """Click flow: sends connection request instantly without note."""
+    session.wait()
+
+    # Click "Send now" / "Send without a note"
+    send_btn = session.page.locator(SELECTORS["send_now"])
+    send_btn.first.click(force=True)
+    session.wait()
+    logger.debug("Connection request submitted (no note)")

linkedin_cli/actions/conversations.py

@@ -0,0 +1,132 @@
+# linkedin/actions/conversations.py
+"""Retrieve past LinkedIn conversations for a given profile."""
+import logging
+from datetime import datetime, timezone
+
+from linkedin_cli.api.client import PlaywrightLinkedinAPI
+from linkedin_cli.api.messaging import fetch_conversations, fetch_messages, encode_urn
+
+logger = logging.getLogger(__name__)
+
+
+def find_conversation_urn(api: PlaywrightLinkedinAPI, target_urn: str, mailbox_urn: str) -> str | None:
+    """Find conversation URN for a target profile URN by scanning recent conversations."""
+    raw = fetch_conversations(api, mailbox_urn)
+    elements = raw.get("data", {}).get("messengerConversationsBySyncToken", {}).get("elements", [])
+
+    for conv in elements:
+        for p in conv.get("conversationParticipants", []):
+            if p.get("hostIdentityUrn") == target_urn:
+                return conv.get("entityUrn")
+    return None
+
+
+def find_conversation_urn_via_navigation(session, target_urn: str) -> str | None:
+    """Navigate to the messaging page for a profile and capture the conversation URN.
+
+    Works for older conversations not in the first page of API results.
+    """
+    page = session.page
+    captured_urn = [None]
+
+    def on_response(response):
+        if "messengerMessages" not in response.url:
+            return
+        try:
+            data = response.json()
+            elements = data.get("data", {}).get("messengerMessagesBySyncToken", {}).get("elements", [])
+            if elements:
+                captured_urn[0] = elements[0].get("conversation", {}).get("entityUrn")
+        except Exception:
+            pass
+
+    session.context.on("response", on_response)
+    try:
+        url = f"https://www.linkedin.com/messaging/thread/new/?recipient={encode_urn(target_urn)}"
+        logger.debug("Navigating to messaging thread → %s", url)
+        page.goto(url, wait_until="domcontentloaded", timeout=30_000)
+        page.wait_for_timeout(8_000)
+    except Exception as e:
+        logger.warning("Navigation to messaging thread failed: %s", e)
+    finally:
+        session.context.remove_listener("response", on_response)
+
+    return captured_urn[0]
+
+
+def parse_message_element(msg: dict) -> dict | None:
+    """Parse a single Voyager message element into a dict.
+
+    Returns {entityUrn, text, sender_name, sender_host_urn, delivered_at, is_outgoing (unset)}
+    or None if the element should be skipped.
+    """
+    body = msg.get("body", {})
+    text = body.get("text", "") if isinstance(body, dict) else str(body)
+    if not text:
+        return None
+
+    sender = msg.get("sender", {})
+    participant = sender.get("participantType", {}).get("member", {})
+    first = (participant.get("firstName") or {}).get("text", "")
+    last = (participant.get("lastName") or {}).get("text", "")
+    sender_name = f"{first} {last}".strip() or "unknown"
+
+    delivered_at = msg.get("deliveredAt")
+    ts = (
+        datetime.fromtimestamp(delivered_at / 1000, tz=timezone.utc)
+        if delivered_at
+        else None
+    )
+
+    return {
+        "entityUrn": msg.get("entityUrn"),
+        "text": text,
+        "sender_name": sender_name,
+        "sender_host_urn": sender.get("hostIdentityUrn", ""),
+        "delivered_at": ts,
+    }
+
+
+def parse_messages(raw: dict) -> list[dict]:
+    """Parse raw messages response into a list of {sender, text, timestamp} dicts."""
+    elements = raw.get("data", {}).get("messengerMessagesBySyncToken", {}).get("elements", [])
+
+    messages = []
+    for msg in elements:
+        parsed = parse_message_element(msg)
+        if not parsed:
+            continue
+        ts = parsed["delivered_at"]
+        messages.append({
+            "sender": parsed["sender_name"],
+            "text": parsed["text"],
+            "timestamp": ts.strftime("%Y-%m-%d %H:%M") if ts else "",
+        })
+
+    messages.sort(key=lambda m: m["timestamp"])
+    return messages
+
+
+def get_conversation(session, target_urn: str, mailbox_urn: str) -> list[dict] | None:
+    """Retrieve past messages with a profile.
+
+    Args:
+        session: Browser session.
+        target_urn: Target profile URN.
+        mailbox_urn: Authenticated user's profile URN.
+
+    Returns a list of {sender, text, timestamp} dicts, or None if no conversation exists.
+    """
+    session.ensure_browser()
+    api = PlaywrightLinkedinAPI(session=session)
+
+    conversation_urn = find_conversation_urn(api, target_urn, mailbox_urn)
+    if not conversation_urn:
+        logger.debug("Not in recent conversations, trying navigation fallback")
+        conversation_urn = find_conversation_urn_via_navigation(session, target_urn)
+    if not conversation_urn:
+        logger.info("No conversation found for %s", target_urn)
+        return None
+
+    raw = fetch_messages(api, conversation_urn)
+    return parse_messages(raw)