adloop 0.1.0__py3-none-any.whl

adloop/ads/write.py

@@ -0,0 +1,950 @@
+"""Google Ads write tools — all behind the safety layer.
+
+Every write tool returns a preview/plan. Nothing executes until
+``confirm_and_apply`` is called with the plan ID.
+"""
+
+from __future__ import annotations
+
+from typing import TYPE_CHECKING
+
+if TYPE_CHECKING:
+    from adloop.config import AdLoopConfig
+
+
+# ---------------------------------------------------------------------------
+# Draft tools — validate inputs, create a ChangePlan, return preview
+# ---------------------------------------------------------------------------
+
+
+def draft_responsive_search_ad(
+    config: AdLoopConfig,
+    *,
+    customer_id: str = "",
+    ad_group_id: str = "",
+    headlines: list[str] | None = None,
+    descriptions: list[str] | None = None,
+    final_url: str = "",
+    path1: str = "",
+    path2: str = "",
+) -> dict:
+    """Draft a Responsive Search Ad — returns preview, does NOT execute."""
+    from adloop.safety.guards import SafetyViolation, check_blocked_operation
+    from adloop.safety.preview import ChangePlan, store_plan
+
+    try:
+        check_blocked_operation("create_responsive_search_ad", config.safety)
+    except SafetyViolation as e:
+        return {"error": str(e)}
+
+    headlines = headlines or []
+    descriptions = descriptions or []
+
+    errors = _validate_rsa(ad_group_id, headlines, descriptions, final_url)
+    if errors:
+        return {"error": "Validation failed", "details": errors}
+
+    warnings = []
+    if len(headlines) < 8:
+        warnings.append(
+            f"Only {len(headlines)} headlines provided. Google recommends 8-15 "
+            "diverse headlines for optimal RSA performance."
+        )
+    if len(descriptions) < 3:
+        warnings.append(
+            f"Only {len(descriptions)} descriptions provided. Google recommends "
+            "3-4 descriptions for optimal RSA performance."
+        )
+
+    plan = ChangePlan(
+        operation="create_responsive_search_ad",
+        entity_type="ad",
+        customer_id=customer_id,
+        changes={
+            "ad_group_id": ad_group_id,
+            "headlines": headlines,
+            "descriptions": descriptions,
+            "final_url": final_url,
+            "path1": path1,
+            "path2": path2,
+        },
+    )
+    store_plan(plan)
+    preview = plan.to_preview()
+    if warnings:
+        preview["warnings"] = warnings
+    return preview
+
+
+def draft_keywords(
+    config: AdLoopConfig,
+    *,
+    customer_id: str = "",
+    ad_group_id: str = "",
+    keywords: list[dict] | None = None,
+) -> dict:
+    """Draft keyword additions with match types — returns preview."""
+    from adloop.safety.guards import SafetyViolation, check_blocked_operation
+    from adloop.safety.preview import ChangePlan, store_plan
+
+    try:
+        check_blocked_operation("add_keywords", config.safety)
+    except SafetyViolation as e:
+        return {"error": str(e)}
+
+    keywords = keywords or []
+
+    errors = _validate_keywords(ad_group_id, keywords)
+    if errors:
+        return {"error": "Validation failed", "details": errors}
+
+    warnings = _check_broad_match_safety(config, customer_id, ad_group_id, keywords)
+
+    plan = ChangePlan(
+        operation="add_keywords",
+        entity_type="keyword",
+        customer_id=customer_id,
+        changes={
+            "ad_group_id": ad_group_id,
+            "keywords": keywords,
+        },
+    )
+    store_plan(plan)
+    preview = plan.to_preview()
+    if warnings:
+        preview["warnings"] = warnings
+    return preview
+
+
+def add_negative_keywords(
+    config: AdLoopConfig,
+    *,
+    customer_id: str = "",
+    campaign_id: str = "",
+    keywords: list[str] | None = None,
+    match_type: str = "EXACT",
+) -> dict:
+    """Draft negative keyword additions — returns preview."""
+    from adloop.safety.guards import SafetyViolation, check_blocked_operation
+    from adloop.safety.preview import ChangePlan, store_plan
+
+    try:
+        check_blocked_operation("add_negative_keywords", config.safety)
+    except SafetyViolation as e:
+        return {"error": str(e)}
+
+    keywords = keywords or []
+    match_type = match_type.upper()
+
+    errors = []
+    if not campaign_id:
+        errors.append("campaign_id is required")
+    if not keywords:
+        errors.append("At least one keyword is required")
+    if match_type not in _VALID_MATCH_TYPES:
+        errors.append(f"Invalid match_type '{match_type}' — use EXACT, PHRASE, or BROAD")
+    if errors:
+        return {"error": "Validation failed", "details": errors}
+
+    plan = ChangePlan(
+        operation="add_negative_keywords",
+        entity_type="negative_keyword",
+        entity_id=campaign_id,
+        customer_id=customer_id,
+        changes={
+            "campaign_id": campaign_id,
+            "keywords": keywords,
+            "match_type": match_type,
+        },
+    )
+    store_plan(plan)
+    return plan.to_preview()
+
+
+def pause_entity(
+    config: AdLoopConfig,
+    *,
+    customer_id: str = "",
+    entity_type: str = "",
+    entity_id: str = "",
+) -> dict:
+    """Draft pausing a campaign/ad group/ad/keyword — returns preview."""
+    return _draft_status_change(
+        config, "pause_entity", customer_id, entity_type, entity_id, "PAUSED"
+    )
+
+
+def enable_entity(
+    config: AdLoopConfig,
+    *,
+    customer_id: str = "",
+    entity_type: str = "",
+    entity_id: str = "",
+) -> dict:
+    """Draft enabling a paused entity — returns preview."""
+    return _draft_status_change(
+        config, "enable_entity", customer_id, entity_type, entity_id, "ENABLED"
+    )
+
+
+def remove_entity(
+    config: AdLoopConfig,
+    *,
+    customer_id: str = "",
+    entity_type: str = "",
+    entity_id: str = "",
+) -> dict:
+    """Draft removing an entity (keyword, negative_keyword, ad, ad_group, campaign).
+
+    This is a DESTRUCTIVE operation — removed entities cannot be re-enabled.
+    For keywords and negative keywords, this fully deletes the criterion.
+    Returns a preview; call confirm_and_apply to execute.
+    """
+    from adloop.safety.guards import SafetyViolation, check_blocked_operation
+    from adloop.safety.preview import ChangePlan, store_plan
+
+    try:
+        check_blocked_operation("remove_entity", config.safety)
+    except SafetyViolation as e:
+        return {"error": str(e)}
+
+    errors = []
+    if entity_type not in _REMOVABLE_ENTITY_TYPES:
+        errors.append(
+            f"entity_type must be one of {_REMOVABLE_ENTITY_TYPES}, "
+            f"got '{entity_type}'"
+        )
+    if not entity_id:
+        errors.append("entity_id is required")
+    if errors:
+        return {"error": "Validation failed", "details": errors}
+
+    plan = ChangePlan(
+        operation="remove_entity",
+        entity_type=entity_type,
+        entity_id=entity_id,
+        customer_id=customer_id,
+        changes={"action": "REMOVE"},
+    )
+    store_plan(plan)
+    return plan.to_preview()
+
+
+def draft_campaign(
+    config: AdLoopConfig,
+    *,
+    customer_id: str = "",
+    campaign_name: str = "",
+    daily_budget: float = 0,
+    bidding_strategy: str = "",
+    target_cpa: float = 0,
+    target_roas: float = 0,
+    channel_type: str = "SEARCH",
+    ad_group_name: str = "",
+    keywords: list[dict] | None = None,
+) -> dict:
+    """Draft a full campaign structure — returns preview, does NOT execute.
+
+    Creates: CampaignBudget + Campaign (PAUSED) + AdGroup + optional Keywords.
+    Ads are NOT included — use draft_responsive_search_ad separately after the
+    campaign exists.
+    """
+    from adloop.safety.guards import (
+        SafetyViolation,
+        check_blocked_operation,
+        check_budget_cap,
+    )
+    from adloop.safety.preview import ChangePlan, store_plan
+
+    try:
+        check_blocked_operation("create_campaign", config.safety)
+    except SafetyViolation as e:
+        return {"error": str(e)}
+
+    errors, warnings = _validate_campaign(
+        config,
+        campaign_name=campaign_name,
+        daily_budget=daily_budget,
+        bidding_strategy=bidding_strategy,
+        target_cpa=target_cpa,
+        target_roas=target_roas,
+        channel_type=channel_type,
+        keywords=keywords,
+    )
+    if errors:
+        return {"error": "Validation failed", "details": errors}
+
+    try:
+        check_budget_cap(daily_budget, config.safety)
+    except SafetyViolation as e:
+        return {"error": str(e)}
+
+    plan = ChangePlan(
+        operation="create_campaign",
+        entity_type="campaign",
+        customer_id=customer_id,
+        changes={
+            "campaign_name": campaign_name,
+            "daily_budget": daily_budget,
+            "bidding_strategy": bidding_strategy.upper(),
+            "target_cpa": target_cpa if target_cpa else None,
+            "target_roas": target_roas if target_roas else None,
+            "channel_type": channel_type.upper(),
+            "ad_group_name": ad_group_name or campaign_name,
+            "keywords": keywords,
+        },
+    )
+    store_plan(plan)
+    preview = plan.to_preview()
+    if warnings:
+        preview["warnings"] = warnings
+    return preview
+
+
+# ---------------------------------------------------------------------------
+# confirm_and_apply — the only function that actually mutates Google Ads
+# ---------------------------------------------------------------------------
+
+
+def confirm_and_apply(
+    config: AdLoopConfig,
+    *,
+    plan_id: str = "",
+    dry_run: bool = True,
+) -> dict:
+    """Execute a previously previewed change.
+
+    Defaults to dry_run=True. The caller must explicitly pass dry_run=False
+    to make real changes.
+    """
+    from adloop.safety.audit import log_mutation
+    from adloop.safety.preview import get_plan, remove_plan
+
+    plan = get_plan(plan_id)
+    if plan is None:
+        return {
+            "error": f"No pending plan found with id '{plan_id}'. "
+            "Plans expire when the MCP server restarts.",
+        }
+
+    if config.safety.require_dry_run:
+        dry_run = True
+
+    if dry_run:
+        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=True,
+            result="dry_run_success",
+        )
+        return {
+            "status": "DRY_RUN_SUCCESS",
+            "plan_id": plan.plan_id,
+            "operation": plan.operation,
+            "changes": plan.changes,
+            "message": (
+                "Dry run completed — no changes were made to your Google Ads account. "
+                "To apply for real, call confirm_and_apply again with dry_run=false."
+            ),
+        }
+
+    try:
+        result = _execute_plan(config, plan)
+    except Exception as e:
+        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="error",
+            error=str(e),
+        )
+        return {"error": str(e), "plan_id": plan.plan_id}
+
+    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="success",
+    )
+    remove_plan(plan.plan_id)
+
+    return {
+        "status": "APPLIED",
+        "plan_id": plan.plan_id,
+        "operation": plan.operation,
+        "result": result,
+    }
+
+
+# ---------------------------------------------------------------------------
+# Internal validation helpers
+# ---------------------------------------------------------------------------
+
+_VALID_MATCH_TYPES = {"EXACT", "PHRASE", "BROAD"}
+_VALID_ENTITY_TYPES = {"campaign", "ad_group", "ad", "keyword"}
+_REMOVABLE_ENTITY_TYPES = _VALID_ENTITY_TYPES | {"negative_keyword"}
+
+_SMART_BIDDING_STRATEGIES = {
+    "MAXIMIZE_CONVERSIONS",
+    "MAXIMIZE_CONVERSION_VALUE",
+    "TARGET_CPA",
+    "TARGET_ROAS",
+}
+
+
+def _check_broad_match_safety(
+    config: AdLoopConfig,
+    customer_id: str,
+    ad_group_id: str,
+    keywords: list[dict],
+) -> list[str]:
+    """Warn if BROAD match keywords are being added to a non-Smart Bidding campaign."""
+    has_broad = any(
+        kw.get("match_type", "").upper() == "BROAD" for kw in keywords
+    )
+    if not has_broad:
+        return []
+
+    try:
+        from adloop.ads.gaql import execute_query
+
+        query = f"""
+            SELECT campaign.bidding_strategy_type, campaign.name
+            FROM ad_group
+            WHERE ad_group.id = {ad_group_id}
+        """
+        rows = execute_query(config, customer_id, query)
+        if not rows:
+            return []
+
+        bidding = rows[0].get("campaign.bidding_strategy_type", "")
+        campaign_name = rows[0].get("campaign.name", "")
+
+        if bidding not in _SMART_BIDDING_STRATEGIES:
+            return [
+                f"DANGEROUS: Adding BROAD match keywords to campaign "
+                f"'{campaign_name}' which uses {bidding} bidding. "
+                f"Broad Match without Smart Bidding (tCPA/tROAS/Maximize Conversions) "
+                f"leads to irrelevant matches and wasted budget. "
+                f"Use PHRASE or EXACT match instead, or switch the campaign "
+                f"to Smart Bidding first."
+            ]
+    except Exception:
+        pass
+
+    return []
+
+
+def _validate_rsa(
+    ad_group_id: str,
+    headlines: list[str],
+    descriptions: list[str],
+    final_url: str,
+) -> list[str]:
+    errors = []
+    if not ad_group_id:
+        errors.append("ad_group_id is required")
+    if not final_url:
+        errors.append("final_url is required")
+    if len(headlines) < 3:
+        errors.append(f"Need at least 3 headlines, got {len(headlines)}")
+    if len(headlines) > 15:
+        errors.append(f"Maximum 15 headlines, got {len(headlines)}")
+    if len(descriptions) < 2:
+        errors.append(f"Need at least 2 descriptions, got {len(descriptions)}")
+    if len(descriptions) > 4:
+        errors.append(f"Maximum 4 descriptions, got {len(descriptions)}")
+    for i, h in enumerate(headlines):
+        if len(h) > 30:
+            errors.append(f"Headline {i + 1} exceeds 30 chars ({len(h)}): '{h}'")
+    for i, d in enumerate(descriptions):
+        if len(d) > 90:
+            errors.append(f"Description {i + 1} exceeds 90 chars ({len(d)}): '{d}'")
+    return errors
+
+
+_VALID_BIDDING_STRATEGIES = {
+    "MAXIMIZE_CONVERSIONS",
+    "MAXIMIZE_CONVERSION_VALUE",
+    "TARGET_CPA",
+    "TARGET_ROAS",
+    "TARGET_SPEND",
+    "MANUAL_CPC",
+}
+
+_VALID_CHANNEL_TYPES = {"SEARCH", "DISPLAY", "SHOPPING", "VIDEO", "PERFORMANCE_MAX"}
+
+
+def _validate_campaign(
+    config: AdLoopConfig,
+    *,
+    campaign_name: str,
+    daily_budget: float,
+    bidding_strategy: str,
+    target_cpa: float,
+    target_roas: float,
+    channel_type: str,
+    keywords: list[dict] | None,
+) -> tuple[list[str], list[str]]:
+    """Validate campaign draft inputs. Returns (errors, warnings)."""
+    errors = []
+    warnings = []
+
+    if not campaign_name or not campaign_name.strip():
+        errors.append("campaign_name is required")
+    if daily_budget <= 0:
+        errors.append("daily_budget must be greater than 0")
+
+    bs = bidding_strategy.upper()
+    if bs not in _VALID_BIDDING_STRATEGIES:
+        errors.append(
+            f"bidding_strategy must be one of {sorted(_VALID_BIDDING_STRATEGIES)}, "
+            f"got '{bidding_strategy}'"
+        )
+    if bs == "TARGET_CPA" and not target_cpa:
+        errors.append("target_cpa is required when bidding_strategy is TARGET_CPA")
+    if bs == "TARGET_ROAS" and not target_roas:
+        errors.append("target_roas is required when bidding_strategy is TARGET_ROAS")
+
+    ct = channel_type.upper()
+    if ct not in _VALID_CHANNEL_TYPES:
+        errors.append(
+            f"channel_type must be one of {sorted(_VALID_CHANNEL_TYPES)}, "
+            f"got '{channel_type}'"
+        )
+
+    if keywords:
+        has_broad = any(
+            kw.get("match_type", "").upper() == "BROAD" for kw in keywords
+        )
+        if has_broad and bs not in _SMART_BIDDING_STRATEGIES:
+            errors.append(
+                f"BROAD match keywords require Smart Bidding "
+                f"(tCPA/tROAS/Maximize Conversions). "
+                f"'{bidding_strategy}' is not a Smart Bidding strategy. "
+                f"Use PHRASE or EXACT match instead."
+            )
+        for i, kw in enumerate(keywords):
+            if not kw.get("text"):
+                errors.append(f"Keyword {i + 1} has no text")
+            mt = kw.get("match_type", "").upper()
+            if mt not in _VALID_MATCH_TYPES:
+                errors.append(
+                    f"Keyword {i + 1} has invalid match_type '{mt}' "
+                    "(must be EXACT, PHRASE, or BROAD)"
+                )
+
+    if target_cpa > 0 and daily_budget < 5 * target_cpa:
+        warnings.append(
+            f"Daily budget €{daily_budget:.2f} is less than 5x target CPA "
+            f"€{target_cpa:.2f}. Google recommends at least 5x target CPA "
+            f"(€{5 * target_cpa:.2f}/day) for sufficient learning data."
+        )
+
+    if bs == "MANUAL_CPC":
+        warnings.append(
+            "MANUAL_CPC bidding requires constant monitoring. Consider using "
+            "MAXIMIZE_CONVERSIONS or TARGET_CPA for automated optimization."
+        )
+
+    return errors, warnings
+
+
+def _validate_keywords(ad_group_id: str, keywords: list[dict]) -> list[str]:
+    errors = []
+    if not ad_group_id:
+        errors.append("ad_group_id is required")
+    if not keywords:
+        errors.append("At least one keyword is required")
+    for i, kw in enumerate(keywords):
+        if not kw.get("text"):
+            errors.append(f"Keyword {i + 1} has no text")
+        mt = kw.get("match_type", "").upper()
+        if mt not in _VALID_MATCH_TYPES:
+            errors.append(
+                f"Keyword {i + 1} has invalid match_type '{mt}' "
+                "(must be EXACT, PHRASE, or BROAD)"
+            )
+    return errors
+
+
+def _draft_status_change(
+    config: AdLoopConfig,
+    operation: str,
+    customer_id: str,
+    entity_type: str,
+    entity_id: str,
+    target_status: str,
+) -> dict:
+    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)}
+
+    errors = []
+    if entity_type not in _VALID_ENTITY_TYPES:
+        errors.append(
+            f"entity_type must be one of {_VALID_ENTITY_TYPES}, got '{entity_type}'"
+        )
+    if not entity_id:
+        errors.append("entity_id is required")
+    if errors:
+        return {"error": "Validation failed", "details": errors}
+
+    plan = ChangePlan(
+        operation=operation,
+        entity_type=entity_type,
+        entity_id=entity_id,
+        customer_id=customer_id,
+        changes={"target_status": target_status},
+    )
+    store_plan(plan)
+    return plan.to_preview()
+
+
+# ---------------------------------------------------------------------------
+# Execution — actual Google Ads API mutate calls
+# ---------------------------------------------------------------------------
+
+
+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
+
+    client = get_ads_client(config)
+    cid = normalize_customer_id(plan.customer_id)
+
+    dispatch = {
+        "create_campaign": _apply_create_campaign,
+        "create_responsive_search_ad": _apply_create_rsa,
+        "add_keywords": _apply_add_keywords,
+        "add_negative_keywords": _apply_add_negative_keywords,
+        "pause_entity": _apply_status_change,
+        "enable_entity": _apply_status_change,
+        "remove_entity": _apply_remove,
+    }
+
+    handler = dispatch.get(plan.operation)
+    if handler is None:
+        raise ValueError(f"Unknown operation: {plan.operation}")
+
+    if plan.operation in ("pause_entity", "enable_entity"):
+        return handler(
+            client,
+            cid,
+            plan.entity_type,
+            plan.entity_id,
+            plan.changes["target_status"],
+        )
+
+    if plan.operation == "remove_entity":
+        return handler(client, cid, plan.entity_type, plan.entity_id)
+
+    return handler(client, cid, plan.changes)
+
+
+def _apply_create_campaign(client: object, cid: str, changes: dict) -> dict:
+    """Create campaign + budget + ad group + optional keywords atomically."""
+    service = client.get_service("GoogleAdsService")
+    campaign_service = client.get_service("CampaignService")
+    budget_service = client.get_service("CampaignBudgetService")
+    ad_group_service = client.get_service("AdGroupService")
+
+    operations = []
+
+    # 1. CampaignBudget (temp ID: -1)
+    budget_op = client.get_type("MutateOperation")
+    budget = budget_op.campaign_budget_operation.create
+    budget.resource_name = budget_service.campaign_budget_path(cid, "-1")
+    budget.name = f"Budget - {changes['campaign_name']}"
+    budget.amount_micros = int(changes["daily_budget"] * 1_000_000)
+    budget.delivery_method = client.enums.BudgetDeliveryMethodEnum.STANDARD
+    budget.explicitly_shared = False
+    operations.append(budget_op)
+
+    # 2. Campaign (temp ID: -2, references budget -1)
+    campaign_op = client.get_type("MutateOperation")
+    campaign = campaign_op.campaign_operation.create
+    campaign.resource_name = campaign_service.campaign_path(cid, "-2")
+    campaign.name = changes["campaign_name"]
+    campaign.campaign_budget = budget_service.campaign_budget_path(cid, "-1")
+    campaign.status = client.enums.CampaignStatusEnum.PAUSED
+
+    channel = changes.get("channel_type", "SEARCH")
+    campaign.advertising_channel_type = getattr(
+        client.enums.AdvertisingChannelTypeEnum, channel
+    )
+
+    bs = changes["bidding_strategy"]
+    if bs == "MAXIMIZE_CONVERSIONS":
+        campaign.maximize_conversions.target_cpa_micros = 0
+        if changes.get("target_cpa"):
+            campaign.maximize_conversions.target_cpa_micros = int(
+                changes["target_cpa"] * 1_000_000
+            )
+    elif bs == "TARGET_CPA":
+        campaign.maximize_conversions.target_cpa_micros = int(
+            changes["target_cpa"] * 1_000_000
+        )
+    elif bs == "MAXIMIZE_CONVERSION_VALUE":
+        campaign.maximize_conversion_value.target_roas = 0
+        if changes.get("target_roas"):
+            campaign.maximize_conversion_value.target_roas = changes["target_roas"]
+    elif bs == "TARGET_ROAS":
+        campaign.maximize_conversion_value.target_roas = changes["target_roas"]
+    elif bs == "TARGET_SPEND":
+        campaign.target_spend.target_spend_micros = 0
+    elif bs == "MANUAL_CPC":
+        campaign.manual_cpc.enhanced_cpc_enabled = False
+
+    campaign.network_settings.target_google_search = True
+    campaign.network_settings.target_search_network = False
+    campaign.network_settings.target_content_network = False
+
+    operations.append(campaign_op)
+
+    # 3. AdGroup (temp ID: -3, references campaign -2)
+    ag_op = client.get_type("MutateOperation")
+    ad_group = ag_op.ad_group_operation.create
+    ad_group.resource_name = ad_group_service.ad_group_path(cid, "-3")
+    ad_group.name = changes.get("ad_group_name", changes["campaign_name"])
+    ad_group.campaign = campaign_service.campaign_path(cid, "-2")
+    ad_group.status = client.enums.AdGroupStatusEnum.ENABLED
+    ad_group.type_ = client.enums.AdGroupTypeEnum.SEARCH_STANDARD
+    operations.append(ag_op)
+
+    # 4. Keywords (reference ad_group -3)
+    kw_list = changes.get("keywords") or []
+    for kw in kw_list:
+        kw_op = client.get_type("MutateOperation")
+        criterion = kw_op.ad_group_criterion_operation.create
+        criterion.ad_group = ad_group_service.ad_group_path(cid, "-3")
+        criterion.keyword.text = kw["text"]
+        criterion.keyword.match_type = getattr(
+            client.enums.KeywordMatchTypeEnum, kw["match_type"].upper()
+        )
+        operations.append(kw_op)
+
+    response = service.mutate(customer_id=cid, mutate_operations=operations)
+
+    resource_names = [r.mutate_operation_response for r in response.mutate_operation_responses]
+    results = {}
+    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))
+            if i == 0:
+                results["campaign_budget"] = resource
+            elif i == 1:
+                results["campaign"] = resource
+            elif i == 2:
+                results["ad_group"] = resource
+            else:
+                results.setdefault("keywords", []).append(resource)
+
+    return results
+
+
+def _apply_create_rsa(client: object, cid: str, changes: dict) -> dict:
+    service = client.get_service("AdGroupAdService")
+    operation = client.get_type("AdGroupAdOperation")
+    ad_group_ad = operation.create
+
+    ad_group_ad.ad_group = client.get_service("AdGroupService").ad_group_path(
+        cid, changes["ad_group_id"]
+    )
+    # Create as PAUSED for safety — user can enable separately
+    ad_group_ad.status = client.enums.AdGroupAdStatusEnum.PAUSED
+
+    ad = ad_group_ad.ad
+    ad.final_urls.append(changes["final_url"])
+
+    for text in changes["headlines"]:
+        asset = client.get_type("AdTextAsset")
+        asset.text = text
+        ad.responsive_search_ad.headlines.append(asset)
+
+    for text in changes["descriptions"]:
+        asset = client.get_type("AdTextAsset")
+        asset.text = text
+        ad.responsive_search_ad.descriptions.append(asset)
+
+    if changes.get("path1"):
+        ad.responsive_search_ad.path1 = changes["path1"]
+    if changes.get("path2"):
+        ad.responsive_search_ad.path2 = changes["path2"]
+
+    response = service.mutate_ad_group_ads(
+        customer_id=cid, operations=[operation]
+    )
+    return {"resource_name": response.results[0].resource_name}
+
+
+def _apply_add_keywords(client: object, cid: str, changes: dict) -> dict:
+    service = client.get_service("AdGroupCriterionService")
+    ad_group_path = client.get_service("AdGroupService").ad_group_path(
+        cid, changes["ad_group_id"]
+    )
+
+    operations = []
+    for kw in changes["keywords"]:
+        operation = client.get_type("AdGroupCriterionOperation")
+        criterion = operation.create
+        criterion.ad_group = ad_group_path
+        criterion.keyword.text = kw["text"]
+        criterion.keyword.match_type = getattr(
+            client.enums.KeywordMatchTypeEnum, kw["match_type"].upper()
+        )
+        operations.append(operation)
+
+    response = service.mutate_ad_group_criteria(
+        customer_id=cid, operations=operations
+    )
+    return {"resource_names": [r.resource_name for r in response.results]}
+
+
+def _apply_add_negative_keywords(client: object, cid: str, changes: dict) -> dict:
+    service = client.get_service("CampaignCriterionService")
+    campaign_path = client.get_service("CampaignService").campaign_path(
+        cid, changes["campaign_id"]
+    )
+
+    operations = []
+    for kw_text in changes["keywords"]:
+        operation = client.get_type("CampaignCriterionOperation")
+        criterion = operation.create
+        criterion.campaign = campaign_path
+        criterion.negative = True
+        criterion.keyword.text = kw_text
+        criterion.keyword.match_type = getattr(
+            client.enums.KeywordMatchTypeEnum, changes["match_type"]
+        )
+        operations.append(operation)
+
+    response = service.mutate_campaign_criteria(
+        customer_id=cid, operations=operations
+    )
+    return {"resource_names": [r.resource_name for r in response.results]}
+
+
+def _apply_remove(
+    client: object,
+    cid: str,
+    entity_type: str,
+    entity_id: str,
+) -> dict:
+    """Remove an entity via the REMOVE mutate operation (irreversible)."""
+    if entity_type == "campaign":
+        service = client.get_service("CampaignService")
+        operation = client.get_type("CampaignOperation")
+        operation.remove = service.campaign_path(cid, entity_id)
+        response = service.mutate_campaigns(
+            customer_id=cid, operations=[operation]
+        )
+
+    elif entity_type == "ad_group":
+        service = client.get_service("AdGroupService")
+        operation = client.get_type("AdGroupOperation")
+        operation.remove = service.ad_group_path(cid, entity_id)
+        response = service.mutate_ad_groups(
+            customer_id=cid, operations=[operation]
+        )
+
+    elif entity_type == "ad":
+        service = client.get_service("AdGroupAdService")
+        operation = client.get_type("AdGroupAdOperation")
+        operation.remove = f"customers/{cid}/adGroupAds/{entity_id}"
+        response = service.mutate_ad_group_ads(
+            customer_id=cid, operations=[operation]
+        )
+
+    elif entity_type == "keyword":
+        service = client.get_service("AdGroupCriterionService")
+        operation = client.get_type("AdGroupCriterionOperation")
+        operation.remove = f"customers/{cid}/adGroupCriteria/{entity_id}"
+        response = service.mutate_ad_group_criteria(
+            customer_id=cid, operations=[operation]
+        )
+
+    elif entity_type == "negative_keyword":
+        service = client.get_service("CampaignCriterionService")
+        operation = client.get_type("CampaignCriterionOperation")
+        operation.remove = f"customers/{cid}/campaignCriteria/{entity_id}"
+        response = service.mutate_campaign_criteria(
+            customer_id=cid, operations=[operation]
+        )
+
+    else:
+        raise ValueError(f"Cannot remove entity_type: {entity_type}")
+
+    return {"resource_name": response.results[0].resource_name}
+
+
+def _apply_status_change(
+    client: object,
+    cid: str,
+    entity_type: str,
+    entity_id: str,
+    status: str,
+) -> dict:
+    """Update the status of a campaign, ad group, ad, or keyword."""
+    if entity_type == "campaign":
+        service = client.get_service("CampaignService")
+        operation = client.get_type("CampaignOperation")
+        entity = operation.update
+        entity.resource_name = service.campaign_path(cid, entity_id)
+        entity.status = getattr(client.enums.CampaignStatusEnum, status)
+        mutate = service.mutate_campaigns
+
+    elif entity_type == "ad_group":
+        service = client.get_service("AdGroupService")
+        operation = client.get_type("AdGroupOperation")
+        entity = operation.update
+        entity.resource_name = service.ad_group_path(cid, entity_id)
+        entity.status = getattr(client.enums.AdGroupStatusEnum, status)
+        mutate = service.mutate_ad_groups
+
+    elif entity_type == "ad":
+        service = client.get_service("AdGroupAdService")
+        operation = client.get_type("AdGroupAdOperation")
+        entity = operation.update
+        entity.resource_name = f"customers/{cid}/adGroupAds/{entity_id}"
+        entity.status = getattr(client.enums.AdGroupAdStatusEnum, status)
+        mutate = service.mutate_ad_group_ads
+
+    elif entity_type == "keyword":
+        service = client.get_service("AdGroupCriterionService")
+        operation = client.get_type("AdGroupCriterionOperation")
+        entity = operation.update
+        entity.resource_name = f"customers/{cid}/adGroupCriteria/{entity_id}"
+        entity.status = getattr(
+            client.enums.AdGroupCriterionStatusEnum, status
+        )
+        mutate = service.mutate_ad_group_criteria
+
+    else:
+        raise ValueError(f"Unknown entity_type: {entity_type}")
+
+    # Build field mask for the status field only
+    field_mask = client.get_type("FieldMask")
+    field_mask.paths.append("status")
+    client.copy_from(operation.update_mask, field_mask)
+
+    response = mutate(customer_id=cid, operations=[operation])
+    return {"resource_name": response.results[0].resource_name}