qodev-apollo-cli 0.1.0__py3-none-any.whl

apollo_cli/commands/notes.py

@@ -0,0 +1,68 @@
+"""Notes command group."""
+
+from __future__ import annotations
+
+from typing import Annotated
+
+from cyclopts import App, Parameter
+
+from apollo_cli.context import ctx
+from apollo_cli.formatters.generic import list_table
+from apollo_cli.output import output, output_list
+
+notes_app = App(name="notes", help="Notes management.")
+
+NOTE_LIST_COLUMNS = [
+    ("ID", "id"),
+    ("Content", "content"),
+    ("Contact ID", "contact_id"),
+    ("Account ID", "account_id"),
+    ("Created", "created_at"),
+]
+
+
+@notes_app.command
+async def search(
+    *,
+    contact_id: Annotated[str | None, Parameter(name="--contact-id", help="Filter by contact ID")] = None,
+    account_id: Annotated[str | None, Parameter(name="--account-id", help="Filter by account ID")] = None,
+) -> None:
+    """Search notes by contact or account."""
+    filters: dict = {}
+    if contact_id:
+        filters["contact_ids"] = [contact_id]
+    if account_id:
+        filters["account_ids"] = [account_id]
+
+    async with ctx.client() as client:
+        result = await client.search_notes(page=ctx.page, limit=ctx.limit, **filters)
+
+    output_list(
+        items=result.items,
+        total=result.total,
+        page=result.page,
+        limit=ctx.limit,
+        ctx=ctx,
+        format_fn=lambda items, **kw: list_table(items, NOTE_LIST_COLUMNS, title="Notes", **kw),
+        resource_name="Notes",
+    )
+
+
+@notes_app.command
+async def create(
+    *,
+    content: Annotated[str, Parameter(name="--content", help="Note content")],
+    contact_ids: Annotated[str | None, Parameter(name="--contact-ids", help="Comma-separated contact IDs")] = None,
+    account_ids: Annotated[str | None, Parameter(name="--account-ids", help="Comma-separated account IDs")] = None,
+) -> None:
+    """Create a new note."""
+    kwargs: dict = {}
+    if contact_ids:
+        kwargs["contact_ids"] = [cid.strip() for cid in contact_ids.split(",")]
+    if account_ids:
+        kwargs["account_ids"] = [aid.strip() for aid in account_ids.split(",")]
+
+    async with ctx.client() as client:
+        result = await client.create_note(content, **kwargs)
+
+    output(result, ctx=ctx)

apollo_cli/commands/people.py

@@ -0,0 +1,34 @@
+"""People database search command group."""
+
+from __future__ import annotations
+
+from typing import Annotated
+
+from cyclopts import App, Parameter
+
+from apollo_cli.context import ctx
+from apollo_cli.output import output
+
+people_app = App(name="people", help="People database search.")
+
+
+@people_app.command
+async def search(
+    *,
+    keywords: Annotated[str | None, Parameter(name="--keywords", help="Search keywords")] = None,
+    titles: Annotated[str | None, Parameter(name="--titles", help="Comma-separated job titles")] = None,
+    locations: Annotated[str | None, Parameter(name="--locations", help="Comma-separated locations")] = None,
+) -> None:
+    """Search Apollo's global people database."""
+    filters: dict = {}
+    if keywords:
+        filters["q_keywords"] = keywords
+    if titles:
+        filters["person_titles"] = [t.strip() for t in titles.split(",")]
+    if locations:
+        filters["person_locations"] = [loc.strip() for loc in locations.split(",")]
+
+    async with ctx.client() as client:
+        result = await client.search_people(**filters)
+
+    output(result, ctx=ctx)

apollo_cli/commands/pipelines.py

@@ -0,0 +1,106 @@
+"""Pipelines and stages command groups."""
+
+from __future__ import annotations
+
+from typing import Annotated
+
+from cyclopts import App, Parameter
+
+from apollo_cli.context import ctx
+from apollo_cli.formatters.generic import detail_table, list_table
+from apollo_cli.output import output, output_list
+
+pipelines_app = App(name="pipelines", help="Pipeline management.")
+stages_app = App(name="stages", help="Stage management.")
+
+PIPELINE_LIST_COLUMNS = [
+    ("ID", "id"),
+    ("Title", "title"),
+    ("Default", "default_pipeline"),
+    ("Order", "display_order"),
+]
+
+PIPELINE_DETAIL_FIELDS = [
+    ("ID", "id"),
+    ("Title", "title"),
+    ("Default", "default_pipeline"),
+    ("Display Order", "display_order"),
+    ("Source", "source"),
+]
+
+STAGE_LIST_COLUMNS = [
+    ("ID", "id"),
+    ("Name", "name"),
+    ("Pipeline ID", "opportunity_pipeline_id"),
+    ("Order", "display_order"),
+    ("Probability", "probability"),
+    ("Type", "type"),
+]
+
+
+@pipelines_app.command(name="list")
+async def list_pipelines() -> None:
+    """List all pipelines."""
+    async with ctx.client() as client:
+        result = await client.list_pipelines(page=ctx.page, limit=ctx.limit)
+
+    output_list(
+        items=result.items,
+        total=result.total,
+        page=result.page,
+        limit=ctx.limit,
+        ctx=ctx,
+        format_fn=lambda items, **kw: list_table(items, PIPELINE_LIST_COLUMNS, title="Pipelines", **kw),
+        resource_name="Pipelines",
+    )
+
+
+@pipelines_app.command
+async def get(
+    id: Annotated[str, Parameter(help="Pipeline ID")],
+) -> None:
+    """Get pipeline details by ID."""
+    async with ctx.client() as client:
+        pipeline = await client.get_pipeline(id)
+
+    output(
+        pipeline,
+        ctx=ctx,
+        format_fn=lambda d: detail_table(d, PIPELINE_DETAIL_FIELDS, title=f"Pipeline: {d.title or d.id}"),
+    )
+
+
+@pipelines_app.command(name="stages")
+async def pipeline_stages(
+    pipeline_id: Annotated[str, Parameter(help="Pipeline ID")],
+) -> None:
+    """List stages for a specific pipeline."""
+    async with ctx.client() as client:
+        result = await client.list_pipeline_stages(pipeline_id, page=ctx.page, limit=ctx.limit)
+
+    output_list(
+        items=result.items,
+        total=result.total,
+        page=result.page,
+        limit=ctx.limit,
+        ctx=ctx,
+        format_fn=lambda items, **kw: list_table(items, STAGE_LIST_COLUMNS, title="Pipeline Stages", **kw),
+        resource_name="Stages",
+    )
+
+
+@stages_app.command(name="list")
+async def list_all_stages() -> None:
+    """List all stages across all pipelines."""
+    async with ctx.client() as client:
+        result = await client.list_all_stages()
+
+    output_list(
+        items=result.items,
+        total=result.total,
+        page=result.page,
+        limit=ctx.limit,
+        ctx=ctx,
+        format_fn=lambda items, **kw: list_table(items, STAGE_LIST_COLUMNS, title="All Stages", **kw),
+        resource_name="Stages",
+    )

apollo_cli/commands/tasks.py

@@ -0,0 +1,79 @@
+"""Tasks command group."""
+
+from __future__ import annotations
+
+from typing import Annotated
+
+from cyclopts import App, Parameter
+
+from apollo_cli.context import ctx
+from apollo_cli.formatters.generic import list_table
+from apollo_cli.output import output, output_list
+
+tasks_app = App(name="tasks", help="Task management.")
+
+TASK_LIST_COLUMNS = [
+    ("ID", "id"),
+    ("Subject", "subject"),
+    ("Type", "type"),
+    ("Priority", "priority"),
+    ("Status", "status"),
+    ("Due", "due_at"),
+]
+
+
+@tasks_app.command
+async def search(
+    *,
+    type: Annotated[str | None, Parameter(name="--type", help="Filter by task type (call, action_item, etc.)")] = None,
+    contact_id: Annotated[str | None, Parameter(name="--contact-id", help="Filter by contact ID")] = None,
+) -> None:
+    """Search tasks."""
+    filters: dict = {}
+    if type:
+        filters["task_type_cds"] = [type]
+    if contact_id:
+        filters["contact_ids"] = [contact_id]
+
+    async with ctx.client() as client:
+        result = await client.search_tasks(page=ctx.page, limit=ctx.limit, **filters)
+
+    output_list(
+        items=result.items,
+        total=result.total,
+        page=result.page,
+        limit=ctx.limit,
+        ctx=ctx,
+        format_fn=lambda items, **kw: list_table(items, TASK_LIST_COLUMNS, title="Tasks", **kw),
+        resource_name="Tasks",
+    )
+
+
+@tasks_app.command
+async def create(
+    *,
+    contact_ids: Annotated[str, Parameter(name="--contact-ids", help="Comma-separated contact IDs")],
+    note: Annotated[str, Parameter(name="--note", help="Task description")],
+    type: Annotated[str, Parameter(name="--type", help="Task type")] = "action_item",
+    priority: Annotated[str, Parameter(name="--priority", help="Priority (high, medium, low)")] = "medium",
+) -> None:
+    """Create a new task."""
+    ids = [cid.strip() for cid in contact_ids.split(",")]
+
+    async with ctx.client() as client:
+        result = await client.create_task(contact_ids=ids, note=note, type=type, priority=priority)
+
+    output(result, ctx=ctx)
+
+
+@tasks_app.command
+async def complete(
+    id: Annotated[str, Parameter(help="Task ID")],
+    *,
+    note: Annotated[str | None, Parameter(name="--note", help="Completion note")] = None,
+) -> None:
+    """Mark a task as completed."""
+    async with ctx.client() as client:
+        result = await client.complete_task(id, note=note)
+
+    output(result, ctx=ctx)

apollo_cli/commands/usage.py

@@ -0,0 +1,56 @@
+"""Usage stats command."""
+
+from __future__ import annotations
+
+from cyclopts import App
+
+from apollo_cli.context import ctx
+from apollo_cli.output import output_json, output_markdown
+
+usage_app = App(name="usage", help="API usage statistics.")
+
+
+@usage_app.default
+async def usage() -> None:
+    """Show API usage statistics and rate limits."""
+    async with ctx.client() as client:
+        data = await client.get_api_usage()
+        rate = client.rate_limit_status
+
+    if ctx.json_mode:
+        output_json({"usage": data, "rate_limits": rate})
+    else:
+        md = _format_usage(data, rate)
+        output_markdown(md)
+
+
+def _format_usage(data: dict, rate: dict) -> str:
+    lines = ["# API Usage"]
+
+    if rate:
+        lines.append("")
+        lines.append("## Rate Limits")
+        lines.append("")
+        lines.append("| Window | Limit | Remaining |")
+        lines.append("|--------|-------|-----------|")
+        if "hourly_limit" in rate:
+            lines.append(f"| Hourly | {rate.get('hourly_limit', '?')} | {rate.get('hourly_left', '?')} |")
+        if "minute_limit" in rate:
+            lines.append(f"| Minute | {rate.get('minute_limit', '?')} | {rate.get('minute_left', '?')} |")
+        if "daily_limit" in rate:
+            lines.append(f"| Daily | {rate.get('daily_limit', '?')} | {rate.get('daily_left', '?')} |")
+
+    if data:
+        lines.append("")
+        lines.append("## Endpoint Usage")
+        lines.append("")
+        lines.append("| Endpoint | Day Consumed | Day Left | Hour Consumed | Hour Left |")
+        lines.append("|----------|-------------|----------|--------------|-----------|")
+        for endpoint, stats in data.items():
+            day_consumed = stats.get("day", {}).get("consumed", "?")
+            day_left = stats.get("day", {}).get("left_over", "?")
+            hour_consumed = stats.get("hour", {}).get("consumed", "?")
+            hour_left = stats.get("hour", {}).get("left_over", "?")
+            lines.append(f"| {endpoint} | {day_consumed} | {day_left} | {hour_consumed} | {hour_left} |")
+
+    return "\n".join(lines)

apollo_cli/context.py

@@ -0,0 +1,35 @@
+"""Global context shared across all commands."""
+
+from __future__ import annotations
+
+from dataclasses import dataclass
+
+from qodev_apollo_api import ApolloClient
+
+
+@dataclass
+class Context:
+    """Shared state passed from the meta launcher to every command."""
+
+    json_mode: bool = False
+    api_key: str | None = None
+    limit: int = 25
+    page: int = 1
+
+    def client(self) -> ApolloClient:
+        """Create a new ApolloClient with the configured API key."""
+        kwargs: dict = {}
+        if self.api_key:
+            kwargs["api_key"] = self.api_key
+        return ApolloClient(**kwargs)
+
+    def configure(self, *, json_mode: bool, api_key: str | None, limit: int, page: int) -> None:
+        """Update context fields in place (preserves references held by command modules)."""
+        self.json_mode = json_mode
+        self.api_key = api_key
+        self.limit = limit
+        self.page = page
+
+
+# Module-level singleton — updated in place by the meta launcher.
+ctx = Context()

apollo_cli/formatters/accounts.py

@@ -0,0 +1,62 @@
+"""Account-specific formatters."""
+
+from __future__ import annotations
+
+from typing import Any
+
+from apollo_cli.formatters.generic import detail_table, list_table
+
+ACCOUNT_DETAIL_FIELDS = [
+    ("ID", "id"),
+    ("Name", "name"),
+    ("Domain", "domain"),
+    ("Phone", "phone"),
+    ("Industry", "industry"),
+    ("Employees", "estimated_num_employees"),
+    ("Revenue", "annual_revenue_printed"),
+    ("LinkedIn", "linkedin_url"),
+    ("Website", "website_url"),
+    ("City", "city"),
+    ("State", "state"),
+    ("Country", "country"),
+    ("Stage ID", "account_stage_id"),
+    ("Owner ID", "owner_id"),
+    ("Contacts", "num_contacts"),
+    ("Founded", "founded_year"),
+    ("Description", "short_description"),
+    ("Created", "created_at"),
+    ("Last Activity", "last_activity_date"),
+]
+
+ACCOUNT_LIST_COLUMNS = [
+    ("Name", "name"),
+    ("Domain", "domain"),
+    ("Industry", "industry"),
+    ("Employees", "estimated_num_employees"),
+    ("City", "city"),
+]
+
+
+def format_account_detail(data: Any) -> str:
+    """Format a single account as a markdown detail view."""
+    name = data.name if hasattr(data, "name") else data.get("name", "Unknown")
+    md = detail_table(data, ACCOUNT_DETAIL_FIELDS, title=f"Account: {name}")
+
+    # Technology stack (detail endpoint)
+    tech = getattr(data, "technology_names", None) or (data.get("technology_names") if isinstance(data, dict) else None)
+    if tech:
+        md += "\n\n## Technology Stack\n"
+        md += "\n" + ", ".join(tech)
+
+    # Keywords
+    keywords = getattr(data, "keywords", None) or (data.get("keywords") if isinstance(data, dict) else None)
+    if keywords:
+        md += "\n\n## Keywords\n"
+        md += "\n" + ", ".join(keywords)
+
+    return md
+
+
+def format_account_list(items: list[Any], *, total: int = 0, page: int = 1) -> str:
+    """Format a list of accounts as a markdown table."""
+    return list_table(items, ACCOUNT_LIST_COLUMNS, title="Accounts", total=total, page=page)

apollo_cli/formatters/contacts.py

@@ -0,0 +1,80 @@
+"""Contact-specific formatters."""
+
+from __future__ import annotations
+
+from typing import Any
+
+from apollo_cli.formatters.generic import detail_table, list_table
+
+CONTACT_DETAIL_FIELDS = [
+    ("ID", "id"),
+    ("Name", "name"),
+    ("Email", "email"),
+    ("Title", "title"),
+    ("Company", "organization_name"),
+    ("LinkedIn", "linkedin_url"),
+    ("Phone", "sanitized_phone"),
+    ("Stage ID", "contact_stage_id"),
+    ("City", "city"),
+    ("State", "state"),
+    ("Country", "country"),
+    ("Source", "source"),
+    ("Owner ID", "owner_id"),
+    ("Created", "created_at"),
+    ("Updated", "updated_at"),
+    ("Last Activity", "last_activity_date"),
+]
+
+CONTACT_LIST_COLUMNS = [
+    ("Name", "name"),
+    ("Title", "title"),
+    ("Company", "organization_name"),
+    ("Email", "email"),
+    ("LinkedIn", "linkedin_url"),
+]
+
+
+def format_contact_detail(data: Any) -> str:
+    """Format a single contact as a markdown detail view."""
+    name = data.name if hasattr(data, "name") else data.get("name", "Unknown")
+    md = detail_table(data, CONTACT_DETAIL_FIELDS, title=f"Contact: {name}")
+
+    # Phone numbers section
+    phones = data.phone_numbers if hasattr(data, "phone_numbers") else data.get("phone_numbers", [])
+    if phones:
+        md += "\n\n## Phone Numbers\n"
+        for p in phones:
+            if hasattr(p, "sanitized_number"):
+                num = p.sanitized_number or p.number
+                ptype = p.type or "unknown"
+            else:
+                num = p.get("sanitized_number") or p.get("number", "")
+                ptype = p.get("type", "unknown")
+            md += f"\n- {num} ({ptype})"
+
+    # Employment history (detail endpoint only)
+    history = getattr(data, "employment_history", None)
+    if history:
+        md += "\n\n## Employment History\n"
+        for entry in history:
+            org = entry.organization_name or "Unknown"
+            title = entry.title or "Unknown"
+            current = " (current)" if entry.current else ""
+            md += f"\n- **{title}** at {org}{current}"
+
+    return md
+
+
+def format_contact_list(items: list[Any], *, total: int = 0, page: int = 1) -> str:
+    """Format a list of contacts as a markdown table."""
+    return list_table(items, CONTACT_LIST_COLUMNS, title="Contacts", total=total, page=page)
+
+
+def format_stages_list(stages: list[Any], *, total: int = 0, page: int = 1) -> str:
+    """Format contact stages."""
+    columns = [
+        ("ID", "id"),
+        ("Name", "name"),
+        ("Display Order", "display_order"),
+    ]
+    return list_table(stages, columns, title="Contact Stages", total=total, page=page)

apollo_cli/formatters/deals.py

@@ -0,0 +1,46 @@
+"""Deal-specific formatters."""
+
+from __future__ import annotations
+
+from typing import Any
+
+from apollo_cli.formatters.generic import detail_table, list_table
+
+DEAL_DETAIL_FIELDS = [
+    ("ID", "id"),
+    ("Name", "name"),
+    ("Amount", "amount"),
+    ("Stage", "stage_name"),
+    ("Pipeline ID", "opportunity_pipeline_id"),
+    ("Probability", "probability"),
+    ("Close Date", "closed_date"),
+    ("Won", "is_won"),
+    ("Closed", "is_closed"),
+    ("Account ID", "account_id"),
+    ("Owner ID", "owner_id"),
+    ("Source", "source"),
+    ("Next Step", "next_step"),
+    ("Next Step Date", "next_step_date"),
+    ("Forecast Category", "forecast_category"),
+    ("Created", "created_at"),
+    ("Last Activity", "last_activity_date"),
+]
+
+DEAL_LIST_COLUMNS = [
+    ("Name", "name"),
+    ("Amount", "amount"),
+    ("Stage", "stage_name"),
+    ("Close Date", "closed_date"),
+    ("Won", "is_won"),
+]
+
+
+def format_deal_detail(data: Any) -> str:
+    """Format a single deal as a markdown detail view."""
+    name = data.name if hasattr(data, "name") else data.get("name", "Unknown")
+    return detail_table(data, DEAL_DETAIL_FIELDS, title=f"Deal: {name}")
+
+
+def format_deal_list(items: list[Any], *, total: int = 0, page: int = 1) -> str:
+    """Format a list of deals as a markdown table."""
+    return list_table(items, DEAL_LIST_COLUMNS, title="Deals", total=total, page=page)

apollo_cli/formatters/generic.py

@@ -0,0 +1,101 @@
+"""Generic formatters for Pydantic models and dicts."""
+
+from __future__ import annotations
+
+from typing import Any
+
+from pydantic import BaseModel
+
+from apollo_cli.output import md_table
+
+
+def detail_table(data: Any, fields: list[tuple[str, str]], *, title: str | None = None) -> str:
+    """Render a single record as a Field/Value markdown table.
+
+    Args:
+        data: Pydantic model or dict.
+        fields: List of (label, key) — key supports dot notation for nested access.
+        title: Optional heading above the table.
+    """
+    d = data.model_dump() if isinstance(data, BaseModel) else data
+
+    lines: list[str] = []
+    if title:
+        lines.append(f"# {title}")
+        lines.append("")
+
+    lines.append("| Field | Value |")
+    lines.append("|-------|-------|")
+    for label, key in fields:
+        value = _get(d, key)
+        if value is None or value == "" or value == []:
+            continue
+        lines.append(f"| {label} | {_fmt(value)} |")
+    return "\n".join(lines)
+
+
+def list_table(
+    items: list[Any],
+    columns: list[tuple[str, str]],
+    *,
+    title: str = "Results",
+    total: int = 0,
+    page: int = 1,
+) -> str:
+    """Render a list of records as a markdown table.
+
+    Args:
+        items: List of Pydantic models or dicts.
+        columns: List of (header_label, key) tuples.
+        title: Heading text.
+        total: Total results count (for pagination header).
+        page: Current page number.
+    """
+    if not items:
+        return f"# {title}\n\n_No results found._"
+
+    header = f"# {title}"
+    if total:
+        header += f" (page {page}, {total} total)"
+
+    rows: list[dict[str, str]] = []
+    for item in items:
+        d = item.model_dump() if isinstance(item, BaseModel) else item
+        row = {}
+        for _, key in columns:
+            row[key] = _fmt(_get(d, key))
+        rows.append(row)
+
+    return f"{header}\n\n{md_table(rows, columns)}"
+
+
+# ---------------------------------------------------------------------------
+# Helpers
+# ---------------------------------------------------------------------------
+
+
+def _get(d: dict, key: str) -> Any:
+    """Get a value from a dict, supporting dot notation."""
+    parts = key.split(".")
+    current: Any = d
+    for part in parts:
+        if isinstance(current, dict):
+            current = current.get(part)
+        else:
+            return None
+        if current is None:
+            return None
+    return current
+
+
+def _fmt(value: Any) -> str:
+    """Format a value for display in a markdown table cell."""
+    if value is None:
+        return ""
+    if isinstance(value, bool):
+        return "Yes" if value else "No"
+    if isinstance(value, list):
+        if not value:
+            return ""
+        return ", ".join(str(v) for v in value)
+    return str(value)