ga4-cli 0.1.1__py3-none-any.whl

ga_cli/commands/datastreams.py

@@ -0,0 +1,146 @@
+"""Data stream management commands"""
+
+import click
+from google.analytics.admin_v1alpha.types import DataStream
+from ga_cli.decorators import with_client
+from ga_cli.formatters.table import format_table
+from ga_cli.formatters.json import format_json
+from ga_cli.validators import validate_property_id, validate_stream_id, validate_url
+from ga_cli.logging_config import logger
+from ga_cli.retry import retry_on_transient_error
+
+
+@click.group()
+def datastreams():
+    """Manage data streams"""
+    pass
+
+
+@datastreams.command()
+@click.argument('property_id', callback=validate_property_id)
+@click.option('--format', type=click.Choice(['table', 'json']), default='table')
+@click.pass_context
+@with_client
+def list(ctx, property_id, format):
+    """List data streams for a property"""
+    client = ctx.obj['client']
+    logger.info(f"Listing data streams for property: {property_id}")
+
+    streams_data = []
+    for stream in _list_datastreams_with_retry(client, property_id):
+        stream_info = {
+            'id': stream.name.split('/')[-1] if '/' in stream.name else stream.name,
+            'name': stream.display_name or 'N/A',
+            'type': stream.type_.name if stream.type_ else 'N/A',
+        }
+
+        # Add stream-type specific data with null checks
+        if stream.web_stream_data:
+            stream_info['measurement_id'] = stream.web_stream_data.measurement_id or 'N/A'
+            stream_info['url'] = stream.web_stream_data.default_uri or 'N/A'
+        elif stream.android_app_stream_data:
+            stream_info['package_name'] = stream.android_app_stream_data.package_name or 'N/A'
+        elif stream.ios_app_stream_data:
+            stream_info['bundle_id'] = stream.ios_app_stream_data.bundle_id or 'N/A'
+
+        streams_data.append(stream_info)
+
+    logger.info(f"Found {len(streams_data)} data streams")
+
+    if format == 'json':
+        format_json(streams_data)
+    else:
+        format_table(streams_data, title=f"Data Streams for Property {property_id}")
+
+
+@datastreams.command()
+@click.argument('property_id', callback=validate_property_id)
+@click.argument('stream_id', callback=validate_stream_id)
+@click.option('--format', type=click.Choice(['table', 'json']), default='table')
+@click.pass_context
+@with_client
+def get(ctx, property_id, stream_id, format):
+    """Get data stream details including measurement ID"""
+    client = ctx.obj['client']
+    logger.info(f"Getting data stream {stream_id} for property: {property_id}")
+
+    stream = _get_datastream_with_retry(client, property_id, stream_id)
+
+    stream_data = {
+        'id': stream.name.split('/')[-1] if '/' in stream.name else stream.name,
+        'name': stream.display_name or 'N/A',
+        'type': stream.type_.name if stream.type_ else 'N/A',
+        'create_time': str(stream.create_time).split('.')[0] if stream.create_time else 'N/A',
+    }
+
+    # Add web stream specific data with null checks
+    if stream.web_stream_data:
+        stream_data['measurement_id'] = stream.web_stream_data.measurement_id or 'N/A'
+        stream_data['url'] = stream.web_stream_data.default_uri or 'N/A'
+        stream_data['firebase_app_id'] = stream.web_stream_data.firebase_app_id or 'N/A'
+
+    logger.info(f"Retrieved data stream: {stream.display_name}")
+
+    if format == 'json':
+        format_json(stream_data)
+    else:
+        format_table([stream_data], title=f"Data Stream: {stream.display_name}")
+
+        if stream.web_stream_data and stream.web_stream_data.measurement_id:
+            click.echo(f"\nMeasurement ID: {stream.web_stream_data.measurement_id}")
+
+
+@datastreams.command()
+@click.argument('property_id', callback=validate_property_id)
+@click.option('--name', required=True, help='Display name for the data stream')
+@click.option('--url', required=True, callback=validate_url, help='Website URL')
+@click.pass_context
+@with_client
+def create(ctx, property_id, name, url):
+    """Create a new web data stream"""
+    client = ctx.obj['client']
+    logger.info(f"Creating data stream '{name}' for property: {property_id}")
+
+    stream = _create_datastream_with_retry(client, property_id, name, url)
+
+    stream_id = stream.name.split('/')[-1] if '/' in stream.name else stream.name
+    logger.info(f"Created data stream: {stream_id}")
+
+    click.echo(f"Created data stream: {stream.display_name}")
+    click.echo(f"  Stream ID: {stream_id}")
+    if stream.web_stream_data:
+        if stream.web_stream_data.measurement_id:
+            click.echo(f"  Measurement ID: {stream.web_stream_data.measurement_id}")
+        if stream.web_stream_data.default_uri:
+            click.echo(f"  URL: {stream.web_stream_data.default_uri}")
+
+
+@retry_on_transient_error()
+def _list_datastreams_with_retry(client, property_id):
+    """List data streams with retry logic"""
+    return list(client.list_data_streams(parent=f"properties/{property_id}"))
+
+
+@retry_on_transient_error()
+def _get_datastream_with_retry(client, property_id, stream_id):
+    """Get data stream with retry logic"""
+    return client.get_data_stream(name=f"properties/{property_id}/dataStreams/{stream_id}")
+
+
+@retry_on_transient_error()
+def _create_datastream_with_retry(client, property_id, name, url):
+    """Create data stream with retry logic"""
+    data_stream = DataStream(
+        display_name=name,
+        type_=DataStream.DataStreamType.WEB_DATA_STREAM,
+    )
+
+    # Safely initialize web_stream_data if not exists
+    if data_stream.web_stream_data is None:
+        data_stream.web_stream_data = DataStream.WebStreamData()
+    data_stream.web_stream_data.default_uri = url
+
+    return client.create_data_stream(
+        parent=f"properties/{property_id}",
+        data_stream=data_stream
+    )

ga_cli/commands/properties.py

@@ -0,0 +1,151 @@
+"""Property management commands"""
+
+import click
+from google.analytics.admin_v1alpha.types import Property
+from ga_cli.decorators import with_client
+from ga_cli.formatters.table import format_table
+from ga_cli.formatters.json import format_json
+from ga_cli.validators import validate_account_id, validate_property_id, validate_timezone, validate_currency
+from ga_cli.logging_config import logger
+from ga_cli.retry import retry_on_transient_error
+
+
+@click.group()
+def properties():
+    """Manage Google Analytics properties"""
+    pass
+
+
+@properties.command()
+@click.argument('account_id', callback=validate_account_id)
+@click.option('--format', type=click.Choice(['table', 'json']), default='table')
+@click.pass_context
+@with_client
+def list(ctx, account_id, format):
+    """List properties for an account"""
+    client = ctx.obj['client']
+    logger.info(f"Listing properties for account: {account_id}")
+
+    properties_data = []
+    request = {"filter": f"ancestor:accounts/{account_id}"}
+    for property in _list_properties_with_retry(client, request):
+        properties_data.append({
+            'id': property.name.split('/')[-1] if '/' in property.name else property.name,
+            'name': property.display_name or 'N/A',
+            'type': property.property_type.name if property.property_type else 'N/A',
+            'timezone': property.time_zone or 'N/A',
+            'currency': property.currency_code or 'N/A',
+        })
+
+    logger.info(f"Found {len(properties_data)} properties")
+
+    if format == 'json':
+        format_json(properties_data)
+    else:
+        format_table(properties_data, title=f"Properties for Account {account_id}")
+
+
+@properties.command()
+@click.argument('property_id', callback=validate_property_id)
+@click.option('--format', type=click.Choice(['table', 'json']), default='table')
+@click.pass_context
+@with_client
+def get(ctx, property_id, format):
+    """Get property details"""
+    client = ctx.obj['client']
+    logger.info(f"Getting property details for: {property_id}")
+
+    property = _get_property_with_retry(client, property_id)
+
+    property_data = {
+        'id': property.name.split('/')[-1] if '/' in property.name else property.name,
+        'name': property.display_name or 'N/A',
+        'type': property.property_type.name if property.property_type else 'N/A',
+        'timezone': property.time_zone or 'N/A',
+        'currency': property.currency_code or 'N/A',
+        'industry': property.industry_category.name if property.industry_category else 'N/A',
+        'create_time': str(property.create_time).split('.')[0] if property.create_time else 'N/A',
+    }
+
+    logger.info(f"Retrieved property: {property.display_name}")
+
+    if format == 'json':
+        format_json(property_data)
+    else:
+        format_table([property_data], title=f"Property: {property.display_name}")
+
+
+@properties.command()
+@click.argument('account_id', callback=validate_account_id)
+@click.option('--name', required=True, help='Display name for the property')
+@click.option('--timezone', default='America/Los_Angeles', callback=validate_timezone,
+              help='Property timezone')
+@click.option('--currency', default='USD', callback=validate_currency,
+              help='Property currency code (e.g., USD, EUR)')
+@click.option('--industry', default='OTHER', help='Industry category')
+@click.pass_context
+@with_client
+def create(ctx, account_id, name, timezone, currency, industry):
+    """Create a new GA4 property"""
+    client = ctx.obj['client']
+    logger.info(f"Creating property '{name}' for account: {account_id}")
+
+    property = _create_property_with_retry(
+        client, account_id, name, timezone, currency, industry
+    )
+
+    property_id = property.name.split('/')[-1] if '/' in property.name else property.name
+    logger.info(f"Created property: {property_id}")
+
+    click.echo(f"Created property: {property.display_name}")
+    click.echo(f"  Property ID: {property_id}")
+    click.echo(f"  Timezone: {property.time_zone}")
+    click.echo(f"  Currency: {property.currency_code}")
+
+
+@properties.command()
+@click.argument('property_id', callback=validate_property_id)
+@click.confirmation_option(prompt='Are you sure you want to delete this property?')
+@click.pass_context
+@with_client
+def delete(ctx, property_id):
+    """Delete a property"""
+    client = ctx.obj['client']
+    logger.info(f"Deleting property: {property_id}")
+
+    _delete_property_with_retry(client, property_id)
+
+    logger.info(f"Deleted property: {property_id}")
+    click.echo(f"Property {property_id} deleted successfully")
+
+
+@retry_on_transient_error()
+def _list_properties_with_retry(client, request):
+    """List properties with retry logic"""
+    return list(client.list_properties(request=request))
+
+
+@retry_on_transient_error()
+def _get_property_with_retry(client, property_id):
+    """Get property with retry logic"""
+    return client.get_property(name=f"properties/{property_id}")
+
+
+@retry_on_transient_error()
+def _create_property_with_retry(client, account_id, name, timezone, currency, industry):
+    """Create property with retry logic"""
+    return client.create_property(
+        property=Property(
+            parent=f"accounts/{account_id}",
+            display_name=name,
+            time_zone=timezone,
+            currency_code=currency,
+            industry_category=industry,
+        )
+    )
+
+
+@retry_on_transient_error()
+def _delete_property_with_retry(client, property_id):
+    """Delete property with retry logic"""
+    return client.delete_property(name=f"properties/{property_id}")

ga_cli/config.py

@@ -0,0 +1,95 @@
+"""Configuration management for GA CLI"""
+
+import os
+import stat
+import configparser
+import click
+from pathlib import Path
+
+
+class ConfigManager:
+    """Manages CLI configuration"""
+
+    def __init__(self):
+        self.config_dir = Path.home() / '.ga-cli'
+        self.config_file = self.config_dir / 'config.ini'
+        self.config = configparser.ConfigParser()
+
+    def ensure_config_dir(self):
+        """Create config directory if it doesn't exist"""
+        self.config_dir.mkdir(exist_ok=True)
+        # Set restrictive permissions on config directory
+        os.chmod(self.config_dir, stat.S_IRWXU)  # 700
+
+    def load(self):
+        """Load configuration from file"""
+        if self.config_file.exists():
+            self.config.read(self.config_file)
+
+    def save(self):
+        """Save configuration to file"""
+        self.ensure_config_dir()
+        with open(self.config_file, 'w') as f:
+            self.config.write(f)
+        # Set restrictive permissions on config file
+        os.chmod(self.config_file, stat.S_IRUSR | stat.S_IWUSR)  # 600
+
+    def get_credentials_path(self):
+        """Get stored credentials path"""
+        self.load()
+        return self.config.get('auth', 'credentials_path', fallback=None)
+
+    def set_credentials_path(self, path):
+        """Store credentials path"""
+        # Validate credentials file before storing
+        if not self._validate_credentials_file(path):
+            raise click.ClickException("Invalid or insecure credentials file")
+
+        if 'auth' not in self.config:
+            self.config['auth'] = {}
+        self.config['auth']['credentials_path'] = path
+        self.save()
+
+    def _validate_credentials_file(self, path: str) -> bool:
+        """Validate credentials file exists and has secure permissions
+
+        Args:
+            path: Path to credentials file
+
+        Returns:
+            True if valid and secure, False otherwise
+        """
+        if not os.path.exists(path):
+            click.echo(f"Error: Credentials file not found: {path}", err=True)
+            return False
+
+        # Check not world-readable
+        st = os.stat(path)
+        if st.st_mode & (stat.S_IROTH | stat.S_IWOTH):
+            click.echo(
+                "Warning: Credentials file is world-readable. "
+                "Consider running: chmod 600 " + path,
+                err=True
+            )
+            # Don't fail, just warn
+
+        # Check ownership (Unix only)
+        if os.name != 'nt' and st.st_uid != os.getuid():
+            click.echo("Warning: Credentials file not owned by current user", err=True)
+            # Don't fail, just warn
+
+        return True
+
+    def get(self, section: str, key: str, fallback=None):
+        """Get a configuration value
+
+        Args:
+            section: Configuration section
+            key: Configuration key
+            fallback: Default value if not found
+
+        Returns:
+            Configuration value or fallback
+        """
+        self.load()
+        return self.config.get(section, key, fallback=fallback)

ga_cli/decorators.py

@@ -0,0 +1,90 @@
+"""Common decorators for CLI commands"""
+
+import functools
+import click
+from ga_cli.auth import AuthManager
+from ga_cli.logging_config import logger
+from ga_cli.errors import get_friendly_error
+from google.api_core import exceptions
+
+
+def with_client(func):
+    """Decorator to provide authenticated API client
+
+    This decorator:
+    - Retrieves credentials from context or config
+    - Creates an authenticated API client
+    - Handles common API exceptions with user-friendly messages
+    - Adds logging for all operations
+    - Injects client into context for use by command
+
+    Usage:
+        @accounts.command()
+        @click.pass_context
+        @with_client
+        def list(ctx):
+            client = ctx.obj['client']
+            # ... rest of logic
+    """
+    @functools.wraps(func)
+    def wrapper(ctx, *args, **kwargs):
+        try:
+            # Get credentials path
+            credentials_path = ctx.obj.get('credentials')
+            if not credentials_path:
+                from ga_cli.config import ConfigManager
+                config_manager = ConfigManager()
+                credentials_path = config_manager.get('credentials', 'path')
+
+            if not credentials_path:
+                logger.error("No credentials configured")
+                raise click.ClickException(
+                    "No credentials configured. Run 'ga-cli config init' first."
+                )
+
+            logger.debug(f"Using credentials: {credentials_path}")
+
+            # Create authenticated client
+            auth = AuthManager(credentials_path)
+            client = auth.get_client()
+
+            # Add client to context
+            ctx.obj['client'] = client
+
+            # Call the actual command
+            logger.info(f"Executing command: {func.__name__}")
+            return func(ctx, *args, **kwargs)
+
+        except exceptions.NotFound as e:
+            logger.error(f"Resource not found: {str(e)}")
+            click.echo(get_friendly_error(e), err=True)
+            raise click.Abort()
+        except exceptions.PermissionDenied as e:
+            logger.error(f"Permission denied: {str(e)}")
+            click.echo(get_friendly_error(e), err=True)
+            raise click.Abort()
+        except exceptions.Unauthenticated as e:
+            logger.error(f"Authentication failed: {str(e)}")
+            click.echo(get_friendly_error(e), err=True)
+            raise click.Abort()
+        except exceptions.InvalidArgument as e:
+            logger.error(f"Invalid argument: {str(e)}")
+            click.echo(get_friendly_error(e), err=True)
+            raise click.Abort()
+        except exceptions.ResourceExhausted as e:
+            logger.error(f"Rate limit exceeded: {str(e)}")
+            click.echo(get_friendly_error(e), err=True)
+            raise click.Abort()
+        except exceptions.GoogleAPIError as e:
+            logger.error(f"Google API error: {str(e)}")
+            click.echo(get_friendly_error(e), err=True)
+            raise click.Abort()
+        except click.ClickException:
+            # Re-raise Click exceptions as-is
+            raise
+        except Exception as e:
+            logger.exception("Unexpected error")
+            click.echo(f"Error: {str(e)}", err=True)
+            raise click.Abort()
+
+    return wrapper

ga_cli/errors.py

@@ -0,0 +1,35 @@
+"""User-friendly error messages for ga-cli"""
+
+from google.api_core import exceptions
+
+
+ERROR_MESSAGES = {
+    'not_found': 'Resource not found. Please check the ID and try again.',
+    'permission_denied': 'Permission denied. Ensure your service account has the required permissions.',
+    'invalid_argument': 'Invalid argument provided. Please check your input.',
+    'unauthenticated': 'Authentication failed. Run "ga-cli config init" to configure credentials.',
+    'resource_exhausted': 'Rate limit exceeded. Please wait a moment and try again.',
+    'internal': 'Internal server error. Please try again later.',
+    'unavailable': 'Service temporarily unavailable. Please try again later.',
+    'deadline_exceeded': 'Request timeout. Please try again.',
+}
+
+
+def get_friendly_error(exception):
+    """Map API exceptions to user-friendly messages"""
+    error_map = {
+        exceptions.NotFound: ERROR_MESSAGES['not_found'],
+        exceptions.PermissionDenied: ERROR_MESSAGES['permission_denied'],
+        exceptions.InvalidArgument: ERROR_MESSAGES['invalid_argument'],
+        exceptions.Unauthenticated: ERROR_MESSAGES['unauthenticated'],
+        exceptions.ResourceExhausted: ERROR_MESSAGES['resource_exhausted'],
+        exceptions.InternalServerError: ERROR_MESSAGES['internal'],
+        exceptions.ServiceUnavailable: ERROR_MESSAGES['unavailable'],
+        exceptions.DeadlineExceeded: ERROR_MESSAGES['deadline_exceeded'],
+    }
+
+    for exc_type, message in error_map.items():
+        if isinstance(exception, exc_type):
+            return message
+
+    return f"An error occurred: {str(exception)}"

ga_cli/formatters/json.py

@@ -0,0 +1,9 @@
+"""JSON formatter"""
+
+import json
+import click
+
+
+def format_json(data):
+    """Format data as JSON"""
+    click.echo(json.dumps(data, indent=2))

ga_cli/formatters/table.py

@@ -0,0 +1,23 @@
+"""Table formatter using Rich"""
+
+from rich.console import Console
+from rich.table import Table
+
+
+def format_table(data, title=None):
+    """Format list of dicts as a Rich table"""
+    console = Console()
+
+    if not data:
+        console.print("[yellow]No results found[/yellow]")
+        return
+
+    table = Table(show_header=True, header_style="bold magenta", title=title)
+
+    for key in data[0].keys():
+        table.add_column(key.replace('_', ' ').title())
+
+    for item in data:
+        table.add_row(*[str(v) for v in item.values()])
+
+    console.print(table)

ga_cli/logging_config.py

@@ -0,0 +1,44 @@
+"""Logging configuration for ga-cli"""
+
+import logging
+from pathlib import Path
+
+
+def setup_logging():
+    """Configure logging for ga-cli"""
+    log_dir = Path.home() / '.ga-cli'
+    log_dir.mkdir(exist_ok=True)
+
+    log_file = log_dir / 'ga-cli.log'
+
+    # Create logger
+    logger = logging.getLogger('ga_cli')
+    logger.setLevel(logging.INFO)
+
+    # Prevent duplicate handlers
+    if logger.handlers:
+        return logger
+
+    # File handler
+    fh = logging.FileHandler(log_file)
+    fh.setLevel(logging.DEBUG)
+
+    # Console handler (only WARNING and above)
+    ch = logging.StreamHandler()
+    ch.setLevel(logging.WARNING)
+
+    # Formatter
+    formatter = logging.Formatter(
+        '%(asctime)s - %(name)s - %(levelname)s - %(message)s'
+    )
+    fh.setFormatter(formatter)
+    ch.setFormatter(formatter)
+
+    logger.addHandler(fh)
+    logger.addHandler(ch)
+
+    return logger
+
+
+# Get logger singleton
+logger = setup_logging()

ga_cli/output.py

@@ -0,0 +1,59 @@
+"""Output helper functions for consistent formatting"""
+
+import click
+import json
+from rich.console import Console
+
+console = Console()
+
+
+def success_message(message: str, format_type: str = 'text'):
+    """Display success message
+
+    Args:
+        message: Success message to display
+        format_type: Output format ('text' or 'json')
+    """
+    if format_type == 'json':
+        click.echo(json.dumps({"success": True, "message": message}))
+    else:
+        console.print(f"[green]{message}[/green]")
+
+
+def error_message(message: str, format_type: str = 'text'):
+    """Display error message
+
+    Args:
+        message: Error message to display
+        format_type: Output format ('text' or 'json')
+    """
+    if format_type == 'json':
+        click.echo(json.dumps({"success": False, "error": message}))
+    else:
+        console.print(f"[red]{message}[/red]", err=True)
+
+
+def info_message(message: str, format_type: str = 'text'):
+    """Display info message
+
+    Args:
+        message: Info message to display
+        format_type: Output format ('text' or 'json')
+    """
+    if format_type == 'json':
+        click.echo(json.dumps({"info": message}))
+    else:
+        console.print(f"[blue]{message}[/blue]")
+
+
+def warning_message(message: str, format_type: str = 'text'):
+    """Display warning message
+
+    Args:
+        message: Warning message to display
+        format_type: Output format ('text' or 'json')
+    """
+    if format_type == 'json':
+        click.echo(json.dumps({"warning": message}))
+    else:
+        console.print(f"[yellow]{message}[/yellow]")