feat(gtm): Tag Manager API integration with three-way tracking audit

[illia-sapryga]

Summary

• New audit_event_coverage cross-reference tool: three-way join across codebase events ↔ GTM tags ↔ GA4 actual fires, with 10 distinct status codes per event and auto-generated insights for every gap
• 11 GTM read tools covering accounts, containers, tags, triggers, variables, workspaces, and version history
• All read-only. Write tools deliberately deferred to a follow-up (rationale below)
• 50 unit tests added covering all pure-function parsers + every audit status code + insight generation + matrix contracts (234/234 suite passes)
• Tool count: 43 → 55

Why this exists

GA4 + Ads tell you what fired. Codebase grep tells you intent. GTM tells you wiring. Each in isolation hides real bugs — paused tags, page-scoped triggers that under-fire, dynamic event names hiding real coverage, codebase events with no tag wired up at all.

validate_tracking already does codebase ↔ GA4. attribution_check does Ads ↔ GA4. Neither sees GTM, so neither can tell you why an event isn't firing — only that it isn't.

audit_event_coverage joins all three sources and returns a per-event status:

Status	Meaning
ok	Codebase event with an active tag and GA4 fires
ok_auto_collected	GA4 Enhanced Measurement event, no tag needed
no_tag_no_fire	Codebase event, no GTM tag, never fires
tag_paused	GTM tag exists but paused
tag_active_but_not_firing	Active tag, no GA4 hits — trigger condition or DOM problem
gtm_only_firing	GA4 event from a tag, not in codebase (possibly stale; verify)
gtm_only_not_firing	Tag exists, not in codebase, no fires (stale tag)
ga4_only	Fires in GA4 with no tag and no codebase ref (other tag manager / 3rd-party SDK)
ga4_fires_no_tag	Codebase event firing without a GTM tag (gtag.js direct path)
auto_event_only	Enhanced Measurement event with no codebase ref

Plus auto-generated insights[] for: codebase events with no tag, paused tags, active-but-not-firing tags, GTM-only tags, GA4-only events, dynamic-event tags using {{Event}} variables, and active Custom HTML tags whose event semantics the audit can't infer.

Validated against a real container

Caught a substantive issue that no single-source diagnostic surfaces: a production container where the GA4 form_submit and click_to_call tags were scoped to /service-promotions/* only, while the Google Ads Enhanced Conversions for Leads tag caught every form submit sitewide. Result: asymmetric Smart Bidding signal — Ads gets full lead data, GA4 sees only ~5 out of N submissions. That was invisible from GA4 + Ads alone.

The same audit also caught a negate: true filter on a trigger that had been silently inverted in earlier hand-inspection — surfaced by the _summarize_filter parser rendering {{Form ID}} NOT contains wf-form-footer-subscribe-one instead of just {{Form ID}} contains wf-form-footer-subscribe-one.

What's added

New module: src/adloop/gtm/

• client.py — Tag Manager API v2 client wrapper (Discovery-built; no gRPC client exists for GTM v2)
• read.py — live container fetching, tag/trigger/variable parsing, workspace diff, version history. Includes type-specific parsing for triggerGroup (member trigger IDs), elementVisibility (selector + timing), and built-in trigger ID resolution (>= 2147479553 are not returned in the trigger list, mapped to readable names like (built-in) All Pages).

auth.py

• _GTM_SCOPES = ["https://www.googleapis.com/auth/tagmanager.readonly"]
• get_gtm_credentials(config) — service account + OAuth user paths
• tagmanager.readonly added to _ALL_SCOPES so OAuth users get GTM access on next re-auth

crossref.py

• audit_event_coverage() — joins GTM live container + GA4 event counts + codebase event list

server.py

• 12 new @mcp.tool(annotations=_READONLY) registrations

pyproject.toml

• google-api-python-client>=2.100.0

README.md

• New "Google Tag Manager Tools" section with all 12 tools
• New "What It Solves" bullet about the three-way audit
• Setup callout for enabling Tag Manager API + adding Read access on the container
• Project structure updated to include gtm/
• Roadmap entry checked off
• Tool count updated 43 → 55

tests/test_gtm.py (added in second commit)

• 50 unit tests across 12 test classes
• Every pure-function parser covered: _params_dict, _summarize_filter, _resolve_trigger, _trigger_group_member_ids, _element_visibility_summary, _parse_trigger, _parse_variable
• One reachability test per audit_event_coverage status code (10 statuses)
• Insight-generation tests for: missing tag, paused tag, dynamic event, Custom HTML
• Matrix contract tests: required fields, container summary breakdown, GA4 error short-circuit, alphabetical event sort
• Uses unittest.mock.patch on adloop.gtm.read.get_live_container and adloop.ga4.tracking.get_tracking_events — deterministic, no live API calls, ~40ms total

Bug caught + fixed by tests

audit_event_coverage's status logic had an unreachable branch: the ok status was matched on in_gtm AND any_active_tag AND ga4_fires without requiring in_codebase, which meant gtm_only_firing (intended semantics: "event fires from a GTM tag but isn't in the codebase, possibly stale") could never be reached for an active tag with GA4 fires. Fixed by adding in_codebase to the ok condition. No user-facing surface area change for events that ARE in the codebase — only events with active firing tags but no codebase reference are affected, and they now correctly route to gtm_only_firing for review.

Setup (for users)

1. Enable Tag Manager API v2 in your GCP project (console.cloud.google.com/apis/library/tagmanager.googleapis.com)
2. In Tag Manager → your container → Admin → User Management (Container column, not Account), add your AdLoop credentials' email (the OAuth user email, or the service account email if using a service account) with Read permission
3. Service-account access takes effect on the next API call. OAuth users will need to re-auth to pick up the new scope.

Why no write tools yet

A bad GTM publish has higher blast radius than any Ads write — deleting the GA4 config tag kills all site tracking instantly. The right write surface needs:

• Workspace as the dry-run sandbox (publish is the actual deploy moment, separate tool)
• Optimistic concurrency via fingerprints (someone editing in the GTM UI wins or you abort)
• Reverse-impact preview (modifying a trigger should auto-list every tag using it)
• A separate gtm.allow_publish: false config gate on top of require_dry_run
• Rollback as a first-class one-call tool

Read-only ships first to validate the diagnose-then-recommend pattern. Write tools (draft_gtm_ga4_event_tag, draft_gtm_trigger_change, pause/enable_gtm_tag, publish_gtm_version, rollback_gtm_to_version) are scoped for a follow-up PR.

Test plan

• Full suite passes: uv run pytest → 234 passed (was 184 baseline + 50 new from this PR)
• _summarize_filter renders negate: true as NOT <op> (regression test for the silent meaning-inversion that hand-inspection had missed)
• _resolve_trigger resolves built-in trigger IDs (>= 2147479553) to readable names instead of (unknown)
• _trigger_group_member_ids extracts member IDs from a triggerGroup's parameter list
• _element_visibility_summary handles case-insensitive selectorType (GTM returns "ID" not "id")
• _parse_trigger adds group_member_trigger_ids for triggerGroup, element_visibility for elementVisibility
• audit_event_coverage matrix produces all 10 status codes (one test per code)
• Insights generated for: codebase event with no tag, paused tag, dynamic-event tag, Custom HTML tag
• GA4 error short-circuits the audit gracefully
• Live API smoke tests (manual): list_gtm_accounts, list_gtm_containers, list_gtm_tags, list_gtm_triggers, list_gtm_variables, list_gtm_workspaces, get_gtm_workspace_diff, list_gtm_versions, get_gtm_version, get_gtm_tag, get_gtm_trigger, audit_event_coverage — all verified end-to-end against a real production container
• Service-account auth path: works after enabling Tag Manager API v2 + adding service account email to container with Read permission
• OAuth user auth path: tested code path but not yet validated end-to-end with a fresh OAuth re-auth that picks up the new tagmanager.readonly scope (existing OAuth users would need to delete their token to trigger re-auth)

[illia-sapryga]

Hey @kLOsk, just rebased onto main — MERGEABLE/CLEAN, 312 tests passing on the branch. Is there anything else you'd like from me to get this in — additional tests, doc updates, scope tweaks? Happy to address anything.

[kLOsk]

The parsing layer and tests here are strong; this is merge-track. Needed for v0.10.0: (1) port to current_config() and drop the module-level load_config() (main is deliberately side-effect-free at import); (2) express GTM auth through the CredentialsProvider protocol in auth.py and add the scope to _ALL_SCOPES; (3) one logic gap: an event that is not in the codebase, with only paused GTM tags, while GA4 still fires, falls through to unknown and deserves its own status plus a test; (4) README re-merge plus a note that users must enable the Tag Manager API in their GCP project and re-auth (good news: v0.10 removed bundled credentials, so there is no central verification concern anymore).

[kLOsk]

Merged to main — thank you @illia-sapryga! The read layer and the three-way audit are exactly the kind of capability this project should have; the parsing care in read.py (negate flags, built-in trigger resolution, surfacing dynamic {{Event}} and Custom HTML tags the audit can't see) held up to a deep review.

Rather than another round-trip I applied the four asks from my July comment maintainer-side during the merge:

1. All registrations ported to current_config() (a static CI guard now enforces this repo-wide).
2. GTM auth is expressed through the CredentialsProvider protocol — the local provider implements gtm_credentials() behind the server-mode guard, and providers that don't support GTM produce a clear capability error. tagmanager.readonly is in _ALL_SCOPES.
3. The paused-tags-but-GA4-still-fires gap is now its own status, gtm_paused_but_firing, with an insight and test.
4. README re-merged (61 tools) with an explicit re-auth note for tokens granted before the GTM scope, plus an INSUFFICIENT_SCOPES structured error pointing users at the fix. Rules files gained a GTM inventory + audit orchestration pattern.

This unblocks #35 — please rebase it onto main (the diff should shrink to just the write surface) and see my addendum there for the remaining items.