# saas-metrics

SaaS subscription-finance and recurring-revenue metrics pack for founders, RevOps, growth analysts and investors modelling a subscription business: compute Monthly Recurring Revenue (mrr) and Annual...


SaaS subscription-finance intelligence pack. Deterministic recurring-revenue, unit-economics and
board-metric math for founders, RevOps and investors, with an optional AI commentary layer on the
cohort and Rule-of-40 tools that activates only when a model is reachable (and silently falls back to
the heuristic core otherwise).

**Estimates for planning/benchmarking only — not financial or investment advice.**

## Tools

| Tool | Args | Does |
|---|---|---|
| `mrr` | `{mrr \| customers,arpu \| plans[]}` | Monthly Recurring Revenue (+ ARR). Build from a flat number, customers×ARPU, or a `plans:[{price,customers,period}]` array. |
| `arr` | `{arr \| mrr \| plans[]}` | Annual Recurring Revenue (+ implied MRR). |
| `arpu` | `{revenue, customers, expansion?, contraction?}` | Average revenue per user/account, net of expansion/contraction. |
| `ltv` | `{arpu, churn, grossMargin?}` | Lifetime value = ARPU × margin ÷ churn (constant-churn geometric model) + avg lifetime. |
| `churnRate` | `{startCustomers, lostCustomers, newCustomers?}` | Churn %, retention %, end count, net change. |
| `retentionCohort` | `{cohorts:[{sizes:[…]}], options?}` | Per-cohort retention %, averaged curve, stabilization flag. `options.advise` adds an AI read. |
| `quickRatio` | `{newMrr, expansionMrr, churnedMrr, contractionMrr}` | SaaS Quick Ratio (growth efficiency) + grade. |
| `magicNumber` | `{newArr \| currentArr,priorArr; salesMarketingSpend}` | Sales Magic Number (efficiency) + implied payback. |
| `ruleOf40` | `{growthRate, profitMargin, options?}` | Rule of 40 score, pass/fail, growth-vs-profit profile. `options.advise` adds an AI verdict. |
| `netRevenueRetention` | `{startingMrr, expansionMrr, contractionMrr, churnedMrr}` | NRR + GRR %, ending MRR, grade. |
| `cac` | `{spend, newCustomers \| channels[]}` | Blended CAC, or per-channel CAC sorted cheapest-first. |
| `paybackMonths` | `{cac, arpu, grossMargin?}` | CAC payback period in months + grade. |

The two tools with an AI path (`retentionCohort`, `ruleOf40`) tag their result `{ mode: 'heuristic' | 'llm' }`.

## Example

```js
import pack from './index.js';
await pack.adapters.ltv({ arpu: 100, churn: 0.05, grossMargin: 0.8 });
// { ltv: 1600, arpu:100, churnRate:0.05, grossMargin:0.8, avgLifetimeMonths:20, … }

await pack.adapters.netRevenueRetention({ startingMrr: 100000, expansionMrr: 15000, contractionMrr: 4000, churnedMrr: 6000 });
// { nrrPct:105, grrPct:90, endingMrr:105000, grade:'net-expanding', … }

await pack.adapters.quickRatio({ newMrr: 40000, expansionMrr: 10000, churnedMrr: 8000, contractionMrr: 2000 });
// { quickRatio:5, addedMrr:50000, lostMrr:10000, grade:'excellent', … }
```

## DRY boundaries

- **`finance`** owns time-value-of-money (NPV, IRR, loan amortization, discounted cash flow);
  **`numbers`** owns generic scalar math and series stats; **`tax`** owns income-tax withholding;
  **`invoice`** owns billing documents. This pack owns *subscription-business composition* —
  recurring-revenue aggregation, cohort retention, unit economics (LTV/CAC/payback) and the SaaS board
  ratios (Quick Ratio, Magic Number, Rule of 40, NRR/GRR) — which none of those own.
- Self-contained: the only cross-pack import is `../_shared/llm.js` for the optional AI layer.

## Hybrid intelligence

Every deterministic core runs offline with no model. `retentionCohort` and `ruleOf40` accept
`options.advise:true` to request LLM commentary; with no model configured/reachable they return the
exact same numbers tagged `mode:'heuristic'`. A down model never throws.


---
Source: shared/engines/adapters/domain/saas-metrics/README.md
Canonical: https://docs.leumas.tech/p/adapters/domain/saas-metrics