affinity-sdk 0.9.5__py3-none-any.whl

affinity/cli/results.py

@@ -0,0 +1,308 @@
+from __future__ import annotations
+
+from datetime import datetime
+from typing import Any
+
+from pydantic import Field
+
+from affinity.models.entities import AffinityModel
+from affinity.models.rate_limit_snapshot import RateLimitSnapshot
+
+
+class CommandContext(AffinityModel):
+    """Structured command context for reproducibility and debugging.
+
+    Attributes:
+        name: Command name (e.g., "person get", "list entry ls")
+        inputs: Required positional/named inputs that identify what was queried
+        modifiers: Optional flags/options that modify behavior
+        resolved: Human-readable names for IDs in inputs (optional)
+    """
+
+    name: str
+    inputs: dict[str, Any] = Field(default_factory=dict)
+    modifiers: dict[str, Any] = Field(default_factory=dict)
+    resolved: dict[str, str] | None = None
+
+    def format_header(self) -> str | None:
+        """Generate human-readable context header for CLI output.
+
+        Returns None for commands that don't need a header (e.g., whoami).
+        """
+        parts = self.name.split()
+        if len(parts) < 2:
+            return None
+
+        entity_type = parts[0]  # person, company, list, etc.
+        action = parts[1]  # get, ls, create, etc.
+
+        # Special case: no header for simple info commands
+        if self.name in ("whoami",):
+            return None
+
+        # Map entity types to display names
+        entity_names = {
+            "person": "Person",
+            "company": "Company",
+            "opportunity": "Opportunity",
+            "list": "List",
+            "field": "Field",
+            "field-value": "Field Value",
+            "field-value-changes": "Field Value Changes",
+            "note": "Note",
+            "interaction": "Interaction",
+            "reminder": "Reminder",
+            "relationship-strength": "Relationship Strength",
+            "entity-file": "Entity File",
+            "webhook": "Webhook",
+        }
+
+        display_name = entity_names.get(entity_type, entity_type.title())
+
+        # Handle "list entry" as a special case
+        if entity_type == "list" and len(parts) >= 3 and parts[1] == "entry":
+            display_name = "List Entry"
+            action = parts[2]
+
+        # Entity get commands
+        if action == "get":
+            return self._format_get_header(display_name)
+
+        # List commands
+        if action == "ls":
+            return self._format_ls_header(display_name)
+
+        # Create commands
+        if action == "create":
+            return self._format_create_header(display_name)
+
+        # Update/delete commands
+        if action in ("update", "delete"):
+            return self._format_mutation_header(display_name, action)
+
+        # Merge commands
+        if action == "merge":
+            return self._format_merge_header(display_name)
+
+        return None
+
+    def _format_get_header(self, display_name: str) -> str:
+        """Format header for get commands."""
+        # Check for selector or entity ID
+        if "selector" in self.inputs:
+            selector = self.inputs["selector"]
+            if self.resolved and "selector" in self.resolved:
+                return f'{display_name} "{self.resolved["selector"]}" ({selector})'
+            return f"{display_name} {selector}"
+
+        # Find the primary ID input
+        id_key = self._find_primary_id_key()
+        if id_key and id_key in self.inputs:
+            entity_id = self.inputs[id_key]
+            if self.resolved and id_key in self.resolved:
+                return f'{display_name} "{self.resolved[id_key]}" (ID {entity_id})'
+            return f"{display_name} ID {entity_id}"
+
+        return display_name
+
+    def _format_ls_header(self, display_name: str) -> str:
+        """Format header for ls commands."""
+        # Special case: relationship-strength with composite keys
+        if self.name == "relationship-strength ls":
+            internal = self.inputs.get("internalId")
+            external = self.inputs.get("externalId")
+            if internal and external:
+                return f"Relationship Strength: Person ID {internal} ↔ Person ID {external}"
+
+        # Check for primary scope input (e.g., listId for list entry ls)
+        scope_input = None
+        for key in ("listId", "entryId"):
+            if key in self.inputs:
+                scope_input = (key, self.inputs[key])
+                break
+
+        if scope_input:
+            key, value = scope_input
+            entity = key.replace("Id", "").title()
+            if self.resolved and key in self.resolved:
+                return f'{display_name}s: {entity} "{self.resolved[key]}"'
+            return f"{display_name}s: {entity} ID {value}"
+
+        # Check for modifier filters
+        filters = self._get_display_filters()
+        if not filters:
+            return f"{display_name}s"
+
+        # Check for primary entity filter (personId, companyId, etc.)
+        entity_filter_keys = ["personId", "companyId", "opportunityId"]
+        present_entity_filters = [ef for ef in entity_filter_keys if ef in filters]
+
+        # Single entity filter uses "for Entity ID X" pattern
+        if len(present_entity_filters) == 1:
+            ef = present_entity_filters[0]
+            entity = ef.replace("Id", "").title()
+            remaining = {k: v for k, v in filters.items() if k != ef}
+            base = f"{display_name}s for {entity} ID {self.modifiers[ef]}"
+            if remaining:
+                extra = self._format_filter_suffix(remaining)
+                return f"{base} ({extra})"
+            return base
+
+        # Multiple filters: use parenthetical format with shortened keys
+        filter_str = self._format_filter_suffix(filters)
+        return f"{display_name}s ({filter_str})"
+
+    def _format_create_header(self, display_name: str) -> str:
+        """Format header for create commands."""
+        # Check for scope input
+        if "listId" in self.inputs:
+            list_id = self.inputs["listId"]
+            if self.resolved and "listId" in self.resolved:
+                return f'{display_name} Create: List "{self.resolved["listId"]}"'
+            return f"{display_name} Create: List ID {list_id}"
+
+        if "type" in self.inputs:
+            return f"{display_name} Create (type: {self.inputs['type']})"
+
+        return f"{display_name} Create"
+
+    def _format_mutation_header(self, display_name: str, action: str) -> str:
+        """Format header for update/delete commands."""
+        id_key = self._find_primary_id_key()
+        if id_key and id_key in self.inputs:
+            entity_id = self.inputs[id_key]
+            if self.resolved and id_key in self.resolved:
+                resolved_name = self.resolved[id_key]
+                return f'{display_name} {action.title()}: "{resolved_name}" (ID {entity_id})'
+            return f"{display_name} {action.title()}: ID {entity_id}"
+        return f"{display_name} {action.title()}"
+
+    def _format_merge_header(self, display_name: str) -> str:
+        """Format header for merge commands."""
+        primary = self.inputs.get("primaryId")
+        duplicate = self.inputs.get("duplicateId")
+        if primary and duplicate:
+            return f"{display_name} Merge: ID {primary} ← ID {duplicate}"
+        return f"{display_name} Merge"
+
+    def _find_primary_id_key(self) -> str | None:
+        """Find the primary ID key in inputs."""
+        id_keys = [
+            "personId",
+            "companyId",
+            "opportunityId",
+            "listId",
+            "entryId",
+            "fieldId",
+            "fieldValueId",
+            "noteId",
+            "interactionId",
+            "reminderId",
+            "entityFileId",
+            "webhookId",
+        ]
+        for key in id_keys:
+            if key in self.inputs:
+                return key
+        return None
+
+    def _get_display_filters(self) -> dict[str, Any]:
+        """Get modifiers that should be displayed in headers (exclude pagination)."""
+        exclude = {"pageSize", "cursor", "maxResults", "allPages"}
+        return {k: v for k, v in self.modifiers.items() if k not in exclude and v is not None}
+
+    def _shorten_key(self, key: str) -> str:
+        """Shorten key names for display (personId → person)."""
+        if key.endswith("Id") and len(key) > 2:
+            return key[:-2]
+        return key
+
+    def _format_filter_suffix(self, filters: dict[str, Any], max_display: int = 2) -> str:
+        """Format filter dict as suffix string, truncating if needed."""
+        items = [(self._shorten_key(k), v) for k, v in filters.items()]
+        if len(items) <= max_display:
+            return ", ".join(f"{k}: {v}" for k, v in items)
+
+        displayed = items[:max_display]
+        remaining = len(items) - max_display
+        parts = [f"{k}: {v}" for k, v in displayed]
+        parts.append(f"+{remaining} more")
+        return ", ".join(parts)
+
+
+class DateRange(AffinityModel):
+    """Date range for time-bounded queries.
+
+    Display format: YYYY-MM-DD → YYYY-MM-DD (compact, for footer)
+    JSON format: Full ISO-8601 with timezone (via Pydantic serialization)
+    """
+
+    start: datetime
+    end: datetime
+
+    def format_display(self) -> str:
+        """Format as 'YYYY-MM-DD → YYYY-MM-DD' for human display."""
+        return f"{self.start.strftime('%Y-%m-%d')} → {self.end.strftime('%Y-%m-%d')}"
+
+
+class ResultSummary(AffinityModel):
+    """Metadata about query results - rendered as footer in table mode.
+
+    This is the standardized way to communicate summary information
+    about results. All commands should use this instead of ad-hoc
+    metadata dictionaries.
+
+    Attributes:
+        total_rows: Total number of rows in the result
+        date_range: For time-bounded queries (e.g., interaction ls)
+        type_breakdown: Count per type (e.g., {"email": 120, "call": 30})
+        included_counts: For query --include (e.g., {"companies": 10})
+        chunks_processed: For chunked fetches (interaction ls)
+        scanned_rows: For filtered queries (rows examined before filter)
+        custom_text: Escape hatch for one-off messages
+    """
+
+    total_rows: int | None = Field(None, alias="totalRows")
+    date_range: DateRange | None = Field(None, alias="dateRange")
+    type_breakdown: dict[str, int] | None = Field(None, alias="typeBreakdown")
+    included_counts: dict[str, int] | None = Field(None, alias="includedCounts")
+    chunks_processed: int | None = Field(None, alias="chunksProcessed")
+    scanned_rows: int | None = Field(None, alias="scannedRows")
+    custom_text: str | None = Field(None, alias="customText")
+
+
+class Artifact(AffinityModel):
+    type: str
+    path: str
+    path_is_relative: bool = Field(..., alias="pathIsRelative")
+    rows_written: int | None = Field(None, alias="rowsWritten")
+    bytes_written: int | None = Field(None, alias="bytesWritten")
+    partial: bool = False
+
+
+class ErrorInfo(AffinityModel):
+    type: str
+    message: str
+    hint: str | None = None
+    docs_url: str | None = Field(None, alias="docsUrl")
+    details: dict[str, Any] | None = None
+
+
+class CommandMeta(AffinityModel):
+    duration_ms: int = Field(..., alias="durationMs")
+    profile: str | None = None
+    resolved: dict[str, Any] | None = None
+    pagination: dict[str, Any] | None = None
+    columns: list[dict[str, Any]] | None = None
+    rate_limit: RateLimitSnapshot | None = Field(None, alias="rateLimit")
+    summary: ResultSummary | None = None
+
+
+class CommandResult(AffinityModel):
+    ok: bool
+    command: CommandContext
+    data: Any | None = None
+    artifacts: list[Artifact] = Field(default_factory=list)
+    warnings: list[str] = Field(default_factory=list)
+    meta: CommandMeta
+    error: ErrorInfo | None = None

affinity/cli/runner.py

@@ -0,0 +1,218 @@
+from __future__ import annotations
+
+import json
+import sys
+import time
+from collections.abc import Callable
+from dataclasses import dataclass
+from typing import Any
+
+from rich.console import Console
+
+from .click_compat import click
+from .context import (
+    CLIContext,
+    build_result,
+    error_info_for_exception,
+    exit_code_for_exception,
+    normalize_exception,
+)
+from .formatters import _empty_output, format_data
+from .render import RenderSettings, render_result
+from .results import Artifact, CommandContext, CommandResult, ResultSummary
+
+
+@dataclass(frozen=True, slots=True)
+class CommandOutput:
+    data: Any | None = None
+    context: CommandContext | None = None  # Structured command context
+    artifacts: list[Artifact] | None = None
+    warnings: list[str] | None = None
+    pagination: dict[str, Any] | None = None
+    resolved: dict[str, Any] | None = None
+    columns: list[dict[str, Any]] | None = None
+    rate_limit: Any | None = None
+    summary: ResultSummary | None = None  # Standardized result summary for footer
+    api_called: bool = False
+    exit_code: int = 0  # Allow commands to specify non-zero exit codes (e.g., check-key)
+
+
+def _emit_json(result: CommandResult) -> None:
+    payload = result.model_dump(by_alias=True, mode="json")
+    meta = payload.get("meta")
+    if isinstance(meta, dict) and meta.get("rateLimit") is None:
+        meta.pop("rateLimit", None)
+    sys.stdout.write(json.dumps(payload, ensure_ascii=False) + "\n")
+
+
+def _emit_warnings(*, ctx: CLIContext, warnings: list[str]) -> None:
+    if ctx.quiet:
+        return
+    if not warnings:
+        return
+    stderr = Console(file=sys.stderr, force_terminal=False)
+    for w in warnings:
+        stderr.print(f"Warning: {w}")
+
+
+def emit_result(ctx: CLIContext, result: CommandResult) -> None:
+    # JSON always uses full envelope (backwards compatible)
+    if ctx.output == "json":
+        _emit_json(result)
+        if ctx.verbosity >= 1 and not ctx.quiet and result.meta.rate_limit is not None:
+            stderr = Console(file=sys.stderr, force_terminal=False)
+            rl = result.meta.rate_limit
+            footer = []
+            if (
+                rl.api_key_per_minute.remaining is not None
+                and rl.api_key_per_minute.limit is not None
+            ):
+                footer.append(
+                    f"user {rl.api_key_per_minute.remaining}/{rl.api_key_per_minute.limit}"
+                )
+            if rl.org_monthly.remaining is not None and rl.org_monthly.limit is not None:
+                footer.append(f"org {rl.org_monthly.remaining}/{rl.org_monthly.limit}")
+            if footer:
+                stderr.print(f"rate-limit[{rl.source}]: " + " | ".join(footer))
+        return
+
+    # Table uses existing sophisticated render.py
+    if ctx.output == "table":
+        render_result(
+            result,
+            settings=RenderSettings(
+                output="table",
+                quiet=ctx.quiet,
+                verbosity=ctx.verbosity,
+                pager=ctx.pager,
+                all_columns=ctx.all_columns,
+                max_columns=ctx.max_columns,
+            ),
+        )
+        _emit_warnings(ctx=ctx, warnings=result.warnings)
+        if ctx.verbosity >= 1 and not ctx.quiet and result.meta.rate_limit is not None:
+            stderr = Console(file=sys.stderr, force_terminal=False)
+            rl = result.meta.rate_limit
+            parts: list[str] = []
+            if (
+                rl.api_key_per_minute.remaining is not None
+                and rl.api_key_per_minute.limit is not None
+            ):
+                parts.append(
+                    f"user {rl.api_key_per_minute.remaining}/{rl.api_key_per_minute.limit}"
+                )
+            if rl.org_monthly.remaining is not None and rl.org_monthly.limit is not None:
+                parts.append(f"org {rl.org_monthly.remaining}/{rl.org_monthly.limit}")
+            if parts:
+                extra = ""
+                if rl.request_id:
+                    extra = f" requestId={rl.request_id}"
+                stderr.print(f"rate-limit[{rl.source}]: " + " | ".join(parts) + extra)
+        return
+
+    # New formats: JSONL, Markdown, TOON, CSV
+    # These output DATA ONLY (no envelope) for token efficiency
+    if ctx.output in ("jsonl", "markdown", "toon", "csv"):
+        if not result.ok:
+            # Errors fall back to JSON envelope for structure
+            # Warn user about format change
+            if not ctx.quiet:
+                stderr = Console(file=sys.stderr, force_terminal=False)
+                stderr.print("Error occurred - output format changed to JSON for error details")
+            _emit_json(result)
+            return
+
+        data = result.data
+        if data is None:
+            sys.stdout.write(_empty_output(ctx.output) + "\n")
+            return
+
+        # Normalize to list of dicts
+        if isinstance(data, dict):
+            data = [data]
+        elif not isinstance(data, list):
+            # Non-tabular data falls back to JSON
+            if not ctx.quiet:
+                stderr = Console(file=sys.stderr, force_terminal=False)
+                stderr.print("Non-tabular data - output format changed to JSON")
+            _emit_json(result)
+            return
+
+        # Detect fieldnames: prefer meta.columns, fall back to first row keys
+        fieldnames: list[str] | None = None
+        if result.meta.columns and len(result.meta.columns) > 0:
+            fieldnames = [
+                c.get("name") or c.get("key") or f"col{i}"
+                for i, c in enumerate(result.meta.columns)
+            ]
+        if not fieldnames and data:
+            fieldnames = list(data[0].keys())
+
+        output = format_data(data, ctx.output, fieldnames=fieldnames)
+        sys.stdout.write(output + "\n")
+
+        # Warnings still go to stderr (consistent with table mode)
+        _emit_warnings(ctx=ctx, warnings=result.warnings)
+        return
+
+
+CommandFn = Callable[[CLIContext, list[str]], CommandOutput]
+
+
+def run_command(ctx: CLIContext, *, command: str, fn: CommandFn) -> None:
+    started = time.time()
+    warnings: list[str] = []
+    try:
+        out = fn(ctx, warnings)
+
+        rate_limit = out.rate_limit
+        if rate_limit is None and out.api_called and ctx._client is not None:
+            rate_limit = ctx._client.rate_limits.snapshot()
+
+        # Use provided context or create minimal one from command name
+        cmd_context = out.context or CommandContext(name=command)
+
+        result = build_result(
+            ok=True,
+            command=cmd_context,
+            started_at=started,
+            data=out.data,
+            artifacts=out.artifacts,
+            warnings=(out.warnings or warnings),
+            profile=ctx.profile,
+            rate_limit=rate_limit,
+            pagination=out.pagination,
+            resolved=out.resolved,
+            columns=out.columns,
+            summary=out.summary,
+        )
+        emit_result(ctx, result)
+        raise click.exceptions.Exit(out.exit_code)
+    except click.exceptions.Exit:
+        raise
+    except Exception as exc:
+        normalized = normalize_exception(exc, verbosity=ctx.verbosity)
+        code = exit_code_for_exception(normalized)
+        rate_limit = None
+        if ctx._client is not None:
+            try:
+                rate_limit = ctx._client.rate_limits.snapshot()
+            except Exception:
+                rate_limit = None
+
+        # Create minimal context for error case
+        cmd_context = CommandContext(name=command)
+
+        result = build_result(
+            ok=False,
+            command=cmd_context,
+            started_at=started,
+            data=None,
+            artifacts=None,
+            warnings=warnings,
+            profile=ctx.profile,
+            rate_limit=rate_limit,
+            error=error_info_for_exception(normalized, verbosity=ctx.verbosity),
+        )
+        emit_result(ctx, result)
+        raise click.exceptions.Exit(code) from exc

affinity/cli/serialization.py

@@ -0,0 +1,65 @@
+"""
+Standard serialization patterns for CLI commands.
+
+All CLI commands should use these helpers to ensure consistent JSON output.
+"""
+
+from __future__ import annotations
+
+from collections.abc import Sequence
+from typing import Any
+
+from pydantic import BaseModel
+
+
+def serialize_model_for_cli(model: BaseModel) -> dict[str, Any]:
+    """
+    Serialize a Pydantic model for CLI JSON output.
+
+    This is the standard serialization pattern for all CLI commands.
+    It ensures:
+    1. JSON-safe types (datetime → ISO string, etc.)
+    2. Consistent null handling (None values excluded)
+    3. Field aliases used (camelCase for API compatibility)
+
+    Args:
+        model: Any Pydantic model to serialize
+
+    Returns:
+        Dictionary suitable for JSON output
+
+    Example:
+        >>> from affinity.models.entities import Person
+        >>> person = Person(id=123, first_name="John", last_name="Doe", emails=[])
+        >>> result = serialize_model_for_cli(person)
+        >>> result['id']
+        123
+        >>> result['firstName']
+        'John'
+    """
+    return model.model_dump(by_alias=True, mode="json", exclude_none=True)
+
+
+def serialize_models_for_cli(models: Sequence[BaseModel]) -> list[dict[str, Any]]:
+    """
+    Serialize a sequence of Pydantic models for CLI JSON output.
+
+    Args:
+        models: Sequence of Pydantic models
+
+    Returns:
+        List of dictionaries suitable for JSON output
+
+    Example:
+        >>> from affinity.models.entities import Person
+        >>> people = [
+        ...     Person(id=1, first_name="Alice", last_name="Smith", emails=[]),
+        ...     Person(id=2, first_name="Bob", last_name="Jones", emails=[])
+        ... ]
+        >>> results = serialize_models_for_cli(people)
+        >>> len(results)
+        2
+        >>> results[0]['firstName']
+        'Alice'
+    """
+    return [serialize_model_for_cli(model) for model in models]