《独立开发者的商业指南·收入与财务工程》7.3 续约、扩张与收缩收入

NRR = (19,280 + 310 − 60 − 290) ÷ 19,280 = 99.79%
GRR = (19,280 − 60 − 290) ÷ 19,280 = 98.18%

GRR = (期初收入 − 收缩 − 流失) ÷ 期初收入
NRR = (期初收入 + 扩张 − 收缩 − 流失) ÷ 期初收入

月度 NRR 99.79% → 年化 99.79%^12 = 97.51%
月度 GRR 98.18% → 年化 98.18%^12 = 80.22%

混合 GRR = 72.7% × 70.0% + 27.3% × 69.38%
         = 50.89% + 18.94%
         = 69.83%

// file: src/unit/nrr.ts
// tier: L1
// verify: node --test test/unit/nrr.test.ts

import { type Cents, sub } from "../core/money.ts";
import { type Bps, divide } from "../core/rate.ts";
import { type Result, fail, ok } from "../core/result.ts";

export type RevenueBridge = {
  startingCents: Cents;
  newCents: Cents;
  expansionCents: Cents;
  contractionCents: Cents;
  churnCents: Cents;
};

export type RetentionMetrics = {
  startingCents: Cents;
  endingCents: Cents;
  newCents: Cents;
  expansionCents: Cents;
  contractionCents: Cents;
  churnCents: Cents;
  nrrBps: Bps;
  grrBps: Bps;
  expansionBps: Bps;
  contractionBps: Bps;
  churnBps: Bps;
  netChangeCents: Cents;
};

export type RetentionBand = "expanding" | "stable" | "leaking" | "critical";
export type GrrBand = "strong" | "moderate" | "weak";

function isCents(value: number): boolean {
  return Number.isInteger(value) && value >= 0;
}

/**
 * NRR and GRR exclude new customers. The starting cohort can expand,
 * contract or churn; new logos are added to the ending balance but
 * never enter the retention ratios.
 */
export function buildRetention(
  bridge: RevenueBridge,
): Result<RetentionMetrics> {
  const amounts: [string, Cents][] = [
    ["starting", bridge.startingCents],
    ["new", bridge.newCents],
    ["expansion", bridge.expansionCents],
    ["contraction", bridge.contractionCents],
    ["churn", bridge.churnCents],
  ];
  for (const [label, amount] of amounts) {
    if (!isCents(amount)) {
      return fail(`${label} must be a non-negative integer number of cents`);
    }
  }
  if (bridge.startingCents <= 0) {
    return fail("starting revenue must be positive");
  }
  if (bridge.contractionCents + bridge.churnCents > bridge.startingCents) {
    return fail("contraction plus churn cannot exceed starting revenue");
  }
  const existingChange = sub(
    bridge.expansionCents,
    bridge.contractionCents + bridge.churnCents,
  );
  const ending =
    bridge.startingCents + bridge.newCents + existingChange;
  if (ending < 0) {
    return fail("bridge produces a negative ending balance");
  }
  const retained = bridge.startingCents - bridge.contractionCents - bridge.churnCents;
  return ok({
    startingCents: bridge.startingCents,
    endingCents: ending,
    newCents: bridge.newCents,
    expansionCents: bridge.expansionCents,
    contractionCents: bridge.contractionCents,
    churnCents: bridge.churnCents,
    nrrBps: divide(retained + bridge.expansionCents, bridge.startingCents),
    grrBps: divide(retained, bridge.startingCents),
    expansionBps: divide(bridge.expansionCents, bridge.startingCents),
    contractionBps: divide(bridge.contractionCents, bridge.startingCents),
    churnBps: divide(bridge.churnCents, bridge.startingCents),
    netChangeCents: existingChange,
  });
}

/** Geometric annualization: a 99.79% month is 97.51% for the year, not 12 x 99.79%. */
export function annualizeRetention(
  periodBps: Bps,
  periodMonths: number,
): Result<Bps> {
  if (
    !Number.isInteger(periodBps) ||
    periodBps < 0 ||
    periodBps > 100000
  ) {
    return fail("period retention must be an integer between 0 and 100000 bps");
  }
  if (
    !Number.isInteger(periodMonths) ||
    periodMonths <= 0 ||
    periodMonths > 120
  ) {
    return fail("period months must be an integer between 1 and 120");
  }
  const annual = Math.pow(periodBps / 10000, 12 / periodMonths) * 10000;
  return ok(Math.round(annual));
}

/** Convert an annual retention rate to a shorter period with the same geometric path. */
export function periodRetention(
  annualBps: Bps,
  months: number,
): Result<Bps> {
  if (
    !Number.isInteger(annualBps) ||
    annualBps < 0 ||
    annualBps > 100000
  ) {
    return fail("annual retention must be an integer between 0 and 100000 bps");
  }
  if (!Number.isInteger(months) || months <= 0 || months > 120) {
    return fail("months must be an integer between 1 and 120");
  }
  const period = Math.pow(annualBps / 10000, months / 12) * 10000;
  return ok(Math.round(period));
}

export function nrrBand(nrrBps: Bps): RetentionBand {
  if (nrrBps >= 11000) return "expanding";
  if (nrrBps >= 10000) return "stable";
  if (nrrBps >= 9000) return "leaking";
  return "critical";
}

export function grrBand(grrBps: Bps): GrrBand {
  if (grrBps >= 9000) return "strong";
  if (grrBps >= 8000) return "moderate";
  return "weak";
}