foxreach-cli 0.1.0__py3-none-any.whl

foxreach_cli/__init__.py

@@ -0,0 +1,3 @@
+"""FoxReach CLI — command-line interface for the FoxReach API."""
+
+__version__ = "0.1.0"

foxreach_cli/client_factory.py

@@ -0,0 +1,22 @@
+from __future__ import annotations
+
+import sys
+
+from foxreach import FoxReach
+
+from . import config as cfg
+from .output import print_error
+
+
+def get_client() -> FoxReach:
+    api_key = cfg.get_api_key()
+    if not api_key:
+        print_error("No API key configured. Run: foxreach config set-key")
+        sys.exit(1)
+
+    kwargs = {"api_key": api_key}
+    base_url = cfg.get_base_url()
+    if base_url:
+        kwargs["base_url"] = base_url
+
+    return FoxReach(**kwargs)

foxreach_cli/commands/accounts.py

@@ -0,0 +1,87 @@
+from __future__ import annotations
+
+import sys
+from dataclasses import asdict
+
+import click
+
+from foxreach import FoxReachError
+
+from ..client_factory import get_client
+from ..output import print_detail, print_error, print_json, print_meta, print_success, print_table
+
+
+@click.group()
+def accounts() -> None:
+    """Manage email accounts."""
+
+
+@accounts.command("list")
+@click.option("--page", default=1, type=int)
+@click.option("--limit", default=50, type=int)
+@click.option("--json", "as_json", is_flag=True, help="Output as JSON")
+def accounts_list(page: int, limit: int, as_json: bool) -> None:
+    """List email accounts."""
+    client = get_client()
+    try:
+        result = client.email_accounts.list(page=page, page_size=limit)
+    except FoxReachError as e:
+        print_error(str(e))
+        sys.exit(1)
+
+    if as_json:
+        print_json({"data": [asdict(a) for a in result.data], "meta": asdict(result.meta)})
+        return
+
+    if not result.data:
+        click.echo("No email accounts found.")
+        return
+
+    print_table(
+        result.data,
+        ["ID", "Email", "Display Name", "Active", "Daily Limit", "Sent Today", "Health"],
+        {
+            "ID": "id", "Email": "email", "Display Name": "display_name",
+            "Active": "is_active", "Daily Limit": "daily_limit",
+            "Sent Today": "sent_today", "Health": "health_score",
+        },
+    )
+    print_meta(result.meta)
+
+
+@accounts.command("get")
+@click.argument("account_id")
+@click.option("--json", "as_json", is_flag=True, help="Output as JSON")
+def accounts_get(account_id: str, as_json: bool) -> None:
+    """Get an email account by ID."""
+    client = get_client()
+    try:
+        account = client.email_accounts.get(account_id)
+    except FoxReachError as e:
+        print_error(str(e))
+        sys.exit(1)
+
+    if as_json:
+        print_json(account)
+        return
+
+    print_detail(account, [
+        "id", "email", "display_name", "provider", "is_active",
+        "daily_limit", "sent_today", "warmup_enabled",
+        "health_score", "bounce_rate", "reply_rate",
+        "connection_status", "created_at",
+    ])
+
+
+@accounts.command("delete")
+@click.argument("account_id")
+@click.confirmation_option(prompt="Are you sure you want to delete this email account?")
+def accounts_delete(account_id: str) -> None:
+    """Delete an email account."""
+    client = get_client()
+    try:
+        client.email_accounts.delete(account_id)
+    except FoxReachError as e:
+        print_error(str(e))
+        sys.exit(1)
+    print_success(f"Email account deleted: {account_id}")

foxreach_cli/commands/analytics.py

@@ -0,0 +1,69 @@
+from __future__ import annotations
+
+import sys
+from dataclasses import asdict
+
+import click
+
+from foxreach import FoxReachError
+
+from ..client_factory import get_client
+from ..output import print_detail, print_error, print_json, print_table
+
+
+@click.group()
+def analytics() -> None:
+    """View analytics and stats."""
+
+
+@analytics.command("overview")
+@click.option("--json", "as_json", is_flag=True, help="Output as JSON")
+def analytics_overview(as_json: bool) -> None:
+    """Show dashboard overview stats."""
+    client = get_client()
+    try:
+        stats = client.analytics.overview()
+    except FoxReachError as e:
+        print_error(str(e))
+        sys.exit(1)
+
+    if as_json:
+        print_json(stats)
+        return
+
+    print_detail(stats, [
+        "total_accounts", "active_accounts",
+        "total_campaigns", "active_campaigns",
+        "total_leads", "total_sent", "total_replies",
+        "reply_rate", "account_health_avg",
+    ])
+
+
+@analytics.command("campaign")
+@click.argument("campaign_id")
+@click.option("--json", "as_json", is_flag=True, help="Output as JSON")
+def analytics_campaign(campaign_id: str, as_json: bool) -> None:
+    """Show campaign analytics."""
+    client = get_client()
+    try:
+        stats = client.analytics.campaign(campaign_id)
+    except FoxReachError as e:
+        print_error(str(e))
+        sys.exit(1)
+
+    if as_json:
+        print_json(stats)
+        return
+
+    print_detail(stats, [
+        "sent", "delivered", "bounced", "replied", "opened",
+        "reply_rate", "bounce_rate",
+    ])
+
+    if stats.daily_stats:
+        click.echo("\nDaily Stats:")
+        print_table(
+            stats.daily_stats,
+            ["Date", "Sent", "Delivered", "Bounced", "Replied", "Opened"],
+            {"Date": "date", "Sent": "sent", "Delivered": "delivered", "Bounced": "bounced", "Replied": "replied", "Opened": "opened"},
+        )

foxreach_cli/commands/campaigns.py

@@ -0,0 +1,218 @@
+from __future__ import annotations
+
+import sys
+from dataclasses import asdict
+from typing import Optional
+
+import click
+
+from foxreach import CampaignCreate, CampaignUpdate, FoxReachError
+
+from ..client_factory import get_client
+from ..output import print_detail, print_error, print_json, print_meta, print_success, print_table
+
+
+@click.group()
+def campaigns() -> None:
+    """Manage campaigns."""
+
+
+@campaigns.command("list")
+@click.option("--status", default=None, type=click.Choice(["draft", "active", "paused", "completed"]))
+@click.option("--page", default=1, type=int)
+@click.option("--limit", default=50, type=int)
+@click.option("--json", "as_json", is_flag=True, help="Output as JSON")
+def campaigns_list(status: Optional[str], page: int, limit: int, as_json: bool) -> None:
+    """List campaigns."""
+    client = get_client()
+    try:
+        result = client.campaigns.list(page=page, page_size=limit, status=status)
+    except FoxReachError as e:
+        print_error(str(e))
+        sys.exit(1)
+
+    if as_json:
+        print_json({"data": [asdict(c) for c in result.data], "meta": asdict(result.meta)})
+        return
+
+    if not result.data:
+        click.echo("No campaigns found.")
+        return
+
+    print_table(
+        result.data,
+        ["ID", "Name", "Status", "Sent", "Replied", "Leads", "Daily Limit"],
+        {
+            "ID": "id", "Name": "name", "Status": "status",
+            "Sent": "total_sent", "Replied": "total_replied",
+            "Leads": "total_leads", "Daily Limit": "daily_limit",
+        },
+    )
+    print_meta(result.meta)
+
+
+@campaigns.command("get")
+@click.argument("campaign_id")
+@click.option("--json", "as_json", is_flag=True, help="Output as JSON")
+def campaigns_get(campaign_id: str, as_json: bool) -> None:
+    """Get a campaign by ID."""
+    client = get_client()
+    try:
+        campaign = client.campaigns.get(campaign_id)
+    except FoxReachError as e:
+        print_error(str(e))
+        sys.exit(1)
+
+    if as_json:
+        print_json(campaign)
+        return
+
+    print_detail(campaign, [
+        "id", "name", "status", "timezone", "sending_days",
+        "sending_start_hour", "sending_end_hour", "daily_limit",
+        "total_leads", "total_sent", "total_delivered",
+        "total_bounced", "total_replied", "total_opened",
+        "created_at", "started_at", "completed_at",
+    ])
+
+
+@campaigns.command("create")
+@click.option("--name", required=True, help="Campaign name")
+@click.option("--timezone", default=None, help="IANA timezone (e.g. America/New_York)")
+@click.option("--daily-limit", default=None, type=int, help="Max emails per day")
+@click.option("--start-hour", default=None, type=int, help="Sending start hour (0-23)")
+@click.option("--end-hour", default=None, type=int, help="Sending end hour (0-23)")
+@click.option("--json", "as_json", is_flag=True, help="Output as JSON")
+def campaigns_create(
+    name: str,
+    timezone: Optional[str],
+    daily_limit: Optional[int],
+    start_hour: Optional[int],
+    end_hour: Optional[int],
+    as_json: bool,
+) -> None:
+    """Create a new campaign."""
+    client = get_client()
+    try:
+        campaign = client.campaigns.create(CampaignCreate(
+            name=name,
+            timezone=timezone or "UTC",
+            daily_limit=daily_limit,
+            sending_start_hour=start_hour,
+            sending_end_hour=end_hour,
+        ))
+    except FoxReachError as e:
+        print_error(str(e))
+        sys.exit(1)
+
+    if as_json:
+        print_json(campaign)
+    else:
+        print_success(f"Campaign created: {campaign.id}")
+
+
+@campaigns.command("update")
+@click.argument("campaign_id")
+@click.option("--name", default=None, help="Campaign name")
+@click.option("--timezone", default=None, help="IANA timezone")
+@click.option("--daily-limit", default=None, type=int, help="Max emails per day")
+@click.option("--start-hour", default=None, type=int, help="Sending start hour")
+@click.option("--end-hour", default=None, type=int, help="Sending end hour")
+@click.option("--json", "as_json", is_flag=True, help="Output as JSON")
+def campaigns_update(
+    campaign_id: str,
+    name: Optional[str],
+    timezone: Optional[str],
+    daily_limit: Optional[int],
+    start_hour: Optional[int],
+    end_hour: Optional[int],
+    as_json: bool,
+) -> None:
+    """Update a campaign."""
+    client = get_client()
+    try:
+        campaign = client.campaigns.update(campaign_id, CampaignUpdate(
+            name=name,
+            timezone=timezone,
+            daily_limit=daily_limit,
+            sending_start_hour=start_hour,
+            sending_end_hour=end_hour,
+        ))
+    except FoxReachError as e:
+        print_error(str(e))
+        sys.exit(1)
+
+    if as_json:
+        print_json(campaign)
+    else:
+        print_success(f"Campaign updated: {campaign.id}")
+
+
+@campaigns.command("delete")
+@click.argument("campaign_id")
+@click.confirmation_option(prompt="Are you sure you want to delete this campaign?")
+def campaigns_delete(campaign_id: str) -> None:
+    """Delete a campaign (must be in draft status)."""
+    client = get_client()
+    try:
+        client.campaigns.delete(campaign_id)
+    except FoxReachError as e:
+        print_error(str(e))
+        sys.exit(1)
+    print_success(f"Campaign deleted: {campaign_id}")
+
+
+@campaigns.command("start")
+@click.argument("campaign_id")
+def campaigns_start(campaign_id: str) -> None:
+    """Start a campaign."""
+    client = get_client()
+    try:
+        campaign = client.campaigns.start(campaign_id)
+    except FoxReachError as e:
+        print_error(str(e))
+        sys.exit(1)
+    print_success(f"Campaign started: {campaign.name} ({campaign.id})")
+
+
+@campaigns.command("pause")
+@click.argument("campaign_id")
+def campaigns_pause(campaign_id: str) -> None:
+    """Pause a running campaign."""
+    client = get_client()
+    try:
+        campaign = client.campaigns.pause(campaign_id)
+    except FoxReachError as e:
+        print_error(str(e))
+        sys.exit(1)
+    print_success(f"Campaign paused: {campaign.name} ({campaign.id})")
+
+
+@campaigns.command("add-leads")
+@click.argument("campaign_id")
+@click.option("--lead-ids", required=True, help="Comma-separated lead IDs")
+def campaigns_add_leads(campaign_id: str, lead_ids: str) -> None:
+    """Add leads to a campaign."""
+    ids = [i.strip() for i in lead_ids.split(",") if i.strip()]
+    client = get_client()
+    try:
+        result = client.campaigns.add_leads(campaign_id, ids)
+    except FoxReachError as e:
+        print_error(str(e))
+        sys.exit(1)
+    print_success(f"Added {result.get('added', len(ids))} leads to campaign {campaign_id}")
+
+
+@campaigns.command("add-accounts")
+@click.argument("campaign_id")
+@click.option("--account-ids", required=True, help="Comma-separated account IDs")
+def campaigns_add_accounts(campaign_id: str, account_ids: str) -> None:
+    """Assign email accounts to a campaign."""
+    ids = [i.strip() for i in account_ids.split(",") if i.strip()]
+    client = get_client()
+    try:
+        result = client.campaigns.add_accounts(campaign_id, ids)
+    except FoxReachError as e:
+        print_error(str(e))
+        sys.exit(1)
+    print_success(f"Added {result.get('added', len(ids))} accounts to campaign {campaign_id}")

foxreach_cli/commands/inbox.py

@@ -0,0 +1,123 @@
+from __future__ import annotations
+
+import sys
+from dataclasses import asdict
+from typing import Optional
+
+import click
+
+from foxreach import FoxReachError, ThreadUpdate
+
+from ..client_factory import get_client
+from ..output import print_detail, print_error, print_json, print_meta, print_success, print_table
+
+
+@click.group()
+def inbox() -> None:
+    """Manage inbox threads."""
+
+
+@inbox.command("list")
+@click.option("--category", default=None, help="Filter by category")
+@click.option("--unread", is_flag=True, default=False, help="Show only unread")
+@click.option("--starred", is_flag=True, default=False, help="Show only starred")
+@click.option("--campaign", default=None, help="Filter by campaign ID")
+@click.option("--account", default=None, help="Filter by account ID")
+@click.option("--search", default=None, help="Search threads")
+@click.option("--page", default=1, type=int)
+@click.option("--limit", default=50, type=int)
+@click.option("--json", "as_json", is_flag=True, help="Output as JSON")
+def inbox_list(
+    category: Optional[str],
+    unread: bool,
+    starred: bool,
+    campaign: Optional[str],
+    account: Optional[str],
+    search: Optional[str],
+    page: int,
+    limit: int,
+    as_json: bool,
+) -> None:
+    """List inbox threads."""
+    client = get_client()
+    try:
+        result = client.inbox.list_threads(
+            page=page,
+            page_size=limit,
+            category=category,
+            is_read=False if unread else None,
+            is_starred=True if starred else None,
+            campaign_id=campaign,
+            account_id=account,
+            search=search,
+        )
+    except FoxReachError as e:
+        print_error(str(e))
+        sys.exit(1)
+
+    if as_json:
+        print_json({"data": [asdict(t) for t in result.data], "meta": asdict(result.meta)})
+        return
+
+    if not result.data:
+        click.echo("No threads found.")
+        return
+
+    print_table(
+        result.data,
+        ["ID", "From", "Subject", "Category", "Read", "Starred", "Received"],
+        {
+            "ID": "id", "From": "from_email", "Subject": "subject",
+            "Category": "category", "Read": "is_read",
+            "Starred": "is_starred", "Received": "received_at",
+        },
+    )
+    print_meta(result.meta)
+
+
+@inbox.command("get")
+@click.argument("reply_id")
+@click.option("--json", "as_json", is_flag=True, help="Output as JSON")
+def inbox_get(reply_id: str, as_json: bool) -> None:
+    """Get a thread by ID."""
+    client = get_client()
+    try:
+        thread = client.inbox.get(reply_id)
+    except FoxReachError as e:
+        print_error(str(e))
+        sys.exit(1)
+
+    if as_json:
+        print_json(thread)
+        return
+
+    print_detail(thread, [
+        "id", "from_email", "to_email", "subject",
+        "body_plain", "category", "is_read", "is_starred",
+        "campaign_id", "lead_id", "received_at",
+    ])
+
+
+@inbox.command("update")
+@click.argument("reply_id")
+@click.option("--read/--unread", default=None, help="Mark as read or unread")
+@click.option("--starred/--unstarred", default=None, help="Star or unstar")
+@click.option("--category", default=None, help="Set category")
+@click.option("--json", "as_json", is_flag=True, help="Output as JSON")
+def inbox_update(reply_id: str, read: Optional[bool], starred: Optional[bool], category: Optional[str], as_json: bool) -> None:
+    """Update a thread (read status, star, category)."""
+    client = get_client()
+    try:
+        thread = client.inbox.update(reply_id, ThreadUpdate(
+            is_read=read,
+            is_starred=starred,
+            category=category,
+        ))
+    except FoxReachError as e:
+        print_error(str(e))
+        sys.exit(1)
+
+    if as_json:
+        print_json(thread)
+    else:
+        print_success(f"Thread updated: {reply_id}")