adloop 0.8.1__tar.gz → 0.9.0__tar.gz

{adloop-0.8.1 → adloop-0.9.0}/PKG-INFO

@@ -1,7 +1,7 @@
 Metadata-Version: 2.3
 Name: adloop
-Version: 0.8.1
-Summary: Stop switching between Google Ads, GA4, and your code editor to figure out why conversions dropped.
+Version: 0.9.0
+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>
@@ -26,7 +26,7 @@ Description-Content-Type: text/markdown
 
 # AdLoop
 
-**Stop switching between Google Ads, GA4, and your code editor to figure out why conversions dropped.**
+**The AI command center for Google 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)
@@ -196,16 +196,23 @@ AdLoop manages real ad spend, so safety is not optional.
 
 ## Setup
 
-### Quick Start (Recommended)
+> **⚠️ Built-in OAuth credentials are temporarily unavailable while Google verification is pending.**
+> Google limits unverified OAuth apps to 100 users, and AdLoop has reached that cap. New users will see a **"This app is blocked"** error if they pick the built-in option in the wizard.
+>
+> **What this means for you:** until Google completes verification, **bring your own Google Cloud project** — it takes ~5 minutes, has no user cap, and the `adloop init` wizard guides you through it. Status updates: [Discussion #13](https://github.com/kLOsk/adloop/discussions/13).
+>
+> *(Existing users whose tokens were already issued before the cap continue to work — only first-time sign-ins are blocked.)*
+
+### Install
 
-**Option A — Install from PyPI:**
+**From PyPI:**
 
 ```bash
 pip install adloop
 adloop init
 ```
 
-**Option B — Install from source:**
+**From source:**
 
 ```bash
 git clone https://github.com/kLOsk/adloop.git
@@ -214,21 +221,19 @@ uv sync
 uv run adloop init
 ```
 
-The `adloop init` wizard walks you through everything. AdLoop ships with built-in Google OAuth credentials, so you don't need to create a Google Cloud project.
+### What `adloop init` does
 
-> **⚠️ Built-in credentials temporarily unavailable — Google verification pending.**
-> Google limits unverified OAuth apps to 100 users. AdLoop has reached that cap while awaiting Google's app verification. Until verification is complete, the built-in credentials will show a **"This app is blocked"** error for new users.
->
-> **Workaround:** set up your own Google Cloud project using the [Advanced Setup](#advanced-setup-custom-google-cloud-project) instructions below (takes ~5 minutes). Your own project has no user cap and is the recommended setup path in the meantime.
+The wizard defaults to the "bring your own Google Cloud project" path while verification is pending. It walks you through:
 
-The wizard:
+1. **Google Cloud setup** — creates a project, enables the three APIs, generates an OAuth client (see [Custom Google Cloud Project Setup](#custom-google-cloud-project-setup) below for the exact steps the wizard refers you to)
+2. **Developer token** — from your Google Ads MCC ([API Center](https://ads.google.com/aw/apicenter))
+3. **MCC Account ID** — your Manager Account ID (top bar in the MCC UI)
+4. **OAuth sign-in** — opens a browser to sign in with Google (or prints a URL for headless servers)
+5. **Auto-discovers your accounts** — finds your GA4 properties and Ads accounts automatically
+6. **Safety defaults** — budget cap and dry-run preference
+7. **Editor config snippets** — prints MCP configuration for both Cursor and Claude Code
 
-1. **Developer token** — from your Google Ads MCC ([API Center](https://ads.google.com/aw/apicenter))
-2. **MCC Account ID** — your Manager Account ID (top bar in the MCC UI)
-3. **OAuth sign-in** — opens a browser to sign in with Google (or prints a URL for headless servers)
-4. **Auto-discovers your accounts** — finds your GA4 properties and Ads accounts automatically
-5. **Safety defaults** — budget cap and dry-run preference
-6. **Editor config snippets** — prints MCP configuration for both Cursor and Claude Code
+The wizard does still offer AdLoop's built-in credentials as a non-default option for existing users whose tokens predate the cap. Picking that option for a brand-new Google account will fail at the consent screen — the wizard warns you about this before you choose.
 
 ### Requirements
 
@@ -258,12 +263,9 @@ A developer token is **always required** — even when using AdLoop's built-in O
 
 Running on a server without a browser (VMs, Docker, SSH)? The wizard automatically detects this and falls back to a manual flow: it prints an authorization URL you can open on any device, then you paste the redirect URL back into the terminal.
 
-### Advanced Setup (Custom Google Cloud Project)
-
-<details>
-<summary>Click to expand — only needed if you want to use your own GCP project instead of AdLoop's built-in credentials</summary>
+### Custom Google Cloud Project Setup
 
-When you run `adloop init`, choose "No" when asked about built-in credentials. The wizard will guide you through:
+This is the default path while built-in credentials are blocked by Google's 100-user cap. The wizard refers to these steps — do them in your browser before running `adloop init` (or while it waits at the OAuth prompt).
 
 #### Step 1 — Google Cloud Project
 
@@ -335,8 +337,6 @@ If you'd rather manage things by hand instead, copy `.claude/rules/adloop.md` an
 
 **Claude Desktop / claude.ai** has no programmatic rules location. Run `adloop install-rules` and it will print the rules content for you to paste into Project settings → Custom instructions on claude.ai.
 
-</details>
-
 ### Use It
 
 Ask your AI assistant things like:
@@ -411,7 +411,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`
-- ~~Bundled OAuth credentials~~ ✓ — no Google Cloud project required, auto-discovery of GA4/Ads accounts (currently capped at 100 users pending Google verification — use [Advanced Setup](#advanced-setup-custom-google-cloud-project) in the meantime)
+- ~~Bundled OAuth credentials~~ ✓ — no Google Cloud project required (**currently blocked at 100-user cap** pending Google verification; `adloop init` defaults to the [Custom Google Cloud Project Setup](#custom-google-cloud-project-setup) path until verification completes)
 - ~~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
 - **Community launch** — HN, Indie Hackers, r/cursor, Twitter
@@ -433,7 +433,7 @@ AdLoop runs entirely on your machine. No data is collected, stored, or transmitt
 
 <div align="center">
 
-**If AdLoop saves you from switching between Google Ads, GA4, and your code editor — [give it a star](https://github.com/kLOsk/adloop).**
+**If AdLoop helps you run Google Ads, GA4, and tracking code from one place — [give it a star](https://github.com/kLOsk/adloop).**
 
 Made by [@kLOsk](https://github.com/kLOsk) | [Privacy Policy](PRIVACY.md)
 

{adloop-0.8.1 → adloop-0.9.0}/README.md

@@ -2,7 +2,7 @@
 
 # AdLoop
 
-**Stop switching between Google Ads, GA4, and your code editor to figure out why conversions dropped.**
+**The AI command center for Google 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)
@@ -172,16 +172,23 @@ AdLoop manages real ad spend, so safety is not optional.
 
 ## Setup
 
-### Quick Start (Recommended)
+> **⚠️ Built-in OAuth credentials are temporarily unavailable while Google verification is pending.**
+> Google limits unverified OAuth apps to 100 users, and AdLoop has reached that cap. New users will see a **"This app is blocked"** error if they pick the built-in option in the wizard.
+>
+> **What this means for you:** until Google completes verification, **bring your own Google Cloud project** — it takes ~5 minutes, has no user cap, and the `adloop init` wizard guides you through it. Status updates: [Discussion #13](https://github.com/kLOsk/adloop/discussions/13).
+>
+> *(Existing users whose tokens were already issued before the cap continue to work — only first-time sign-ins are blocked.)*
+
+### Install
 
-**Option A — Install from PyPI:**
+**From PyPI:**
 
 ```bash
 pip install adloop
 adloop init
 ```
 
-**Option B — Install from source:**
+**From source:**
 
 ```bash
 git clone https://github.com/kLOsk/adloop.git
@@ -190,21 +197,19 @@ uv sync
 uv run adloop init
 ```
 
-The `adloop init` wizard walks you through everything. AdLoop ships with built-in Google OAuth credentials, so you don't need to create a Google Cloud project.
+### What `adloop init` does
 
-> **⚠️ Built-in credentials temporarily unavailable — Google verification pending.**
-> Google limits unverified OAuth apps to 100 users. AdLoop has reached that cap while awaiting Google's app verification. Until verification is complete, the built-in credentials will show a **"This app is blocked"** error for new users.
->
-> **Workaround:** set up your own Google Cloud project using the [Advanced Setup](#advanced-setup-custom-google-cloud-project) instructions below (takes ~5 minutes). Your own project has no user cap and is the recommended setup path in the meantime.
+The wizard defaults to the "bring your own Google Cloud project" path while verification is pending. It walks you through:
 
-The wizard:
+1. **Google Cloud setup** — creates a project, enables the three APIs, generates an OAuth client (see [Custom Google Cloud Project Setup](#custom-google-cloud-project-setup) below for the exact steps the wizard refers you to)
+2. **Developer token** — from your Google Ads MCC ([API Center](https://ads.google.com/aw/apicenter))
+3. **MCC Account ID** — your Manager Account ID (top bar in the MCC UI)
+4. **OAuth sign-in** — opens a browser to sign in with Google (or prints a URL for headless servers)
+5. **Auto-discovers your accounts** — finds your GA4 properties and Ads accounts automatically
+6. **Safety defaults** — budget cap and dry-run preference
+7. **Editor config snippets** — prints MCP configuration for both Cursor and Claude Code
 
-1. **Developer token** — from your Google Ads MCC ([API Center](https://ads.google.com/aw/apicenter))
-2. **MCC Account ID** — your Manager Account ID (top bar in the MCC UI)
-3. **OAuth sign-in** — opens a browser to sign in with Google (or prints a URL for headless servers)
-4. **Auto-discovers your accounts** — finds your GA4 properties and Ads accounts automatically
-5. **Safety defaults** — budget cap and dry-run preference
-6. **Editor config snippets** — prints MCP configuration for both Cursor and Claude Code
+The wizard does still offer AdLoop's built-in credentials as a non-default option for existing users whose tokens predate the cap. Picking that option for a brand-new Google account will fail at the consent screen — the wizard warns you about this before you choose.
 
 ### Requirements
 
@@ -234,12 +239,9 @@ A developer token is **always required** — even when using AdLoop's built-in O
 
 Running on a server without a browser (VMs, Docker, SSH)? The wizard automatically detects this and falls back to a manual flow: it prints an authorization URL you can open on any device, then you paste the redirect URL back into the terminal.
 
-### Advanced Setup (Custom Google Cloud Project)
-
-<details>
-<summary>Click to expand — only needed if you want to use your own GCP project instead of AdLoop's built-in credentials</summary>
+### Custom Google Cloud Project Setup
 
-When you run `adloop init`, choose "No" when asked about built-in credentials. The wizard will guide you through:
+This is the default path while built-in credentials are blocked by Google's 100-user cap. The wizard refers to these steps — do them in your browser before running `adloop init` (or while it waits at the OAuth prompt).
 
 #### Step 1 — Google Cloud Project
 
@@ -311,8 +313,6 @@ If you'd rather manage things by hand instead, copy `.claude/rules/adloop.md` an
 
 **Claude Desktop / claude.ai** has no programmatic rules location. Run `adloop install-rules` and it will print the rules content for you to paste into Project settings → Custom instructions on claude.ai.
 
-</details>
-
 ### Use It
 
 Ask your AI assistant things like:
@@ -387,7 +387,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`
-- ~~Bundled OAuth credentials~~ ✓ — no Google Cloud project required, auto-discovery of GA4/Ads accounts (currently capped at 100 users pending Google verification — use [Advanced Setup](#advanced-setup-custom-google-cloud-project) in the meantime)
+- ~~Bundled OAuth credentials~~ ✓ — no Google Cloud project required (**currently blocked at 100-user cap** pending Google verification; `adloop init` defaults to the [Custom Google Cloud Project Setup](#custom-google-cloud-project-setup) path until verification completes)
 - ~~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
 - **Community launch** — HN, Indie Hackers, r/cursor, Twitter
@@ -409,7 +409,7 @@ AdLoop runs entirely on your machine. No data is collected, stored, or transmitt
 
 <div align="center">
 
-**If AdLoop saves you from switching between Google Ads, GA4, and your code editor — [give it a star](https://github.com/kLOsk/adloop).**
+**If AdLoop helps you run Google Ads, GA4, and tracking code from one place — [give it a star](https://github.com/kLOsk/adloop).**
 
 Made by [@kLOsk](https://github.com/kLOsk) | [Privacy Policy](PRIVACY.md)
 

{adloop-0.8.1 → adloop-0.9.0}/pyproject.toml

@@ -1,7 +1,7 @@
 [project]
 name = "adloop"
-version = "0.8.1"
-description = "Stop switching between Google Ads, GA4, and your code editor to figure out why conversions dropped."
+version = "0.9.0"
+description = "The AI command center for Google Ads, GA4, and tracking code."
 readme = "README.md"
 authors = [
     { name = "Daniel Klose", email = "info@daniel-klose.com" }

{adloop-0.8.1 → adloop-0.9.0}/src/adloop/__init__.py

@@ -2,7 +2,7 @@
 
 import sys
 
-__version__ = "0.8.1"
+__version__ = "0.9.0"
 
 
 def main() -> None:

{adloop-0.8.1 → adloop-0.9.0}/src/adloop/ads/forecast.py

@@ -98,30 +98,43 @@ def estimate_budget(
     response = kp_service.generate_keyword_forecast_metrics(request=request)
     metrics = response.campaign_forecast_metrics
 
+    # KeywordForecastMetrics fields are ``optional`` in v23, so the SDK
+    # returns ``None`` for unset fields and the actual integer (including
+    # 0) otherwise. Falsy checks like ``int(v) if v else None`` would
+    # silently map a real 0-click or 0-cost forecast to None and the
+    # caller couldn't tell "no data" apart from "data says zero" — same
+    # bug class as discover_keywords (issue Bug 2). Use ``is not None``
+    # throughout and the shared ``_micros_to_currency`` helper for the
+    # micros→currency conversions.
     clicks = getattr(metrics, "clicks", None)
     impressions = getattr(metrics, "impressions", None)
     avg_cpc_micros = getattr(metrics, "average_cpc_micros", None)
     cost_micros = getattr(metrics, "cost_micros", None)
     ctr = getattr(metrics, "click_through_rate", None)
 
-    total_cost = round(cost_micros / 1_000_000, 2) if cost_micros else None
-    avg_cpc = round(avg_cpc_micros / 1_000_000, 2) if avg_cpc_micros else None
+    total_cost = _micros_to_currency(cost_micros)
+    avg_cpc = _micros_to_currency(avg_cpc_micros)
 
     days = max(forecast_days, 1)
     daily = {
-        "clicks": round(clicks / days, 1) if clicks else None,
-        "impressions": round(impressions / days, 1) if impressions else None,
-        "cost": round(total_cost / days, 2) if total_cost else None,
+        "clicks": round(clicks / days, 1) if clicks is not None else None,
+        "impressions": (
+            round(impressions / days, 1) if impressions is not None else None
+        ),
+        "cost": round(total_cost / days, 2) if total_cost is not None else None,
     }
 
     insights = []
+    # Only emit the headline insight when there's actually something to
+    # report (real clicks AND real cost) — a zero-click forecast gets its
+    # own dedicated insight below, and a None forecast shouldn't trigger
+    # either path.
     if total_cost is not None and clicks is not None and clicks > 0:
-        effective_cpa_budget = total_cost / clicks * 10
         insights.append(
             f"Estimated {clicks:.0f} clicks over {forecast_days} days at "
             f"~{avg_cpc} avg CPC. Total estimated cost: {total_cost:.2f}."
         )
-    if daily_budget > 0 and daily["cost"] is not None:
+    if daily_budget > 0 and daily["cost"] is not None and daily["cost"] > 0:
         if daily_budget < daily["cost"]:
             capture_pct = round(daily_budget / daily["cost"] * 100)
             insights.append(
@@ -134,7 +147,12 @@ def estimate_budget(
                 f"most available traffic (estimated daily cost: {daily['cost']:.2f})."
             )
 
-    if impressions is not None and clicks is not None and impressions > 0 and clicks == 0:
+    if (
+        impressions is not None
+        and clicks is not None
+        and impressions > 0
+        and clicks == 0
+    ):
         insights.append(
             "Forecast shows impressions but zero clicks — keywords may be too "
             "generic or CPCs too low for competitive positions."
@@ -149,7 +167,7 @@ def estimate_budget(
         "estimated_impressions": impressions,
         "estimated_cost": total_cost,
         "estimated_avg_cpc": avg_cpc,
-        "estimated_ctr": round(ctr, 4) if ctr else None,
+        "estimated_ctr": round(ctr, 4) if ctr is not None else None,
         "daily_estimates": daily,
         "keywords_used": len([kw for kw in keywords if kw.get("text")]),
         "insights": insights,

{adloop-0.8.1 → adloop-0.9.0}/src/adloop/cli.py

@@ -319,12 +319,33 @@ def run_init_wizard() -> None:
         return fallback
 
     # Step 1: Credentials mode
+    #
+    # We used to default to AdLoop's bundled OAuth credentials (zero-GCP
+    # setup, "Use built-in credentials? (recommended)" Y/N with Y as default).
+    # That stopped being safe once Google's 100-user cap on unverified OAuth
+    # apps was reached — new users picking the bundled option now hit a
+    # "This app is blocked" error at the consent screen, leaving them
+    # stranded mid-wizard with no path forward.
+    #
+    # Until Google completes verification, the wizard defaults to the
+    # "bring your own Google Cloud project" path (which has no cap and
+    # works immediately) and only offers the bundled path as an opt-in
+    # for existing users whose tokens predate the cap. We surface the
+    # status explicitly so people understand WHY the default flipped
+    # rather than wondering whether the wizard is broken.
     _step_header(1, "Google Credentials")
-    _print("  AdLoop includes built-in Google OAuth credentials so you")
-    _print("  don't need to create your own Google Cloud project.")
+    _print("  ⚠  AdLoop's built-in Google OAuth is currently blocked at")
+    _print("     Google's 100-user cap (pending OAuth verification).")
+    _print("     New sign-ins will fail with \"This app is blocked\".")
+    _print("     Status: https://github.com/kLOsk/adloop/discussions/13")
+    _print()
+    _print("  The wizard will set you up with your own Google Cloud")
+    _print("  project instead — takes ~5 minutes, no cap, works today.")
     _print()
     use_bundled = _prompt_bool(
-        "Use built-in credentials? (recommended)", default=True
+        "Use built-in credentials anyway? (only works if you already "
+        "authorized AdLoop before the cap)",
+        default=False,
     )
 
     credentials_path = ""