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

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

@@ -5,7 +5,239 @@ 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).
 
-## [Unreleased]
+## [2.0.4] - 2026-10-14
+
+**Exception to semantic versioning** (the maintainer's call, as 2.0.2 and 2.0.3): which API key
+the CLI uses changes when a key flag and a key environment variable are both set. The
+`### Changed` entry says how. Some fixes below also change what a call returns or raises,
+or a CLI exit code; each is marked **Behavior change**.
+
+### Changed
+
+- **CLI: `--api-key-file` and `--api-key-stdin` win over the environment.** A key named on the
+  command line is used even when `AFFINITY_API_KEY`, `AFFINITY_API_KEY_FILE` or
+  `AFFINITY_API_KEY_COMMAND` is set, and the CLI warns that those are ignored (the file is not
+  read and the command is not run). Before, an environment key silently replaced the flag's key,
+  so a stale `export` could send reads and writes to another workspace. To keep using the
+  environment key, drop the flag. The SDK and the MCP server (which passes no key flag) are
+  unchanged.
+
+### Fixed
+
+- `config check-key` reports `source: "flag"` (and a `pattern` repeating the flag) when
+  `--api-key-file` or `--api-key-stdin` is given, as commands now use that key first. It
+  doesn't read stdin; a missing or empty key file counts as not configured.
+- The missing-API-key error no longer says `config setup-key` saves to the system keychain: it
+  writes a config file, or a `.env` file with `--scope project`.
+- Docs: one API-key resolution order across the README, guides, CLI page, MCP README and CLI
+  skill (there is no `--api-key` CLI flag).
+- Docs: the README coverage table, routing guide, glossary and errors guide describe 2.0's
+  routing (company and person field values, `notes.get`, transcripts, teams, semantic search
+  and connections are V2); `api-versions.md` lists every call that sends a minimum version;
+  beta endpoints need no opt-in.
+- Docs: the CLI command page documents `files ls`/`read`/`download` on persons, companies and
+  opportunities (not the old `files dump`), `relationship-strength ls` (not `get`),
+  `opportunity field`, `list entry get`, `file-url` and `config update-check`; the CLI page says
+  which list commands return a bare `data` array.
+- Docs: the official-MCP comparison lists this project's transcript, meeting, team, user,
+  duplicate and connection reads; `VERSIONING.md` describes 2.x and its patch-release
+  exceptions; the MCP README asks for Python 3.10+.
+- Docs: the docs home page introduces the project and links configuration, migration, API
+  versions, the query command and webhooks; a Transcripts reference page; the reference nav no
+  longer files V2 services under "V1 endpoints"; the `Affinity`/`AsyncAffinity` docstrings and
+  the sync/async table list every service; the field-values guide starts with the V2
+  company/person/list-entry methods; the plugins page covers all three plugins.
+- Docs and `file-url` help: examples use placeholder ids and names.
+- **Behavior change. SDK: an empty id list returns an empty page.** `list(ids=[])` on companies,
+  persons, opportunities, webhooks, teams, users and reminders used to omit the filter and return
+  the whole collection; it now returns no rows without calling the API. `limit=0` (or less) raises
+  `ValueError` where it used to be dropped silently (companies, persons, opportunities, a
+  company's lists and list entries, saved-view entries).
+- **Behavior change. SDK: field writes.** A `bool` value raises `TypeError` (Affinity has no
+  boolean field type; it was sent as malformed text). Datetimes are sent as whole-second UTC with
+  `Z`, like every other write; a naive datetime is taken as UTC.
+- **Behavior change. SDK: delete results.** A delete whose response has no `success` key (an empty
+  body) returns `True`; only an explicit `"success": false` returns `False`.
+- SDK: `get_all_pages` raises `AffinityError` when it stops at `max_pages` with pages left,
+  instead of returning (and caching) a cut-off result.
+- SDK: company and person merges raise `AffinityError` when the response has no `taskUrl`,
+  instead of returning an empty URL.
+- SDK: the sync client rejects an `async` hook with `ConfigurationError` at construction; under
+  `hook_error_policy="swallow"` it was logged and never ran.
+- SDK: followed pagination URLs must match the exact host and port of the V1 or V2 base URL.
+- SDK: the response cache key includes the per-call API version sent.
+- SDK: `tasks.wait` no longer sleeps past its `timeout`.
+- SDK: `lists.resolve` no longer remembers a name it didn't find, so a list created later is found.
+- SDK: `lists.get_size` is shared by every list service on a client and dropped when an entry is
+  added or removed, an opportunity is created or deleted, or a person or company is deleted.
+- SDK: paging stops when a cursor repeats, when a page says more follow but gives no cursor, or
+  after 1,000 empty pages in a row (with a `RuntimeWarning`), instead of looping. This covers the
+  page iterators (`iter()`, `all()`) and the `pages()` generators of companies, persons,
+  opportunities, lists, saved views and list entries (filtered reads included), sync and async.
+- SDK: association paging tolerates `"pagination": null`.
+- SDK filters: `in`, `has_any` and `has_all` compare values the way `=` does, so `score in [5, 6]`
+  matches the number 5.
+- SDK models: `FieldId(True)`, `FieldValueType(True)` and fractional floats for open enums raise
+  `ValueError`; a fractional float no longer replaces a known enum member for the rest of the
+  process. `FieldValues.get` accepts bare-digit ids (`123`, `"123"`). Person and opportunity
+  company ids also read `companyIds` and `current_organization_ids`; `Location` reads
+  `streetAddress`; V2 list entries pick the entity model from `type`.
+- **CLI `query`: resuming a cut-off result no longer skips rows.** The resume cursor jumped to
+  the next API page, losing the rest of the current page and every fetched row that didn't fit in
+  `--max-output-bytes`. A cut-off result, with its included records, is now cached and the
+  cursor resumes from it without API calls; each page's `included` holds only the records related
+  to that page's rows, also when `select` leaves out `id` (TOON pages hold as many rows as fit,
+  with matching counts; related records that can't be matched to rows are cut to the budget and
+  counted in `includedOmitted`). A cursor needs the same `--max-records` as the first run; a cursor from an
+  earlier version is refused as not matching the query (cursors expire after an hour).
+- **Behavior change. CLI `query`: errors are no longer read as "no data".** A rate-limit, server or
+  auth error while fetching related records (for `include`, relationship filters, or an id
+  lookup, or `include: interactions`), an expansion (`interactionDates`, `unreplied`, person
+  names) or a list's field definitions (when the query uses a list field) fails the query. Before,
+  the record silently had no related records, an id-only stub or an empty expansion, so `none`,
+  `all` and `_count eq 0` filters could match wrongly. Only a deleted or merged record counts as
+  empty.
+- **Behavior change. CLI `query`: `--max-records`.** When results are cut at it, a warning says
+  so and `meta.truncated` is set, on every path (before, the cut was silent); with `orderBy` or
+  an aggregate the cut comes after sorting and aggregating (also when the query has no `where`), so counts, sums, groups and top-N use
+  every match. Before, they were computed on the first 10,000.
+- **Behavior change. CLI `query`: Ctrl+C exits 130** (exit 0 before). Rows that already went
+  through the query's filter, sort and aggregate are printed; when one of those hadn't run yet, no
+  rows are printed (before, unfiltered rows were) and the error type is `interrupted`. On Python
+  3.10, Ctrl+C prints no rows (it still exits 130); Python 3.11+ prints them.
+- **Behavior change. CLI `query`:** a `listName` that matches more than one list, or none, is a
+  validation error (exit 2) asking for the list id; before, the last list with that name was
+  used. An include's `list:` name that matches several lists fails (exit 2,
+  `ambiguous_resolution`) and one that matches none is not found (exit 4); before, the scope was
+  dropped. `min`/`max` over objects,
+  lists, or a mix of numbers and text is a validation error instead of a crash or a silent pick.
+- CLI `query`: with `orderBy` or `limit`, `include` (and an `expand` the sort doesn't read) runs
+  on the rows kept after sorting, limiting and `--max-records`, not on every match, so a top-N
+  query makes one call per kept row.
+- CLI `query`: an Affinity error exits with the CLI's documented code (3 auth, 4 not found, 5
+  rate limit or server error) and its usual error envelope, instead of exit 1 with "Query
+  execution failed".
+- CLI `query`: CSV output with `--max-output-bytes` cuts on whole records (a note with a line
+  break could be split), has every row's columns, honors `--csv-bom` and can be resumed; JSONL
+  resume no longer skips rows whose data contains `"truncated"`. A row larger than
+  `--max-output-bytes` is printed whole (JSON too, which exited 1 partway through paging) instead
+  of giving an empty page whose cursor repeats.
+- CLI `query`: `include` options are applied: `list`, `where`, `limit` and `days` on a
+  `listEntries` include, and `limit` and `days` on an `interactions` include. Before, they were
+  ignored, so related opportunities came from every list and interactions used the default 90-day
+  window and 100-record limit.
+- CLI `query`: a relationship filter on `interactions` (`interactions._count`,
+  `exists`/`all`/`none`) no longer hangs when the query has at least as many records as the
+  concurrency limit (10).
+- CLI `query`: when fetching related records for a `listEntries` include fails, the other fetches
+  are stopped instead of continuing to call the API and printing "Task exception was never
+  retrieved".
+- CLI `query --output toon`: a cut-off page, its `cursor:` line included, stays within
+  `--max-output-bytes` (if the cursor alone, about 500 bytes, doesn't fit, one row is shown).
+- **Behavior change. CLI `query --output csv`:** without `--max-output-bytes`, execution warnings
+  (the `--max-records` cut, multi-value fields cut off) go to stderr as with the other formats,
+  and the CSV has the same shape as with a budget: columns in `select` order (first-seen order
+  without `select`; they were sorted alphabetically), selected `fields.*` and expanded
+  `interactionDates` flattened into columns, and every record ending with CRLF.
+- CLI `query`: `groupBy` on object values (such as a location) works; formula fields filter and
+  sort as numbers.
+- **Behavior change. CLI: a delete Affinity reports as failed exits 1** (`api_error`) instead of
+  printing `"success": false` with exit 0.
+- **Behavior change. CLI `field history-bulk`:** when every entry fails it exits with the usual
+  code for that error (3 auth, 4 not found, 5 rate limit or server; 1 for mixed errors), and 3 on
+  any auth error (all exited 0). Partial failures still exit 0 with warnings and now set
+  `meta.truncated` with `truncationReason: "partialFailure"`.
+- **Behavior change. CLI `list export` expansions:** a failed interaction, opportunity or
+  unreplied-message lookup fails the export under the default `--expand-on-error raise` (it was
+  left empty silently), and warns under `skip`, keeping the entry's other expansions. An auth
+  error during any expansion fails the export; a deleted opportunity is left out. With `--csv`
+  these warnings, and the export's other warnings (such as "Filtering locally"), are printed to
+  stderr; they were dropped.
+- **Behavior change. CLI `--page-size` below 1** is a usage error (exit 2) on `company`,
+  `person`, `opportunity`, `list`, `note`, `interaction` and `reminder ls`, `list export` and
+  `files download`. With the SDK's new `limit` check it was an `internal_error` (exit 1) on most
+  of them, and `note ls` and `interaction ls` accepted it. `--help --json` (and the MCP command
+  registry) reports such range-checked options, including `search --max-results` and
+  `files ls --max-results`, as `int`; they were `string`.
+- **Behavior change. CLI field writes:** `true`/`false` anywhere in a `--set-json` value (including
+  list items and object values) is refused before any write (exit 2, `validation_error`);
+  Affinity has no boolean field type. A text field no longer stores `true` as `"true"`.
+- CLI `list entry field --unset-value` exits 1 when Affinity reports the delete failed, instead of
+  reporting the value as deleted. When an `--unset-value` or `--append` step fails after something
+  was already changed, the error is `partial_write` naming every field written and value removed;
+  a step that timed out or lost the connection is named as "may or may not have been applied"
+  (`details.uncertain`), and alone it is a `network_error` that says re-running is safe; `field delete` clears its caches only after a confirmed delete.
+- CLI: answering "n" to a confirmation under `--json` prints an error envelope (type `aborted`),
+  still exit 1, instead of an empty stdout.
+- CLI `list ls --type`: warns when the first page has no list of that type but more pages exist.
+
+### Plugins
+
+- **CLI plugin**: 2.0.2 → 2.0.3 — skill: the API-key resolution order (key flags first) and
+  where `config setup-key` stores the key. Installs pin the CLI version the plugin was written
+  for (`XAFFINITY_CLI_SPEC` overrides it); the Read hook also guards the CLI's `config.toml`;
+  the skill names the `partialFailure` truncation reason; the file download example uses `--out`
+  (there is no `--output-dir`).
+- **SDK plugin**: 2.0.3 → 2.0.4 — skill: the duplicate-company example uses a placeholder name.
+
+## [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
 

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

@@ -1,6 +1,6 @@
 Metadata-Version: 2.5
 Name: affinity-sdk
-Version: 2.0.2
+Version: 2.0.4
 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/
@@ -106,7 +106,7 @@ For a detailed comparison, see [Affinity SDK vs. Official MCP](https://yaniv-gol
 
 ## Features
 
-- **Complete API coverage** - Full V1 + V2 support with smart routing
+- **Broad API coverage** - V1 and V2, routed per operation (6 V2 operations still planned)
 - **CLI included** - Scriptable command-line interface for automation
 - **Strong typing** - Full Pydantic V2 models with typed ID classes
 - **No magic numbers** - Comprehensive enums for all API constants
@@ -539,45 +539,50 @@ from affinity.types import (
 
 ## API Coverage
 
-Which Affinity API version offers each feature, and which one the SDK uses. Affinity has been
-adding V2 endpoints through 2026; the SDK still uses V1 where V1 was the only option, and moving
-those to V2 is planned.
-
-| Feature | V2 | V1 | SDK uses |
-|---------|:--:|:--:|:---:|
-| Companies (read) | ✅ | ✅ | V2 |
-| Companies (write) | Fields only (no create/delete) | ✅ | V1 |
-| Persons (read) | ✅ | ✅ | V2 |
-| Persons (write) | Create, delete, fields | ✅ | V1 |
-| Company/person merges | ✅ | ❌ | V2 |
-| Opportunities (read) | ✅ | ✅ | V2 |
-| Opportunities (write) | Update/delete | ✅ | V1 |
-| Lists (read) | ✅ | ✅ | V2 |
-| Lists (write) | Create | ✅ | V1 |
-| List Entries (read) | ✅ | ✅ | V2 |
-| List Entries (write) | Create | ✅ | V1 |
-| Field Values (read) | ✅ | ✅ | V2 |
-| Field Values (write) | ✅ | ✅ | V2 (list entries), V1 (companies/persons) |
-| Notes | ✅ | ✅ | V1 reads; V2 writes |
-| Reminders | ✅ | ✅ | V2 (V1 for type changes, and when V2 refuses a non-owner) |
-| Webhooks | ✅ | ✅ | V2 |
-| Interactions | Read-only | ✅ | V1 |
-| Entity Files | Read-only | ✅ | V1 |
-| Relationship Strengths | ✅ | ✅ | V1 |
-
-V2-only features the SDK does not wrap yet include semantic search, transcripts, duplicate
-suggestions, coworker/investor connections and teams.
+Which Affinity API the SDK uses for each feature. The SDK uses V2 wherever V2 can do the job and
+V1 where it can't. The [API coverage](https://yaniv-golan.github.io/affinity-sdk/latest/reference/api-coverage/)
+page lists every operation and the SDK call that sends it.
+
+| Feature | SDK uses |
+|---------|:---:|
+| Companies, persons, opportunities (read, search) | V2 |
+| Companies, persons (create, update, delete) | V1 (V2 has no create/update; person create/delete are planned) |
+| Opportunities (create, update, delete) | V1 (V2 update/delete are planned) |
+| Company/person merges | V2 |
+| Lists, list entries (read) | V2 |
+| Lists (create) | V2 (V1 when `owner_id` or `additional_permissions` is set) |
+| List entries (add, delete) | V1 (V2 add is planned) |
+| Field values (read and write, on companies, persons and list entries) | V2 |
+| Fields (create, delete); the `field_values` service | V1 |
+| Notes | V2, except `notes.list()` for one entity (V1) |
+| Reminders | V2 (V1 for type changes, and when V2 refuses a non-owner) |
+| Webhooks | V2 |
+| Interactions | V2 reads by type (emails, meetings, calls, chat messages); V1 `list`/`get` and writes |
+| Entity files | V1 list, get and upload; V2 feed and download URL |
+| Relationship strengths | V1 `relationships.get`; V2 `list_relationships` on companies/persons |
+| Transcripts, teams, users, semantic search, duplicate suggestions, coworker/investor connections | V2 |
+
+Still planned (Affinity documents them, but the API didn't serve them when tested): V2 person
+create/delete, opportunity update/delete, list-entry create, and transcript delete.
 
 ## Authentication
 
-The SDK resolves the API key through the following chain (first non-empty value wins):
+The SDK and CLI resolve the API key through the following chain (first non-empty value wins):
 
-1. **Explicit constructor arg** — `Affinity(api_key="…")` or `--api-key` CLI flag
+1. **The key you pass explicitly** — `Affinity(api_key="…")` in the SDK; `--api-key-file <path>`
+   or `--api-key-stdin` in the CLI (the CLI has no `--api-key` flag)
 2. **`AFFINITY_API_KEY`** — standard environment variable
 3. **`AFFINITY_API_KEY_FILE`** — path to a file containing the key (12-factor / Docker secrets convention)
 4. **`AFFINITY_API_KEY_COMMAND`** — shell command whose stdout is the key (credential-helper convention)
-5. **`--api-key-file <path>`** or **`--api-key-stdin`** — CLI flags
-6. **`xaffinity config setup-key`** — saved to the system keychain
+5. **User config file** — `api_key` in `config.toml`, written by `xaffinity config setup-key --scope user`
+   (file mode `0600` on Unix; `xaffinity config path` prints the location). CLI only.
+
+The SDK uses steps 1–4; step 5 is CLI only. When the CLI uses a key flag while
+`AFFINITY_API_KEY`, `AFFINITY_API_KEY_FILE` or `AFFINITY_API_KEY_COMMAND` is also set, it warns
+that those are ignored (the file is not read and the command is not run). With `load_dotenv=True` (SDK) or `--dotenv` (CLI),
+a `.env` file is loaded into the environment before step 2, so its `AFFINITY_API_KEY` counts as
+step 2. That is how a key saved by `xaffinity config setup-key --scope project` (a `.env` in the
+current directory) is used: run commands with `--dotenv`.
 
 Empty string is treated as unset at every step (safe against stale `export AFFINITY_API_KEY=` lines).
 
@@ -651,7 +656,7 @@ client = Affinity(
     # Affinity V2 API version (default: your API key's default version)
     # affinity_api_version="2026-09-17",   # or "current"; CLI: --api-version / AFFINITY_API_VERSION
 
-    # Hooks (DX-008)
+    # Hooks
     # on_event=lambda event: print(event.type),
     # on_request=lambda req: print(req.method, req.url),
     # on_response=lambda resp: print(resp.status_code, resp.request.url),
@@ -712,7 +717,7 @@ asyncio.run(main())
 
 Async support mirrors the sync client surface area (including the V1 services like notes and files).
 
-See `docs/public/guides/sync-vs-async.md` for more details.
+See [Sync vs async](https://yaniv-golan.github.io/affinity-sdk/latest/guides/sync-vs-async/) for more details.
 
 If you don't use `async with`, make sure to `await client.close()` (e.g., in a `finally`) to avoid leaking connections.
 
@@ -742,7 +747,7 @@ MIT License - see [LICENSE](LICENSE) for details.
 
 ## Contributing
 
-Contributions welcome! Please read our contributing guidelines first.
+Contributions welcome! Please read the [contributing guidelines](https://github.com/yaniv-golan/affinity-sdk/blob/main/CONTRIBUTING.md) first.
 
 ## Links
 

{affinity_sdk-2.0.2 → affinity_sdk-2.0.4}/README.md

@@ -45,7 +45,7 @@ For a detailed comparison, see [Affinity SDK vs. Official MCP](https://yaniv-gol
 
 ## Features
 
-- **Complete API coverage** - Full V1 + V2 support with smart routing
+- **Broad API coverage** - V1 and V2, routed per operation (6 V2 operations still planned)
 - **CLI included** - Scriptable command-line interface for automation
 - **Strong typing** - Full Pydantic V2 models with typed ID classes
 - **No magic numbers** - Comprehensive enums for all API constants
@@ -478,45 +478,50 @@ from affinity.types import (
 
 ## API Coverage
 
-Which Affinity API version offers each feature, and which one the SDK uses. Affinity has been
-adding V2 endpoints through 2026; the SDK still uses V1 where V1 was the only option, and moving
-those to V2 is planned.
-
-| Feature | V2 | V1 | SDK uses |
-|---------|:--:|:--:|:---:|
-| Companies (read) | ✅ | ✅ | V2 |
-| Companies (write) | Fields only (no create/delete) | ✅ | V1 |
-| Persons (read) | ✅ | ✅ | V2 |
-| Persons (write) | Create, delete, fields | ✅ | V1 |
-| Company/person merges | ✅ | ❌ | V2 |
-| Opportunities (read) | ✅ | ✅ | V2 |
-| Opportunities (write) | Update/delete | ✅ | V1 |
-| Lists (read) | ✅ | ✅ | V2 |
-| Lists (write) | Create | ✅ | V1 |
-| List Entries (read) | ✅ | ✅ | V2 |
-| List Entries (write) | Create | ✅ | V1 |
-| Field Values (read) | ✅ | ✅ | V2 |
-| Field Values (write) | ✅ | ✅ | V2 (list entries), V1 (companies/persons) |
-| Notes | ✅ | ✅ | V1 reads; V2 writes |
-| Reminders | ✅ | ✅ | V2 (V1 for type changes, and when V2 refuses a non-owner) |
-| Webhooks | ✅ | ✅ | V2 |
-| Interactions | Read-only | ✅ | V1 |
-| Entity Files | Read-only | ✅ | V1 |
-| Relationship Strengths | ✅ | ✅ | V1 |
-
-V2-only features the SDK does not wrap yet include semantic search, transcripts, duplicate
-suggestions, coworker/investor connections and teams.
+Which Affinity API the SDK uses for each feature. The SDK uses V2 wherever V2 can do the job and
+V1 where it can't. The [API coverage](https://yaniv-golan.github.io/affinity-sdk/latest/reference/api-coverage/)
+page lists every operation and the SDK call that sends it.
+
+| Feature | SDK uses |
+|---------|:---:|
+| Companies, persons, opportunities (read, search) | V2 |
+| Companies, persons (create, update, delete) | V1 (V2 has no create/update; person create/delete are planned) |
+| Opportunities (create, update, delete) | V1 (V2 update/delete are planned) |
+| Company/person merges | V2 |
+| Lists, list entries (read) | V2 |
+| Lists (create) | V2 (V1 when `owner_id` or `additional_permissions` is set) |
+| List entries (add, delete) | V1 (V2 add is planned) |
+| Field values (read and write, on companies, persons and list entries) | V2 |
+| Fields (create, delete); the `field_values` service | V1 |
+| Notes | V2, except `notes.list()` for one entity (V1) |
+| Reminders | V2 (V1 for type changes, and when V2 refuses a non-owner) |
+| Webhooks | V2 |
+| Interactions | V2 reads by type (emails, meetings, calls, chat messages); V1 `list`/`get` and writes |
+| Entity files | V1 list, get and upload; V2 feed and download URL |
+| Relationship strengths | V1 `relationships.get`; V2 `list_relationships` on companies/persons |
+| Transcripts, teams, users, semantic search, duplicate suggestions, coworker/investor connections | V2 |
+
+Still planned (Affinity documents them, but the API didn't serve them when tested): V2 person
+create/delete, opportunity update/delete, list-entry create, and transcript delete.
 
 ## Authentication
 
-The SDK resolves the API key through the following chain (first non-empty value wins):
+The SDK and CLI resolve the API key through the following chain (first non-empty value wins):
 
-1. **Explicit constructor arg** — `Affinity(api_key="…")` or `--api-key` CLI flag
+1. **The key you pass explicitly** — `Affinity(api_key="…")` in the SDK; `--api-key-file <path>`
+   or `--api-key-stdin` in the CLI (the CLI has no `--api-key` flag)
 2. **`AFFINITY_API_KEY`** — standard environment variable
 3. **`AFFINITY_API_KEY_FILE`** — path to a file containing the key (12-factor / Docker secrets convention)
 4. **`AFFINITY_API_KEY_COMMAND`** — shell command whose stdout is the key (credential-helper convention)
-5. **`--api-key-file <path>`** or **`--api-key-stdin`** — CLI flags
-6. **`xaffinity config setup-key`** — saved to the system keychain
+5. **User config file** — `api_key` in `config.toml`, written by `xaffinity config setup-key --scope user`
+   (file mode `0600` on Unix; `xaffinity config path` prints the location). CLI only.
+
+The SDK uses steps 1–4; step 5 is CLI only. When the CLI uses a key flag while
+`AFFINITY_API_KEY`, `AFFINITY_API_KEY_FILE` or `AFFINITY_API_KEY_COMMAND` is also set, it warns
+that those are ignored (the file is not read and the command is not run). With `load_dotenv=True` (SDK) or `--dotenv` (CLI),
+a `.env` file is loaded into the environment before step 2, so its `AFFINITY_API_KEY` counts as
+step 2. That is how a key saved by `xaffinity config setup-key --scope project` (a `.env` in the
+current directory) is used: run commands with `--dotenv`.
 
 Empty string is treated as unset at every step (safe against stale `export AFFINITY_API_KEY=` lines).
 
@@ -590,7 +595,7 @@ client = Affinity(
     # Affinity V2 API version (default: your API key's default version)
     # affinity_api_version="2026-09-17",   # or "current"; CLI: --api-version / AFFINITY_API_VERSION
 
-    # Hooks (DX-008)
+    # Hooks
     # on_event=lambda event: print(event.type),
     # on_request=lambda req: print(req.method, req.url),
     # on_response=lambda resp: print(resp.status_code, resp.request.url),
@@ -651,7 +656,7 @@ asyncio.run(main())
 
 Async support mirrors the sync client surface area (including the V1 services like notes and files).
 
-See `docs/public/guides/sync-vs-async.md` for more details.
+See [Sync vs async](https://yaniv-golan.github.io/affinity-sdk/latest/guides/sync-vs-async/) for more details.
 
 If you don't use `async with`, make sure to `await client.close()` (e.g., in a `finally`) to avoid leaking connections.
 
@@ -681,7 +686,7 @@ MIT License - see [LICENSE](LICENSE) for details.
 
 ## Contributing
 
-Contributions welcome! Please read our contributing guidelines first.
+Contributions welcome! Please read the [contributing guidelines](https://github.com/yaniv-golan/affinity-sdk/blob/main/CONTRIBUTING.md) first.
 
 ## Links
 

{affinity_sdk-2.0.2 → affinity_sdk-2.0.4}/VERSIONING.md

@@ -1,6 +1,6 @@
 # Versioning Policy
 
-This document defines how versions are managed across the affinity-api-x repository.
+This document defines how versions are managed across the affinity-sdk repository.
 
 ## Overview
 
@@ -81,15 +81,16 @@ have valid JSON but does not enforce version sync.
 - Plugin cache invalidation is based on git commit hash, not version number,
   so version bumps are for human traceability, not distribution mechanics
 
-## Since 1.0 (Current State)
+## Current State (2.x)
 
-**The SDK has been at 1.x since 1.0.0**, so the rules above apply: a breaking change to the
-public SDK or CLI means a MAJOR bump, and PATCH releases stay backwards-compatible.
+The SDK and CLI are at 2.x. The rules above are the default: a breaking change to the public
+SDK or CLI means a MAJOR bump.
 
-- An exception (a breaking change shipped in a MINOR) is a deliberate decision, never a default.
-  The CHANGELOG entry must say it is an exception and why, and the release's Highlights must
-  carry a **Breaking:** line with a migration hint. Example: 1.20 removes
-  `get_fields(field_types=)`, which the API never supported.
+- **Exceptions in 2.x:** the maintainer may ship a breaking change in a 2.0.x PATCH instead of a
+  new MAJOR (2.0.1, 2.0.2 and 2.0.3 did). This is the maintainer's decision for each release,
+  never a default. The CHANGELOG entry must open with **Exception to semantic versioning**,
+  say why, and list exactly what changes and how to migrate.
+- MCP and the plugins whose content changed are bumped to the same version in that release.
 - MCP must track CLI minor version for compatibility
 
 ## CLI Changes That Affect MCP
@@ -117,7 +118,7 @@ The release detection workflow compares the current version in version files aga
 1. **After CI passes** on `main`, the release detection workflow runs
 2. It reads the SDK version from `pyproject.toml` and MCP version from `mcp/VERSION`
 3. It checks if release tags exist:
-   - SDK: checks for `v{version}` tag (e.g., `v0.9.2`)
+   - SDK: checks for `v{version}` tag (e.g., `v2.0.3`)
    - MCP: checks for `mcp-v{version}` tag (e.g., `mcp-v1.7.6`)
 4. If no tag exists for the current version, it triggers the release workflow via `workflow_dispatch` API
 
@@ -140,6 +141,16 @@ This approach is robust regardless of how many commits are pushed together, squa
 
 SDK releases include MCPB bundles (built from the same commit) for convenience, so users don't need to find separate MCP releases.
 
+**CLI pin in the CLI plugin.** The xaffinity-cli plugin installs an exact CLI version
+(`affinity-sdk[cli]==X.Y.Z` in `hooks/session-setup.sh`, `hooks/pre-xaffinity.sh` and the skill's
+install lines). It always equals `pyproject.toml`'s version, and
+`tests/test_cli_session_setup_hook.py` fails until it does. So the version bump in step 1 also
+updates the pin. That is a plugin content change, so it bumps the CLI plugin's patch version.
+Plugin users get the new pin as soon as `main` is pushed, while PyPI gets the version only when
+the release workflow finishes. In between, a fresh install asks pip for a version that doesn't
+exist yet and fails. Machines with the CLI already installed are not affected. Don't push
+anything else on top of a version bump until the release workflow is green.
+
 ### MCP Release
 
 1. Update `mcp/VERSION`
@@ -260,7 +271,7 @@ the release notes lack context.
 ## Release Checklist
 
 ### SDK Release
-- [ ] Version bumped in `pyproject.toml`
+- [ ] Version bumped in `pyproject.toml`, and the CLI plugin's install pin with it (bump the CLI plugin patch version)
 - [ ] If plugin content also changed: plugin versions bumped in their `plugin.json` files
 - [ ] Pre-commit ran
 - [ ] `CHANGELOG.md` updated with `### Highlights` and categorized changes

{affinity_sdk-2.0.2 → affinity_sdk-2.0.4}/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.4/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.
+"""