async_linkedinlib 0.2.0__py3-none-any.whl

async_linkedinlib/resources/search/queries.py

@@ -0,0 +1,79 @@
+"""The app's persisted search operations and the variables it sends them.
+
+Search screens build a `SearchQueryForInput` (SearchFrameworkUtils.getSearchQuery) and job
+search a `JobSearchQueryForInput` (JobSearchQueryUtils); filters travel as a map of query
+keys to value lists, which rest.li writes as `(geoUrn:List(103644278),...)`.
+"""
+
+from typing import Any
+
+from ...models.search import TypeaheadKind
+from ...models.search import Vertical
+from ...models.search_filters import Params
+from ...transport.voyager import GraphQLQuery
+
+CLUSTERS = GraphQLQuery(
+    "voyagerSearchDashClusters.c2c5d4b012c05a6a94396191208d45f6", "SearchClusterCollection"
+)
+FILTERS = GraphQLQuery(
+    "voyagerSearchDashFilterClusters.d163cc1a7c36e8f4472c2b539b730829",
+    "SearchFilterClustersByFilters",
+)
+TYPEAHEAD = GraphQLQuery(
+    "voyagerSearchDashReusableTypeahead.ae52ba922ef9ede5129d80936bd4249c",
+    "SearchReusableTypeaheadByType",
+)
+GLOBAL_TYPEAHEAD = GraphQLQuery(
+    "voyagerSearchDashTypeahead.0b3defba877012c806fcd8427c7ce135", "SearchGlobalTypeahead"
+)
+JOB_CARDS = GraphQLQuery(
+    "voyagerJobsDashJobCards.eb54097e5bda5435af797ec5bbedf723", "JobCardsByJobSearch"
+)
+JOB_FILTERS = GraphQLQuery(
+    "voyagerJobsDashSearchFilterClustersResource.4a3b04e4d980bf06ab986f66ef129f4e",
+    "JobSearchFiltersByJobSeachQuery",
+)
+
+# The filter sheet's location typeahead asks for these place types.
+GEO_SEARCH_TYPES = ("MARKET_AREA", "COUNTRY_REGION", "ADMIN_DIVISION_1", "CITY")
+
+
+def search_query(vertical: Vertical, keywords: str, params: Params) -> dict[str, Any]:
+    """A `SearchQueryForInput`; keywords are left out when empty, as the app does."""
+    return {
+        "flagshipSearchIntent": "SEARCH_SRP",
+        "keywords": keywords or None,
+        "queryParameters": {"resultType": [vertical.value], **params},
+        "spellCorrectionEnabled": True,
+    }
+
+
+def search_origin(vertical: Vertical, params: Params) -> str:
+    """The origin the app reports: the search bar, a vertical switch or applied filters."""
+    if vertical is Vertical.ALL:
+        return "GLOBAL_SEARCH_HEADER"
+    return "FACETED_SEARCH" if params else "SWITCH_SEARCH_VERTICAL"
+
+
+def job_query(keywords: str, geo_urn: str | None, params: Params) -> dict[str, Any]:
+    """A `JobSearchQueryForInput`; `locationUnion` is the geoUrn member of its union."""
+    return {
+        "origin": "JOB_SEARCH_PAGE_JOB_FILTER" if params else "JOB_SEARCH_PAGE_SEARCH_BUTTON",
+        "keywords": keywords or None,
+        "locationUnion": {"geoUrn": geo_urn} if geo_urn else None,
+        "selectedFilters": params or None,
+        "spellCorrectionEnabled": True,
+    }
+
+
+def typeahead_variables(kind: TypeaheadKind, keywords: str, count: int | None) -> dict[str, Any]:
+    """TypeaheadRoutes.buildTypeaheadQuery as the search filter sheet calls it."""
+    filter_query: dict[str, Any] = {"standardizationEntityType": "industryV2"}
+    if kind is TypeaheadKind.GEO:
+        filter_query = {"geoSearchTypes": list(GEO_SEARCH_TYPES), **filter_query}
+    return {
+        "keywords": keywords,
+        "query": {"showFullLastNameForConnections": True, "typeaheadFilterQuery": filter_query},
+        "type": kind.value,
+        "count": count,
+    }

async_linkedinlib/resources/search/results.py

@@ -0,0 +1,85 @@
+"""Decode search replies into pages whose cursors continue only the same query."""
+
+from collections.abc import Callable
+from typing import Any
+from typing import TypeVar
+
+from ...models._json import dig
+from ...models._json import integer
+from ...models._json import items
+from ...models._json import obj
+from ...models._json import text
+from ...models.content import Post
+from ...models.pagination import Page
+from ...models.search import PersonResult
+from ...models.search import ResultGroup
+from ...models.search import SearchResult
+from .. import paging
+
+T = TypeVar("T")
+Item = PersonResult | SearchResult | Post
+
+
+Where = tuple[str, str, int, int, str]  # operation, scope, start, count, cursor owner
+
+
+def result_page(
+    reply: dict[str, Any], read: Callable[[dict[str, Any]], T | None], where: Where
+) -> Page[T]:
+    """Flatten the items of every cluster on a vertical's page. Banners, counts and feedback
+    cards are skipped."""
+    entries = [
+        obj(entry.get("item"))
+        for cluster in items(reply.get("elements"))
+        for entry in items(cluster.get("items"))
+    ]
+    return paging.page(reply, read, *where, elements=entries, total=_total(reply))
+
+
+def group_page(reply: dict[str, Any], where: Where) -> Page[ResultGroup]:
+    """Blended results: one group per cluster that holds people, entities or posts."""
+    return paging.page(reply, _group, *where, total=_total(reply))
+
+
+def job_page(
+    reply: dict[str, Any], read: Callable[[dict[str, Any]], T | None], where: Where
+) -> Page[T]:
+    cards = [obj(element.get("jobCard")) for element in items(reply.get("elements"))]
+    return paging.page(reply, read, *where, elements=cards)
+
+
+def _group(cluster: dict[str, Any]) -> ResultGroup | None:
+    found = [
+        result
+        for entry in items(cluster.get("items"))
+        if (result := any_item(obj(entry.get("item")))) is not None
+    ]
+    return ResultGroup(text(cluster, "title"), tuple(found), cluster) if found else None
+
+
+def person(item: dict[str, Any]) -> PersonResult | None:
+    return PersonResult.from_entity(obj(item.get("entityResult")))
+
+
+def entity(item: dict[str, Any]) -> SearchResult | None:
+    found = obj(item.get("entityResult"))
+    return SearchResult.from_entity(found) if found else None
+
+
+def post(item: dict[str, Any]) -> Post | None:
+    update = obj(dig(item, "searchFeedUpdate", "update"))
+    if not update:
+        return None
+    return Post.from_update(update)
+
+
+def any_item(item: dict[str, Any]) -> Item | None:
+    """A blended item: a profile, another entity, or a post."""
+    if "searchFeedUpdate" in item:
+        return post(item)
+    return person(item) or entity(item)
+
+
+def _total(reply: dict[str, Any]) -> int | None:
+    total = integer(reply, "metadata", "totalResultCount")
+    return total if total is not None else integer(reply, "paging", "total")

async_linkedinlib/resources/search/search.py

@@ -0,0 +1,284 @@
+"""Search people, posts, companies, jobs and other verticals, their filters and typeahead.
+
+Every call is one read. Nothing here adds to the viewer's search history; the app sends
+that as a separate write, which this client does not.
+"""
+
+from collections.abc import Callable
+from typing import Any
+from typing import TypeVar
+
+from ...models._json import items
+from ...models.content import Post
+from ...models.pagination import Cursor
+from ...models.pagination import Page
+from ...models.search import Filter
+from ...models.search import PersonResult
+from ...models.search import ResultGroup
+from ...models.search import SearchResult
+from ...models.search import Suggestion
+from ...models.search import TypeaheadKind
+from ...models.search import Vertical
+from ...models.search import filters_from_clusters
+from ...models.search_filters import CompanyFilters
+from ...models.search_filters import CourseFilters
+from ...models.search_filters import Params
+from ...models.search_filters import PeopleFilters
+from ...models.search_filters import PostFilters
+from ...models.search_filters import ProductFilters
+from ...models.search_filters import ServiceFilters
+from ...models.search_jobs import JobFilters
+from ...models.search_jobs import JobResult
+from ...transport import restli
+from ...transport.voyager import Voyager
+from .. import paging
+from . import queries
+from . import results
+
+T = TypeVar("T")
+VerticalFilters = (
+    PeopleFilters | PostFilters | CompanyFilters | ServiceFilters | ProductFilters | CourseFilters
+)
+FILTER_TYPES: dict[Vertical, type[VerticalFilters]] = {
+    Vertical.PEOPLE: PeopleFilters,
+    Vertical.POSTS: PostFilters,
+    Vertical.COMPANIES: CompanyFilters,
+    Vertical.SERVICES: ServiceFilters,
+    Vertical.PRODUCTS: ProductFilters,
+    Vertical.COURSES: CourseFilters,
+}
+MAX_COUNT = 50
+
+
+class Search:
+    """Search LinkedIn the way the app's search and job search screens do.
+
+    Vertical methods return one page; pass `page.next` as `cursor` with the same keywords
+    and filters to continue. `count` is a page size from 1 to 50.
+    """
+
+    def __init__(self, voyager: Voyager) -> None:
+        self._voyager = voyager
+
+    async def all(
+        self, keywords: str, *, count: int = 10, cursor: Cursor | None = None
+    ) -> Page[ResultGroup]:
+        """Blended results: groups such as Jobs, Posts, People and Companies."""
+        if not _keywords(keywords):
+            raise ValueError("Blended search needs keywords.")
+        reply, where = await self._clusters(Vertical.ALL, keywords, {}, count, cursor)
+        return results.group_page(reply, where)
+
+    async def people(
+        self,
+        keywords: str = "",
+        filters: PeopleFilters | None = None,
+        *,
+        count: int = 10,
+        cursor: Cursor | None = None,
+    ) -> Page[PersonResult]:
+        return await self._vertical(
+            Vertical.PEOPLE, keywords, filters, count, cursor, results.person
+        )
+
+    async def posts(
+        self,
+        keywords: str = "",
+        filters: PostFilters | None = None,
+        *,
+        count: int = 10,
+        cursor: Cursor | None = None,
+    ) -> Page[Post]:
+        """Posts as feed `Post`s; results the feed model cannot read are left out."""
+        return await self._vertical(Vertical.POSTS, keywords, filters, count, cursor, results.post)
+
+    async def companies(
+        self,
+        keywords: str = "",
+        filters: CompanyFilters | None = None,
+        *,
+        count: int = 10,
+        cursor: Cursor | None = None,
+    ) -> Page[SearchResult]:
+        return await self._vertical(
+            Vertical.COMPANIES, keywords, filters, count, cursor, results.entity
+        )
+
+    async def groups(
+        self, keywords: str, *, count: int = 10, cursor: Cursor | None = None
+    ) -> Page[SearchResult]:
+        return await self._vertical(Vertical.GROUPS, keywords, None, count, cursor, results.entity)
+
+    async def schools(
+        self, keywords: str, *, count: int = 10, cursor: Cursor | None = None
+    ) -> Page[SearchResult]:
+        return await self._vertical(Vertical.SCHOOLS, keywords, None, count, cursor, results.entity)
+
+    async def events(
+        self, keywords: str, *, count: int = 10, cursor: Cursor | None = None
+    ) -> Page[SearchResult]:
+        return await self._vertical(Vertical.EVENTS, keywords, None, count, cursor, results.entity)
+
+    async def courses(
+        self,
+        keywords: str = "",
+        filters: CourseFilters | None = None,
+        *,
+        count: int = 10,
+        cursor: Cursor | None = None,
+    ) -> Page[SearchResult]:
+        """LinkedIn Learning courses."""
+        return await self._vertical(
+            Vertical.COURSES, keywords, filters, count, cursor, results.entity
+        )
+
+    async def products(
+        self,
+        keywords: str = "",
+        filters: ProductFilters | None = None,
+        *,
+        count: int = 10,
+        cursor: Cursor | None = None,
+    ) -> Page[SearchResult]:
+        return await self._vertical(
+            Vertical.PRODUCTS, keywords, filters, count, cursor, results.entity
+        )
+
+    async def services(
+        self,
+        keywords: str = "",
+        filters: ServiceFilters | None = None,
+        *,
+        count: int = 10,
+        cursor: Cursor | None = None,
+    ) -> Page[PersonResult]:
+        """Members who offer services."""
+        return await self._vertical(
+            Vertical.SERVICES, keywords, filters, count, cursor, results.person
+        )
+
+    async def jobs(
+        self,
+        keywords: str = "",
+        filters: JobFilters | None = None,
+        *,
+        count: int = 25,
+        cursor: Cursor | None = None,
+    ) -> Page[JobResult]:
+        """Job cards; pass `JobResult.id` to the jobs feature for details or applying."""
+        query = _job_query(keywords, filters)
+        operation, scope = "search.jobs", restli.encode(query)
+        start, _token = paging.resume(cursor, operation, scope, self._voyager.owner)
+        size = _count(count)
+        data = await self._voyager.query(
+            queries.JOB_CARDS,
+            {"query": query, "count": size, "start": start, "includeJobState": True},
+        )
+        reply = paging.collection(data, "jobsDashJobCardsByJobSearch")
+        where = (operation, scope, start, size, self._voyager.owner)
+        return results.job_page(reply, JobResult.from_card, where)
+
+    async def filters(
+        self,
+        vertical: Vertical,
+        keywords: str = "",
+        applied: VerticalFilters | None = None,
+    ) -> tuple[Filter, ...]:
+        """The filters and suggested values the app offers for a vertical and query."""
+        vertical = Vertical(vertical)
+        query = queries.search_query(vertical, _keywords(keywords), _params(vertical, applied))
+        data = await self._voyager.query(queries.FILTERS, {"query": query})
+        reply = paging.collection(data, "searchDashFilterClustersByFilters")
+        return filters_from_clusters(items(reply.get("elements")))
+
+    async def job_filters(
+        self, keywords: str = "", filters: JobFilters | None = None
+    ) -> tuple[Filter, ...]:
+        """Job search filters for a query, such as salary buckets and distances near a place."""
+        data = await self._voyager.query(
+            queries.JOB_FILTERS, {"query": _job_query(keywords, filters)}
+        )
+        reply = paging.collection(data, "jobsDashSearchFilterClustersResourceByFilters")
+        return filters_from_clusters(items(reply.get("elements")))
+
+    async def typeahead(
+        self, kind: TypeaheadKind, keywords: str, *, count: int | None = None
+    ) -> tuple[Suggestion, ...]:
+        """Find filter values by name, for example `typeahead(TypeaheadKind.GEO, "Berlin")`."""
+        kind = TypeaheadKind(kind)
+        if not _keywords(keywords):
+            raise ValueError("Typeahead needs some text to match.")
+        variables = queries.typeahead_variables(
+            kind, _keywords(keywords), None if count is None else _count(count)
+        )
+        data = await self._voyager.query(queries.TYPEAHEAD, variables)
+        reply = paging.collection(data, "searchDashReusableTypeaheadByType")
+        return tuple(Suggestion.from_typeahead(item) for item in items(reply.get("elements")))
+
+    async def suggest(self, keywords: str) -> tuple[Suggestion, ...]:
+        """The search bar's suggestions: matching entities and completed keywords."""
+        if not _keywords(keywords):
+            raise ValueError("Suggestions need some text to match.")
+        data = await self._voyager.query(queries.GLOBAL_TYPEAHEAD, {"query": _keywords(keywords)})
+        reply = paging.collection(data, "searchDashTypeaheadByGlobalTypeahead")
+        return tuple(Suggestion.from_global(item) for item in items(reply.get("elements")))
+
+    async def _vertical(
+        self,
+        vertical: Vertical,
+        keywords: str,
+        filters: VerticalFilters | None,
+        count: int,
+        cursor: Cursor | None,
+        read: Callable[[dict[str, Any]], T | None],
+    ) -> Page[T]:
+        params = _params(vertical, filters)
+        reply, where = await self._clusters(vertical, keywords, params, count, cursor)
+        return results.result_page(reply, read, where)
+
+    async def _clusters(
+        self, vertical: Vertical, keywords: str, params: Params, count: int, cursor: Cursor | None
+    ) -> tuple[dict[str, Any], results.Where]:
+        query = queries.search_query(vertical, _keywords(keywords), params)
+        operation, scope = f"search.{vertical.name.lower()}", restli.encode(query)
+        start, token = paging.resume(cursor, operation, scope, self._voyager.owner)
+        size = _count(count)
+        variables = {
+            "start": start,
+            "count": size,
+            "origin": queries.search_origin(vertical, params),
+            "query": query,
+            "paginationToken": token,
+        }
+        data = await self._voyager.query(queries.CLUSTERS, variables)
+        reply = paging.collection(data, "searchDashClustersByAll")
+        return reply, (operation, scope, start, size, self._voyager.owner)
+
+
+def _params(vertical: Vertical, filters: VerticalFilters | None) -> Params:
+    if filters is None:
+        return {}
+    expected = FILTER_TYPES.get(vertical)
+    if expected is None or not isinstance(filters, expected):
+        name = expected.__name__ if expected else "no filters"
+        raise ValueError(f"{vertical.name.lower()} search takes {name}.")
+    return filters.params()
+
+
+def _job_query(keywords: str, filters: JobFilters | None) -> dict[str, Any]:
+    if filters is not None and not isinstance(filters, JobFilters):
+        raise ValueError("Job search takes JobFilters.")
+    filters = filters or JobFilters()
+    return queries.job_query(_keywords(keywords), filters.geo_urn(), filters.params())
+
+
+def _keywords(keywords: str) -> str:
+    if not isinstance(keywords, str):
+        raise ValueError("keywords must be text.")
+    return " ".join(keywords.split())
+
+
+def _count(count: int) -> int:
+    if type(count) is not int or not 1 <= count <= MAX_COUNT:
+        raise ValueError(f"count must be an integer from 1 to {MAX_COUNT}.")
+    return count

async_linkedinlib/resources/threads.py

@@ -0,0 +1,30 @@
+"""Social threads: the post and comment URNs that reactions and comment lists address."""
+
+import re
+
+_POST = re.compile(r"urn:li:(activity|ugcPost):[0-9]+")
+_COMMENT = re.compile(r"urn:li:comment:\((activity|ugcPost):[0-9]+,[0-9]+\)")
+
+
+def post(urn: str) -> str:
+    """A post's social thread: `urn:li:activity:<id>` or `urn:li:ugcPost:<id>` (`Post.urn`)."""
+    if not isinstance(urn, str) or not _POST.fullmatch(urn):
+        raise ValueError(
+            "A post URN such as urn:li:activity:<id> or urn:li:ugcPost:<id> is needed."
+        )
+    return urn
+
+
+def thread(urn: str) -> str:
+    """A reactable thread: a post URN or `urn:li:comment:(activity:<post>,<id>)`."""
+    if isinstance(urn, str) and _COMMENT.fullmatch(urn):
+        return urn
+    if not isinstance(urn, str) or not _POST.fullmatch(urn):
+        raise ValueError("A post or comment URN such as urn:li:activity:<id> is needed.")
+    return urn
+
+
+def social_detail(thread_urn: str) -> str:
+    """The social detail of a thread: it lists a post's comments or a comment's replies and
+    carries the thread's comment settings."""
+    return f"urn:li:fsd_socialDetail:({thread_urn},{thread_urn},urn:li:highlightedReply:-)"

async_linkedinlib/session/__init__.py

@@ -0,0 +1,5 @@
+"""Session public exports."""
+
+from .state import Session  # Private account state and persistence.
+
+__all__ = ["Session"]

async_linkedinlib/session/cookies.py

@@ -0,0 +1,52 @@
+"""Scoped, serializable cookies."""
+
+from dataclasses import dataclass
+from http.cookiejar import Cookie
+
+from ..exceptions import SessionError
+
+
+@dataclass(slots=True, repr=False)
+class SessionCookie:
+    """Preserve cookie scope and expiry instead of flattening the cookie jar."""
+
+    name: str
+    value: str
+    domain: str
+    path: str = "/"
+    secure: bool = True
+    expires: int | None = None
+    host_only: bool = False
+
+    def __post_init__(self) -> None:
+        if (
+            not all(isinstance(v, str) for v in (self.name, self.value, self.domain, self.path))
+            or not self.name
+            or not self.path.startswith("/")
+            or self.domain.lstrip(".") not in {"linkedin.com", "www.linkedin.com"}
+            or any(ch in self.name + self.value for ch in "\r\n")
+            or type(self.secure) is not bool
+            or type(self.host_only) is not bool
+            or (self.expires is not None and type(self.expires) is not int)
+        ):
+            raise SessionError("Invalid LinkedIn cookie state.")
+
+    def to_cookie(self) -> Cookie:
+        return Cookie(
+            version=0,
+            name=self.name,
+            value=self.value,
+            port=None,
+            port_specified=False,
+            domain=self.domain,
+            domain_specified=not self.host_only,
+            domain_initial_dot=self.domain.startswith("."),
+            path=self.path,
+            path_specified=True,
+            secure=self.secure,
+            expires=self.expires,
+            discard=self.expires is None,
+            comment=None,
+            comment_url=None,
+            rest={},
+        )

async_linkedinlib/session/lease.py

@@ -0,0 +1,30 @@
+"""POSIX ownership of one session file, following the local Instagram client's pattern."""
+
+import os
+from pathlib import Path
+
+from ..exceptions import SessionInUse
+
+
+class SessionLease:
+    """Hold a stable sidecar lock until the owning client closes."""
+
+    def __init__(self, path: Path) -> None:
+        import fcntl
+
+        path.parent.mkdir(parents=True, exist_ok=True, mode=0o700)
+        self._fd = os.open(str(path) + ".lock", os.O_CREAT | os.O_RDWR, 0o600)
+        try:
+            os.fchmod(self._fd, 0o600)
+            fcntl.flock(self._fd, fcntl.LOCK_EX | fcntl.LOCK_NB)
+        except BlockingIOError:
+            self.close()
+            raise SessionInUse("This session file is already open in another client.") from None
+        except BaseException:
+            self.close()
+            raise
+
+    def close(self) -> None:
+        if self._fd >= 0:
+            os.close(self._fd)
+            self._fd = -1