async_linkedinlib 0.2.0__py3-none-any.whl

async_linkedinlib/models/search_filters.py

@@ -0,0 +1,339 @@
+"""Typed search filters per vertical, mapped to the query keys the app's filter sheets use.
+
+ID fields take IDs or simple URNs (`"1035"`, `"urn:li:fsd_company:1035"`); typeahead
+`Suggestion.id` values fit directly. `extra` adds raw query keys from `Search.filters()` that
+have no typed field, for example `{"seniorityV2": ["120"]}`; it cannot repeat a typed key.
+"""
+
+import re
+from collections.abc import Mapping
+from collections.abc import Sequence
+from dataclasses import dataclass
+from dataclasses import field
+from enum import StrEnum
+from typing import Any
+
+Params = dict[str, list[str]]
+
+
+class Network(StrEnum):
+    """Connection degree."""
+
+    FIRST = "F"
+    SECOND = "S"
+    THIRD_PLUS = "O"
+
+
+class PostSort(StrEnum):
+    RELEVANCE = "relevance"  # Top match
+    LATEST = "date_posted"
+
+
+class DatePosted(StrEnum):
+    PAST_24_HOURS = "past-24h"
+    PAST_WEEK = "past-week"
+    PAST_MONTH = "past-month"
+
+
+class ContentType(StrEnum):
+    VIDEOS = "videos"
+    IMAGES = "photos"
+    JOB_POSTS = "jobs"
+    LIVE_VIDEOS = "liveVideos"
+    DOCUMENTS = "documents"
+    COLLABORATIVE_ARTICLES = "collaborativeArticles"
+
+
+class PostedBy(StrEnum):
+    FIRST_CONNECTIONS = "first"
+    ME = "me"
+    PEOPLE_YOU_FOLLOW = "following"
+
+
+class CompanySize(StrEnum):
+    SIZE_1_10 = "B"
+    SIZE_11_50 = "C"
+    SIZE_51_200 = "D"
+    SIZE_201_500 = "E"
+    SIZE_501_1000 = "F"
+    SIZE_1001_5000 = "G"
+    SIZE_5001_10000 = "H"
+    SIZE_10001_PLUS = "I"
+
+
+class CourseLevel(StrEnum):
+    BEGINNER = "Beginner"
+    INTERMEDIATE = "Intermediate"
+    ADVANCED = "Advanced"
+
+
+class CourseLength(StrEnum):
+    UNDER_10_MINUTES = "< 10 mins"
+    MINUTES_10_30 = "10 - 30 mins"
+    MINUTES_30_60 = "30 - 60 mins"
+    HOURS_1_2 = "1 - 2 hours"
+    HOURS_2_3 = "2 - 3 hours"
+    OVER_3_HOURS = "3+ hours"
+
+
+@dataclass(frozen=True, slots=True)
+class PeopleFilters:
+    """People search filters; `first_name` to `school` are the free-text keyword filters."""
+
+    network: Sequence[Network] = ()
+    locations: Sequence[str] = ()
+    current_companies: Sequence[str] = ()
+    past_companies: Sequence[str] = ()
+    schools: Sequence[str] = ()
+    industries: Sequence[str] = ()
+    profile_languages: Sequence[str] = ()  # language codes: en, fr, ... ("_o" = others)
+    service_categories: Sequence[str] = ()
+    connection_of: str | None = None  # profile ID or URN
+    follower_of: str | None = None  # profile ID or URN
+    open_to_volunteer: bool = False
+    first_name: str | None = None
+    last_name: str | None = None
+    title: str | None = None
+    company: str | None = None
+    school: str | None = None
+    extra: Mapping[str, Sequence[str]] = field(default_factory=dict)
+
+    def __post_init__(self) -> None:
+        self.params()
+
+    def params(self) -> Params:
+        return merge(
+            {
+                "network": choices(Network, "network", self.network),
+                "geoUrn": ids("locations", self.locations),
+                "currentCompany": ids("current_companies", self.current_companies),
+                "pastCompany": ids("past_companies", self.past_companies),
+                "schoolFilter": ids("schools", self.schools),
+                "industry": ids("industries", self.industries),
+                "profileLanguage": ids("profile_languages", self.profile_languages),
+                "serviceCategory": ids("service_categories", self.service_categories),
+                "connectionOf": one_id("connection_of", self.connection_of),
+                "followerOf": one_id("follower_of", self.follower_of),
+                "openToVolunteer": flag("open_to_volunteer", self.open_to_volunteer),
+                "firstName": phrase("first_name", self.first_name),
+                "lastName": phrase("last_name", self.last_name),
+                "title": phrase("title", self.title),
+                "company": phrase("company", self.company),
+                "schoolFreetext": phrase("school", self.school),
+            },
+            self.extra,
+        )
+
+
+@dataclass(frozen=True, slots=True)
+class PostFilters:
+    """Post (content) search filters; member fields take profile IDs, company fields IDs."""
+
+    sort_by: PostSort | None = None
+    date_posted: DatePosted | None = None
+    content_type: ContentType | None = None
+    posted_by: Sequence[PostedBy] = ()
+    from_members: Sequence[str] = ()
+    from_companies: Sequence[str] = ()
+    mentions_members: Sequence[str] = ()
+    mentions_companies: Sequence[str] = ()
+    author_industries: Sequence[str] = ()
+    author_companies: Sequence[str] = ()
+    author_title: str | None = None
+    extra: Mapping[str, Sequence[str]] = field(default_factory=dict)
+
+    def __post_init__(self) -> None:
+        self.params()
+
+    def params(self) -> Params:
+        return merge(
+            {
+                "sortBy": choices(PostSort, "sort_by", optional(self.sort_by)),
+                "datePosted": choices(DatePosted, "date_posted", optional(self.date_posted)),
+                "contentType": choices(ContentType, "content_type", optional(self.content_type)),
+                "postedBy": choices(PostedBy, "posted_by", self.posted_by),
+                "fromMember": ids("from_members", self.from_members),
+                "fromOrganization": ids("from_companies", self.from_companies),
+                "mentionsMember": ids("mentions_members", self.mentions_members),
+                "mentionsOrganization": ids("mentions_companies", self.mentions_companies),
+                "authorIndustry": ids("author_industries", self.author_industries),
+                "authorCompany": ids("author_companies", self.author_companies),
+                "authorJobTitle": phrase("author_title", self.author_title),
+            },
+            self.extra,
+        )
+
+
+@dataclass(frozen=True, slots=True)
+class CompanyFilters:
+    """Company search filters; `locations` are headquarters geo IDs."""
+
+    locations: Sequence[str] = ()
+    industries: Sequence[str] = ()
+    sizes: Sequence[CompanySize] = ()
+    has_jobs: bool = False
+    network: Sequence[Network] = ()
+    extra: Mapping[str, Sequence[str]] = field(default_factory=dict)
+
+    def __post_init__(self) -> None:
+        self.params()
+
+    def params(self) -> Params:
+        return merge(
+            {
+                "companyHqGeo": ids("locations", self.locations),
+                "industryCompanyVertical": ids("industries", self.industries),
+                "companySize": choices(CompanySize, "sizes", self.sizes),
+                "hasJobs": ["1"] if flag("has_jobs", self.has_jobs) else [],
+                "network": choices(Network, "network", self.network),
+            },
+            self.extra,
+        )
+
+
+@dataclass(frozen=True, slots=True)
+class ServiceFilters:
+    """Service provider search filters."""
+
+    service_categories: Sequence[str] = ()
+    locations: Sequence[str] = ()
+    network: Sequence[Network] = ()
+    profile_languages: Sequence[str] = ()
+    extra: Mapping[str, Sequence[str]] = field(default_factory=dict)
+
+    def __post_init__(self) -> None:
+        self.params()
+
+    def params(self) -> Params:
+        return merge(
+            {
+                "serviceCategory": ids("service_categories", self.service_categories),
+                "geoUrn": ids("locations", self.locations),
+                "network": choices(Network, "network", self.network),
+                "profileLanguage": ids("profile_languages", self.profile_languages),
+            },
+            self.extra,
+        )
+
+
+@dataclass(frozen=True, slots=True)
+class ProductFilters:
+    """Product search filters; categories come from the PRODUCT_CATEGORY typeahead."""
+
+    categories: Sequence[str] = ()
+    companies: Sequence[str] = ()
+    free_plan: bool = False
+    extra: Mapping[str, Sequence[str]] = field(default_factory=dict)
+
+    def __post_init__(self) -> None:
+        self.params()
+
+    def params(self) -> Params:
+        return merge(
+            {
+                "productCategory": ids("categories", self.categories),
+                "productCompany": ids("companies", self.companies),
+                "productFreePlan": flag("free_plan", self.free_plan),
+            },
+            self.extra,
+        )
+
+
+@dataclass(frozen=True, slots=True)
+class CourseFilters:
+    """LinkedIn Learning course filters; `software`, `topics` and `education_units` take the
+    values `Search.filters(Vertical.COURSES, ...)` lists (software names, topic IDs, CPE...)."""
+
+    levels: Sequence[CourseLevel] = ()
+    lengths: Sequence[CourseLength] = ()
+    software: Sequence[str] = ()
+    topics: Sequence[str] = ()
+    education_units: Sequence[str] = ()
+    extra: Mapping[str, Sequence[str]] = field(default_factory=dict)
+
+    def __post_init__(self) -> None:
+        self.params()
+
+    def params(self) -> Params:
+        return merge(
+            {
+                "difficultyLevel": choices(CourseLevel, "levels", self.levels),
+                "timeToComplete": choices(CourseLength, "lengths", self.lengths),
+                "softwareNames": phrases("software", self.software),
+                "categoryIds": ids("topics", self.topics),
+                "continuingEducationUnits": phrases("education_units", self.education_units),
+            },
+            self.extra,
+        )
+
+
+def merge(typed: Params, extra: Mapping[str, Sequence[str]]) -> Params:
+    """Drop empty filters and add validated raw keys."""
+    found = {key: values for key, values in typed.items() if values}
+    if not isinstance(extra, Mapping):
+        raise ValueError("extra maps query keys to lists of values.")
+    for key, values in extra.items():
+        if not isinstance(key, str) or not re.fullmatch(r"[A-Za-z][A-Za-z0-9_]*", key):
+            raise ValueError("extra keys are query parameter names such as seniorityV2.")
+        if key in typed or key in ("resultType", "keywords"):
+            raise ValueError(f"extra cannot set {key}; use its typed field or argument.")
+        found[key] = phrases(f"extra[{key}]", values)
+    return {key: values for key, values in found.items() if values}
+
+
+def ids(name: str, values: Sequence[str]) -> list[str]:
+    return [identifier(name, value) for value in sequence(name, values)]
+
+
+def one_id(name: str, value: str | None) -> list[str]:
+    return [] if value is None else [identifier(name, value)]
+
+
+def identifier(name: str, value: object) -> str:
+    """An ID, or the last part of a simple URN such as urn:li:fsd_geo:103644278."""
+    if not isinstance(value, str) or not value.strip():
+        raise ValueError(f"{name} takes IDs or URNs as nonempty strings.")
+    value = value.strip()
+    if value.startswith("urn:li:"):
+        if "(" in value:
+            raise ValueError(f"{name} takes simple URNs, not compound ones.")
+        value = value.rsplit(":", 1)[1]
+    if not value or any(char.isspace() for char in value):
+        raise ValueError(f"{name} takes IDs without spaces.")
+    return value
+
+
+def choices(kind: type[StrEnum], name: str, values: Sequence[StrEnum | str]) -> list[str]:
+    try:
+        return [kind(value).value for value in sequence(name, values)]
+    except ValueError:
+        options = ", ".join(member.name for member in kind)
+        raise ValueError(f"{name} takes {kind.__name__} values: {options}.") from None
+
+
+def optional(value: StrEnum | str | None) -> tuple[StrEnum | str, ...]:
+    return () if value is None else (value,)
+
+
+def phrase(name: str, value: object) -> list[str]:
+    if value is None:
+        return []
+    if not isinstance(value, str) or not value.strip():
+        raise ValueError(f"{name} must be nonempty text.")
+    return [value.strip()]
+
+
+def phrases(name: str, values: Sequence[str]) -> list[str]:
+    return [item for value in sequence(name, values) for item in phrase(name, value)]
+
+
+def flag(name: str, value: bool) -> list[str]:
+    if not isinstance(value, bool):
+        raise ValueError(f"{name} must be True or False.")
+    return ["true"] if value else []
+
+
+def sequence(name: str, values: object) -> Sequence[Any]:
+    if isinstance(values, (str, bytes)) or not isinstance(values, Sequence):
+        raise ValueError(f"{name} takes a list of values, not a single string.")
+    return values

async_linkedinlib/models/search_jobs.py

@@ -0,0 +1,213 @@
+"""Job search filters and job cards from the app's job search results.
+
+Job details and applying belong to the jobs feature: pass `JobResult.id` to it.
+"""
+
+from collections.abc import Mapping
+from collections.abc import Sequence
+from copy import deepcopy
+from dataclasses import dataclass
+from dataclasses import field
+from datetime import datetime
+from enum import StrEnum
+from typing import Any
+
+from ._json import boolean
+from ._json import dig
+from ._json import epoch_ms
+from ._json import integer
+from ._json import items
+from ._json import obj
+from ._json import string
+from ._json import text
+from ._json import urn_id
+from .jobs import WORKPLACE_IDS
+from .jobs import WorkplaceType
+from .search_filters import Params
+from .search_filters import choices
+from .search_filters import flag
+from .search_filters import identifier
+from .search_filters import ids
+from .search_filters import merge
+from .search_filters import optional
+
+
+class JobSort(StrEnum):
+    MOST_RELEVANT = "R"
+    MOST_RECENT = "DD"
+
+
+class JobDatePosted(StrEnum):
+    PAST_24_HOURS = "r86400"
+    PAST_WEEK = "r604800"
+    PAST_MONTH = "r2592000"
+
+
+class ExperienceLevel(StrEnum):
+    INTERNSHIP = "1"
+    ENTRY = "2"
+    ASSOCIATE = "3"
+    MID_SENIOR = "4"
+    DIRECTOR = "5"
+    EXECUTIVE = "6"
+
+
+class JobType(StrEnum):
+    FULL_TIME = "F"
+    PART_TIME = "P"
+    CONTRACT = "C"
+    TEMPORARY = "T"
+    VOLUNTEER = "V"
+    INTERNSHIP = "I"
+    OTHER = "O"
+
+
+class Commitment(StrEnum):
+    """Employer commitments the app lets job seekers filter by."""
+
+    DIVERSITY = "1"
+    SUSTAINABILITY = "2"
+    WORK_LIFE_BALANCE = "3"
+    SOCIAL_IMPACT = "4"
+    CAREER_GROWTH = "5"
+
+
+DISTANCES = (0, 5, 10, 25, 50, 100)
+
+
+@dataclass(frozen=True, slots=True)
+class JobFilters:
+    """Job search filters.
+
+    `location` is a geo ID or URN (GEO typeahead); `distance` is miles from it (0, 5, 10,
+    25, 50 or 100) and `places` narrows to populated places inside it. `salary` is the
+    app's bucket index from `Search.job_filters()` (in the US 1 = $40,000+ ... 9 = $200,000+).
+    `functions` take codes such as "eng"; `titles` and `companies` take IDs.
+    """
+
+    location: str | None = None
+    sort_by: JobSort | None = None
+    date_posted: JobDatePosted | None = None
+    easy_apply: bool = False
+    under_10_applicants: bool = False
+    in_my_network: bool = False
+    verified: bool = False
+    workplace: Sequence[WorkplaceType] = ()
+    experience: Sequence[ExperienceLevel] = ()
+    job_types: Sequence[JobType] = ()
+    companies: Sequence[str] = ()
+    places: Sequence[str] = ()
+    distance: int | None = None
+    salary: int | None = None
+    industries: Sequence[str] = ()
+    functions: Sequence[str] = ()
+    titles: Sequence[str] = ()
+    commitments: Sequence[Commitment] = ()
+    extra: Mapping[str, Sequence[str]] = field(default_factory=dict)
+
+    def __post_init__(self) -> None:
+        self.params()
+        self.geo_urn()
+
+    def geo_urn(self) -> str | None:
+        """The location as the `urn:li:fsd_geo:<id>` the job query takes."""
+        if self.location is None:
+            return None
+        return "urn:li:fsd_geo:" + identifier("location", self.location)
+
+    def params(self) -> Params:
+        if self.distance is not None and (
+            type(self.distance) is not int or self.distance not in DISTANCES
+        ):
+            raise ValueError("distance must be one of 0, 5, 10, 25, 50 or 100 miles.")
+        if self.salary is not None and (type(self.salary) is not int or not 1 <= self.salary <= 9):
+            raise ValueError("salary must be a bucket index from 1 to 9.")
+        return merge(
+            {
+                "sortBy": choices(JobSort, "sort_by", optional(self.sort_by)),
+                "timePostedRange": choices(
+                    JobDatePosted, "date_posted", optional(self.date_posted)
+                ),
+                "applyWithLinkedin": flag("easy_apply", self.easy_apply),
+                "earlyApplicant": flag("under_10_applicants", self.under_10_applicants),
+                "jobInYourNetwork": flag("in_my_network", self.in_my_network),
+                "verifiedJob": flag("verified", self.verified),
+                "workplaceType": [
+                    WORKPLACE_IDS[WorkplaceType(kind)]
+                    for kind in choices(WorkplaceType, "workplace", self.workplace)
+                ],
+                "experience": choices(ExperienceLevel, "experience", self.experience),
+                "jobType": choices(JobType, "job_types", self.job_types),
+                "company": ids("companies", self.companies),
+                "populatedPlace": ids("places", self.places),
+                "distance": [] if self.distance is None else [str(self.distance)],
+                "salaryBucketV2": [] if self.salary is None else [str(self.salary)],
+                "industry": ids("industries", self.industries),
+                "function": ids("functions", self.functions),
+                "title": ids("titles", self.titles),
+                "commitments": choices(Commitment, "commitments", self.commitments),
+            },
+            self.extra,
+        )
+
+
+@dataclass(frozen=True, slots=True)
+class JobResult:
+    """One job card from job search.
+
+    `id` is the job posting ID for the jobs feature; `urn` is `urn:li:fsd_jobPosting:<id>`.
+    `easy_apply`, `promoted` and `verified` mirror the labels the card shows. `states` are
+    the viewer's states for the job (SAVED, APPLIED, VIEWED, APPLICATION_IN_PROGRESS).
+    """
+
+    id: str
+    urn: str
+    title: str | None
+    company: str | None
+    company_urn: str | None
+    location: str | None
+    listed_at: datetime | None
+    easy_apply: bool
+    promoted: bool
+    verified: bool
+    reposted: bool | None = None
+    applicants: str | None = None
+    insight: str | None = None
+    states: tuple[str, ...] = ()
+    raw: dict[str, Any] = field(default_factory=dict, repr=False, compare=False)
+
+    @classmethod
+    def from_card(cls, card: dict[str, Any]) -> "JobResult | None":
+        """Build from a `JobCard`; None for cards that are not job postings."""
+        posting_card = obj(card.get("jobPostingCard"))
+        posting = obj(posting_card.get("jobPosting"))
+        urn = string(posting, "entityUrn")
+        job_id = urn_id(urn)
+        if not urn or not job_id:
+            return None
+        footers = {
+            string(footer, "type"): footer for footer in items(posting_card.get("footerItems"))
+        }
+        listed = integer(footers.get("LISTED_DATE"), "timeAt")
+        logo = items(dig(posting_card, "logo", "attributes"))
+        states = (
+            string(action, "jobSeekerJobStateEnums")
+            for action in items(dig(posting_card, "jobSeekerJobState", "jobSeekerJobStateActions"))
+        )
+        return cls(
+            id=job_id,
+            urn=urn,
+            title=string(posting_card, "jobPostingTitle") or string(posting, "title"),
+            company=text(posting_card, "primaryDescription"),
+            company_urn=string(logo[0], "detailData", "companyLogo", "entityUrn") if logo else None,
+            location=text(posting_card, "secondaryDescription"),
+            listed_at=epoch_ms(listed),
+            easy_apply="EASY_APPLY_TEXT" in footers,
+            promoted="PROMOTED" in footers,
+            verified=bool(dig(posting_card, "jobPostingVerification", "badge")),
+            reposted=boolean(posting, "repostedJob"),
+            applicants=text(footers.get("APPLICANT_COUNT_TEXT"), "text"),
+            insight=text(posting_card, "relevanceInsight", "text"),
+            states=tuple(state for state in states if state),
+            raw=deepcopy(card),
+        )

async_linkedinlib/resources/__init__.py

@@ -0,0 +1,12 @@
+"""Resources public exports."""
+
+from .account import Account  # Read and verify the current member.
+from .comments import Comments  # Comment reads, writes and reactions.
+from .feed import Feed  # Feed reads and explicit post actions.
+from .jobs import Jobs  # Job details, saved jobs, the tracker and Easy Apply.
+from .posts import PostMedia  # Uploads, processing status and link previews.
+from .posts import Posts  # Create, edit, delete, schedule and repost own posts.
+from .reactions import Reactions  # Reactions on posts and comments.
+from .search import Search  # Search verticals, filters and typeahead.
+
+__all__ = ["Account", "Comments", "Feed", "Jobs", "PostMedia", "Posts", "Reactions", "Search"]

async_linkedinlib/resources/account.py

@@ -0,0 +1,35 @@
+"""Account verification through the mobile SSO endpoint observed after login."""
+
+from ..exceptions import AuthenticationError
+from ..exceptions import ProtocolError
+from ..models import Member
+from ..transport import Transport
+
+
+class Account:
+    """Read and verify the current account without changing server-side state."""
+
+    def __init__(self, transport: Transport) -> None:
+        self._transport = transport
+
+    async def me(self) -> Member:
+        if not self._transport.session.authenticated:
+            raise AuthenticationError("A li_at and JSESSIONID session is required.")
+        response = await self._transport.request("GET", "/mob/sso/you")
+        data = self._transport.json_object(response)
+        member_id = data.get("memberID")
+        if type(member_id) not in (int, str) or not str(member_id).isdigit():
+            raise ProtocolError("Account response did not contain a valid member identity.")
+        fields = [data.get(k) for k in ("firstName", "lastName", "fullName", "headline")]
+        if not all(isinstance(v, str) for v in fields):
+            raise ProtocolError("Account response did not match the captured member schema.")
+        state = self._transport.session
+        if state.member_id is not None and state.member_id != str(member_id):
+            state.clear_authentication()
+            self._transport.checkpoint()
+            raise AuthenticationError("The session resolved to a different account.")
+        state.member_id = str(member_id)
+        self._transport.checkpoint()
+        return Member(
+            str(member_id), data["firstName"], data["lastName"], data["fullName"], data["headline"]
+        )

async_linkedinlib/resources/comments/__init__.py

@@ -0,0 +1,5 @@
+"""Comments resource exports."""
+
+from .resource import Comments  # Comment reads, writes and reactions.
+
+__all__ = ["Comments"]