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

ga_cli/auth/service_account.py

@@ -0,0 +1,155 @@
+"""Service account authentication.
+
+Supports:
+1. GA_CLI_SERVICE_ACCOUNT env var (path to key file)
+2. GOOGLE_APPLICATION_CREDENTIALS env var (standard Google convention)
+3. Saved auth method from a previous ``ga auth login --service-account`` call
+
+Equivalent to GTM CLI's auth/service-account.ts.
+"""
+
+from __future__ import annotations
+
+import json
+import logging
+import os
+from pathlib import Path
+from typing import Optional
+
+from google.auth.transport.requests import Request
+from google.oauth2 import service_account
+
+from ..config.constants import OAUTH_SCOPES, get_auth_method_path, get_config_dir
+
+logger = logging.getLogger(__name__)
+
+
+def validate_service_account_key(key_path: str) -> dict:
+    """Validate a service account key file.
+
+    Checks that the JSON is valid and contains required fields.
+    Returns the parsed key data.
+
+    Raises:
+        FileNotFoundError: If the key file does not exist.
+        ValueError: If the file is not valid service account JSON.
+    """
+    path = Path(key_path)
+
+    if not path.exists():
+        raise FileNotFoundError(f"Service account key file not found: {key_path}")
+
+    try:
+        data = json.loads(path.read_text())
+    except json.JSONDecodeError as exc:
+        raise ValueError(
+            f"Invalid JSON in service account key file: {key_path}"
+        ) from exc
+
+    if data.get("type") != "service_account":
+        raise ValueError(
+            f"Invalid key file: expected type 'service_account', "
+            f"got '{data.get('type', '<missing>')}'"
+        )
+
+    missing = [f for f in ("private_key", "client_email") if not data.get(f)]
+    if missing:
+        raise ValueError(
+            f"Invalid key file: missing required fields: {', '.join(missing)}"
+        )
+
+    return data
+
+
+def login_with_service_account(key_path: str) -> str:
+    """Login with a service account key file.
+
+    Validates the key, tests authentication, and saves the auth method.
+    Returns the service account email.
+
+    Raises:
+        FileNotFoundError: If the key file does not exist.
+        ValueError: If the key file is invalid.
+        google.auth.exceptions.RefreshError: If authentication fails.
+    """
+    key_data = validate_service_account_key(key_path)
+
+    # Test that we can actually get a token
+    creds = service_account.Credentials.from_service_account_file(
+        key_path,
+        scopes=OAUTH_SCOPES,
+    )
+    creds.refresh(Request())
+
+    # Save auth method config
+    _save_auth_method(
+        {
+            "method": "service-account",
+            "service_account_path": str(Path(key_path).resolve()),
+            "service_account_email": key_data["client_email"],
+        }
+    )
+
+    return key_data["client_email"]
+
+
+def get_service_account_credentials() -> Optional[service_account.Credentials]:
+    """Get service account credentials if configured.
+
+    Check order:
+    1. GA_CLI_SERVICE_ACCOUNT env var
+    2. GOOGLE_APPLICATION_CREDENTIALS env var
+    3. Saved auth method from previous login
+
+    Returns None if no service account is configured (OAuth should be used).
+    """
+    # Check env vars first
+    for env_var in ("GA_CLI_SERVICE_ACCOUNT", "GOOGLE_APPLICATION_CREDENTIALS"):
+        key_path = os.environ.get(env_var)
+        if key_path:
+            validate_service_account_key(key_path)
+            return service_account.Credentials.from_service_account_file(
+                key_path,
+                scopes=OAUTH_SCOPES,
+            )
+
+    # Check saved auth method
+    auth_method = _load_auth_method()
+    if auth_method and auth_method.get("method") == "service-account":
+        key_path = auth_method.get("service_account_path")
+        if key_path:
+            validate_service_account_key(key_path)
+            return service_account.Credentials.from_service_account_file(
+                key_path,
+                scopes=OAUTH_SCOPES,
+            )
+
+    return None
+
+
+def _save_auth_method(config: dict) -> None:
+    """Save auth method configuration."""
+    config_dir = get_config_dir()
+    config_dir.mkdir(parents=True, exist_ok=True)
+    get_auth_method_path().write_text(json.dumps(config, indent=2))
+
+
+def _load_auth_method() -> Optional[dict]:
+    """Load auth method configuration."""
+    try:
+        return json.loads(get_auth_method_path().read_text())
+    except (FileNotFoundError, json.JSONDecodeError):
+        return None
+
+
+def clear_auth_method() -> None:
+    """Delete auth method configuration."""
+    try:
+        get_auth_method_path().unlink()
+    except FileNotFoundError:
+        pass
+
+
+def load_auth_method() -> Optional[dict]:
+    """Public access to load auth method (used by auth status command)."""
+    return _load_auth_method()

ga_cli/commands/access_bindings.py

@@ -0,0 +1,254 @@
+"""Access binding management commands."""
+
+from typing import Optional
+
+import questionary
+import typer
+
+from ..api.client import get_admin_alpha_client
+from ..config.store import get_effective_value
+from ..utils import handle_error, info, output, resolve_output_format, success
+from ..utils.pagination import paginate_all
+
+access_bindings_app = typer.Typer(
+    name="access-bindings",
+    help="Manage access bindings (user-role assignments)",
+    no_args_is_help=True,
+)
+
+
+def _resolve_parent(
+    account_id: Optional[str], property_id: Optional[str]
+) -> tuple[str, str]:
+    """Resolve the parent resource for access binding commands.
+
+    Exactly one of account_id or property_id must be provided.
+    property_id falls back to config default if not explicitly set.
+
+    Returns (parent_string, parent_type) where parent_type is
+    "accounts" or "properties".
+    """
+    if account_id and property_id:
+        raise typer.BadParameter(
+            "Provide either --account-id or --property-id, not both."
+        )
+    if account_id:
+        return f"accounts/{account_id}", "accounts"
+
+    # Only fall back to config default when --account-id is not provided
+    effective_property = get_effective_value(property_id, "default_property_id")
+    if effective_property:
+        return f"properties/{effective_property}", "properties"
+    raise typer.BadParameter(
+        "Either --account-id or --property-id is required."
+    )
+
+
+def _get_access_bindings_resource(admin, parent_type: str):
+    """Get the correct accessBindings API resource for the parent type."""
+    if parent_type == "accounts":
+        return admin.accounts().accessBindings()
+    return admin.properties().accessBindings()
+
+
+def _format_roles(roles: list[str]) -> str:
+    """Strip predefinedRoles/ prefix for display."""
+    return ", ".join(r.removeprefix("predefinedRoles/") for r in roles)
+
+
+@access_bindings_app.command("list")
+def list_cmd(
+    account_id: Optional[str] = typer.Option(
+        None, "--account-id", "-a", help="Account ID"
+    ),
+    property_id: Optional[str] = typer.Option(
+        None, "--property-id", "-p", help="Property ID (numeric)"
+    ),
+    output_format: Optional[str] = typer.Option(
+        None, "--output", "-o", help="Output format (json, table, compact)"
+    ),
+):
+    """List access bindings for an account or property."""
+    try:
+        parent, parent_type = _resolve_parent(account_id, property_id)
+        effective_format = resolve_output_format(output_format)
+
+        admin = get_admin_alpha_client()
+        resource = _get_access_bindings_resource(admin, parent_type)
+        bindings = paginate_all(
+            lambda **kw: resource.list(parent=parent, **kw).execute(),
+            "accessBindings",
+            pageSize=500,
+        )
+
+        if effective_format != "json":
+            for b in bindings:
+                if "roles" in b:
+                    b["_roles_display"] = _format_roles(b["roles"])
+
+        output(
+            bindings,
+            effective_format,
+            columns=["name", "user", "_roles_display"],
+            headers=["Resource Name", "User", "Roles"],
+        )
+    except typer.BadParameter:
+        raise
+    except Exception as e:
+        handle_error(e)
+
+
+@access_bindings_app.command("get")
+def get_cmd(
+    account_id: Optional[str] = typer.Option(
+        None, "--account-id", "-a", help="Account ID"
+    ),
+    property_id: Optional[str] = typer.Option(
+        None, "--property-id", "-p", help="Property ID (numeric)"
+    ),
+    binding_id: str = typer.Option(
+        ..., "--binding-id", "-b", help="Access binding ID"
+    ),
+    output_format: Optional[str] = typer.Option(
+        None, "--output", "-o", help="Output format (json, table, compact)"
+    ),
+):
+    """Get details for an access binding."""
+    try:
+        parent, parent_type = _resolve_parent(account_id, property_id)
+        effective_format = resolve_output_format(output_format)
+
+        admin = get_admin_alpha_client()
+        resource = _get_access_bindings_resource(admin, parent_type)
+        resource_name = f"{parent}/accessBindings/{binding_id}"
+        binding = resource.get(name=resource_name).execute()
+        output(binding, effective_format)
+    except typer.BadParameter:
+        raise
+    except Exception as e:
+        handle_error(e)
+
+
+@access_bindings_app.command("create")
+def create_cmd(
+    account_id: Optional[str] = typer.Option(
+        None, "--account-id", "-a", help="Account ID"
+    ),
+    property_id: Optional[str] = typer.Option(
+        None, "--property-id", "-p", help="Property ID (numeric)"
+    ),
+    user: str = typer.Option(
+        ..., "--user", "-u", help="Email address of the user"
+    ),
+    roles: str = typer.Option(
+        ..., "--roles", "-r", help="Comma-separated roles (e.g. viewer,editor)"
+    ),
+    output_format: Optional[str] = typer.Option(
+        None, "--output", "-o", help="Output format (json, table, compact)"
+    ),
+):
+    """Create an access binding for a user."""
+    try:
+        parent, parent_type = _resolve_parent(account_id, property_id)
+        effective_format = resolve_output_format(output_format)
+
+        role_list = [
+            r.strip() if "/" in r.strip() else f"predefinedRoles/{r.strip()}"
+            for r in roles.split(",")
+            if r.strip()
+        ]
+
+        if not role_list:
+            raise typer.BadParameter("--roles must contain at least one role.")
+
+        body = {"user": user, "roles": role_list}
+
+        admin = get_admin_alpha_client()
+        resource = _get_access_bindings_resource(admin, parent_type)
+        binding = resource.create(parent=parent, body=body).execute()
+        output(binding, effective_format)
+    except typer.BadParameter:
+        raise
+    except Exception as e:
+        handle_error(e)
+
+
+@access_bindings_app.command("update")
+def update_cmd(
+    account_id: Optional[str] = typer.Option(
+        None, "--account-id", "-a", help="Account ID"
+    ),
+    property_id: Optional[str] = typer.Option(
+        None, "--property-id", "-p", help="Property ID (numeric)"
+    ),
+    binding_id: str = typer.Option(
+        ..., "--binding-id", "-b", help="Access binding ID"
+    ),
+    roles: str = typer.Option(
+        ..., "--roles", "-r", help="Comma-separated roles (e.g. viewer,editor)"
+    ),
+    output_format: Optional[str] = typer.Option(
+        None, "--output", "-o", help="Output format (json, table, compact)"
+    ),
+):
+    """Update roles for an access binding."""
+    try:
+        parent, parent_type = _resolve_parent(account_id, property_id)
+        effective_format = resolve_output_format(output_format)
+
+        role_list = [
+            r.strip() if "/" in r.strip() else f"predefinedRoles/{r.strip()}"
+            for r in roles.split(",")
+            if r.strip()
+        ]
+
+        if not role_list:
+            raise typer.BadParameter("--roles must contain at least one role.")
+
+        resource_name = f"{parent}/accessBindings/{binding_id}"
+        body = {"name": resource_name, "roles": role_list}
+
+        admin = get_admin_alpha_client()
+        resource = _get_access_bindings_resource(admin, parent_type)
+        binding = resource.patch(name=resource_name, body=body).execute()
+        output(binding, effective_format)
+    except typer.BadParameter:
+        raise
+    except Exception as e:
+        handle_error(e)
+
+
+@access_bindings_app.command("delete")
+def delete_cmd(
+    account_id: Optional[str] = typer.Option(
+        None, "--account-id", "-a", help="Account ID"
+    ),
+    property_id: Optional[str] = typer.Option(
+        None, "--property-id", "-p", help="Property ID (numeric)"
+    ),
+    binding_id: str = typer.Option(
+        ..., "--binding-id", "-b", help="Access binding ID"
+    ),
+    yes: bool = typer.Option(False, "--yes", "-y", help="Skip confirmation prompt"),
+):
+    """Delete an access binding."""
+    try:
+        parent, parent_type = _resolve_parent(account_id, property_id)
+
+        if not yes:
+            confirmed = questionary.confirm(
+                f"Delete access binding {binding_id}? This cannot be undone."
+            ).ask()
+            if not confirmed:
+                info("Cancelled.")
+                raise typer.Exit()
+
+        resource_name = f"{parent}/accessBindings/{binding_id}"
+        admin = get_admin_alpha_client()
+        resource = _get_access_bindings_resource(admin, parent_type)
+        resource.delete(name=resource_name).execute()
+        success(f"Access binding {binding_id} deleted.")
+    except (typer.BadParameter, typer.Exit):
+        raise
+    except Exception as e:
+        handle_error(e)

ga_cli/commands/access_reports.py

@@ -0,0 +1,201 @@
+"""Access report commands: who accessed what data and when.
+
+Uses the Analytics Admin API v1beta runAccessReport endpoint.
+"""
+
+from typing import Optional
+
+import typer
+
+from ..api.client import get_admin_client
+from ..config.store import get_effective_value
+from ..utils import console, handle_error, info, output, require_options, resolve_output_format
+
+access_reports_app = typer.Typer(
+    name="access-reports",
+    help="Run data-access reports (who accessed what)",
+    no_args_is_help=True,
+)
+
+_DEFAULT_DIMENSIONS = "userEmail,epochTimeMicros"
+_DEFAULT_METRICS = "accessCount"
+
+
+def _build_access_report_body(
+    dimensions: str,
+    metrics: str,
+    start_date: str,
+    end_date: str,
+    limit: int,
+    offset: int,
+    include_all_users: bool,
+    expand_groups: bool,
+) -> dict:
+    """Build the request body for runAccessReport."""
+    body: dict = {
+        "dimensions": [{"dimensionName": d.strip()} for d in dimensions.split(",")],
+        "metrics": [{"metricName": m.strip()} for m in metrics.split(",")],
+        "dateRanges": [{"startDate": start_date, "endDate": end_date}],
+        "limit": limit,
+    }
+    if offset > 0:
+        body["offset"] = offset
+    if include_all_users:
+        body["includeAllUsers"] = True
+    if expand_groups:
+        body["expandGroups"] = True
+    return body
+
+
+def _transform_access_rows(result: dict) -> tuple[list[dict], list[str], list[str]]:
+    """Transform an access report response into a list of dicts."""
+    dim_headers = [h.get("dimensionName", "") for h in result.get("dimensionHeaders", [])]
+    met_headers = [h.get("metricName", "") for h in result.get("metricHeaders", [])]
+
+    all_keys = dim_headers + met_headers
+    rows = []
+    for row in result.get("rows", []):
+        entry = {}
+        for i, name in enumerate(dim_headers):
+            entry[name] = row["dimensionValues"][i]["value"]
+        for i, name in enumerate(met_headers):
+            entry[name] = row["metricValues"][i]["value"]
+        rows.append(entry)
+
+    return rows, all_keys, all_keys
+
+
+@access_reports_app.command("run-account")
+def run_account_cmd(
+    account_id: Optional[str] = typer.Option(
+        None, "--account-id", "-a", help="Account ID (numeric)"
+    ),
+    dimensions: str = typer.Option(
+        _DEFAULT_DIMENSIONS, "--dimensions", "-d", help="Comma-separated dimension names"
+    ),
+    metrics: str = typer.Option(
+        _DEFAULT_METRICS, "--metrics", "-m", help="Comma-separated metric names"
+    ),
+    start_date: str = typer.Option("7daysAgo", "--start-date", help="Start date"),
+    end_date: str = typer.Option("today", "--end-date", help="End date"),
+    limit: int = typer.Option(10000, "--limit", "-l", help="Max rows to return"),
+    offset: int = typer.Option(0, "--offset", help="Row offset for pagination"),
+    include_all_users: bool = typer.Option(
+        False, "--include-all-users", help="Include users who never made an API call"
+    ),
+    expand_groups: bool = typer.Option(
+        False, "--expand-groups", help="Expand user group members (requires --include-all-users)"
+    ),
+    output_format: Optional[str] = typer.Option(
+        None, "--output", "-o", help="Output format (json, table, compact)"
+    ),
+):
+    """Run a data-access report for an account."""
+    try:
+        effective_account = get_effective_value(account_id, "default_account_id")
+        require_options({"account_id": effective_account}, ["account_id"])
+        effective_format = resolve_output_format(output_format)
+
+        body = _build_access_report_body(
+            dimensions,
+            metrics,
+            start_date,
+            end_date,
+            limit,
+            offset,
+            include_all_users,
+            expand_groups,
+        )
+
+        admin = get_admin_client()
+        result = (
+            admin.accounts()
+            .runAccessReport(
+                entity=f"accounts/{effective_account}",
+                body=body,
+            )
+            .execute()
+        )
+
+        rows, columns, headers = _transform_access_rows(result)
+        row_count = result.get("rowCount", len(rows))
+
+        if not rows:
+            info("No access data found.")
+            return
+
+        output(rows, effective_format, columns=columns, headers=headers)
+
+        if effective_format == "table" and row_count > 0:
+            console.print(f"\n[dim]{row_count} total rows[/dim]")
+
+    except Exception as e:
+        handle_error(e)
+
+
+@access_reports_app.command("run-property")
+def run_property_cmd(
+    property_id: Optional[str] = typer.Option(
+        None, "--property-id", "-p", help="Property ID (numeric)"
+    ),
+    dimensions: str = typer.Option(
+        _DEFAULT_DIMENSIONS, "--dimensions", "-d", help="Comma-separated dimension names"
+    ),
+    metrics: str = typer.Option(
+        _DEFAULT_METRICS, "--metrics", "-m", help="Comma-separated metric names"
+    ),
+    start_date: str = typer.Option("7daysAgo", "--start-date", help="Start date"),
+    end_date: str = typer.Option("today", "--end-date", help="End date"),
+    limit: int = typer.Option(10000, "--limit", "-l", help="Max rows to return"),
+    offset: int = typer.Option(0, "--offset", help="Row offset for pagination"),
+    include_all_users: bool = typer.Option(
+        False, "--include-all-users", help="Include users who never made an API call"
+    ),
+    expand_groups: bool = typer.Option(
+        False, "--expand-groups", help="Expand user group members (requires --include-all-users)"
+    ),
+    output_format: Optional[str] = typer.Option(
+        None, "--output", "-o", help="Output format (json, table, compact)"
+    ),
+):
+    """Run a data-access report for a property."""
+    try:
+        effective_property = get_effective_value(property_id, "default_property_id")
+        require_options({"property_id": effective_property}, ["property_id"])
+        effective_format = resolve_output_format(output_format)
+
+        body = _build_access_report_body(
+            dimensions,
+            metrics,
+            start_date,
+            end_date,
+            limit,
+            offset,
+            include_all_users,
+            expand_groups,
+        )
+
+        admin = get_admin_client()
+        result = (
+            admin.properties()
+            .runAccessReport(
+                entity=f"properties/{effective_property}",
+                body=body,
+            )
+            .execute()
+        )
+
+        rows, columns, headers = _transform_access_rows(result)
+        row_count = result.get("rowCount", len(rows))
+
+        if not rows:
+            info("No access data found.")
+            return
+
+        output(rows, effective_format, columns=columns, headers=headers)
+
+        if effective_format == "table" and row_count > 0:
+            console.print(f"\n[dim]{row_count} total rows[/dim]")
+
+    except Exception as e:
+        handle_error(e)

ga_cli/commands/account_summaries.py

@@ -0,0 +1,68 @@
+"""Account summaries command."""
+
+from typing import Optional
+
+import typer
+
+from ..api.client import get_admin_client
+from ..utils import handle_error, output, resolve_output_format
+from ..utils.pagination import paginate_all
+
+account_summaries_app = typer.Typer(
+    name="account-summaries",
+    help="View account summaries",
+    no_args_is_help=True,
+)
+
+
+@account_summaries_app.command("list")
+def list_cmd(
+    output_format: Optional[str] = typer.Option(
+        None, "--output", "-o", help="Output format (json, table, compact)"
+    ),
+):
+    """List all accounts with their property summaries."""
+    try:
+        effective_format = resolve_output_format(output_format)
+
+        admin = get_admin_client()
+        summaries = paginate_all(
+            lambda **kw: admin.accountSummaries().list(**kw).execute(),
+            "accountSummaries",
+            pageSize=200,
+        )
+
+        if effective_format != "table":
+            output(summaries, effective_format)
+            return
+
+        # Flatten into rows: one row per property
+        rows = []
+        for acct in summaries:
+            acct_name = acct.get("displayName", "")
+            acct_id = acct.get("account", "").replace("accounts/", "")
+            for prop in acct.get("propertySummaries", []):
+                rows.append({
+                    "accountName": acct_name,
+                    "accountId": acct_id,
+                    "propertyName": prop.get("displayName", ""),
+                    "propertyId": prop.get("property", "").replace("properties/", ""),
+                    "propertyType": prop.get("propertyType", ""),
+                })
+            if not acct.get("propertySummaries"):
+                rows.append({
+                    "accountName": acct_name,
+                    "accountId": acct_id,
+                    "propertyName": "",
+                    "propertyId": "",
+                    "propertyType": "",
+                })
+
+        output(
+            rows,
+            effective_format,
+            columns=["accountName", "accountId", "propertyName", "propertyId", "propertyType"],
+            headers=["Account Name", "Account ID", "Property Name", "Property ID", "Property Type"],
+        )
+    except Exception as e:
+        handle_error(e)