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

{asa_api_cli-0.3.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.3.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

{asa_api_cli-0.3.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.3.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.3.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.2.1
+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.3.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.3.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.3.0 → asa_api_cli-0.4.0}/asa_api_cli/auth.py

@@ -67,7 +67,16 @@ def test_auth(
         table.add_column("Setting", style="label")
         table.add_column("Status")
 
-        errors_by_field = {err["loc"][0]: err["msg"] for err in e.errors()}
+        errors_by_field: dict[str, str] = {}
+        model_errors: list[str] = []
+        for err in e.errors():
+            if err["loc"]:
+                errors_by_field[str(err["loc"][0])] = err["msg"]
+            else:
+                model_errors.append(err["msg"])
+                if "private_key" in err["msg"]:
+                    errors_by_field.setdefault("private_key", err["msg"])
+                    errors_by_field.setdefault("private_key_path", err["msg"])
 
         for field in ["client_id", "team_id", "key_id", "org_id", "private_key", "private_key_path"]:
             if field in errors_by_field:
@@ -77,7 +86,11 @@ def test_auth(
 
         error_console.print(table)
         error_console.print()
-        print_error("Configuration Error", "Missing or invalid settings")
+        print_error(
+            "Configuration Error",
+            "Missing or invalid settings",
+            details="\n".join(model_errors) if model_errors else None,
+        )
         raise typer.Exit(EXIT_USAGE) from None
 
     # Display loaded configuration
@@ -200,9 +213,12 @@ def show_config(
     except ValidationError as e:
         print_error("Configuration Error", "Could not load settings")
         for err in e.errors():
-            field = err["loc"][0]
             msg = err["msg"]
-            error_console.print(f"  [error]ASA_{str(field).upper()}:[/error] {msg}")
+            if err["loc"]:
+                field = err["loc"][0]
+                error_console.print(f"  [error]ASA_{str(field).upper()}:[/error] {msg}")
+            else:
+                error_console.print(f"  [error]Configuration:[/error] {msg}")
         raise typer.Exit(EXIT_USAGE) from None
 
 

{asa_api_cli-0.3.0 → asa_api_cli-0.4.0}/asa_api_cli/impression_share.py

@@ -224,9 +224,12 @@ def analyze_impression_share(
                 poll_interval=3.0,
                 timeout=120.0,
             )
-        except Exception as e:
+        except AppleSearchAdsError as e:
             handle_api_error(e)
             return
+        except (TimeoutError, RuntimeError) as e:
+            print_error("Report Error", str(e))
+            return
 
     if not report.row:
         print_warning("No impression share data available for the selected period")
@@ -359,9 +362,12 @@ def generate_share_report(
                 poll_interval=3.0,
                 timeout=120.0,
             )
-        except Exception as e:
+        except AppleSearchAdsError as e:
             handle_api_error(e)
             return
+        except (TimeoutError, RuntimeError) as e:
+            print_error("Report Error", str(e))
+            return
 
     if not report.row:
         print_warning("No data available")
@@ -444,9 +450,12 @@ def share_summary(
                 poll_interval=3.0,
                 timeout=120.0,
             )
-        except Exception as e:
+        except AppleSearchAdsError as e:
             handle_api_error(e)
             return
+        except (TimeoutError, RuntimeError) as e:
+            print_error("Report Error", str(e))
+            return
 
     if not report.row:
         print_warning("No data available")

{asa_api_cli-0.3.0 → asa_api_cli-0.4.0}/asa_api_cli/keywords.py

@@ -221,7 +221,7 @@ def add_keyword(
                 {
                     "ID": str(keyword.id),
                     "Text": keyword.text,
-                    "Match Type": keyword.match_type.value,
+                    "Match Type": enum_value(keyword.match_type),
                 },
             )
             print_hint(f"asa keywords list --campaign {campaign_id} --ad-group {ad_group_id}")
@@ -454,8 +454,8 @@ def list_negatives(
                 {
                     "id": n.id,
                     "text": n.text,
-                    "match_type": n.match_type.value,
-                    "status": n.status.value,
+                    "match_type": enum_value(n.match_type),
+                    "status": enum_value(n.status),
                 }
                 for n in negatives
             ]
@@ -519,7 +519,7 @@ def add_negative(
                 {
                     "Level": level.title(),
                     "Text": negative.text,
-                    "Match Type": negative.match_type.value,
+                    "Match Type": enum_value(negative.match_type),
                 },
             )
             hint_args = f"--campaign {campaign_id}"

{asa_api_cli-0.3.0 → asa_api_cli-0.4.0}/asa_api_cli/main.py

@@ -3,6 +3,7 @@
 from typing import Annotated
 
 import typer
+from asa_api_client.cli import v1_smoke
 
 from asa_api_cli import (
     ad_groups,
@@ -21,7 +22,7 @@ from asa_api_cli import (
     reports,
     translate,
 )
-from asa_api_cli.utils import cli_state, error_console, init_consoles
+from asa_api_cli.utils import EXIT_ERROR, cli_state, error_console, init_consoles, print_error
 
 app = typer.Typer(
     name="asa",
@@ -29,6 +30,38 @@ app = typer.Typer(
     rich_markup_mode="rich",
 )
 
+
+def _register_analyze_command(target_app: typer.Typer) -> None:
+    """Register ``asa analyze`` from asa-api-client, or a clean install-hint fallback."""
+    try:
+        from asa_api_client.cli.analyze import analyze as analyze_command
+    except ImportError:
+
+        @target_app.command(
+            "analyze",
+            help="Generate an Excel performance analysis workbook (requires [analyze] extra)",
+            context_settings={"allow_extra_args": True, "ignore_unknown_options": True},
+        )
+        def _analyze_missing_extra() -> None:
+            """Generate an Excel performance analysis workbook.
+
+            Requires optional dependencies (pandas and xlsxwriter).
+            """
+            print_error(
+                "Missing Optional Dependencies",
+                "The 'analyze' command requires pandas and xlsxwriter.",
+                details=('Install with: pip install "asa-api-cli[analyze]" or uv tool install "asa-api-cli[analyze]"'),
+            )
+            raise typer.Exit(EXIT_ERROR)
+
+        return
+
+    target_app.command(
+        "analyze",
+        help="Generate an Excel performance analysis workbook",
+    )(analyze_command)
+
+
 # Register sub-commands
 app.add_typer(auth.app, name="auth", help="Authentication commands")
 app.add_typer(brand.app, name="brand", help="Create brand protection campaigns")
@@ -45,6 +78,11 @@ app.add_typer(reports.app, name="reports", help="Generate reports")
 app.add_typer(optimize.app, name="optimize", help="Optimization tools")
 app.add_typer(impression_share.app, name="impression-share", help="Impression share analysis")
 app.add_typer(translate.app, name="translate", help="Translate keywords to multiple languages")
+_register_analyze_command(app)
+app.command(
+    "v1-smoke",
+    help="Run a read-only smoke test against the Apple Ads Platform API v1",
+)(v1_smoke.command)
 
 
 def version_callback(value: bool) -> None:

{asa_api_cli-0.3.0 → asa_api_cli-0.4.0}/asa_api_cli/optimize.py

@@ -1675,6 +1675,8 @@ def analyze_cpa_cap_impact(
                             currency = perf_30d.get("currency", "USD")
 
                             # Parse CPA goal
+                            if ag.cpa_goal is None:
+                                continue
                             cpa_goal_amount = ag.cpa_goal.amount
                             if hasattr(cpa_goal_amount, "amount"):
                                 # Money object
@@ -1885,24 +1887,24 @@ def analyze_cpa_cap_impact(
                 console.print()
 
                 changes_made = 0
-                for i, ag in enumerate(problem_groups, 1):
+                for i, analysis in enumerate(problem_groups, 1):
                     console.rule(f"[bold]{i}/{len(problem_groups)}")
                     console.print()
 
                     # Show ad group details
-                    impact_color = "red" if ag.impact_level in ("BLOCKED", "CRITICAL") else "yellow"
-                    console.print(f"[bold]Ad Group:[/bold] {ag.ad_group_name}")
-                    console.print(f"[bold]Campaign:[/bold] {ag.campaign_name} ({ag.country})")
+                    impact_color = "red" if analysis.impact_level in ("BLOCKED", "CRITICAL") else "yellow"
+                    console.print(f"[bold]Ad Group:[/bold] {analysis.ad_group_name}")
+                    console.print(f"[bold]Campaign:[/bold] {analysis.campaign_name} ({analysis.country})")
                     console.print()
-                    cpa_str = f"{ag.cpa_goal:.2f} {ag.currency}"
+                    cpa_str = f"{analysis.cpa_goal:.2f} {analysis.currency}"
                     console.print(f"  CPA Goal:        [{impact_color}]{cpa_str}[/{impact_color}]")
-                    if ag.avg_cpa:
-                        console.print(f"  Actual Avg CPA:  {ag.avg_cpa:.2f} {ag.currency}")
-                    console.print(f"  Impressions 7d:  {ag.impressions_7d:,}")
-                    console.print(f"  Impressions 30d: {ag.impressions_30d:,}")
-                    console.print(f"  Taps 30d:        {ag.taps_30d:,}")
-                    console.print(f"  Installs 30d:    {ag.installs_30d:,}")
-                    console.print(f"  Impact:          [{impact_color}]{ag.impact_level}[/{impact_color}]")
+                    if analysis.avg_cpa:
+                        console.print(f"  Actual Avg CPA:  {analysis.avg_cpa:.2f} {analysis.currency}")
+                    console.print(f"  Impressions 7d:  {analysis.impressions_7d:,}")
+                    console.print(f"  Impressions 30d: {analysis.impressions_30d:,}")
+                    console.print(f"  Taps 30d:        {analysis.taps_30d:,}")
+                    console.print(f"  Installs 30d:    {analysis.installs_30d:,}")
+                    console.print(f"  Impact:          [{impact_color}]{analysis.impact_level}[/{impact_color}]")
                     console.print()
 
                     action = (
@@ -1928,20 +1930,20 @@ def analyze_cpa_cap_impact(
                             with spinner("Removing CPA goal..."):
                                 # Update ad group with cpa_goal set to remove it
                                 # Note: The API may require a specific way to clear the CPA goal
-                                client.campaigns(ag.campaign_id).ad_groups.update(
-                                    ag.ad_group_id,
+                                client.campaigns(analysis.campaign_id).ad_groups.update(
+                                    analysis.ad_group_id,
                                     AdGroupUpdate(cpa_goal=None),
                                 )
-                            print_success(f"Removed CPA goal from '{ag.ad_group_name}'")
+                            print_success(f"Removed CPA goal from '{analysis.ad_group_name}'")
                             changes_made += 1
                         except AppleSearchAdsError as e:
                             print_error("Failed to remove CPA goal", str(e))
                         console.print()
                     elif action in ("i", "increase"):
                         # Prompt for new CPA goal
-                        suggested = ag.cpa_goal * Decimal("1.5")  # Suggest 50% increase
+                        suggested = analysis.cpa_goal * Decimal("1.5")  # Suggest 50% increase
                         new_goal_str = typer.prompt(
-                            f"New CPA goal ({ag.currency})",
+                            f"New CPA goal ({analysis.currency})",
                             default=f"{suggested:.2f}",
                         )
                         try:
@@ -1953,13 +1955,17 @@ def analyze_cpa_cap_impact(
                             with spinner("Updating CPA goal..."):
                                 from asa_api_client.models import CpaGoal as CpaGoalModel
 
-                                client.campaigns(ag.campaign_id).ad_groups.update(
-                                    ag.ad_group_id,
+                                client.campaigns(analysis.campaign_id).ad_groups.update(
+                                    analysis.ad_group_id,
                                     AdGroupUpdate(
-                                        cpa_goal=CpaGoalModel(amount=Money(amount=str(new_goal), currency=ag.currency))
+                                        cpa_goal=CpaGoalModel(
+                                            amount=Money(amount=str(new_goal), currency=analysis.currency)
+                                        )
                                     ),
                                 )
-                            print_success(f"Updated CPA goal: {ag.cpa_goal:.2f} → {new_goal:.2f} {ag.currency}")
+                            print_success(
+                                f"Updated CPA goal: {analysis.cpa_goal:.2f} → {new_goal:.2f} {analysis.currency}"
+                            )
                             changes_made += 1
                         except ValueError:
                             print_warning(f"Invalid input '{new_goal_str}', skipping")

{asa_api_cli-0.3.0 → asa_api_cli-0.4.0}/asa_api_cli/product_pages.py

@@ -24,6 +24,10 @@ LOCALE_COLUMNS = ["language_code", "language", "app_name", "device_classes"]
 
 @app.command("list")
 def list_product_pages(
+    adam_id: Annotated[
+        int,
+        typer.Option("--adam-id", "-a", help="App Store app ID (adamId)"),
+    ],
     limit: Annotated[
         int,
         typer.Option("--limit", "-l", help="Maximum number of results"),
@@ -33,18 +37,18 @@ def list_product_pages(
         typer.Option("--format", "-f", help="Output format"),
     ] = OutputFormat.TABLE,
 ) -> None:
-    """List custom product pages.
+    """List custom product pages for an app.
 
     Examples:
-        asa product-pages list
-        asa product-pages list --format json
+        asa product-pages list --adam-id 123456789
+        asa product-pages list -a 123456789 --format json
     """
     client = get_client()
 
     try:
         with client:
             with spinner("Fetching product pages..."):
-                result = client.product_pages.list(limit=limit)
+                result = client.product_pages(adam_id).list(limit=limit)
 
             if not result.data:
                 print_warning("No product pages found")
@@ -73,18 +77,22 @@ def get_product_page(
         str,
         typer.Argument(help="Product page ID"),
     ],
+    adam_id: Annotated[
+        int,
+        typer.Option("--adam-id", "-a", help="App Store app ID (adamId)"),
+    ],
 ) -> None:
     """Show details for a single custom product page.
 
     Example:
-        asa product-pages get <product-page-id>
+        asa product-pages get <product-page-id> --adam-id 123456789
     """
     client = get_client()
 
     try:
         with client:
             with spinner("Fetching product page..."):
-                pp = client.product_pages.get(product_page_id)
+                pp = client.product_pages(adam_id).get(product_page_id)
 
             print_result_panel(
                 f"Product page {pp.id}",
@@ -106,6 +114,10 @@ def product_page_locales(
         str,
         typer.Argument(help="Product page ID"),
     ],
+    adam_id: Annotated[
+        int,
+        typer.Option("--adam-id", "-a", help="App Store app ID (adamId)"),
+    ],
     format: Annotated[
         OutputFormat,
         typer.Option("--format", "-f", help="Output format"),
@@ -114,14 +126,14 @@ def product_page_locales(
     """List the per-locale details of a custom product page.
 
     Example:
-        asa product-pages locales <product-page-id>
+        asa product-pages locales <product-page-id> --adam-id 123456789
     """
     client = get_client()
 
     try:
         with client:
             with spinner("Fetching locale details..."):
-                details = client.product_pages.get_locale_details(product_page_id)
+                details = client.product_pages(adam_id).get_locale_details(product_page_id)
 
             if not details:
                 print_warning("No locale details found")

{asa_api_cli-0.3.0 → asa_api_cli-0.4.0}/asa_api_cli/utils.py

@@ -122,7 +122,7 @@ def handle_api_error(e: AppleSearchAdsError) -> None:
     Args:
         e: The exception to handle.
     """
-    from asa_api_client.exceptions import ValidationError
+    from asa_api_client.exceptions import PartialFailureError, ValidationError
 
     details_parts = []
 
@@ -139,10 +139,18 @@ def handle_api_error(e: AppleSearchAdsError) -> None:
             for err in errors:
                 details_parts.append(f"  {field}: {err}")
 
+    # Show per-item error entries for partial failures (2xx with error block)
+    if isinstance(e, PartialFailureError) and e.details:
+        for item in e.details:
+            field_name = item.get("field")
+            code = item.get("messageCode") or item.get("code")
+            msg = item.get("message") or code or json.dumps(item)
+            prefix = f"{field_name}: " if field_name else ""
+            suffix = f" ({code})" if code and code != msg else ""
+            details_parts.append(f"  {prefix}{msg}{suffix}")
+
     # Show response body if available (for debugging)
     if e.response_body:
-        import json
-
         # Remove internal _request field before displaying
         body_copy = {k: v for k, v in e.response_body.items() if not k.startswith("_")}
         body_str = json.dumps(body_copy, indent=2)

{asa_api_cli-0.3.0 → asa_api_cli-0.4.0}/pyproject.toml

@@ -4,7 +4,7 @@ build-backend = "hatchling.build"
 
 [project]
 name = "asa-api-cli"
-version = "0.3.0"
+version = "0.4.0"
 description = "Command-line interface for Apple Search Ads campaign management"
 readme = "README.md"
 license = "MIT"
@@ -28,7 +28,7 @@ classifiers = [
     "Typing :: Typed",
 ]
 dependencies = [
-    "asa-api-client>=0.2.1",
+    "asa-api-client>=0.6.1",
     "typer>=0.13.0",
     "rich>=13.9.0",
     "pydantic-ai>=0.1.0",
@@ -39,6 +39,9 @@ dependencies = [
 asa = "asa_api_cli:app"
 
 [project.optional-dependencies]
+analyze = [
+    "asa-api-client[cli]>=0.6.1",
+]
 dev = [
     "pytest>=8.3.0",
     "pytest-asyncio>=0.24.0",
@@ -64,6 +67,7 @@ python_version = "3.13"
 strict = true
 ignore_missing_imports = true
 warn_unused_ignores = false
+plugins = ["pydantic.mypy"]
 
 [tool.ruff]
 target-version = "py313"