affinity-sdk 0.9.5__py3-none-any.whl

affinity/__init__.py

@@ -0,0 +1,139 @@
+"""
+Affinity Python SDK - A modern, strongly-typed wrapper for the Affinity CRM API.
+
+This SDK provides:
+- V2 terminology throughout (Company, not Organization)
+- V2 API for reads, V1 for writes where V2 isn't available
+- Strong typing with Pydantic V2 models
+- Typed ID classes to prevent type confusion (PersonId, CompanyId, etc.)
+- Automatic pagination iterators
+- Optional response caching for field metadata
+- Rate limit handling with automatic retry
+- Both sync and async clients
+
+Example:
+    ```python
+    from affinity import Affinity
+    from affinity.types import CompanyId, FieldId, FieldType, ListId, PersonId
+
+    # Initialize
+    with Affinity(api_key="your-key") as client:
+        # Iterate all companies with enriched data
+        for company in client.companies.all(field_types=[FieldType.ENRICHED]):
+            print(f"{company.name}: {company.domain}")
+
+        # Get a person with field values
+        person = client.persons.get(PersonId(12345))
+
+        # Add to a list and update fields
+        entries = client.lists.entries(ListId(789))
+        entry = entries.add_company(CompanyId(456))
+        entries.update_field_value(entry.id, FieldId(101), "New status")
+    ```
+"""
+
+from __future__ import annotations
+
+import logging
+from importlib.metadata import version as _get_version
+
+# Main client
+from . import models, types
+from .client import Affinity, AsyncAffinity
+
+# Exceptions
+from .exceptions import (
+    AffinityError,
+    AuthenticationError,
+    AuthorizationError,
+    CompanyNotFoundError,
+    ConfigurationError,
+    ConflictError,
+    EntityNotFoundError,
+    FilterParseError,
+    NetworkError,
+    NotFoundError,
+    OpportunityNotFoundError,
+    PersonNotFoundError,
+    PolicyError,
+    RateLimitError,
+    ServerError,
+    TimeoutError,
+    TooManyResultsError,
+    ValidationError,
+    VersionCompatibilityError,
+    WebhookInvalidJsonError,
+    WebhookInvalidPayloadError,
+    WebhookInvalidSentAtError,
+    WebhookMissingKeyError,
+    WebhookParseError,
+    WriteNotAllowedError,
+)
+
+# Filter builder (FR-007)
+from .filters import F, Filter, FilterExpression
+
+# Inbound webhook parsing helpers (optional)
+from .inbound_webhooks import BodyRegistry, WebhookEnvelope, dispatch_webhook, parse_webhook
+
+# Pagination helpers
+from .models.pagination import PaginationProgress
+
+# Policies
+from .policies import ExternalHookPolicy, Policies, WritePolicy
+
+__version__ = _get_version("affinity-sdk")
+
+_logger = logging.getLogger("affinity_sdk")
+if not any(isinstance(h, logging.NullHandler) for h in _logger.handlers):
+    _logger.addHandler(logging.NullHandler())
+
+__all__ = [
+    # Main clients
+    "Affinity",
+    "AsyncAffinity",
+    # Exceptions
+    "AffinityError",
+    "AuthenticationError",
+    "AuthorizationError",
+    "NotFoundError",
+    "EntityNotFoundError",
+    "PersonNotFoundError",
+    "CompanyNotFoundError",
+    "OpportunityNotFoundError",
+    "ValidationError",
+    "RateLimitError",
+    "ConflictError",
+    "ServerError",
+    "ConfigurationError",
+    "TimeoutError",
+    "NetworkError",
+    "PolicyError",
+    "WriteNotAllowedError",
+    "TooManyResultsError",
+    "VersionCompatibilityError",
+    "WebhookParseError",
+    "WebhookInvalidJsonError",
+    "WebhookInvalidPayloadError",
+    "WebhookMissingKeyError",
+    "WebhookInvalidSentAtError",
+    "FilterParseError",
+    # Filter builder
+    "Filter",
+    "FilterExpression",
+    "F",
+    # Inbound webhooks
+    "WebhookEnvelope",
+    "parse_webhook",
+    "dispatch_webhook",
+    "BodyRegistry",
+    # Policies
+    "WritePolicy",
+    "ExternalHookPolicy",
+    "Policies",
+    # Pagination helpers
+    "PaginationProgress",
+    # Type aliases (re-exported for convenience)
+    "types",
+    "models",
+]

affinity/cli/__init__.py

@@ -0,0 +1,7 @@
+"""
+Affinity CLI (optional).
+
+This package is only intended to be used when installing `affinity-sdk[cli]`.
+"""
+
+from __future__ import annotations

affinity/cli/click_compat.py

@@ -0,0 +1,27 @@
+from __future__ import annotations
+
+from typing import Any, cast
+
+try:
+    import click  # pyright: ignore[reportMissingImports]
+except ModuleNotFoundError as exc:  # pragma: no cover
+    raise ModuleNotFoundError(
+        'The Affinity CLI requires `click`. Install it with `pip install "affinity-sdk[cli]"`.'
+    ) from exc
+
+rich_click: Any
+try:
+    import rich_click as _rich_click  # pyright: ignore[reportMissingImports]
+except ModuleNotFoundError:  # pragma: no cover
+    rich_click = None
+else:
+    rich_click = _rich_click
+
+if rich_click is not None:  # pragma: no cover
+    RichGroup = cast(type[click.Group], rich_click.RichGroup)
+    RichCommand = cast(type[click.Command], rich_click.RichCommand)
+else:
+    RichGroup = click.Group
+    RichCommand = click.Command
+
+__all__ = ["RichCommand", "RichGroup", "click"]

affinity/cli/commands/__init__.py

@@ -0,0 +1 @@
+from __future__ import annotations

affinity/cli/commands/_entity_files_dump.py

@@ -0,0 +1,219 @@
+from __future__ import annotations
+
+import asyncio
+import json
+from pathlib import Path, PurePosixPath
+from typing import Any, TypedDict
+
+from affinity import AsyncAffinity
+from affinity.models.rate_limit_snapshot import RateLimitSnapshot
+from affinity.models.secondary import EntityFile
+
+from ..context import CLIContext
+from ..csv_utils import sanitize_filename
+from ..errors import CLIError
+from ..progress import ProgressManager, ProgressSettings
+from ..results import CommandContext
+from ..runner import CommandOutput
+
+
+class ManifestFile(TypedDict):
+    fileId: int
+    name: str
+    contentType: str | None
+    size: int
+    createdAt: str
+    uploaderId: int
+    path: str
+
+
+async def dump_entity_files_bundle(
+    *,
+    ctx: CLIContext,
+    warnings: list[str],
+    out_dir: str | None,
+    overwrite: bool,
+    concurrency: int,
+    page_size: int,
+    max_files: int | None,
+    default_dirname: str,
+    manifest_entity: dict[str, Any],
+    files_list_kwargs: dict[str, Any],
+    context: CommandContext | None = None,
+) -> CommandOutput:
+    """
+    Download all files for a single entity into a folder bundle with a manifest.
+
+    Notes:
+    - Uses a bounded worker pool (avoids spawning one task per file).
+    - Uses the same resolved client settings as sync commands (env/profile/flags).
+    """
+    settings = ctx.resolve_client_settings(warnings=warnings)
+
+    entity_dir = Path(out_dir) if out_dir is not None else (Path.cwd() / default_dirname)
+    files_dir = entity_dir / "files"
+    files_dir.mkdir(parents=True, exist_ok=True)
+
+    workers = max(1, int(concurrency))
+    queue: asyncio.Queue[EntityFile | None] = asyncio.Queue(maxsize=workers * 2)
+
+    manifest_files: list[ManifestFile] = []
+    rate_limit_snapshot: RateLimitSnapshot | None = None
+    task_lock = asyncio.Lock()
+    skipped_existing = 0
+    downloaded = 0
+    used_filenames: set[str] = set()
+
+    async with AsyncAffinity(
+        api_key=settings.api_key,
+        v1_base_url=settings.v1_base_url,
+        v2_base_url=settings.v2_base_url,
+        timeout=settings.timeout,
+        log_requests=settings.log_requests,
+        max_retries=settings.max_retries,
+        on_request=settings.on_request,
+        on_response=settings.on_response,
+        on_error=settings.on_error,
+        policies=settings.policies,
+    ) as async_client:
+
+        async def producer() -> None:
+            token: str | None = None
+            produced = 0
+            while True:
+                resp = await async_client.files.list(
+                    **files_list_kwargs,
+                    page_size=page_size,
+                    page_token=token,
+                )
+                for f in resp.data:
+                    await queue.put(f)
+                    produced += 1
+                    if max_files is not None and produced >= max_files:
+                        token = None
+                        break
+                if max_files is not None and produced >= max_files:
+                    break
+                if not resp.next_page_token:
+                    break
+                token = resp.next_page_token
+
+            for _ in range(workers):
+                await queue.put(None)
+
+        with ProgressManager(settings=ProgressSettings(mode=ctx.progress, quiet=ctx.quiet)) as pm:
+
+            async def worker() -> None:
+                nonlocal skipped_existing
+                nonlocal downloaded
+                while True:
+                    f = await queue.get()
+                    if f is None:
+                        return
+
+                    def choose_filename(name: str, file_id: int) -> str:
+                        candidate = sanitize_filename(name) or str(file_id)
+                        if candidate not in used_filenames:
+                            return candidate
+
+                        base = PurePosixPath(candidate)
+                        stem = base.stem or "file"
+                        suffix = base.suffix
+                        disambiguated = f"{stem}__{file_id}{suffix}"
+                        if disambiguated not in used_filenames:
+                            return disambiguated
+
+                        i = 2
+                        while True:
+                            alt = f"{stem}__{file_id}__{i}{suffix}"
+                            if alt not in used_filenames:
+                                return alt
+                            i += 1
+
+                    filename = choose_filename(f.name, int(f.id))
+                    used_filenames.add(filename)
+                    dest = files_dir / filename
+                    if dest.exists() and not overwrite:
+                        existing_size = dest.stat().st_size
+                        if f.size and existing_size != int(f.size):
+                            raise CLIError(
+                                (
+                                    "Refusing to skip existing file with size mismatch: "
+                                    f"{dest} (expected {int(f.size)} bytes, got {existing_size}); "
+                                    "use --overwrite to re-download."
+                                ),
+                                error_type="usage_error",
+                            )
+                        skipped_existing += 1
+                        manifest_files.append(
+                            {
+                                "fileId": int(f.id),
+                                "name": f.name,
+                                "contentType": f.content_type,
+                                "size": f.size,
+                                "createdAt": f.created_at.isoformat(),
+                                "uploaderId": int(f.uploader_id),
+                                "path": str(dest.relative_to(entity_dir)),
+                            }
+                        )
+                        continue
+                    async with task_lock:
+                        _task_id, cb = pm.task(
+                            description=f"download {f.name}",
+                            total_bytes=int(f.size) if f.size else None,
+                        )
+                    await async_client.files.download_to(
+                        f.id,
+                        dest,
+                        overwrite=overwrite,
+                        on_progress=cb,
+                        timeout=settings.timeout,
+                    )
+                    downloaded += 1
+                    manifest_files.append(
+                        {
+                            "fileId": int(f.id),
+                            "name": f.name,
+                            "contentType": f.content_type,
+                            "size": f.size,
+                            "createdAt": f.created_at.isoformat(),
+                            "uploaderId": int(f.uploader_id),
+                            "path": str(dest.relative_to(entity_dir)),
+                        }
+                    )
+
+            await asyncio.gather(
+                producer(),
+                *(worker() for _ in range(workers)),
+            )
+
+        if skipped_existing and not overwrite:
+            warnings.append(
+                f"Skipped {skipped_existing} existing file(s); use --overwrite to re-download."
+            )
+
+        manifest = {
+            "entity": manifest_entity,
+            "files": sorted(manifest_files, key=lambda x: x["fileId"]),
+        }
+        (entity_dir / "manifest.json").write_text(
+            json.dumps(manifest, ensure_ascii=False, indent=2) + "\n",
+            encoding="utf-8",
+        )
+
+        rate_limit_snapshot = async_client.rate_limits.snapshot()
+
+    data = {
+        "out": str(entity_dir),
+        "filesDownloaded": downloaded,
+        "filesSkippedExisting": skipped_existing,
+        "filesTotal": len(manifest_files),
+        "manifest": str((entity_dir / "manifest.json").relative_to(entity_dir)),
+    }
+    return CommandOutput(
+        data=data,
+        context=context,
+        warnings=warnings,
+        api_called=True,
+        rate_limit=rate_limit_snapshot,
+    )

affinity/cli/commands/_list_entry_fields.py

@@ -0,0 +1,41 @@
+from __future__ import annotations
+
+from typing import Any, Literal
+
+ListEntryFieldsScope = Literal["list-only", "all"]
+
+
+def _is_list_type(value: Any) -> bool:
+    if not isinstance(value, str):
+        return False
+    return value.strip().lower() == "list"
+
+
+def filter_list_entry_fields(
+    fields: list[Any],
+    *,
+    scope: ListEntryFieldsScope,
+) -> tuple[list[dict[str, Any]], int, int]:
+    field_dicts = [f for f in fields if isinstance(f, dict)]
+    total_count = len(field_dicts)
+    list_only = [f for f in field_dicts if _is_list_type(f.get("type"))]
+    list_only_count = len(list_only)
+
+    if scope == "list-only":
+        return list_only, list_only_count, total_count
+    return field_dicts, list_only_count, total_count
+
+
+def build_list_entry_field_rows(fields: list[dict[str, Any]]) -> list[dict[str, Any]]:
+    rows: list[dict[str, Any]] = []
+    for f in fields:
+        rows.append(
+            {
+                "id": f.get("id"),
+                "type": f.get("type"),
+                "enrichmentSource": f.get("enrichmentSource"),
+                "name": f.get("name"),
+                "value": f.get("value"),
+            }
+        )
+    return rows

affinity/cli/commands/_v1_parsing.py

@@ -0,0 +1,77 @@
+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
+
+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 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_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