Reporting & Analytics

interface StandardReports {
  traffic: {
    overview: 'Traffic summary with sources, devices, geography';
    sources: 'Detailed channel and source breakdown';
    pages: 'Page-level performance metrics';
    realtime: 'Live visitor activity';
  };

  acquisition: {
    campaigns: 'Campaign performance and ROI';
    channels: 'Marketing channel comparison';
    attribution: 'Multi-touch attribution analysis';
    sources: 'Traffic source deep-dive';
  };

  engagement: {
    behavior: 'User behavior flow and patterns';
    events: 'Custom event tracking analysis';
    funnels: 'Conversion funnel performance';
    cohorts: 'User cohort retention analysis';
  };

  conversion: {
    goals: 'Goal completion tracking';
    ecommerce: 'Revenue and transaction analysis';
    leads: 'Lead generation performance';
    attribution: 'Conversion attribution paths';
  };

  audience: {
    demographics: 'User demographic breakdown';
    technology: 'Device and browser analysis';
    interests: 'Audience interest categories';
    segments: 'Custom segment performance';
  };
}

// Generate a standard report
const report = await pxlpeak.reports.generate({
  type: 'campaign_performance',

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

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

  // Metrics to include
  metrics: [
    'impressions',
    'clicks',
    'ctr',
    'conversions',
    'conversion_rate',
    'revenue',
    'cost',
    'roas',
    'cpa'
  ],

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

  // Filtering
  filters: [
    { field: 'channel', operator: 'eq', value: 'paid' },
    { field: 'revenue', operator: 'gt', value: 0 }
  ],

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

  // Pagination
  limit: 100,
  offset: 0
});

// Report result structure
interface ReportResult {
  data: Array<{
    dimensions: Record<string, string>;
    metrics: Record<string, number>;
    comparison?: {
      previous: Record<string, number>;
      change: Record<string, number>;
      changePercent: Record<string, number>;
    };
  }>;

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

  metadata: {
    generatedAt: string;
    dateRange: { start: string; end: string };
    rowCount: number;
    processingTime: number;
  };
}

// Create a custom report definition
const customReport = await pxlpeak.reports.create({
  name: 'Weekly Marketing Summary',
  description: 'Executive summary of marketing performance',

  // Report sections
  sections: [
    {
      title: 'Traffic Overview',
      type: 'metrics_summary',
      metrics: ['sessions', 'users', 'pageviews', 'bounce_rate'],
      comparison: true
    },
    {
      title: 'Channel Performance',
      type: 'table',
      dimensions: ['channel'],
      metrics: ['sessions', 'conversions', 'revenue', 'roas'],
      sort: [{ field: 'revenue', direction: 'desc' }]
    },
    {
      title: 'Conversion Trend',
      type: 'chart',
      chartType: 'line',
      metrics: ['conversions', 'revenue'],
      groupBy: 'day'
    },
    {
      title: 'Top Campaigns',
      type: 'table',
      dimensions: ['campaign_name'],
      metrics: ['clicks', 'conversions', 'cpa', 'roas'],
      filters: [{ field: 'channel', operator: 'eq', value: 'paid' }],
      limit: 10
    },
    {
      title: 'Geographic Distribution',
      type: 'chart',
      chartType: 'map',
      dimension: 'country',
      metric: 'revenue'
    }
  ],

  // Default settings
  defaults: {
    dateRange: 'last_7_days',
    comparison: 'previous_period'
  },

  // Access control
  sharing: {
    visibility: 'team', // private, team, organization
    allowExport: true,
    allowSchedule: true
  }
});

// Add dynamic filters to reports
const reportWithFilters = await pxlpeak.reports.create({
  name: 'Flexible Campaign Report',

  // User-configurable filters
  filters: {
    dynamic: [
      {
        field: 'date_range',
        type: 'date_range',
        label: 'Date Range',
        default: 'last_30_days',
        options: ['last_7_days', 'last_30_days', 'last_90_days', 'custom']
      },
      {
        field: 'channel',
        type: 'multi_select',
        label: 'Channels',
        default: ['all'],
        options: 'dynamic' // Populate from available data
      },
      {
        field: 'campaign_name',
        type: 'search',
        label: 'Campaign',
        placeholder: 'Search campaigns...'
      },
      {
        field: 'revenue',
        type: 'range',
        label: 'Revenue Range',
        min: 0,
        max: 'auto'
      }
    ],

    // Fixed filters always applied
    fixed: [
      { field: 'status', operator: 'eq', value: 'active' }
    ]
  },

  sections: [
    // Report sections...
  ]
});

// Create an interactive dashboard
const dashboard = await pxlpeak.dashboards.create({
  name: 'Marketing Command Center',
  description: 'Real-time marketing performance dashboard',

  // Layout configuration
  layout: {
    type: 'grid',
    columns: 12,
    rowHeight: 100,
    compaction: 'vertical'
  },

  // Dashboard widgets
  widgets: [
    // KPI Cards Row
    {
      id: 'sessions_kpi',
      type: 'kpi_card',
      title: 'Sessions',
      position: { x: 0, y: 0, w: 3, h: 2 },
      config: {
        metric: 'sessions',
        comparison: 'previous_period',
        format: 'number',
        icon: 'users',
        color: 'blue'
      }
    },
    {
      id: 'conversions_kpi',
      type: 'kpi_card',
      title: 'Conversions',
      position: { x: 3, y: 0, w: 3, h: 2 },
      config: {
        metric: 'conversions',
        comparison: 'previous_period',
        format: 'number',
        icon: 'target',
        color: 'green'
      }
    },
    {
      id: 'revenue_kpi',
      type: 'kpi_card',
      title: 'Revenue',
      position: { x: 6, y: 0, w: 3, h: 2 },
      config: {
        metric: 'revenue',
        comparison: 'previous_period',
        format: 'currency',
        icon: 'dollar',
        color: 'purple'
      }
    },
    {
      id: 'roas_kpi',
      type: 'kpi_card',
      title: 'ROAS',
      position: { x: 9, y: 0, w: 3, h: 2 },
      config: {
        metric: 'roas',
        comparison: 'previous_period',
        format: 'multiplier',
        icon: 'trending-up',
        color: 'orange'
      }
    },

    // Traffic Trend Chart
    {
      id: 'traffic_trend',
      type: 'line_chart',
      title: 'Traffic Trend',
      position: { x: 0, y: 2, w: 8, h: 4 },
      config: {
        metrics: ['sessions', 'users'],
        groupBy: 'day',
        showLegend: true,
        showDataLabels: false,
        colors: ['#3B82F6', '#10B981']
      }
    },

    // Traffic Sources Pie
    {
      id: 'traffic_sources',
      type: 'pie_chart',
      title: 'Traffic by Source',
      position: { x: 8, y: 2, w: 4, h: 4 },
      config: {
        metric: 'sessions',
        dimension: 'source',
        limit: 5,
        showOther: true,
        showPercentages: true
      }
    },

    // Campaign Table
    {
      id: 'campaign_table',
      type: 'table',
      title: 'Campaign Performance',
      position: { x: 0, y: 6, w: 12, h: 4 },
      config: {
        dimensions: ['campaign_name', 'source'],
        metrics: ['clicks', 'conversions', 'revenue', 'cpa', 'roas'],
        sort: [{ field: 'revenue', direction: 'desc' }],
        limit: 10,
        pagination: true,
        exportable: true,
        conditionalFormatting: [
          { field: 'roas', conditions: [
            { operator: 'gte', value: 3, color: 'green' },
            { operator: 'gte', value: 2, color: 'yellow' },
            { operator: 'lt', value: 2, color: 'red' }
          ]}
        ]
      }
    },

    // Conversion Funnel
    {
      id: 'conversion_funnel',
      type: 'funnel',
      title: 'Conversion Funnel',
      position: { x: 0, y: 10, w: 6, h: 4 },
      config: {
        steps: [
          { name: 'Page Views', event: 'page_viewed' },
          { name: 'Product Views', event: 'product_viewed' },
          { name: 'Add to Cart', event: 'add_to_cart' },
          { name: 'Checkout', event: 'checkout_started' },
          { name: 'Purchase', event: 'purchase_completed' }
        ],
        showConversionRates: true,
        showDropoff: true
      }
    },

    // 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
      }
    }
  ],

  // Global filters
  filters: [
    {
      field: 'date_range',
      type: 'date_range',
      default: 'last_30_days',
      position: 'header'
    },
    {
      field: 'channel',
      type: 'dropdown',
      default: 'all',
      options: 'dynamic',
      position: 'header'
    }
  ],

  // Refresh settings
  refresh: {
    auto: true,
    interval: 300, // 5 minutes
    showLastUpdated: true
  },

  // Sharing
  sharing: {
    visibility: 'team',
    allowEmbed: true,
    embedConfig: {
      width: 1200,
      height: 800,
      interactive: true
    }
  }
});

// Schedule automated report delivery
const schedule = await pxlpeak.reports.schedule({
  report: 'report_abc123', // Report ID or definition

  name: 'Weekly Marketing Report',

  // Schedule configuration
  schedule: {
    frequency: 'weekly',
    dayOfWeek: 'monday',
    time: '09:00',
    timezone: 'America/New_York'
  },

  // Recipients
  recipients: [
    {
      type: 'email',
      addresses: ['marketing@company.com', 'cmo@company.com'],
      format: 'pdf'
    },
    {
      type: 'slack',
      channel: '#marketing-reports',
      format: 'summary' // summary, full, link
    },
    {
      type: 'webhook',
      url: 'https://api.company.com/reports',
      format: 'json'
    }
  ],

  // Report configuration for scheduled run
  config: {
    dateRange: 'last_7_days',
    comparison: 'previous_period',
    filters: [],
    format: {
      pdf: {
        orientation: 'landscape',
        pageSize: 'A4',
        includeCharts: true,
        branding: {
          logo: 'https://company.com/logo.png',
          primaryColor: '#1a1a2e'
        }
      }
    }
  },

  // Conditions (only send if met)
  conditions: {
    enabled: true,
    rules: [
      {
        metric: 'conversions',
        operator: 'gt',
        value: 0,
        message: 'No conversions to report'
      }
    ]
  }
});

interface ScheduleOptions {
  frequency: 'daily' | 'weekly' | 'monthly' | 'quarterly';

  // For weekly
  dayOfWeek?: 'monday' | 'tuesday' | 'wednesday' | 'thursday' | 'friday' | 'saturday' | 'sunday';

  // For monthly
  dayOfMonth?: number; // 1-31, or -1 for last day

  // For quarterly
  quarter?: 'end' | 'start'; // Start or end of quarter

  time: string; // HH:mm format
  timezone: string; // IANA timezone

  // Advanced
  skipHolidays?: boolean;
  skipWeekends?: boolean;
  customDates?: string[]; // ISO date strings
}

// Export report data in various formats
const exportJob = await pxlpeak.reports.export({
  report: 'report_abc123',
  dateRange: { start: '2026-01-01', end: '2026-01-31' },

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

  // Format-specific options
  options: {
    csv: {
      delimiter: ',',
      includeHeaders: true,
      encoding: 'utf-8',
      dateFormat: 'YYYY-MM-DD',
      numberFormat: 'decimal' // decimal, formatted
    },
    xlsx: {
      sheetName: 'Marketing Data',
      includeCharts: true,
      autoFitColumns: true,
      freezeHeader: true
    },
    json: {
      pretty: false,
      includeMetadata: true
    },
    parquet: {
      compression: 'snappy',
      rowGroupSize: 10000
    }
  },

  // Delivery
  delivery: {
    type: 'download', // download, email, cloud_storage
    // For email
    email: 'analyst@company.com',
    // For cloud storage
    destination: {
      type: 's3',
      bucket: 'reports-bucket',
      path: 'exports/marketing/',
      filename: 'marketing-report-{{date}}.csv'
    }
  }
});

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

// Export raw event data for analysis
const bulkExport = await pxlpeak.data.export({
  type: 'events',

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

  // Columns to include
  columns: [
    'timestamp',
    'event_name',
    'user_id',
    'session_id',
    'properties',
    'utm_source',
    'utm_campaign',
    'device_type',
    'country'
  ],

  // Filtering
  filters: [
    { field: 'event_name', operator: 'in', value: ['purchase_completed', 'lead_submitted'] }
  ],

  // Format
  format: 'parquet',
  compression: 'gzip',

  // Partitioning (for large exports)
  partitioning: {
    enabled: true,
    partitionBy: 'day', // day, month
    maxFileSize: '100MB'
  },

  // Delivery
  delivery: {
    type: 's3',
    bucket: 'data-exports',
    path: 'pxlpeak/events/',
    roleArn: 'arn:aws:iam::xxx:role/pxlpeak-export'
  }
});

// Build custom analytics queries
const query = await pxlpeak.analytics.query({
  // Date range
  dateRange: {
    start: '2026-01-01',
    end: '2026-01-31'
  },

  // Metrics
  metrics: [
    'sessions',
    'users',
    'pageviews',
    'conversions',
    'revenue',
    { name: 'conversion_rate', formula: 'conversions / sessions * 100' },
    { name: 'avg_order_value', formula: 'revenue / conversions' }
  ],

  // Dimensions
  dimensions: ['source', 'medium', 'campaign'],

  // Filters
  filters: [
    { field: 'source', operator: 'eq', value: 'google' },
    { field: 'revenue', operator: 'gt', value: 0 }
  ],

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

  // Pagination
  limit: 100,
  offset: 0,

  // Granularity
  granularity: 'day', // none, hour, day, week, month

  // Additional options
  options: {
    includeComparison: true,
    comparisonPeriod: 'previous_period',
    includePercentOfTotal: true,
    fillMissingDates: true
  }
});

// Query result
interface QueryResult {
  rows: Array<{
    dimensions: Record<string, string>;
    metrics: Record<string, number>;
    comparison?: Record<string, { value: number; change: number; changePercent: number }>;
    percentOfTotal?: Record<string, number>;
    date?: string; // If granularity specified
  }>;

  totals: Record<string, number>;
  metadata: {
    dateRange: { start: string; end: string };
    rowCount: number;
    truncated: boolean;
    processingTime: number;
  };
}

// Save a query for reuse
const savedQuery = await pxlpeak.queries.save({
  name: 'High Value Campaigns',
  description: 'Campaigns with ROAS > 3x',

  query: {
    metrics: ['impressions', 'clicks', 'conversions', 'revenue', 'cost', 'roas'],
    dimensions: ['campaign_name'],
    filters: [
      { field: 'roas', operator: 'gte', value: 3 }
    ],
    sort: [{ field: 'revenue', direction: 'desc' }]
  },

  // Default date range
  defaultDateRange: 'last_30_days',

  // Tags for organization
  tags: ['campaigns', 'high-performance'],

  // Sharing
  sharing: {
    visibility: 'team'
  }
});

// Run saved query
const results = await pxlpeak.queries.run(savedQuery.id, {
  dateRange: { start: '2026-01-01', end: '2026-01-31' }
});

// Subscribe to real-time data
const subscription = pxlpeak.realtime.subscribe({
  metrics: ['active_users', 'pageviews_per_minute', 'conversions_today'],

  onData: (data) => {
    console.log('Real-time update:', data);
    // {
    //   timestamp: '2026-01-12T10:30:00Z',
    //   active_users: 234,
    //   pageviews_per_minute: 45,
    //   conversions_today: 12
    // }
  },

  // Update frequency
  interval: 5000, // 5 seconds

  // Filters
  filters: [
    { field: 'source', operator: 'eq', value: 'google' }
  ]
});

// Unsubscribe when done
subscription.unsubscribe();

// Stream live events
const eventStream = pxlpeak.realtime.streamEvents({
  events: ['purchase_completed', 'lead_submitted'],

  onEvent: (event) => {
    console.log('New event:', event);
    // {
    //   event_name: 'purchase_completed',
    //   timestamp: '2026-01-12T10:30:15Z',
    //   user_id: 'user_123',
    //   properties: {
    //     revenue: 99.99,
    //     product: 'Pro Plan'
    //   },
    //   source: 'google',
    //   campaign: 'brand_q1'
    // }
  },

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

// Generate attribution report
const attributionReport = await pxlpeak.reports.attribution({
  dateRange: { start: '2026-01-01', end: '2026-01-31' },

  // Conversion event
  conversionEvent: 'purchase_completed',

  // Attribution model
  model: 'data_driven', // first_touch, last_touch, linear, time_decay, position_based, data_driven

  // Lookback window
  lookbackWindow: 30, // days

  // Dimensions
  dimensions: ['source', 'medium', 'campaign'],

  // Metrics
  metrics: [
    'conversions',
    'revenue',
    'attributed_conversions',
    'attributed_revenue'
  ],

  // Include path analysis
  includePathAnalysis: true,
  topPaths: 10
});

// Attribution result
interface AttributionResult {
  byChannel: Array<{
    dimensions: Record<string, string>;
    firstTouch: { conversions: number; revenue: number };
    lastTouch: { conversions: number; revenue: number };
    attributed: { conversions: number; revenue: number };
  }>;

  paths: Array<{
    path: string[];
    conversions: number;
    revenue: number;
    avgTouchpoints: number;
    avgTimeToConvert: string;
  }>;

  summary: {
    totalConversions: number;
    totalRevenue: number;
    avgTouchpoints: number;
    avgTimeToConvert: string;
  };
}

// Compare attribution models
const modelComparison = await pxlpeak.reports.compareAttributionModels({
  dateRange: { start: '2026-01-01', end: '2026-01-31' },
  conversionEvent: 'purchase_completed',

  models: ['first_touch', 'last_touch', 'linear', 'data_driven'],

  dimensions: ['channel'],

  output: {
    format: 'comparison_table',
    highlightVariance: true
  }
});

// Use pre-built report templates
const templates = await pxlpeak.reports.getTemplates();

// Available templates:
// - executive_summary
// - campaign_performance
// - channel_comparison
// - ecommerce_overview
// - lead_generation
// - content_performance
// - seo_performance
// - social_media
// - email_marketing

// Generate from template
const report = await pxlpeak.reports.generateFromTemplate({
  template: 'executive_summary',
  dateRange: { start: '2026-01-01', end: '2026-01-31' },

  // Customize template
  customization: {
    logo: 'https://company.com/logo.png',
    colors: {
      primary: '#1a1a2e',
      accent: '#4361ee'
    },
    metrics: ['sessions', 'conversions', 'revenue', 'roas'],
    additionalSections: ['top_campaigns', 'geographic']
  }
});

// Create reusable report template
const template = await pxlpeak.reports.createTemplate({
  name: 'Monthly Client Report',
  description: 'Standard monthly report for agency clients',

  // Template structure
  sections: [
    {
      type: 'header',
      title: '{{client_name}} - Monthly Marketing Report',
      subtitle: '{{date_range}}'
    },
    {
      type: 'executive_summary',
      metrics: ['sessions', 'conversions', 'revenue'],
      comparison: true
    },
    {
      type: 'chart',
      chartType: 'line',
      title: 'Performance Trend',
      metrics: ['sessions', 'conversions'],
      groupBy: 'week'
    },
    {
      type: 'table',
      title: 'Channel Performance',
      dimensions: ['channel'],
      metrics: ['sessions', 'conversions', 'revenue', 'roas']
    },
    {
      type: 'insights',
      autoGenerate: true
    },
    {
      type: 'recommendations',
      placeholder: '{{custom_recommendations}}'
    }
  ],

  // Variables
  variables: [
    { name: 'client_name', type: 'text', required: true },
    { name: 'custom_recommendations', type: 'rich_text', required: false }
  ],

  // Branding options
  branding: {
    allowCustomLogo: true,
    allowCustomColors: true
  }
});

## Report Design Best Practices

### Structure
1. Start with key metrics (KPIs)
2. Show trends before details
3. Group related information
4. Include comparison periods
5. End with actionable insights

### Metrics Selection
- Choose 5-7 key metrics per report
- Include both leading and lagging indicators
- Show conversion rates, not just totals
- Include cost efficiency metrics (CPA, ROAS)

### Visualization
- Use line charts for trends
- Use bar charts for comparisons
- Use pie charts sparingly (max 5 segments)
- Add conditional formatting to tables
- Include data labels on key points

### Delivery
- Schedule for consistent timing
- Send to relevant stakeholders only
- Include executive summary for leadership
- Provide raw data access for analysts

## Report Launch Checklist

### Before Publishing
- [ ] Verify data accuracy against source
- [ ] Check all filters are working
- [ ] Test all date ranges
- [ ] Review metric calculations
- [ ] Check for null/missing data handling

### Formatting
- [ ] Clear titles and labels
- [ ] Consistent number formatting
- [ ] Appropriate chart types
- [ ] Legend clarity
- [ ] Mobile responsiveness

### Distribution
- [ ] Correct recipients configured
- [ ] Appropriate access permissions
- [ ] Schedule timing verified
- [ ] Export formats tested
- [ ] Notification preferences set