adloop 0.13.3__tar.gz → 0.14.0__tar.gz

adloop-0.13.3/README.md → adloop-0.14.0/PKG-INFO

@@ -1,10 +1,37 @@
+Metadata-Version: 2.3
+Name: adloop
+Version: 0.14.0
+Summary: The AI command center for Google Ads, Reddit Ads, GA4, and tracking code.
+Keywords: mcp,google-ads,reddit-ads,google-analytics,ga4,cursor,marketing
+Author: Daniel Klose
+Author-email: Daniel Klose <info@daniel-klose.com>
+License: MIT
+Requires-Dist: fastmcp>=3.0.0
+Requires-Dist: google-ads>=31.1.0
+Requires-Dist: google-analytics-data>=0.20.0
+Requires-Dist: google-analytics-admin>=0.27.0
+Requires-Dist: google-api-python-client>=2.100.0
+Requires-Dist: google-auth-oauthlib>=1.0.0
+Requires-Dist: google-api-python-client>=2.0.0
+Requires-Dist: pyyaml>=6.0
+Requires-Dist: requests>=2.31
+Requires-Dist: pytest>=8.0 ; extra == 'dev'
+Requires-Dist: pytest-asyncio>=0.23 ; extra == 'dev'
+Requires-Python: >=3.11
+Project-URL: Homepage, https://github.com/kLOsk/adloop
+Project-URL: Repository, https://github.com/kLOsk/adloop
+Project-URL: Issues, https://github.com/kLOsk/adloop/issues
+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
 
-**The AI command center for Google Ads, GA4, and tracking code.**
+**The AI command center for Google Ads, Reddit Ads, GA4, and tracking code.**
 
 [![PyPI](https://img.shields.io/pypi/v/adloop.svg)](https://pypi.org/project/adloop/)
 [![License: MIT](https://img.shields.io/badge/License-MIT-blue.svg)](LICENSE)
@@ -14,7 +41,7 @@
 [![GA4 Data API](https://img.shields.io/badge/GA4-Data%20API-E37400.svg?logo=google-analytics&logoColor=white)](https://developers.google.com/analytics/devguides/reporting/data/v1)
 [![GitHub stars](https://img.shields.io/github/stars/kLOsk/adloop?style=social)](https://github.com/kLOsk/adloop)
 
-An MCP server that gives your AI assistant read + write access to Google Ads and GA4 — with safety guardrails that prevent accidental spend.
+An MCP server that gives your AI assistant read + write access to Google Ads, Reddit Ads and GA4 — with safety guardrails that prevent accidental spend.
 
 **[☁️ Skip the setup — use AdLoop Cloud (free plan, no card)](https://getadloop.com)** &nbsp;·&nbsp; or self-host: `pip install adloop`
 
@@ -171,6 +198,27 @@ These tools read the live GTM container and join it with the codebase + GA4 to f
 
 > **Setup for GSC tools** — Enable the **Search Console API** in your GCP project. Upgrading OAuth users must re-authorize once for the new scope (delete `~/.adloop/token.json`, run any tool). The killer combo: cross-reference organic queries with `get_keyword_performance` to find paid/organic cannibalization and untapped keyword opportunities.
 
+### Reddit Ads Tools
+
+A second ad platform, same safety model. Reddit is a separate connection: its own developer app, its own OAuth, no developer token and no approval process. Every tool takes `ad_account_id` (defaults to `reddit.ad_account_id`).
+
+| Tool | What It Does |
+|------|-------------|
+| `list_reddit_accounts` | Discover businesses and ad accounts (currency, time zone, approval state) |
+| `list_reddit_funding_instruments` | Billing instruments and posting profiles — prerequisites for creating campaigns and ads |
+| `get_reddit_campaigns` / `get_reddit_ad_groups` / `get_reddit_ads` | Structure with configured vs effective status, budgets, bids, pixel, targeting, weekly schedule, rejection reasons; `include_copy` returns each ad's post (headline, body, destination, media) |
+| `get_reddit_performance` | Spend, clicks, CTR, CPC, conversions, CPA, ROAS per account/campaign/ad group/ad, optional breakdown (date, country, community, keyword, placement, …), compact mode with insights |
+| `run_reddit_report` | Raw reports endpoint for any metric (REACH, video, per-event conversions) |
+| `get_reddit_pixels` | Pixels and when each event last fired — flags ad groups optimizing for events the pixel never sent |
+| `search_reddit_targeting` | Communities, interests, geolocations, languages, keyword suggestions, and Reddit's related-community suggestions (by seed communities or website) |
+| `get_reddit_account_history` | Who changed what and when: field, before/after, member |
+| `estimate_reddit_ad_group` | Audience size, delivery estimate and suggested bid range for a planned ad group (Reddit's counterpart of `estimate_budget`) |
+| `pause_reddit_entity` / `enable_reddit_entity` / `remove_reddit_entity` | Status changes through the preview gate (remove = ARCHIVE, irreversible, double-confirmed) |
+| `update_reddit_campaign` / `update_reddit_ad_group` / `update_reddit_ad` | Budget, bid, run dates, weekly schedule (day names, viewer-local hours), targeting and placements (validated with Reddit at draft time), landing URL and comment changes with old → new previews, budget cap and bid-increase guards |
+| `draft_reddit_campaign` / `draft_reddit_ad_group` / `draft_reddit_ad` | Create campaign → ad group (pixel + targeting required) → post + ad, or promote an existing post with `post_id`. Everything is created **PAUSED**. |
+
+> **Setup for Reddit Ads tools** — In Reddit Ads Manager open **Business Manager → Developer Application → Create app** (business admins only; no approval wait). Register the redirect URL exactly as `http://localhost:8765/callback`, then run `adloop init` and complete the Reddit Ads step: it opens Reddit's consent page (scopes `adsread` + `adsedit`, permanent grant), stores the refresh token at `~/.adloop/reddit_token.json`, and lets you pick the default ad account. Reddit rate-limits per user (reporting: 60 requests/min) and requires a descriptive User-Agent, which AdLoop builds from your app id and Reddit username. Reddit has no validate-only mode, so `confirm_and_apply(dry_run=true)` re-reads the target and re-checks the safety caps instead.
+
 ### Planning Tools
 
 | Tool | What It Does |
@@ -420,6 +468,10 @@ All configuration lives in `~/.adloop/config.yaml`. See [`config.yaml.example`](
 | `ads` | `developer_token` | — | Your Google Ads API developer token |
 | `ads` | `customer_id` | — | Default Google Ads customer ID (auto-discovered by `adloop init`) |
 | `ads` | `login_customer_id` | — | Your MCC account ID |
+| `reddit` | `client_id` / `client_secret` | *(empty)* | Your Reddit developer app (Business Manager → Developer Application) |
+| `reddit` | `ad_account_id` | *(empty)* | Default Reddit ad account for every Reddit tool (picked by `adloop init`) |
+| `reddit` | `username` | *(empty)* | Your Reddit username, used only in the User-Agent Reddit requires |
+| `reddit` | `token_path` | `~/.adloop/reddit_token.json` | Where the Reddit refresh token is stored |
 | `safety` | `max_daily_budget` | `50.00` | Maximum allowed daily budget per campaign |
 | `safety` | `require_dry_run` | `true` | Force all writes to dry-run mode |
 | `safety` | `two_phase_apply` | `false` | Refuse real applies until the plan had a dry-run pass |
@@ -442,6 +494,7 @@ Most MCP clients (claude.ai, ChatGPT, Cursor, …) load **every tool schema into
 | `gsc` | Search Console reads |
 | `web` | PageSpeed / Core Web Vitals |
 | `merchant` | Merchant Center feed health |
+| `reddit` | Reddit Ads reads, writes, and planning |
 
 `health_check` and `confirm_and_apply` are always included, whatever you select. Unset = the full catalog; unknown names fail at startup with the valid list. The effect is real: `ads,ga4` drops the session cost to ~13k tokens, and a `ga4`-only client pays ~2k — nearly 90% less. Toolsets are per *client*, not per install: one AdLoop config can serve a trimmed Cursor and a full-catalog Claude Code side by side.
 
@@ -452,7 +505,7 @@ On [AdLoop Cloud](https://getadloop.com), the same feature is per API key: pick
 ```
 src/adloop/
 ├── __init__.py        # Entry point — routes 'adloop init' to wizard, otherwise starts MCP server
-├── server.py          # FastMCP server — 67 tool registrations with safety annotations
+├── server.py          # FastMCP server — every tool registration with safety annotations and toolset tags
 ├── config.py          # Config loader (~/.adloop/config.yaml)
 ├── auth.py            # OAuth 2.0 flow (user-supplied credentials, headless fallback) + service accounts; GA4 / Ads / GTM scopes
 ├── cli.py             # Interactive 'adloop init' setup wizard
@@ -472,6 +525,11 @@ src/adloop/
 ├── gtm/
 │   ├── client.py      # Google Tag Manager API v2 client
 │   └── read.py        # Live container fetching, tag/trigger/variable parsing, workspace diff, version history
+├── reddit/
+│   ├── auth.py        # Reddit OAuth2 (own app, permanent refresh token, loopback flow for adloop init)
+│   ├── client.py      # Reddit Ads API v3 REST client — bearer refresh, per-user rate limits, pagination
+│   ├── read.py        # Accounts, campaigns, ad groups, ads, performance reports, pixels, targeting lookups
+│   └── write.py       # Draft/preflight/apply for status, budget, bid, targeting, and PAUSED creation
 └── safety/
     ├── guards.py      # Budget caps, bid limits, blocked operations, Broad Match safety
     ├── preview.py     # Change plans and previews

adloop-0.13.3/PKG-INFO → adloop-0.14.0/README.md

@@ -1,36 +1,10 @@
-Metadata-Version: 2.3
-Name: adloop
-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
-Author-email: Daniel Klose <info@daniel-klose.com>
-License: MIT
-Requires-Dist: fastmcp>=3.0.0
-Requires-Dist: google-ads>=31.1.0
-Requires-Dist: google-analytics-data>=0.20.0
-Requires-Dist: google-analytics-admin>=0.27.0
-Requires-Dist: google-api-python-client>=2.100.0
-Requires-Dist: google-auth-oauthlib>=1.0.0
-Requires-Dist: google-api-python-client>=2.0.0
-Requires-Dist: pyyaml>=6.0
-Requires-Dist: pytest>=8.0 ; extra == 'dev'
-Requires-Dist: pytest-asyncio>=0.23 ; extra == 'dev'
-Requires-Python: >=3.11
-Project-URL: Homepage, https://github.com/kLOsk/adloop
-Project-URL: Repository, https://github.com/kLOsk/adloop
-Project-URL: Issues, https://github.com/kLOsk/adloop/issues
-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
 
-**The AI command center for Google Ads, GA4, and tracking code.**
+**The AI command center for Google Ads, Reddit Ads, GA4, and tracking code.**
 
 [![PyPI](https://img.shields.io/pypi/v/adloop.svg)](https://pypi.org/project/adloop/)
 [![License: MIT](https://img.shields.io/badge/License-MIT-blue.svg)](LICENSE)
@@ -40,7 +14,7 @@ Description-Content-Type: text/markdown
 [![GA4 Data API](https://img.shields.io/badge/GA4-Data%20API-E37400.svg?logo=google-analytics&logoColor=white)](https://developers.google.com/analytics/devguides/reporting/data/v1)
 [![GitHub stars](https://img.shields.io/github/stars/kLOsk/adloop?style=social)](https://github.com/kLOsk/adloop)
 
-An MCP server that gives your AI assistant read + write access to Google Ads and GA4 — with safety guardrails that prevent accidental spend.
+An MCP server that gives your AI assistant read + write access to Google Ads, Reddit Ads and GA4 — with safety guardrails that prevent accidental spend.
 
 **[☁️ Skip the setup — use AdLoop Cloud (free plan, no card)](https://getadloop.com)** &nbsp;·&nbsp; or self-host: `pip install adloop`
 
@@ -197,6 +171,27 @@ These tools read the live GTM container and join it with the codebase + GA4 to f
 
 > **Setup for GSC tools** — Enable the **Search Console API** in your GCP project. Upgrading OAuth users must re-authorize once for the new scope (delete `~/.adloop/token.json`, run any tool). The killer combo: cross-reference organic queries with `get_keyword_performance` to find paid/organic cannibalization and untapped keyword opportunities.
 
+### Reddit Ads Tools
+
+A second ad platform, same safety model. Reddit is a separate connection: its own developer app, its own OAuth, no developer token and no approval process. Every tool takes `ad_account_id` (defaults to `reddit.ad_account_id`).
+
+| Tool | What It Does |
+|------|-------------|
+| `list_reddit_accounts` | Discover businesses and ad accounts (currency, time zone, approval state) |
+| `list_reddit_funding_instruments` | Billing instruments and posting profiles — prerequisites for creating campaigns and ads |
+| `get_reddit_campaigns` / `get_reddit_ad_groups` / `get_reddit_ads` | Structure with configured vs effective status, budgets, bids, pixel, targeting, weekly schedule, rejection reasons; `include_copy` returns each ad's post (headline, body, destination, media) |
+| `get_reddit_performance` | Spend, clicks, CTR, CPC, conversions, CPA, ROAS per account/campaign/ad group/ad, optional breakdown (date, country, community, keyword, placement, …), compact mode with insights |
+| `run_reddit_report` | Raw reports endpoint for any metric (REACH, video, per-event conversions) |
+| `get_reddit_pixels` | Pixels and when each event last fired — flags ad groups optimizing for events the pixel never sent |
+| `search_reddit_targeting` | Communities, interests, geolocations, languages, keyword suggestions, and Reddit's related-community suggestions (by seed communities or website) |
+| `get_reddit_account_history` | Who changed what and when: field, before/after, member |
+| `estimate_reddit_ad_group` | Audience size, delivery estimate and suggested bid range for a planned ad group (Reddit's counterpart of `estimate_budget`) |
+| `pause_reddit_entity` / `enable_reddit_entity` / `remove_reddit_entity` | Status changes through the preview gate (remove = ARCHIVE, irreversible, double-confirmed) |
+| `update_reddit_campaign` / `update_reddit_ad_group` / `update_reddit_ad` | Budget, bid, run dates, weekly schedule (day names, viewer-local hours), targeting and placements (validated with Reddit at draft time), landing URL and comment changes with old → new previews, budget cap and bid-increase guards |
+| `draft_reddit_campaign` / `draft_reddit_ad_group` / `draft_reddit_ad` | Create campaign → ad group (pixel + targeting required) → post + ad, or promote an existing post with `post_id`. Everything is created **PAUSED**. |
+
+> **Setup for Reddit Ads tools** — In Reddit Ads Manager open **Business Manager → Developer Application → Create app** (business admins only; no approval wait). Register the redirect URL exactly as `http://localhost:8765/callback`, then run `adloop init` and complete the Reddit Ads step: it opens Reddit's consent page (scopes `adsread` + `adsedit`, permanent grant), stores the refresh token at `~/.adloop/reddit_token.json`, and lets you pick the default ad account. Reddit rate-limits per user (reporting: 60 requests/min) and requires a descriptive User-Agent, which AdLoop builds from your app id and Reddit username. Reddit has no validate-only mode, so `confirm_and_apply(dry_run=true)` re-reads the target and re-checks the safety caps instead.
+
 ### Planning Tools
 
 | Tool | What It Does |
@@ -446,6 +441,10 @@ All configuration lives in `~/.adloop/config.yaml`. See [`config.yaml.example`](
 | `ads` | `developer_token` | — | Your Google Ads API developer token |
 | `ads` | `customer_id` | — | Default Google Ads customer ID (auto-discovered by `adloop init`) |
 | `ads` | `login_customer_id` | — | Your MCC account ID |
+| `reddit` | `client_id` / `client_secret` | *(empty)* | Your Reddit developer app (Business Manager → Developer Application) |
+| `reddit` | `ad_account_id` | *(empty)* | Default Reddit ad account for every Reddit tool (picked by `adloop init`) |
+| `reddit` | `username` | *(empty)* | Your Reddit username, used only in the User-Agent Reddit requires |
+| `reddit` | `token_path` | `~/.adloop/reddit_token.json` | Where the Reddit refresh token is stored |
 | `safety` | `max_daily_budget` | `50.00` | Maximum allowed daily budget per campaign |
 | `safety` | `require_dry_run` | `true` | Force all writes to dry-run mode |
 | `safety` | `two_phase_apply` | `false` | Refuse real applies until the plan had a dry-run pass |
@@ -468,6 +467,7 @@ Most MCP clients (claude.ai, ChatGPT, Cursor, …) load **every tool schema into
 | `gsc` | Search Console reads |
 | `web` | PageSpeed / Core Web Vitals |
 | `merchant` | Merchant Center feed health |
+| `reddit` | Reddit Ads reads, writes, and planning |
 
 `health_check` and `confirm_and_apply` are always included, whatever you select. Unset = the full catalog; unknown names fail at startup with the valid list. The effect is real: `ads,ga4` drops the session cost to ~13k tokens, and a `ga4`-only client pays ~2k — nearly 90% less. Toolsets are per *client*, not per install: one AdLoop config can serve a trimmed Cursor and a full-catalog Claude Code side by side.
 
@@ -478,7 +478,7 @@ On [AdLoop Cloud](https://getadloop.com), the same feature is per API key: pick
 ```
 src/adloop/
 ├── __init__.py        # Entry point — routes 'adloop init' to wizard, otherwise starts MCP server
-├── server.py          # FastMCP server — 67 tool registrations with safety annotations
+├── server.py          # FastMCP server — every tool registration with safety annotations and toolset tags
 ├── config.py          # Config loader (~/.adloop/config.yaml)
 ├── auth.py            # OAuth 2.0 flow (user-supplied credentials, headless fallback) + service accounts; GA4 / Ads / GTM scopes
 ├── cli.py             # Interactive 'adloop init' setup wizard
@@ -498,6 +498,11 @@ src/adloop/
 ├── gtm/
 │   ├── client.py      # Google Tag Manager API v2 client
 │   └── read.py        # Live container fetching, tag/trigger/variable parsing, workspace diff, version history
+├── reddit/
+│   ├── auth.py        # Reddit OAuth2 (own app, permanent refresh token, loopback flow for adloop init)
+│   ├── client.py      # Reddit Ads API v3 REST client — bearer refresh, per-user rate limits, pagination
+│   ├── read.py        # Accounts, campaigns, ad groups, ads, performance reports, pixels, targeting lookups
+│   └── write.py       # Draft/preflight/apply for status, budget, bid, targeting, and PAUSED creation
 └── safety/
     ├── guards.py      # Budget caps, bid limits, blocked operations, Broad Match safety
     ├── preview.py     # Change plans and previews

{adloop-0.13.3 → adloop-0.14.0}/pyproject.toml

@@ -1,12 +1,13 @@
 [project]
 name = "adloop"
-version = "0.13.3"
-description = "The AI command center for Google Ads, GA4, and tracking code."
+version = "0.14.0"
+description = "The AI command center for Google Ads, Reddit Ads, GA4, and tracking code."
 readme = "README.md"
 requires-python = ">=3.11"
 keywords = [
     "mcp",
     "google-ads",
+    "reddit-ads",
     "google-analytics",
     "ga4",
     "cursor",
@@ -21,6 +22,7 @@ dependencies = [
     "google-auth-oauthlib>=1.0.0",
     "google-api-python-client>=2.0.0",
     "pyyaml>=6.0",
+    "requests>=2.31",
 ]
 
 [[project.authors]]

{adloop-0.13.3 → adloop-0.14.0}/pyproject.toml.orig

@@ -1,14 +1,14 @@
 [project]
 name = "adloop"
-version = "0.13.3"
-description = "The AI command center for Google Ads, GA4, and tracking code."
+version = "0.14.0"
+description = "The AI command center for Google Ads, Reddit Ads, GA4, and tracking code."
 readme = "README.md"
 authors = [
     { name = "Daniel Klose", email = "info@daniel-klose.com" }
 ]
 requires-python = ">=3.11"
 license = { text = "MIT" }
-keywords = ["mcp", "google-ads", "google-analytics", "ga4", "cursor", "marketing"]
+keywords = ["mcp", "google-ads", "reddit-ads", "google-analytics", "ga4", "cursor", "marketing"]
 dependencies = [
     "fastmcp>=3.0.0",
     "google-ads>=31.1.0",
@@ -18,6 +18,9 @@ dependencies = [
     "google-auth-oauthlib>=1.0.0",
     "google-api-python-client>=2.0.0",
     "pyyaml>=6.0",
+    # Reddit Ads has no SDK; the REST client (adloop.reddit.client) and the
+    # PageSpeed helper call requests directly.
+    "requests>=2.31",
 ]
 
 [project.urls]