Customer Engagement Metrics That Matter

interface EngagementMetric {
  id: string;
  name: string;
  level: "health" | "diagnostic" | "operational";
  definition: string;
  formula: string;
  owner: string;
  refreshFrequency: "real-time" | "hourly" | "daily" | "weekly";
  thresholds: MetricThreshold[];
}
 
interface MetricThreshold {
  direction: "above" | "below";
  value: number;
  severity: "info" | "warning" | "critical";
  action: string;
}
 
const engagementMetrics: EngagementMetric[] = [
  {
    id: "mau",
    name: "Monthly Active Users",
    level: "health",
    definition: "Unique customers with at least one meaningful interaction in the last 30 days",
    formula: "COUNT(DISTINCT customer_id) WHERE last_interaction_date >= NOW() - INTERVAL '30 days'",
    owner: "product-team",
    refreshFrequency: "daily",
    thresholds: [
      { direction: "below", value: 0.9, severity: "warning", action: "Investigate by segment" },
      { direction: "below", value: 0.8, severity: "critical", action: "Emergency retention review" },
    ],
  },
  {
    id: "activation-rate",
    name: "30-Day Activation Rate",
    level: "diagnostic",
    definition: "Percentage of new customers who complete a key action within 30 days of signup",
    formula: "COUNT(activated_in_30d) / COUNT(new_signups) * 100",
    owner: "growth-team",
    refreshFrequency: "daily",
    thresholds: [
      { direction: "below", value: 60, severity: "warning", action: "Review onboarding funnel" },
    ],
  },
  {
    id: "campaign-ctr",
    name: "Campaign Click-Through Rate",
    level: "operational",
    definition: "Percentage of delivered campaign messages that received a click",
    formula: "COUNT(clicked) / COUNT(delivered) * 100",
    owner: "crm-team",
    refreshFrequency: "real-time",
    thresholds: [
      { direction: "below", value: 2, severity: "info", action: "Review targeting and content" },
    ],
  },
];

interface ActivityWeight {
  eventType: string;
  weight: number;
  description: string;
}
 
const activityWeights: ActivityWeight[] = [
  { eventType: "transaction.completed", weight: 10, description: "Completed a financial transaction" },
  { eventType: "payment.initiated", weight: 8, description: "Initiated a payment" },
  { eventType: "balance.checked", weight: 3, description: "Checked account balance" },
  { eventType: "feature.used", weight: 5, description: "Used a product feature" },
  { eventType: "app.opened", weight: 1, description: "Opened the application" },
  { eventType: "notification.clicked", weight: 2, description: "Clicked a notification" },
  { eventType: "support.contacted", weight: 4, description: "Contacted customer support" },
];
 
interface EngagementScore {
  customerId: string;
  period: { start: Date; end: Date };
  rawScore: number;
  normalizedScore: number; // 0-100
  activityBreakdown: Array<{
    eventType: string;
    count: number;
    weightedScore: number;
  }>;
  trend: "improving" | "stable" | "declining";
}
 
function computeEngagementScore(
  customerId: string,
  events: CustomerEvent[],
  weights: ActivityWeight[],
  period: { start: Date; end: Date }
): EngagementScore {
  const periodEvents = events.filter(
    (e) =>
      e.customerId === customerId &&
      e.timestamp >= period.start &&
      e.timestamp <= period.end
  );
 
  const weightMap = new Map(weights.map((w) => [w.eventType, w.weight]));
  const breakdown = new Map<string, { count: number; weightedScore: number }>();
 
  let rawScore = 0;
  for (const event of periodEvents) {
    const weight = weightMap.get(event.eventType) ?? 0;
    rawScore += weight;
 
    const existing = breakdown.get(event.eventType) ?? {
      count: 0,
      weightedScore: 0,
    };
    existing.count++;
    existing.weightedScore += weight;
    breakdown.set(event.eventType, existing);
  }
 
  return {
    customerId,
    period,
    rawScore,
    normalizedScore: Math.min(100, rawScore), // Cap at 100
    activityBreakdown: Array.from(breakdown.entries()).map(
      ([eventType, data]) => ({
        eventType,
        ...data,
      })
    ),
    trend: "stable", // Computed by comparing with previous period
  };
}
 
interface CustomerEvent {
  customerId: string;
  eventType: string;
  timestamp: Date;
  payload: Record<string, unknown>;
}

interface RetentionCohort {
  cohortMonth: string;
  initialSize: number;
  retentionByMonth: Map<number, number>; // month offset -> retained count
}
 
interface RetentionTable {
  cohorts: RetentionCohort[];
  averageRetentionByMonth: Map<number, number>;
}
 
function buildRetentionTable(
  customers: Array<{ id: string; signupDate: Date }>,
  activityMonths: Map<string, Set<string>> // month -> set of active customer IDs
): RetentionTable {
  const cohortMap = new Map<string, string[]>();
 
  // Group customers by signup month
  for (const customer of customers) {
    const cohortKey = formatMonth(customer.signupDate);
    const existing = cohortMap.get(cohortKey) ?? [];
    existing.push(customer.id);
    cohortMap.set(cohortKey, existing);
  }
 
  const cohorts: RetentionCohort[] = [];
 
  for (const [cohortMonth, customerIds] of cohortMap) {
    const retentionByMonth = new Map<number, number>();
    const cohortDate = parseMonth(cohortMonth);
 
    for (let monthOffset = 0; monthOffset <= 12; monthOffset++) {
      const targetMonth = addMonths(cohortDate, monthOffset);
      const targetKey = formatMonth(targetMonth);
      const activeInMonth = activityMonths.get(targetKey) ?? new Set();
 
      const retainedCount = customerIds.filter((id) =>
        activeInMonth.has(id)
      ).length;
      retentionByMonth.set(monthOffset, retainedCount);
    }
 
    cohorts.push({
      cohortMonth,
      initialSize: customerIds.length,
      retentionByMonth,
    });
  }
 
  // Compute average retention curve
  const averageRetentionByMonth = new Map<number, number>();
  for (let monthOffset = 0; monthOffset <= 12; monthOffset++) {
    const rates = cohorts
      .filter((c) => c.retentionByMonth.has(monthOffset))
      .map(
        (c) => c.retentionByMonth.get(monthOffset)! / c.initialSize
      );
    if (rates.length > 0) {
      averageRetentionByMonth.set(
        monthOffset,
        rates.reduce((a, b) => a + b, 0) / rates.length
      );
    }
  }
 
  return { cohorts, averageRetentionByMonth };
}
 
function formatMonth(date: Date): string {
  return `${date.getFullYear()}-${String(date.getMonth() + 1).padStart(2, "0")}`;
}
 
function parseMonth(month: string): Date {
  const [year, m] = month.split("-").map(Number);
  return new Date(year, m - 1, 1);
}
 
function addMonths(date: Date, months: number): Date {
  const result = new Date(date);
  result.setMonth(result.getMonth() + months);
  return result;
}

interface FeatureAdoption {
  customerId: string;
  features: Map<string, FeatureUsage>;
  adoptionScore: number;
  nextBestFeature: string | null;
}
 
interface FeatureUsage {
  featureName: string;
  firstUsedAt: Date | null;
  lastUsedAt: Date | null;
  usageCount30d: number;
  adopted: boolean; // Used at least N times
}
 
function computeFeatureAdoption(
  customerId: string,
  allFeatures: string[],
  usageData: Map<string, FeatureUsage>,
  adoptionThreshold: number = 3
): FeatureAdoption {
  const features = new Map<string, FeatureUsage>();
 
  for (const featureName of allFeatures) {
    const usage = usageData.get(featureName) ?? {
      featureName,
      firstUsedAt: null,
      lastUsedAt: null,
      usageCount30d: 0,
      adopted: false,
    };
    usage.adopted = usage.usageCount30d >= adoptionThreshold;
    features.set(featureName, usage);
  }
 
  const adoptedCount = Array.from(features.values()).filter(
    (f) => f.adopted
  ).length;
  const adoptionScore = (adoptedCount / allFeatures.length) * 100;
 
  // Determine next best feature to recommend
  const unadopted = Array.from(features.values())
    .filter((f) => !f.adopted)
    .sort((a, b) => b.usageCount30d - a.usageCount30d);
 
  const nextBestFeature =
    unadopted.length > 0 ? unadopted[0].featureName : null;
 
  return {
    customerId,
    features,
    adoptionScore,
    nextBestFeature,
  };
}