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

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

@@ -7,6 +7,110 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 ## [Unreleased]
 
+## [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.2}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.5
 Name: affinity-sdk
-Version: 2.0.1
+Version: 2.0.2
 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.2}/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.2}/affinity/cli/commands/company_cmds.py

@@ -25,7 +25,9 @@ from ..confirm import run_destructive
 from ..context import CLIContext
 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 ..mcp_limits import apply_mcp_limits
 from ..options import csv_output_options, csv_suboption_callback, output_options
 from ..progress import ProgressManager, ProgressSettings
@@ -327,7 +329,8 @@ def _parse_field_types(values: tuple[str, ...]) -> list[FieldType] | None:
     "filter_expr",
     type=str,
     default=None,
-    help="Filter: 'field op value'. Ops: = != =~ =^ =$ > < >= <=. E.g., 'name =~ \"Acme\"'.",
+    help="Filter on company fields, applied by Affinity's search: 'field op value'. Ops: = != "
+    "=~ =^ =$ > < >= <= starts_word. E.g., 'Stage = \"Seed\"'. Name search: --query.",
 )
 @click.option(
     "--query",
@@ -378,17 +381,6 @@ def company_ls(
     """
 
     def fn(ctx: CLIContext, warnings: list[str]) -> CommandOutput:
-        if filter_expr is not None:
-            raise CLIError(
-                "The V2 /companies endpoint does not support server-side filtering. "
-                "The --filter flag was silently ignored in previous versions. "
-                "Use --query TERM for name/domain fuzzy search instead.",
-                exit_code=2,
-                error_type="unsupported_filter",
-                hint='Try: xaffinity company ls --query "Acme"',
-                details={"rejected_filter": str(filter_expr)},
-            )
-
         client = ctx.get_client(warnings=warnings)
 
         if cursor is not None and page_size is not None:
@@ -440,6 +432,32 @@ def company_ls(
             [FieldId(fid) for fid in field_ids] if field_ids else None
         )
 
+        # --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):
+            found, next_token = filtered_ls(
+                client.companies,
+                entity="company",
+                filter_expr=filter_expr,
+                cursor=cursor,
+                row_keys=COMPANY_KEYS,
+                row=_company_ls_row,
+                field_ids=list(field_ids or ()),
+                page_size=page_size,
+                max_results=max_results,
+                all_pages=all_pages,
+                warnings=warnings,
+            )
+            return CommandOutput(
+                data={"companies": found},
+                context=cmd_context,
+                pagination=(
+                    {"companies": {"nextCursor": next_token, "prevCursor": None}}
+                    if next_token
+                    else None
+                ),
+                api_called=True,
+            )
+
         rows: list[dict[str, object]] = []
         first_page = True
         use_v1_search = query is not None

affinity_sdk-2.0.2/affinity/cli/commands/discovery_cmds.py

@@ -0,0 +1,243 @@
+"""`company duplicates`, `person duplicates`, `company connections` (V2, beta)."""
+
+from __future__ import annotations
+
+from typing import Any
+
+from affinity.models.discovery import (
+    CompanyDuplicateSuggestion,
+    CoworkerConnectionGroup,
+    DuplicateCompanyProfile,
+    InvestorExecutiveConnectionGroup,
+    PersonDuplicateSuggestion,
+)
+from affinity.models.entities import Person
+from affinity.models.relationships_v2 import RelationshipPerson
+
+from ..click_compat import RichCommand, click
+from ..context import CLIContext
+from ..decorators import category
+from ..mcp_limits import apply_mcp_limits
+from ..options import output_options
+from ..results import CommandContext
+from ..runner import CommandOutput, run_command
+from ._org_reads import collect_pages, page_limit, pagination
+from .company_cmds import _resolve_company_selector, company_group
+from .org_read_cmds import _cursor_alone, _paging_options
+from .person_cmds import person_group
+
+_ORDER = click.Choice(["name", "-name", "createdAt", "-createdAt"])
+
+
+def _name(first: str | None, last: str | None) -> str | None:
+    return f"{first or ''} {last or ''}".strip() or None
+
+
+def _company(c: DuplicateCompanyProfile) -> dict[str, object]:
+    return {"id": int(c.id), "name": c.name, "domain": c.domain}
+
+
+def _person(p: Person) -> dict[str, object]:
+    return {"id": int(p.id), "name": _name(p.first_name, p.last_name), "email": p.primary_email}
+
+
+def company_suggestion_row(s: CompanyDuplicateSuggestion) -> dict[str, object]:
+    return {
+        "suggestionId": s.id,
+        "matchCriteria": s.match_criteria,
+        "primary": _company(s.primary),
+        "duplicate": _company(s.duplicates[0]) if s.duplicates else None,
+    }
+
+
+def person_suggestion_row(s: PersonDuplicateSuggestion) -> dict[str, object]:
+    return {
+        "suggestionId": s.id,
+        "matchCriteria": s.match_criteria,
+        "primary": _person(s.primary),
+        "duplicate": _person(s.duplicates[0]) if s.duplicates else None,
+    }
+
+
+def _source(p: RelationshipPerson) -> dict[str, object]:
+    return {
+        "personId": int(p.id),
+        "name": _name(p.first_name, p.last_name),
+        "email": p.primary_email_address,
+    }
+
+
+def connection_row(
+    g: CoworkerConnectionGroup | InvestorExecutiveConnectionGroup,
+) -> dict[str, object]:
+    target = {
+        "name": g.target.full_name,
+        "title": g.target.title,
+        "linkedinUrl": g.target.linkedin_url,
+        "companyId": int(g.target.current_company.id),
+    }
+    via: list[dict[str, object]] = []
+    if isinstance(g, CoworkerConnectionGroup):
+        for c in g.connections:
+            via.append(
+                {
+                    **_source(c.source),
+                    "sharedEmployer": c.shared_employer.name,
+                    "from": c.overlap_start.isoformat(),
+                    "to": c.overlap_end.isoformat(),
+                }
+            )
+    else:
+        for deal in g.connections:
+            via.append(
+                {
+                    **_source(deal.source),
+                    "investorFirm": deal.investor.company.name,
+                    "investorTitle": deal.investor.title,
+                    "round": deal.funding_round.series,
+                    "roundDate": deal.funding_round.date.isoformat(),
+                    "executiveTitle": deal.executive.title,
+                    "portfolioCompany": deal.executive.company.name,
+                }
+            )
+    return {"target": target, "via": via}
+
+
+def _duplicates_command(entity: str, parent: Any, matches: list[str]) -> None:
+    command = f"{entity} duplicates"
+    service_name = "companies" if entity == "company" else "persons"
+    row = company_suggestion_row if entity == "company" else person_suggestion_row
+
+    @category("read")
+    @parent.command(name="duplicates", cls=RichCommand)
+    @click.option("--term", default=None, help="Narrow by name (2+ characters).")
+    @click.option(
+        "--match", "match", type=click.Choice(matches), default=None, help="Match criterion."
+    )
+    @click.option("--sort", type=_ORDER, default=None, help="Order ('-' for descending).")
+    @_paging_options
+    @output_options
+    @click.pass_obj
+    @apply_mcp_limits()
+    def duplicates(
+        ctx: CLIContext,
+        *,
+        term: str | None,
+        match: str | None,
+        sort: str | None,
+        cursor: str | None,
+        max_results: int | None,
+        all_pages: bool,
+    ) -> None:
+        def fn(ctx: CLIContext, warnings: list[str]) -> CommandOutput:
+            _cursor_alone(cursor, term=term, match=match, sort=sort)
+            service = getattr(ctx.get_client(warnings=warnings), service_name)
+            rows, next_cursor = collect_pages(
+                (lambda: service.list_duplicate_suggestions(cursor=cursor))
+                if cursor is not None
+                else (
+                    lambda: service.list_duplicate_suggestions(
+                        term=term,
+                        match_criteria=match,
+                        order_by=sort,
+                        limit=page_limit(max_results),
+                    )
+                ),
+                lambda c: service.list_duplicate_suggestions(cursor=c),
+                row,
+                max_results=max_results,
+                all_pages=all_pages,
+                warnings=warnings,
+            )
+            modifiers = {k: v for k, v in (("term", term), ("match", match), ("sort", sort)) if v}
+            return CommandOutput(
+                data={"suggestions": rows},
+                context=CommandContext(name=command, inputs={}, modifiers=modifiers),
+                pagination=pagination(next_cursor),
+                api_called=True,
+            )
+
+        run_command(ctx, command=command, fn=fn)
+
+    confidence = (
+        "domain-match (high), domain-redirect (medium), name (low)"
+        if entity == "company"
+        else "intelligent (medium: email matching across sources), name (low)"
+    )
+    duplicates.help = (
+        f"{entity.capitalize()} pairs Affinity thinks are duplicates, not yet acted on (V2, "
+        f"beta; API 2026-07-15+). Match criteria: {confidence}. Merge one with "
+        f"`{entity} merge <primary> <duplicate>`."
+    )
+
+
+_duplicates_command("company", company_group, ["domain-match", "domain-redirect", "name"])
+_duplicates_command("person", person_group, ["intelligent", "name"])
+
+
+@category("read")
+@company_group.command(name="connections", cls=RichCommand)
+@click.argument("selector", type=str)
+@click.option(
+    "--type",
+    "kind",
+    type=click.Choice(["coworkers", "investor-executive"]),
+    default="coworkers",
+    show_default=True,
+    help="coworkers: worked together before; investor-executive: an investor you know backed "
+    "a company the target ran.",
+)
+@_paging_options
+@output_options
+@click.pass_obj
+@apply_mcp_limits()
+def company_connections(
+    ctx: CLIContext,
+    *,
+    selector: str,
+    kind: str,
+    cursor: str | None,
+    max_results: int | None,
+    all_pages: bool,
+) -> None:
+    """Warm intros into a company: people there today whom someone you know may know (V2, beta).
+
+    One row per target, strongest first, with `via`: the people you know and why. Targets
+    aren't in your Affinity data (name, title, LinkedIn only).
+    """
+
+    def fn(ctx: CLIContext, warnings: list[str]) -> CommandOutput:
+        _cursor_alone(cursor)
+        client = ctx.get_client(warnings=warnings)
+        company_id, resolved = _resolve_company_selector(
+            client=client, selector=selector, cache=ctx.session_cache
+        )
+        method = (
+            client.companies.list_coworker_connections
+            if kind == "coworkers"
+            else client.companies.list_investor_executive_connections
+        )
+        limit = min(max_results, 50) if max_results is not None else None
+        rows, next_cursor = collect_pages(
+            (lambda: method(company_id, cursor=cursor))
+            if cursor is not None
+            else (lambda: method(company_id, limit=limit)),
+            lambda c: method(company_id, cursor=c),
+            connection_row,
+            max_results=max_results,
+            all_pages=all_pages,
+            warnings=warnings,
+        )
+        return CommandOutput(
+            data={"connections": rows},
+            context=CommandContext(
+                name="company connections",
+                inputs={"selector": selector},
+                modifiers={"type": kind},
+            ),
+            resolved=resolved,
+            pagination=pagination(next_cursor),
+            api_called=True,
+        )
+
+    run_command(ctx, command="company connections", fn=fn)