affinity-sdk 0.9.11__tar.gz → 0.9.14__tar.gz

{affinity_sdk-0.9.11 → affinity_sdk-0.9.14}/.github/workflows/ci.yml

@@ -84,14 +84,19 @@ jobs:
             echo "Skipping traceability mapping (docs/internal not present in repo checkout)."
           fi
 
-      - name: CLI commands registry is valid
+      - name: MCP commands registry is valid
         run: |
           # Verify registry file exists and is valid JSON with expected structure
           python -c "
           import json
           import sys
-          with open('mcp/.registry/commands.json') as f:
+          with open('mcp/.registry/commands.generated.json') as f:
               data = json.load(f)
+          # Check _generated metadata (auto-generated indicator)
+          assert '_generated' in data, 'Missing _generated metadata'
+          assert 'generator' in data['_generated'], 'Missing generator in _generated'
+          assert 'cliVersion' in data['_generated'], 'Missing cliVersion in _generated'
+          # Check commands structure
           assert 'commands' in data, 'Missing commands key'
           assert isinstance(data['commands'], list), 'commands must be a list'
           assert len(data['commands']) > 0, 'commands list is empty'
@@ -99,11 +104,11 @@ jobs:
               assert 'name' in cmd, f'Command missing name: {cmd}'
               assert 'category' in cmd, f'Command {cmd[\"name\"]} missing category'
               assert cmd['category'] in ('read', 'write', 'local'), f'Invalid category for {cmd[\"name\"]}'
-          print(f'Registry valid: {len(data[\"commands\"])} commands')
+          print(f'Registry valid: {len(data[\"commands\"])} commands (v{data[\"_generated\"][\"cliVersion\"]})')
           "
           # Regenerate registry and verify it matches committed version
-          python tools/generate_cli_commands_registry.py
-          git diff --exit-code mcp/.registry/commands.json
+          python tools/generate_mcp_command_registry.py
+          git diff --exit-code mcp/.registry/commands.generated.json
 
   test-timezone:
     runs-on: ubuntu-latest

{affinity_sdk-0.9.11 → affinity_sdk-0.9.14}/.github/workflows/release.yml

@@ -159,8 +159,8 @@ jobs:
 
       - name: Verify registry is up to date
         run: |
-          python tools/generate_cli_commands_registry.py
-          git diff --exit-code mcp/.registry/commands.json
+          python tools/generate_mcp_command_registry.py
+          git diff --exit-code mcp/.registry/commands.generated.json
 
   build:
     runs-on: ubuntu-latest

{affinity_sdk-0.9.11 → affinity_sdk-0.9.14}/.gitignore

@@ -59,3 +59,4 @@ tmp-scripts/set_primary_email_status.py
 test-output/
 CLAUDE.md
 .sandbox.env
+tests/integration/query_parity_test_data.json

{affinity_sdk-0.9.11 → affinity_sdk-0.9.14}/.pre-commit-config.yaml

@@ -66,3 +66,10 @@ repos:
         language: python
         files: ^(mcp/VERSION|mcp/\.claude-plugin/plugin\.json|mcp/server\.d/server\.meta\.json)$
         pass_filenames: false
+      - id: pytest-pre-push
+        name: Run tests before push
+        entry: pytest tests/ -x -q --tb=short
+        language: system
+        pass_filenames: false
+        stages: [pre-push]
+        always_run: true

{affinity_sdk-0.9.11 → affinity_sdk-0.9.14}/CHANGELOG.md

@@ -7,6 +7,40 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 ## [Unreleased]
 
+## 0.9.14 - 2026-01-19
+
+### Fixed
+- CLI: Query `select` clause now automatically includes `expand` fields. Previously, using `select` with `expand` would filter out the expansion data (e.g., `interactionDates`, `unrepliedEmails`), requiring users to explicitly list expansions in `select`.
+
+## 0.9.13 - 2026-01-19
+
+### Added
+- CLI: Query `include` for `listEntries` now supports `persons`, `companies`, `opportunities`, and `interactions`. Fetches related entities based on list entry entity type (e.g., company entries get associated persons).
+- CLI: Query `expand: ["unrepliedEmails"]` now works with `listEntries`. Checks each list entry's underlying entity for unreplied incoming emails.
+- CLI: Query extended include syntax with parameters:
+  - `{include: {interactions: {limit: 50, days: 180}}}` - Limit and lookback control
+  - `{include: {opportunities: {list: "Pipeline"}}}` - Scope to specific opportunity list
+  - `{include: {persons: {where: {...}}}}` - Filter included entities
+
+### Fixed
+- CLI: Query TOON format now correctly flattens `fields.*` and `interactionDates` like markdown and CSV formats do. Previously, TOON was missing the `_apply_explicit_flattening()` call, causing nested fields to be truncated and interaction dates to be missing entirely.
+- CLI: `list export --check-unreplied-emails` now works standalone without requiring `--expand`.
+- CLI: `expand: ["interactionDates"]` now always produces 8 canonical columns regardless of data presence, ensuring consistent schema across all records.
+- SDK: Improved error message when adding wrong entity type to a list (e.g., adding a company to a person list). Now provides clear guidance about list type requirements instead of exposing raw API validation error.
+
+### Performance
+- CLI: Query `expand: ["interactionDates"]` is significantly faster with parallel person resolution, bounded concurrent fetches (semaphore=10), and parallelized section resolution. Default concurrency increased from 5 to 15 (tunable via `XAFFINITY_QUERY_CONCURRENCY`).
+
+## 0.9.12 - 2026-01-17
+
+### Changed
+- CLI: Query `listEntries` now normalizes reference field values to display strings:
+  - Person fields: `{"firstName": "Jane", "lastName": "Doe"}` → `"Jane Doe"`
+  - Company fields: `{"name": "Acme Corp", "id": 123}` → `"Acme Corp"`
+  - Multi-person/company fields: Arrays of names instead of raw objects
+  - Use `expand` or `include` for full entity data when needed
+- CLI: Query output with explicit `select` on `fields.*` paths now flattens fields to top-level columns in table/CSV/markdown formats. JSON output preserves nested structure.
+
 ## 0.9.11 - 2026-01-17
 
 ### Added
@@ -207,7 +241,15 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 - CLI: `--limit` alias for `--max-results` on all `ls` commands (LLM-friendly).
 - CLI: Option aliases now included in `--help --json` output.
 
-## 0.8.0 - Unreleased
+## 0.8.2 - 2026-01-10
+
+_No user-facing changes. Version bump for PyPI release._
+
+## 0.8.1 - 2026-01-10
+
+_No user-facing changes. Version bump for PyPI release._
+
+## 0.8.0 - 2026-01-10
 
 ### Changed
 - CLI: Renamed `--json` to `--set-json` on `person field`, `company field`, `opportunity field` commands to avoid conflict with global `--json` output flag.

{affinity_sdk-0.9.11 → affinity_sdk-0.9.14}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: affinity-sdk
-Version: 0.9.11
+Version: 0.9.14
 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/
@@ -126,6 +126,8 @@ Optional: install the CLI:
 pipx install "affinity-sdk[cli]"
 ```
 
+The CLI includes a powerful `query` command for structured data extraction with filtering, aggregations, and relationship includes. Output formats include JSON, CSV, markdown, and TOON (token-optimized for LLMs).
+
 CLI docs: https://yaniv-golan.github.io/affinity-sdk/latest/cli/
 
 ### MCP Server

{affinity_sdk-0.9.11 → affinity_sdk-0.9.14}/README.md

@@ -69,6 +69,8 @@ Optional: install the CLI:
 pipx install "affinity-sdk[cli]"
 ```
 
+The CLI includes a powerful `query` command for structured data extraction with filtering, aggregations, and relationship includes. Output formats include JSON, CSV, markdown, and TOON (token-optimized for LLMs).
+
 CLI docs: https://yaniv-golan.github.io/affinity-sdk/latest/cli/
 
 ### MCP Server

{affinity_sdk-0.9.11 → affinity_sdk-0.9.14}/affinity/cli/commands/company_cmds.py

@@ -1904,7 +1904,10 @@ def company_merge(
     primary_id: int,
     duplicate_id: int,
 ) -> None:
-    """Merge a duplicate company into a primary company (beta)."""
+    """Merge a duplicate company into a primary (beta).
+
+    Returns a taskUrl for tracking progress. Use 'task wait <url>' to wait for completion.
+    """
 
     def fn(ctx: CLIContext, warnings: list[str]) -> CommandOutput:
         client = ctx.get_client(warnings=warnings)

{affinity_sdk-0.9.11 → affinity_sdk-0.9.14}/affinity/cli/commands/list_cmds.py

@@ -1055,8 +1055,8 @@ def list_export(
                     ):
                         next_cursor = page_next_cursor
 
-                        if not want_expand:
-                            # No expansion - yield row as-is
+                        if not want_expand and not check_unreplied_emails:
+                            # No expansion and no unreplied email check - yield row as-is
                             rows_written += 1
                             if progress is not None and task_id is not None:
                                 filter_desc = _format_filter_progress(csv_iter_state)
@@ -1469,7 +1469,8 @@ def list_export(
             ):
                 next_cursor = page_next_cursor
 
-                if not want_expand:
+                if not want_expand and not check_unreplied_emails:
+                    # No expansion and no unreplied email check - add row as-is
                     rows.append(row)
                     if progress is not None and task_id is not None:
                         filter_desc = _format_filter_progress(table_iter_state)

{affinity_sdk-0.9.11 → affinity_sdk-0.9.14}/affinity/cli/commands/person_cmds.py

@@ -1763,7 +1763,10 @@ def person_merge(
     primary_id: int,
     duplicate_id: int,
 ) -> None:
-    """Merge a duplicate person into a primary person (beta)."""
+    """Merge a duplicate person into a primary (beta).
+
+    Returns a taskUrl for tracking progress. Use 'task wait <url>' to wait for completion.
+    """
 
     def fn(ctx: CLIContext, warnings: list[str]) -> CommandOutput:
         client = ctx.get_client(warnings=warnings)

{affinity_sdk-0.9.11 → affinity_sdk-0.9.14}/affinity/cli/commands/task_cmds.py

@@ -13,7 +13,19 @@ from ..serialization import serialize_model_for_cli
 
 @click.group(name="task", cls=RichGroup)
 def task_group() -> None:
-    """Task commands."""
+    """Poll async tasks (e.g., merges).
+
+    Some operations like 'company merge' and 'person merge' run asynchronously
+    and return a task URL. Use these commands to check status or wait for completion.
+
+    Example workflow:
+
+        xaffinity company merge 123 456 --json
+
+        # Returns {"taskUrl": "https://api.affinity.co/v2/tasks/..."}
+
+        xaffinity task wait "https://api.affinity.co/v2/tasks/..."
+    """
 
 
 def _task_payload(task: MergeTask) -> dict[str, object]:
@@ -26,7 +38,10 @@ def _task_payload(task: MergeTask) -> dict[str, object]:
 @output_options
 @click.pass_obj
 def task_get(ctx: CLIContext, task_url: str) -> None:
-    """Get task status."""
+    """Get current status of an async task.
+
+    Returns task status (pending, in_progress, success, failed) without waiting.
+    """
 
     def fn(ctx: CLIContext, warnings: list[str]) -> CommandOutput:
         client = ctx.get_client(warnings=warnings)
@@ -78,7 +93,11 @@ def task_wait(
     poll_interval: float,
     max_poll_interval: float,
 ) -> None:
-    """Wait for a task to complete."""
+    """Wait for an async task to complete.
+
+    Polls the task URL with exponential backoff until it reaches 'success' or 'failed'.
+    Returns the final task status. Raises an error if the task fails or times out.
+    """
 
     def fn(ctx: CLIContext, warnings: list[str]) -> CommandOutput:
         client = ctx.get_client(warnings=warnings)

{affinity_sdk-0.9.11 → affinity_sdk-0.9.14}/affinity/cli/interaction_utils.py

@@ -10,6 +10,7 @@ This module provides:
 
 from __future__ import annotations
 
+import asyncio
 import logging
 from datetime import datetime, timedelta, timezone
 from typing import TYPE_CHECKING, Any
@@ -270,13 +271,21 @@ async def _resolve_person_names_async(
     client: AsyncAffinity,
     person_ids: list[int],
     cache: dict[int, str] | None = None,
+    *,
+    person_semaphore: asyncio.Semaphore | None = None,
 ) -> list[str]:
     """Resolve person IDs to names asynchronously, using cache when available.
 
+    Person fetches run in parallel with bounded concurrency via a SHARED semaphore.
+
     Args:
         client: AsyncAffinity client for async API calls
         person_ids: List of person IDs to resolve
         cache: Optional dict cache (mutated in place). Thread-safe under CPython GIL.
+        person_semaphore: Optional SHARED semaphore for bounded concurrent fetches.
+            IMPORTANT: Pass the same semaphore across all calls to limit total
+            concurrent person API calls. Creating a new semaphore per call defeats
+            the bounded concurrency purpose.
 
     Returns:
         List of person names in same order as input IDs.
@@ -285,42 +294,56 @@ async def _resolve_person_names_async(
     if cache is None:
         cache = {}
 
-    names: list[str] = []
-    for pid in person_ids:
-        if pid in cache:
-            names.append(cache[pid])
-            continue
+    # NOTE: Benign race possible - two tasks may both see same ID as uncached
+    # before either updates cache. Result: duplicate fetch, correct final state.
+    uncached_ids = [pid for pid in person_ids if pid not in cache]
 
-        try:
-            # Fetch person name from API asynchronously
-            from affinity.types import PersonId
+    if uncached_ids:
+        # Use SHARED semaphore from caller, or create local fallback (for backwards compat)
+        sem = person_semaphore or asyncio.Semaphore(10)
 
-            person = await client.persons.get(PersonId(pid))
-            name = person.full_name or f"Person {pid}"
-            cache[pid] = name
-            names.append(name)
-        except Exception:
-            # Cache as fallback to avoid repeated failures
-            cache[pid] = f"Person {pid}"
-            names.append(f"Person {pid}")
+        async def fetch_person(pid: int) -> None:
+            async with sem:
+                try:
+                    from affinity.types import PersonId
 
-    return names
+                    person = await client.persons.get(PersonId(pid))
+                    name = person.full_name or f"Person {pid}"
+                    cache[pid] = name
+                except Exception:
+                    # Cache as fallback to avoid repeated failures
+                    cache[pid] = f"Person {pid}"
+
+        # PERF: Parallelize person fetches with bounded concurrency
+        await asyncio.gather(*[fetch_person(pid) for pid in uncached_ids])
+
+    # Return names in original order
+    return [cache.get(pid, f"Person {pid}") for pid in person_ids]
 
 
+# PERF: section_iteration_boundary
 async def resolve_interaction_names_async(
     client: AsyncAffinity,
     interaction_data: dict[str, Any] | None,
     cache: dict[int, str] | None = None,
+    *,
+    person_semaphore: asyncio.Semaphore | None = None,
 ) -> None:
     """Resolve teamMemberNames in transformed interaction data asynchronously.
 
     Mutates the interaction_data dict in place, adding teamMemberNames
     to any section that has teamMemberIds.
 
+    Sections (lastMeeting, nextMeeting, lastEmail) are resolved in parallel.
+    Person fetches within each section use a SHARED semaphore for bounded concurrency.
+
     Args:
         client: AsyncAffinity client for async API calls
         interaction_data: Transformed interaction data from transform_interaction_data()
         cache: Optional dict cache for person names (mutated in place)
+        person_semaphore: Optional SHARED semaphore for bounded person resolution.
+            If not provided, a local semaphore is created (not recommended for
+            multi-record expansion - pass shared semaphore from caller).
     """
     if interaction_data is None:
         return
@@ -328,16 +351,21 @@ async def resolve_interaction_names_async(
     if cache is None:
         cache = {}
 
-    # Process each section that may have teamMemberIds
-    for section_key in ("lastMeeting", "nextMeeting", "lastEmail"):
+    async def resolve_section(section_key: str) -> None:
+        """Resolve person names for a single section."""
         section = interaction_data.get(section_key)
         if section and "teamMemberIds" in section:
             person_ids = section["teamMemberIds"]
             if person_ids:
                 section["teamMemberNames"] = await _resolve_person_names_async(
-                    client, person_ids, cache
+                    client, person_ids, cache, person_semaphore=person_semaphore
                 )
 
+    # PERF: Parallelize over sections (lastMeeting, nextMeeting, lastEmail)
+    await asyncio.gather(
+        *[resolve_section(key) for key in ("lastMeeting", "nextMeeting", "lastEmail")]
+    )
+
 
 # =============================================================================
 # Unreplied Email Detection
@@ -436,6 +464,98 @@ def check_unreplied_email(
         return None
 
 
+async def async_check_unreplied_email(
+    client: AsyncAffinity,
+    entity_type: str | int,
+    entity_id: int,
+    lookback_days: int = 30,
+) -> dict[str, Any] | None:
+    """Async version: Check for unreplied incoming emails for an entity.
+
+    Supports person, company, and opportunity entity types.
+    Also handles V1 integer entityType formats (0=person, 1=company).
+
+    Args:
+        client: AsyncAffinity client for API calls
+        entity_type: "company", "person", "opportunity" (or V1 integers 0, 1)
+        entity_id: The entity ID
+        lookback_days: Number of days to look back for emails (default 30)
+
+    Returns:
+        Dict with unreplied email info if found, None otherwise.
+        Example: {
+            "date": "2026-01-10T10:00:00Z",
+            "daysSince": 5,
+            "subject": "Following up on our conversation",
+        }
+    """
+    from affinity.models.types import InteractionDirection, InteractionType
+    from affinity.types import CompanyId, OpportunityId, PersonId
+
+    try:
+        now = datetime.now(timezone.utc)
+        start_time = now - timedelta(days=lookback_days)
+
+        # Build entity-specific filter kwargs
+        # Handle V1 (integer) and V2 (string) entityType formats
+        iter_kwargs: dict[str, Any] = {
+            "type": InteractionType.EMAIL,
+            "start_time": start_time,
+            "end_time": now,
+        }
+
+        if entity_type in ("company", 1, "organization"):
+            iter_kwargs["company_id"] = CompanyId(entity_id)
+        elif entity_type in ("person", 0):
+            iter_kwargs["person_id"] = PersonId(entity_id)
+        elif entity_type == "opportunity":
+            iter_kwargs["opportunity_id"] = OpportunityId(entity_id)
+        else:
+            logger.debug(f"Unsupported entity type for unreplied email check: {entity_type}")
+            return None
+
+        # Fetch email interactions for the entity
+        emails = []
+        async for email in client.interactions.iter(**iter_kwargs):
+            emails.append(email)
+
+        if not emails:
+            return None
+
+        # Sort by date descending (most recent first)
+        emails.sort(key=lambda e: e.date, reverse=True)
+
+        # Find the most recent incoming email
+        last_incoming = None
+        for email in emails:
+            if email.direction == InteractionDirection.INCOMING:
+                last_incoming = email
+                break
+
+        if not last_incoming:
+            return None
+
+        # Check if there's an outgoing email after the last incoming
+        has_reply = any(
+            e.direction == InteractionDirection.OUTGOING and e.date > last_incoming.date
+            for e in emails
+        )
+
+        if has_reply:
+            return None
+
+        # Return unreplied email info
+        return {
+            "date": _format_datetime(last_incoming.date),
+            "daysSince": _days_since(last_incoming.date, now),
+            "subject": last_incoming.subject,
+        }
+
+    except Exception as e:
+        logger.warning(f"Failed to check unreplied emails for {entity_type} {entity_id}: {e}")
+        return None
+
+
 def flatten_unreplied_email_for_csv(unreplied: dict[str, Any] | None) -> dict[str, str]:
     """Flatten unreplied email data for CSV columns.