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

ga_cli/commands/upgrade_cmd.py

@@ -0,0 +1,148 @@
+"""Upgrade command: check for updates and self-update ga-cli."""
+
+from __future__ import annotations
+
+import json
+import shutil
+import subprocess
+import sys
+import time
+import urllib.request
+from typing import Optional
+
+import typer
+
+from .. import __version__
+from ..config.constants import get_update_check_path
+from ..utils import error, info, success, warn
+
+upgrade_app = typer.Typer(
+    name="upgrade", help="Check for and install updates", invoke_without_command=True
+)
+
+PYPI_URL = "https://pypi.org/pypi/ga-cli/json"
+PYPI_TIMEOUT = 5
+UPDATE_CHECK_INTERVAL = 86400  # 24 hours in seconds
+
+
+def _check_pypi_version() -> Optional[str]:
+    """Fetch the latest ga-cli version from PyPI.
+
+    Returns the version string, or None on any error.
+    """
+    try:
+        req = urllib.request.Request(PYPI_URL, headers={"Accept": "application/json"})
+        with urllib.request.urlopen(req, timeout=PYPI_TIMEOUT) as resp:
+            data = json.loads(resp.read().decode())
+            return data["info"]["version"]
+    except Exception:
+        return None
+
+
+def _is_newer(latest: str, current: str) -> bool:
+    """Return True if latest is strictly newer than current."""
+    from packaging.version import parse
+
+    return parse(latest) > parse(current)
+
+
+def _detect_installer() -> list[str]:
+    """Detect the best install command to upgrade ga-cli.
+
+    Checks for pipx first, then falls back to pip via the current interpreter.
+    """
+    if shutil.which("pipx"):
+        return ["pipx", "upgrade", "ga-cli"]
+    return [sys.executable, "-m", "pip", "install", "--upgrade", "ga-cli"]
+
+
+@upgrade_app.callback(invoke_without_command=True)
+def upgrade_cmd(
+    check: bool = typer.Option(False, "--check", help="Check for updates without installing"),
+    force: bool = typer.Option(False, "--force", help="Force reinstall current version"),
+):
+    """Check for and install updates."""
+    current = __version__
+
+    if check:
+        latest = _check_pypi_version()
+        if latest is None:
+            error("Could not check for updates. Please check your network connection.")
+            raise typer.Exit(1)
+        if _is_newer(latest, current):
+            info(f"Update available: {current} → {latest}. Run 'ga upgrade' to install.")
+        else:
+            success(f"ga-cli {current} is the latest version.")
+        return
+
+    if force:
+        info(f"Force-reinstalling ga-cli {current}...")
+        cmd = _detect_installer()
+        # Append --force-reinstall for pip-based installs
+        if cmd[0] != "pipx":
+            cmd.append("--force-reinstall")
+        else:
+            cmd = ["pipx", "install", "--force", "ga-cli"]
+        result = subprocess.run(cmd, capture_output=True, text=True)
+        if result.returncode == 0:
+            success(f"Reinstalled ga-cli {current}.")
+        else:
+            error(f"Upgrade failed:\n{result.stderr.strip()}")
+            raise typer.Exit(1)
+        return
+
+    # Default: check and upgrade
+    latest = _check_pypi_version()
+    if latest is None:
+        error("Could not check for updates. Please check your network connection.")
+        raise typer.Exit(1)
+
+    if not _is_newer(latest, current):
+        success(f"ga-cli {current} is already up to date.")
+        return
+
+    info(f"Upgrading ga-cli {current} → {latest}...")
+    cmd = _detect_installer()
+    result = subprocess.run(cmd, capture_output=True, text=True)
+    if result.returncode == 0:
+        success(f"Successfully upgraded to ga-cli {latest}.")
+    else:
+        error(f"Upgrade failed:\n{result.stderr.strip()}")
+        raise typer.Exit(1)
+
+
+def maybe_check_for_updates() -> None:
+    """Run a non-blocking daily update check.
+
+    Called from main.py after command dispatch. Prints a dim notice
+    to stderr if a newer version is available. Never raises.
+    """
+    try:
+        check_path = get_update_check_path()
+
+        # Read last check timestamp
+        last_check = 0.0
+        if check_path.exists():
+            try:
+                data = json.loads(check_path.read_text())
+                last_check = data.get("last_check", 0.0)
+            except (json.JSONDecodeError, OSError):
+                pass
+
+        now = time.time()
+        if now - last_check < UPDATE_CHECK_INTERVAL:
+            return
+
+        latest = _check_pypi_version()
+
+        # Write new timestamp regardless of result
+        check_path.parent.mkdir(parents=True, exist_ok=True)
+        check_path.write_text(json.dumps({"last_check": now}))
+
+        if latest and _is_newer(latest, __version__):
+            warn(
+                f"A new version of ga-cli is available (v{latest}). "
+                "Run 'ga upgrade' to update."
+            )
+    except Exception:
+        pass

ga_cli/config/constants.py

@@ -0,0 +1,61 @@
+"""Application constants and configuration paths."""
+
+import os
+from pathlib import Path
+
+from platformdirs import user_config_dir
+
+# App identity
+APP_NAME = "ga-cli"
+
+# OAuth 2.0 scopes
+OAUTH_SCOPES = [
+    "openid",
+    "https://www.googleapis.com/auth/analytics.readonly",
+    "https://www.googleapis.com/auth/analytics.edit",
+    "https://www.googleapis.com/auth/analytics.manage.users",
+    "https://www.googleapis.com/auth/userinfo.email",
+    "https://www.googleapis.com/auth/userinfo.profile",
+]
+
+# OAuth callback server
+OAUTH_CALLBACK_PORT = 8085
+
+# Configuration directory
+# Priority: GA_CLI_CONFIG_DIR env var > platformdirs (XDG-compliant)
+def get_config_dir() -> Path:
+    """Get the configuration directory path."""
+    env_dir = os.environ.get("GA_CLI_CONFIG_DIR")
+    if env_dir:
+        return Path(env_dir)
+    return Path(user_config_dir(APP_NAME))  # ~/.config/ga-cli/ on Linux/macOS
+
+
+def get_credentials_path() -> Path:
+    """Path to stored OAuth credentials."""
+    return get_config_dir() / "credentials.json"
+
+
+def get_config_path() -> Path:
+    """Path to user configuration file."""
+    return get_config_dir() / "config.json"
+
+
+def get_auth_method_path() -> Path:
+    """Path to auth method tracking file."""
+    return get_config_dir() / "auth-method.json"
+
+
+def get_client_secret_path() -> Path:
+    """Path to OAuth client secret file (alternative to env vars)."""
+    return get_config_dir() / "client_secret.json"
+
+
+def get_update_check_path() -> Path:
+    """Path to update-check timestamp file."""
+    return get_config_dir() / "update-check.json"
+
+
+# Pagination defaults
+DEFAULT_PAGE_SIZE = 50
+MAX_PAGE_SIZE = 200

ga_cli/config/store.py

@@ -0,0 +1,115 @@
+"""User configuration persistence.
+
+Implements the same pattern as GTM CLI:
+- JSON file at ~/.config/ga-cli/config.json
+- In-memory cache for performance
+- CLI flag > config file > None resolution via get_effective_value()
+"""
+
+from __future__ import annotations
+
+import json
+from dataclasses import asdict, dataclass
+from typing import Literal, Optional
+
+from .constants import get_config_dir, get_config_path
+
+OutputFormat = Literal["json", "table", "compact"]
+
+
+@dataclass
+class UserConfig:
+    """User configuration. GA-specific fields."""
+
+    default_property_id: Optional[str] = None
+    default_account_id: Optional[str] = None
+    output_format: OutputFormat = "table"
+
+
+# In-memory cache (same pattern as GTM CLI)
+_cached_config: Optional[UserConfig] = None
+
+
+def load_config() -> UserConfig:
+    """Load config from disk, merge with defaults, cache in memory."""
+    global _cached_config
+    if _cached_config is not None:
+        return _cached_config
+
+    config_path = get_config_path()
+    try:
+        data = json.loads(config_path.read_text())
+        _cached_config = UserConfig(
+            default_property_id=data.get("default_property_id"),
+            default_account_id=data.get("default_account_id"),
+            output_format=data.get("output_format", "table"),
+        )
+    except (FileNotFoundError, json.JSONDecodeError):
+        _cached_config = UserConfig()
+
+    return _cached_config
+
+
+def save_config(config: UserConfig) -> None:
+    """Write config to disk and update cache."""
+    global _cached_config
+    config_dir = get_config_dir()
+    config_dir.mkdir(parents=True, exist_ok=True)
+
+    # Only write non-None values
+    data = {k: v for k, v in asdict(config).items() if v is not None}
+    get_config_path().write_text(json.dumps(data, indent=2))
+    _cached_config = config
+
+
+def update_config(**updates: str) -> UserConfig:
+    """Merge updates into current config and save."""
+    config = load_config()
+    for key, value in updates.items():
+        if hasattr(config, key):
+            setattr(config, key, value)
+    save_config(config)
+    return config
+
+
+def get_config_value(key: str) -> Optional[str]:
+    """Get a single config value by key name."""
+    config = load_config()
+    return getattr(config, key, None)
+
+
+def set_config_value(key: str, value: str) -> None:
+    """Set a single config value."""
+    update_config(**{key: value})
+
+
+def unset_config_value(key: str) -> None:
+    """Remove a config value (set to None)."""
+    config = load_config()
+    if hasattr(config, key):
+        setattr(config, key, None)
+    save_config(config)
+
+
+def clear_config() -> None:
+    """Reset config to defaults."""
+    save_config(UserConfig())
+
+
+def get_effective_value(cli_value: Optional[str], config_key: str) -> Optional[str]:
+    """Resolve a value: CLI flag > config file > None.
+
+    This is the critical resolution function used by every command.
+    Equivalent to GTM CLI's getEffectiveValue().
+    """
+    if cli_value:
+        return cli_value
+    return get_config_value(config_key)
+
+
+# Valid config keys (for validation in set/unset commands)
+VALID_CONFIG_KEYS = {
+    "default_property_id": "Default GA4 Property ID",
+    "default_account_id": "Default Account ID",
+    "output_format": "Output format (json, table, compact)",
+}

ga_cli/main.py

@@ -0,0 +1,110 @@
+"""GA CLI entry point."""
+
+import typer
+
+from .commands.access_bindings import access_bindings_app
+from .commands.access_reports import access_reports_app
+from .commands.account_summaries import account_summaries_app
+from .commands.accounts import accounts_app
+from .commands.agent_cmd import agent_app
+from .commands.annotations import annotations_app
+from .commands.audiences import audiences_app
+from .commands.auth_cmd import auth_app
+from .commands.bigquery_links import bigquery_links_app
+from .commands.calculated_metrics import calculated_metrics_app
+from .commands.channel_groups import channel_groups_app
+from .commands.completions_cmd import completions_app
+from .commands.config_cmd import config_app
+from .commands.custom_dimensions import custom_dimensions_app
+from .commands.custom_metrics import custom_metrics_app
+from .commands.data_retention import data_retention_app
+from .commands.data_streams import data_streams_app
+from .commands.event_create_rules import event_create_rules_app
+from .commands.event_edit_rules import event_edit_rules_app
+from .commands.firebase_links import firebase_links_app
+from .commands.google_ads_links import google_ads_links_app
+from .commands.key_events import key_events_app
+from .commands.mp_secrets import mp_secrets_app
+from .commands.properties import properties_app
+from .commands.property_settings import property_settings_app
+from .commands.reports import reports_app
+from .commands.upgrade_cmd import upgrade_app
+
+app = typer.Typer(
+    name="ga",
+    help="Command-line interface for Google Analytics 4",
+    no_args_is_help=True,
+)
+
+# Register command groups
+app.add_typer(auth_app, name="auth")
+app.add_typer(config_app, name="config")
+app.add_typer(accounts_app, name="accounts")
+app.add_typer(account_summaries_app, name="account-summaries")
+app.add_typer(properties_app, name="properties")
+app.add_typer(custom_dimensions_app, name="custom-dimensions")
+app.add_typer(custom_metrics_app, name="custom-metrics")
+app.add_typer(data_retention_app, name="data-retention")
+app.add_typer(data_streams_app, name="data-streams")
+app.add_typer(access_bindings_app, name="access-bindings")
+app.add_typer(access_reports_app, name="access-reports")
+app.add_typer(annotations_app, name="annotations")
+app.add_typer(audiences_app, name="audiences")
+app.add_typer(bigquery_links_app, name="bigquery-links")
+app.add_typer(calculated_metrics_app, name="calculated-metrics")
+app.add_typer(channel_groups_app, name="channel-groups")
+app.add_typer(event_create_rules_app, name="event-create-rules")
+app.add_typer(event_edit_rules_app, name="event-edit-rules")
+app.add_typer(firebase_links_app, name="firebase-links")
+app.add_typer(google_ads_links_app, name="google-ads-links")
+app.add_typer(key_events_app, name="key-events")
+app.add_typer(mp_secrets_app, name="mp-secrets")
+app.add_typer(property_settings_app, name="property-settings")
+app.add_typer(reports_app, name="reports")
+app.add_typer(agent_app, name="agent")
+app.add_typer(upgrade_app, name="upgrade")
+app.add_typer(completions_app, name="completions")
+
+
+@app.callback(invoke_without_command=True)
+def main(
+    version: bool = typer.Option(False, "--version", "-v", help="Show version"),
+    quiet: bool = typer.Option(False, "--quiet", "-q", help="Suppress non-essential output"),
+    no_color: bool = typer.Option(False, "--no-color", help="Disable colored output"),
+    describe: bool = typer.Option(False, "--describe", help="Show CLI schema as JSON"),
+):
+    """GA CLI — Command-line interface for Google Analytics 4."""
+    from .config.store import get_effective_value
+    from .utils.output import is_tty, set_no_color, set_output_format, set_quiet
+
+    if quiet:
+        set_quiet(True)
+    if no_color:
+        set_no_color(True)
+
+    # Resolve output format early so errors are structured when appropriate
+    effective_fmt = get_effective_value(None, "output_format") or ("table" if is_tty() else "json")
+    set_output_format(effective_fmt)
+
+    if version:
+        from . import __version__
+
+        print(f"ga-cli {__version__}")
+        raise typer.Exit()
+
+    if describe:
+        from .utils.describe import handle_describe_all
+
+        handle_describe_all(app)
+
+
+def run():
+    """Entry point for the CLI (called by pyproject.toml [project.scripts])."""
+    from .commands.upgrade_cmd import maybe_check_for_updates
+
+    app()
+    maybe_check_for_updates()
+
+
+if __name__ == "__main__":
+    run()

ga_cli/utils/__init__.py

@@ -0,0 +1,20 @@
+"""Utility re-exports."""
+
+from .describe import handle_describe_all as handle_describe_all
+from .dry_run import handle_dry_run as handle_dry_run
+from .errors import classify_error as classify_error
+from .errors import format_api_error as format_api_error
+from .errors import handle_error as handle_error
+from .errors import require_options as require_options
+from .output import OutputFormat as OutputFormat
+from .output import console as console
+from .output import error as error
+from .output import get_output_format as get_output_format
+from .output import info as info
+from .output import output as output
+from .output import resolve_output_format as resolve_output_format
+from .output import success as success
+from .output import warn as warn
+from .pagination import PaginatedResult as PaginatedResult
+from .pagination import paginate as paginate
+from .pagination import paginate_all as paginate_all

ga_cli/utils/describe.py

@@ -0,0 +1,129 @@
+"""Schema introspection for --describe flag.
+
+Auto-extracts command schemas from Typer/Click internals.
+No manual registration needed — parameters, types, flags, and
+metadata (mutative, dry-run, json-input) are all derived from
+the live command definitions.
+"""
+
+import json
+import sys
+
+import click
+import typer
+
+
+def _click_type_to_json(param_type: click.ParamType) -> str:
+    """Map a Click parameter type to a JSON Schema type string."""
+    if isinstance(param_type, click.types.IntParamType):
+        return "integer"
+    if isinstance(param_type, click.types.FloatParamType):
+        return "number"
+    if isinstance(param_type, click.types.BoolParamType):
+        return "boolean"
+    return "string"
+
+
+# Parameters to exclude from schema output (meta/infrastructure flags).
+_EXCLUDED_PARAMS = frozenset({
+    "help", "version", "quiet", "no_color", "describe",
+    "dry_run", "json_input",
+})
+
+
+def _param_to_schema(param: click.Parameter) -> tuple[str, dict] | None:
+    """Convert a Click parameter to a (name, JSON Schema property) pair.
+
+    Returns None for parameters that should be excluded from output.
+    """
+    if not isinstance(param, click.Option):
+        return None
+    if param.name in _EXCLUDED_PARAMS:
+        return None
+
+    prop: dict = {
+        "type": _click_type_to_json(param.type),
+        "description": param.help or "",
+    }
+
+    long_flags = [o for o in param.opts if o.startswith("--")]
+    short_flags = [o for o in param.opts if o.startswith("-") and not o.startswith("--")]
+    if long_flags:
+        prop["flag"] = long_flags[0]
+    if short_flags:
+        prop["aliases"] = short_flags
+
+    if isinstance(param.type, click.Choice):
+        prop["enum"] = list(param.type.choices)
+
+    if param.default is not None and not param.required:
+        prop["default"] = param.default
+
+    return param.name, prop
+
+
+def _introspect_command(cmd: click.Command, prefix: str) -> dict:
+    """Build a JSON-Schema-like descriptor for a single Click command."""
+    full_name = f"{prefix} {cmd.name}" if prefix else cmd.name
+
+    properties: dict = {}
+    required: list[str] = []
+    has_dry_run = False
+    has_json_input = False
+
+    for param in cmd.params:
+        if param.name == "dry_run":
+            has_dry_run = True
+        if param.name == "json_input":
+            has_json_input = True
+
+        result = _param_to_schema(param)
+        if result is None:
+            continue
+        name, prop = result
+        properties[name] = prop
+        if param.required:
+            required.append(name)
+
+    schema: dict = {
+        "command": full_name,
+        "description": cmd.help or "",
+        "parameters": {
+            "type": "object",
+            "properties": properties,
+        },
+        "mutative": has_dry_run,
+        "supports_dry_run": has_dry_run,
+        "supports_json_input": has_json_input,
+    }
+    if required:
+        schema["parameters"]["required"] = required
+
+    return schema
+
+
+def _introspect_group(group: click.Group, prefix: str) -> list[dict]:
+    """Recursively introspect a Click group and all its sub-commands."""
+    commands: list[dict] = []
+    for name in sorted(group.list_commands(None)):  # type: ignore[arg-type]
+        cmd = group.get_command(None, name)  # type: ignore[arg-type]
+        if cmd is None:
+            continue
+        full_prefix = f"{prefix} {name}" if prefix else name
+        if isinstance(cmd, click.Group):
+            commands.extend(_introspect_group(cmd, full_prefix))
+        else:
+            commands.append(_introspect_command(cmd, prefix))
+    return commands
+
+
+def handle_describe_all(typer_app: typer.Typer) -> None:
+    """Output schemas for all CLI commands as JSON and exit."""
+    click_group = typer.main.get_group(typer_app)
+    schemas = _introspect_group(click_group, "ga")
+    result = {
+        "cli": "ga-cli",
+        "commands": {s["command"]: s for s in schemas},
+    }
+    print(json.dumps(result, indent=2), file=sys.stdout)
+    raise typer.Exit(0)

ga_cli/utils/dry_run.py

@@ -0,0 +1,40 @@
+"""Dry-run support for mutative commands."""
+
+import json
+import sys
+
+import typer
+
+
+def handle_dry_run(
+    action: str,
+    method: str,
+    resource_path: str,
+    body: dict | None,
+    update_mask: str | None = None,
+) -> None:
+    """Output what would be sent to the API and exit.
+
+    Always outputs JSON regardless of the current output format,
+    since dry-run consumers are primarily agents.
+
+    Args:
+        action: "create", "update", "delete", "archive", or "acknowledge"
+        method: HTTP method equivalent ("POST", "PATCH", "DELETE")
+        resource_path: Full API resource path (e.g., "properties/123456")
+        body: Request body dict, or None for deletes
+        update_mask: For PATCH requests, the updateMask value
+    """
+    payload: dict = {
+        "dry_run": True,
+        "action": action,
+        "method": method,
+        "resource": resource_path,
+        "idempotent": action == "delete",
+    }
+    if body is not None:
+        payload["body"] = body
+    if update_mask is not None:
+        payload["update_mask"] = update_mask
+    print(json.dumps(payload, indent=2), file=sys.stdout)
+    raise typer.Exit(0)