jaz-cli 2.3.0 → 2.5.0

package/dist/calc/format.js

@@ -0,0 +1,389 @@
+/**
+ * Output formatters for calc results.
+ * Table format for human reading, JSON for programmatic use.
+ *
+ * Currency-aware: when a result has a currency code, it appears in
+ * the title and summary lines (e.g. "Loan Amortization Schedule (SGD)").
+ */
+import chalk from 'chalk';
+const fmt = (n) => n.toLocaleString('en-US', { minimumFractionDigits: 2, maximumFractionDigits: 2 });
+const fmtR = (n) => fmt(n).padStart(14);
+const fmtPct = (n) => `${n}%`;
+const currTag = (c) => c ? ` (${c})` : '';
+const line = (w) => chalk.dim('─'.repeat(w));
+function printJournal(journal) {
+    console.log(chalk.dim(`    ${journal.description}`));
+    for (const l of journal.lines) {
+        if (l.debit > 0) {
+            console.log(chalk.dim(`      Dr ${l.account.padEnd(35)} ${fmt(l.debit)}`));
+        }
+        if (l.credit > 0) {
+            console.log(chalk.dim(`      Cr ${l.account.padEnd(35)}          ${fmt(l.credit)}`));
+        }
+    }
+}
+// ── Loan ──────────────────────────────────────────────────────────
+function printLoanTable(result) {
+    const W = 90;
+    console.log();
+    console.log(chalk.bold(`Loan Amortization Schedule${currTag(result.currency)}`));
+    console.log(line(W));
+    console.log(chalk.bold(`  Principal:      ${fmt(result.inputs.principal)}`));
+    console.log(chalk.bold(`  Annual Rate:    ${fmtPct(result.inputs.annualRate)}`));
+    console.log(chalk.bold(`  Term:           ${result.inputs.termMonths} months`));
+    console.log(chalk.bold(`  Monthly PMT:    ${fmt(result.monthlyPayment)}`));
+    console.log(line(W));
+    const header = [
+        'Period'.padStart(6),
+        result.inputs.startDate ? 'Date'.padStart(12) : null,
+        'Opening'.padStart(14),
+        'Payment'.padStart(14),
+        'Interest'.padStart(14),
+        'Principal'.padStart(14),
+        'Closing'.padStart(14),
+    ].filter(Boolean).join('  ');
+    console.log(chalk.dim(header));
+    console.log(line(W));
+    for (const row of result.schedule) {
+        const cols = [
+            String(row.period).padStart(6),
+            row.date ? row.date.padStart(12) : null,
+            fmtR(row.openingBalance),
+            fmtR(row.payment),
+            fmtR(row.interest),
+            fmtR(row.principal),
+            fmtR(row.closingBalance),
+        ].filter(Boolean).join('  ');
+        console.log(cols);
+    }
+    console.log(line(W));
+    const totalCols = [
+        'TOTAL'.padStart(6),
+        result.inputs.startDate ? ''.padStart(12) : null,
+        ''.padStart(14),
+        fmtR(result.totalPayments),
+        fmtR(result.totalInterest),
+        fmtR(result.totalPrincipal),
+        fmtR(0),
+    ].filter(Boolean).join('  ');
+    console.log(chalk.bold(totalCols));
+    console.log();
+    console.log(chalk.bold('Journal Entries'));
+    console.log(line(60));
+    console.log(chalk.dim('  Disbursement:'));
+    console.log(chalk.dim(`    Dr Cash / Bank Account${' '.repeat(14)}${fmt(result.inputs.principal)}`));
+    console.log(chalk.dim(`    Cr Loan Payable${' '.repeat(21)}     ${fmt(result.inputs.principal)}`));
+    console.log();
+    console.log(chalk.dim(`  Per period (example — Month 1):`));
+    printJournal(result.schedule[0].journal);
+    console.log();
+}
+// ── Lease ─────────────────────────────────────────────────────────
+function printLeaseTable(result) {
+    const W = 90;
+    console.log();
+    console.log(chalk.bold(`IFRS 16 Lease Schedule${currTag(result.currency)}`));
+    console.log(line(W));
+    console.log(chalk.bold(`  Monthly Payment:     ${fmt(result.inputs.monthlyPayment)}`));
+    console.log(chalk.bold(`  Lease Term:          ${result.inputs.termMonths} months`));
+    console.log(chalk.bold(`  Discount Rate (IBR): ${fmtPct(result.inputs.annualRate)}`));
+    console.log(chalk.bold(`  Present Value:       ${fmt(result.presentValue)}`));
+    console.log(chalk.bold(`  Monthly ROU Dep:     ${fmt(result.monthlyRouDepreciation)}`));
+    console.log(line(W));
+    console.log(chalk.bold('\nInitial Recognition'));
+    printJournal(result.initialJournal);
+    console.log(chalk.bold('\nLiability Unwinding Schedule'));
+    const header = [
+        'Period'.padStart(6),
+        result.inputs.startDate ? 'Date'.padStart(12) : null,
+        'Opening'.padStart(14),
+        'Payment'.padStart(14),
+        'Interest'.padStart(14),
+        'Principal'.padStart(14),
+        'Closing'.padStart(14),
+    ].filter(Boolean).join('  ');
+    console.log(chalk.dim(header));
+    console.log(line(W));
+    for (const row of result.schedule) {
+        const cols = [
+            String(row.period).padStart(6),
+            row.date ? row.date.padStart(12) : null,
+            fmtR(row.openingBalance),
+            fmtR(row.payment),
+            fmtR(row.interest),
+            fmtR(row.principal),
+            fmtR(row.closingBalance),
+        ].filter(Boolean).join('  ');
+        console.log(cols);
+    }
+    console.log(line(W));
+    const totalCols = [
+        'TOTAL'.padStart(6),
+        result.inputs.startDate ? ''.padStart(12) : null,
+        ''.padStart(14),
+        fmtR(result.totalCashPayments),
+        fmtR(result.totalInterest),
+        fmtR(result.presentValue),
+        fmtR(0),
+    ].filter(Boolean).join('  ');
+    console.log(chalk.bold(totalCols));
+    console.log();
+    console.log(chalk.bold('Monthly ROU Depreciation'));
+    console.log(chalk.dim(`  Dr Depreciation Expense — ROU${' '.repeat(8)}${fmt(result.monthlyRouDepreciation)}`));
+    console.log(chalk.dim(`  Cr Accumulated Depreciation — ROU${' '.repeat(4)}     ${fmt(result.monthlyRouDepreciation)}`));
+    console.log();
+    console.log(chalk.bold('Summary'));
+    console.log(`  Total cash payments:    ${fmt(result.totalCashPayments)}`);
+    console.log(`  Total interest expense: ${fmt(result.totalInterest)}`);
+    console.log(`  Total ROU depreciation: ${fmt(result.totalDepreciation)}`);
+    console.log(`  Total P&L impact:       ${fmt(result.totalInterest + result.totalDepreciation)}`);
+    console.log();
+}
+// ── Depreciation ──────────────────────────────────────────────────
+function printDepreciationTable(result) {
+    const isSL = result.inputs.method === 'sl';
+    const isMonthly = result.inputs.frequency === 'monthly';
+    const periodLabel = isMonthly ? 'Month' : 'Year';
+    const methodLabel = result.inputs.method.toUpperCase();
+    const W = isSL ? 72 : 100;
+    console.log();
+    console.log(chalk.bold(`${isSL ? 'Straight-Line' : 'Declining Balance'} Depreciation Schedule${isSL ? '' : ` (${methodLabel})`}${currTag(result.currency)}`));
+    console.log(line(W));
+    console.log(chalk.bold(`  Asset Cost:     ${fmt(result.inputs.cost)}`));
+    console.log(chalk.bold(`  Salvage Value:  ${fmt(result.inputs.salvageValue)}`));
+    console.log(chalk.bold(`  Useful Life:    ${result.inputs.usefulLifeYears} years`));
+    if (!isSL) {
+        const mult = result.inputs.method === 'ddb' ? 2 : 1.5;
+        console.log(chalk.bold(`  Method:         ${methodLabel} (${mult} / ${result.inputs.usefulLifeYears} = ${(mult / result.inputs.usefulLifeYears * 100).toFixed(1)}% per year)`));
+    }
+    console.log(line(W));
+    if (isSL) {
+        // Straight-line: simpler table — no DDB/SL comparison columns
+        const header = [
+            periodLabel.padStart(6),
+            'Opening BV'.padStart(14),
+            'Depreciation'.padStart(14),
+            'Closing BV'.padStart(14),
+        ].join('  ');
+        console.log(chalk.dim(header));
+        console.log(line(W));
+        for (const row of result.schedule) {
+            const cols = [
+                String(row.period).padStart(6),
+                fmtR(row.openingBookValue),
+                fmtR(row.depreciation),
+                fmtR(row.closingBookValue),
+            ].join('  ');
+            console.log(cols);
+        }
+    }
+    else {
+        // DDB/150DB: full comparison table
+        const header = [
+            periodLabel.padStart(6),
+            'Opening BV'.padStart(14),
+            'DDB'.padStart(14),
+            'SL'.padStart(14),
+            'Method'.padStart(8),
+            'Depreciation'.padStart(14),
+            'Closing BV'.padStart(14),
+        ].join('  ');
+        console.log(chalk.dim(header));
+        console.log(line(W));
+        for (const row of result.schedule) {
+            const cols = [
+                String(row.period).padStart(6),
+                fmtR(row.openingBookValue),
+                fmtR(row.ddbAmount),
+                fmtR(row.slAmount),
+                row.methodUsed.padStart(8),
+                fmtR(row.depreciation),
+                fmtR(row.closingBookValue),
+            ].join('  ');
+            console.log(cols);
+        }
+    }
+    console.log(line(W));
+    console.log(chalk.bold(`  Total depreciation: ${fmt(result.totalDepreciation)}  (cost ${fmt(result.inputs.cost)} − salvage ${fmt(result.inputs.salvageValue)})`));
+    console.log();
+    console.log(chalk.bold('Journal Entry (per period)'));
+    printJournal(result.schedule[0].journal);
+    console.log();
+}
+// ── Prepaid Expense / Deferred Revenue ────────────────────────────
+function printRecognitionTable(result) {
+    const isPrepaid = result.type === 'prepaid-expense';
+    const title = isPrepaid
+        ? 'Prepaid Expense Recognition Schedule'
+        : 'Deferred Revenue Recognition Schedule';
+    const amountLabel = isPrepaid ? 'Prepaid Amount' : 'Deferred Amount';
+    const W = 60;
+    console.log();
+    console.log(chalk.bold(`${title}${currTag(result.currency)}`));
+    console.log(line(W));
+    console.log(chalk.bold(`  ${amountLabel}:  ${fmt(result.inputs.amount)}`));
+    console.log(chalk.bold(`  Periods:        ${result.inputs.periods} (${result.inputs.frequency})`));
+    console.log(chalk.bold(`  Per Period:     ${fmt(result.perPeriodAmount)}`));
+    console.log(line(W));
+    const recognizedLabel = isPrepaid ? 'Expensed' : 'Recognized';
+    const header = [
+        'Period'.padStart(6),
+        result.inputs.startDate ? 'Date'.padStart(12) : null,
+        recognizedLabel.padStart(14),
+        'Remaining'.padStart(14),
+    ].filter(Boolean).join('  ');
+    console.log(chalk.dim(header));
+    console.log(line(W));
+    for (const row of result.schedule) {
+        const cols = [
+            String(row.period).padStart(6),
+            row.date ? row.date.padStart(12) : null,
+            fmtR(row.amortized),
+            fmtR(row.remainingBalance),
+        ].filter(Boolean).join('  ');
+        console.log(cols);
+    }
+    console.log(line(W));
+    console.log();
+    console.log(chalk.bold('Journal Entry (per period)'));
+    printJournal(result.schedule[0].journal);
+    console.log();
+}
+// ── FX Revaluation ────────────────────────────────────────────────
+function printFxRevalTable(result) {
+    const W = 70;
+    const ccy = result.currency ?? 'FCY';
+    const base = result.inputs.baseCurrency;
+    console.log();
+    console.log(chalk.bold(`FX Revaluation — IAS 21`));
+    console.log(line(W));
+    console.log(chalk.bold(`  Foreign Currency:      ${ccy}`));
+    console.log(chalk.bold(`  Base Currency:         ${base}`));
+    console.log(chalk.bold(`  Amount Outstanding:    ${ccy} ${fmt(result.inputs.amount)}`));
+    console.log(chalk.bold(`  Book Rate:             ${result.inputs.bookRate}`));
+    console.log(chalk.bold(`  Closing Rate:          ${result.inputs.closingRate}`));
+    console.log(line(W));
+    console.log();
+    console.log(`  Book Value (${base}):      ${fmt(result.bookValue)}  (${ccy} ${fmt(result.inputs.amount)} × ${result.inputs.bookRate})`);
+    console.log(`  Closing Value (${base}):   ${fmt(result.closingValue)}  (${ccy} ${fmt(result.inputs.amount)} × ${result.inputs.closingRate})`);
+    console.log(line(W));
+    const label = result.isGain ? chalk.green('Unrealized GAIN') : chalk.red('Unrealized LOSS');
+    console.log(`  ${label}:  ${base} ${fmt(Math.abs(result.gainOrLoss))}`);
+    console.log();
+    console.log(chalk.bold('Revaluation Journal'));
+    printJournal(result.journal);
+    console.log();
+    console.log(chalk.bold('Day 1 Reversal'));
+    printJournal(result.reversalJournal);
+    console.log();
+}
+// ── ECL Provision ─────────────────────────────────────────────────
+function printEclTable(result) {
+    const W = 75;
+    console.log();
+    console.log(chalk.bold(`Expected Credit Loss — IFRS 9 Provision Matrix${currTag(result.currency)}`));
+    console.log(line(W));
+    // Provision matrix table
+    const header = [
+        'Aging Bucket'.padEnd(16),
+        'Balance'.padStart(14),
+        'Loss Rate'.padStart(10),
+        'ECL'.padStart(14),
+    ].join('  ');
+    console.log(chalk.dim(header));
+    console.log(line(W));
+    for (const row of result.bucketDetails) {
+        const cols = [
+            row.bucket.padEnd(16),
+            fmtR(row.balance),
+            `${row.lossRate}%`.padStart(10),
+            fmtR(row.ecl),
+        ].join('  ');
+        console.log(cols);
+    }
+    console.log(line(W));
+    const totalCols = [
+        'TOTAL'.padEnd(16),
+        fmtR(result.totalReceivables),
+        `${result.weightedRate}%`.padStart(10),
+        fmtR(result.totalEcl),
+    ].join('  ');
+    console.log(chalk.bold(totalCols));
+    console.log();
+    // Adjustment summary
+    console.log(chalk.bold('Provision Adjustment'));
+    console.log(`  Required provision:    ${fmt(result.totalEcl)}`);
+    console.log(`  Existing provision:    ${fmt(result.inputs.existingProvision)}`);
+    console.log(line(45));
+    const adjLabel = result.isIncrease
+        ? chalk.yellow(`Increase needed`)
+        : chalk.green(`Release available`);
+    console.log(`  ${adjLabel}:  ${fmt(Math.abs(result.adjustmentRequired))}`);
+    console.log();
+    console.log(chalk.bold('Journal Entry'));
+    printJournal(result.journal);
+    console.log();
+}
+// ── Provision PV Unwinding ────────────────────────────────────────
+function printProvisionTable(result) {
+    const W = 80;
+    console.log();
+    console.log(chalk.bold(`IAS 37 Provision — PV Measurement & Unwinding${currTag(result.currency)}`));
+    console.log(line(W));
+    console.log(chalk.bold(`  Nominal Outflow:  ${fmt(result.nominalAmount)}`));
+    console.log(chalk.bold(`  Discount Rate:    ${fmtPct(result.inputs.annualRate)}`));
+    console.log(chalk.bold(`  Settlement Term:  ${result.inputs.termMonths} months`));
+    console.log(chalk.bold(`  Present Value:    ${fmt(result.presentValue)}`));
+    console.log(chalk.bold(`  Total Unwinding:  ${fmt(result.totalUnwinding)}`));
+    console.log(line(W));
+    console.log(chalk.bold('\nInitial Recognition'));
+    printJournal(result.initialJournal);
+    console.log(chalk.bold('\nDiscount Unwinding Schedule'));
+    const header = [
+        'Period'.padStart(6),
+        result.inputs.startDate ? 'Date'.padStart(12) : null,
+        'Opening'.padStart(14),
+        'Unwinding'.padStart(14),
+        'Closing'.padStart(14),
+    ].filter(Boolean).join('  ');
+    console.log(chalk.dim(header));
+    console.log(line(W));
+    for (const row of result.schedule) {
+        const cols = [
+            String(row.period).padStart(6),
+            row.date ? row.date.padStart(12) : null,
+            fmtR(row.openingBalance),
+            fmtR(row.interest),
+            fmtR(row.closingBalance),
+        ].filter(Boolean).join('  ');
+        console.log(cols);
+    }
+    console.log(line(W));
+    const finalRow = result.schedule[result.schedule.length - 1];
+    console.log(chalk.bold(`  Final provision balance: ${fmt(finalRow.closingBalance)}  (= nominal outflow)`));
+    console.log();
+    console.log(chalk.bold('Summary'));
+    console.log(`  Initial recognition (PV):  ${fmt(result.presentValue)}`);
+    console.log(`  Total unwinding (P&L):     ${fmt(result.totalUnwinding)}`);
+    console.log(`  Nominal outflow:           ${fmt(result.nominalAmount)}`);
+    console.log();
+    console.log(chalk.bold('Journal Entry (per period)'));
+    printJournal(result.schedule[0].journal);
+    console.log();
+}
+// ── Dispatch ──────────────────────────────────────────────────────
+export function printResult(result) {
+    switch (result.type) {
+        case 'loan': return printLoanTable(result);
+        case 'lease': return printLeaseTable(result);
+        case 'depreciation': return printDepreciationTable(result);
+        case 'prepaid-expense': return printRecognitionTable(result);
+        case 'deferred-revenue': return printRecognitionTable(result);
+        case 'fx-reval': return printFxRevalTable(result);
+        case 'ecl': return printEclTable(result);
+        case 'provision': return printProvisionTable(result);
+    }
+}
+export function printJson(result) {
+    console.log(JSON.stringify(result, null, 2));
+}

package/dist/calc/fx-reval.js

@@ -0,0 +1,83 @@
+/**
+ * FX Revaluation calculator (IAS 21).
+ *
+ * Calculates unrealized gain/loss on non-AR/AP foreign currency monetary
+ * items at period-end. This is for items NOT auto-revalued by the platform
+ * (which handles invoices, bills, credit notes, cash, and bank balances).
+ *
+ * Use cases:
+ *  - Intercompany loan receivables/payables (booked as manual journals)
+ *  - Foreign currency term deposits or escrow
+ *  - FX-denominated provisions
+ *  - Any manual journal balance in a foreign currency account
+ *
+ * IAS 21.23: All monetary items translated at closing rate.
+ * IAS 21.28: Exchange differences recognized in P&L.
+ */
+import { round2 } from './types.js';
+import { validatePositive } from './validate.js';
+import { journalStep } from './blueprint.js';
+export function calculateFxReval(inputs) {
+    const { amount, bookRate, closingRate, currency = 'USD', baseCurrency = 'SGD', } = inputs;
+    validatePositive(amount, 'Foreign currency amount');
+    validatePositive(bookRate, 'Book rate');
+    validatePositive(closingRate, 'Closing rate');
+    // Base currency equivalents
+    const bookValue = round2(amount * bookRate);
+    const closingValue = round2(amount * closingRate);
+    const gainOrLoss = round2(closingValue - bookValue);
+    const isGain = gainOrLoss >= 0;
+    const absAmount = Math.abs(gainOrLoss);
+    // Journal entry for the revaluation adjustment
+    let journal;
+    if (isGain) {
+        journal = {
+            description: `FX revaluation — ${currency} ${amount.toLocaleString()} @ ${closingRate} (was ${bookRate})`,
+            lines: [
+                { account: `${currency} Monetary Item`, debit: absAmount, credit: 0 },
+                { account: 'FX Unrealized Gain', debit: 0, credit: absAmount },
+            ],
+        };
+    }
+    else {
+        journal = {
+            description: `FX revaluation — ${currency} ${amount.toLocaleString()} @ ${closingRate} (was ${bookRate})`,
+            lines: [
+                { account: 'FX Unrealized Loss', debit: absAmount, credit: 0 },
+                { account: `${currency} Monetary Item`, debit: 0, credit: absAmount },
+            ],
+        };
+    }
+    // Reversal journal (Day 1 of next period)
+    const reversalJournal = {
+        description: `Reversal of FX revaluation — ${currency} ${amount.toLocaleString()}`,
+        lines: journal.lines.map(l => ({
+            account: l.account,
+            debit: l.credit, // swap debit/credit
+            credit: l.debit,
+        })),
+    };
+    // Blueprint: revaluation + reversal
+    const blueprint = {
+        capsuleType: 'FX Revaluation',
+        capsuleName: `FX Reval — ${currency} ${amount.toLocaleString()} — ${bookRate} → ${closingRate}`,
+        tags: ['FX Revaluation', currency],
+        customFields: { 'Source Account': null, 'Period End Date': null },
+        steps: [
+            journalStep(1, journal.description, null, journal.lines),
+            journalStep(2, reversalJournal.description, null, reversalJournal.lines),
+        ],
+    };
+    return {
+        type: 'fx-reval',
+        currency,
+        inputs: { amount, bookRate, closingRate, baseCurrency },
+        bookValue,
+        closingValue,
+        gainOrLoss,
+        isGain,
+        journal,
+        reversalJournal,
+        blueprint,
+    };
+}

package/dist/calc/lease.js

@@ -0,0 +1,117 @@
+/**
+ * IFRS 16 lease calculator.
+ *
+ * Compliance references:
+ *  - IFRS 16.26: Initial measurement — PV of lease payments
+ *  - IFRS 16.36-37: Subsequent measurement — effective interest method
+ *  - IFRS 16.31-32: ROU depreciation — straight-line over lease term
+ *
+ * Uses `financial` package for PV calculation.
+ * Final period penny adjustment closes lease liability to exactly zero.
+ */
+import { pv } from 'financial';
+import { round2, addMonths } from './types.js';
+import { validatePositive, validatePositiveInteger, validateDateFormat, validateRate } from './validate.js';
+import { journalStep, noteStep, fmtCapsuleAmount } from './blueprint.js';
+export function calculateLease(inputs) {
+    const { monthlyPayment, termMonths, annualRate, startDate, currency } = inputs;
+    validatePositive(monthlyPayment, 'Monthly payment');
+    validateRate(annualRate, 'Annual rate (IBR)');
+    validatePositiveInteger(termMonths, 'Term (months)');
+    validateDateFormat(startDate);
+    const monthlyRate = annualRate / 100 / 12;
+    // PV of an ordinary annuity (payments at end of period)
+    // pv() returns negative, negate for positive value
+    const presentValue = round2(-pv(monthlyRate, termMonths, monthlyPayment));
+    // ROU depreciation: straight-line over lease term (IFRS 16.31-32)
+    const monthlyRouDepreciation = round2(presentValue / termMonths);
+    const initialJournal = {
+        description: 'Initial recognition — IFRS 16 lease',
+        lines: [
+            { account: 'Right-of-Use Asset', debit: presentValue, credit: 0 },
+            { account: 'Lease Liability', debit: 0, credit: presentValue },
+        ],
+    };
+    // Liability unwinding schedule (effective interest method, IFRS 16.36-37)
+    const schedule = [];
+    let liability = presentValue;
+    let totalInterest = 0;
+    let totalPrincipal = 0;
+    for (let i = 1; i <= termMonths; i++) {
+        const openingBalance = round2(liability);
+        const isFinal = i === termMonths;
+        let interest;
+        let principalPortion;
+        let periodPayment;
+        if (isFinal) {
+            // Final period: close liability to exactly zero
+            interest = round2(openingBalance * monthlyRate);
+            principalPortion = openingBalance;
+            periodPayment = round2(principalPortion + interest);
+        }
+        else {
+            interest = round2(openingBalance * monthlyRate);
+            principalPortion = round2(monthlyPayment - interest);
+            periodPayment = monthlyPayment;
+        }
+        liability = round2(openingBalance - principalPortion);
+        totalInterest = round2(totalInterest + interest);
+        totalPrincipal = round2(totalPrincipal + principalPortion);
+        const date = startDate ? addMonths(startDate, i) : null;
+        const journal = {
+            description: `Lease payment — Month ${i} of ${termMonths}`,
+            lines: [
+                { account: 'Lease Liability', debit: principalPortion, credit: 0 },
+                { account: 'Interest Expense — Leases', debit: interest, credit: 0 },
+                { account: 'Cash / Bank Account', debit: 0, credit: periodPayment },
+            ],
+        };
+        schedule.push({
+            period: i,
+            date,
+            openingBalance,
+            payment: periodPayment,
+            interest,
+            principal: principalPortion,
+            closingBalance: liability,
+            journal,
+        });
+    }
+    // ROU depreciation total (final month absorbs rounding)
+    const totalDepreciation = round2(monthlyRouDepreciation * (termMonths - 1) +
+        (presentValue - monthlyRouDepreciation * (termMonths - 1)));
+    // Build blueprint for agent execution
+    let blueprint = null;
+    if (startDate) {
+        const steps = [
+            journalStep(1, initialJournal.description, startDate, initialJournal.lines),
+            noteStep(2, `Register Right-of-Use Asset in Fixed Asset register: cost ${presentValue}, salvage 0, life ${termMonths} months (straight-line). Jaz will auto-post monthly depreciation of ${monthlyRouDepreciation}.`, startDate),
+            ...schedule.map((row, idx) => journalStep(idx + 3, row.journal.description, row.date, row.journal.lines)),
+        ];
+        blueprint = {
+            capsuleType: 'Lease Accounting',
+            capsuleName: `IFRS 16 Lease — ${fmtCapsuleAmount(monthlyPayment, currency)}/month — ${termMonths} months`,
+            tags: ['Lease Accounting'],
+            customFields: { 'Lease Contract #': null },
+            steps,
+        };
+    }
+    return {
+        type: 'lease',
+        currency: currency ?? null,
+        inputs: {
+            monthlyPayment,
+            termMonths,
+            annualRate,
+            startDate: startDate ?? null,
+        },
+        presentValue,
+        monthlyRouDepreciation,
+        totalCashPayments: round2(totalInterest + totalPrincipal),
+        totalInterest,
+        totalDepreciation,
+        initialJournal,
+        schedule,
+        blueprint,
+    };
+}

package/dist/calc/loan.js

@@ -0,0 +1,97 @@
+/**
+ * Loan amortization calculator.
+ * Uses the `financial` package for PMT calculation.
+ * IFRS-compliant rounding: 2 decimals per period, final period closes to zero.
+ */
+import { pmt } from 'financial';
+import { round2, addMonths } from './types.js';
+import { validatePositive, validatePositiveInteger, validateDateFormat, validateRate } from './validate.js';
+import { journalStep, fmtCapsuleAmount } from './blueprint.js';
+export function calculateLoan(inputs) {
+    const { principal, annualRate, termMonths, startDate, currency } = inputs;
+    validatePositive(principal, 'Principal');
+    validateRate(annualRate, 'Annual rate');
+    validatePositiveInteger(termMonths, 'Term (months)');
+    validateDateFormat(startDate);
+    const monthlyRate = annualRate / 100 / 12;
+    // PMT returns negative (cash outflow convention), negate for positive value
+    const payment = round2(-pmt(monthlyRate, termMonths, principal));
+    const schedule = [];
+    let balance = principal;
+    let totalInterest = 0;
+    let totalPrincipal = 0;
+    for (let i = 1; i <= termMonths; i++) {
+        const openingBalance = round2(balance);
+        const isFinal = i === termMonths;
+        let interest;
+        let principalPortion;
+        let periodPayment;
+        if (isFinal) {
+            // Final period: close balance to exactly zero
+            interest = round2(openingBalance * monthlyRate);
+            principalPortion = openingBalance;
+            periodPayment = round2(principalPortion + interest);
+        }
+        else {
+            interest = round2(openingBalance * monthlyRate);
+            principalPortion = round2(payment - interest);
+            periodPayment = payment;
+        }
+        balance = round2(openingBalance - principalPortion);
+        totalInterest = round2(totalInterest + interest);
+        totalPrincipal = round2(totalPrincipal + principalPortion);
+        const date = startDate ? addMonths(startDate, i) : null;
+        const journal = {
+            description: `Loan payment — Month ${i} of ${termMonths}`,
+            lines: [
+                { account: 'Loan Payable', debit: principalPortion, credit: 0 },
+                { account: 'Interest Expense', debit: interest, credit: 0 },
+                { account: 'Cash / Bank Account', debit: 0, credit: periodPayment },
+            ],
+        };
+        schedule.push({
+            period: i,
+            date,
+            openingBalance,
+            payment: periodPayment,
+            interest,
+            principal: principalPortion,
+            closingBalance: balance,
+            journal,
+        });
+    }
+    // Build blueprint for agent execution
+    let blueprint = null;
+    if (startDate) {
+        const steps = [
+            journalStep(1, 'Loan disbursement', startDate, [
+                { account: 'Cash / Bank Account', debit: principal, credit: 0 },
+                { account: 'Loan Payable', debit: 0, credit: principal },
+            ]),
+            ...schedule.map((row, idx) => journalStep(idx + 2, row.journal.description, row.date, row.journal.lines)),
+        ];
+        blueprint = {
+            capsuleType: 'Loan Repayment',
+            capsuleName: `Bank Loan — ${fmtCapsuleAmount(principal, currency)} — ${annualRate}% — ${termMonths} months`,
+            tags: ['Bank Loan'],
+            customFields: { 'Loan Reference': null },
+            steps,
+        };
+    }
+    return {
+        type: 'loan',
+        currency: currency ?? null,
+        inputs: {
+            principal,
+            annualRate,
+            termMonths,
+            startDate: startDate ?? null,
+        },
+        monthlyPayment: payment,
+        totalPayments: round2(totalInterest + totalPrincipal),
+        totalInterest,
+        totalPrincipal,
+        schedule,
+        blueprint,
+    };
+}