linkedin-search-core 0.1.0__tar.gz

linkedin_search_core-0.1.0/.gitignore

@@ -0,0 +1,39 @@
+cookies.json
+cookies*.json
+storage_state.json
+session_snapshot.json
+*.session
+linkedin-session*
+credentials.json
+secrets.json
+.secrets
+posts.json
+selected_posts.json
+worker/results/*.json
+.env
+.venv/
+venv/
+__pycache__/
+*.pyc
+*.pyo
+*.egg-info/
+*.egg
+dist/
+build/
+**/dist/
+**/build/
+**/*.egg-info/
+.pytest_cache/
+
+# Cursor debug session logs
+**/.cursor/debug-*.log
+
+# Frontend (Next.js)
+frontend/node_modules/
+frontend/.next/
+frontend/.vercel/
+frontend/.env.local
+frontend/.env.*.local
+
+# Local tools (portable Node, etc.)
+.tools/

linkedin_search_core-0.1.0/LICENSE

@@ -0,0 +1,3 @@
+Proprietary. All rights reserved.
+This software is licensed for use by the copyright holder only.
+Redistribution or publication without permission is not allowed.

linkedin_search_core-0.1.0/PKG-INFO

@@ -0,0 +1,67 @@
+Metadata-Version: 2.5
+Name: linkedin-search-core
+Version: 0.1.0
+Summary: Shared Playwright session, authentication, and errors for LinkedIn search.
+Project-URL: Homepage, https://github.com/vkudymov/linkedin-pulse-reader-v.3
+Project-URL: Repository, https://github.com/vkudymov/linkedin-pulse-reader-v.3
+Project-URL: Issues, https://github.com/vkudymov/linkedin-pulse-reader-v.3/issues
+Author: LinkedIn Pulse Reader
+Maintainer: LinkedIn Pulse Reader
+License: Proprietary
+License-File: LICENSE
+Keywords: linkedin,playwright,session
+Classifier: Development Status :: 3 - Alpha
+Classifier: Intended Audience :: Developers
+Classifier: License :: Other/Proprietary License
+Classifier: Operating System :: OS Independent
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Typing :: Typed
+Requires-Python: >=3.11
+Requires-Dist: playwright>=1.49.0
+Provides-Extra: dev
+Requires-Dist: pytest>=8.0.0; extra == 'dev'
+Description-Content-Type: text/markdown
+
+# linkedin-search-core
+
+## Description
+
+Shared LinkedIn browser session for search libraries. This package opens Chromium through Playwright, restores a session, and runs interactive login. It does not search jobs or posts.
+
+Requires Python 3.11+.
+
+## Installation
+
+```bash
+pip install linkedin-search-core
+```
+
+Local editable install from this monorepo:
+
+```bash
+pip install -e packages/linkedin-search-core
+```
+
+## Dependencies
+
+- `playwright>=1.49.0`
+- `session-snapshot` is optional. Import it in the same environment when you restore or export a full Chrome session snapshot. Without it, cookie-only login still works.
+
+## Usage
+
+```python
+from linkedin_search_core import LinkedInSession
+
+with LinkedInSession(cookies=cookies, headless=True) as session:
+    print(session.is_logged_in())
+```
+
+## API
+
+- `LinkedInSession` — context manager for the browser session (`login_and_get_cookies`, `get_cookies`, `export_session_snapshot`, `is_logged_in`)
+- `LinkedInClientConfig`, `BrowserConfig`, `LoginMethod`
+- `UserIdentity`
+- Errors: `LinkedInClientError`, `BrowserLifecycleError`, `CookieFormatError`, `LoginRequiredError`, `LoginTimeoutError`, `LoginCheckpointError`, `LoginCancelledError`, `FeedLoadError`, `PostParseError`

linkedin_search_core-0.1.0/README.md

@@ -0,0 +1,40 @@
+# linkedin-search-core
+
+## Description
+
+Shared LinkedIn browser session for search libraries. This package opens Chromium through Playwright, restores a session, and runs interactive login. It does not search jobs or posts.
+
+Requires Python 3.11+.
+
+## Installation
+
+```bash
+pip install linkedin-search-core
+```
+
+Local editable install from this monorepo:
+
+```bash
+pip install -e packages/linkedin-search-core
+```
+
+## Dependencies
+
+- `playwright>=1.49.0`
+- `session-snapshot` is optional. Import it in the same environment when you restore or export a full Chrome session snapshot. Without it, cookie-only login still works.
+
+## Usage
+
+```python
+from linkedin_search_core import LinkedInSession
+
+with LinkedInSession(cookies=cookies, headless=True) as session:
+    print(session.is_logged_in())
+```
+
+## API
+
+- `LinkedInSession` — context manager for the browser session (`login_and_get_cookies`, `get_cookies`, `export_session_snapshot`, `is_logged_in`)
+- `LinkedInClientConfig`, `BrowserConfig`, `LoginMethod`
+- `UserIdentity`
+- Errors: `LinkedInClientError`, `BrowserLifecycleError`, `CookieFormatError`, `LoginRequiredError`, `LoginTimeoutError`, `LoginCheckpointError`, `LoginCancelledError`, `FeedLoadError`, `PostParseError`

linkedin_search_core-0.1.0/pyproject.toml

@@ -0,0 +1,51 @@
+[build-system]
+requires = ["hatchling>=1.21.0"]
+build-backend = "hatchling.build"
+
+[project]
+name = "linkedin-search-core"
+version = "0.1.0"
+description = "Shared Playwright session, authentication, and errors for LinkedIn search."
+readme = "README.md"
+requires-python = ">=3.11"
+license = { text = "Proprietary" }
+authors = [{ name = "LinkedIn Pulse Reader" }]
+maintainers = [{ name = "LinkedIn Pulse Reader" }]
+keywords = ["linkedin", "playwright", "session"]
+classifiers = [
+  "Development Status :: 3 - Alpha",
+  "Intended Audience :: Developers",
+  "License :: Other/Proprietary License",
+  "Operating System :: OS Independent",
+  "Programming Language :: Python :: 3",
+  "Programming Language :: Python :: 3.11",
+  "Programming Language :: Python :: 3.12",
+  "Programming Language :: Python :: 3.13",
+  "Typing :: Typed",
+]
+dependencies = [
+  "playwright>=1.49.0",
+]
+
+[project.urls]
+Homepage = "https://github.com/vkudymov/linkedin-pulse-reader-v.3"
+Repository = "https://github.com/vkudymov/linkedin-pulse-reader-v.3"
+Issues = "https://github.com/vkudymov/linkedin-pulse-reader-v.3/issues"
+
+[project.optional-dependencies]
+dev = [
+  "pytest>=8.0.0",
+]
+
+[tool.hatch.build.targets.sdist]
+include = [
+  "/src",
+  "/README.md",
+  "/LICENSE",
+]
+
+[tool.hatch.build.targets.wheel]
+packages = ["src/linkedin_search_core"]
+
+[tool.pytest.ini_options]
+testpaths = ["tests"]

linkedin_search_core-0.1.0/src/linkedin_search_core/__init__.py

@@ -0,0 +1,35 @@
+"""Shared LinkedIn browser session, auth, and errors."""
+
+from .auth.methods import LoginMethod
+from .browser.config import BrowserConfig
+from .config import LinkedInClientConfig
+from .exceptions import (
+    BrowserLifecycleError,
+    CookieFormatError,
+    FeedLoadError,
+    LinkedInClientError,
+    LoginCancelledError,
+    LoginCheckpointError,
+    LoginRequiredError,
+    LoginTimeoutError,
+    PostParseError,
+)
+from .models.user import UserIdentity
+from .session import LinkedInSession
+
+__all__ = [
+    "BrowserConfig",
+    "BrowserLifecycleError",
+    "CookieFormatError",
+    "FeedLoadError",
+    "LinkedInClientConfig",
+    "LinkedInClientError",
+    "LinkedInSession",
+    "LoginCancelledError",
+    "LoginCheckpointError",
+    "LoginMethod",
+    "LoginRequiredError",
+    "LoginTimeoutError",
+    "PostParseError",
+    "UserIdentity",
+]

linkedin_search_core-0.1.0/src/linkedin_search_core/auth/__init__.py

@@ -0,0 +1,13 @@
+"""
+RU: Auth boundary.
+    В этом пакете собраны механизмы восстановления сессии через session_snapshot и manual login.
+    Хранение сессии — ответственность внешнего приложения.
+
+EN: Auth boundary.
+    This package contains session restoration via session_snapshot and manual login.
+    Persistence belongs to the calling application.
+"""
+
+from .methods import LoginMethod
+
+__all__ = ["LoginMethod"]

linkedin_search_core-0.1.0/src/linkedin_search_core/auth/email_password.py

@@ -0,0 +1,69 @@
+from __future__ import annotations
+
+from collections.abc import Callable
+from dataclasses import dataclass
+
+from playwright.sync_api import BrowserContext, Page
+
+from .wait import SessionWaitConfig, wait_for_session
+
+
+@dataclass(frozen=True, slots=True)
+class EmailPasswordLoginParams:
+    identifier: str | None
+    password: str | None
+
+
+class EmailPasswordLoginFlow:
+    """
+    Best-effort email/phone + password automation for LinkedIn login form.
+
+    If params are missing, the flow keeps the UI open and only waits for the user
+    to complete login (same behavior as manual flow).
+    """
+
+    def __init__(
+        self,
+        *,
+        timeout_ms: int,
+        params: EmailPasswordLoginParams,
+        cancelled: Callable[[], bool] | None = None,
+        on_checkpoint: Callable[[], None] | None = None,
+    ) -> None:
+        self._timeout_ms = timeout_ms
+        self._params = params
+        self._cancelled = cancelled
+        self._on_checkpoint = on_checkpoint
+
+    def run(self, page: Page, context: BrowserContext) -> None:
+        identifier = (self._params.identifier or "").strip()
+        password = self._params.password or ""
+
+        if identifier and password:
+            self._fill_and_submit(page, identifier=identifier, password=password)
+
+        wait_for_session(
+            page,
+            cfg=SessionWaitConfig(
+                timeout_ms=self._timeout_ms,
+                cancelled=self._cancelled,
+                on_checkpoint=self._on_checkpoint,
+            ),
+        )
+
+    @staticmethod
+    def _fill_and_submit(page: Page, *, identifier: str, password: str) -> None:
+        # LinkedIn uses slightly different selectors depending on the variant of login page.
+        user_sel = "input#username, input[name='session_key']"
+        pass_sel = "input#password, input[name='session_password']"
+
+        page.wait_for_selector(user_sel, timeout=10_000)
+        page.locator(user_sel).first.fill(identifier)
+        page.locator(pass_sel).first.fill(password)
+
+        # Submit: prefer explicit button, fallback to form submit.
+        if page.locator("button[type='submit']").count() > 0:
+            page.locator("button[type='submit']").first.click()
+        else:
+            page.keyboard.press("Enter")
+

linkedin_search_core-0.1.0/src/linkedin_search_core/auth/methods.py

@@ -0,0 +1,10 @@
+from __future__ import annotations
+
+from enum import StrEnum
+
+
+class LoginMethod(StrEnum):
+    email = "email"
+    google = "google"
+    apple = "apple"
+

linkedin_search_core-0.1.0/src/linkedin_search_core/auth/social.py

@@ -0,0 +1,107 @@
+from __future__ import annotations
+
+import re
+from collections.abc import Callable
+from contextlib import suppress
+from dataclasses import dataclass
+
+from playwright.sync_api import BrowserContext, Page, TimeoutError as PlaywrightTimeoutError
+
+from .methods import LoginMethod
+from .wait import SessionWaitConfig, wait_for_session
+
+
+@dataclass(frozen=True, slots=True)
+class SocialLoginParams:
+    method: LoginMethod
+
+
+class SocialLoginFlow:
+    """
+    Social provider login entry (Google / Apple) on the LinkedIn login page.
+
+    The OAuth step is intentionally interactive: the user may need to complete
+    CAPTCHA/2FA in the opened browser. This flow only clicks the provider button
+    and waits until LinkedIn feed becomes available.
+    """
+
+    def __init__(
+        self,
+        *,
+        timeout_ms: int,
+        params: SocialLoginParams,
+        cancelled: Callable[[], bool] | None = None,
+        on_checkpoint: Callable[[], None] | None = None,
+    ) -> None:
+        self._timeout_ms = timeout_ms
+        self._params = params
+        self._cancelled = cancelled
+        self._on_checkpoint = on_checkpoint
+
+    def run(self, page: Page, context: BrowserContext) -> None:
+        # LinkedIn can open OAuth in a popup or do a same-tab redirect.
+        # We click once and (best-effort) capture the popup if it appears.
+        with suppress(PlaywrightTimeoutError):
+            with context.expect_page(timeout=2_000) as pinfo:
+                self._click_provider_button(page)
+            popup = pinfo.value
+            with suppress(Exception):
+                popup.bring_to_front()
+
+        wait_for_session(
+            page,
+            cfg=SessionWaitConfig(
+                timeout_ms=self._timeout_ms,
+                cancelled=self._cancelled,
+                on_checkpoint=self._on_checkpoint,
+            ),
+        )
+
+    def _click_provider_button(self, page: Page) -> None:
+        name_rx = self._provider_button_name_regex()
+
+        # Prefer accessible role-based selectors.
+        with suppress(Exception):
+            btn = page.get_by_role("button", name=name_rx)
+            if btn.count() > 0:
+                btn.first.click()
+                return
+
+        # Fallback selectors observed on some LinkedIn variants.
+        candidates = self._provider_fallback_selectors()
+        for sel in candidates:
+            with suppress(Exception):
+                loc = page.locator(sel)
+                if loc.count() > 0:
+                    loc.first.click()
+                    return
+
+        # Last resort: click by text.
+        with suppress(Exception):
+            page.get_by_text(name_rx).first.click()
+            return
+
+        raise RuntimeError(f"Could not find LinkedIn {self._params.method} login button.")
+
+    def _provider_button_name_regex(self) -> re.Pattern[str]:
+        if self._params.method == LoginMethod.google:
+            return re.compile(r"(continue|sign)\s+in\s+with\s+google", re.IGNORECASE)
+        if self._params.method == LoginMethod.apple:
+            return re.compile(r"(continue|sign)\s+in\s+with\s+apple", re.IGNORECASE)
+        return re.compile(r".*", re.IGNORECASE)
+
+    def _provider_fallback_selectors(self) -> list[str]:
+        if self._params.method == LoginMethod.google:
+            return [
+                "button[data-tracking-control-name*='google']",
+                "button[aria-label*='Google' i]",
+                "a[data-tracking-control-name*='google']",
+            ]
+        if self._params.method == LoginMethod.apple:
+            return [
+                "button[data-tracking-control-name*='apple']",
+                "button[aria-label*='Apple' i]",
+                "a[data-tracking-control-name*='apple']",
+            ]
+        return []
+

linkedin_search_core-0.1.0/src/linkedin_search_core/auth/wait.py

@@ -0,0 +1,114 @@
+from __future__ import annotations
+
+from collections.abc import Callable
+from contextlib import suppress
+from dataclasses import dataclass
+from time import monotonic
+from urllib.parse import urlparse
+
+from playwright.sync_api import Page, TimeoutError as PlaywrightTimeoutError
+
+from ..exceptions import LoginCancelledError, LoginCheckpointError, LoginTimeoutError
+
+
+@dataclass(frozen=True, slots=True)
+class SessionWaitConfig:
+    timeout_ms: int
+    cancelled: Callable[[], bool] | None = None
+    on_checkpoint: Callable[[], None] | None = None
+    raise_on_checkpoint: bool = False
+
+
+def wait_for_session(page: Page, *, cfg: SessionWaitConfig) -> None:
+    """
+    Wait until LinkedIn session becomes authenticated (feed redirect/layout).
+
+    This is intentionally best-effort and UI-driven:
+    - If LinkedIn redirects to /feed, cookies are usable.
+    - If LinkedIn shows checkpoint/challenge, the user must complete it.
+    """
+    deadline = monotonic() + max(cfg.timeout_ms, 0) / 1000.0
+    checkpoint_notified = False
+
+    while monotonic() < deadline:
+        if cfg.cancelled is not None and cfg.cancelled():
+            raise LoginCancelledError("Login flow cancelled by caller.")
+
+        url = _safe_url(page)
+        if _is_logged_in_url(url):
+            return
+
+        if _is_linkedin_url(url) and (_is_checkpoint_url(url) or _looks_like_checkpoint_page(page)):
+            if cfg.raise_on_checkpoint and cfg.on_checkpoint is None:
+                raise LoginCheckpointError(
+                    "LinkedIn requires verification (checkpoint). "
+                    "Complete it in the opened browser window."
+                )
+            if not checkpoint_notified:
+                checkpoint_notified = True
+                if cfg.on_checkpoint is not None:
+                    with suppress(Exception):
+                        cfg.on_checkpoint()
+
+        remaining_ms = int(max(0.0, (deadline - monotonic()) * 1000.0))
+        slice_ms = min(1500, remaining_ms) if remaining_ms else 0
+
+        # Prefer URL-based signal, but don't block for the entire timeout in one call.
+        if slice_ms:
+            with suppress(PlaywrightTimeoutError):
+                page.wait_for_url("**/feed/**", timeout=slice_ms)
+                if _is_logged_in_url(_safe_url(page)):
+                    return
+
+        # If nothing happened, yield a bit to allow the page to update.
+        with suppress(Exception):
+            page.wait_for_timeout(250)
+
+    raise LoginTimeoutError(
+        "Login did not complete in time. Complete authentication in the opened browser window."
+    )
+
+
+def _safe_url(page: Page) -> str:
+    try:
+        return (page.url or "").strip()
+    except Exception:
+        return ""
+
+
+def _is_logged_in_url(url: str) -> bool:
+    lowered = url.lower()
+    return (
+        "linkedin.com/feed" in lowered
+        and "/checkpoint" not in lowered
+        and "/login" not in lowered
+        and "/authwall" not in lowered
+        and "linkedin.com/uas/" not in lowered
+    )
+
+
+def _is_checkpoint_url(url: str) -> bool:
+    lowered = url.lower()
+    return "/checkpoint" in lowered or "/challenge" in lowered
+
+
+def _is_linkedin_url(url: str) -> bool:
+    try:
+        host = (urlparse(url).hostname or "").lower()
+        return host.endswith("linkedin.com") or host.endswith("www.linkedin.com")
+    except Exception:
+        return False
+
+
+def _looks_like_checkpoint_page(page: Page) -> bool:
+    # Keep selectors conservative and LinkedIn-specific.
+    try:
+        return (
+            page.locator(
+                "form[action*='checkpoint'], input[name='challengeId'], input[name='pin']"
+            ).count()
+            > 0
+        )
+    except Exception:
+        return False
+

linkedin_search_core-0.1.0/src/linkedin_search_core/browser/__init__.py

@@ -0,0 +1,13 @@
+"""
+RU: Platform/browser layer.
+    Инкапсулирует lifecycle Playwright/Chromium и runtime-настройки браузера.
+
+EN: Platform/browser layer.
+    Encapsulates Playwright/Chromium lifecycle and browser runtime configuration.
+"""
+
+from .config import BrowserConfig
+from .manager import BrowserManager
+
+__all__ = ["BrowserConfig", "BrowserManager"]
+

linkedin_search_core-0.1.0/src/linkedin_search_core/browser/config.py

@@ -0,0 +1,37 @@
+from __future__ import annotations
+
+from dataclasses import dataclass
+
+
+@dataclass(frozen=True, slots=True)
+class BrowserConfig:
+    """
+    RU: Настройки runtime-окружения браузера (platform policy).
+        Держим их отдельно от фич-логики, чтобы управление запуском Chromium было централизованным.
+
+    EN: Browser runtime settings (platform policy).
+        Kept separate from feature logic so Chromium startup policy is centralized.
+    """
+    headless: bool = True
+    timeout_ms: int = 30_000
+
+    locale: str | None = "en-US"
+    timezone_id: str | None = None
+    user_agent: str | None = None
+
+    viewport_width: int = 1365
+    viewport_height: int = 768
+
+    slow_mo_ms: int | None = None
+
+    # Prefer real Chrome for social auth (Google/Apple) where Chromium automation can be blocked.
+    # Example: "chrome", "msedge". When not available, the library falls back to default chromium.
+    channel: str | None = None
+
+    # Extra launch args passed to Playwright. Keep optional to avoid breaking defaults.
+    launch_args: list[str] | None = None
+
+    # When set, Playwright will use a persistent browser profile (user-data-dir).
+    # This is important for Google OAuth flows that block automated ephemeral contexts.
+    user_data_dir: str | None = None
+