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

{asa_api_cli-0.2.0 → asa_api_cli-0.4.0}/.github/dependabot.yml

@@ -1,6 +1,6 @@
 version: 2
 updates:
-  - package-ecosystem: "pip"
+  - package-ecosystem: "uv"
     directory: "/"
     schedule:
       interval: "weekly"

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

@@ -14,7 +14,7 @@ jobs:
         python-version: ["3.13"]
 
     steps:
-      - uses: actions/checkout@v6
+      - uses: actions/checkout@v7
 
       - name: Install uv
         uses: astral-sh/setup-uv@v7
@@ -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.4.0}/.github/workflows/publish.yml

@@ -12,7 +12,7 @@ jobs:
       id-token: write  # Required for trusted publishing
 
     steps:
-      - uses: actions/checkout@v6
+      - uses: actions/checkout@v7
 
       - name: Install uv
         uses: astral-sh/setup-uv@v7

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

@@ -1,6 +1,6 @@
-Metadata-Version: 2.4
+Metadata-Version: 2.5
 Name: asa-api-cli
-Version: 0.2.0
+Version: 0.4.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,11 +18,13 @@ 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.6.1
 Requires-Dist: pydantic-ai>=0.1.0
 Requires-Dist: pydantic-settings>=2.0.0
 Requires-Dist: rich>=13.9.0
 Requires-Dist: typer>=0.13.0
+Provides-Extra: analyze
+Requires-Dist: asa-api-client[cli]>=0.6.1; extra == 'analyze'
 Provides-Extra: dev
 Requires-Dist: mypy>=1.13.0; extra == 'dev'
 Requires-Dist: pre-commit>=4.0.0; extra == 'dev'
@@ -49,12 +51,18 @@ Using [uv](https://docs.astral.sh/uv/) (recommended):
 
 ```bash
 uv tool install asa-api-cli
+
+# Include Excel workbook analysis support (pandas + xlsxwriter)
+uv tool install "asa-api-cli[analyze]"
 ```
 
 Using pip:
 
 ```bash
 pip install asa-api-cli
+
+# Or with Excel workbook analysis support
+pip install "asa-api-cli[analyze]"
 ```
 
 Using pipx:
@@ -131,6 +139,16 @@ asa reports keywords 123456789 --start 2024-01-01 --end 2024-01-31
 asa reports campaigns --start 2024-01-01 --end 2024-01-31 --output report.csv
 ```
 
+### Analysis Workbook & Platform API v1 Smoke Test
+
+```bash
+# Generate an Excel performance analysis workbook (requires [analyze] extra)
+asa analyze --period 30d --output asa-30d.xlsx
+
+# Run a read-only smoke test against the Apple Ads Platform API v1
+asa v1-smoke
+```
+
 ### Brand Campaigns
 
 Create brand protection campaigns for your app:

{asa_api_cli-0.2.0 → asa_api_cli-0.4.0}/README.md

@@ -15,12 +15,18 @@ Using [uv](https://docs.astral.sh/uv/) (recommended):
 
 ```bash
 uv tool install asa-api-cli
+
+# Include Excel workbook analysis support (pandas + xlsxwriter)
+uv tool install "asa-api-cli[analyze]"
 ```
 
 Using pip:
 
 ```bash
 pip install asa-api-cli
+
+# Or with Excel workbook analysis support
+pip install "asa-api-cli[analyze]"
 ```
 
 Using pipx:
@@ -97,6 +103,16 @@ asa reports keywords 123456789 --start 2024-01-01 --end 2024-01-31
 asa reports campaigns --start 2024-01-01 --end 2024-01-31 --output report.csv
 ```
 
+### Analysis Workbook & Platform API v1 Smoke Test
+
+```bash
+# Generate an Excel performance analysis workbook (requires [analyze] extra)
+asa analyze --period 30d --output asa-30d.xlsx
+
+# Run a read-only smoke test against the Apple Ads Platform API v1
+asa v1-smoke
+```
+
 ### Brand Campaigns
 
 Create brand protection campaigns for your app:

{asa_api_cli-0.2.0 → asa_api_cli-0.4.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.2.0 → asa_api_cli-0.4.0}/asa_api_cli/ad_groups.py

@@ -661,7 +661,7 @@ def review_negatives(
             # Step 2: Fetch all ad groups
             with spinner("Fetching ad groups..."):
                 ad_groups_resp = client.campaigns(campaign_id).ad_groups.find(
-                    Selector(conditions=[{"field": "status", "operator": "EQUALS", "values": ["ENABLED"]}])
+                    Selector().where("status", "==", "ENABLED")
                 )
                 ad_groups = ad_groups_resp
 
@@ -887,9 +887,7 @@ def review_skag(
 
             # Step 2: Fetch all ad groups
             with spinner("Fetching ad groups..."):
-                ad_groups = client.campaigns(campaign_id).ad_groups.find(
-                    Selector(conditions=[{"field": "status", "operator": "EQUALS", "values": ["ENABLED"]}])
-                )
+                ad_groups = client.campaigns(campaign_id).ad_groups.find(Selector().where("status", "==", "ENABLED"))
 
             if not ad_groups:
                 print_warning("No enabled ad groups found in this campaign")

asa_api_cli-0.4.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.4.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