affinity-sdk 0.9.5__py3-none-any.whl

affinity/cli/resolve.py

@@ -0,0 +1,222 @@
+from __future__ import annotations
+
+from dataclasses import dataclass
+from typing import TYPE_CHECKING, Any
+
+from affinity import Affinity
+from affinity.exceptions import NotFoundError
+from affinity.models.entities import AffinityList, FieldMetadata, SavedView
+from affinity.types import ListId, SavedViewId
+
+from .errors import CLIError
+
+if TYPE_CHECKING:
+    from .session_cache import SessionCache
+
+
+@dataclass(frozen=True, slots=True)
+class ResolvedList:
+    list: AffinityList
+    resolved: dict[str, Any]
+
+
+def _looks_int(value: str) -> bool:
+    return value.isdigit()
+
+
+def resolve_list_selector(
+    *,
+    client: Affinity,
+    selector: str,
+    cache: SessionCache | None = None,
+) -> ResolvedList:
+    """Resolve list by name/ID with optional session cache support."""
+    selector = selector.strip()
+
+    # ID lookups don't benefit from name resolution cache
+    if _looks_int(selector):
+        list_id = ListId(int(selector))
+        lst = client.lists.get(list_id)
+        return ResolvedList(list=lst, resolved={"list": {"input": selector, "listId": int(lst.id)}})
+
+    cache_key = f"list_resolve_{selector.lower()}_any"
+
+    if cache and cache.enabled:
+        cached = cache.get(cache_key, AffinityList)
+        if cached is not None:
+            return ResolvedList(
+                list=cached,
+                resolved={"list": {"input": selector, "listId": int(cached.id), "cached": True}},
+            )
+
+    matches = client.lists.resolve_all(name=selector)
+    if not matches:
+        raise CLIError(
+            f'List not found: "{selector}"',
+            exit_code=4,
+            error_type="not_found",
+            details={"selector": selector},
+        )
+    if len(matches) > 1:
+        raise CLIError(
+            f'Ambiguous list name: "{selector}" ({len(matches)} matches)',
+            exit_code=2,
+            error_type="ambiguous_resolution",
+            details={
+                "selector": selector,
+                "matches": [
+                    {"listId": int(m.id), "name": m.name, "type": m.type} for m in matches[:20]
+                ],
+            },
+        )
+
+    lst = matches[0]
+
+    if cache and cache.enabled:
+        cache.set(cache_key, lst)
+
+    return ResolvedList(list=lst, resolved={"list": {"input": selector, "listId": int(lst.id)}})
+
+
+def resolve_saved_view(
+    *,
+    client: Affinity,
+    list_id: ListId,
+    selector: str,
+    cache: SessionCache | None = None,
+) -> tuple[SavedView, dict[str, Any]]:
+    selector = selector.strip()
+    if _looks_int(selector):
+        view_id = SavedViewId(int(selector))
+        try:
+            v = client.lists.get_saved_view(list_id, view_id)
+        except NotFoundError as exc:
+            raise CLIError(
+                f"Saved view not found: {selector}",
+                exit_code=4,
+                error_type="not_found",
+                details={"listId": int(list_id), "selector": selector},
+            ) from exc
+        return v, {
+            "savedView": {
+                "input": selector,
+                "savedViewId": int(v.id),
+                "name": v.name,
+            }
+        }
+
+    views = list_all_saved_views(client=client, list_id=list_id, cache=cache)
+    exact = [v for v in views if v.name.lower() == selector.lower()]
+    if not exact:
+        raise CLIError(
+            f'Saved view not found: "{selector}"',
+            exit_code=4,
+            error_type="not_found",
+            details={"listId": int(list_id), "selector": selector},
+        )
+    if len(exact) > 1:
+        raise CLIError(
+            f'Ambiguous saved view name: "{selector}"',
+            exit_code=2,
+            error_type="ambiguous_resolution",
+            details={
+                "listId": int(list_id),
+                "selector": selector,
+                "matches": [{"savedViewId": int(v.id), "name": v.name} for v in exact[:20]],
+            },
+        )
+    v = exact[0]
+    return v, {"savedView": {"input": selector, "savedViewId": int(v.id), "name": v.name}}
+
+
+def list_all_saved_views(
+    *,
+    client: Affinity,
+    list_id: ListId,
+    cache: SessionCache | None = None,
+) -> list[SavedView]:
+    """Get saved views for a list with optional session cache support.
+
+    Note: This caches the full list of saved views. If the fetch is
+    interrupted mid-pagination, the cache won't be populated.
+    """
+    cache_key = f"saved_views_{list_id}"
+
+    if cache and cache.enabled:
+        cached = cache.get_list(cache_key, SavedView)
+        if cached is not None:
+            return cached
+
+    # Eagerly evaluate paginated iterator to cache complete list
+    # Note: If pagination is interrupted (e.g., network error), no partial
+    # result is cached - the next call will retry from scratch
+    views = list(client.lists.saved_views_all(list_id))
+
+    if cache and cache.enabled:
+        cache.set(cache_key, views)
+
+    return views
+
+
+def list_fields_for_list(
+    *,
+    client: Affinity,
+    list_id: ListId,
+    cache: SessionCache | None = None,
+) -> list[FieldMetadata]:
+    """Get list fields with optional session cache support."""
+    cache_key = f"list_fields_{list_id}"
+
+    if cache and cache.enabled:
+        cached = cache.get_list(cache_key, FieldMetadata)
+        if cached is not None:
+            return cached
+
+    fields = client.lists.get_fields(list_id)
+
+    if cache and cache.enabled:
+        cache.set(cache_key, fields)
+
+    return fields
+
+
+def get_person_fields(
+    *,
+    client: Affinity,
+    cache: SessionCache | None = None,
+) -> list[FieldMetadata]:
+    """Get global person fields with optional session cache support."""
+    cache_key = "person_fields_global"
+
+    if cache and cache.enabled:
+        cached = cache.get_list(cache_key, FieldMetadata)
+        if cached is not None:
+            return cached
+
+    fields = client.persons.get_fields()
+
+    if cache and cache.enabled:
+        cache.set(cache_key, fields)
+
+    return fields
+
+
+def get_company_fields(
+    *,
+    client: Affinity,
+    cache: SessionCache | None = None,
+) -> list[FieldMetadata]:
+    """Get global company fields with optional session cache support."""
+    cache_key = "company_fields_global"
+
+    if cache and cache.enabled:
+        cached = cache.get_list(cache_key, FieldMetadata)
+        if cached is not None:
+            return cached
+
+    fields = client.companies.get_fields()
+
+    if cache and cache.enabled:
+        cache.set(cache_key, fields)
+
+    return fields

affinity/cli/resolvers.py

@@ -0,0 +1,249 @@
+"""
+Standard resolver types for CLI commands.
+
+These dataclasses provide consistent structure for resolved metadata,
+ensuring all CLI commands follow the same patterns when resolving
+user inputs (IDs, URLs, emails, names, etc.) to API parameters.
+"""
+
+from __future__ import annotations
+
+from dataclasses import asdict, dataclass
+from typing import Any, Literal
+
+
+@dataclass(frozen=True, slots=True)
+class ResolvedEntity:
+    """
+    Standard structure for entity resolution metadata.
+
+    This class represents how a user's input selector (ID, URL, email, name)
+    was resolved to an entity ID for API calls.
+
+    Attributes:
+        input: The original user input (e.g., "john@example.com", "123", "acme.com")
+        entity_id: The resolved numeric entity ID
+        entity_type: Type of entity (person, company, opportunity, list)
+        source: How the input was resolved (id, url, email, name, domain)
+        canonical_url: Optional canonical Affinity URL for the entity
+
+    Example:
+        >>> resolved = ResolvedEntity(
+        ...     input="john@example.com",
+        ...     entity_id=12345,
+        ...     entity_type="person",
+        ...     source="email",
+        ...     canonical_url="https://app.affinity.co/persons/12345"
+        ... )
+        >>> resolved.to_dict()
+        {
+            'input': 'john@example.com',
+            'personId': 12345,
+            'source': 'email',
+            'canonicalUrl': 'https://app.affinity.co/persons/12345'
+        }
+    """
+
+    input: str
+    entity_id: int
+    entity_type: Literal["person", "company", "opportunity", "list"]
+    source: Literal["id", "url", "email", "name", "domain"]
+    canonical_url: str | None = None
+
+    def to_dict(self) -> dict[str, Any]:
+        """
+        Convert to dict for resolved metadata.
+
+        Returns a dictionary suitable for inclusion in CommandOutput.resolved,
+        with entity_id renamed to {entityType}Id (e.g., personId, companyId).
+        """
+        data = asdict(self)
+        # Rename entity_id to {entityType}Id
+        entity_id = data.pop("entity_id")
+        data[f"{self.entity_type}Id"] = entity_id
+        # Remove entity_type from output (it's redundant with the key name)
+        data.pop("entity_type", None)
+        # Convert snake_case to camelCase for canonical_url
+        if "canonical_url" in data and data["canonical_url"] is not None:
+            data["canonicalUrl"] = data.pop("canonical_url")
+        elif "canonical_url" in data:
+            data.pop("canonical_url")
+        return data
+
+
+@dataclass(frozen=True, slots=True)
+class ResolvedFieldSelection:
+    """
+    Field selection resolution metadata.
+
+    This class represents which fields were requested by the user
+    through --field-id or --field-type flags.
+
+    Attributes:
+        field_ids: List of specific field IDs requested (e.g., ["field-123", "field-456"])
+        field_types: List of field types requested (e.g., ["global", "enriched"])
+
+    Example:
+        >>> resolved = ResolvedFieldSelection(
+        ...     field_ids=["field-123"],
+        ...     field_types=["global", "enriched"]
+        ... )
+        >>> resolved.to_dict()
+        {'fieldIds': ['field-123'], 'fieldTypes': ['global', 'enriched']}
+    """
+
+    field_ids: list[str] | None = None
+    field_types: list[str] | None = None
+
+    def to_dict(self) -> dict[str, Any]:
+        """
+        Convert to dict, excluding None values.
+
+        Returns a dictionary with camelCase field names, omitting any
+        fields that are None.
+        """
+        result = {}
+        if self.field_ids is not None:
+            result["fieldIds"] = self.field_ids
+        if self.field_types is not None:
+            result["fieldTypes"] = self.field_types
+        return result
+
+
+@dataclass(frozen=True, slots=True)
+class ResolvedList:
+    """
+    List resolution metadata.
+
+    This class represents how a user's list selector (ID, URL, name)
+    was resolved to a list ID.
+
+    Attributes:
+        input: The original user input
+        list_id: The resolved numeric list ID
+        source: How the input was resolved (id, url, name)
+
+    Example:
+        >>> resolved = ResolvedList(
+        ...     input="Sales Pipeline",
+        ...     list_id=789,
+        ...     source="name"
+        ... )
+        >>> resolved.to_dict()
+        {'input': 'Sales Pipeline', 'listId': 789, 'source': 'name'}
+    """
+
+    input: str
+    list_id: int
+    source: Literal["id", "url", "name"]
+
+    def to_dict(self) -> dict[str, Any]:
+        """Convert to dict with camelCase field names."""
+        return {
+            "input": self.input,
+            "listId": self.list_id,
+            "source": self.source,
+        }
+
+
+@dataclass(frozen=True, slots=True)
+class ResolvedSavedView:
+    """
+    Saved view resolution metadata.
+
+    This class represents how a user's saved view selector was resolved
+    to a saved view ID.
+
+    Attributes:
+        input: The original user input
+        saved_view_id: The resolved numeric saved view ID
+        name: The name of the saved view
+
+    Example:
+        >>> resolved = ResolvedSavedView(
+        ...     input="Active Deals",
+        ...     saved_view_id=456,
+        ...     name="Active Deals"
+        ... )
+        >>> resolved.to_dict()
+        {'input': 'Active Deals', 'savedViewId': 456, 'name': 'Active Deals'}
+    """
+
+    input: str
+    saved_view_id: int
+    name: str
+
+    def to_dict(self) -> dict[str, Any]:
+        """Convert to dict with camelCase field names."""
+        return {
+            "input": self.input,
+            "savedViewId": self.saved_view_id,
+            "name": self.name,
+        }
+
+
+def build_resolved_metadata(
+    *,
+    entity: ResolvedEntity | None = None,
+    list_resolution: ResolvedList | None = None,
+    saved_view: ResolvedSavedView | None = None,
+    field_selection: ResolvedFieldSelection | None = None,
+    expand: list[str] | None = None,
+) -> dict[str, Any]:
+    """
+    Build a complete resolved metadata dict for CommandOutput.
+
+    This is a convenience function to construct the resolved metadata
+    dictionary in a consistent way across all commands.
+
+    Args:
+        entity: Entity resolution metadata (person, company, opportunity)
+        list_resolution: List resolution metadata
+        saved_view: Saved view resolution metadata
+        field_selection: Field selection metadata
+        expand: List of expansion options used
+
+    Returns:
+        Dictionary suitable for CommandOutput(resolved=...)
+
+    Example:
+        >>> person = ResolvedEntity(
+        ...     input="john@example.com",
+        ...     entity_id=12345,
+        ...     entity_type="person",
+        ...     source="email"
+        ... )
+        >>> fields = ResolvedFieldSelection(field_types=["global"])
+        >>> resolved = build_resolved_metadata(
+        ...     entity=person,
+        ...     field_selection=fields,
+        ...     expand=["lists"]
+        ... )
+        >>> resolved
+        {
+            'person': {'input': 'john@example.com', 'personId': 12345, 'source': 'email'},
+            'fieldSelection': {'fieldTypes': ['global']},
+            'expand': ['lists']
+        }
+    """
+    result: dict[str, Any] = {}
+
+    if entity is not None:
+        # Use entity_type as the key (e.g., "person", "company")
+        result[entity.entity_type] = entity.to_dict()
+
+    if list_resolution is not None:
+        result["list"] = list_resolution.to_dict()
+
+    if saved_view is not None:
+        result["savedView"] = saved_view.to_dict()
+
+    if field_selection is not None:
+        field_dict = field_selection.to_dict()
+        if field_dict:  # Only include if not empty
+            result["fieldSelection"] = field_dict
+
+    if expand is not None and expand:
+        result["expand"] = expand
+
+    return result