adloop 0.5.2__tar.gz → 0.6.0__tar.gz

{adloop-0.5.2 → adloop-0.6.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.3
 Name: adloop
-Version: 0.5.2
+Version: 0.6.0
 Summary: Stop switching between Google Ads, GA4, and your code editor to figure out why conversions dropped.
 Keywords: mcp,google-ads,google-analytics,ga4,cursor,marketing
 Author: Daniel Klose

{adloop-0.5.2 → adloop-0.6.0}/pyproject.toml

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

{adloop-0.5.2 → adloop-0.6.0}/src/adloop/__init__.py

@@ -2,7 +2,7 @@
 
 import sys
 
-__version__ = "0.5.2"
+__version__ = "0.6.0"
 
 
 def main() -> None:

{adloop-0.5.2 → adloop-0.6.0}/src/adloop/ads/read.py

@@ -267,7 +267,8 @@ def get_negative_keyword_list_keywords(
         return {"error": "shared_set_id must be a numeric ID"}
 
     query = f"""
-        SELECT shared_criterion.keyword.text,
+        SELECT shared_criterion.criterion_id,
+               shared_criterion.keyword.text,
                shared_criterion.keyword.match_type,
                shared_criterion.type,
                shared_set.id, shared_set.name
@@ -277,6 +278,11 @@ def get_negative_keyword_list_keywords(
     """
 
     rows = execute_query(config, customer_id, query)
+    for row in rows:
+        ssid = row.get("shared_set.id")
+        crit_id = row.get("shared_criterion.criterion_id")
+        if ssid and crit_id:
+            row["resource_id"] = f"{ssid}~{crit_id}"
     return {
         "keywords": rows,
         "total_keywords": len(rows),

{adloop-0.5.2 → adloop-0.6.0}/src/adloop/ads/write.py

@@ -396,6 +396,77 @@ def propose_negative_keyword_list(
     return plan.to_preview()
 
 
+def add_to_negative_keyword_list(
+    config: AdLoopConfig,
+    *,
+    customer_id: str = "",
+    shared_set_id: str = "",
+    keywords: list[str] | None = None,
+    match_type: str = "EXACT",
+) -> dict:
+    """Draft adding keywords to an existing shared negative keyword list — returns PREVIEW.
+
+    Unlike ``propose_negative_keyword_list`` (which creates a NEW list), this
+    appends keywords to an existing SharedSet identified by ``shared_set_id``.
+    Use ``get_negative_keyword_lists`` to find the list's ID. Call
+    ``confirm_and_apply`` with the returned plan_id to execute.
+    """
+    from adloop.safety.guards import SafetyViolation, check_blocked_operation
+    from adloop.safety.preview import ChangePlan, store_plan
+
+    try:
+        check_blocked_operation("add_to_negative_keyword_list", config.safety)
+    except SafetyViolation as e:
+        return {"error": str(e)}
+
+    keywords = keywords or []
+    match_type = match_type.upper()
+
+    errors = []
+    if not shared_set_id:
+        errors.append("shared_set_id is required")
+    elif not str(shared_set_id).isdigit():
+        errors.append("shared_set_id must be a numeric ID (from get_negative_keyword_lists)")
+    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}
+
+    seen: set[str] = set()
+    deduped: list[str] = []
+    for kw in keywords:
+        text = kw.strip()
+        if not text:
+            continue
+        key = text.lower()
+        if key in seen:
+            continue
+        seen.add(key)
+        deduped.append(text)
+
+    if not deduped:
+        return {
+            "error": "Validation failed",
+            "details": ["At least one non-empty keyword is required"],
+        }
+
+    plan = ChangePlan(
+        operation="add_to_negative_keyword_list",
+        entity_type="negative_keyword_list",
+        entity_id=str(shared_set_id),
+        customer_id=customer_id,
+        changes={
+            "shared_set_id": str(shared_set_id),
+            "keywords": deduped,
+            "match_type": match_type,
+        },
+    )
+    store_plan(plan)
+    return plan.to_preview()
+
+
 def update_ad_group(
     config: AdLoopConfig,
     *,
@@ -484,11 +555,26 @@ def remove_entity(
     entity_type: str = "",
     entity_id: str = "",
 ) -> dict:
-    """Draft removing an entity (keyword, negative_keyword, ad, ad_group, campaign).
+    """Draft removing an entity — returns preview.
+
+    Supported ``entity_type`` values: ``campaign``, ``ad_group``, ``ad``,
+    ``keyword``, ``negative_keyword``, ``shared_criterion``, ``campaign_asset``,
+    ``asset``, ``customer_asset``.
+
+    Composite ``entity_id`` formats:
+
+    - ``keyword``: ``adGroupId~criterionId``
+    - ``negative_keyword``: ``campaignId~criterionId`` (use the ``resource_id``
+      field from ``get_negative_keywords``)
+    - ``shared_criterion``: ``sharedSetId~criterionId`` (use the ``resource_id``
+      field from ``get_negative_keyword_list_keywords``)
+    - ``campaign_asset``: ``campaignId~assetId~fieldType``
+    - ``customer_asset``: ``assetId~fieldType``
+    - ``asset``: bare asset ID
 
     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.
+    Prefer ``pause_entity`` unless the user explicitly wants permanent removal.
+    Call ``confirm_and_apply`` with the returned plan_id to execute.
     """
     from adloop.safety.guards import SafetyViolation, check_blocked_operation
     from adloop.safety.preview import ChangePlan, store_plan
@@ -1167,6 +1253,7 @@ _VALID_MATCH_TYPES = {"EXACT", "PHRASE", "BROAD"}
 _VALID_ENTITY_TYPES = {"campaign", "ad_group", "ad", "keyword"}
 _REMOVABLE_ENTITY_TYPES = _VALID_ENTITY_TYPES | {
     "negative_keyword", "campaign_asset", "asset", "customer_asset",
+    "shared_criterion",
 }
 
 _SMART_BIDDING_STRATEGIES = {
@@ -1726,6 +1813,7 @@ def _execute_plan(config: AdLoopConfig, plan: object) -> dict:
         "add_keywords": _apply_add_keywords,
         "add_negative_keywords": _apply_add_negative_keywords,
         "create_negative_keyword_list": _apply_create_negative_keyword_list,
+        "add_to_negative_keyword_list": _apply_add_to_negative_keyword_list,
         "pause_entity": _apply_status_change,
         "enable_entity": _apply_status_change,
         "remove_entity": _apply_remove,
@@ -2282,6 +2370,19 @@ def _apply_remove(
             customer_id=cid, operations=[operation]
         )
 
+    elif entity_type == "shared_criterion":
+        if "~" not in entity_id:
+            raise ValueError(
+                f"shared_criterion entity_id must be "
+                f"'sharedSetId~criterionId', got '{entity_id}'"
+            )
+        service = client.get_service("SharedCriterionService")
+        operation = client.get_type("SharedCriterionOperation")
+        operation.remove = f"customers/{cid}/sharedCriteria/{entity_id}"
+        response = service.mutate_shared_criteria(
+            customer_id=cid, operations=[operation]
+        )
+
     elif entity_type == "campaign_asset":
         parts = entity_id.split("~")
         if len(parts) != 3:
@@ -2599,3 +2700,34 @@ def _apply_create_negative_keyword_list(
         "campaign_shared_set_resource": css_response.results[0].resource_name,
         "keyword_count": len(changes["keywords"]),
     }
+
+
+def _apply_add_to_negative_keyword_list(
+    client: object, cid: str, changes: dict
+) -> dict:
+    """Append keywords to an existing shared negative keyword list."""
+    shared_set_service = client.get_service("SharedSetService")
+    shared_set_resource = shared_set_service.shared_set_path(
+        cid, changes["shared_set_id"]
+    )
+
+    sc_service = client.get_service("SharedCriterionService")
+    operations = []
+    for kw_text in changes["keywords"]:
+        op = client.get_type("SharedCriterionOperation")
+        criterion = op.create
+        criterion.shared_set = shared_set_resource
+        criterion.keyword.text = kw_text
+        criterion.keyword.match_type = getattr(
+            client.enums.KeywordMatchTypeEnum, changes["match_type"]
+        )
+        operations.append(op)
+
+    response = sc_service.mutate_shared_criteria(
+        customer_id=cid, operations=operations
+    )
+    return {
+        "shared_set_resource": shared_set_resource,
+        "resource_names": [r.resource_name for r in response.results],
+        "keyword_count": len(response.results),
+    }

{adloop-0.5.2 → adloop-0.6.0}/src/adloop/server.py

@@ -979,6 +979,39 @@ def propose_negative_keyword_list(
     )
 
 
+@mcp.tool(annotations=_WRITE)
+@_safe
+def add_to_negative_keyword_list(
+    shared_set_id: str,
+    keywords: list[str],
+    customer_id: str = "",
+    match_type: str = "EXACT",
+) -> dict:
+    """Append keywords to an EXISTING shared negative keyword list — returns a PREVIEW.
+
+    Use this when a suitable list already exists and only needs more keywords
+    (instead of propose_negative_keyword_list, which creates a new list).
+    Always call get_negative_keyword_lists first to find the right shared_set_id
+    and get_negative_keyword_list_keywords to avoid duplicating existing terms.
+
+    shared_set_id: numeric ID from get_negative_keyword_lists (shared_set.id).
+    keywords: list of keyword strings to append (duplicates in the input list
+        are collapsed).
+    match_type: "EXACT", "PHRASE", or "BROAD"
+
+    Call confirm_and_apply with the returned plan_id to execute.
+    """
+    from adloop.ads.write import add_to_negative_keyword_list as _impl
+
+    return _impl(
+        _config,
+        customer_id=customer_id or _config.ads.customer_id,
+        shared_set_id=shared_set_id,
+        keywords=keywords,
+        match_type=match_type,
+    )
+
+
 @mcp.tool(annotations=_WRITE)
 @_safe
 def update_ad_group(
@@ -1119,11 +1152,13 @@ def remove_entity(
     """Draft REMOVING an entity — returns a PREVIEW. This is IRREVERSIBLE.
 
     entity_type: "campaign", "ad_group", "ad", "keyword", "negative_keyword",
-                 "campaign_asset", "asset", or "customer_asset"
+                 "shared_criterion", "campaign_asset", "asset", or "customer_asset"
     entity_id: The resource ID.
                For keywords: "adGroupId~criterionId"
                For negative_keywords: "campaignId~criterionId"
                    (use the resource_id field from get_negative_keywords)
+               For shared_criterion: "sharedSetId~criterionId"
+                   (use the resource_id field from get_negative_keyword_list_keywords)
                For campaign_asset: "campaignId~assetId~fieldType"
                For asset: simple asset ID
                For customer_asset: "assetId~fieldType"