Blog Google

#!/usr/bin/env python3
"""
CrUX History API for Core Web Vitals trends over time.

Fetches up to 25 weekly data points from the Chrome UX Report History API
and identifies improving, stable, or degrading trends per metric.

Usage:
    python crux_history.py https://example.com
    python crux_history.py https://example.com --form-factor PHONE --json
    python crux_history.py https://example.com --origin
"""

import argparse
import json
import sys
from typing import Optional
from urllib.parse import urlparse

try:
    import requests
except ImportError:
    print("Error: requests library required. Install with: pip install requests")
    sys.exit(1)

try:
    from google_auth import get_api_key
except ImportError:
    import os
    sys.path.insert(0, os.path.dirname(os.path.abspath(__file__)))
    from google_auth import get_api_key

CRUX_HISTORY_ENDPOINT = "https://chromeuxreport.googleapis.com/v1/records:queryHistoryRecord"

CWV_THRESHOLDS = {
    "largest_contentful_paint": {"good": 2500, "poor": 4000, "label": "LCP", "unit": "ms"},
    "interaction_to_next_paint": {"good": 200, "poor": 500, "label": "INP", "unit": "ms"},
    "cumulative_layout_shift": {"good": 0.1, "poor": 0.25, "label": "CLS", "unit": ""},
    "first_contentful_paint": {"good": 1800, "poor": 3000, "label": "FCP", "unit": "ms"},
    "experimental_time_to_first_byte": {"good": 800, "poor": 1800, "label": "TTFB", "unit": "ms"},
}


def query_history(
    url_or_origin: str,
    api_key: str,
    form_factor: Optional[str] = None,
) -> dict:
    """
    Query CrUX History API for weekly CWV trends.

    Args:
        url_or_origin: Full URL or origin.
        api_key: Google API key.
        form_factor: DESKTOP, PHONE, or TABLET. None for all.

    Returns:
        Dictionary with metrics timeseries, collection periods, and trend analysis.
    """
    result = {
        "target": url_or_origin,
        "form_factor": form_factor or "ALL",
        "metrics": {},
        "collection_periods": [],
        "trends": {},
        "error": None,
    }

    parsed = urlparse(url_or_origin)
    is_origin = parsed.path in ("", "/") and not parsed.query

    body = {}
    if is_origin:
        body["origin"] = f"{parsed.scheme}://{parsed.netloc}"
    else:
        body["url"] = url_or_origin

    if form_factor:
        body["formFactor"] = form_factor.upper()

    try:
        resp = requests.post(
            f"{CRUX_HISTORY_ENDPOINT}?key={api_key}",
            json=body,
            timeout=30,
        )

        if resp.status_code == 404:
            target_type = "origin" if is_origin else "URL"
            result["error"] = (
                f"No CrUX history data for this {target_type}. "
                "Insufficient Chrome traffic volume for eligibility."
            )
            return result

        if resp.status_code == 429:
            result["error"] = "CrUX API rate limit exceeded (150 QPM shared). Wait and retry."
            return result

        resp.raise_for_status()
        data = resp.json()
    except requests.exceptions.RequestException as e:
        result["error"] = f"CrUX History API request failed: {e}"
        return result

    record = data.get("record", {})

    # Collection periods
    periods = record.get("collectionPeriods", [])
    for period in periods:
        first = period.get("firstDate", {})
        last = period.get("lastDate", {})
        result["collection_periods"].append({
            "first": f"{first.get('year')}-{first.get('month', 0):02d}-{first.get('day', 0):02d}",
            "last": f"{last.get('year')}-{last.get('month', 0):02d}-{last.get('day', 0):02d}",
        })

    # Metrics timeseries
    for metric_name, metric_data in record.get("metrics", {}).items():
        if metric_name not in CWV_THRESHOLDS:
            continue

        thresholds = CWV_THRESHOLDS[metric_name]
        p75s_data = metric_data.get("percentilesTimeseries", {})
        p75s_raw = p75s_data.get("p75s", [])

        # Parse p75 values (CLS is string-encoded)
        p75s = []
        for val in p75s_raw:
            if val is None:
                p75s.append(None)
            elif metric_name == "cumulative_layout_shift":
                try:
                    p75s.append(float(str(val)))
                except (ValueError, TypeError):
                    p75s.append(None)
            else:
                try:
                    p75s.append(int(val))
                except (ValueError, TypeError):
                    try:
                        p75s.append(float(val))
                    except (ValueError, TypeError):
                        p75s.append(None)

        # Distributions timeseries
        histogram_ts = metric_data.get("histogramTimeseries", [])
        good_pcts = []
        if len(histogram_ts) >= 3:
            good_densities = histogram_ts[0].get("densities", [])
            for d in good_densities:
                if d is None or str(d) == "NaN":
                    good_pcts.append(None)
                else:
                    try:
                        good_pcts.append(round(float(d) * 100, 1))
                    except (ValueError, TypeError):
                        good_pcts.append(None)

        # Extract needs_improvement (bin 1) and poor (bin 2) percentages
        ni_pcts = []
        poor_pcts = []
        if len(histogram_ts) >= 3:
            for bin_idx, target_list in [(1, ni_pcts), (2, poor_pcts)]:
                bin_densities = histogram_ts[bin_idx].get("densities", [])
                for d in bin_densities:
                    if d is None or str(d) == "NaN":
                        target_list.append(None)
                    else:
                        try:
                            target_list.append(round(float(d) * 100, 1))
                        except (ValueError, TypeError):
                            target_list.append(None)

        result["metrics"][metric_name] = {
            "label": thresholds["label"],
            "unit": thresholds["unit"],
            "p75_values": p75s,
            "good_percentages": good_pcts,
            "needs_improvement_percentages": ni_pcts,
            "poor_percentages": poor_pcts,
            "latest_p75": p75s[-1] if p75s and p75s[-1] is not None else None,
            "good_threshold": thresholds["good"],
            "poor_threshold": thresholds["poor"],
        }

    # Trend analysis
    result["trends"] = detect_trends(result["metrics"])

    return result


def detect_trends(metrics: dict) -> dict:
    """
    Analyze p75 timeseries to detect trends.

    Compares the average of the last 4 weeks to the average of the first 4 weeks.

    Returns:
        Dictionary mapping metric names to trend info:
        direction (improving/stable/degrading), change_pct, latest, earliest.
    """
    trends = {}

    for metric_name, data in metrics.items():
        p75s = data.get("p75_values", [])
        valid = [v for v in p75s if v is not None]

        if len(valid) < 8:
            trends[metric_name] = {
                "direction": "insufficient_data",
                "label": data.get("label", metric_name),
            }
            continue

        # First 4 valid vs last 4 valid
        first_4 = valid[:4]
        last_4 = valid[-4:]
        avg_first = sum(first_4) / len(first_4)
        avg_last = sum(last_4) / len(last_4)

        if avg_first == 0:
            change_pct = 0
        else:
            change_pct = ((avg_last - avg_first) / avg_first) * 100

        # For CWV, lower is better (except CLS where lower is also better)
        # So a negative change_pct means improvement
        if abs(change_pct) < 5:
            direction = "stable"
        elif change_pct < 0:
            direction = "improving"
        else:
            direction = "degrading"

        trends[metric_name] = {
            "direction": direction,
            "change_pct": round(change_pct, 1),
            "earliest_avg": round(avg_first, 3) if data.get("unit") == "" else round(avg_first),
            "latest_avg": round(avg_last, 3) if data.get("unit") == "" else round(avg_last),
            "label": data.get("label", metric_name),
            "data_points": len(valid),
        }

    return trends


def main():
    parser = argparse.ArgumentParser(
        description="CrUX History API - Core Web Vitals trends over time"
    )
    parser.add_argument("url", help="URL or origin to analyze")
    parser.add_argument(
        "--form-factor",
        choices=["PHONE", "DESKTOP", "TABLET"],
        help="Filter by form factor",
    )
    parser.add_argument(
        "--api-key",
        help="Google API key (overrides config/env)",
    )
    parser.add_argument(
        "--origin",
        action="store_true",
        help="Force origin-level query (strip path/query)",
    )
    parser.add_argument(
        "--json", "-j",
        action="store_true",
        help="Output as JSON",
    )

    args = parser.parse_args()

    api_key = args.api_key or get_api_key()
    if not api_key:
        print("Error: API key required. Use --api-key or configure GOOGLE_API_KEY.", file=sys.stderr)
        sys.exit(1)

    target = args.url
    if args.origin:
        parsed = urlparse(target)
        target = f"{parsed.scheme}://{parsed.netloc}"

    result = query_history(target, api_key, form_factor=args.form_factor)

    if args.json:
        print(json.dumps(result, indent=2))
    else:
        if result.get("error"):
            print(f"Error: {result['error']}", file=sys.stderr)
            sys.exit(1)

        print(f"=== CrUX History ({result.get('form_factor', 'ALL')}) ===")
        print(f"Target: {result.get('target')}")

        periods = result.get("collection_periods", [])
        if periods:
            print(f"Range: {periods[0]['first']} to {periods[-1]['last']} ({len(periods)} weeks)")

        print("\nTrend Analysis:")
        for name, trend in result.get("trends", {}).items():
            label = trend.get("label", name)
            direction = trend.get("direction", "?")
            if direction == "insufficient_data":
                print(f"  {label}: Insufficient data")
                continue

            arrow = {"improving": "IMPROVING", "stable": "STABLE", "degrading": "DEGRADING"}.get(direction, "?")
            change = trend.get("change_pct", 0)
            earliest = trend.get("earliest_avg")
            latest = trend.get("latest_avg")
            print(f"  {label}: {arrow} ({change:+.1f}%) | {earliest} -> {latest}")


if __name__ == "__main__":
    main()

#!/usr/bin/env python3
"""
GA4 Data API v1beta - organic traffic reporting.

Queries the Google Analytics Data API for organic search traffic,
top landing pages, and session metrics with channel filtering.

Usage:
    python ga4_report.py --property 123456789
    python ga4_report.py --property 123456789 --days 90 --report top-pages
    python ga4_report.py --property 123456789 --report organic --json
"""

import argparse
import json
import sys
from datetime import datetime, timedelta
from typing import Optional

try:
    from google.analytics.data_v1beta import BetaAnalyticsDataClient
    from google.analytics.data_v1beta.types import (
        DateRange,
        Dimension,
        Filter,
        FilterExpression,
        Metric,
        OrderBy,
        RunReportRequest,
    )
except ImportError:
    print(
        "Error: google-analytics-data required. "
        "Install with: pip install google-analytics-data",
        file=sys.stderr,
    )
    sys.exit(1)

try:
    from google_auth import get_oauth_credentials, load_config
except ImportError:
    import os
    sys.path.insert(0, os.path.dirname(os.path.abspath(__file__)))
    from google_auth import get_oauth_credentials, load_config

GA4_SCOPES = ["https://www.googleapis.com/auth/analytics.readonly"]


def _build_ga4_client():
    """Build the GA4 BetaAnalyticsDataClient."""
    credentials = get_oauth_credentials(GA4_SCOPES)
    if not credentials:
        return None
    try:
        return BetaAnalyticsDataClient(credentials=credentials)
    except Exception as e:
        print(f"Error building GA4 client: {e}", file=sys.stderr)
        return None


def _resolve_property(property_id: str) -> str:
    """Ensure property ID is in the correct format."""
    if not property_id:
        return ""
    if property_id.startswith("properties/"):
        return property_id
    return f"properties/{property_id}"


def organic_traffic_report(
    property_id: str,
    days: int = 28,
    limit: int = 100,
) -> dict:
    """
    Generate organic traffic report from GA4.

    Filters by sessionDefaultChannelGroup == "Organic Search" and returns
    daily sessions, top landing pages, and key metrics.

    Args:
        property_id: GA4 property ID (numeric or 'properties/123456789').
        days: Number of days to query (default: 28).
        limit: Max rows (default: 100).

    Returns:
        Dictionary with daily_data, top_pages, totals, and quota usage.
    """
    result = {
        "property": property_id,
        "report": "organic_traffic",
        "date_range": None,
        "totals": {},
        "daily_data": [],
        "top_pages": [],
        "quota_tokens_used": None,
        "error": None,
    }

    client = _build_ga4_client()
    if not client:
        result["error"] = (
            "Could not build GA4 client. Ensure the service account has "
            "Viewer access in GA4 Admin > Property Access Management."
        )
        return result

    prop = _resolve_property(property_id)
    start_date = (datetime.now() - timedelta(days=days)).strftime("%Y-%m-%d")
    end_date = (datetime.now() - timedelta(days=1)).strftime("%Y-%m-%d")
    result["date_range"] = {"start": start_date, "end": end_date}

    # Daily organic sessions
    try:
        daily_request = RunReportRequest(
            property=prop,
            dimensions=[Dimension(name="date")],
            metrics=[
                Metric(name="sessions"),
                Metric(name="totalUsers"),
                Metric(name="screenPageViews"),
                Metric(name="bounceRate"),
                Metric(name="averageSessionDuration"),
                Metric(name="engagementRate"),
            ],
            date_ranges=[DateRange(start_date=start_date, end_date=end_date)],
            dimension_filter=FilterExpression(
                filter=Filter(
                    field_name="sessionDefaultChannelGroup",
                    string_filter=Filter.StringFilter(
                        match_type=Filter.StringFilter.MatchType.EXACT,
                        value="Organic Search",
                    ),
                )
            ),
            order_bys=[OrderBy(dimension=OrderBy.DimensionOrderBy(dimension_name="date"))],
            limit=days + 5,
            return_property_quota=True,
        )

        daily_response = client.run_report(daily_request)

        for row in daily_response.rows:
            result["daily_data"].append({
                "date": row.dimension_values[0].value,
                "sessions": int(row.metric_values[0].value),
                "users": int(row.metric_values[1].value),
                "pageviews": int(row.metric_values[2].value),
                "bounce_rate": round(float(row.metric_values[3].value) * 100, 1),
                "avg_session_duration": round(float(row.metric_values[4].value), 1),
                "engagement_rate": round(float(row.metric_values[5].value) * 100, 1),
            })

        # Quota info
        if daily_response.property_quota:
            pq = daily_response.property_quota
            result["quota_tokens_used"] = {
                "daily_consumed": pq.tokens_per_day.consumed if pq.tokens_per_day else None,
                "daily_remaining": pq.tokens_per_day.remaining if pq.tokens_per_day else None,
                "hourly_consumed": pq.tokens_per_hour.consumed if pq.tokens_per_hour else None,
                "hourly_remaining": pq.tokens_per_hour.remaining if pq.tokens_per_hour else None,
            }

    except Exception as e:
        error_str = str(e)
        if "403" in error_str or "PERMISSION_DENIED" in error_str:
            result["error"] = (
                f"Permission denied for property '{property_id}'. "
                "Add the service account email as Viewer in "
                "GA4 Admin > Property Access Management."
            )
        elif "404" in error_str or "NOT_FOUND" in error_str:
            result["error"] = (
                f"Property '{property_id}' not found. "
                "Verify the numeric property ID in GA4 Admin > Property Details."
            )
        else:
            result["error"] = f"GA4 API error: {e}"
        return result

    # Top landing pages by organic sessions
    try:
        pages_request = RunReportRequest(
            property=prop,
            dimensions=[Dimension(name="landingPage")],
            metrics=[
                Metric(name="sessions"),
                Metric(name="totalUsers"),
                Metric(name="screenPageViews"),
                Metric(name="bounceRate"),
                Metric(name="engagementRate"),
            ],
            date_ranges=[DateRange(start_date=start_date, end_date=end_date)],
            dimension_filter=FilterExpression(
                filter=Filter(
                    field_name="sessionDefaultChannelGroup",
                    string_filter=Filter.StringFilter(
                        match_type=Filter.StringFilter.MatchType.EXACT,
                        value="Organic Search",
                    ),
                )
            ),
            order_bys=[
                OrderBy(
                    metric=OrderBy.MetricOrderBy(metric_name="sessions"),
                    desc=True,
                )
            ],
            limit=limit,
        )

        pages_response = client.run_report(pages_request)

        for row in pages_response.rows:
            result["top_pages"].append({
                "landing_page": row.dimension_values[0].value,
                "sessions": int(row.metric_values[0].value),
                "users": int(row.metric_values[1].value),
                "pageviews": int(row.metric_values[2].value),
                "bounce_rate": round(float(row.metric_values[3].value) * 100, 1),
                "engagement_rate": round(float(row.metric_values[4].value) * 100, 1),
            })

    except Exception as e:
        # Non-fatal: daily data succeeded, pages failed
        result["pages_error"] = f"Error fetching top pages: {e}"

    # Calculate totals
    if result["daily_data"]:
        total_sessions = sum(d["sessions"] for d in result["daily_data"])
        total_users = sum(d["users"] for d in result["daily_data"])
        total_pageviews = sum(d["pageviews"] for d in result["daily_data"])
        result["totals"] = {
            "sessions": total_sessions,
            "users": total_users,
            "pageviews": total_pageviews,
            "avg_daily_sessions": round(total_sessions / len(result["daily_data"]), 1),
        }

    return result


def top_pages_report(
    property_id: str,
    days: int = 28,
    limit: int = 50,
) -> dict:
    """
    Get top organic landing pages from GA4.

    Args:
        property_id: GA4 property ID.
        days: Number of days.
        limit: Max pages to return.

    Returns:
        Dictionary with top pages ranked by organic sessions.
    """
    report = organic_traffic_report(property_id, days, limit)
    # Slim it down to just pages
    return {
        "property": property_id,
        "report": "top_organic_pages",
        "date_range": report.get("date_range"),
        "pages": report.get("top_pages", []),
        "total_organic_sessions": report.get("totals", {}).get("sessions", 0),
        "quota_tokens_used": report.get("quota_tokens_used"),
        "error": report.get("error"),
    }


def device_breakdown(
    property_id: str,
    days: int = 28,
) -> dict:
    """
    Organic sessions broken down by device category.

    Args:
        property_id: GA4 property ID.
        days: Number of days.

    Returns:
        Dictionary with device breakdown data.
    """
    result = {"property": property_id, "report": "device_breakdown", "devices": [], "error": None}

    client = _build_ga4_client()
    if not client:
        result["error"] = "Could not build GA4 client."
        return result

    prop = _resolve_property(property_id)
    start_date = (datetime.now() - timedelta(days=days)).strftime("%Y-%m-%d")
    end_date = (datetime.now() - timedelta(days=1)).strftime("%Y-%m-%d")
    result["date_range"] = {"start": start_date, "end": end_date}

    try:
        request = RunReportRequest(
            property=prop,
            dimensions=[Dimension(name="deviceCategory")],
            metrics=[
                Metric(name="sessions"),
                Metric(name="totalUsers"),
                Metric(name="bounceRate"),
                Metric(name="engagementRate"),
            ],
            date_ranges=[DateRange(start_date=start_date, end_date=end_date)],
            dimension_filter=FilterExpression(
                filter=Filter(
                    field_name="sessionDefaultChannelGroup",
                    string_filter=Filter.StringFilter(
                        match_type=Filter.StringFilter.MatchType.EXACT,
                        value="Organic Search",
                    ),
                )
            ),
            order_bys=[OrderBy(metric=OrderBy.MetricOrderBy(metric_name="sessions"), desc=True)],
        )
        response = client.run_report(request)
        for row in response.rows:
            result["devices"].append({
                "category": row.dimension_values[0].value,
                "sessions": int(row.metric_values[0].value),
                "users": int(row.metric_values[1].value),
                "bounce_rate": round(float(row.metric_values[2].value) * 100, 1),
                "engagement_rate": round(float(row.metric_values[3].value) * 100, 1),
            })
    except Exception as e:
        result["error"] = f"GA4 device breakdown error: {e}"

    return result


def country_breakdown(
    property_id: str,
    days: int = 28,
    limit: int = 20,
) -> dict:
    """
    Organic sessions broken down by country.

    Args:
        property_id: GA4 property ID.
        days: Number of days.
        limit: Max countries to return.

    Returns:
        Dictionary with country breakdown data.
    """
    result = {"property": property_id, "report": "country_breakdown", "countries": [], "error": None}

    client = _build_ga4_client()
    if not client:
        result["error"] = "Could not build GA4 client."
        return result

    prop = _resolve_property(property_id)
    start_date = (datetime.now() - timedelta(days=days)).strftime("%Y-%m-%d")
    end_date = (datetime.now() - timedelta(days=1)).strftime("%Y-%m-%d")
    result["date_range"] = {"start": start_date, "end": end_date}

    try:
        request = RunReportRequest(
            property=prop,
            dimensions=[Dimension(name="country")],
            metrics=[
                Metric(name="sessions"),
                Metric(name="totalUsers"),
            ],
            date_ranges=[DateRange(start_date=start_date, end_date=end_date)],
            dimension_filter=FilterExpression(
                filter=Filter(
                    field_name="sessionDefaultChannelGroup",
                    string_filter=Filter.StringFilter(
                        match_type=Filter.StringFilter.MatchType.EXACT,
                        value="Organic Search",
                    ),
                )
            ),
            order_bys=[OrderBy(metric=OrderBy.MetricOrderBy(metric_name="sessions"), desc=True)],
            limit=limit,
        )
        response = client.run_report(request)
        for row in response.rows:
            result["countries"].append({
                "country": row.dimension_values[0].value,
                "sessions": int(row.metric_values[0].value),
                "users": int(row.metric_values[1].value),
            })
    except Exception as e:
        result["error"] = f"GA4 country breakdown error: {e}"

    return result


def main():
    parser = argparse.ArgumentParser(
        description="GA4 Data API - organic traffic reporting"
    )
    parser.add_argument(
        "--property", "-p",
        help="GA4 property ID (numeric, e.g., 123456789). Uses config default if not specified.",
    )
    parser.add_argument("--days", "-d", type=int, default=28, help="Number of days (default: 28)")
    parser.add_argument(
        "--report", "-r",
        choices=["organic", "top-pages", "device", "country"],
        default="organic",
        help="Report type (default: organic)",
    )
    parser.add_argument("--limit", type=int, default=50, help="Max rows (default: 50)")
    parser.add_argument("--json", "-j", action="store_true", help="Output as JSON")

    args = parser.parse_args()

    # Resolve property
    prop = args.property
    if not prop:
        config = load_config()
        prop = config.get("ga4_property_id") or ""
        # Strip 'properties/' prefix if present for consistency
        if prop and prop.startswith("properties/"):
            prop = prop[len("properties/"):]
    if not prop:
        print(
            "Error: No GA4 property specified. Use --property or set ga4_property_id in config.",
            file=sys.stderr,
        )
        sys.exit(1)

    if args.report == "top-pages":
        result = top_pages_report(prop, args.days, args.limit)
    elif args.report == "device":
        result = device_breakdown(prop, args.days)
    elif args.report == "country":
        result = country_breakdown(prop, args.days, args.limit)
    else:
        result = organic_traffic_report(prop, args.days, args.limit)

    if result.get("error"):
        print(f"Error: {result['error']}", file=sys.stderr)
        if not args.json:
            sys.exit(1)

    if args.json:
        print(json.dumps(result, indent=2, default=str))
    else:
        if args.report == "top-pages":
            print(f"=== Top Organic Landing Pages ===")
            print(f"Property: {prop} | Period: {result.get('date_range', {}).get('start')} to {result.get('date_range', {}).get('end')}")
            print(f"Total organic sessions: {result.get('total_organic_sessions', 0):,}")
            print()
            for i, page in enumerate(result.get("pages", [])[:20], 1):
                print(f"  {i:2d}. {page['landing_page']}")
                print(f"      Sessions: {page['sessions']:,} | Users: {page['users']:,} | Bounce: {page['bounce_rate']}%")
        else:
            totals = result.get("totals", {})
            print(f"=== GA4 Organic Traffic Report ===")
            print(f"Property: {prop}")
            dr = result.get("date_range", {})
            print(f"Period: {dr.get('start')} to {dr.get('end')}")
            print(f"\nSessions: {totals.get('sessions', 0):,} | Users: {totals.get('users', 0):,} | Pageviews: {totals.get('pageviews', 0):,}")
            print(f"Avg Daily Sessions: {totals.get('avg_daily_sessions', 0):,.0f}")

            quota = result.get("quota_tokens_used")
            if quota and quota.get("daily_remaining") is not None:
                print(f"\nQuota: {quota['daily_consumed']} tokens used / {quota['daily_remaining']} remaining (daily)")

            pages = result.get("top_pages", [])
            if pages:
                print(f"\nTop {min(10, len(pages))} Organic Landing Pages:")
                for i, page in enumerate(pages[:10], 1):
                    print(f"  {i:2d}. {page['landing_page']} ({page['sessions']:,} sessions)")


if __name__ == "__main__":
    main()

#!/usr/bin/env python3
"""
Google API credential management for Claude SEO.

Loads and validates credentials for Google Search Console, PageSpeed Insights,
CrUX, Indexing API, and GA4. Supports service accounts, OAuth web credentials
with token refresh, API keys, and environment variable fallbacks.

Usage:
    python google_auth.py --check                  # Check all credentials
    python google_auth.py --check gsc              # Check specific service
    python google_auth.py --check --json            # JSON output
    python google_auth.py --setup                   # Show setup instructions
    python google_auth.py --tier                    # Show detected credential tier
    python google_auth.py --auth --creds /path/to/client_secret.json  # OAuth browser flow
"""

import argparse
import json
import os
import secrets
import sys
import tempfile
import time
from typing import Optional

CONFIG_PATH = os.path.expanduser("~/.config/claude-seo/google-api.json")
TOKEN_PATH = os.path.expanduser("~/.config/claude-seo/oauth-token.json")

# Service-to-scope mapping
SCOPES = {
    "gsc_readonly": "https://www.googleapis.com/auth/webmasters.readonly",
    "gsc_write": "https://www.googleapis.com/auth/webmasters",
    "indexing": "https://www.googleapis.com/auth/indexing",
    "ga4": "https://www.googleapis.com/auth/analytics.readonly",
}

# Which services need which auth type
SERVICE_AUTH = {
    "psi": "api_key",
    "crux": "api_key",
    "crux_history": "api_key",
    "gsc": "oauth_or_sa",
    "indexing": "oauth_or_sa",
    "ga4": "oauth_or_sa",
}

OAUTH_REDIRECT_URI = "http://127.0.0.1:8085"


def _write_secret_atomic(path: str, content: str) -> None:
    """Atomically write `content` to `path` with mode 0o600.

    Uses tempfile in same dir + os.replace for atomicity (no partial writes
    on crash). Sets restrictive file mode before writing payload.
    """
    # Bare-filename safety: os.path.dirname returns "" if path has no dir
    # component. Pass that to mkstemp(dir="") and it errors with FileNotFoundError.
    parent = os.path.dirname(path) or "."
    os.makedirs(parent, mode=0o700, exist_ok=True)
    fd, tmp = tempfile.mkstemp(dir=parent, prefix=".tmp-")
    try:
        os.fchmod(fd, 0o600)
        with os.fdopen(fd, "w") as f:
            f.write(content)
        os.replace(tmp, path)
        os.chmod(path, 0o600)  # belt-and-braces if file pre-existed
    except Exception:
        try:
            os.unlink(tmp)
        except OSError:
            pass
        raise


def _scopes_for(services: list = None) -> str:
    """Build OAuth scope string for the requested services.

    Defaults to a read-only set so OAuth-without-flag grants minimal scopes.
    """
    if services is None:
        # Safer default: read-only scopes only.
        services = ["gsc_readonly", "ga4"]
    scope_urls = []
    for s in services:
        if s in SCOPES:
            scope_urls.append(SCOPES[s])
        else:
            raise ValueError(f"Unknown scope service: {s}")
    return " ".join(scope_urls)

# Human-readable service names
SERVICE_NAMES = {
    "psi": "PageSpeed Insights v5",
    "crux": "Chrome UX Report (CrUX) API",
    "crux_history": "CrUX History API",
    "gsc": "Google Search Console API",
    "indexing": "Google Indexing API v3",
    "ga4": "GA4 Data API v1beta",
}


def load_config() -> dict:
    """
    Load configuration from config file with environment variable fallbacks.

    Reads ~/.config/claude-seo/google-api.json first. Any missing fields
    are filled from environment variables.

    Returns:
        Dictionary with keys: service_account_path, api_key,
        default_property, ga4_property_id. Missing values are None.
    """
    config = {
        "service_account_path": None,
        "api_key": None,
        "default_property": None,
        "ga4_property_id": None,
    }

    # Load from config file
    if os.path.exists(CONFIG_PATH):
        try:
            with open(CONFIG_PATH, "r") as f:
                file_config = json.load(f)
            config.update({k: v for k, v in file_config.items() if v})
        except (json.JSONDecodeError, IOError) as e:
            print(f"Warning: Could not read config file: {e}", file=sys.stderr)

    # Environment variable fallbacks
    if not config["service_account_path"]:
        config["service_account_path"] = os.environ.get("GOOGLE_APPLICATION_CREDENTIALS")

    if not config["api_key"]:
        config["api_key"] = os.environ.get("GOOGLE_API_KEY")

    if not config["ga4_property_id"]:
        config["ga4_property_id"] = os.environ.get("GA4_PROPERTY_ID")

    if not config["default_property"]:
        config["default_property"] = os.environ.get("GSC_PROPERTY")

    return config


def get_service_account_credentials(scopes: list):
    """
    Load Google service account credentials.

    Args:
        scopes: List of OAuth scope URLs.

    Returns:
        google.oauth2.service_account.Credentials object, or None on failure.
    """
    try:
        from google.oauth2 import service_account
    except ImportError:
        print(
            "Error: google-auth library required. "
            "Install with: pip install google-auth",
            file=sys.stderr,
        )
        return None

    config = load_config()
    sa_path = config.get("service_account_path")

    if not sa_path:
        return None

    sa_path = os.path.expanduser(sa_path)
    if not os.path.exists(sa_path):
        print(
            f"Error: Service account file not found: {sa_path}",
            file=sys.stderr,
        )
        return None

    try:
        credentials = service_account.Credentials.from_service_account_file(
            sa_path, scopes=scopes
        )
        return credentials
    except Exception as e:
        print(f"Error loading service account: {e}", file=sys.stderr)
        return None


def _load_oauth_client(creds_path: str) -> Optional[dict]:
    """Load OAuth client credentials from a client_secret JSON file."""
    try:
        with open(creds_path, "r") as f:
            data = json.load(f)
        return data.get("web", data.get("installed", {}))
    except (json.JSONDecodeError, IOError) as e:
        print(f"Error reading OAuth client file: {e}", file=sys.stderr)
        return None


def _load_oauth_token() -> Optional[dict]:
    """Load saved OAuth token from TOKEN_PATH."""
    if not os.path.exists(TOKEN_PATH):
        return None
    try:
        with open(TOKEN_PATH, "r") as f:
            return json.load(f)
    except (json.JSONDecodeError, IOError):
        return None


def _save_oauth_token(token_data: dict):
    """Save OAuth token to TOKEN_PATH with mode 0o600 and atomic write."""
    _write_secret_atomic(TOKEN_PATH, json.dumps(token_data, indent=2))


def _refresh_oauth_token(client: dict, token_data: dict) -> Optional[dict]:
    """Refresh an expired OAuth token using the refresh_token."""
    import urllib.parse
    import urllib.request

    if not token_data.get("refresh_token"):
        return None

    params = urllib.parse.urlencode({
        "client_id": client["client_id"],
        "client_secret": client["client_secret"],
        "refresh_token": token_data["refresh_token"],
        "grant_type": "refresh_token",
    }).encode()

    try:
        req = urllib.request.Request(client.get("token_uri", "https://oauth2.googleapis.com/token"), data=params)
        with urllib.request.urlopen(req) as resp:
            new_data = json.loads(resp.read())
        token_data["access_token"] = new_data["access_token"]
        token_data["expires_at"] = time.time() + new_data.get("expires_in", 3600)
        if "refresh_token" in new_data:  # Google now sometimes rotates these
            token_data["refresh_token"] = new_data["refresh_token"]
        # AUTH-001 (v1.9.1): strip client_secret on every save so older
        # token files migrate forward the first time they're refreshed.
        token_data.pop("client_secret", None)
        _save_oauth_token(token_data)
        return token_data
    except Exception as e:
        print(f"Error refreshing OAuth token: {e}", file=sys.stderr)
        return None


def get_oauth_credentials(scopes: list):
    """
    Get OAuth credentials from saved token, refreshing if needed.

    Falls back to service account if no OAuth token is available.

    Args:
        scopes: List of OAuth scope URLs (used for service account fallback).

    Returns:
        google.oauth2.credentials.Credentials or service_account.Credentials, or None.
    """
    config = load_config()

    # Try OAuth token first
    token_data = _load_oauth_token()
    if token_data and token_data.get("access_token"):
        # Check if token needs refresh
        if time.time() > token_data.get("expires_at", 0) - 60:
            oauth_creds_path = config.get("oauth_client_path")
            if oauth_creds_path:
                client = _load_oauth_client(os.path.expanduser(oauth_creds_path))
                if client:
                    token_data = _refresh_oauth_token(client, token_data)
                    if not token_data:
                        print("OAuth token refresh failed. Re-run --auth.", file=sys.stderr)
                        return get_service_account_credentials(scopes)

        if token_data and token_data.get("access_token"):
            try:
                from google.oauth2.credentials import Credentials
                # AUTH-001 (v1.9.1): client_secret is no longer stored in
                # the token file. Re-read from config["oauth_client_path"]
                # so the long-lived app credential stays in its own
                # 0o600 file (and is referenced, not duplicated).
                # Backwards-compat: legacy token files still containing
                # client_secret are honored (token_data.get fallback)
                # until v1.10.0 makes oauth_client_path mandatory.
                client_secret = None
                oauth_creds_path = config.get("oauth_client_path")
                if oauth_creds_path:
                    client = _load_oauth_client(os.path.expanduser(oauth_creds_path))
                    if client:
                        client_secret = client.get("client_secret")
                if client_secret is None:
                    client_secret = token_data.get("client_secret")  # legacy compat
                return Credentials(
                    token=token_data["access_token"],
                    refresh_token=token_data.get("refresh_token"),
                    token_uri="https://oauth2.googleapis.com/token",
                    client_id=token_data.get("client_id"),
                    client_secret=client_secret,
                )
            except ImportError:
                print("Error: google-auth required. Install with: pip install google-auth", file=sys.stderr)

    # Fall back to service account
    return get_service_account_credentials(scopes)


def run_oauth_flow(creds_path: str, services: list = None):
    """
    Run OAuth browser-based authentication flow.

    Opens a browser for consent, captures the auth code via local HTTP server,
    exchanges for tokens, and saves them.

    Args:
        creds_path: Path to the OAuth client_secret JSON file.
        services: Optional list of scope service keys (see SCOPES). Defaults to
            the read-only set built by `_scopes_for(None)`.
    """
    import http.server
    import urllib.parse
    import urllib.request
    import webbrowser

    client = _load_oauth_client(creds_path)
    if not client:
        print("Error: Could not load OAuth client credentials.", file=sys.stderr)
        sys.exit(1)

    state_token = secrets.token_urlsafe(32)
    scopes_str = _scopes_for(services)

    auth_params = {
        "client_id": client["client_id"],
        "redirect_uri": OAUTH_REDIRECT_URI,
        "response_type": "code",
        "scope": scopes_str,
        "access_type": "offline",
        "prompt": "consent",
        "state": state_token,
        "include_granted_scopes": "true",
    }
    auth_url = (
        f"{client.get('auth_uri', 'https://accounts.google.com/o/oauth2/auth')}"
        f"?{urllib.parse.urlencode(auth_params)}"
    )

    auth_code = [None]

    class Handler(http.server.BaseHTTPRequestHandler):
        def do_GET(self):
            params = urllib.parse.parse_qs(urllib.parse.urlparse(self.path).query)
            received_state = params.get("state", [""])[0]
            if received_state != state_token:
                self.send_response(403)
                self.send_header("Content-Type", "text/plain")
                self.end_headers()
                self.wfile.write(b"State mismatch - possible CSRF. Aborted.")
                return
            if "code" in params:
                auth_code[0] = params["code"][0]
                self.send_response(200)
                self.send_header("Content-Type", "text/html")
                self.end_headers()
                self.wfile.write(b"<html><body><h1>Authorization complete.</h1>You can close this tab.</body></html>")
            else:
                self.send_response(400)
                self.end_headers()
        def log_message(self, *a):
            pass

    server = http.server.HTTPServer(("127.0.0.1", 8085), Handler)
    server.timeout = 300

    print(f"\nOpen this URL in your browser:\n\n{auth_url}\n")
    print("Waiting up to 5 minutes for authentication...")

    try:
        webbrowser.open(auth_url)
    except Exception:
        pass

    server.handle_request()
    server.server_close()

    if not auth_code[0]:
        print("\nAuthentication failed or timed out.", file=sys.stderr)
        print("If the browser showed '127.0.0.1 refused to connect', copy the full URL")
        print("from the browser address bar and run:")
        print(f"  python scripts/google_auth.py --exchange --creds {creds_path} --code 'THE_CODE'")
        sys.exit(1)

    # Exchange code for tokens
    _exchange_code(client, auth_code[0])


def _exchange_code(client: dict, code: str):
    """Exchange an authorization code for tokens."""
    import urllib.parse
    import urllib.request

    params = urllib.parse.urlencode({
        "code": code,
        "client_id": client["client_id"],
        "client_secret": client["client_secret"],
        "redirect_uri": OAUTH_REDIRECT_URI,
        "grant_type": "authorization_code",
    }).encode()

    try:
        req = urllib.request.Request(
            client.get("token_uri", "https://oauth2.googleapis.com/token"), data=params
        )
        with urllib.request.urlopen(req) as resp:
            token_data = json.loads(resp.read())
        token_data["expires_at"] = time.time() + token_data.get("expires_in", 3600)
        token_data["client_id"] = client["client_id"]
        # AUTH-001 (v1.9.1): client_secret is NO LONGER stored in the token
        # file. Co-locating the long-lived app credential with the
        # short-lived access token expands blast radius if the token file
        # leaks. Refresh paths re-read client_secret from
        # config["oauth_client_path"] instead. See get_oauth_credentials.
        token_data.pop("client_secret", None)
        _save_oauth_token(token_data)
        print("OAuth token saved successfully!")

        # Also save the OAuth client path to config
        config = load_config()
        # Don't overwrite existing config, just suggest
        print(f"\nToken saved to: {TOKEN_PATH}")
    except Exception as e:
        print(f"Error exchanging authorization code: {e}", file=sys.stderr)
        sys.exit(1)


def get_api_key() -> Optional[str]:
    """
    Get the Google API key from config or environment.

    Returns:
        API key string, or None if not configured.
    """
    config = load_config()
    return config.get("api_key")


def build_service(api_name: str, version: str, scopes: list):
    """
    Build a Google API discovery service client.

    Args:
        api_name: API name (e.g., 'searchconsole', 'indexing', 'pagespeedonline').
        version: API version (e.g., 'v1', 'v3', 'v5').
        scopes: OAuth scopes needed.

    Returns:
        googleapiclient.discovery.Resource object, or None on failure.
    """
    try:
        from googleapiclient.discovery import build
    except ImportError:
        print(
            "Error: google-api-python-client required. "
            "Install with: pip install google-api-python-client",
            file=sys.stderr,
        )
        return None

    credentials = get_oauth_credentials(scopes)
    if not credentials:
        return None

    try:
        service = build(api_name, version, credentials=credentials)
        return service
    except Exception as e:
        print(f"Error building {api_name} service: {e}", file=sys.stderr)
        return None


def check_credentials(service: str) -> dict:
    """
    Validate credentials for a specific Google API service.

    Args:
        service: One of 'psi', 'crux', 'crux_history', 'gsc', 'indexing', 'ga4'.

    Returns:
        Dictionary with:
            - available: bool
            - method: 'api_key' or 'service_account'
            - service: service name
            - error: error message or None
    """
    result = {
        "available": False,
        "method": SERVICE_AUTH.get(service, "unknown"),
        "service": SERVICE_NAMES.get(service, service),
        "error": None,
    }

    config = load_config()

    if SERVICE_AUTH.get(service) == "api_key":
        api_key = config.get("api_key")
        if api_key:
            result["available"] = True
        else:
            result["error"] = (
                "No API key found. Set GOOGLE_API_KEY environment variable "
                f"or add 'api_key' to {CONFIG_PATH}"
            )

    elif SERVICE_AUTH.get(service) == "oauth_or_sa":
        # Check OAuth token first
        token_data = _load_oauth_token()
        if token_data and token_data.get("access_token"):
            result["available"] = True
            result["method"] = "oauth_token"
            expired = time.time() > token_data.get("expires_at", 0) - 60
            if expired and token_data.get("refresh_token"):
                result["note"] = "Token expired but refresh_token available (will auto-refresh)"
            elif expired:
                result["available"] = False
                result["error"] = "OAuth token expired and no refresh_token. Re-run --auth."
        else:
            # Fall back to service account
            sa_path = config.get("service_account_path")
            if not sa_path:
                result["error"] = (
                    "No OAuth token or service account found. Either:\n"
                    "         1. Run: python scripts/google_auth.py --auth --creds /path/to/client_secret.json\n"
                    f"         2. Or add 'service_account_path' to {CONFIG_PATH}"
                )
            else:
                sa_path = os.path.expanduser(sa_path)
                if not os.path.exists(sa_path):
                    result["error"] = f"Service account file not found: {sa_path}"
                else:
                    try:
                        with open(sa_path, "r") as f:
                            sa_data = json.load(f)
                        if "client_email" not in sa_data or "private_key" not in sa_data:
                            result["error"] = "Service account JSON missing required fields (client_email, private_key)"
                        else:
                            result["available"] = True
                            result["method"] = "service_account"
                            result["client_email"] = sa_data.get("client_email")
                    except (json.JSONDecodeError, IOError) as e:
                        result["error"] = f"Invalid service account file: {e}"

        # GA4 also needs property ID
        if service == "ga4" and result["available"]:
            ga4_id = config.get("ga4_property_id")
            if not ga4_id:
                result["available"] = False
                result["error"] = (
                    "Credentials found but no GA4 property ID configured. "
                    f"Set GA4_PROPERTY_ID or add 'ga4_property_id' to {CONFIG_PATH}"
                )
    else:
        result["error"] = f"Unknown service: {service}"

    return result


def detect_tier() -> dict:
    """
    Detect the credential tier available.

    Returns:
        Dictionary with:
            - tier: 0, 1, or 2
            - description: human-readable tier description
            - capabilities: list of available API groups
            - missing: what's needed for the next tier
    """
    config = load_config()

    has_api_key = bool(config.get("api_key"))
    has_authenticated = False
    has_ga4 = False
    auth_method = None

    # Check OAuth token
    token_data = _load_oauth_token()
    if token_data and token_data.get("access_token"):
        has_authenticated = True
        auth_method = "oauth_token"

    # Check service account
    if not has_authenticated:
        sa_path = config.get("service_account_path")
        if sa_path:
            sa_path = os.path.expanduser(sa_path)
            if os.path.exists(sa_path):
                try:
                    with open(sa_path, "r") as f:
                        sa_data = json.load(f)
                    if "client_email" in sa_data and "private_key" in sa_data:
                        has_authenticated = True
                        auth_method = "service_account"
                except (json.JSONDecodeError, IOError):
                    pass

    if has_authenticated and config.get("ga4_property_id"):
        has_ga4 = True

    if has_ga4:
        return {
            "tier": 2,
            "description": "Full (API key + Service Account + GA4)",
            "capabilities": [
                "PageSpeed Insights", "CrUX", "CrUX History",
                "Search Console", "URL Inspection", "Sitemaps",
                "Indexing API", "GA4 Organic Traffic",
            ],
            "missing": None,
        }
    elif has_authenticated:
        return {
            "tier": 1,
            "description": "Authenticated (API key + OAuth/Service Account)",
            "capabilities": [
                "PageSpeed Insights", "CrUX", "CrUX History",
                "Search Console", "URL Inspection", "Sitemaps",
                "Indexing API",
            ],
            "missing": "Add 'ga4_property_id' to unlock GA4 organic traffic reports",
        }
    elif has_api_key:
        return {
            "tier": 0,
            "description": "API Key Only",
            "capabilities": [
                "PageSpeed Insights", "CrUX", "CrUX History",
            ],
            "missing": "Add a service account to unlock Search Console, URL Inspection, and Indexing API",
        }
    else:
        return {
            "tier": -1,
            "description": "No credentials configured",
            "capabilities": [],
            "missing": (
                f"Create config at {CONFIG_PATH} with at minimum an 'api_key' field. "
                "Run with --setup for full instructions."
            ),
        }


def print_setup_instructions():
    """Print step-by-step setup instructions."""
    print("""
Google SEO API Setup Instructions
=================================

1. CREATE A GOOGLE CLOUD PROJECT
   - Go to https://console.cloud.google.com
   - Create a new project (or select existing)
   - Note the project ID

2. ENABLE APIs
   In API Library (APIs & Services > Library), enable:
   - Google Search Console API
   - PageSpeed Insights API
   - Chrome UX Report API
   - Web Search Indexing API (for Indexing API)
   - Google Analytics Data API (for GA4)

3. CREATE AN API KEY (for PSI, CrUX - free, no service account needed)
   - APIs & Services > Credentials > Create Credentials > API key
   - Restrict to: PageSpeed Insights API, Chrome UX Report API

4. CREATE A SERVICE ACCOUNT (for GSC, Indexing API, GA4)
   - IAM & Admin > Service Accounts > Create Service Account
   - Download JSON key file, store securely

5. GRANT ACCESS
   - Search Console: Settings > Users and permissions > Add user
     Paste the service account client_email, set as Owner (for Indexing API) or Full (read-only)
   - GA4: Admin > Property Access Management > Add
     Paste email, set Viewer role

6. CREATE CONFIG FILE
   mkdir -p ~/.config/claude-seo
   Save to ~/.config/claude-seo/google-api.json:

   {
     "service_account_path": "/path/to/service_account.json",
     "api_key": "AIzaSy...",
     "default_property": "sc-domain:example.com",
     "ga4_property_id": "properties/123456789"
   }

7. VERIFY
   python scripts/google_auth.py --check

ENVIRONMENT VARIABLE ALTERNATIVES:
   GOOGLE_API_KEY              - API key
   GOOGLE_APPLICATION_CREDENTIALS - Path to service account JSON
   GA4_PROPERTY_ID             - GA4 property ID (e.g., properties/123456789)
   GSC_PROPERTY                - Default Search Console property
""")


def main():
    parser = argparse.ArgumentParser(
        description="Google API credential management for Claude SEO"
    )
    parser.add_argument(
        "--check",
        nargs="?",
        const="all",
        metavar="SERVICE",
        help="Check credentials. Optionally specify service: psi, crux, gsc, indexing, ga4",
    )
    parser.add_argument(
        "--setup",
        action="store_true",
        help="Show setup instructions",
    )
    parser.add_argument(
        "--tier",
        action="store_true",
        help="Show detected credential tier",
    )
    parser.add_argument(
        "--json",
        action="store_true",
        help="Output as JSON",
    )
    parser.add_argument(
        "--auth",
        action="store_true",
        help="Run OAuth browser-based authentication flow",
    )
    parser.add_argument(
        "--exchange",
        action="store_true",
        help="Manually exchange an auth code for tokens",
    )
    parser.add_argument(
        "--creds",
        help="Path to OAuth client_secret JSON file (for --auth and --exchange)",
    )
    parser.add_argument(
        "--code",
        help="Authorization code to exchange (for --exchange)",
    )
    parser.add_argument(
        "--scopes",
        help=(
            "Comma-separated scope service keys for --auth (e.g. "
            "'gsc_readonly,ga4' or 'indexing,gsc_write'). Defaults to a "
            "read-only set: gsc_readonly,ga4."
        ),
    )

    args = parser.parse_args()

    if args.auth:
        if not args.creds:
            print("Error: --creds is required with --auth", file=sys.stderr)
            sys.exit(1)
        services = None
        if args.scopes:
            services = [s.strip() for s in args.scopes.split(",") if s.strip()]
        try:
            run_oauth_flow(args.creds, services=services)
        except ValueError as e:
            # _scopes_for raises ValueError for unknown service keys.
            # Surface a clean error instead of a stack trace.
            print(f"Error: {e}", file=sys.stderr)
            print(
                f"Valid scope keys: {', '.join(sorted(SCOPES.keys()))}",
                file=sys.stderr,
            )
            sys.exit(2)
        return

    if args.exchange:
        if not args.creds or not args.code:
            print("Error: --creds and --code are required with --exchange", file=sys.stderr)
            sys.exit(1)
        client = _load_oauth_client(args.creds)
        if client:
            _exchange_code(client, args.code)
        return

    if args.setup:
        print_setup_instructions()
        return

    if args.tier:
        tier_info = detect_tier()
        if args.json:
            print(json.dumps(tier_info, indent=2))
        else:
            print(f"Credential Tier: {tier_info['tier']} - {tier_info['description']}")
            if tier_info["capabilities"]:
                print(f"Available APIs: {', '.join(tier_info['capabilities'])}")
            if tier_info["missing"]:
                print(f"Next tier: {tier_info['missing']}")
        return

    if args.check:
        services = (
            list(SERVICE_AUTH.keys())
            if args.check == "all"
            else [args.check]
        )

        results = {}
        for svc in services:
            if svc not in SERVICE_AUTH:
                results[svc] = {"available": False, "error": f"Unknown service: {svc}"}
                continue
            results[svc] = check_credentials(svc)

        if args.json:
            tier_info = detect_tier()
            output = {"tier": tier_info, "services": results}
            print(json.dumps(output, indent=2))
        else:
            tier_info = detect_tier()
            print(f"Credential Tier: {tier_info['tier']} - {tier_info['description']}")
            print()
            for svc, result in results.items():
                status = "OK" if result["available"] else "MISSING"
                print(f"  [{status}] {result.get('service', svc)}")
                if result.get("error"):
                    print(f"         {result['error']}")
                if result.get("client_email"):
                    print(f"         Service account: {result['client_email']}")
            print()
            if tier_info["missing"]:
                print(f"Tip: {tier_info['missing']}")
        return

    # Default: show tier
    tier_info = detect_tier()
    if args.json:
        print(json.dumps(tier_info, indent=2))
    else:
        print(f"Credential Tier: {tier_info['tier']} - {tier_info['description']}")
        if tier_info["missing"]:
            print(f"Run --setup for configuration instructions.")


if __name__ == "__main__":
    main()