adloop 0.12.0__tar.gz → 0.13.0__tar.gz

{adloop-0.12.0 → adloop-0.13.0}/PKG-INFO

@@ -1,13 +1,13 @@
 Metadata-Version: 2.3
 Name: adloop
-Version: 0.12.0
+Version: 0.13.0
 Summary: The AI command center for Google Ads, GA4, and tracking code.
 Keywords: mcp,google-ads,google-analytics,ga4,cursor,marketing
 Author: Daniel Klose
 Author-email: Daniel Klose <info@daniel-klose.com>
 License: MIT
 Requires-Dist: fastmcp>=3.0.0
-Requires-Dist: google-ads>=29.0.0
+Requires-Dist: google-ads>=31.1.0
 Requires-Dist: google-analytics-data>=0.20.0
 Requires-Dist: google-analytics-admin>=0.27.0
 Requires-Dist: google-api-python-client>=2.100.0
@@ -34,7 +34,7 @@ Description-Content-Type: text/markdown
 [![License: MIT](https://img.shields.io/badge/License-MIT-blue.svg)](LICENSE)
 [![Python 3.11+](https://img.shields.io/badge/Python-3.11+-3776AB.svg?logo=python&logoColor=white)](https://www.python.org/downloads/)
 [![MCP Compatible](https://img.shields.io/badge/MCP-Compatible-8A2BE2.svg)](https://modelcontextprotocol.io)
-[![Google Ads API](https://img.shields.io/badge/Google%20Ads-API%20v23-4285F4.svg?logo=google-ads&logoColor=white)](https://developers.google.com/google-ads/api/docs/start)
+[![Google Ads API](https://img.shields.io/badge/Google%20Ads-API%20v24-4285F4.svg?logo=google-ads&logoColor=white)](https://developers.google.com/google-ads/api/docs/start)
 [![GA4 Data API](https://img.shields.io/badge/GA4-Data%20API-E37400.svg?logo=google-analytics&logoColor=white)](https://developers.google.com/analytics/devguides/reporting/data/v1)
 [![GitHub stars](https://img.shields.io/github/stars/kLOsk/adloop?style=social)](https://github.com/kLOsk/adloop)
 
@@ -45,13 +45,13 @@ An MCP server that gives your AI assistant read + write access to Google Ads and
 </div>
 
 > [!TIP]
-> **[AdLoop Cloud](https://getadloop.com) is the hosted version of this project — live now, free during beta (limited seats).** Connect Google in two clicks and use the same 64 tools from claude.ai, ChatGPT, Claude Code, Cursor, or Gemini. No Google Cloud project, no developer token, no OAuth verification wait. EU-hosted, GDPR-first, DPA included.
+> **[AdLoop Cloud](https://getadloop.com) is the hosted version of this project — live now, free during beta (limited seats).** Connect Google in two clicks and use the full toolset from claude.ai, ChatGPT, Claude Code, Cursor, or Gemini. No Google Cloud project, no developer token, no OAuth verification wait. EU-hosted, GDPR-first, DPA included.
 
 ---
 
 ## Cloud or Self-Hosted?
 
-Both versions run the same 64 tools with the same safety model. The difference is who handles the plumbing:
+Both versions run the same tools with the same safety model. The difference is who handles the plumbing:
 
 |  | ☁️ [AdLoop Cloud](https://getadloop.com) | 🛠️ Self-hosted (this repo) |
 |---|---|---|
@@ -89,7 +89,7 @@ Every tool exists because of an actual problem hit while running real Google Ads
 
 The best features come from real workflows. If you're using AdLoop and find yourself wishing it could do something it can't, **open an issue describing your situation** — not just "add feature X" but "I was trying to do Y and couldn't because Z." The context matters more than the request.
 
-## All 64 Tools
+## All Tools
 
 > **Quick start:** `pip install adloop` or `git clone https://github.com/kLOsk/adloop.git && cd adloop && uv sync && uv run adloop init` — or zero setup on [AdLoop Cloud](https://getadloop.com)
 
@@ -182,6 +182,15 @@ These tools read the live GTM container and join it with the codebase + GA4 to f
 |------|-------------|
 | `analyze_page_speed` | PageSpeed Insights for landing pages — Lighthouse score, Core Web Vitals, real-user CrUX data, top fixes. No OAuth needed (optional API key). |
 
+### Merchant Center Tools
+
+| Tool | What It Does |
+|------|-------------|
+| `list_merchant_accounts` | Discover accessible Merchant Center accounts |
+| `get_merchant_feed_health` | Feed health — approved/pending/disapproved counts per reporting context, top product issues with docs, account-level issues. Disapprovals silently starve Shopping/PMax. |
+
+> **Setup for Merchant Center tools** — Enable the **Merchant API** in your GCP project (the Content API for Shopping is deprecated). The Merchant API has no read-only scope; AdLoop uses it strictly read-only. Upgrading OAuth users re-authorize once.
+
 > **Setup for GSC tools** — Enable the **Search Console API** in your GCP project. Upgrading OAuth users must re-authorize once for the new scope (delete `~/.adloop/token.json`, run any tool). The killer combo: cross-reference organic queries with `get_keyword_performance` to find paid/organic cannibalization and untapped keyword opportunities.
 
 ### Planning Tools
@@ -189,7 +198,7 @@ These tools read the live GTM container and join it with the codebase + GA4 to f
 | Tool | What It Does |
 |------|-------------|
 | `discover_keywords` | Discover new keyword ideas from seed keywords and/or a URL — with optional per-month search history + seasonality insights (`include_monthly_volumes`) using Google Ads Keyword Planner. Returns avg monthly searches, competition level, and top-of-page bid range. |
-| `estimate_budget` | Forecast clicks, impressions, and cost for a set of keywords using Google Ads Keyword Planner. Supports geo/language targeting. Essential for budget planning before launching campaigns. |
+| `estimate_budget` | Forecast clicks, cost, and conversions for a set of keywords using Google Ads Keyword Planner. Supports geo/language targeting. Essential for budget planning before launching campaigns. |
 
 ### Google Ads Write Tools
 
@@ -208,6 +217,7 @@ All write operations follow a **draft → preview → confirm** workflow. Nothin
 | `draft_keywords` | Propose keyword additions with match types. Proactively checks bidding strategy — blocks BROAD match on Manual CPC campaigns. |
 | `add_negative_keywords` | Propose negative keywords directly on a campaign |
 | `add_negative_locations` | Propose negative geo exclusions on a campaign — exclude cities/regions while keeping broader positive targets |
+| `draft_key_event` | Mark a GA4 event as a key event (conversion) — the fix for "fires but isn't tracked as a conversion" |
 | `draft_demographic_targeting` | Propose demographic criteria (age, gender, parental status, income) — exclusions by default |
 | `propose_negative_keyword_list` | Draft a shared negative keyword list (SharedSet) and attach it to a campaign — reusable across multiple campaigns |
 | `pause_entity` | Pause a campaign, ad group, ad, or keyword |
@@ -248,6 +258,7 @@ AdLoop manages real ad spend, so safety is not optional.
 
 - **Two-step writes.** Every mutation returns a preview first. A separate `confirm_and_apply` call is required to execute.
 - **Dry-run by default.** Even `confirm_and_apply` defaults to `dry_run=true`. Real changes require explicit `dry_run=false`.
+- **Two-phase apply (optional).** With `safety.two_phase_apply: true`, `confirm_and_apply` refuses `dry_run=false` until the plan has completed one dry-run pass — preview-then-apply becomes server-enforced instead of a convention.
 - **Budget caps.** Configurable maximum daily budget — the server rejects anything above the cap.
 - **Audit log.** Every operation (including dry runs) is logged to `~/.adloop/audit.log`.
 - **New campaigns and ads are PAUSED.** Nothing goes live without manual enablement.
@@ -296,8 +307,10 @@ The wizard walks you through:
 3. **MCC Account ID** — your Manager Account ID (top bar in the MCC UI)
 4. **OAuth sign-in** — opens a browser to sign in with Google (or prints a URL for headless servers)
 5. **Auto-discovers your accounts** — finds your GA4 properties and Ads accounts automatically
-6. **Safety defaults** — budget cap and dry-run preference
-7. **Editor config snippets** — prints MCP configuration for both Cursor and Claude Code
+6. **Optional services** — pin a GTM container, a Search Console property (both auto-discovered too), and a PageSpeed API key; skip any of them with Enter
+7. **Safety defaults** — budget cap and dry-run preference
+8. **Toolsets** — optionally expose only part of the tool catalog to your AI client (see [Toolsets](#toolsets--trim-the-context-footprint))
+9. **Editor config snippets** — prints MCP configuration for both Cursor and Claude Code, including your toolset selection
 
 ### Requirements
 
@@ -431,14 +444,37 @@ All configuration lives in `~/.adloop/config.yaml`. See [`config.yaml.example`](
 | `ads` | `login_customer_id` | — | Your MCC account ID |
 | `safety` | `max_daily_budget` | `50.00` | Maximum allowed daily budget per campaign |
 | `safety` | `require_dry_run` | `true` | Force all writes to dry-run mode |
+| `safety` | `two_phase_apply` | `false` | Refuse real applies until the plan had a dry-run pass |
 | `safety` | `blocked_operations` | `[]` | Operations to block entirely |
 
+### Toolsets — trim the context footprint
+
+Most MCP clients (claude.ai, ChatGPT, Cursor, …) load **every tool schema into the model's context at the start of every conversation**. AdLoop's full catalog costs roughly 18k tokens per session that way — paid before you type a word. If you only use part of AdLoop, expose a subset with the `ADLOOP_TOOLSETS` environment variable in your MCP client's `env` block (the `adloop init` wizard offers this and writes it into the snippets for you):
+
+```json
+"env": { "ADLOOP_TOOLSETS": "ads,ga4" }
+```
+
+| Toolset | Covers |
+|---|---|
+| `ads` | Google Ads reads, writes, and planning (Keyword Planner) |
+| `ga4` | Google Analytics reports, realtime, key events |
+| `tracking` | Cross-channel attribution + tracking code generation |
+| `gtm` | Google Tag Manager audits and reads |
+| `gsc` | Search Console reads |
+| `web` | PageSpeed / Core Web Vitals |
+| `merchant` | Merchant Center feed health |
+
+`health_check` and `confirm_and_apply` are always included, whatever you select. Unset = the full catalog; unknown names fail at startup with the valid list. The effect is real: `ads,ga4` drops the session cost to ~13k tokens, and a `ga4`-only client pays ~2k — nearly 90% less. Toolsets are per *client*, not per install: one AdLoop config can serve a trimmed Cursor and a full-catalog Claude Code side by side.
+
+On [AdLoop Cloud](https://getadloop.com), the same feature is per API key: pick toolsets when creating a key in the dashboard, and that key's tools/list is trimmed server-side for whichever AI client uses it.
+
 ## Project Structure
 
 ```
 src/adloop/
 ├── __init__.py        # Entry point — routes 'adloop init' to wizard, otherwise starts MCP server
-├── server.py          # FastMCP server — 64 tool registrations with safety annotations
+├── server.py          # FastMCP server — 67 tool registrations with safety annotations
 ├── config.py          # Config loader (~/.adloop/config.yaml)
 ├── auth.py            # OAuth 2.0 flow (user-supplied credentials, headless fallback) + service accounts; GA4 / Ads / GTM scopes
 ├── cli.py             # Interactive 'adloop init' setup wizard

{adloop-0.12.0 → adloop-0.13.0}/README.md

@@ -8,7 +8,7 @@
 [![License: MIT](https://img.shields.io/badge/License-MIT-blue.svg)](LICENSE)
 [![Python 3.11+](https://img.shields.io/badge/Python-3.11+-3776AB.svg?logo=python&logoColor=white)](https://www.python.org/downloads/)
 [![MCP Compatible](https://img.shields.io/badge/MCP-Compatible-8A2BE2.svg)](https://modelcontextprotocol.io)
-[![Google Ads API](https://img.shields.io/badge/Google%20Ads-API%20v23-4285F4.svg?logo=google-ads&logoColor=white)](https://developers.google.com/google-ads/api/docs/start)
+[![Google Ads API](https://img.shields.io/badge/Google%20Ads-API%20v24-4285F4.svg?logo=google-ads&logoColor=white)](https://developers.google.com/google-ads/api/docs/start)
 [![GA4 Data API](https://img.shields.io/badge/GA4-Data%20API-E37400.svg?logo=google-analytics&logoColor=white)](https://developers.google.com/analytics/devguides/reporting/data/v1)
 [![GitHub stars](https://img.shields.io/github/stars/kLOsk/adloop?style=social)](https://github.com/kLOsk/adloop)
 
@@ -19,13 +19,13 @@ An MCP server that gives your AI assistant read + write access to Google Ads and
 </div>
 
 > [!TIP]
-> **[AdLoop Cloud](https://getadloop.com) is the hosted version of this project — live now, free during beta (limited seats).** Connect Google in two clicks and use the same 64 tools from claude.ai, ChatGPT, Claude Code, Cursor, or Gemini. No Google Cloud project, no developer token, no OAuth verification wait. EU-hosted, GDPR-first, DPA included.
+> **[AdLoop Cloud](https://getadloop.com) is the hosted version of this project — live now, free during beta (limited seats).** Connect Google in two clicks and use the full toolset from claude.ai, ChatGPT, Claude Code, Cursor, or Gemini. No Google Cloud project, no developer token, no OAuth verification wait. EU-hosted, GDPR-first, DPA included.
 
 ---
 
 ## Cloud or Self-Hosted?
 
-Both versions run the same 64 tools with the same safety model. The difference is who handles the plumbing:
+Both versions run the same tools with the same safety model. The difference is who handles the plumbing:
 
 |  | ☁️ [AdLoop Cloud](https://getadloop.com) | 🛠️ Self-hosted (this repo) |
 |---|---|---|
@@ -63,7 +63,7 @@ Every tool exists because of an actual problem hit while running real Google Ads
 
 The best features come from real workflows. If you're using AdLoop and find yourself wishing it could do something it can't, **open an issue describing your situation** — not just "add feature X" but "I was trying to do Y and couldn't because Z." The context matters more than the request.
 
-## All 64 Tools
+## All Tools
 
 > **Quick start:** `pip install adloop` or `git clone https://github.com/kLOsk/adloop.git && cd adloop && uv sync && uv run adloop init` — or zero setup on [AdLoop Cloud](https://getadloop.com)
 
@@ -156,6 +156,15 @@ These tools read the live GTM container and join it with the codebase + GA4 to f
 |------|-------------|
 | `analyze_page_speed` | PageSpeed Insights for landing pages — Lighthouse score, Core Web Vitals, real-user CrUX data, top fixes. No OAuth needed (optional API key). |
 
+### Merchant Center Tools
+
+| Tool | What It Does |
+|------|-------------|
+| `list_merchant_accounts` | Discover accessible Merchant Center accounts |
+| `get_merchant_feed_health` | Feed health — approved/pending/disapproved counts per reporting context, top product issues with docs, account-level issues. Disapprovals silently starve Shopping/PMax. |
+
+> **Setup for Merchant Center tools** — Enable the **Merchant API** in your GCP project (the Content API for Shopping is deprecated). The Merchant API has no read-only scope; AdLoop uses it strictly read-only. Upgrading OAuth users re-authorize once.
+
 > **Setup for GSC tools** — Enable the **Search Console API** in your GCP project. Upgrading OAuth users must re-authorize once for the new scope (delete `~/.adloop/token.json`, run any tool). The killer combo: cross-reference organic queries with `get_keyword_performance` to find paid/organic cannibalization and untapped keyword opportunities.
 
 ### Planning Tools
@@ -163,7 +172,7 @@ These tools read the live GTM container and join it with the codebase + GA4 to f
 | Tool | What It Does |
 |------|-------------|
 | `discover_keywords` | Discover new keyword ideas from seed keywords and/or a URL — with optional per-month search history + seasonality insights (`include_monthly_volumes`) using Google Ads Keyword Planner. Returns avg monthly searches, competition level, and top-of-page bid range. |
-| `estimate_budget` | Forecast clicks, impressions, and cost for a set of keywords using Google Ads Keyword Planner. Supports geo/language targeting. Essential for budget planning before launching campaigns. |
+| `estimate_budget` | Forecast clicks, cost, and conversions for a set of keywords using Google Ads Keyword Planner. Supports geo/language targeting. Essential for budget planning before launching campaigns. |
 
 ### Google Ads Write Tools
 
@@ -182,6 +191,7 @@ All write operations follow a **draft → preview → confirm** workflow. Nothin
 | `draft_keywords` | Propose keyword additions with match types. Proactively checks bidding strategy — blocks BROAD match on Manual CPC campaigns. |
 | `add_negative_keywords` | Propose negative keywords directly on a campaign |
 | `add_negative_locations` | Propose negative geo exclusions on a campaign — exclude cities/regions while keeping broader positive targets |
+| `draft_key_event` | Mark a GA4 event as a key event (conversion) — the fix for "fires but isn't tracked as a conversion" |
 | `draft_demographic_targeting` | Propose demographic criteria (age, gender, parental status, income) — exclusions by default |
 | `propose_negative_keyword_list` | Draft a shared negative keyword list (SharedSet) and attach it to a campaign — reusable across multiple campaigns |
 | `pause_entity` | Pause a campaign, ad group, ad, or keyword |
@@ -222,6 +232,7 @@ AdLoop manages real ad spend, so safety is not optional.
 
 - **Two-step writes.** Every mutation returns a preview first. A separate `confirm_and_apply` call is required to execute.
 - **Dry-run by default.** Even `confirm_and_apply` defaults to `dry_run=true`. Real changes require explicit `dry_run=false`.
+- **Two-phase apply (optional).** With `safety.two_phase_apply: true`, `confirm_and_apply` refuses `dry_run=false` until the plan has completed one dry-run pass — preview-then-apply becomes server-enforced instead of a convention.
 - **Budget caps.** Configurable maximum daily budget — the server rejects anything above the cap.
 - **Audit log.** Every operation (including dry runs) is logged to `~/.adloop/audit.log`.
 - **New campaigns and ads are PAUSED.** Nothing goes live without manual enablement.
@@ -270,8 +281,10 @@ The wizard walks you through:
 3. **MCC Account ID** — your Manager Account ID (top bar in the MCC UI)
 4. **OAuth sign-in** — opens a browser to sign in with Google (or prints a URL for headless servers)
 5. **Auto-discovers your accounts** — finds your GA4 properties and Ads accounts automatically
-6. **Safety defaults** — budget cap and dry-run preference
-7. **Editor config snippets** — prints MCP configuration for both Cursor and Claude Code
+6. **Optional services** — pin a GTM container, a Search Console property (both auto-discovered too), and a PageSpeed API key; skip any of them with Enter
+7. **Safety defaults** — budget cap and dry-run preference
+8. **Toolsets** — optionally expose only part of the tool catalog to your AI client (see [Toolsets](#toolsets--trim-the-context-footprint))
+9. **Editor config snippets** — prints MCP configuration for both Cursor and Claude Code, including your toolset selection
 
 ### Requirements
 
@@ -405,14 +418,37 @@ All configuration lives in `~/.adloop/config.yaml`. See [`config.yaml.example`](
 | `ads` | `login_customer_id` | — | Your MCC account ID |
 | `safety` | `max_daily_budget` | `50.00` | Maximum allowed daily budget per campaign |
 | `safety` | `require_dry_run` | `true` | Force all writes to dry-run mode |
+| `safety` | `two_phase_apply` | `false` | Refuse real applies until the plan had a dry-run pass |
 | `safety` | `blocked_operations` | `[]` | Operations to block entirely |
 
+### Toolsets — trim the context footprint
+
+Most MCP clients (claude.ai, ChatGPT, Cursor, …) load **every tool schema into the model's context at the start of every conversation**. AdLoop's full catalog costs roughly 18k tokens per session that way — paid before you type a word. If you only use part of AdLoop, expose a subset with the `ADLOOP_TOOLSETS` environment variable in your MCP client's `env` block (the `adloop init` wizard offers this and writes it into the snippets for you):
+
+```json
+"env": { "ADLOOP_TOOLSETS": "ads,ga4" }
+```
+
+| Toolset | Covers |
+|---|---|
+| `ads` | Google Ads reads, writes, and planning (Keyword Planner) |
+| `ga4` | Google Analytics reports, realtime, key events |
+| `tracking` | Cross-channel attribution + tracking code generation |
+| `gtm` | Google Tag Manager audits and reads |
+| `gsc` | Search Console reads |
+| `web` | PageSpeed / Core Web Vitals |
+| `merchant` | Merchant Center feed health |
+
+`health_check` and `confirm_and_apply` are always included, whatever you select. Unset = the full catalog; unknown names fail at startup with the valid list. The effect is real: `ads,ga4` drops the session cost to ~13k tokens, and a `ga4`-only client pays ~2k — nearly 90% less. Toolsets are per *client*, not per install: one AdLoop config can serve a trimmed Cursor and a full-catalog Claude Code side by side.
+
+On [AdLoop Cloud](https://getadloop.com), the same feature is per API key: pick toolsets when creating a key in the dashboard, and that key's tools/list is trimmed server-side for whichever AI client uses it.
+
 ## Project Structure
 
 ```
 src/adloop/
 ├── __init__.py        # Entry point — routes 'adloop init' to wizard, otherwise starts MCP server
-├── server.py          # FastMCP server — 64 tool registrations with safety annotations
+├── server.py          # FastMCP server — 67 tool registrations with safety annotations
 ├── config.py          # Config loader (~/.adloop/config.yaml)
 ├── auth.py            # OAuth 2.0 flow (user-supplied credentials, headless fallback) + service accounts; GA4 / Ads / GTM scopes
 ├── cli.py             # Interactive 'adloop init' setup wizard

{adloop-0.12.0 → adloop-0.13.0}/pyproject.toml

@@ -1,6 +1,6 @@
 [project]
 name = "adloop"
-version = "0.12.0"
+version = "0.13.0"
 description = "The AI command center for Google Ads, GA4, and tracking code."
 readme = "README.md"
 authors = [
@@ -11,7 +11,7 @@ license = { text = "MIT" }
 keywords = ["mcp", "google-ads", "google-analytics", "ga4", "cursor", "marketing"]
 dependencies = [
     "fastmcp>=3.0.0",
-    "google-ads>=29.0.0",
+    "google-ads>=31.1.0",
     "google-analytics-data>=0.20.0",
     "google-analytics-admin>=0.27.0",
     "google-api-python-client>=2.100.0",

{adloop-0.12.0 → adloop-0.13.0}/src/adloop/ads/client.py

@@ -16,7 +16,7 @@ if TYPE_CHECKING:
 # Pin the API version so library upgrades don't silently break field names,
 # enum values, or mutate operation structures. Bump this deliberately when
 # migrating to a new API version — never let it float to the library default.
-GOOGLE_ADS_API_VERSION = "v23"
+GOOGLE_ADS_API_VERSION = "v24"
 
 
 def get_ads_client(config: AdLoopConfig) -> GoogleAdsClient:

{adloop-0.12.0 → adloop-0.13.0}/src/adloop/ads/forecast.py

@@ -22,13 +22,16 @@ def estimate_budget(
     forecast_days: int = 30,
     customer_id: str = "",
 ) -> dict:
-    """Forecast clicks, impressions, and cost for a set of keywords.
+    """Forecast clicks, cost, and conversions for a set of keywords.
 
     Uses KeywordPlanIdeaService.GenerateKeywordForecastMetrics to estimate
     campaign performance without creating anything. Useful for budget planning
     before launching a new campaign.
 
     keywords: list of {"text": str, "match_type": "EXACT|PHRASE|BROAD", "max_cpc": float (optional)}
+        Since Ads API v24 the forecast takes no per-keyword bids — the
+        highest max_cpc across the list becomes the campaign-level manual
+        CPC cap.
     geo_target_id: geo target constant (2276=Germany, 2840=USA, 2826=UK, 2250=France)
     language_id: language constant (1000=English, 1001=German, 1002=French, 1003=Spanish)
     forecast_days: number of days to forecast (default 30)
@@ -45,9 +48,6 @@ def estimate_budget(
     kp_service = client.get_service("KeywordPlanIdeaService")
 
     campaign = client.get_type("CampaignToForecast")
-    campaign.keyword_plan_network = (
-        client.enums.KeywordPlanNetworkEnum.GOOGLE_SEARCH
-    )
 
     max_bid = max(
         (int(kw.get("max_cpc", 0) * 1_000_000) for kw in keywords),
@@ -57,11 +57,9 @@ def estimate_budget(
         max_bid = _DEFAULT_MAX_CPC_MICROS
     campaign.bidding_strategy.manual_cpc_bidding_strategy.max_cpc_bid_micros = max_bid
 
-    geo_modifier = client.get_type("CriterionBidModifier")
-    geo_modifier.geo_target_constant = googleads_service.geo_target_constant_path(
-        geo_target_id
+    campaign.geo_target_constants.append(
+        googleads_service.geo_target_constant_path(geo_target_id)
     )
-    campaign.geo_modifiers.append(geo_modifier)
 
     campaign.language_constants.append(
         googleads_service.language_constant_path(language_id)
@@ -74,15 +72,13 @@ def estimate_budget(
         if not text:
             continue
         match_type = kw.get("match_type", "BROAD").upper()
-        cpc_micros = int(kw.get("max_cpc", 0) * 1_000_000) or _DEFAULT_MAX_CPC_MICROS
 
-        biddable = client.get_type("BiddableKeyword")
-        biddable.max_cpc_bid_micros = cpc_micros
-        biddable.keyword.text = text
-        biddable.keyword.match_type = getattr(
+        keyword = client.get_type("KeywordInfo")
+        keyword.text = text
+        keyword.match_type = getattr(
             client.enums.KeywordMatchTypeEnum, match_type, client.enums.KeywordMatchTypeEnum.BROAD
         )
-        ad_group.biddable_keywords.append(biddable)
+        ad_group.keywords.append(keyword)
 
     campaign.ad_groups.append(ad_group)
 
@@ -98,29 +94,29 @@ def estimate_budget(
     response = kp_service.generate_keyword_forecast_metrics(request=request)
     metrics = response.campaign_forecast_metrics
 
-    # KeywordForecastMetrics fields are ``optional`` in v23, so the SDK
-    # returns ``None`` for unset fields and the actual integer (including
-    # 0) otherwise. Falsy checks like ``int(v) if v else None`` would
+    # KeywordForecastMetrics fields are ``optional``, so the SDK returns
+    # ``None`` for unset fields and the actual number (including 0)
+    # otherwise. Falsy checks like ``int(v) if v else None`` would
     # silently map a real 0-click or 0-cost forecast to None and the
     # caller couldn't tell "no data" apart from "data says zero" — same
     # bug class as discover_keywords (issue Bug 2). Use ``is not None``
     # throughout and the shared ``_micros_to_currency`` helper for the
     # micros→currency conversions.
+    # v24 dropped impressions/click_through_rate from the forecast and
+    # added conversions/average_cpa_micros.
     clicks = getattr(metrics, "clicks", None)
-    impressions = getattr(metrics, "impressions", None)
     avg_cpc_micros = getattr(metrics, "average_cpc_micros", None)
     cost_micros = getattr(metrics, "cost_micros", None)
-    ctr = getattr(metrics, "click_through_rate", None)
+    conversions = getattr(metrics, "conversions", None)
+    avg_cpa_micros = getattr(metrics, "average_cpa_micros", None)
 
     total_cost = _micros_to_currency(cost_micros)
     avg_cpc = _micros_to_currency(avg_cpc_micros)
+    avg_cpa = _micros_to_currency(avg_cpa_micros)
 
     days = max(forecast_days, 1)
     daily = {
         "clicks": round(clicks / days, 1) if clicks is not None else None,
-        "impressions": (
-            round(impressions / days, 1) if impressions is not None else None
-        ),
         "cost": round(total_cost / days, 2) if total_cost is not None else None,
     }
 
@@ -147,15 +143,16 @@ def estimate_budget(
                 f"most available traffic (estimated daily cost: {daily['cost']:.2f})."
             )
 
-    if (
-        impressions is not None
-        and clicks is not None
-        and impressions > 0
-        and clicks == 0
-    ):
+    if clicks is not None and clicks == 0:
+        insights.append(
+            "Forecast shows zero clicks — keywords may be too niche, too "
+            "generic, or the max CPC too low for competitive positions."
+        )
+
+    if conversions is not None and conversions > 0 and avg_cpa is not None:
         insights.append(
-            "Forecast shows impressions but zero clicks — keywords may be too "
-            "generic or CPCs too low for competitive positions."
+            f"Estimated {conversions:.1f} conversions at ~{avg_cpa:.2f} avg "
+            f"CPA (based on historical conversion rates for these keywords)."
         )
 
     return {
@@ -164,10 +161,12 @@ def estimate_budget(
             "end": end_date.isoformat(),
         },
         "estimated_clicks": clicks,
-        "estimated_impressions": impressions,
         "estimated_cost": total_cost,
         "estimated_avg_cpc": avg_cpc,
-        "estimated_ctr": round(ctr, 4) if ctr is not None else None,
+        "estimated_conversions": (
+            round(conversions, 1) if conversions is not None else None
+        ),
+        "estimated_avg_cpa": avg_cpa,
         "daily_estimates": daily,
         "keywords_used": len([kw for kw in keywords if kw.get("text")]),
         "insights": insights,
@@ -227,7 +226,7 @@ def _build_keyword_ideas_rest_body(
 ) -> dict:
     """Build the JSON body for the REST generateKeywordIdeas endpoint.
 
-    Schema follows google-ads REST v23 (camelCase). Exactly one of
+    Schema follows google-ads REST v24 (camelCase). Exactly one of
     ``keywordSeed`` / ``urlSeed`` / ``keywordAndUrlSeed`` is set based on
     which inputs were provided.
     """
@@ -255,7 +254,7 @@ def _post_keyword_ideas_rest_page(
 
     Issue #37: ``KeywordPlanIdeaService.GenerateKeywordIdeas`` over gRPC sits
     in a tight quota bucket that exhausts after a small number of sequential
-    calls and returns ``RESOURCE_EXHAUSTED`` regardless of QPS. The REST v23
+    calls and returns ``RESOURCE_EXHAUSTED`` regardless of QPS. The REST
     endpoint for the same method lives in a separate, much larger quota
     bucket, so this swap eliminates the 429s that made ``discover_keywords``
     unusable for any multi-geo or repeat-call workflow. Filed against
@@ -389,7 +388,7 @@ def discover_keywords(
         seasonality insight — the "Google Trends" view for keyword demand.
 
     Network: this tool intentionally bypasses the google-ads gRPC client for
-    KeywordPlanIdeaService and calls the v23 REST endpoint directly. The
+    KeywordPlanIdeaService and calls the versioned REST endpoint directly. The
     gRPC quota bucket for this single method exhausts almost immediately
     under sequential single-geo calls (issue #37); REST sits in a separate,
     much larger bucket and works without issue. All other Ads tools still

{adloop-0.12.0 → adloop-0.13.0}/src/adloop/ads/pmax.py

@@ -121,7 +121,7 @@ def get_asset_performance(
     content. ``primary_status`` shows whether the asset is eligible to serve
     (ELIGIBLE, NOT_ELIGIBLE, PAUSED, PENDING).
 
-    Note: the Google Ads API v23 does not expose per-asset performance labels
+    Note: the Google Ads API does not expose per-asset performance labels
     (BEST/GOOD/LOW) for PMax assets via GAQL. Use ``get_detailed_asset_performance``
     to see which asset *combinations* Google selects most — that's the closest
     proxy for individual asset quality.

{adloop-0.12.0 → adloop-0.13.0}/src/adloop/ads/write.py

@@ -1789,7 +1789,7 @@ def confirm_and_apply(
     to make real changes.
     """
     from adloop.safety.audit import log_mutation
-    from adloop.safety.preview import get_plan, remove_plan
+    from adloop.safety.preview import get_plan, remove_plan, store_plan
 
     plan = get_plan(plan_id)
     if plan is None:
@@ -1813,6 +1813,17 @@ def confirm_and_apply(
             dry_run=True,
             result="dry_run_success",
         )
+        if plan.dry_run_result is None:
+            # Persist the dry-run pass on the plan; two-phase apply checks
+            # this marker before allowing a real write. Re-storing
+            # overwrites the pending plan (PlanStore.store is an upsert).
+            from datetime import datetime, timezone
+
+            plan.dry_run_result = {
+                "status": "DRY_RUN_SUCCESS",
+                "at": datetime.now(timezone.utc).isoformat(),
+            }
+            store_plan(plan)
         response = {
             "status": "DRY_RUN_SUCCESS",
             "plan_id": plan.plan_id,
@@ -1848,6 +1859,33 @@ def confirm_and_apply(
             )
         return response
 
+    if config.safety.two_phase_apply and plan.dry_run_result is None:
+        # Server-enforced two-phase apply: the preview→confirm flow is a
+        # protocol requirement here, not a convention the calling agent
+        # can skip. Refuse, log the refusal, and keep the plan pending.
+        log_mutation(
+            config.safety.log_file,
+            operation=plan.operation,
+            customer_id=plan.customer_id,
+            entity_type=plan.entity_type,
+            entity_id=plan.entity_id,
+            changes=plan.changes,
+            dry_run=False,
+            result="refused_two_phase",
+        )
+        return {
+            "status": "DRY_RUN_REQUIRED",
+            "plan_id": plan.plan_id,
+            "operation": plan.operation,
+            "message": (
+                f"No changes were made: two-phase apply is enabled and plan "
+                f"'{plan.plan_id}' has not completed a dry run yet. Call "
+                f"confirm_and_apply with dry_run=true once, show the result "
+                f"to the user and get their approval, then call again with "
+                f"dry_run=false — that second call will succeed."
+            ),
+        }
+
     try:
         result = _execute_plan(config, plan)
     except Exception as e:
@@ -2520,9 +2558,16 @@ def _extract_resource_name(resp: object) -> str:
 
 
 def _execute_plan(config: AdLoopConfig, plan: object) -> dict:
-    """Dispatch to the right Google Ads mutate call based on plan.operation."""
+    """Dispatch to the right Google API call based on plan.operation."""
     from adloop.ads.client import get_ads_client, normalize_customer_id
 
+    # GA4 plans dispatch before Ads client construction so they work for
+    # GA4-only setups (no Ads credentials/developer token required).
+    if plan.operation == "create_key_event":
+        from adloop.ga4.write import _apply_create_key_event
+
+        return _apply_create_key_event(config, plan.changes)
+
     client = get_ads_client(config)
     cid = normalize_customer_id(plan.customer_id)