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

apollo_cli/help_reference.py

@@ -0,0 +1,123 @@
+"""Build a flat command reference for the root --help epilogue."""
+
+from __future__ import annotations
+
+import inspect
+import types
+from typing import Annotated, Any, Union, get_args, get_origin, get_type_hints
+
+from cyclopts import App, Parameter
+
+COL_WIDTH = 46
+MAX_LINE = 78
+MIN_DESC_WIDTH = 10
+ELLIPSIS = "\u2026"
+
+
+def _is_bool_type(tp: object) -> bool:
+    if tp is bool:
+        return True
+    if tp is None:
+        return False
+    origin = get_origin(tp)
+    if origin is Union or isinstance(tp, types.UnionType):
+        return bool in get_args(tp)
+    return False
+
+
+def _display_len(s: str) -> int:
+    """Return rendered width (Rich \\[ escapes render as single [)."""
+    return len(s.replace("\\[", "["))
+
+
+def _format_signature(func: Any, prefix_len: int, col_width: int) -> str:
+    sig = inspect.signature(func)
+    try:
+        hints = get_type_hints(func, include_extras=True)
+    except (TypeError, NameError):
+        hints = {}
+
+    required: list[str] = []
+    optional: list[str] = []
+    for pname, param in sig.parameters.items():
+        hint = hints.get(pname)
+
+        cli_param = None
+        base_type = hint
+        if hint is not None and get_origin(hint) is Annotated:
+            args = get_args(hint)
+            base_type = args[0]
+            for arg in args[1:]:
+                if isinstance(arg, Parameter):
+                    cli_param = arg
+                    break
+
+        is_bool = _is_bool_type(base_type)
+        has_default = param.default is not inspect.Parameter.empty
+
+        if param.kind == param.KEYWORD_ONLY:
+            if cli_param and cli_param.name:
+                names = cli_param.name if isinstance(cli_param.name, (list, tuple)) else [cli_param.name]
+                cli_name = names[0]
+            else:
+                cli_name = f"--{pname.replace('_', '-')}"
+
+            if has_default:
+                optional.append(f"\\[{cli_name}]")
+            elif is_bool:
+                required.append(cli_name)
+            else:
+                required.append(f"{cli_name} {pname.upper()}")
+        elif param.kind in (param.POSITIONAL_ONLY, param.POSITIONAL_OR_KEYWORD):
+            label = pname.upper()
+            if has_default:
+                optional.append(f"\\[{label}]")
+            else:
+                required.append(label)
+
+    max_sig = col_width - prefix_len - 2
+    parts = required + optional
+    result = " ".join(parts)
+    while len(result) > max_sig and optional:
+        optional.pop()
+        parts = required + optional + ["..."]
+        result = " ".join(parts)
+
+    return result
+
+
+def build_command_reference(sub_apps: list[App]) -> str:
+    """Walk sub-apps and build a formatted "All Commands" block."""
+    entries: list[tuple[str, str]] = []
+    for sub in sub_apps:
+        sub_name = sub.name[0] if sub.name else "?"
+        for cmd_name, cmd_app in sub.resolved_commands().items():
+            if cmd_name.startswith("-"):
+                continue
+            func = cmd_app.default_command
+            if func is None:
+                continue
+            prefix = f"  {sub_name} {cmd_name} "
+            sig_str = _format_signature(func, prefix_len=len(prefix), col_width=COL_WIDTH)
+            doc = (func.__doc__ or "").strip().split("\n")[0]
+            left = f"  {sub_name} {cmd_name}"
+            if sig_str:
+                left += f" {sig_str}"
+            entries.append((left, doc))
+        entries.append(("", ""))
+
+    if entries and entries[-1] == ("", ""):
+        entries.pop()
+
+    lines = ["All Commands:\n"]
+    for left, doc in entries:
+        if not left:
+            lines.append("")
+        else:
+            display_w = _display_len(left)
+            pad = max(2, COL_WIDTH - display_w)
+            avail = MAX_LINE - display_w - pad
+            if len(doc) > avail > MIN_DESC_WIDTH:
+                doc = doc[: avail - 1] + ELLIPSIS
+            lines.append(f"{left}{' ' * pad}{doc}")
+    return "\n".join(lines)

apollo_cli/output.py

@@ -0,0 +1,150 @@
+"""Output formatting — JSON and Markdown modes."""
+
+from __future__ import annotations
+
+import json
+import sys
+from datetime import datetime
+from decimal import Decimal
+from typing import Any
+
+from pydantic import BaseModel
+from rich.console import Console
+from rich.markdown import Markdown
+
+from apollo_cli.context import Context
+
+# Rich console for stderr diagnostics and markdown rendering
+console = Console(stderr=True)
+stdout_console = Console()
+
+
+def serialize(obj: Any) -> Any:
+    """Convert an object to a JSON-serializable structure."""
+    if isinstance(obj, BaseModel):
+        return obj.model_dump(mode="json")
+    if isinstance(obj, datetime):
+        return obj.isoformat()
+    if isinstance(obj, Decimal):
+        return float(obj)
+    if isinstance(obj, list):
+        return [serialize(item) for item in obj]
+    if isinstance(obj, dict):
+        return {k: serialize(v) for k, v in obj.items()}
+    return obj
+
+
+def output_json(data: Any) -> None:
+    """Print data as JSON to stdout."""
+    print(json.dumps(serialize(data), indent=2, default=str))
+
+
+def output_markdown(text: str) -> None:
+    """Render markdown text to the terminal via rich."""
+    stdout_console.print(Markdown(text))
+
+
+def output(data: Any, *, ctx: Context, format_fn: Any = None) -> None:
+    """Route output through the correct formatter.
+
+    Args:
+        data: The data to output (Pydantic model, dict, list, etc.)
+        ctx: The global context (determines json vs markdown mode).
+        format_fn: Optional callable(data) -> str that returns markdown.
+    """
+    if ctx.json_mode:
+        output_json(data)
+    else:
+        md = format_fn(data) if format_fn else generic_markdown(data)
+        output_markdown(md)
+
+
+def output_list(
+    *,
+    items: list[Any],
+    total: int,
+    page: int,
+    limit: int,
+    ctx: Context,
+    format_fn: Any,
+    resource_name: str = "Results",
+) -> None:
+    """Output a paginated list of items.
+
+    In JSON mode, emits ``{items, total, page, limit}``.
+    In markdown mode, calls *format_fn* and appends a pagination footer.
+    """
+    if ctx.json_mode:
+        output_json({"items": serialize(items), "total": total, "page": page, "limit": limit})
+    else:
+        md = format_fn(items, total=total, page=page)
+        if total > page * limit:
+            md += f"\n\n*Showing {len(items)} of {total} results. Use `--page {page + 1}` for next page.*"
+        elif total > 0:
+            md += f"\n\n*Showing {len(items)} of {total} results.*"
+        output_markdown(md)
+
+
+def error(message: str, *, ctx: Context | None = None, code: str = "error", exit_code: int = 1) -> None:
+    """Output an error and exit.
+
+    In JSON mode, writes a JSON error object to stdout.
+    In markdown mode, writes to stderr.
+    """
+    if ctx and ctx.json_mode:
+        print(json.dumps({"error": message, "code": code}))
+    else:
+        console.print(f"[red]Error:[/red] {message}")
+    sys.exit(exit_code)
+
+
+# ---------------------------------------------------------------------------
+# Generic markdown helpers
+# ---------------------------------------------------------------------------
+
+
+def generic_markdown(data: Any) -> str:
+    """Best-effort markdown rendering for arbitrary data."""
+    if isinstance(data, BaseModel):
+        return _model_to_md(data)
+    if isinstance(data, dict):
+        return _dict_to_md(data)
+    if isinstance(data, list):
+        if not data:
+            return "_No results._"
+        return "\n\n".join(generic_markdown(item) for item in data)
+    return str(data)
+
+
+def _model_to_md(model: BaseModel) -> str:
+    d = model.model_dump(exclude_none=True)
+    return _dict_to_md(d)
+
+
+def _dict_to_md(d: dict) -> str:
+    lines = ["| Field | Value |", "|-------|-------|"]
+    for key, value in d.items():
+        if isinstance(value, (dict, list)):
+            continue  # skip complex nested fields in generic view
+        display_key = key.replace("_", " ").title()
+        lines.append(f"| {display_key} | {value} |")
+    return "\n".join(lines)
+
+
+def md_table(rows: list[dict[str, str]], headers: list[tuple[str, str]]) -> str:
+    """Build a markdown table from rows.
+
+    Args:
+        rows: List of dicts with values to display.
+        headers: List of (header_label, key) tuples.
+    """
+    if not rows:
+        return "_No results._"
+
+    header_line = "| " + " | ".join(h for h, _ in headers) + " |"
+    sep_line = "| " + " | ".join("---" for _ in headers) + " |"
+    lines = [header_line, sep_line]
+    for row in rows:
+        cells = [str(row.get(key, "")) for _, key in headers]
+        lines.append("| " + " | ".join(cells) + " |")
+    return "\n".join(lines)

apollo_cli/skills/SKILL.md

@@ -0,0 +1,200 @@
+# qodev-apollo-cli
+
+Agent-friendly CLI for the Apollo.io API. Designed for AI coding agents with structured JSON output and predictable exit codes.
+
+## Setup
+
+```bash
+pip install qodev-apollo-cli
+export APOLLO_API_KEY="your_api_key"
+
+# Install skill files into the current workspace
+qodev-apollo-cli install --skills
+```
+
+Get your API key from [Apollo.io Settings → API](https://app.apollo.io/#/settings/integrations/api).
+
+## Global Options
+
+| Flag | Description |
+|------|-------------|
+| `--json` | Output as JSON (default: rich Markdown) |
+| `--api-key` | Apollo API key (overrides APOLLO_API_KEY) |
+| `--limit` | Results per page (default: 25) |
+| `--page` | Page number (default: 1) |
+
+## Command Reference
+
+### contacts
+
+| Command | Description |
+|---------|-------------|
+| `contacts search [--query Q] [--stage-id ID] [--linkedin-url URL]` | Search contacts |
+| `contacts get ID` | Get contact details |
+| `contacts create --first-name F --last-name L [--email E] [--title T] [--company C] [--linkedin-url URL]` | Create contact |
+| `contacts update ID [--title T] [--label-ids IDS]` | Update contact |
+| `contacts find-by-linkedin URL [--create] [--name N] [--stage-id ID]` | Find contact by LinkedIn URL |
+| `contacts stages` | List all contact stages |
+
+### accounts
+
+| Command | Description |
+|---------|-------------|
+| `accounts search [--query Q] [--domain D]` | Search companies/accounts |
+| `accounts get ID` | Get account details |
+
+### deals
+
+| Command | Description |
+|---------|-------------|
+| `deals search [--query Q] [--stage-id ID]` | Search opportunities/deals |
+| `deals get ID` | Get deal details |
+
+### pipelines
+
+| Command | Description |
+|---------|-------------|
+| `pipelines list` | List all deal pipelines |
+| `pipelines get ID` | Get pipeline details |
+| `pipelines stages ID` | List stages in a pipeline |
+
+### stages
+
+| Command | Description |
+|---------|-------------|
+| `stages list` | List all contact stages |
+| `stages get ID` | Get stage details |
+
+### enrich
+
+| Command | Description |
+|---------|-------------|
+| `enrich org DOMAIN` | Enrich organization by domain (FREE - no credits used) |
+| `enrich person EMAIL` | Enrich person by email (1 credit per lookup) |
+
+### people
+
+| Command | Description |
+|---------|-------------|
+| `people search [--person-titles TITLES] [--q-organization-domains DOMAINS]` | Search people database |
+
+### notes
+
+| Command | Description |
+|---------|-------------|
+| `notes search [--contact-id ID]` | Search notes |
+| `notes create --contact-ids IDS --note TEXT` | Create a note |
+
+### tasks
+
+| Command | Description |
+|---------|-------------|
+| `tasks search [--type TYPE] [--status STATUS]` | Search tasks |
+| `tasks create --contact-ids IDS --note TEXT [--due-at DATE]` | Create a task |
+
+### calls
+
+| Command | Description |
+|---------|-------------|
+| `calls search` | Search call activities |
+
+### emails
+
+| Command | Description |
+|---------|-------------|
+| `emails search` | Search email activities |
+
+### news
+
+| Command | Description |
+|---------|-------------|
+| `news search [--categories CATS]` | Search news |
+
+### jobs
+
+| Command | Description |
+|---------|-------------|
+| `jobs search [--job-titles TITLES] [--company-domains DOMAINS]` | Search job postings |
+
+### usage
+
+| Command | Description |
+|---------|-------------|
+| `usage` | Show API usage stats and rate limits |
+
+## Exit Codes
+
+| Code | Meaning |
+|------|---------|
+| 0 | Success |
+| 80 | Authentication error (invalid API key) |
+| 81 | Rate limit exceeded |
+| 82 | API error (server error, invalid request) |
+| 83 | Validation error (missing required fields) |
+
+## JSON Output
+
+All commands support `--json` for structured output:
+
+```bash
+qodev-apollo-cli --json contacts search --query "engineer" | jq '.items[0].name'
+```
+
+Paginated responses include:
+
+```json
+{
+  "items": [...],
+  "total": 142,
+  "page": 1,
+  "limit": 25
+}
+```
+
+## Common Patterns
+
+### Find and enrich a contact
+
+```bash
+# Search by keyword
+qodev-apollo-cli contacts search --query "jane smith"
+
+# Get full details
+qodev-apollo-cli contacts get <contact-id>
+
+# Enrich person data (1 credit)
+qodev-apollo-cli enrich person jane@example.com
+```
+
+### Pipeline management
+
+```bash
+# List all pipelines
+qodev-apollo-cli pipelines list
+
+# Get stages in a pipeline
+qodev-apollo-cli pipelines stages <pipeline-id>
+
+# Search deals in specific stage
+qodev-apollo-cli deals search --stage-id <stage-id>
+```
+
+### LinkedIn integration
+
+```bash
+# Find contact by LinkedIn URL
+qodev-apollo-cli contacts find-by-linkedin "https://linkedin.com/in/janesmith"
+
+# Auto-create if not found
+qodev-apollo-cli contacts find-by-linkedin "https://linkedin.com/in/janesmith" --create
+
+# Assign to stage on creation
+qodev-apollo-cli contacts find-by-linkedin "https://linkedin.com/in/janesmith" \
+  --create --stage-id <stage-id>
+```
+
+## References
+
+- [Contact Management Workflows](references/contact-workflows.md)
+- [Deal Pipeline Workflows](references/deal-workflows.md)
+- [Account Enrichment Patterns](references/account-workflows.md)

apollo_cli/skills/__init__.py

@@ -0,0 +1 @@
+"""AI agent skill files for Apollo CLI."""

apollo_cli/skills/references/__init__.py

@@ -0,0 +1 @@
+"""Reference documentation for Apollo CLI workflows."""

apollo_cli/skills/references/account-workflows.md

@@ -0,0 +1,202 @@
+# Account Enrichment Patterns
+
+## Overview
+
+Apollo provides two types of enrichment:
+- **Organization enrichment** (FREE - no credits used)
+- **Person enrichment** (1 credit per lookup)
+
+## Organization Enrichment (FREE)
+
+Enrich company data by domain without using credits:
+
+```bash
+# Basic enrichment
+qodev-apollo-cli enrich org acme.com
+
+# JSON output for scripting
+qodev-apollo-cli --json enrich org acme.com
+
+# Extract specific fields
+qodev-apollo-cli --json enrich org acme.com | jq '{name, industry, employees: .estimated_num_employees}'
+```
+
+### What you get (FREE):
+- Company name
+- Industry classification
+- Employee count estimate
+- Company size category
+- Website URL
+- Social media profiles
+- Founded year
+- Revenue estimates
+- Technologies used
+
+## Account Search
+
+Search for companies in Apollo's database:
+
+```bash
+# Search by name
+qodev-apollo-cli accounts search --query "technology"
+
+# Search by domain
+qodev-apollo-cli accounts search --domain "acme.com"
+
+# Pagination
+qodev-apollo-cli accounts search --query "software" --page 2 --limit 50
+```
+
+## Account Details
+
+```bash
+# Get full account details
+qodev-apollo-cli accounts get <account-id>
+
+# Extract specific data
+qodev-apollo-cli --json accounts get <account-id> | \
+  jq '{name, domain, industry, employees: .estimated_num_employees}'
+```
+
+## Bulk Enrichment
+
+Enrich multiple organizations:
+
+```bash
+# From a list of domains
+cat domains.txt | while read domain; do
+  echo "Enriching $domain..."
+  qodev-apollo-cli --json enrich org "$domain" > "data/${domain}.json"
+  sleep 1  # Rate limiting
+done
+
+# Extract key fields
+for file in data/*.json; do
+  jq '{domain: .domain, name: .name, industry: .industry, employees: .estimated_num_employees}' "$file"
+done | jq -s '.'
+```
+
+## Person Enrichment (1 credit)
+
+Enrich person data by email:
+
+```bash
+# Basic enrichment
+qodev-apollo-cli enrich person jane@example.com
+
+# JSON output
+qodev-apollo-cli --json enrich person jane@example.com
+
+# Extract contact details
+qodev-apollo-cli --json enrich person jane@example.com | \
+  jq '{name, title, company: .organization_name, linkedin: .linkedin_url}'
+```
+
+### What you get (1 credit):
+- Full name
+- Job title
+- Company
+- Email verification
+- Phone numbers (if available)
+- LinkedIn profile
+- Work history
+- Education
+
+## Rate Limits and Usage
+
+Check your API usage:
+
+```bash
+# View usage stats
+qodev-apollo-cli usage
+
+# JSON output for monitoring
+qodev-apollo-cli --json usage | jq '{credits_available, requests_used, request_limit}'
+```
+
+## Enrichment Workflows
+
+### Pre-meeting research
+
+```bash
+# Enrich company (free)
+qodev-apollo-cli enrich org acme.com > company_info.txt
+
+# Search for contacts at company
+qodev-apollo-cli --json accounts search --domain "acme.com" | \
+  jq -r '.items[0].id' | \
+  xargs -I {} qodev-apollo-cli contacts search --account-id {}
+```
+
+### Lead qualification
+
+```bash
+# Enrich organization to check company size
+company_size=$(qodev-apollo-cli --json enrich org "$domain" | \
+  jq -r '.estimated_num_employees')
+
+if [ "$company_size" -gt 100 ]; then
+  echo "Qualified: Enterprise ($company_size employees)"
+else
+  echo "Not qualified: SMB ($company_size employees)"
+fi
+```
+
+### Data enrichment pipeline
+
+```bash
+#!/bin/bash
+# Enrich contacts from CSV
+
+while IFS=, read -r email domain; do
+  # Free org enrichment
+  org_data=$(qodev-apollo-cli --json enrich org "$domain")
+
+  # Paid person enrichment (1 credit)
+  person_data=$(qodev-apollo-cli --json enrich person "$email")
+
+  # Combine and save
+  echo "{\"organization\": $org_data, \"person\": $person_data}" >> enriched_data.jsonl
+
+  sleep 1  # Rate limiting
+done < contacts.csv
+```
+
+## JSON Output Examples
+
+### Organization Enrichment
+
+```json
+{
+  "domain": "acme.com",
+  "name": "Acme Corp",
+  "industry": "Technology",
+  "estimated_num_employees": 500,
+  "website_url": "https://acme.com",
+  "founded_year": 2010,
+  "technologies": ["AWS", "React", "Python"]
+}
+```
+
+### Person Enrichment
+
+```json
+{
+  "name": "Jane Smith",
+  "email": "jane@example.com",
+  "title": "VP Engineering",
+  "organization_name": "Acme Corp",
+  "linkedin_url": "https://linkedin.com/in/janesmith",
+  "phone_numbers": [
+    {"number": "+1-555-0100", "type": "mobile"}
+  ]
+}
+```
+
+## Best Practices
+
+1. **Use free enrichment first**: Always enrich organizations (free) before enriching people (1 credit)
+2. **Batch operations**: Process enrichment requests in batches with rate limiting
+3. **Cache results**: Save enriched data to avoid duplicate lookups
+4. **Monitor usage**: Check `qodev-apollo-cli usage` regularly to track credit consumption
+5. **Validate domains**: Ensure domains are correctly formatted before enrichment