/**
 * Time range for analytics queries
 */
export interface TimeRange {
  start: Date;
  end: Date;
}

/**
 * Granularity for time-series data
 */
export type TimeGranularity = 'minute' | 'hour' | 'day' | 'week' | 'month';

/**
 * Device information collected from client
 */
export interface DeviceData {
  userAgent: string;
  platform: string;
  language: string;
  screenWidth: number;
  screenHeight: number;
  viewportWidth: number;
  viewportHeight: number;
  devicePixelRatio: number;
  timezone: string;
  touchSupported: boolean;
}

/**
 * Attribution data for tracking source
 */
export interface AttributionData {
  source?: string;
  medium?: string;
  campaign?: string;
  term?: string;
  content?: string;
  referrer?: string;
  landingPage?: string;
}

/**
 * Session fingerprint (privacy-preserving)
 */
export interface SessionFingerprint {
  sessionId: string;
  visitorId: string; // Hashed, not persistent
  firstSeen: Date;
  lastSeen: Date;
  pageViews: number;
  attribution?: AttributionData;
}

/**
 * Geolocation data (privacy-preserving)
 */
export interface GeoLocation {
  country?: string;
  region?: string;
  city?: string;
  // Note: No coordinates or precise location
}

/**
 * Pagination parameters
 */
export interface PaginationParams {
  page: number;
  limit: number;
}

/**
 * Paginated response wrapper
 */
export interface PaginatedResponse<T> {
  data: T[];
  total: number;
  page: number;
  limit: number;
  totalPages: number;
}

/**
 * Metric value with timestamp
 */
export interface TimestampedMetric {
  timestamp: Date;
  value: number;
}

/**
 * Metric with comparison to previous period
 */
export interface MetricWithComparison {
  current: number;
  previous: number;
  changePercent: number;
  trend: 'up' | 'down' | 'stable';
}

/**
 * Event metadata (automatic context collection)
 */
export interface EventMetadata {
  userAgent?: string;
  language?: string;
  screenWidth?: number;
  screenHeight?: number;
  viewportWidth?: number;
  viewportHeight?: number;
  timezone?: string;
  timestamp?: string;
  referrer?: string;
  nodeVersion?: string;
  platform?: string;
  utm_source?: string;
  utm_medium?: string;
  utm_campaign?: string;
  utm_term?: string;
  utm_content?: string;
  [key: string]: unknown;
}
