dottide 0.2.0__tar.gz

dottide-0.2.0/.gitignore

@@ -0,0 +1,13 @@
+.venv/
+__pycache__/
+*.pyc
+.pytest_cache/
+.ruff_cache/
+dist/
+.DS_Store
+
+# Keys and filled-in profiles never belong in the repo.
+*.json
+*.toml
+!pyproject.toml
+!src/dottide/profile_template.toml

dottide-0.2.0/CHANGELOG.md

@@ -0,0 +1,14 @@
+# Changelog
+
+## 0.2.0
+
+- Published on PyPI: `uvx dottide` runs it with nothing to clone.
+- `init` writes a starter profile to `~/.config/dottide/`.
+- `discover` finds every Search Console property and GA4 property the key can read and adds the missing sites to a profile.
+
+## 0.1.0 (not published)
+
+- First version: the `sites`, `search_queries`, `traffic` and `store_stats` MCP tools, the matching commands, and the weekly snapshot.
+- Keys stored in the macOS keychain with `dottide import-key`.
+- Docs for Google setup, configuration and everyday use.
+- README cover in light and dark.

dottide-0.2.0/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Dotbrain LLC
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

dottide-0.2.0/PKG-INFO

@@ -0,0 +1,115 @@
+Metadata-Version: 2.5
+Name: dottide
+Version: 0.2.0
+Summary: Read-only numbers for every site and product you run, across Google accounts, for people and AI agents.
+Project-URL: Homepage, https://github.com/dotbrainhq/dottide
+Project-URL: Documentation, https://github.com/dotbrainhq/dottide/tree/main/docs
+Project-URL: Issues, https://github.com/dotbrainhq/dottide/issues
+Project-URL: Changelog, https://github.com/dotbrainhq/dottide/blob/main/CHANGELOG.md
+Author-email: Dotbrain LLC <hello@dotbrainhq.com>
+License-Expression: MIT
+License-File: LICENSE
+Keywords: ai-agents,analytics,claude,cli,ga4,google-analytics,google-search-console,mcp,mcp-server,seo
+Classifier: Development Status :: 3 - Alpha
+Classifier: Environment :: Console
+Classifier: Intended Audience :: Developers
+Classifier: Operating System :: MacOS
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Topic :: Internet :: WWW/HTTP :: Site Management
+Requires-Python: >=3.12
+Requires-Dist: google-auth[requests]>=2.40
+Requires-Dist: httpx>=0.28
+Requires-Dist: mcp>=2.3
+Description-Content-Type: text/markdown
+
+<picture>
+  <source media="(prefers-color-scheme: dark)" srcset="https://raw.githubusercontent.com/dotbrainhq/dottide/main/.github/assets/cover-dark.png">
+  <img src="https://raw.githubusercontent.com/dotbrainhq/dottide/main/.github/assets/cover-light.png" alt="dotTide: every site's numbers, one place. Search Console, GA4 and store stats across Google accounts, for you and your AI agents. Local and read-only. Next to the text, the dotTide icon: a wave running across a green tile, with one dot under the surface.">
+</picture>
+
+# dotTide
+
+dotTide is a read-only MCP server and command-line tool that gives Claude, Cursor, Codex and other AI agents the numbers for every site you run. It reads Google Search Console and Google Analytics 4 (GA4) across multiple Google accounts, plus WordPress.org, Firefox Add-ons and GitHub stats, and writes a weekly snapshot for scripts and agents.
+
+Nothing gets added to your sites. dotTide only reads numbers you already have, and your keys stay on your Mac.
+
+## Why
+
+If your sites sit under different Google accounts, checking them means logging in and out of each one. The weekly check slips to monthly, and any AI agent you ask works from stale numbers. Store numbers for plugins, extensions and repos live in yet more places.
+
+dotTide reads all of it with one read-only key, and answers the same way in Claude, on the command line, and in a weekly JSON file.
+
+## What it does
+
+- **`sites`:** every configured site, which key covers it, and whether Search Console and GA4 access works when you ask.
+- **`search_queries`:** clicks, impressions, CTR and average position by query or page, for any date range, with an optional comparison to the previous period.
+- **`traffic`:** GA4 sessions by source and medium, with AI assistant referrals (ChatGPT, Perplexity, Copilot, Gemini, Claude and others) counted separately. Only for sites that have GA4.
+- **`store_stats`:** live public numbers that need no key: WordPress.org plugins, Firefox Add-ons, GitHub stars.
+- **`discover`:** finds every Search Console property and GA4 property the key can read, and writes the profile entries for you.
+- **Weekly snapshot:** last full week against the week before, one JSON file per profile, for scripts and agents that read files.
+
+## How access works
+
+No site moves to a new Google account. You create one Google service account, and whichever Google account owns a site invites that service account's email:
+
+- **Search Console:** as a Restricted user.
+- **GA4:** as a Viewer.
+
+The service account can only read, and you can remove it from any site in one click. Its key lives in the macOS keychain.
+
+## Quick start
+
+You need macOS and [uv](https://docs.astral.sh/uv/). There is nothing to clone: `uvx` downloads dotTide the first time you run it.
+
+1. Write a starter profile, then add a plugin slug, an add-on slug or a GitHub user under `[stores]` in it:
+
+```
+uvx dottide init
+```
+
+2. Check that it runs. Store numbers need no Google setup at all:
+
+```
+uvx dottide store_stats
+```
+
+3. Set up Google access by following [Google setup](https://github.com/dotbrainhq/dottide/blob/main/docs/google-setup.md). It takes about ten minutes, plus a minute per site.
+
+4. Store the key, let dotTide find your sites, and check access:
+
+```
+uvx dottide import-key dottide-main ~/Downloads/<downloaded-key>.json
+uvx dottide discover --write
+uvx dottide sites
+```
+
+5. Connect it to Claude Code:
+
+```
+claude mcp add --scope user dottide -- uvx dottide
+```
+
+To update later, run `uvx dottide@latest sites` once; after that `uvx dottide` uses the new version.
+
+## Documentation
+
+- [Google setup](https://github.com/dotbrainhq/dottide/blob/main/docs/google-setup.md): the service account, click by click, and sharing each site.
+- [Configuration](https://github.com/dotbrainhq/dottide/blob/main/docs/configuration.md): profiles, every field, keys and environment variables.
+- [Using dotTide](https://github.com/dotbrainhq/dottide/blob/main/docs/usage.md): each tool and its options, MCP clients, the weekly snapshot and its format, and fixes for common errors.
+- [Asking an AI agent for your numbers](https://github.com/dotbrainhq/dottide/blob/main/docs/examples.md): example prompts for weekly checks, content to refresh, AI referrals and store numbers, plus a saved Claude Code command.
+- [Connecting AI clients](https://github.com/dotbrainhq/dottide/blob/main/docs/clients.md): Claude Code, Claude Desktop, Cursor, Windsurf, VS Code, Codex, Gemini CLI, Grok, and agents without MCP.
+
+## Good to know
+
+- Search Console data settles about three days after the fact, so default ranges end three days ago.
+- Every Google scope dotTide asks for is read-only, and no tool can change anything.
+- GitHub allows 60 anonymous requests an hour per IP. Set `DOTTIDE_GITHUB_TOKEN` to a read-only token if you hit the limit.
+
+## Contributing
+
+See [CONTRIBUTING.md](https://github.com/dotbrainhq/dottide/blob/main/CONTRIBUTING.md). Security reports go through [SECURITY.md](https://github.com/dotbrainhq/dottide/blob/main/SECURITY.md).
+
+## License
+
+The code is released under the [MIT License](https://github.com/dotbrainhq/dottide/blob/main/LICENSE). The dotTide name and icon are not covered by the license, so please use your own name and icon if you ship a copy.

dottide-0.2.0/README.md

@@ -0,0 +1,90 @@
+<picture>
+  <source media="(prefers-color-scheme: dark)" srcset="https://raw.githubusercontent.com/dotbrainhq/dottide/main/.github/assets/cover-dark.png">
+  <img src="https://raw.githubusercontent.com/dotbrainhq/dottide/main/.github/assets/cover-light.png" alt="dotTide: every site's numbers, one place. Search Console, GA4 and store stats across Google accounts, for you and your AI agents. Local and read-only. Next to the text, the dotTide icon: a wave running across a green tile, with one dot under the surface.">
+</picture>
+
+# dotTide
+
+dotTide is a read-only MCP server and command-line tool that gives Claude, Cursor, Codex and other AI agents the numbers for every site you run. It reads Google Search Console and Google Analytics 4 (GA4) across multiple Google accounts, plus WordPress.org, Firefox Add-ons and GitHub stats, and writes a weekly snapshot for scripts and agents.
+
+Nothing gets added to your sites. dotTide only reads numbers you already have, and your keys stay on your Mac.
+
+## Why
+
+If your sites sit under different Google accounts, checking them means logging in and out of each one. The weekly check slips to monthly, and any AI agent you ask works from stale numbers. Store numbers for plugins, extensions and repos live in yet more places.
+
+dotTide reads all of it with one read-only key, and answers the same way in Claude, on the command line, and in a weekly JSON file.
+
+## What it does
+
+- **`sites`:** every configured site, which key covers it, and whether Search Console and GA4 access works when you ask.
+- **`search_queries`:** clicks, impressions, CTR and average position by query or page, for any date range, with an optional comparison to the previous period.
+- **`traffic`:** GA4 sessions by source and medium, with AI assistant referrals (ChatGPT, Perplexity, Copilot, Gemini, Claude and others) counted separately. Only for sites that have GA4.
+- **`store_stats`:** live public numbers that need no key: WordPress.org plugins, Firefox Add-ons, GitHub stars.
+- **`discover`:** finds every Search Console property and GA4 property the key can read, and writes the profile entries for you.
+- **Weekly snapshot:** last full week against the week before, one JSON file per profile, for scripts and agents that read files.
+
+## How access works
+
+No site moves to a new Google account. You create one Google service account, and whichever Google account owns a site invites that service account's email:
+
+- **Search Console:** as a Restricted user.
+- **GA4:** as a Viewer.
+
+The service account can only read, and you can remove it from any site in one click. Its key lives in the macOS keychain.
+
+## Quick start
+
+You need macOS and [uv](https://docs.astral.sh/uv/). There is nothing to clone: `uvx` downloads dotTide the first time you run it.
+
+1. Write a starter profile, then add a plugin slug, an add-on slug or a GitHub user under `[stores]` in it:
+
+```
+uvx dottide init
+```
+
+2. Check that it runs. Store numbers need no Google setup at all:
+
+```
+uvx dottide store_stats
+```
+
+3. Set up Google access by following [Google setup](https://github.com/dotbrainhq/dottide/blob/main/docs/google-setup.md). It takes about ten minutes, plus a minute per site.
+
+4. Store the key, let dotTide find your sites, and check access:
+
+```
+uvx dottide import-key dottide-main ~/Downloads/<downloaded-key>.json
+uvx dottide discover --write
+uvx dottide sites
+```
+
+5. Connect it to Claude Code:
+
+```
+claude mcp add --scope user dottide -- uvx dottide
+```
+
+To update later, run `uvx dottide@latest sites` once; after that `uvx dottide` uses the new version.
+
+## Documentation
+
+- [Google setup](https://github.com/dotbrainhq/dottide/blob/main/docs/google-setup.md): the service account, click by click, and sharing each site.
+- [Configuration](https://github.com/dotbrainhq/dottide/blob/main/docs/configuration.md): profiles, every field, keys and environment variables.
+- [Using dotTide](https://github.com/dotbrainhq/dottide/blob/main/docs/usage.md): each tool and its options, MCP clients, the weekly snapshot and its format, and fixes for common errors.
+- [Asking an AI agent for your numbers](https://github.com/dotbrainhq/dottide/blob/main/docs/examples.md): example prompts for weekly checks, content to refresh, AI referrals and store numbers, plus a saved Claude Code command.
+- [Connecting AI clients](https://github.com/dotbrainhq/dottide/blob/main/docs/clients.md): Claude Code, Claude Desktop, Cursor, Windsurf, VS Code, Codex, Gemini CLI, Grok, and agents without MCP.
+
+## Good to know
+
+- Search Console data settles about three days after the fact, so default ranges end three days ago.
+- Every Google scope dotTide asks for is read-only, and no tool can change anything.
+- GitHub allows 60 anonymous requests an hour per IP. Set `DOTTIDE_GITHUB_TOKEN` to a read-only token if you hit the limit.
+
+## Contributing
+
+See [CONTRIBUTING.md](https://github.com/dotbrainhq/dottide/blob/main/CONTRIBUTING.md). Security reports go through [SECURITY.md](https://github.com/dotbrainhq/dottide/blob/main/SECURITY.md).
+
+## License
+
+The code is released under the [MIT License](https://github.com/dotbrainhq/dottide/blob/main/LICENSE). The dotTide name and icon are not covered by the license, so please use your own name and icon if you ship a copy.

dottide-0.2.0/pyproject.toml

@@ -0,0 +1,49 @@
+[project]
+name = "dottide"
+version = "0.2.0"
+description = "Read-only numbers for every site and product you run, across Google accounts, for people and AI agents."
+readme = "README.md"
+license = "MIT"
+keywords = ["mcp", "mcp-server", "google-search-console", "google-analytics", "ga4", "seo", "analytics", "ai-agents", "claude", "cli"]
+requires-python = ">=3.12"
+authors = [{ name = "Dotbrain LLC", email = "hello@dotbrainhq.com" }]
+classifiers = [
+    "Development Status :: 3 - Alpha",
+    "Environment :: Console",
+    "Intended Audience :: Developers",
+    "Operating System :: MacOS",
+    "Programming Language :: Python :: 3.12",
+    "Programming Language :: Python :: 3.13",
+    "Topic :: Internet :: WWW/HTTP :: Site Management",
+]
+dependencies = [
+    "google-auth[requests]>=2.40",
+    "httpx>=0.28",
+    "mcp>=2.3",
+]
+
+[project.urls]
+Homepage = "https://github.com/dotbrainhq/dottide"
+Documentation = "https://github.com/dotbrainhq/dottide/tree/main/docs"
+Issues = "https://github.com/dotbrainhq/dottide/issues"
+Changelog = "https://github.com/dotbrainhq/dottide/blob/main/CHANGELOG.md"
+
+[project.scripts]
+dottide = "dottide.server:main"
+
+[dependency-groups]
+dev = ["pytest>=8", "ruff>=0.6"]
+
+[build-system]
+requires = ["hatchling"]
+build-backend = "hatchling.build"
+
+[tool.hatch.build.targets.sdist]
+include = ["src", "tests", "README.md", "LICENSE", "CHANGELOG.md", "pyproject.toml", "uv.lock"]
+
+[tool.ruff]
+line-length = 100
+target-version = "py312"
+
+[tool.ruff.lint]
+select = ["E", "F", "I", "UP", "B"]

dottide-0.2.0/src/dottide/config.py

@@ -0,0 +1,106 @@
+"""Profiles: one TOML file per side, each with its own Google key and its own sites.
+
+Keeping one file per side means a personal profile and a business profile never share a key,
+and an agent can be pointed at a single file when it should only see one side.
+"""
+
+from __future__ import annotations
+
+import os
+import tomllib
+from dataclasses import dataclass, field
+from importlib.resources import files
+from pathlib import Path
+
+from dottide import keys
+
+DEFAULT_DIR = Path("~/.config/dottide")
+
+
+@dataclass(frozen=True)
+class Site:
+    name: str
+    profile: str
+    search_console: str | None = None
+    ga4_property: str | None = None
+
+
+@dataclass
+class Profile:
+    name: str
+    keychain: str | None = None
+    key_file: str | None = None
+    sites: list[Site] = field(default_factory=list)
+    stores: dict = field(default_factory=dict)
+
+    @property
+    def key_source(self) -> str:
+        if self.keychain:
+            return f"keychain:{self.keychain}"
+        if self.key_file:
+            return f"file:{self.key_file}"
+        return "none"
+
+    def key_info(self) -> dict:
+        if self.keychain:
+            return keys.read(self.keychain)
+        if self.key_file:
+            return keys.read_file(self.key_file)
+        raise PermissionError(f"profile {self.name!r} has no [key] set")
+
+
+def config_paths() -> list[Path]:
+    """DOTTIDE_CONFIG may name one file or a folder of .toml files."""
+    target = Path(os.environ.get("DOTTIDE_CONFIG", DEFAULT_DIR)).expanduser()
+    if target.is_file():
+        return [target]
+    if target.is_dir():
+        return sorted(p for p in target.glob("*.toml") if not p.name.startswith("_"))
+    return []
+
+
+def load_profile(path: Path) -> Profile:
+    data = tomllib.loads(path.read_text())
+    key = data.get("key", {})
+    profile = Profile(
+        name=path.stem,
+        keychain=key.get("keychain"),
+        key_file=key.get("file"),
+        stores=data.get("stores", {}),
+    )
+    for entry in data.get("sites", []):
+        ga4 = entry.get("ga4_property")
+        profile.sites.append(
+            Site(
+                name=entry["name"],
+                profile=profile.name,
+                search_console=entry.get("search_console"),
+                ga4_property=str(ga4) if ga4 else None,
+            )
+        )
+    return profile
+
+
+def load_profiles() -> list[Profile]:
+    return [load_profile(p) for p in config_paths()]
+
+
+def find_site(profiles: list[Profile], name: str) -> tuple[Profile, Site]:
+    for profile in profiles:
+        for site in profile.sites:
+            if site.name == name:
+                return profile, site
+    known = ", ".join(s.name for p in profiles for s in p.sites) or "none configured"
+    raise ValueError(f"unknown site {name!r}. Configured sites: {known}")
+
+
+def init_profile(name: str = "main") -> Path:
+    """Write a starter profile from the bundled template. Never overwrites a file."""
+    folder = DEFAULT_DIR.expanduser()
+    path = folder / f"{name}.toml"
+    if path.exists():
+        raise FileExistsError(f"{path} already exists; edit it, or pick another --profile name")
+    folder.mkdir(mode=0o700, parents=True, exist_ok=True)
+    path.write_text(files("dottide").joinpath("profile_template.toml").read_text())
+    path.chmod(0o600)
+    return path

dottide-0.2.0/src/dottide/discover.py

@@ -0,0 +1,122 @@
+"""Find every site the key can read and suggest profile entries for the ones not set up yet.
+
+Reading is all it does on Google's side. The only write is `--write`, which appends
+the suggested [[sites]] blocks to a local profile file.
+"""
+
+from __future__ import annotations
+
+from urllib.parse import urlparse
+
+from dottide import google
+from dottide.config import Profile, config_paths, load_profiles
+
+
+def host(address: str) -> str:
+    """The bare domain behind a Search Console property or a site URL."""
+    if address.startswith("sc-domain:"):
+        address = address.removeprefix("sc-domain:")
+    elif "://" in address:
+        address = urlparse(address).hostname or ""
+    return address.strip("/").lower().removeprefix("www.")
+
+
+def plan(gsc_properties: list[str], streams: list[dict], configured: list[dict]) -> list[dict]:
+    """Suggested sites, one per domain, skipping anything a profile already covers.
+
+    A domain property wins over a URL-prefix property for the same domain, because it
+    covers every subdomain and protocol.
+    """
+    taken = {host(s["name"]) for s in configured}
+    taken |= {host(s["search_console"]) for s in configured if s.get("search_console")}
+    taken_ga4 = {s["ga4_property"] for s in configured if s.get("ga4_property")}
+
+    by_host: dict[str, dict] = {}
+    for prop in gsc_properties:
+        entry = by_host.setdefault(host(prop), {"name": host(prop)})
+        current = entry.get("search_console", "")
+        if not current or (prop.startswith("sc-domain:") and not current.startswith("sc-domain:")):
+            entry["search_console"] = prop
+    for stream in streams:
+        key = host(stream["url"]) if stream["url"] else ""
+        if not key or stream["property"] in taken_ga4:
+            continue
+        entry = by_host.setdefault(key, {"name": key})
+        entry.setdefault("ga4_property", stream["property"])
+        entry.setdefault("measurement_id", stream["measurement_id"])
+    return [by_host[k] for k in sorted(by_host) if k not in taken]
+
+
+def to_toml(sites: list[dict]) -> str:
+    blocks = []
+    for site in sites:
+        lines = ["[[sites]]", f'name = "{site["name"]}"']
+        if site.get("search_console"):
+            lines.append(f'search_console = "{site["search_console"]}"')
+        if site.get("ga4_property"):
+            note = f"   # {site['measurement_id']}" if site.get("measurement_id") else ""
+            lines.append(f'ga4_property = "{site["ga4_property"]}"{note}')
+        blocks.append("\n".join(lines))
+    return "\n\n".join(blocks)
+
+
+def discover(profile_name: str | None = None) -> dict:
+    """Read what the key can see and compare it with every profile."""
+    profiles = load_profiles()
+    keyed = [p for p in profiles if p.keychain or p.key_file]
+    if profile_name:
+        keyed = [p for p in keyed if p.name == profile_name]
+    if not keyed:
+        raise ValueError("no profile with a [key]; add one first (see docs/configuration.md)")
+
+    configured = [
+        {"name": s.name, "search_console": s.search_console, "ga4_property": s.ga4_property}
+        for p in profiles
+        for s in p.sites
+    ]
+    # Several profiles often share one key; read each key once.
+    seen: dict[str, Profile] = {}
+    for p in keyed:
+        seen.setdefault(p.key_source, p)
+
+    gsc, streams, errors = [], [], []
+    for profile in seen.values():
+        gsc += google.gsc_properties(profile)
+        try:
+            streams += google.ga4_web_streams(profile)
+        except Exception as exc:  # noqa: BLE001 - GA4 is optional; Search Console still counts
+            errors.append(f"GA4 ({profile.key_source}): {exc}")
+
+    new = plan(sorted(set(gsc)), streams, configured)
+    result = {
+        "keys": list(seen),
+        "search_console_properties": sorted(set(gsc)),
+        "ga4_web_streams": streams,
+        "already_configured": [s["name"] for s in configured],
+        "new_sites": new,
+        "toml": to_toml(new),
+    }
+    if errors:
+        result["errors"] = errors
+    return result
+
+
+def write(profile_name: str | None, toml: str) -> str:
+    """Append suggested blocks to a profile file and return its path."""
+    paths = config_paths()
+    if profile_name:
+        paths = [p for p in paths if p.stem == profile_name]
+    if len(paths) != 1:
+        names = ", ".join(p.stem for p in config_paths()) or "none"
+        raise ValueError(f"pick one profile with --profile to write to. Profiles: {names}")
+    path = paths[0]
+    text = path.read_text().rstrip()
+    # New sites go before [stores] when it exists, so the file keeps its usual order.
+    marker = "\n[stores]"
+    if marker in text:
+        head, tail = text.split(marker, 1)
+        text = f"{head.rstrip()}\n\n{toml}\n{marker}{tail}"
+    else:
+        text = f"{text}\n\n{toml}"
+    path.write_text(text + "\n")
+    return str(path)

dottide-0.2.0/src/dottide/google.py

@@ -0,0 +1,126 @@
+"""Search Console and GA4 reads through a service account. Read-only scopes only."""
+
+from __future__ import annotations
+
+from urllib.parse import quote
+
+import httpx
+from google.auth.transport.requests import Request
+from google.oauth2 import service_account
+
+from dottide.config import Profile
+
+SCOPES = [
+    "https://www.googleapis.com/auth/webmasters.readonly",
+    "https://www.googleapis.com/auth/analytics.readonly",
+]
+GSC = "https://searchconsole.googleapis.com/webmasters/v3"
+GA4_DATA = "https://analyticsdata.googleapis.com/v1beta"
+GA4_ADMIN = "https://analyticsadmin.googleapis.com/v1beta"
+
+_credentials: dict[str, service_account.Credentials] = {}
+
+
+def client_email(profile: Profile) -> str:
+    return profile.key_info()["client_email"]
+
+
+def _token(profile: Profile) -> str:
+    creds = _credentials.get(profile.name)
+    if creds is None:
+        creds = service_account.Credentials.from_service_account_info(
+            profile.key_info(), scopes=SCOPES
+        )
+        _credentials[profile.name] = creds
+    if not creds.valid:
+        creds.refresh(Request())
+    return creds.token
+
+
+def _call(profile: Profile, method: str, url: str, **kwargs) -> dict:
+    headers = {"Authorization": f"Bearer {_token(profile)}"}
+    response = httpx.request(method, url, headers=headers, timeout=30, **kwargs)
+    if response.status_code >= 400:
+        try:
+            message = response.json()["error"]["message"]
+        except (ValueError, KeyError, TypeError):
+            message = response.text[:200]
+        raise RuntimeError(f"Google API {response.status_code}: {message}")
+    return response.json()
+
+
+def gsc_properties(profile: Profile) -> list[str]:
+    entries = _call(profile, "GET", f"{GSC}/sites").get("siteEntry", [])
+    return [e["siteUrl"] for e in entries if e.get("permissionLevel") != "siteUnverifiedUser"]
+
+
+def gsc_query(
+    profile: Profile, prop: str, start: str, end: str, dimension: str | None, limit: int = 25
+) -> dict[str, dict]:
+    """Rows keyed by query or page. With no dimension, one row keyed "total"."""
+    body: dict = {"startDate": start, "endDate": end, "rowLimit": limit}
+    if dimension:
+        body["dimensions"] = [dimension]
+    url = f"{GSC}/sites/{quote(prop, safe='')}/searchAnalytics/query"
+    rows = _call(profile, "POST", url, json=body).get("rows", [])
+    return {
+        (row["keys"][0] if dimension else "total"): {
+            "clicks": row["clicks"],
+            "impressions": row["impressions"],
+            "ctr": round(row["ctr"] * 100, 2),
+            "position": round(row["position"], 1),
+        }
+        for row in rows
+    }
+
+
+def ga4_sources(profile: Profile, prop: str, start: str, end: str) -> list[dict]:
+    """Sessions by source and medium, biggest first."""
+    body = {
+        "dateRanges": [{"startDate": start, "endDate": end}],
+        "dimensions": [{"name": "sessionSource"}, {"name": "sessionMedium"}],
+        "metrics": [{"name": "sessions"}, {"name": "engagedSessions"}, {"name": "totalUsers"}],
+        "orderBys": [{"metric": {"metricName": "sessions"}, "desc": True}],
+        "limit": 1000,
+    }
+    data = _call(profile, "POST", f"{GA4_DATA}/properties/{prop}:runReport", json=body)
+    rows = []
+    for row in data.get("rows", []):
+        source, medium = (d["value"] for d in row["dimensionValues"])
+        sessions, engaged, users = (int(m["value"]) for m in row["metricValues"])
+        rows.append(
+            {
+                "source": source,
+                "medium": medium,
+                "sessions": sessions,
+                "engaged_sessions": engaged,
+                "users": users,
+            }
+        )
+    return rows
+
+
+def ga4_web_streams(profile: Profile) -> list[dict]:
+    """Every GA4 web stream the key can read, with the site address it tracks."""
+    streams, page = [], None
+    while True:
+        params = {"pageSize": 200, **({"pageToken": page} if page else {})}
+        data = _call(profile, "GET", f"{GA4_ADMIN}/accountSummaries", params=params)
+        for account in data.get("accountSummaries", []):
+            for prop in account.get("propertySummaries", []):
+                pid = prop["property"].split("/")[1]
+                url = f"{GA4_ADMIN}/properties/{pid}/dataStreams"
+                for stream in _call(profile, "GET", url).get("dataStreams", []):
+                    web = stream.get("webStreamData")
+                    if web:
+                        streams.append(
+                            {
+                                "property": pid,
+                                "name": prop.get("displayName"),
+                                "measurement_id": web.get("measurementId"),
+                                "url": web.get("defaultUri", ""),
+                            }
+                        )
+        page = data.get("nextPageToken")
+        if not page:
+            return streams