jaz-cli 2.3.0 → 2.6.0

package/dist/calc/ecl.js

@@ -0,0 +1,101 @@
+/**
+ * Expected Credit Loss (ECL) calculator — IFRS 9 simplified approach.
+ *
+ * Builds a provision matrix from aged receivables buckets and historical
+ * loss rates, then calculates the required provision adjustment.
+ *
+ * Compliance references:
+ *  - IFRS 9.5.5.15: Simplified approach for trade receivables
+ *  - IFRS 9.B5.5.35: Provision matrix method
+ *  - IFRS 9.5.5.17: Always recognize lifetime ECL (no staging)
+ *
+ * Standard aging buckets: Current, 1-30d, 31-60d, 61-90d, 91+d
+ * Each bucket gets a historical loss rate (%) applied.
+ * The delta between total ECL and existing provision = period charge.
+ */
+import { round2 } from './types.js';
+import { validateNonNegative } from './validate.js';
+import { journalStep, fmtCapsuleAmount, fmtAmt } from './blueprint.js';
+export function calculateEcl(inputs) {
+    const { buckets, existingProvision = 0, currency } = inputs;
+    // Validate each bucket
+    for (const b of buckets) {
+        validateNonNegative(b.balance, `${b.name} balance`);
+        validateNonNegative(b.rate, `${b.name} loss rate`);
+    }
+    validateNonNegative(existingProvision, 'Existing provision');
+    // Calculate ECL per bucket
+    const bucketDetails = buckets.map(b => ({
+        bucket: b.name,
+        balance: b.balance,
+        lossRate: b.rate,
+        ecl: round2(b.balance * b.rate / 100),
+    }));
+    const totalReceivables = round2(buckets.reduce((sum, b) => sum + b.balance, 0));
+    const totalEcl = round2(bucketDetails.reduce((sum, b) => sum + b.ecl, 0));
+    const adjustmentRequired = round2(totalEcl - existingProvision);
+    const isIncrease = adjustmentRequired >= 0;
+    const absAdj = Math.abs(adjustmentRequired);
+    // Weighted average loss rate for summary
+    const weightedRate = totalReceivables > 0
+        ? round2(totalEcl / totalReceivables * 100 * 100) / 100 // round to 2dp %
+        : 0;
+    // Journal entry for the provision adjustment
+    let journal;
+    if (isIncrease) {
+        journal = {
+            description: `ECL provision increase — IFRS 9 simplified approach`,
+            lines: [
+                { account: 'Bad Debt Expense', debit: absAdj, credit: 0 },
+                { account: 'Allowance for Doubtful Debts', debit: 0, credit: absAdj },
+            ],
+        };
+    }
+    else {
+        journal = {
+            description: `ECL provision release — IFRS 9 simplified approach`,
+            lines: [
+                { account: 'Allowance for Doubtful Debts', debit: absAdj, credit: 0 },
+                { account: 'Bad Debt Expense', debit: 0, credit: absAdj },
+            ],
+        };
+    }
+    // Blueprint
+    const c = currency ?? undefined;
+    const bucketWorkings = bucketDetails.map(b => `  ${b.bucket}: ${fmtAmt(b.balance, c)} × ${b.lossRate}% = ${fmtAmt(b.ecl, c)}`).join('\n');
+    const workings = [
+        `ECL Provision Matrix Workings (IFRS 9)`,
+        `Total receivables: ${fmtAmt(totalReceivables, c)} | Weighted avg loss rate: ${weightedRate}%`,
+        `Provision matrix:`,
+        bucketWorkings,
+        `Total ECL required: ${fmtAmt(totalEcl, c)} | Existing provision: ${fmtAmt(existingProvision, c)}`,
+        `Adjustment: ${fmtAmt(Math.abs(adjustmentRequired), c)} (${isIncrease ? 'increase' : 'release'})`,
+        `Method: IFRS 9.5.5.15 simplified approach — lifetime ECL, provision matrix`,
+    ].join('\n');
+    const blueprint = {
+        capsuleType: 'ECL Provision',
+        capsuleName: `ECL Provision — ${fmtCapsuleAmount(totalEcl, currency)} — ${buckets.length} buckets`,
+        capsuleDescription: workings,
+        tags: ['ECL', 'Bad Debt'],
+        customFields: { 'Reporting Period': null, 'Aged Receivables Report Date': null },
+        steps: [
+            journalStep(1, journal.description, null, journal.lines),
+        ],
+    };
+    return {
+        type: 'ecl',
+        currency: currency ?? null,
+        inputs: {
+            buckets: buckets.map(b => ({ name: b.name, balance: b.balance, rate: b.rate })),
+            existingProvision,
+        },
+        totalReceivables,
+        totalEcl,
+        weightedRate,
+        adjustmentRequired,
+        isIncrease,
+        bucketDetails,
+        journal,
+        blueprint,
+    };
+}

package/dist/calc/fixed-deposit.js

@@ -0,0 +1,169 @@
+/**
+ * Fixed deposit interest accrual calculator.
+ *
+ * Compliance references:
+ *  - IFRS 9.4.1.2: Classification at amortized cost (hold-to-collect, passes SPPI)
+ *  - IFRS 9.5.4.1: Interest revenue via effective interest rate method
+ *
+ * Supports simple interest (default) and compound interest (monthly/quarterly/annually).
+ * Final period absorbs rounding — maturity value is exact.
+ */
+import { fv } from 'financial';
+import { round2, addMonths } from './types.js';
+import { validatePositive, validatePositiveInteger, validateDateFormat, validateRate } from './validate.js';
+import { journalStep, cashOutStep, cashInStep, fmtCapsuleAmount, fmtAmt } from './blueprint.js';
+export function calculateFixedDeposit(inputs) {
+    const { principal, annualRate, termMonths, compounding = 'none', startDate, currency, } = inputs;
+    validatePositive(principal, 'Principal');
+    validateRate(annualRate, 'Annual rate');
+    validatePositiveInteger(termMonths, 'Term (months)');
+    validateDateFormat(startDate);
+    const monthlyRate = annualRate / 100 / 12;
+    // Compute total interest based on compounding method
+    let maturityValue;
+    if (compounding === 'none') {
+        // Simple interest: Principal × Rate × Time
+        maturityValue = round2(principal + principal * (annualRate / 100) * (termMonths / 12));
+    }
+    else {
+        // Compound interest using fv() from financial package
+        // fv(rate, nper, pmt, pv) — returns negative, negate
+        const periodsPerYear = compounding === 'monthly' ? 12 : compounding === 'quarterly' ? 4 : 1;
+        const compoundRate = annualRate / 100 / periodsPerYear;
+        const totalCompoundPeriods = Math.floor(termMonths / (12 / periodsPerYear));
+        // fv() with negative pv (outflow) returns positive (inflow at maturity)
+        maturityValue = round2(fv(compoundRate, totalCompoundPeriods, 0, -principal));
+    }
+    const totalInterest = round2(maturityValue - principal);
+    // Effective annual rate (for display)
+    const effectiveRate = round2((Math.pow(maturityValue / principal, 12 / termMonths) - 1) * 100 * 100) / 100;
+    // Build monthly accrual schedule
+    const schedule = [];
+    let accruedTotal = 0;
+    if (compounding === 'none') {
+        // Simple interest: equal accrual each month
+        const monthlyInterest = round2(totalInterest / termMonths);
+        let balance = principal;
+        for (let i = 1; i <= termMonths; i++) {
+            const isFinal = i === termMonths;
+            const interest = isFinal ? round2(totalInterest - accruedTotal) : monthlyInterest;
+            accruedTotal = round2(accruedTotal + interest);
+            const date = startDate ? addMonths(startDate, i) : null;
+            const journal = {
+                description: `Interest accrual — Month ${i} of ${termMonths}`,
+                lines: [
+                    { account: 'Accrued Interest Receivable', debit: interest, credit: 0 },
+                    { account: 'Interest Income', debit: 0, credit: interest },
+                ],
+            };
+            schedule.push({
+                period: i,
+                date,
+                openingBalance: balance,
+                interest,
+                closingBalance: balance, // simple interest: principal unchanged
+                journal,
+            });
+        }
+    }
+    else {
+        // Compound interest: effective interest on growing carrying amount
+        let balance = principal;
+        for (let i = 1; i <= termMonths; i++) {
+            const openingBalance = round2(balance);
+            const isFinal = i === termMonths;
+            let interest;
+            if (isFinal) {
+                // Final period: close to exact maturity value
+                interest = round2(maturityValue - openingBalance);
+            }
+            else {
+                interest = round2(openingBalance * monthlyRate);
+            }
+            balance = round2(openingBalance + interest);
+            accruedTotal = round2(accruedTotal + interest);
+            const date = startDate ? addMonths(startDate, i) : null;
+            const journal = {
+                description: `Interest accrual — Month ${i} of ${termMonths}`,
+                lines: [
+                    { account: 'Accrued Interest Receivable', debit: interest, credit: 0 },
+                    { account: 'Interest Income', debit: 0, credit: interest },
+                ],
+            };
+            schedule.push({
+                period: i,
+                date,
+                openingBalance,
+                interest,
+                closingBalance: balance,
+                journal,
+            });
+        }
+    }
+    const placementJournal = {
+        description: 'Fixed deposit placement',
+        lines: [
+            { account: 'Fixed Deposit', debit: principal, credit: 0 },
+            { account: 'Cash / Bank Account', debit: 0, credit: principal },
+        ],
+    };
+    const maturityJournal = {
+        description: 'Fixed deposit maturity',
+        lines: [
+            { account: 'Cash / Bank Account', debit: maturityValue, credit: 0 },
+            { account: 'Fixed Deposit', debit: 0, credit: principal },
+            { account: 'Accrued Interest Receivable', debit: 0, credit: totalInterest },
+        ],
+    };
+    // Build blueprint
+    let blueprint = null;
+    if (startDate) {
+        const steps = [
+            cashOutStep(1, 'Transfer funds from operating account to fixed deposit', startDate, placementJournal.lines),
+            ...schedule.map((row, idx) => journalStep(idx + 2, row.journal.description, row.date, row.journal.lines)),
+            cashInStep(termMonths + 2, 'Fixed deposit maturity — principal + accrued interest returned to Cash', addMonths(startDate, termMonths), maturityJournal.lines),
+        ];
+        const c = currency ?? undefined;
+        const compoundLabel = compounding === 'none' ? 'Simple interest' : `Compound ${compounding}`;
+        const monthlyAccrual = compounding === 'none' ? round2(totalInterest / termMonths) : null;
+        const workingsLines = [
+            `Fixed Deposit Interest Accrual Workings (IFRS 9)`,
+            `Principal: ${fmtAmt(principal, c)} | Rate: ${annualRate}% p.a. | Term: ${termMonths} months`,
+            `Method: ${compoundLabel}`,
+        ];
+        if (compounding === 'none') {
+            workingsLines.push(`Interest: ${fmtAmt(principal, c)} × ${annualRate}% × ${termMonths}/12 = ${fmtAmt(totalInterest, c)}`, `Monthly accrual: ${fmtAmt(monthlyAccrual, c)}`);
+        }
+        else {
+            const periodsPerYear = compounding === 'monthly' ? 12 : compounding === 'quarterly' ? 4 : 1;
+            workingsLines.push(`Compounding: ${periodsPerYear}× per year | Effective annual rate: ${effectiveRate}%`, `Total interest: ${fmtAmt(totalInterest, c)}`);
+        }
+        workingsLines.push(`Maturity value: ${fmtAmt(maturityValue, c)}`, `Classification: Amortized cost (hold-to-collect, passes SPPI)`, `Rounding: 2dp per period, final period closes to exact maturity value`);
+        blueprint = {
+            capsuleType: 'Fixed Deposit',
+            capsuleName: `Fixed Deposit — ${fmtCapsuleAmount(principal, currency)} — ${annualRate}% — ${termMonths} months`,
+            capsuleDescription: workingsLines.join('\n'),
+            tags: ['Fixed Deposit'],
+            customFields: { 'Deposit Reference': null, 'Bank Name': null },
+            steps,
+        };
+    }
+    return {
+        type: 'fixed-deposit',
+        currency: currency ?? null,
+        inputs: {
+            principal,
+            annualRate,
+            termMonths,
+            compounding,
+            startDate: startDate ?? null,
+        },
+        maturityValue,
+        totalInterest,
+        effectiveRate,
+        schedule,
+        placementJournal,
+        maturityJournal,
+        blueprint,
+    };
+}