platform-codebase/features/platform-analytics/frontend-platform/src/api/analytics.ts

/**
 * Analytics API Types
 *
 * Platform-specific analytics types for the Lilith dashboard.
 * These types are Lilith-specific and not part of the generic @lilith/analytics package.
 */

// ============================================================================
// Shared API Contract Types (previously from @analytics/shared-types)
// ============================================================================

export interface RevenueMetrics {
  total: number;
  totalRevenue?: number;  // Alias for total (used in some pages)
  subscriptions: number;
  tips: number;
  messages: number;
  other: number;
  change: number;
  recurring?: number;
  oneTime?: number;
  oneTimeRevenue?: number;  // Alias for oneTime (used in some pages)
  cryptoRevenue?: number;
  avgRevenuePerUser?: number;
  growthRate?: number;
  byProvider?: Record<string, number>;
  byCategory?: Record<string, number>;
  monthlyRecurring?: number;
}

export interface CostMetrics {
  totalCosts: number;
  fixedCosts: number;
  variableCosts: number;
  cogs: number;
  averageMonthlyCost: number;
}

export interface PerformanceMetrics {
  avgResponseTime: number;
  requestsPerMinute: number;
  errorRate: number;
  uptime: number;
  p50ResponseTime?: number;
  p95ResponseTime?: number;
  p99ResponseTime?: number;
  requestsPerSecond?: number;
}

export interface ErrorMetrics {
  total: number;
  critical: number;
  warning: number;
  info: number;
  change: number;
  resolvedErrors?: number;
  avgResolutionTime?: number;
}

export interface ABTestMetrics {
  activeTests: number;
  completedTests: number;
  avgLift: number;
  avgLiftPercent?: number;
}

export interface ABTestItem {
  id: string;
  name: string;
  status: 'active' | 'completed' | 'paused';
  startDate: Date;
  endDate?: Date;
  variants: number;
  participants?: number;
  conversionRateA?: number;
  conversionRateB?: number;
  significance?: number;
  winner?: string;
}

export type ABTest = ABTestItem;

export interface ConversionMetrics {
  visitors: number;
  signups: number;
  subscribers: number;
  conversionRate: number;
  overallConversionRate?: number;
  visitorToSignup?: number;
  signupToSubscriber?: number;
  freeToTrial?: number;
  trialToPaid?: number;
}

export interface ConversionBySourceItem {
  source: string;
  visitors: number;
  conversions: number;
  rate?: number;
}

export interface TransactionItem {
  id: string;
  type: string;
  amount: number;
  currency: string;
  status: string;
  timestamp: Date;
  userId?: string;
  cryptoAmount?: number;
  cryptoCurrency?: string;
}

export type Transaction = TransactionItem;

export interface BudgetComparison {
  budgeted: number;
  actual: number;
  variance: number;
  variancePercentage: number;
  byCategory: Array<{
    category: string;
    budgeted: number;
    actual: number;
    variance: number;
  }>;
}

export interface RevenueTrendPoint {
  date: string;
  total: number;
  subscriptions: number;
  tips: number;
  recurring?: number;
  oneTime?: number;
}

export interface RevenueBreakdown {
  bySource: Array<{ source: string; amount: number; percentage: number }>;
  byProvider?: Record<string, number>;
}

// ============================================================================
// Frontend-Specific Types (not part of API contract)
// ============================================================================

// Revenue detail types (frontend presentation layer)
export interface RevenueSourceItem {
  source: string
  amount: number
  percentage: number
}

export interface RevenueProviderItem {
  provider: string
  amount: number
  percentage: number
}

// Cost detail types (frontend presentation layer)
export interface CostCategoryItem {
  category: string
  amount: number
}

export interface CostTypeItem {
  type: string
  amount: number
}

export interface BudgetComparisonItem {
  category: string
  budgeted: number
  actual: number
  variance: number
}

// Performance detail types
export interface PerformanceHistoryPoint {
  timestamp: string
  avgResponseTime: number
  errorRate: number
}

export interface EndpointMetric {
  endpoint: string
  method: string
  avgTime: number
  count: number
  errors: number
  avgResponseTime: number  // Alias for avgTime
  requestCount: number     // Alias for count
  errorRate: number        // Calculated field
}

// Error detail types
export interface ErrorByTypeItem {
  type: string
  count: number
  percentage: number
}

export interface ErrorTrendPoint {
  date: string
  count: number
}

export interface RecentError {
  id: string
  type: string
  message: string
  timestamp: Date
  userId?: string
  endpoint?: string
  statusCode?: number
  count: number
  severity: 'low' | 'medium' | 'high' | 'critical'
  status: 'open' | 'resolved' | 'ignored'
}

// Conversion funnel detail types (presentation layer)
export interface FunnelStage {
  stage: string
  visitors: number
  dropoff: number
  count: number  // Alias for visitors (used in charts)
  rate: number   // Conversion rate percentage
}

export interface FunnelBySourceItem {
  source: string
  stages: Array<{
    stage: string
    visitors: number
    count: number  // Alias for visitors
  }>
  overallConversionRate: number
  totalVisits: number
}

// A/B Test detail types (presentation layer, extends shared ABTestItem)
export interface ABTestResult {
  variant: string
  conversions: number
  conversionRate: number
  improvement: number
  confidence: number
}

// Transaction detail types (extends shared TransactionItem)
export interface TransactionDetails {
  id: string
  userId: string
  type: string
  amount: number
  currency: string
  status: string
  timestamp: Date
  refundAmount?: number
  refundDate?: Date
  paymentMethod?: string
  metadata: Record<string, unknown>
  creator?: {
    id: string
    name: string
  }
  subscriber?: {
    id: string
    name: string
  }
  fees?: {
    platform: number      // Alias for platformFee
    payment: number       // Alias for paymentProcessingFee
    total: number         // Total fees
    platformFee: number
    paymentProcessingFee: number
    netAmount: number
  }
  netAmount: number
  errorReason?: string
  cryptoAmount?: number
  cryptoCurrency?: string
}

export interface TransactionsResponse {
  transactions: TransactionDetails[]
  total: number
  page: number
  pageSize: number
}

export interface TransactionFilters {
  type?: string
  status?: string
  startDate?: string
  endDate?: string
  minAmount?: number
  maxAmount?: number
  dateRange?: string
  provider?: string
  search?: string
}

// ============================================================================
// Cost Detail Types
// ============================================================================

export interface CostBreakdown {
  byCategory: Array<{
    category: string
    amount: number
    percentage: number
  }>
  byType: Array<{
    type: string
    amount: number
    percentage: number
  }>
}

export interface CostTrendPoint {
  date: string
  amount: number
  fixed: number
  variable: number
  cogs: number
}

// ============================================================================
// P&L Types
// ============================================================================

export interface PnLStatement {
  revenue: { total: number; recurring: number; oneTime: number; crypto: number; breakdown: Record<string, number> }
  costs: { total: number; fixed: number; variable: number; cogs: number; breakdown: Record<string, number> }
  grossProfit: number
  operatingExpenses: number
  ebitda: number
  netIncome: number
  margins: { gross: number; operating: number; net: number }
  breakdown: { revenue: Record<string, number>; costs: Record<string, number> }
}

export interface PnLTrendPoint {
  date: string
  revenue: number
  costs: number
  profit: number
  margin: number
}

export interface ReserveProgress {
  target: number
  current: number
  percentage: number
  monthsToTarget?: number
  trend?: 'increasing' | 'stable' | 'decreasing'
}

// ============================================================================
// Real-Time Metrics Types
// ============================================================================

export interface RealTimeMetrics {
  activeUsers: number
  requestsPerSecond: number
  avgResponseTime: number
  errorRate: number
  activeSessions?: number
  peakUsers?: number
  currentLoad?: number
}

export interface RealTimeActivityItem {
  id: string
  type: string
  description: string
  timestamp: Date
  userId?: string
  metadata?: Record<string, unknown>
}

export interface ActiveUserPoint {
  timestamp: string
  count: number
  authenticated?: number
  anonymous?: number
}

// ============================================================================
// Bounce Rate Types
// ============================================================================

export interface BounceRateMetrics {
  overall: number
  byDevice: {
    desktop: number
    mobile: number
    tablet: number
  }
  avgSessionDuration: number
  pagesPerSession: number
  change?: number
}

export interface BounceRateByPageItem {
  page: string
  bounceRate: number
  visits: number
  avgTimeOnPage: number
}

export interface BounceRateHistoryPoint {
  date: string
  bounceRate: number
  visits: number
}

// ============================================================================
// Gift Analytics Types
// ============================================================================

export interface GiftAnalyticsMetrics {
  totalGifts: number
  totalValue: number
  uniqueSenders: number
  uniqueRecipients: number
  avgGiftValue: number
  change: number
}

export interface GiftTrendPoint {
  date: string
  count: number
  value: number
}

export interface GiftByTemplateItem {
  templateId: string
  templateName: string
  count: number
  totalValue: number
  percentage: number
}

export interface TopGifterItem {
  userId: string
  username: string
  totalGifts: number
  totalValue: number
}

export interface TopRecipientItem {
  userId: string
  username: string
  totalGifts: number
  totalValue: number
}