affinity-sdk 2.0.7__tar.gz → 2.0.8__tar.gz

{affinity_sdk-2.0.7 → affinity_sdk-2.0.8}/CHANGELOG.md

@@ -5,6 +5,41 @@ 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.8] - 2026-11-05
+
+**Exception to semantic versioning** (as 2.0.2–2.0.7): one fix changes which rows a filter
+returns. It is marked **Behavior change**.
+
+### Highlights
+
+Filters on a person or company field by id (`Owner = 12345`) now run on Affinity's side for list
+entries, so `list export` needs no `--all` and downloads only the matching rows. A number on a
+record reference is its id only.
+
+### Changed
+
+- **Behavior change (correctness fix). CLI and SDK (`--filter`, `query`, `affinity.filters`,
+  `list(filter=...)`): an integer or 1–20 digits on a person, company or other record-reference
+  field matches the record's id only.** It no longer matches a record whose name is those digits;
+  use `starts_word` to find such a name. (As before, a reference with no name, such as a person
+  without a first and last name or a company with an empty name, can't be matched by id.)
+- CLI and SDK: on list entries, `=` and `in` with record ids on a person or company field, and
+  `=`, `in`, `has_any` and `has_all` with ids on a multi-person or multi-company field, go to
+  Affinity's search. Such filters need no `--all` / `--max-results` and download only matching
+  rows. Ids above 2147483647, names, `!=`, enriched person and company fields, and filters on
+  `company ls` / `person ls` / `query` from companies or persons are still checked locally.
+- CLI: a `starts_word` with no letter (`starts_word "360"`) is checked locally instead of being
+  sent as Affinity's name search. On `list export` it needs a scope flag; on `company ls`,
+  `person ls` and `query` from companies or persons it needs another field condition (or use
+  `--query`).
+
+### Fixed
+
+- CLI: `list export --filter` with a filter Affinity's search refuses (for example a key without
+  the "Export data from Lists" permission), run without `--all`, `--max-results` or
+  `--first-page-only`, exits 2 before any output. It used to print only the first page, as if it
+  were the whole result. `details.refused` carries Affinity's reason.
+
 ## [2.0.7] - 2026-11-03
 
 **Exception to semantic versioning** (as 2.0.2–2.0.6): two fixes change which rows a filter

{affinity_sdk-2.0.7 → affinity_sdk-2.0.8}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.5
 Name: affinity-sdk
-Version: 2.0.7
+Version: 2.0.8
 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.7 → affinity_sdk-2.0.8}/affinity/_filtering/pushdown.py

@@ -21,12 +21,28 @@ from dataclasses import dataclass, field
 from datetime import date, datetime, timedelta
 from typing import Any
 
-from ..compare import compare_values
+from ..compare import _as_entity_id, compare_values
 from ..criteria import Condition, FilterGroup, filter_value_type
 from ..models.entities import DropdownOption, FieldMetadata
 from .dates import parse_date_value
 from .where import WhereClause
 
+# Person and company id conditions (list entries only): ``=`` / ``in`` on a single field,
+# membership and set conditions on a multi field. Always in ALL_MAPPINGS, so the golden keeps
+# testing them; only the pairs that passed it are in VERIFIED.
+REFERENCE_MAPPINGS: frozenset[tuple[str, str]] = frozenset(
+    {
+        ("person", "is-any-of"),
+        ("company", "is-any-of"),
+        ("person-multi", "has-any-of"),
+        ("person-multi", "has-all-of"),
+        ("company-multi", "has-any-of"),
+        ("company-multi", "has-all-of"),
+    }
+)
+# Largest record id sent. Affinity's search refused ids above this in the golden run.
+ID_MAX = 2**31 - 1
+
 # (filter value type, server operator) pairs confirmed by tools/search_golden.py: no record the
 # local filter keeps was missing from the server's answer (5 lists, about 3,750 entries,
 # 2026-10-13). Enriched fields and shared field names were excluded (they stay local).
@@ -84,8 +100,16 @@ VERIFIED: frozenset[tuple[str, str]] = frozenset(
         ("location", "is-not-empty"),
         ("location-multi", "is-empty"),
         ("location-multi", "is-not-empty"),
+        # Fifth run (person and company ids on list entries, 6 lists, about 12,300 entries,
+        # 2026-11-04; the single-company field on a list of its own, 12 cases): no record
+        # missing from the server's answer.
+        *REFERENCE_MAPPINGS,
     }
 )
+# What goes to the company and person search endpoints: the golden run can only check list
+# entries (the company directory can't be downloaded to compute an independent local set), so
+# id conditions on person and company fields stay local there.
+ENTITY_VERIFIED: frozenset[tuple[str, str]] = VERIFIED - REFERENCE_MAPPINGS
 
 _NUMBER_OPS = {
     "eq": "is-equal-to",
@@ -125,6 +149,7 @@ ALL_MAPPINGS: frozenset[tuple[str, str]] = frozenset(
         for op in ("has-any-of", "has-all-of", "has-none-of")
     }
     | {("number", "is-not-equal-to")}
+    | REFERENCE_MAPPINGS
 )
 
 _DROPDOWN = {"dropdown", "ranked-dropdown"}
@@ -232,12 +257,14 @@ def split_where(
 
 def _plain_term(value: Any) -> bool:
     """A name search term Affinity's search matches like ``starts_word``: letters, digits and
-    spaces, 3+ characters (a term with punctuation, e.g. a placeholder name "- -", can match
-    differently; golden test, 2026-10-13)."""
+    spaces, 3+ characters with at least one letter (a term with punctuation, e.g. a placeholder
+    name "- -", can match differently; golden test, 2026-10-13. A number is never sent: the
+    search may read it as a phone number or an id)."""
     return (
         isinstance(value, str)
         and re.fullmatch(r"[^\W_]+(?: [^\W_]+)*", value.strip()) is not None
         and len(value.strip()) >= 3
+        and any(c.isalpha() for c in value)
     )
 
 
@@ -338,17 +365,24 @@ def _field(w: WhereClause, ctx: _Ctx) -> tuple[FieldMetadata, str] | None:
     return meta, vt
 
 
-def _emit(
-    w: WhereClause, meta: FieldMetadata, vt: str, op: str, value: Any, ctx: _Ctx
-) -> Condition | None:
+def _refused(w: WhereClause, meta: FieldMetadata, vt: str, op: str, ctx: _Ctx) -> bool:
+    """True (with the reason noted) when the pair isn't verified or the field doesn't take it."""
     if (vt, op) not in ctx.verified:
         ctx.local.append(f"{_describe(w)}: {vt} {op} not verified against the API yet")
-        return None
+        return True
     allowed = [
         str(o.get("id")) for o in (meta.filterability or {}).get("operators") or [] if o.get("id")
     ]
     if "filterability" in meta.model_fields_set and allowed and op not in allowed:
         ctx.local.append(f"{_describe(w)}: the field doesn't take {op}")
+        return True
+    return False
+
+
+def _emit(
+    w: WhereClause, meta: FieldMetadata, vt: str, op: str, value: Any, ctx: _Ctx
+) -> Condition | None:
+    if _refused(w, meta, vt, op, ctx):
         return None
     if isinstance(value, list) and not 1 <= len(value) <= MAX_VALUES:
         ctx.local.append(f"{_describe(w)}: needs 1 to {MAX_VALUES} values on the server")
@@ -399,8 +433,13 @@ def _condition(w: WhereClause, ctx: _Ctx) -> Condition | None:
         )
         return None
     if vt in _NAMED and op == "starts_word":
-        ctx.local.append(f"{_describe(w)}: one name search per query (the rest stay local)")
+        if isinstance(value, str) and re.fullmatch(r"[0-9 ]+", value.strip()):
+            ctx.local.append(f"{_describe(w)}: a number isn't sent as a name search")
+        else:
+            ctx.local.append(f"{_describe(w)}: one name search per query (the rest stay local)")
         return None
+    if vt in _NAMED and op in ("eq", "in", "has_any", "has_all"):
+        return _reference(w, meta, vt, ctx)
     if vt in _DROPDOWN:
         return _dropdown(w, meta, vt, ctx)
     if vt in ("dropdown-multi", "filterable-text-multi"):
@@ -423,6 +462,63 @@ def _condition(w: WhereClause, ctx: _Ctx) -> Condition | None:
     return None
 
 
+_NAMES_REASON = "names are matched locally (use the id to filter on Affinity's side)"
+
+
+def _valid_ids(value: list[Any]) -> list[int] | str:
+    """The deduplicated record ids in ``value`` (order kept), or the reason they stay local:
+    any value that isn't id-shaped (a name) first, then any id outside ``1..ID_MAX``."""
+    ids = [_as_entity_id(v) for v in value]
+    if any(i is None for i in ids):
+        return _NAMES_REASON
+    valid = [i for i in ids if i is not None]
+    if any(not 1 <= i <= ID_MAX for i in valid):
+        return "not a valid record id"
+    return list(dict.fromkeys(valid))
+
+
+def _reference_operator(op: str, value: Any, multi: bool) -> str | None:
+    """The server operator for a person or company condition, or ``None`` when none answers it
+    (locally ``in`` / ``has_any`` / ``has_all`` on a single field or with a scalar are False,
+    so pushing them would make the filter complete and return nothing)."""
+    as_list = isinstance(value, list)
+    if multi:
+        if (op in ("in", "has_any") and as_list) or (op == "eq" and not as_list):
+            return "has-any-of"
+        if op in ("has_all", "eq") and as_list:
+            return "has-all-of"
+        return None
+    if (op == "eq" and not as_list) or (op == "in" and as_list):
+        return "is-any-of"
+    return None
+
+
+def _reference(w: WhereClause, meta: FieldMetadata, vt: str, ctx: _Ctx) -> Condition | None:
+    """Record ids on a person or company field: the server matches the id, the local filter
+    (which runs afterwards on every record) matches the id too (a number is an id only)."""
+    op, value = w.op or "", w.value
+    if meta.type == "enriched":
+        # Enriched values were never checked with these mappings, and search reads them
+        # differently from the entries API
+        ctx.local.append(f"{_describe(w)}: Affinity enriched fields stay local")
+        return None
+    server_op = None if value is None else _reference_operator(op, value, vt.endswith("-multi"))
+    if server_op is None:
+        ctx.local.append(f"{_describe(w)}: no server mapping for {vt} {op}")
+        return None
+    if _refused(w, meta, vt, server_op, ctx):
+        return None
+    items = value if isinstance(value, list) else [value]
+    if any(item is None for item in items):
+        ctx.local.append(f"{_describe(w)}: no server mapping for {vt} {op}")
+        return None
+    ids = _valid_ids(items)
+    if isinstance(ids, str):
+        ctx.local.append(f"{_describe(w)}: {ids}")
+        return None
+    return _emit(w, meta, vt, server_op, ids, ctx)
+
+
 def _dropdown(w: WhereClause, meta: FieldMetadata, vt: str, ctx: _Ctx) -> Condition | None:
     """Locally a dropdown value is the option's text, so map the text test onto option ids."""
     op, value = w.op, w.value

{affinity_sdk-2.0.7 → affinity_sdk-2.0.8}/affinity/cli/commands/list_cmds.py

@@ -17,14 +17,15 @@ from affinity.exceptions import (
     AuthorizationError,
     ClientSideFilterWarning,
     NotFoundError,
+    UnsupportedOperationError,
 )
 from affinity.exceptions import ValidationError as SDKValidationError
 from affinity.filters import FilterExpression
 from affinity.filters import parse as parse_filter
 from affinity.models.entities import FieldMetadata, ListCreate, ListEntryWithEntity
-from affinity.models.pagination import FilterStats
+from affinity.models.pagination import FilterStats, PaginatedResponse
 from affinity.models.types import InteractionType, ListType
-from affinity.services.lists import _entry_to_filter_dict
+from affinity.services.lists import ListEntryService, _entry_to_filter_dict
 from affinity.types import (
     AnyFieldId,
     CompanyId,
@@ -1149,6 +1150,33 @@ def list_export(
                 api_called=True,
             )
 
+        # Open Affinity's search here, before any output: a refusal must not surface halfway
+        # through a CSV (its header is already written) or leave a silent first page.
+        search_body: dict[str, Any] | None = list_search.body if list_search else None
+        opened_page: PaginatedResponse[ListEntryWithEntity] | None = None
+        if search_body is not None and filter_expr and not saved_view and cursor is None:
+            try:
+                opened_page = _open_search(
+                    client.lists.entries(list_id),
+                    search_body,
+                    list(dict.fromkeys([*selected_field_ids, *filter_field_ids])),
+                    page_size,
+                )
+            except (
+                AuthorizationError,
+                NotFoundError,
+                SDKValidationError,
+                UnsupportedOperationError,
+            ) as e:
+                if not (all_pages or max_results is not None or first_page_only):
+                    raise _filter_scope_error(
+                        filter_expr, list_search.local if list_search else [], reason=str(e)
+                    ) from e
+                warnings.append(f"Affinity's search refused the filter, filtering locally: {e}")
+                if server_filter is not None:
+                    server_filter["fallback"] = e.message
+                search_body = None
+
         # Build expand field data structures from parsed_expand_fields
         # - expand_field_ids: list of field IDs for API calls
         # - field_id_to_display: dict mapping field ID (str) -> display name (original spec)
@@ -1338,7 +1366,8 @@ def list_export(
                         state=csv_iter_state,
                         cache=cache,
                         filter_progress_callback=filter_callback,
-                        search=list_search.body if list_search else None,
+                        search=search_body,
+                        opened_page=opened_page,
                         filter_field_ids=filter_field_ids,
                     ):
                         next_cursor = page_next_cursor
@@ -1664,7 +1693,6 @@ def list_export(
                 # only reach the JSON envelope, which CSV never builds.
                 for msg in [
                     *warnings,
-                    *csv_iter_state.get("warnings", []),
                     *truncation_warnings(
                         csv_iter_state.get("truncatedFields", []), filtered=bool(filter_expr)
                     ),
@@ -1776,7 +1804,8 @@ def list_export(
                 state=table_iter_state,
                 cache=cache,
                 filter_progress_callback=json_filter_callback,
-                search=list_search.body if list_search else None,
+                search=search_body,
+                opened_page=opened_page,
                 filter_field_ids=filter_field_ids,
             ):
                 next_cursor = page_next_cursor
@@ -1919,9 +1948,6 @@ def list_export(
                 warnings.append("Results limited by --max-results. Use --all to fetch all results.")
             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)
@@ -2115,6 +2141,7 @@ def _iterate_list_entries(
     cache: Any = None,
     filter_progress_callback: Callable[[FilterStats], None] | None = None,
     search: dict[str, Any] | None = None,
+    opened_page: PaginatedResponse[ListEntryWithEntity] | None = None,
     filter_field_ids: list[str] | None = None,
 ) -> Any:
     """
@@ -2196,38 +2223,27 @@ def _iterate_list_entries(
         else None
     )
     if decoded is not None or (search is not None and filter_expr):
-        try:
-            if decoded is not None:
-                assert decoded.body is not None
-                body, local_filter = decoded.body, decoded.filter
-                first = entries.find_body(body, cursor=decoded.url)
-            else:
-                assert search is not None and filter_expr
-                body, local_filter = search, parse_filter(filter_expr)
-                first = entries.find_body(body, field_ids=fetch_ids, limit=page_size)
-        except (AuthorizationError, NotFoundError, SDKValidationError) as e:
-            if decoded is not None:
-                raise
-            if state is not None:
-                state.setdefault("warnings", []).append(
-                    f"Affinity's search refused the filter, filtering locally: {e}"
-                )
-                state["searchFallback"] = getattr(e, "message", None) or str(e)
+        if decoded is not None:
+            assert decoded.body is not None
+            body, local_filter = decoded.body, decoded.filter
+            first = entries.find_body(body, cursor=decoded.url)
         else:
-            yield from _search_rows(
-                entries,
-                first,
-                body=body,
-                local_filter=local_filter,
-                selected_field_ids=selected_field_ids,
-                field_by_id=field_by_id,
-                key_mode=key_mode,
-                max_results=max_results,
-                all_pages=all_pages,
-                state=state,
-                filter_progress_callback=filter_progress_callback,
-            )
-            return
+            assert search is not None and filter_expr and opened_page is not None
+            body, local_filter, first = search, parse_filter(filter_expr), opened_page
+        yield from _search_rows(
+            entries,
+            first,
+            body=body,
+            local_filter=local_filter,
+            selected_field_ids=selected_field_ids,
+            field_by_id=field_by_id,
+            key_mode=key_mode,
+            max_results=max_results,
+            all_pages=all_pages,
+            state=state,
+            filter_progress_callback=filter_progress_callback,
+        )
+        return
 
     pages = (
         entries.pages(cursor=cursor)
@@ -2300,17 +2316,39 @@ def _filter_names_list_fields(filter_expr: str) -> bool:
         return False
 
 
-def _filter_scope_error(filter_expr: str, local: list[str]) -> CLIError:
-    return CLIError(
-        "Part of this --filter runs locally on fetched pages, so without a scope flag the "
-        "export would silently return only first-page matches. Add --all to scan everything, "
-        "--max-results N to cap, or --first-page-only to opt in.",
-        exit_code=2,
-        error_type="usage_error",
-        hint="details.local names the conditions Affinity's search can't apply; --saved-view "
-        "filters large lists on Affinity's side.",
-        details={"rejected_filter": str(filter_expr), "local": local},
+def _open_search(
+    entries: ListEntryService,
+    body: dict[str, Any],
+    field_ids: list[str],
+    page_size: int,
+) -> PaginatedResponse[ListEntryWithEntity]:
+    """First page of Affinity's list entry search (raises when Affinity refuses the filter)."""
+    return entries.find_body(body, field_ids=field_ids, limit=page_size)
+
+
+def _filter_scope_error(filter_expr: str, local: list[str], reason: str | None = None) -> CLIError:
+    scope_flags = (
+        "Add --all to scan everything, --max-results N to cap, or --first-page-only to opt in."
     )
+    if reason is None:
+        message = (
+            "Part of this --filter runs locally on fetched pages, so without a scope flag the "
+            f"export would silently return only first-page matches. {scope_flags}"
+        )
+        hint = (
+            "details.local names the conditions Affinity's search can't apply; --saved-view "
+            "filters large lists on Affinity's side."
+        )
+        details: dict[str, Any] = {"rejected_filter": str(filter_expr), "local": local}
+    else:
+        message = (
+            f"Affinity's search refused this --filter ({reason}), so it would run locally on "
+            "fetched pages, and without a scope flag the export would silently return only "
+            f"first-page matches. {scope_flags}"
+        )
+        hint = "Affinity refused the search; add --all or --max-results to filter locally."
+        details = {"rejected_filter": str(filter_expr), "local": local, "refused": reason}
+    return CLIError(message, exit_code=2, error_type="usage_error", hint=hint, details=details)
 
 
 def _search_rows(

{affinity_sdk-2.0.7 → affinity_sdk-2.0.8}/affinity/cli/entity_search.py

@@ -21,7 +21,7 @@ from affinity.filters import FilterExpression
 from affinity.services._search import SEARCH_INCLUDES
 
 from .query.models import WhereClause
-from .query.pushdown import fields_index, split_where
+from .query.pushdown import ENTITY_VERIFIED, fields_index, split_where
 
 # Record attributes (not fields) a company or person filter can test.
 COMPANY_KEYS = frozenset({"id", "name", "domain", "domains"})
@@ -57,7 +57,7 @@ def plan_entity_search(service: Any, where: WhereClause) -> EntitySearch:
             options[key] = list(service.get_field_dropdown_options(meta.id))
         return options[key]
 
-    split = split_where(where, fields, options_for, enriched="as-is")
+    split = split_where(where, fields, options_for, verified=ENTITY_VERIFIED, enriched="as-is")
     index = fields_index(fields)
     field_ids = sorted(
         {
@@ -94,8 +94,8 @@ def _paths(where: WhereClause) -> set[str]:
 
 def entity_filter_dict(entity: Any) -> dict[str, Any]:
     """What a ``--filter`` on companies or persons sees: field values by name (dropdowns as
-    text, persons and companies as names that also match their id) plus the record's own
-    attributes."""
+    text, persons and companies as names; a number in a filter matches their id) plus the
+    record's own attributes."""
     result: dict[str, Any] = {}
     by_id: dict[str, Any] = {}
     for item in getattr(entity, "fields_raw", None) or []:

{affinity_sdk-2.0.7 → affinity_sdk-2.0.8}/affinity/cli/query/executor.py

@@ -271,7 +271,7 @@ def _normalize_list_entry_fields(
                                     extracted.append(item)
                             normalized_fields[field_name] = extracted
                         # Handle person reference: {"firstName": "Jane", "lastName": "Doe"}
-                        # (names carry the record id: a filter on the id matches too)
+                        # (names carry the record id: a number in a filter matches the id only)
                         elif isinstance(data, dict) and ("firstName" in data or "lastName" in data):
                             normalized_fields[field_name] = entity_name(
                                 _extract_person_display_name(data), data.get("id")
@@ -1887,7 +1887,7 @@ class QueryExecutor:
         would mean reading Affinity's whole directory."""
         from affinity.services._search import SEARCH_INCLUDES
 
-        from .pushdown import fields_index, split_where
+        from .pushdown import ENTITY_VERIFIED, fields_index, split_where
 
         where = ctx.query.where
         if entity not in ("companies", "persons"):
@@ -1915,7 +1915,13 @@ class QueryExecutor:
                 if meta is not None:
                     field_ids.add(str(meta.id))
         self._search_field_ids = sorted(field_ids)
-        split = split_where(where, fields, lambda m: options.get(str(m.id), []), enriched="as-is")
+        split = split_where(
+            where,
+            fields,
+            lambda m: options.get(str(m.id), []),
+            verified=ENTITY_VERIFIED,
+            enriched="as-is",
+        )
         if split.errors:
             raise QueryValidationError("; ".join(split.errors), field="where")
         if names and not split.server_side:

affinity_sdk-2.0.8/affinity/cli/query/pushdown.py

@@ -0,0 +1,25 @@
+"""Server-side filter split (moved to :mod:`affinity._filtering.pushdown`; re-exported)."""
+
+from ..._filtering.pushdown import (
+    ALL_MAPPINGS,
+    ENRICHED,
+    ENTITY_VERIFIED,
+    ID_MAX,
+    REFERENCE_MAPPINGS,
+    VERIFIED,
+    Pushdown,
+    fields_index,
+    split_where,
+)
+
+__all__ = [
+    "ALL_MAPPINGS",
+    "ENRICHED",
+    "ENTITY_VERIFIED",
+    "ID_MAX",
+    "REFERENCE_MAPPINGS",
+    "VERIFIED",
+    "Pushdown",
+    "fields_index",
+    "split_where",
+]

{affinity_sdk-2.0.7 → affinity_sdk-2.0.8}/affinity/compare.py

@@ -18,7 +18,8 @@ from ._filtering.dates import as_utc, parse_date_value, parse_iso_datetime
 
 class EntityName(str):
     """A person's or company's name (or another record reference's) that also carries the
-    record's id, so a filter can match either: ``Owner = "Jane Doe"`` or ``Owner = 123``.
+    record's id: ``Owner = "Jane Doe"`` matches the name, ``Owner = 123`` the id (a number is
+    the id only; it never matches a name made of digits).
 
     It is a ``str`` everywhere else (output, sorting, text operators)."""
 
@@ -49,7 +50,8 @@ def entity_name(value: Any, entity_id: Any) -> Any:
 
 
 def _as_entity_id(value: Any) -> int | None:
-    """A filter value read as a record id: an int, or a string of ASCII digits."""
+    """A filter value read as a record id: an int, or a string of 1-20 ASCII digits (surrounding
+    spaces ignored)."""
     if isinstance(value, bool):
         return None
     if isinstance(value, int):
@@ -68,7 +70,7 @@ def normalize_value(value: Any) -> Any:
     - Dropdowns become their text: {"text": "Active"} -> "Active"
     - Persons become their name: {"firstName": "Jane", "lastName": "Doe"} -> "Jane Doe"
     - Companies become their name: {"name": "Acme", "domain": ...} -> "Acme"
-      (as :class:`EntityName`, carrying the record id, so a number matches the id)
+      (as :class:`EntityName`, carrying the record id, so a number matches the id only)
     - Multi-value arrays become lists of those: [{"text": "A"}, {"text": "B"}] -> ["A", "B"]
     - Scalars pass through unchanged
 
@@ -226,19 +228,23 @@ def _eq(a: Any, b: Any) -> bool:
 
 def _scalar_eq(a: Any, b: Any) -> bool:
     """Scalar equality as ``eq`` uses it, and ``in`` / ``has_any`` / ``has_all`` per element:
-    direct, then an :class:`EntityName` against its id, then ``"true"``/``"false"`` against a
-    bool, then by string (``5`` matches ``"5"``). ``a`` is the field value."""
+    an :class:`EntityName` against an id-shaped value is an id comparison only; otherwise
+    direct, then ``"true"``/``"false"`` against a bool, then by string (``5`` matches ``"5"``).
+    ``a`` is the field value."""
     if a is None or b is None:
         return a is b
 
+    # A record reference (person, company, list...) against a number or digit string is its
+    # id, never a name made of digits (Owner = 123 does not match a person named "123")
+    if isinstance(a, EntityName) and a.entity_id is not None:
+        record_id = _as_entity_id(b)
+        if record_id is not None:
+            return record_id == a.entity_id
+
     # Try direct comparison first
     if a == b:
         return True
 
-    # A person or company also matches its id (Owner = 123)
-    if isinstance(a, EntityName) and a.entity_id is not None and _as_entity_id(b) == a.entity_id:
-        return True
-
     # Handle boolean coercion: filter string "true"/"false" should match Python bool
     # Filter parser outputs lowercase "true"/"false", Python str(True) is "True"
     if isinstance(a, bool) and isinstance(b, str):

{affinity_sdk-2.0.7 → affinity_sdk-2.0.8}/docs/public/cli/commands.md

@@ -278,7 +278,7 @@ Options:
 - `--csv`: output as CSV (to stdout)
 - `--csv-bom`: add UTF-8 BOM for Excel compatibility
 
-**Note:** `--filter` goes through Affinity's search: the conditions on person fields that Affinity can answer are applied on its side, and the whole filter (including attributes like `firstName` or `primaryEmail`) then runs on what comes back. A filter with only attribute conditions is refused; search names and emails with `--query`. When part of the filter runs locally, `--all` or `--max-results` is required. Filters on enriched fields warn that a few records may be missed. The next-page cursor of a filtered run starts with `xsearch2:` and `--cursor` alone resumes it. `--query` and `--filter` can't be combined. With `--json`, `meta.serverFilter` lists the conditions Affinity applied (`pushed`) and those checked locally (`local`); a `--cursor` resume doesn't report it.
+**Note:** `--filter` goes through Affinity's search: the conditions on person fields that Affinity can answer are applied on its side, and the whole filter (including attributes like `firstName` or `primaryEmail`) then runs on what comes back. A filter with only attribute conditions is refused; search names and emails with `--query`. When part of the filter runs locally, `--all` or `--max-results` is required. Filters on enriched fields warn that a few records may be missed. Id conditions on person and company fields (`Mentor = 9`) are checked locally here, and a `starts_word` made only of digits needs another field condition (or use `--query`). The next-page cursor of a filtered run starts with `xsearch2:` and `--cursor` alone resumes it. `--query` and `--filter` can't be combined. With `--json`, `meta.serverFilter` lists the conditions Affinity applied (`pushed`) and those checked locally (`local`); a `--cursor` resume doesn't report it.
 
 **Note:** `--query` can be combined with `--field` and `--field-type` to search with field data.
 
@@ -461,7 +461,7 @@ Options:
 - `--csv`: output as CSV (to stdout)
 - `--csv-bom`: add UTF-8 BOM for Excel compatibility
 
-**Note:** `--filter` goes through Affinity's search: the conditions on company fields that Affinity can answer are applied on its side, and the whole filter (including attributes like `name` or `domain`) then runs on what comes back. A filter with only attribute conditions (e.g. `name =~ "Acme"`) is refused, since it would mean reading Affinity's whole company directory; search names and domains with `--query`. When part of the filter runs locally, `--all` or `--max-results` is required. Filters on enriched fields warn that a few records may be missed. The next-page cursor of a filtered run starts with `xsearch2:` and `--cursor` alone resumes it. `--query` and `--filter` can't be combined. With `--json`, `meta.serverFilter` lists the conditions Affinity applied (`pushed`) and those checked locally (`local`); a `--cursor` resume doesn't report it.
+**Note:** `--filter` goes through Affinity's search: the conditions on company fields that Affinity can answer are applied on its side, and the whole filter (including attributes like `name` or `domain`) then runs on what comes back. A filter with only attribute conditions (e.g. `name =~ "Acme"`) is refused, since it would mean reading Affinity's whole company directory; search names and domains with `--query`. When part of the filter runs locally, `--all` or `--max-results` is required. Filters on enriched fields warn that a few records may be missed. Id conditions on person and company fields (`Mentor = 9`) are checked locally here, and a `starts_word` made only of digits needs another field condition (or use `--query`). The next-page cursor of a filtered run starts with `xsearch2:` and `--cursor` alone resumes it. `--query` and `--filter` can't be combined. With `--json`, `meta.serverFilter` lists the conditions Affinity applied (`pushed`) and those checked locally (`local`); a `--cursor` resume doesn't report it.
 
 **Note:** `--query` can be combined with `--field` and `--field-type` to search with field data.
 
@@ -849,7 +849,7 @@ Options:
 - `--unreplied-types <types>`: Comma-separated types to check: email, chat, all (default: email,chat)
 - `--unreplied-lookback-days <days>`: Lookback period for unreplied message detection (default: 30)
 
-**`--filter` and Affinity's search.** Conditions on list fields that Affinity's search can answer are applied on its side, so only matching entries are downloaded; the whole filter still runs locally on what comes back. When Affinity applies the whole filter, `--all`, `--max-results` and `--first-page-only` are not required (page one is the first page of matches). When part of the filter runs locally, one of them is required, otherwise the command exits with code 2 and the error's `details.local` names the conditions that stay local. The next-page cursor of a filtered export starts with `xsearch2:` and carries the search, so `--cursor` alone resumes it. If Affinity refuses the search (e.g. the API key lacks the "Export data from Lists" permission), the export reads the whole list and filters locally, with a warning. With `--json`, `meta.serverFilter` reports the split (in `--dry-run`, `data.serverFilter`): `pushed` (conditions Affinity's search applied), `local` (what runs only on your machine, with reasons) and, when the search was refused or turned off, `fallback` (why; the whole filter then ran locally). A `--cursor` resume doesn't report it. CSV and table output report the split as warnings on stderr. `XAFFINITY_QUERY_SERVER_FILTER=0` turns server filtering off for list entries (`query` on listEntries and `list export`); company and person filters always use it. `--saved-view` also filters on Affinity's side; for one known company or person use `--company-id` / `--person-id`. See [Filtering](../guides/filtering.md#filtering-on-affinitys-side) for which conditions Affinity applies.
+**`--filter` and Affinity's search.** Conditions on list fields that Affinity's search can answer are applied on its side, so only matching entries are downloaded; the whole filter still runs locally on what comes back. When Affinity applies the whole filter, `--all`, `--max-results` and `--first-page-only` are not required (page one is the first page of matches). When part of the filter runs locally, one of them is required, otherwise the command exits with code 2 and the error's `details.local` names the conditions that stay local. The next-page cursor of a filtered export starts with `xsearch2:` and carries the search, so `--cursor` alone resumes it. If Affinity refuses the search (e.g. the API key lacks the "Export data from Lists" permission), the export reads the whole list and filters locally, with a warning, when `--all`, `--max-results` or `--first-page-only` is given; without one the command exits with code 2 before any output (`details.refused` carries the refusal). Id conditions on person and company fields (`Owner = 12345`, ids up to 2147483647) are applied on Affinity's side; names, `!=` and enriched fields of those types run locally, and a `starts_word` made only of digits runs locally too, so it needs a scope flag. With `--json`, `meta.serverFilter` reports the split (in `--dry-run`, `data.serverFilter`): `pushed` (conditions Affinity's search applied), `local` (what runs only on your machine, with reasons) and, when the search was refused or turned off, `fallback` (why; the whole filter then ran locally). A `--cursor` resume doesn't report it. CSV and table output report the split as warnings on stderr. `XAFFINITY_QUERY_SERVER_FILTER=0` turns server filtering off for list entries (`query` on listEntries and `list export`); company and person filters always use it. `--saved-view` also filters on Affinity's side; for one known company or person use `--company-id` / `--person-id`. See [Filtering](../guides/filtering.md#filtering-on-affinitys-side) for which conditions Affinity applies.
 
 **Truncation envelope.** JSON output includes a `meta` object with `truncated` (boolean) and, when `truncated=true`, a `truncationReason` string naming the cause (`firstPageOnly` here; `field history-bulk` uses `partialFailure`). Always check this before treating a response as complete.