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

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

@@ -7,6 +7,169 @@ 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)
+
+**Exception to semantic versioning:** these change what some filters return, in a patch release
+(the maintainer's call). Filters now mean what Affinity's own search means, so the same filter
+gives the same answer whether Affinity or the CLI applies it. This reaches Python code too:
+`affinity.filters` (`F`, filter strings, `lists.entries(...).list/iter/pages(filter=...)`)
+uses the same comparison rules as the CLI.
+
+- **An empty multi-value field counts as empty.** `is_null` / `is empty` now match a field with
+  no items (`[]`), and `is_not_null` / `is not null` no longer do, in `query`, `--filter` and
+  the SDK's `affinity.filters`.
+- **`contains` on person and company fields is refused** (in `query` on list entries): use the
+  new **`starts_word`** operator, which matches a word in the name that starts with the text,
+  the way Affinity's search does ("Jan" finds "Jane Doe"; "ane" doesn't).
+- **`query` sorts the way Affinity's search sorts:** Affinity's order is kept when it sorts,
+  and the local sort breaks ties by id (ascending) instead of keeping fetch order.
+- **`query`: a field name two list fields share is refused.** Name the field by id instead:
+  `fields.<field id>` (e.g. Affinity's and Dealroom's "Year Founded"). Such fields come back
+  keyed by id, instead of one silently overwriting the other. Any field can be named by id.
+- **Person and company field values filter by name** in `--filter` and the SDK's
+  `affinity.filters` (`Owner = "Jane Doe"`, `Owner starts_word "Jan"`), as they already did in
+  `query`; before, they were compared as raw objects.
+
+### Added
+
+- **`starts_word` filter operator** (`query` JSON and `--filter` text: `Owner starts_word "Jan"`).
+
+- **Teams, users and feedback (V2):** `client.teams.list/iter/get` (Affinity API 2026-09-17+;
+  filter by name, sort, `includes` for the first members and accessible lists),
+  `client.users.list/iter/get` (internal users; `term`, `status`; a user's id is their person
+  id), `client.feedback.send(kind, subject, body)` (to Affinity's product team). New models
+  `Team`, `TeamMember`, `UserAccount`, `UserStatus`.
+- **`interactions.get_meeting(id)`** (V2, API 2026-07-15+) and
+  **`notes.list/iter_attached_companies|persons|opportunities(note_id)`** (every entity a note
+  is attached to, beyond `get()`'s preview).
+- **Duplicate suggestions and warm intros (V2, beta):**
+  `companies/persons.list|iter_duplicate_suggestions` (API 2026-07-15+; `term`,
+  `match_criteria`, `order_by`) and `companies.list|iter_coworker_connections(company_id)` /
+  `list|iter_investor_executive_connections(company_id)` (people at a company today whom someone
+  you know may know). CLI `company duplicates`, `person duplicates`, `company connections`.
+- **One field at a time (V2):** `companies/persons.get_field_value(id, field_id)` (the value,
+  unwrapped) and `update_field_value(id, field_id, value, value_type=None)`;
+  `companies/persons.list|iter_field_value_items(id, field_id)` and
+  `lists.entries(list_id).list|iter_field_value_items(entry_id, field_id)` page through a
+  multi-value field's items (API 2026-09-17+); `lists.entries(list_id).list|iter_field_changes(
+  entry_id, ...)` give one entry's field change history, oldest first.
+- **Search on Affinity's side (V2, beta):** `companies.find`, `persons.find` and
+  `lists.entries(list_id).find` (plus `iter_find`, and `find_body` for a prebuilt request
+  body) filter, sort and keyword-search on the server, so only matching records are
+  downloaded. Build filters with `affinity.criteria`: `Condition(field_id, operator, value)`,
+  `all_of`, `any_of`, `Sort`. Value types are read from the fields metadata when omitted, and
+  each operator is checked against the field. Needs the "Export All Organizations directory"
+  permission (companies, persons) or "Export data from Lists" (list entries). Allowed under
+  read-only mode.
+- **`query` on list entries filters on Affinity's side:** conditions on list fields that
+  Affinity's search answers (dropdown and ranked-dropdown values, `!=` on dropdowns, numbers,
+  dates, text `contains`/`eq`/`starts_with`, `is_not_null` on single-value fields)
+  go to the server, so only matching entries are downloaded; the full `where` still runs
+  locally on what comes back, so results are unchanged. Everything else (related records,
+  `entityName`, `is_null`, Affinity's enriched fields, field names two fields share) is
+  filtered locally, as before. If the search is refused (for example, no "Export data from
+  Lists" permission) the query reads the whole list instead, with a warning.
+  `--include-meta` shows `meta.serverFilter` (what went to the server, and why the rest
+  didn't); `--dry-run` names the candidate fields. `XAFFINITY_QUERY_SERVER_FILTER=0` turns it
+  off.
+- **`list export --filter` filters on Affinity's side** through the same engine as `query`:
+  the `--filter` text becomes a `query` where clause, the part Affinity's search answers is
+  sent, and the whole filter still runs locally. When Affinity applies the whole filter,
+  `--all` / `--max-results` / `--first-page-only` are no longer required (page one is the
+  first page of matches); otherwise the error's `details.local` says which conditions stay
+  local. The printed cursor (`xsearch1:...`) carries the search, so `--cursor` alone resumes
+  a filtered export. A refused search falls back to reading the whole list, with a warning.
+- **`company ls --filter` and `person ls --filter` work** (they used to be refused): the filter
+  goes to Affinity's search, which filters on field values, and the whole filter still runs
+  locally on what comes back. A filter with no field condition is still refused (reading every
+  company isn't practical: use `--query`). Conditions on Affinity's enriched fields are sent
+  as they are, with a warning that Affinity's search can miss a few records' enriched values.
+  The cursor carries the search (`xsearch1:...`).
+- **`query` on companies and persons can filter on their fields** (`fields.<name>`): Affinity's
+  search applies what it can, the rest of the `where` (e.g. `name contains`) runs on what comes
+  back. A `where` with no field condition is still refused (it would mean reading Affinity's
+  whole directory). `meta.serverFilter` with `--include-meta`; enriched-field conditions carry
+  a warning that a few records' enriched values can be missed.
+- **More of `query` goes to Affinity** (list entries too): `is_null` / `is_not_null` on every
+  verified field type, multi-value fields included; multi-select dropdowns (`eq` membership,
+  `in`, `has_any`, `has_all`, `contains`/`starts_word` on option text, `!=`); `!=` on numbers;
+  and `starts_word` on a person or company
+  field (person, multi-person and multi-company fields; one per query, at the top level of the
+  `where`, plain text of 3+ letters).
+- **`query` sorts on Affinity's side** when every `orderBy` key is a sortable field
+  (`fields.<name>`, up to 5, no `groupBy`/`aggregate`): with a `limit`, the fetch stops once
+  enough records pass the filter, instead of reading everything to sort it. This works on
+  companies and persons without a `where` too. `meta.serverFilter.sort` says so.
+- **CLI:** `team ls|get`, `user ls|get`, `meeting get`, `note attached`, `feedback send` (asks
+  for confirmation: the text leaves your organization). The MCP registry has them; `feedback
+  send` goes through the user-confirmation flow.
+
+### Fixed
+
+- **`query --dry-run`** no longer claims a "server-side filter" for list entries that was never
+  applied.
+
 ## [2.0.1] - 2026-10-12
 
 ### Changed (breaking)

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

@@ -1,6 +1,6 @@
 Metadata-Version: 2.5
 Name: affinity-sdk
-Version: 2.0.1
+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/
@@ -215,15 +215,22 @@ with Affinity.from_env() as client:
 ### Working with Companies
 
 ```python
-from affinity import Affinity, F
+from datetime import date
+
+from affinity import Affinity
+from affinity.criteria import Condition, Sort, all_of
 from affinity.models import CompanyCreate
-from affinity.types import CompanyId, FieldType
+from affinity.types import CompanyId
 
 with Affinity(api_key="your-key") as client:
-    # List companies with filtering (V2 API)
-    companies = client.companies.list(
-        filter=F.field("domain").contains("acme"),
-        field_types=[FieldType.ENRICHED],
+    # Filter and sort on Affinity's side (V2 search, beta)
+    page = client.companies.find(
+        all_of(
+            Condition("field-498220", "is-any-of", [3, 4]),
+            Condition("affinity-data-last-funding-date", "is-after", date(2025, 1, 1)),
+        ),
+        sort=[Sort("affinity-data-total-funding-amount", "desc")],
+        limit=50,
     )
 
     # Iterate through all companies with automatic pagination

{affinity_sdk-2.0.1 → affinity_sdk-2.0.3}/README.md

@@ -154,15 +154,22 @@ with Affinity.from_env() as client:
 ### Working with Companies
 
 ```python
-from affinity import Affinity, F
+from datetime import date
+
+from affinity import Affinity
+from affinity.criteria import Condition, Sort, all_of
 from affinity.models import CompanyCreate
-from affinity.types import CompanyId, FieldType
+from affinity.types import CompanyId
 
 with Affinity(api_key="your-key") as client:
-    # List companies with filtering (V2 API)
-    companies = client.companies.list(
-        filter=F.field("domain").contains("acme"),
-        field_types=[FieldType.ENRICHED],
+    # Filter and sort on Affinity's side (V2 search, beta)
+    page = client.companies.find(
+        all_of(
+            Condition("field-498220", "is-any-of", [3, 4]),
+            Condition("affinity-data-last-funding-date", "is-after", date(2025, 1, 1)),
+        ),
+        sort=[Sort("affinity-data-total-funding-amount", "desc")],
+        limit=50,
     )
 
     # Iterate through all companies with automatic pagination

{affinity_sdk-2.0.1 → 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.1/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.3/affinity/_filtering/filter_text.py

@@ -0,0 +1,52 @@
+"""The ``--filter`` text language as a query WHERE clause.
+
+``--filter 'Status = "Won" & Amount > 5'`` and the JSON ``where`` of ``query`` are one filter
+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.
+
+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 (
+    AndExpression,
+    FieldComparison,
+    FilterExpression,
+    NotExpression,
+    OrExpression,
+    RawToken,
+)
+from .where import WhereClause
+
+# Row-level keys a list entry filter sees besides its fields (they aren't list fields).
+ROW_KEYS = frozenset(
+    {"name", "domain", "primary_email", "listEntryId", "entityId", "entityName", "entityType"}
+)
+
+
+def where_from_filter(expr: FilterExpression, row_keys: frozenset[str] = ROW_KEYS) -> WhereClause:
+    """The WHERE clause for a parsed ``--filter`` expression: field names become
+    ``fields.<name>`` paths; ``row_keys`` (attributes such as ``entityName``) keep their own
+    path. The default keys are a list entry's."""
+    if isinstance(expr, AndExpression):
+        return WhereClause(
+            and_=[where_from_filter(expr.left, row_keys), where_from_filter(expr.right, row_keys)]
+        )
+    if isinstance(expr, OrExpression):
+        return WhereClause(
+            or_=[where_from_filter(expr.left, row_keys), where_from_filter(expr.right, row_keys)]
+        )
+    if isinstance(expr, NotExpression):
+        return WhereClause(not_=where_from_filter(expr.expr, row_keys))
+    if isinstance(expr, FieldComparison):
+        name = expr.field_name
+        path = name if name in row_keys else f"fields.{name}"
+        if isinstance(expr.value, RawToken) and expr.value.token == "*":
+            # `field = *` is "has a value"; `field != *` is "no value"
+            op = "is_not_null" if expr.operator == "=" else "is_null"
+            return WhereClause(path=path, op=op)
+        return WhereClause(path=path, op=map_operator(expr.operator), value=expr.value)
+    # Raw filter strings can't be analysed: keep them local
+    return WhereClause(path=None, op=None)