affinity-sdk 0.9.5__py3-none-any.whl

affinity/cli/csv_utils.py

@@ -0,0 +1,195 @@
+from __future__ import annotations
+
+import csv
+import io
+import logging
+import re
+import sys
+from collections.abc import Iterable
+from dataclasses import dataclass
+from datetime import datetime
+from pathlib import Path
+from typing import Any
+
+# Import to_cell from formatters (single source of truth)
+# Re-exported here for backwards compatibility
+from .formatters import to_cell
+
+logger = logging.getLogger(__name__)
+
+# Re-export to_cell for any external consumers
+__all__ = ["to_cell", "CsvWriteResult", "write_csv", "write_csv_from_rows", "write_csv_to_stdout"]
+
+
+@dataclass(frozen=True, slots=True)
+class CsvWriteResult:
+    rows_written: int
+    bytes_written: int
+
+
+_FILENAME_SAFE = re.compile(r"[^A-Za-z0-9._-]+")
+
+
+def sanitize_filename(name: str, *, max_len: int = 180) -> str:
+    cleaned = _FILENAME_SAFE.sub("_", name).strip("._- ")
+    if not cleaned:
+        cleaned = "file"
+    if len(cleaned) > max_len:
+        cleaned = cleaned[:max_len]
+    return cleaned
+
+
+def write_csv(
+    *,
+    path: Path,
+    rows: Iterable[dict[str, Any]],
+    fieldnames: list[str],
+    bom: bool,
+) -> CsvWriteResult:
+    path.parent.mkdir(parents=True, exist_ok=True)
+    encoding = "utf-8-sig" if bom else "utf-8"
+    rows_written = 0
+
+    with path.open("w", newline="", encoding=encoding) as f:
+        writer = csv.DictWriter(f, fieldnames=fieldnames, extrasaction="ignore")
+        writer.writeheader()
+        for row in rows:
+            writer.writerow({k: to_cell(v) for k, v in row.items()})
+            rows_written += 1
+
+    bytes_written = path.stat().st_size
+    return CsvWriteResult(rows_written=rows_written, bytes_written=bytes_written)
+
+
+def artifact_path(path: Path) -> tuple[str, bool]:
+    """
+    Resolve artifact path to relative or absolute string.
+
+    Returns:
+        Tuple of (path_string, is_relative)
+    """
+    try:
+        rel = path.resolve().relative_to(Path.cwd().resolve())
+        return str(rel), True
+    except Exception:
+        return str(path.resolve()), False
+
+
+def write_csv_from_rows(
+    *,
+    path: Path,
+    rows: Iterable[dict[str, Any]],
+    bom: bool = False,
+) -> CsvWriteResult:
+    """
+    Write CSV from row dictionaries with auto-detected columns.
+
+    Detects column names from first row. Handles empty row lists gracefully.
+
+    Args:
+        path: Output CSV file path
+        rows: Iterable of dictionaries (must all have same keys)
+        bom: Whether to write UTF-8 BOM for Excel compatibility
+
+    Returns:
+        CsvWriteResult with row/byte counts
+
+    Example:
+        >>> rows = [{"id": 1, "name": "Alice"}, {"id": 2, "name": "Bob"}]
+        >>> write_csv_from_rows(path=Path("out.csv"), rows=rows)
+        CsvWriteResult(rows_written=2, bytes_written=42)
+    """
+    rows_list = list(rows)
+    if not rows_list:
+        # Write empty file (no headers - we don't know column names without data)
+        path.parent.mkdir(parents=True, exist_ok=True)
+        path.touch()
+        return CsvWriteResult(rows_written=0, bytes_written=0)
+
+    fieldnames = list(rows_list[0].keys())
+
+    return write_csv(
+        path=path,
+        rows=rows_list,
+        fieldnames=fieldnames,
+        bom=bom,
+    )
+
+
+def write_csv_to_stdout(
+    *,
+    rows: Iterable[dict[str, Any]],
+    fieldnames: list[str],
+    bom: bool,
+) -> int:
+    """
+    Write CSV data to stdout.
+
+    Uses TextIOWrapper around stdout.buffer for proper UTF-8 encoding on all platforms.
+    BOM is written when bom=True (useful for Excel compatibility when redirecting to file).
+
+    Args:
+        rows: Iterable of dictionaries to write
+        fieldnames: Column names for CSV header
+        bom: Whether to write UTF-8 BOM
+
+    Returns:
+        Number of rows written
+    """
+    encoding = "utf-8-sig" if bom else "utf-8"
+    stream = io.TextIOWrapper(sys.stdout.buffer, encoding=encoding, newline="")
+
+    writer = csv.DictWriter(stream, fieldnames=fieldnames, extrasaction="ignore")
+    writer.writeheader()
+    rows_written = 0
+    for row in rows:
+        writer.writerow({k: to_cell(v) for k, v in row.items()})
+        rows_written += 1
+
+    stream.flush()
+    stream.detach()  # Don't close stdout.buffer
+    return rows_written
+
+
+def localize_iso_string(value: str) -> str:
+    """
+    Convert ISO datetime string from UTC to local time.
+
+    Used for CSV output where human-readable local time is preferred.
+
+    Args:
+        value: ISO datetime string (e.g., "2024-01-01T05:00:00+00:00")
+
+    Returns:
+        Local time ISO string (e.g., "2024-01-01T00:00:00-05:00" for EST)
+        Returns input unchanged if not a valid datetime string.
+    """
+    try:
+        dt = datetime.fromisoformat(value.replace("Z", "+00:00"))
+        local = dt.astimezone()
+        return local.isoformat()
+    except (ValueError, AttributeError):
+        # Log at debug level - this is expected for non-datetime fields
+        logger.debug("Could not localize value as datetime: %r", value)
+        return value  # Return unchanged if not a valid datetime
+
+
+def localize_row_datetimes(
+    row: dict[str, Any],
+    datetime_fields: set[str],
+) -> dict[str, Any]:
+    """
+    Localize datetime fields in a row dictionary for CSV output.
+
+    Args:
+        row: Dictionary with field values
+        datetime_fields: Set of field names that contain datetime values
+
+    Returns:
+        New dictionary with datetime fields localized
+    """
+    result = dict(row)
+    for field in datetime_fields:
+        if field in result and isinstance(result[field], str):
+            result[field] = localize_iso_string(result[field])
+    return result

affinity/cli/date_utils.py

@@ -0,0 +1,42 @@
+"""Date utilities for CLI commands."""
+
+from __future__ import annotations
+
+from collections.abc import Iterator
+from dataclasses import dataclass
+from datetime import datetime, timedelta
+from typing import TYPE_CHECKING
+
+if TYPE_CHECKING:
+    from affinity.models.secondary import Interaction
+
+MAX_CHUNK_DAYS = 365
+
+
+@dataclass
+class ChunkedFetchResult:
+    """Result from chunked interaction fetching."""
+
+    interactions: list[Interaction]
+    chunks_processed: int
+
+
+def chunk_date_range(
+    start: datetime,
+    end: datetime,
+    max_days: int = MAX_CHUNK_DAYS,
+) -> Iterator[tuple[datetime, datetime]]:
+    """
+    Split a date range into chunks of max_days.
+
+    Yields (chunk_start, chunk_end) tuples.
+
+    Note: Relies on API using exclusive end_time boundary.
+    If an interaction has timestamp exactly at chunk boundary,
+    it will appear in the later chunk (not both).
+    """
+    current = start
+    while current < end:
+        chunk_end = min(current + timedelta(days=max_days), end)
+        yield (current, chunk_end)
+        current = chunk_end

affinity/cli/decorators.py

@@ -0,0 +1,77 @@
+"""Command decorators for CLI metadata.
+
+These decorators mark commands with metadata used by the JSON help generator
+for MCP tools and automation.
+"""
+
+from __future__ import annotations
+
+from collections.abc import Callable
+from typing import TypeVar
+
+from .click_compat import click
+
+F = TypeVar("F", bound=Callable[..., object])
+
+
+def destructive(cmd: click.Command) -> click.Command:
+    """Mark a command as destructive (data loss possible).
+
+    Destructive commands require explicit confirmation via --yes flag.
+
+    Usage:
+        @person_group.command(name="delete")
+        @destructive
+        @click.argument("person_id", type=int)
+        def person_delete(person_id: int) -> None:
+            ...
+    """
+    cmd.destructive = True  # type: ignore[attr-defined]
+    return cmd
+
+
+def category(cat: str) -> Callable[[click.Command], click.Command]:
+    """Tag command category ('read', 'write', or 'local').
+
+    Categories:
+        - read: Reads from Affinity API (safe, idempotent)
+        - write: Modifies Affinity data (requires caution)
+        - local: No API interaction (version, config, completion, etc.)
+
+    Usage:
+        @category("read")
+        @person_group.command(name="get")
+        def person_get(...) -> None:
+            ...
+
+    Args:
+        cat: One of "read", "write", or "local"
+    """
+    if cat not in ("read", "write", "local"):
+        raise ValueError(f"category must be 'read', 'write', or 'local', got {cat!r}")
+
+    def decorator(cmd: click.Command) -> click.Command:
+        cmd.category = cat  # type: ignore[attr-defined]
+        return cmd
+
+    return decorator
+
+
+def progress_capable(cmd: click.Command) -> click.Command:
+    """Mark a command as supporting progress reporting.
+
+    Commands marked with this decorator emit NDJSON progress to stderr
+    when not connected to a TTY, enabling MCP tools to forward progress.
+
+    Usage:
+        @person_group.command(name="files-upload")
+        @progress_capable
+        @click.argument("person_id", type=int)
+        @click.option("--file", required=True)
+        def files_upload(person_id: int, file: str) -> None:
+            ...
+
+    Note: Decorator order (bottom-up): def → options → progress_capable → command
+    """
+    cmd.progress_capable = True  # type: ignore[attr-defined]
+    return cmd

affinity/cli/errors.py

@@ -0,0 +1,28 @@
+from __future__ import annotations
+
+from typing import Any
+
+
+class CLIError(Exception):
+    def __init__(
+        self,
+        message: str,
+        *,
+        exit_code: int = 1,
+        error_type: str = "error",
+        details: dict[str, Any] | None = None,
+        hint: str | None = None,
+        docs_url: str | None = None,
+        cause: Exception | None = None,
+    ) -> None:
+        super().__init__(message)
+        self.message = message
+        self.exit_code = exit_code
+        self.error_type = error_type
+        self.details = details
+        self.hint = hint
+        self.docs_url = docs_url
+        self.cause = cause
+
+    def __str__(self) -> str:  # pragma: no cover
+        return self.message

affinity/cli/field_utils.py

@@ -0,0 +1,355 @@
+"""Utilities for field name resolution and field metadata management.
+
+This module provides shared helpers for resolving human-readable field names
+to field IDs across person/company/opportunity/list-entry commands.
+"""
+
+from __future__ import annotations
+
+from typing import TYPE_CHECKING, Any, Literal, cast
+
+from .errors import CLIError
+
+if TYPE_CHECKING:
+    from affinity.models.entities import FieldMetadata
+
+
+EntityType = Literal["person", "company", "opportunity", "list-entry"]
+
+
+def fetch_field_metadata(
+    *,
+    client: Any,
+    entity_type: EntityType,
+    list_id: int | None = None,
+) -> list[FieldMetadata]:
+    """Fetch field metadata for an entity type.
+
+    Args:
+        client: The Affinity client instance.
+        entity_type: Type of entity ("person", "company", "opportunity", "list-entry").
+        list_id: Required for opportunity and list-entry entity types.
+
+    Returns:
+        List of FieldMetadata objects.
+
+    Raises:
+        CLIError: If list_id is required but not provided.
+    """
+    from affinity.models.entities import FieldMetadata as FM
+
+    if entity_type == "person":
+        return cast(list[FM], client.persons.get_fields())
+    elif entity_type == "company":
+        return cast(list[FM], client.companies.get_fields())
+    elif entity_type in ("opportunity", "list-entry"):
+        if list_id is None:
+            raise CLIError(
+                f"list_id is required for {entity_type} field metadata.",
+                exit_code=2,
+                error_type="internal_error",
+            )
+        from affinity.types import ListId
+
+        return cast(list[FM], client.lists.get_fields(ListId(list_id)))
+    else:
+        raise CLIError(
+            f"Unknown entity type: {entity_type}",
+            exit_code=2,
+            error_type="internal_error",
+        )
+
+
+def build_field_id_to_name_map(fields: list[FieldMetadata]) -> dict[str, str]:
+    """Build a mapping from field ID to field name.
+
+    Args:
+        fields: List of FieldMetadata objects.
+
+    Returns:
+        Dictionary mapping field_id -> field_name.
+    """
+    result: dict[str, str] = {}
+    for field in fields:
+        field_id = str(field.id)
+        field_name = str(field.name) if field.name else ""
+        result[field_id] = field_name
+    return result
+
+
+def build_field_name_to_id_map(fields: list[FieldMetadata]) -> dict[str, list[str]]:
+    """Build a mapping from lowercase field name to field IDs.
+
+    Multiple fields can have the same name (case-insensitive), so this returns
+    a list of field IDs for each name.
+
+    Args:
+        fields: List of FieldMetadata objects.
+
+    Returns:
+        Dictionary mapping lowercase_name -> [field_id, ...].
+    """
+    result: dict[str, list[str]] = {}
+    for field in fields:
+        field_id = str(field.id)
+        field_name = str(field.name) if field.name else ""
+        if field_name:
+            result.setdefault(field_name.lower(), []).append(field_id)
+    return result
+
+
+class FieldResolver:
+    """Helper class for resolving field names to field IDs.
+
+    Provides case-insensitive field name resolution with proper error handling
+    for ambiguous or missing field names.
+    """
+
+    def __init__(self, fields: list[FieldMetadata]) -> None:
+        """Initialize the resolver with field metadata.
+
+        Args:
+            fields: List of FieldMetadata objects.
+        """
+        self._fields = fields
+        self._by_id = build_field_id_to_name_map(fields)
+        self._by_name = build_field_name_to_id_map(fields)
+
+    @property
+    def available_names(self) -> list[str]:
+        """Get list of available field names for error messages."""
+        names: list[str] = []
+        seen: set[str] = set()
+        for field in self._fields:
+            name = str(field.name) if field.name else ""
+            if name and name.lower() not in seen:
+                names.append(name)
+                seen.add(name.lower())
+        return sorted(names, key=str.lower)
+
+    def resolve_field_name_or_id(
+        self,
+        value: str,
+        *,
+        context: str = "field",
+    ) -> str:
+        """Resolve a field name or ID to a field ID.
+
+        If the value starts with "field-", it's treated as a field ID and validated.
+        Otherwise, it's treated as a field name and resolved case-insensitively.
+
+        Args:
+            value: Field name or field ID (e.g., "Phone" or "field-260415").
+            context: Context for error messages (e.g., "field" or "list-entry field").
+
+        Returns:
+            The resolved field ID.
+
+        Raises:
+            CLIError: If the field is not found or the name is ambiguous.
+        """
+        value = value.strip()
+        if not value:
+            raise CLIError(
+                f"Empty {context} name.",
+                exit_code=2,
+                error_type="usage_error",
+            )
+
+        # If starts with "field-", treat as field ID
+        if value.startswith("field-"):
+            if value not in self._by_id:
+                available = ", ".join(self.available_names[:10])
+                suffix = "..." if len(self.available_names) > 10 else ""
+                raise CLIError(
+                    f"Field ID '{value}' not found.",
+                    exit_code=2,
+                    error_type="not_found",
+                    hint=f"Available fields: {available}{suffix}",
+                )
+            return value
+
+        # Otherwise, resolve by name (case-insensitive)
+        matches = self._by_name.get(value.lower(), [])
+        if len(matches) == 1:
+            return matches[0]
+        if len(matches) > 1:
+            # Ambiguous - multiple fields with same name
+            details: list[dict[str, Any]] = []
+            for fid in matches[:10]:
+                details.append(
+                    {
+                        "fieldId": fid,
+                        "name": self._by_id.get(fid, ""),
+                    }
+                )
+            raise CLIError(
+                f"Ambiguous {context} name '{value}' matches {len(matches)} fields.",
+                exit_code=2,
+                error_type="ambiguous_resolution",
+                details={"name": value, "matches": details},
+                hint="Use --field-id with the specific field ID instead.",
+            )
+
+        # Not found
+        available = ", ".join(self.available_names[:10])
+        suffix = "..." if len(self.available_names) > 10 else ""
+        raise CLIError(
+            f"Field '{value}' not found.",
+            exit_code=2,
+            error_type="not_found",
+            hint=f"Available fields: {available}{suffix}",
+        )
+
+    def resolve_all_field_names_or_ids(
+        self,
+        updates: dict[str, Any],
+        *,
+        context: str = "field",
+    ) -> tuple[dict[str, Any], list[str]]:
+        """Resolve all field names/IDs in an updates dict to field IDs.
+
+        Validates ALL field names first and reports ALL errors at once.
+
+        Args:
+            updates: Dictionary of field_name_or_id -> value.
+            context: Context for error messages.
+
+        Returns:
+            Tuple of (resolved_updates, errors) where resolved_updates maps
+            field_id -> value and errors is a list of invalid field names.
+
+        Raises:
+            CLIError: If any field names are invalid (lists all invalid names).
+        """
+        resolved: dict[str, Any] = {}
+        invalid: list[str] = []
+
+        for key, value in updates.items():
+            key = key.strip()
+            if not key:
+                continue
+
+            # If starts with "field-", treat as field ID
+            if key.startswith("field-"):
+                if key not in self._by_id:
+                    invalid.append(key)
+                else:
+                    resolved[key] = value
+                continue
+
+            # Otherwise, resolve by name (case-insensitive)
+            matches = self._by_name.get(key.lower(), [])
+            if len(matches) == 1:
+                resolved[matches[0]] = value
+            elif len(matches) > 1:
+                # For batch updates, treat ambiguous as invalid
+                invalid.append(f"{key} (ambiguous: {', '.join(matches[:3])})")
+            else:
+                invalid.append(key)
+
+        if invalid:
+            available = ", ".join(self.available_names[:10])
+            suffix = "..." if len(self.available_names) > 10 else ""
+            raise CLIError(
+                f"Invalid {context}s: {', '.join(repr(n) for n in invalid)}.",
+                exit_code=2,
+                error_type="not_found",
+                hint=f"Available fields: {available}{suffix}",
+            )
+
+        return resolved, []
+
+    def get_field_name(self, field_id: str) -> str:
+        """Get the field name for a field ID.
+
+        Args:
+            field_id: The field ID.
+
+        Returns:
+            The field name, or empty string if not found.
+        """
+        return self._by_id.get(field_id, "")
+
+
+def validate_field_option_mutual_exclusion(
+    *,
+    field: str | None,
+    field_id: str | None,
+) -> None:
+    """Validate that exactly one of --field or --field-id is provided.
+
+    Args:
+        field: The --field option value.
+        field_id: The --field-id option value.
+
+    Raises:
+        CLIError: If neither or both options are provided.
+    """
+    if field is None and field_id is None:
+        raise CLIError(
+            "Must specify either --field or --field-id.",
+            exit_code=2,
+            error_type="usage_error",
+        )
+    if field is not None and field_id is not None:
+        raise CLIError(
+            "Use only one of --field or --field-id.",
+            exit_code=2,
+            error_type="usage_error",
+        )
+
+
+def find_field_values_for_field(
+    *,
+    field_values: list[dict[str, Any]],
+    field_id: str,
+) -> list[dict[str, Any]]:
+    """Find all field values matching a specific field ID.
+
+    Args:
+        field_values: List of field value dicts from the API.
+        field_id: The field ID to match.
+
+    Returns:
+        List of matching field value dicts.
+    """
+    matches: list[dict[str, Any]] = []
+    for fv in field_values:
+        fv_field_id = fv.get("fieldId") or fv.get("field_id")
+        if str(fv_field_id) == field_id:
+            matches.append(fv)
+    return matches
+
+
+def format_value_for_comparison(value: Any) -> str:
+    """Format a field value for string comparison.
+
+    Non-string values are serialized to their string representation.
+
+    Args:
+        value: The field value.
+
+    Returns:
+        String representation for comparison.
+    """
+    if value is None:
+        return ""
+    if isinstance(value, str):
+        return value
+    if isinstance(value, bool):
+        return str(value).lower()
+    if isinstance(value, (int, float)):
+        return str(value)
+    if isinstance(value, dict):
+        # Handle typed values like {type: "...", data: ...}
+        data = value.get("data")
+        if data is not None:
+            return format_value_for_comparison(data)
+        text = value.get("text") or value.get("name")
+        if text is not None:
+            return str(text)
+    if isinstance(value, list):
+        # For lists, join with comma
+        return ", ".join(format_value_for_comparison(v) for v in value)
+    return str(value)