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

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

@@ -58,3 +58,4 @@ tools/tmp_readonly_endpoint_syntax_suite.py
 tmp-scripts/set_primary_email_status.py
 test-output/
 CLAUDE.md
+.sandbox.env

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

@@ -5,6 +5,51 @@ All notable changes to this project will be documented in this file.
 The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.1.0/),
 and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
 
+## [Unreleased]
+
+## 0.9.11 - 2026-01-17
+
+### Added
+- CLI: Query `include` clause now displays included relationships inline by default. Use `--include-style=separate` for separate tables or `--include-style=ids-only` for raw IDs. JSON output includes full `included` and `included_by_parent` mappings for correlation.
+- CLI: Query `include` extended syntax for custom display fields: `include: {companies: {display: ["name", "domain"]}}`.
+- SDK: `with_interaction_dates` and `with_interaction_persons` parameters for `CompanyService.get()` and `PersonService.get()`. When enabled, routes to V1 API to fetch interaction date summaries (last/next meeting, email dates, team member IDs).
+- CLI: `--expand interactions` option for `list export` command. Adds interaction date summaries to each list entry (last meeting, next meeting, last email, last interaction with daysSince/daysUntil calculations and team member names). Supports both JSON and CSV output formats.
+- CLI: `expand: ["interactionDates"]` support in `query` command. Enriches records with interaction date summaries directly on each record in `result.data`. Works with `persons`, `companies`, and `listEntries` queries.
+- CLI: `--check-unreplied-emails` flag for `list export` command. Detects unreplied incoming emails for each list entry and adds date, daysSince, and subject to output. Use `--unreplied-lookback-days` to configure lookback period (default: 30 days).
+- CLI: `--with-interaction-dates` and `--with-interaction-persons` flags for `company get` and `person get` commands. Fetches interaction date summaries directly in entity get operations.
+- MCP: Query tool `format` parameter now functional (was previously ignored). Supports `toon`, `markdown`, `json`, `jsonl`, `csv`.
+- CLI: `--max-output-bytes` option for `query` command. Enables format-aware truncation for MCP use, returning exit code 100 when truncated.
+- CLI: `format_toon_envelope()` function for TOON output with full envelope (`data[N]{...}:`, `pagination:`, `included_*:` sections).
+- SDK: Batch association methods for PersonService, CompanyService, and OpportunityService:
+  - `get_associated_company_ids_batch(person_ids)` / `get_associated_opportunity_ids_batch(person_ids)`
+  - `get_associated_person_ids_batch(company_ids)` / `get_associated_opportunity_ids_batch(company_ids)`
+  - `get_associated_person_ids_batch(opportunity_ids)` / `get_associated_company_ids_batch(opportunity_ids)`
+  - All return `dict[EntityId, list[AssocId]]` with `on_error="raise"|"skip"` parameter.
+- SDK: `retries` parameter on `persons.get()`, `companies.get()`, and `opportunities.get()` methods. Enables automatic retry with exponential backoff on 404 errors to handle V1→V2 eventual consistency after create operations. Default is `retries=0` (fail fast).
+- CLI: Reminder date options now accept relative dates and keywords in addition to ISO-8601:
+  - `--due-date`: `+7d`, `+2w`, `+1m`, `+1y`, `today`, `tomorrow`, `yesterday`, `now`
+  - `--due-after`, `--due-before`: Same formats for filtering in `reminder ls`
+  - Example: `xaffinity reminder create --due-date +7d --type one-time --owner-id 123`
+- CLI: Domain validation for `company create` and `company update` now provides helpful error messages:
+  - Detects underscores (RFC 1035 violation) and suggests dash replacement
+  - Detects URL prefixes and extracts domain
+  - Example: `--domain test_company.com` → "Use 'test-company.com' instead"
+- Docs: V1→V2 eventual consistency guide covering 404 after create and stale data after update scenarios.
+- Tests: Integration test suite for SDK write operations (`tests/integration/`).
+
+### Changed
+- SDK: `OpportunityService.get_associated_people()` and `get_associated_companies()` now use V2 batch lookup instead of individual V1 fetches, reducing N+1 API calls (e.g., 50 people now fetched in 2 calls instead of 51).
+- SDK: Query executor `_batch_fetch_by_ids()` now uses V2 batch lookup for persons and companies, improving query performance on relationship includes.
+- CLI: Query `include` clause now fetches relationship IDs in parallel, then batch-fetches full records via V2 API, reducing API calls from N×M to N+1 for deduped lookups.
+
+### Changed (Breaking)
+- MCP: Query tool default format changed from `json` to `toon` for better token efficiency (~40% fewer tokens).
+- CLI: TOON query output now includes full envelope structure instead of data-only format. The `data` prefix is added to the array header: `data[N]{fields}:` instead of `[N]{fields}:`.
+
+### Fixed
+- MCP: Query tool now honors the `format` parameter instead of always using JSON output.
+- SDK: `ListEntryService.batch_update_fields()` now uses correct V2 API payload format. Previously failed with "Missing discriminator for property operation" error.
+
 ## 0.9.9 - 2026-01-14
 
 ### Added

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

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: affinity-sdk
-Version: 0.9.9
+Version: 0.9.11
 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-0.9.11/affinity/cli/__main__.py

@@ -0,0 +1,6 @@
+"""Enable running the CLI via `python -m affinity.cli`."""
+
+from affinity.cli.main import cli
+
+if __name__ == "__main__":
+    cli()

{affinity_sdk-0.9.9 → affinity_sdk-0.9.11}/affinity/cli/commands/_entity_files_dump.py

@@ -94,9 +94,9 @@ async def dump_entity_files_bundle(
                         break
                 if max_files is not None and produced >= max_files:
                     break
-                if not resp.next_page_token:
+                if not resp.next_cursor:
                     break
-                token = resp.next_page_token
+                token = resp.next_cursor
 
             for _ in range(workers):
                 await queue.put(None)

affinity_sdk-0.9.11/affinity/cli/commands/_v1_parsing.py

@@ -0,0 +1,186 @@
+from __future__ import annotations
+
+import json
+from collections.abc import Mapping
+from datetime import datetime, timezone
+from typing import Any, TypeVar
+
+from ..errors import CLIError
+from ..query.dates import is_relative_date, parse_relative_date
+
+T = TypeVar("T")
+
+
+def parse_choice(value: str | None, mapping: Mapping[str, T], *, label: str) -> T | None:
+    if value is None:
+        return None
+    key = value.strip().lower()
+    if key in mapping:
+        return mapping[key]
+    choices = ", ".join(sorted(mapping.keys()))
+    raise CLIError(
+        f"Unknown {label}: {value}",
+        error_type="usage_error",
+        exit_code=2,
+        hint=f"Choose one of: {choices}.",
+    )
+
+
+def validate_domain(value: str | None, *, label: str = "domain") -> str | None:
+    """
+    Validate domain format before API call.
+
+    Checks for common domain format mistakes that would be rejected by the
+    Affinity API with a cryptic error message. Validates against RFC 1035
+    constraints and common user errors.
+
+    Args:
+        value: Domain string to validate (or None)
+        label: Human-readable label for error messages
+
+    Returns:
+        The validated domain string (unchanged), or None if input was None
+
+    Raises:
+        CLIError: If domain format is invalid
+    """
+    if value is None:
+        return None
+
+    domain = value.strip()
+    if not domain:
+        return None
+
+    # Check for protocol prefix (common mistake)
+    if domain.startswith(("http://", "https://")):
+        # Extract domain from URL
+        clean = domain.split("//", 1)[1].split("/", 1)[0]
+        raise CLIError(
+            f"Invalid {label}: provide domain only, not URL",
+            error_type="usage_error",
+            exit_code=2,
+            hint=f"Use '{clean}' instead of '{value}'.",
+        )
+
+    # Check for underscores (RFC 1035 violation - most common issue)
+    if "_" in domain:
+        suggested = domain.replace("_", "-")
+        raise CLIError(
+            f"Invalid {label}: domains cannot contain underscores",
+            error_type="usage_error",
+            exit_code=2,
+            hint=f"Use '{suggested}' instead of '{domain}'.",
+        )
+
+    # Check for spaces
+    if " " in domain:
+        raise CLIError(
+            f"Invalid {label}: domains cannot contain spaces",
+            error_type="usage_error",
+            exit_code=2,
+            hint="Remove spaces from the domain.",
+        )
+
+    return domain
+
+
+def parse_iso_datetime(value: str, *, label: str) -> datetime:
+    """
+    Parse ISO-8601 datetime string to UTC-aware datetime.
+
+    Timezone handling:
+    - Explicit timezone (Z or offset): Respected, converted to UTC
+    - Naive string: Interpreted as LOCAL time, converted to UTC
+
+    This provides intuitive UX for CLI users who think in local time.
+
+    Examples (assuming user is in EST/UTC-5):
+        "2024-01-01"            → 2024-01-01T05:00:00Z (midnight EST)
+        "2024-01-01T12:00:00"   → 2024-01-01T17:00:00Z (noon EST)
+        "2024-01-01T12:00:00Z"  → 2024-01-01T12:00:00Z (explicit UTC)
+        "2024-01-01T12:00:00-05:00" → 2024-01-01T17:00:00Z (explicit EST)
+
+    Returns:
+        UTC-aware datetime object
+    """
+    raw = value.strip()
+    if raw.endswith("Z"):
+        raw = raw[:-1] + "+00:00"
+    try:
+        dt = datetime.fromisoformat(raw)
+    except ValueError as exc:
+        raise CLIError(
+            f"Invalid {label} datetime: {value}",
+            error_type="usage_error",
+            exit_code=2,
+            hint="Use ISO-8601, e.g. 2024-01-01, 2024-01-01T13:00:00, or 2024-01-01T13:00:00Z.",
+        ) from exc
+
+    # Convert to UTC
+    if dt.tzinfo is None:
+        # Naive datetime = local time
+        # astimezone() on naive datetime uses system timezone
+        dt = dt.astimezone()
+    return dt.astimezone(timezone.utc)
+
+
+def parse_date_flexible(
+    value: str,
+    *,
+    label: str,
+    now: datetime | None = None,
+) -> datetime:
+    """
+    Parse date string as either relative or ISO format.
+
+    Tries relative first (+7d, tomorrow), then ISO-8601.
+    Returns UTC-aware datetime.
+
+    Args:
+        value: Date string to parse
+        label: Human-readable label for error messages
+        now: Reference time for relative dates (default: current UTC)
+
+    Returns:
+        UTC-aware datetime
+
+    Raises:
+        CLIError: If value cannot be parsed as either format
+    """
+    # Validate non-empty
+    if not value or not value.strip():
+        raise CLIError(
+            f"Missing {label} date value",
+            error_type="usage_error",
+            exit_code=2,
+        )
+
+    # Try relative date first
+    if is_relative_date(value):
+        try:
+            return parse_relative_date(value, now=now, use_utc=True)
+        except ValueError:
+            pass  # Shouldn't happen if is_relative_date() returned True
+
+    # Fall back to ISO parsing, but wrap error with unified hint
+    try:
+        return parse_iso_datetime(value, label=label)
+    except CLIError:
+        raise CLIError(
+            f"Invalid {label} date: {value}",
+            error_type="usage_error",
+            exit_code=2,
+            hint="Use ISO-8601 (2026-01-01), relative (+7d, +2w), or keyword (today, tomorrow).",
+        ) from None
+
+
+def parse_json_value(value: str, *, label: str) -> Any:
+    try:
+        return json.loads(value)
+    except json.JSONDecodeError as exc:
+        raise CLIError(
+            f"Invalid JSON for {label}.",
+            error_type="usage_error",
+            exit_code=2,
+            hint='Provide a valid JSON literal (e.g. "\\"text\\"", 123, true, {"k": 1}).',
+        ) from exc

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

@@ -32,6 +32,7 @@ from ._list_entry_fields import (
     build_list_entry_field_rows,
     filter_list_entry_fields,
 )
+from ._v1_parsing import validate_domain
 from .resolve_url_cmd import _parse_affinity_url
 
 
@@ -484,7 +485,7 @@ def company_ls(
                     page_size=page_size,
                     page_token=cursor,
                 ):
-                    next_cursor = v1_page.next_page_token
+                    next_cursor = v1_page.next_cursor
                     prev_cursor = None  # V1 doesn't have prev cursor
 
                     if v1_page.data:
@@ -526,7 +527,7 @@ def company_ls(
                     page_size=page_size,
                     page_token=cursor,
                 ):
-                    next_cursor = search_page.next_page_token
+                    next_cursor = search_page.next_cursor
                     prev_cursor = None  # Search doesn't have prev cursor
 
                     for idx, company in enumerate(search_page.data):
@@ -717,7 +718,7 @@ def _resolve_company_by_domain(*, client: Any, domain: str) -> CompanyId:
                 matches.append(company)
                 if len(matches) >= 20:
                     break
-        if len(matches) >= 20 or not page.next_page_token:
+        if len(matches) >= 20 or not page.next_cursor:
             break
 
     if not matches:
@@ -758,7 +759,7 @@ def _resolve_company_by_name(*, client: Any, name: str) -> CompanyId:
                 matches.append(company)
                 if len(matches) >= 20:
                     break
-        if len(matches) >= 20 or not page.next_page_token:
+        if len(matches) >= 20 or not page.next_cursor:
             break
 
     if not matches:
@@ -915,7 +916,7 @@ def company_files_dump(
             ctx_modifiers["outDir"] = out_dir
         if overwrite:
             ctx_modifiers["overwrite"] = True
-        if concurrency != 4:
+        if concurrency != 3:
             ctx_modifiers["concurrency"] = concurrency
         if page_size != 100:
             ctx_modifiers["pageSize"] = page_size
@@ -1119,6 +1120,18 @@ def company_files_upload(
     is_flag=True,
     help="Fetch all pages for expansions (still capped by --max-results if set).",
 )
+@click.option(
+    "--with-interaction-dates",
+    "with_interaction_dates",
+    is_flag=True,
+    help="Include interaction date summaries (last/next meeting, email dates).",
+)
+@click.option(
+    "--with-interaction-persons",
+    "with_interaction_persons",
+    is_flag=True,
+    help="Include person IDs for each interaction (requires --with-interaction-dates).",
+)
 @output_options
 @click.pass_obj
 def company_get(
@@ -1136,6 +1149,8 @@ def company_get(
     list_entry_fields_scope: ListEntryFieldsScope,
     max_results: int | None,
     all_pages: bool,
+    with_interaction_dates: bool,
+    with_interaction_persons: bool,
 ) -> None:
     """
     Get a company by id, URL, domain, or name.
@@ -1359,6 +1374,8 @@ def company_get(
             company_id,
             field_ids=field_ids,
             field_types=field_types_param,
+            with_interaction_dates=with_interaction_dates,
+            with_interaction_persons=with_interaction_persons,
         )
         company_payload = serialize_model_for_cli(company)
         fields_raw = getattr(company, "fields_raw", None)
@@ -1744,11 +1761,13 @@ def company_create(
     """Create a company."""
 
     def fn(ctx: CLIContext, warnings: list[str]) -> CommandOutput:
+        validated_domain = validate_domain(domain, label="domain")
+
         client = ctx.get_client(warnings=warnings)
         created = client.companies.create(
             CompanyCreate(
                 name=name,
-                domain=domain,
+                domain=validated_domain,
                 person_ids=[PersonId(pid) for pid in person_ids],
             )
         )
@@ -1807,12 +1826,14 @@ def company_update(
                 error_type="usage_error",
                 hint="Use --name, --domain, or --person-id.",
             )
+        validated_domain = validate_domain(domain, label="domain")
+
         client = ctx.get_client(warnings=warnings)
         updated = client.companies.update(
             CompanyId(company_id),
             CompanyUpdate(
                 name=name,
-                domain=domain,
+                domain=validated_domain,
                 person_ids=[PersonId(pid) for pid in person_ids] if person_ids else None,
             ),
         )

{affinity_sdk-0.9.9 → affinity_sdk-0.9.11}/affinity/cli/commands/interaction_cmds.py

@@ -288,7 +288,7 @@ def _fetch_interactions_chunked(
                         chunks_processed=chunks_processed,
                     )
 
-            page_token = page.next_page_token
+            page_token = page.next_cursor
             if not page_token:
                 break