affinity-sdk 2.0.4__tar.gz → 2.0.5__tar.gz

{affinity_sdk-2.0.4 → affinity_sdk-2.0.5}/.github/workflows/plugin-build.yml

@@ -84,6 +84,8 @@ jobs:
       - name: Build MCPB bundle
         run: |
           cd mcp
+          # mcp-bash refuses to load server.d/policy.sh from group/other-writable paths
+          chmod -R go-w .
           mcp-bash bundle --output dist --verbose
           ls -la dist/*.mcpb
           echo "MCPB bundle created"

{affinity_sdk-2.0.4 → affinity_sdk-2.0.5}/.github/workflows/plugin-release.yml

@@ -106,6 +106,8 @@ jobs:
       - name: Build MCPB bundle
         run: |
           cd mcp
+          # mcp-bash refuses to load server.d/policy.sh from group/other-writable paths
+          chmod -R go-w .
           mcp-bash bundle --output dist --verbose
           ls -la dist/*.mcpb
 

{affinity_sdk-2.0.4 → affinity_sdk-2.0.5}/.github/workflows/release.yml

@@ -221,6 +221,8 @@ jobs:
       - name: Build MCPB bundle
         run: |
           cd mcp
+          # mcp-bash refuses to load server.d/policy.sh from group/other-writable paths
+          chmod -R go-w .
           mcp-bash bundle --output dist --verbose
           ls -la dist/*.mcpb
 

{affinity_sdk-2.0.4 → affinity_sdk-2.0.5}/CHANGELOG.md

@@ -5,6 +5,64 @@ All notable changes to this project will be documented in this file.
 The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.1.0/),
 and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
 
+## [2.0.5] - 2026-10-14
+
+**Exception to semantic versioning** (as 2.0.2–2.0.4): two fixes change what a call returns or
+what the CLI prints. Each is marked **Behavior change**.
+
+### Changed
+
+- **Behavior change. CLI: deleted dropdown options in `field history` and `field history-bulk`
+  (`--json`).** Affinity sends an option deleted since as its bare text ("Reach Out") and a live
+  one as `{id, text, rank, color}`; the CLI passed both through, so one field's history mixed
+  strings and objects. A deleted option is now `{"id": null, "text": "Reach Out", "deleted":
+  true}`, so every dropdown value has a `text`. Text fields keep their string values; live
+  options are unchanged. When a value is plain text the CLI reads the field's metadata (one call)
+  to tell a dropdown from a text field (`history-bulk --list-id` already has it). Table and CSV
+  output show the text, as before.
+- **Behavior change. SDK: `on_error="skip"` leaves failed records out of
+  `AsyncReminderService.list_batch` and `AsyncFileService.list_batch`.** A failed request used
+  to leave its ids in the result with empty or partial lists, which looked like "no reminders" /
+  "no files"; one failed reminders request (50 ids) silently hid them all. They are now absent
+  from the result, as with every other `on_error="skip"` method: a requested id with no key
+  failed.
+- SDK: `field_value_changes.iter_all()` reads 10,000 changes per call by default (was 100), the
+  V1 maximum: a 16,000-change history takes 3 calls instead of 161 (paging ends on an empty
+  page). Pass `page_size` for smaller
+  pages.
+- SDK: `AsyncCompanyService.batch_get` / `AsyncPersonService.batch_get` with
+  `with_interaction_dates` and `field_ids` / `field_types` read the fields in one call per 100
+  ids and the dates in one V1 call per record: about N + N/100 calls instead of 2N. Results are
+  the same. Under `on_error="skip"` a failed fields call falls back to one read per id of it.
+
+### Added
+
+- CLI: `list export --filter`, `company ls --filter` and `person ls --filter` report how the
+  filter was split in `meta.serverFilter` (`--json`): `pushed` (conditions Affinity's search
+  applied), `local` (checked only locally, with reasons) and, on `list export` when the search
+  was refused or turned off, `fallback` (why: refused, the list's fields unreadable, or
+  `XAFFINITY_QUERY_SERVER_FILTER=0`; the whole filter then ran locally). `list export
+  --dry-run` shows it as `data.serverFilter`. A `--cursor` resume doesn't report it.
+  Like `query --include-meta`, but always present with `--json`.
+- SDK: `persons.get_list_entries()` takes `limit` and `cursor` (it returned only the first page).
+
+### Fixed
+
+- SDK: `companies.get_list_entries()` and `persons.get_list_entries()` set each entry's
+  `entity_id` and `entity_type` (`ORGANIZATION` / `PERSON`); the endpoint doesn't send them, so
+  they were `None`. `entity` stays `None` there. A `cursor` from another company's or person's
+  entries raises `ValueError` instead of labelling its entries with the wrong record. CLI:
+  `company get --expand list-entries` and `person get --expand list-entries` (`--json`) now
+  show each entry's `entityId` and `entityType` (1 company, 0 person).
+- SDK: the `ListEntry` docstring said it always contains the entity; it says where `entity` is
+  filled.
+- Docs: filtered-run cursors start with `xsearch2:` (the CLI page, filtering guide, CLI skill
+  and MCP data model said `xsearch1:`). The `field changes` docs say a deleted dropdown option is
+  `{"referenceType": "deleted-entity", "displayValue": ...}`. The companies and persons pages
+  say what reading interaction dates for many records costs, and the companies page and
+  `batch_get` docstring point to the relationship-intelligence fields for last / next meeting
+  dates.
+
 ## [2.0.4] - 2026-10-14
 
 **Exception to semantic versioning** (the maintainer's call, as 2.0.2 and 2.0.3): which API key

{affinity_sdk-2.0.4 → affinity_sdk-2.0.5}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.5
 Name: affinity-sdk
-Version: 2.0.4
+Version: 2.0.5
 Summary: A modern, strongly-typed Python SDK for the Affinity CRM API
 Project-URL: Homepage, https://github.com/yaniv-golan/affinity-sdk
 Project-URL: Documentation, https://yaniv-golan.github.io/affinity-sdk/latest/

{affinity_sdk-2.0.4 → affinity_sdk-2.0.5}/affinity/cli/commands/company_cmds.py

@@ -436,6 +436,7 @@ def company_ls(
 
         # --filter (or a cursor from a filtered run): Affinity's search filters on its side
         if filter_expr is not None or is_filter_cursor(cursor):
+            server_filter: dict[str, Any] = {}
             found, next_token = filtered_ls(
                 client.companies,
                 entity="company",
@@ -448,6 +449,7 @@ def company_ls(
                 max_results=max_results,
                 all_pages=all_pages,
                 warnings=warnings,
+                server_filter=server_filter,
             )
             return CommandOutput(
                 data={"companies": found},
@@ -457,6 +459,7 @@ def company_ls(
                     if next_token
                     else None
                 ),
+                server_filter=server_filter or None,
                 api_called=True,
             )
 

{affinity_sdk-2.0.4 → affinity_sdk-2.0.5}/affinity/cli/commands/field_cmds.py

@@ -123,6 +123,75 @@ def _field_value_change_payload(item: FieldValueChange) -> dict[str, object]:
     }
 
 
+_DROPDOWN_VALUE_TYPES = frozenset(
+    {"dropdown", "dropdown-multi", "ranked-dropdown", "status-dropdown"}
+)
+
+
+def _is_dropdown(meta: FieldMetadata) -> bool:
+    """True for a dropdown field. V1 metadata's value type 2 covers both text and dropdown
+    fields, so there a dropdown is the ranked kind (7) or a field with options."""
+    raw = getattr(meta, "value_type_raw", None)
+    if isinstance(raw, int):
+        return raw == 7 or bool(getattr(meta, "dropdown_options", None))
+    if not isinstance(raw, str):
+        value_type = getattr(meta, "value_type", None)
+        raw = getattr(value_type, "value", value_type)
+    kind = raw
+    return str(kind).lower() in _DROPDOWN_VALUE_TYPES
+
+
+def _mark_deleted_options(
+    rows: list[dict[str, object]],
+    field_id: str,
+    *,
+    meta: FieldMetadata | None,
+    ctx: CLIContext,
+    warnings: list[str],
+) -> None:
+    """In a dropdown's history, V1 sends an option deleted since as its bare text ("Reach Out")
+    and a live one as {id, text, rank, color}. Give the deleted ones the same shape:
+    {"id": null, "text": "Reach Out", "deleted": true}, so every value has a .text.
+
+    ``meta`` is the field's metadata when the caller has it (V2 list fields); otherwise V1
+    field metadata is read, only when some value is a bare string.
+    """
+
+    def is_text(value: object) -> bool:
+        return isinstance(value, str) or (
+            isinstance(value, list) and any(isinstance(v, str) for v in value)
+        )
+
+    if not any(is_text(row.get("value")) for row in rows):
+        return
+    if meta is None:
+        try:
+            metas = ctx.get_client(warnings=warnings).fields.list()
+        except Exception:  # the history itself was read: don't fail it over its labels
+            metas = []
+        meta = next((m for m in metas if _same_field(m.id, field_id)), None)
+    if meta is None:
+        warnings.append(
+            f"Could not read {field_id}'s type, so text values are shown as sent; in a dropdown "
+            "they are options deleted since."
+        )
+        return
+    if not _is_dropdown(meta):
+        return
+
+    def deleted(value: object) -> object:
+        if isinstance(value, str):
+            return {"id": None, "text": value, "deleted": True}
+        return value
+
+    for row in rows:
+        value = row.get("value")
+        if isinstance(value, list):
+            row["value"] = [deleted(v) for v in value]
+        else:
+            row["value"] = deleted(value)
+
+
 def _validate_history_selector(
     person_id: int | None,
     company_id: int | None,
@@ -470,6 +539,7 @@ def field_history(
             _refuse_if_global(ctx, warnings, field_id, "--list-entry-id")
 
         payload = [_field_value_change_payload(item) for item in changes]
+        _mark_deleted_options(payload, field_id, meta=None, ctx=ctx, warnings=warnings)
 
         # Build CommandContext for richer output metadata
         # Per spec: required params are inputs, optional params are modifiers
@@ -1297,6 +1367,7 @@ def field_history_bulk(
         # What kind of field: a list field's changes belong to list entries, a global field's to
         # the company/person (they carry no list entry, so per-entry reads find none).
         field_kind: str | None = None
+        field_meta: FieldMetadata | None = None  # V2 metadata, when the list's fields were read
         if list_id is not None:
             try:
                 list_fields: list[FieldMetadata] | None = client.lists.get_fields(
@@ -1332,6 +1403,7 @@ def field_history_bulk(
                         exit_code=2,
                     )
                 field_kind = kind
+                field_meta = match
 
         # Global field: one read per company/person, labelled with its entry on the list
         entity_entry: dict[int, int] = {}  # entity id -> the first entry of it on the list
@@ -1649,6 +1721,7 @@ def field_history_bulk(
             partial = failed_count > 0
             if list_entry_ids is not None and not all_changes and not async_warnings:
                 _refuse_if_global(ctx, warnings, field_id, "--list-entry-ids")
+        _mark_deleted_options(all_changes, field_id, meta=field_meta, ctx=ctx, warnings=warnings)
         all_changes.sort(
             key=lambda r: (str(r.get("changedAt") or ""), str(r.get("id") or "").zfill(20))
         )

{affinity_sdk-2.0.4 → affinity_sdk-2.0.5}/affinity/cli/commands/list_cmds.py

@@ -827,12 +827,19 @@ def list_export(
 
         # --filter: Affinity's search applies what it can; the whole filter still runs locally
         list_search: ListSearch | None = None
+        # meta.serverFilter: what Affinity's search applied, what ran locally, and why not
+        server_filter: dict[str, Any] | None = None
         if filter_expr and not saved_view:
             if os.environ.get("XAFFINITY_QUERY_SERVER_FILTER", "1") != "0":
                 try:
                     list_search = plan_list_search(client, list_id, filter_expr)
                 except (AuthorizationError, NotFoundError, SDKValidationError) as e:
                     warnings.append(f"Filtering locally: could not read the list's fields ({e}).")
+                    server_filter = {"fallback": f"could not read the list's fields ({e})"}
+                else:
+                    server_filter = {"pushed": list_search.pushed, "local": list_search.local}
+            else:
+                server_filter = {"fallback": "XAFFINITY_QUERY_SERVER_FILTER=0"}
             # Without a scope flag a locally filtered export would silently return only what
             # matched on the first page. When Affinity applies the whole filter, page one is
             # the first page of matches, so no flag is needed.
@@ -1018,6 +1025,8 @@ def list_export(
                     "cursor": cursor,
                     "csv": want_csv,
                 }
+            if server_filter is not None:
+                data["serverFilter"] = server_filter
             if want_expand:
                 # Estimate API calls for expansion (get_size uses V1 API for accurate values)
                 entry_count = client.lists.get_size(list_id)
@@ -1903,6 +1912,8 @@ def list_export(
             from ..field_utils import truncation_warnings
 
             warnings.extend(table_iter_state.get("warnings", []))
+            if server_filter is not None and table_iter_state.get("searchFallback"):
+                server_filter["fallback"] = table_iter_state["searchFallback"]
             warnings.extend(
                 truncation_warnings(
                     table_iter_state.get("truncatedFields", []), filtered=bool(filter_expr)
@@ -1972,6 +1983,7 @@ def list_export(
                 # to truncation, so mark truncated=True whenever the flag is set.
                 truncated=True if first_page_only else None,
                 truncation_reason="firstPageOnly" if first_page_only else None,
+                server_filter=server_filter,
             )
         raise AssertionError("unreachable")
 
@@ -2192,6 +2204,7 @@ def _iterate_list_entries(
                 state.setdefault("warnings", []).append(
                     f"Affinity's search refused the filter, filtering locally: {e}"
                 )
+                state["searchFallback"] = getattr(e, "message", None) or str(e)
         else:
             yield from _search_rows(
                 entries,

{affinity_sdk-2.0.4 → affinity_sdk-2.0.5}/affinity/cli/commands/person_cmds.py

@@ -15,7 +15,7 @@ from rich.progress import BarColumn, Progress, SpinnerColumn, TaskID, TextColumn
 
 from affinity.exceptions import DuplicateEntityError
 from affinity.models.entities import Person, PersonCreate, PersonUpdate
-from affinity.models.types import FieldId
+from affinity.models.types import EntityType, FieldId
 from affinity.types import CompanyId, FieldType, ListId, PersonId
 
 from ..click_compat import RichCommand, RichGroup, click
@@ -308,6 +308,7 @@ def person_ls(
 
         # --filter (or a cursor from a filtered run): Affinity's search filters on its side
         if filter_expr is not None or is_filter_cursor(cursor):
+            server_filter: dict[str, Any] = {}
             found, next_token = filtered_ls(
                 client.persons,
                 entity="person",
@@ -320,6 +321,7 @@ def person_ls(
                 max_results=max_results,
                 all_pages=all_pages,
                 warnings=warnings,
+                server_filter=server_filter,
             )
             return CommandOutput(
                 data={"persons": found},
@@ -329,6 +331,7 @@ def person_ls(
                     if next_token
                     else None
                 ),
+                server_filter=server_filter or None,
                 api_called=True,
             )
 
@@ -1190,6 +1193,14 @@ def person_get(
                     pagination=pagination,
                     keep_item=keep_entry if list_id is not None else None,
                 )
+                # The endpoint doesn't name the entity: label each entry with this person, as
+                # persons.get_list_entries() (and company get) do
+                for entry in entries_items:
+                    if isinstance(entry, dict):
+                        if entry.get("entityId") is None:
+                            entry["entityId"] = int(person_id)
+                        if entry.get("entityType") is None:
+                            entry["entityType"] = int(EntityType.PERSON)
                 data["listEntries"] = entries_items
 
         if "list-entries" in expand_set and entries_items and ctx.output != "json":

{affinity_sdk-2.0.4 → affinity_sdk-2.0.5}/affinity/cli/context.py

@@ -995,6 +995,7 @@ def build_result(
     truncation_reason: str | None = None,
     not_requested: list[dict[str, str]] | None = None,
     explanation: str | None = None,
+    server_filter: dict[str, Any] | None = None,
     affinity_api_version: str | list[str] | None = None,
     affinity_api_version_per_operation: list[str] | None = None,
 ) -> CommandResult:
@@ -1013,6 +1014,7 @@ def build_result(
         truncation_reason=truncation_reason,
         not_requested=not_requested,
         explanation=explanation,
+        server_filter=server_filter,
     )
     return CommandResult(
         ok=ok,

{affinity_sdk-2.0.4 → affinity_sdk-2.0.5}/affinity/cli/entity_search.py

@@ -172,9 +172,11 @@ def filtered_ls(
     max_results: int | None,
     all_pages: bool,
     warnings: list[str],
+    server_filter: dict[str, Any] | None = None,
 ) -> tuple[list[dict[str, Any]], str | None]:
     """``company ls`` / ``person ls`` with ``--filter`` (or a search ``--cursor``): rows and the
-    next cursor. Raises ``CLIError`` for a filter Affinity's search can't apply at all."""
+    next cursor. Raises ``CLIError`` for a filter Affinity's search can't apply at all.
+    ``server_filter`` (when given) receives the split: ``pushed`` and ``local`` conditions."""
     from affinity.filters import parse as parse_filter
 
     from .errors import CLIError
@@ -241,6 +243,8 @@ def filtered_ls(
             hint="details.local names the conditions Affinity's search can't apply.",
             details=details,
         )
+    if server_filter is not None:
+        server_filter.update(pushed=plan.pushed, local=plan.local)
     warnings.extend(plan.caveats)
     if plan.local:
         warnings.append(

{affinity_sdk-2.0.4 → affinity_sdk-2.0.5}/affinity/cli/results.py

@@ -303,6 +303,10 @@ class CommandMeta(AffinityModel):
     not_requested: list[dict[str, str]] | None = Field(None, alias="notRequested")
     # Server-provided explanation of how a query was interpreted (semantic search).
     explanation: str | None = None
+    # How a --filter was split: {"pushed": [...], "local": [...]} — what Affinity's search
+    # applied and what was checked locally — plus "fallback" (why) when the search was refused or
+    # turned off: then the whole filter ran locally (and pushed/local may be absent).
+    server_filter: dict[str, Any] | None = Field(None, alias="serverFilter")
     # Affinity V2 API version(s) that answered this command (echoed X-Affinity-Api-Version,
     # incl. cache hits): a string, or a sorted list when more than one answered.
     affinity_api_version: str | list[str] | None = Field(None, alias="affinityApiVersion")

{affinity_sdk-2.0.4 → affinity_sdk-2.0.5}/affinity/cli/runner.py

@@ -38,6 +38,7 @@ class CommandOutput:
     # [{"key": "data.listEntries", "flag": "--expand list-entries"}, ...]
     not_requested: list[dict[str, str]] | None = None
     explanation: str | None = None  # meta.explanation (semantic search)
+    server_filter: dict[str, Any] | None = None  # meta.serverFilter (--filter split)
     api_called: bool = False
     exit_code: int = 0  # Allow commands to specify non-zero exit codes (e.g., check-key)
 
@@ -52,6 +53,7 @@ def _emit_json(result: CommandResult) -> None:
             "truncationReason",
             "notRequested",
             "explanation",
+            "serverFilter",
             "affinityApiVersion",
             "affinityApiVersionPerOperation",
         ):
@@ -239,6 +241,7 @@ def run_command(ctx: CLIContext, *, command: str, fn: CommandFn) -> None:
             truncation_reason=out.truncation_reason,
             not_requested=out.not_requested,
             explanation=out.explanation,
+            server_filter=out.server_filter,
             affinity_api_version=api_version,
             affinity_api_version_per_operation=ctx.api_versions_per_operation(),
         )

{affinity_sdk-2.0.4 → affinity_sdk-2.0.5}/affinity/models/entities.py

@@ -737,7 +737,10 @@ class ListEntry(AffinityModel):
     """
     A row in a list, linking an entity to a list.
 
-    Contains the entity data and list-specific field values.
+    Holds the list-specific field values and which entity the row is for (``entity_id``,
+    ``entity_type``). ``entity`` (a summary of that entity) is filled only where the endpoint
+    embeds it, e.g. a list's entries; it is ``None`` from ``companies.get_list_entries()`` and
+    ``persons.get_list_entries()``.
     """
 
     id: ListEntryId

affinity_sdk-2.0.5/affinity/services/_batch_interactions.py

@@ -0,0 +1,92 @@
+"""``batch_get`` with interaction dates and field filters, in fewer calls.
+
+``get(id, with_interaction_dates=True, field_ids=...|field_types=...)`` makes two calls per id: V1
+``/organizations|persons/{id}`` for the dates and V2 ``/companies|persons/{id}`` for the fields.
+For many ids the V2 half goes as one ``/companies|persons?ids=...`` call per 100 ids instead, and
+each record is merged exactly as ``get`` merges it.
+"""
+
+from __future__ import annotations
+
+import asyncio
+from collections.abc import Awaitable, Callable, Sequence
+from typing import Any, Literal, TypeVar
+
+from ..exceptions import AffinityError, NotFoundError
+
+IdT = TypeVar("IdT", bound=int)
+
+V2_IDS_PER_CALL = 100  # V2 list endpoints return at most 100 records per page
+
+
+async def batch_get_with_dates(
+    client: Any,
+    ids: Sequence[IdT],
+    *,
+    v1_path: str,
+    v2_path: str,
+    kind: str,
+    v1_params: dict[str, Any],
+    v2_params: dict[str, Any],
+    max_concurrent: int,
+    on_error: Literal["raise", "skip"],
+    get_one: Callable[[IdT], Awaitable[Any]],
+    build: Callable[[dict[str, Any]], Any],
+) -> dict[IdT, Any]:
+    """Records for ``ids`` (unique, in order): the V2 fields of each merged with its V1
+    interaction dates and interactions. ``get_one`` (the plain per-id ``get``) re-reads the ids
+    of a V2 call that failed under ``on_error="skip"``, so one bad id doesn't drop 99 others.
+    """
+    fields_by_id: dict[int, dict[str, Any]] = {}
+    retry_one_by_one: set[int] = set()
+    for start in range(0, len(ids), V2_IDS_PER_CALL):
+        chunk = list(ids[start : start + V2_IDS_PER_CALL])
+        try:
+            data = await client.get(
+                v2_path,
+                params={**v2_params, "ids": [int(i) for i in chunk], "limit": V2_IDS_PER_CALL},
+            )
+            while True:
+                for item in data.get("data", []):
+                    fields_by_id[int(item["id"])] = item
+                next_url = (data.get("pagination") or {}).get("nextUrl")
+                if not next_url:
+                    break
+                data = await client.get_url(next_url)
+        except AffinityError:
+            if on_error == "raise":
+                raise
+            retry_one_by_one.update(int(i) for i in chunk)
+
+    async def dates_of(record_id: IdT) -> tuple[IdT, Any | None]:
+        try:
+            if int(record_id) in retry_one_by_one:
+                return record_id, await get_one(record_id)
+            fields = fields_by_id.get(int(record_id))
+            if fields is None:
+                raise NotFoundError(f"{kind} {int(record_id)} not found", status_code=404)
+            dates = await client.get(f"{v1_path}/{int(record_id)}", params=v1_params, v1=True)
+            merged = dict(fields)
+            merged["interaction_dates"] = dates.get("interaction_dates")
+            merged["interactions"] = dates.get("interactions")
+            return record_id, build(merged)
+        except AffinityError:
+            if on_error == "raise":
+                raise
+            return record_id, None
+
+    results: dict[IdT, Any] = {}
+    for start in range(0, len(ids), max_concurrent):
+        tasks = [asyncio.create_task(dates_of(i)) for i in ids[start : start + max_concurrent]]
+        try:
+            for done in asyncio.as_completed(tasks):
+                record_id, record = await done
+                if record is not None:
+                    results[record_id] = record
+        except BaseException:
+            for task in tasks:
+                if not task.done():
+                    task.cancel()
+            await asyncio.gather(*tasks, return_exceptions=True)
+            raise
+    return results

{affinity_sdk-2.0.4 → affinity_sdk-2.0.5}/affinity/services/_org_reads.py

@@ -5,11 +5,14 @@ from __future__ import annotations
 from collections.abc import Iterable
 from datetime import datetime
 from typing import Any, TypeVar
+from urllib.parse import urlsplit
 
 from pydantic import BaseModel
 
 from ..exceptions import AffinityError
-from ..models.pagination import PaginatedResponse, PaginationInfoWithTotal
+from ..models.entities import ListEntry
+from ..models.pagination import PaginatedResponse, PaginationInfo, PaginationInfoWithTotal
+from ..models.types import EntityType
 from ._v2_filters import v2_filter_datetime
 
 T = TypeVar("T", bound=BaseModel)
@@ -69,6 +72,39 @@ def check_cursor_alone(cursor: str | None, *others: Any) -> None:
         )
 
 
+def check_list_entries_cursor(cursor: str, path: str) -> None:
+    """A cursor of ``/companies/{id}/list-entries`` (or persons) must be for the entity asked
+    about: its entries are labelled with that entity, so another entity's cursor would mislabel
+    them."""
+    if not urlsplit(cursor).path.endswith(path):
+        raise ValueError(
+            f"This cursor is not for {path}: pass the cursor with the same entity id that "
+            "returned it."
+        )
+
+
+def entity_list_entries_page(
+    data: dict[str, Any], *, entity_id: int, entity_type: EntityType
+) -> PaginatedResponse[ListEntry]:
+    """A page of one entity's list entries (``/companies|persons/{id}/list-entries``).
+
+    Those items don't name their entity, so ``entity_id`` / ``entity_type`` are filled in from
+    the entity asked about (a value the API does send is kept). ``entity`` stays ``None``.
+    """
+    items = []
+    for raw in data.get("data", []):
+        item = dict(raw)
+        if item.get("entityId") is None:
+            item["entityId"] = int(entity_id)
+        if item.get("entityType") is None:
+            item["entityType"] = int(entity_type)
+        items.append(ListEntry.model_validate(item))
+    return PaginatedResponse[ListEntry](
+        data=items,
+        pagination=PaginationInfo.model_validate(data.get("pagination", {})),
+    )
+
+
 def check_positive_limit(limit: int | None) -> None:
     """For endpoints without a documented maximum: ``limit`` must still be at least 1."""
     if limit is not None and limit < 1: