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

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

@@ -5,6 +5,42 @@ 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.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
+
+- `FieldResolver.get`, `get_many` and `get_by_id` accept a plain `ListEntry` (as returned by
+  `companies.get_list_entries()` and `persons.get_list_entries()`) in their type hints. They
+  already worked on it at runtime; strict type checkers no longer need a cast.
+
 ## [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
@@ -20,12 +56,14 @@ what the CLI prints. Each is marked **Behavior change**.
   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
+- **Behavior change (correctness fix). 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.
+  to leave its ids in the result with empty lists, which looked like "no reminders" / "no files";
+  one failed reminders request (50 ids) silently hid them all. A failure on a later page left a
+  partial list that looked complete. They are now absent from the result, as with every other
+  `on_error="skip"` method: a requested id with no key failed. **If you stored or cached results
+  of these calls made with `on_error="skip"` before 2.0.5, some empty or partial lists may be
+  failures: re-fetch them.**
 - 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

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

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

@@ -44,7 +44,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 +457,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 +576,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",

{affinity_sdk-2.0.5 → affinity_sdk-2.0.7}/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.5 → affinity_sdk-2.0.7}/affinity/cli/entity_search.py

@@ -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 that also match 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.5 → affinity_sdk-2.0.7}/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).
 

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

@@ -16,6 +16,7 @@ from collections.abc import AsyncIterator, Awaitable, Callable, Mapping
 from dataclasses import dataclass, field
 from typing import TYPE_CHECKING, Any, Protocol, TypeVar
 
+from ...compare import entity_name
 from ...exceptions import (
     AuthorizationError,
     MergedEntityError,
@@ -262,19 +263,24 @@ def _normalize_list_entry_fields(
                                     # Person reference in multi-select
                                     name = _extract_person_display_name(item)
                                     if name:
-                                        extracted.append(name)
+                                        extracted.append(entity_name(name, item.get("id")))
                                 elif isinstance(item, dict) and "name" in item:
                                     # Company reference in multi-select
-                                    extracted.append(item["name"])
+                                    extracted.append(entity_name(item["name"], item.get("id")))
                                 else:
                                     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)
                         elif isinstance(data, dict) and ("firstName" in data or "lastName" in data):
-                            normalized_fields[field_name] = _extract_person_display_name(data)
+                            normalized_fields[field_name] = entity_name(
+                                _extract_person_display_name(data), data.get("id")
+                            )
                         # Handle company reference: {"name": "Acme", "domain": "acme.com"}
                         elif isinstance(data, dict) and "name" in data:
-                            normalized_fields[field_name] = data["name"]
+                            normalized_fields[field_name] = entity_name(
+                                data["name"], data.get("id")
+                            )
                         else:
                             normalized_fields[field_name] = data
                     else:

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

@@ -16,6 +16,51 @@ from typing import Any
 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``.
+
+    It is a ``str`` everywhere else (output, sorting, text operators)."""
+
+    __slots__ = ("entity_id",)
+    entity_id: int | None
+
+    def __new__(cls, value: str, entity_id: int | None = None) -> EntityName:
+        self = super().__new__(cls, value)
+        self.entity_id = entity_id
+        return self
+
+    def __reduce__(self) -> tuple[Any, ...]:
+        # Keeps the id through copy, deepcopy and every pickle protocol
+        return (type(self), (str(self), self.entity_id))
+
+
+def entity_name(value: Any, entity_id: Any) -> Any:
+    """``value`` as an :class:`EntityName` when it is a non-empty name and ``entity_id`` an
+    integer id; anything else (no name, no id) is returned unchanged."""
+    if (
+        isinstance(value, str)
+        and value
+        and isinstance(entity_id, int)
+        and not isinstance(entity_id, bool)
+    ):
+        return EntityName(value, entity_id)
+    return value
+
+
+def _as_entity_id(value: Any) -> int | None:
+    """A filter value read as a record id: an int, or a string of ASCII digits."""
+    if isinstance(value, bool):
+        return None
+    if isinstance(value, int):
+        return value
+    if isinstance(value, str):
+        text = value.strip()
+        if text and text.isascii() and text.isdigit() and len(text) <= 20:
+            return int(text)
+    return None
+
+
 def normalize_value(value: Any) -> Any:
     """Normalize a value for comparison.
 
@@ -23,6 +68,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)
     - Multi-value arrays become lists of those: [{"text": "A"}, {"text": "B"}] -> ["A", "B"]
     - Scalars pass through unchanged
 
@@ -46,9 +92,9 @@ def _normalize_item(item: dict[str, Any]) -> Any:
         parts = [
             p.strip() for p in (item.get("firstName"), item.get("lastName")) if isinstance(p, str)
         ]
-        return " ".join(p for p in parts if p) or None
+        return entity_name(" ".join(p for p in parts if p) or None, item.get("id"))
     if "name" in item:
-        return item["name"]
+        return entity_name(item["name"], item.get("id"))
     return item
 
 
@@ -163,6 +209,8 @@ def _eq(a: Any, b: Any) -> bool:
     if isinstance(a, list):
         # If comparing list to list, check set equality (order-insensitive)
         if isinstance(b, list):
+            if any(isinstance(x, EntityName) for x in a):
+                return _same_members(a, b)
             try:
                 return set(a) == set(b)
             except TypeError:
@@ -178,7 +226,8 @@ 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 ``"true"``/``"false"`` against a bool, then by string (``5`` matches ``"5"``)."""
+    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."""
     if a is None or b is None:
         return a is b
 
@@ -186,6 +235,10 @@ def _scalar_eq(a: Any, b: Any) -> bool:
     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):
@@ -198,6 +251,14 @@ def _scalar_eq(a: Any, b: Any) -> bool:
     return str(a) == str(b)
 
 
+def _same_members(a: list[Any], b: list[Any]) -> bool:
+    """Set equality through :func:`_scalar_eq` (field elements first), for lists of record
+    references: every target matches some element and every element matches some target."""
+    return all(any(_scalar_eq(x, y) for x in a) for y in b) and all(
+        any(_scalar_eq(x, y) for y in b) for x in a
+    )
+
+
 def _neq(a: Any, b: Any) -> bool:
     """Not equal operator with array membership support."""
     if a is None:
@@ -205,6 +266,8 @@ def _neq(a: Any, b: Any) -> bool:
 
     if isinstance(a, list):
         if isinstance(b, list):
+            if any(isinstance(x, EntityName) for x in a):
+                return not _same_members(a, b)
             try:
                 return set(a) != set(b)
             except TypeError:

{affinity_sdk-2.0.5 → affinity_sdk-2.0.7}/affinity/field_resolver.py

@@ -12,6 +12,7 @@ from .field_resolve_utils import (
     resolve_location,
     resolve_person,
 )
+from .models.entities import FieldValues
 from .models.types import FieldValueType, ResolveMode
 
 __all__ = ["AmbiguousFieldError", "FieldResolver"]
@@ -20,6 +21,7 @@ if TYPE_CHECKING:
     from .models.entities import (
         Company,
         FieldMetadata,
+        ListEntry,
         ListEntryWithEntity,
         Opportunity,
         Person,
@@ -27,6 +29,25 @@ if TYPE_CHECKING:
     from .models.types import AnyFieldId
 
 
+def _field_values(
+    entity: Company | Person | Opportunity | ListEntry | ListEntryWithEntity,
+) -> FieldValues:
+    """
+    The field values to read: the entity's own, or, for a list entry fetched without its
+    list fields, those of the embedded entity when they were requested. A ``ListEntry``
+    from ``get_list_entries()`` has no embedded entity (``entity`` is None), so it reads
+    its own fields.
+    """
+    inner_fields = getattr(getattr(entity, "entity", None), "fields", None)
+    if (
+        not entity.fields.requested
+        and isinstance(inner_fields, FieldValues)
+        and inner_fields.requested
+    ):
+        return inner_fields
+    return entity.fields
+
+
 class AmbiguousFieldError(Exception):
     """Raised when find_field() matches multiple fields and disambiguation is needed."""
 
@@ -97,7 +118,7 @@ class FieldResolver:
 
     def get(
         self,
-        entity: Company | Person | Opportunity | ListEntryWithEntity,
+        entity: Company | Person | Opportunity | ListEntry | ListEntryWithEntity,
         field_name: str,
         *,
         resolve: ResolveMode = ResolveMode.RAW,
@@ -123,17 +144,8 @@ class FieldResolver:
             >>> stage = resolver.get(opportunity, "Stage", resolve=ResolveMode.TEXT)
             >>> print(stage)  # "Negotiation" instead of 12345
         """
-        # Delegate to inner entity for ListEntryWithEntity
-        if (
-            hasattr(entity, "entity")
-            and entity.entity is not None
-            and hasattr(entity.entity, "fields")
-            and not entity.fields.requested
-            and entity.entity.fields.requested
-        ):
-            entity = entity.entity
-
-        if not entity.fields.requested:
+        fields = _field_values(entity)
+        if not fields.requested:
             warnings.warn(
                 "Fields were not requested for this entity. "
                 "Pass field_ids or field_types when fetching to populate field values.",
@@ -146,7 +158,7 @@ class FieldResolver:
         if field is None:
             return None
 
-        value = entity.fields.get_value(str(field.id))
+        value = fields.get_value(str(field.id))
 
         if resolve == ResolveMode.TEXT and value is not None:
             value = self._resolve_value(value, field.value_type)
@@ -155,7 +167,7 @@ class FieldResolver:
 
     def get_many(
         self,
-        entity: Company | Person | Opportunity | ListEntryWithEntity,
+        entity: Company | Person | Opportunity | ListEntry | ListEntryWithEntity,
         field_names: Sequence[str],
         *,
         resolve: ResolveMode = ResolveMode.RAW,
@@ -284,7 +296,7 @@ class FieldResolver:
 
     def get_by_id(
         self,
-        entity: Company | Person | Opportunity | ListEntryWithEntity,
+        entity: Company | Person | Opportunity | ListEntry | ListEntryWithEntity,
         field_id: str | AnyFieldId,
         *,
         resolve: ResolveMode = ResolveMode.RAW,
@@ -300,18 +312,8 @@ class FieldResolver:
         Returns:
             The extracted field value, or None if not found.
         """
-        # Delegate to inner entity for ListEntryWithEntity
-        if (
-            hasattr(entity, "entity")
-            and entity.entity is not None
-            and hasattr(entity.entity, "fields")
-            and not entity.fields.requested
-            and entity.entity.fields.requested
-        ):
-            entity = entity.entity
-
         field_id_str = str(field_id)
-        value = entity.fields.get_value(field_id_str)
+        value = _field_values(entity).get_value(field_id_str)
         if resolve == ResolveMode.TEXT and value is not None:
             field = self._by_id.get(field_id_str)
             value_type = field.value_type if field else None

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

@@ -273,7 +273,7 @@ Options:
 - `--query <term>` / `-q <term>`: free-text search (name or email)
 - `--field <id-or-name>` (repeatable): field ID or name to include
 - `--field-type <type>` (repeatable): field type to include (global, enriched, relationship-intelligence)
-- `--filter <expression>`: filter expression; must include a condition on a person field (Affinity's search applies it)
+- `--filter <expression>` (repeatable, values ANDed): filter expression; must include a condition on a person field (Affinity's search applies it)
 - `--page-size`, `--cursor`, `--max-results`, `--all`: pagination options
 - `--csv`: output as CSV (to stdout)
 - `--csv-bom`: add UTF-8 BOM for Excel compatibility
@@ -456,7 +456,7 @@ Options:
 - `--query <term>` / `-q <term>`: free-text search (name or domain)
 - `--field <id-or-name>` (repeatable): field ID or name to include
 - `--field-type <type>` (repeatable): field type to include (global, enriched, relationship-intelligence)
-- `--filter <expression>`: filter expression; must include a condition on a company field (Affinity's search applies it)
+- `--filter <expression>` (repeatable, values ANDed): filter expression; must include a condition on a company field (Affinity's search applies it)
 - `--page-size`, `--cursor`, `--max-results`, `--all`: pagination options
 - `--csv`: output as CSV (to stdout)
 - `--csv-bom`: add UTF-8 BOM for Excel compatibility
@@ -838,7 +838,7 @@ Options:
 - `--csv-bom`: add UTF-8 BOM for Excel compatibility
 - `--field <id-or-name>` (repeatable): include specific fields
 - `--saved-view <name>`: use a saved view's field selection (server-side filtering)
-- `--filter <expression>`: filter expression; Affinity's search applies what it can, the rest runs locally (see below)
+- `--filter <expression>` (repeatable, values ANDed): filter expression; Affinity's search applies what it can, the rest runs locally (see below)
 - `--company-id <id>` (repeatable): entity-scoped export — return only rows where the entry is for this company
 - `--person-id <id>` (repeatable): entity-scoped export — return only rows where the entry is for this person
 - `--first-page-only`: fetch a single page of results; output includes `meta.truncated=true` and `meta.truncationReason="firstPageOnly"` when there are more pages

{affinity_sdk-2.0.5 → affinity_sdk-2.0.7}/docs/public/guides/filtering.md

@@ -120,6 +120,10 @@ multi_region = entries.list(
 For CLI or advanced SDK use, you can use raw filter strings: the `--filter` text of
 `list export`, `company ls` and `person ls`, and `affinity.filters.parse()` in the SDK.
 
+`--filter` (and `--expand-filter`) can be repeated: the values are ANDed, so
+`--filter 'Status = "Active"' --filter 'Region = "US"'` is `(Status = "Active") & (Region = "US")`.
+Each value must be a complete expression; for OR, use `|` inside one value.
+
 ### Standard Operators
 
 These operators work in every `--filter` and in `affinity.filters`:
@@ -184,7 +188,8 @@ Human/LLM-friendly aliases for official operators:
 - **`starts_word`**: a word in the value starts with the text, case-insensitive, the way
   Affinity's search matches names. `"Jan"` matches "Jane Doe" and "Mary-Jane"; `"ane"`
   doesn't. JSON spelling in `query`: `{"path": "fields.Owner", "op": "starts_word", "value": "Jan"}`.
-- **Person and company fields** are compared by name ("Jane Doe", "Acme"). In `--filter`
+- **Person and company fields** are compared by name ("Jane Doe", "Acme"), or by id when the value is a number
+  (`Owner = 26229794`: that person's id; a value with no name can't match by id). In `--filter`
   and `query`, `contains` (and `contains_any` / `contains_all`) on a person or company
   field is refused: use `starts_word`.
 - **Empty multi-value fields**: a multi-value field with no items counts as empty.
@@ -228,6 +233,9 @@ xaffinity list export Pipeline --filter 'Region = "US" | Region = "Canada"'
 # A person field by name
 xaffinity list export Pipeline --filter 'Owner starts_word "Jan"'
 
+# A person field by id
+xaffinity list export Pipeline --filter 'Owner = 26229794' --all
+
 # Null check
 xaffinity list export Pipeline --filter 'Owner != *'
 

{affinity_sdk-2.0.5 → affinity_sdk-2.0.7}/docs/public/guides/query-command.md

@@ -185,7 +185,7 @@ Example: {"from": "persons", "include": ["interactions"]}
 | `has_any` | Array contains any of the values | `["LB", "MA"]` |
 | `has_all` | Array contains all of the values | `["LB", "MA"]` |
 
-`starts_word` matches the way Affinity's search matches names: `"Jan"` matches "Jane Doe" and "Mary-Jane"; `"ane"` doesn't. Person and company field values are compared by name ("Jane Doe", "Acme"), and `contains` / `contains_any` / `contains_all` on a person or company field is refused: use `starts_word`. An empty multi-value field (no items) counts as empty: `is_null` matches it, `is_not_null` doesn't.
+`starts_word` matches the way Affinity's search matches names: `"Jan"` matches "Jane Doe" and "Mary-Jane"; `"ane"` doesn't. Person and company field values are compared by name ("Jane Doe", "Acme"), or by id when the value is a number (`{"path": "fields.Owner", "op": "eq", "value": 26229794}`), and `contains` / `contains_any` / `contains_all` on a person or company field is refused: use `starts_word`. An empty multi-value field (no items) counts as empty: `is_null` matches it, `is_not_null` doesn't.
 
 The `--filter` text of `list export`, `company ls` and `person ls` is the same filter language: every condition means the same in both spellings.
 

{affinity_sdk-2.0.5 → affinity_sdk-2.0.7}/docs/public/reference/query-language.md

@@ -146,7 +146,7 @@ Example: {"from": "persons", "include": ["interactions"]}
 | `starts_with` | Starts with prefix (case-insensitive) | string |
 | `starts_word` | A word in the value starts with the text (case-insensitive) | string |
 
-`starts_word` matches the way Affinity's search matches names: `"Jan"` matches "Jane Doe" and "Mary-Jane"; `"ane"` doesn't. Person and company field values are compared by name ("Jane Doe", "Acme"); `contains`, `contains_any` and `contains_all` on a person or company field are refused (use `starts_word`).
+`starts_word` matches the way Affinity's search matches names: `"Jan"` matches "Jane Doe" and "Mary-Jane"; `"ane"` doesn't. Person and company field values are compared by name ("Jane Doe", "Acme"), or by id when the value is a number (`{"path": "fields.Owner", "op": "eq", "value": 26229794}`); `contains`, `contains_any` and `contains_all` on a person or company field are refused (use `starts_word`).
 
 #### Collection
 

{affinity_sdk-2.0.5 → affinity_sdk-2.0.7}/mcp/.claude-plugin/plugin.json

@@ -1,7 +1,7 @@
 {
   "name": "affinity-crm-mcp-unofficial",
   "description": "Affinity CRM workflows for Claude \u2014 meeting prep, pipeline review, warm intros, interaction logging, and relationship intelligence",
-  "version": "2.0.6",
+  "version": "2.0.8",
   "author": {
     "name": "Yaniv Golan",
     "email": "yaniv@golan.name"

{affinity_sdk-2.0.5 → affinity_sdk-2.0.7}/mcp/.claude-plugin/skills/query-language/SKILL.md

@@ -106,7 +106,7 @@ Structured query language for the `query` MCP tool. For simple lookups, prefer `
 Common operators: `eq`, `neq`, `gt`, `gte`, `lt`, `lte`, `contains`, `starts_with`, `starts_word`, `in`, `between`, `is_null`, `is_not_null`, `has_any`, `has_all`
 
 - `starts_word`: a word in the value starts with the text, case-insensitive, the way Affinity's search matches names (`"Jan"` matches "Jane Doe" and "Mary-Jane"; `"ane"` doesn't).
-- Person and company field values are compared by name ("Jane Doe", "Acme"). `contains` / `contains_any` / `contains_all` on them is refused: use `starts_word`.
+- Person and company field values are compared by name ("Jane Doe", "Acme"), or by id when the value is a number. `contains` / `contains_any` / `contains_all` on them is refused: use `starts_word`.
 - An empty multi-value field counts as empty: `is_null` matches it, `is_not_null` doesn't.
 - Name any field by id with `fields.<field id>` (e.g. `fields.affinity-data-year-founded`). When two list fields share a name (e.g. Affinity's and Dealroom's "Year Founded"), `fields.<name>` is refused with an error listing the ids; use the id. Such fields come back keyed by id.
 

{affinity_sdk-2.0.5 → affinity_sdk-2.0.7}/mcp/.claude-plugin/skills/query-language/references/filter-operators.md

@@ -23,7 +23,7 @@ Complete reference for all filter operators in the Affinity query language.
 
 `starts_word` matches the way Affinity's search matches names: `"Jan"` matches "Jane Doe" and "Mary-Jane"; `"ane"` doesn't.
 
-Person and company field values are compared by name ("Jane Doe", "Acme"). `contains`, `contains_any` and `contains_all` on a person or company field are refused: use `starts_word`.
+Person and company field values are compared by name ("Jane Doe", "Acme"), or by id when the value is a number. `contains`, `contains_any` and `contains_all` on a person or company field are refused: use `starts_word`.
 
 ## Collection Operators
 

affinity_sdk-2.0.7/mcp/.mcp-bash/VERSION

@@ -0,0 +1 @@
+1.9.6