adloop 0.36.0__tar.gz → 0.37.0__tar.gz

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

@@ -1,6 +1,6 @@
 Metadata-Version: 2.3
 Name: adloop
-Version: 0.36.0
+Version: 0.37.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
@@ -131,6 +131,7 @@ The best features come from real workflows. If you're using AdLoop and find your
 | `get_negative_keyword_list_keywords` | List the keywords inside a specific shared negative keyword list |
 | `get_negative_keyword_list_campaigns` | List which campaigns a shared negative keyword list is attached to |
 | `get_recommendations` | Google's auto-generated recommendations with type, estimated impact, and campaign context |
+| `get_recommendation_subscriptions` | Which recommendation types Google applies automatically (auto-apply), with status and last change; flags any that are on |
 | `get_pmax_performance` | Performance Max campaign metrics with network breakdown + asset group ad strength |
 | `get_pmax_assets` | Per-asset details for PMax — field type, serving status, content |
 | `get_asset_group_signals` | A PMax asset group's search themes and audience signal, plus the audiences available for it |
@@ -297,12 +298,12 @@ All write operations follow a **draft → preview → confirm** workflow. Nothin
 
 | Tool | What It Does |
 |------|-------------|
-| `draft_campaign` | Create a full campaign structure — budget + campaign (PAUSED) + ad group + optional keywords. Supports Search partners, display expansion, and `max_cpc` for either MANUAL_CPC initial ad-group bids or TARGET_SPEND (Maximize Clicks) CPC caps. |
+| `draft_campaign` | Create a full campaign structure — budget + campaign (PAUSED) + ad group + optional keywords. Supports Search partners, display expansion, the location option (presence vs presence or interest), campaign URL options (tracking template, final URL suffix, custom parameters), and `max_cpc` for either MANUAL_CPC initial ad-group bids or TARGET_SPEND (Maximize Clicks) CPC caps. |
 | `draft_shopping_campaign` | Create a Standard Shopping campaign for a linked Merchant Center feed — budget, campaign (PAUSED), product ad group, Shopping ad and an "All products" group in one atomic request. Manual CPC, Maximize clicks or target ROAS. |
 | `draft_asset_group_assets` | Add and remove Performance Max assets (text, images incl. uploads, YouTube videos) in one change, so replacing an asset never drops a group below Google's minimums |
 | `draft_asset_group_signals` | Add search themes or set the audience signal of a PMax asset group |
 | `draft_pmax_product_exclusions` | Exclude products from a retail PMax asset group by item id, brand or custom label |
-| `update_campaign` | Modify existing campaign settings — bidding, budget, geo/language targeting, Search partners, display expansion, and TARGET_SPEND (Maximize Clicks) `max_cpc` caps. |
+| `update_campaign` | Modify existing campaign settings — bidding, budget, geo/language targeting, the location option, campaign URL options, Search partners, display expansion, and TARGET_SPEND (Maximize Clicks) `max_cpc` caps. |
 | `draft_ad_group` | Create a paused SEARCH_STANDARD ad group inside an existing campaign, with optional MANUAL_CPC `max_cpc`. |
 | `update_ad_group` | Update an ad group name and/or MANUAL_CPC `max_cpc`. Use `pause_entity` / `enable_entity` for ad-group status changes. |
 | `draft_responsive_search_ad` | Create RSA preview (3-15 headlines ≤30 chars, 2-4 descriptions ≤90 chars). Warns if headline/description count is below best practice. |
@@ -336,6 +337,7 @@ All write operations follow a **draft → preview → confirm** workflow. Nothin
 | `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) |
+| `draft_recommendation_subscriptions` | Pause auto-apply for recommendation types, so Google stops changing the account without a preview. Switching auto-apply back on stays in the Google Ads UI |
 | `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. |

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

@@ -103,6 +103,7 @@ The best features come from real workflows. If you're using AdLoop and find your
 | `get_negative_keyword_list_keywords` | List the keywords inside a specific shared negative keyword list |
 | `get_negative_keyword_list_campaigns` | List which campaigns a shared negative keyword list is attached to |
 | `get_recommendations` | Google's auto-generated recommendations with type, estimated impact, and campaign context |
+| `get_recommendation_subscriptions` | Which recommendation types Google applies automatically (auto-apply), with status and last change; flags any that are on |
 | `get_pmax_performance` | Performance Max campaign metrics with network breakdown + asset group ad strength |
 | `get_pmax_assets` | Per-asset details for PMax — field type, serving status, content |
 | `get_asset_group_signals` | A PMax asset group's search themes and audience signal, plus the audiences available for it |
@@ -269,12 +270,12 @@ All write operations follow a **draft → preview → confirm** workflow. Nothin
 
 | Tool | What It Does |
 |------|-------------|
-| `draft_campaign` | Create a full campaign structure — budget + campaign (PAUSED) + ad group + optional keywords. Supports Search partners, display expansion, and `max_cpc` for either MANUAL_CPC initial ad-group bids or TARGET_SPEND (Maximize Clicks) CPC caps. |
+| `draft_campaign` | Create a full campaign structure — budget + campaign (PAUSED) + ad group + optional keywords. Supports Search partners, display expansion, the location option (presence vs presence or interest), campaign URL options (tracking template, final URL suffix, custom parameters), and `max_cpc` for either MANUAL_CPC initial ad-group bids or TARGET_SPEND (Maximize Clicks) CPC caps. |
 | `draft_shopping_campaign` | Create a Standard Shopping campaign for a linked Merchant Center feed — budget, campaign (PAUSED), product ad group, Shopping ad and an "All products" group in one atomic request. Manual CPC, Maximize clicks or target ROAS. |
 | `draft_asset_group_assets` | Add and remove Performance Max assets (text, images incl. uploads, YouTube videos) in one change, so replacing an asset never drops a group below Google's minimums |
 | `draft_asset_group_signals` | Add search themes or set the audience signal of a PMax asset group |
 | `draft_pmax_product_exclusions` | Exclude products from a retail PMax asset group by item id, brand or custom label |
-| `update_campaign` | Modify existing campaign settings — bidding, budget, geo/language targeting, Search partners, display expansion, and TARGET_SPEND (Maximize Clicks) `max_cpc` caps. |
+| `update_campaign` | Modify existing campaign settings — bidding, budget, geo/language targeting, the location option, campaign URL options, Search partners, display expansion, and TARGET_SPEND (Maximize Clicks) `max_cpc` caps. |
 | `draft_ad_group` | Create a paused SEARCH_STANDARD ad group inside an existing campaign, with optional MANUAL_CPC `max_cpc`. |
 | `update_ad_group` | Update an ad group name and/or MANUAL_CPC `max_cpc`. Use `pause_entity` / `enable_entity` for ad-group status changes. |
 | `draft_responsive_search_ad` | Create RSA preview (3-15 headlines ≤30 chars, 2-4 descriptions ≤90 chars). Warns if headline/description count is below best practice. |
@@ -308,6 +309,7 @@ All write operations follow a **draft → preview → confirm** workflow. Nothin
 | `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) |
+| `draft_recommendation_subscriptions` | Pause auto-apply for recommendation types, so Google stops changing the account without a preview. Switching auto-apply back on stays in the Google Ads UI |
 | `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. |

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

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

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

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

adloop-0.37.0/src/adloop/ads/recommendation_subscriptions.py

@@ -0,0 +1,202 @@
+"""Read and pause Google Ads auto-apply recommendation subscriptions.
+
+A subscription makes Google apply every new recommendation of one type
+without asking, so a change reaches the account with no preview. The v25 API
+(verified against the SDK):
+
+    recommendation_subscription  resource_name, type, status (ENABLED | PAUSED),
+                                 create_date_time, modify_date_time
+    RecommendationSubscriptionService.MutateRecommendationSubscription
+        MutateRecommendationSubscriptionRequest{customer_id, operations[],
+            partial_failure, validate_only, response_content_type}
+
+A type with no subscription row is not auto-applied. The write side can only
+set a subscription to PAUSED: re-enabling auto-apply is a decision for the
+Google Ads UI, because it lets Google change the account without a preview,
+which is what AdLoop's flow exists to prevent. Pausing reduces automation, so
+a single confirmation is enough. The request has ``validate_only``, so the dry
+run goes through the validate-only client like other Google Ads writes.
+"""
+
+from __future__ import annotations
+
+import re
+from datetime import date, datetime, timezone
+from typing import TYPE_CHECKING
+
+if TYPE_CHECKING:
+    from adloop.config import AdLoopConfig
+
+OPERATION = "pause_recommendation_subscriptions"
+
+# A subscription modified this recently is reported as a change, not only as a
+# standing setting: someone (or something) turned it on or touched it lately.
+RECENT_DAYS = 30
+
+_TYPE_RE = re.compile(r"^[A-Z][A-Z0-9_]*$")
+
+_QUERY = """
+    SELECT recommendation_subscription.resource_name,
+           recommendation_subscription.type,
+           recommendation_subscription.status,
+           recommendation_subscription.create_date_time,
+           recommendation_subscription.modify_date_time
+    FROM recommendation_subscription
+"""
+
+
+def _read(config: AdLoopConfig, customer_id: str) -> list[dict]:
+    from adloop.ads.gaql import execute_query
+
+    return [
+        {
+            "type": row.get("recommendation_subscription.type", ""),
+            "status": row.get("recommendation_subscription.status", ""),
+            "resource_name": row.get("recommendation_subscription.resource_name", ""),
+            "create_date_time": row.get("recommendation_subscription.create_date_time", ""),
+            "modify_date_time": row.get("recommendation_subscription.modify_date_time", ""),
+        }
+        for row in execute_query(config, customer_id, _QUERY)
+    ]
+
+
+def _day(value: str) -> date | None:
+    """``2026-10-27 09:14:03`` (account time zone) -> the date, or None."""
+    try:
+        return date.fromisoformat(str(value or "")[:10])
+    except ValueError:
+        return None
+
+
+def get_recommendation_subscriptions(
+    config: AdLoopConfig, *, customer_id: str = "", today: date | None = None
+) -> dict:
+    """Read-only: every auto-apply subscription with its status and dates."""
+    subscriptions = sorted(_read(config, customer_id), key=lambda s: s["type"])
+    enabled = [s for s in subscriptions if s["status"] == "ENABLED"]
+    today = today or datetime.now(timezone.utc).date()
+
+    insights: list[str] = []
+    if enabled:
+        insights.append(
+            f"{len(enabled)} recommendation type(s) auto-apply without a preview: "
+            + ", ".join(s["type"] for s in enabled)
+            + ". Google changes the account for these on its own. "
+            "draft_recommendation_subscriptions pauses them."
+        )
+    for sub in enabled:
+        modified = _day(sub["modify_date_time"])
+        if modified and (today - modified).days <= RECENT_DAYS:
+            insights.append(
+                f"{sub['type']} auto-apply was turned on or changed on "
+                f"{sub['modify_date_time']}, within the last {RECENT_DAYS} days. "
+                "Confirm that was intended."
+            )
+    if not enabled:
+        insights.append("No recommendation type is set to auto-apply.")
+
+    return {
+        "subscriptions": subscriptions,
+        "total_subscriptions": len(subscriptions),
+        "enabled_count": len(enabled),
+        "insights": insights,
+    }
+
+
+def draft_recommendation_subscriptions(
+    config: AdLoopConfig,
+    *,
+    customer_id: str = "",
+    recommendation_types: list[str] | None = None,
+) -> dict:
+    """Draft pausing auto-apply for recommendation types — returns PREVIEW.
+
+    Pausing is the only change this can make. Each type must have an ENABLED
+    subscription; a type with none, or one already paused, is refused by name
+    so the preview only lists what the apply will change.
+    """
+    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)}
+
+    types: list[str] = []
+    errors: list[str] = []
+    for raw in recommendation_types or []:
+        value = str(raw or "").strip().upper()
+        if not value:
+            continue
+        if not _TYPE_RE.match(value):
+            errors.append(f"'{raw}' is not a RecommendationType name")
+        elif value not in types:
+            types.append(value)
+    if not types and not errors:
+        errors.append("At least one recommendation type is required")
+    if errors:
+        return {"error": "Validation failed", "details": errors}
+
+    current = {s["type"]: s for s in _read(config, customer_id)}
+    not_enabled = [t for t in types if current.get(t, {}).get("status") != "ENABLED"]
+    if not_enabled:
+        return {
+            "error": "Validation failed",
+            "details": [
+                "Not auto-applied in this account (no subscription, or already "
+                "paused): " + ", ".join(not_enabled)
+                + ". get_recommendation_subscriptions lists the subscriptions."
+            ],
+        }
+
+    subscriptions = [
+        {
+            "type": t,
+            "resource_name": current[t]["resource_name"],
+            "current_status": "ENABLED",
+            "status": "PAUSED",
+            "modify_date_time": current[t]["modify_date_time"],
+        }
+        for t in types
+    ]
+    plan = ChangePlan(
+        operation=OPERATION,
+        entity_type="recommendation_subscription",
+        entity_id=",".join(types),
+        customer_id=customer_id,
+        changes={
+            "subscriptions": subscriptions,
+            "count": len(subscriptions),
+            "note": (
+                "Pausing stops Google applying these recommendation types on its "
+                "own. Recommendations still appear in get_recommendations. "
+                "Re-enabling auto-apply is done in the Google Ads UI."
+            ),
+        },
+    )
+    store_plan(plan)
+    return plan.to_preview()
+
+
+def _apply_pause_recommendation_subscriptions(
+    client: object, cid: str, changes: dict
+) -> dict:
+    """Set each planned subscription to PAUSED in one request."""
+    from google.protobuf import field_mask_pb2
+
+    service = client.get_service("RecommendationSubscriptionService")
+    request = client.get_type("MutateRecommendationSubscriptionRequest")
+    request.customer_id = cid
+    paused_status = client.enums.RecommendationSubscriptionStatusEnum.PAUSED
+    for sub in changes["subscriptions"]:
+        # Hard-coded: whatever a stored plan says, this path only pauses.
+        operation = client.get_type("RecommendationSubscriptionOperation")
+        operation.update.resource_name = sub["resource_name"]
+        operation.update.status = paused_status
+        operation.update_mask.CopyFrom(field_mask_pb2.FieldMask(paths=["status"]))
+        request.operations.append(operation)
+
+    response = service.mutate_recommendation_subscription(request=request)
+    paused = [result.resource_name for result in response.results]
+    return {"paused": paused, "paused_count": len(paused)}