google-analytics-cli 0.1.0rc1__py3-none-any.whl

ga_cli/__init__.py

@@ -0,0 +1,8 @@
+"""GA CLI — Command-line interface for Google Analytics 4."""
+
+from importlib.metadata import PackageNotFoundError, version
+
+try:
+    __version__ = version("ga-cli")
+except PackageNotFoundError:
+    __version__ = "0.0.0-dev"

ga_cli/api/client.py

@@ -0,0 +1,142 @@
+"""Google Analytics API client wrappers.
+
+Provides authenticated clients for the Analytics Admin API and Data API.
+Uses google-api-python-client (REST-based), consistent with GTM CLI's use
+of the googleapis npm package.
+
+Authentication priority:
+1. Service account (env var or saved method)
+2. OAuth (stored credentials)
+
+Equivalent to GTM CLI's api/client.ts.
+"""
+
+from __future__ import annotations
+
+from typing import Optional
+
+from google.oauth2.credentials import Credentials
+from googleapiclient.discovery import Resource, build
+
+from ..auth.credentials import get_valid_credentials
+from ..auth.service_account import get_service_account_credentials
+
+# Cached client instances (same pattern as GTM CLI)
+_cached_admin_client: Optional[Resource] = None
+_cached_admin_alpha_client: Optional[Resource] = None
+_cached_data_client: Optional[Resource] = None
+_cached_data_alpha_client: Optional[Resource] = None
+
+
+def _get_credentials() -> Credentials:
+    """Get valid credentials (service account or OAuth).
+
+    Priority: service account > OAuth.
+    Raises if no authentication is configured.
+    """
+    # Try service account first
+    sa_creds = get_service_account_credentials()
+    if sa_creds is not None:
+        from google.auth.transport.requests import Request
+        if sa_creds.expired:
+            sa_creds.refresh(Request())
+        return sa_creds
+
+    # Fall back to OAuth
+    oauth_creds = get_valid_credentials()
+    if oauth_creds is not None:
+        return oauth_creds
+
+    raise RuntimeError(
+        "Not authenticated. Run 'ga auth login' or configure a service account."
+    )
+
+
+def get_admin_client() -> Resource:
+    """Get an authenticated Analytics Admin API client.
+
+    Returns a googleapiclient Resource for analyticsadmin v1beta.
+    Uses caching to avoid rebuilding the client on every call.
+
+    Usage:
+        admin = get_admin_client()
+        result = admin.accounts().list().execute()
+    """
+    global _cached_admin_client
+    if _cached_admin_client is None:
+        creds = _get_credentials()
+        _cached_admin_client = build(
+            "analyticsadmin",
+            "v1beta",
+            credentials=creds,
+        )
+    return _cached_admin_client
+
+
+def get_admin_alpha_client() -> Resource:
+    """Get an authenticated Analytics Admin API client (v1alpha).
+
+    Returns a googleapiclient Resource for analyticsadmin v1alpha.
+    Used for alpha-only resources: audiences, BigQuery links, channel groups,
+    calculated metrics, event rules, access bindings, annotations, etc.
+    """
+    global _cached_admin_alpha_client
+    if _cached_admin_alpha_client is None:
+        creds = _get_credentials()
+        _cached_admin_alpha_client = build(
+            "analyticsadmin",
+            "v1alpha",
+            credentials=creds,
+        )
+    return _cached_admin_alpha_client
+
+
+def get_data_client() -> Resource:
+    """Get an authenticated Analytics Data API client.
+
+    Returns a googleapiclient Resource for analyticsdata v1beta.
+
+    Usage:
+        data = get_data_client()
+        result = data.properties().runReport(
+            property="properties/12345",
+            body={...},
+        ).execute()
+    """
+    global _cached_data_client
+    if _cached_data_client is None:
+        creds = _get_credentials()
+        _cached_data_client = build(
+            "analyticsdata",
+            "v1beta",
+            credentials=creds,
+        )
+    return _cached_data_client
+
+
+def get_data_alpha_client() -> Resource:
+    """Get an authenticated Analytics Data API client (v1alpha).
+
+    Returns a googleapiclient Resource for analyticsdata v1alpha.
+    Used for alpha-only methods: funnel reports, property quotas snapshot.
+    """
+    global _cached_data_alpha_client
+    if _cached_data_alpha_client is None:
+        creds = _get_credentials()
+        _cached_data_alpha_client = build(
+            "analyticsdata",
+            "v1alpha",
+            credentials=creds,
+            static_discovery=False,
+        )
+    return _cached_data_alpha_client
+
+
+def clear_client_cache() -> None:
+    """Clear cached API clients (e.g., after re-authentication)."""
+    global _cached_admin_client, _cached_admin_alpha_client
+    global _cached_data_client, _cached_data_alpha_client
+    _cached_admin_client = None
+    _cached_admin_alpha_client = None
+    _cached_data_client = None
+    _cached_data_alpha_client = None

ga_cli/auth/__init__.py

@@ -0,0 +1,35 @@
+"""Authentication module for GA CLI.
+
+Public API for OAuth and service account authentication.
+"""
+
+from .credentials import (
+    delete_credentials,
+    get_valid_credentials,
+    has_credentials,
+    load_credentials,
+    save_credentials,
+)
+from .oauth import get_auth_status, login, logout
+from .service_account import (
+    get_service_account_credentials,
+    load_auth_method,
+    login_with_service_account,
+)
+
+__all__ = [
+    # OAuth flow
+    "login",
+    "logout",
+    "get_auth_status",
+    # Credentials
+    "get_valid_credentials",
+    "load_credentials",
+    "save_credentials",
+    "delete_credentials",
+    "has_credentials",
+    # Service account
+    "login_with_service_account",
+    "get_service_account_credentials",
+    "load_auth_method",
+]

ga_cli/auth/credentials.py

@@ -0,0 +1,126 @@
+"""Credential storage and management.
+
+Stores OAuth tokens at ~/.config/ga-cli/credentials.json with
+restrictive permissions (0o600 on Unix).
+
+Equivalent to GTM CLI's auth/credentials.ts.
+"""
+
+from __future__ import annotations
+
+import json
+import logging
+import os
+import platform
+from datetime import datetime
+from typing import Optional
+
+from google.oauth2.credentials import Credentials
+
+from ..config.constants import (
+    OAUTH_SCOPES,
+    get_config_dir,
+    get_credentials_path,
+)
+
+logger = logging.getLogger(__name__)
+
+
+def save_credentials(credentials: Credentials) -> None:
+    """Save OAuth credentials to disk.
+
+    Stores the token data as JSON with 0o600 permissions on Unix.
+    """
+    config_dir = get_config_dir()
+    config_dir.mkdir(parents=True, exist_ok=True)
+
+    creds_path = get_credentials_path()
+
+    data = {
+        "token": credentials.token,
+        "refresh_token": credentials.refresh_token,
+        "token_uri": credentials.token_uri,
+        "client_id": credentials.client_id,
+        "client_secret": credentials.client_secret,
+        "scopes": list(credentials.scopes) if credentials.scopes else OAUTH_SCOPES,
+        "expiry": credentials.expiry.isoformat() if credentials.expiry else None,
+    }
+
+    creds_path.write_text(json.dumps(data, indent=2))
+
+    # Set restrictive permissions on Unix
+    if platform.system() != "Windows":
+        os.chmod(creds_path, 0o600)
+
+
+def load_credentials() -> Optional[Credentials]:
+    """Load OAuth credentials from disk.
+
+    Returns None if no credentials file exists or if the file is corrupt.
+    """
+    creds_path = get_credentials_path()
+
+    if not creds_path.exists():
+        return None
+
+    try:
+        data = json.loads(creds_path.read_text())
+    except (json.JSONDecodeError, OSError) as exc:
+        logger.warning("Failed to read credentials file: %s", exc)
+        return None
+
+    creds = Credentials(
+        token=data.get("token"),
+        refresh_token=data.get("refresh_token"),
+        token_uri=data.get("token_uri", "https://oauth2.googleapis.com/token"),
+        client_id=data.get("client_id"),
+        client_secret=data.get("client_secret"),
+        scopes=data.get("scopes", OAUTH_SCOPES),
+    )
+
+    if data.get("expiry"):
+        try:
+            expiry = datetime.fromisoformat(data["expiry"])
+            # google-auth expects expiry without tzinfo (assumes UTC internally)
+            creds.expiry = expiry.replace(tzinfo=None)
+        except ValueError:
+            logger.warning("Invalid expiry timestamp in credentials file")
+
+    return creds
+
+
+def delete_credentials() -> None:
+    """Delete stored credentials file."""
+    creds_path = get_credentials_path()
+    try:
+        creds_path.unlink()
+    except FileNotFoundError:
+        pass
+
+
+def has_credentials() -> bool:
+    """Check if credentials file exists."""
+    return get_credentials_path().exists()
+
+
+def get_valid_credentials() -> Optional[Credentials]:
+    """Load credentials and refresh if expired.
+
+    This is the main entry point for getting a usable token.
+    Returns None if no credentials are stored.
+    """
+    creds = load_credentials()
+    if creds is None:
+        return None
+
+    if creds.expired and creds.refresh_token:
+        from google.auth.transport.requests import Request
+
+        try:
+            creds.refresh(Request())
+            save_credentials(creds)
+        except Exception as exc:
+            logger.warning("Failed to refresh token: %s", exc)
+            return None
+
+    return creds

ga_cli/auth/oauth.py

@@ -0,0 +1,322 @@
+"""OAuth 2.0 authentication flow.
+
+Uses google-auth-oauthlib's InstalledAppFlow which handles:
+- Local HTTP server for the callback
+- Browser opening
+- CSRF state parameter
+- Authorization code exchange
+- Token retrieval
+
+This replaces ~300 lines of manual OAuth code in the GTM CLI.
+"""
+
+from __future__ import annotations
+
+import logging
+import os
+import webbrowser
+import wsgiref.simple_server
+import wsgiref.util
+from typing import Optional
+
+import requests
+import typer
+from google.oauth2.credentials import Credentials
+from google_auth_oauthlib.flow import InstalledAppFlow
+from rich.panel import Panel
+
+from ..config.constants import (
+    OAUTH_CALLBACK_PORT,
+    OAUTH_SCOPES,
+    get_client_secret_path,
+)
+from .credentials import (
+    delete_credentials,
+    get_valid_credentials,
+    load_credentials,
+    save_credentials,
+)
+
+logger = logging.getLogger(__name__)
+
+_SUCCESS_HTML = """\
+<!DOCTYPE html>
+<html lang="en">
+<head>
+    <meta charset="UTF-8">
+    <meta name="viewport" content="width=device-width, initial-scale=1.0">
+    <title>GA CLI – Authentication Successful</title>
+    <style>
+        * { margin: 0; padding: 0; box-sizing: border-box; }
+        body {
+            font-family: -apple-system, BlinkMacSystemFont, "Segoe UI", Roboto,
+                         Helvetica, Arial, sans-serif;
+            background: #f8f9fa;
+            color: #1a1a2e;
+            display: flex;
+            align-items: center;
+            justify-content: center;
+            min-height: 100vh;
+        }
+        .card {
+            background: #fff;
+            border-radius: 16px;
+            box-shadow: 0 4px 24px rgba(0, 0, 0, 0.08);
+            padding: 48px 40px;
+            text-align: center;
+            max-width: 420px;
+            width: 100%;
+        }
+        .icon {
+            width: 80px; height: 80px;
+            background: #235495;
+            border-radius: 50%;
+            display: flex;
+            align-items: center;
+            justify-content: center;
+            margin: 0 auto 20px;
+        }
+        .icon svg { width: 40px; height: 40px; }
+        .brand {
+            font-size: 14px;
+            font-weight: 600;
+            color: #dd973a;
+            letter-spacing: 0.5px;
+            margin-bottom: 8px;
+        }
+        h1 {
+            font-size: 24px;
+            font-weight: 700;
+            margin-bottom: 8px;
+        }
+        .subtitle {
+            font-size: 15px;
+            color: #666;
+            margin-bottom: 28px;
+        }
+        .command {
+            display: inline-block;
+            background: #f4f4f5;
+            border: 1px solid #e4e4e7;
+            border-radius: 8px;
+            padding: 10px 20px;
+            font-family: "SF Mono", "Fira Code", "Cascadia Code", monospace;
+            font-size: 14px;
+            color: #1a1a2e;
+        }
+        .footer {
+            margin-top: 32px;
+            font-size: 12px;
+            color: #aaa;
+        }
+        .footer a { color: #dd973a; text-decoration: none; }
+        .footer a:hover { text-decoration: underline; }
+    </style>
+</head>
+<body>
+    <div class="card">
+        <div class="icon">
+            <svg viewBox="0 0 24 24" fill="none" stroke="#ffffff" stroke-width="2.5"
+                 stroke-linecap="round" stroke-linejoin="round">
+                <path d="M20 6L9 17l-5-5"/>
+            </svg>
+        </div>
+        <div class="brand">GA CLI</div>
+        <h1>Authentication Successful</h1>
+        <p class="subtitle">
+            You're all set! You can close this window and<br>return to your terminal.
+        </p>
+        <div class="command">ga accounts list</div>
+        <div class="footer">
+            Powered by <a href="https://github.com/daidalytics/google-analytics-cli"
+                          target="_blank" rel="noopener">ga-cli</a>
+        </div>
+    </div>
+</body>
+</html>
+"""
+
+
+class _HtmlRedirectWSGIApp:
+    """WSGI app that serves a styled HTML success page on OAuth callback."""
+
+    def __init__(self, html: str):
+        self.last_request_uri: Optional[str] = None
+        self._html = html
+
+    def __call__(self, environ, start_response):
+        start_response(
+            "200 OK",
+            [("Content-Type", "text/html; charset=utf-8")],
+        )
+        self.last_request_uri = wsgiref.util.request_uri(environ)
+        return [self._html.encode("utf-8")]
+
+
+class _SilentRequestHandler(wsgiref.simple_server.WSGIRequestHandler):
+    """Request handler that logs to the logger instead of stderr."""
+
+    def log_message(self, format, *args):  # noqa: A002
+        logger.debug(format, *args)
+
+
+def _get_client_config() -> dict:
+    """Build the OAuth client config dict from env vars."""
+    client_id = os.environ.get("GA_CLI_CLIENT_ID", "")
+    client_secret = os.environ.get("GA_CLI_CLIENT_SECRET", "")
+    return {
+        "installed": {
+            "client_id": client_id,
+            "client_secret": client_secret,
+            "auth_uri": "https://accounts.google.com/o/oauth2/v2/auth",
+            "token_uri": "https://oauth2.googleapis.com/token",
+            "redirect_uris": [f"http://localhost:{OAUTH_CALLBACK_PORT}"],
+        }
+    }
+
+
+def login() -> Credentials:
+    """Run the full OAuth login flow.
+
+    Opens a browser, starts a local server, waits for the callback,
+    exchanges the code for tokens, and saves credentials to disk.
+
+    Raises:
+        typer.Exit: If client credentials are not configured.
+        OSError: If the callback port is already in use.
+    """
+    client_secret_path = get_client_secret_path()
+
+    if client_secret_path.exists():
+        flow = InstalledAppFlow.from_client_secrets_file(
+            str(client_secret_path),
+            scopes=OAUTH_SCOPES,
+        )
+    elif os.environ.get("GA_CLI_CLIENT_ID") and os.environ.get("GA_CLI_CLIENT_SECRET"):
+        flow = InstalledAppFlow.from_client_config(
+            _get_client_config(),
+            scopes=OAUTH_SCOPES,
+        )
+    else:
+        from ..utils.output import err_console
+
+        err_console.print(Panel(
+            "[bold]OAuth client credentials not found.[/bold]\n\n"
+            "GA CLI requires your own GCP OAuth credentials. "
+            "Choose one of the following:\n\n"
+            "[cyan]Option 1:[/cyan] Place a client_secret.json file in:\n"
+            f"  [green]{client_secret_path}[/green]\n\n"
+            "[cyan]Option 2:[/cyan] Set environment variables:\n"
+            "  [green]GA_CLI_CLIENT_ID[/green] and "
+            "[green]GA_CLI_CLIENT_SECRET[/green]\n\n"
+            "For step-by-step setup instructions, run:\n"
+            "  [bold yellow]ga auth setup[/bold yellow]\n\n"
+            "Create OAuth credentials in the GCP Console:\n"
+            "  APIs & Services > Credentials > Create OAuth client ID (Desktop app)",
+            title="[red]Missing Credentials[/red]",
+            border_style="red",
+            expand=False,
+        ))
+        raise typer.Exit(1)
+
+    # Custom local server flow to serve a styled HTML success page
+    wsgi_app = _HtmlRedirectWSGIApp(_SUCCESS_HTML)
+    wsgiref.simple_server.WSGIServer.allow_reuse_address = False
+    local_server = wsgiref.simple_server.make_server(
+        "localhost",
+        OAUTH_CALLBACK_PORT,
+        wsgi_app,
+        handler_class=_SilentRequestHandler,
+    )
+
+    try:
+        flow.redirect_uri = f"http://localhost:{local_server.server_port}/"
+        auth_url, _ = flow.authorization_url(
+            prompt="consent",
+            access_type="offline",
+        )
+
+        webbrowser.open(auth_url, new=1, autoraise=True)
+        print(f"Please visit this URL to authorize this application: {auth_url}")
+
+        local_server.handle_request()
+
+        authorization_response = wsgi_app.last_request_uri.replace(
+            "http", "https"
+        )
+        flow.fetch_token(authorization_response=authorization_response)
+    finally:
+        local_server.server_close()
+
+    credentials = flow.credentials
+    save_credentials(credentials)
+    return credentials
+
+
+def logout() -> None:
+    """Revoke tokens and delete local credentials.
+
+    Attempts to revoke the token with Google (best-effort),
+    then deletes the local credentials file.
+    """
+    creds = load_credentials()
+
+    if creds and creds.token:
+        try:
+            requests.post(
+                "https://oauth2.googleapis.com/revoke",
+                params={"token": creds.token},
+                headers={"Content-Type": "application/x-www-form-urlencoded"},
+                timeout=10,
+            )
+        except requests.RequestException:
+            logger.debug("Token revocation failed (token may already be revoked)")
+
+    delete_credentials()
+
+
+def get_auth_status() -> dict:
+    """Get current OAuth authentication status.
+
+    Returns a dict with authentication state, suitable for display.
+    """
+    creds = load_credentials()
+
+    if creds is None:
+        return {"authenticated": False}
+
+    result: dict = {
+        "authenticated": True,
+        "token_valid": creds.valid,
+        "expired": creds.expired,
+        "has_refresh_token": creds.refresh_token is not None,
+    }
+
+    if creds.expiry:
+        result["expires_at"] = creds.expiry.isoformat()
+
+    # Try to fetch user info if we have a valid or refreshable token
+    if creds.valid or (creds.expired and creds.refresh_token):
+        valid_creds = get_valid_credentials()
+        if valid_creds and valid_creds.token:
+            user_info = _fetch_user_info(valid_creds.token)
+            if user_info:
+                result["email"] = user_info.get("email")
+                result["name"] = user_info.get("name")
+
+    return result
+
+
+def _fetch_user_info(access_token: str) -> Optional[dict]:
+    """Fetch user info from Google (email, name)."""
+    try:
+        resp = requests.get(
+            "https://www.googleapis.com/oauth2/v2/userinfo",
+            headers={"Authorization": f"Bearer {access_token}"},
+            timeout=10,
+        )
+        if resp.ok:
+            return resp.json()
+    except requests.RequestException:
+        logger.debug("Failed to fetch user info")
+    return None