async_linkedinlib 0.2.0__py3-none-any.whl

async_linkedinlib/session/state.py

@@ -0,0 +1,129 @@
+"""Scoped cookies and atomic, private session persistence."""
+
+import json
+import os
+import tempfile
+import time
+from dataclasses import asdict
+from dataclasses import dataclass
+from dataclasses import field
+from pathlib import Path
+from uuid import uuid4
+
+import httpx
+
+from ..config import ClientProfile
+from ..exceptions import SessionError
+from .cookies import SessionCookie
+
+
+@dataclass(slots=True, repr=False)
+class Session:
+    """Local credential presence is not proof that LinkedIn still accepts the session."""
+
+    device_id: str = field(default_factory=lambda: str(uuid4()))
+    profile: ClientProfile = field(default_factory=ClientProfile)
+    cookies: list[SessionCookie] = field(default_factory=list)
+    member_id: str | None = None
+    rate_limit_until: float = 0.0
+
+    def __repr__(self) -> str:
+        return f"Session(authenticated={self.authenticated})"
+
+    @property
+    def authenticated(self) -> bool:
+        return bool(self.cookie_value("li_at") and self.cookie_value("JSESSIONID"))
+
+    def cookie_value(self, name: str, path: str = "/") -> str | None:
+        valid = [
+            cookie
+            for cookie in self.cookies
+            if cookie.name == name
+            and (cookie.expires is None or cookie.expires > time.time())
+            and (path == cookie.path or path.startswith(cookie.path.rstrip("/") + "/"))
+            and (not cookie.host_only or cookie.domain == "www.linkedin.com")
+        ]
+        if not valid:
+            return None
+        # Prefer the most specific matching cookie, including a host-specific cookie.
+        cookie = max(valid, key=lambda c: (len(c.path), len(c.domain.lstrip("."))))
+        return cookie.value
+
+    def clear_authentication(self) -> None:
+        self.cookies = [c for c in self.cookies if c.name != "li_at"]
+        self.member_id = None
+
+    def to_httpx(self) -> httpx.Cookies:
+        jar = httpx.Cookies()
+        for cookie in self.cookies:
+            jar.jar.set_cookie(cookie.to_cookie())
+        return jar
+
+    def update_cookies(self, jar: httpx.Cookies) -> None:
+        self.cookies = [
+            SessionCookie(
+                name=c.name,
+                value=c.value or "",
+                domain=c.domain,
+                path=c.path,
+                secure=c.secure,
+                expires=c.expires,
+                host_only=not c.domain_specified,
+            )
+            for c in jar.jar
+            if c.domain.lstrip(".") in {"linkedin.com", "www.linkedin.com"}
+        ]
+
+    @classmethod
+    def from_cookies(cls, li_at: str, jsessionid: str) -> "Session":
+        """Import your own session cookie pair; accepts JSESSIONID with or without quotes."""
+        if not li_at.strip() or not jsessionid.strip().strip('"'):
+            raise SessionError("Both li_at and JSESSIONID are required.")
+        csrf = jsessionid.strip().strip('"')
+        return cls(
+            cookies=[
+                SessionCookie("li_at", li_at.strip(), ".www.linkedin.com"),
+                SessionCookie("JSESSIONID", f'"{csrf}"', ".www.linkedin.com"),
+            ]
+        )
+
+    def save(self, path: str | Path) -> None:
+        """Atomically write mode 0600; credentials are never printed or put in errors."""
+        destination = Path(path).expanduser()
+        destination.parent.mkdir(parents=True, exist_ok=True, mode=0o700)
+        temporary = None
+        try:
+            with tempfile.NamedTemporaryFile(
+                mode="w", encoding="utf-8", dir=destination.parent, delete=False
+            ) as stream:
+                temporary = stream.name
+                os.fchmod(stream.fileno(), 0o600)
+                json.dump({"schema_version": 1, **asdict(self)}, stream, indent=2)
+                stream.flush()
+                os.fsync(stream.fileno())
+            os.replace(temporary, destination)
+        finally:
+            if temporary and os.path.exists(temporary):
+                os.unlink(temporary)
+
+    @classmethod
+    def load(cls, path: str | Path) -> "Session":
+        """Load supported state without silently replacing corrupt files or expired tokens."""
+        try:
+            data = json.loads(Path(path).expanduser().read_text())
+            if data.pop("schema_version") != 1:
+                raise ValueError
+            profile = ClientProfile(**data.pop("profile"))
+            cookies = [SessionCookie(**cookie) for cookie in data.pop("cookies")]
+            state = cls(profile=profile, cookies=cookies, **data)
+            if (
+                not isinstance(state.device_id, str)
+                or not state.device_id
+                or any(ch in state.device_id for ch in "\r\n")
+                or not isinstance(state.rate_limit_until, (float, int))
+                or (state.member_id is not None and not isinstance(state.member_id, str))
+            ):
+                raise ValueError
+            return state
+        except (ValueError, TypeError, KeyError, AttributeError, SessionError):
+            raise SessionError("Invalid or unsupported LinkedIn session file.") from None

async_linkedinlib/transport/__init__.py

@@ -0,0 +1,6 @@
+"""Transport public exports."""
+
+from .http import Transport  # Shared HTTP exchange and cookie rotation.
+from .voyager import Voyager  # Voyager GraphQL and rest.li calls over the transport.
+
+__all__ = ["Transport", "Voyager"]

async_linkedinlib/transport/http.py

@@ -0,0 +1,183 @@
+"""Origin-bound HTTP exchanges with cookie rotation, cooldowns, and no automatic retries."""
+
+import asyncio
+import time
+from collections.abc import Mapping
+from datetime import UTC
+from datetime import datetime
+from email.utils import parsedate_to_datetime
+from pathlib import Path
+from typing import Any
+from urllib.parse import unquote
+from urllib.parse import urlsplit
+
+import httpx
+
+from ..config import ClientOptions
+from ..exceptions import AuthenticationError
+from ..exceptions import ChallengeRequired
+from ..exceptions import HTTPError
+from ..exceptions import NetworkError
+from ..exceptions import ProtocolError
+from ..exceptions import RateLimited
+from ..session import Session
+
+ORIGIN = "https://www.linkedin.com"
+
+
+class Transport:
+    """Own the connection pool and serialize updates to one account's cookie jar."""
+
+    def __init__(
+        self,
+        session: Session,
+        options: ClientOptions,
+        transport: httpx.AsyncBaseTransport | None = None,
+    ) -> None:
+        self.session = session
+        self.session_file: Path | None = None
+        self._lock = asyncio.Lock()
+        self._closed = False
+        self._client = httpx.AsyncClient(
+            timeout=options.timeout,
+            http2=True,
+            trust_env=False,
+            follow_redirects=False,
+            limits=httpx.Limits(max_connections=options.max_connections),
+            transport=transport,
+        )
+
+    async def request(
+        self,
+        method: str,
+        path: str,
+        data: Mapping[str, str] | None = None,
+        *,
+        json: object | None = None,
+        content: bytes | None = None,
+        headers: Mapping[str, str] | None = None,
+    ) -> httpx.Response:
+        """Send one exchange.
+
+        `json` bodies and extra headers serve the Voyager API; `content` sends raw upload
+        bytes (set its content-type in `headers`).
+        """
+        if not path.startswith("/") or path.startswith("//") or "#" in path:
+            raise ValueError("A LinkedIn origin-relative path is required.")
+        if sum(body is not None for body in (data, json, content)) > 1:
+            raise ValueError("Send one body: form data, JSON or raw content.")
+        async with self._lock:
+            if self._closed:
+                raise RuntimeError("LinkedIn client is closed.")
+            remaining = self.session.rate_limit_until - time.time()
+            if remaining > 0:
+                raise RateLimited(remaining)
+            sent = self.session.profile.auth_headers(self.session.device_id)
+            csrf = self.session.cookie_value("JSESSIONID", path)
+            if csrf:
+                sent["csrf-token"] = csrf.strip('"')
+            if path == "/mob/tracking":
+                sent = {"user-agent": self.session.profile.user_agent}
+            sent.update(headers or {})
+            self._client.cookies = self.session.to_httpx()
+            try:
+                response = await self._client.request(
+                    method,
+                    ORIGIN + path,
+                    headers=sent,
+                    data=data,
+                    json=json,
+                    content=content,
+                )
+            except httpx.RequestError:
+                raise NetworkError("LinkedIn request failed and was not retried.") from None
+            finally:
+                self.session.update_cookies(self._client.cookies)
+                self.checkpoint()
+            if response.status_code == 429:
+                delay = self._retry_after(response.headers.get("retry-after"))
+                self.session.rate_limit_until = time.time() + delay
+                self.checkpoint()
+                raise RateLimited(delay)
+            if response.status_code == 401:
+                self.session.clear_authentication()
+                self.checkpoint()
+                raise AuthenticationError("LinkedIn rejected the session or credentials.")
+            if response.status_code == 403:
+                raise ChallengeRequired()
+            if 300 <= response.status_code < 400:
+                raise ProtocolError("LinkedIn returned a redirect; it was not followed.")
+            if response.status_code >= 400:
+                raise HTTPError(response.status_code, self._service_message(response))
+            return response
+
+    @staticmethod
+    def upload_path(url: object, prefix: str) -> str | None:
+        """The origin path of an upload URL LinkedIn handed out, or None if it is not ours.
+
+        Only https://www.linkedin.com URLs under `prefix` qualify; dot segments (also
+        percent-encoded) are refused because the HTTP client would resolve them elsewhere.
+        """
+        if not isinstance(url, str):
+            return None
+        parts = urlsplit(url)
+        segments = unquote(parts.path).split("/")
+        if (
+            parts.scheme != "https"
+            or parts.netloc != "www.linkedin.com"
+            or not parts.path.startswith(prefix)
+            or "." in segments
+            or ".." in segments
+            or "\\" in parts.path
+        ):
+            return None
+        return parts.path + (f"?{parts.query}" if parts.query else "")
+
+    def checkpoint(self) -> None:
+        if self.session_file is not None:
+            self.session.save(self.session_file)
+
+    @staticmethod
+    def json_object(response: httpx.Response) -> dict[str, Any]:
+        try:
+            data = response.json()
+        except ValueError:
+            raise ProtocolError("LinkedIn returned an unsupported response format.") from None
+        if not isinstance(data, dict):
+            raise ProtocolError("LinkedIn returned an unsupported response shape.")
+        return data
+
+    @staticmethod
+    def _service_message(response: httpx.Response) -> str | None:
+        """Rest.li's short client-error reason; server traces and bodies are never kept."""
+        if not 400 <= response.status_code < 500:
+            return None
+        try:
+            data = response.json()
+        except ValueError:
+            return None
+        message = data.get("message") if isinstance(data, dict) else None
+        if isinstance(message, str) and message and "\n" not in message:
+            return message[:300]
+        return None
+
+    @staticmethod
+    def _retry_after(value: str | None) -> float:
+        if value:
+            try:
+                return max(0.0, float(int(value)))
+            except ValueError:
+                try:
+                    date = parsedate_to_datetime(value)
+                    if date.tzinfo is None:
+                        date = date.replace(tzinfo=UTC)
+                    return max(0.0, (date - datetime.now(UTC)).total_seconds())
+                except (ValueError, TypeError, OverflowError):
+                    pass
+        return 60.0
+
+    async def aclose(self) -> None:
+        async with self._lock:
+            if not self._closed:
+                self._closed = True
+                await self._client.aclose()

async_linkedinlib/transport/restli.py

@@ -0,0 +1,46 @@
+"""Rest.li 2.0 URL encoding, as the app's DataEncoder writes GraphQL variables."""
+
+import re
+from collections.abc import Mapping
+from collections.abc import Sequence
+from decimal import Decimal
+from urllib.parse import quote
+
+# Rest.li reserves these characters inside values; they and '%' become %XX first.
+_RESERVED = frozenset("(:),'%")
+# Android's Uri.encode keeps these (plus '%', so the rest.li escapes survive).
+_URI_SAFE = "-_.!~*'()%"
+
+
+def encode(value: object) -> str:
+    """Encode records as `(k:v)`, lists as `List(a,b)`, strings escaped and percent-encoded."""
+    if isinstance(value, bool):
+        return "true" if value else "false"
+    if isinstance(value, int):
+        return str(value)
+    if isinstance(value, float):
+        if value != value or value in (float("inf"), float("-inf")):
+            raise ValueError("Rest.li values must be finite numbers.")
+        # Plain decimal notation: an exponent's '+' would read as a space in a URL.
+        return format(Decimal(repr(value)), "f")
+    if isinstance(value, str):
+        return _string(value)
+    if isinstance(value, Mapping):
+        parts = []
+        for key, item in value.items():
+            # Keys are written verbatim, as the app does, so they must be plain identifiers.
+            if not isinstance(key, str) or not re.fullmatch(r"[A-Za-z_][A-Za-z0-9_$]*", key):
+                raise ValueError("Rest.li record keys must be identifiers.")
+            if item is not None:
+                parts.append(f"{key}:{encode(item)}")
+        return "(" + ",".join(parts) + ")"
+    if isinstance(value, Sequence) and not isinstance(value, bytes | bytearray):
+        return "List(" + ",".join(encode(item) for item in value) + ")"
+    raise ValueError(f"Rest.li cannot encode {type(value).__name__} values.")
+
+
+def _string(value: str) -> str:
+    if not value:
+        return "''"
+    escaped = "".join(f"%{ord(ch):02X}" if ch in _RESERVED else ch for ch in value)
+    return quote(escaped, safe=_URI_SAFE)

async_linkedinlib/transport/voyager.py

@@ -0,0 +1,151 @@
+"""The Voyager JSON API: persisted GraphQL operations and rest.li resources.
+
+The Android app ships these operations and asks for protobuf; the same routes answer plain
+JSON when asked, so requests carry `accept: application/json` and JSON bodies.
+"""
+
+import re
+from collections.abc import Mapping
+from dataclasses import dataclass
+from typing import Any
+
+from ..exceptions import OperationRejected
+from ..exceptions import ProtocolError
+from . import restli
+from .http import Transport
+
+_JSON = {"accept": "application/json"}
+_GRAPHQL = {"accept": "application/json", "x-li-graphql-pegasus-client": "true"}
+
+
+@dataclass(frozen=True, slots=True)
+class GraphQLQuery:
+    """One persisted GraphQL operation from the app: query ID plus operation name."""
+
+    id: str
+    name: str
+
+    def __post_init__(self) -> None:
+        if not re.fullmatch(r"voyager[A-Za-z]+\.[0-9a-f]{32}", self.id):
+            raise ValueError("GraphQL query IDs look like voyagerName.<32 hex digits>.")
+        if not re.fullmatch(r"[A-Za-z][A-Za-z0-9]*", self.name):
+            raise ValueError("GraphQL operation names are identifiers.")
+
+
+@dataclass(frozen=True, slots=True)
+class Reply:
+    """A rest.li reply: its JSON object (empty when none) and the created entity's ID."""
+
+    data: dict[str, Any]
+    created_id: str | None = None
+
+
+class Voyager:
+    """Voyager calls over the client's one transport; no retries, no hidden paging."""
+
+    def __init__(self, transport: Transport) -> None:
+        self.transport = transport
+
+    @property
+    def owner(self) -> str:
+        """The session's device ID, which ties page cursors to this session."""
+        return self.transport.session.device_id
+
+    async def query(
+        self,
+        query: GraphQLQuery,
+        variables: Mapping[str, object] | None = None,
+        *,
+        ignore_null_field_errors: bool = False,
+    ) -> dict[str, Any]:
+        """Run a read and return its `data` object.
+
+        Some finders report a null in a field they declare non-null next to complete data.
+        `ignore_null_field_errors` accepts those replies; any other error still raises.
+        """
+        params = f"variables={restli.encode(variables)}&" if variables else ""
+        path = f"/voyager/api/graphql?{params}queryId={query.id}&queryName={query.name}"
+        response = await self.transport.request("GET", path, headers=_GRAPHQL)
+        envelope = self.transport.json_object(response)
+        if ignore_null_field_errors and isinstance(envelope.get("data"), dict):
+            errors = envelope.get("errors")
+            if isinstance(errors, list) and all(map(_null_field_error, errors)):
+                envelope = {"data": envelope["data"]}
+        return _graphql_data(envelope)
+
+    async def mutate(self, query: GraphQLQuery, variables: Mapping[str, object]) -> dict[str, Any]:
+        """Run a write once and return its `data` object; a timeout leaves the outcome unknown."""
+        path = f"/voyager/api/graphql?action=execute&queryId={query.id}&queryName={query.name}"
+        body = {"queryId": query.id, "queryName": query.name, "variables": dict(variables)}
+        response = await self.transport.request("POST", path, json=body, headers=_GRAPHQL)
+        envelope = self.transport.json_object(response)
+        value = envelope.get("value")
+        if not isinstance(value, dict):
+            raise ProtocolError("GraphQL action reply had no value object.")
+        return _graphql_data(value)
+
+    async def get(
+        self, resource: str, params: Mapping[str, object] | None = None
+    ) -> dict[str, Any]:
+        """Read a rest.li resource such as `voyagerJobsDashJobPostings/<id>`."""
+        response = await self.transport.request(
+            "GET", _resource_path(resource, params), headers=_JSON
+        )
+        return self.transport.json_object(response)
+
+    async def post(
+        self,
+        resource: str,
+        body: Mapping[str, object],
+        params: Mapping[str, object] | None = None,
+    ) -> Reply:
+        """Create or run a rest.li action once; the server may reply with no body."""
+        response = await self.transport.request(
+            "POST", _resource_path(resource, params), json=dict(body), headers=_JSON
+        )
+        data = self.transport.json_object(response) if response.content else {}
+        created = response.headers.get("x-restli-id") or response.headers.get("x-linkedin-id")
+        return Reply(data, created)
+
+    async def delete(self, resource: str, params: Mapping[str, object] | None = None) -> None:
+        """Delete a rest.li entity once."""
+        await self.transport.request("DELETE", _resource_path(resource, params), headers=_JSON)
+
+
+def _resource_path(resource: str, params: Mapping[str, object] | None) -> str:
+    if not re.fullmatch(r"voyager[A-Za-z]+(/[A-Za-z0-9%()_:.,'\-~!*]+)*", resource):
+        raise ValueError("A Voyager resource name such as voyagerJobsDashJobPostings is required.")
+    path = "/voyager/api/" + resource
+    if params:
+        query = "&".join(
+            f"{key}={value if isinstance(value, str) and key in _RAW else restli.encode(value)}"
+            for key, value in params.items()
+            if value is not None
+        )
+        path += "?" + query
+    return path
+
+
+# Plain query parameters the app writes without rest.li value encoding.
+_RAW = frozenset({"q", "action", "decorationId"})
+
+
+def _null_field_error(error: object) -> bool:
+    if not isinstance(error, dict) or not isinstance(error.get("extensions"), dict):
+        return False
+    return bool(error["extensions"].get("classification") == "NullValueInNonNullableField")
+
+
+def _graphql_data(envelope: dict[str, Any]) -> dict[str, Any]:
+    errors = envelope.get("errors")
+    if errors:
+        reasons = tuple(
+            str(error.get("message"))[:300]
+            for error in errors
+            if isinstance(error, dict) and error.get("message")
+        )
+        raise OperationRejected(reasons)
+    data = envelope.get("data")
+    if not isinstance(data, dict):
+        raise ProtocolError("GraphQL reply had no data object.")
+    return data