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

{affinity_sdk-1.29.0 → affinity_sdk-2.0.0}/.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.0}/.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.0}/CHANGELOG.md

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

@@ -1,6 +1,6 @@
 Metadata-Version: 2.5
 Name: affinity-sdk
-Version: 1.29.0
+Version: 2.0.0
 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.0}/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.0}/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(

{affinity_sdk-1.29.0 → affinity_sdk-2.0.0}/affinity/cli/commands/note_cmds.py

@@ -1,14 +1,16 @@
 from __future__ import annotations
 
+import re
 import sys
 from contextlib import ExitStack
 from datetime import datetime, timedelta, timezone
 from typing import Any
 
+from pydantic import ValidationError as PydanticValidationError
 from rich.console import Console
 from rich.progress import BarColumn, Progress, TaskID, TextColumn, TimeElapsedColumn
 
-from affinity.models.secondary import Note, NoteCreate, NoteUpdate
+from affinity.models.secondary import Note, NoteCreate, NoteUpdate, NoteV2
 from affinity.models.types import InteractionType, NoteType
 from affinity.services.search import NOTE_SEARCH_DEFAULT_LIMIT, build_keyword_search_body
 from affinity.types import CompanyId, NoteId, OpportunityId, PersonId, UserId
@@ -42,8 +44,6 @@ _NOTE_TYPE_MAP = {
     "plain-text": NoteType.PLAIN_TEXT,
     "plain": NoteType.PLAIN_TEXT,
     "html": NoteType.HTML,
-    "ai-notetaker": NoteType.AI_NOTETAKER,
-    "email-derived": NoteType.EMAIL_DERIVED,
 }
 
 
@@ -66,6 +66,17 @@ def _get_cached_user_id(ctx: CLIContext, client: Any) -> int | None:
         return None
 
 
+def _comparable(text: str) -> str:
+    """Note text for the duplicate check, in a form both copies share.
+
+    V1 shows notes stored as HTML (every note written through V2) in a markdown form: special
+    characters backslash-escaped (``snake\\_case``) and two spaces before a line break. Undo
+    those, and compare whitespace-insensitively.
+    """
+    text = re.sub(r"\\(.)", r"\1", text)
+    return " ".join(text.split())
+
+
 def _maybe_warn_duplicate_note(
     *,
     ctx: CLIContext,
@@ -99,7 +110,7 @@ def _maybe_warn_duplicate_note(
             return
         scoped_creator_id = resolved_id
 
-    normalized_new = content.strip()
+    normalized_new = _comparable(content)
     if not normalized_new:
         return
 
@@ -119,8 +130,7 @@ def _maybe_warn_duplicate_note(
             # transient list failure abort the actual note write.
             return False
         for existing in getattr(page, "data", []) or []:
-            existing_content = (existing.content or "").strip()
-            if existing_content != normalized_new:
+            if _comparable(existing.content or "") != normalized_new:
                 continue
             created_at = getattr(existing, "created_at", None)
             if created_at is None:
@@ -182,6 +192,78 @@ def _note_payload(note: Note) -> dict[str, object]:
     }
 
 
+_INPUT_MODELS = ("NoteCreate", "NoteUpdate")
+
+
+def _is_input_error(exc: ValueError) -> bool:
+    """Our own checks, or the request model; not a response the API sent that didn't parse
+    (the write may have happened: a usage error would invite a duplicating retry)."""
+    if isinstance(exc, PydanticValidationError):
+        return exc.title in _INPUT_MODELS
+    return True
+
+
+def _usage(exc: ValueError) -> CLIError:
+    errors = getattr(exc, "errors", None)
+    message = str(exc)
+    if callable(errors):  # pydantic ValidationError: keep only the messages
+        message = "; ".join(str(e.get("msg", "")).removeprefix("Value error, ") for e in errors())
+    return CLIError(message, error_type="usage_error", exit_code=2)
+
+
+def _ids(given: list[int] | None, preview: list[Any] | None) -> list[int]:
+    if given is not None:
+        return [int(i) for i in given]
+    return [int(item.id) for item in preview or []]
+
+
+def _note_v2_payload(
+    note: NoteV2,
+    *,
+    person_ids: list[int] | None = None,
+    company_ids: list[int] | None = None,
+    opportunity_ids: list[int] | None = None,
+) -> dict[str, object]:
+    """A note written through V2, with the same keys as `note get` (V2 stores HTML).
+
+    Attachment ids come from the request when given, else from the note as read back.
+    """
+    interaction = note.interaction or {}
+    persons = _ids(person_ids, note.persons)
+    mentioned = [
+        int(m["person"]["id"])
+        for m in note.mentions
+        if isinstance(m, dict) and isinstance(m.get("person"), dict) and m["person"].get("id")
+    ]
+    return {
+        "id": int(note.id),
+        "type": "html",
+        "creatorId": int(note.creator.id) if note.creator else None,
+        "content": note.content.html,
+        "personIds": persons,
+        "associatedPersonIds": persons,
+        "interactionPersonIds": [],
+        "mentionedPersonIds": mentioned,
+        "companyIds": _ids(company_ids, note.companies),
+        "opportunityIds": _ids(opportunity_ids, note.opportunities),
+        "interactionId": interaction.get("id"),
+        "interactionType": interaction.get("type"),
+        "isMeeting": interaction.get("type") == "meeting",
+        "parentId": int(note.parent["id"]) if note.parent and note.parent.get("id") else None,
+        "createdAt": note.created_at,
+        "updatedAt": note.updated_at,
+    }
+
+
+def _truncation_warnings(note: NoteV2, warnings: list[str]) -> None:
+    for key in ("persons", "companies", "opportunities"):
+        shown, total = getattr(note, key), getattr(note, f"{key}_total")
+        if shown is not None and total is not None and total > len(shown):
+            warnings.append(
+                f"The note has {total} attached {key}; the output lists the first {len(shown)}."
+            )
+
+
 @category("read")
 @note_group.command(name="ls", cls=RichCommand)
 @click.option("--person-id", type=int, default=None, help="Filter by person id.")
@@ -488,7 +570,7 @@ def note_search(
     "note_type",
     type=click.Choice(sorted(_NOTE_TYPE_MAP.keys())),
     default=None,
-    help="Note type (plain-text, html, ai-notetaker, email-derived).",
+    help="How --content is written: plain-text (default; stored as escaped HTML) or html.",
 )
 @click.option("--person-id", "person_ids", multiple=True, type=int, help="Associate person id.")
 @click.option(
@@ -548,15 +630,16 @@ def note_create(
     """
     Create a note attached to an entity.
 
-    Note: The Affinity API escapes underscores in note content (e.g., "test_note"
-    becomes "test\\_note"). This is server-side markdown escaping and cannot be
-    prevented. If you need to search for or compare note content, account for
-    this transformation.
+    Affinity stores notes as HTML: plain text is escaped and wrapped in paragraphs (a blank
+    line starts a new one). With --type html, <b>/<i> become <strong>/<em>; tags Affinity
+    rejects (style/class attributes, img, pre, code, blockquote, ...) fail before anything is
+    sent. A reply (--parent-id) has no persons, companies or opportunities of its own.
 
     Examples:
 
     - `xaffinity note create --content "Meeting notes" --person-id 12345`
-    - `xaffinity note create --content "<b>Summary</b>" --type html --company-id 67890`
+    - `xaffinity note create --content "<p><strong>Summary</strong></p>" --type html \\
+      --company-id 67890`
     """
 
     def fn(ctx: CLIContext, warnings: list[str]) -> CommandOutput:
@@ -597,18 +680,23 @@ def note_create(
                 window_seconds=duplicate_window_seconds,
             )
 
-        note = client.notes.create(
-            NoteCreate(
-                content=content,
-                type=parsed_type or NoteType.PLAIN_TEXT,
-                person_ids=[PersonId(pid) for pid in person_ids],
-                company_ids=[CompanyId(cid) for cid in company_ids],
-                opportunity_ids=[OpportunityId(oid) for oid in opportunity_ids],
-                parent_id=NoteId(parent_id) if parent_id else None,
-                creator_id=UserId(creator_id) if creator_id is not None else None,
-                created_at=created_at_value,
+        try:
+            note = client.notes.create(
+                NoteCreate(
+                    content=content,
+                    type=parsed_type or NoteType.PLAIN_TEXT,
+                    person_ids=[PersonId(pid) for pid in person_ids],
+                    company_ids=[CompanyId(cid) for cid in company_ids],
+                    opportunity_ids=[OpportunityId(oid) for oid in opportunity_ids],
+                    parent_id=NoteId(parent_id) if parent_id else None,
+                    creator_id=UserId(creator_id) if creator_id is not None else None,
+                    created_at=created_at_value,
+                )
             )
-        )
+        except ValueError as exc:
+            if not _is_input_error(exc):
+                raise
+            raise _usage(exc) from exc
 
         ctx_modifiers: dict[str, object] = {}
         if note_type:
@@ -633,7 +721,14 @@ def note_create(
         )
 
         return CommandOutput(
-            data={"note": _note_payload(note)},
+            data={
+                "note": _note_v2_payload(
+                    note,
+                    person_ids=list(person_ids),
+                    company_ids=list(company_ids),
+                    opportunity_ids=list(opportunity_ids),
+                )
+            },
             context=cmd_context,
             api_called=True,
         )
@@ -645,23 +740,47 @@ def note_create(
 @note_group.command(name="update", cls=RichCommand)
 @click.argument("note_id", type=int)
 @click.option("--content", type=str, required=True, help="Updated note content.")
+@click.option(
+    "--type",
+    "note_type",
+    type=click.Choice(sorted(_NOTE_TYPE_MAP.keys())),
+    default=None,
+    help="How --content is written: plain-text (default) or html, whatever the note was before.",
+)
 @output_options
 @click.pass_obj
-def note_update(ctx: CLIContext, note_id: int, *, content: str) -> None:
-    """Update a note."""
+def note_update(ctx: CLIContext, note_id: int, *, content: str, note_type: str | None) -> None:
+    """Replace a note's content.
+
+    The content is plain text unless you pass --type html (an HTML note updated with plain text
+    shows the text as typed). Notes with @mentions can't be changed through the API.
+    """
 
     def fn(ctx: CLIContext, warnings: list[str]) -> CommandOutput:
+        parsed_type = parse_choice(note_type, _NOTE_TYPE_MAP, label="note type")
         client = ctx.get_client(warnings=warnings)
-        note = client.notes.update(NoteId(note_id), NoteUpdate(content=content))
+        try:
+            note = client.notes.update(
+                NoteId(note_id),
+                NoteUpdate(content=content, type=parsed_type or NoteType.PLAIN_TEXT),
+            )
+        except ValueError as exc:
+            if not _is_input_error(exc):
+                raise
+            raise _usage(exc) from exc
+        _truncation_warnings(note, warnings)
 
+        modifiers: dict[str, object] = {"content": content}
+        if note_type:
+            modifiers["type"] = note_type
         cmd_context = CommandContext(
             name="note update",
             inputs={"noteId": note_id},
-            modifiers={"content": content},
+            modifiers=modifiers,
         )
 
         return CommandOutput(
-            data={"note": _note_payload(note)},
+            data={"note": _note_v2_payload(note)},
             context=cmd_context,
             api_called=True,
         )