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

{affinity_sdk-1.29.0 → affinity_sdk-2.0.1}/.github/workflows/ci.yml

@@ -224,6 +224,9 @@ jobs:
             echo "Skipping traceability mapping (docs/internal not present in repo checkout)."
           fi
 
+      - name: API coverage ledger matches the pinned specs
+        run: python tools/api_coverage.py --check
+
       - name: MCP commands registry is valid
         run: |
           # Verify registry file exists and is valid JSON with expected structure

{affinity_sdk-1.29.0 → affinity_sdk-2.0.1}/.github/workflows/plugin-build.yml

@@ -40,6 +40,19 @@ jobs:
         # Uses the full mcp-bash installed above; the vendored runtime has no validate.
         run: ./mcp/xaffinity-mcp.sh validate
 
+      - uses: actions/setup-python@v6
+        with:
+          python-version: '3.12'
+
+      - name: Install the CLI from this checkout
+        run: python -m pip install -e ".[cli]"
+
+      - name: MCP tool tests (dry runs; no key, API unreachable)
+        env:
+          AFFINITY_V1_BASE_URL: http://127.0.0.1:9
+          AFFINITY_V2_BASE_URL: http://127.0.0.1:9/v2
+        run: ./mcp/test/run.sh
+
       - name: Build MCP plugin ZIP
         run: make -C mcp plugin
 

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

@@ -7,6 +7,172 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 ## [Unreleased]
 
+## [2.0.1] - 2026-10-12
+
+### Changed (breaking)
+
+**Exception to semantic versioning:** these renames break code written against 2.0.0, in a
+patch release. 2.0.0 had been out for under an hour, and the renames remove method names that
+said which Affinity API they used instead of what they do.
+
+- `notes.list_v2()` / `iter_v2()` → **`notes.feed()` / `iter_feed()`** (every note across the
+  organization; the CLI's `note feed`).
+- `notes.get_v2()` → **`notes.get()`**, which now returns `NoteV2` (`includes=True` adds the
+  attached companies, persons and opportunities). The V1 `notes.get()` (returning `Note`) is
+  removed; `notes.list()` (one entity's notes, V1) is unchanged.
+- `files.list_v2()` / `iter_v2()` → **`files.feed()` / `iter_feed()`** (every file you can see,
+  newest first).
+- `files.get_v2()` is removed. **`files.get_download_url()`** now asks V2 first: one request
+  for the details and a signed URL (valid 60 seconds) instead of V1's two. It falls back to
+  V1 when the client is pinned to an API version older than 2026-09-17, or when V2 refuses or
+  doesn't find the file; the result (`PresignedUrl`) is the same either way. `files.get()`
+  stays on V1 (`EntityFile`, with the file's person, company or opportunity) and works under
+  any version pin.
+- CLI `note get` reads the note from V2: same output keys, `content` is the stored HTML (as in
+  `note create`/`update` output), and the attachment ids come from V2.
+- CLI `files read` and `file-url` get the file's details and URL in one request where V2 can
+  answer (V1's path otherwise).
+
+### Plugins
+
+- **SDK plugin**: 2.0.0 → 2.0.1 — skill: the renamed note methods.
+
+## [2.0.0] - 2026-10-12
+
+### Highlights
+
+**SDK 2.0 moves to Affinity's V2 API wherever V2 can do the job.** Webhooks, reminders, note
+writes, list get/create, file reads (new `files.get_v2`/`list_v2`) and the rate-limit endpoint
+now use V2; the CLI gains `xaffinity webhook ls|get|create|update|delete`. V1 stays only where
+V2 can't do it, and for person create/delete, opportunity rename/delete and adding to a list,
+which the V2 spec documents but the API didn't serve when tested. **Breaking:** webhook and
+reminder models change shape, note writes return `NoteV2`, `add_opportunity()` is removed, and
+operations added in newer Affinity API versions refuse a client pinned to an older one
+(`ApiVersionTooOldError`). See the [Migrating to 2.0](https://yaniv-golan.github.io/affinity-sdk/latest/guides/migrating-to-2/)
+guide.
+
+### Changed (breaking)
+
+- **Webhooks use the V2 API** (`/v2/webhooks`, Affinity API 2026-07-15 or later, beta).
+  `WebhookSubscription` is now `Webhook`: `webhook_url` → `url`, `disabled` →
+  `status` (`WebhookStatus.ACTIVE`/`DISABLED`), `created_by` → `creator` (`PersonRef`), plus
+  `created_at`/`updated_at`. `WebhookCreate(url=…, subscriptions=[…])` requires `subscriptions`
+  (`[]` = every event type). `WebhookUpdate` takes `url`, `subscriptions`, `status` and sends
+  only what is set. `list()` returns one page (`ids`, created/updated ranges, `limit`,
+  `cursor`); `iter()` returns every webhook. `update()` returns the webhook as read back (two
+  requests); `delete()` returns `None`. 1.x field names raise `ValidationError` instead of being
+  ignored. Without permission to manage all webhooks, the API lists, reads and changes only the
+  caller's own webhooks. A client pinned to API version 2024-01-01 gets
+  `ApiVersionTooOldError`.
+- **Reminders use the V2 API** (`/v2/reminders`; `get`/`delete` need API 2026-07-15, `update`
+  2026-09-17). `Reminder` has the V2 shape: `creator`, `owner`, `completer`, `person` are
+  `PersonRef` (id only; look names up separately), `company`/`opportunity` are
+  `CompanyRef`/`OpportunityRef`, recurrence is `recurrence` (`period_days`, `reset_type`; the
+  read-only `reset_type`/`reminder_days` properties still work), plus `updated_at`.
+  `ReminderType`, `ReminderResetType` and `ReminderStatus` are string enums with the V2 values
+  (member names unchanged; the 1.x integers are still accepted); `ReminderResetType.MEETING` is
+  now an alias of `EVENT`. `list()` takes `limit` (1-100), `cursor`, `ids` and created/updated
+  ranges instead of `page_size`/`page_token`, and returns reminders soonest-due first.
+  `update()` sends only the fields that are set (`clear_content=True` removes the content) and
+  returns the reminder as read back. `list_batch()` is on the sync client too, and fetches up to
+  50 entities per request. Kept on V1 where V2 can't do it: changing a reminder's type, and updating or deleting a
+  reminder you didn't create and don't own (V2 refuses; the SDK retries through V1). A reminder
+  must be attached to one person, company or opportunity (both APIs require it; the SDK now
+  says so before sending).
+- **Note writes use the V2 API** (`notes.create`, `update`, `delete`; reads are unchanged).
+  `create()` and `update()` return `NoteV2` (`content.html`, `creator`; `update()` reads the note
+  back with its attachments, two requests). V2 stores notes as HTML: plain text (the default
+  `type`) is escaped and wrapped in paragraphs, and `NoteUpdate` takes `type` too (plain text
+  unless set to `HTML`, whatever the note was before). With `type=NoteType.HTML`, `<b>`/`<i>`
+  become `<strong>`/`<em>`, and what the API rejects (style/class attributes, img, pre, code,
+  blockquote, mention spans, non-http(s)/mailto links) raises `ValueError` naming the allowed
+  tags. A reply (`parent_id`) with persons/companies/opportunities raises instead of ignoring
+  them; `AI_NOTETAKER`/`EMAIL_DERIVED` can't be created. `NoteUpdate` can replace a note's
+  persons, companies and opportunities (`[]` clears). Changing the text of a note that
+  @mentions people is refused by the API; the error now says so. `NoteV2` and `NoteContent`
+  are exported from `affinity.models`.
+- **`rate_limits.refresh()` reads `GET /v2/rate-limit`** (API 2026-07-15+), falling back to
+  response headers as before (now also when the client is pinned to an older API version).
+  `RateLimitSnapshot` is unchanged; `RateLimits` also reads the V2 names (`callerPerMinute`,
+  `orgPerMonth`).
+- **Lists: `get()` and `create()` use the V2 API.** `get()` no longer fills `fields` (use
+  `get_fields()`) or `additional_permissions`; it sets `created_at`. `get_size()` still reads
+  the size from V1 (V2 has none). `create()` makes the caller the owner; a public list needs the
+  "Share accessible Lists globally" permission. A list created with `owner_id` or
+  `additional_permissions` still goes through V1.
+- **`entries(list_id).add_opportunity()` is removed.** Opportunities can't be added to a list
+  as entries: create them on their list with `opportunities.create(OpportunityCreate(list_id=...))`.
+- Person create/delete, opportunity rename/delete and adding to a list stay on V1: the V2 spec
+  documents them, but Affinity didn't serve them when tested (2026-10-12).
+
+### Added
+
+- **`files.get_v2()`, `files.list_v2()`, `files.iter_v2()`** (V2, Affinity API 2026-09-17+):
+  a file's metadata with a download URL that expires after 60 seconds, and every file visible to
+  you across the organization, newest first (filter by created date and uploader). `FileV2`
+  model. `files.get/list/iter` stay on V1: only V1 lists one entity's files.
+- **CLI `webhook ls|get|create|update|delete`.** `create` takes `--url` and `--event`
+  (repeatable) or `--all-events`; `update` takes `--url`, `--event`/`--all-events`, `--status
+  active|disabled`. `create`, `update` and `delete` ask for confirmation (`--yes` in scripts),
+  since a webhook sends CRM events to an outside URL. Rows include `allEvents`.
+- **CLI `list get <id>`** no longer prints `.data.list.fields` (the fields are in `.data.fields`
+  as before), `additionalPermissions` is always `[]`, and `createdAt` is added; `list create
+  --owner-id` creates the list through V1.
+- **CLI `reminder create/update --reminder-days`** help now says what it is: the days between a
+  recurring reminder's due dates.
+- **CLI `note update --type plain-text|html`**; `note create --type` is now plain-text or html
+  (Affinity creates the other kinds itself). `note create`/`update` output keeps the `note get`
+  keys (`type` is `html`; content is the stored HTML). The duplicate-note warning still finds
+  an earlier copy: V1 shows notes stored as HTML in a markdown form, which the check allows for.
+- **CLI `reminder update --clear-content`**; `reminder ls --page-size` is now at most 100, and
+  rows include `updatedAt`; `--reset-type event` (`meeting` still accepted, printed as `event`).
+- **MCP:** the webhook commands are in the command registry; `webhook create`/`update`/`delete`
+  go through the same user confirmation as deletes, and the confirmation says why (events sent
+  to an outside URL).
+
+### Fixed
+
+- `Person.company_ids` and `Opportunity.company_ids` are now read from V1 responses
+  (`organization_ids`), e.g. from `persons.create()` with companies, `persons.update()`,
+  `opportunities.update()` and `get_details()`; they were always empty.
+
+### Docs
+
+- New **API coverage** reference page: every Affinity API operation (V2 and V1) and how the SDK
+  supports it — the SDK call, an equivalent operation, or the planned release — with beta
+  operations and the minimum API version marked.
+
+### Internal
+
+- `tools/api_coverage.py` and the ledger `tools/api_coverage.json` (CI: `--check`): every
+  operation in the pinned V2 snapshots and the new V1 snapshot (`tools/api_coverage_v1_snapshot.json`,
+  59 operations) has exactly one row. `tests/test_api_coverage.py` runs each supported row's call,
+  sync and async, against a recording HTTP layer and checks the method, path and API version it
+  requests.
+
+### Plugins
+
+- **SDK plugin**: 1.7.1 → 2.0.0 (matches SDK 2.0) — skill: note writes go through V2 (HTML, the
+  allowed tags), and `add_opportunity()` is gone (create the opportunity on its list).
+- **CLI plugin**: 1.13.6 → 2.0.0 (matches CLI 2.0; no content change).
+- **MCP**: 1.32.2 → 2.0.0 (requires CLI 2.0.0; see `mcp/CHANGELOG.md`).
+- **CLI plugin**: 1.13.5 → 1.13.6 — skill: the Cowork install line adds
+  `--no-warn-script-location` (pip's "not on PATH" warning was noise; the skill adds the folder to
+  PATH in each call), and the Cowork key paths (`--env-file`, `AFFINITY_API_KEY_FILE`) are quoted,
+  so connected folders with spaces in their names work.
+- **CLI plugin**: 1.13.4 → 1.13.5 — no `clis` credential declaration. In local Cowork it routed
+  every `xaffinity` call through Desktop's CLI credential broker, which isn't enabled yet and
+  refuses the call ("cli-wrapper: plugin oauth disabled"), so the CLI never ran whatever key the
+  VM had. Cowork's plugin settings no longer show an Affinity API Key field. The VM has no
+  `xaffinity` of its own, so the skill now installs it when it's missing (`pip install --user`,
+  about 10s, once per task) and puts `~/.local/bin` on PATH in each call; the CLI then reads the
+  key as the skill describes (a connected folder's `.env` with `--env-file`, or a key file).
+- **CLI plugin**: 1.13.3 → 1.13.4 — in local Cowork the plugin's hooks run on the host Mac, not
+  in the VM where the CLI runs, so the key check saw the Mac's key (or none) and could deny every
+  data command even with a key set in Cowork. There the hooks now do nothing; a missing key
+  shows up as the CLI's own error. Cloud Cowork and Claude Code keep the check. The `.env` read
+  guard's message no longer claims the key is in the environment.
+
 ## [1.29.0] - 2026-10-11
 
 ### Highlights

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

@@ -1,6 +1,6 @@
 Metadata-Version: 2.5
 Name: affinity-sdk
-Version: 1.29.0
+Version: 2.0.1
 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/
@@ -373,8 +373,8 @@ with Affinity(api_key="your-key") as client:
 ```python
 from datetime import datetime, timedelta
 from affinity import Affinity
-from affinity.models import ReminderCreate
-from affinity.types import PersonId, ReminderResetType, ReminderType, UserId
+from affinity.models import ReminderCreate, ReminderUpdate
+from affinity.types import PersonId, ReminderResetType, ReminderStatus, ReminderType, UserId
 
 with Affinity(api_key="your-key") as client:
     # Get current user
@@ -402,6 +402,14 @@ with Affinity(api_key="your-key") as client:
             person_id=PersonId(123),
         )
     )
+
+    # Complete it (a recurring reminder moves to its next due date)
+    client.reminders.update(recurring.id, ReminderUpdate(is_completed=True))
+
+    # Overdue reminders for many people, one request per 50 people
+    overdue = client.reminders.list_batch(
+        person_ids=[PersonId(123), PersonId(456)], status=ReminderStatus.OVERDUE
+    )
 ```
 
 ### Files
@@ -456,13 +464,13 @@ with Affinity(api_key="your-key") as client:
 ```python
 from affinity import Affinity
 from affinity.models import WebhookCreate, WebhookUpdate
-from affinity.types import WebhookEvent
+from affinity.types import WebhookEvent, WebhookStatus
 
 with Affinity(api_key="your-key") as client:
-    # Create a webhook subscription
+    # Create a webhook (subscriptions is required; [] means every event type)
     webhook = client.webhooks.create(
         WebhookCreate(
-            webhook_url="https://your-server.com/webhook",
+            url="https://your-server.com/webhook",
             subscriptions=[
                 WebhookEvent.LIST_ENTRY_CREATED,
                 WebhookEvent.LIST_ENTRY_DELETED,
@@ -471,14 +479,12 @@ with Affinity(api_key="your-key") as client:
         )
     )
 
-    # List all webhooks (max 3 per instance)
-    webhooks = client.webhooks.list()
+    # All webhooks you can see (all of them if you may manage all webhooks)
+    for hook in client.webhooks.iter():
+        print(hook.id, hook.url, hook.status)
 
-    # Disable a webhook
-    client.webhooks.update(
-        webhook.id,
-        WebhookUpdate(disabled=True)
-    )
+    # Pause a webhook (returns it as read back)
+    client.webhooks.update(webhook.id, WebhookUpdate(status=WebhookStatus.DISABLED))
 ```
 
 ### Rate Limits
@@ -545,9 +551,9 @@ those to V2 is planned.
 | List Entries (write) | Create | ✅ | V1 |
 | Field Values (read) | ✅ | ✅ | V2 |
 | Field Values (write) | ✅ | ✅ | V2 (list entries), V1 (companies/persons) |
-| Notes | ✅ | ✅ | V1 |
-| Reminders | ✅ | ✅ | V1 |
-| Webhooks | ✅ | ✅ | V1 |
+| 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 |
@@ -697,7 +703,7 @@ async def main():
 asyncio.run(main())
 ```
 
-Async support mirrors the sync client surface area (including V1-only services like notes/reminders/webhooks/files).
+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.
 

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

@@ -312,8 +312,8 @@ with Affinity(api_key="your-key") as client:
 ```python
 from datetime import datetime, timedelta
 from affinity import Affinity
-from affinity.models import ReminderCreate
-from affinity.types import PersonId, ReminderResetType, ReminderType, UserId
+from affinity.models import ReminderCreate, ReminderUpdate
+from affinity.types import PersonId, ReminderResetType, ReminderStatus, ReminderType, UserId
 
 with Affinity(api_key="your-key") as client:
     # Get current user
@@ -341,6 +341,14 @@ with Affinity(api_key="your-key") as client:
             person_id=PersonId(123),
         )
     )
+
+    # Complete it (a recurring reminder moves to its next due date)
+    client.reminders.update(recurring.id, ReminderUpdate(is_completed=True))
+
+    # Overdue reminders for many people, one request per 50 people
+    overdue = client.reminders.list_batch(
+        person_ids=[PersonId(123), PersonId(456)], status=ReminderStatus.OVERDUE
+    )
 ```
 
 ### Files
@@ -395,13 +403,13 @@ with Affinity(api_key="your-key") as client:
 ```python
 from affinity import Affinity
 from affinity.models import WebhookCreate, WebhookUpdate
-from affinity.types import WebhookEvent
+from affinity.types import WebhookEvent, WebhookStatus
 
 with Affinity(api_key="your-key") as client:
-    # Create a webhook subscription
+    # Create a webhook (subscriptions is required; [] means every event type)
     webhook = client.webhooks.create(
         WebhookCreate(
-            webhook_url="https://your-server.com/webhook",
+            url="https://your-server.com/webhook",
             subscriptions=[
                 WebhookEvent.LIST_ENTRY_CREATED,
                 WebhookEvent.LIST_ENTRY_DELETED,
@@ -410,14 +418,12 @@ with Affinity(api_key="your-key") as client:
         )
     )
 
-    # List all webhooks (max 3 per instance)
-    webhooks = client.webhooks.list()
+    # All webhooks you can see (all of them if you may manage all webhooks)
+    for hook in client.webhooks.iter():
+        print(hook.id, hook.url, hook.status)
 
-    # Disable a webhook
-    client.webhooks.update(
-        webhook.id,
-        WebhookUpdate(disabled=True)
-    )
+    # Pause a webhook (returns it as read back)
+    client.webhooks.update(webhook.id, WebhookUpdate(status=WebhookStatus.DISABLED))
 ```
 
 ### Rate Limits
@@ -484,9 +490,9 @@ those to V2 is planned.
 | List Entries (write) | Create | ✅ | V1 |
 | Field Values (read) | ✅ | ✅ | V2 |
 | Field Values (write) | ✅ | ✅ | V2 (list entries), V1 (companies/persons) |
-| Notes | ✅ | ✅ | V1 |
-| Reminders | ✅ | ✅ | V1 |
-| Webhooks | ✅ | ✅ | V1 |
+| 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 |
@@ -636,7 +642,7 @@ async def main():
 asyncio.run(main())
 ```
 
-Async support mirrors the sync client surface area (including V1-only services like notes/reminders/webhooks/files).
+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.
 

{affinity_sdk-1.29.0 → affinity_sdk-2.0.1}/affinity/cli/commands/_entity_files_read.py

@@ -87,9 +87,9 @@ def read_file_content(
     def fn(ctx: CLIContext, warnings: list[str]) -> CommandOutput:
         client = ctx.get_client(warnings=warnings)
 
-        # Get file metadata
-        file_meta = client.files.get(FileId(file_id))
-        file_size = file_meta.size or 0
+        # Name, size, type and a signed URL: one V2 request (or V1's two where V2 can't answer)
+        presigned = client.files.get_download_url(FileId(file_id))
+        file_size = presigned.size or 0
 
         # Validate offset
         if offset < 0:
@@ -107,9 +107,6 @@ def read_file_content(
                 hint=f"File size is {file_size} bytes. Use --offset 0 to start from beginning.",
             )
 
-        # Get presigned URL
-        presigned = client.files.get_download_url(FileId(file_id))
-
         # Calculate actual bytes to read
         remaining = file_size - offset
         bytes_to_read = min(limit, remaining)
@@ -161,9 +158,9 @@ def read_file_content(
 
         data = {
             "fileId": int(file_id),
-            "name": file_meta.name,
+            "name": presigned.name,
             "size": file_size,
-            "contentType": file_meta.content_type,
+            "contentType": presigned.content_type,
             "offset": offset,
             "length": actual_length,
             "hasMore": has_more,

{affinity_sdk-1.29.0 → affinity_sdk-2.0.1}/affinity/cli/commands/list_cmds.py

@@ -292,7 +292,12 @@ def list_ls(
     default=False,
     help="Whether the list is public (default: private).",
 )
-@click.option("--owner-id", type=int, default=None, help="Owner id.")
+@click.option(
+    "--owner-id",
+    type=int,
+    default=None,
+    help="Owner id (creates the list through the V1 API; otherwise you are the owner).",
+)
 @output_options
 @click.pass_obj
 def list_create(