async_linkedinlib 0.2.0__py3-none-any.whl

async_linkedinlib/resources/jobs/answers.py

@@ -0,0 +1,239 @@
+"""Check answers against an Easy Apply form and encode the app's `submitApplication` body.
+
+Encoding follows the app's FormsResponseBuilderUtils and JobApplyFeature:
+- text and numbers are sent trimmed as `textInputValue`;
+- a choice is an `entityInputValue` with the option's enum string as `inputEntityName`, or
+  its label plus `inputEntityUrn` when it has no enum string;
+- each response repeats its values as `formElementInputValues` and
+  `formElementInputValuesResolutionResults`;
+- a question left unanswered keeps LinkedIn's prefilled values when they are complete;
+- file slots are answered with `{formElementUrn, inputUrn}` in `fileUploadResponses`.
+The body starts with `followCompany`, `referenceId` and `trackingCode` (empty strings when
+unknown, as the app sends them) and the job's tracking ID as a 16-character byte string.
+Forms that need a data-consent step or repeatable sections are refused.
+"""
+
+import base64
+import binascii
+import math
+import re
+from collections.abc import Mapping
+from collections.abc import Sequence
+from decimal import Decimal
+from typing import Any
+
+from ...models.jobs_apply import ApplicationForm
+from ...models.jobs_apply import FileQuestion
+from ...models.jobs_apply import Option
+from ...models.jobs_apply import Question
+from ...models.jobs_apply import QuestionKind
+from ...models.jobs_apply import Resume
+from ...models.jobs_apply import Submission
+from ...models.jobs_apply import UploadedFile
+from .upload import DOCUMENT_TYPES
+
+_DECIMAL = re.compile(r"-?[0-9]+(\.[0-9]+)?")
+
+Answer = str | int | float | Sequence[str]
+FileAnswer = str | UploadedFile | Resume
+
+_TEXT = frozenset({QuestionKind.TEXT, QuestionKind.MULTILINE_TEXT, QuestionKind.NUMBER})
+_CHOICE = frozenset({QuestionKind.SINGLE_CHOICE, QuestionKind.DROPDOWN, QuestionKind.CHECKBOX})
+
+
+def build(
+    form: ApplicationForm,
+    answers: Mapping[str, Answer],
+    files: Mapping[str, FileAnswer] | None = None,
+    *,
+    follow_company: bool = False,
+    reference_id: str | None = None,
+    tracking_id: str | None = None,
+) -> Submission:
+    if form.needs_data_consent:
+        raise ValueError("This form asks for data consent first, which this client does not send.")
+    if form.has_repeatable_sections:
+        raise ValueError("This form has repeatable sections, which this client does not build.")
+    chosen: dict[str, list[dict[str, Any]]] = {}
+    for key, value in answers.items():
+        question = form.question(key)
+        if question.id in chosen:
+            raise ValueError(f"{_name(question)} is answered twice.")
+        chosen[question.id] = _values(question, value)
+    responses: list[dict[str, Any]] = []
+    shown: list[tuple[str, tuple[str, ...]]] = []
+    missing: list[str] = []
+    for question in form.questions:
+        values = chosen.get(question.id) or _prefilled(question)
+        if values:
+            responses.append(_response(question.id, values))
+            shown.append((question.label or question.id, tuple(_display(v) for v in values)))
+        elif question.required and not question.conditional:
+            missing.append(_name(question))
+    picked = {}
+    for key, attached in (files or {}).items():
+        slot = form.file(key)
+        picked[slot.id] = _file_urn(slot, attached)
+    uploads = []
+    for slot in form.files:
+        urn = picked.get(slot.id) or slot.prefilled
+        if urn:
+            uploads.append({"formElementUrn": slot.id, "inputUrn": urn})
+            shown.append((slot.label or slot.id, (urn,)))
+        elif slot.required:
+            missing.append(slot.label or slot.id)
+    if missing:
+        raise ValueError("Answer the required questions: " + "; ".join(missing))
+    body: dict[str, Any] = {
+        "followCompany": bool(follow_company),
+        "referenceId": reference_id or "",
+        # The app's `trk` code from the screen that opened the job; empty when none.
+        "trackingCode": "",
+    }
+    if tracking := tracking_bytes(tracking_id):
+        body["trackingId"] = tracking
+    body["responses"] = responses
+    body["fileUploadResponses"] = uploads
+    return Submission(job_id=form.job_id, body=body, answers=tuple(shown))
+
+
+def tracking_bytes(tracking_id: str | None) -> str | None:
+    """The app's TrackingUtils: a base64 tracking ID as its 16 bytes, one char per byte."""
+    if not tracking_id:
+        return None
+    try:
+        raw = base64.b64decode(tracking_id, validate=True)
+    except (binascii.Error, ValueError):
+        return None
+    return raw[:16].decode("latin-1") if len(raw) >= 16 else None
+
+
+def _values(question: Question, value: Answer) -> list[dict[str, Any]]:
+    if question.kind is QuestionKind.OTHER:
+        raise ValueError(
+            f"{_name(question)} uses {question.component}, which this client cannot answer."
+        )
+    if question.kind is QuestionKind.NUMBER:
+        return [{"textInputValue": _number(question, value)}]
+    if question.kind in _TEXT:
+        if not isinstance(value, str):
+            raise ValueError(f"{_name(question)} takes text.")
+        answer = value.strip()
+        if not answer:
+            raise ValueError(f"{_name(question)} is empty.")
+        # Android counts text in UTF-16 units, so an emoji uses two of the limit.
+        length = len(answer.encode("utf-16-le")) // 2
+        if question.max_length is not None and length > question.max_length:
+            raise ValueError(f"{_name(question)} allows at most {question.max_length} characters.")
+        if question.min_length is not None and length < question.min_length:
+            raise ValueError(f"{_name(question)} needs at least {question.min_length} characters.")
+        return [{"textInputValue": answer}]
+    if isinstance(value, int | float):
+        raise ValueError(f"{_name(question)} takes the label of one of its options.")
+    picks = [value] if isinstance(value, str) else list(value)
+    if not all(isinstance(pick, str) for pick in picks):
+        raise ValueError(f"{_name(question)} takes the label of one of its options.")
+    options = list(dict.fromkeys(_option(question, pick) for pick in picks))
+    if not options:
+        raise ValueError(f"{_name(question)} needs a choice.")
+    if question.kind is not QuestionKind.CHECKBOX and len(options) > 1:
+        raise ValueError(f"{_name(question)} takes one choice.")
+    if question.max_choices is not None and len(options) > question.max_choices:
+        raise ValueError(f"{_name(question)} allows at most {question.max_choices} choices.")
+    if question.min_choices is not None and len(options) < question.min_choices:
+        raise ValueError(f"{_name(question)} needs at least {question.min_choices} choices.")
+    return [{"entityInputValue": _entity(option)} for option in options]
+
+
+def _number(question: Question, value: Answer) -> str:
+    """The number as the app sends it; text must be a plain decimal such as -12 or 3.5."""
+    if isinstance(value, bool) or not isinstance(value, int | float | str):
+        raise ValueError(f"{_name(question)} takes a number.")
+    if isinstance(value, str):
+        if not _DECIMAL.fullmatch(value.strip()):
+            raise ValueError(f"{_name(question)} takes a plain decimal number.")
+        number = Decimal(value.strip())
+    elif isinstance(value, float) and not math.isfinite(value):
+        raise ValueError(f"{_name(question)} takes a finite number.")
+    else:
+        number = Decimal(repr(value)) if isinstance(value, float) else Decimal(value)
+    if question.whole_number and number != number.to_integral_value():
+        raise ValueError(f"{_name(question)} takes a whole number.")
+    if question.minimum is not None and number < Decimal(repr(question.minimum)):
+        raise ValueError(f"{_name(question)} must be at least {question.minimum:g}.")
+    if question.maximum is not None and number > Decimal(repr(question.maximum)):
+        raise ValueError(f"{_name(question)} must be at most {question.maximum:g}.")
+    return format(number.normalize(), "f")
+
+
+def _option(question: Question, pick: str) -> Option:
+    # A label wins over an enum string, which wins over a URN.
+    for attribute in ("label", "value", "urn"):
+        found = [option for option in question.options if getattr(option, attribute) == pick]
+        if found:
+            return found[0]
+    labels = ", ".join(repr(option.label) for option in question.options[:10])
+    raise ValueError(f"{_name(question)} has no option {pick!r}; options: {labels}")
+
+
+def _entity(option: Option) -> dict[str, str]:
+    if option.value is not None:
+        return {"inputEntityName": option.value}
+    entity = {}
+    if option.label is not None:
+        entity["inputEntityName"] = option.label
+    if option.urn is not None:
+        entity["inputEntityUrn"] = option.urn
+    return entity
+
+
+def _prefilled(question: Question) -> list[dict[str, Any]]:
+    """LinkedIn's prefill when complete enough to send, as the app checks before sending."""
+    values = list(question.input_values)
+    if not values:
+        return []
+    if question.kind in _TEXT:
+        first = values[0].get("textInputValue")
+        if not isinstance(first, str) or not first:
+            return []
+        if question.max_length is not None and len(first) > question.max_length:
+            return []
+    elif question.kind in _CHOICE and not all(value.get("entityInputValue") for value in values):
+        return []
+    return values
+
+
+def _file_urn(slot: FileQuestion, value: FileAnswer) -> str:
+    if isinstance(value, Resume):
+        return value.urn
+    if isinstance(value, UploadedFile):
+        kinds = [kind for kind, mime in DOCUMENT_TYPES.items() if mime == value.content_type]
+        if slot.mime_types and not set(kinds) & set(slot.mime_types):
+            raise ValueError(f"{slot.label or slot.id} accepts {', '.join(slot.mime_types)} files.")
+        if slot.max_size is not None and value.size > slot.max_size:
+            raise ValueError(f"{slot.label or slot.id} accepts files up to {slot.max_size} bytes.")
+        return value.urn
+    if isinstance(value, str) and value.startswith("urn:li:"):
+        return value
+    raise ValueError("A file slot takes an UploadedFile, a Resume or a resume URN.")
+
+
+def _response(urn: str, values: list[dict[str, Any]]) -> dict[str, Any]:
+    return {
+        "formElementUrn": urn,
+        "formElementInputValues": values,
+        "formElementInputValuesResolutionResults": values,
+    }
+
+
+def _display(value: dict[str, Any]) -> str:
+    if isinstance(value.get("textInputValue"), str):
+        return str(value["textInputValue"])
+    entity = value.get("entityInputValue")
+    if isinstance(entity, dict):
+        return str(entity.get("inputEntityName") or entity.get("inputEntityUrn") or "")
+    return str(next(iter(value.values()), ""))
+
+
+def _name(question: Question) -> str:
+    return repr(question.label) if question.label else question.id

async_linkedinlib/resources/jobs/resource.py

@@ -0,0 +1,212 @@
+"""Job details, saved jobs, the job tracker and Easy Apply through the app's Voyager calls.
+
+- `get`: the posting record (`voyagerJobsDashJobPostings/<urn>`) plus the job details top
+  card and description (`JobPostingDetailSectionsByCardSectionTypesV2`, cards TOP_CARD_V2
+  and JOB_DESCRIPTION_CARD, as the job details screen asks).
+- `save`/`unsave`: a `{"patch": {"$set": {"saved": ...}}}` on the job's save state
+  (`voyagerFeedDashSaveStates/urn:li:fsd_saveState:(SAVE,<job urn>)`), as SaveJobManager.
+- `tracked`: the "My jobs" tracker, `SearchClusterCollection` with intent
+  SEARCH_MY_ITEMS_JOB_SEEKER and a `cardType` filter.
+- `application`/`upload_file`/`submission`/`submit`: the Easy Apply steps of
+  JobApplyRepositoryImpl. Only `submit` applies, and it is sent once.
+"""
+
+import os
+import re
+from collections.abc import Mapping
+
+from ...exceptions import ProtocolError
+from ...models._json import dig
+from ...models._json import integer
+from ...models._json import items
+from ...models._json import obj
+from ...models._json import string
+from ...models.jobs import Job
+from ...models.jobs import TrackedJob
+from ...models.jobs import TrackedStatus
+from ...models.jobs_apply import ApplicationForm
+from ...models.jobs_apply import ApplicationStatus
+from ...models.jobs_apply import Submission
+from ...models.jobs_apply import UploadedFile
+from ...models.pagination import Cursor
+from ...models.pagination import Page
+from ...transport.voyager import GraphQLQuery
+from ...transport.voyager import Voyager
+from .. import paging
+from ..search.queries import CLUSTERS
+from . import answers as answer_rules
+from . import upload as uploads
+from .answers import Answer
+from .answers import FileAnswer
+
+POSTINGS = "voyagerJobsDashJobPostings"
+SAVE_STATES = "voyagerFeedDashSaveStates"
+ONSITE_APPLY = "voyagerJobsDashOnsiteApplyApplication"
+DETAIL_SECTIONS = GraphQLQuery(
+    "voyagerJobsDashJobPostingDetailSections.65c973ecf268b881b304305978de9fed",
+    "JobPostingDetailSectionsByCardSectionTypesV2",
+)
+APPLICATION = GraphQLQuery(
+    "voyagerJobsDashOnsiteApplyApplication.3a3ede1703d12540cf2e7e4bd04a3bbd",
+    "JobsOnsiteApplyApplicationByJobPosting",
+)
+# The cards the job details screen requests first: header, apply state and description.
+DETAIL_CARDS = ("TOP_CARD_V2", "JOB_DESCRIPTION_CARD")
+TRACKER_INTENT = "SEARCH_MY_ITEMS_JOB_SEEKER"
+
+_JOB = re.compile(
+    r"(?:urn:li:(?:fsd_jobPosting|jobPosting|fs_normalized_jobPosting|fs_jobPosting):)?([0-9]+)"
+)
+
+
+class Jobs:
+    """Read jobs, save them, and apply with Easy Apply in explicit steps."""
+
+    def __init__(self, voyager: Voyager) -> None:
+        self._voyager = voyager
+
+    async def get(self, job: str) -> Job:
+        """Read a job posting; HTTPError 404 when it does not exist."""
+        job_id = job_id_of(job)
+        urn = f"urn:li:fsd_jobPosting:{job_id}"
+        posting = await self._voyager.get(f"{POSTINGS}/{urn}")
+        sections = await self._voyager.query(
+            DETAIL_SECTIONS,
+            {"cardSectionTypes": list(DETAIL_CARDS), "jobPostingUrn": urn, "includeJobState": True},
+        )
+        found = obj(sections.get("jobsDashJobPostingDetailSectionsByCardSectionTypes"))
+        if string(posting, "entityUrn") != urn or not found:
+            raise ProtocolError("LinkedIn returned an unexpected job posting.")
+        return Job.from_json(job_id, posting, found)
+
+    async def save(self, job: str) -> None:
+        """Save a job to the viewer's saved jobs."""
+        await self._set_saved(job, True)
+
+    async def unsave(self, job: str) -> None:
+        """Remove a job from the viewer's saved jobs."""
+        await self._set_saved(job, False)
+
+    async def tracked(
+        self,
+        status: TrackedStatus = TrackedStatus.SAVED,
+        *,
+        count: int = 10,
+        cursor: Cursor | None = None,
+    ) -> Page[TrackedJob]:
+        """Read one page of the viewer's saved, in-progress, applied or archived jobs."""
+        status = TrackedStatus(status)
+        if type(count) is not int or not 1 <= count <= 100:
+            raise ValueError("count must be between 1 and 100.")
+        scope = status.value
+        start, token = paging.resume(cursor, "jobs.tracked", scope, self._voyager.owner)
+        variables = {
+            "query": {
+                "flagshipSearchIntent": TRACKER_INTENT,
+                "queryParameters": {"cardType": [status.value]},
+            },
+            "count": count,
+            "paginationToken": token,
+            "start": start,
+        }
+        data = await self._voyager.query(CLUSTERS, variables)
+        clusters = paging.collection(data, "searchDashClustersByAll")
+        results = [
+            obj(dig(entry, "item", "entityResult"))
+            for cluster in items(clusters.get("elements"))
+            for entry in items(cluster.get("items"))
+        ]
+        total = integer(clusters, "paging", "total")
+        if total is None:
+            total = integer(clusters, "metadata", "totalResultCount")
+        return paging.page(
+            clusters,
+            TrackedJob.from_result,
+            "jobs.tracked",
+            scope,
+            start,
+            count,
+            self._voyager.owner,
+            elements=results,
+            total=total,
+        )
+
+    async def application(self, job: str) -> ApplicationForm:
+        """Read a job's Easy Apply form; OperationRejected for jobs without Easy Apply."""
+        job_id = job_id_of(job)
+        data = await self._voyager.query(
+            APPLICATION, {"jobPostingUrn": f"urn:li:fsd_jobPosting:{job_id}"}
+        )
+        found = items(dig(data, "jobsDashOnsiteApplyApplicationByJobPosting", "elements"))
+        if not found:
+            raise ProtocolError("LinkedIn returned no Easy Apply form for this job.")
+        return ApplicationForm.from_json(job_id, found[0])
+
+    async def upload_file(
+        self,
+        file: str | os.PathLike[str] | bytes,
+        *,
+        filename: str | None = None,
+        max_size: int | None = None,
+    ) -> UploadedFile:
+        """Store a .pdf, .doc or .docx resume or cover letter for a submission to name.
+
+        The upload applies to nothing by itself and LinkedIn offers no way to delete it, so
+        pass the slot's limit (`form.file("Resume").max_size`) to refuse a file before it is
+        stored.
+        """
+        return await uploads.upload(self._voyager, file, filename, max_size)
+
+    def submission(
+        self,
+        form: ApplicationForm,
+        answers: Mapping[str, Answer],
+        *,
+        files: Mapping[str, FileAnswer] | None = None,
+        follow_company: bool = False,
+        job: Job | None = None,
+    ) -> Submission:
+        """Check answers against the form and build the submission; nothing is sent.
+
+        Keys are question URNs or labels. Text questions take strings, number questions
+        numbers, choice questions an option label (checkboxes a list of labels). Unanswered
+        questions keep LinkedIn's prefill. `files` maps file slots (URN, label or section
+        such as RESUME) to an UploadedFile, a Resume or a resume URN. Pass the `Job` from
+        `get` to send its tracking values like the app. The app's follow-company box
+        starts checked; here following is off unless asked for.
+        """
+        if job is not None and job.id != form.job_id:
+            raise ValueError("The job and the form belong to different jobs.")
+        return answer_rules.build(
+            form,
+            answers,
+            files,
+            follow_company=follow_company,
+            reference_id=job.reference_id if job else None,
+            tracking_id=job.tracking_id if job else None,
+        )
+
+    async def submit(self, submission: Submission) -> ApplicationStatus:
+        """Submit the application once; a timeout leaves the outcome unknown."""
+        if not isinstance(submission, Submission):
+            raise ValueError("Build the submission with Jobs.submission first.")
+        job_id_of(submission.job_id)
+        reply = await self._voyager.post(
+            ONSITE_APPLY, submission.body, {"action": "submitApplication"}
+        )
+        return ApplicationStatus.from_json(obj(reply.data.get("value")))
+
+    async def _set_saved(self, job: str, saved: bool) -> None:
+        urn = f"urn:li:fsd_jobPosting:{job_id_of(job)}"
+        await self._voyager.post(
+            f"{SAVE_STATES}/urn:li:fsd_saveState:(SAVE,{urn})",
+            {"patch": {"$set": {"saved": saved}}},
+        )
+
+
+def job_id_of(job: str) -> str:
+    """The numeric job ID from an ID or a job posting URN."""
+    found = _JOB.fullmatch(job) if isinstance(job, str) else None
+    if not found:
+        raise ValueError("A job ID or urn:li:fsd_jobPosting:<id> is required.")
+    return found[1]

async_linkedinlib/resources/jobs/upload.py

@@ -0,0 +1,78 @@
+"""Store a resume or cover letter for an Easy Apply form, as the app's file picker does.
+
+`voyagerJobsDashAmbryUploadUrls?action=requestUrl` returns an upload URL on
+www.linkedin.com (`/ambry/?x-li-ambry-ep=...`); the file bytes are posted there once and
+LinkedIn answers 201 with the stored file's `location`. The app answers the file slot
+with `urn:li:fsd_resume:<location>`. Nothing is attached or applied until a submission
+names that URN.
+"""
+
+import asyncio
+import os
+from pathlib import Path
+
+from ...exceptions import ProtocolError
+from ...exceptions import UnconfirmedWrite
+from ...models.jobs_apply import UploadedFile
+from ...transport import Transport
+from ...transport.voyager import Voyager
+
+UPLOAD_URLS = "voyagerJobsDashAmbryUploadUrls"
+# The app's MimeType names for the document types resume slots accept.
+DOCUMENT_TYPES = {
+    "PDF": "application/pdf",
+    "DOC": "application/msword",
+    "DOCX": "application/vnd.openxmlformats-officedocument.wordprocessingml.document",
+}
+_EXTENSIONS = {".pdf": "PDF", ".doc": "DOC", ".docx": "DOCX"}
+
+
+def document_type(filename: str) -> str:
+    """The app's MimeType name (PDF, DOC or DOCX) for a file name."""
+    kind = _EXTENSIONS.get(Path(filename).suffix.lower())
+    if kind is None:
+        raise ValueError("Resumes and cover letters must be .pdf, .doc or .docx files.")
+    return kind
+
+
+async def upload(
+    voyager: Voyager,
+    file: str | os.PathLike[str] | bytes,
+    filename: str | None,
+    max_size: int | None,
+) -> UploadedFile:
+    if max_size is not None and (type(max_size) is not int or max_size < 1):
+        raise ValueError("max_size must be a positive number of bytes.")
+    if isinstance(file, bytes):
+        if not filename:
+            raise ValueError("A file name is required when uploading bytes.")
+        data, name = file, filename
+    else:
+        path = Path(file)
+        if max_size is not None and (await asyncio.to_thread(path.stat)).st_size > max_size:
+            raise ValueError(f"The file is larger than {max_size} bytes.")
+        data = await asyncio.to_thread(path.read_bytes)
+        name = filename or path.name
+    if not data:
+        raise ValueError("The file is empty.")
+    if max_size is not None and len(data) > max_size:
+        raise ValueError(f"The file is larger than {max_size} bytes.")
+    kind = document_type(name)
+    reply = await voyager.post(
+        UPLOAD_URLS, {"contentType": kind, "filename": name}, {"action": "requestUrl"}
+    )
+    target = Transport.upload_path(reply.data.get("value"), "/ambry/")
+    if target is None:
+        raise ProtocolError("LinkedIn offered an upload location this client does not support.")
+    response = await voyager.transport.request(
+        "POST", target, content=data, headers={"content-type": DOCUMENT_TYPES[kind]}
+    )
+    location = response.headers.get("location")
+    if response.status_code != 201 or not location:
+        raise UnconfirmedWrite("LinkedIn did not confirm the file upload.")
+    return UploadedFile(
+        urn=f"urn:li:fsd_resume:{location}",
+        file_name=name,
+        content_type=DOCUMENT_TYPES[kind],
+        size=len(data),
+    )

async_linkedinlib/resources/mentions.py

@@ -0,0 +1,58 @@
+"""Mentions inside post and comment text, written as the app's text attributes.
+
+Offsets count Unicode code points: a live post on 2026-10-31 with an emoji before a mention
+kept the mention only with code-point offsets; UTF-16 offsets were silently dropped.
+"""
+
+import re
+from collections.abc import Sequence
+from typing import Any
+
+from ..models.comments import Mention
+
+# Mention URN kinds and the TextAttributeData union member the app writes for each.
+_KINDS = {"fsd_profile": "profileFullName", "fsd_company": "companyName"}
+_URN = re.compile(r"urn:li:(fsd_profile|fsd_company):[A-Za-z0-9_-]+")
+
+
+def attributes(
+    text: str, mentions: Sequence[Mention], *, companies: bool = True
+) -> list[dict[str, Any]]:
+    """One attribute per mention, in text order; mentions may not overlap or leave the text.
+
+    Without `companies`, only members (`urn:li:fsd_profile`) may be mentioned.
+    """
+    if isinstance(mentions, str | bytes | Mention) or not isinstance(mentions, Sequence):
+        raise ValueError("Mentions must be a sequence of Mention values.")
+    checked = [_checked(mention, companies) for mention in mentions]
+    written = []
+    end = 0
+    for mention in sorted(checked, key=lambda item: item.start):
+        if mention.start < end or mention.start + mention.length > len(text):
+            raise ValueError("Mentions must cover separate parts of the text.")
+        kind = _KINDS[mention.urn.split(":")[2]]
+        written.append(
+            {
+                "start": mention.start,
+                "length": mention.length,
+                "detailDataUnion": {kind: mention.urn},
+            }
+        )
+        end = mention.start + mention.length
+    return written
+
+
+def _checked(mention: object, companies: bool) -> Mention:
+    if (
+        not isinstance(mention, Mention)
+        or not isinstance(mention.urn, str)
+        or not _URN.fullmatch(mention.urn)
+        or (not companies and not mention.urn.startswith("urn:li:fsd_profile:"))
+        or type(mention.start) is not int
+        or type(mention.length) is not int
+        or mention.start < 0
+        or mention.length < 1
+    ):
+        who = "a urn:li:fsd_profile or urn:li:fsd_company" if companies else "a urn:li:fsd_profile"
+        raise ValueError(f"A mention needs {who} URN, a start of at least 0 and a positive length.")
+    return mention

async_linkedinlib/resources/paging.py

@@ -0,0 +1,88 @@
+"""Turn Voyager collections into pages, continuing them the way the app's pager does."""
+
+from collections.abc import Callable
+from typing import Any
+from typing import TypeVar
+
+from ..exceptions import ProtocolError
+from ..models._json import integer
+from ..models._json import items
+from ..models._json import obj
+from ..models._json import string
+from ..models.pagination import Cursor
+from ..models.pagination import Page
+
+T = TypeVar("T")
+
+
+def collection(data: dict[str, Any], field: str) -> dict[str, Any]:
+    """The named collection of a GraphQL `data` object; it must carry an elements list."""
+    found = data.get(field)
+    if not isinstance(found, dict) or not isinstance(found.get("elements"), list):
+        raise ProtocolError(f"LinkedIn's reply had no {field} collection.")
+    return found
+
+
+def resume(
+    cursor: Cursor | None, operation: str, scope: str, owner: str = ""
+) -> tuple[int, str | None]:
+    """Where a request starts and its pagination token; the cursor must belong to it."""
+    if cursor is None:
+        return 0, None
+    if not isinstance(cursor, Cursor):
+        raise ValueError("cursor must be a Cursor from a previous page.")
+    cursor.check(operation, scope, owner)
+    return cursor.start, cursor.token
+
+
+def page(
+    found: dict[str, Any],
+    read: Callable[[dict[str, Any]], T | None],
+    operation: str,
+    scope: str,
+    start: int,
+    count: int,
+    owner: str = "",
+    *,
+    elements: list[dict[str, Any]] | None = None,
+    total: int | None = None,
+) -> Page[T]:
+    """Read each element; elements that `read` turns into None are left out of `items`.
+
+    `elements` replaces the collection's own when results are nested deeper. `total` is
+    shown instead of `paging.total` for finders that report a separate estimate; paging
+    still stops at `paging.total`. Paging follows the collection's own elements, so a page
+    whose entries are all skipped still continues.
+    """
+    own = items(found.get("elements"))
+    bound = integer(found, "paging", "total")
+    results = tuple(
+        result for result in map(read, own if elements is None else elements) if result is not None
+    )
+    following = _next(found, bool(own), bound, operation, scope, start, count, owner)
+    return Page(results, following, bound if total is None else total, found)
+
+
+def _next(
+    found: dict[str, Any],
+    any_elements: bool,
+    total: int | None,
+    operation: str,
+    scope: str,
+    start: int,
+    count: int,
+    owner: str,
+) -> Cursor | None:
+    # The app continues at paging.start + paging.count while the total allows it, or while
+    # pages come back non-empty when there is no total. An empty page always ends here.
+    if not any_elements:
+        return None
+    paging = obj(found.get("paging"))
+    first = integer(paging, "start")
+    size = integer(paging, "count")
+    step = size if size is not None and size > 0 else count
+    next_start = (start if first is None else first) + step
+    if total is not None and next_start >= total:
+        return None
+    token = string(found, "metadata", "paginationToken") or None
+    return Cursor(operation, scope, next_start, token, owner)

async_linkedinlib/resources/posts/__init__.py

@@ -0,0 +1,6 @@
+"""Posts resource exports."""
+
+from .media import PostMedia  # Uploads, processing status and link previews for posts.
+from .resource import Posts  # Create, edit, delete, schedule and repost own posts.
+
+__all__ = ["PostMedia", "Posts"]