jaz-cli 2.5.0 → 2.7.0

package/assets/skills/transaction-recipes/references/fixed-deposit.md

@@ -0,0 +1,164 @@
+# Recipe: Fixed Deposit
+
+## Scenario
+
+Your company places $100,000 in a 12-month fixed deposit at 3.5% annual interest. Under IFRS 9, this is classified as a financial asset at amortized cost (hold-to-collect business model, passes the SPPI test — solely payments of principal and interest). Interest is accrued monthly using the effective interest rate method and recognized in profit or loss. At maturity, the bank returns the principal plus accumulated interest.
+
+**Pattern:** Manual journals + capsule (monthly accrual, single maturity settlement)
+
+---
+
+## Accounts Involved
+
+| Account | Type | Subtype | Role |
+|---|---|---|---|
+| Fixed Deposit | Asset | Current Asset | Carries the principal for the deposit term |
+| Accrued Interest Receivable | Asset | Current Asset | Accumulates monthly interest accruals |
+| Interest Income | Revenue | Other Income | P&L recognition of interest earned |
+| Cash / Bank Account | Asset | Bank | Outflow on placement, inflow at maturity |
+
+---
+
+## Journal Entries
+
+### Step 1: Placement (Day 1) — cash-out
+
+Record the transfer from operating account to the fixed deposit. This is a **cash-out** entry in Jaz (cash leaves the bank account):
+
+| Line | Account | Debit | Credit |
+|---|---|---|---|
+| 1 | Fixed Deposit | $100,000 | |
+| 2 | Cash / Bank Account | | $100,000 |
+
+> In Jaz, record this via the bank module (match the outgoing bank feed entry) or as a manual journal.
+
+### Step 2: Monthly Interest Accrual (each month)
+
+**Simple interest (default):** Equal monthly accrual amount.
+
+| Line | Account | Debit | Credit |
+|---|---|---|---|
+| 1 | Accrued Interest Receivable | $291.67 | |
+| 2 | Interest Income | | $291.67 |
+
+**Calculation:**
+- Annual interest = $100,000 × 3.5% = $3,500
+- Monthly accrual = $3,500 / 12 = $291.67
+
+**Compound interest:** Interest is calculated on the carrying amount (principal + previously accrued interest) using the effective interest rate. Each month's accrual is slightly higher than the last. Use `jaz calc fixed-deposit --principal 100000 --rate 3.5 --term 12 --compound monthly` to generate the exact schedule.
+
+### Step 3: Maturity (final day) — cash-in
+
+Principal plus accrued interest returns to the bank account. This is a **cash-in** entry in Jaz (cash arrives in the bank account):
+
+| Line | Account | Debit | Credit |
+|---|---|---|---|
+| 1 | Cash / Bank Account | $103,500 | |
+| 2 | Fixed Deposit | | $100,000 |
+| 3 | Accrued Interest Receivable | | $3,500 |
+
+> After this entry, Fixed Deposit and Accrued Interest Receivable both zero out. The net P&L impact is $3,500 of Interest Income recognized over the 12 months. In Jaz, record via the bank module (match the incoming bank feed entry) or as a manual journal.
+
+---
+
+## Capsule Structure
+
+**Capsule:** "Fixed Deposit — DBS — 2025"
+**Capsule Type:** "Fixed Deposit"
+
+Contents:
+- 1 placement journal
+- 12 monthly interest accrual journals
+- 1 maturity journal
+- **Total entries:** 14
+
+The CLI generates a `capsuleDescription` field with full workings — including the interest calculation method, per-period accrual amounts, and maturity value — so the capsule is self-documenting.
+
+---
+
+## Worked Example
+
+**Deposit terms:**
+- Principal: $100,000
+- Annual rate: 3.5%
+- Term: 12 months (simple interest)
+- Monthly accrual: $100,000 × 3.5% / 12 = $291.67
+- Total interest: $3,500.00
+- Maturity value: $103,500.00
+
+**CLI command:**
+```
+jaz calc fixed-deposit --principal 100000 --rate 3.5 --term 12 --currency SGD
+```
+
+### Accrual Schedule (first 3 months + last month)
+
+| Month | Accrual Amount | Cumulative Interest | Accrued Interest Receivable |
+|---|---|---|---|
+| 1 | $291.67 | $291.67 | $291.67 |
+| 2 | $291.67 | $583.34 | $583.34 |
+| 3 | $291.67 | $875.01 | $875.01 |
+| ... | ... | ... | ... |
+| 12 | $291.63* | $3,500.00 | $3,500.00 |
+
+> *Final month adjusted by $0.04 to close the balance exactly to $3,500.00 (rounding correction).
+
+**Month 1 journal entry:**
+- Dr Accrued Interest Receivable $291.67
+- Cr Interest Income $291.67
+- Description: "FD interest accrual — Month 1 of 12 (DBS)"
+- Assign to capsule
+
+**Month 3 journal entry:**
+- Dr Accrued Interest Receivable $291.67
+- Cr Interest Income $291.67
+- Description: "FD interest accrual — Month 3 of 12 (DBS)"
+- Assign to capsule
+
+**Maturity journal entry:**
+- Dr Cash $103,500.00
+- Cr Fixed Deposit $100,000.00
+- Cr Accrued Interest Receivable $3,500.00
+- Description: "FD maturity — principal + interest received (DBS)"
+- Assign to capsule
+
+**Totals over 12 months:**
+- Total interest income: $3,500.00
+- Net cash impact: −$100,000 at placement, +$103,500 at maturity = +$3,500
+
+---
+
+## Enrichment Suggestions
+
+| Enrichment | Value | Why |
+|---|---|---|
+| Tracking Tag | "Fixed Deposit" | Filter all FD-related transactions in reports |
+| Nano Classifier | Instrument → "Term Deposit" | Distinguish from savings accounts or money market funds |
+| Custom Field | "Deposit Reference" → "TD-2025-001" | Record the bank's deposit certificate number |
+| Custom Field | "Bank Name" → "DBS" | Identify the issuing bank for multi-bank portfolios |
+
+Set the tag and nano classifier on each accrual journal. Custom fields go on the placement journal (the capsule groups everything together).
+
+---
+
+## Verification
+
+1. **Accrued Interest Receivable should accumulate monthly** → Trial Balance at month 6 should show $1,750.02 (6 × $291.67). The balance grows each month until maturity.
+2. **Interest Income P&L line = total accrual to date** → P&L at any date should equal the sum of accrual entries posted up to that date.
+3. **At maturity, Fixed Deposit account zeros out** → After the maturity journal, Fixed Deposit balance = $0 and Accrued Interest Receivable balance = $0.
+4. **Cash flow: Cash decreased by principal on placement, increased by maturity value at end** → Net cash movement over the 12 months = +$3,500 (the interest earned).
+5. **Group General Ledger by Capsule** → "Fixed Deposit — DBS — 2025" should show all 14 entries. Fixed Deposit nets to $0 and Interest Income totals $3,500.
+
+---
+
+## Variations
+
+**Compound interest:** Use `jaz calc fixed-deposit --principal 100000 --rate 3.5 --term 12 --compound monthly` to generate a schedule where each month's interest is calculated on the carrying amount (principal + accrued interest to date). Total interest will be slightly higher than simple interest ($3,556.46 vs $3,500.00 for monthly compounding). The effective interest rate method applies the same logic — each period's income = carrying amount × periodic rate.
+
+**FX-denominated deposit:** If the deposit is in USD but your base currency is SGD, record the placement journal with `currency: { sourceCurrency: "USD" }`. Monthly accruals should use the spot rate at each month-end. At maturity, any difference between the cumulative translated amounts and the actual SGD received is an FX gain/loss. Cross-reference the fx-revaluation recipe for month-end revaluation of the outstanding balance.
+
+**Premature withdrawal:** The bank may impose a penalty (reduced interest rate or flat fee). Record the maturity journal with the reduced interest amount. If interest already accrued exceeds the actual payout, reverse the excess: Dr Interest Income / Cr Accrued Interest Receivable. Note the penalty in the journal description.
+
+**Auto-rollover:** When the bank automatically rolls over the deposit at maturity, close the original capsule with a maturity journal (Dr Fixed Deposit New / Cr Fixed Deposit Old + Cr Accrued Interest Receivable), then create a new capsule for the rolled deposit. The new principal may include the prior interest if the bank compounds on rollover.
+
+**PH withholding tax (20% final WHT on interest income):** In jurisdictions that withhold tax on interest at source, the maturity cash received is net of WHT. Record: Dr Cash (net) + Dr WHT Receivable or Tax Expense / Cr Fixed Deposit + Cr Accrued Interest Receivable. This variation is deferred to a future recipe update.

package/assets/skills/transaction-recipes/references/hire-purchase.md

@@ -0,0 +1,190 @@
+# Recipe: Hire Purchase
+
+## Scenario
+
+Your company acquires a motor vehicle under a hire purchase (HP) agreement: $5,000/month for 36 months at 5% incremental borrowing rate. Ownership transfers to you at the end of the term. Under IFRS 16, this is accounted for the same way as any other lease — right-of-use asset, lease liability, effective interest unwinding — with **one critical difference**: the ROU asset is depreciated over its **useful life** (60 months), not the lease term (36 months), because ownership transfers at the end.
+
+**Pattern:** Hybrid — native fixed asset (straight-line ROU depreciation over useful life) + manual journals (liability unwinding) + capsule
+
+**Cross-reference:** This recipe is a variant of the [IFRS 16 Lease recipe](./ifrs16-lease.md). Everything is identical except the depreciation period. Read the IFRS 16 recipe first for the full foundational treatment, then return here for the hire purchase-specific difference.
+
+**Why the difference:** IFRS 16.32 requires that when ownership transfers (or a purchase option is reasonably certain to be exercised), the ROU asset is depreciated over the asset's useful life rather than the lease term. Hire purchase agreements always transfer ownership, so this rule always applies.
+
+---
+
+## Accounts Involved
+
+| Account | Type | Subtype | Role |
+|---|---|---|---|
+| Right-of-Use Asset | Asset | Non-Current Asset | The HP'd asset (e.g., motor vehicle) |
+| Accumulated Depreciation — ROU | Asset | Non-Current Asset | Contra-asset reducing ROU net book value |
+| Lease Liability | Liability | Non-Current Liability | PV of future HP payments |
+| Interest Expense — Leases | Expense | Finance Cost | Effective interest on lease liability |
+| Depreciation Expense — ROU | Expense | Depreciation | Straight-line over useful life (NOT lease term) |
+| Cash / Bank Account | Asset | Bank | Makes monthly HP payments |
+
+> **Same accounts as IFRS 16 lease.** The only change is the depreciation calculation — the accounts, journal structure, and liability unwinding are all identical.
+
+---
+
+## Journal Entries
+
+### Step 1: Initial Recognition (same as IFRS 16)
+
+| Line | Account | Debit | Credit |
+|---|---|---|---|
+| 1 | Right-of-Use Asset | $166,828.51 | |
+| 2 | Lease Liability | | $166,828.51 |
+
+PV of 36 payments of $5,000 at 5% annual (0.4167% monthly).
+
+### Step 2: Monthly HP Payment (same as IFRS 16)
+
+Each $5,000 payment splits between interest (expense) and principal (liability reduction):
+
+| Line | Account | Debit | Credit |
+|---|---|---|---|
+| 1 | Lease Liability | *principal portion* | |
+| 2 | Interest Expense — Leases | *interest portion* | |
+| 3 | Cash / Bank Account | | $5,000 |
+
+**Calculation per month:**
+- Interest = Outstanding liability x 0.4167%
+- Principal = $5,000 - Interest
+- New liability = Outstanding liability - Principal
+
+### Step 3: Monthly Depreciation — THE KEY DIFFERENCE
+
+| Line | Account | Debit | Credit |
+|---|---|---|---|
+| 1 | Depreciation Expense — ROU | $2,780.48 | |
+| 2 | Accumulated Depreciation — ROU | | $2,780.48 |
+
+**Standard IFRS 16 lease:** $166,828.51 / 36 months = **$4,634.13/month**
+**Hire purchase:** $166,828.51 / 60 months = **$2,780.48/month**
+
+> The hire purchase depreciation rate is **$1,853.65/month LESS** than a standard lease. This is because the asset's economic life (60 months) extends well beyond the payment term (36 months). Ownership transfers, so the asset continues generating value after the last payment.
+
+---
+
+## Capsule Structure
+
+**Capsule:** "Hire Purchase — Motor Vehicle — 2025"
+**Capsule Type:** "Hire Purchase"
+
+Contents:
+- 1 initial recognition journal (ROU asset + lease liability)
+- 36 monthly payment journals (manual — interest changes each month)
+- 60 monthly depreciation entries (auto-generated by fixed asset register — these appear in the ledger but aren't manually created)
+- **Manually created entries:** 37
+
+> The fixed asset depreciation entries are not assigned to the capsule automatically. Group the General Ledger by the ROU asset account alongside the capsule view for a complete picture. Depreciation continues for 24 months after the last HP payment.
+
+---
+
+## Worked Example
+
+**HP terms:**
+- Monthly payment: $5,000
+- Lease term: 36 months
+- Incremental borrowing rate: 5% annual (0.4167% monthly)
+- Asset useful life: 60 months
+- PV of lease payments: $166,828.51
+
+**CLI command:**
+```
+jaz calc lease --payment 5000 --term 36 --rate 5 --useful-life 60 --start-date 2025-01-01
+```
+
+The `--useful-life 60` flag tells the calculator this is a hire purchase — depreciation will use 60 months instead of the 36-month lease term. The CLI generates a `capsuleDescription` with full workings so the capsule is self-documenting.
+
+### Liability Unwinding Table (first 3 months + month 36)
+
+| Month | Opening Liability | Interest (0.4167%) | Principal | Closing Liability |
+|---|---|---|---|---|
+| 1 | $166,828.51 | $695.12 | $4,304.88 | $162,523.63 |
+| 2 | $162,523.63 | $677.18 | $4,322.82 | $158,200.81 |
+| 3 | $158,200.81 | $659.17 | $4,340.83 | $153,859.98 |
+| ... | ... | ... | ... | ... |
+| 36 | $4,979.24 | $20.75 | $4,979.24 | $0.00* |
+
+> *Final payment adjusted to close the liability exactly to zero (payment = $4,999.99).
+
+**Month 1 journal entry (manual — same as IFRS 16):**
+- Dr Lease Liability $4,304.88
+- Dr Interest Expense — Leases $695.12
+- Cr Cash $5,000.00
+- Description: "HP payment — Month 1 of 36 (Motor Vehicle)"
+- Assign to capsule
+
+**Month 1 depreciation (automatic — posted by Jaz FA register):**
+- Dr Depreciation Expense — ROU $2,780.48
+- Cr Accumulated Depreciation — ROU $2,780.48
+
+### Depreciation Comparison: Hire Purchase vs Standard Lease
+
+| Item | Standard IFRS 16 Lease | Hire Purchase |
+|---|---|---|
+| Depreciation period | 36 months (lease term) | 60 months (useful life) |
+| Monthly depreciation | $4,634.13 | $2,780.48 |
+| **Difference** | — | **$1,853.65/month LESS** |
+
+### What Happens After Month 36 (Lease Payments End)
+
+| Item | Value |
+|---|---|
+| Lease Liability | $0 (fully unwound) |
+| ROU Asset (gross) | $166,828.51 |
+| Accumulated Depreciation (36 months) | $100,097.28 |
+| **ROU Net Book Value** | **$66,731.23** |
+| Remaining depreciation period | 24 more months |
+
+After the last HP payment, the lease liability is zero and no more cash leaves the account. But the ROU asset still has a book value of $66,731.23 because it was depreciated over 60 months, not 36. Depreciation of $2,780.48/month continues for another 24 months until the asset is fully depreciated.
+
+### Summary Over Full Useful Life (60 Months)
+
+| Item | Total |
+|---|---|
+| Total cash payments | $180,000 (36 x $5,000) |
+| Total interest expense | $13,171.48 |
+| Total depreciation expense | $166,828.51 |
+| **Total P&L impact** | **$180,000** |
+| Lease liability at month 36 | $0 |
+| ROU asset net book value at month 36 | $66,731.23 |
+| ROU asset net book value at month 60 | $0 |
+
+> **P&L timing differs from a standard lease.** With hire purchase, the P&L charge is spread over 60 months instead of 36. In months 1-36, both interest and depreciation hit the P&L. In months 37-60, only depreciation remains — at a lower rate than the original cash payment.
+
+---
+
+## Enrichment Suggestions
+
+| Enrichment | Value | Why |
+|---|---|---|
+| Tracking Tag | "Hire Purchase" | Filter all HP-related transactions |
+| Nano Classifier | Asset Type → "Motor Vehicle" | Break down by asset class if multiple HPs |
+| Custom Field | "HP Agreement #" → "HP-2025-0089" | Record the hire purchase agreement reference |
+
+---
+
+## Verification
+
+1. **Lease Liability should reduce to $0 at end of lease term (month 36)** → Group General Ledger by Capsule. Liability starts at $166,828.51 and closes at $0 after 36 payments.
+2. **Interest Expense total = total cash payments - PV** → $180,000 − $166,828.51 = $13,171.48 (rounding may cause ±$0.01 variance).
+3. **ROU Asset continues depreciating after lease payments end** → At month 36, ROU net book value = $66,731.23. Depreciation continues at $2,780.48/month for 24 more months.
+4. **At end of useful life (month 60), ROU asset is fully depreciated** → ROU Asset $166,828.51 − Accumulated Depreciation $166,828.51 = $0 net book value.
+5. **Balance Sheet check** → Between months 37-60, no lease liability exists but the ROU asset (net of accumulated depreciation) continues appearing on the balance sheet. This is the distinguishing feature of hire purchase vs operating lease.
+
+---
+
+## Variations
+
+**Standard operating lease (no ownership transfer):** Use `jaz calc lease --payment 5000 --term 36 --rate 5` without the `--useful-life` flag. The ROU asset is depreciated over the lease term (36 months), not useful life. See the [IFRS 16 Lease recipe](./ifrs16-lease.md).
+
+**Guaranteed residual value:** If the HP agreement includes a guaranteed residual value (e.g., $10,000 balloon payment at end of term), add the PV of the residual to the initial ROU asset and lease liability. The liability schedule must include the balloon as the final period payment.
+
+**Variable payments:** Only the fixed portion of HP payments is included in the PV calculation. Any variable component (e.g., mileage-based charges) is recognized as expense when incurred, not capitalized in the ROU asset.
+
+**SG motor vehicle specifics:** The COE (Certificate of Entitlement) is typically treated as a separate intangible asset with its own amortization schedule (10 years for Category A/B), not bundled into the HP's ROU asset. Create a separate capsule for the COE if applicable.
+
+**SG tax depreciation (IRAS):** Capital allowances for motor vehicles under Section 19/19A may differ from IFRS depreciation. The S-car cap ($35,000 for private cars) and the 3-year write-off period for commercial vehicles don't align with IFRS useful life estimates. Businesses may need to track both IFRS depreciation (for financial reporting) and tax depreciation (for S68 deductions) separately. This recipe covers IFRS only — tax depreciation adjustments are out of scope.

package/dist/__tests__/amortization.test.js

@@ -0,0 +1,101 @@
+import { describe, it, expect } from 'vitest';
+import { calculatePrepaidExpense, calculateDeferredRevenue } from '../calc/amortization.js';
+import { CalcValidationError } from '../calc/validate.js';
+describe('calculatePrepaidExpense', () => {
+    const base = { amount: 12000, periods: 12 };
+    it('per period = amount / periods', () => {
+        const r = calculatePrepaidExpense(base);
+        expect(r.perPeriodAmount).toBe(1000);
+    });
+    it('schedule has correct length', () => {
+        const r = calculatePrepaidExpense(base);
+        expect(r.schedule).toHaveLength(12);
+    });
+    it('total amortized = original amount', () => {
+        const r = calculatePrepaidExpense(base);
+        const total = r.schedule.reduce((s, row) => s + row.amortized, 0);
+        expect(Math.round(total * 100) / 100).toBe(12000);
+    });
+    it('remaining balance reaches zero at final period', () => {
+        const r = calculatePrepaidExpense(base);
+        expect(r.schedule[r.schedule.length - 1].remainingBalance).toBe(0);
+    });
+    it('handles rounding — 10000 / 3 periods', () => {
+        const r = calculatePrepaidExpense({ amount: 10000, periods: 3 });
+        expect(r.perPeriodAmount).toBe(3333.33);
+        const total = r.schedule.reduce((s, row) => s + row.amortized, 0);
+        expect(Math.round(total * 100) / 100).toBe(10000);
+        // Final period absorbs rounding
+        expect(r.schedule[2].amortized).toBe(3333.34);
+    });
+    it('every journal entry balanced', () => {
+        const r = calculatePrepaidExpense(base);
+        for (const row of r.schedule) {
+            const debits = row.journal.lines.reduce((s, l) => s + l.debit, 0);
+            const credits = row.journal.lines.reduce((s, l) => s + l.credit, 0);
+            expect(debits).toBe(credits);
+        }
+    });
+    it('journal entries use Expense / Prepaid Asset accounts', () => {
+        const r = calculatePrepaidExpense(base);
+        expect(r.schedule[0].journal.lines[0].account).toBe('Expense');
+        expect(r.schedule[0].journal.lines[1].account).toBe('Prepaid Asset');
+    });
+    // Blueprint
+    it('blueprint step 1 = bill', () => {
+        const r = calculatePrepaidExpense({ ...base, startDate: '2025-01-01' });
+        expect(r.blueprint.steps[0].action).toBe('bill');
+    });
+    it('blueprint step count = 1 + periods', () => {
+        const r = calculatePrepaidExpense({ ...base, startDate: '2025-01-01' });
+        expect(r.blueprint.steps).toHaveLength(13);
+    });
+    it('blueprint null without startDate', () => {
+        const r = calculatePrepaidExpense(base);
+        expect(r.blueprint).toBeNull();
+    });
+    // Quarterly
+    it('quarterly frequency works', () => {
+        const r = calculatePrepaidExpense({ amount: 12000, periods: 4, frequency: 'quarterly', startDate: '2025-01-01' });
+        expect(r.schedule).toHaveLength(4);
+        // Date present and properly formatted (exact value depends on TZ)
+        expect(r.schedule[0].date).toMatch(/^\d{4}-\d{2}-\d{2}$/);
+    });
+    // Validation
+    it('rejects zero amount', () => {
+        expect(() => calculatePrepaidExpense({ amount: 0, periods: 12 })).toThrow(CalcValidationError);
+    });
+    it('rejects zero periods', () => {
+        expect(() => calculatePrepaidExpense({ amount: 12000, periods: 0 })).toThrow(CalcValidationError);
+    });
+});
+describe('calculateDeferredRevenue', () => {
+    const base = { amount: 36000, periods: 12 };
+    it('per period = amount / periods', () => {
+        const r = calculateDeferredRevenue(base);
+        expect(r.perPeriodAmount).toBe(3000);
+    });
+    it('total recognized = original amount', () => {
+        const r = calculateDeferredRevenue(base);
+        const total = r.schedule.reduce((s, row) => s + row.amortized, 0);
+        expect(Math.round(total * 100) / 100).toBe(36000);
+    });
+    it('journal entries use Deferred Revenue / Revenue accounts', () => {
+        const r = calculateDeferredRevenue(base);
+        expect(r.schedule[0].journal.lines[0].account).toBe('Deferred Revenue');
+        expect(r.schedule[0].journal.lines[1].account).toBe('Revenue');
+    });
+    // Blueprint
+    it('blueprint step 1 = invoice', () => {
+        const r = calculateDeferredRevenue({ ...base, startDate: '2025-01-01' });
+        expect(r.blueprint.steps[0].action).toBe('invoice');
+    });
+    it('capsuleType is Deferred Revenue', () => {
+        const r = calculateDeferredRevenue({ ...base, startDate: '2025-01-01' });
+        expect(r.blueprint.capsuleType).toBe('Deferred Revenue');
+    });
+    it('capsuleDescription present', () => {
+        const r = calculateDeferredRevenue({ ...base, startDate: '2025-01-01' });
+        expect(r.blueprint.capsuleDescription).toBeTruthy();
+    });
+});