TimeTracker/app/utils/posthog_features.py

"""
PostHog Feature Flags and Advanced Features

This module provides utilities for using PostHog's advanced features:
- Feature flags (for A/B testing and gradual rollouts)
- Experiments
- Feature enablement checks
- Remote configuration
"""

import os
import posthog
from typing import Optional, Any, Dict
from functools import wraps
from flask import request


def is_posthog_enabled() -> bool:
    """Check if PostHog is enabled and configured"""
    return bool(os.getenv("POSTHOG_API_KEY", ""))


def get_feature_flag(user_id: Any, flag_key: str, default: bool = False) -> bool:
    """
    Check if a feature flag is enabled for a user.

    Args:
        user_id: The user ID (internal ID, not PII)
        flag_key: The feature flag key in PostHog
        default: Default value if PostHog is not configured

    Returns:
        True if feature is enabled, False otherwise
    """
    if not is_posthog_enabled():
        return default

    try:
        return posthog.feature_enabled(flag_key, str(user_id)) or default
    except Exception:
        return default


def get_feature_flag_payload(user_id: Any, flag_key: str) -> Optional[Dict[str, Any]]:
    """
    Get the payload for a feature flag (for remote configuration).

    Example usage:
        config = get_feature_flag_payload(user.id, "new-dashboard-config")
        if config:
            theme = config.get("theme", "light")
            features = config.get("features", [])

    Args:
        user_id: The user ID
        flag_key: The feature flag key

    Returns:
        Dict with payload data, or None if not available
    """
    if not is_posthog_enabled():
        return None

    try:
        return posthog.get_feature_flag_payload(flag_key, str(user_id))
    except Exception:
        return None


def get_all_feature_flags(user_id: Any) -> Dict[str, Any]:
    """
    Get all feature flags for a user.

    Returns a dictionary of flag_key -> enabled/disabled

    Args:
        user_id: The user ID

    Returns:
        Dict of feature flags
    """
    if not is_posthog_enabled():
        return {}

    try:
        return posthog.get_all_flags(str(user_id)) or {}
    except Exception:
        return {}


def feature_flag_required(flag_key: str, redirect_to: Optional[str] = None):
    """
    Decorator to require a feature flag for a route.

    Usage:
        @app.route('/beta-feature')
        @feature_flag_required('beta-features')
        def beta_feature():
            return "This is a beta feature!"

    Args:
        flag_key: The feature flag key to check
        redirect_to: URL to redirect to if flag is disabled (optional)
    """

    def decorator(f):
        @wraps(f)
        def decorated_function(*args, **kwargs):
            from flask_login import current_user
            from flask import abort, redirect, url_for

            if not current_user.is_authenticated:
                # Can't check feature flags for anonymous users
                if redirect_to:
                    return redirect(redirect_to)
                abort(403)

            if not get_feature_flag(current_user.id, flag_key):
                # Feature not enabled for this user
                if redirect_to:
                    return redirect(redirect_to)
                abort(403)

            return f(*args, **kwargs)

        return decorated_function

    return decorator


def get_active_experiments(user_id: Any) -> Dict[str, str]:
    """
    Get active experiments and their variants for a user.

    This can be used for A/B testing and tracking which
    variants users are seeing.

    Args:
        user_id: The user ID

    Returns:
        Dict of experiment_key -> variant
    """
    flags = get_all_feature_flags(user_id)

    # Filter for experiments (flags that have variants)
    experiments = {}
    for flag_key, value in flags.items():
        if isinstance(value, str) and value not in ["true", "false"]:
            # This is likely a multivariate flag (experiment)
            experiments[flag_key] = value

    return experiments


def inject_feature_flags_to_frontend(user_id: Any) -> Dict[str, Any]:
    """
    Get feature flags formatted for frontend injection.

    This can be used to inject feature flags into JavaScript
    for frontend feature toggling.

    Usage in template:
        <script>
            window.featureFlags = {{ feature_flags|tojson }};
        </script>

    Args:
        user_id: The user ID

    Returns:
        Dict of feature flags safe for frontend use
    """
    if not is_posthog_enabled():
        return {}

    try:
        flags = get_all_feature_flags(user_id)
        # Convert to boolean values for frontend
        return {key: bool(value) for key, value in flags.items()}
    except Exception:
        return {}


def override_feature_flag(user_id: Any, flag_key: str, value: bool):
    """
    Override a feature flag for testing purposes.

    Note: This only works in development/testing environments.

    Args:
        user_id: The user ID
        flag_key: The feature flag key
        value: The value to set
    """
    if os.getenv("FLASK_ENV") not in ["development", "testing"]:
        # Only allow overrides in dev/test
        return

    try:
        # Store override in session or cache
        # This is a placeholder - implement based on your needs
        pass
    except Exception:
        pass


def track_feature_flag_interaction(user_id: Any, flag_key: str, action: str, properties: Optional[Dict] = None):
    """
    Track when users interact with features controlled by feature flags.

    This helps measure the impact of features and experiments.

    Args:
        user_id: The user ID
        flag_key: The feature flag key
        action: The action taken (e.g., "clicked", "viewed", "completed")
        properties: Additional properties to track
    """
    from app import track_event

    event_properties = {"feature_flag": flag_key, "action": action, **(properties or {})}

    track_event(user_id, "feature_interaction", event_properties)


# Predefined feature flags for common use cases
class FeatureFlags:
    """
    Centralized feature flag keys for the application.

    Define your feature flags here to avoid typos and enable autocomplete.
    """

    # Beta features
    BETA_FEATURES = "beta-features"
    NEW_DASHBOARD = "new-dashboard"
    ADVANCED_REPORTS = "advanced-reports"

    # Experiments
    TIMER_UI_EXPERIMENT = "timer-ui-experiment"
    ONBOARDING_FLOW = "onboarding-flow"

    # Rollout features
    NEW_ANALYTICS_PAGE = "new-analytics-page"
    BULK_OPERATIONS = "bulk-operations"

    # Kill switches (for emergency feature disabling)
    ENABLE_EXPORTS = "enable-exports"
    ENABLE_API = "enable-api"
    ENABLE_WEBSOCKETS = "enable-websockets"

    # Premium features (if you have paid tiers)
    CUSTOM_REPORTS = "custom-reports"
    API_ACCESS = "api-access"
    INTEGRATIONS = "integrations"


# Example usage helper
def is_feature_enabled_for_request(flag_key: str, default: bool = False) -> bool:
    """
    Check if a feature is enabled for the current request's user.

    Convenience function for use in templates and view functions.

    Args:
        flag_key: The feature flag key
        default: Default value if user not authenticated

    Returns:
        True if feature is enabled
    """
    from flask_login import current_user

    if not current_user.is_authenticated:
        return default

    return get_feature_flag(current_user.id, flag_key, default)