warmpath 0.3.2__tar.gz → 0.3.4__tar.gz

{warmpath-0.3.2 → warmpath-0.3.4}/PKG-INFO

@@ -1,8 +1,9 @@
 Metadata-Version: 2.5
 Name: warmpath
-Version: 0.3.2
+Version: 0.3.4
 Summary: Local LinkedIn visible-connections scraper.
 Requires-Python: >=3.10
 Requires-Dist: browser-cookie3>=0.20.1
+Requires-Dist: curl-cffi>=0.16.3
 Requires-Dist: open-linkedin-api>=2.3.1
 Requires-Dist: platformdirs>=4.11.8

warmpath-0.3.4/README.md

@@ -0,0 +1,88 @@
+![Warmpath banner](warmpath.jpg)
+
+# Warmpath
+
+Find LinkedIn mutuals and warm paths using your logged-in browser session.
+
+## Usage
+
+Log in to LinkedIn in a regular browser window, then import that session. Replace `chrome` with your browser's name if needed.
+
+```sh
+# Import and check your browser session
+uvx warmpath auth import --browser chrome
+uvx warmpath auth status
+
+# Find people who can introduce you to a company
+uvx warmpath company HashiCorp
+uvx warmpath company https://www.linkedin.com/company/hashicorp/ --max-degree 2 --limit 5
+
+# List the current employers of all your direct connections
+uvx warmpath companies
+uvx warmpath companies --urls
+uvx warmpath companies --refresh-cache
+
+# Find reachable people with a skill
+uvx warmpath skill Flutter
+uvx warmpath skill Leadership --max-depth 2
+
+# Find mutual connections with a person
+uvx warmpath human https://www.linkedin.com/in/mitchellh/
+
+# Refresh cached results
+uvx warmpath human https://www.linkedin.com/in/mitchellh/ --refresh-cache
+
+# Show options for a command; also works with companies, auth, skill, and human
+uvx warmpath company --help
+```
+
+`companies` walks the complete 1st-degree connections list, looks up current
+employers, and deduplicates by company ID. It includes multiple current employers
+and keeps unlinked employer names; `--urls` prints only known LinkedIn company
+URLs. It does not infer employment from profile headlines.
+
+Connections are requested in pages of 1,000. Profiles are looked up once per
+unique connection when employer data is absent from the connection row. Company
+names and URLs come from those responses, with no separate company lookups.
+Completed lookups are cached so interrupted runs can resume, and repeating a
+completed snapshot makes no HTTP calls. Use `--refresh-cache` for updated
+connections and employment. Caches are scoped to the imported session.
+
+If LinkedIn restricts a profile or truncates its employment data, the command
+prints the known companies, reports the incomplete result on stderr, and exits
+with status 1. Cached snapshots preserve that status until refreshed.
+
+## Browser sessions
+
+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 LinkedIn's `li_at` and `JSESSIONID` tokens together with its device, security, and routing cookies, and manages the saved session automatically. `company`, `companies`, `skill`, and `human` use it on subsequent runs. Failed imports preserve the previous session.
+
+`auth import` and `auth status` print only `Logged in as <name>` after confirming your session with LinkedIn. If `auth status` cannot confirm a login, it prints `Not logged in` and exits with status 1. Both commands require a connection to LinkedIn.
+
+Successful requests preserve updated cookies returned by LinkedIn. When a saved session expires or is rejected, Warmpath reads the current session from the previously imported browser and retries a read once. Healthy requests need no extra auth checks or browser access. If LinkedIn has also signed out the browser, sign in there again and retry; cookie expiry dates alone cannot indicate whether LinkedIn has revoked a session. Rate limits and server errors are reported rather than treated as empty search results.
+
+LinkedIn requests use [curl_cffi](https://curl-cffi.readthedocs.io/en/latest/impersonate/_index.html) to match the browser family's TLS and HTTP/2 behavior, rather than just changing the user-agent. Chrome, Chromium, and Edge imports use the installed browser version for the user-agent and client hints, with the closest supported transport preset. Requests are spaced at least half a second apart within a client; this does not add HTTP calls. The CLI reads the browser's cookie store without writing to it. Because the copied cookies share the browser's LinkedIn session, server-side revocation can still affect both.
+
+## Development
+
+Browser cookie import uses [browser-cookie3](https://github.com/borisbabic/browser_cookie3).
+
+To test changes in this checkout, use `uv run warmpath` instead of `uvx warmpath`,
+which runs the published package. For example:
+
+```sh
+uv run warmpath auth import --browser chrome
+uv run warmpath auth status
+```
+
+[go-task](https://taskfile.dev/) runs the repository checks. Install it with Homebrew on macOS, or follow the [installation guide](https://taskfile.dev/docs/installation) for other platforms. Then verify the tool, install the Python development dependencies, and run the checks:
+
+```sh
+# macOS
+brew install go-task
+
+task --version
+uv sync
+task check
+```

{warmpath-0.3.2 → warmpath-0.3.4}/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 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.
+`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 whether you are logged in and as whom.
 
 ## Defaults
 

{warmpath-0.3.2 → warmpath-0.3.4}/pyproject.toml

@@ -1,10 +1,11 @@
 [project]
 name = "warmpath"
-version = "0.3.2"
+version = "0.3.4"
 description = "Local LinkedIn visible-connections scraper."
 requires-python = ">=3.10"
 dependencies = [
     "browser-cookie3>=0.20.1",
+    "curl-cffi>=0.16.3",
     "open-linkedin-api>=2.3.1",
     "platformdirs>=4.11.8",
 ]

{warmpath-0.3.2 → warmpath-0.3.4}/tests/test_auth.py

@@ -148,42 +148,41 @@ def test_imported_session_reaches_linkedin_with_csrf_and_cookie_attributes(reade
     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, profile_fetch):
+def test_import_and_status_print_only_the_logged_in_user(reader, capsys, auth_path, profile_fetch):
     cli.main(["auth", "import", "--browser", "Chrome"])
-    profile_fetch.assert_not_called()
+    output = capsys.readouterr()
+    assert output.out == "Logged in as Ada Lovelace\n"
+    assert output.err == ""
+    profile_fetch.assert_called_once_with("/me", timeout=15, evade=cli.no_delay)
+    profile_fetch.reset_mock()
     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 output.out.count("User: Ada Lovelace") == 1
-    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 output.out == "Logged in as Ada Lovelace\n"
     assert auth_path.read_bytes() == before
     reader.assert_not_called()
     profile_fetch.assert_called_once_with("/me", timeout=15, evade=cli.no_delay)
 
 
+@pytest.mark.parametrize("command", [["status"], ["import", "--browser", "chrome"]])
 @pytest.mark.parametrize("profile,expected", [
     ({"firstName": "  Ada ", "lastName": " Lovelace  "}, "Ada Lovelace"),
     ({"firstName": "Адель", "lastName": "Низамутдинов"}, "Адель Низамутдинов"),
     ({"firstName": "Ada"}, "Ada"),
     ({"lastName": "Lovelace"}, "Lovelace"),
 ])
-def test_status_prints_the_logged_in_users_name(profile, expected, reader, profile_fetch, capsys):
+def test_auth_prints_the_logged_in_users_name(command, profile, expected, reader, profile_fetch, capsys):
     auth.import_browser("chrome")
     profile_fetch.return_value.json.return_value = {"miniProfile": profile}
 
-    cli.main(["auth", "status"])
+    cli.main(["auth", *command])
 
-    assert f"User: {expected}\n" in capsys.readouterr().out
+    output = capsys.readouterr()
+    assert output.out == f"Logged in as {expected}\n"
+    assert output.err == ""
 
 
 @pytest.mark.parametrize("payload", [
@@ -198,11 +197,10 @@ def test_status_rejects_a_profile_without_a_name(payload, reader, profile_fetch,
     with pytest.raises(SystemExit) as error:
         cli.main(["auth", "status"])
 
-    assert error.value.code == 2
+    assert error.value.code == 1
     output = capsys.readouterr()
-    assert "LinkedIn did not return a name" in output.err
-    assert "User:" not in output.out
-    assert "private-linkedin-token" not in output.out + output.err
+    assert output.out == "Not logged in\n"
+    assert output.err == ""
 
 
 @pytest.mark.parametrize("failure", ["connection", "timeout", "http", "json"])
@@ -222,12 +220,10 @@ def test_status_handles_failed_user_lookup_without_exposing_secrets(failure, rea
     with pytest.raises(SystemExit) as error:
         cli.main(["auth", "status"])
 
-    assert error.value.code == 2
+    assert error.value.code == 1
     output = capsys.readouterr()
-    assert "Could not fetch the logged-in LinkedIn user" in output.err
-    assert "warmpath auth import --browser" in output.err
-    assert "User:" not in output.out
-    assert "private-linkedin-token" not in output.out + output.err
+    assert output.out == "Not logged in\n"
+    assert output.err == ""
     assert auth_path.read_bytes() == before
     reader.assert_not_called()
 
@@ -240,14 +236,36 @@ def test_status_reports_rejected_sessions(status_code, reader, profile_fetch, ca
     with pytest.raises(SystemExit) as error:
         cli.main(["auth", "status"])
 
-    assert error.value.code == 2
+    assert error.value.code == 1
     output = capsys.readouterr()
-    assert "LinkedIn rejected the saved session" in output.err
-    assert "warmpath auth import --browser" in output.err
-    assert "User:" not in output.out
+    assert output.out == "Not logged in\n"
+    assert output.err == ""
     profile_fetch.return_value.json.assert_not_called()
 
 
+@pytest.mark.parametrize("failure", ["rejected", "connection", "missing_name"])
+def test_failed_import_lookup_preserves_previous_session(failure, reader, browser_cookies, auth_path, profile_fetch, capsys):
+    auth.import_browser("chrome")
+    before = auth_path.read_bytes()
+    next(cookie for cookie in browser_cookies if cookie.name == "li_at").value = "new-private-token"
+    if failure == "rejected":
+        profile_fetch.return_value.status_code = 401
+    elif failure == "connection":
+        profile_fetch.side_effect = ConnectionError("new-private-token")
+    else:
+        profile_fetch.return_value.json.return_value = {}
+
+    with pytest.raises(SystemExit) as error:
+        cli.main(["auth", "import", "--browser", "chrome"])
+
+    assert error.value.code == 2
+    output = capsys.readouterr()
+    assert output.out == ""
+    assert output.err
+    assert "new-private-token" not in output.err
+    assert auth_path.read_bytes() == before
+
+
 @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()
@@ -309,7 +327,7 @@ def test_failed_save_preserves_previous_session_and_cleans_up(reader, auth_path,
 
 
 @pytest.mark.parametrize("command", [
-    ["auth", "status"], ["company", "Acme"], ["skill", "Python"],
+    ["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):
@@ -326,19 +344,34 @@ def test_missing_auth_has_import_guidance_without_browser_or_api_access(command,
     linkedin.assert_not_called()
 
 
+def test_missing_auth_status_prints_not_logged_in(reader, monkeypatch, capsys, auth_path):
+    linkedin = Mock()
+    monkeypatch.setattr(cli, "Linkedin", linkedin)
+
+    with pytest.raises(SystemExit) as error:
+        cli.main(["auth", "status"])
+
+    assert error.value.code == 1
+    output = capsys.readouterr()
+    assert output.out == "Not logged in\n"
+    assert output.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):
+def test_corrupt_store_status_prints_not_logged_in(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
+    assert error.value.code == 1
     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 output.out == "Not logged in\n"
+    assert output.err == ""
     assert auth_path.read_bytes() == content
 
 
@@ -358,7 +391,7 @@ def test_invalid_stored_cookie_is_rejected(field, value, reader, auth_path):
         auth.load_cookies()
 
 
-def test_expired_session_is_reported_and_rejected_without_reimport(reader, capsys, profile_fetch):
+def test_expired_session_is_reported_when_browser_also_has_no_valid_session(reader, capsys, profile_fetch):
     session = auth.import_browser("chrome")
     next(cookie for cookie in session.cookies if cookie.name == "li_at").expires = 1
     auth.save_auth(session)
@@ -369,19 +402,77 @@ def test_expired_session_is_reported_and_rejected_without_reimport(reader, capsy
 
     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
+    assert output.out == "Not logged in\n"
+    assert output.err == ""
 
     with pytest.raises(SystemExit) as api_error:
-        cli.build_api()
+        cli.main(["company", "Acme"])
 
     assert api_error.value.code == 2
     assert "warmpath auth import --browser chrome" in capsys.readouterr().err
-    reader.assert_not_called()
+    assert reader.call_count == 2
     profile_fetch.assert_not_called()
 
 
+def test_expired_saved_session_is_replaced_by_valid_browser_session(reader, capsys):
+    from copy import deepcopy
+
+    session = auth.import_browser("chrome")
+    session.cookies = deepcopy(session.cookies)
+    next(cookie for cookie in session.cookies if cookie.name == "li_at").expires = 1
+    auth.save_auth(session)
+    reader.reset_mock()
+
+    cli.main(["auth", "status"])
+
+    assert capsys.readouterr().out == "Logged in as Ada Lovelace\n"
+    assert not auth.load_auth().missing_cookies()
+    reader.assert_called_once_with(domain_name="linkedin.com")
+
+
+def test_import_keeps_linkedin_device_security_and_routing_cookies(reader, browser_cookies):
+    for name in ("bcookie", "bscookie", "lidc", "liap", "dfpfpt", "fptctx2"):
+        browser_cookies.set(name, f"value-for-{name}", domain=".linkedin.com", secure=True)
+
+    auth.import_browser("chrome")
+
+    saved = auth.load_cookies()
+    for name in ("bcookie", "bscookie", "lidc", "liap", "dfpfpt", "fptctx2"):
+        assert saved.get(name) == f"value-for-{name}"
+
+
+def test_import_persists_browser_user_agent(reader, monkeypatch):
+    monkeypatch.setattr(auth, "browser_user_agent", lambda browser: "Browser/152.0.0.0")
+
+    auth.import_browser("chrome")
+
+    assert auth.load_auth().user_agent == "Browser/152.0.0.0"
+
+
+def test_chrome_user_agent_uses_installed_major_version(monkeypatch):
+    import plistlib
+
+    monkeypatch.setattr(auth.sys, "platform", "darwin")
+    monkeypatch.setattr(Path, "read_bytes", lambda self: plistlib.dumps({"CFBundleShortVersionString": "152.0.7977.83"}))
+
+    agent = auth.browser_user_agent("chrome")
+
+    assert agent is not None
+    assert "Chrome/152.0.0.0" in agent
+    assert "Macintosh; Intel Mac OS X 10_15_7" in agent
+
+
+@pytest.mark.parametrize("value", ["Browser\r\nInjected: private-token", "", 123, ["Browser"]])
+def test_invalid_stored_user_agent_is_rejected(value, reader, auth_path):
+    auth.import_browser("chrome")
+    payload = json.loads(auth_path.read_text())
+    payload["user_agent"] = value
+    auth_path.write_text(json.dumps(payload))
+
+    with pytest.raises(auth.AuthError, match="saved LinkedIn session is invalid"):
+        auth.load_auth()
+
+
 @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: