ai-roi-calculator

A typed TypeScript library for answering the question every business asks before an AI automation project: "Will this actually pay for itself?"

Feed it four numbers you already know — hours saved, what those hours cost, what the automation costs to build, and what it costs to run — and get back the payback period, net savings, and a sensitivity range that keeps the estimate honest.

Why this exists

Most AI project pitches lead with capabilities; buyers decide on payback. The math is not hard, but it's done ad hoc in throwaway spreadsheets — with inconsistent assumptions (52 working weeks, base wage instead of fully-loaded cost) and a single rosy point estimate. This library makes the model explicit, tested, and reusable:

• Fully-loaded hourly cost and 48 working weeks/year as defaults you can override, not silent assumptions.
• Sensitivity range built in — the number people overestimate most is hours saved, so every estimate can be bracketed by pessimistic and optimistic scenarios.
• Honest edge cases — a tool whose subscription eats the savings reports paybackMonths: null, not a misleading number.

Install

npm install ai-roi-calculator
# or
pnpm add ai-roi-calculator

Zero dependencies. Ships ESM and CJS with TypeScript declarations.

Usage

import { calculateRoi } from 'ai-roi-calculator';

const result = calculateRoi({
  hoursSavedPerWeek: 10, // manual work eliminated
  hourlyCost: 50, // fully-loaded cost of the people doing it
  implementationCost: 5000, // one-time build/rollout cost
  monthlySubscriptionCost: 200, // recurring subscriptions, API usage, hosting
});

console.log(result);
// {
//   grossMonthlySavings: 2000,
//   netMonthlySavings: 1800,
//   annualNetSavings: 21600,
//   paybackMonths: 2.78,       // ~12 weeks to break even
//   firstYearRoiPercent: 332,
//   firstYearNetValue: 16600,
//   threeYearNetValue: 59800
// }

Sensitivity range

Point estimates oversell. sensitivityRange varies hours saved ±25% (or a variation you choose) and returns all three scenarios:

import { sensitivityRange } from 'ai-roi-calculator';

const { pessimistic, expected, optimistic } = sensitivityRange({
  hoursSavedPerWeek: 10,
  hourlyCost: 50,
  implementationCost: 5000,
  monthlySubscriptionCost: 200,
});

console.log(pessimistic.paybackMonths); // 3.85  (7.5 h/week saved)
console.log(expected.paybackMonths); // 2.78  (10 h/week)
console.log(optimistic.paybackMonths); // 2.17  (12.5 h/week)

So the pitch becomes: "even if we only hit 75% of the estimate, this pays back in under 4 months."

Options and edge cases

• weeksPerYear (default 48) — annualization basis; set 52 if the work truly never stops.
• paybackMonths is null when net savings are zero or negative (the investment never pays back), and 0 when there's no implementation cost.
• firstYearRoiPercent is null when implementationCost is 0 (the ratio is undefined).
• Negative or non-finite inputs throw a typed InvalidInputError with a field property naming the offending input.

Full input/output shapes are documented in the exported types: RoiInputs, RoiResult, SensitivityOptions, SensitivityRange.

Web demo

An interactive Next.js demo lives in demo/:

git clone https://github.com/brutusdev0/ai-roi-calculator.git
cd ai-roi-calculator
pnpm install
pnpm --filter ai-roi-calculator-demo dev

Then open http://localhost:3000 — adjust the inputs and watch the payback period and pessimistic/optimistic range update live.

Development

pnpm install
pnpm test        # Vitest suite
pnpm run lint    # ESLint
pnpm run build   # tsup → dist/ (ESM + CJS + d.ts)

License

MIT © Rick (brutusdev0)