/**
 * Dashboard and shared analytics contracts.
 *
 * The wire shape for this feature. Imported by BOTH its route handlers and its
 * components, so a server/client drift is a type error rather than a runtime
 * surprise. When a real backend arrives, this file is the negotiation artifact.
 */

export type KpiId = 'visitors' | 'purchases' | 'revenue' | 'activeRewards';

export type KpiUnit = 'count' | 'inr' | 'lyt' | 'pct';

export interface Kpi {
  id: KpiId;
  label: string;
  value: number;
  unit: KpiUnit;
  /** Change against the previous comparable period. */
  deltaPct: number;
  /** Whether a rise is good. Churn rises are not. */
  isRiseGood: boolean;
  trend: {t: string; v: number}[];
}

export interface TimePoint {
  t: string;
  visitors: number;
  purchases: number;
  revenue: number;
  /** Purchases ÷ visitors, as a percentage. */
  conversion: number;
}

export interface HourCell {
  day: number;
  hour: number;
  value: number;
}

export type ActivityKind =
  | 'reward_redeemed'
  | 'staff_checked_in'
  | 'purchase'
  | 'reward_expired'
  | 'store_opened';

export interface ActivityEvent {
  id: string;
  at: string;
  kind: ActivityKind;
  title: string;
  detail?: string;
  storeId: string;
}

export interface StoreComparison {
  storeId: string;
  name: string;
  visitors: number;
  purchases: number;
  revenueInr: number;
  conversionPct: number;
  /** 14-point trend for the store's sparkline. */
  trend: {t: string; v: number}[];
}

export interface RewardUsagePoint {
  rewardId: string;
  name: string;
  claimed: number;
  used: number;
  /** used ÷ claimed, as a percentage. */
  usageRatePct: number;
}

export type Granularity = 'weekly' | 'monthly';

export interface PeriodPoint {
  /** Bucket label — "W32" or "Aug". */
  label: string;
  visitors: number;
  purchases: number;
  revenue: number;
}

export type InsightSeverity = 'info' | 'success' | 'warning' | 'error';

export interface Insight {
  id: string;
  severity: InsightSeverity;
  title: string;
  body: string;
  action?: {label: string; href: string};
}

export interface DashboardTask {
  id: string;
  label: string;
  detail?: string;
  /** Plain-language deadline — "before 18:00", "today". Never a raw date. */
  due: string;
  isDone: boolean;
  action?: {label: string; href: string};
}

export interface DashboardBriefing {
  /** One-paragraph narrative of the selected scope and period. */
  summary: string;
  /** Most severe first. */
  alerts: Insight[];
  tasks: DashboardTask[];
}
