adloop 0.1.0__py3-none-any.whl

adloop/auth.py

@@ -0,0 +1,132 @@
+"""Google API authentication — OAuth 2.0 and service account support."""
+
+from __future__ import annotations
+
+from pathlib import Path
+from typing import TYPE_CHECKING
+
+if TYPE_CHECKING:
+    from google.auth.credentials import Credentials
+
+    from adloop.config import AdLoopConfig
+
+# Request all scopes in a single OAuth flow so one token works for both
+# GA4 and Google Ads. Without this, separate tokens would constantly
+# overwrite each other at the same token_path.
+_ALL_SCOPES = [
+    "https://www.googleapis.com/auth/analytics.readonly",
+    "https://www.googleapis.com/auth/analytics.edit",
+    "https://www.googleapis.com/auth/adwords",
+]
+
+_GA4_SCOPES = [
+    "https://www.googleapis.com/auth/analytics.readonly",
+    "https://www.googleapis.com/auth/analytics.edit",
+]
+
+_ADS_SCOPES = [
+    "https://www.googleapis.com/auth/adwords",
+]
+
+
+def get_ga4_credentials(config: AdLoopConfig) -> Credentials:
+    """Return authenticated credentials for GA4 APIs."""
+    creds_path = Path(config.google.credentials_path).expanduser()
+
+    if creds_path.exists():
+        import json
+
+        with open(creds_path) as f:
+            creds_info = json.load(f)
+
+        if creds_info.get("type") == "service_account":
+            from google.oauth2 import service_account
+
+            return service_account.Credentials.from_service_account_file(
+                str(creds_path),
+                scopes=_GA4_SCOPES,
+            )
+
+        return _oauth_flow(config)
+
+    import google.auth
+
+    credentials, _ = google.auth.default(scopes=_GA4_SCOPES)
+    return credentials
+
+
+def get_ads_credentials(config: AdLoopConfig) -> Credentials:
+    """Return authenticated credentials for Google Ads API."""
+    creds_path = Path(config.google.credentials_path).expanduser()
+
+    if creds_path.exists():
+        import json
+
+        with open(creds_path) as f:
+            creds_info = json.load(f)
+
+        if creds_info.get("type") == "service_account":
+            from google.oauth2 import service_account
+
+            return service_account.Credentials.from_service_account_file(
+                str(creds_path),
+                scopes=_ADS_SCOPES,
+            )
+
+        return _oauth_flow(config)
+
+    import google.auth
+
+    credentials, _ = google.auth.default(scopes=_ADS_SCOPES)
+    return credentials
+
+
+def _oauth_flow(config: AdLoopConfig) -> Credentials:
+    """Run OAuth Desktop flow requesting all scopes (GA4 + Ads).
+
+    Uses a single token file for all scopes to avoid conflicts between
+    GA4 and Ads auth sharing the same token_path.
+    """
+    from google.auth.transport.requests import Request
+    from google.oauth2.credentials import Credentials as OAuthCredentials
+    from google_auth_oauthlib.flow import InstalledAppFlow
+
+    token_path = Path(config.google.token_path).expanduser()
+    creds_path = Path(config.google.credentials_path).expanduser()
+
+    creds = None
+    if token_path.exists():
+        creds = OAuthCredentials.from_authorized_user_file(
+            str(token_path), _ALL_SCOPES
+        )
+
+    if creds and creds.valid:
+        return creds
+
+    if creds and creds.expired and creds.refresh_token:
+        try:
+            creds.refresh(Request())
+        except Exception as exc:
+            err_str = str(exc).lower()
+            if "revoked" in err_str or "invalid_grant" in err_str:
+                token_path.unlink(missing_ok=True)
+                raise RuntimeError(
+                    "OAuth token has been revoked or expired. "
+                    "This typically happens when the Google Cloud consent screen "
+                    "is in 'Testing' mode (tokens expire after 7 days). "
+                    "Fix: (1) re-run any AdLoop tool to trigger re-authorization, "
+                    "(2) publish the consent screen to 'In production' in Google "
+                    "Cloud Console to prevent future expiry."
+                ) from exc
+            raise
+    else:
+        flow = InstalledAppFlow.from_client_secrets_file(
+            str(creds_path), _ALL_SCOPES
+        )
+        creds = flow.run_local_server(port=0)
+
+    token_path.parent.mkdir(parents=True, exist_ok=True)
+    with open(token_path, "w") as f:
+        f.write(creds.to_json())
+
+    return creds

adloop/cli.py

@@ -0,0 +1,375 @@
+"""Interactive setup wizard for first-time AdLoop configuration."""
+
+from __future__ import annotations
+
+import re
+import sys
+import textwrap
+from pathlib import Path
+
+_ADLOOP_DIR = Path.home() / ".adloop"
+_CONFIG_PATH = _ADLOOP_DIR / "config.yaml"
+
+_GOOGLE_CLOUD_INSTRUCTIONS = """\
+┌─────────────────────────────────────────────────────────────────┐
+│  Google Cloud Setup Checklist                                   │
+│                                                                 │
+│  Complete these steps in your browser before continuing:        │
+│                                                                 │
+│  1. Create (or select) a Google Cloud project                   │
+│     → https://console.cloud.google.com/projectcreate            │
+│                                                                 │
+│  2. Enable these APIs:                                          │
+│     • Google Analytics Data API                                 │
+│     • Google Analytics Admin API                                │
+│     • Google Ads API                                            │
+│     → https://console.cloud.google.com/apis/library             │
+│                                                                 │
+│  3. Create an OAuth consent screen (External, Testing mode OK)  │
+│     → https://console.cloud.google.com/apis/credentials/consent │
+│     Add your email as a test user.                              │
+│                                                                 │
+│  4. Create OAuth 2.0 Client ID (Desktop application)            │
+│     → https://console.cloud.google.com/apis/credentials         │
+│     Download the JSON file.                                     │
+│                                                                 │
+│  5. Get your Google Ads Developer Token from your MCC account   │
+│     → https://ads.google.com/aw/apicenter                      │
+│     (You need a Manager Account / MCC)                          │
+└─────────────────────────────────────────────────────────────────┘
+"""
+
+
+def _print(msg: str = "") -> None:
+    print(msg)
+
+
+def _prompt(label: str, default: str = "", required: bool = True) -> str:
+    suffix = f" [{default}]" if default else ""
+    while True:
+        raw = input(f"  {label}{suffix}: ").strip()
+        value = raw or default
+        if value or not required:
+            return value
+        _print("    ⚠  This field is required.")
+
+
+def _prompt_bool(label: str, default: bool = True) -> bool:
+    hint = "Y/n" if default else "y/N"
+    raw = input(f"  {label} [{hint}]: ").strip().lower()
+    if not raw:
+        return default
+    return raw in ("y", "yes", "true", "1")
+
+
+def _format_customer_id(raw: str) -> str:
+    """Normalize a customer ID to XXX-XXX-XXXX format."""
+    digits = re.sub(r"[^0-9]", "", raw)
+    if len(digits) == 10:
+        return f"{digits[:3]}-{digits[3:6]}-{digits[6:]}"
+    return raw
+
+
+def _validate_customer_id(raw: str) -> str | None:
+    digits = re.sub(r"[^0-9]", "", raw)
+    if len(digits) != 10:
+        return "Customer ID must be 10 digits (e.g. 123-456-7890)"
+    return None
+
+
+def _prompt_customer_id(label: str, default: str = "") -> str:
+    while True:
+        value = _prompt(label, default=default)
+        formatted = _format_customer_id(value)
+        err = _validate_customer_id(formatted)
+        if err:
+            _print(f"    ⚠  {err}")
+            continue
+        return formatted
+
+
+def _validate_credentials_path(path_str: str) -> str | None:
+    p = Path(path_str).expanduser()
+    if not p.exists():
+        return f"File not found: {p}"
+    if not p.suffix == ".json":
+        return "Expected a .json file"
+    return None
+
+
+def _prompt_credentials_path(default: str = "~/.adloop/credentials.json") -> str:
+    while True:
+        value = _prompt("Path to OAuth credentials JSON", default=default)
+        err = _validate_credentials_path(value)
+        if err:
+            _print(f"    ⚠  {err}")
+            retry = _prompt_bool("Try again?", default=True)
+            if not retry:
+                return value
+            continue
+        return value
+
+
+def _prompt_property_id(default: str = "") -> str:
+    while True:
+        value = _prompt("GA4 Property ID (numeric)", default=default)
+        if value and not value.isdigit():
+            _print("    ⚠  Property ID should be numeric (e.g. 519379787)")
+            continue
+        return value
+
+
+def _generate_config_yaml(
+    *,
+    project_id: str,
+    credentials_path: str,
+    property_id: str,
+    developer_token: str,
+    customer_id: str,
+    login_customer_id: str,
+    max_daily_budget: float,
+    require_dry_run: bool,
+) -> str:
+    dry_run_str = "true" if require_dry_run else "false"
+    return textwrap.dedent(f"""\
+        # AdLoop configuration
+        # Generated by: adloop init
+        # Docs: https://github.com/your-org/adloop
+
+        google:
+          project_id: "{project_id}"
+          credentials_path: "{credentials_path}"
+          token_path: "~/.adloop/token.json"
+
+        ga4:
+          property_id: "{property_id}"
+
+        ads:
+          developer_token: "{developer_token}"
+          customer_id: "{customer_id}"
+          # MCC / Manager Account ID (required if using a manager account)
+          login_customer_id: "{login_customer_id}"
+
+        safety:
+          # Maximum daily budget AdLoop can set (safety cap)
+          max_daily_budget: {max_daily_budget}
+          max_bid_increase_pct: 100
+          # When true, confirm_and_apply always runs as dry_run regardless of the parameter
+          require_dry_run: {dry_run_str}
+          log_file: "~/.adloop/audit.log"
+          blocked_operations: []
+    """)
+
+
+def _generate_cursor_snippet() -> str:
+    python_path = sys.executable
+    return textwrap.dedent(f"""\
+        {{
+          "mcpServers": {{
+            "adloop": {{
+              "command": "{python_path}",
+              "args": ["-m", "adloop"]
+            }}
+          }}
+        }}
+    """).strip()
+
+
+def _generate_claude_code_snippet() -> str:
+    """Generate the Claude Code CLI command to add AdLoop as an MCP server."""
+    python_path = sys.executable
+    quoted = f'"{python_path}"' if " " in python_path else python_path
+    return f"claude mcp add --transport stdio adloop -- {quoted} -m adloop"
+
+
+def _generate_claude_json_snippet() -> str:
+    """Generate .mcp.json configuration for Claude Code."""
+    python_path = sys.executable
+    return textwrap.dedent(f"""\
+        {{
+          "mcpServers": {{
+            "adloop": {{
+              "command": "{python_path}",
+              "args": ["-m", "adloop"]
+            }}
+          }}
+        }}
+    """).strip()
+
+
+def _step_header(num: int, title: str) -> None:
+    _print()
+    _print(f"  ── Step {num}: {title} ──")
+    _print()
+
+
+def run_init_wizard() -> None:
+    """Interactive setup wizard for AdLoop."""
+    _print()
+    _print("  ╔═══════════════════════════════════╗")
+    _print("  ║     AdLoop Setup Wizard           ║")
+    _print("  ╚═══════════════════════════════════╝")
+    _print()
+
+    existing_config = None
+    if _CONFIG_PATH.exists():
+        _print(f"  Found existing config at {_CONFIG_PATH}")
+        if not _prompt_bool("Overwrite existing configuration?", default=False):
+            _print("  Keeping existing config. Exiting.")
+            return
+        try:
+            import yaml
+
+            with open(_CONFIG_PATH) as f:
+                existing_config = yaml.safe_load(f) or {}
+        except Exception:
+            existing_config = {}
+
+    def _existing(section: str, key: str, fallback: str = "") -> str:
+        if existing_config and section in existing_config:
+            return str(existing_config[section].get(key, fallback))
+        return fallback
+
+    # Step 1: Google Cloud instructions
+    _step_header(1, "Google Cloud Setup")
+    _print(_GOOGLE_CLOUD_INSTRUCTIONS)
+    input("  Press Enter when you've completed the steps above...")
+
+    # Step 2: Credentials path
+    _step_header(2, "OAuth Credentials")
+    credentials_path = _prompt_credentials_path(
+        default=_existing("google", "credentials_path", "~/.adloop/credentials.json")
+    )
+
+    # Step 3: Google Cloud Project ID
+    _step_header(3, "Google Cloud Project")
+    project_id = _prompt(
+        "Google Cloud Project ID",
+        default=_existing("google", "project_id"),
+    )
+
+    # Step 4: GA4 Property ID
+    _step_header(4, "Google Analytics (GA4)")
+    _print("  Find your GA4 Property ID at:")
+    _print("  → https://analytics.google.com → Admin → Property Settings")
+    _print()
+    property_id = _prompt_property_id(
+        default=_existing("ga4", "property_id"),
+    )
+
+    # Step 5: Developer Token
+    _step_header(5, "Google Ads Developer Token")
+    developer_token = _prompt(
+        "Developer Token",
+        default=_existing("ads", "developer_token"),
+    )
+
+    # Step 6: Customer ID
+    _step_header(6, "Google Ads Account IDs")
+    customer_id = _prompt_customer_id(
+        "Ads Customer ID (XXX-XXX-XXXX)",
+        default=_existing("ads", "customer_id"),
+    )
+    login_customer_id = _prompt_customer_id(
+        "MCC / Manager Account ID (XXX-XXX-XXXX)",
+        default=_existing("ads", "login_customer_id"),
+    )
+
+    # Step 7: Safety defaults
+    _step_header(7, "Safety Defaults")
+    budget_str = _prompt(
+        "Max daily budget cap (safety limit)",
+        default=str(_existing("safety", "max_daily_budget", "50")),
+        required=False,
+    )
+    try:
+        max_daily_budget = float(budget_str) if budget_str else 50.0
+    except ValueError:
+        max_daily_budget = 50.0
+        _print("    ⚠  Invalid number, using default 50.0")
+
+    require_dry_run = _prompt_bool(
+        "Require dry_run for all mutations? (recommended for setup)",
+        default=True,
+    )
+
+    # Write config
+    _print()
+    _print("  ── Writing Configuration ──")
+    _ADLOOP_DIR.mkdir(parents=True, exist_ok=True)
+
+    config_yaml = _generate_config_yaml(
+        project_id=project_id,
+        credentials_path=credentials_path,
+        property_id=property_id,
+        developer_token=developer_token,
+        customer_id=customer_id,
+        login_customer_id=login_customer_id,
+        max_daily_budget=max_daily_budget,
+        require_dry_run=require_dry_run,
+    )
+    _CONFIG_PATH.write_text(config_yaml)
+    _print(f"  ✓ Config written to {_CONFIG_PATH}")
+
+    # Optional: Copy credentials.json to ~/.adloop/ if it's elsewhere
+    creds_expanded = Path(credentials_path).expanduser()
+    adloop_creds = _ADLOOP_DIR / "credentials.json"
+    if creds_expanded != adloop_creds and creds_expanded.exists():
+        if _prompt_bool(
+            f"Copy {creds_expanded.name} to {_ADLOOP_DIR}?", default=True
+        ):
+            import shutil
+
+            shutil.copy2(creds_expanded, adloop_creds)
+            _print(f"  ✓ Credentials copied to {adloop_creds}")
+
+    # Optional OAuth
+    _print()
+    if _prompt_bool("Run OAuth authorization now? (opens browser)", default=True):
+        _print("  Starting OAuth flow...")
+        try:
+            from adloop.config import load_config
+            from adloop.auth import _oauth_flow
+
+            cfg = load_config(str(_CONFIG_PATH))
+            _oauth_flow(cfg)
+            _print("  ✓ OAuth token saved — AdLoop is ready to connect")
+        except Exception as exc:
+            _print(f"  ✗ OAuth failed: {exc}")
+            _print("    You can retry later — any AdLoop tool call will trigger auth.")
+    else:
+        _print("  Skipped — OAuth will run automatically on first tool call.")
+
+    # MCP configuration snippets
+    _print()
+    _print("  ── MCP Configuration ──")
+
+    # Cursor
+    _print()
+    _print("  For Cursor, add to .cursor/mcp.json:")
+    _print()
+    cursor_snippet = _generate_cursor_snippet()
+    for line in cursor_snippet.splitlines():
+        _print(f"    {line}")
+    _print()
+    _print("  Then copy .cursor/rules/adloop.mdc into your project.")
+
+    # Claude Code
+    _print()
+    _print("  For Claude Code, run:")
+    _print()
+    _print(f"    {_generate_claude_code_snippet()}")
+    _print()
+    _print("  Or add to your project's .mcp.json:")
+    _print()
+    claude_snippet = _generate_claude_json_snippet()
+    for line in claude_snippet.splitlines():
+        _print(f"    {line}")
+    _print()
+    _print("  Then copy .claude/rules/adloop.md and .claude/commands/ into your project.")
+
+    _print()
+    _print("  Restart your editor to pick up the MCP server.")
+    _print()
+    _print("  ✓ Setup complete!")
+    _print()

adloop/config.py

@@ -0,0 +1,102 @@
+"""Load and validate AdLoop configuration from ~/.adloop/config.yaml."""
+
+from __future__ import annotations
+
+import os
+from dataclasses import dataclass, field
+from pathlib import Path
+
+import yaml
+
+
+@dataclass
+class GoogleConfig:
+    project_id: str = ""
+    credentials_path: str = "~/.adloop/credentials.json"
+    token_path: str = "~/.adloop/token.json"
+
+
+@dataclass
+class GA4Config:
+    property_id: str = ""
+
+    def __post_init__(self) -> None:
+        if self.property_id and not self.property_id.startswith("properties/"):
+            self.property_id = f"properties/{self.property_id}"
+
+
+@dataclass
+class AdsConfig:
+    developer_token: str = ""
+    customer_id: str = ""
+    login_customer_id: str = ""
+
+
+@dataclass
+class SafetyConfig:
+    max_daily_budget: float = 50.0
+    max_bid_increase_pct: int = 100
+    require_dry_run: bool = True
+    log_file: str = "~/.adloop/audit.log"
+    blocked_operations: list[str] = field(default_factory=list)
+
+
+@dataclass
+class AdLoopConfig:
+    google: GoogleConfig = field(default_factory=GoogleConfig)
+    ga4: GA4Config = field(default_factory=GA4Config)
+    ads: AdsConfig = field(default_factory=AdsConfig)
+    safety: SafetyConfig = field(default_factory=SafetyConfig)
+
+
+def _resolve_path(path_str: str) -> Path:
+    """Expand ~ and env vars in a path string."""
+    return Path(os.path.expandvars(os.path.expanduser(path_str)))
+
+
+def load_config(config_path: str | None = None) -> AdLoopConfig:
+    """Load configuration from YAML file.
+
+    Resolution order:
+    1. Explicit ``config_path`` argument
+    2. ``ADLOOP_CONFIG`` environment variable
+    3. ``~/.adloop/config.yaml`` default
+    """
+    if config_path is None:
+        config_path = os.environ.get("ADLOOP_CONFIG", "~/.adloop/config.yaml")
+
+    path = _resolve_path(config_path)
+
+    if not path.exists():
+        return AdLoopConfig()
+
+    with open(path) as f:
+        raw = yaml.safe_load(f) or {}
+
+    google_raw = raw.get("google", {})
+    ga4_raw = raw.get("ga4", {})
+    ads_raw = raw.get("ads", {})
+    safety_raw = raw.get("safety", {})
+
+    return AdLoopConfig(
+        google=GoogleConfig(
+            project_id=google_raw.get("project_id", ""),
+            credentials_path=google_raw.get("credentials_path", "~/.adloop/credentials.json"),
+            token_path=google_raw.get("token_path", "~/.adloop/token.json"),
+        ),
+        ga4=GA4Config(
+            property_id=ga4_raw.get("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", ""),
+        ),
+        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),
+            log_file=safety_raw.get("log_file", "~/.adloop/audit.log"),
+            blocked_operations=safety_raw.get("blocked_operations", []),
+        ),
+    )