asa-api-cli 0.1.0__py3-none-any.whl

asa_api_cli/__init__.py

@@ -0,0 +1,15 @@
+"""Command-line interface for Apple Search Ads.
+
+This module provides a CLI for interacting with the Apple Search Ads API.
+
+Usage:
+    asa --help
+    asa campaigns list
+    asa reports campaigns --start 2024-01-01 --end 2024-01-31
+"""
+
+from asa_api_cli.main import app
+
+__all__ = ["app"]
+
+__version__ = "0.1.0"

asa_api_cli/ad_groups.py

@@ -0,0 +1,270 @@
+"""Ad Group CLI commands."""
+
+from typing import Annotated, Any
+
+import typer
+from asa_api_client.exceptions import AppleSearchAdsError
+from asa_api_client.models import AdGroupStatus, AdGroupUpdate, Money, Selector
+
+from asa_api_cli.utils import (
+    OutputFormat,
+    confirm_action,
+    enum_value,
+    format_money,
+    get_client,
+    handle_api_error,
+    output_data,
+    print_json,
+    print_result_panel,
+    print_success,
+    print_warning,
+    spinner,
+)
+
+app = typer.Typer(help="Manage ad groups")
+
+AD_GROUP_COLUMNS = [
+    "id",
+    "name",
+    "status",
+    "serving_status",
+    "default_bid",
+    "search_match",
+]
+
+AD_GROUP_COLUMN_LABELS = {
+    "id": "ID",
+    "serving_status": "Serving",
+    "default_bid": "Default Bid",
+    "search_match": "Search Match",
+}
+
+
+def ad_group_to_dict(ad_group: object) -> dict[str, Any]:
+    """Convert ad group to display dictionary."""
+    return {
+        "id": ad_group.id,  # type: ignore
+        "name": ad_group.name,  # type: ignore
+        "status": enum_value(ad_group.status),  # type: ignore
+        "serving_status": enum_value(ad_group.serving_status),  # type: ignore
+        "default_bid": format_money(
+            ad_group.default_bid_amount.amount,  # type: ignore
+            ad_group.default_bid_amount.currency,  # type: ignore
+        ),
+        "search_match": enum_value(ad_group.automated_keywords_opt_in),  # type: ignore
+    }
+
+
+@app.command("list")
+def list_ad_groups(
+    campaign_id: Annotated[int, typer.Argument(help="Campaign ID")],
+    status: Annotated[
+        AdGroupStatus | None,
+        typer.Option("--status", "-s", help="Filter by status"),
+    ] = None,
+    limit: Annotated[
+        int,
+        typer.Option("--limit", "-l", help="Maximum number of results"),
+    ] = 100,
+    format: Annotated[
+        OutputFormat,
+        typer.Option("--format", "-f", help="Output format"),
+    ] = OutputFormat.TABLE,
+) -> None:
+    """List ad groups in a campaign.
+
+    Examples:
+        asa ad-groups list 123456789
+        asa ad-groups list 123456789 --status ENABLED
+        asa ad-groups list 123456789 --format json
+    """
+    client = get_client()
+
+    try:
+        with client:
+            with spinner("Fetching ad groups..."):
+                if status:
+                    selector = Selector().where("status", "==", status.value).limit(limit)
+                    ad_groups = client.campaigns(campaign_id).ad_groups.find(selector)
+                else:
+                    ad_groups = client.campaigns(campaign_id).ad_groups.list(limit=limit)
+
+            if not ad_groups.data:
+                print_warning("No ad groups found")
+                return
+
+            data = [ad_group_to_dict(ag) for ag in ad_groups]
+            output_data(
+                data,
+                AD_GROUP_COLUMNS,
+                format,
+                title=f"Ad Groups ({ad_groups.total_results} total)",
+                column_labels=AD_GROUP_COLUMN_LABELS,
+            )
+
+    except AppleSearchAdsError as e:
+        handle_api_error(e)
+        raise typer.Exit(1) from None
+
+
+@app.command("get")
+def get_ad_group(
+    campaign_id: Annotated[int, typer.Argument(help="Campaign ID")],
+    ad_group_id: Annotated[int, typer.Argument(help="Ad Group ID")],
+    format: Annotated[
+        OutputFormat,
+        typer.Option("--format", "-f", help="Output format"),
+    ] = OutputFormat.JSON,
+) -> None:
+    """Get details for a specific ad group.
+
+    Examples:
+        asa ad-groups get 123456789 987654321
+        asa ad-groups get 123456789 987654321 --format table
+    """
+    client = get_client()
+
+    try:
+        with client:
+            with spinner("Fetching ad group..."):
+                ad_group = client.campaigns(campaign_id).ad_groups.get(ad_group_id)
+
+            if format == OutputFormat.JSON:
+                print_json(ad_group, title=f"Ad Group {ad_group_id}")
+            else:
+                data = [ad_group_to_dict(ad_group)]
+                output_data(data, AD_GROUP_COLUMNS, format, column_labels=AD_GROUP_COLUMN_LABELS)
+
+    except AppleSearchAdsError as e:
+        handle_api_error(e)
+        raise typer.Exit(1) from None
+
+
+@app.command("pause")
+def pause_ad_group(
+    campaign_id: Annotated[int, typer.Argument(help="Campaign ID")],
+    ad_group_id: Annotated[int, typer.Argument(help="Ad Group ID to pause")],
+) -> None:
+    """Pause an ad group.
+
+    Examples:
+        asa ad-groups pause 123456789 987654321
+    """
+    client = get_client()
+
+    try:
+        with client:
+            with spinner("Pausing ad group..."):
+                ad_group = client.campaigns(campaign_id).ad_groups.update(
+                    ad_group_id,
+                    data=AdGroupUpdate(status=AdGroupStatus.PAUSED),
+                )
+            print_success(f"Ad group '{ad_group.name}' paused")
+
+    except AppleSearchAdsError as e:
+        handle_api_error(e)
+        raise typer.Exit(1) from None
+
+
+@app.command("enable")
+def enable_ad_group(
+    campaign_id: Annotated[int, typer.Argument(help="Campaign ID")],
+    ad_group_id: Annotated[int, typer.Argument(help="Ad Group ID to enable")],
+) -> None:
+    """Enable a paused ad group.
+
+    Examples:
+        asa ad-groups enable 123456789 987654321
+    """
+    client = get_client()
+
+    try:
+        with client:
+            with spinner("Enabling ad group..."):
+                ad_group = client.campaigns(campaign_id).ad_groups.update(
+                    ad_group_id,
+                    data=AdGroupUpdate(status=AdGroupStatus.ENABLED),
+                )
+            print_success(f"Ad group '{ad_group.name}' enabled")
+
+    except AppleSearchAdsError as e:
+        handle_api_error(e)
+        raise typer.Exit(1) from None
+
+
+@app.command("set-bid")
+def set_default_bid(
+    campaign_id: Annotated[int, typer.Argument(help="Campaign ID")],
+    ad_group_id: Annotated[int, typer.Argument(help="Ad Group ID")],
+    bid: Annotated[float, typer.Argument(help="New default bid amount")],
+    currency: Annotated[
+        str,
+        typer.Option("--currency", "-c", help="Currency code"),
+    ] = "USD",
+) -> None:
+    """Set the default bid for an ad group.
+
+    Examples:
+        asa ad-groups set-bid 123456789 987654321 2.50
+        asa ad-groups set-bid 123456789 987654321 2.50 --currency EUR
+    """
+    client = get_client()
+
+    try:
+        with client:
+            with spinner("Updating default bid..."):
+                ad_group = client.campaigns(campaign_id).ad_groups.update(
+                    ad_group_id,
+                    data=AdGroupUpdate(default_bid_amount=Money(amount=str(bid), currency=currency)),
+                )
+
+            print_result_panel(
+                "Default Bid Updated",
+                {
+                    "Ad Group": ad_group.name,
+                    "Default Bid": f"{ad_group.default_bid_amount.amount} {ad_group.default_bid_amount.currency}",
+                },
+            )
+
+    except AppleSearchAdsError as e:
+        handle_api_error(e)
+        raise typer.Exit(1) from None
+
+
+@app.command("delete")
+def delete_ad_group(
+    campaign_id: Annotated[int, typer.Argument(help="Campaign ID")],
+    ad_group_id: Annotated[int, typer.Argument(help="Ad Group ID to delete")],
+    force: Annotated[
+        bool,
+        typer.Option("--force", "-f", help="Skip confirmation"),
+    ] = False,
+) -> None:
+    """Delete an ad group.
+
+    WARNING: This action cannot be undone.
+
+    Examples:
+        asa ad-groups delete 123456789 987654321
+        asa ad-groups delete 123456789 987654321 --force
+    """
+    client = get_client()
+
+    try:
+        with client:
+            with spinner("Fetching ad group..."):
+                ad_group = client.campaigns(campaign_id).ad_groups.get(ad_group_id)
+
+            if not force:
+                if not confirm_action(f"Are you sure you want to delete ad group '{ad_group.name}'?"):
+                    print_warning("Cancelled")
+                    raise typer.Exit(0)
+
+            with spinner("Deleting ad group..."):
+                client.campaigns(campaign_id).ad_groups.delete(ad_group_id)
+
+            print_success(f"Ad group '{ad_group.name}' deleted")
+
+    except AppleSearchAdsError as e:
+        handle_api_error(e)
+        raise typer.Exit(1) from None

asa_api_cli/auth.py

@@ -0,0 +1,186 @@
+"""Authentication CLI commands."""
+
+from pathlib import Path
+from typing import Annotated
+
+import typer
+from asa_api_client import AppleSearchAdsClient, Settings
+from asa_api_client.exceptions import AppleSearchAdsError, ConfigurationError
+from pydantic import ValidationError
+from rich.table import Table
+
+from asa_api_cli.utils import (
+    console,
+    print_error,
+    print_info,
+    print_result_panel,
+    spinner,
+)
+
+app = typer.Typer(help="Authentication commands")
+
+
+@app.command("test")
+def test_auth(
+    env_file: Annotated[
+        Path | None,
+        typer.Option("--env-file", "-e", help="Path to .env file"),
+    ] = Path(".env"),
+) -> None:
+    """Test authentication credentials.
+
+    Loads configuration from environment variables and .env file,
+    then attempts to authenticate with the Apple Search Ads API.
+
+    Examples:
+        asa auth test
+        asa auth test --env-file .env.production
+    """
+    print_info("Testing Apple Search Ads API credentials...")
+    console.print()
+
+    # Try to load settings
+    try:
+        if env_file and env_file.exists():
+            settings = Settings(_env_file=env_file)  # type: ignore[call-arg]
+            print_info(f"Loaded configuration from {env_file}")
+        else:
+            settings = Settings(_env_file=None)  # type: ignore[call-arg]
+            if env_file:
+                print_info("No .env file found, using environment variables only")
+    except ValidationError as e:
+        # Show what's missing
+        table = Table(
+            title="Configuration Status",
+            show_header=True,
+            header_style="header",
+            border_style="muted",
+        )
+        table.add_column("Setting", style="label")
+        table.add_column("Status")
+
+        errors_by_field = {err["loc"][0]: err["msg"] for err in e.errors()}
+
+        for field in ["client_id", "team_id", "key_id", "org_id", "private_key", "private_key_path"]:
+            if field in errors_by_field:
+                table.add_row(f"ASA_{field.upper()}", f"[error]{errors_by_field[field]}[/error]")
+            else:
+                table.add_row(f"ASA_{field.upper()}", "[success]OK[/success]")
+
+        console.print(table)
+        console.print()
+        print_error("Configuration Error", "Missing or invalid settings")
+        raise typer.Exit(1) from None
+
+    # Display loaded configuration
+    table = Table(
+        title="Configuration",
+        show_header=True,
+        header_style="header",
+        border_style="muted",
+    )
+    table.add_column("Setting", style="label")
+    table.add_column("Value")
+
+    # Mask client_id
+    client_id_display = settings.client_id[:20] + "..." if len(settings.client_id) > 20 else settings.client_id
+    table.add_row("ASA_CLIENT_ID", f"[success]{client_id_display}[/success]")
+    table.add_row("ASA_TEAM_ID", f"[success]{settings.team_id}[/success]")
+    table.add_row("ASA_KEY_ID", f"[success]{settings.key_id}[/success]")
+    table.add_row("ASA_ORG_ID", f"[success]{settings.org_id}[/success]")
+
+    if settings.private_key_path:
+        table.add_row("ASA_PRIVATE_KEY_PATH", f"[success]{settings.private_key_path}[/success]")
+    if settings.private_key:
+        table.add_row("ASA_PRIVATE_KEY", "[success]<set>[/success]")
+
+    console.print(table)
+    console.print()
+
+    # Try to authenticate
+    print_info("Attempting to authenticate...")
+
+    try:
+        client = AppleSearchAdsClient.from_env(env_file=env_file)
+    except ConfigurationError as e:
+        print_error("Configuration Error", e.message)
+        raise typer.Exit(1) from None
+
+    try:
+        # Try to list campaigns to verify authentication works
+        with client:
+            with spinner("Authenticating with Apple Search Ads API..."):
+                campaigns = client.campaigns.list(limit=1)
+
+            print_result_panel(
+                "Authentication Successful",
+                {
+                    "Organization ID": str(client.org_id),
+                    "Total Campaigns": str(campaigns.total_results),
+                },
+            )
+
+    except AppleSearchAdsError as e:
+        print_error("API Error", e.message, f"Status code: {e.status_code}" if e.status_code else None)
+        raise typer.Exit(1) from None
+
+
+@app.command("show")
+def show_config(
+    env_file: Annotated[
+        Path | None,
+        typer.Option("--env-file", "-e", help="Path to .env file"),
+    ] = Path(".env"),
+) -> None:
+    """Show current authentication configuration.
+
+    Displays configuration loaded from environment variables and .env file.
+
+    Examples:
+        asa auth show
+        asa auth show --env-file .env.production
+    """
+    # Try to load settings
+    try:
+        if env_file and env_file.exists():
+            settings = Settings(_env_file=env_file)  # type: ignore[call-arg]
+            source = f"from {env_file}"
+        else:
+            settings = Settings(_env_file=None)  # type: ignore[call-arg]
+            source = "from environment variables"
+
+        table = Table(
+            title=f"Current Configuration ({source})",
+            show_header=True,
+            header_style="header",
+            border_style="muted",
+        )
+        table.add_column("Setting", style="label")
+        table.add_column("Value")
+
+        # Mask client_id partially
+        client_id_display = settings.client_id[:20] + "..." if len(settings.client_id) > 20 else settings.client_id
+        table.add_row("ASA_CLIENT_ID", client_id_display)
+        table.add_row("ASA_TEAM_ID", settings.team_id)
+        table.add_row("ASA_KEY_ID", settings.key_id)
+        table.add_row("ASA_ORG_ID", str(settings.org_id))
+
+        if settings.private_key_path:
+            table.add_row("ASA_PRIVATE_KEY_PATH", str(settings.private_key_path))
+        else:
+            table.add_row("ASA_PRIVATE_KEY_PATH", "[muted]<not set>[/muted]")
+
+        if settings.private_key:
+            table.add_row("ASA_PRIVATE_KEY", "[success]<set>[/success]")
+        else:
+            table.add_row("ASA_PRIVATE_KEY", "[muted]<not set>[/muted]")
+
+        console.print(table)
+
+    except ValidationError as e:
+        print_error("Configuration Error", "Could not load settings")
+        for err in e.errors():
+            field = err["loc"][0]
+            msg = err["msg"]
+            console.print(f"  [error]ASA_{str(field).upper()}:[/error] {msg}")
+        raise typer.Exit(1) from None