feat(connectors/google-ads): first-class Google Ads primitives + MCP/HTTP-SSE + Temporal

[ninan-versioning]

Summary

Adds @shoploop/connector-google-ads — the first Performance Ingest source, closing the right half of the architecture loop:

Distribution (Meta / TikTok / Klaviyo) → Performance Ingest (ROAS, CTR, CAC)
→ Thompson Sampling → brand_rules.json → render pack regenerates

Mirrors connectors/shopify (PR #15) exactly: same primitives/ · mcp/ · temporal/ layout, same HTTP/SSE transport, same bearer auth (SHOPLOOP_MCP_TOKEN), same single-internal-core discipline, same Temporal idempotency convention. MCP-shaped and agent-callable — not a thin REST wrapper. Uses google-ads-api (Google Ads API v17, OAuth2 refresh-token flow, env-driven creds).

Stacked on #15. Branched from jared-shoploop/shopify-connector-mcp; until #15 merges, this PR's diff against main includes the Shopify connector. Review only connectors/google-ads/** + the root README connector matrix here. The join helper reuses the Shopify connector's update_metafield write path (injected — no duplicated Shopify client code).

Four primitives

1. Performance ingest — ingestPerformance({ customerId, since, outDir }). GAQL across campaign/ad_group/ad (impressions, clicks, conversions, cost_micros, ctr, average_cpc, derived roas = conversions_value / cost) → one JSONL/day at <outDir>/<customerId>/YYYY-MM-DD.jsonl matching contracts/performance_observation.v1.json. Dedupes by (date, campaign_id, ad_group_id, ad_id). Joins campaign.id ↔ Shopify product.id via the shoploop.gads_campaign_id metafield.
2. MCP tools (HTTP/SSE on :8788) — list_campaigns, get_campaign, get_performance (daily/weekly rollups), get_search_terms (negative-keyword harvesting), get_change_history; write tools pause_campaign / resume_campaign gated behind SHOPLOOP_GADS_WRITE_ENABLED=true (default off, refused otherwise).
3. Brand-rules feedback hook — recordPerformanceForBandit(observation) enqueues to BANDIT_QUEUE_PATH. Thompson Sampling update is stubbed with a clear TODO; the typed PerformanceObservation is the producer/consumer contract so a real bandit drops in without changing the producer side.
4. Scheduled ingest workflow — IngestGoogleAdsPerformanceWorkflow(customerId) (hourly, queries last 25h overlap, flushes observations to the bandit queue) + PauseUnderperformingCampaignWorkflow(customerId, campaignId, reason) (typed entry point, no-op behind the write flag). Worker on task queue shoploop-google-ads; idempotency id gads:<customerId>:<workflow>:<hour_bucket>. CLI worker --once --customer <id> runs the hourly workflow on-demand for dev.

CLI binaries: shoploop-google-ads ingest|mcp|worker.

Decision gate (per AGENTS.md)

1. Varitea dogfood critical path? Yes — Varitea already runs Google Ads; this is the loop's input layer.
2. Deepens the moat? Yes — feeds the Thompson Sampling bandit that drives brand_rules.json; ingest + signal, no commodity ad-buying.
3. Mistral/Codestral cheaper? N/A (no autoresearch call).
4. Ships ≤2 weeks solo? Yes.
5. Monthly cost: ~$0/mo incremental — API free (Basic Access tier), JSONL storage <$1/mo, co-located on the Shopify t4g.small.

Testing

• npm run typecheck — clean.
• npm test — 23 passing across 3 files:
  • primitives.test.ts — ingest emits 7 JSONL files / 56 observations (8/day), contract shape + derived roas, overlap dedup, Shopify join, rollups (daily + Monday-weekly), bandit enqueue, join metafield write.
  • mcp.test.ts — in-proc over MCP transport: all 7 tools listed, each read tool exercised, write tools refused when the flag is off and succeed when on.
  • workflow.test.ts — Temporal hour-bucket idempotency (duplicate hourly fires collapse to one execution under REJECT_DUPLICATE; next hour starts fresh).
• npm run build — emits dist/ (CLI bin → dist/cli.js).

Varitea dogfood acceptance

• shoploop-google-ads ingest --customer 5128873230 --since 2026-06-12 --out ./var/shoploop/perf → JSONL emitted per day under 5128873230/.
• MCP get_performance returns the 7-day daily rollup (and a Monday-keyed weekly rollup) with derived ROAS.

Test plan

• CI typecheck + tests green
• Live smoke against the Varitea customer id once OAuth creds are in the deploy env
• Merge after feat(connectors/shopify): first-class Shopify→USD primitives + MCP/HTTP-SSE + Temporal #15 (Shopify connector) lands

🤖 Generated with Claude Code