adloop 0.13.0__tar.gz → 0.13.2__tar.gz

{adloop-0.13.0 → adloop-0.13.2}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.3
 Name: adloop
-Version: 0.13.0
+Version: 0.13.2
 Summary: The AI command center for Google Ads, GA4, and tracking code.
 Keywords: mcp,google-ads,google-analytics,ga4,cursor,marketing
 Author: Daniel Klose
@@ -47,6 +47,8 @@ An MCP server that gives your AI assistant read + write access to Google Ads and
 > [!TIP]
 > **[AdLoop Cloud](https://getadloop.com) is the hosted version of this project — live now, free during beta (limited seats).** Connect Google in two clicks and use the full toolset from claude.ai, ChatGPT, Claude Code, Cursor, or Gemini. No Google Cloud project, no developer token, no OAuth verification wait. EU-hosted, GDPR-first, DPA included.
 
+> 📚 **Documentation: [docs.getadloop.com](https://docs.getadloop.com)** — setup guides per AI client, toolsets, the safety model, and troubleshooting for both editions.
+
 ---
 
 ## Cloud or Self-Hosted?

{adloop-0.13.0 → adloop-0.13.2}/README.md

@@ -21,6 +21,8 @@ An MCP server that gives your AI assistant read + write access to Google Ads and
 > [!TIP]
 > **[AdLoop Cloud](https://getadloop.com) is the hosted version of this project — live now, free during beta (limited seats).** Connect Google in two clicks and use the full toolset from claude.ai, ChatGPT, Claude Code, Cursor, or Gemini. No Google Cloud project, no developer token, no OAuth verification wait. EU-hosted, GDPR-first, DPA included.
 
+> 📚 **Documentation: [docs.getadloop.com](https://docs.getadloop.com)** — setup guides per AI client, toolsets, the safety model, and troubleshooting for both editions.
+
 ---
 
 ## Cloud or Self-Hosted?

adloop-0.13.2/pyproject.toml

@@ -0,0 +1,50 @@
+[project]
+name = "adloop"
+version = "0.13.2"
+description = "The AI command center for Google Ads, GA4, and tracking code."
+readme = "README.md"
+requires-python = ">=3.11"
+keywords = [
+    "mcp",
+    "google-ads",
+    "google-analytics",
+    "ga4",
+    "cursor",
+    "marketing",
+]
+dependencies = [
+    "fastmcp>=3.0.0",
+    "google-ads>=31.1.0",
+    "google-analytics-data>=0.20.0",
+    "google-analytics-admin>=0.27.0",
+    "google-api-python-client>=2.100.0",
+    "google-auth-oauthlib>=1.0.0",
+    "google-api-python-client>=2.0.0",
+    "pyyaml>=6.0",
+]
+
+[[project.authors]]
+name = "Daniel Klose"
+email = "info@daniel-klose.com"
+
+[project.license]
+text = "MIT"
+
+[project.urls]
+Homepage = "https://github.com/kLOsk/adloop"
+Repository = "https://github.com/kLOsk/adloop"
+Issues = "https://github.com/kLOsk/adloop/issues"
+Changelog = "https://github.com/kLOsk/adloop/releases"
+
+[project.scripts]
+adloop = "adloop:main"
+
+[project.optional-dependencies]
+dev = [
+    "pytest>=8.0",
+    "pytest-asyncio>=0.23",
+]
+
+[build-system]
+requires = ["uv_build>=0.10.8,<0.11.0"]
+build-backend = "uv_build"

adloop-0.13.0/pyproject.toml → adloop-0.13.2/pyproject.toml.orig

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

{adloop-0.13.0 → adloop-0.13.2}/src/adloop/__init__.py

@@ -9,6 +9,25 @@ except PackageNotFoundError:  # running from a source tree without install
     __version__ = "0.0.0.dev0"
 
 
+def install_runtime_patches() -> None:
+    """Arm the upstream-bug workarounds for a long-running host process.
+
+    Importing ``adloop.server`` is deliberately free of process-global side
+    effects so the server can be embedded in an ASGI app. That leaves the
+    workarounds in ``_mcp_patches`` unarmed for any embedder, including a
+    hosted deployment, which is exactly where they matter most: the
+    cancellation race they guard against (python-sdk#2416) fires when a
+    host cancels a slow tool call, and it takes the transport down with it.
+
+    Embedders should call this once during application startup. It is
+    idempotent, never raises, and each patch inside self-disarms once the
+    upstream bug it tracks is fixed.
+    """
+    from adloop import _mcp_patches
+
+    _mcp_patches.install()
+
+
 def main() -> None:
     """Entry point for `adloop` console script.
 
@@ -50,10 +69,10 @@ def main() -> None:
     # the stdio cancellation-race monkeypatch) are deliberately installed
     # here — in the stdio entry point — rather than at adloop.server import
     # time, so embedding the server in an ASGI app stays side-effect-free.
-    from adloop import _mcp_patches, diagnostics
+    from adloop import diagnostics
 
     diagnostics.install()
-    _mcp_patches.install()
+    install_runtime_patches()
 
     from adloop.server import mcp
 

{adloop-0.13.0 → adloop-0.13.2}/src/adloop/ads/write.py

@@ -270,17 +270,49 @@ def _build_public_only_opener():
     return urllib.request.build_opener(_PublicOnlyRedirectHandler)
 
 
-def _validate_urls(urls: list[str], timeout: int = 10) -> dict[str, str | None]:
+# Statuses that say nothing about whether the landing page is any good:
+# the site is throttling us, or is briefly unwell. Refusing to draft an ad
+# over one punishes the advertiser for their own rate limiting — and we
+# are frequently the cause of it, since drafting several ads at once fires
+# several HEAD requests at the same origin within a second or two.
+#
+# A genuinely dead URL still blocks: 404 and 410 are the cases this check
+# exists for, and they do not resolve themselves on a retry.
+_INCONCLUSIVE_STATUSES = frozenset({408, 425, 429, 500, 502, 503, 504})
+
+
+def _validate_urls(
+    urls: list[str], timeout: int = 10
+) -> tuple[dict[str, str | None], dict[str, str]]:
     """Check that each URL returns a 2xx/3xx status.
 
-    Returns a dict of {url: error_message_or_None}. None means the URL is fine.
+    Returns (errors, warnings). ``errors`` maps url -> message for URLs
+    that should block the operation, None when fine. ``warnings`` maps
+    url -> message for checks that came back inconclusive; callers should
+    surface those but proceed, because the alternative is refusing to work
+    whenever the advertiser's own site is briefly throttling or flaky.
     """
     import urllib.request
     import urllib.error
 
     opener = _build_public_only_opener()
 
-    results = {}
+    results: dict[str, str | None] = {}
+    warnings: dict[str, str] = {}
+
+    def _record_status(url: str, status: int) -> None:
+        if status in _INCONCLUSIVE_STATUSES:
+            results[url] = None
+            warnings[url] = (
+                f"HTTP {status} — could not verify the URL right now "
+                "(the site may be rate-limiting or temporarily down). "
+                "Proceeding without the check; confirm the page is live."
+            )
+        elif status >= 400:
+            results[url] = f"HTTP {status}"
+        else:
+            results[url] = None
+
     for url in urls:
         if not url:
             continue
@@ -292,10 +324,7 @@ def _validate_urls(urls: list[str], timeout: int = 10) -> dict[str, str | None]:
             req = urllib.request.Request(url, method="HEAD")
             req.add_header("User-Agent", "AdLoop-URLCheck/1.0")
             resp = opener.open(req, timeout=timeout)
-            if resp.status >= 400:
-                results[url] = f"HTTP {resp.status}"
-            else:
-                results[url] = None
+            _record_status(url, resp.status)
         except urllib.error.HTTPError as e:
             if e.code == 405:
                 # HEAD not allowed, try GET
@@ -303,18 +332,17 @@ def _validate_urls(urls: list[str], timeout: int = 10) -> dict[str, str | None]:
                     req = urllib.request.Request(url, method="GET")
                     req.add_header("User-Agent", "AdLoop-URLCheck/1.0")
                     resp = opener.open(req, timeout=timeout)
-                    if resp.status >= 400:
-                        results[url] = f"HTTP {resp.status}"
-                    else:
-                        results[url] = None
+                    _record_status(url, resp.status)
+                except urllib.error.HTTPError as e2:
+                    _record_status(url, e2.code)
                 except Exception as e2:
                     results[url] = str(e2)
             else:
-                results[url] = f"HTTP {e.code}"
+                _record_status(url, e.code)
         except Exception as e:
             results[url] = str(e)
 
-    return results
+    return results, warnings
 
 
 def _normalize_display_network_setting(
@@ -467,7 +495,7 @@ def draft_responsive_search_ad(
     if errors:
         return {"error": "Validation failed", "details": errors}
 
-    url_check = _validate_urls([final_url])
+    url_check, url_warnings = _validate_urls([final_url])
     if url_check.get(final_url):
         return {
             "error": "URL validation failed",
@@ -478,6 +506,8 @@ def draft_responsive_search_ad(
         }
 
     warnings = []
+    if url_warnings.get(final_url):
+        warnings.append(f"final_url '{final_url}': {url_warnings[final_url]}")
     if len(headlines) < 8:
         warnings.append(
             f"Only {len(headlines)} headlines provided. Google recommends 8-15 "
@@ -1703,7 +1733,7 @@ def draft_sitelinks(
         return {"error": "Validation failed", "details": errors}
 
     sitelink_urls = [sl["final_url"] for sl in validated]
-    url_checks = _validate_urls(sitelink_urls)
+    url_checks, url_warnings = _validate_urls(sitelink_urls)
     bad_urls = {u: err for u, err in url_checks.items() if err}
     if bad_urls:
         return {
@@ -1712,6 +1742,7 @@ def draft_sitelinks(
                 f"'{url}' is not reachable: {err}" for url, err in bad_urls.items()
             ],
         }
+    warnings.extend(f"'{url}': {msg}" for url, msg in url_warnings.items())
 
     if len(validated) < 2:
         warnings.append(
@@ -2291,6 +2322,32 @@ def _validate_campaign(
             f"channel_type must be one of {sorted(_VALID_CHANNEL_TYPES)}, "
             f"got '{channel_type}'"
         )
+
+    # Performance Max has no ad groups. Every campaign needs at least one
+    # asset group, and the API requires the asset group plus all of its
+    # required assets in a single atomic mutate. We cannot supply the
+    # images, so creating the campaign alone would leave the user with
+    # something that can never serve while reporting success.
+    if ct == "PERFORMANCE_MAX":
+        errors.append(
+            "Performance Max campaigns cannot be created yet. PMax has no ad "
+            "groups: a campaign needs at least one asset group, and Google "
+            "requires the asset group and all its assets (headlines, "
+            "descriptions, business name, logo, and images in several aspect "
+            "ratios) in one atomic request. Creating the campaign on its own "
+            "would produce a campaign that can never serve. Create it in the "
+            "Google Ads interface, then use AdLoop to analyse it — "
+            "get_pmax_performance reports per-asset-group Ad Strength."
+        )
+    elif ct != "SEARCH":
+        # These do produce a usable campaign, but nothing here can populate
+        # them: draft_ad_group refuses anything that is not SEARCH.
+        warnings.append(
+            f"{ct} campaigns are created as a shell only. AdLoop can add ad "
+            f"groups, ads and keywords to SEARCH campaigns; finish this one "
+            f"in the Google Ads interface."
+        )
+
     if ct != "SEARCH" and search_partners_enabled:
         errors.append("search_partners_enabled is only supported for SEARCH campaigns")
     if ct != "SEARCH" and display_network_enabled:

{adloop-0.13.0 → adloop-0.13.2}/src/adloop/merchant/client.py

@@ -13,7 +13,15 @@ from typing import TYPE_CHECKING
 if TYPE_CHECKING:
     from adloop.config import AdLoopConfig
 
-_BASE = "https://merchantapi.googleapis.com/accounts/v1"
+_BASE = "https://merchantapi.googleapis.com"
+
+# The Merchant API is split into independently versioned sub-APIs, and the
+# sub-API is part of the path: accounts/v1 serves accounts and account
+# issues, but product-status aggregation lives under issueresolution/v1.
+# Guessing wrong yields a bare 404 with no error message, so every call
+# states its sub-API and API_ACCOUNTS is only the default.
+API_ACCOUNTS = "accounts/v1"
+API_ISSUE_RESOLUTION = "issueresolution/v1"
 
 # Google blocks every Merchant API call from a GCP project that is not
 # registered as a developer with the merchant account (401 UNAUTHENTICATED,
@@ -32,6 +40,7 @@ def _request(
     method: str,
     path: str,
     *,
+    api: str = API_ACCOUNTS,
     params: dict | None = None,
     json_body: dict | None = None,
 ) -> dict:
@@ -39,10 +48,11 @@ def _request(
 
     from adloop.auth import get_merchant_credentials
 
+    url = f"{_BASE}/{api.strip('/')}/{path.lstrip('/')}"
     session = AuthorizedSession(get_merchant_credentials(config))
     response = session.request(
         method,
-        f"{_BASE}/{path.lstrip('/')}",
+        url,
         params=params or {},
         json=json_body,
         timeout=30,
@@ -55,18 +65,35 @@ def _request(
             pass
         if _REGISTRATION_MARKER in detail:
             raise MerchantNotRegistered(detail)
-        raise RuntimeError(f"Merchant API returned {response.status_code}: {detail}")
+        # A wrong sub-API prefix answers 404 with an empty message, so name
+        # the URL that failed rather than reporting a bare status code.
+        raise RuntimeError(
+            f"Merchant API returned {response.status_code} for {url}"
+            f"{f': {detail}' if detail else ''}"
+        )
     return response.json()
 
 
-def merchant_get(config: AdLoopConfig, path: str, params: dict | None = None) -> dict:
-    """Authorized GET against the Merchant API accounts_v1 surface."""
-    return _request(config, "GET", path, params=params)
+def merchant_get(
+    config: AdLoopConfig,
+    path: str,
+    params: dict | None = None,
+    *,
+    api: str = API_ACCOUNTS,
+) -> dict:
+    """Authorized GET against a Merchant API sub-API (default: accounts)."""
+    return _request(config, "GET", path, api=api, params=params)
 
 
-def merchant_post(config: AdLoopConfig, path: str, body: dict | None = None) -> dict:
-    """Authorized POST against the Merchant API accounts_v1 surface."""
-    return _request(config, "POST", path, json_body=body or {})
+def merchant_post(
+    config: AdLoopConfig,
+    path: str,
+    body: dict | None = None,
+    *,
+    api: str = API_ACCOUNTS,
+) -> dict:
+    """Authorized POST against a Merchant API sub-API (default: accounts)."""
+    return _request(config, "POST", path, api=api, json_body=body or {})
 
 
 def register_gcp(config: AdLoopConfig, account_id: str) -> dict:

{adloop-0.13.0 → adloop-0.13.2}/src/adloop/merchant/read.py

@@ -118,6 +118,7 @@ def get_merchant_feed_health(
     them) with account-level issues that can suspend the whole account.
     """
     from adloop.merchant.client import (
+        API_ISSUE_RESOLUTION,
         MerchantNotRegistered,
         merchant_get,
         register_gcp,
@@ -132,8 +133,12 @@ def get_merchant_feed_health(
 
     def _fetch() -> tuple[dict, dict]:
         return (
+            # Product-status aggregation is served by the issueresolution
+            # sub-API, not accounts — the wrong prefix 404s.
             merchant_get(
-                config, f"accounts/{account_id}/aggregateProductStatuses"
+                config,
+                f"accounts/{account_id}/aggregateProductStatuses",
+                api=API_ISSUE_RESOLUTION,
             ),
             merchant_get(config, f"accounts/{account_id}/issues"),
         )