warmpath 0.2.0__tar.gz → 0.3.0__tar.gz

{warmpath-0.2.0 → warmpath-0.3.0}/PKG-INFO

@@ -1,6 +1,8 @@
-Metadata-Version: 2.4
+Metadata-Version: 2.5
 Name: warmpath
-Version: 0.2.0
+Version: 0.3.0
 Summary: Local LinkedIn visible-connections scraper.
 Requires-Python: >=3.10
+Requires-Dist: browser-cookie3>=0.20.1
 Requires-Dist: open-linkedin-api>=2.3.1
+Requires-Dist: platformdirs>=4.11.8

warmpath-0.3.0/README.md

@@ -0,0 +1,80 @@
+![Warmpath banner](warmpath.jpg)
+
+# Warmpath
+
+Find LinkedIn mutuals and warm paths using your logged-in browser session.
+
+## Setup
+
+Log in to LinkedIn in a regular browser window, then import that session:
+
+```sh
+uvx warmpath auth import --browser chrome
+uvx warmpath auth status
+```
+
+Import uses [browser-cookie3](https://github.com/borisbabic/browser_cookie3) to read your browser's local cookie store. Supported browsers are Chrome, Chromium, Firefox, Edge, Brave, Safari, Arc, Vivaldi, Opera, Opera GX (`opera-gx`), and LibreWolf; availability depends on your operating system. Your OS may ask for keychain/keyring access. If the cookie store is locked, close the browser and retry. Private-window sessions cannot be imported.
+
+Warmpath imports only LinkedIn's `li_at` and `JSESSIONID` cookies and manages the saved session automatically. `company`, `skill`, and `human` use it on subsequent runs. Failed imports preserve the previous session.
+
+`auth status` shows the source browser, import time, cookie expiry, and storage location without displaying cookie values. It checks the saved session locally; LinkedIn may revoke a session before its cookies expire. If the session expires or LinkedIn stops accepting it, log in again and repeat `auth import`.
+
+## Development
+
+[go-task](https://taskfile.dev/) is required to run the repository checks. Install it with Homebrew on macOS:
+
+```sh
+brew install go-task
+```
+
+For other platforms, follow the [go-task installation guide](https://taskfile.dev/docs/installation). Verify that the `task` command is available before running any checks:
+
+```sh
+task --version
+```
+
+Then install the Python development dependencies and run the full check suite:
+
+```sh
+uv sync
+task check
+```
+
+## Usage
+
+### Company
+
+Who can introduce me into this company?
+
+```sh
+uvx warmpath company HashiCorp
+```
+
+### Skill
+
+Which reachable people match this recruiting need?
+
+```sh
+uvx warmpath skill Flutter
+```
+
+### Human
+
+Can I reach this exact person, and through whom?
+
+```sh
+uvx warmpath human https://www.linkedin.com/in/mitchellh/
+```
+
+## More Examples
+
+```sh
+uvx warmpath company "HashiCorp" --max-degree 2 --limit 5
+uvx warmpath auth import --browser firefox
+uvx warmpath company https://www.linkedin.com/company/hashicorp/
+uvx warmpath skill Leadership --max-depth 2
+uvx warmpath human https://www.linkedin.com/in/mitchellh/ --refresh-cache
+uvx warmpath company --help
+uvx warmpath skill --help
+uvx warmpath human --help
+```

{warmpath-0.2.0 → warmpath-0.3.0}/Taskfile.yaml

@@ -31,7 +31,7 @@ tasks:
     cmd: uv tree --outdated
 
   release:
-    desc: Check, build, tag, publish, and smoke-test a committed version.
+    desc: Check, build, publish, smoke-test, and tag a committed version.
     deps:
       - check
     cmd: scripts/release.sh

{warmpath-0.2.0 → warmpath-0.3.0}/docs/skill.md

@@ -18,7 +18,7 @@ For the `skill` subcommand, the call path is:
 4. `find_skill_connections(...)`
 5. `render_skill_connections_result(result)`
 
-`run_skill_command` builds a LinkedIn API client from the cookie file, resolves the cache directory, calls the skill search pipeline, and prints the rendered result.
+`run_skill_command` builds a LinkedIn API client from the session saved by `warmpath auth import --browser <browser>`, resolves the cache directory, calls the skill search pipeline, and prints the rendered result. Use `warmpath auth status` to check the saved session's expiry locally.
 
 ## Defaults
 

{warmpath-0.2.0 → warmpath-0.3.0}/pyproject.toml

@@ -1,9 +1,13 @@
 [project]
 name = "warmpath"
-version = "0.2.0"
+version = "0.3.0"
 description = "Local LinkedIn visible-connections scraper."
 requires-python = ">=3.10"
-dependencies = ["open-linkedin-api>=2.3.1"]
+dependencies = [
+    "browser-cookie3>=0.20.1",
+    "open-linkedin-api>=2.3.1",
+    "platformdirs>=4.11.8",
+]
 
 [dependency-groups]
 dev = ["pytest>=8.4.1", "pytest-xdist>=3.8.0", "pyright>=1.1.411"]

{warmpath-0.2.0 → warmpath-0.3.0}/scripts/release.sh

@@ -75,12 +75,12 @@ if uv run python -m zipfile -l "$wheel" | grep -q '\.uv-cache'; then
   exit 1
 fi
 
-echo "Tagging ${PACKAGE} ${version}"
-git tag -a "$tag" -m "${PACKAGE} ${version}"
-git push origin "$tag"
-
 echo "Publishing ${PACKAGE} ${version}"
 UV_PUBLISH_TOKEN="$token" uv publish
 
-echo "Smoke-testing uvx ${PACKAGE}"
-uvx --refresh-package "$PACKAGE" "$PACKAGE" --help
+echo "Smoke-testing uvx ${PACKAGE} ${version}"
+uvx --refresh-package "$PACKAGE" --from "${PACKAGE}==${version}" "$PACKAGE" --help
+
+echo "Tagging ${PACKAGE} ${version}"
+git tag -a "$tag" -m "${PACKAGE} ${version}"
+git push origin "$tag"

warmpath-0.3.0/tests/test_auth.py

@@ -0,0 +1,269 @@
+import json
+import os
+from pathlib import Path
+from unittest.mock import Mock
+
+import pytest
+from requests import Request
+from requests.cookies import RequestsCookieJar
+
+from warmpath import auth, cli
+
+
+@pytest.fixture(autouse=True)
+def auth_path(tmp_path, monkeypatch):
+    path = tmp_path / "warmpath" / "auth.json"
+    monkeypatch.setattr(auth, "auth_store_path", lambda: path)
+    return path
+
+
+@pytest.fixture
+def browser_cookies():
+    jar = RequestsCookieJar()
+    jar.set(
+        "li_at", "private-linkedin-token", domain=".linkedin.com", path="/",
+        secure=True, expires=4102444800,
+    )
+    jar.set(
+        "JSESSIONID", '"ajax:private-csrf-token"', domain="www.linkedin.com",
+        path="/", secure=True,
+    )
+    next(cookie for cookie in jar if cookie.name == "JSESSIONID").domain_specified = False
+    return jar
+
+
+@pytest.fixture
+def reader(browser_cookies, monkeypatch):
+    reader = Mock(return_value=browser_cookies)
+    monkeypatch.setattr(auth.browser_cookie3, "chrome", reader)
+    return reader
+
+
+@pytest.mark.parametrize("browser", auth.BROWSERS)
+def test_import_reads_only_the_selected_browser(browser, browser_cookies, monkeypatch):
+    reader = Mock(return_value=browser_cookies)
+    monkeypatch.setattr(auth.browser_cookie3, browser.replace("-", "_"), reader)
+
+    cli.main(["auth", "import", "--browser", browser])
+
+    reader.assert_called_once_with(domain_name="linkedin.com")
+    assert auth.load_auth().browser == browser
+
+
+def test_import_filters_unrelated_expired_and_out_of_scope_cookies(reader, browser_cookies, auth_path):
+    for name, domain, path, expires, value in [
+        ("tracking", ".linkedin.com", "/", None, "unrelated-tracking-token"),
+        ("li_at", ".notlinkedin.com", "/", None, "unrelated-domain-token"),
+        ("li_at", ".linkedin.com.example.org", "/", None, "unrelated-suffix-token"),
+        ("li_at", "jobs.linkedin.com", "/", None, "unrelated-host-token"),
+        ("li_at", ".linkedin.com", "/jobs", None, "unrelated-path-token"),
+        ("li_at", "www.linkedin.com", "/", 1, "expired-token"),
+        ("JSESSIONID", ".linkedin.com", "/", None, "invalid;token"),
+    ]:
+        browser_cookies.set(name, value, domain=domain, path=path, expires=expires)
+
+    auth.import_browser("chrome")
+
+    saved = auth.load_cookies()
+    assert saved.get_dict() == {
+        "li_at": "private-linkedin-token",
+        "JSESSIONID": '"ajax:private-csrf-token"',
+    }
+    assert len(saved) == 2
+    assert "unrelated" not in auth_path.read_text()
+    assert "expired-token" not in auth_path.read_text()
+    assert "invalid;token" not in auth_path.read_text()
+
+
+def test_imported_session_reaches_linkedin_with_csrf_and_cookie_attributes(reader, browser_cookies):
+    # A broader JSESSIONID must not conflict with the www cookie in the API's
+    # lookup by name, or replace the token associated with that scope.
+    browser_cookies.set("JSESSIONID", '"ajax:broader-token"', domain=".linkedin.com")
+    auth.import_browser("chrome")
+
+    api = cli.build_api()
+    session = api.client.session
+    request = session.prepare_request(Request("GET", "https://www.linkedin.com/voyager/api/me"))
+
+    assert request.headers["csrf-token"] == "ajax:private-csrf-token"
+    assert "li_at=private-linkedin-token" in request.headers["Cookie"]
+    assert 'JSESSIONID="ajax:private-csrf-token"' in request.headers["Cookie"]
+    assert "broader-token" not in request.headers["Cookie"]
+    cookies = {cookie.name: cookie for cookie in session.cookies}
+    assert cookies["li_at"].expires == 4102444800
+    assert cookies["li_at"].domain == ".linkedin.com"
+    assert cookies["JSESSIONID"].expires is None
+    assert cookies["JSESSIONID"].domain_specified is False
+    assert all(cookie.secure for cookie in session.cookies)
+    assert "Cookie" not in session.prepare_request(Request("GET", "https://example.org/")).headers
+    assert "Cookie" not in session.prepare_request(Request("GET", "http://www.linkedin.com/")).headers
+
+
+def test_import_and_status_report_metadata_without_cookie_values(reader, capsys, auth_path):
+    cli.main(["auth", "import", "--browser", "Chrome"])
+    before = auth_path.read_bytes()
+    reader.reset_mock()
+    cli.main(["auth", "status"])
+
+    output = capsys.readouterr()
+    assert output.err == ""
+    assert output.out.count("Status: ready (local expiry check)") == 2
+    assert "Browser: chrome" in output.out
+    assert "Imported:" in output.out
+    assert str(auth_path) in output.out
+    assert "Cookie: JSESSIONID; expires: session" in output.out
+    assert "Cookie: li_at; expires: 2100-01-01T00:00:00+00:00" in output.out
+    assert "private-linkedin-token" not in output.out
+    assert "private-csrf-token" not in output.out
+    assert auth_path.read_bytes() == before
+    reader.assert_not_called()
+
+
+@pytest.mark.skipif(os.name != "posix", reason="Unix file permissions")
+def test_auth_store_is_private_even_when_replacing_an_existing_file(reader, auth_path):
+    auth_path.parent.mkdir()
+    auth_path.write_text("previous session")
+    auth_path.chmod(0o644)
+
+    auth.import_browser("chrome")
+
+    assert auth_path.stat().st_mode & 0o777 == 0o600
+    assert list(auth_path.parent.iterdir()) == [auth_path]
+
+
+@pytest.mark.parametrize("condition", ["empty", "missing", "expired", "empty_value"])
+def test_unusable_import_preserves_previous_session(condition, reader, browser_cookies, auth_path):
+    auth.import_browser("chrome")
+    before = auth_path.read_bytes()
+    if condition == "empty":
+        browser_cookies.clear()
+    elif condition == "missing":
+        browser_cookies.clear(".linkedin.com", "/", "li_at")
+    else:
+        cookie = next(cookie for cookie in browser_cookies if cookie.name == "li_at")
+        if condition == "expired":
+            cookie.expires = 1
+        else:
+            cookie.value = ""
+
+    with pytest.raises(auth.AuthError, match="No usable LinkedIn session"):
+        auth.import_browser("chrome")
+
+    assert auth_path.read_bytes() == before
+
+
+def test_browser_error_preserves_session_and_does_not_echo_secrets(reader, auth_path, capsys):
+    auth.import_browser("chrome")
+    before = auth_path.read_bytes()
+    reader.side_effect = RuntimeError("private-linkedin-token")
+
+    with pytest.raises(SystemExit) as error:
+        cli.main(["auth", "import", "--browser", "chrome"])
+
+    assert error.value.code == 2
+    output = capsys.readouterr()
+    assert "Could not read chrome cookies" in output.err
+    assert "private-linkedin-token" not in output.out + output.err
+    assert auth_path.read_bytes() == before
+
+
+def test_failed_save_preserves_previous_session_and_cleans_up(reader, auth_path, monkeypatch):
+    auth.import_browser("chrome")
+    before = auth_path.read_bytes()
+    monkeypatch.setattr(Path, "replace", Mock(side_effect=PermissionError("cannot replace")))
+
+    with pytest.raises(auth.AuthError, match="Could not save"):
+        auth.import_browser("chrome")
+
+    assert auth_path.read_bytes() == before
+    assert list(auth_path.parent.iterdir()) == [auth_path]
+
+
+@pytest.mark.parametrize("command", [
+    ["auth", "status"], ["company", "Acme"], ["skill", "Python"],
+    ["human", "https://www.linkedin.com/in/example/"],
+])
+def test_missing_auth_has_import_guidance_without_browser_or_api_access(command, reader, monkeypatch, capsys, auth_path):
+    linkedin = Mock()
+    monkeypatch.setattr(cli, "Linkedin", linkedin)
+
+    with pytest.raises(SystemExit) as error:
+        cli.main(command)
+
+    assert error.value.code == 2
+    assert "warmpath auth import --browser" in capsys.readouterr().err
+    assert not auth_path.exists()
+    reader.assert_not_called()
+    linkedin.assert_not_called()
+
+
+@pytest.mark.parametrize("content", [b"", b"[]", b"{}", b"private-token", b"\xff"])
+def test_corrupt_store_has_reimport_guidance(content, auth_path, capsys):
+    auth_path.parent.mkdir()
+    auth_path.write_bytes(content)
+
+    with pytest.raises(SystemExit) as error:
+        cli.main(["auth", "status"])
+
+    assert error.value.code == 2
+    output = capsys.readouterr()
+    assert "saved LinkedIn session is invalid" in output.err
+    assert "warmpath auth import --browser" in output.err
+    assert "private-token" not in output.out + output.err
+    assert auth_path.read_bytes() == content
+
+
+@pytest.mark.parametrize("field,value", [
+    ("domain", "example.org"), ("path", "/jobs"), ("secure", "true"),
+    ("expires", "tomorrow"), ("expires", 10**20),
+    ("domain_specified", False), ("value", "token\r\nInjected: header"),
+])
+def test_invalid_stored_cookie_is_rejected(field, value, reader, auth_path):
+    auth.import_browser("chrome")
+    payload = json.loads(auth_path.read_text())
+    payload["cookies"][0][field] = value
+    auth_path.write_text(json.dumps(payload))
+
+    with pytest.raises(auth.AuthError, match="saved LinkedIn session is invalid"):
+        auth.load_cookies()
+
+
+def test_expired_session_is_reported_and_rejected_without_reimport(reader, capsys):
+    session = auth.import_browser("chrome")
+    next(cookie for cookie in session.cookies if cookie.name == "li_at").expires = 1
+    auth.save_auth(session)
+    reader.reset_mock()
+
+    with pytest.raises(SystemExit) as status_error:
+        cli.main(["auth", "status"])
+
+    assert status_error.value.code == 1
+    output = capsys.readouterr()
+    assert "Status: expired or incomplete" in output.out
+    assert "Missing or expired: li_at" in output.out
+    assert "warmpath auth import --browser chrome" in output.out
+
+    with pytest.raises(SystemExit) as api_error:
+        cli.build_api()
+
+    assert api_error.value.code == 2
+    assert "warmpath auth import --browser chrome" in capsys.readouterr().err
+    reader.assert_not_called()
+
+
+@pytest.mark.parametrize("arguments", [[], ["import"], ["import", "--browser", "unknown"], ["login"]])
+def test_auth_rejects_missing_and_unknown_arguments(arguments, reader):
+    with pytest.raises(SystemExit) as error:
+        cli.main(["auth", *arguments])
+
+    assert error.value.code == 2
+    reader.assert_not_called()
+
+
+@pytest.mark.parametrize("command,target", [("company", "Acme"), ("skill", "Python"), ("human", "example")])
+def test_manual_cookie_option_is_removed(command, target, capsys):
+    with pytest.raises(SystemExit) as error:
+        cli.main([command, target, "--cookie-file", "unused"])
+
+    assert error.value.code == 2
+    assert "unrecognized arguments" in capsys.readouterr().err

{warmpath-0.2.0 → warmpath-0.3.0}/tests/test_cli_commands.py

@@ -5,7 +5,7 @@ from pathlib import Path
 
 import pytest
 
-from warmpath import cli
+from warmpath import auth, cli
 
 
 ROOT = Path(__file__).resolve().parents[1]
@@ -30,24 +30,19 @@ def run_cli(*args: str, timeout: int = 30) -> subprocess.CompletedProcess[str]:
     )
 
 
-def linkedin_cookie_file() -> Path:
-    cookie_file = cli.DEFAULT_COOKIE_FILE
-    if not cookie_file.exists() or cookie_file.stat().st_size == 0:
-        pytest.skip("LinkedIn cookies are required for live integration tests")
-    return cookie_file
-
-
 def run_live_cli(
     tmp_path: Path,
     *args: str,
     timeout: int = 180,
 ) -> subprocess.CompletedProcess[str]:
+    if not auth.auth_store_path().exists():
+        pytest.skip("Run warmpath auth import --browser <browser> for live integration tests")
+    if auth.load_auth().missing_cookies():
+        pytest.skip("The imported LinkedIn session has expired; run warmpath auth import again")
     return run_cli(
         *args,
         "--cache-dir",
         str(tmp_path),
-        "--cookie-file",
-        str(linkedin_cookie_file()),
         "--refresh-cache",
         timeout=timeout,
     )
@@ -79,6 +74,8 @@ def test_top_level_help_shows_command_shapes() -> None:
     assert "human PROFILE_URL" in result.stdout
     assert "company COMPANY" in result.stdout
     assert "skill SKILL" in result.stdout
+    assert "auth import --browser BROWSER" in result.stdout
+    assert "auth status" in result.stdout
     assert f"human {RUSLAN_URL}" in result.stdout
     assert "company https://www.linkedin.com/company/ozon-tech" in result.stdout
     assert "skill Flutter" in result.stdout
@@ -138,13 +135,15 @@ def test_company_default_limit_is_five() -> None:
     assert args.limit == 5
 
 
-def test_default_paths_use_user_directories() -> None:
+def test_company_accepts_filter_query() -> None:
+    args = cli.parse_company_args(["Avito", "--filter", "Android Developer"])
+
+    assert args.filter == "Android Developer"
+
+
+def test_default_cache_uses_user_directory() -> None:
     args = cli.parse_company_args(["https://www.linkedin.com/company/binance/"])
 
-    assert (
-        args.cookie_file
-        == Path.home() / ".config" / "warmpath" / "linkedin.cookies"
-    )
     assert args.cache_dir == Path.home() / ".cache" / "warmpath"
 
 

{warmpath-0.2.0 → warmpath-0.3.0}/tests/test_mutual_connections.py

@@ -1,10 +1,33 @@
 from warmpath.cli import (
+    candidate_matches_filter,
     company_path_candidate,
     connection_result_row,
     render_company_path_result,
 )
 
 
+def test_candidate_filter_matches_visible_profile_fields_case_insensitively() -> None:
+    candidate = {
+        "target": {
+            "name": "Ada Lovelace",
+            "jobtitle": "Senior Android Developer",
+            "location": "London, United Kingdom",
+            "url": "https://www.linkedin.com/in/ada-lovelace/",
+        }
+    }
+
+    assert candidate_matches_filter(candidate, "android developer")
+    assert candidate_matches_filter(candidate, "ADA")
+    assert candidate_matches_filter(candidate, "united kingdom")
+    assert not candidate_matches_filter(candidate, "iOS")
+
+
+def test_candidate_filter_normalizes_whitespace() -> None:
+    candidate = {"target": {"jobtitle": "Senior Android   Developer"}}
+
+    assert candidate_matches_filter(candidate, "android developer")
+
+
 def test_connection_result_row_extracts_visible_mutual_connection_names() -> None:
     row = connection_result_row(
         {