Analytics Dashboard

┌─────────────────────────────────────────────────────────────────────────┐
│                         pxlpeak Analytics Engine                         │
├─────────────────────────────────────────────────────────────────────────┤
│                                                                         │
│   Data Collection          Processing           Storage & Query         │
│   ┌─────────────┐        ┌─────────────┐       ┌─────────────┐        │
│   │   Browser   │───────▶│   Ingestion │──────▶│  Columnar   │        │
│   │   Tracker   │        │   Pipeline  │       │   Storage   │        │
│   └─────────────┘        └─────────────┘       └──────┬──────┘        │
│   ┌─────────────┐        ┌─────────────┐              │               │
│   │  Server SDK │───────▶│  Real-time  │              │               │
│   │             │        │  Processor  │              ▼               │
│   └─────────────┘        └─────────────┘       ┌─────────────┐        │
│   ┌─────────────┐        ┌─────────────┐       │   Query     │        │
│   │   Mobile    │───────▶│  Enrichment │──────▶│   Engine    │        │
│   │    SDK      │        │   Service   │       │  (< 100ms)  │        │
│   └─────────────┘        └─────────────┘       └──────┬──────┘        │
│                                                       │               │
│                          ┌────────────────────────────┼───────┐       │
│                          │                            │       │       │
│                          ▼                            ▼       ▼       │
│                   ┌─────────────┐            ┌─────────────┐         │
│                   │  Dashboard  │            │     API     │         │
│                   │     UI      │            │   Exports   │         │
│                   └─────────────┘            └─────────────┘         │
│                                                                         │
└─────────────────────────────────────────────────────────────────────────┘

// Event processing pipeline stages
interface AnalyticsPipeline {
  stages: {
    // Stage 1: Collection
    collection: {
      sources: ['browser', 'server', 'mobile', 'import'];
      validation: 'schema_enforced';
      deduplication: 'event_id_based';
    };

    // Stage 2: Enrichment
    enrichment: {
      geoIP: true;           // Country, region, city
      deviceParsing: true;   // Device, browser, OS
      sessionStitching: true; // Cross-device sessions
      userResolution: true;   // Anonymous to identified
      utmParsing: true;       // Campaign attribution
      referrerParsing: true;  // Traffic source classification
    };

    // Stage 3: Processing
    processing: {
      sessionization: '30_minute_timeout';
      aggregation: ['realtime', 'hourly', 'daily'];
      indexing: ['timestamp', 'user_id', 'event_name'];
    };

    // Stage 4: Storage
    storage: {
      format: 'columnar_parquet';
      compression: 'zstd';
      partitioning: 'date_based';
      retention: 'plan_based'; // 90 days to unlimited
    };
  };
}

// Real-time metrics subscription
const realtime = pxlpeak.analytics.realtime.subscribe({
  metrics: [
    'active_users',
    'active_sessions',
    'pageviews_per_minute',
    'events_per_minute',
    'conversions_per_hour',
    'revenue_today'
  ],

  // Update frequency
  interval: 1000, // 1 second

  // Optional filters
  filters: [
    { field: 'country', operator: 'eq', value: 'US' }
  ],

  // Callback for updates
  onUpdate: (data) => {
    console.log('Active users:', data.active_users);
    console.log('Events/min:', data.events_per_minute);
    updateDashboard(data);
  },

  // Error handling
  onError: (error) => {
    console.error('Realtime error:', error);
  }
});

// Response structure
interface RealtimeData {
  timestamp: string;
  active_users: number;
  active_sessions: number;
  pageviews_per_minute: number;
  events_per_minute: number;
  conversions_per_hour: number;
  revenue_today: number;

  // Breakdowns
  top_pages: Array<{ page: string; active_users: number }>;
  top_sources: Array<{ source: string; active_users: number }>;
  top_countries: Array<{ country: string; active_users: number }>;
  top_events: Array<{ event: string; count_per_minute: number }>;
}

// Cleanup when done
realtime.unsubscribe();

// Subscribe to live events
const eventStream = pxlpeak.analytics.realtime.streamEvents({
  // Event types to stream
  events: ['purchase', 'signup', 'lead_submitted'],

  // Optional filters
  filters: [
    { field: 'properties.revenue', operator: 'gte', value: 100 }
  ],

  // Callback for each event
  onEvent: (event) => {
    console.log('New event:', {
      name: event.name,
      userId: event.userId,
      properties: event.properties,
      timestamp: event.timestamp,
      source: event.attribution.source,
      campaign: event.attribution.campaign
    });

    // Show notification for high-value events
    if (event.properties.revenue > 1000) {
      showNotification(`High-value conversion: $${event.properties.revenue}`);
    }
  },

  // Buffer settings
  buffer: {
    enabled: false, // true for batched delivery
    maxSize: 100,
    flushInterval: 5000
  }
});

// Track segment changes live
const segmentStream = pxlpeak.analytics.realtime.streamSegments({
  segments: ['high_value_users', 'cart_abandoners', 'trial_users'],

  onEnter: (event) => {
    console.log(`User ${event.userId} entered segment: ${event.segment}`);
    triggerPersonalization(event.userId, event.segment);
  },

  onExit: (event) => {
    console.log(`User ${event.userId} exited segment: ${event.segment}`);
  },

  // Include segment counts
  includeCounts: true,
  countInterval: 60000 // Update counts every minute
});

// Available metrics organized by category
interface AnalyticsMetrics {
  // Traffic metrics
  traffic: {
    visitors: 'Unique visitors (by anonymous_id or user_id)';
    new_visitors: 'First-time visitors';
    returning_visitors: 'Visitors with previous sessions';
    sessions: 'Total sessions (30-min timeout)';
    pageviews: 'Total page views';
    unique_pageviews: 'Unique pages per session';
    events: 'Total tracked events';
  };

  // Engagement metrics
  engagement: {
    avg_session_duration: 'Average time per session (seconds)';
    avg_time_on_page: 'Average time per page (seconds)';
    pages_per_session: 'Average pages viewed per session';
    bounce_rate: 'Single-page session percentage';
    exit_rate: 'Percentage exiting from page';
    scroll_depth: 'Average scroll percentage';
    engagement_rate: 'Non-bounce rate with 10s+ duration';
  };

  // Conversion metrics
  conversion: {
    conversions: 'Total conversion events';
    conversion_rate: 'Conversions / Sessions * 100';
    goal_completions: 'Goal completions by goal';
    goal_value: 'Total goal value';
    transactions: 'E-commerce transactions';
    revenue: 'Total revenue';
    avg_order_value: 'Revenue / Transactions';
    items_per_transaction: 'Products per order';
  };

  // Acquisition metrics
  acquisition: {
    cost: 'Advertising spend (from integrations)';
    cpc: 'Cost per click';
    cpm: 'Cost per thousand impressions';
    cpa: 'Cost per acquisition';
    roas: 'Return on ad spend';
    ltv: 'Customer lifetime value';
  };

  // Retention metrics
  retention: {
    retention_rate: 'Users returning in period';
    churn_rate: 'Users not returning';
    dau: 'Daily active users';
    wau: 'Weekly active users';
    mau: 'Monthly active users';
    stickiness: 'DAU / MAU ratio';
  };
}

// Available dimensions for analysis
interface AnalyticsDimensions {
  // Time dimensions
  time: {
    date: 'YYYY-MM-DD';
    datetime: 'YYYY-MM-DD HH:mm:ss';
    hour: '0-23';
    day_of_week: 'Monday-Sunday';
    week: 'ISO week number';
    month: 'January-December';
    quarter: 'Q1-Q4';
    year: 'YYYY';
  };

  // User dimensions
  user: {
    user_id: 'Identified user ID';
    anonymous_id: 'Anonymous visitor ID';
    user_type: 'new, returning';
    first_seen_date: 'First visit date';
    signup_date: 'Registration date';
    user_properties: 'Custom user properties';
  };

  // Session dimensions
  session: {
    session_id: 'Unique session identifier';
    session_number: 'Nth session for user';
    landing_page: 'First page of session';
    exit_page: 'Last page of session';
    session_duration_bucket: '0-10s, 10-30s, 30-60s, 1-3m, 3-10m, 10m+';
  };

  // Page dimensions
  page: {
    page_path: '/path/to/page';
    page_title: 'Page title';
    page_url: 'Full URL';
    hostname: 'Domain name';
    page_type: 'Custom page classification';
    content_group: 'Content grouping';
  };

  // Traffic source dimensions
  source: {
    source: 'Traffic source (google, facebook, etc.)';
    medium: 'Traffic medium (organic, cpc, email, etc.)';
    campaign: 'Campaign name';
    content: 'Ad content';
    term: 'Search term';
    channel: 'Grouped channel (Organic Search, Paid Search, etc.)';
    referrer: 'Referring URL';
    referrer_domain: 'Referring domain';
  };

  // Technology dimensions
  technology: {
    browser: 'Chrome, Firefox, Safari, etc.';
    browser_version: 'Major.minor version';
    os: 'Operating system';
    os_version: 'OS version';
    device_type: 'desktop, mobile, tablet';
    device_brand: 'Apple, Samsung, etc.';
    device_model: 'iPhone 14, Galaxy S23, etc.';
    screen_resolution: 'Width x Height';
  };

  // Geography dimensions
  geography: {
    country: 'Country name';
    country_code: 'ISO 3166-1 alpha-2';
    region: 'State/Province';
    city: 'City name';
    postal_code: 'ZIP/Postal code';
    timezone: 'IANA timezone';
    language: 'Browser language';
  };

  // Event dimensions
  event: {
    event_name: 'Event identifier';
    event_category: 'Event grouping';
    event_label: 'Event label';
    event_value: 'Numeric event value';
    event_properties: 'Custom event properties';
  };
}

// Define custom metrics
const customMetrics = await pxlpeak.analytics.metrics.create([
  {
    name: 'engaged_sessions',
    displayName: 'Engaged Sessions',
    description: 'Sessions with 2+ pages or 30s+ duration',
    formula: `
      COUNT(DISTINCT session_id) WHERE (
        pages_per_session >= 2 OR
        session_duration >= 30
      )
    `,
    format: { type: 'number', decimals: 0 }
  },
  {
    name: 'engagement_rate',
    displayName: 'Engagement Rate',
    description: 'Percentage of engaged sessions',
    formula: 'engaged_sessions / sessions * 100',
    format: { type: 'percentage', decimals: 1 }
  },
  {
    name: 'revenue_per_session',
    displayName: 'Revenue per Session',
    description: 'Average revenue generated per session',
    formula: 'revenue / sessions',
    format: { type: 'currency', currency: 'USD', decimals: 2 }
  },
  {
    name: 'qualified_leads',
    displayName: 'Qualified Leads',
    description: 'Leads with score >= 50',
    formula: `
      COUNT(DISTINCT user_id) WHERE (
        event_name = 'lead_created' AND
        lead_score >= 50
      )
    `,
    format: { type: 'number', decimals: 0 }
  },
  {
    name: 'lead_to_customer_rate',
    displayName: 'Lead to Customer Rate',
    description: 'Percentage of leads that convert to customers',
    formula: `
      COUNT(DISTINCT user_id WHERE event_name = 'purchase') /
      COUNT(DISTINCT user_id WHERE event_name = 'lead_created') * 100
    `,
    format: { type: 'percentage', decimals: 2 }
  },
  {
    name: 'content_efficiency_score',
    displayName: 'Content Efficiency Score',
    description: 'Composite score of content performance',
    formula: `
      (avg_time_on_page / 60) * 0.3 +
      (scroll_depth / 100) * 0.3 +
      (1 - bounce_rate / 100) * 0.4
    `,
    format: { type: 'number', decimals: 2 }
  }
]);

// Define custom dimensions from event properties
await pxlpeak.analytics.dimensions.create([
  {
    name: 'subscription_tier',
    displayName: 'Subscription Tier',
    description: 'User subscription level',
    source: 'user_properties.subscription_tier',
    type: 'string',
    values: ['free', 'starter', 'pro', 'enterprise']
  },
  {
    name: 'experiment_variant',
    displayName: 'A/B Test Variant',
    description: 'Experiment variant assignment',
    source: 'event_properties.variant',
    type: 'string'
  },
  {
    name: 'content_author',
    displayName: 'Content Author',
    description: 'Author of the content',
    source: 'page_properties.author',
    type: 'string'
  },
  {
    name: 'product_category',
    displayName: 'Product Category',
    description: 'E-commerce product category',
    source: 'event_properties.category',
    type: 'string'
  },
  {
    name: 'customer_segment',
    displayName: 'Customer Segment',
    description: 'Business segment classification',
    source: 'user_properties.segment',
    type: 'string',
    values: ['smb', 'mid_market', 'enterprise']
  }
]);

// Comprehensive query example
const results = await pxlpeak.analytics.query({
  // Date range
  dateRange: {
    start: '2026-01-01',
    end: '2026-01-31',
    timezone: 'America/New_York',
    granularity: 'day' // none, hour, day, week, month
  },

  // Comparison period
  comparison: {
    type: 'previous_period', // previous_period, previous_year, custom
    // customRange: { start: '2025-12-01', end: '2025-12-31' }
  },

  // Metrics to retrieve
  metrics: [
    'sessions',
    'visitors',
    'pageviews',
    'bounce_rate',
    'avg_session_duration',
    'conversions',
    'conversion_rate',
    'revenue',
    {
      name: 'avg_order_value',
      formula: 'revenue / conversions'
    }
  ],

  // Dimensions for breakdown
  dimensions: [
    'channel',
    'source',
    'medium',
    'landing_page'
  ],

  // Filters
  filters: [
    { field: 'country', operator: 'eq', value: 'US' },
    { field: 'device_type', operator: 'in', value: ['desktop', 'mobile'] },
    { field: 'sessions', operator: 'gte', value: 10 },
    {
      logic: 'or',
      conditions: [
        { field: 'source', operator: 'eq', value: 'google' },
        { field: 'source', operator: 'eq', value: 'facebook' }
      ]
    }
  ],

  // Segments to apply
  segments: ['returning_users', 'converted_users'],

  // Sorting
  sort: [
    { field: 'revenue', order: 'desc' },
    { field: 'sessions', order: 'desc' }
  ],

  // Pagination
  limit: 100,
  offset: 0,

  // Options
  options: {
    includeEmpty: false,     // Include rows with zero values
    includePercentOfTotal: true, // Add percentage column
    fillMissingDates: true,  // Fill gaps in time series
    sampling: false          // Disable sampling for exact results
  }
});

// Response structure
interface QueryResult {
  data: Array<{
    // Dimension values
    date?: string;
    channel: string;
    source: string;
    medium: string;
    landing_page: string;

    // Metric values
    sessions: number;
    visitors: number;
    pageviews: number;
    bounce_rate: number;
    avg_session_duration: number;
    conversions: number;
    conversion_rate: number;
    revenue: number;
    avg_order_value: number;

    // Comparison (if enabled)
    comparison?: {
      sessions: { value: number; change: number; changePercent: number };
      revenue: { value: number; change: number; changePercent: number };
      // ... other metrics
    };

    // Percentage of total (if enabled)
    percentOfTotal?: {
      sessions: number;
      revenue: number;
    };
  }>;

  // Totals row
  totals: {
    sessions: number;
    visitors: number;
    pageviews: number;
    bounce_rate: number;
    avg_session_duration: number;
    conversions: number;
    conversion_rate: number;
    revenue: number;
    avg_order_value: number;
  };

  // Comparison totals
  comparisonTotals?: Record<string, number>;

  // Query metadata
  metadata: {
    dateRange: { start: string; end: string };
    comparisonRange?: { start: string; end: string };
    rowCount: number;
    totalRows: number;
    truncated: boolean;
    samplingApplied: boolean;
    samplingRate?: number;
    queryTime: number; // milliseconds
    cacheHit: boolean;
  };
}

// Create and analyze conversion funnels
const funnel = await pxlpeak.analytics.funnel({
  name: 'Purchase Funnel',

  // Funnel steps
  steps: [
    {
      name: 'Viewed Homepage',
      event: 'page_view',
      filter: { page_path: '/' }
    },
    {
      name: 'Viewed Product',
      event: 'product_viewed',
      // Optional: require specific property
      filter: { category: 'electronics' }
    },
    {
      name: 'Added to Cart',
      event: 'add_to_cart'
    },
    {
      name: 'Started Checkout',
      event: 'checkout_started'
    },
    {
      name: 'Completed Purchase',
      event: 'purchase'
    }
  ],

  // Date range
  dateRange: {
    start: '2026-01-01',
    end: '2026-01-31'
  },

  // Conversion window
  conversionWindow: {
    value: 7,
    unit: 'days'
  },

  // Options
  options: {
    sequential: true,        // Require steps in order
    perUser: true,           // One conversion per user
    includeTimeDistribution: true,
    includeDropoffAnalysis: true
  },

  // Breakdown
  breakdown: {
    dimension: 'device_type',
    limit: 5
  }
});

// Response
interface FunnelResult {
  steps: Array<{
    name: string;
    event: string;
    users: number;
    conversionRate: number;      // From previous step
    overallConversionRate: number; // From first step
    dropoff: number;             // Users who didn't continue
    dropoffRate: number;
    avgTimeToNext: number;       // Seconds to next step
    medianTimeToNext: number;
  }>;

  summary: {
    totalStarted: number;
    totalCompleted: number;
    overallConversionRate: number;
    avgCompletionTime: number;
    medianCompletionTime: number;
  };

  // Time distribution (if enabled)
  timeDistribution?: Array<{
    step: string;
    percentile10: number;
    percentile25: number;
    percentile50: number;
    percentile75: number;
    percentile90: number;
  }>;

  // Dropoff analysis (if enabled)
  dropoffAnalysis?: Array<{
    fromStep: string;
    toStep: string;
    dropoffUsers: number;
    topExitPages: Array<{ page: string; users: number }>;
    topNextEvents: Array<{ event: string; users: number }>;
  }>;

  // Breakdown (if specified)
  breakdown?: Array<{
    value: string; // e.g., 'desktop', 'mobile'
    steps: Array<{ name: string; users: number; conversionRate: number }>;
    overallConversionRate: number;
  }>;
}

// Retention cohort analysis
const cohort = await pxlpeak.analytics.cohort({
  // Cohort definition
  cohortType: 'first_visit', // first_visit, signup, first_purchase, custom_event

  // For custom event cohort
  // cohortEvent: { event: 'trial_started', filter: { plan: 'pro' } },

  // Return definition
  returnEvent: {
    type: 'any_visit', // any_visit, specific_event, conversion
    // event: 'purchase', // For specific_event
  },

  // Date range for cohort creation
  dateRange: {
    start: '2025-10-01',
    end: '2026-01-31'
  },

  // Cohort granularity
  cohortGranularity: 'week', // day, week, month

  // Return period granularity
  returnGranularity: 'week', // day, week, month

  // Number of return periods
  periods: 12,

  // Filters
  filters: [
    { field: 'channel', operator: 'eq', value: 'paid_search' }
  ],

  // Segment
  segment: 'trial_users'
});

// Response
interface CohortResult {
  cohorts: Array<{
    cohort: string;           // '2025-W40', '2025-10', etc.
    cohortStart: string;
    cohortEnd: string;
    cohortSize: number;

    retention: Array<{
      period: number;         // 0, 1, 2, 3, ...
      users: number;
      retentionRate: number;  // Percentage
    }>;
  }>;

  summary: {
    totalCohortUsers: number;
    avgRetentionWeek1: number;
    avgRetentionWeek4: number;
    avgRetentionWeek12: number;
    bestCohort: { cohort: string; retentionWeek4: number };
    worstCohort: { cohort: string; retentionWeek4: number };
  };

  // Trend analysis
  trends: {
    retentionTrend: 'improving' | 'stable' | 'declining';
    weekOverWeekChange: number; // Percentage
  };
}

// User journey path analysis
const paths = await pxlpeak.analytics.paths({
  // Starting point
  startingPoint: {
    type: 'page', // page, event
    value: '/pricing' // or event name
  },

  // Ending point (optional)
  endingPoint: {
    type: 'event',
    value: 'purchase'
  },

  // Direction
  direction: 'forward', // forward, backward, both

  // Date range
  dateRange: {
    start: '2026-01-01',
    end: '2026-01-31'
  },

  // Options
  options: {
    maxSteps: 5,           // Maximum path length
    minOccurrences: 100,   // Minimum users for path
    groupSimilarPages: true, // Group /product/123 as /product/*
    includeEvents: true,    // Include non-pageview events
    excludeEvents: ['scroll', 'mouse_move'] // Exclude noisy events
  }
});

// Response
interface PathResult {
  paths: Array<{
    steps: string[];          // ['/', '/products', '/product/*', 'add_to_cart', 'purchase']
    users: number;
    sessions: number;
    conversionRate: number;   // If ending point specified
    avgTimeToComplete: number;
  }>;

  // Visualization data (Sankey diagram)
  sankey: {
    nodes: Array<{ id: string; name: string }>;
    links: Array<{ source: string; target: string; value: number }>;
  };

  summary: {
    totalPaths: number;
    avgPathLength: number;
    mostCommonPath: string[];
    shortestConvertingPath: string[];
  };
}

// Create a complex segment
const segment = await pxlpeak.analytics.segments.create({
  name: 'High-Value Engaged Users',
  description: 'Users with high engagement and revenue potential',

  // Segment conditions
  conditions: {
    // All conditions must be true (AND)
    all: [
      // Behavioral conditions
      {
        type: 'behavior',
        event: 'page_view',
        aggregation: 'count',
        operator: 'gte',
        value: 10,
        timeframe: 'last_30_days'
      },
      {
        type: 'behavior',
        metric: 'sessions',
        operator: 'gte',
        value: 3,
        timeframe: 'last_30_days'
      },

      // Any of these conditions (OR)
      {
        any: [
          {
            type: 'behavior',
            event: 'purchase',
            aggregation: 'count',
            operator: 'gte',
            value: 1,
            timeframe: 'last_90_days'
          },
          {
            type: 'property',
            field: 'user_properties.lead_score',
            operator: 'gte',
            value: 70
          }
        ]
      },

      // Property conditions
      {
        type: 'property',
        field: 'user_properties.subscription_tier',
        operator: 'in',
        value: ['pro', 'enterprise']
      },

      // Recency condition
      {
        type: 'recency',
        event: 'any',
        operator: 'within',
        value: 7,
        unit: 'days'
      }
    ],

    // Exclusions (none of these)
    none: [
      {
        type: 'property',
        field: 'user_properties.churned',
        operator: 'eq',
        value: true
      },
      {
        type: 'behavior',
        event: 'unsubscribed',
        aggregation: 'exists',
        timeframe: 'all_time'
      }
    ]
  },

  // Segment options
  options: {
    dynamic: true,           // Auto-update membership
    refreshInterval: 'hourly', // Refresh frequency
    estimateSize: true       // Calculate estimated size
  }
});

// Get segment size and composition
const segmentInfo = await pxlpeak.analytics.segments.analyze('segment_abc123');
// {
//   id: 'segment_abc123',
//   name: 'High-Value Engaged Users',
//   size: 12450,
//   percentOfTotal: 8.3,
//   growth: { last7Days: 5.2, last30Days: 12.8 },
//   composition: {
//     byCountry: [{ country: 'US', users: 6200 }, ...],
//     byDevice: [{ device: 'desktop', users: 8100 }, ...],
//     byChannel: [{ channel: 'organic', users: 5000 }, ...]
//   }
// }

// Compare multiple segments
const comparison = await pxlpeak.analytics.segments.compare({
  segments: ['high_value_users', 'at_risk_users', 'new_users'],

  metrics: [
    'sessions',
    'avg_session_duration',
    'pages_per_session',
    'conversion_rate',
    'revenue',
    'ltv'
  ],

  dateRange: {
    start: '2026-01-01',
    end: '2026-01-31'
  }
});

// Response
{
  segments: [
    {
      id: 'high_value_users',
      name: 'High-Value Users',
      size: 12450,
      metrics: {
        sessions: 45000,
        avg_session_duration: 420,
        pages_per_session: 8.5,
        conversion_rate: 12.3,
        revenue: 450000,
        ltv: 850
      }
    },
    // ... other segments
  ],
  insights: [
    'High-Value Users have 3.2x higher conversion rate than New Users',
    'At-Risk Users session duration dropped 25% vs last period'
  ]
}

// Create a custom dashboard
const dashboard = await pxlpeak.dashboards.create({
  name: 'Executive Overview',
  description: 'High-level KPIs for leadership',

  // Layout configuration
  layout: {
    type: 'grid',
    columns: 12,
    rowHeight: 80,
    gap: 16
  },

  // Default settings
  defaults: {
    dateRange: 'last_30_days',
    comparison: 'previous_period',
    refreshInterval: 300 // seconds
  },

  // Global filters
  filters: [
    {
      field: 'date_range',
      type: 'date_picker',
      position: 'header'
    },
    {
      field: 'channel',
      type: 'multi_select',
      label: 'Channel',
      options: 'dynamic',
      position: 'header'
    }
  ],

  // Dashboard widgets
  widgets: [
    // KPI row
    {
      id: 'visitors_kpi',
      type: 'metric_card',
      title: 'Visitors',
      position: { x: 0, y: 0, w: 3, h: 2 },
      config: {
        metric: 'visitors',
        format: 'compact', // 12.5K
        comparison: true,
        sparkline: true,
        icon: 'users',
        color: 'blue'
      }
    },
    {
      id: 'revenue_kpi',
      type: 'metric_card',
      title: 'Revenue',
      position: { x: 3, y: 0, w: 3, h: 2 },
      config: {
        metric: 'revenue',
        format: 'currency',
        comparison: true,
        sparkline: true,
        icon: 'dollar',
        color: 'green',
        goal: {
          value: 500000,
          showProgress: true
        }
      }
    },
    {
      id: 'conversion_kpi',
      type: 'metric_card',
      title: 'Conversion Rate',
      position: { x: 6, y: 0, w: 3, h: 2 },
      config: {
        metric: 'conversion_rate',
        format: 'percentage',
        comparison: true,
        sparkline: true,
        icon: 'target',
        color: 'purple',
        thresholds: [
          { value: 3, color: 'green' },
          { value: 2, color: 'yellow' },
          { value: 0, color: 'red' }
        ]
      }
    },
    {
      id: 'roas_kpi',
      type: 'metric_card',
      title: 'ROAS',
      position: { x: 9, y: 0, w: 3, h: 2 },
      config: {
        metric: 'roas',
        format: 'multiplier',
        comparison: true,
        sparkline: true,
        icon: 'trending-up',
        color: 'orange'
      }
    },

    // Traffic trend chart
    {
      id: 'traffic_trend',
      type: 'line_chart',
      title: 'Traffic & Conversions',
      position: { x: 0, y: 2, w: 8, h: 4 },
      config: {
        metrics: ['visitors', 'conversions'],
        granularity: 'day',
        stacked: false,
        showLegend: true,
        showDataLabels: false,
        colors: ['#3B82F6', '#10B981'],
        yAxes: [
          { metric: 'visitors', position: 'left' },
          { metric: 'conversions', position: 'right' }
        ],
        annotations: {
          enabled: true,
          source: 'campaigns' // Show campaign launches
        }
      }
    },

    // Channel distribution
    {
      id: 'channel_pie',
      type: 'pie_chart',
      title: 'Traffic by Channel',
      position: { x: 8, y: 2, w: 4, h: 4 },
      config: {
        metric: 'sessions',
        dimension: 'channel',
        limit: 6,
        showOther: true,
        showPercentages: true,
        showLegend: true,
        innerRadius: 40 // Donut chart
      }
    },

    // Top pages table
    {
      id: 'top_pages',
      type: 'table',
      title: 'Top Pages',
      position: { x: 0, y: 6, w: 6, h: 4 },
      config: {
        dimensions: ['page_path'],
        metrics: ['pageviews', 'unique_pageviews', 'avg_time_on_page', 'bounce_rate'],
        sort: { field: 'pageviews', order: 'desc' },
        limit: 10,
        pagination: false,
        conditionalFormatting: [
          {
            field: 'bounce_rate',
            rules: [
              { operator: 'lt', value: 40, style: { color: 'green' } },
              { operator: 'gt', value: 60, style: { color: 'red' } }
            ]
          }
        ]
      }
    },

    // Top sources table
    {
      id: 'top_sources',
      type: 'table',
      title: 'Top Sources',
      position: { x: 6, y: 6, w: 6, h: 4 },
      config: {
        dimensions: ['source', 'medium'],
        metrics: ['sessions', 'conversions', 'revenue', 'conversion_rate'],
        sort: { field: 'revenue', order: 'desc' },
        limit: 10,
        sparklines: {
          sessions: { type: 'bar', width: 60 }
        }
      }
    },

    // Conversion funnel
    {
      id: 'conversion_funnel',
      type: 'funnel',
      title: 'Conversion Funnel',
      position: { x: 0, y: 10, w: 6, h: 4 },
      config: {
        steps: [
          { event: 'page_view', label: 'Site Visit' },
          { event: 'product_viewed', label: 'Product View' },
          { event: 'add_to_cart', label: 'Add to Cart' },
          { event: 'purchase', label: 'Purchase' }
        ],
        showConversionRates: true,
        showDropoff: true,
        horizontal: false
      }
    },

    // Geographic map
    {
      id: 'geo_map',
      type: 'map',
      title: 'Revenue by Country',
      position: { x: 6, y: 10, w: 6, h: 4 },
      config: {
        metric: 'revenue',
        dimension: 'country',
        colorScale: 'sequential',
        showTooltip: true,
        showLabels: true,
        zoomEnabled: true
      }
    }
  ],

  // Sharing settings
  sharing: {
    visibility: 'team',
    editableBy: ['admin', 'analyst'],
    viewableBy: ['marketing', 'sales']
  }
});

// All available widget types
type WidgetType =
  | 'metric_card'      // Single KPI with optional sparkline, comparison, goal
  | 'line_chart'       // Time series, multiple metrics, annotations
  | 'area_chart'       // Stacked area, percentage area
  | 'bar_chart'        // Horizontal/vertical, stacked, grouped
  | 'pie_chart'        // Pie or donut chart
  | 'funnel'           // Conversion funnel visualization
  | 'table'            // Data table with sorting, filtering, sparklines
  | 'map'              // Geographic choropleth map
  | 'heatmap'          // Calendar or grid heatmap
  | 'gauge'            // Goal progress gauge
  | 'leaderboard'      // Ranked list with bars
  | 'cohort'           // Cohort retention grid
  | 'sankey'           // Flow diagram for paths
  | 'scatter'          // Scatter/bubble plot
  | 'treemap'          // Hierarchical treemap
  | 'text'             // Markdown text/notes
  | 'iframe'           // External embed
  | 'custom';          // Custom visualization

// Create analytics alerts
const alert = await pxlpeak.analytics.alerts.create({
  name: 'Traffic Drop Alert',
  description: 'Alert when traffic drops significantly',

  // Trigger conditions
  conditions: {
    metric: 'sessions',
    comparison: 'previous_period', // previous_period, previous_week, previous_month, fixed
    threshold: {
      type: 'percentage_decrease',
      value: 20 // Alert if 20%+ drop
    },
    // Additional conditions
    filters: [
      { field: 'channel', operator: 'eq', value: 'organic_search' }
    ]
  },

  // Evaluation settings
  evaluation: {
    frequency: 'hourly', // realtime, hourly, daily, weekly
    lookbackPeriod: '24h',
    minimumDataPoints: 100, // Avoid false positives
    sensitivity: 'medium' // low, medium, high
  },

  // Notification channels
  notifications: {
    email: {
      recipients: ['marketing@company.com', 'cto@company.com'],
      includeChart: true,
      includeRecommendations: true
    },
    slack: {
      channel: '#analytics-alerts',
      mentionUsers: ['@marketing-lead']
    },
    webhook: {
      url: 'https://api.company.com/alerts',
      headers: { 'X-Alert-Source': 'pxlpeak' }
    },
    sms: {
      numbers: ['+1-555-123-4567'],
      onlyCritical: true // Only for critical severity
    }
  },

  // Alert behavior
  behavior: {
    severity: 'warning', // info, warning, critical
    cooldownPeriod: '4h', // Don't re-alert within this period
    autoResolve: true,    // Resolve when condition no longer met
    escalation: {
      enabled: true,
      escalateAfter: '2h',
      escalateTo: ['vp-marketing@company.com']
    }
  }
});

// Enable ML-powered anomaly detection
await pxlpeak.analytics.anomalies.configure({
  // Metrics to monitor
  metrics: [
    'sessions',
    'pageviews',
    'conversions',
    'revenue',
    'bounce_rate',
    'avg_session_duration'
  ],

  // Detection settings
  detection: {
    algorithm: 'prophet', // prophet, isolation_forest, statistical
    sensitivity: 0.95,    // Confidence level
    seasonality: {
      daily: true,
      weekly: true,
      yearly: true
    },
    excludeHolidays: true,
    trainingPeriod: '90d'
  },

  // Alert on anomalies
  alerting: {
    enabled: true,
    minimumDeviation: 2.5, // Standard deviations
    notifyOn: ['spike', 'drop', 'trend_change'],
    channels: ['email', 'slack']
  }
});

// Get detected anomalies
const anomalies = await pxlpeak.analytics.anomalies.list({
  dateRange: { start: '2026-01-01', end: '2026-01-31' },
  status: 'unresolved', // unresolved, resolved, ignored
  severity: ['high', 'critical']
});

// Response
{
  anomalies: [
    {
      id: 'anomaly_abc123',
      metric: 'conversions',
      type: 'drop',
      severity: 'high',
      detectedAt: '2026-01-15T14:30:00Z',
      value: 45,
      expectedValue: 120,
      deviation: -62.5, // percentage
      confidence: 0.97,
      possibleCauses: [
        'Checkout page error spike detected',
        'Traffic from Google dropped 40%',
        'Payment gateway latency increased 300%'
      ],
      suggestedActions: [
        'Check checkout error logs',
        'Review recent deployments',
        'Verify payment gateway status'
      ],
      status: 'unresolved',
      assignedTo: null
    }
  ],
  summary: {
    total: 12,
    bySeverity: { critical: 2, high: 5, medium: 5 },
    byMetric: { conversions: 4, revenue: 3, sessions: 5 }
  }
}

// Configure data quality rules
await pxlpeak.analytics.dataQuality.configure({
  validation: {
    // Required event properties
    requiredProperties: {
      'page_view': ['page_path', 'page_title'],
      'purchase': ['order_id', 'revenue', 'currency'],
      'signup': ['user_id', 'email']
    },

    // Property type validation
    propertyTypes: {
      'revenue': 'number',
      'order_id': 'string',
      'quantity': 'integer',
      'email': 'email',
      'url': 'url'
    },

    // Value constraints
    constraints: {
      'revenue': { min: 0, max: 1000000 },
      'quantity': { min: 1, max: 100 },
      'page_path': { pattern: '^/' }
    }
  },

  // Anomaly detection for data quality
  anomalyDetection: {
    enabled: true,
    metrics: [
      'events_per_minute',
      'unique_users_per_hour',
      'error_rate'
    ],
    alertThreshold: 3 // Standard deviations
  },

  // Actions on validation failure
  onValidationFailure: {
    action: 'flag', // drop, flag, transform
    logLevel: 'warning',
    notify: ['data-team@company.com']
  }
});

// Get data quality report
const qualityReport = await pxlpeak.analytics.dataQuality.report({
  dateRange: { start: '2026-01-01', end: '2026-01-31' }
});

// Response
{
  summary: {
    totalEvents: 5420000,
    validEvents: 5380000,
    invalidEvents: 40000,
    validationRate: 99.26
  },
  issues: [
    {
      type: 'missing_property',
      event: 'purchase',
      property: 'currency',
      occurrences: 15000,
      percentage: 0.28,
      recommendation: 'Add currency to purchase event tracking'
    },
    {
      type: 'invalid_value',
      event: 'purchase',
      property: 'revenue',
      issue: 'Negative values detected',
      occurrences: 250,
      recommendation: 'Validate revenue is positive before tracking'
    }
  ],
  trends: {
    validationRateTrend: 'improving', // +0.5% vs previous period
    topNewIssues: [],
    resolvedIssues: ['missing_user_id on signup events']
  }
}

// Optimize query performance
const optimizedQuery = await pxlpeak.analytics.query({
  // ... query configuration ...

  // Performance options
  performance: {
    // Use sampling for large datasets
    sampling: {
      enabled: true,
      rate: 0.1, // 10% sample
      confidence: 0.95
    },

    // Query hints
    hints: {
      useCache: true,
      cacheTTL: 3600,      // Cache for 1 hour
      maxExecutionTime: 30000, // 30 second timeout
      preferApproximate: false // Use exact counts
    },

    // Pagination for large results
    streaming: {
      enabled: false,
      batchSize: 1000
    }
  }
});

// Get query performance metrics
const queryMetrics = await pxlpeak.analytics.performance.getQueryMetrics({
  dateRange: { start: '2026-01-01', end: '2026-01-07' }
});

// {
//   totalQueries: 45000,
//   avgResponseTime: 85, // ms
//   p50ResponseTime: 45,
//   p95ResponseTime: 250,
//   p99ResponseTime: 800,
//   cacheHitRate: 78.5,
//   slowQueries: 120, // > 1000ms
//   failedQueries: 5
// }

// Configure precomputed aggregations for common queries
await pxlpeak.analytics.aggregations.configure({
  aggregations: [
    {
      name: 'daily_channel_metrics',
      dimensions: ['date', 'channel'],
      metrics: ['sessions', 'conversions', 'revenue'],
      refreshInterval: 'hourly'
    },
    {
      name: 'hourly_realtime',
      dimensions: ['hour', 'page_path'],
      metrics: ['pageviews', 'unique_visitors'],
      refreshInterval: 'realtime'
    },
    {
      name: 'weekly_cohorts',
      dimensions: ['cohort_week', 'return_week'],
      metrics: ['users', 'retention_rate'],
      refreshInterval: 'daily'
    }
  ]
});

// REST API example
const response = await fetch('https://api.pxlpeak.com/v1/analytics/query', {
  method: 'POST',
  headers: {
    'Authorization': `Bearer ${API_KEY}`,
    'Content-Type': 'application/json'
  },
  body: JSON.stringify({
    dateRange: { start: '2026-01-01', end: '2026-01-31' },
    metrics: ['sessions', 'conversions', 'revenue'],
    dimensions: ['source', 'medium'],
    filters: [
      { field: 'country', operator: 'eq', value: 'US' }
    ],
    sort: [{ field: 'revenue', order: 'desc' }],
    limit: 100
  })
});

const data = await response.json();

// Export analytics data
const exportJob = await pxlpeak.analytics.export({
  // Query configuration
  query: {
    dateRange: { start: '2026-01-01', end: '2026-01-31' },
    metrics: ['sessions', 'pageviews', 'conversions', 'revenue'],
    dimensions: ['date', 'source', 'medium', 'campaign'],
    granularity: 'day'
  },

  // Export format
  format: 'csv', // csv, json, parquet, xlsx

  // Delivery
  delivery: {
    type: 'download', // download, email, s3, gcs, webhook
    // email: 'analyst@company.com',
    // s3: { bucket: 'exports', path: 'analytics/' }
  },

  // Options
  options: {
    includeHeaders: true,
    dateFormat: 'ISO8601',
    nullValue: '',
    compression: 'gzip'
  }
});

// Check export status
const status = await pxlpeak.analytics.export.status(exportJob.id);
// { status: 'completed', downloadUrl: '...', expiresAt: '...' }

## Analytics Implementation Checklist

### Data Collection
- [ ] Tracking code installed on all pages
- [ ] SPA navigation tracked correctly
- [ ] Custom events defined and documented
- [ ] User identification implemented
- [ ] E-commerce tracking configured
- [ ] Cross-domain tracking (if needed)

### Data Quality
- [ ] Required properties validated
- [ ] PII exclusion rules configured
- [ ] Bot filtering enabled
- [ ] Deduplication logic verified
- [ ] Data sampling settings reviewed

### Dashboards & Reports
- [ ] Executive dashboard created
- [ ] Team-specific dashboards built
- [ ] Scheduled reports configured
- [ ] Alerts set up for key metrics
- [ ] Anomaly detection enabled

### Integration
- [ ] CRM integration configured
- [ ] Ad platform connections active
- [ ] Data warehouse export enabled
- [ ] API access tested

### Governance
- [ ] Access permissions defined
- [ ] Data retention policy set
- [ ] Audit logging enabled
- [ ] Documentation maintained

## Query Performance Best Practices

### Date Ranges
- Use shorter date ranges for faster queries
- Avoid "all time" queries in dashboards
- Cache results for historical data

### Dimensions & Metrics
- Limit to 5-7 dimensions per query
- Use pre-aggregated metrics when possible
- Avoid high-cardinality dimensions in real-time

### Filters
- Apply filters early in the query
- Use indexed dimensions for filtering
- Avoid regex filters on large datasets

### Sampling
- Enable sampling for exploration
- Disable for final reports
- Monitor query times and adjust