adloop 0.4.1__tar.gz → 0.4.3__tar.gz

{adloop-0.4.1 → adloop-0.4.3}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.3
 Name: adloop
-Version: 0.4.1
+Version: 0.4.3
 Summary: Stop switching between Google Ads, GA4, and your code editor to figure out why conversions dropped.
 Keywords: mcp,google-ads,google-analytics,ga4,cursor,marketing
 Author: Daniel Klose
@@ -224,6 +224,25 @@ The wizard:
 
 - Python 3.11+
 - A Google Ads account with an MCC (Manager Account)
+- A Google Ads Developer Token (see below)
+
+### Google Ads Developer Token
+
+A developer token is **always required** — even when using AdLoop's built-in OAuth credentials. The built-in credentials handle Google sign-in; the developer token is a separate key that grants API access to your Google Ads data.
+
+1. **Create an MCC** (free) at [ads.google.com/home/tools/manager-accounts](https://ads.google.com/home/tools/manager-accounts/) if you don't have one. Link your regular Google Ads account to it.
+2. In the MCC, go to **Tools & Settings → API Center**
+3. Your **developer token** is shown there. Copy it — the wizard will ask for it.
+
+**Access levels** — your token's access level determines what it can do:
+
+| Level | How to Get | What It Allows |
+|-------|-----------|----------------|
+| **Test Account** | Default for new tokens | Can only access test accounts — **not production accounts**. If you see `DEVELOPER_TOKEN_NOT_APPROVED`, this is why. |
+| **Explorer** | Automatic after first API call with a production account | 2,880 operations/day on production accounts. Enough to get started. |
+| **Basic** | [Apply through API Center](https://ads.google.com/aw/apicenter) | 15,000 operations/day. Apply if you need more. |
+
+> **Getting `DEVELOPER_TOKEN_NOT_APPROVED`?** Your token is at "Test Account" level. Go to [API Center](https://ads.google.com/aw/apicenter) in your MCC and check your access level. If it shows "Test Account", you need to apply for Basic access or wait for Explorer access to be granted after your first production API call.
 
 ### Headless Servers
 
@@ -253,17 +272,7 @@ When you run `adloop init`, choose "No" when asked about built-in credentials. T
 
 > Service accounts are also supported — just place the service account key JSON at the same `credentials_path`. AdLoop detects the file type automatically.
 
-#### Step 3 — Google Ads Developer Token
-
-1. **Create an MCC** (free) at [ads.google.com/home/tools/manager-accounts](https://ads.google.com/home/tools/manager-accounts/) if you don't have one. Link your regular Google Ads account to it.
-2. In the MCC, go to **Tools & Settings → API Center**
-3. Your **developer token** is shown there. Copy it.
-
-Access levels:
-- **Explorer** (automatic) — 2,880 operations/day on production accounts. Enough to get started.
-- **Basic** (requires application) — 15,000 operations/day. Apply through the same API Center page if you need more.
-
-#### Step 4 — Connect to Your Editor
+#### Step 3 — Connect to Your Editor
 
 **Cursor** — Add to your project's `.cursor/mcp.json`:
 

{adloop-0.4.1 → adloop-0.4.3}/README.md

@@ -200,6 +200,25 @@ The wizard:
 
 - Python 3.11+
 - A Google Ads account with an MCC (Manager Account)
+- A Google Ads Developer Token (see below)
+
+### Google Ads Developer Token
+
+A developer token is **always required** — even when using AdLoop's built-in OAuth credentials. The built-in credentials handle Google sign-in; the developer token is a separate key that grants API access to your Google Ads data.
+
+1. **Create an MCC** (free) at [ads.google.com/home/tools/manager-accounts](https://ads.google.com/home/tools/manager-accounts/) if you don't have one. Link your regular Google Ads account to it.
+2. In the MCC, go to **Tools & Settings → API Center**
+3. Your **developer token** is shown there. Copy it — the wizard will ask for it.
+
+**Access levels** — your token's access level determines what it can do:
+
+| Level | How to Get | What It Allows |
+|-------|-----------|----------------|
+| **Test Account** | Default for new tokens | Can only access test accounts — **not production accounts**. If you see `DEVELOPER_TOKEN_NOT_APPROVED`, this is why. |
+| **Explorer** | Automatic after first API call with a production account | 2,880 operations/day on production accounts. Enough to get started. |
+| **Basic** | [Apply through API Center](https://ads.google.com/aw/apicenter) | 15,000 operations/day. Apply if you need more. |
+
+> **Getting `DEVELOPER_TOKEN_NOT_APPROVED`?** Your token is at "Test Account" level. Go to [API Center](https://ads.google.com/aw/apicenter) in your MCC and check your access level. If it shows "Test Account", you need to apply for Basic access or wait for Explorer access to be granted after your first production API call.
 
 ### Headless Servers
 
@@ -229,17 +248,7 @@ When you run `adloop init`, choose "No" when asked about built-in credentials. T
 
 > Service accounts are also supported — just place the service account key JSON at the same `credentials_path`. AdLoop detects the file type automatically.
 
-#### Step 3 — Google Ads Developer Token
-
-1. **Create an MCC** (free) at [ads.google.com/home/tools/manager-accounts](https://ads.google.com/home/tools/manager-accounts/) if you don't have one. Link your regular Google Ads account to it.
-2. In the MCC, go to **Tools & Settings → API Center**
-3. Your **developer token** is shown there. Copy it.
-
-Access levels:
-- **Explorer** (automatic) — 2,880 operations/day on production accounts. Enough to get started.
-- **Basic** (requires application) — 15,000 operations/day. Apply through the same API Center page if you need more.
-
-#### Step 4 — Connect to Your Editor
+#### Step 3 — Connect to Your Editor
 
 **Cursor** — Add to your project's `.cursor/mcp.json`:
 

{adloop-0.4.1 → adloop-0.4.3}/pyproject.toml

@@ -1,6 +1,6 @@
 [project]
 name = "adloop"
-version = "0.4.1"
+version = "0.4.3"
 description = "Stop switching between Google Ads, GA4, and your code editor to figure out why conversions dropped."
 readme = "README.md"
 authors = [

{adloop-0.4.1 → adloop-0.4.3}/src/adloop/__init__.py

@@ -2,7 +2,7 @@
 
 import sys
 
-__version__ = "0.4.1"
+__version__ = "0.4.3"
 
 
 def main() -> None:
@@ -11,10 +11,18 @@ def main() -> None:
     Routes to the setup wizard when called as ``adloop init``,
     otherwise starts the MCP server.
     """
+    if len(sys.argv) > 1 and sys.argv[1] in ("--version", "-V"):
+        print(f"adloop {__version__}")
+        return
+
     if len(sys.argv) > 1 and sys.argv[1] == "init":
         from adloop.cli import run_init_wizard
 
-        run_init_wizard()
+        try:
+            run_init_wizard()
+        except KeyboardInterrupt:
+            print("\n\n  Setup cancelled.\n")
+            sys.exit(130)
     else:
         from adloop.server import mcp
 

{adloop-0.4.1 → adloop-0.4.3}/src/adloop/ads/read.py

@@ -214,6 +214,11 @@ def get_negative_keywords(
     """
 
     rows = execute_query(config, customer_id, query)
+    for row in rows:
+        cid = row.get("campaign.id")
+        crit_id = row.get("campaign_criterion.criterion_id")
+        if cid and crit_id:
+            row["resource_id"] = f"{cid}~{crit_id}"
     return {"negative_keywords": rows, "total_negative_keywords": len(rows)}
 
 

{adloop-0.4.1 → adloop-0.4.3}/src/adloop/ads/write.py

@@ -1626,6 +1626,35 @@ def _draft_status_change(
 # ---------------------------------------------------------------------------
 
 
+_MUTATE_RESPONSE_RESULT_FIELDS = [
+    "campaign_budget_result",
+    "campaign_result",
+    "ad_group_result",
+    "ad_group_ad_result",
+    "ad_group_criterion_result",
+    "campaign_criterion_result",
+    "asset_result",
+    "campaign_asset_result",
+    "customer_asset_result",
+]
+
+
+def _extract_resource_name(resp: object) -> str:
+    """Extract the resource_name from a MutateOperationResponse.
+
+    Uses direct field access instead of WhichOneof, which doesn't work on
+    proto-plus wrapped messages returned by the google-ads library.
+    """
+    for field in _MUTATE_RESPONSE_RESULT_FIELDS:
+        try:
+            result = getattr(resp, field, None)
+            if result and result.resource_name:
+                return result.resource_name
+        except Exception:
+            continue
+    return ""
+
+
 def _execute_plan(config: AdLoopConfig, plan: object) -> dict:
     """Dispatch to the right Google Ads mutate call based on plan.operation."""
     from adloop.ads.client import get_ads_client, normalize_customer_id
@@ -1818,22 +1847,20 @@ def _apply_create_campaign(client: object, cid: str, changes: dict) -> dict:
     num_geo = len(changes.get("geo_target_ids") or [])
     num_lang = len(changes.get("language_ids") or [])
     for i, resp in enumerate(response.mutate_operation_responses):
-        resp_type = resp.WhichOneof("response")
-        if resp_type:
-            inner = getattr(resp, resp_type)
-            resource = getattr(inner, "resource_name", str(inner))
+        rn = _extract_resource_name(resp)
+        if rn:
             if i == 0:
-                results["campaign_budget"] = resource
+                results["campaign_budget"] = rn
             elif i == 1:
-                results["campaign"] = resource
+                results["campaign"] = rn
             elif i == 2:
-                results["ad_group"] = resource
+                results["ad_group"] = rn
             elif i < 3 + num_keywords:
-                results.setdefault("keywords", []).append(resource)
+                results.setdefault("keywords", []).append(rn)
             elif i < 3 + num_keywords + num_geo:
-                results.setdefault("geo_targets", []).append(resource)
+                results.setdefault("geo_targets", []).append(rn)
             else:
-                results.setdefault("language_targets", []).append(resource)
+                results.setdefault("language_targets", []).append(rn)
 
     return results
 
@@ -1874,14 +1901,12 @@ def _apply_create_ad_group(client: object, cid: str, changes: dict) -> dict:
 
     results: dict = {}
     for i, resp in enumerate(response.mutate_operation_responses):
-        resp_type = resp.WhichOneof("response")
-        if resp_type:
-            inner = getattr(resp, resp_type)
-            resource = getattr(inner, "resource_name", str(inner))
+        rn = _extract_resource_name(resp)
+        if rn:
             if i == 0:
-                results["ad_group"] = resource
+                results["ad_group"] = rn
             else:
-                results.setdefault("keywords", []).append(resource)
+                results.setdefault("keywords", []).append(rn)
 
     return results
 
@@ -2039,11 +2064,7 @@ def _apply_update_campaign(client: object, cid: str, changes: dict) -> dict:
 
     results = {"updated": []}
     for resp in response.mutate_operation_responses:
-        rn = (
-            resp.campaign_result.resource_name
-            or resp.campaign_budget_result.resource_name
-            or resp.campaign_criterion_result.resource_name
-        )
+        rn = _extract_resource_name(resp)
         if rn:
             results["updated"].append(rn)
     return results

{adloop-0.4.1 → adloop-0.4.3}/src/adloop/cli.py

@@ -150,39 +150,42 @@ def _generate_config_yaml(
 ) -> str:
     dry_run_str = "true" if require_dry_run else "false"
 
-    google_section = "google:\n"
+    lines = [
+        "# AdLoop configuration",
+        "# Generated by: adloop init",
+        "# Docs: https://github.com/kLOsk/adloop",
+        "",
+        "google:",
+    ]
     if project_id:
-        google_section += f'  project_id: "{project_id}"\n'
+        lines.append(f'  project_id: "{project_id}"')
     if credentials_path:
-        google_section += f'  credentials_path: "{credentials_path}"\n'
+        lines.append(f'  credentials_path: "{credentials_path}"')
     else:
-        google_section += "  # Using built-in credentials (no credentials_path needed)\n"
-    google_section += '  token_path: "~/.adloop/token.json"\n'
-
-    return textwrap.dedent(f"""\
-        # AdLoop configuration
-        # Generated by: adloop init
-        # Docs: https://github.com/kLOsk/adloop
-
-        {google_section}
-        ga4:
-          property_id: "{property_id}"
-
-        ads:
-          developer_token: "{developer_token}"
-          customer_id: "{customer_id}"
-          # MCC / Manager Account ID (required if using a manager account)
-          login_customer_id: "{login_customer_id}"
-
-        safety:
-          # Maximum daily budget AdLoop can set (safety cap)
-          max_daily_budget: {max_daily_budget}
-          max_bid_increase_pct: 100
-          # When true, confirm_and_apply always runs as dry_run regardless of the parameter
-          require_dry_run: {dry_run_str}
-          log_file: "~/.adloop/audit.log"
-          blocked_operations: []
-    """)
+        lines.append("  # Using built-in credentials (no credentials_path needed)")
+    lines.append('  token_path: "~/.adloop/token.json"')
+    lines += [
+        "",
+        "ga4:",
+        f'  property_id: "{property_id}"',
+        "",
+        "ads:",
+        f'  developer_token: "{developer_token}"',
+        f'  customer_id: "{customer_id}"',
+        "  # MCC / Manager Account ID (required if using a manager account)",
+        f'  login_customer_id: "{login_customer_id}"',
+        "",
+        "safety:",
+        "  # Maximum daily budget AdLoop can set (safety cap)",
+        f"  max_daily_budget: {max_daily_budget}",
+        "  max_bid_increase_pct: 100",
+        "  # When true, confirm_and_apply always runs as dry_run regardless of the parameter",
+        f"  require_dry_run: {dry_run_str}",
+        '  log_file: "~/.adloop/audit.log"',
+        "  blocked_operations: []",
+        "",
+    ]
+    return "\n".join(lines)
 
 
 def _generate_cursor_snippet() -> str:
@@ -291,16 +294,17 @@ def run_init_wizard() -> None:
     _print()
 
     existing_config = None
+    _original_config_backup: str | None = None
     if _CONFIG_PATH.exists():
         _print(f"  Found existing config at {_CONFIG_PATH}")
         if not _prompt_bool("Overwrite existing configuration?", default=False):
             _print("  Keeping existing config. Exiting.")
             return
+        _original_config_backup = _CONFIG_PATH.read_text()
         try:
             import yaml
 
-            with open(_CONFIG_PATH) as f:
-                existing_config = yaml.safe_load(f) or {}
+            existing_config = yaml.safe_load(_original_config_backup) or {}
         except Exception:
             existing_config = {}
 
@@ -361,7 +365,8 @@ def run_init_wizard() -> None:
     step_num += 1
     _step_header(step_num, "Authorization & Account Discovery")
 
-    # Write a minimal temporary config for OAuth + discovery
+    # Write a temporary config for OAuth + discovery.  If the wizard is
+    # interrupted after this point, _cleanup_on_cancel restores the original.
     _ADLOOP_DIR.mkdir(parents=True, exist_ok=True)
     temp_config_yaml = _generate_config_yaml(
         project_id=project_id,
@@ -375,6 +380,40 @@ def run_init_wizard() -> None:
     )
     _CONFIG_PATH.write_text(temp_config_yaml)
 
+    # Everything below uses the temp config for OAuth and discovery.
+    # If the wizard is interrupted, restore the original config (or remove
+    # the temp) so we never leave a half-baked config on disk.
+    try:
+        _run_wizard_post_config(
+            use_bundled=use_bundled,
+            credentials_path=credentials_path,
+            project_id=project_id,
+            developer_token=developer_token,
+            login_customer_id=login_customer_id,
+            step_num=step_num,
+            _existing=_existing,
+        )
+    except KeyboardInterrupt:
+        if _original_config_backup is not None:
+            _CONFIG_PATH.write_text(_original_config_backup)
+        elif _CONFIG_PATH.exists():
+            _CONFIG_PATH.unlink()
+        raise
+
+
+def _run_wizard_post_config(
+    *,
+    use_bundled: bool,
+    credentials_path: str,
+    project_id: str,
+    developer_token: str,
+    login_customer_id: str,
+    step_num: int,
+    _existing: object,
+) -> None:
+    """Run the wizard steps after the temp config has been written."""
+    from adloop.config import load_config
+
     # Optional: copy custom credentials to ~/.adloop/
     if not use_bundled and credentials_path:
         creds_expanded = Path(credentials_path).expanduser()
@@ -392,13 +431,14 @@ def run_init_wizard() -> None:
     _print()
     oauth_ok = False
     try:
-        from adloop.config import load_config
         from adloop.auth import _oauth_flow
 
         cfg = load_config(str(_CONFIG_PATH))
         _oauth_flow(cfg)
         _print("  ✓ OAuth token saved")
         oauth_ok = True
+    except KeyboardInterrupt:
+        raise
     except Exception as exc:
         _print(f"  ✗ OAuth failed: {exc}")
         _print("    You can retry later — any AdLoop tool call will trigger auth.")
@@ -424,10 +464,12 @@ def run_init_wizard() -> None:
             else:
                 _print("  No GA4 properties found. Enter manually:")
                 property_id = _prompt_property_id()
+        except KeyboardInterrupt:
+            raise
         except Exception as exc:
             _print(f"  Could not auto-discover GA4 properties: {exc}")
             property_id = _prompt_property_id(
-                default=_existing("ga4", "property_id"),
+                default=_existing("ga4", "property_id"),  # type: ignore[operator]
             )
     else:
         step_num += 1
@@ -436,7 +478,7 @@ def run_init_wizard() -> None:
         _print("  → https://analytics.google.com → Admin → Property Settings")
         _print()
         property_id = _prompt_property_id(
-            default=_existing("ga4", "property_id"),
+            default=_existing("ga4", "property_id"),  # type: ignore[operator]
         )
 
     # Auto-discover Ads accounts
@@ -460,18 +502,20 @@ def run_init_wizard() -> None:
             else:
                 _print("  No Ads accounts found. Enter manually:")
                 customer_id = _prompt_customer_id("Ads Customer ID (XXX-XXX-XXXX)")
+        except KeyboardInterrupt:
+            raise
         except Exception as exc:
             _print(f"  Could not auto-discover Ads accounts: {exc}")
             customer_id = _prompt_customer_id(
                 "Ads Customer ID (XXX-XXX-XXXX)",
-                default=_existing("ads", "customer_id"),
+                default=_existing("ads", "customer_id"),  # type: ignore[operator]
             )
     else:
         step_num += 1
         _step_header(step_num, "Google Ads Account")
         customer_id = _prompt_customer_id(
             "Ads Customer ID (XXX-XXX-XXXX)",
-            default=_existing("ads", "customer_id"),
+            default=_existing("ads", "customer_id"),  # type: ignore[operator]
         )
 
     # Safety defaults
@@ -479,7 +523,7 @@ def run_init_wizard() -> None:
     _step_header(step_num, "Safety Defaults")
     budget_str = _prompt(
         "Max daily budget cap (safety limit)",
-        default=str(_existing("safety", "max_daily_budget", "50")),
+        default=str(_existing("safety", "max_daily_budget", "50")),  # type: ignore[operator]
         required=False,
     )
     try:

{adloop-0.4.1 → adloop-0.4.3}/src/adloop/server.py

@@ -1039,7 +1039,8 @@ def remove_entity(
                  "campaign_asset", "asset", or "customer_asset"
     entity_id: The resource ID.
                For keywords: "adGroupId~criterionId"
-               For negative_keywords: the campaign criterion ID
+               For negative_keywords: "campaignId~criterionId"
+                   (use the resource_id field from get_negative_keywords)
                For campaign_asset: "campaignId~assetId~fieldType"
                For asset: simple asset ID
                For customer_asset: "assetId~fieldType"