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

ga_cli/commands/properties.py

@@ -0,0 +1,330 @@
+"""Property management commands."""
+
+from typing import Optional
+
+import questionary
+import typer
+
+from ..api.client import get_admin_client, get_data_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
+
+properties_app = typer.Typer(name="properties", help="Manage GA4 properties", no_args_is_help=True)
+
+
+@properties_app.command("list")
+def list_cmd(
+    account_id: Optional[str] = typer.Option(None, "--account-id", "-a", help="Account ID"),
+    output_format: Optional[str] = typer.Option(
+        None, "--output", "-o", help="Output format (json, table, compact)"
+    ),
+):
+    """List GA4 properties 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)
+
+        admin = get_admin_client()
+        properties = paginate_all(
+            lambda **kw: (
+                admin.properties()
+                .list(filter=f"parent:accounts/{effective_account}", **kw)
+                .execute()
+            ),
+            "properties",
+            pageSize=200,
+        )
+
+        output(
+            properties,
+            effective_format,
+            columns=["name", "displayName", "timeZone", "currencyCode"],
+            headers=["Resource Name", "Display Name", "Time Zone", "Currency"],
+        )
+    except Exception as e:
+        handle_error(e)
+
+
+@properties_app.command("get")
+def get_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)"
+    ),
+):
+    """Get details for a specific 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_client()
+        prop = admin.properties().get(name=f"properties/{effective_property}").execute()
+        output(prop, effective_format)
+    except Exception as e:
+        handle_error(e)
+
+
+@properties_app.command("create")
+def create_cmd(
+    display_name: str = typer.Option(..., "--name", help="Property display name"),
+    account_id: Optional[str] = typer.Option(None, "--account-id", "-a", help="Account ID"),
+    timezone: str = typer.Option("America/Los_Angeles", "--timezone", help="Reporting time zone"),
+    currency: str = typer.Option("USD", "--currency", help="Currency code"),
+    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 new GA4 property."""
+    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 = {
+            "parent": f"accounts/{effective_account}",
+            "displayName": display_name,
+            "timeZone": timezone,
+            "currencyCode": currency,
+        }
+        if dry_run:
+            handle_dry_run("create", "POST", f"accounts/{effective_account}", body)
+
+        admin = get_admin_client()
+        prop = admin.properties().create(body=body).execute()
+        output(prop, effective_format)
+    except typer.Exit:
+        raise
+    except Exception as e:
+        handle_error(e)
+
+
+@properties_app.command("update")
+def update_cmd(
+    property_id: Optional[str] = typer.Option(
+        None, "--property-id", "-p", help="Property ID (numeric)"
+    ),
+    name: Optional[str] = typer.Option(None, "--name", help="New display name"),
+    timezone: Optional[str] = typer.Option(
+        None, "--timezone", help="Reporting time zone (e.g., America/New_York)"
+    ),
+    currency: Optional[str] = typer.Option(
+        None, "--currency", help="Currency code (e.g., USD, EUR)"
+    ),
+    industry: Optional[str] = typer.Option(None, "--industry", help="Industry category"),
+    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 GA4 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)
+
+        # Map CLI options to API field names
+        field_map = {
+            "displayName": name,
+            "timeZone": timezone,
+            "currencyCode": currency,
+            "industryCategory": industry,
+        }
+        body = {k: v for k, v in field_map.items() if v is not None}
+
+        if not body:
+            raise typer.BadParameter(
+                "At least one of --name, --timezone, --currency, or --industry must be specified."
+            )
+
+        update_mask = ",".join(body.keys())
+
+        if dry_run:
+            handle_dry_run(
+                "update", "PATCH", f"properties/{effective_property}",
+                body, update_mask=update_mask,
+            )
+
+        admin = get_admin_client()
+        prop = (
+            admin.properties()
+            .patch(
+                name=f"properties/{effective_property}",
+                body=body,
+                updateMask=update_mask,
+            )
+            .execute()
+        )
+        output(prop, effective_format)
+    except (typer.BadParameter, typer.Exit):
+        raise
+    except Exception as e:
+        handle_error(e)
+
+
+@properties_app.command("delete")
+def delete_cmd(
+    property_id: Optional[str] = typer.Option(
+        None, "--property-id", "-p", help="Property ID (numeric)"
+    ),
+    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 GA4 property (soft delete)."""
+    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}", None)
+
+        if not yes:
+            confirmed = questionary.confirm(
+                f"Delete property {effective_property}? This cannot be undone."
+            ).ask()
+            if not confirmed:
+                info("Cancelled.")
+                raise typer.Exit()
+
+        admin = get_admin_client()
+        admin.properties().delete(name=f"properties/{effective_property}").execute()
+        success(f"Property {effective_property} deleted.")
+    except typer.Exit:
+        raise
+    except Exception as e:
+        handle_error(e)
+
+
+_UDC_ACKNOWLEDGEMENT = (
+    "I acknowledge that I have the necessary privacy disclosures and rights "
+    "from my end users for the collection and processing of their data, "
+    "including the association of such data with the visitation information "
+    "Google Analytics collects from my site and/or app property."
+)
+
+
+@properties_app.command("acknowledge-udc")
+def acknowledge_udc_cmd(
+    property_id: Optional[str] = typer.Option(
+        None, "--property-id", "-p", help="Property ID (numeric)"
+    ),
+    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"
+    ),
+):
+    """Acknowledge user data collection for a property.
+
+    Required before Measurement Protocol secrets can be created.
+    """
+    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(
+                "acknowledge", "POST", f"properties/{effective_property}",
+                {"acknowledgement": _UDC_ACKNOWLEDGEMENT},
+            )
+
+        if not yes:
+            info(f'You are about to acknowledge:\n\n  "{_UDC_ACKNOWLEDGEMENT}"\n')
+            confirmed = questionary.confirm("Proceed with acknowledgement?").ask()
+            if not confirmed:
+                info("Cancelled.")
+                raise typer.Exit()
+
+        admin = get_admin_client()
+        admin.properties().acknowledgeUserDataCollection(
+            property=f"properties/{effective_property}",
+            body={"acknowledgement": _UDC_ACKNOWLEDGEMENT},
+        ).execute()
+        success(f"User data collection acknowledged for property {effective_property}.")
+    except typer.Exit:
+        raise
+    except Exception as e:
+        handle_error(e)
+
+
+def _format_quota_category(key: str) -> str:
+    """Convert API field name to human-readable label (e.g. 'tokensPerDay' -> 'Tokens Per Day')."""
+    import re
+
+    # Split on camelCase boundaries
+    words = re.sub(r"([a-z])([A-Z])", r"\1 \2", key)
+    return words.title()
+
+
+@properties_app.command("quotas")
+def quotas_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)"
+    ),
+):
+    """Show API quota usage 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)
+
+        data_alpha = get_data_alpha_client()
+        result = (
+            data_alpha.properties()
+            .getPropertyQuotasSnapshot(
+                name=f"properties/{effective_property}/propertyQuotasSnapshot"
+            )
+            .execute()
+        )
+
+        if effective_format != "table":
+            output(result, effective_format)
+            return
+
+        rows = []
+        for category_key, category_value in result.items():
+            if not isinstance(category_value, dict):
+                continue
+            category_label = _format_quota_category(category_key)
+            for metric_key, metric_value in category_value.items():
+                if isinstance(metric_value, dict) and "remaining" in metric_value:
+                    rows.append({
+                        "category": category_label,
+                        "metric": _format_quota_category(metric_key),
+                        "consumed": str(metric_value.get("consumed", 0)),
+                        "remaining": str(metric_value.get("remaining", 0)),
+                    })
+
+        if not rows:
+            info("No quota data available.")
+        else:
+            output(
+                rows,
+                effective_format,
+                columns=["category", "metric", "consumed", "remaining"],
+                headers=["Quota Category", "Metric", "Consumed", "Remaining"],
+            )
+
+    except Exception as e:
+        handle_error(e)

ga_cli/commands/property_settings.py

@@ -0,0 +1,287 @@
+"""Property settings commands (attribution, Google Signals, enhanced measurement)."""
+
+from typing import Optional
+
+import typer
+
+from ..api.client import get_admin_alpha_client
+from ..config.store import get_effective_value
+from ..utils import handle_error, output, require_options, resolve_output_format, success
+
+property_settings_app = typer.Typer(
+    name="property-settings",
+    help="Manage property-level settings",
+    no_args_is_help=True,
+)
+
+# --- Attribution Settings ---
+
+_ACQUISITION_LOOKBACK_CHOICES = [
+    "ACQUISITION_CONVERSION_EVENT_LOOKBACK_WINDOW_7_DAYS",
+    "ACQUISITION_CONVERSION_EVENT_LOOKBACK_WINDOW_30_DAYS",
+]
+
+_OTHER_LOOKBACK_CHOICES = [
+    "OTHER_CONVERSION_EVENT_LOOKBACK_WINDOW_30_DAYS",
+    "OTHER_CONVERSION_EVENT_LOOKBACK_WINDOW_60_DAYS",
+    "OTHER_CONVERSION_EVENT_LOOKBACK_WINDOW_90_DAYS",
+]
+
+_ATTRIBUTION_MODEL_CHOICES = [
+    "PAID_AND_ORGANIC_CHANNELS_DATA_DRIVEN",
+    "PAID_AND_ORGANIC_CHANNELS_LAST_CLICK",
+    "GOOGLE_PAID_CHANNELS_LAST_CLICK",
+]
+
+_ADS_EXPORT_SCOPE_CHOICES = [
+    "NOT_SELECTED_YET",
+    "PAID_AND_ORGANIC_CHANNELS",
+    "GOOGLE_PAID_CHANNELS",
+]
+
+
+def _validate_enum(value: Optional[str], choices: list[str], flag_name: str) -> None:
+    """Validate an enum value against allowed choices."""
+    if value is not None and value not in choices:
+        raise typer.BadParameter(
+            f"Invalid value '{value}' for {flag_name}. "
+            f"Must be one of: {', '.join(choices)}"
+        )
+
+
+@property_settings_app.command("attribution")
+def attribution_cmd(
+    property_id: Optional[str] = typer.Option(
+        None, "--property-id", "-p", help="Property ID (numeric)"
+    ),
+    acquisition_lookback: Optional[str] = typer.Option(
+        None,
+        "--acquisition-lookback",
+        help=f"Acquisition conversion lookback window ({', '.join(_ACQUISITION_LOOKBACK_CHOICES)})",
+    ),
+    other_lookback: Optional[str] = typer.Option(
+        None,
+        "--other-lookback",
+        help=f"Other conversion lookback window ({', '.join(_OTHER_LOOKBACK_CHOICES)})",
+    ),
+    attribution_model: Optional[str] = typer.Option(
+        None,
+        "--attribution-model",
+        help=f"Reporting attribution model ({', '.join(_ATTRIBUTION_MODEL_CHOICES)})",
+    ),
+    ads_export_scope: Optional[str] = typer.Option(
+        None,
+        "--ads-export-scope",
+        help=f"Ads web conversion data export scope ({', '.join(_ADS_EXPORT_SCOPE_CHOICES)})",
+    ),
+    output_format: Optional[str] = typer.Option(
+        None, "--output", "-o", help="Output format (json, table, compact)"
+    ),
+):
+    """Get or update attribution settings. With no update flags, displays current settings."""
+    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)
+
+        resource_name = f"properties/{effective_property}/attributionSettings"
+        admin = get_admin_alpha_client()
+
+        field_map = {
+            "acquisitionConversionEventLookbackWindow": acquisition_lookback,
+            "otherConversionEventLookbackWindow": other_lookback,
+            "reportingAttributionModel": attribution_model,
+            "adsWebConversionDataExportScope": ads_export_scope,
+        }
+        body = {k: v for k, v in field_map.items() if v is not None}
+
+        if body:
+            # Validate enums
+            _validate_enum(
+                acquisition_lookback,
+                _ACQUISITION_LOOKBACK_CHOICES,
+                "--acquisition-lookback",
+            )
+            _validate_enum(other_lookback, _OTHER_LOOKBACK_CHOICES, "--other-lookback")
+            _validate_enum(attribution_model, _ATTRIBUTION_MODEL_CHOICES, "--attribution-model")
+            _validate_enum(ads_export_scope, _ADS_EXPORT_SCOPE_CHOICES, "--ads-export-scope")
+
+            update_mask = ",".join(body.keys())
+            settings = (
+                admin.properties()
+                .updateAttributionSettings(
+                    name=resource_name, updateMask=update_mask, body=body
+                )
+                .execute()
+            )
+            success("Attribution settings updated.")
+        else:
+            settings = (
+                admin.properties()
+                .getAttributionSettings(name=resource_name)
+                .execute()
+            )
+
+        output(settings, effective_format)
+    except typer.BadParameter:
+        raise
+    except Exception as e:
+        handle_error(e)
+
+
+# --- Google Signals Settings ---
+
+_SIGNALS_STATE_CHOICES = [
+    "GOOGLE_SIGNALS_ENABLED",
+    "GOOGLE_SIGNALS_DISABLED",
+]
+
+
+@property_settings_app.command("google-signals")
+def google_signals_cmd(
+    property_id: Optional[str] = typer.Option(
+        None, "--property-id", "-p", help="Property ID (numeric)"
+    ),
+    state: Optional[str] = typer.Option(
+        None,
+        "--state",
+        help=f"Google Signals state ({', '.join(_SIGNALS_STATE_CHOICES)})",
+    ),
+    output_format: Optional[str] = typer.Option(
+        None, "--output", "-o", help="Output format (json, table, compact)"
+    ),
+):
+    """Get or update Google Signals settings. With no update flags, displays current settings."""
+    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)
+
+        resource_name = f"properties/{effective_property}/googleSignalsSettings"
+        admin = get_admin_alpha_client()
+
+        if state is not None:
+            _validate_enum(state, _SIGNALS_STATE_CHOICES, "--state")
+            body = {"state": state}
+            settings = (
+                admin.properties()
+                .updateGoogleSignalsSettings(
+                    name=resource_name, updateMask="state", body=body
+                )
+                .execute()
+            )
+            success("Google Signals settings updated.")
+        else:
+            settings = (
+                admin.properties()
+                .getGoogleSignalsSettings(name=resource_name)
+                .execute()
+            )
+
+        output(settings, effective_format)
+    except typer.BadParameter:
+        raise
+    except Exception as e:
+        handle_error(e)
+
+
+# --- Enhanced Measurement Settings ---
+
+
+@property_settings_app.command("enhanced-measurement")
+def enhanced_measurement_cmd(
+    property_id: Optional[str] = typer.Option(
+        None, "--property-id", "-p", help="Property ID (numeric)"
+    ),
+    stream_id: str = typer.Option(
+        ..., "--stream-id", "-s", help="Data stream ID"
+    ),
+    stream_enabled: Optional[bool] = typer.Option(
+        None,
+        "--stream-enabled/--no-stream-enabled",
+        help="Enable/disable enhanced measurement for this stream",
+    ),
+    scrolls: Optional[bool] = typer.Option(
+        None, "--scrolls/--no-scrolls", help="Capture scroll events"
+    ),
+    outbound_clicks: Optional[bool] = typer.Option(
+        None, "--outbound-clicks/--no-outbound-clicks", help="Capture outbound click events"
+    ),
+    site_search: Optional[bool] = typer.Option(
+        None, "--site-search/--no-site-search", help="Capture site search events"
+    ),
+    video_engagement: Optional[bool] = typer.Option(
+        None, "--video-engagement/--no-video-engagement", help="Capture video engagement events"
+    ),
+    file_downloads: Optional[bool] = typer.Option(
+        None, "--file-downloads/--no-file-downloads", help="Capture file download events"
+    ),
+    page_changes: Optional[bool] = typer.Option(
+        None, "--page-changes/--no-page-changes", help="Capture page change (history) events"
+    ),
+    form_interactions: Optional[bool] = typer.Option(
+        None, "--form-interactions/--no-form-interactions", help="Capture form interaction events"
+    ),
+    search_query_parameter: Optional[str] = typer.Option(
+        None, "--search-query-parameter", help="URL query parameters for site search"
+    ),
+    uri_query_parameter: Optional[str] = typer.Option(
+        None, "--uri-query-parameter", help="Additional URL query parameters"
+    ),
+    output_format: Optional[str] = typer.Option(
+        None, "--output", "-o", help="Output format (json, table, compact)"
+    ),
+):
+    """Get or update enhanced measurement settings.
+
+    With no update flags, displays current settings.
+    """
+    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)
+
+        resource_name = (
+            f"properties/{effective_property}/dataStreams/{stream_id}"
+            "/enhancedMeasurementSettings"
+        )
+        admin = get_admin_alpha_client()
+
+        field_map = {
+            "streamEnabled": stream_enabled,
+            "scrollsEnabled": scrolls,
+            "outboundClicksEnabled": outbound_clicks,
+            "siteSearchEnabled": site_search,
+            "videoEngagementEnabled": video_engagement,
+            "fileDownloadsEnabled": file_downloads,
+            "pageChangesEnabled": page_changes,
+            "formInteractionsEnabled": form_interactions,
+            "searchQueryParameter": search_query_parameter,
+            "uriQueryParameter": uri_query_parameter,
+        }
+        body = {k: v for k, v in field_map.items() if v is not None}
+
+        if body:
+            update_mask = ",".join(body.keys())
+            settings = (
+                admin.properties()
+                .dataStreams()
+                .updateEnhancedMeasurementSettings(
+                    name=resource_name, updateMask=update_mask, body=body
+                )
+                .execute()
+            )
+            success("Enhanced measurement settings updated.")
+        else:
+            settings = (
+                admin.properties()
+                .dataStreams()
+                .getEnhancedMeasurementSettings(name=resource_name)
+                .execute()
+            )
+
+        output(settings, effective_format)
+    except typer.BadParameter:
+        raise
+    except Exception as e:
+        handle_error(e)