affinity-sdk 2.0.2__tar.gz → 2.0.3__tar.gz

{affinity_sdk-2.0.2 → affinity_sdk-2.0.3}/CHANGELOG.md

@@ -7,6 +7,65 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 ## [Unreleased]
 
+## [2.0.3] - 2026-10-13
+
+**Exception to semantic versioning** (the maintainer's call, as 2.0.2): some results change
+(`list(filter=...)` pages, the local sort's order, date comparisons in filters). The
+`### Changed` entries say how.
+
+### Changed
+
+- **SDK list-entry filters go through Affinity's search:**
+  `lists.entries(id).list/pages/all/iter/get_first(filter=...)` send the part of the filter
+  Affinity's search can answer and check the whole filter locally, as `list export --filter`
+  does. Only when no part can go there (or the search is refused) is every entry read; that
+  case emits the new `ClientSideFilterWarning` (a `UserWarning`).
+- **`list(filter=...)` returns the matches of one page read**, possibly fewer than `limit` (or
+  none), with a `next_cursor` that carries the filter: follow it, or use `iter()` for every
+  match. Before, it filtered only the first page and had no way to continue.
+- **Filtered-read cursors are `xsearch2:`** (the filter travels as data, so multi-word field
+  names and dates round-trip) in the SDK, `list export`, and `company ls` / `person ls`;
+  2.0.2's `xsearch1:` cursors still work.
+- **Field values can be named by id in text filters** (`F.field("field-123")`,
+  `--filter 'field-123 = …'`), as `query` allows `fields.<id>`.
+- **`query`'s local sort follows Affinity's order** (when Affinity can't sort, e.g. an
+  unsortable field or a refused search): ranked dropdowns sort by rank (not by text),
+  multi-value fields by their first item, and text case-insensitively ("apple" before
+  "Zeta"); empty values stay last in both directions. Fields named only in `orderBy` are now
+  fetched (a local sort used to see them empty). Grouped rows (`groupBy`) sort by their keys
+  as before.
+- **Quantifier queries (`all`/`none`/`exists`) on companies and persons no longer always need
+  `--max-records`**: their `where` must test a field, which Affinity's search applies first;
+  when it matches at most 100 records the query runs, otherwise it stops and names the count.
+  `--dry-run` gives a number of API calls instead of "UNBOUNDED" (with `--max-records` too),
+  which also fixes the MCP query tool's timeout for these queries (it fell back to 120 s).
+  Validation errors found while the query runs exit 2 with `validation_error`, like those
+  found while planning.
+
+### Added
+
+- **`server_filter=False`** on the list-entry `list/pages/all/iter/get_first` reads every entry
+  and filters locally (to compare or debug), and **`affinity.ClientSideFilterWarning`**.
+- **More filters go to Affinity's search** (verified live): `starts_word` on single-company
+  fields, and `is_not_null` / `is_null` on location fields.
+
+- **A team's members and accessible lists, every page** (V2, beta; API 2026-09-17+):
+  `teams.list|iter_members(team_id)` and `teams.list|iter_accessible_lists(team_id)`; CLI
+  `team members <id>` and `team lists <id>` (`team get` shows only the first 10).
+
+### Fixed
+
+- **Dates compare as dates in `>`, `>=`, `<`, `<=` and between**, everywhere filters run
+  (`query`, `--filter`, `--expand-filter`, `company ls` / `person ls --filter`, and the SDK's
+  `affinity.filters`): relative dates (`-30d`, `today`) and ISO dates are compared with the
+  field's timestamp in UTC. Before, the text filter compared them as text, so
+  `Close > "-30d"` matched every dated entry. Equality stays textual (`= "today"` matches the
+  word). Timestamps with `Z` or long fractions parse on Python 3.10 too.
+- **`list export --field X --filter "Y = …"`** returned no rows: the filter's fields are now
+  fetched even when `--field` leaves them out of the output.
+- **`Team` reads `updatedAt`** (`updated_at`), and accepts the `membersPreview` /
+  `accessibleListsPreview` blocks under their own names too.
+
 ## [2.0.2] - 2026-10-13
 
 ### Changed (breaking)

{affinity_sdk-2.0.2 → affinity_sdk-2.0.3}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.5
 Name: affinity-sdk
-Version: 2.0.2
+Version: 2.0.3
 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.2 → affinity_sdk-2.0.3}/affinity/__init__.py

@@ -47,6 +47,7 @@ from .exceptions import (
     ApiVersionTooOldError,
     AuthenticationError,
     AuthorizationError,
+    ClientSideFilterWarning,
     CompanyMergedError,
     CompanyNotFoundError,
     ConfigurationError,
@@ -108,6 +109,7 @@ __all__ = [
     "AsyncAffinity",
     # Exceptions
     "AffinityError",
+    "ClientSideFilterWarning",
     "AuthenticationError",
     "AuthorizationError",
     "NotFoundError",

affinity_sdk-2.0.3/affinity/_filtering/__init__.py

@@ -0,0 +1,5 @@
+"""The filter engine shared by the SDK and the CLI: WHERE clauses, date parsing, the split of a
+filter into what Affinity's search can answer, and the ``--filter`` text conversion.
+
+Private package: not part of the public SDK API.
+"""

{affinity_sdk-2.0.2/affinity/cli/query → affinity_sdk-2.0.3/affinity/_filtering}/dates.py

@@ -1,7 +1,7 @@
 """Relative date parsing for query WHERE clauses.
 
 This module provides parsing for relative date strings like "-30d", "today", etc.
-It is CLI-only and NOT part of the public SDK API.
+Private module: not part of the public SDK API (the CLI and the SDK share it).
 """
 
 from __future__ import annotations
@@ -113,17 +113,31 @@ def parse_date_value(value: str) -> datetime | None:
         pass
 
     # Try ISO date
-    if ISO_DATE_PATTERN.match(value):
-        try:
-            # Handle with and without time component
-            if "T" in value:
-                return datetime.fromisoformat(value.replace("Z", "+00:00"))
-            else:
-                return datetime.fromisoformat(value)
-        except ValueError:
-            pass
-
-    return None
+    return parse_iso_datetime(value)
+
+
+_FRACTION = re.compile(r"(\.\d+)")
+
+
+def parse_iso_datetime(value: object) -> datetime | None:
+    """An ISO 8601 date or date-time (``YYYY-MM-DD``, ``...THH:MM:SS[.fraction][Z|±HH:MM]``) as a
+    datetime, or ``None``. Tolerant of what Python 3.10's ``fromisoformat`` rejects: ``Z`` and
+    fractions that aren't 3 or 6 digits."""
+    if not isinstance(value, str) or not ISO_DATE_PATTERN.match(value.strip()):
+        return None
+    text = value.strip()
+    if text.endswith(("Z", "z")):
+        text = text[:-1] + "+00:00"
+    text = _FRACTION.sub(lambda m: (m.group(1) + "000000")[:7], text, count=1)
+    try:
+        return datetime.fromisoformat(text)
+    except ValueError:
+        return None
+
+
+def as_utc(value: datetime) -> datetime:
+    """``value`` with a time zone: naive values are taken as UTC."""
+    return value if value.tzinfo is not None else value.replace(tzinfo=timezone.utc)
 
 
 def days_since(date: datetime, *, now: datetime | None = None) -> int:

{affinity_sdk-2.0.2/affinity/cli/query → affinity_sdk-2.0.3/affinity/_filtering}/filter_text.py

@@ -4,13 +4,13 @@
 language written two ways; this turns the first into the second, so both go through the same
 server-side split (:mod:`.pushdown`). The text filter still runs locally exactly as before.
 
-This module is CLI-only and NOT part of the public SDK API.
+Private module: not part of the public SDK API (the CLI and the SDK share it).
 """
 
 from __future__ import annotations
 
-from ...compare import map_operator
-from ...filters import (
+from ..compare import map_operator
+from ..filters import (
     AndExpression,
     FieldComparison,
     FilterExpression,
@@ -18,7 +18,7 @@ from ...filters import (
     OrExpression,
     RawToken,
 )
-from .models import WhereClause
+from .where import WhereClause
 
 # Row-level keys a list entry filter sees besides its fields (they aren't list fields).
 ROW_KEYS = frozenset(

{affinity_sdk-2.0.2/affinity/cli/query → affinity_sdk-2.0.3/affinity/_filtering}/pushdown.py

@@ -9,7 +9,7 @@ A mapping is used only when it is in :data:`VERIFIED` — confirmed against the
 ``tools/search_golden.py`` (server count == local count on real data). Unverified mappings stay
 local.
 
-This module is CLI-only and NOT part of the public SDK API.
+Private module: not part of the public SDK API (the CLI and the SDK share it).
 """
 
 from __future__ import annotations
@@ -21,11 +21,11 @@ from dataclasses import dataclass, field
 from datetime import date, datetime, timedelta
 from typing import Any
 
-from ...compare import compare_values
-from ...criteria import Condition, FilterGroup, filter_value_type
-from ...models.entities import DropdownOption, FieldMetadata
+from ..compare import compare_values
+from ..criteria import Condition, FilterGroup, filter_value_type
+from ..models.entities import DropdownOption, FieldMetadata
 from .dates import parse_date_value
-from .models import WhereClause
+from .where import WhereClause
 
 # (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,
@@ -78,6 +78,12 @@ VERIFIED: frozenset[tuple[str, str]] = frozenset(
         ("dropdown-multi", "has-all-of"),
         ("dropdown-multi", "has-none-of"),
         ("number", "is-not-equal-to"),
+        # Fourth run (lists with single-company and location fields), 2026-10-13
+        ("company", "term"),
+        ("company", "is-not-empty"),
+        ("location", "is-not-empty"),
+        ("location-multi", "is-empty"),
+        ("location-multi", "is-not-empty"),
     }
 )
 

affinity_sdk-2.0.3/affinity/_filtering/search.py

@@ -0,0 +1,305 @@
+"""Filtering list entries, companies and persons through Affinity's search, shared by the SDK
+(``lists.entries(id).list/pages/all/iter(filter=...)``) and the CLI (``list export --filter``,
+``company ls`` / ``person ls --filter``).
+
+- :func:`plan_filter` splits a text filter (or :class:`~affinity.filters.FilterExpression`)
+  into the search body Affinity can answer and the rest, which the caller re-checks locally.
+- Next-page cursors carry the filter, so a cursor alone resumes a filtered read:
+  ``xsearch2:`` + base64 JSON ``{"k": "search"|"local", "u": next page URL, "b": search body,
+  "f": filter tree}``. ``k="search"`` re-sends ``b`` to ``u`` (a search's next page needs its
+  body); ``k="local"`` reads ``u`` (a plain page) and filters it locally. ``xsearch1:`` cursors
+  (filter as text, always a search) from 2.0.2 still decode.
+- :class:`SearchCache` keeps fields, dropdown options and refused searches per list for a while.
+
+Private module: not part of the public SDK API.
+"""
+
+from __future__ import annotations
+
+import base64
+import json
+import threading
+import time
+from collections.abc import Callable, Iterable, Sequence
+from dataclasses import dataclass, field
+from datetime import date, datetime
+from typing import Any, Literal
+from urllib.parse import urlparse
+
+from ..criteria import SearchCriteria
+from ..filters import (
+    AndExpression,
+    FieldComparison,
+    FilterExpression,
+    NotExpression,
+    OrExpression,
+    RawFilter,
+    RawToken,
+    parse,
+)
+from ..models.entities import DropdownOption, FieldMetadata
+from .filter_text import ROW_KEYS, where_from_filter
+from .pushdown import fields_index, split_where
+from .where import WhereClause
+
+CURSOR_V2 = "xsearch2:"
+CURSOR_V1 = "xsearch1:"
+CURSOR_PREFIXES = (CURSOR_V2, CURSOR_V1)
+CACHE_TTL_SECONDS = 300.0
+
+CursorKind = Literal["search", "local"]
+
+
+# --- plan ---------------------------------------------------------------------------------------
+
+
+@dataclass
+class FilterPlan:
+    """What Affinity's search applies of a filter (``body``; ``None``: nothing) and the notes."""
+
+    body: dict[str, Any] | None
+    field_ids: list[str] = field(default_factory=list)  # fields the filter tests
+    pushed: list[str] = field(default_factory=list)
+    local: list[str] = field(default_factory=list)
+    caveats: list[str] = field(default_factory=list)
+    errors: list[str] = field(default_factory=list)
+
+    @property
+    def complete(self) -> bool:
+        """Every condition went to the server."""
+        return self.body is not None and not self.local
+
+
+def reject_raw_filters(expr: FilterExpression) -> None:
+    """``RawFilter`` can't be evaluated locally; refuse it anywhere in the tree."""
+    if isinstance(expr, RawFilter):
+        raise ValueError(
+            "A raw filter string can't filter list entries, companies or persons: "
+            "use a parsed filter (affinity.filters.parse or the F builder)"
+        )
+    for child in _children(expr):
+        reject_raw_filters(child)
+
+
+def _children(expr: FilterExpression) -> list[FilterExpression]:
+    if isinstance(expr, (AndExpression, OrExpression)):
+        return [expr.left, expr.right]
+    if isinstance(expr, NotExpression):
+        return [expr.expr]
+    return []
+
+
+def _field_paths(where: WhereClause) -> set[str]:
+    paths: set[str] = set()
+    if where.path and where.path.startswith("fields."):
+        paths.add(where.path.removeprefix("fields."))
+    for child in [*(where.and_ or []), *(where.or_ or [])]:
+        paths |= _field_paths(child)
+    if where.not_ is not None:
+        paths |= _field_paths(where.not_)
+    return paths
+
+
+def referenced_field_names(expr: FilterExpression, row_keys: frozenset[str] = ROW_KEYS) -> set[str]:
+    """The field names (or ids) a filter tests; record attributes (``row_keys``) excluded."""
+    return _field_paths(where_from_filter(expr, row_keys))
+
+
+def plan_filter(
+    expr: FilterExpression,
+    fields: Sequence[FieldMetadata],
+    options_for: Callable[[FieldMetadata], Sequence[DropdownOption]],
+    *,
+    row_keys: frozenset[str] = ROW_KEYS,
+    enriched: str = "or-empty",
+) -> FilterPlan:
+    """Split ``expr`` for these fields (pure: ``options_for`` supplies dropdown options)."""
+    where = where_from_filter(expr, row_keys)
+    split = split_where(where, fields, options_for, enriched=enriched)
+    index = fields_index(fields)
+    ids: list[str] = []
+    for name in sorted(_field_paths(where)):
+        meta = index.get(name) or index.get(name.lower())
+        if meta is not None and str(meta.id) not in ids:
+            ids.append(str(meta.id))
+    body = (
+        SearchCriteria(where=split.where, term=split.term, term_fields=split.term_fields).to_body()
+        if split.server_side
+        else None
+    )
+    return FilterPlan(
+        body=body,
+        field_ids=ids,
+        pushed=split.pushed,
+        local=split.local,
+        caveats=split.caveats,
+        errors=split.errors,
+    )
+
+
+def dropdown_fields(expr: FilterExpression, fields: Sequence[FieldMetadata]) -> list[FieldMetadata]:
+    """The dropdown fields a filter tests (their options are needed to plan it)."""
+    index = fields_index(fields)
+    out: list[FieldMetadata] = []
+    for name in sorted(referenced_field_names(expr)):
+        meta = index.get(name) or index.get(name.lower())
+        value_type = str(getattr(meta.value_type, "value", meta.value_type)) if meta else ""
+        if meta is not None and value_type in ("dropdown", "ranked-dropdown", "dropdown-multi"):
+            out.append(meta)
+    return out
+
+
+# --- filter tree (cursor payload) ---------------------------------------------------------------
+
+
+def _value_to_json(value: Any) -> Any:
+    if isinstance(value, RawToken):
+        return {"t": "raw", "v": value.token}
+    if isinstance(value, datetime):
+        return {"t": "datetime", "v": value.isoformat()}
+    if isinstance(value, date):
+        return {"t": "date", "v": value.isoformat()}
+    if isinstance(value, (list, tuple)):
+        return {"t": "list", "v": [_value_to_json(v) for v in value]}
+    if value is None or isinstance(value, (str, bool, int, float)):
+        return {"t": "value", "v": value}
+    raise ValueError(f"Can't put a {type(value).__name__} filter value in a cursor")
+
+
+def _value_from_json(obj: Any) -> Any:
+    if not isinstance(obj, dict) or set(obj) != {"t", "v"}:
+        raise ValueError("bad value")
+    tag, v = obj["t"], obj["v"]
+    if tag == "raw":
+        if v != "*":
+            raise ValueError("bad raw token")
+        return RawToken("*")
+    if tag == "datetime" and isinstance(v, str):
+        return datetime.fromisoformat(v)
+    if tag == "date" and isinstance(v, str):
+        return date.fromisoformat(v)
+    if tag == "list" and isinstance(v, list):
+        return [_value_from_json(x) for x in v]
+    if tag == "value" and (v is None or isinstance(v, (str, bool, int, float))):
+        return v
+    raise ValueError("bad value")
+
+
+def filter_to_json(expr: FilterExpression) -> Any:
+    """A filter expression as JSON data (round-trips, unlike ``to_string``)."""
+    if isinstance(expr, FieldComparison):
+        return {
+            "cmp": [expr.field_name, expr.operator, _value_to_json(expr.value)],
+        }
+    if isinstance(expr, AndExpression):
+        return {"and": [filter_to_json(expr.left), filter_to_json(expr.right)]}
+    if isinstance(expr, OrExpression):
+        return {"or": [filter_to_json(expr.left), filter_to_json(expr.right)]}
+    if isinstance(expr, NotExpression):
+        return {"not": filter_to_json(expr.expr)}
+    raise ValueError(f"Can't put a {type(expr).__name__} in a cursor")
+
+
+def filter_from_json(obj: Any, depth: int = 0) -> FilterExpression:
+    """The filter expression :func:`filter_to_json` made; ``ValueError`` for anything else."""
+    if depth > 64 or not isinstance(obj, dict) or len(obj) != 1:
+        raise ValueError("bad filter")
+    ((key, value),) = obj.items()
+    if key == "cmp" and isinstance(value, list) and len(value) == 3:
+        name, operator, raw = value
+        if not isinstance(name, str) or not isinstance(operator, str):
+            raise ValueError("bad comparison")
+        return FieldComparison(name, operator, _value_from_json(raw))
+    if key in ("and", "or") and isinstance(value, list) and len(value) == 2:
+        left, right = (filter_from_json(v, depth + 1) for v in value)
+        return AndExpression(left, right) if key == "and" else OrExpression(left, right)
+    if key == "not":
+        return NotExpression(filter_from_json(value, depth + 1))
+    raise ValueError("bad filter")
+
+
+# --- cursors ------------------------------------------------------------------------------------
+
+
+@dataclass(frozen=True)
+class SearchCursor:
+    """A decoded filtered-read cursor."""
+
+    kind: CursorKind
+    url: str
+    body: dict[str, Any] | None
+    filter: FilterExpression
+
+
+def encode_cursor(
+    kind: CursorKind, url: str, body: dict[str, Any] | None, expr: FilterExpression
+) -> str:
+    payload = {"k": kind, "u": url, "b": body, "f": filter_to_json(expr)}
+    raw = json.dumps(payload, separators=(",", ":")).encode()
+    return CURSOR_V2 + base64.urlsafe_b64encode(raw).decode().rstrip("=")
+
+
+def is_filter_cursor(cursor: str | None) -> bool:
+    return cursor is not None and cursor.startswith(CURSOR_PREFIXES)
+
+
+def decode_cursor(cursor: str, *, path_suffixes: Iterable[str]) -> SearchCursor | None:
+    """The filtered-read cursor in ``cursor`` (``None`` when it's a plain page URL). The
+    cursor is user input: anything malformed, or a cursor for another kind of record (its URL
+    path must end with one of ``path_suffixes``), raises ``ValueError``."""
+    if not is_filter_cursor(cursor):
+        return None
+    prefix = CURSOR_V2 if cursor.startswith(CURSOR_V2) else CURSOR_V1
+    encoded = cursor.removeprefix(prefix)
+    try:
+        data = json.loads(base64.urlsafe_b64decode(encoded + "=" * (-len(encoded) % 4)))
+    except (ValueError, TypeError) as e:
+        raise ValueError("This cursor is damaged: start the read again without it") from e
+    if not isinstance(data, dict) or not isinstance(data.get("u"), str):
+        raise ValueError("This cursor is damaged: start the read again without it")
+    url = data["u"]
+    if not any(urlparse(url).path.endswith(s) for s in path_suffixes):
+        raise ValueError("This cursor belongs to a different list or kind of record")
+    if prefix == CURSOR_V1:
+        body, text = data.get("b"), data.get("f")
+        if not isinstance(body, dict) or not isinstance(text, str):
+            raise ValueError("This cursor is damaged: start the read again without it")
+        return SearchCursor("search", url, body, parse(text))
+    kind, body = data.get("k"), data.get("b")
+    if kind not in ("search", "local") or (kind == "search" and not isinstance(body, dict)):
+        raise ValueError("This cursor is damaged: start the read again without it")
+    return SearchCursor(
+        kind, url, body if kind == "search" else None, filter_from_json(data.get("f"))
+    )
+
+
+# --- cache --------------------------------------------------------------------------------------
+
+
+class SearchCache:
+    """Per-client cache for planning searches: a list's fields (with filterability), dropdown
+    options, and lists whose search was refused (403 / 404 / unsupported). Entries expire
+    after ``ttl`` seconds; races only cost a duplicate fetch."""
+
+    def __init__(self, ttl: float = CACHE_TTL_SECONDS) -> None:
+        self._ttl = ttl
+        self._data: dict[tuple[str, ...], tuple[float, Any]] = {}
+        self._lock = threading.Lock()
+
+    def get(self, key: tuple[str, ...]) -> Any | None:
+        with self._lock:
+            hit = self._data.get(key)
+            if hit is None or hit[0] < time.monotonic():
+                self._data.pop(key, None)
+                return None
+            return hit[1]
+
+    def put(self, key: tuple[str, ...], value: Any) -> None:
+        with self._lock:
+            self._data[key] = (time.monotonic() + self._ttl, value)
+
+    def drop_scope(self, scope: str) -> None:
+        """Forget everything cached for one list (or entity type), e.g. after a 400."""
+        with self._lock:
+            for key in [k for k in self._data if k[1:2] == (scope,)]:
+                del self._data[key]

affinity_sdk-2.0.3/affinity/_filtering/where.py

@@ -0,0 +1,108 @@
+"""WHERE clauses: the filter language's structured form (``query``'s JSON ``where``; the
+``--filter`` text converts to it). Shared by the SDK's server-side filtering and the CLI.
+
+Private module: not part of the public SDK API.
+"""
+
+from __future__ import annotations
+
+from typing import Any, Literal
+
+from pydantic import BaseModel, ConfigDict, Field
+
+__all__ = ["ExistsClause", "FilterCondition", "QuantifierClause", "WhereClause"]
+
+
+class FilterCondition(BaseModel):
+    """A single filter condition.
+
+    Examples:
+        {"path": "email", "op": "contains", "value": "@acme.com"}
+        {"path": "createdAt", "op": "gt", "value": "-30d"}
+        {"path": "companies._count", "op": "gte", "value": 2}
+    """
+
+    model_config = ConfigDict(extra="forbid")
+
+    path: str | None = None
+    expr: dict[str, Any] | None = None
+    op: Literal[
+        "eq",
+        "neq",
+        "gt",
+        "gte",
+        "lt",
+        "lte",
+        "contains",
+        "starts_with",
+        "in",
+        "between",
+        "is_null",
+        "is_not_null",
+        "contains_any",
+        "contains_all",
+        "starts_word",
+    ]
+    value: Any = None
+
+
+class QuantifierClause(BaseModel):
+    """Quantifier clause for 'all' or 'none' predicates.
+
+    Examples:
+        {"all": {"path": "interactions", "where": {"path": "type", "op": "eq", "value": "MEETING"}}}
+    """
+
+    model_config = ConfigDict(extra="forbid")
+
+    path: str
+    where: WhereClause
+
+
+class ExistsClause(BaseModel):
+    """EXISTS subquery clause.
+
+    Examples:
+        {"exists": {"from": "interactions", "via": "personId", "where": {...}}}
+    """
+
+    model_config = ConfigDict(extra="forbid")
+
+    from_: str = Field(..., alias="from")
+    via: str | None = None
+    where: WhereClause | None = None
+
+
+class WhereClause(BaseModel):
+    """WHERE clause supporting compound conditions.
+
+    Can be:
+    - A single condition: {"path": "x", "op": "eq", "value": "y"}
+    - Compound: {"and": [...]} or {"or": [...]}
+    - Negation: {"not": {...}}
+    - Quantifiers: {"all": {...}} or {"none": {...}}
+    - Existence: {"exists": {...}}
+    """
+
+    model_config = ConfigDict(extra="forbid", populate_by_name=True)
+
+    # Single condition fields
+    path: str | None = None
+    expr: dict[str, Any] | None = None
+    op: str | None = None
+    value: Any = None
+
+    # Compound conditions
+    and_: list[WhereClause] | None = Field(None, alias="and")
+    or_: list[WhereClause] | None = Field(None, alias="or")
+    not_: WhereClause | None = Field(None, alias="not")
+
+    # Quantifiers
+    all_: QuantifierClause | None = Field(None, alias="all")
+    none_: QuantifierClause | None = Field(None, alias="none")
+
+    # Existence
+    exists_: ExistsClause | None = Field(None, alias="exists")
+
+
+WhereClause.model_rebuild()

{affinity_sdk-2.0.2 → affinity_sdk-2.0.3}/affinity/cli/commands/company_cmds.py

@@ -27,7 +27,7 @@ from ..csv_utils import write_csv_to_stdout
 from ..decorators import category, destructive, progress_capable
 from ..entity_search import COMPANY_KEYS, filtered_ls
 from ..errors import CLIError
-from ..list_search import SEARCH_CURSOR_PREFIX
+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 ..progress import ProgressManager, ProgressSettings
@@ -433,7 +433,7 @@ def company_ls(
         )
 
         # --filter (or a cursor from a filtered run): Affinity's search filters on its side
-        if filter_expr is not None or (cursor or "").startswith(SEARCH_CURSOR_PREFIX):
+        if filter_expr is not None or is_filter_cursor(cursor):
             found, next_token = filtered_ls(
                 client.companies,
                 entity="company",