adloop 0.13.0__tar.gz → 0.13.3__tar.gz

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

@@ -1,6 +1,6 @@
 Metadata-Version: 2.3
 Name: adloop
-Version: 0.13.0
+Version: 0.13.3
 Summary: The AI command center for Google Ads, GA4, and tracking code.
 Keywords: mcp,google-ads,google-analytics,ga4,cursor,marketing
 Author: Daniel Klose
@@ -24,6 +24,8 @@ Project-URL: Changelog, https://github.com/kLOsk/adloop/releases
 Provides-Extra: dev
 Description-Content-Type: text/markdown
 
+<!-- mcp-name: com.getadloop/adloop -->
+
 <div align="center">
 
 # AdLoop
@@ -40,12 +42,14 @@ Description-Content-Type: text/markdown
 
 An MCP server that gives your AI assistant read + write access to Google Ads and GA4 — with safety guardrails that prevent accidental spend.
 
-**[☁️ Skip the setup — use AdLoop Cloud (free beta)](https://getadloop.com)** &nbsp;·&nbsp; or self-host: `pip install adloop`
+**[☁️ Skip the setup — use AdLoop Cloud (free plan, no card)](https://getadloop.com)** &nbsp;·&nbsp; or self-host: `pip install adloop`
 
 </div>
 
 > [!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.
+> **[AdLoop Cloud](https://getadloop.com) is the hosted version of this project, with a free plan that needs no credit card.** 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.
 
 ---
 
@@ -61,7 +65,7 @@ Both versions run the same tools with the same safety model. The difference is w
 | **Works with** | claude.ai, ChatGPT, Claude Code, Cursor, Gemini | Claude Code, Cursor, Claude Desktop, any local MCP client |
 | **Where your data flows** | EU servers (Germany), GDPR-first, DPA included | 100% your machine — nothing leaves it |
 | **Updates** | Automatic | `pip install -U adloop` |
-| **Price** | Free during beta | Free forever (MIT) |
+| **Price** | Free plan, no card; [paid plans](https://getadloop.com/preise) for more accounts and volume | Free forever (MIT) |
 
 **Not sure? [Start with Cloud](https://getadloop.com)** — it's the fastest way to see what AdLoop can do, and it's the only way to use AdLoop from claude.ai or ChatGPT. Self-host when you want everything on your own machine or need to modify the code. And if you're here to hack on AdLoop itself: welcome, keep scrolling.
 
@@ -515,7 +519,7 @@ What's been shipped and what's next:
 - ~~Claude Code support~~ ✓ — `CLAUDE.md`, `.mcp.json`, `.claude/rules/`, `.claude/commands/`, CLI wizard snippets
 - **Claude Desktop one-click install** — `adloop install claude-desktop` (and/or a `.dxt` extension bundle) that writes the AdLoop MCP entry into `claude_desktop_config.json` automatically, so Claude Desktop + Cowork users don't have to hand-edit JSON
 - ~~PyPI package~~ ✓ — `pip install adloop`
-- ~~[AdLoop Cloud](https://getadloop.com)~~ ✓ — the hosted version, live in beta: no Google Cloud project, no developer token, connect Google in two clicks (EU-hosted, GDPR-first)
+- ~~[AdLoop Cloud](https://getadloop.com)~~ ✓ — the hosted version: no Google Cloud project, no developer token, connect Google in two clicks (EU-hosted, GDPR-first)
 - ~~Headless server support~~ ✓ — manual URL copy-paste flow for servers without a browser
 - ~~Behavioral eval suites~~ ✓ — 28 prompt-and-expectation tests covering read, write, tracking, and planning workflows
 - ~~Google Tag Manager integration~~ ✓ — read tools for tags, triggers, variables, workspaces, and version history, plus the `audit_event_coverage` three-way join across codebase events, GTM tags, and GA4 actual fires

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

@@ -1,3 +1,5 @@
+<!-- mcp-name: com.getadloop/adloop -->
+
 <div align="center">
 
 # AdLoop
@@ -14,12 +16,14 @@
 
 An MCP server that gives your AI assistant read + write access to Google Ads and GA4 — with safety guardrails that prevent accidental spend.
 
-**[☁️ Skip the setup — use AdLoop Cloud (free beta)](https://getadloop.com)** &nbsp;·&nbsp; or self-host: `pip install adloop`
+**[☁️ Skip the setup — use AdLoop Cloud (free plan, no card)](https://getadloop.com)** &nbsp;·&nbsp; or self-host: `pip install adloop`
 
 </div>
 
 > [!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.
+> **[AdLoop Cloud](https://getadloop.com) is the hosted version of this project, with a free plan that needs no credit card.** 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.
 
 ---
 
@@ -35,7 +39,7 @@ Both versions run the same tools with the same safety model. The difference is w
 | **Works with** | claude.ai, ChatGPT, Claude Code, Cursor, Gemini | Claude Code, Cursor, Claude Desktop, any local MCP client |
 | **Where your data flows** | EU servers (Germany), GDPR-first, DPA included | 100% your machine — nothing leaves it |
 | **Updates** | Automatic | `pip install -U adloop` |
-| **Price** | Free during beta | Free forever (MIT) |
+| **Price** | Free plan, no card; [paid plans](https://getadloop.com/preise) for more accounts and volume | Free forever (MIT) |
 
 **Not sure? [Start with Cloud](https://getadloop.com)** — it's the fastest way to see what AdLoop can do, and it's the only way to use AdLoop from claude.ai or ChatGPT. Self-host when you want everything on your own machine or need to modify the code. And if you're here to hack on AdLoop itself: welcome, keep scrolling.
 
@@ -489,7 +493,7 @@ What's been shipped and what's next:
 - ~~Claude Code support~~ ✓ — `CLAUDE.md`, `.mcp.json`, `.claude/rules/`, `.claude/commands/`, CLI wizard snippets
 - **Claude Desktop one-click install** — `adloop install claude-desktop` (and/or a `.dxt` extension bundle) that writes the AdLoop MCP entry into `claude_desktop_config.json` automatically, so Claude Desktop + Cowork users don't have to hand-edit JSON
 - ~~PyPI package~~ ✓ — `pip install adloop`
-- ~~[AdLoop Cloud](https://getadloop.com)~~ ✓ — the hosted version, live in beta: no Google Cloud project, no developer token, connect Google in two clicks (EU-hosted, GDPR-first)
+- ~~[AdLoop Cloud](https://getadloop.com)~~ ✓ — the hosted version: no Google Cloud project, no developer token, connect Google in two clicks (EU-hosted, GDPR-first)
 - ~~Headless server support~~ ✓ — manual URL copy-paste flow for servers without a browser
 - ~~Behavioral eval suites~~ ✓ — 28 prompt-and-expectation tests covering read, write, tracking, and planning workflows
 - ~~Google Tag Manager integration~~ ✓ — read tools for tags, triggers, variables, workspaces, and version history, plus the `audit_event_coverage` three-way join across codebase events, GTM tags, and GA4 actual fires

adloop-0.13.3/pyproject.toml

@@ -0,0 +1,50 @@
+[project]
+name = "adloop"
+version = "0.13.3"
+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.3/pyproject.toml.orig

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

{adloop-0.13.0 → adloop-0.13.3}/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.3}/src/adloop/ads/read.py

@@ -278,10 +278,24 @@ def get_keyword_performance(
         return {"keywords": rows, "total_keywords": len(rows)}
 
     qs_field = "ad_group_criterion.quality_info.quality_score"
+
+    def _rated_score(r: dict) -> int | None:
+        """The Quality Score, or None when Google has not assigned one.
+
+        Google never issues a real score of 0: both null and 0 mean "not
+        enough impressions to rate". Counting those as "< 5" reports an
+        ordinary unrated long tail as an account-wide relevance problem and
+        sends the assistant off fixing ads and landing pages that are fine.
+        """
+        score = r.get(qs_field)
+
+        return score if isinstance(score, int) and score > 0 else None
+
     low_quality = [
         r for r in rows
-        if r.get(qs_field) is not None and (r.get(qs_field) or 0) < 5
+        if (score := _rated_score(r)) is not None and score < 5
     ]
+    unrated_count = sum(1 for r in rows if _rated_score(r) is None)
     zero_conv_spenders = [
         r for r in rows
         if (r.get("metrics.cost_micros") or 0) > 0
@@ -304,6 +318,11 @@ def get_keyword_performance(
             f"{len(low_quality)} keyword(s) have quality score < 5 — fix ad "
             f"relevance and landing pages before adding keywords or budget."
         )
+    if unrated_count:
+        insights.append(
+            f"{unrated_count} keyword(s) have no quality score yet (too few "
+            f"impressions to rate). They are excluded from the count above."
+        )
     if zero_conv_spenders:
         wasted = round(
             sum((r.get("metrics.cost_micros") or 0) for r in zero_conv_spenders)
@@ -325,6 +344,7 @@ def get_keyword_performance(
         ),
         "keywords_top_spend": top,
         "low_quality_score": [_kw(r) for r in low_quality[:10]],
+        "unrated_quality_score": unrated_count,
         "zero_conversion_spenders": [_kw(r) for r in zero_conv_spenders[:10]],
         "insights": insights,
         "note": _compact_note(len(top), len(rows), "get_keyword_performance"),
@@ -430,7 +450,7 @@ def get_search_terms(
     return {
         "compact": True,
         "total_search_terms": len(rows),
-        "totals": _compact_totals(rows, currency_code),
+        "totals": _compact_totals(rows, currency_code, row_limit=200),
         "search_terms_top_clicks": top,
         "waste_candidates": [_term(r) for r in waste[:10]],
         "top_converters": [_term(r) for r in converters[:5]],
@@ -923,8 +943,15 @@ def _date_clause(start: str, end: str) -> str:
     return "AND segments.date DURING LAST_30_DAYS"
 
 
-def _compact_totals(rows: list[dict], currency_code: str) -> dict:
-    """Deterministic account-level aggregates over enriched metric rows."""
+def _compact_totals(
+    rows: list[dict], currency_code: str, *, row_limit: int | None = None
+) -> dict:
+    """Deterministic aggregates over the rows given.
+
+    Not account-level whenever the query behind them carries a LIMIT: pass
+    ``row_limit`` for those reports so a truncated total is marked partial
+    instead of being read as the account's real cost and conversions.
+    """
     cost = sum((r.get("metrics.cost_micros") or 0) for r in rows) / 1_000_000
     clicks = sum((r.get("metrics.clicks") or 0) for r in rows)
     impressions = sum((r.get("metrics.impressions") or 0) for r in rows)
@@ -940,6 +967,21 @@ def _compact_totals(rows: list[dict], currency_code: str) -> dict:
         totals["cpa"] = round(cost / conversions, 2)
     if impressions > 0:
         totals["ctr_pct"] = round(clicks / impressions * 100, 2)
+
+    # Hitting the ceiling exactly is indistinguishable from stopping there, so
+    # this errs toward declaring partial. Silently under-reporting cost is the
+    # worse failure: these numbers are labelled "totals" and get compared
+    # against campaign-level truth.
+    if row_limit is not None and len(rows) >= row_limit:
+        totals["partial"] = True
+        totals["rows_counted"] = len(rows)
+        totals["partial_reason"] = (
+            f"The underlying query returns at most {row_limit} rows, ranked by "
+            f"the report's sort metric, and this account reached that ceiling. "
+            f"These totals cover those rows only, not the whole account. Use "
+            f"get_campaign_performance for account-level figures."
+        )
+
     return totals
 
 

{adloop-0.13.0 → adloop-0.13.3}/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.3}/src/adloop/config.py

@@ -82,6 +82,26 @@ def _resolve_path(path_str: str) -> Path:
     return Path(os.path.expandvars(os.path.expanduser(path_str)))
 
 
+def _text(raw: dict, key: str, default: str = "") -> str:
+    """Read a string setting, treating blank as absent.
+
+    ``raw.get(key, default)`` only falls back when the key is *missing*, so an
+    explicit ``token_path: ""`` — easy to produce from a template with blank
+    placeholders — passed straight through. ``Path("")`` is ``Path(".")``, the
+    working directory always exists, and adloop then tried to read the cwd as
+    a token file and died with ``[Errno 1] Operation not permitted: '.'``,
+    which points nowhere near the config that caused it.
+
+    Also coerces non-strings, so ``customer_id: 1234567890`` in YAML arrives
+    as text rather than an int.
+    """
+    value = raw.get(key, default)
+
+    if value is None:
+        return default
+
+    return str(value).strip() or default
+
 def load_config(config_path: str | None = None) -> AdLoopConfig:
     """Load configuration from YAML file.
 
@@ -112,34 +132,34 @@ def load_config(config_path: str | None = None) -> AdLoopConfig:
 
     return AdLoopConfig(
         google=GoogleConfig(
-            project_id=google_raw.get("project_id", ""),
-            credentials_path=google_raw.get("credentials_path", ""),
-            token_path=google_raw.get("token_path", "~/.adloop/token.json"),
+            project_id=_text(google_raw, "project_id"),
+            credentials_path=_text(google_raw, "credentials_path"),
+            token_path=_text(google_raw, "token_path", "~/.adloop/token.json"),
         ),
         ga4=GA4Config(
-            property_id=ga4_raw.get("property_id", ""),
+            property_id=_text(ga4_raw, "property_id"),
         ),
         ads=AdsConfig(
-            developer_token=ads_raw.get("developer_token", ""),
-            customer_id=ads_raw.get("customer_id", ""),
-            login_customer_id=ads_raw.get("login_customer_id", ""),
+            developer_token=_text(ads_raw, "developer_token"),
+            customer_id=_text(ads_raw, "customer_id"),
+            login_customer_id=_text(ads_raw, "login_customer_id"),
         ),
         gsc=GscConfig(
-            site_url=gsc_raw.get("site_url", ""),
+            site_url=_text(gsc_raw, "site_url"),
         ),
         gtm=GtmConfig(
-            account_id=str(gtm_raw.get("account_id", "")),
-            container_id=str(gtm_raw.get("container_id", "")),
+            account_id=_text(gtm_raw, "account_id"),
+            container_id=_text(gtm_raw, "container_id"),
         ),
         pagespeed=PageSpeedConfig(
-            api_key=str(pagespeed_raw.get("api_key", "")),
+            api_key=_text(pagespeed_raw, "api_key"),
         ),
         safety=SafetyConfig(
             max_daily_budget=safety_raw.get("max_daily_budget", 50.0),
             max_bid_increase_pct=safety_raw.get("max_bid_increase_pct", 100),
             require_dry_run=safety_raw.get("require_dry_run", True),
             two_phase_apply=safety_raw.get("two_phase_apply", False),
-            log_file=safety_raw.get("log_file", "~/.adloop/audit.log"),
+            log_file=_text(safety_raw, "log_file", "~/.adloop/audit.log"),
             blocked_operations=safety_raw.get("blocked_operations", []),
         ),
         source_path=resolved,

{adloop-0.13.0 → adloop-0.13.3}/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.3}/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"),
         )

{adloop-0.13.0 → adloop-0.13.3}/src/adloop/rules/adloop.md

@@ -655,16 +655,29 @@ For cities/regions, use `run_gaql` with `geo_target_constant` resource or look u
 
 ### Common Language IDs (languageConstants)
 
-| ID | Language |
-|----|----------|
-| 1000 | English |
-| 1001 | German |
-| 1002 | French |
-| 1003 | Italian |
-| 1004 | Spanish |
-| 1005 | Dutch |
-| 1009 | Portuguese |
-| 1014 | Polish |
+Verified against the `language_constant` resource. Google accepts a wrong
+language ID silently, so confirm anything not listed here with:
+`SELECT language_constant.id, language_constant.code, language_constant.name FROM language_constant`
+
+| ID | Code | Language |
+|----|------|----------|
+| 1000 | en | English |
+| 1001 | de | German |
+| 1002 | fr | French |
+| 1003 | es | Spanish |
+| 1004 | it | Italian |
+| 1005 | ja | Japanese |
+| 1009 | da | Danish |
+| 1010 | nl | Dutch |
+| 1011 | fi | Finnish |
+| 1014 | pt | Portuguese |
+| 1015 | sv | Swedish |
+| 1017 | zh_CN | Chinese (simplified) |
+| 1019 | ar | Arabic |
+| 1021 | cs | Czech |
+| 1030 | pl | Polish |
+| 1031 | ru | Russian |
+| 1037 | tr | Turkish |
 
 ## Marketing Best Practices