gadschain 0.1.0__tar.gz

gadschain-0.1.0/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 SnipMCP
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

gadschain-0.1.0/PKG-INFO

@@ -0,0 +1,141 @@
+Metadata-Version: 2.4
+Name: gadschain
+Version: 0.1.0
+Summary: Google Ads MCP server — clean, agent-friendly tools over the Google Ads API.
+License: MIT
+Project-URL: Homepage, https://github.com/SnipMCP/gadschain
+Project-URL: Repository, https://github.com/SnipMCP/gadschain
+Project-URL: Issues, https://github.com/SnipMCP/gadschain/issues
+Keywords: mcp,google-ads,ads,marketing,ai-agents
+Classifier: Development Status :: 3 - Alpha
+Classifier: Intended Audience :: Developers
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Operating System :: OS Independent
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Topic :: Office/Business
+Classifier: Topic :: Software Development :: Libraries
+Requires-Python: >=3.11
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Requires-Dist: fastmcp>=0.1.0
+Requires-Dist: google-ads<32.0.0,>=31.0.0
+Requires-Dist: pydantic>=2.0.0
+Requires-Dist: python-dotenv>=1.0.0
+Provides-Extra: dev
+Requires-Dist: pytest>=8.0.0; extra == "dev"
+Requires-Dist: pytest-asyncio>=0.23.0; extra == "dev"
+Dynamic: license-file
+
+# GadsChain
+
+The AI layer between your Google Ads account and your marketing decisions.
+
+**Battle-tested.** Six tools cover the daily-ops loop — campaign listing, search-term review, budget tuning, pause/enable, and negative-keyword grooming. All responses are strict Pydantic models. No raw protobuf reaches the agent.
+
+## ☁️ Moving to production?
+
+The open-source server runs locally with your own API keys.
+For hosted infrastructure with multi-account failover, SLA guarantees,
+and webhook alerts — [join the managed cloud waitlist](https://snipmcp.com).
+
+## The Problem
+
+Raw Google Ads API returns thousands of rows. One bad campaign structure bleeds budget silently. GadsChain reads, sanitizes, and acts on your ad data before waste compounds.
+
+## Installation
+
+```bash
+git clone https://github.com/SnipMCP/gadschain.git
+cd gadschain
+pip install -e ".[dev]"
+cp .env.example .env
+```
+
+Or with Docker:
+
+```bash
+docker-compose up --build
+```
+
+## Configuration
+
+```env
+GOOGLE_ADS_DEVELOPER_TOKEN=your_developer_token_here
+GOOGLE_ADS_CLIENT_ID=your_oauth_client_id_here
+GOOGLE_ADS_CLIENT_SECRET=your_oauth_client_secret_here
+GOOGLE_ADS_REFRESH_TOKEN=your_refresh_token_here
+GOOGLE_ADS_LOGIN_CUSTOMER_ID=1234567890   # MCC (manager), digits only
+GOOGLE_ADS_CUSTOMER_ID=1234567890         # default operating account
+GOOGLE_ADS_API_VERSION=v24
+LOG_LEVEL=INFO
+```
+
+## Usage
+
+Three example prompts to send to Claude (or any MCP-compatible agent):
+
+1. `Use get_campaigns to show me which campaigns are bleeding budget this month`
+2. `Run get_search_terms for the last 30 days and tell me which queries are wasting spend`
+3. `Add "free", "cheap", "jobs" as negative keywords to campaign 12345`
+
+### Run it in two terminals
+
+```bash
+# Tab 1 — start the MCP server
+python -m gadschain.server
+```
+
+```bash
+# Tab 2 — call a tool from a Python shell or your MCP client
+# Tool signatures:
+#   get_campaigns(customer_id=None)
+#   get_search_terms(customer_id=None, days=30, campaign_id=None)
+#   update_budget(campaign_id, new_budget_dollars, customer_id=None)
+#   pause_campaign(campaign_id, customer_id=None)
+#   enable_campaign(campaign_id, customer_id=None)
+#   add_negative_keywords(campaign_id, keywords, match_type="BROAD", customer_id=None)
+```
+
+## How it works
+
+Three layers between raw Google Ads output and your model:
+
+```
+Google Ads API → [Fetch] → [Transform] → [Act] → MCP Tool → AI Agent
+                  GAQL      micros→$       safe
+                  queries   enum→str       mutations
+                            CTR→%          shared-budget guard
+```
+
+- **Fetch**: Targeted GAQL queries — only the columns the daily-ops loop actually needs. No `SELECT *`, no protobuf pagination footguns.
+- **Transform**: Currency micros divided to dollars, CTR scaled to percent, enums to human strings, every nested attribute lookup tolerates missing fields without crashing.
+- **Act**: Mutations route through guard rails — `REMOVED` blocked on status changes, shared budgets refused (`shared_budget_refused`), match types validated before any mutate call. The agent never gets an exception; it gets a structured `{"error": ..., "message": ...}` it can reason about.
+
+### Real numbers from a live Franka Pizzeria account (28-day window)
+
+```
+RAW GOOGLE ADS PAYLOAD          GADSCHAIN OUTPUT
+─────────────────────────────────────────────────
+Impressions:    3,389           Spend (28d):      $51.41
+Clicks:         163             Conversions:      3 ($17.14 each)
+CTR:            4.81%           Conv. rate:       1.84%
+Cost/click:     $0.32 avg       Surface:          Display Network waste
+                                                  identified on Fridays
+                                                  ($0.11 CPC vs $0.44 avg)
+```
+
+In one read of a real account, GadsChain surfaced **$51.41 spent over 28 days for 3 conversions at $17.14 each** — a 1.84% conversion rate hidden inside a 4.81% CTR that looks healthy on paper. The Display Network was the silent culprit, with Friday clicks averaging **$0.11 CPC vs the $0.44 search-side average** — cheap junk traffic inflating CTR while contributing nothing to conversions. The agent saw it because the transformed payload made channel attribution legible instead of buried in protobuf.
+
+## Roadmap
+
+- Managed cloud tier (hosted, multi-tenant, webhook alerts)
+- Phase 2: ChatGPT REST shim (FastAPI surface over the same six tools)
+- Bid-strategy tuning tools (target CPA, target ROAS)
+- Anomaly alerts on cost-per-conversion drift
+
+## Contributing
+
+PRs welcome. Run `pytest` before submitting.

gadschain-0.1.0/README.md

@@ -0,0 +1,110 @@
+# GadsChain
+
+The AI layer between your Google Ads account and your marketing decisions.
+
+**Battle-tested.** Six tools cover the daily-ops loop — campaign listing, search-term review, budget tuning, pause/enable, and negative-keyword grooming. All responses are strict Pydantic models. No raw protobuf reaches the agent.
+
+## ☁️ Moving to production?
+
+The open-source server runs locally with your own API keys.
+For hosted infrastructure with multi-account failover, SLA guarantees,
+and webhook alerts — [join the managed cloud waitlist](https://snipmcp.com).
+
+## The Problem
+
+Raw Google Ads API returns thousands of rows. One bad campaign structure bleeds budget silently. GadsChain reads, sanitizes, and acts on your ad data before waste compounds.
+
+## Installation
+
+```bash
+git clone https://github.com/SnipMCP/gadschain.git
+cd gadschain
+pip install -e ".[dev]"
+cp .env.example .env
+```
+
+Or with Docker:
+
+```bash
+docker-compose up --build
+```
+
+## Configuration
+
+```env
+GOOGLE_ADS_DEVELOPER_TOKEN=your_developer_token_here
+GOOGLE_ADS_CLIENT_ID=your_oauth_client_id_here
+GOOGLE_ADS_CLIENT_SECRET=your_oauth_client_secret_here
+GOOGLE_ADS_REFRESH_TOKEN=your_refresh_token_here
+GOOGLE_ADS_LOGIN_CUSTOMER_ID=1234567890   # MCC (manager), digits only
+GOOGLE_ADS_CUSTOMER_ID=1234567890         # default operating account
+GOOGLE_ADS_API_VERSION=v24
+LOG_LEVEL=INFO
+```
+
+## Usage
+
+Three example prompts to send to Claude (or any MCP-compatible agent):
+
+1. `Use get_campaigns to show me which campaigns are bleeding budget this month`
+2. `Run get_search_terms for the last 30 days and tell me which queries are wasting spend`
+3. `Add "free", "cheap", "jobs" as negative keywords to campaign 12345`
+
+### Run it in two terminals
+
+```bash
+# Tab 1 — start the MCP server
+python -m gadschain.server
+```
+
+```bash
+# Tab 2 — call a tool from a Python shell or your MCP client
+# Tool signatures:
+#   get_campaigns(customer_id=None)
+#   get_search_terms(customer_id=None, days=30, campaign_id=None)
+#   update_budget(campaign_id, new_budget_dollars, customer_id=None)
+#   pause_campaign(campaign_id, customer_id=None)
+#   enable_campaign(campaign_id, customer_id=None)
+#   add_negative_keywords(campaign_id, keywords, match_type="BROAD", customer_id=None)
+```
+
+## How it works
+
+Three layers between raw Google Ads output and your model:
+
+```
+Google Ads API → [Fetch] → [Transform] → [Act] → MCP Tool → AI Agent
+                  GAQL      micros→$       safe
+                  queries   enum→str       mutations
+                            CTR→%          shared-budget guard
+```
+
+- **Fetch**: Targeted GAQL queries — only the columns the daily-ops loop actually needs. No `SELECT *`, no protobuf pagination footguns.
+- **Transform**: Currency micros divided to dollars, CTR scaled to percent, enums to human strings, every nested attribute lookup tolerates missing fields without crashing.
+- **Act**: Mutations route through guard rails — `REMOVED` blocked on status changes, shared budgets refused (`shared_budget_refused`), match types validated before any mutate call. The agent never gets an exception; it gets a structured `{"error": ..., "message": ...}` it can reason about.
+
+### Real numbers from a live Franka Pizzeria account (28-day window)
+
+```
+RAW GOOGLE ADS PAYLOAD          GADSCHAIN OUTPUT
+─────────────────────────────────────────────────
+Impressions:    3,389           Spend (28d):      $51.41
+Clicks:         163             Conversions:      3 ($17.14 each)
+CTR:            4.81%           Conv. rate:       1.84%
+Cost/click:     $0.32 avg       Surface:          Display Network waste
+                                                  identified on Fridays
+                                                  ($0.11 CPC vs $0.44 avg)
+```
+
+In one read of a real account, GadsChain surfaced **$51.41 spent over 28 days for 3 conversions at $17.14 each** — a 1.84% conversion rate hidden inside a 4.81% CTR that looks healthy on paper. The Display Network was the silent culprit, with Friday clicks averaging **$0.11 CPC vs the $0.44 search-side average** — cheap junk traffic inflating CTR while contributing nothing to conversions. The agent saw it because the transformed payload made channel attribution legible instead of buried in protobuf.
+
+## Roadmap
+
+- Managed cloud tier (hosted, multi-tenant, webhook alerts)
+- Phase 2: ChatGPT REST shim (FastAPI surface over the same six tools)
+- Bid-strategy tuning tools (target CPA, target ROAS)
+- Anomaly alerts on cost-per-conversion drift
+
+## Contributing
+
+PRs welcome. Run `pytest` before submitting.

gadschain-0.1.0/pyproject.toml

@@ -0,0 +1,47 @@
+[build-system]
+requires = ["setuptools>=68"]
+build-backend = "setuptools.build_meta"
+
+[project]
+name = "gadschain"
+version = "0.1.0"
+description = "Google Ads MCP server — clean, agent-friendly tools over the Google Ads API."
+readme = "README.md"
+license = {text = "MIT"}
+requires-python = ">=3.11"
+keywords = ["mcp", "google-ads", "ads", "marketing", "ai-agents"]
+classifiers = [
+    "Development Status :: 3 - Alpha",
+    "Intended Audience :: Developers",
+    "License :: OSI Approved :: MIT License",
+    "Operating System :: OS Independent",
+    "Programming Language :: Python :: 3",
+    "Programming Language :: Python :: 3.11",
+    "Programming Language :: Python :: 3.12",
+    "Programming Language :: Python :: 3.13",
+    "Topic :: Office/Business",
+    "Topic :: Software Development :: Libraries",
+]
+dependencies = [
+    "fastmcp>=0.1.0",
+    "google-ads>=31.0.0,<32.0.0",
+    "pydantic>=2.0.0",
+    "python-dotenv>=1.0.0",
+]
+
+[project.optional-dependencies]
+dev = [
+    "pytest>=8.0.0",
+    "pytest-asyncio>=0.23.0",
+]
+
+[project.scripts]
+gadschain = "gadschain.server:main"
+
+[project.urls]
+Homepage = "https://github.com/SnipMCP/gadschain"
+Repository = "https://github.com/SnipMCP/gadschain"
+Issues = "https://github.com/SnipMCP/gadschain/issues"
+
+[tool.setuptools.packages.find]
+where = ["src"]

gadschain-0.1.0/setup.cfg

@@ -0,0 +1,4 @@
+[egg_info]
+tag_build = 
+tag_date = 0
+

gadschain-0.1.0/src/gadschain/__init__.py

@@ -0,0 +1 @@
+__version__ = "0.1.0"

gadschain-0.1.0/src/gadschain/clients/__init__.py

@@ -0,0 +1,4 @@
+from .base import BaseAdsClient, AdsClientError
+from .google_ads import GoogleAdsClientWrapper
+
+__all__ = ["BaseAdsClient", "AdsClientError", "GoogleAdsClientWrapper"]

gadschain-0.1.0/src/gadschain/clients/base.py

@@ -0,0 +1,42 @@
+from abc import ABC, abstractmethod
+from typing import Optional
+
+
+class AdsClientError(Exception):
+    def __init__(self, message: str, code: Optional[str] = None):
+        super().__init__(message)
+        self.code = code
+
+
+class BaseAdsClient(ABC):
+    name: str = "base"
+
+    @abstractmethod
+    def list_campaigns(self, customer_id: str) -> list[dict]:
+        ...
+
+    @abstractmethod
+    def list_search_terms(self, customer_id: str, days: int, campaign_id: Optional[str] = None) -> list[dict]:
+        ...
+
+    @abstractmethod
+    def get_campaign_budget(self, customer_id: str, campaign_id: str) -> dict:
+        ...
+
+    @abstractmethod
+    def update_campaign_budget(self, customer_id: str, campaign_id: str, daily_budget_usd: float) -> dict:
+        ...
+
+    @abstractmethod
+    def set_campaign_status(self, customer_id: str, campaign_id: str, status: str) -> dict:
+        ...
+
+    @abstractmethod
+    def add_negative_keywords(
+        self,
+        customer_id: str,
+        campaign_id: str,
+        keywords: list[str],
+        match_type: str = "BROAD",
+    ) -> dict:
+        ...

gadschain-0.1.0/src/gadschain/clients/google_ads.py

@@ -0,0 +1,302 @@
+import os
+from datetime import date, timedelta
+from typing import Optional
+
+from .base import BaseAdsClient, AdsClientError
+
+
+VALID_MATCH_TYPES = {"EXACT", "PHRASE", "BROAD"}
+MUTABLE_STATUSES = {"ENABLED", "PAUSED"}
+
+
+def _clean_customer_id(cid: str) -> str:
+    """Strip dashes and whitespace from a Google Ads customer ID."""
+    return (cid or "").replace("-", "").replace(" ", "")
+
+
+def _date_range(days: int) -> tuple[str, str]:
+    end = date.today()
+    start = end - timedelta(days=max(1, int(days)))
+    return start.isoformat(), end.isoformat()
+
+
+class GoogleAdsClientWrapper(BaseAdsClient):
+    """Wraps google.ads.googleads.client.GoogleAdsClient with lazy auth."""
+
+    name = "google_ads"
+
+    def __init__(
+        self,
+        developer_token: Optional[str] = None,
+        client_id: Optional[str] = None,
+        client_secret: Optional[str] = None,
+        refresh_token: Optional[str] = None,
+        login_customer_id: Optional[str] = None,
+        api_version: Optional[str] = None,
+    ):
+        self.developer_token = developer_token or os.getenv("GOOGLE_ADS_DEVELOPER_TOKEN", "")
+        self.client_id = client_id or os.getenv("GOOGLE_ADS_CLIENT_ID", "")
+        self.client_secret = client_secret or os.getenv("GOOGLE_ADS_CLIENT_SECRET", "")
+        self.refresh_token = refresh_token or os.getenv("GOOGLE_ADS_REFRESH_TOKEN", "")
+        self.login_customer_id = _clean_customer_id(
+            login_customer_id or os.getenv("GOOGLE_ADS_LOGIN_CUSTOMER_ID", "")
+        )
+        self.api_version = api_version or os.getenv("GOOGLE_ADS_API_VERSION") or None
+        self._client = None
+
+    # ── Auth ─────────────────────────────────────────────────────────────────
+
+    def _ensure_client(self):
+        if self._client is not None:
+            return self._client
+
+        missing = [
+            name for name, val in [
+                ("GOOGLE_ADS_DEVELOPER_TOKEN", self.developer_token),
+                ("GOOGLE_ADS_CLIENT_ID", self.client_id),
+                ("GOOGLE_ADS_CLIENT_SECRET", self.client_secret),
+                ("GOOGLE_ADS_REFRESH_TOKEN", self.refresh_token),
+            ] if not val
+        ]
+        if missing:
+            raise AdsClientError(
+                f"Google Ads credentials missing: {', '.join(missing)}",
+                code="missing_credentials",
+            )
+
+        try:
+            from google.ads.googleads.client import GoogleAdsClient
+        except ImportError as e:
+            raise AdsClientError(
+                f"google-ads library not installed: {e}",
+                code="missing_dependency",
+            )
+
+        creds = {
+            "developer_token": self.developer_token,
+            "client_id": self.client_id,
+            "client_secret": self.client_secret,
+            "refresh_token": self.refresh_token,
+            "use_proto_plus": True,
+        }
+        if self.login_customer_id:
+            creds["login_customer_id"] = self.login_customer_id
+
+        if self.api_version:
+            self._client = GoogleAdsClient.load_from_dict(creds, version=self.api_version)
+        else:
+            self._client = GoogleAdsClient.load_from_dict(creds)
+        return self._client
+
+    # ── Read paths ───────────────────────────────────────────────────────────
+
+    def list_campaigns(self, customer_id: str) -> list[dict]:
+        client = self._ensure_client()
+        cid = _clean_customer_id(customer_id)
+        ga_service = client.get_service("GoogleAdsService")
+        query = """
+            SELECT
+              campaign.id,
+              campaign.name,
+              campaign.status,
+              campaign.advertising_channel_type,
+              campaign.bidding_strategy_type,
+              campaign.start_date,
+              campaign.end_date,
+              campaign_budget.amount_micros,
+              metrics.clicks,
+              metrics.impressions,
+              metrics.ctr,
+              metrics.average_cpc,
+              metrics.cost_micros,
+              metrics.conversions,
+              metrics.cost_per_conversion
+            FROM campaign
+            WHERE campaign.status != 'REMOVED'
+            ORDER BY metrics.cost_micros DESC
+        """
+        stream = ga_service.search(customer_id=cid, query=query)
+        return list(stream)
+
+    def list_search_terms(
+        self,
+        customer_id: str,
+        days: int = 30,
+        campaign_id: Optional[str] = None,
+    ) -> list[dict]:
+        client = self._ensure_client()
+        cid = _clean_customer_id(customer_id)
+        ga_service = client.get_service("GoogleAdsService")
+        start, end = _date_range(days)
+
+        where_clauses = [
+            f"segments.date BETWEEN '{start}' AND '{end}'",
+            "metrics.impressions > 0",
+        ]
+        if campaign_id:
+            where_clauses.append(f"campaign.id = {int(campaign_id)}")
+
+        query = f"""
+            SELECT
+              search_term_view.search_term,
+              metrics.clicks,
+              metrics.impressions,
+              metrics.ctr,
+              metrics.average_cpc,
+              metrics.cost_micros,
+              metrics.conversions,
+              campaign.id,
+              campaign.name,
+              ad_group.id
+            FROM search_term_view
+            WHERE {' AND '.join(where_clauses)}
+            ORDER BY metrics.cost_micros DESC
+            LIMIT 50
+        """
+        stream = ga_service.search(customer_id=cid, query=query)
+        return list(stream)
+
+    def get_campaign_budget(self, customer_id: str, campaign_id: str) -> dict:
+        client = self._ensure_client()
+        cid = _clean_customer_id(customer_id)
+        ga_service = client.get_service("GoogleAdsService")
+        # The campaign resource carries campaign_budget as an implicit join target;
+        # selecting campaign_budget.* from campaign yields the linked budget row.
+        # TODO: confirm against live API; fallback is to query `campaign_budget` directly
+        # using the resource_name returned by `campaign.campaign_budget`.
+        query = f"""
+            SELECT
+              campaign_budget.id,
+              campaign_budget.amount_micros,
+              campaign_budget.explicitly_shared
+            FROM campaign
+            WHERE campaign.id = {int(campaign_id)}
+        """
+        rows = list(ga_service.search(customer_id=cid, query=query))
+        if not rows:
+            raise AdsClientError(
+                f"No budget found for campaign {campaign_id} on customer {cid}",
+                code="budget_not_found",
+            )
+        return rows[0]
+
+    # ── Mutate paths ─────────────────────────────────────────────────────────
+
+    def update_campaign_budget(
+        self,
+        customer_id: str,
+        campaign_id: str,
+        daily_budget_usd: float,
+    ) -> dict:
+        client = self._ensure_client()
+        cid = _clean_customer_id(customer_id)
+
+        existing = self.get_campaign_budget(cid, campaign_id)
+        budget_id = existing.campaign_budget.id
+        previous_micros = existing.campaign_budget.amount_micros
+        explicitly_shared = bool(getattr(existing.campaign_budget, "explicitly_shared", False))
+
+        if explicitly_shared:
+            raise AdsClientError(
+                f"Budget {budget_id} is explicitly shared across campaigns. Refusing to mutate.",
+                code="shared_budget_refused",
+            )
+
+        new_micros = int(round(float(daily_budget_usd) * 1_000_000))
+
+        budget_service = client.get_service("CampaignBudgetService")
+        operation = client.get_type("CampaignBudgetOperation")
+        operation.update.resource_name = budget_service.campaign_budget_path(cid, budget_id)
+        operation.update.amount_micros = new_micros
+
+        from google.api_core import protobuf_helpers
+        operation.update_mask.CopyFrom(
+            protobuf_helpers.field_mask(None, operation.update._pb)
+        )
+
+        response = budget_service.mutate_campaign_budgets(
+            customer_id=cid,
+            operations=[operation],
+        )
+        return {
+            "budget_id": str(budget_id),
+            "previous_micros": int(previous_micros) if previous_micros is not None else None,
+            "new_micros": new_micros,
+            "resource_name": response.results[0].resource_name if response.results else None,
+        }
+
+    def set_campaign_status(self, customer_id: str, campaign_id: str, status: str) -> dict:
+        status = (status or "").upper()
+        if status not in MUTABLE_STATUSES:
+            raise AdsClientError(
+                f"status must be one of {sorted(MUTABLE_STATUSES)}. Got '{status}'.",
+                code="invalid_status",
+            )
+        client = self._ensure_client()
+        cid = _clean_customer_id(customer_id)
+        campaign_service = client.get_service("CampaignService")
+        status_enum = client.enums.CampaignStatusEnum.CampaignStatus
+
+        operation = client.get_type("CampaignOperation")
+        operation.update.resource_name = campaign_service.campaign_path(cid, campaign_id)
+        operation.update.status = getattr(status_enum, status)
+
+        from google.api_core import protobuf_helpers
+        operation.update_mask.CopyFrom(
+            protobuf_helpers.field_mask(None, operation.update._pb)
+        )
+
+        response = campaign_service.mutate_campaigns(
+            customer_id=cid,
+            operations=[operation],
+        )
+        return {
+            "campaign_id": str(campaign_id),
+            "new_status": status,
+            "resource_name": response.results[0].resource_name if response.results else None,
+        }
+
+    def add_negative_keywords(
+        self,
+        customer_id: str,
+        campaign_id: str,
+        keywords: list[str],
+        match_type: str = "BROAD",
+    ) -> dict:
+        match_type = (match_type or "BROAD").upper()
+        if match_type not in VALID_MATCH_TYPES:
+            raise AdsClientError(
+                f"match_type must be one of {sorted(VALID_MATCH_TYPES)}. Got '{match_type}'.",
+                code="invalid_match_type",
+            )
+        keywords = [k for k in (keywords or []) if k and k.strip()]
+        if not keywords:
+            raise AdsClientError("keywords list is empty", code="empty_keywords")
+
+        client = self._ensure_client()
+        cid = _clean_customer_id(customer_id)
+        campaign_service = client.get_service("CampaignService")
+        criterion_service = client.get_service("CampaignCriterionService")
+        match_enum = client.enums.KeywordMatchTypeEnum.KeywordMatchType
+
+        operations = []
+        campaign_resource = campaign_service.campaign_path(cid, campaign_id)
+        for kw in keywords:
+            op = client.get_type("CampaignCriterionOperation")
+            op.create.campaign = campaign_resource
+            op.create.negative = True
+            op.create.keyword.text = kw.strip()
+            op.create.keyword.match_type = getattr(match_enum, match_type)
+            operations.append(op)
+
+        response = criterion_service.mutate_campaign_criteria(
+            customer_id=cid,
+            operations=operations,
+        )
+        return {
+            "campaign_id": str(campaign_id),
+            "match_type": match_type,
+            "keywords_added": keywords,
+            "count": len(response.results),
+            "resource_names": [r.resource_name for r in response.results],
+        }

gadschain-0.1.0/src/gadschain/core/__init__.py

@@ -0,0 +1,3 @@
+from .transformer import Transformer
+
+__all__ = ["Transformer"]