affinity-sdk 0.9.5__py3-none-any.whl

affinity/cli/commands/resolve_url_cmd.py

@@ -0,0 +1,127 @@
+from __future__ import annotations
+
+import re
+from dataclasses import dataclass
+from typing import Literal
+from urllib.parse import urlparse
+
+from affinity.types import CompanyId, ListEntryId, ListId, OpportunityId, PersonId
+
+from ..click_compat import RichCommand, click
+from ..context import CLIContext
+from ..decorators import category
+from ..errors import CLIError
+from ..options import output_options
+from ..runner import CommandOutput, run_command
+
+ResolvedType = Literal["person", "company", "opportunity", "list", "list_entry"]
+
+
+@dataclass(frozen=True, slots=True)
+class ResolvedUrl:
+    type: ResolvedType
+    person_id: int | None = None
+    company_id: int | None = None
+    opportunity_id: int | None = None
+    list_id: int | None = None
+    list_entry_id: int | None = None
+
+
+_ENTITY_RE = re.compile(r"^/(persons|companies|opportunities)/(\d+)$")
+_LIST_RE = re.compile(r"^/lists/(\d+)$")
+_LIST_ENTRY_RE = re.compile(r"^/lists/(\d+)/entries/(\d+)$")
+
+
+def _parse_affinity_url(url: str) -> ResolvedUrl:
+    parsed = urlparse(url)
+    if parsed.scheme not in {"http", "https"}:
+        raise CLIError(
+            "URL must start with http:// or https://", exit_code=2, error_type="usage_error"
+        )
+    host = (parsed.hostname or "").lower()
+    if (
+        host not in {"app.affinity.co", "app.affinity.com"}
+        and not host.endswith(".affinity.co")
+        and not host.endswith(".affinity.com")
+    ):
+        raise CLIError(
+            "Not an Affinity UI URL (expected *.affinity.co or *.affinity.com)",
+            exit_code=2,
+            error_type="usage_error",
+        )
+
+    path = parsed.path.rstrip("/")
+    if m := _ENTITY_RE.match(path):
+        kind, raw_id = m.group(1), m.group(2)
+        entity_id = int(raw_id)
+        if kind == "persons":
+            return ResolvedUrl(type="person", person_id=entity_id)
+        if kind == "companies":
+            return ResolvedUrl(type="company", company_id=entity_id)
+        return ResolvedUrl(type="opportunity", opportunity_id=entity_id)
+    if m := _LIST_ENTRY_RE.match(path):
+        return ResolvedUrl(
+            type="list_entry",
+            list_id=int(m.group(1)),
+            list_entry_id=int(m.group(2)),
+        )
+    if m := _LIST_RE.match(path):
+        return ResolvedUrl(type="list", list_id=int(m.group(1)))
+
+    raise CLIError("Unrecognized Affinity URL path.", exit_code=2, error_type="usage_error")
+
+
+@category("read")
+@click.command(name="resolve-url", cls=RichCommand)
+@click.argument("url", type=str)
+@output_options
+@click.pass_obj
+def resolve_url_cmd(ctx: CLIContext, url: str) -> None:
+    """Resolve an Affinity UI URL to entity type and IDs."""
+
+    def fn(ctx: CLIContext, warnings: list[str]) -> CommandOutput:
+        resolved = _parse_affinity_url(url)
+        client = ctx.get_client(warnings=warnings)
+
+        # Validate existence/permissions via SDK.
+        if resolved.type == "person":
+            _ = client.persons.get(PersonId(resolved.person_id or 0))
+        elif resolved.type == "company":
+            _ = client.companies.get(CompanyId(resolved.company_id or 0))
+        elif resolved.type == "opportunity":
+            _ = client.opportunities.get(OpportunityId(resolved.opportunity_id or 0))
+        elif resolved.type == "list":
+            _ = client.lists.get(ListId(resolved.list_id or 0))
+        else:
+            _ = client.lists.entries(ListId(resolved.list_id or 0)).get(
+                ListEntryId(resolved.list_entry_id or 0)
+            )
+
+        data = {
+            "type": resolved.type,
+            "personId": resolved.person_id,
+            "companyId": resolved.company_id,
+            "opportunityId": resolved.opportunity_id,
+            "listId": resolved.list_id,
+            "listEntryId": resolved.list_entry_id,
+            "canonicalUrl": _canonical_url(resolved),
+        }
+        return CommandOutput(
+            data={k: v for k, v in data.items() if v is not None},
+            warnings=warnings,
+            api_called=True,
+        )
+
+    run_command(ctx, command="resolve-url", fn=fn)
+
+
+def _canonical_url(resolved: ResolvedUrl) -> str:
+    if resolved.type == "person":
+        return f"https://app.affinity.co/persons/{resolved.person_id}"
+    if resolved.type == "company":
+        return f"https://app.affinity.co/companies/{resolved.company_id}"
+    if resolved.type == "opportunity":
+        return f"https://app.affinity.co/opportunities/{resolved.opportunity_id}"
+    if resolved.type == "list":
+        return f"https://app.affinity.co/lists/{resolved.list_id}"
+    return f"https://app.affinity.co/lists/{resolved.list_id}/entries/{resolved.list_entry_id}"

affinity/cli/commands/session_cmds.py

@@ -0,0 +1,84 @@
+"""Session cache management commands."""
+
+from __future__ import annotations
+
+import os
+import shutil
+import tempfile
+import time
+from pathlib import Path
+
+from ..click_compat import RichCommand, RichGroup, click
+from ..decorators import category
+
+
+@click.group(name="session", cls=RichGroup)
+def session_group() -> None:
+    """Manage CLI session cache for pipeline optimization."""
+
+
+@category("local")
+@session_group.command(name="start", cls=RichCommand)
+def session_start() -> None:
+    """Create a new session cache directory.
+
+    Usage: export AFFINITY_SESSION_CACHE=$(affinity session start)
+    """
+    try:
+        cache_dir = tempfile.mkdtemp(prefix="affinity_session_")
+        # Output just the path (no newline issues with click.echo)
+        click.echo(cache_dir)
+    except OSError as e:
+        click.echo(f"Error: Cannot create session cache: {e}", err=True)
+        raise SystemExit(1) from None
+
+
+@category("local")
+@session_group.command(name="end", cls=RichCommand)
+def session_end() -> None:
+    """Clean up the current session cache.
+
+    Reads AFFINITY_SESSION_CACHE env var and removes the directory.
+    Safe to call multiple times (idempotent).
+    """
+    cache_dir = os.environ.get("AFFINITY_SESSION_CACHE")
+    if not cache_dir:
+        click.echo("No active session (AFFINITY_SESSION_CACHE not set)", err=True)
+        return
+    cache_path = Path(cache_dir)
+    if cache_path.exists():
+        shutil.rmtree(cache_dir, ignore_errors=True)
+        click.echo(f"Session ended: {cache_dir}", err=True)
+    else:
+        click.echo(f"Session directory already removed: {cache_dir}", err=True)
+
+
+@category("local")
+@session_group.command(name="status", cls=RichCommand)
+def session_status() -> None:
+    """Show current session cache status.
+
+    Note: Shows stats for ALL cache files in the directory, regardless of
+    which API key created them. Filtering by tenant would require API key
+    access, which this command intentionally avoids.
+    """
+    cache_dir = os.environ.get("AFFINITY_SESSION_CACHE")
+    if not cache_dir:
+        click.echo("No active session (AFFINITY_SESSION_CACHE not set)")
+        return
+
+    cache_path = Path(cache_dir)
+    if not cache_path.exists():
+        click.echo(f"Session directory missing: {cache_dir}")
+        return
+
+    # Count cache entries and calculate stats
+    cache_files = list(cache_path.glob("*.json"))
+    total_size = sum(f.stat().st_size for f in cache_files)
+    oldest_mtime = min((f.stat().st_mtime for f in cache_files), default=time.time())
+    age_seconds = int(time.time() - oldest_mtime)
+
+    click.echo(f"Session active: {cache_dir}")
+    click.echo(f"Cache entries: {len(cache_files)}")
+    click.echo(f"Total size: {total_size / 1024:.1f} KB")
+    click.echo(f"Oldest entry: {age_seconds // 60}m {age_seconds % 60}s ago")

affinity/cli/commands/task_cmds.py

@@ -0,0 +1,110 @@
+from __future__ import annotations
+
+from affinity.models.secondary import MergeTask
+
+from ..click_compat import RichCommand, RichGroup, click
+from ..context import CLIContext
+from ..decorators import category
+from ..options import output_options
+from ..results import CommandContext
+from ..runner import CommandOutput, run_command
+from ..serialization import serialize_model_for_cli
+
+
+@click.group(name="task", cls=RichGroup)
+def task_group() -> None:
+    """Task commands."""
+
+
+def _task_payload(task: MergeTask) -> dict[str, object]:
+    return serialize_model_for_cli(task)
+
+
+@category("read")
+@task_group.command(name="get", cls=RichCommand)
+@click.argument("task_url", type=str)
+@output_options
+@click.pass_obj
+def task_get(ctx: CLIContext, task_url: str) -> None:
+    """Get task status."""
+
+    def fn(ctx: CLIContext, warnings: list[str]) -> CommandOutput:
+        client = ctx.get_client(warnings=warnings)
+        task = client.tasks.get(task_url)
+        payload = _task_payload(task)
+
+        cmd_context = CommandContext(
+            name="task get",
+            inputs={"taskUrl": task_url},
+            modifiers={},
+        )
+
+        return CommandOutput(data={"task": payload}, context=cmd_context, api_called=True)
+
+    run_command(ctx, command="task get", fn=fn)
+
+
+@category("read")
+@task_group.command(name="wait", cls=RichCommand)
+@click.argument("task_url", type=str)
+@click.option(
+    "--timeout",
+    type=float,
+    default=300.0,
+    show_default=True,
+    help="Maximum seconds to wait for task completion.",
+)
+@click.option(
+    "--poll-interval",
+    type=float,
+    default=2.0,
+    show_default=True,
+    help="Initial polling interval in seconds.",
+)
+@click.option(
+    "--max-poll-interval",
+    type=float,
+    default=30.0,
+    show_default=True,
+    help="Maximum polling interval in seconds.",
+)
+@output_options
+@click.pass_obj
+def task_wait(
+    ctx: CLIContext,
+    task_url: str,
+    *,
+    timeout: float,
+    poll_interval: float,
+    max_poll_interval: float,
+) -> None:
+    """Wait for a task to complete."""
+
+    def fn(ctx: CLIContext, warnings: list[str]) -> CommandOutput:
+        client = ctx.get_client(warnings=warnings)
+        task = client.tasks.wait(
+            task_url,
+            timeout=timeout,
+            poll_interval=poll_interval,
+            max_poll_interval=max_poll_interval,
+        )
+        payload = _task_payload(task)
+
+        # Build CommandContext - only include non-default modifiers
+        ctx_modifiers: dict[str, object] = {}
+        if timeout != 300.0:
+            ctx_modifiers["timeout"] = timeout
+        if poll_interval != 2.0:
+            ctx_modifiers["pollInterval"] = poll_interval
+        if max_poll_interval != 30.0:
+            ctx_modifiers["maxPollInterval"] = max_poll_interval
+
+        cmd_context = CommandContext(
+            name="task wait",
+            inputs={"taskUrl": task_url},
+            modifiers=ctx_modifiers,
+        )
+
+        return CommandOutput(data={"task": payload}, context=cmd_context, api_called=True)
+
+    run_command(ctx, command="task wait", fn=fn)

affinity/cli/commands/version_cmd.py

@@ -0,0 +1,29 @@
+from __future__ import annotations
+
+import platform
+
+import affinity
+
+from ..click_compat import RichCommand, click
+from ..context import CLIContext
+from ..decorators import category
+from ..options import output_options
+from ..runner import CommandOutput, run_command
+
+
+@category("local")
+@click.command(name="version", cls=RichCommand)
+@output_options
+@click.pass_obj
+def version_cmd(ctx: CLIContext) -> None:
+    """Show version, Python, and platform information."""
+
+    def fn(_: CLIContext, _warnings: list[str]) -> CommandOutput:
+        data = {
+            "version": affinity.__version__,
+            "pythonVersion": platform.python_version(),
+            "platform": platform.platform(),
+        }
+        return CommandOutput(data=data, api_called=False)
+
+    run_command(ctx, command="version", fn=fn)

affinity/cli/commands/whoami_cmd.py

@@ -0,0 +1,36 @@
+from __future__ import annotations
+
+from ..click_compat import RichCommand, click
+from ..context import CLIContext
+from ..decorators import category
+from ..options import output_options
+from ..results import CommandContext
+from ..runner import CommandOutput, run_command
+from ..serialization import serialize_model_for_cli
+
+
+@category("read")
+@click.command(name="whoami", cls=RichCommand)
+@output_options
+@click.pass_obj
+def whoami_cmd(ctx: CLIContext) -> None:
+    """Show current authenticated user information."""
+
+    def fn(ctx: CLIContext, warnings: list[str]) -> CommandOutput:
+        client = ctx.get_client(warnings=warnings)
+        who = client.whoami()
+
+        cmd_context = CommandContext(
+            name="whoami",
+            inputs={},
+            modifiers={},
+        )
+
+        return CommandOutput(
+            data=serialize_model_for_cli(who),
+            context=cmd_context,
+            warnings=warnings,
+            api_called=True,
+        )
+
+    run_command(ctx, command="whoami", fn=fn)

affinity/cli/config.py

@@ -0,0 +1,108 @@
+from __future__ import annotations
+
+import json
+import os
+import stat
+import sys
+from dataclasses import dataclass
+from pathlib import Path
+from typing import Any, cast
+
+from .errors import CLIError
+
+if sys.version_info >= (3, 11):  # pragma: no cover
+    import tomllib as _tomllib
+else:  # pragma: no cover
+    import tomli as _tomllib
+
+
+@dataclass(frozen=True, slots=True)
+class ProfileConfig:
+    api_key: str | None = None
+    timeout_seconds: float | None = None
+    v1_base_url: str | None = None
+    v2_base_url: str | None = None
+
+
+@dataclass(frozen=True, slots=True)
+class LoadedConfig:
+    default: ProfileConfig
+    profiles: dict[str, ProfileConfig]
+
+
+def _profile_from_mapping(data: dict[str, Any]) -> ProfileConfig:
+    timeout = data.get("timeout_seconds")
+    return ProfileConfig(
+        api_key=data.get("api_key") or None,
+        timeout_seconds=float(timeout) if timeout is not None else None,
+        v1_base_url=data.get("v1_base_url") or None,
+        v2_base_url=data.get("v2_base_url") or None,
+    )
+
+
+def load_config(path: Path) -> LoadedConfig:
+    if not path.exists():
+        return LoadedConfig(default=ProfileConfig(), profiles={})
+
+    if path.suffix.lower() == ".json":
+        raw = json.loads(path.read_text(encoding="utf-8"))
+    else:
+        raw = _tomllib.loads(path.read_text(encoding="utf-8"))
+
+    if not isinstance(raw, dict):
+        raise CLIError(
+            f"Invalid config file: expected a mapping at top-level: {path}",
+            exit_code=2,
+            error_type="usage_error",
+        )
+
+    raw_dict = cast(dict[str, Any], raw)
+    default_raw_any = raw_dict.get("default")
+    default_raw = default_raw_any if isinstance(default_raw_any, dict) else {}
+    profiles_raw_any = raw_dict.get("profiles")
+    profiles_raw = profiles_raw_any if isinstance(profiles_raw_any, dict) else {}
+    profiles: dict[str, ProfileConfig] = {}
+    for name, value in profiles_raw.items():
+        if isinstance(value, dict):
+            profiles[str(name)] = _profile_from_mapping(cast(dict[str, Any], value))
+
+    return LoadedConfig(default=_profile_from_mapping(default_raw), profiles=profiles)
+
+
+def config_file_permission_warnings(path: Path) -> list[str]:
+    if os.name != "posix":
+        return []
+    try:
+        mode = path.stat().st_mode
+    except FileNotFoundError:
+        return []
+
+    insecure = bool(mode & (stat.S_IRGRP | stat.S_IROTH))
+    if insecure:
+        return [
+            (
+                f"Config file is group/world readable: {path} "
+                "(consider `chmod 600` to protect secrets)."
+            )
+        ]
+    return []
+
+
+def config_init_template() -> str:
+    return """# Affinity CLI configuration
+#
+# This file is optional. Prefer environment variables or --api-key-file for secrets.
+# On POSIX systems, ensure permissions are restrictive (e.g. chmod 600).
+#
+# Format: TOML
+
+[default]
+# api_key = "..."
+# timeout_seconds = 30
+
+[profiles.dev]
+# api_key = "..."
+# timeout_seconds = 30
+# v1_base_url = "https://api.affinity.co"
+# v2_base_url = "https://api.affinity.co"
+"""