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

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

@@ -5,6 +5,69 @@ 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
+returns. Each is marked **Behavior change**.
+
+### Highlights
+
+A repeated `--filter` now combines its conditions instead of keeping only the last one, and a
+person or company field filtered by id (`Owner = 26229794`) matches that person instead of
+nothing.
+
+### Changed
+
+- **Behavior change (correctness fix). CLI: repeated `--filter` values are ANDed** on
+  `list export`, `company ls` and `person ls`, and so are repeated `list export --expand-filter`
+  values. Only the last one used to apply, and the others were dropped without a warning, so such
+  runs returned rows that didn't match the earlier conditions: re-run them. `--filter A --filter B`
+  is `(A) & (B)`; for OR, use `|` inside one value. Each repeated value must be a complete
+  expression on its own. (The MCP server refused a repeated `--filter`, so MCP calls weren't
+  affected.)
+- **Behavior change (correctness fix). CLI and SDK: a person or company field compared with a
+  number matches the record's id.** `Owner = 26229794` (and `in`, `has_any`, `has_all`) in
+  `--filter`, `query` and `affinity.filters` compared the name with "26229794" and matched nothing,
+  without a warning (`!=` matched every row). It now matches that person's id, and names still
+  match as before. Other record references, such as lists, match their id too. Re-run filters that
+  used ids. A reference with no name (a person without a first and last name, a company with an
+  empty name) still can't be matched by id.
+
 ## [2.0.6] - 2026-10-14
 
 ### Fixed

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

@@ -1,6 +1,6 @@
 Metadata-Version: 2.5
 Name: affinity-sdk
-Version: 2.0.6
+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.6 → 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.6 → affinity_sdk-2.0.8}/affinity/cli/commands/company_cmds.py

@@ -29,7 +29,12 @@ from ..entity_search import COMPANY_KEYS, filtered_ls
 from ..errors import CLIError
 from ..list_search import is_filter_cursor
 from ..mcp_limits import apply_mcp_limits
-from ..options import csv_output_options, csv_suboption_callback, output_options
+from ..options import (
+    csv_output_options,
+    csv_suboption_callback,
+    join_filters_callback,
+    output_options,
+)
 from ..progress import ProgressManager, ProgressSettings
 from ..resolve import get_company_fields, resolve_list_selector
 from ..resolvers import ResolvedEntity
@@ -330,9 +335,11 @@ def _parse_field_types(values: tuple[str, ...]) -> list[FieldType] | None:
     "--filter",
     "filter_expr",
     type=str,
-    default=None,
+    multiple=True,
+    callback=join_filters_callback,
     help="Filter on company fields, applied by Affinity's search: 'field op value'. Ops: = != "
-    "=~ =^ =$ > < >= <= starts_word. E.g., 'Stage = \"Seed\"'. Name search: --query.",
+    "=~ =^ =$ > < >= <= starts_word. E.g., 'Stage = \"Seed\"'. Name search: --query. "
+    "Repeatable: repeated values are ANDed.",
 )
 @click.option(
     "--query",

{affinity_sdk-2.0.6 → 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,
@@ -44,7 +45,12 @@ from ..decorators import category, destructive
 from ..errors import CLIError
 from ..list_search import ListSearch, decode_cursor, encode_cursor, plan_list_search
 from ..mcp_limits import apply_mcp_limits
-from ..options import csv_output_options, csv_suboption_callback, output_options
+from ..options import (
+    csv_output_options,
+    csv_suboption_callback,
+    join_filters_callback,
+    output_options,
+)
 from ..render import format_duration
 from ..resolve import (
     list_all_saved_views,
@@ -452,9 +458,10 @@ ExpandOnError = Literal["raise", "skip"]
     "--filter",
     "filter_expr",
     type=str,
-    default=None,
+    multiple=True,
+    callback=join_filters_callback,
     help="Filter (field op value): Affinity's search applies what it can, the rest is checked "
-    'locally. Quote multi-word: Status="Intro Meeting".',
+    'locally. Quote multi-word: Status="Intro Meeting". Repeatable: repeated values are ANDed.',
 )
 @click.option(
     "--page-size",
@@ -570,8 +577,10 @@ ExpandOnError = Literal["raise", "skip"]
     "--expand-filter",
     "expand_filter",
     type=str,
-    default=None,
-    help="Filter expanded entities (e.g., 'field=value' or 'field!=value').",
+    multiple=True,
+    callback=join_filters_callback,
+    help="Filter expanded entities (e.g., 'field=value' or 'field!=value'). "
+    "Repeatable: repeated values are ANDed.",
 )
 @click.option(
     "--expand-opportunities-list",
@@ -1141,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)
@@ -1330,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
@@ -1656,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)
                     ),
@@ -1768,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
@@ -1911,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)
@@ -2107,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:
     """
@@ -2188,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)
@@ -2292,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.6 → affinity_sdk-2.0.8}/affinity/cli/commands/person_cmds.py

@@ -27,7 +27,12 @@ from ..entity_search import PERSON_KEYS, filtered_ls
 from ..errors import CLIError
 from ..list_search import is_filter_cursor
 from ..mcp_limits import apply_mcp_limits
-from ..options import csv_output_options, csv_suboption_callback, output_options
+from ..options import (
+    csv_output_options,
+    csv_suboption_callback,
+    join_filters_callback,
+    output_options,
+)
 from ..progress import ProgressManager, ProgressSettings
 from ..resolve import get_person_fields, resolve_list_selector
 from ..resolvers import ResolvedEntity
@@ -207,9 +212,11 @@ def _parse_field_types(values: tuple[str, ...]) -> list[FieldType] | None:
     "--filter",
     "filter_expr",
     type=str,
-    default=None,
+    multiple=True,
+    callback=join_filters_callback,
     help="Filter on person fields, applied by Affinity's search: 'field op value'. Ops: = != "
-    "=~ =^ =$ > < >= <= starts_word. E.g., 'Deals > 5'. Name/email search: --query.",
+    "=~ =^ =$ > < >= <= starts_word. E.g., 'Deals > 5'. Name/email search: --query. "
+    "Repeatable: repeated values are ANDed.",
 )
 @click.option(
     "--query",

{affinity_sdk-2.0.6 → 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,7 +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) 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.6 → affinity_sdk-2.0.8}/affinity/cli/options.py

@@ -4,6 +4,8 @@ import functools
 from collections.abc import Callable
 from typing import Any, TypeVar, cast
 
+from affinity.filters import parse
+
 from .click_compat import click
 from .context import CLIContext, OutputFormat
 from .errors import CLIError
@@ -143,6 +145,28 @@ def _emit_validation_error(ctx: CLIContext, err: CLIError) -> None:
             sys.stderr.write(f"Hint: {err.hint}\n")
 
 
+def join_filters_callback(
+    _ctx: click.Context, _param: click.Parameter, value: tuple[str, ...]
+) -> str | None:
+    """Callback for a repeatable filter option (--filter, --expand-filter): AND the values.
+
+    One value is passed on unchanged. Repeated values are each parsed on their own first, so a
+    value can't close the parentheses it is wrapped in, and its error names it.
+    """
+    if not value:
+        return None
+    if len(value) == 1:
+        return value[0]
+    for i, text in enumerate(value, 1):
+        if not text.strip():
+            raise click.BadParameter(f"value {i} is empty; each repeated value needs an expression")
+        try:
+            parse(text)
+        except ValueError as e:
+            raise click.BadParameter(f"value {i} ({text!r}): {e}") from e
+    return " & ".join(f"({text})" for text in value)
+
+
 def csv_suboption_callback(ctx: click.Context, param: click.Parameter, value: Any) -> Any:
     """Callback for CSV-related sub-options (--csv-bom, --csv-header, --csv-mode).