asa-api-cli 0.2.0__tar.gz → 0.3.0__tar.gz

{asa_api_cli-0.2.0 → asa_api_cli-0.3.0}/.github/workflows/ci.yml

@@ -40,7 +40,7 @@ jobs:
         run: uv run pytest --cov=asa_api_cli --cov-report=xml
 
       - name: Upload coverage to Codecov
-        uses: codecov/codecov-action@v5
+        uses: codecov/codecov-action@v7
         with:
           file: ./coverage.xml
           fail_ci_if_error: false

{asa_api_cli-0.2.0 → asa_api_cli-0.3.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: asa-api-cli
-Version: 0.2.0
+Version: 0.3.0
 Summary: Command-line interface for Apple Search Ads campaign management
 Project-URL: Homepage, https://github.com/SamPetherbridge/asa-api-cli
 Project-URL: Repository, https://github.com/SamPetherbridge/asa-api-cli
@@ -18,7 +18,7 @@ Classifier: Programming Language :: Python :: 3
 Classifier: Programming Language :: Python :: 3.13
 Classifier: Typing :: Typed
 Requires-Python: >=3.13
-Requires-Dist: asa-api-client>=0.1.5
+Requires-Dist: asa-api-client>=0.2.1
 Requires-Dist: pydantic-ai>=0.1.0
 Requires-Dist: pydantic-settings>=2.0.0
 Requires-Dist: rich>=13.9.0

{asa_api_cli-0.2.0 → asa_api_cli-0.3.0}/asa_api_cli/__init__.py

@@ -8,8 +8,13 @@ Usage:
     asa reports campaigns --start 2024-01-01 --end 2024-01-31
 """
 
+from importlib.metadata import PackageNotFoundError, version
+
 from asa_api_cli.main import app
 
 __all__ = ["app"]
 
-__version__ = "0.2.0"
+try:
+    __version__ = version("asa-api-cli")
+except PackageNotFoundError:  # pragma: no cover - only when running from a non-installed checkout
+    __version__ = "0.0.0"

asa_api_cli-0.3.0/asa_api_cli/ads.py

@@ -0,0 +1,345 @@
+"""Ad (creative) CLI commands."""
+
+from typing import Annotated, Any
+
+import typer
+from asa_api_client.exceptions import AppleSearchAdsError
+from asa_api_client.models import AdCreate, AdStatus, AdUpdate, CreativeType
+
+from asa_api_cli.utils import (
+    EXIT_ERROR,
+    EXIT_USAGE,
+    OutputFormat,
+    confirm_action,
+    enum_value,
+    get_client,
+    handle_api_error,
+    output_data,
+    print_error,
+    print_info,
+    print_result_panel,
+    print_success,
+    print_warning,
+    spinner,
+)
+
+app = typer.Typer(help="View and manage ads (creatives) within ad groups")
+
+AD_COLUMNS = ["id", "name", "creative_type", "status", "serving_status", "creative_id"]
+
+
+def _validate_create(creative_type: CreativeType, product_page_id: str | None) -> None:
+    """Validate the creative-type / product-page combination before any API call.
+
+    Raises typer.Exit(EXIT_USAGE) with a friendly message on an invalid combination.
+    """
+    if creative_type == CreativeType.CREATIVE_SET:
+        print_error(
+            "Unsupported creative type",
+            "CREATIVE_SET ads require selecting creative set assets, which this command "
+            "does not support yet. Use CUSTOM_PRODUCT_PAGE or DEFAULT_PRODUCT_PAGE.",
+        )
+        raise typer.Exit(EXIT_USAGE)
+    if creative_type == CreativeType.CUSTOM_PRODUCT_PAGE and not product_page_id:
+        print_error(
+            "Missing product page",
+            "CUSTOM_PRODUCT_PAGE ads require --product-page <id>. Find ids with 'asa product-pages list'.",
+        )
+        raise typer.Exit(EXIT_USAGE)
+    if creative_type == CreativeType.DEFAULT_PRODUCT_PAGE and product_page_id:
+        print_error(
+            "Unexpected product page",
+            "DEFAULT_PRODUCT_PAGE ads must not specify --product-page.",
+        )
+        raise typer.Exit(EXIT_USAGE)
+
+
+@app.command("list")
+def list_ads(
+    campaign_id: Annotated[
+        int,
+        typer.Option("--campaign", "-c", help="Campaign ID"),
+    ],
+    ad_group_id: Annotated[
+        int,
+        typer.Option("--ad-group", "-a", help="Ad group ID"),
+    ],
+    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 ads in an ad group.
+
+    Examples:
+        asa ads list --campaign 123 --ad-group 456
+        asa ads list -c 123 -a 456 --format json
+    """
+    client = get_client()
+
+    try:
+        with client:
+            with spinner("Fetching ads..."):
+                result = client.campaigns(campaign_id).ad_groups(ad_group_id).ads.list(limit=limit)
+
+            if not result.data:
+                print_warning("No ads found")
+                return
+
+            rows: list[dict[str, Any]] = [
+                {
+                    "id": ad.id,
+                    "name": ad.name,
+                    "creative_type": enum_value(ad.creative_type),
+                    "status": enum_value(ad.status),
+                    "serving_status": enum_value(ad.serving_status),
+                    "creative_id": ad.creative_id or "-",
+                }
+                for ad in result.data
+            ]
+
+            output_data(rows, AD_COLUMNS, format, title=f"Ads in ad group {ad_group_id}")
+    except AppleSearchAdsError as e:
+        handle_api_error(e)
+        raise typer.Exit(EXIT_ERROR) from None
+
+
+@app.command("get")
+def get_ad(
+    ad_id: Annotated[
+        int,
+        typer.Argument(help="Ad ID"),
+    ],
+    campaign_id: Annotated[
+        int,
+        typer.Option("--campaign", "-c", help="Campaign ID"),
+    ],
+    ad_group_id: Annotated[
+        int,
+        typer.Option("--ad-group", "-a", help="Ad group ID"),
+    ],
+) -> None:
+    """Show details for a single ad.
+
+    Example:
+        asa ads get 789 --campaign 123 --ad-group 456
+    """
+    client = get_client()
+
+    try:
+        with client:
+            with spinner("Fetching ad..."):
+                ad = client.campaigns(campaign_id).ad_groups(ad_group_id).ads.get(ad_id)
+
+            print_result_panel(
+                f"Ad {ad.id}",
+                {
+                    "Name": ad.name,
+                    "Creative type": enum_value(ad.creative_type),
+                    "Status": enum_value(ad.status),
+                    "Serving status": enum_value(ad.serving_status),
+                    "Creative ID": str(ad.creative_id) if ad.creative_id else "-",
+                    "Campaign ID": str(ad.campaign_id),
+                    "Ad group ID": str(ad.ad_group_id),
+                },
+            )
+    except AppleSearchAdsError as e:
+        handle_api_error(e)
+        raise typer.Exit(EXIT_ERROR) from None
+
+
+@app.command("create")
+def create_ad(
+    name: Annotated[
+        str,
+        typer.Option("--name", "-n", help="Ad name"),
+    ],
+    campaign_id: Annotated[
+        int,
+        typer.Option("--campaign", "-c", help="Campaign ID"),
+    ],
+    ad_group_id: Annotated[
+        int,
+        typer.Option("--ad-group", "-a", help="Ad group ID"),
+    ],
+    creative_type: Annotated[
+        CreativeType,
+        typer.Option("--creative-type", "-t", help="Creative type"),
+    ] = CreativeType.CUSTOM_PRODUCT_PAGE,
+    product_page_id: Annotated[
+        str | None,
+        typer.Option("--product-page", "-p", help="Custom product page ID (required for CUSTOM_PRODUCT_PAGE)"),
+    ] = None,
+    status: Annotated[
+        AdStatus,
+        typer.Option("--status", "-s", help="Initial status"),
+    ] = AdStatus.ENABLED,
+    dry_run: Annotated[
+        bool,
+        typer.Option("--dry-run", help="Preview the ad payload without creating it"),
+    ] = False,
+    yes: Annotated[
+        bool,
+        typer.Option("--yes", "-y", help="Skip the confirmation prompt"),
+    ] = False,
+) -> None:
+    """Create an ad in an ad group.
+
+    CUSTOM_PRODUCT_PAGE ads need a --product-page id (see 'asa product-pages list').
+    DEFAULT_PRODUCT_PAGE ads use the app's default page and take no product page.
+
+    Examples:
+        asa ads create -c 123 -a 456 -n "Holiday CPP" -p <product-page-id>
+        asa ads create -c 123 -a 456 -n "Default ad" -t DEFAULT_PRODUCT_PAGE
+        asa ads create -c 123 -a 456 -n "Preview" -p <id> --dry-run
+    """
+    _validate_create(creative_type, product_page_id)
+
+    payload = AdCreate(
+        name=name,
+        creative_type=creative_type,
+        status=status,
+        product_page_id=product_page_id,
+    )
+
+    preview = {
+        "Name": name,
+        "Creative type": enum_value(creative_type),
+        "Status": enum_value(status),
+        "Product page": product_page_id or "-",
+        "Campaign ID": str(campaign_id),
+        "Ad group ID": str(ad_group_id),
+    }
+
+    if dry_run:
+        print_info("Dry run - no ad created")
+        print_result_panel("Ad payload", preview)
+        return
+
+    if not yes and not confirm_action(f"Create ad '{name}' in ad group {ad_group_id}?", default=True):
+        print_info("Cancelled")
+        return
+
+    client = get_client()
+
+    try:
+        with client:
+            with spinner("Creating ad..."):
+                ad = client.campaigns(campaign_id).ad_groups(ad_group_id).ads.create(payload)
+
+            print_success(f"Created ad {ad.id}: {ad.name}")
+            print_result_panel(
+                f"Ad {ad.id}",
+                {
+                    "Name": ad.name,
+                    "Creative type": enum_value(ad.creative_type),
+                    "Status": enum_value(ad.status),
+                    "Serving status": enum_value(ad.serving_status),
+                },
+            )
+    except AppleSearchAdsError as e:
+        handle_api_error(e)
+        raise typer.Exit(EXIT_ERROR) from None
+
+
+@app.command("update")
+def update_ad(
+    ad_id: Annotated[
+        int,
+        typer.Argument(help="Ad ID"),
+    ],
+    campaign_id: Annotated[
+        int,
+        typer.Option("--campaign", "-c", help="Campaign ID"),
+    ],
+    ad_group_id: Annotated[
+        int,
+        typer.Option("--ad-group", "-a", help="Ad group ID"),
+    ],
+    name: Annotated[
+        str | None,
+        typer.Option("--name", "-n", help="New ad name"),
+    ] = None,
+    status: Annotated[
+        AdStatus | None,
+        typer.Option("--status", "-s", help="New status (ENABLED or PAUSED)"),
+    ] = None,
+) -> None:
+    """Update an ad's name and/or status.
+
+    At least one of --name or --status must be provided.
+
+    Examples:
+        asa ads update 789 -c 123 -a 456 --status PAUSED
+        asa ads update 789 -c 123 -a 456 --name "Renamed ad"
+    """
+    if name is None and status is None:
+        print_error("Nothing to update", "Provide at least one of --name or --status.")
+        raise typer.Exit(EXIT_USAGE)
+
+    payload = AdUpdate(name=name, status=status)
+
+    client = get_client()
+
+    try:
+        with client:
+            with spinner("Updating ad..."):
+                ad = client.campaigns(campaign_id).ad_groups(ad_group_id).ads.update(ad_id, payload)
+
+            print_success(f"Updated ad {ad.id}")
+            print_result_panel(
+                f"Ad {ad.id}",
+                {
+                    "Name": ad.name,
+                    "Status": enum_value(ad.status),
+                    "Serving status": enum_value(ad.serving_status),
+                },
+            )
+    except AppleSearchAdsError as e:
+        handle_api_error(e)
+        raise typer.Exit(EXIT_ERROR) from None
+
+
+@app.command("delete")
+def delete_ad(
+    ad_id: Annotated[
+        int,
+        typer.Argument(help="Ad ID"),
+    ],
+    campaign_id: Annotated[
+        int,
+        typer.Option("--campaign", "-c", help="Campaign ID"),
+    ],
+    ad_group_id: Annotated[
+        int,
+        typer.Option("--ad-group", "-a", help="Ad group ID"),
+    ],
+    yes: Annotated[
+        bool,
+        typer.Option("--yes", "-y", help="Skip the confirmation prompt"),
+    ] = False,
+) -> None:
+    """Delete an ad.
+
+    Example:
+        asa ads delete 789 -c 123 -a 456
+    """
+    if not yes and not confirm_action(f"Delete ad {ad_id}? This cannot be undone.", default=False):
+        print_info("Cancelled")
+        return
+
+    client = get_client()
+
+    try:
+        with client:
+            with spinner("Deleting ad..."):
+                client.campaigns(campaign_id).ad_groups(ad_group_id).ads.delete(ad_id)
+
+            print_success(f"Deleted ad {ad_id}")
+    except AppleSearchAdsError as e:
+        handle_api_error(e)
+        raise typer.Exit(EXIT_ERROR) from None

asa_api_cli-0.3.0/asa_api_cli/apps.py

@@ -0,0 +1,81 @@
+"""App lookup CLI commands."""
+
+from typing import Annotated, Any
+
+import typer
+from asa_api_client.exceptions import AppleSearchAdsError
+
+from asa_api_cli.utils import (
+    EXIT_ERROR,
+    OutputFormat,
+    get_client,
+    handle_api_error,
+    output_data,
+    print_warning,
+    spinner,
+)
+
+app = typer.Typer(help="Search the App Store for advertisable apps")
+
+APP_COLUMNS = ["adam_id", "app_name", "developer_name", "countries"]
+
+
+@app.command("search")
+def search_apps(
+    query: Annotated[
+        str,
+        typer.Argument(help="Search term (app name or keyword)"),
+    ],
+    own: Annotated[
+        bool,
+        typer.Option("--own", help="Only return apps owned by your org"),
+    ] = False,
+    limit: Annotated[
+        int,
+        typer.Option("--limit", "-l", help="Maximum number of results"),
+    ] = 50,
+    format: Annotated[
+        OutputFormat,
+        typer.Option("--format", "-f", help="Output format"),
+    ] = OutputFormat.TABLE,
+) -> None:
+    """Search for iOS apps eligible for advertising.
+
+    Returns each app's adamId — the identifier you need to create campaigns.
+
+    Examples:
+        asa apps search "weather"
+        asa apps search "my app" --own
+        asa apps search photo --limit 10 --format json
+    """
+    client = get_client()
+
+    try:
+        with client:
+            with spinner("Searching App Store..."):
+                results = client.apps.search(query=query, return_own_apps=own, limit=limit)
+
+            if not results:
+                print_warning("No apps found")
+                return
+
+            rows: list[dict[str, Any]] = [
+                {
+                    "adam_id": app_info.adam_id,
+                    "app_name": app_info.app_name,
+                    "developer_name": app_info.developer_name or "-",
+                    "countries": ", ".join(app_info.country_or_region_codes or []) or "-",
+                }
+                for app_info in results
+            ]
+
+            output_data(
+                rows,
+                APP_COLUMNS,
+                format,
+                title=f"App search: {query}",
+                column_labels={"adam_id": "adam ID"},
+            )
+    except AppleSearchAdsError as e:
+        handle_api_error(e)
+        raise typer.Exit(EXIT_ERROR) from None

{asa_api_cli-0.2.0 → asa_api_cli-0.3.0}/asa_api_cli/auth.py

@@ -1,7 +1,7 @@
 """Authentication CLI commands."""
 
 from pathlib import Path
-from typing import Annotated
+from typing import Annotated, Any
 
 import typer
 from asa_api_client import AppleSearchAdsClient, Settings
@@ -12,8 +12,12 @@ from rich.table import Table
 from asa_api_cli.utils import (
     EXIT_ERROR,
     EXIT_USAGE,
+    OutputFormat,
     console,
     error_console,
+    get_client,
+    handle_api_error,
+    output_data,
     print_error,
     print_info,
     print_result_panel,
@@ -200,3 +204,55 @@ def show_config(
             msg = err["msg"]
             error_console.print(f"  [error]ASA_{str(field).upper()}:[/error] {msg}")
         raise typer.Exit(EXIT_USAGE) from None
+
+
+ORG_COLUMNS = ["org_id", "org_name", "currency", "role_names", "time_zone"]
+
+
+@app.command("orgs")
+def list_orgs(
+    format: Annotated[
+        OutputFormat,
+        typer.Option("--format", "-f", help="Output format"),
+    ] = OutputFormat.TABLE,
+) -> None:
+    """List organizations your credentials can access.
+
+    Shows each org's ID (use as ASA_ORG_ID), name, currency, and your roles.
+
+    Examples:
+        asa auth orgs
+        asa auth orgs --format json
+    """
+    client = get_client()
+
+    try:
+        with client:
+            with spinner("Fetching accessible organizations..."):
+                acls = client.acls.list()
+
+            if not acls:
+                print_warning("No organizations found for these credentials")
+                return
+
+            rows: list[dict[str, Any]] = [
+                {
+                    "org_id": acl.org_id,
+                    "org_name": acl.org_name,
+                    "currency": acl.currency or "-",
+                    "role_names": ", ".join(acl.role_names) or "-",
+                    "time_zone": acl.time_zone or "-",
+                }
+                for acl in acls
+            ]
+
+            output_data(
+                rows,
+                ORG_COLUMNS,
+                format,
+                title="Accessible organizations",
+                column_labels={"org_id": "Org ID", "time_zone": "Time Zone"},
+            )
+    except AppleSearchAdsError as e:
+        handle_api_error(e)
+        raise typer.Exit(EXIT_ERROR) from None

asa_api_cli-0.3.0/asa_api_cli/budget_orders.py

@@ -0,0 +1,114 @@
+"""Budget order CLI commands."""
+
+from typing import Annotated, Any
+
+import typer
+from asa_api_client.exceptions import AppleSearchAdsError
+
+from asa_api_cli.utils import (
+    EXIT_ERROR,
+    OutputFormat,
+    enum_value,
+    format_money,
+    get_client,
+    handle_api_error,
+    output_data,
+    print_result_panel,
+    print_warning,
+    spinner,
+)
+
+app = typer.Typer(help="View budget orders")
+
+BUDGET_ORDER_COLUMNS = ["id", "name", "status", "budget", "order_number", "start_date", "end_date"]
+
+
+def _date_str(value: object) -> str:
+    """Render a datetime/date-ish value as an ISO date, or '-'."""
+    if value is None:
+        return "-"
+    return str(value).split("T")[0].split(" ")[0]
+
+
+@app.command("list")
+def list_budget_orders(
+    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 budget orders.
+
+    Examples:
+        asa budget-orders list
+        asa budget-orders list --format json
+    """
+    client = get_client()
+
+    try:
+        with client:
+            with spinner("Fetching budget orders..."):
+                result = client.budget_orders.list(limit=limit)
+
+            if not result.data:
+                print_warning("No budget orders found")
+                return
+
+            rows: list[dict[str, Any]] = [
+                {
+                    "id": bo.id,
+                    "name": bo.name or "-",
+                    "status": enum_value(bo.status) if bo.status else "-",
+                    "budget": format_money(bo.budget.amount, bo.budget.currency) if bo.budget else "-",
+                    "order_number": bo.order_number or "-",
+                    "start_date": _date_str(bo.start_date),
+                    "end_date": _date_str(bo.end_date),
+                }
+                for bo in result.data
+            ]
+
+            output_data(rows, BUDGET_ORDER_COLUMNS, format, title="Budget orders")
+    except AppleSearchAdsError as e:
+        handle_api_error(e)
+        raise typer.Exit(EXIT_ERROR) from None
+
+
+@app.command("get")
+def get_budget_order(
+    budget_order_id: Annotated[
+        int,
+        typer.Argument(help="Budget order ID"),
+    ],
+) -> None:
+    """Show details for a single budget order.
+
+    Example:
+        asa budget-orders get 123456
+    """
+    client = get_client()
+
+    try:
+        with client:
+            with spinner("Fetching budget order..."):
+                bo = client.budget_orders.get(budget_order_id)
+
+            print_result_panel(
+                f"Budget order {bo.id}",
+                {
+                    "Name": bo.name or "-",
+                    "Status": enum_value(bo.status) if bo.status else "-",
+                    "Budget": format_money(bo.budget.amount, bo.budget.currency) if bo.budget else "-",
+                    "Order number": bo.order_number or "-",
+                    "Start date": _date_str(bo.start_date),
+                    "End date": _date_str(bo.end_date),
+                    "Client name": bo.client_name or "-",
+                    "Billing email": bo.billing_email or "-",
+                },
+            )
+    except AppleSearchAdsError as e:
+        handle_api_error(e)
+        raise typer.Exit(EXIT_ERROR) from None