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

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

@@ -7,6 +7,36 @@ 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

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

@@ -1,6 +1,6 @@
 Metadata-Version: 2.5
 Name: affinity-sdk
-Version: 2.0.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/

{affinity_sdk-2.0.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-2.0.0 → affinity_sdk-2.0.1}/affinity/cli/commands/note_cmds.py

@@ -432,7 +432,8 @@ def note_get(ctx: CLIContext, note_id: int) -> None:
 
     def fn(ctx: CLIContext, warnings: list[str]) -> CommandOutput:
         client = ctx.get_client(warnings=warnings)
-        note = client.notes.get(NoteId(note_id))
+        note = client.notes.get(NoteId(note_id), includes=True)
+        _truncation_warnings(note, warnings)
 
         cmd_context = CommandContext(
             name="note get",
@@ -440,7 +441,7 @@ def note_get(ctx: CLIContext, note_id: int) -> None:
             modifiers={},
         )
 
-        payload = _note_payload(note)
+        payload = _note_v2_payload(note)
 
         # For table display, separate content from metadata for better readability
         if ctx.output != "json":

{affinity_sdk-2.0.0 → affinity_sdk-2.0.1}/affinity/cli/commands/org_read_cmds.py

@@ -486,17 +486,17 @@ def note_feed(
             "updated_after": _when(updated_after, "--updated-after"),
         }
         rows, next_cursor = collect_pages(
-            (lambda: notes.list_v2(cursor=cursor))
+            (lambda: notes.feed(cursor=cursor))
             if cursor is not None
             else (
-                lambda: notes.list_v2(
+                lambda: notes.feed(
                     **times,
                     creator_id=creator_id,
                     includes=True if with_attached else None,
                     limit=page_limit(max_results),
                 )
             ),
-            lambda c: notes.list_v2(cursor=c),
+            lambda c: notes.feed(cursor=c),
             note_row,
             max_results=max_results,
             all_pages=all_pages,

{affinity_sdk-2.0.0 → affinity_sdk-2.0.1}/affinity/models/secondary.py

@@ -134,8 +134,8 @@ class NoteV2(AffinityModel):
     """V2 API note format.
 
     ``replies_count`` and the attached ``companies`` / ``persons`` / ``opportunities`` (first ones,
-    with ``*_total``) are filled only when requested with ``includes`` (``notes.list_v2`` /
-    ``notes.get_v2``); otherwise they are ``None``.
+    with ``*_total``) are filled only when requested with ``includes`` (``notes.feed`` /
+    ``notes.get``); otherwise they are ``None``.
     """
 
     id: NoteId
@@ -280,10 +280,10 @@ class OpportunityRef(AffinityModel):
 
 
 class FileV2(AffinityModel):
-    """A file's metadata from V2 (``files.get_v2``, ``files.list_v2``).
+    """A file's metadata from V2 (``files.feed``).
 
-    V2 files carry no person/company/opportunity; ``download_url`` (``get_v2`` only) is a signed
-    URL that expires 60 seconds after the response.
+    V2 files carry no person/company/opportunity; ``download_url`` (single-file reads only) is
+    a signed URL that expires 60 seconds after the response.
     """
 
     id: FileId

{affinity_sdk-2.0.0 → affinity_sdk-2.0.1}/affinity/services/v1_only.py

@@ -24,7 +24,12 @@ import httpx
 from pydantic import AliasChoices, TypeAdapter, ValidationError
 
 from ..downloads import AsyncDownloadedFile, DownloadedFile
-from ..exceptions import AffinityError
+from ..exceptions import (
+    AffinityError,
+    ApiVersionTooOldError,
+    AuthorizationError,
+    NotFoundError,
+)
 from ..exceptions import ValidationError as AffinityValidationError
 from ..models.entities import (
     FieldCreate,
@@ -117,6 +122,26 @@ class PresignedUrl:
     expires_at: datetime
 
 
+def _presigned(
+    url: str, file_id: int, name: str, size: int, content_type: str | None
+) -> PresignedUrl:
+    """A ``PresignedUrl``; its lifetime comes from ``X-Amz-Expires`` (60 seconds if absent)."""
+    expires_in = 60
+    qs = parse_qs(urlparse(url).query)
+    if "X-Amz-Expires" in qs:
+        with contextlib.suppress(ValueError, IndexError):
+            expires_in = int(qs["X-Amz-Expires"][0])
+    return PresignedUrl(
+        url=url,
+        file_id=int(file_id),
+        name=name,
+        size=size,
+        content_type=content_type,
+        expires_in=expires_in,
+        expires_at=datetime.now(timezone.utc) + timedelta(seconds=expires_in),
+    )
+
+
 _MAX_INTERACTION_RANGE_DAYS = 365
 
 
@@ -345,11 +370,6 @@ class NoteService(NoteSearchMixin):
             next_page_token=data.get("next_page_token") or data.get("nextPageToken"),
         )
 
-    def get(self, note_id: NoteId) -> Note:
-        """Get a single note by ID."""
-        data = self._client.get(f"/notes/{note_id}", v1=True)
-        return Note.model_validate(data)
-
     def create(self, data: NoteCreate) -> NoteV2:
         """Create a note (V2) and return it.
 
@@ -373,11 +393,11 @@ class NoteService(NoteSearchMixin):
             if data.content is not None:
                 note = None
                 with contextlib.suppress(AffinityError):
-                    note = self.get_v2(note_id)
+                    note = self.get(note_id)
                 if has_mentions(note):
                     raise mentions_error(exc) from exc
             raise
-        return self.get_v2(note_id, includes=True)
+        return self.get(note_id, includes=True)
 
     def delete(self, note_id: NoteId) -> bool:
         """Delete a note you created (V2). Deleting a note also deletes its replies."""
@@ -423,7 +443,7 @@ class NoteService(NoteSearchMixin):
     # V2 notes (read): NoteV2 with creator, HTML content, interaction, transcript
     # =========================================================================
 
-    def list_v2(
+    def feed(
         self,
         *,
         creator_id: int | None = None,
@@ -467,7 +487,7 @@ class NoteService(NoteSearchMixin):
         )
         return page_of(NoteV2, self._client.get("/notes", params=params or None))
 
-    def iter_v2(
+    def iter_feed(
         self,
         *,
         creator_id: int | None = None,
@@ -477,12 +497,12 @@ class NoteService(NoteSearchMixin):
         includes: bool | Sequence[str] | None = None,
         limit: int | None = None,
     ) -> Iterator[NoteV2]:
-        """All notes matching the filters (every page); see :meth:`list_v2`."""
+        """All notes matching the filters (every page); see :meth:`feed`."""
 
         def fetch_page(next_url: str | None) -> PaginatedResponse[NoteV2]:
             if next_url:
-                return self.list_v2(cursor=next_url)
-            return self.list_v2(
+                return self.feed(cursor=next_url)
+            return self.feed(
                 creator_id=creator_id,
                 created_after=created_after,
                 created_before=created_before,
@@ -493,8 +513,8 @@ class NoteService(NoteSearchMixin):
 
         return PageIterator(fetch_page)
 
-    def get_v2(self, note_id: NoteId, *, includes: bool | Sequence[str] | None = None) -> NoteV2:
-        """One note as ``NoteV2`` (``includes`` as in :meth:`list_v2`)."""
+    def get(self, note_id: NoteId, *, includes: bool | Sequence[str] | None = None) -> NoteV2:
+        """One note as ``NoteV2`` (``includes`` as in :meth:`feed`)."""
         params = [("includes", value) for value in note_includes(includes)]
         return NoteV2.model_validate(
             self._client.get(f"/notes/{int(note_id)}", params=params or None)
@@ -1852,18 +1872,12 @@ class EntityFileService(FileSearchMixin):
         )
 
     def get(self, file_id: FileId) -> EntityFile:
-        """Get file metadata."""
+        """A file's details, including the person, company or opportunity it belongs to (V1;
+        works under any API version). :meth:`get_download_url` adds a download link."""
         data = self._client.get(f"/entity-files/{file_id}", v1=True)
         return EntityFile.model_validate(data)
 
-    def get_v2(self, file_id: FileId) -> FileV2:
-        """One file's metadata from V2 (Affinity API 2026-09-17+), with a download URL that
-        expires 60 seconds later. :meth:`get` (V1) is unchanged."""
-        return FileV2.model_validate(
-            self._client.get(f"/files/{int(file_id)}", min_api_version=FILES_V2_MIN_API_VERSION)
-        )
-
-    def list_v2(
+    def feed(
         self,
         *,
         created_after: datetime | None = None,
@@ -1895,7 +1909,7 @@ class EntityFileService(FileSearchMixin):
             ),
         )
 
-    def iter_v2(
+    def iter_feed(
         self,
         *,
         created_after: datetime | None = None,
@@ -1903,12 +1917,12 @@ class EntityFileService(FileSearchMixin):
         creator_id: UserId | None = None,
         limit: int | None = None,
     ) -> Iterator[FileV2]:
-        """All files matching the filters (every page); see :meth:`list_v2`."""
+        """All files matching the filters (every page); see :meth:`feed`."""
 
         def fetch_page(next_url: str | None) -> PaginatedResponse[FileV2]:
             if next_url:
-                return self.list_v2(cursor=next_url)
-            return self.list_v2(
+                return self.feed(cursor=next_url)
+            return self.feed(
                 created_after=created_after,
                 created_before=created_before,
                 creator_id=creator_id,
@@ -1954,7 +1968,16 @@ class EntityFileService(FileSearchMixin):
         Raises:
             AffinityError: If the API doesn't return a redirect URL
         """
-        # Fetch file metadata first
+        # V2 answers with the details and a signed URL in one request (API 2026-09-17+, beta);
+        # a client pinned older, or a V2 refusal, uses V1's details and redirect instead
+        try:
+            v2 = FileV2.model_validate(
+                self._client.get(f"/files/{int(file_id)}", min_api_version=FILES_V2_MIN_API_VERSION)
+            )
+            if v2.download_url:
+                return _presigned(v2.download_url, v2.id, v2.name, v2.size, v2.content_type)
+        except (ApiVersionTooOldError, AuthorizationError, NotFoundError):
+            pass
         file_meta = self.get(file_id)
 
         url = self._client.get_redirect_url(
@@ -1967,27 +1990,7 @@ class EntityFileService(FileSearchMixin):
                 f"Failed to get presigned URL for file {file_id}: no redirect returned"
             )
 
-        # Parse X-Amz-Expires from the presigned URL to determine TTL
-        # Default to 60 seconds if not found (Affinity's typical TTL)
-        parsed = urlparse(url)
-        qs = parse_qs(parsed.query)
-        expires_in = 60  # default
-        if "X-Amz-Expires" in qs:
-            with contextlib.suppress(ValueError, IndexError):
-                expires_in = int(qs["X-Amz-Expires"][0])
-
-        now = datetime.now(timezone.utc)
-        expires_at = now + timedelta(seconds=expires_in)
-
-        return PresignedUrl(
-            url=url,
-            file_id=int(file_id),
-            name=file_meta.name,
-            size=file_meta.size,
-            content_type=file_meta.content_type,
-            expires_in=expires_in,
-            expires_at=expires_at,
-        )
+        return _presigned(url, file_id, file_meta.name, file_meta.size, file_meta.content_type)
 
     def download_stream(
         self,
@@ -2468,10 +2471,6 @@ class AsyncNoteService(AsyncNoteSearchMixin):
             next_page_token=data.get("next_page_token") or data.get("nextPageToken"),
         )
 
-    async def get(self, note_id: NoteId) -> Note:
-        data = await self._client.get(f"/notes/{note_id}", v1=True)
-        return Note.model_validate(data)
-
     async def create(self, data: NoteCreate) -> NoteV2:
         """Create a note (V2); see :meth:`NoteService.create`."""
         return NoteV2.model_validate(await self._client.post("/notes", json=note_create_body(data)))
@@ -2484,11 +2483,11 @@ class AsyncNoteService(AsyncNoteSearchMixin):
             if data.content is not None:
                 note = None
                 with contextlib.suppress(AffinityError):
-                    note = await self.get_v2(note_id)
+                    note = await self.get(note_id)
                 if has_mentions(note):
                     raise mentions_error(exc) from exc
             raise
-        return await self.get_v2(note_id, includes=True)
+        return await self.get(note_id, includes=True)
 
     async def delete(self, note_id: NoteId) -> bool:
         """Delete a note you created (V2); see :meth:`NoteService.delete`."""
@@ -2534,7 +2533,7 @@ class AsyncNoteService(AsyncNoteSearchMixin):
     # V2 notes (read): NoteV2 with creator, HTML content, interaction, transcript
     # =========================================================================
 
-    async def list_v2(
+    async def feed(
         self,
         *,
         creator_id: int | None = None,
@@ -2578,7 +2577,7 @@ class AsyncNoteService(AsyncNoteSearchMixin):
         )
         return page_of(NoteV2, await self._client.get("/notes", params=params or None))
 
-    def iter_v2(
+    def iter_feed(
         self,
         *,
         creator_id: int | None = None,
@@ -2588,12 +2587,12 @@ class AsyncNoteService(AsyncNoteSearchMixin):
         includes: bool | Sequence[str] | None = None,
         limit: int | None = None,
     ) -> AsyncIterator[NoteV2]:
-        """All notes matching the filters (every page); see :meth:`list_v2`."""
+        """All notes matching the filters (every page); see :meth:`feed`."""
 
         async def fetch_page(next_url: str | None) -> PaginatedResponse[NoteV2]:
             if next_url:
-                return await self.list_v2(cursor=next_url)
-            return await self.list_v2(
+                return await self.feed(cursor=next_url)
+            return await self.feed(
                 creator_id=creator_id,
                 created_after=created_after,
                 created_before=created_before,
@@ -2604,10 +2603,8 @@ class AsyncNoteService(AsyncNoteSearchMixin):
 
         return AsyncPageIterator(fetch_page)
 
-    async def get_v2(
-        self, note_id: NoteId, *, includes: bool | Sequence[str] | None = None
-    ) -> NoteV2:
-        """One note as ``NoteV2`` (``includes`` as in :meth:`list_v2`)."""
+    async def get(self, note_id: NoteId, *, includes: bool | Sequence[str] | None = None) -> NoteV2:
+        """One note as ``NoteV2`` (``includes`` as in :meth:`feed`)."""
         params = [("includes", value) for value in note_includes(includes)]
         return NoteV2.model_validate(
             await self._client.get(f"/notes/{int(note_id)}", params=params or None)
@@ -3735,19 +3732,11 @@ class AsyncEntityFileService(AsyncFileSearchMixin):
         )
 
     async def get(self, file_id: FileId) -> EntityFile:
+        """A file's details (V1); see :meth:`EntityFileService.get`."""
         data = await self._client.get(f"/entity-files/{file_id}", v1=True)
         return EntityFile.model_validate(data)
 
-    async def get_v2(self, file_id: FileId) -> FileV2:
-        """One file's metadata from V2 (Affinity API 2026-09-17+), with a download URL that
-        expires 60 seconds later. :meth:`get` (V1) is unchanged."""
-        return FileV2.model_validate(
-            await self._client.get(
-                f"/files/{int(file_id)}", min_api_version=FILES_V2_MIN_API_VERSION
-            )
-        )
-
-    async def list_v2(
+    async def feed(
         self,
         *,
         created_after: datetime | None = None,
@@ -3780,7 +3769,7 @@ class AsyncEntityFileService(AsyncFileSearchMixin):
             ),
         )
 
-    def iter_v2(
+    def iter_feed(
         self,
         *,
         created_after: datetime | None = None,
@@ -3788,12 +3777,12 @@ class AsyncEntityFileService(AsyncFileSearchMixin):
         creator_id: UserId | None = None,
         limit: int | None = None,
     ) -> AsyncIterator[FileV2]:
-        """All files matching the filters (every page); see :meth:`list_v2`."""
+        """All files matching the filters (every page); see :meth:`feed`."""
 
         async def fetch_page(next_url: str | None) -> PaginatedResponse[FileV2]:
             if next_url:
-                return await self.list_v2(cursor=next_url)
-            return await self.list_v2(
+                return await self.feed(cursor=next_url)
+            return await self.feed(
                 created_after=created_after,
                 created_before=created_before,
                 creator_id=creator_id,
@@ -3992,7 +3981,18 @@ class AsyncEntityFileService(AsyncFileSearchMixin):
         Raises:
             AffinityError: If the API doesn't return a redirect URL
         """
-        # Fetch file metadata first
+        # V2 answers with the details and a signed URL in one request (API 2026-09-17+, beta);
+        # a client pinned older, or a V2 refusal, uses V1's details and redirect instead
+        try:
+            v2 = FileV2.model_validate(
+                await self._client.get(
+                    f"/files/{int(file_id)}", min_api_version=FILES_V2_MIN_API_VERSION
+                )
+            )
+            if v2.download_url:
+                return _presigned(v2.download_url, v2.id, v2.name, v2.size, v2.content_type)
+        except (ApiVersionTooOldError, AuthorizationError, NotFoundError):
+            pass
         file_meta = await self.get(file_id)
 
         url = await self._client.get_redirect_url(
@@ -4005,27 +4005,7 @@ class AsyncEntityFileService(AsyncFileSearchMixin):
                 f"Failed to get presigned URL for file {file_id}: no redirect returned"
             )
 
-        # Parse X-Amz-Expires from the presigned URL to determine TTL
-        # Default to 60 seconds if not found (Affinity's typical TTL)
-        parsed = urlparse(url)
-        qs = parse_qs(parsed.query)
-        expires_in = 60  # default
-        if "X-Amz-Expires" in qs:
-            with contextlib.suppress(ValueError, IndexError):
-                expires_in = int(qs["X-Amz-Expires"][0])
-
-        now = datetime.now(timezone.utc)
-        expires_at = now + timedelta(seconds=expires_in)
-
-        return PresignedUrl(
-            url=url,
-            file_id=int(file_id),
-            name=file_meta.name,
-            size=file_meta.size,
-            content_type=file_meta.content_type,
-            expires_in=expires_in,
-            expires_at=expires_at,
-        )
+        return _presigned(url, file_id, file_meta.name, file_meta.size, file_meta.content_type)
 
     def download_stream(
         self,

{affinity_sdk-2.0.0 → affinity_sdk-2.0.1}/docs/public/examples.md

@@ -84,7 +84,7 @@ from affinity.types import CompanyId, NoteId
 
 since = datetime(2025, 6, 1, tzinfo=timezone.utc)
 with Affinity.from_env() as client:
-    for note in client.notes.iter_v2(created_after=since, includes=True):
+    for note in client.notes.iter_feed(created_after=since, includes=True):
         print(note.id, note.type, note.creator, note.replies_count, note.companies_total)
 
     for reply in client.notes.iter_replies(NoteId(123)):

{affinity_sdk-2.0.0 → affinity_sdk-2.0.1}/docs/public/guides/api-versions-and-routing.md

@@ -28,7 +28,8 @@ Where V2 has the operation but can't do one part of it, that case goes through V
 | `lists.create` | `owner_id` or `additional_permissions` is set |
 | `reminders.update` | `type` is set (V2 can't change a reminder's type) |
 | `reminders.update` / `delete` | V2 refuses (403: only the creator or owner may change it on V2); retried once on V1 |
-| `files.list` / `iter` / `get` | always (only V1 lists one entity's files; `files.list_v2`/`get_v2` are the V2 reads) |
+| `files.get` / `list` / `iter` | always (only V1 has the file's person, company or opportunity and works under any version pin; `files.feed` lists through V2) |
+| `files.get_download_url` | when V2 can't answer: pinned older than 2026-09-17, or V2 refuses (V2 otherwise, in one request) |
 | `lists.get_size` | always (V2 has no list size) |
 
 The [API coverage](../reference/api-coverage.md) page lists every operation, the SDK call that

{affinity_sdk-2.0.0 → affinity_sdk-2.0.1}/docs/public/guides/migrating-to-2.md

@@ -59,8 +59,10 @@ ls|get|create|update|delete`; create, update and delete ask for confirmation.
 | `type=HTML` with any tags | `<b>`/`<i>` become `<strong>`/`<em>`; tags Affinity rejects raise `ValueError` naming the allowed ones |
 | `parent_id` with entity ids (ids ignored) | `ValidationError` |
 
-`note get`/`note ls` and `notes.list/get` still use V1, which shows notes stored as HTML in a
-markdown-like form. Changing the text of a note that @mentions people is refused by the API.
+`notes.get()` returns `NoteV2` (`includes=True` adds the attached companies, persons and
+opportunities); `notes.list_v2()`/`iter_v2()`/`get_v2()` are now `notes.feed()`/`iter_feed()`/
+`get()`. `notes.list()` (one entity's notes) and CLI `note ls` still use V1, which shows notes
+stored as HTML in a markdown-like form. Changing the text of a note that @mentions people is refused by the API.
 
 ## Lists
 
@@ -76,9 +78,9 @@ unchanged (V1): Affinity's V2 spec documents them, but the API didn't serve them
 
 ## Files and rate limits
 
-`files.get/list/iter` are unchanged (V1). New: `files.get_v2()` (with a download URL that
-expires after 60 seconds) and `files.list_v2()`/`iter_v2()` (every file you can see, newest
-first). `rate_limits.refresh()` reads the V2 endpoint; `RateLimitSnapshot` is unchanged.
+`files.get/list/iter` are unchanged (V1). `files.get_download_url()` uses V2 when it can (one
+request for the details and a URL valid 60 seconds) and V1 otherwise. New:
+`files.feed()`/`iter_feed()` (every file you can see, newest first, as `FileV2`). `rate_limits.refresh()` reads the V2 endpoint; `RateLimitSnapshot` is unchanged.
 
 ## CLI and MCP
 

{affinity_sdk-2.0.0 → affinity_sdk-2.0.1}/docs/public/reference/api-coverage.md

@@ -35,9 +35,9 @@ against the pinned API specs and checks that each supported call requests its op
 | `GET /v2/emails` | supported | `interactions.list_emails()` |  |
 | `POST /v2/feedback` | planned |  | phase 2.x-1 |
 | `GET /v2/field-value-changes` | supported | `field_value_changes.list_global(field_id=FieldId(1))` |  |
-| `GET /v2/files` | supported | `files.list_v2()` | beta; API 2026-09-17+ |
+| `GET /v2/files` | supported | `files.feed()` | beta; API 2026-09-17+ |
 | `POST /v2/files/search` | supported | `files.search("prompt text")` |  |
-| `GET /v2/files/{fileId}` | supported | `files.get_v2(FileId(1))` | beta; API 2026-09-17+ |
+| `GET /v2/files/{fileId}` | supported | `files.get_download_url(FileId(1))` | beta; API 2026-09-17+ |
 | `GET /v2/inferred-connections/coworkers` | planned |  | beta; phase 2.x-2 |
 | `GET /v2/inferred-connections/investor-executive-connections` | planned |  | beta; phase 2.x-2 |
 | `GET /v2/lists` | supported | `lists.list()` |  |
@@ -64,11 +64,11 @@ against the pinned API specs and checks that each supported call requests its op
 | `GET /v2/lists/{listId}/saved-views/{viewId}/list-entries` | supported | `lists.entries(ListId(1)).from_saved_view(SavedViewId(1))` |  |
 | `GET /v2/meetings` | supported | `interactions.list_meetings()` |  |
 | `GET /v2/meetings/{meetingId}` | planned |  | beta; API 2026-07-15+; phase 2.x-1 |
-| `GET /v2/notes` | supported | `notes.list_v2()` |  |
+| `GET /v2/notes` | supported | `notes.feed()` |  |
 | `POST /v2/notes` | supported | `notes.create(NoteCreate(content="x", person_ids=[PersonId(1)]))` |  |
 | `POST /v2/notes/search` | supported | `notes.search("prompt text")` |  |
 | `DELETE /v2/notes/{noteId}` | supported | `notes.delete(NoteId(1))` |  |
-| `GET /v2/notes/{noteId}` | supported | `notes.get_v2(NoteId(1))` |  |
+| `GET /v2/notes/{noteId}` | supported | `notes.get(NoteId(1))` |  |
 | `POST /v2/notes/{noteId}` | supported | `notes.update(NoteId(1), NoteUpdate(content="x"))` |  |
 | `GET /v2/notes/{noteId}/attached-companies` | planned |  | phase 2.x-1 |
 | `GET /v2/notes/{noteId}/attached-opportunities` | planned |  | phase 2.x-1 |
@@ -125,15 +125,15 @@ against the pinned API specs and checks that each supported call requests its op
 
 ## V1 API
 
-41 supported, 18 equivalent
+40 supported, 19 equivalent
 
 | Operation | Status | SDK | Notes |
 |---|---|---|---|
 | `GET /auth/whoami` | equivalent |  | via v2 GET /v2/auth/whoami |
-| `GET /entity-files` | supported | `files.list(company_id=CompanyId(1))` | one person's, company's or opportunity's files (V2 lists only org-wide: files.list_v2) |
+| `GET /entity-files` | supported | `files.list(company_id=CompanyId(1))` | one person's, company's or opportunity's files (V2 lists only org-wide: files.feed) |
 | `POST /entity-files` | supported | `files.upload_bytes(b"x", "a.txt", company_id=CompanyId(1))` |  |
 | `GET /entity-files/download/{}` | supported | `files.download(FileId(1))` |  |
-| `GET /entity-files/{}` | supported | `files.get(FileId(1))` | works under any API version pin; files.get_v2 adds a download URL (API 2026-09-17+) |
+| `GET /entity-files/{}` | supported | `files.get(FileId(1))` | the file's record, with its person/company/opportunity, under any API version pin; get_download_url uses V2 when it can |
 | `GET /field-value-changes` | supported | `field_value_changes.list(FieldId(1), company_id=CompanyId(1))` |  |
 | `GET /field-values` | supported | `field_values.list(company_id=CompanyId(1))` |  |
 | `POST /field-values` | supported | `field_values.create(FieldValueCreate(field_id=FieldId(1), entity_id=1, value="x"))` |  |
@@ -157,7 +157,7 @@ against the pinned API specs and checks that each supported call requests its op
 | `GET /notes` | supported | `notes.list()` |  |
 | `POST /notes` | equivalent |  | via v2 POST /v2/notes |
 | `DELETE /notes/{}` | equivalent |  | via v2 DELETE /v2/notes/{noteId} |
-| `GET /notes/{}` | supported | `notes.get(NoteId(1))` |  |
+| `GET /notes/{}` | equivalent |  | via v2 GET /v2/notes/{noteId} |
 | `PUT /notes/{}` | equivalent |  | via v2 POST /v2/notes/{noteId} |
 | `GET /opportunities` | supported | `opportunities.search("x")` |  |
 | `POST /opportunities` | supported | `opportunities.create(OpportunityCreate(name="x", list_id=ListId(1)))` |  |

affinity_sdk-2.0.1/docs/public/reference/services/v1/files.md

@@ -0,0 +1,8 @@
+# Files
+
+`get`, `list`, `all`, `iter`, uploads and downloads use V1: only V1 has a file's person,
+company or opportunity, and it works under any API version pin. `get_download_url` uses V2 when
+it can (one request for the details and a signed URL) and V1 otherwise. `feed`/`iter_feed`
+list every file visible to you, newest first, through V2 (Affinity API 2026-09-17+).
+
+::: affinity.services.v1_only.EntityFileService

{affinity_sdk-2.0.0 → affinity_sdk-2.0.1}/docs/public/reference/services/v1/notes.md

@@ -1,6 +1,6 @@
 # Notes
 
-Reads (`list`, `get`, `iter`) use V1; `list_v2`, `get_v2`, `list_replies`, `search` and the
+Reads by entity (`list`, `iter`) use V1; `get`, `feed`, `iter_feed`, `list_replies`, `search` and the
 writes (`create`, `update`, `delete`) use V2, which stores notes as HTML.
 
 ::: affinity.services.v1_only.NoteService

{affinity_sdk-2.0.0 → affinity_sdk-2.0.1}/mcp/.registry/commands.generated.json

@@ -2,11 +2,11 @@
   "_generated": {
     "warning": "DO NOT EDIT - This file is auto-generated",
     "generator": "tools/generate_mcp_command_registry.py",
-    "cliVersion": "2.0.0",
+    "cliVersion": "2.0.1",
     "sourceConfig": "mcp/.registry/mcp-commands.json"
   },
   "version": 1,
-  "cliVersion": "2.0.0",
+  "cliVersion": "2.0.1",
   "commands": [
     {
       "name": "company create",