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

ga_cli/commands/annotations.py

@@ -0,0 +1,264 @@
+"""Reporting data annotation 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_dry_run,
+    handle_error,
+    info,
+    output,
+    require_options,
+    resolve_output_format,
+    success,
+)
+from ..utils.pagination import paginate_all
+
+annotations_app = typer.Typer(
+    name="annotations",
+    help="Manage reporting data annotations",
+    no_args_is_help=True,
+)
+
+
+@annotations_app.command("list")
+def list_cmd(
+    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 reporting data annotations 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)
+
+        admin = get_admin_alpha_client()
+        annotations = paginate_all(
+            lambda **kw: admin.properties()
+            .reportingDataAnnotations()
+            .list(parent=f"properties/{effective_property}", **kw)
+            .execute(),
+            "reportingDataAnnotations",
+            pageSize=200,
+        )
+
+        output(
+            annotations,
+            effective_format,
+            columns=[
+                "name",
+                "title",
+                "annotationDate",
+                "description",
+                "color",
+            ],
+            headers=[
+                "Resource Name",
+                "Title",
+                "Date",
+                "Description",
+                "Color",
+            ],
+        )
+    except Exception as e:
+        handle_error(e)
+
+
+@annotations_app.command("get")
+def get_cmd(
+    property_id: Optional[str] = typer.Option(
+        None, "--property-id", "-p", help="Property ID (numeric)"
+    ),
+    annotation_id: str = typer.Option(
+        ..., "--annotation-id", "-a", help="Annotation ID"
+    ),
+    output_format: Optional[str] = typer.Option(
+        None, "--output", "-o", help="Output format (json, table, compact)"
+    ),
+):
+    """Get details for a reporting data annotation."""
+    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)
+
+        admin = get_admin_alpha_client()
+        annotation = (
+            admin.properties()
+            .reportingDataAnnotations()
+            .get(
+                name=f"properties/{effective_property}/reportingDataAnnotations/{annotation_id}"
+            )
+            .execute()
+        )
+        output(annotation, effective_format)
+    except Exception as e:
+        handle_error(e)
+
+
+@annotations_app.command("create")
+def create_cmd(
+    property_id: Optional[str] = typer.Option(
+        None, "--property-id", "-p", help="Property ID (numeric)"
+    ),
+    title: str = typer.Option(..., "--title", help="Annotation title"),
+    annotation_date: str = typer.Option(
+        ..., "--annotation-date", help="Date in YYYY-MM-DD format"
+    ),
+    description: str = typer.Option("", "--description", help="Annotation description"),
+    color: Optional[str] = typer.Option(None, "--color", help="Annotation color"),
+    dry_run: bool = typer.Option(
+        False, "--dry-run", help="Preview the request without executing"
+    ),
+    output_format: Optional[str] = typer.Option(
+        None, "--output", "-o", help="Output format (json, table, compact)"
+    ),
+):
+    """Create a reporting data annotation."""
+    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 = {
+            "title": title,
+            "annotationDate": annotation_date,
+            "description": description,
+        }
+        if color is not None:
+            body["color"] = color
+
+        if dry_run:
+            handle_dry_run("create", "POST", f"properties/{effective_property}", body)
+
+        admin = get_admin_alpha_client()
+        annotation = (
+            admin.properties()
+            .reportingDataAnnotations()
+            .create(parent=f"properties/{effective_property}", body=body)
+            .execute()
+        )
+        output(annotation, effective_format)
+    except typer.Exit:
+        raise
+    except Exception as e:
+        handle_error(e)
+
+
+@annotations_app.command("update")
+def update_cmd(
+    property_id: Optional[str] = typer.Option(
+        None, "--property-id", "-p", help="Property ID (numeric)"
+    ),
+    annotation_id: str = typer.Option(
+        ..., "--annotation-id", "-a", help="Annotation ID"
+    ),
+    title: Optional[str] = typer.Option(None, "--title", help="New title"),
+    description: Optional[str] = typer.Option(None, "--description", help="New description"),
+    color: Optional[str] = typer.Option(None, "--color", help="New color"),
+    dry_run: bool = typer.Option(
+        False, "--dry-run", help="Preview the request without executing"
+    ),
+    output_format: Optional[str] = typer.Option(
+        None, "--output", "-o", help="Output format (json, table, compact)"
+    ),
+):
+    """Update a reporting data annotation."""
+    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 = {}
+        mask_fields = []
+        if title is not None:
+            body["title"] = title
+            mask_fields.append("title")
+        if description is not None:
+            body["description"] = description
+            mask_fields.append("description")
+        if color is not None:
+            body["color"] = color
+            mask_fields.append("color")
+
+        if not mask_fields:
+            raise typer.BadParameter(
+                "At least one field must be specified: --title, --description, --color"
+            )
+
+        resource_name = f"properties/{effective_property}/reportingDataAnnotations/{annotation_id}"
+        if dry_run:
+            handle_dry_run(
+                "update", "PATCH", resource_name,
+                body, update_mask=",".join(mask_fields),
+            )
+
+        admin = get_admin_alpha_client()
+        annotation = (
+            admin.properties()
+            .reportingDataAnnotations()
+            .patch(
+                name=resource_name,
+                body=body,
+                updateMask=",".join(mask_fields),
+            )
+            .execute()
+        )
+        output(annotation, effective_format)
+    except (typer.BadParameter, typer.Exit):
+        raise
+    except Exception as e:
+        handle_error(e)
+
+
+@annotations_app.command("delete")
+def delete_cmd(
+    property_id: Optional[str] = typer.Option(
+        None, "--property-id", "-p", help="Property ID (numeric)"
+    ),
+    annotation_id: str = typer.Option(
+        ..., "--annotation-id", "-a", help="Annotation ID"
+    ),
+    yes: bool = typer.Option(False, "--yes", "-y", help="Skip confirmation prompt"),
+    dry_run: bool = typer.Option(
+        False, "--dry-run", help="Preview the request without executing"
+    ),
+):
+    """Delete a reporting data annotation."""
+    try:
+        effective_property = get_effective_value(property_id, "default_property_id")
+        require_options({"property_id": effective_property}, ["property_id"])
+
+        if dry_run:
+            handle_dry_run(
+                "delete", "DELETE",
+                f"properties/{effective_property}/reportingDataAnnotations/{annotation_id}",
+                None,
+            )
+
+        if not yes:
+            confirmed = questionary.confirm(
+                f"Delete annotation {annotation_id}? This cannot be undone."
+            ).ask()
+            if not confirmed:
+                info("Cancelled.")
+                raise typer.Exit()
+
+        admin = get_admin_alpha_client()
+        resource_name = f"properties/{effective_property}/reportingDataAnnotations/{annotation_id}"
+        admin.properties().reportingDataAnnotations().delete(
+            name=resource_name
+        ).execute()
+        success(f"Annotation {annotation_id} deleted.")
+    except typer.Exit:
+        raise
+    except Exception as e:
+        handle_error(e)

ga_cli/commands/audiences.py

@@ -0,0 +1,223 @@
+"""Audience management commands."""
+
+import json
+from pathlib import Path
+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, require_options, resolve_output_format, success
+from ..utils.pagination import paginate_all
+
+audiences_app = typer.Typer(
+    name="audiences",
+    help="Manage audiences",
+    no_args_is_help=True,
+)
+
+
+def _load_json_config(config_file: str) -> dict:
+    """Load and parse a JSON config file."""
+    config_path = Path(config_file)
+    if not config_path.exists():
+        raise typer.BadParameter(f"Config file not found: {config_file}")
+    try:
+        return json.loads(config_path.read_text())
+    except json.JSONDecodeError as exc:
+        raise typer.BadParameter(f"Invalid JSON in config file: {exc}")
+
+
+@audiences_app.command("list")
+def list_cmd(
+    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 audiences 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)
+
+        admin = get_admin_alpha_client()
+        audiences = paginate_all(
+            lambda **kw: admin.properties()
+            .audiences()
+            .list(parent=f"properties/{effective_property}", **kw)
+            .execute(),
+            "audiences",
+            pageSize=200,
+        )
+
+        output(
+            audiences,
+            effective_format,
+            columns=[
+                "name",
+                "displayName",
+                "description",
+                "membershipDurationDays",
+            ],
+            headers=[
+                "Resource Name",
+                "Display Name",
+                "Description",
+                "Membership Days",
+            ],
+        )
+    except Exception as e:
+        handle_error(e)
+
+
+@audiences_app.command("get")
+def get_cmd(
+    property_id: Optional[str] = typer.Option(
+        None, "--property-id", "-p", help="Property ID (numeric)"
+    ),
+    audience_id: str = typer.Option(
+        ..., "--audience-id", "-a", help="Audience ID"
+    ),
+    output_format: Optional[str] = typer.Option(
+        None, "--output", "-o", help="Output format (json, table, compact)"
+    ),
+):
+    """Get details for an audience."""
+    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)
+
+        admin = get_admin_alpha_client()
+        audience = (
+            admin.properties()
+            .audiences()
+            .get(
+                name=f"properties/{effective_property}/audiences/{audience_id}"
+            )
+            .execute()
+        )
+        output(audience, effective_format)
+    except Exception as e:
+        handle_error(e)
+
+
+@audiences_app.command("create")
+def create_cmd(
+    property_id: Optional[str] = typer.Option(
+        None, "--property-id", "-p", help="Property ID (numeric)"
+    ),
+    config_file: str = typer.Option(
+        ..., "--config", "-c", help="Path to JSON audience config file"
+    ),
+    output_format: Optional[str] = typer.Option(
+        None, "--output", "-o", help="Output format (json, table, compact)"
+    ),
+):
+    """Create an audience from a JSON config file."""
+    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 = _load_json_config(config_file)
+
+        admin = get_admin_alpha_client()
+        audience = (
+            admin.properties()
+            .audiences()
+            .create(parent=f"properties/{effective_property}", body=body)
+            .execute()
+        )
+        output(audience, effective_format)
+    except typer.BadParameter:
+        raise
+    except Exception as e:
+        handle_error(e)
+
+
+@audiences_app.command("update")
+def update_cmd(
+    property_id: Optional[str] = typer.Option(
+        None, "--property-id", "-p", help="Property ID (numeric)"
+    ),
+    audience_id: str = typer.Option(
+        ..., "--audience-id", "-a", help="Audience ID"
+    ),
+    config_file: str = typer.Option(
+        ..., "--config", "-c", help="Path to JSON file with fields to update"
+    ),
+    output_format: Optional[str] = typer.Option(
+        None, "--output", "-o", help="Output format (json, table, compact)"
+    ),
+):
+    """Update an audience from a JSON config file."""
+    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 = _load_json_config(config_file)
+
+        if not body:
+            raise typer.BadParameter("Config file must contain at least one field to update.")
+
+        update_mask = ",".join(body.keys())
+
+        admin = get_admin_alpha_client()
+        resource_name = f"properties/{effective_property}/audiences/{audience_id}"
+        audience = (
+            admin.properties()
+            .audiences()
+            .patch(
+                name=resource_name,
+                body=body,
+                updateMask=update_mask,
+            )
+            .execute()
+        )
+        output(audience, effective_format)
+    except typer.BadParameter:
+        raise
+    except Exception as e:
+        handle_error(e)
+
+
+@audiences_app.command("archive")
+def archive_cmd(
+    property_id: Optional[str] = typer.Option(
+        None, "--property-id", "-p", help="Property ID (numeric)"
+    ),
+    audience_id: str = typer.Option(
+        ..., "--audience-id", "-a", help="Audience ID"
+    ),
+    yes: bool = typer.Option(False, "--yes", "-y", help="Skip confirmation prompt"),
+):
+    """Archive an audience."""
+    try:
+        effective_property = get_effective_value(property_id, "default_property_id")
+        require_options({"property_id": effective_property}, ["property_id"])
+
+        if not yes:
+            confirmed = questionary.confirm(
+                f"Archive audience {audience_id}? This cannot be undone."
+            ).ask()
+            if not confirmed:
+                info("Cancelled.")
+                raise typer.Exit()
+
+        admin = get_admin_alpha_client()
+        resource_name = f"properties/{effective_property}/audiences/{audience_id}"
+        admin.properties().audiences().archive(
+            name=resource_name, body={}
+        ).execute()
+        success(f"Audience {audience_id} archived.")
+    except typer.Exit:
+        raise
+    except Exception as e:
+        handle_error(e)

ga_cli/commands/auth_cmd.py

@@ -0,0 +1,205 @@
+"""Authentication commands: login, logout, status.
+
+Equivalent to GTM CLI's commands/auth.ts.
+"""
+
+from typing import Optional
+
+import typer
+
+from ..api.client import clear_client_cache
+from ..auth.oauth import get_auth_status, login, logout
+from ..auth.service_account import (
+    clear_auth_method,
+    load_auth_method,
+    login_with_service_account,
+)
+from ..utils import error, info, output, success
+
+auth_app = typer.Typer(name="auth", help="Manage authentication", no_args_is_help=True)
+
+_SETUP_GUIDE = r"""# GA CLI — OAuth Credential Setup
+
+GA CLI requires your own Google Cloud Platform OAuth credentials.
+Follow these steps to create them.
+
+## Step 1: Create or Select a GCP Project
+
+1. Go to the Google Cloud Console: https://console.cloud.google.com/
+2. Create a new project or select an existing one
+3. Note your project ID
+
+## Step 2: Enable Required APIs
+
+In the GCP Console, go to APIs & Services > Library and enable:
+- Google Analytics Admin API
+- Google Analytics Data API
+
+Or via gcloud CLI:
+
+    gcloud services enable analyticsadmin.googleapis.com analyticsdata.googleapis.com
+
+## Step 3: Configure OAuth Consent Screen
+
+1. Go to APIs & Services > OAuth consent screen
+2. Choose "External" user type (or "Internal" if using Google Workspace)
+3. Fill in the required fields: app name, user support email, developer contact
+4. No scopes need to be added manually — GA CLI requests them at login time
+5. For personal use, leave the app in "Testing" mode — it works for the
+   project owner and up to 100 added test users without Google verification
+
+## Step 4: Create OAuth Client ID
+
+1. Go to APIs & Services > Credentials
+2. Click "Create Credentials" > "OAuth client ID"
+3. Choose "Desktop app" as the application type
+4. Give it a name (e.g., "GA CLI")
+5. Click "Create" and download the JSON file
+
+## Step 5: Provide Credentials to GA CLI
+
+Option A — Place the downloaded JSON file (recommended):
+
+    mkdir -p ~/.config/ga-cli
+    cp /path/to/downloaded/client_secret_*.json ~/.config/ga-cli/client_secret.json
+
+Option B — Set environment variables:
+
+    export GA_CLI_CLIENT_ID="your-client-id.apps.googleusercontent.com"
+    export GA_CLI_CLIENT_SECRET="your-client-secret"
+
+## Step 6: Authenticate
+
+    ga auth login
+
+This opens your browser for Google OAuth consent and stores the token
+locally at ~/.config/ga-cli/credentials.json.
+
+## Verification
+
+    ga auth status          # Check authentication state
+    ga accounts list        # Verify API access
+
+## Notes
+
+- "Testing" mode is sufficient for personal use — no Google verification needed
+- For team use, publish the consent screen to "Production" within your GCP project
+- Service account auth (ga auth login --service-account /path/key.json) does not
+  require OAuth credentials and works independently
+"""
+
+
+@auth_app.command("setup")
+def setup_cmd():
+    """Show step-by-step instructions for obtaining GCP OAuth credentials."""
+    print(_SETUP_GUIDE)
+
+
+@auth_app.command("login")
+def login_cmd(
+    service_account: Optional[str] = typer.Option(
+        None, "--service-account", "-s",
+        help="Path to service account key JSON file",
+    ),
+):
+    """Authenticate with Google Analytics."""
+    try:
+        if service_account:
+            info(f"Authenticating with service account: {service_account}")
+            email = login_with_service_account(service_account)
+            success(f"Authenticated as {email}")
+            info("Service account credentials are now active.")
+            return
+
+        # OAuth (default)
+        status = get_auth_status()
+        if status.get("authenticated") and status.get("email"):
+            info(f"Already authenticated as {status['email']}")
+            info("Run 'ga auth logout' first, or 'ga auth status' to view details.")
+            return
+
+        info("Opening browser for authentication...")
+        login()
+        clear_client_cache()
+
+        # Fetch user info to display
+        status = get_auth_status()
+        email = status.get("email", "unknown")
+        success(f"Authenticated as {email}")
+    except Exception as e:
+        error(f"Authentication failed: {e}")
+        raise typer.Exit(1)
+
+
+@auth_app.command("logout")
+def logout_cmd():
+    """Sign out and revoke access tokens."""
+    try:
+        auth_method = load_auth_method()
+        status = get_auth_status()
+
+        if not auth_method and not status.get("authenticated"):
+            info("Not currently authenticated.")
+            return
+
+        if auth_method and auth_method.get("method") == "service-account":
+            clear_auth_method()
+            email = auth_method.get("service_account_email", "")
+            success(f"Cleared service account configuration ({email})")
+            info("The service account key file was not deleted.")
+
+        if status.get("authenticated"):
+            logout()
+            clear_client_cache()
+            success("Logged out from OAuth session.")
+
+    except Exception as e:
+        error(f"Logout failed: {e}")
+        raise typer.Exit(1)
+
+
+@auth_app.command("status")
+def status_cmd(
+    output_format: str = typer.Option("table", "--output", "-o", help="Output format"),
+):
+    """Show current authentication status."""
+    try:
+        import os
+
+        # Check for env var override (same priority as GTM CLI)
+        env_key = os.environ.get("GA_CLI_SERVICE_ACCOUNT") or os.environ.get(
+            "GOOGLE_APPLICATION_CREDENTIALS"
+        )
+        if env_key:
+            data = {
+                "authenticated": True,
+                "method": "service-account",
+                "source": "environment variable",
+                "key_path": env_key,
+            }
+            output(data, output_format)
+            return
+
+        # Check saved auth method
+        auth_method = load_auth_method()
+        if auth_method and auth_method.get("method") == "service-account":
+            data = {
+                "authenticated": True,
+                "method": "service-account",
+                "email": auth_method.get("service_account_email"),
+                "key_path": auth_method.get("service_account_path"),
+            }
+            output(data, output_format)
+            return
+
+        # Fall back to OAuth
+        auth_status = get_auth_status()
+        auth_status["method"] = "oauth"
+        output(auth_status, output_format)
+
+        if not auth_status.get("authenticated"):
+            info("Run 'ga auth login' to authenticate.")
+
+    except Exception as e:
+        error(f"Failed to get status: {e}")
+        raise typer.Exit(1)