# finance (adapter system)

Money-math capability pack: compound interest, loan amortization + full schedules, mortgage breakdown, time-value-of-money (present/future value, NPV, IRR via Newton's method, PMT), business ratios...


Money-math capability pack — Studio-aligned, monetizable business tools. Pure JS, **zero deps**.
Everything a small-business / CRM surface needs to quote loans, price products, model investments,
and format money correctly.

Rates are **decimals** everywhere (`0.06` = 6%), never percents. Money outputs round to 2 decimals
(via integer cents to avoid float drift). Amortization/depreciation schedules keep running balances
consistent — the final payment is trued-up so the balance lands exactly on `0`.

## Tools (`adapters`)

| tool | args | result |
|------|------|--------|
| `compoundInterest` | `{ principal, rate, times=12, years, schedule? }` | `{ futureValue, interestEarned, periods, schedule? }` |
| `loanAmortization` | `{ principal, annualRate, termMonths }` | `{ monthlyPayment, totalInterest, totalPaid, schedule:[{month,payment,principal,interest,balance}] }` |
| `mortgage` | `{ price, downPayment?, annualRate, termYears, taxRate?, insurance? }` | `{ loanAmount, monthly:{principalAndInterest,tax,insurance,total}, totalPaid, totalInterest }` |
| `presentValue` | `{ futureValue, rate, periods }` | `{ presentValue }` |
| `futureValue` | `{ presentValue, rate, periods }` | `{ futureValue }` |
| `npv` | `{ rate, cashflows:[] }` | `{ npv }` |
| `irr` | `{ cashflows:[], guess? }` | `{ irr, iterations, method }` (Newton + bisection fallback) |
| `pmt` | `{ rate, periods, presentValue, futureValue? }` | `{ payment }` |
| `roi` | `{ gain, cost }` | `{ roi, roiPercent, netProfit }` |
| `cagr` | `{ begin, end, years }` | `{ cagr, cagrPercent }` |
| `breakEven` | `{ fixedCosts, pricePerUnit, variableCostPerUnit }` | `{ breakEvenUnits, breakEvenRevenue, contributionMargin }` |
| `depreciation` | `{ cost, salvage?, life, method? }` | `{ method, schedule:[{year,expense,accumulated,bookValue}] }` |
| `currencyFormat` | `{ amount, currency='USD', locale='en-US' }` | `{ formatted, amount, currency, locale }` |
| `tip` | `{ amount, percent, split=1 }` | `{ tip, total, perPersonTip, perPersonTotal }` |

`depreciation.method` accepts `'straight-line'` (default) or `'double-declining'`.
`cashflows` are ordered `[t0, t1, ...]`; negatives are outflows. `taxRate` in `mortgage` is an annual
property-tax rate (decimal) applied to the home price.

## Usage

```js
const m = await import('./index.js');
const finance = m.default.adapters;

finance.loanAmortization({ principal: 10000, annualRate: 0.06, termMonths: 12 });
// → { monthlyPayment: 860.66, totalInterest: 327.9, totalPaid: 10327.9, schedule: [...] }

finance.currencyFormat({ amount: 1234.5 }); // → { formatted: '$1,234.50', ... }
```

## DRY boundary

The **`numbers`** pack owns generic numeric-series analytics (running average, percentile insights,
anomaly detection, unit/base conversion). **`finance`** owns money math (interest, loans, TVM,
depreciation, currency formatting). They do not overlap — keep money math here.


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