adloop 0.35.0__tar.gz → 0.36.0__tar.gz

{adloop-0.35.0 → adloop-0.36.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.3
 Name: adloop
-Version: 0.35.0
+Version: 0.36.0
 Summary: The AI command center for Google Ads, Reddit Ads, GA4, and tracking code.
 Keywords: mcp,google-ads,reddit-ads,google-analytics,ga4,cursor,marketing
 Author: Daniel Klose
@@ -148,6 +148,7 @@ The best features come from real workflows. If you're using AdLoop and find your
 | `get_brand_list_brands` | List the brands inside a list, with the Commercial KG MID and the criterion ID for removals |
 | `get_brand_list_campaigns` | Which campaigns a brand list is attached to, and whether each attachment excludes or targets |
 | `get_ai_max_settings` | AI Max knobs per campaign and ad group — `enable_ai_max`, `bundling_required`, the full `asset_automation_settings` list and each ad group's `disable_search_term_matching` |
+| `get_campaign_settings` | One flat record per Search campaign — networks, location option, campaign-level broad match, bidding, budget, URL options and AI Max — with the settings that widen reach flagged |
 | `get_custom_conversion_goals` | Custom conversion goals with their actions, plus one campaign's goal config |
 | `run_gaql` | Arbitrary GAQL queries for anything else |
 
@@ -334,6 +335,7 @@ All write operations follow a **draft → preview → confirm** workflow. Nothin
 | `draft_update_custom_conversion_goal` | Rename a custom conversion goal and/or replace its action list (list replace, not append) |
 | `draft_assign_custom_conversion_goal` | Point a campaign at a custom conversion goal (`goal_config_level = CAMPAIGN`) |
 | `draft_clear_custom_conversion_goal` | Put a campaign back on the account-level goals (rollback) |
+| `draft_dismiss_recommendations` | Dismiss Google recommendations you won't take, so they stop reappearing (Google can show them again later) |
 | `pause_entity` | Pause a campaign, ad group, ad, keyword or PMax asset group |
 | `enable_entity` | Re-enable a paused entity |
 | `remove_entity` | Permanently remove an entity (irreversible — prefers pause). Supports keywords, negative keywords, ads, ad groups, campaigns. |
@@ -523,8 +525,8 @@ adloop install-rules
 
 This writes a managed block to `~/.claude/CLAUDE.md` and copies the slash commands (prefixed `adloop-*`) into `~/.claude/commands/`. The block is delimited by sentinel comments so it's safe to run multiple times — re-running just refreshes the content. Two install modes:
 
-- **inline** (default) — full rules embedded in `~/.claude/CLAUDE.md`. Reliable but adds ~10K tokens to every Claude Code session.
-- **lazy** (`adloop install-rules --lazy`) — small directive in `CLAUDE.md` pointing at `~/.claude/rules/adloop.md`. Cheaper baseline cost; the LLM reads the rules file only when AdLoop tools are in scope.
+- **inline** (default for `install-rules`) — full rules embedded in `~/.claude/CLAUDE.md`. Reliable, but they load into every Claude Code session in every repository, about 30K tokens, whether AdLoop is connected or not.
+- **lazy** (`adloop install-rules --lazy`, and the default in `adloop init`) — a short directive in `CLAUDE.md` pointing at `~/.adloop/rules/adloop.md`. The LLM reads the rules file only when AdLoop tools are in scope, so sessions without AdLoop stay almost free. The file sits outside `~/.claude/` on purpose: Claude Code loads everything in `~/.claude/rules/` into every session.
 
 To refresh after upgrading AdLoop: `adloop update-rules`. To remove cleanly: `adloop uninstall-rules` — only the managed block and `adloop-*` commands are touched, never your own content.
 

{adloop-0.35.0 → adloop-0.36.0}/README.md

@@ -120,6 +120,7 @@ The best features come from real workflows. If you're using AdLoop and find your
 | `get_brand_list_brands` | List the brands inside a list, with the Commercial KG MID and the criterion ID for removals |
 | `get_brand_list_campaigns` | Which campaigns a brand list is attached to, and whether each attachment excludes or targets |
 | `get_ai_max_settings` | AI Max knobs per campaign and ad group — `enable_ai_max`, `bundling_required`, the full `asset_automation_settings` list and each ad group's `disable_search_term_matching` |
+| `get_campaign_settings` | One flat record per Search campaign — networks, location option, campaign-level broad match, bidding, budget, URL options and AI Max — with the settings that widen reach flagged |
 | `get_custom_conversion_goals` | Custom conversion goals with their actions, plus one campaign's goal config |
 | `run_gaql` | Arbitrary GAQL queries for anything else |
 
@@ -306,6 +307,7 @@ All write operations follow a **draft → preview → confirm** workflow. Nothin
 | `draft_update_custom_conversion_goal` | Rename a custom conversion goal and/or replace its action list (list replace, not append) |
 | `draft_assign_custom_conversion_goal` | Point a campaign at a custom conversion goal (`goal_config_level = CAMPAIGN`) |
 | `draft_clear_custom_conversion_goal` | Put a campaign back on the account-level goals (rollback) |
+| `draft_dismiss_recommendations` | Dismiss Google recommendations you won't take, so they stop reappearing (Google can show them again later) |
 | `pause_entity` | Pause a campaign, ad group, ad, keyword or PMax asset group |
 | `enable_entity` | Re-enable a paused entity |
 | `remove_entity` | Permanently remove an entity (irreversible — prefers pause). Supports keywords, negative keywords, ads, ad groups, campaigns. |
@@ -495,8 +497,8 @@ adloop install-rules
 
 This writes a managed block to `~/.claude/CLAUDE.md` and copies the slash commands (prefixed `adloop-*`) into `~/.claude/commands/`. The block is delimited by sentinel comments so it's safe to run multiple times — re-running just refreshes the content. Two install modes:
 
-- **inline** (default) — full rules embedded in `~/.claude/CLAUDE.md`. Reliable but adds ~10K tokens to every Claude Code session.
-- **lazy** (`adloop install-rules --lazy`) — small directive in `CLAUDE.md` pointing at `~/.claude/rules/adloop.md`. Cheaper baseline cost; the LLM reads the rules file only when AdLoop tools are in scope.
+- **inline** (default for `install-rules`) — full rules embedded in `~/.claude/CLAUDE.md`. Reliable, but they load into every Claude Code session in every repository, about 30K tokens, whether AdLoop is connected or not.
+- **lazy** (`adloop install-rules --lazy`, and the default in `adloop init`) — a short directive in `CLAUDE.md` pointing at `~/.adloop/rules/adloop.md`. The LLM reads the rules file only when AdLoop tools are in scope, so sessions without AdLoop stay almost free. The file sits outside `~/.claude/` on purpose: Claude Code loads everything in `~/.claude/rules/` into every session.
 
 To refresh after upgrading AdLoop: `adloop update-rules`. To remove cleanly: `adloop uninstall-rules` — only the managed block and `adloop-*` commands are touched, never your own content.
 

{adloop-0.35.0 → adloop-0.36.0}/pyproject.toml

@@ -1,6 +1,6 @@
 [project]
 name = "adloop"
-version = "0.35.0"
+version = "0.36.0"
 description = "The AI command center for Google Ads, Reddit Ads, GA4, and tracking code."
 readme = "README.md"
 requires-python = ">=3.11"

{adloop-0.35.0 → adloop-0.36.0}/pyproject.toml.orig

@@ -1,6 +1,6 @@
 [project]
 name = "adloop"
-version = "0.35.0"
+version = "0.36.0"
 description = "The AI command center for Google Ads, Reddit Ads, GA4, and tracking code."
 readme = "README.md"
 authors = [

{adloop-0.35.0 → adloop-0.36.0}/src/adloop/ads/assets.py

@@ -1415,13 +1415,14 @@ def draft_promotion(
     scope: str = "",
     language_code: str = "",
     currency_code: str = "",
+    ad_schedule: list[dict] | None = None,
     **promotion,
 ) -> dict:
     """Draft a promotion asset linked to an ad group, a campaign or the account.
 
     ``promotion`` takes promotion_target, final_url, money_off or percent_off,
     promotion_code or orders_over_amount, occasion, discount_modifier and the
-    four dates.
+    four dates. ``ad_schedule`` limits the hours it shows.
     """
     from adloop.safety.preview import ChangePlan, store_plan
 
@@ -1430,6 +1431,8 @@ def draft_promotion(
     scope, campaign_id, ad_group_id, errors = resolve_scope(scope, campaign_id, ad_group_id)
     fields, parse_errors = _promotion_input(**promotion)
     fields["language_code"] = _language(language_code, errors)
+    fields["ad_schedule"], schedule_errors = _validate_schedule(ad_schedule or [])
+    errors += schedule_errors
     errors += parse_errors or _check_promotion(fields)
     if errors:
         return {"error": "Validation failed", "details": errors}
@@ -1456,6 +1459,8 @@ def draft_promotion(
     preview = plan.to_preview()
     preview["warnings"] = [*warnings, *_promotion_warnings(fields), *url_warnings] + (
         [_account_scope_warning("promotions")] if scope == "account" else [])
+    if fields["ad_schedule"]:
+        preview["warnings"].append(_time_zone_note(_account_settings(config, customer_id)["time_zone"]))
     return preview
 
 
@@ -1472,8 +1477,10 @@ _PROMOTION_FIELDS = {
     "discount_modifier": "asset.promotion_asset.discount_modifier",
     "language_code": "asset.promotion_asset.language_code",
     **{field: f"asset.promotion_asset.{field}" for field in _DATE_FIELDS},
+    "ad_schedule": "asset.promotion_asset.ad_schedule_targets",
 }
-_CLEARABLE = ("promotion_code", "orders_over_amount", "occasion", "discount_modifier", *_DATE_FIELDS)
+_CLEARABLE = ("promotion_code", "orders_over_amount", "occasion", "discount_modifier", *_DATE_FIELDS,
+              "ad_schedule")
 
 
 def _promotion_from_google(raw: dict) -> dict:
@@ -1490,6 +1497,7 @@ def _promotion_from_google(raw: dict) -> dict:
         "discount_modifier": raw["discount_modifier"],
         "language_code": raw["language_code"],
         **{field: raw[field] for field in _DATE_FIELDS},
+        "ad_schedule": _schedule_from_google(raw["ad_schedule"]),
     }
 
 
@@ -1501,9 +1509,14 @@ def update_promotion(
     language_code: str = "",
     currency_code: str = "",
     clear_fields: list[str] | None = None,
+    ad_schedule: list[dict] | None = None,
     **promotion,
 ) -> dict:
-    """Draft an in-place edit of a promotion asset; fields not passed stay as they are."""
+    """Draft an in-place edit of a promotion asset; fields not passed stay as they are.
+
+    A non-empty ``ad_schedule`` replaces the promotion's schedule;
+    ``clear_fields=["ad_schedule"]`` removes it.
+    """
     if blocked := _blocked("update_promotion", config):
         return blocked
     asset_id = _clean(asset_id)
@@ -1511,6 +1524,10 @@ def update_promotion(
     passed, parse_errors = _promotion_input(**promotion)
     errors += parse_errors
     passed = {k: v for k, v in passed.items() if v}
+    windows, schedule_errors = _validate_schedule(ad_schedule or [])
+    errors += schedule_errors
+    if windows:
+        passed["ad_schedule"] = windows
     if _clean(language_code):
         passed["language_code"] = _language(language_code, errors)
     clear = [_clean(f).lower() for f in clear_fields or []]
@@ -1539,7 +1556,7 @@ def update_promotion(
     if "orders_over_amount" in passed:
         merged["promotion_code"] = ""
     for field in clear:
-        merged[field] = 0.0 if field == "orders_over_amount" else ""
+        merged[field] = {"orders_over_amount": 0.0, "ad_schedule": []}.get(field, "")
     errors = _check_promotion(merged)
     if errors:
         return {"error": "Validation failed", "details": errors}
@@ -1565,6 +1582,10 @@ def update_promotion(
                          {"set": changed, "promotion": merged},
                          {k: current[k] for k in changed}, pinned={k: raw[k] for k in _PROMOTION_FIELDS})
     preview["warnings"] += warnings + _promotion_warnings(merged)
+    if "ad_schedule" in changed:
+        preview["warnings"].append(
+            _time_zone_note(_account_settings(config, customer_id)["time_zone"]) if merged["ad_schedule"]
+            else "Without a schedule the promotion shows at all hours the campaign serves.")
     return preview
 
 
@@ -1589,6 +1610,10 @@ def _populate_promotion(client, asset, promo: dict) -> None:
     for field in _DATE_FIELDS:
         if promo.get(field):
             setattr(p, field, promo[field])
+    for window in promo.get("ad_schedule") or []:
+        info = client.get_type("AdScheduleInfo")
+        _populate_schedule(client, info, window)
+        p.ad_schedule_targets.append(info)
     asset.final_urls.append(promo["final_url"])
 
 
@@ -1638,6 +1663,12 @@ def _apply_update_promotion(client, cid: str, changes: dict) -> dict:
                 if promo[field]:
                     setattr(p, field, promo[field])
                 paths.append(f"promotion_asset.{field}")
+        if "ad_schedule" in changed:  # replaces the whole list; empty clears it
+            for window in promo["ad_schedule"]:
+                info = client.get_type("AdScheduleInfo")
+                _populate_schedule(client, info, window)
+                p.ad_schedule_targets.append(info)
+            paths.append("promotion_asset.ad_schedule_targets")
         return list(dict.fromkeys(paths))
 
     return _apply_asset_update(client, cid, changes["asset_id"], set_fields)

adloop-0.36.0/src/adloop/ads/campaign_settings.py

@@ -0,0 +1,222 @@
+"""One read for the settings that decide how far a Search campaign reaches.
+
+A recurring audit ("has Google switched anything back on?") otherwise needs
+``get_ai_max_settings`` plus hand-written GAQL for networks, location option,
+campaign-level broad match and URL options. Every field below was checked
+against the v25 ``campaign`` resource:
+
+    campaign.network_settings.target_google_search / target_search_network /
+        target_content_network / target_partner_search_network
+    campaign.geo_target_type_setting.positive_geo_target_type   PRESENCE_OR_INTEREST,
+                                                                SEARCH_INTEREST, PRESENCE
+    campaign.geo_target_type_setting.negative_geo_target_type   PRESENCE_OR_INTEREST, PRESENCE
+    campaign.keyword_match_type                                 BROAD, or unset
+    campaign.tracking_url_template, final_url_suffix, url_custom_parameters
+    campaign.bidding_strategy_type and the per-strategy targets
+    campaign_budget.amount_micros, explicitly_shared
+
+The AI Max half comes from ``ai_max.read_ai_max_state`` unchanged, so both tools
+always agree. Read-only: nothing here mutates.
+"""
+
+from __future__ import annotations
+
+from typing import TYPE_CHECKING
+
+if TYPE_CHECKING:
+    from adloop.config import AdLoopConfig
+
+_SETTINGS_SELECT = """
+    SELECT campaign.id, campaign.name, campaign.status,
+           campaign.advertising_channel_type,
+           campaign.bidding_strategy_type, campaign.bidding_strategy,
+           campaign.target_spend.cpc_bid_ceiling_micros,
+           campaign.maximize_conversions.target_cpa_micros,
+           campaign.target_cpa.target_cpa_micros,
+           campaign.target_roas.target_roas,
+           campaign.maximize_conversion_value.target_roas,
+           campaign.network_settings.target_google_search,
+           campaign.network_settings.target_search_network,
+           campaign.network_settings.target_content_network,
+           campaign.geo_target_type_setting.positive_geo_target_type,
+           campaign.geo_target_type_setting.negative_geo_target_type,
+           campaign.keyword_match_type,
+           campaign.tracking_url_template, campaign.final_url_suffix,
+           campaign.url_custom_parameters,
+           campaign_budget.amount_micros, campaign_budget.explicitly_shared
+    FROM campaign
+    WHERE {where}
+    ORDER BY campaign.name
+"""
+
+_SEARCH_ONLY = "campaign.advertising_channel_type = 'SEARCH'"
+_WHERE_ALL = f"campaign.status != 'REMOVED' AND {_SEARCH_ONLY}"
+
+# Google's default; it also reaches people elsewhere who search *about* the
+# targeted locations.
+_WIDE_LOCATION_OPTIONS = {"PRESENCE_OR_INTEREST", "SEARCH_INTEREST"}
+
+
+def _money(micros: object) -> float | None:
+    """Micros to account currency; 0 or missing means "not set"."""
+    if not micros:
+        return None
+    return round(int(micros) / 1_000_000, 2)
+
+
+def _target_cpa(row: dict) -> float | None:
+    return _money(
+        row.get("campaign.target_cpa.target_cpa_micros")
+        or row.get("campaign.maximize_conversions.target_cpa_micros")
+    )
+
+
+def _target_roas(row: dict) -> float | None:
+    value = row.get("campaign.target_roas.target_roas") or row.get(
+        "campaign.maximize_conversion_value.target_roas"
+    )
+    return value or None
+
+
+def _custom_parameters(value: object) -> list[dict]:
+    if not isinstance(value, list):
+        return []
+    return [
+        {"key": item.get("key", ""), "value": item.get("value", "")}
+        for item in value
+        if isinstance(item, dict)
+    ]
+
+
+def _widening(campaign: dict) -> list[str]:
+    """The settings on this campaign that let ads reach beyond what was chosen."""
+    found: list[str] = []
+    if campaign["search_partners"]:
+        found.append("search partners on")
+    if campaign["display_network"]:
+        found.append("Display network on")
+    if campaign["location_option"] in _WIDE_LOCATION_OPTIONS:
+        found.append(f"location option {campaign['location_option']}")
+    if campaign["keyword_match_type"] == "BROAD":
+        found.append("campaign-level broad match on")
+    if campaign["enable_ai_max"]:
+        found.append("AI Max on")
+    for automation, status in campaign["asset_automation"].items():
+        if status == "OPTED_IN":
+            found.append(f"{automation} opted in")
+    return found
+
+
+def get_campaign_settings(
+    config: AdLoopConfig,
+    *,
+    customer_id: str = "",
+    campaign_id: str = "",
+) -> dict:
+    """Read-only, one flat record per Search campaign. See the module docstring."""
+    from adloop.ads.client import get_ads_client, normalize_customer_id
+    from adloop.ads.currency import get_currency_code
+
+    campaign_id = str(campaign_id or "").strip()
+    if campaign_id and not campaign_id.isdigit():
+        return {"error": "campaign_id must be a numeric ID"}
+
+    cid = normalize_customer_id(customer_id or config.ads.customer_id)
+    client = get_ads_client(config)
+    result = read_campaign_settings(client, cid, campaign_id=campaign_id)
+    result["currency"] = get_currency_code(config, cid)
+    return result
+
+
+def read_campaign_settings(client: object, cid: str, *, campaign_id: str = "") -> dict:
+    """Run both reads and merge them per campaign."""
+    from adloop.ads.ai_max import _search, read_ai_max_state
+
+    if campaign_id and not str(campaign_id).isdigit():
+        # The id goes into the query text; anything else must not reach GAQL.
+        raise ValueError("campaign_id must be a numeric ID")
+    # An explicit ID stays Search-only too: the AI Max and location settings
+    # read here don't apply to Performance Max or Display campaigns.
+    where = f"campaign.id = {campaign_id} AND {_SEARCH_ONLY}" if campaign_id else _WHERE_ALL
+    rows = _search(
+        client.get_service("GoogleAdsService"), cid, _SETTINGS_SELECT.format(where=where)
+    )
+    ai_max = {
+        c["campaign_id"]: c
+        for c in read_ai_max_state(client, cid, campaign_id=campaign_id)["campaigns"]
+    }
+
+    campaigns: list[dict] = []
+    for row in rows:
+        key = str(row.get("campaign.id", ""))
+        if not key or (campaign_id and key != str(campaign_id)):
+            continue
+        ai = ai_max.get(key, {})
+        campaign = {
+            "campaign_id": key,
+            "campaign_name": row.get("campaign.name"),
+            "status": row.get("campaign.status"),
+            "advertising_channel_type": row.get("campaign.advertising_channel_type"),
+            "bidding_strategy_type": row.get("campaign.bidding_strategy_type"),
+            "portfolio_bidding_strategy": row.get("campaign.bidding_strategy") or None,
+            "cpc_bid_ceiling": _money(
+                row.get("campaign.target_spend.cpc_bid_ceiling_micros")
+            ),
+            "target_cpa": _target_cpa(row),
+            "target_roas": _target_roas(row),
+            "daily_budget": _money(row.get("campaign_budget.amount_micros")),
+            "budget_shared": bool(row.get("campaign_budget.explicitly_shared")),
+            "google_search": bool(row.get("campaign.network_settings.target_google_search")),
+            "search_partners": bool(
+                row.get("campaign.network_settings.target_search_network")
+            ),
+            "display_network": bool(
+                row.get("campaign.network_settings.target_content_network")
+            ),
+            "location_option": row.get(
+                "campaign.geo_target_type_setting.positive_geo_target_type"
+            ),
+            "negative_location_option": row.get(
+                "campaign.geo_target_type_setting.negative_geo_target_type"
+            ),
+            "keyword_match_type": row.get("campaign.keyword_match_type"),
+            "tracking_url_template": row.get("campaign.tracking_url_template") or "",
+            "final_url_suffix": row.get("campaign.final_url_suffix") or "",
+            "url_custom_parameters": _custom_parameters(
+                row.get("campaign.url_custom_parameters")
+            ),
+            "enable_ai_max": bool(ai.get("enable_ai_max")),
+            "asset_automation": {
+                item["asset_automation_type"]: item.get("asset_automation_status", "")
+                for item in ai.get("asset_automation_settings", [])
+            },
+            # Search term matching only acts under AI Max; listing every ad
+            # group's default False otherwise would be noise.
+            "ad_groups_with_search_term_matching": [
+                g["ad_group_name"]
+                for g in ai.get("ad_groups", [])
+                if g.get("disable_search_term_matching") is False
+            ] if ai.get("enable_ai_max") else [],
+        }
+        campaign["widening_settings"] = _widening(campaign)
+        campaigns.append(campaign)
+
+    insights: list[str] = []
+    for campaign in campaigns:
+        if campaign["widening_settings"]:
+            insights.append(
+                f"{campaign['campaign_name']} ({campaign['campaign_id']}): "
+                + ", ".join(campaign["widening_settings"])
+                + ". These let the ads reach beyond the keywords and locations "
+                "chosen; confirm they are intended."
+            )
+    if campaigns and not insights:
+        insights.append("No setting that widens reach is on in any campaign returned.")
+    if not campaigns:
+        insights.append("No non-removed Search campaign matched.")
+
+    return {
+        "campaigns": campaigns,
+        "total_campaigns": len(campaigns),
+        "insights": insights,
+    }

{adloop-0.35.0 → adloop-0.36.0}/src/adloop/ads/read.py

@@ -843,6 +843,10 @@ def get_recommendations(
         pot_conversions = _round_metric(getattr(pot, "conversions", 0))
 
         entry = {
+            # The ID (last segment of the resource name) is what
+            # draft_dismiss_recommendations takes.
+            "recommendation.id": rec.resource_name.rsplit("/", 1)[-1],
+            "recommendation.resource_name": rec.resource_name,
             "recommendation.type": rec_type,
             "recommendation.campaign": rec.campaign,
             "recommendation.ad_group": rec.ad_group or "",

adloop-0.36.0/src/adloop/ads/recommendations.py

@@ -0,0 +1,210 @@
+"""Dismiss Google Ads recommendations.
+
+``get_recommendations`` (in ``ads/read.py``) lists the active ones; this module
+turns a chosen subset down. The v25 call (verified against the SDK):
+
+    RecommendationService.DismissRecommendation
+        DismissRecommendationRequest{customer_id, operations[], partial_failure}
+        DismissRecommendationOperation{resource_name}
+
+The request has **no** ``validate_only`` field, so a dry run cannot hand the
+exact call to Google the way other Google Ads writes do. Instead the dry run
+re-reads the account and checks that every planned recommendation is still
+active (``preflight``), the same approach the Reddit, Tag Manager and GA4
+writes use. The validate-only client still refuses the call outright, so this
+path can never dismiss anything during a dry run.
+
+Dismissing is mild: nothing in the account changes, and Google can show the
+recommendation again later. A single confirmation is enough.
+"""
+
+from __future__ import annotations
+
+import re
+from typing import TYPE_CHECKING
+
+if TYPE_CHECKING:
+    from adloop.config import AdLoopConfig
+
+OPERATION = "dismiss_recommendations"
+
+# A recommendation ID is the last segment of its resource name. Google does not
+# document the alphabet, so accept what resource names can carry and nothing
+# that could break out of one.
+_ID_RE = re.compile(r"^[A-Za-z0-9_~=+-]+$")
+_RESOURCE_RE = re.compile(r"^customers/(\d+)/recommendations/([A-Za-z0-9_~=+-]+)$")
+
+
+def recommendation_id(resource_name: str) -> str:
+    """``customers/1/recommendations/abc`` -> ``abc``."""
+    return str(resource_name or "").rsplit("/", 1)[-1]
+
+
+def _clean_ids(values: list[str] | None, cid: str) -> tuple[list[str], list[str]]:
+    """Accept bare IDs or full resource names. Returns (errors, deduped IDs)."""
+    errors: list[str] = []
+    ids: list[str] = []
+    for raw in values or []:
+        value = str(raw or "").strip()
+        if not value:
+            continue
+        match = _RESOURCE_RE.match(value)
+        if match:
+            if match.group(1) != cid:
+                errors.append(
+                    f"{value} belongs to account {match.group(1)}, not {cid}"
+                )
+                continue
+            value = match.group(2)
+        elif not _ID_RE.match(value):
+            errors.append(f"'{value}' is not a recommendation ID or resource name")
+            continue
+        if value not in ids:
+            ids.append(value)
+    return errors, ids
+
+
+def _active_by_id(config: AdLoopConfig, customer_id: str) -> dict[str, dict]:
+    """Every active (not dismissed) recommendation, keyed by ID."""
+    from adloop.ads.read import get_recommendations
+
+    rows = get_recommendations(config, customer_id=customer_id).get(
+        "recommendations", []
+    )
+    return {
+        recommendation_id(row.get("recommendation.resource_name", "")): row
+        for row in rows
+        if row.get("recommendation.resource_name")
+    }
+
+
+def draft_dismiss_recommendations(
+    config: AdLoopConfig,
+    *,
+    customer_id: str = "",
+    recommendation_ids: list[str] | None = None,
+) -> dict:
+    """Draft dismissing recommendations — returns PREVIEW.
+
+    Reads the active recommendations first: an ID that is unknown or already
+    dismissed is refused by name, so the preview only ever lists what the
+    apply will turn down. Each entry carries its type, campaign and Google's
+    estimated improvement, the same numbers ``get_recommendations`` shows.
+
+    Call ``confirm_and_apply`` with the returned plan_id to execute.
+    """
+    from adloop.ads.client import normalize_customer_id
+    from adloop.safety.guards import SafetyViolation, check_blocked_operation
+    from adloop.safety.preview import ChangePlan, store_plan
+
+    try:
+        check_blocked_operation(OPERATION, config.safety)
+    except SafetyViolation as e:
+        return {"error": str(e)}
+
+    cid = normalize_customer_id(customer_id or config.ads.customer_id)
+    errors, ids = _clean_ids(recommendation_ids, cid)
+    if not ids and not errors:
+        errors.append("At least one recommendation_id is required")
+    if errors:
+        return {"error": "Validation failed", "details": errors}
+
+    active = _active_by_id(config, customer_id)
+    missing = [rec_id for rec_id in ids if rec_id not in active]
+    if missing:
+        return {
+            "error": "Validation failed",
+            "details": [
+                "Not an active recommendation in this account (unknown, or "
+                "already dismissed): " + ", ".join(missing)
+                + ". get_recommendations lists the active ones with their IDs."
+            ],
+        }
+
+    recommendations = [
+        {
+            "recommendation_id": rec_id,
+            "resource_name": active[rec_id]["recommendation.resource_name"],
+            "type": active[rec_id].get("recommendation.type", ""),
+            "campaign": active[rec_id].get("recommendation.campaign", ""),
+            "ad_group": active[rec_id].get("recommendation.ad_group", ""),
+            "estimated_improvement": active[rec_id].get("estimated_improvement", {}),
+        }
+        for rec_id in ids
+    ]
+    plan = ChangePlan(
+        operation=OPERATION,
+        entity_type="recommendation",
+        entity_id=",".join(ids),
+        customer_id=customer_id,
+        changes={
+            "recommendations": recommendations,
+            "count": len(recommendations),
+            "note": (
+                "Dismissing changes nothing in the account. Google can show a "
+                "dismissed recommendation again later."
+            ),
+        },
+    )
+    store_plan(plan)
+    return plan.to_preview()
+
+
+def preflight(config: AdLoopConfig, plan: object) -> dict:
+    """Dry run: every planned recommendation must still be active.
+
+    DismissRecommendation has no validate-only mode, so this re-read is the
+    whole check. Raises when any recommendation has gone (dismissed in the UI,
+    applied, or expired), so the dry run fails instead of reporting success.
+    """
+    planned = [r["recommendation_id"] for r in plan.changes["recommendations"]]
+    active = _active_by_id(config, plan.customer_id)
+    gone = [rec_id for rec_id in planned if rec_id not in active]
+    if gone:
+        raise ValueError(
+            "No longer active (dismissed, applied or expired since the "
+            "preview): " + ", ".join(gone) + ". Draft again."
+        )
+    return {"recommendations_checked": len(planned), "still_active": len(planned)}
+
+
+def _apply_dismiss_recommendations(client: object, cid: str, changes: dict) -> dict:
+    """Dismiss the planned recommendations; per-recommendation errors are reported."""
+    from adloop.ads.write import _parse_partial_failure_per_op
+
+    names = [r["resource_name"] for r in changes["recommendations"]]
+    service = client.get_service("RecommendationService")
+    request = client.get_type("DismissRecommendationRequest")
+    request.customer_id = cid
+    request.partial_failure = True
+    operation_type = type(request).DismissRecommendationOperation
+    for name in names:
+        request.operations.append(operation_type(resource_name=name))
+
+    response = service.dismiss_recommendation(request=request)
+
+    pf_error = getattr(response, "partial_failure_error", None)
+    per_op_errors = _parse_partial_failure_per_op(client, pf_error)
+    dismissed: list[str] = []
+    failed: list[dict] = []
+    for index, result in enumerate(response.results):
+        if result.resource_name:
+            dismissed.append(result.resource_name)
+        else:
+            failed.append(
+                {
+                    "recommendation_id": recommendation_id(names[index]),
+                    "error": per_op_errors.get(
+                        index, "Unknown error (see partial_failure_message)"
+                    ),
+                }
+            )
+
+    out: dict = {"dismissed": dismissed, "dismissed_count": len(dismissed)}
+    if failed:
+        out["partial_failure"] = True
+        out["failed"] = failed
+        message = getattr(pf_error, "message", "") if pf_error is not None else ""
+        if message:
+            out["partial_failure_message"] = message
+    return out