adloop 0.11.0__tar.gz → 0.12.0__tar.gz

adloop-0.11.0/README.md → adloop-0.12.0/PKG-INFO

@@ -1,3 +1,29 @@
+Metadata-Version: 2.3
+Name: adloop
+Version: 0.12.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>
+License: MIT
+Requires-Dist: fastmcp>=3.0.0
+Requires-Dist: google-ads>=29.0.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
+
 <div align="center">
 
 # AdLoop
@@ -19,13 +45,13 @@ An MCP server that gives your AI assistant read + write access to Google Ads and
 </div>
 
 > [!TIP]
-> **[AdLoop Cloud](https://getadloop.com) is the hosted version of this project — live now, free during beta (limited seats).** Connect Google in two clicks and use the same 61 tools from claude.ai, ChatGPT, Claude Code, Cursor, or Gemini. No Google Cloud project, no developer token, no OAuth verification wait. EU-hosted, GDPR-first, DPA included.
+> **[AdLoop Cloud](https://getadloop.com) is the hosted version of this project — live now, free during beta (limited seats).** Connect Google in two clicks and use the same 64 tools from claude.ai, ChatGPT, Claude Code, Cursor, or Gemini. No Google Cloud project, no developer token, no OAuth verification wait. EU-hosted, GDPR-first, DPA included.
 
 ---
 
 ## Cloud or Self-Hosted?
 
-Both versions run the same 61 tools with the same safety model. The difference is who handles the plumbing:
+Both versions run the same 64 tools with the same safety model. The difference is who handles the plumbing:
 
 |  | ☁️ [AdLoop Cloud](https://getadloop.com) | 🛠️ Self-hosted (this repo) |
 |---|---|---|
@@ -63,7 +89,7 @@ Every tool exists because of an actual problem hit while running real Google Ads
 
 The best features come from real workflows. If you're using AdLoop and find yourself wishing it could do something it can't, **open an issue describing your situation** — not just "add feature X" but "I was trying to do Y and couldn't because Z." The context matters more than the request.
 
-## All 61 Tools
+## All 64 Tools
 
 > **Quick start:** `pip install adloop` or `git clone https://github.com/kLOsk/adloop.git && cd adloop && uv sync && uv run adloop init` — or zero setup on [AdLoop Cloud](https://getadloop.com)
 
@@ -143,11 +169,26 @@ These tools read the live GTM container and join it with the codebase + GA4 to f
 
 > **Setup for GTM tools** — Enable the **Tag Manager API v2** in your GCP project, then add your AdLoop credentials' email (the OAuth user, or the service account email if using a service account) as a **Read** user on the GTM container under Admin → User Management. Service accounts pick up access on the next call. **OAuth users upgrading from an earlier AdLoop version must re-authorize once**: the GTM scope is new, so delete `~/.adloop/token.json` and run any tool to re-consent — until then GTM tools return a permissions error.
 
+### Search Console Tools
+
+| Tool | What It Does |
+|------|-------------|
+| `list_gsc_sites` | List Search Console properties the connected account can access |
+| `run_gsc_report` | Organic search analytics — clicks, impressions, CTR, position by query/page/country/device/date |
+
+### Web Performance Tools
+
+| Tool | What It Does |
+|------|-------------|
+| `analyze_page_speed` | PageSpeed Insights for landing pages — Lighthouse score, Core Web Vitals, real-user CrUX data, top fixes. No OAuth needed (optional API key). |
+
+> **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.
+
 ### Planning Tools
 
 | Tool | What It Does |
 |------|-------------|
-| `discover_keywords` | Discover new keyword ideas from seed keywords and/or a URL using Google Ads Keyword Planner. Returns avg monthly searches, competition level, and top-of-page bid range. |
+| `discover_keywords` | Discover new keyword ideas from seed keywords and/or a URL — with optional per-month search history + seasonality insights (`include_monthly_volumes`) using Google Ads Keyword Planner. Returns avg monthly searches, competition level, and top-of-page bid range. |
 | `estimate_budget` | Forecast clicks, impressions, and cost for a set of keywords using Google Ads Keyword Planner. Supports geo/language targeting. Essential for budget planning before launching campaigns. |
 
 ### Google Ads Write Tools
@@ -225,6 +266,9 @@ AdLoop manages real ad spend, so safety is not optional.
 >
 > *(Upgrading from ≤0.9 with built-in credentials? Those sign-ins were retired in 0.10 — run `adloop init` once to switch to your own project.)*
 
+> [!IMPORTANT]
+> **Seeing `deleted_client: The OAuth client was deleted.` or `invalid_client`?** The shared Google Cloud project behind AdLoop ≤0.9's bundled credentials has been shut down, so its stored sign-ins no longer refresh. Two ways forward: **[AdLoop Cloud](https://getadloop.com)** (connect Google in two clicks, nothing to configure) or stay self-hosted with `pip install -U adloop && adloop init` to set up your own free Google Cloud project. Details in [the pinned issue (#49)](https://github.com/kLOsk/adloop/issues/49).
+
 ### Install
 
 **From PyPI:**
@@ -394,7 +438,7 @@ All configuration lives in `~/.adloop/config.yaml`. See [`config.yaml.example`](
 ```
 src/adloop/
 ├── __init__.py        # Entry point — routes 'adloop init' to wizard, otherwise starts MCP server
-├── server.py          # FastMCP server — 61 tool registrations with safety annotations
+├── server.py          # FastMCP server — 64 tool registrations with safety annotations
 ├── 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

adloop-0.11.0/PKG-INFO → adloop-0.12.0/README.md

@@ -1,28 +1,3 @@
-Metadata-Version: 2.3
-Name: adloop
-Version: 0.11.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>
-License: MIT
-Requires-Dist: fastmcp>=3.0.0
-Requires-Dist: google-ads>=29.0.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: 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
-
 <div align="center">
 
 # AdLoop
@@ -44,13 +19,13 @@ An MCP server that gives your AI assistant read + write access to Google Ads and
 </div>
 
 > [!TIP]
-> **[AdLoop Cloud](https://getadloop.com) is the hosted version of this project — live now, free during beta (limited seats).** Connect Google in two clicks and use the same 61 tools from claude.ai, ChatGPT, Claude Code, Cursor, or Gemini. No Google Cloud project, no developer token, no OAuth verification wait. EU-hosted, GDPR-first, DPA included.
+> **[AdLoop Cloud](https://getadloop.com) is the hosted version of this project — live now, free during beta (limited seats).** Connect Google in two clicks and use the same 64 tools from claude.ai, ChatGPT, Claude Code, Cursor, or Gemini. No Google Cloud project, no developer token, no OAuth verification wait. EU-hosted, GDPR-first, DPA included.
 
 ---
 
 ## Cloud or Self-Hosted?
 
-Both versions run the same 61 tools with the same safety model. The difference is who handles the plumbing:
+Both versions run the same 64 tools with the same safety model. The difference is who handles the plumbing:
 
 |  | ☁️ [AdLoop Cloud](https://getadloop.com) | 🛠️ Self-hosted (this repo) |
 |---|---|---|
@@ -88,7 +63,7 @@ Every tool exists because of an actual problem hit while running real Google Ads
 
 The best features come from real workflows. If you're using AdLoop and find yourself wishing it could do something it can't, **open an issue describing your situation** — not just "add feature X" but "I was trying to do Y and couldn't because Z." The context matters more than the request.
 
-## All 61 Tools
+## All 64 Tools
 
 > **Quick start:** `pip install adloop` or `git clone https://github.com/kLOsk/adloop.git && cd adloop && uv sync && uv run adloop init` — or zero setup on [AdLoop Cloud](https://getadloop.com)
 
@@ -168,11 +143,26 @@ These tools read the live GTM container and join it with the codebase + GA4 to f
 
 > **Setup for GTM tools** — Enable the **Tag Manager API v2** in your GCP project, then add your AdLoop credentials' email (the OAuth user, or the service account email if using a service account) as a **Read** user on the GTM container under Admin → User Management. Service accounts pick up access on the next call. **OAuth users upgrading from an earlier AdLoop version must re-authorize once**: the GTM scope is new, so delete `~/.adloop/token.json` and run any tool to re-consent — until then GTM tools return a permissions error.
 
+### Search Console Tools
+
+| Tool | What It Does |
+|------|-------------|
+| `list_gsc_sites` | List Search Console properties the connected account can access |
+| `run_gsc_report` | Organic search analytics — clicks, impressions, CTR, position by query/page/country/device/date |
+
+### Web Performance Tools
+
+| Tool | What It Does |
+|------|-------------|
+| `analyze_page_speed` | PageSpeed Insights for landing pages — Lighthouse score, Core Web Vitals, real-user CrUX data, top fixes. No OAuth needed (optional API key). |
+
+> **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.
+
 ### Planning Tools
 
 | Tool | What It Does |
 |------|-------------|
-| `discover_keywords` | Discover new keyword ideas from seed keywords and/or a URL using Google Ads Keyword Planner. Returns avg monthly searches, competition level, and top-of-page bid range. |
+| `discover_keywords` | Discover new keyword ideas from seed keywords and/or a URL — with optional per-month search history + seasonality insights (`include_monthly_volumes`) using Google Ads Keyword Planner. Returns avg monthly searches, competition level, and top-of-page bid range. |
 | `estimate_budget` | Forecast clicks, impressions, and cost for a set of keywords using Google Ads Keyword Planner. Supports geo/language targeting. Essential for budget planning before launching campaigns. |
 
 ### Google Ads Write Tools
@@ -250,6 +240,9 @@ AdLoop manages real ad spend, so safety is not optional.
 >
 > *(Upgrading from ≤0.9 with built-in credentials? Those sign-ins were retired in 0.10 — run `adloop init` once to switch to your own project.)*
 
+> [!IMPORTANT]
+> **Seeing `deleted_client: The OAuth client was deleted.` or `invalid_client`?** The shared Google Cloud project behind AdLoop ≤0.9's bundled credentials has been shut down, so its stored sign-ins no longer refresh. Two ways forward: **[AdLoop Cloud](https://getadloop.com)** (connect Google in two clicks, nothing to configure) or stay self-hosted with `pip install -U adloop && adloop init` to set up your own free Google Cloud project. Details in [the pinned issue (#49)](https://github.com/kLOsk/adloop/issues/49).
+
 ### Install
 
 **From PyPI:**
@@ -419,7 +412,7 @@ All configuration lives in `~/.adloop/config.yaml`. See [`config.yaml.example`](
 ```
 src/adloop/
 ├── __init__.py        # Entry point — routes 'adloop init' to wizard, otherwise starts MCP server
-├── server.py          # FastMCP server — 61 tool registrations with safety annotations
+├── server.py          # FastMCP server — 64 tool registrations with safety annotations
 ├── 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

{adloop-0.11.0 → adloop-0.12.0}/pyproject.toml

@@ -1,6 +1,6 @@
 [project]
 name = "adloop"
-version = "0.11.0"
+version = "0.12.0"
 description = "The AI command center for Google Ads, GA4, and tracking code."
 readme = "README.md"
 authors = [
@@ -16,6 +16,7 @@ dependencies = [
     "google-analytics-admin>=0.27.0",
     "google-api-python-client>=2.100.0",
     "google-auth-oauthlib>=1.0.0",
+    "google-api-python-client>=2.0.0",
     "pyyaml>=6.0",
 ]
 

{adloop-0.11.0 → adloop-0.12.0}/src/adloop/ads/forecast.py

@@ -295,6 +295,69 @@ def _post_keyword_ideas_rest_page(
     return response.json()
 
 
+
+_MONTH_NUMBERS = {
+    "JANUARY": 1, "FEBRUARY": 2, "MARCH": 3, "APRIL": 4, "MAY": 5,
+    "JUNE": 6, "JULY": 7, "AUGUST": 8, "SEPTEMBER": 9, "OCTOBER": 10,
+    "NOVEMBER": 11, "DECEMBER": 12,
+}
+
+_MONTH_NAMES = {v: k.capitalize() for k, v in _MONTH_NUMBERS.items()}
+
+
+def _parse_monthly_volumes(raw: list[dict]) -> list[dict]:
+    """REST monthlySearchVolumes → compact chronological history.
+
+    Keeps the last 24 months: enough to see seasonality across two cycles
+    without flooding the response (the API returns up to ~4 years).
+    """
+    volumes = []
+    for row in raw:
+        month = _MONTH_NUMBERS.get(str(row.get("month", "")).upper())
+        year = _maybe_int(row.get("year"))
+        if month is None or year is None:
+            continue
+        volumes.append({
+            "year": year,
+            "month": month,
+            "searches": _maybe_int(row.get("monthlySearches")) or 0,
+        })
+    volumes.sort(key=lambda v: (v["year"], v["month"]))
+    return volumes[-24:]
+
+
+def _seasonality_insight(idea: dict) -> str | None:
+    """Name the peak months when demand is meaningfully seasonal (>=40%
+    above the keyword's own monthly average)."""
+    volumes = idea.get("monthly_search_volumes") or []
+    if len(volumes) < 12:
+        return None
+
+    by_month: dict[int, list[int]] = {}
+    for v in volumes:
+        by_month.setdefault(v["month"], []).append(v["searches"])
+    month_avgs = {m: sum(s) / len(s) for m, s in by_month.items()}
+    overall = sum(month_avgs.values()) / len(month_avgs)
+    if overall <= 0:
+        return None
+
+    peaks = sorted(
+        (m for m, avg in month_avgs.items() if avg >= overall * 1.4),
+        key=lambda m: month_avgs[m],
+        reverse=True,
+    )
+    if not peaks:
+        return None
+
+    names = ", ".join(_MONTH_NAMES[m] for m in peaks[:3])
+    ratio = month_avgs[peaks[0]] / overall
+    return (
+        f"'{idea['keyword']}' is seasonal: demand peaks in {names} "
+        f"(up to {ratio:.1f}x its monthly average). Plan budgets and "
+        f"campaign launches around the ramp-up, not the peak itself."
+    )
+
+
 def discover_keywords(
     config: AdLoopConfig,
     *,
@@ -304,6 +367,7 @@ def discover_keywords(
     language_id: str = "1000",
     page_size: int = 50,
     customer_id: str = "",
+    include_monthly_volumes: bool = False,
 ) -> dict:
     """Discover new keyword ideas using Google Ads Keyword Planner.
 
@@ -320,6 +384,9 @@ def discover_keywords(
     geo_target_id: geo target constant (2276=Germany, 2840=USA, 2826=UK)
     language_id: language constant (1000=English, 1001=German, 1002=French)
     page_size: max number of keyword ideas to return (default 50, max 1000)
+    include_monthly_volumes: attach per-month search volume history (up to
+        ~4 years, trimmed to the last 24 months, top 20 ideas only) plus a
+        seasonality insight — the "Google Trends" view for keyword demand.
 
     Network: this tool intentionally bypasses the google-ads gRPC client for
     KeywordPlanIdeaService and calls the v23 REST endpoint directly. The
@@ -358,7 +425,7 @@ def discover_keywords(
             # ``_micros_to_currency`` preserve legitimate 0 values that
             # falsy checks would otherwise silently drop. See the helper
             # docstrings for the failure modes this defends against.
-            ideas.append({
+            entry = {
                 "keyword": idea.get("text", ""),
                 "avg_monthly_searches": _maybe_int(metrics.get("avgMonthlySearches")),
                 "competition": competition,
@@ -369,7 +436,12 @@ def discover_keywords(
                 "high_top_of_page_bid": _micros_to_currency(
                     _maybe_int(metrics.get("highTopOfPageBidMicros"))
                 ),
-            })
+            }
+            if include_monthly_volumes:
+                entry["monthly_search_volumes"] = _parse_monthly_volumes(
+                    metrics.get("monthlySearchVolumes") or []
+                )
+            ideas.append(entry)
 
         page_token = payload.get("nextPageToken") or ""
         if not page_token:
@@ -378,6 +450,13 @@ def discover_keywords(
     # Sort by avg monthly searches descending (None last)
     ideas.sort(key=lambda x: x["avg_monthly_searches"] or 0, reverse=True)
 
+    if include_monthly_volumes:
+        # History is context-heavy (24 rows per keyword) — keep it on the
+        # ideas that matter and drop it from the long tail.
+        for i, idea in enumerate(ideas):
+            if i >= 20:
+                idea.pop("monthly_search_volumes", None)
+
     insights = []
     if ideas:
         high_competition = [i for i in ideas if i["competition"] == "HIGH"]
@@ -399,6 +478,9 @@ def discover_keywords(
                 f"Highest-volume idea: '{top['keyword']}' with ~{top['avg_monthly_searches']:,} "
                 f"avg monthly searches."
             )
+            seasonality = _seasonality_insight(top)
+            if seasonality:
+                insights.append(seasonality)
 
     return {
         "keyword_ideas": ideas,

{adloop-0.11.0 → adloop-0.12.0}/src/adloop/auth.py

@@ -28,6 +28,7 @@ _ALL_SCOPES = [
     "https://www.googleapis.com/auth/analytics.edit",
     "https://www.googleapis.com/auth/adwords",
     "https://www.googleapis.com/auth/tagmanager.readonly",
+    "https://www.googleapis.com/auth/webmasters.readonly",
 ]
 
 _GA4_SCOPES = [
@@ -43,6 +44,10 @@ _GTM_SCOPES = [
     "https://www.googleapis.com/auth/tagmanager.readonly",
 ]
 
+_GSC_SCOPES = [
+    "https://www.googleapis.com/auth/webmasters.readonly",
+]
+
 
 class CredentialsProvider(Protocol):
     """Source of authenticated Google credentials for the current context.
@@ -59,6 +64,8 @@ class CredentialsProvider(Protocol):
 
     def gtm_credentials(self, config: AdLoopConfig) -> Credentials: ...
 
+    def gsc_credentials(self, config: AdLoopConfig) -> Credentials: ...
+
 
 class LocalFileCredentialsProvider:
     """OSS default: local credential files + interactive OAuth.
@@ -90,6 +97,10 @@ class LocalFileCredentialsProvider:
         self._guard_local_only()
         return _local_credentials(config, _GTM_SCOPES)
 
+    def gsc_credentials(self, config: AdLoopConfig) -> Credentials:
+        self._guard_local_only()
+        return _local_credentials(config, _GSC_SCOPES)
+
 
 _active_provider: CredentialsProvider = LocalFileCredentialsProvider()
 
@@ -179,6 +190,18 @@ def get_gtm_credentials(config: AdLoopConfig) -> Credentials:
     return provider.gtm_credentials(config)
 
 
+def get_gsc_credentials(config: AdLoopConfig) -> Credentials:
+    """Return authenticated credentials for the Search Console API."""
+    provider = _active_provider
+    if not hasattr(provider, "gsc_credentials"):
+        raise RuntimeError(
+            "This deployment's credentials provider does not support "
+            "Google Search Console. GSC tools are only available where "
+            "the provider implements gsc_credentials()."
+        )
+    return provider.gsc_credentials(config)
+
+
 def _oauth_flow(
     config: AdLoopConfig, creds_path: Path | None = None
 ) -> Credentials:

{adloop-0.11.0 → adloop-0.12.0}/src/adloop/config.py

@@ -32,6 +32,22 @@ class AdsConfig:
     login_customer_id: str = ""
 
 
+@dataclass
+class GscConfig:
+    site_url: str = ""  # e.g. "https://example.com/" or "sc-domain:example.com"
+
+
+@dataclass
+class GtmConfig:
+    account_id: str = ""
+    container_id: str = ""
+
+
+@dataclass
+class PageSpeedConfig:
+    api_key: str = ""  # optional — keyless PSI calls work but are rate-limited
+
+
 @dataclass
 class SafetyConfig:
     max_daily_budget: float = 50.0
@@ -46,6 +62,9 @@ class AdLoopConfig:
     google: GoogleConfig = field(default_factory=GoogleConfig)
     ga4: GA4Config = field(default_factory=GA4Config)
     ads: AdsConfig = field(default_factory=AdsConfig)
+    gsc: GscConfig = field(default_factory=GscConfig)
+    gtm: GtmConfig = field(default_factory=GtmConfig)
+    pagespeed: PageSpeedConfig = field(default_factory=PageSpeedConfig)
     safety: SafetyConfig = field(default_factory=SafetyConfig)
     # Absolute path the config was resolved from (even if it did not exist
     # on disk when loaded). Used by the runtime to tell callers exactly
@@ -81,6 +100,9 @@ def load_config(config_path: str | None = None) -> AdLoopConfig:
     google_raw = raw.get("google", {})
     ga4_raw = raw.get("ga4", {})
     ads_raw = raw.get("ads", {})
+    gsc_raw = raw.get("gsc", {})
+    gtm_raw = raw.get("gtm", {})
+    pagespeed_raw = raw.get("pagespeed", {})
     safety_raw = raw.get("safety", {})
 
     return AdLoopConfig(
@@ -97,6 +119,16 @@ def load_config(config_path: str | None = None) -> AdLoopConfig:
             customer_id=ads_raw.get("customer_id", ""),
             login_customer_id=ads_raw.get("login_customer_id", ""),
         ),
+        gsc=GscConfig(
+            site_url=gsc_raw.get("site_url", ""),
+        ),
+        gtm=GtmConfig(
+            account_id=str(gtm_raw.get("account_id", "")),
+            container_id=str(gtm_raw.get("container_id", "")),
+        ),
+        pagespeed=PageSpeedConfig(
+            api_key=str(pagespeed_raw.get("api_key", "")),
+        ),
         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),

adloop-0.12.0/src/adloop/gsc/client.py

@@ -0,0 +1,22 @@
+"""Google Search Console API client wrapper."""
+
+from __future__ import annotations
+
+from typing import TYPE_CHECKING
+
+if TYPE_CHECKING:
+    from googleapiclient.discovery import Resource
+
+    from adloop.config import AdLoopConfig
+
+
+def get_gsc_client(config: AdLoopConfig) -> Resource:
+    """Return an authenticated Google Search Console API client."""
+    from googleapiclient.discovery import build
+
+    from adloop.auth import get_gsc_credentials
+
+    credentials = get_gsc_credentials(config)
+    return build(
+        "searchconsole", "v1", credentials=credentials, cache_discovery=False
+    )

adloop-0.12.0/src/adloop/gsc/reports.py

@@ -0,0 +1,137 @@
+"""Google Search Console report tools."""
+
+from __future__ import annotations
+
+from typing import TYPE_CHECKING, Literal
+
+if TYPE_CHECKING:
+    from adloop.config import AdLoopConfig
+
+
+def list_gsc_sites(config: AdLoopConfig) -> dict:
+    """List all Google Search Console properties the authenticated user can access."""
+    from adloop.gsc.client import get_gsc_client
+
+    client = get_gsc_client(config)
+    result = client.sites().list().execute()
+
+    sites = result.get("siteEntry", [])
+    return {
+        "sites": [
+            {
+                "site_url": s["siteUrl"],
+                "permission_level": s.get("permissionLevel", "unknown"),
+            }
+            for s in sites
+        ],
+        "total": len(sites),
+    }
+
+
+def run_gsc_report(
+    config: AdLoopConfig,
+    *,
+    site_url: str = "",
+    dimensions: list[str] | None = None,
+    date_range_start: str = "7daysAgo",
+    date_range_end: str = "today",
+    limit: int = 100,
+    search_type: Literal["web", "image", "video", "news", "discover", "googleNews"] = "web",
+    dimension_filter_groups: list[dict] | None = None,
+) -> dict:
+    """Run a Google Search Console search analytics report.
+
+    Returns clicks, impressions, CTR, and average position for the
+    requested dimensions and date range.
+
+    dimensions: one or more of ["query", "page", "country", "device", "date"]
+    date_range_start / date_range_end: ISO dates (YYYY-MM-DD) or relative
+        values like "7daysAgo", "30daysAgo", "today"
+    search_type: "web" (default), "image", "video", "news", "discover",
+        "googleNews"
+    dimension_filter_groups: optional list of GSC DimensionFilterGroup dicts
+        to filter by query, page, country, or device. Example:
+        [{"filters": [{"dimension": "query", "operator": "contains",
+                       "expression": "analytics"}]}]
+    limit: maximum number of rows to return (default 100, max 25000)
+    """
+    from adloop.gsc.client import get_gsc_client
+
+    if not site_url:
+        site_url = config.gsc.site_url
+
+    if not site_url:
+        return {
+            "error": "site_url is required. Pass it as an argument or set "
+                     "gsc.site_url in ~/.adloop/config.yaml."
+        }
+
+    if not dimensions:
+        dimensions = ["query"]
+
+    # Resolve relative date shorthands to ISO dates
+    start_date = _resolve_date(date_range_start)
+    end_date = _resolve_date(date_range_end)
+
+    body: dict = {
+        "startDate": start_date,
+        "endDate": end_date,
+        "dimensions": dimensions,
+        "type": search_type,
+        "rowLimit": min(limit, 25_000),
+        "startRow": 0,
+    }
+
+    if dimension_filter_groups:
+        body["dimensionFilterGroups"] = dimension_filter_groups
+
+    client = get_gsc_client(config)
+    result = (
+        client.searchanalytics()
+        .query(siteUrl=site_url, body=body)
+        .execute()
+    )
+
+    rows = result.get("rows", [])
+    formatted = []
+    for row in rows:
+        entry: dict = {}
+        for i, dim in enumerate(dimensions):
+            entry[dim] = row["keys"][i]
+        entry["clicks"] = row.get("clicks", 0)
+        entry["impressions"] = row.get("impressions", 0)
+        entry["ctr"] = round(row.get("ctr", 0.0) * 100, 2)  # as %
+        entry["position"] = round(row.get("position", 0.0), 1)
+        formatted.append(entry)
+
+    return {
+        "site_url": site_url,
+        "date_range": {"start": start_date, "end": end_date},
+        "search_type": search_type,
+        "dimensions": dimensions,
+        "rows": formatted,
+        "total_rows": len(formatted),
+    }
+
+
+def _resolve_date(value: str) -> str:
+    """Resolve a relative date string to ISO format (YYYY-MM-DD)."""
+    import re
+    from datetime import date, timedelta
+
+    value = value.strip()
+    if re.match(r"^\d{4}-\d{2}-\d{2}$", value):
+        return value
+
+    today = date.today()
+    if value == "today":
+        return today.isoformat()
+    if value == "yesterday":
+        return (today - timedelta(days=1)).isoformat()
+
+    m = re.match(r"^(\d+)daysAgo$", value)
+    if m:
+        return (today - timedelta(days=int(m.group(1)))).isoformat()
+
+    # Unknown format — pass through and let the API surface the error
+    return value