dubs-server 1.0.0

package/routes/analyticsRoutes.js

@@ -0,0 +1,1262 @@
+/**
+ * Analytics Routes
+ * 
+ * Receives analytics events from the frontend and stores them in PostgreSQL.
+ * Uses the audit_logs table with enhanced structure for analytics queries.
+ */
+
+const express = require('express');
+const router = express.Router();
+const { pool } = require('../services/db'); // Shared database pool
+
+/**
+ * POST /api/analytics/events
+ * 
+ * Receive batch of analytics events from frontend
+ * Public endpoint - no auth required (events include user context)
+ */
+router.post('/events', async (req, res) => {
+  try {
+    const { events } = req.body;
+
+    if (!events || !Array.isArray(events) || events.length === 0) {
+      return res.status(400).json({ 
+        success: false, 
+        error: 'Events array is required' 
+      });
+    }
+
+    // Limit batch size to prevent abuse
+    if (events.length > 50) {
+      return res.status(400).json({ 
+        success: false, 
+        error: 'Maximum 50 events per batch' 
+      });
+    }
+
+    
+    // Insert all events in a single transaction
+    const client = await pool.connect();
+    
+    try {
+      await client.query('BEGIN');
+
+      const insertPromises = events.map(event => {
+        const {
+          eventName,
+          eventCategory,
+          userId,
+          properties,
+          context,
+          clientTimestamp,
+          funnelId,
+          funnelStep,
+        } = event;
+
+        // Build metadata object combining properties and context
+        const metadata = {
+          ...properties,
+          context: context || {},
+          funnelId,
+          funnelStep,
+          clientTimestamp,
+        };
+
+        return client.query(
+          `INSERT INTO audit_logs (log_type, method, user_id, metadata, created_at)
+           VALUES ($1, $2, $3, $4, NOW())`,
+          [
+            eventName,           // log_type = event name
+            eventCategory,       // method = category
+            userId || null,      // user_id = wallet address
+            JSON.stringify(metadata),
+          ]
+        );
+      });
+
+      await Promise.all(insertPromises);
+      await client.query('COMMIT');
+
+      console.log(`[Analytics] Stored ${events.length} events`);
+
+      return res.json({ 
+        success: true, 
+        stored: events.length 
+      });
+
+    } catch (insertError) {
+      await client.query('ROLLBACK');
+      throw insertError;
+    } finally {
+      client.release();
+    }
+
+  } catch (error) {
+    console.error('[Analytics] Error storing events:', error);
+    return res.status(500).json({ 
+      success: false, 
+      error: 'Failed to store events' 
+    });
+  }
+});
+
+/**
+ * GET /api/analytics/events
+ * 
+ * Query events for dashboard/analysis (protected - future admin use)
+ */
+router.get('/events', async (req, res) => {
+  try {
+    
+    const {
+      eventName,
+      category,
+      userId,
+      startDate,
+      endDate,
+      limit = 100,
+      offset = 0,
+    } = req.query;
+
+    let query = 'SELECT * FROM audit_logs WHERE 1=1';
+    const params = [];
+    let paramIndex = 1;
+
+    if (eventName) {
+      query += ` AND log_type = $${paramIndex++}`;
+      params.push(eventName);
+    }
+
+    if (category) {
+      query += ` AND method = $${paramIndex++}`;
+      params.push(category);
+    }
+
+    if (userId) {
+      query += ` AND user_id = $${paramIndex++}`;
+      params.push(userId);
+    }
+
+    if (startDate) {
+      query += ` AND created_at >= $${paramIndex++}`;
+      params.push(startDate);
+    }
+
+    if (endDate) {
+      query += ` AND created_at <= $${paramIndex++}`;
+      params.push(endDate);
+    }
+
+    query += ` ORDER BY created_at DESC`;
+    query += ` LIMIT $${paramIndex++} OFFSET $${paramIndex++}`;
+    params.push(Math.min(parseInt(limit), 1000), parseInt(offset) || 0);
+
+    const result = await pool.query(query, params);
+
+    return res.json({
+      success: true,
+      events: result.rows,
+      count: result.rows.length,
+    });
+
+  } catch (error) {
+    console.error('[Analytics] Error querying events:', error);
+    return res.status(500).json({ 
+      success: false, 
+      error: 'Failed to query events' 
+    });
+  }
+});
+
+/**
+ * GET /api/analytics/funnel/:funnelId
+ * 
+ * Get funnel conversion data with step context
+ */
+router.get('/funnel/:funnelId', async (req, res) => {
+  try {
+    const { funnelId } = req.params;
+    const { startDate, endDate } = req.query;
+
+    // Default to last 7 days
+    const start = startDate || new Date(Date.now() - 7 * 24 * 60 * 60 * 1000).toISOString();
+    const end = endDate || new Date().toISOString();
+
+    // Get events for this funnel with context from metadata
+    // For tutorial_step_completed, we group by stepIndex to get each step separately
+    // Use COALESCE for user_id to handle anonymous users (null user_id) by using session_id from context
+    const result = await pool.query(
+      `SELECT 
+         log_type as event_name,
+         metadata->>'funnelStep' as funnel_step,
+         COALESCE(metadata->>'stepTitle', metadata->>'stepIndex', '') as step_context,
+         COALESCE((metadata->>'stepIndex')::int, 0) as step_order,
+         COUNT(DISTINCT COALESCE(user_id, metadata->'context'->>'sessionId', id::text)) as unique_users,
+         COUNT(*) as total_events
+       FROM audit_logs 
+       WHERE metadata->>'funnelId' = $1
+         AND created_at >= $2 
+         AND created_at <= $3
+       GROUP BY log_type, metadata->>'funnelStep', 
+                COALESCE(metadata->>'stepTitle', metadata->>'stepIndex', ''),
+                COALESCE((metadata->>'stepIndex')::int, 0)
+       ORDER BY MIN(created_at), step_order`,
+      [funnelId, start, end]
+    );
+    
+    console.log(`[Analytics] Funnel ${funnelId}: found ${result.rows.length} steps`);
+
+    // Post-process to create meaningful labels
+    const processedSteps = result.rows.map(row => {
+      let displayName = row.event_name;
+
+      // Add context for tutorial steps
+      if (row.event_name === 'tutorial_step_viewed' && row.step_context) {
+        displayName = `Tutorial: ${row.step_context}`;
+      } else if (row.event_name === 'tutorial_skipped' && row.step_context) {
+        displayName = `Tutorial Skipped at: ${row.step_context}`;
+      } else if (row.event_name === 'tutorial_started') {
+        displayName = 'Tutorial Started';
+      } else if (row.event_name === 'tutorial_completed') {
+        displayName = 'Tutorial Completed';
+      } else if (row.event_name === 'onboarding_currency_selected' && row.step_context) {
+        displayName = `Currency: ${row.step_context}`;
+      }
+      // Seeker onboarding event display names
+      else if (row.event_name === 'welcome_shown') {
+        displayName = '📱 Welcome Shown';
+      } else if (row.event_name === 'cat_tapped') {
+        displayName = '🐱 Cat Tapped';
+      } else if (row.event_name === 'tutorial_started' && funnelId === 'seeker_onboarding') {
+        displayName = '🚀 Tutorial Started';
+      } else if (row.event_name === 'category_selected') {
+        displayName = '🎯 Category Selected';
+      } else if (row.event_name === 'sport_selected') {
+        displayName = '⚽ Sport Selected';
+      } else if (row.event_name === 'game_type_selected') {
+        displayName = '🎮 Game Selected';
+      } else if (row.event_name === 'sports_event_selected') {
+        displayName = '🏟️ Match Selected';
+      } else if (row.event_name === 'team_selected') {
+        displayName = '👥 Team Selected';
+      } else if (row.event_name === 'bet_amount_selected') {
+        displayName = '💰 Bet Amount Set';
+      } else if (row.event_name === 'share_link_clicked') {
+        displayName = '🔗 Share Link Clicked';
+      } else if (row.event_name === 'step_completed') {
+        displayName = '✅ Step Completed';
+      } else if (row.event_name === 'back_clicked') {
+        displayName = '⬅️ Back Clicked';
+      } else if (row.event_name === 'tutorial_completed' && funnelId === 'seeker_onboarding') {
+        displayName = '🎉 Tutorial Completed';
+      } else if (row.event_name === 'connect4_started') {
+        displayName = '🎮 Connect4 Started';
+      } else if (row.event_name === 'connect4_move') {
+        displayName = '🔵 Connect4 Move';
+      } else if (row.event_name === 'connect4_won') {
+        displayName = '🏆 Connect4 Won';
+      } else if (row.event_name === 'wallet_connected') {
+        displayName = '💳 Wallet Connected';
+      }
+
+      return {
+        ...row,
+        display_name: displayName,
+      };
+    });
+
+    return res.json({
+      success: true,
+      funnelId,
+      steps: processedSteps,
+      dateRange: { start, end },
+    });
+
+  } catch (error) {
+    console.error('[Analytics] Error getting funnel:', error);
+    return res.status(500).json({ 
+      success: false, 
+      error: 'Failed to get funnel data' 
+    });
+  }
+});
+
+/**
+ * GET /api/analytics/summary
+ * 
+ * Get high-level analytics summary
+ */
+router.get('/summary', async (req, res) => {
+  try {
+    const { days = 7 } = req.query;
+
+    const startDate = new Date(Date.now() - parseInt(days) * 24 * 60 * 60 * 1000).toISOString();
+
+    // Get summary stats
+    const [totalEvents, uniqueUsers, eventsByCategory, eventsByName] = await Promise.all([
+      // Total events
+      pool.query(
+        'SELECT COUNT(*) as count FROM audit_logs WHERE created_at >= $1',
+        [startDate]
+      ),
+      // Unique users
+      pool.query(
+        'SELECT COUNT(DISTINCT user_id) as count FROM audit_logs WHERE created_at >= $1 AND user_id IS NOT NULL',
+        [startDate]
+      ),
+      // Events by category
+      pool.query(
+        `SELECT method as category, COUNT(*) as count 
+         FROM audit_logs 
+         WHERE created_at >= $1 
+         GROUP BY method 
+         ORDER BY count DESC`,
+        [startDate]
+      ),
+      // Top events by name
+      pool.query(
+        `SELECT log_type as event_name, COUNT(*) as count 
+         FROM audit_logs 
+         WHERE created_at >= $1 
+         GROUP BY log_type 
+         ORDER BY count DESC 
+         LIMIT 20`,
+        [startDate]
+      ),
+    ]);
+
+    return res.json({
+      success: true,
+      summary: {
+        period: `Last ${days} days`,
+        totalEvents: parseInt(totalEvents.rows[0].count),
+        uniqueUsers: parseInt(uniqueUsers.rows[0].count),
+        byCategory: eventsByCategory.rows,
+        topEvents: eventsByName.rows,
+      },
+    });
+
+  } catch (error) {
+    console.error('[Analytics] Error getting summary:', error);
+    return res.status(500).json({ 
+      success: false, 
+      error: 'Failed to get summary' 
+    });
+  }
+});
+
+/**
+ * GET /api/analytics/daily
+ * 
+ * Get daily event counts
+ */
+router.get('/daily', async (req, res) => {
+  try {
+    const { days = 30, eventName, category } = req.query;
+
+    let query = `
+      SELECT 
+        DATE(created_at) as date,
+        COUNT(*) as total_events,
+        COUNT(DISTINCT user_id) as unique_users
+      FROM audit_logs 
+      WHERE created_at >= NOW() - INTERVAL '${parseInt(days)} days'
+    `;
+
+    const params = [];
+    let paramIndex = 1;
+
+    if (eventName) {
+      query += ` AND log_type = $${paramIndex++}`;
+      params.push(eventName);
+    }
+
+    if (category) {
+      query += ` AND method = $${paramIndex++}`;
+      params.push(category);
+    }
+
+    query += ` GROUP BY DATE(created_at) ORDER BY date DESC`;
+
+    const result = await pool.query(query, params);
+
+    return res.json({
+      success: true,
+      daily: result.rows,
+    });
+
+  } catch (error) {
+    console.error('[Analytics] Error getting daily stats:', error);
+    return res.status(500).json({ 
+      success: false, 
+      error: 'Failed to get daily stats' 
+    });
+  }
+});
+
+/**
+ * GET /api/analytics/chat-social
+ * 
+ * Get chat social features stats (@, #, $)
+ */
+router.get('/chat-social', async (req, res) => {
+  try {
+    const { days = 7 } = req.query;
+    const startDate = new Date(Date.now() - parseInt(days) * 24 * 60 * 60 * 1000).toISOString();
+
+    // Define all chat social event types
+    const chatEvents = [
+      'chat_mention_dropdown_opened',
+      'chat_mention_selected',
+      'chat_animation_dropdown_opened',
+      'chat_animation_selected',
+      'chat_message_with_features',
+      'chat_payment_initiated',
+      'chat_payment_completed',
+      'chat_payment_failed',
+      'chat_payment_cancelled',
+    ];
+
+    // Get counts for each event type
+    const result = await pool.query(
+      `SELECT 
+         log_type as event_name,
+         COUNT(*) as total_events,
+         COUNT(DISTINCT COALESCE(user_id, metadata->'context'->>'sessionId', id::text)) as unique_users
+       FROM audit_logs 
+       WHERE log_type = ANY($1)
+         AND created_at >= $2
+       GROUP BY log_type`,
+      [chatEvents, startDate]
+    );
+
+    // Build structured response
+    const eventCounts = {};
+    result.rows.forEach(row => {
+      eventCounts[row.event_name] = {
+        total: parseInt(row.total_events),
+        unique: parseInt(row.unique_users),
+      };
+    });
+
+    const stats = {
+      mentions: {
+        dropdownOpened: eventCounts['chat_mention_dropdown_opened']?.total || 0,
+        selected: eventCounts['chat_mention_selected']?.total || 0,
+      },
+      animations: {
+        dropdownOpened: eventCounts['chat_animation_dropdown_opened']?.total || 0,
+        selected: eventCounts['chat_animation_selected']?.total || 0,
+      },
+      payments: {
+        initiated: eventCounts['chat_payment_initiated']?.total || 0,
+        completed: eventCounts['chat_payment_completed']?.total || 0,
+        failed: eventCounts['chat_payment_failed']?.total || 0,
+        cancelled: eventCounts['chat_payment_cancelled']?.total || 0,
+      },
+      messagesWithFeatures: eventCounts['chat_message_with_features']?.total || 0,
+    };
+
+    console.log('[Analytics] Chat social stats:', stats);
+
+    return res.json({
+      success: true,
+      stats,
+      raw: result.rows,
+      period: `Last ${days} days`,
+    });
+
+  } catch (error) {
+    console.error('[Analytics] Error getting chat social stats:', error);
+    return res.status(500).json({ 
+      success: false, 
+      error: 'Failed to get chat social stats' 
+    });
+  }
+});
+
+/**
+ * GET /api/analytics/sol-volume
+ * 
+ * High-performance endpoint to calculate SOL flowing through the system
+ * Derived from games database - no blockchain queries needed
+ */
+router.get('/sol-volume', async (req, res) => {
+  try {
+    const { days = 7 } = req.query;
+    let daysInt = parseInt(days);
+    
+    // Cap days to prevent invalid dates (max ~10 years, or use 'all time' mode)
+    const isAllTime = daysInt > 3650;
+    if (isAllTime) {
+      daysInt = 3650; // 10 years max for comparison period
+    }
+    
+    // Current period
+    const currentEnd = new Date();
+    // For "all time", use epoch start; otherwise calculate from days
+    const currentStart = isAllTime 
+      ? new Date('2020-01-01T00:00:00.000Z') // Platform launch date (adjust as needed)
+      : new Date(Date.now() - daysInt * 24 * 60 * 60 * 1000);
+    
+    // Previous period for comparison (only meaningful for non-all-time queries)
+    const prevEnd = currentStart;
+    const prevStart = isAllTime
+      ? new Date('2019-01-01T00:00:00.000Z') // Year before platform launch
+      : new Date(Date.now() - 2 * daysInt * 24 * 60 * 60 * 1000);
+
+    // Fee constants
+    const PLATFORM_FEE_PERCENT = 0.01; // 1%
+    const ORACLE_FEE_PERCENT = 0.002;  // 0.2%
+    const TOTAL_FEE_PERCENT = PLATFORM_FEE_PERCENT + ORACLE_FEE_PERCENT;
+
+    // Query for current period - calculate everything in a single optimized query
+    const currentStatsQuery = `
+      SELECT 
+        COUNT(*) as total_games,
+        COUNT(CASE WHEN is_resolved = true THEN 1 END) as resolved_games,
+        COUNT(CASE WHEN is_locked = true AND is_resolved = false THEN 1 END) as locked_games,
+        COUNT(CASE WHEN is_locked = false AND is_resolved = false THEN 1 END) as pending_games,
+        COALESCE(SUM(buy_in), 0) as total_buy_ins,
+        COALESCE(SUM(
+          buy_in * (
+            COALESCE(array_length(home_team_players, 1), 0) + 
+            COALESCE(array_length(away_team_players, 1), 0)
+          )
+        ), 0) as total_wagered,
+        COALESCE(SUM(
+          COALESCE(array_length(home_team_players, 1), 0) + 
+          COALESCE(array_length(away_team_players, 1), 0)
+        ), 0) as total_players,
+        COALESCE(AVG(buy_in), 0) as avg_buy_in,
+        COALESCE(AVG(
+          COALESCE(array_length(home_team_players, 1), 0) + 
+          COALESCE(array_length(away_team_players, 1), 0)
+        ), 0) as avg_players_per_game,
+        COUNT(DISTINCT created_by) as unique_creators
+      FROM games 
+      WHERE created_at >= $1 AND created_at < $2
+    `;
+
+    // Query for previous period
+    const prevStatsQuery = `
+      SELECT 
+        COUNT(*) as total_games,
+        COALESCE(SUM(
+          buy_in * (
+            COALESCE(array_length(home_team_players, 1), 0) + 
+            COALESCE(array_length(away_team_players, 1), 0)
+          )
+        ), 0) as total_wagered,
+        COALESCE(SUM(
+          COALESCE(array_length(home_team_players, 1), 0) + 
+          COALESCE(array_length(away_team_players, 1), 0)
+        ), 0) as total_players
+      FROM games 
+      WHERE created_at >= $1 AND created_at < $2
+    `;
+
+    // Query for buy-in distribution (for chart)
+    const buyInDistributionQuery = `
+      SELECT 
+        CASE 
+          WHEN buy_in <= 0.05 THEN '0.01-0.05'
+          WHEN buy_in <= 0.1 THEN '0.05-0.1'
+          WHEN buy_in <= 0.5 THEN '0.1-0.5'
+          WHEN buy_in <= 1 THEN '0.5-1'
+          ELSE '1+'
+        END as range,
+        COUNT(*) as count,
+        COALESCE(SUM(
+          buy_in * (
+            COALESCE(array_length(home_team_players, 1), 0) + 
+            COALESCE(array_length(away_team_players, 1), 0)
+          )
+        ), 0) as volume
+      FROM games 
+      WHERE created_at >= $1 AND created_at < $2
+      GROUP BY 
+        CASE 
+          WHEN buy_in <= 0.05 THEN '0.01-0.05'
+          WHEN buy_in <= 0.1 THEN '0.05-0.1'
+          WHEN buy_in <= 0.5 THEN '0.1-0.5'
+          WHEN buy_in <= 1 THEN '0.5-1'
+          ELSE '1+'
+        END
+      ORDER BY MIN(buy_in)
+    `;
+
+    // Query for daily volume (for sparkline)
+    const dailyVolumeQuery = `
+      SELECT 
+        DATE(created_at) as date,
+        COUNT(*) as games,
+        COALESCE(SUM(
+          buy_in * (
+            COALESCE(array_length(home_team_players, 1), 0) + 
+            COALESCE(array_length(away_team_players, 1), 0)
+          )
+        ), 0) as volume
+      FROM games 
+      WHERE created_at >= $1 AND created_at < $2
+      GROUP BY DATE(created_at)
+      ORDER BY date
+    `;
+
+    // Execute all queries in parallel
+    const [currentStats, prevStats, buyInDist, dailyVolume] = await Promise.all([
+      pool.query(currentStatsQuery, [currentStart.toISOString(), currentEnd.toISOString()]),
+      pool.query(prevStatsQuery, [prevStart.toISOString(), prevEnd.toISOString()]),
+      pool.query(buyInDistributionQuery, [currentStart.toISOString(), currentEnd.toISOString()]),
+      pool.query(dailyVolumeQuery, [currentStart.toISOString(), currentEnd.toISOString()]),
+    ]);
+
+    const current = currentStats.rows[0];
+    const prev = prevStats.rows[0];
+
+    // Calculate derived metrics
+    const totalWagered = parseFloat(current.total_wagered) || 0;
+    const prevTotalWagered = parseFloat(prev.total_wagered) || 0;
+    const platformFees = totalWagered * PLATFORM_FEE_PERCENT;
+    const oracleFees = totalWagered * ORACLE_FEE_PERCENT;
+    const totalFees = totalWagered * TOTAL_FEE_PERCENT;
+    const netToPlayers = totalWagered - totalFees;
+
+    // Calculate percentage changes
+    const calculateChange = (current, previous) => {
+      if (previous === 0) return current > 0 ? 100 : null;
+      return Math.round(((current - previous) / previous) * 100);
+    };
+
+    const response = {
+      success: true,
+      period: {
+        days: daysInt,
+        start: currentStart.toISOString(),
+        end: currentEnd.toISOString(),
+      },
+      volume: {
+        totalWagered: parseFloat(totalWagered.toFixed(4)),
+        platformFees: parseFloat(platformFees.toFixed(4)),
+        oracleFees: parseFloat(oracleFees.toFixed(4)),
+        totalFees: parseFloat(totalFees.toFixed(4)),
+        netToPlayers: parseFloat(netToPlayers.toFixed(4)),
+      },
+      games: {
+        total: parseInt(current.total_games) || 0,
+        resolved: parseInt(current.resolved_games) || 0,
+        locked: parseInt(current.locked_games) || 0,
+        pending: parseInt(current.pending_games) || 0,
+      },
+      players: {
+        total: parseInt(current.total_players) || 0,
+        uniqueCreators: parseInt(current.unique_creators) || 0,
+        avgPerGame: parseFloat(parseFloat(current.avg_players_per_game).toFixed(1)) || 0,
+      },
+      averages: {
+        buyIn: parseFloat(parseFloat(current.avg_buy_in).toFixed(4)) || 0,
+        potSize: parseInt(current.total_games) > 0 
+          ? parseFloat((totalWagered / parseInt(current.total_games)).toFixed(4)) 
+          : 0,
+      },
+      comparison: {
+        volumeChange: calculateChange(totalWagered, prevTotalWagered),
+        gamesChange: calculateChange(parseInt(current.total_games), parseInt(prev.total_games)),
+        playersChange: calculateChange(parseInt(current.total_players), parseInt(prev.total_players)),
+        previousVolume: parseFloat(prevTotalWagered.toFixed(4)),
+      },
+      distribution: buyInDist.rows.map(row => ({
+        range: row.range,
+        count: parseInt(row.count),
+        volume: parseFloat(parseFloat(row.volume).toFixed(4)),
+      })),
+      daily: dailyVolume.rows.map(row => ({
+        date: row.date,
+        games: parseInt(row.games),
+        volume: parseFloat(parseFloat(row.volume).toFixed(4)),
+      })),
+      feeRates: {
+        platform: PLATFORM_FEE_PERCENT * 100,
+        oracle: ORACLE_FEE_PERCENT * 100,
+        total: TOTAL_FEE_PERCENT * 100,
+      },
+    };
+
+    console.log('[Analytics] SOL Volume:', {
+      totalWagered: response.volume.totalWagered,
+      games: response.games.total,
+      players: response.players.total,
+    });
+
+    return res.json(response);
+
+  } catch (error) {
+    console.error('[Analytics] Error getting SOL volume:', error);
+    return res.status(500).json({ 
+      success: false, 
+      error: 'Failed to get SOL volume data' 
+    });
+  }
+});
+
+/**
+ * GET /api/analytics/phantom-warning
+ * 
+ * Get Phantom wallet warning stats
+ */
+router.get('/phantom-warning', async (req, res) => {
+  try {
+    const { days = 7 } = req.query;
+    const startDate = new Date(Date.now() - parseInt(days) * 24 * 60 * 60 * 1000).toISOString();
+
+    // Define Phantom warning event types
+    const phantomEvents = [
+      'phantom_warning_shown',
+      'phantom_warning_acknowledged',
+      'phantom_warning_cancelled',
+    ];
+
+    // Get counts for each event type
+    const result = await pool.query(
+      `SELECT 
+         log_type as event_name,
+         COUNT(*) as total_events,
+         COUNT(DISTINCT COALESCE(user_id, metadata->'context'->>'sessionId', id::text)) as unique_users
+       FROM audit_logs 
+       WHERE log_type = ANY($1)
+         AND created_at >= $2
+       GROUP BY log_type`,
+      [phantomEvents, startDate]
+    );
+
+    // Build structured response
+    const eventCounts = {};
+    result.rows.forEach(row => {
+      eventCounts[row.event_name] = {
+        total: parseInt(row.total_events),
+        unique: parseInt(row.unique_users),
+      };
+    });
+
+    const stats = {
+      shown: eventCounts['phantom_warning_shown']?.total || 0,
+      acknowledged: eventCounts['phantom_warning_acknowledged']?.total || 0,
+      cancelled: eventCounts['phantom_warning_cancelled']?.total || 0,
+    };
+
+    console.log('[Analytics] Phantom warning stats:', stats);
+
+    return res.json({
+      success: true,
+      stats,
+      raw: result.rows,
+      period: `Last ${days} days`,
+    });
+
+  } catch (error) {
+    console.error('[Analytics] Error getting phantom warning stats:', error);
+    return res.status(500).json({ 
+      success: false, 
+      error: 'Failed to get phantom warning stats' 
+    });
+  }
+});
+
+/**
+ * GET /api/analytics/comparison
+ * 
+ * Get comparison data between current period and previous period
+ * for all funnels to show change percentages
+ */
+router.get('/comparison', async (req, res) => {
+  try {
+    const { days = 7 } = req.query;
+    const daysInt = parseInt(days);
+    
+    // Current period: now - days ago
+    const currentEnd = new Date();
+    const currentStart = new Date(Date.now() - daysInt * 24 * 60 * 60 * 1000);
+    
+    // Previous period: days ago - 2*days ago
+    const prevEnd = currentStart;
+    const prevStart = new Date(Date.now() - 2 * daysInt * 24 * 60 * 60 * 1000);
+
+    // Define funnel IDs to track
+    const funnelIds = ['bet_creation', 'game_join', 'chat_social', 'social', 'user_onboarding', 'registration', 'invitation_flow'];
+    
+    // Chat social events
+    const chatEvents = [
+      'chat_mention_dropdown_opened', 'chat_mention_selected',
+      'chat_animation_dropdown_opened', 'chat_animation_selected',
+      'chat_payment_initiated', 'chat_payment_completed',
+    ];
+    
+    // Social events
+    const socialEvents = [
+      'social_page_viewed', 'social_search_performed',
+      'friend_request_sent', 'friend_request_accepted', 'friend_request_declined',
+      'friend_removed', 'social_user_profile_viewed',
+    ];
+
+    // Get funnel totals for current and previous periods
+    const [currentFunnels, prevFunnels, currentChat, prevChat, currentSocial, prevSocial] = await Promise.all([
+      // Current period funnel totals
+      pool.query(
+        `SELECT 
+           metadata->>'funnelId' as funnel_id,
+           COUNT(*) as total_events
+         FROM audit_logs 
+         WHERE metadata->>'funnelId' = ANY($1)
+           AND created_at >= $2 AND created_at < $3
+         GROUP BY metadata->>'funnelId'`,
+        [funnelIds, currentStart.toISOString(), currentEnd.toISOString()]
+      ),
+      // Previous period funnel totals
+      pool.query(
+        `SELECT 
+           metadata->>'funnelId' as funnel_id,
+           COUNT(*) as total_events
+         FROM audit_logs 
+         WHERE metadata->>'funnelId' = ANY($1)
+           AND created_at >= $2 AND created_at < $3
+         GROUP BY metadata->>'funnelId'`,
+        [funnelIds, prevStart.toISOString(), prevEnd.toISOString()]
+      ),
+      // Current period chat social
+      pool.query(
+        `SELECT COUNT(*) as total FROM audit_logs 
+         WHERE log_type = ANY($1) AND created_at >= $2 AND created_at < $3`,
+        [chatEvents, currentStart.toISOString(), currentEnd.toISOString()]
+      ),
+      // Previous period chat social
+      pool.query(
+        `SELECT COUNT(*) as total FROM audit_logs 
+         WHERE log_type = ANY($1) AND created_at >= $2 AND created_at < $3`,
+        [chatEvents, prevStart.toISOString(), prevEnd.toISOString()]
+      ),
+      // Current period social page
+      pool.query(
+        `SELECT COUNT(*) as total FROM audit_logs 
+         WHERE log_type = ANY($1) AND created_at >= $2 AND created_at < $3`,
+        [socialEvents, currentStart.toISOString(), currentEnd.toISOString()]
+      ),
+      // Previous period social page
+      pool.query(
+        `SELECT COUNT(*) as total FROM audit_logs 
+         WHERE log_type = ANY($1) AND created_at >= $2 AND created_at < $3`,
+        [socialEvents, prevStart.toISOString(), prevEnd.toISOString()]
+      ),
+    ]);
+
+    // Build comparison object
+    const currentFunnelMap = {};
+    currentFunnels.rows.forEach(row => {
+      currentFunnelMap[row.funnel_id] = parseInt(row.total_events);
+    });
+    
+    const prevFunnelMap = {};
+    prevFunnels.rows.forEach(row => {
+      prevFunnelMap[row.funnel_id] = parseInt(row.total_events);
+    });
+
+    const comparison = {
+      betCreation: {
+        current: currentFunnelMap['bet_creation'] || 0,
+        previous: prevFunnelMap['bet_creation'] || 0,
+      },
+      gameJoin: {
+        current: currentFunnelMap['game_join'] || 0,
+        previous: prevFunnelMap['game_join'] || 0,
+      },
+      chatSocial: {
+        current: parseInt(currentChat.rows[0]?.total) || 0,
+        previous: parseInt(prevChat.rows[0]?.total) || 0,
+      },
+      social: {
+        current: parseInt(currentSocial.rows[0]?.total) || 0,
+        previous: parseInt(prevSocial.rows[0]?.total) || 0,
+      },
+      onboarding: {
+        current: currentFunnelMap['user_onboarding'] || 0,
+        previous: prevFunnelMap['user_onboarding'] || 0,
+      },
+      registration: {
+        current: currentFunnelMap['registration'] || 0,
+        previous: prevFunnelMap['registration'] || 0,
+      },
+      invitationFlow: {
+        current: currentFunnelMap['invitation_flow'] || 0,
+        previous: prevFunnelMap['invitation_flow'] || 0,
+      },
+    };
+
+    console.log('[Analytics] Comparison data:', comparison);
+
+    return res.json({
+      success: true,
+      comparison,
+      periods: {
+        current: { start: currentStart.toISOString(), end: currentEnd.toISOString() },
+        previous: { start: prevStart.toISOString(), end: prevEnd.toISOString() },
+      },
+    });
+
+  } catch (error) {
+    console.error('[Analytics] Error getting comparison:', error);
+    return res.status(500).json({ 
+      success: false, 
+      error: 'Failed to get comparison data' 
+    });
+  }
+});
+
+/**
+ * GET /api/analytics/cohort-retention
+ * 
+ * Get cohort retention analysis showing user retention over time
+ * grouped by signup week or month
+ */
+router.get('/cohort-retention', async (req, res) => {
+  try {
+    const { period = 'weekly', source = 'all', limit = 12 } = req.query;
+    const limitInt = Math.min(parseInt(limit), 52); // Max 52 cohorts (1 year weekly)
+    
+    // Validate period
+    if (!['weekly', 'monthly'].includes(period)) {
+      return res.status(400).json({
+        success: false,
+        error: 'Period must be "weekly" or "monthly"',
+      });
+    }
+    
+    // Build the cohort retention query
+    const cohortQuery = `
+      WITH signups AS (
+        -- Get first registration event per user
+        SELECT 
+          user_id,
+          MIN(DATE(created_at)) as signup_date,
+          MIN(metadata->>'referralCode') as referral_code
+        FROM audit_logs
+        WHERE log_type = 'registration_completed'
+          AND user_id IS NOT NULL
+        GROUP BY user_id
+      ),
+      cohorts AS (
+        -- Group signups into weekly or monthly cohorts
+        SELECT 
+          DATE_TRUNC('${period === 'weekly' ? 'week' : 'month'}', signup_date) as cohort_period,
+          user_id,
+          signup_date,
+          CASE 
+            WHEN referral_code IS NOT NULL AND referral_code != '' THEN 'referral'
+            ELSE 'organic'
+          END as user_source
+        FROM signups
+      ),
+      user_activity AS (
+        -- Get only BET-RELATED activity after signup (core action retention)
+        -- A user is "retained" only if they placed a bet, not just opened the app
+        SELECT 
+          c.cohort_period,
+          c.user_id,
+          c.signup_date,
+          c.user_source,
+          DATE(al.created_at) as activity_date,
+          al.created_at - c.signup_date as time_since_signup
+        FROM cohorts c
+        LEFT JOIN audit_logs al ON al.user_id = c.user_id
+          AND DATE(al.created_at) >= c.signup_date
+          -- ONLY count bet-related actions as "retained"
+          AND al.log_type IN (
+            'bet_creation_completed',     -- Created a bet (sports)
+            'join_game_completed',        -- Joined an existing bet
+            'billiards_create_completed', -- Created pool game
+            'billiards_join_completed'    -- Joined pool game
+          )
+        WHERE $1 = 'all' OR c.user_source = $1
+      ),
+      retention_calc AS (
+        -- Calculate retention metrics
+        SELECT 
+          cohort_period,
+          user_source,
+          COUNT(DISTINCT user_id) as total_users,
+          -- Day 1 retention (24-48 hours)
+          COUNT(DISTINCT CASE 
+            WHEN time_since_signup >= INTERVAL '1 day' 
+            AND time_since_signup < INTERVAL '2 days' 
+            THEN user_id 
+          END) as d1_users,
+          -- Day 7 retention (7-8 days)
+          COUNT(DISTINCT CASE 
+            WHEN time_since_signup >= INTERVAL '7 days' 
+            AND time_since_signup < INTERVAL '8 days' 
+            THEN user_id 
+          END) as d7_users,
+          -- Day 14 retention (14-15 days)
+          COUNT(DISTINCT CASE 
+            WHEN time_since_signup >= INTERVAL '14 days' 
+            AND time_since_signup < INTERVAL '15 days' 
+            THEN user_id 
+          END) as d14_users,
+          -- Day 30 retention (30-31 days)
+          COUNT(DISTINCT CASE 
+            WHEN time_since_signup >= INTERVAL '30 days' 
+            AND time_since_signup < INTERVAL '31 days' 
+            THEN user_id 
+          END) as d30_users
+        FROM user_activity
+        GROUP BY cohort_period, user_source
+      )
+      SELECT 
+        cohort_period,
+        total_users,
+        d1_users,
+        ROUND(100.0 * d1_users / NULLIF(total_users, 0), 1) as d1_pct,
+        d7_users,
+        ROUND(100.0 * d7_users / NULLIF(total_users, 0), 1) as d7_pct,
+        d14_users,
+        ROUND(100.0 * d14_users / NULLIF(total_users, 0), 1) as d14_pct,
+        d30_users,
+        ROUND(100.0 * d30_users / NULLIF(total_users, 0), 1) as d30_pct,
+        user_source
+      FROM retention_calc
+      WHERE total_users > 0
+      ORDER BY cohort_period DESC
+      LIMIT $2
+    `;
+    
+    const result = await pool.query(cohortQuery, [source, limitInt]);
+    
+    // Format the response with readable date ranges
+    const cohorts = result.rows.map(row => {
+      const cohortDate = new Date(row.cohort_period);
+      let dateRange;
+      
+      if (period === 'weekly') {
+        const endDate = new Date(cohortDate);
+        endDate.setDate(endDate.getDate() + 6);
+        // Use UTC methods to avoid timezone issues
+        dateRange = `${cohortDate.toLocaleDateString('en-US', { month: 'short', day: 'numeric', timeZone: 'UTC' })} - ${endDate.toLocaleDateString('en-US', { month: 'short', day: 'numeric', year: 'numeric', timeZone: 'UTC' })}`;
+      } else {
+        // Use UTC timezone to ensure correct month display
+        dateRange = cohortDate.toLocaleDateString('en-US', { month: 'long', year: 'numeric', timeZone: 'UTC' });
+      }
+      
+      return {
+        signup_cohort: row.cohort_period,
+        signup_date_range: dateRange,
+        total_signups: parseInt(row.total_users),
+        d1_users: parseInt(row.d1_users),
+        d1_pct: parseFloat(row.d1_pct) || 0,
+        d7_users: parseInt(row.d7_users),
+        d7_pct: parseFloat(row.d7_pct) || 0,
+        d14_users: parseInt(row.d14_users),
+        d14_pct: parseFloat(row.d14_pct) || 0,
+        d30_users: parseInt(row.d30_users),
+        d30_pct: parseFloat(row.d30_pct) || 0,
+        source: source === 'all' ? 'all' : row.user_source,
+      };
+    });
+    
+    console.log(`[Analytics] Cohort retention: ${cohorts.length} cohorts (${period}, source: ${source})`);
+    
+    return res.json({
+      success: true,
+      period,
+      source,
+      cohorts,
+      total_cohorts: cohorts.length,
+    });
+    
+  } catch (error) {
+    console.error('[Analytics] Error getting cohort retention:', error);
+    return res.status(500).json({
+      success: false,
+      error: 'Failed to get cohort retention data',
+    });
+  }
+});
+
+/**
+ * GET /api/analytics/cohort-retention/csv
+ * 
+ * Export cohort retention data as CSV
+ */
+router.get('/cohort-retention/csv', async (req, res) => {
+  try {
+    const { period = 'weekly', source = 'all', limit = 52 } = req.query;
+    
+    // Get the cohort data (reuse the same endpoint logic)
+    const cohortResponse = await new Promise((resolve, reject) => {
+      // Call the cohort-retention endpoint internally
+      const mockReq = { query: { period, source, limit } };
+      const mockRes = {
+        json: (data) => resolve(data),
+        status: () => mockRes,
+      };
+      
+      // Use the same query logic
+      pool.query(`
+        WITH signups AS (
+          SELECT 
+            user_id,
+            MIN(DATE(created_at)) as signup_date,
+            MIN(metadata->>'referralCode') as referral_code
+          FROM audit_logs
+          WHERE log_type = 'registration_completed'
+            AND user_id IS NOT NULL
+          GROUP BY user_id
+        ),
+        cohorts AS (
+          SELECT 
+            DATE_TRUNC('${period === 'weekly' ? 'week' : 'month'}', signup_date) as cohort_period,
+            user_id,
+            signup_date,
+            CASE 
+              WHEN referral_code IS NOT NULL AND referral_code != '' THEN 'referral'
+              ELSE 'organic'
+            END as user_source
+          FROM signups
+        ),
+        user_activity AS (
+          -- Get only BET-RELATED activity after signup (core action retention)
+          SELECT 
+            c.cohort_period,
+            c.user_id,
+            c.signup_date,
+            c.user_source,
+            DATE(al.created_at) as activity_date,
+            al.created_at - c.signup_date as time_since_signup
+          FROM cohorts c
+          LEFT JOIN audit_logs al ON al.user_id = c.user_id
+            AND DATE(al.created_at) >= c.signup_date
+            -- ONLY count bet-related actions as "retained"
+            AND al.log_type IN (
+              'bet_creation_completed',     -- Created a bet (sports)
+              'join_game_completed',        -- Joined an existing bet
+              'billiards_create_completed', -- Created pool game
+              'billiards_join_completed'    -- Joined pool game
+            )
+          WHERE $1 = 'all' OR c.user_source = $1
+        ),
+        retention_calc AS (
+          SELECT 
+            cohort_period,
+            user_source,
+            COUNT(DISTINCT user_id) as total_users,
+            COUNT(DISTINCT CASE 
+              WHEN time_since_signup >= INTERVAL '1 day' 
+              AND time_since_signup < INTERVAL '2 days' 
+              THEN user_id 
+            END) as d1_users,
+            COUNT(DISTINCT CASE 
+              WHEN time_since_signup >= INTERVAL '7 days' 
+              AND time_since_signup < INTERVAL '8 days' 
+              THEN user_id 
+            END) as d7_users,
+            COUNT(DISTINCT CASE 
+              WHEN time_since_signup >= INTERVAL '14 days' 
+              AND time_since_signup < INTERVAL '15 days' 
+              THEN user_id 
+            END) as d14_users,
+            COUNT(DISTINCT CASE 
+              WHEN time_since_signup >= INTERVAL '30 days' 
+              AND time_since_signup < INTERVAL '31 days' 
+              THEN user_id 
+            END) as d30_users
+          FROM user_activity
+          GROUP BY cohort_period, user_source
+        )
+        SELECT 
+          cohort_period,
+          total_users,
+          d1_users,
+          ROUND(100.0 * d1_users / NULLIF(total_users, 0), 1) as d1_pct,
+          d7_users,
+          ROUND(100.0 * d7_users / NULLIF(total_users, 0), 1) as d7_pct,
+          d14_users,
+          ROUND(100.0 * d14_users / NULLIF(total_users, 0), 1) as d14_pct,
+          d30_users,
+          ROUND(100.0 * d30_users / NULLIF(total_users, 0), 1) as d30_pct,
+          user_source
+        FROM retention_calc
+        WHERE total_users > 0
+        ORDER BY cohort_period DESC
+        LIMIT $2
+      `, [source, Math.min(parseInt(limit), 52)])
+      .then(result => resolve(result.rows))
+      .catch(reject);
+    });
+    
+    // Build CSV content
+    const headers = [
+      'signup_cohort',
+      'signup_date_range',
+      'total_signups',
+      'd1_users',
+      'd1_pct',
+      'd7_users',
+      'd7_pct',
+      'd14_users',
+      'd14_pct',
+      'd30_users',
+      'd30_pct',
+      'source',
+    ];
+    
+    let csv = headers.join(',') + '\n';
+    
+    cohortResponse.forEach(row => {
+      const cohortDate = new Date(row.cohort_period);
+      let dateRange;
+      
+      if (period === 'weekly') {
+        const endDate = new Date(cohortDate);
+        endDate.setDate(endDate.getDate() + 6);
+        // Use UTC methods to avoid timezone issues
+        dateRange = `${cohortDate.toLocaleDateString('en-US', { month: 'short', day: 'numeric', timeZone: 'UTC' })} - ${endDate.toLocaleDateString('en-US', { month: 'short', day: 'numeric', year: 'numeric', timeZone: 'UTC' })}`;
+      } else {
+        // Use UTC timezone to ensure correct month display
+        dateRange = cohortDate.toLocaleDateString('en-US', { month: 'long', year: 'numeric', timeZone: 'UTC' });
+      }
+      
+      const values = [
+        `"${period === 'weekly' ? 'Week of ' : ''}${cohortDate.toLocaleDateString('en-US', { month: 'short', day: 'numeric', year: 'numeric', timeZone: 'UTC' })}"`,
+        `"${dateRange}"`,
+        parseInt(row.total_users),
+        parseInt(row.d1_users),
+        parseFloat(row.d1_pct) || 0,
+        parseInt(row.d7_users),
+        parseFloat(row.d7_pct) || 0,
+        parseInt(row.d14_users),
+        parseFloat(row.d14_pct) || 0,
+        parseInt(row.d30_users),
+        parseFloat(row.d30_pct) || 0,
+        source === 'all' ? 'all' : row.user_source,
+      ];
+      
+      csv += values.join(',') + '\n';
+    });
+    
+    // Set headers for file download
+    const filename = `cohort-retention-${period}-${new Date().toISOString().split('T')[0]}.csv`;
+    res.setHeader('Content-Type', 'text/csv');
+    res.setHeader('Content-Disposition', `attachment; filename="${filename}"`);
+    
+    console.log(`[Analytics] CSV export: ${cohortResponse.length} cohorts`);
+    
+    return res.send(csv);
+    
+  } catch (error) {
+    console.error('[Analytics] Error exporting cohort CSV:', error);
+    return res.status(500).json({
+      success: false,
+      error: 'Failed to export cohort retention CSV',
+    });
+  }
+});
+
+module.exports = router;
+