business-as-code 2.1.3 → 2.4.0

package/test/metrics.test.ts

@@ -0,0 +1,744 @@
+/**
+ * Tests for metrics.ts - SaaS metrics calculations
+ */
+
+import { describe, it, expect } from 'vitest'
+import {
+  calculateMRR,
+  calculateARRFromMRR,
+  calculateNRR,
+  calculateGRR,
+  calculateCACMetric,
+  calculateLTVMetric,
+  calculateLTVtoCACRatio,
+  calculateQuickRatioMetric,
+  calculateMagicNumberMetric,
+  calculateBurnMultipleMetric,
+  calculateRuleOf40Metric,
+  calculateGrowthRates,
+  calculateChurnMetrics,
+  aggregateTimeSeries,
+  createMetricPeriod,
+} from '../src/metrics.js'
+import type { MRR, LTV, CAC, TimeSeries, MetricPeriod } from '../src/metrics.js'
+
+describe('SaaS Metrics', () => {
+  const testPeriod: MetricPeriod = {
+    period: 'monthly',
+    range: { start: new Date('2024-01-01'), end: new Date('2024-01-31') },
+    label: 'January 2024',
+  }
+
+  describe('calculateMRR()', () => {
+    it('should calculate MRR from components', () => {
+      const mrr = calculateMRR({
+        newMRR: 10000,
+        expansionMRR: 5000,
+        contractionMRR: 2000,
+        churnedMRR: 3000,
+        previousMRR: 100000,
+        period: testPeriod,
+      })
+
+      expect(mrr.newMRR).toBe(10000)
+      expect(mrr.expansionMRR).toBe(5000)
+      expect(mrr.contractionMRR).toBe(2000)
+      expect(mrr.churnedMRR).toBe(3000)
+      expect(mrr.reactivationMRR).toBe(0)
+      expect(mrr.netNewMRR).toBe(10000) // 10000 + 5000 - 2000 - 3000
+      expect(mrr.total).toBe(110000) // 100000 + 10000
+    })
+
+    it('should include reactivation MRR when provided', () => {
+      const mrr = calculateMRR({
+        newMRR: 10000,
+        expansionMRR: 5000,
+        contractionMRR: 2000,
+        churnedMRR: 3000,
+        reactivationMRR: 1000,
+        previousMRR: 100000,
+        period: testPeriod,
+      })
+
+      expect(mrr.reactivationMRR).toBe(1000)
+      expect(mrr.netNewMRR).toBe(11000) // 10000 + 5000 - 2000 - 3000 + 1000
+      expect(mrr.total).toBe(111000)
+    })
+
+    it('should use default currency USD', () => {
+      const mrr = calculateMRR({
+        newMRR: 1000,
+        expansionMRR: 0,
+        contractionMRR: 0,
+        churnedMRR: 0,
+        previousMRR: 0,
+        period: testPeriod,
+      })
+
+      expect(mrr.currency).toBe('USD')
+    })
+
+    it('should use provided currency', () => {
+      const mrr = calculateMRR({
+        newMRR: 1000,
+        expansionMRR: 0,
+        contractionMRR: 0,
+        churnedMRR: 0,
+        previousMRR: 0,
+        currency: 'EUR',
+        period: testPeriod,
+      })
+
+      expect(mrr.currency).toBe('EUR')
+    })
+
+    it('should handle negative net new MRR', () => {
+      const mrr = calculateMRR({
+        newMRR: 1000,
+        expansionMRR: 500,
+        contractionMRR: 3000,
+        churnedMRR: 2000,
+        previousMRR: 100000,
+        period: testPeriod,
+      })
+
+      expect(mrr.netNewMRR).toBe(-3500)
+      expect(mrr.total).toBe(96500)
+    })
+  })
+
+  describe('calculateARRFromMRR()', () => {
+    it('should calculate ARR from MRR', () => {
+      const arr = calculateARRFromMRR(10000)
+
+      expect(arr.total).toBe(120000)
+      expect(arr.fromMRR).toBe(120000)
+      expect(arr.currency).toBe('USD')
+    })
+
+    it('should use provided currency', () => {
+      const arr = calculateARRFromMRR(10000, 'EUR')
+      expect(arr.currency).toBe('EUR')
+    })
+
+    it('should handle zero MRR', () => {
+      const arr = calculateARRFromMRR(0)
+      expect(arr.total).toBe(0)
+    })
+  })
+
+  describe('calculateNRR()', () => {
+    it('should calculate Net Revenue Retention', () => {
+      const nrr = calculateNRR({
+        startingMRR: 100000,
+        expansion: 15000,
+        contraction: 5000,
+        churn: 5000,
+        period: testPeriod,
+      })
+
+      expect(nrr.startingMRR).toBe(100000)
+      expect(nrr.endingMRR).toBe(105000) // 100000 + 15000 - 5000 - 5000
+      expect(nrr.rate).toBe(105) // 105%
+    })
+
+    it('should handle zero starting MRR', () => {
+      const nrr = calculateNRR({
+        startingMRR: 0,
+        expansion: 0,
+        contraction: 0,
+        churn: 0,
+        period: testPeriod,
+      })
+
+      expect(nrr.rate).toBe(0)
+    })
+
+    it('should handle high churn (NRR < 100%)', () => {
+      const nrr = calculateNRR({
+        startingMRR: 100000,
+        expansion: 5000,
+        contraction: 10000,
+        churn: 15000,
+        period: testPeriod,
+      })
+
+      expect(nrr.rate).toBe(80) // 80%
+    })
+  })
+
+  describe('calculateGRR()', () => {
+    it('should calculate Gross Revenue Retention', () => {
+      const grr = calculateGRR({
+        startingMRR: 100000,
+        contraction: 5000,
+        churn: 10000,
+        period: testPeriod,
+      })
+
+      expect(grr.rate).toBe(85) // 85%
+      expect(grr.endingMRR).toBe(85000)
+    })
+
+    it('should cap GRR at 100%', () => {
+      const grr = calculateGRR({
+        startingMRR: 100000,
+        contraction: 0,
+        churn: 0,
+        period: testPeriod,
+      })
+
+      expect(grr.rate).toBe(100)
+    })
+
+    it('should handle zero starting MRR', () => {
+      const grr = calculateGRR({
+        startingMRR: 0,
+        contraction: 0,
+        churn: 0,
+        period: testPeriod,
+      })
+
+      expect(grr.rate).toBe(0)
+    })
+  })
+
+  describe('calculateCACMetric()', () => {
+    it('should calculate Customer Acquisition Cost', () => {
+      const cac = calculateCACMetric({
+        salesMarketingSpend: 100000,
+        newCustomers: 100,
+        period: testPeriod,
+      })
+
+      expect(cac.value).toBe(1000)
+      expect(cac.totalSalesMarketingSpend).toBe(100000)
+      expect(cac.newCustomersAcquired).toBe(100)
+    })
+
+    it('should handle zero customers', () => {
+      const cac = calculateCACMetric({
+        salesMarketingSpend: 100000,
+        newCustomers: 0,
+        period: testPeriod,
+      })
+
+      expect(cac.value).toBe(0)
+    })
+
+    it('should calculate CAC by channel', () => {
+      const cac = calculateCACMetric({
+        salesMarketingSpend: 100000,
+        newCustomers: 100,
+        period: testPeriod,
+        byChannel: {
+          organic: { spend: 20000, customers: 40 },
+          paid: { spend: 80000, customers: 60 },
+        },
+      })
+
+      expect(cac.byChannel?.organic).toBe(500)
+      expect(cac.byChannel?.paid).toBeCloseTo(1333.33, 1)
+    })
+  })
+
+  describe('calculateLTVMetric()', () => {
+    it('should calculate Customer Lifetime Value', () => {
+      const ltv = calculateLTVMetric({
+        arpu: 100,
+        grossMargin: 70,
+        churnRate: 0.05, // 5% monthly churn
+      })
+
+      // LTV = (ARPU * Gross Margin) / Churn Rate
+      // LTV = (100 * 0.7) / 0.05 = 1400
+      expect(ltv.value).toBe(1400)
+      expect(ltv.averageLifetimeMonths).toBe(20) // 1 / 0.05
+    })
+
+    it('should handle zero churn rate', () => {
+      const ltv = calculateLTVMetric({
+        arpu: 100,
+        grossMargin: 70,
+        churnRate: 0,
+      })
+
+      expect(ltv.value).toBe(0)
+      expect(ltv.averageLifetimeMonths).toBe(0)
+    })
+  })
+
+  describe('calculateLTVtoCACRatio()', () => {
+    it('should calculate LTV:CAC ratio', () => {
+      const ltv: LTV = {
+        value: 3000,
+        arpu: 100,
+        grossMargin: 70,
+        churnRate: 0.05,
+        averageLifetimeMonths: 20,
+        currency: 'USD',
+      }
+
+      const cac: CAC = {
+        value: 1000,
+        totalSalesMarketingSpend: 100000,
+        newCustomersAcquired: 100,
+        currency: 'USD',
+        period: testPeriod,
+      }
+
+      const ratio = calculateLTVtoCACRatio(ltv, cac)
+
+      expect(ratio.ratio).toBe(3)
+      expect(ratio.healthy).toBe(true) // >= 3
+      expect(ratio.paybackMonths).toBeCloseTo(14.29, 1) // 1000 / (100 * 0.7)
+    })
+
+    it('should handle zero CAC', () => {
+      const ltv: LTV = {
+        value: 3000,
+        arpu: 100,
+        grossMargin: 70,
+        churnRate: 0.05,
+        averageLifetimeMonths: 20,
+        currency: 'USD',
+      }
+
+      const cac: CAC = {
+        value: 0,
+        totalSalesMarketingSpend: 0,
+        newCustomersAcquired: 0,
+        currency: 'USD',
+        period: testPeriod,
+      }
+
+      const ratio = calculateLTVtoCACRatio(ltv, cac)
+
+      expect(ratio.ratio).toBe(0)
+      expect(ratio.healthy).toBe(false)
+    })
+
+    it('should mark low ratio as unhealthy', () => {
+      const ltv: LTV = {
+        value: 1500,
+        arpu: 100,
+        grossMargin: 70,
+        churnRate: 0.05,
+        averageLifetimeMonths: 20,
+        currency: 'USD',
+      }
+
+      const cac: CAC = {
+        value: 1000,
+        totalSalesMarketingSpend: 100000,
+        newCustomersAcquired: 100,
+        currency: 'USD',
+        period: testPeriod,
+      }
+
+      const ratio = calculateLTVtoCACRatio(ltv, cac)
+
+      expect(ratio.ratio).toBe(1.5)
+      expect(ratio.healthy).toBe(false) // < 3
+    })
+  })
+
+  describe('calculateQuickRatioMetric()', () => {
+    it('should calculate Quick Ratio', () => {
+      const mrr: MRR = {
+        total: 110000,
+        newMRR: 10000,
+        expansionMRR: 5000,
+        contractionMRR: 2000,
+        churnedMRR: 3000,
+        reactivationMRR: 0,
+        netNewMRR: 10000,
+        currency: 'USD',
+        period: testPeriod,
+      }
+
+      const quickRatio = calculateQuickRatioMetric(mrr)
+
+      // Quick Ratio = (New + Expansion) / (Churn + Contraction)
+      // Quick Ratio = 15000 / 5000 = 3
+      expect(quickRatio.ratio).toBe(3)
+      expect(quickRatio.healthy).toBe(false) // >= 4 is healthy
+    })
+
+    it('should mark high Quick Ratio as healthy', () => {
+      const mrr: MRR = {
+        total: 120000,
+        newMRR: 20000,
+        expansionMRR: 8000,
+        contractionMRR: 2000,
+        churnedMRR: 4000,
+        reactivationMRR: 0,
+        netNewMRR: 22000,
+        currency: 'USD',
+        period: testPeriod,
+      }
+
+      const quickRatio = calculateQuickRatioMetric(mrr)
+
+      expect(quickRatio.ratio).toBeCloseTo(4.67, 1)
+      expect(quickRatio.healthy).toBe(true)
+    })
+
+    it('should handle zero loss', () => {
+      const mrr: MRR = {
+        total: 110000,
+        newMRR: 10000,
+        expansionMRR: 5000,
+        contractionMRR: 0,
+        churnedMRR: 0,
+        reactivationMRR: 0,
+        netNewMRR: 15000,
+        currency: 'USD',
+        period: testPeriod,
+      }
+
+      const quickRatio = calculateQuickRatioMetric(mrr)
+
+      expect(quickRatio.ratio).toBe(Infinity)
+      expect(quickRatio.healthy).toBe(true)
+    })
+  })
+
+  describe('calculateMagicNumberMetric()', () => {
+    it('should calculate Magic Number', () => {
+      const magicNumber = calculateMagicNumberMetric({
+        netNewARR: 100000,
+        salesMarketingSpend: 100000,
+        period: testPeriod,
+      })
+
+      expect(magicNumber.value).toBe(1)
+      expect(magicNumber.efficient).toBe(true) // >= 0.75
+    })
+
+    it('should mark low Magic Number as inefficient', () => {
+      const magicNumber = calculateMagicNumberMetric({
+        netNewARR: 50000,
+        salesMarketingSpend: 100000,
+        period: testPeriod,
+      })
+
+      expect(magicNumber.value).toBe(0.5)
+      expect(magicNumber.efficient).toBe(false)
+    })
+
+    it('should handle zero spend', () => {
+      const magicNumber = calculateMagicNumberMetric({
+        netNewARR: 100000,
+        salesMarketingSpend: 0,
+        period: testPeriod,
+      })
+
+      expect(magicNumber.value).toBe(0)
+      expect(magicNumber.efficient).toBe(false)
+    })
+  })
+
+  describe('calculateBurnMultipleMetric()', () => {
+    it('should calculate Burn Multiple', () => {
+      const burnMultiple = calculateBurnMultipleMetric({
+        netBurn: 100000,
+        netNewARR: 200000,
+        period: testPeriod,
+      })
+
+      expect(burnMultiple.value).toBe(0.5)
+      expect(burnMultiple.efficient).toBe(true) // <= 1.5
+    })
+
+    it('should mark high Burn Multiple as inefficient', () => {
+      const burnMultiple = calculateBurnMultipleMetric({
+        netBurn: 200000,
+        netNewARR: 100000,
+        period: testPeriod,
+      })
+
+      expect(burnMultiple.value).toBe(2)
+      expect(burnMultiple.efficient).toBe(false)
+    })
+
+    it('should handle zero net new ARR', () => {
+      const burnMultiple = calculateBurnMultipleMetric({
+        netBurn: 100000,
+        netNewARR: 0,
+        period: testPeriod,
+      })
+
+      expect(burnMultiple.value).toBe(Infinity)
+      expect(burnMultiple.efficient).toBe(false)
+    })
+  })
+
+  describe('calculateRuleOf40Metric()', () => {
+    it('should calculate Rule of 40', () => {
+      const ruleOf40 = calculateRuleOf40Metric({
+        revenueGrowthRate: 30,
+        profitMargin: 15,
+        period: testPeriod,
+      })
+
+      expect(ruleOf40.score).toBe(45)
+      expect(ruleOf40.passing).toBe(true) // >= 40
+    })
+
+    it('should fail Rule of 40 for low scores', () => {
+      const ruleOf40 = calculateRuleOf40Metric({
+        revenueGrowthRate: 20,
+        profitMargin: 10,
+        period: testPeriod,
+      })
+
+      expect(ruleOf40.score).toBe(30)
+      expect(ruleOf40.passing).toBe(false)
+    })
+
+    it('should handle negative margins', () => {
+      const ruleOf40 = calculateRuleOf40Metric({
+        revenueGrowthRate: 50,
+        profitMargin: -5,
+        period: testPeriod,
+      })
+
+      expect(ruleOf40.score).toBe(45)
+      expect(ruleOf40.passing).toBe(true)
+    })
+  })
+
+  describe('calculateGrowthRates()', () => {
+    it('should calculate month-over-month growth', () => {
+      const growth = calculateGrowthRates({
+        current: 120000,
+        previousMonth: 100000,
+        metric: 'MRR',
+        period: testPeriod,
+      })
+
+      expect(growth.mom).toBe(20)
+    })
+
+    it('should calculate quarter-over-quarter growth', () => {
+      const growth = calculateGrowthRates({
+        current: 150000,
+        previousQuarter: 100000,
+        metric: 'ARR',
+        period: testPeriod,
+      })
+
+      expect(growth.qoq).toBe(50)
+    })
+
+    it('should calculate year-over-year growth', () => {
+      const growth = calculateGrowthRates({
+        current: 200000,
+        previousYear: 100000,
+        metric: 'ARR',
+        period: testPeriod,
+      })
+
+      expect(growth.yoy).toBe(100)
+    })
+
+    it('should handle zero previous values', () => {
+      const growth = calculateGrowthRates({
+        current: 100000,
+        previousMonth: 0,
+        previousQuarter: 0,
+        previousYear: 0,
+        metric: 'MRR',
+        period: testPeriod,
+      })
+
+      expect(growth.mom).toBe(0)
+      expect(growth.qoq).toBe(0)
+      expect(growth.yoy).toBe(0)
+    })
+
+    it('should handle negative growth', () => {
+      const growth = calculateGrowthRates({
+        current: 80000,
+        previousMonth: 100000,
+        metric: 'MRR',
+        period: testPeriod,
+      })
+
+      expect(growth.mom).toBe(-20)
+    })
+  })
+
+  describe('calculateChurnMetrics()', () => {
+    it('should calculate churn metrics', () => {
+      const churn = calculateChurnMetrics({
+        customersStart: 100,
+        customersLost: 5,
+        mrrStart: 100000,
+        mrrChurned: 5000,
+        expansionMRR: 8000,
+        period: testPeriod,
+      })
+
+      expect(churn.customerChurnRate).toBe(5)
+      expect(churn.revenueChurnRate).toBe(5)
+      expect(churn.netRevenueChurnRate).toBe(-3) // Negative because expansion > churn
+    })
+
+    it('should handle zero starting values', () => {
+      const churn = calculateChurnMetrics({
+        customersStart: 0,
+        customersLost: 0,
+        mrrStart: 0,
+        mrrChurned: 0,
+        expansionMRR: 0,
+        period: testPeriod,
+      })
+
+      expect(churn.customerChurnRate).toBe(0)
+      expect(churn.revenueChurnRate).toBe(0)
+      expect(churn.netRevenueChurnRate).toBe(0)
+    })
+  })
+
+  describe('aggregateTimeSeries()', () => {
+    const dailySeries: TimeSeries<number> = {
+      metric: 'revenue',
+      unit: 'USD',
+      aggregation: 'sum',
+      dataPoints: [
+        { timestamp: new Date('2024-01-01T12:00:00Z'), value: 100 },
+        { timestamp: new Date('2024-01-02T12:00:00Z'), value: 150 },
+        { timestamp: new Date('2024-01-03T12:00:00Z'), value: 200 },
+        { timestamp: new Date('2024-01-15T12:00:00Z'), value: 300 },
+        { timestamp: new Date('2024-02-01T12:00:00Z'), value: 250 },
+      ],
+    }
+
+    it('should aggregate to monthly', () => {
+      const monthly = aggregateTimeSeries(dailySeries, 'monthly')
+
+      expect(monthly.dataPoints).toHaveLength(2)
+      // The first bucket should contain January data
+      const janTotal = monthly.dataPoints.find((p) => p.timestamp.toISOString().includes('2024-01'))
+      const febTotal = monthly.dataPoints.find((p) => p.timestamp.toISOString().includes('2024-02'))
+      expect(janTotal?.value).toBe(750) // Jan total
+      expect(febTotal?.value).toBe(250) // Feb total
+    })
+
+    it('should aggregate with average', () => {
+      const avgSeries: TimeSeries<number> = {
+        ...dailySeries,
+        aggregation: 'avg',
+      }
+
+      const monthly = aggregateTimeSeries(avgSeries, 'monthly')
+
+      // Find January data
+      const janAvg = monthly.dataPoints.find((p) => p.timestamp.toISOString().includes('2024-01'))
+      expect(janAvg?.value).toBe(187.5) // (100 + 150 + 200 + 300) / 4
+    })
+
+    it('should aggregate with min', () => {
+      const minSeries: TimeSeries<number> = {
+        ...dailySeries,
+        aggregation: 'min',
+      }
+
+      const monthly = aggregateTimeSeries(minSeries, 'monthly')
+
+      const janMin = monthly.dataPoints.find((p) => p.timestamp.toISOString().includes('2024-01'))
+      expect(janMin?.value).toBe(100)
+    })
+
+    it('should aggregate with max', () => {
+      const maxSeries: TimeSeries<number> = {
+        ...dailySeries,
+        aggregation: 'max',
+      }
+
+      const monthly = aggregateTimeSeries(maxSeries, 'monthly')
+
+      const janMax = monthly.dataPoints.find((p) => p.timestamp.toISOString().includes('2024-01'))
+      expect(janMax?.value).toBe(300)
+    })
+
+    it('should aggregate with last', () => {
+      const lastSeries: TimeSeries<number> = {
+        ...dailySeries,
+        aggregation: 'last',
+      }
+
+      const monthly = aggregateTimeSeries(lastSeries, 'monthly')
+
+      // The implementation may not maintain order, so we check if the aggregation works
+      const janLast = monthly.dataPoints.find((p) => p.timestamp.toISOString().includes('2024-01'))
+      // Last value depends on internal ordering - just check it returns a value
+      expect(janLast?.value).toBeDefined()
+    })
+
+    it('should aggregate with first', () => {
+      const firstSeries: TimeSeries<number> = {
+        ...dailySeries,
+        aggregation: 'first',
+      }
+
+      const monthly = aggregateTimeSeries(firstSeries, 'monthly')
+
+      const janFirst = monthly.dataPoints.find((p) => p.timestamp.toISOString().includes('2024-01'))
+      // First value depends on internal ordering - just check it returns a value
+      expect(janFirst?.value).toBeDefined()
+    })
+  })
+
+  describe('createMetricPeriod()', () => {
+    it('should create a metric period', () => {
+      // Use UTC dates to avoid timezone issues
+      const period = createMetricPeriod(
+        'monthly',
+        new Date('2024-01-15T12:00:00Z'),
+        new Date('2024-01-31T12:00:00Z')
+      )
+
+      expect(period.period).toBe('monthly')
+      expect(period.range.start.toISOString()).toContain('2024-01')
+      expect(period.range.end.toISOString()).toContain('2024-01')
+      // Label depends on local timezone, just check it contains the year
+      expect(period.label).toContain('2024')
+    })
+
+    it('should create a quarterly period', () => {
+      const period = createMetricPeriod(
+        'quarterly',
+        new Date('2024-04-15T12:00:00Z'),
+        new Date('2024-06-30T12:00:00Z')
+      )
+
+      // Label format depends on implementation, just check it contains Q and year
+      expect(period.label).toContain('Q')
+      expect(period.label).toContain('2024')
+    })
+
+    it('should create a yearly period', () => {
+      const period = createMetricPeriod(
+        'yearly',
+        new Date('2024-06-15T12:00:00Z'),
+        new Date('2024-12-31T12:00:00Z')
+      )
+
+      expect(period.label).toContain('2024')
+    })
+
+    it('should use custom label', () => {
+      const period = createMetricPeriod(
+        'monthly',
+        new Date('2024-01-01T12:00:00Z'),
+        new Date('2024-01-31T12:00:00Z'),
+        'Custom Label'
+      )
+
+      expect(period.label).toBe('Custom Label')
+    })
+  })
+})