jaz-cli 2.6.0 → 2.7.0

package/assets/skills/api/SKILL.md

@@ -1,6 +1,6 @@
 ---
 name: api
-version: 2.6.0
+version: 2.7.0
 description: Complete reference for the Jaz/Juan REST API — the accounting platform backend. Use this skill whenever building, modifying, debugging, or extending any code that calls the API — including API clients, integrations, data seeding, test data, or new endpoint work. Contains every field name, response shape, error, gotcha, and edge case discovered through live production testing.
 license: MIT
 compatibility: Requires Jaz/Juan API key (x-jk-api-key header). Works with Claude Code, Claude Cowork, Claude.ai, and any agent that reads markdown.
@@ -22,7 +22,7 @@ You are working with the **Jaz/Juan REST API** — the backend for Jaz (Singapor
 
 **Base URL**: `https://api.getjaz.com`
 **Auth**: `x-jk-api-key: <key>` header on every request — key has `jk-` prefix (e.g., `jk-a1b2c3...`). NOT `Authorization: Bearer` or `x-api-key`.
-**Content-Type**: `application/json` for all POST/PUT/PATCH
+**Content-Type**: `application/json` for all POST/PUT/PATCH (except multipart endpoints: `createBusinessTransactionFromAttachment` FILE mode, `importBankStatementFromAttachment`, and attachment uploads)
 **All paths are prefixed**: `/api/v1/` (e.g., `https://api.getjaz.com/api/v1/invoices`)
 
 ## Critical Rules
@@ -129,6 +129,14 @@ You are working with the **Jaz/Juan REST API** — the backend for Jaz (Singapor
 55. **Scheduled endpoints support date aliases** — `txnDateAliases` middleware (mapping `issueDate`/`date` → `valueDate`) now applies to all scheduled create/update endpoints: `POST/PUT /scheduled/invoices`, `POST/PUT /scheduled/bills`, `POST/PUT /scheduled/journals`, `POST/PUT /scheduled/subscriptions`.
 56. **Kebab-case URL aliases** — `capsuleTypes` endpoints also accept kebab-case paths: `/capsule-types` (list, search, CRUD). `moveTransactionCapsules` also accepts `/move-transaction-capsules`. Both camelCase and kebab-case work identically.
 
+### Jaz Magic — Extraction & Autofill
+57. **When the user starts from an attachment, always use Jaz Magic** — if the input is a PDF, JPG, or any document image (invoice, bill, receipt), the correct path is `POST /magic/createBusinessTransactionFromAttachment`. Do NOT manually construct a `POST /invoices` or `POST /bills` payload from an attachment — Jaz Magic handles the entire extraction-and-autofill pipeline server-side: OCR, line item detection, contact matching, CoA auto-mapping via ML learning, and draft creation with all fields pre-filled. Only use `POST /invoices` or `POST /bills` when building transactions from structured data (JSON, CSV, database rows) where the fields are already known.
+58. **Two upload modes with different content types** — `sourceType: "FILE"` requires **multipart/form-data** with `sourceFile` blob (JSON body fails with 400 "sourceFile is a required field"). `sourceType: "URL"` accepts **application/json** with `sourceURL` string. The OAS only documents URL mode — FILE mode (the common case) is undocumented.
+59. **Three required fields**: `sourceFile` (multipart blob — NOT `file`), `businessTransactionType` (`"INVOICE"` or `"BILL"` only — `EXPENSE` rejected), `sourceType` (`"FILE"` or `"URL"`). All three are validated server-side.
+60. **Response maps transaction types**: Request `BILL` → response `businessTransactionType: "PURCHASE"`. Request `INVOICE` → response `businessTransactionType: "SALE"`. S3 paths follow: `/purchases/` vs `/sales/`.
+61. **Extraction is asynchronous** — the API response is immediate (file upload confirmation only). The actual Magic pipeline — OCR, line item extraction, contact matching, CoA learning, and autofill — runs asynchronously. The `subscriptionFBPath` in the response (e.g., `magic_transactions/{orgId}/purchase/{fileId}`) is a Firebase Realtime Database path for subscribing to extraction status updates.
+62. **Accepts PDF and JPG/JPEG** — both file types confirmed working. Handwritten documents are accepted at upload stage (extraction quality varies). `fileType` in response reflects actual format: `"PDF"`, `"JPEG"`.
+
 ## Supporting Files
 
 For detailed reference, read these files in this skill directory:
@@ -154,6 +162,8 @@ The backend DX overhaul is live. Key improvements now available:
 
 ## Recommended Client Patterns
 
+- **Starting from an attachment?** → Use Jaz Magic (`POST /magic/createBusinessTransactionFromAttachment`). Never manually parse a PDF/JPG to construct `POST /invoices` or `POST /bills` — let the extraction & autofill pipeline handle it.
+- **Starting from structured data?** → Use `POST /invoices` or `POST /bills` directly with the known field values.
 - **Serialization (Python)**: `model_dump(mode="json", by_alias=True, exclude_unset=True, exclude_none=True)`
 - **Field names**: All request bodies use camelCase
 - **Date serialization**: Python `date` type → `YYYY-MM-DD` strings

package/assets/skills/api/references/dependencies.md

@@ -54,8 +54,9 @@ Resources MUST be created in this order. Steps at the same level can run in para
 - `POST /items` → create items (needs CoA + tax profile IDs from Levels 0-1)
 
 ### Level 3: Transactions (parallel)
-- `POST /invoices` → create invoices (needs contacts + CoA + tax profiles)
-- `POST /bills` → create bills (same deps, can embed payments)
+- `POST /magic/createBusinessTransactionFromAttachment` → **starting from an attachment (PDF/JPG)?** Use Jaz Magic — extraction & autofill creates a draft invoice or bill with all fields pre-filled. See SKILL.md Rules 57-62.
+- `POST /invoices` → create invoices from structured data (needs contacts + CoA + tax profiles)
+- `POST /bills` → create bills from structured data (same deps, can embed payments)
 - `POST /journals` → create journal entries (needs CoA)
 - `POST /cash-in-journals` → cash receipts (needs bank account from CoA)
 - `POST /cash-out-journals` → cash payments (needs bank account from CoA)

package/assets/skills/api/references/endpoints.md

@@ -790,6 +790,84 @@ Valid `datatypeCode`: `TEXT`, `NUMBER`, `BOOLEAN`, `DATE`, `LINK`.
 
 ---
 
+## 14g. Jaz Magic — Extraction & Autofill
+
+### POST /api/v1/magic/createBusinessTransactionFromAttachment
+
+**When the user starts from an attachment (PDF, JPG, document image), this is the endpoint to use.** Do not manually parse files to construct `POST /invoices` or `POST /bills` — Jaz Magic handles the full extraction-and-autofill pipeline server-side: OCR, line item detection, contact matching, and CoA auto-mapping via ML learning. Creates a complete draft transaction with all fields pre-filled. Use `POST /invoices` or `POST /bills` only when building from structured data where the fields are already known.
+
+Processing is **asynchronous** — the API response confirms file upload immediately. The extraction pipeline runs server-side and pushes status updates via Firebase Realtime Database.
+
+**Two modes** — content type depends on `sourceType`:
+
+#### FILE mode (multipart/form-data) — most common
+
+```
+POST /api/v1/magic/createBusinessTransactionFromAttachment
+Content-Type: multipart/form-data
+
+Fields:
+  - sourceFile: PDF or JPG file blob (NOT "file")
+  - businessTransactionType: "INVOICE" or "BILL" (NOT "EXPENSE")
+  - sourceType: "FILE"
+```
+
+```json
+/ Response (201):
+{
+  "data": {
+    "businessTransactionType": "PURCHASE",
+    "filename": "NB64458.pdf",
+    "invalidFiles": [],
+    "validFiles": [{
+      "subscriptionFBPath": "magic_transactions/{orgId}/purchase/{fileId}",
+      "errorCode": null,
+      "errorMessage": null,
+      "fileDetails": {
+        "fileId": "6e999313b8b53ccef0757394ee6c7e6a",
+        "fileType": "PDF",
+        "fileURL": "https://s3.ap-southeast-1.amazonaws.com/.../{resourceId}.PDF",
+        "fileName": "NB64458.pdf"
+      }
+    }]
+  }
+}
+```
+
+#### URL mode (application/json) — for remote files
+
+```json
+/ Request:
+POST /api/v1/magic/createBusinessTransactionFromAttachment
+Content-Type: application/json
+
+{
+  "businessTransactionType": "BILL",
+  "sourceType": "URL",
+  "sourceURL": "https://example.com/invoice.pdf"
+}
+
+/ Response: same shape as FILE mode
+```
+
+**What Jaz Magic extracts and autofills:**
+- Line items (description, quantity, unit price, amounts)
+- Contact name and details (matched against existing contacts)
+- Chart of Accounts mapping (ML-based learning from past transactions)
+- Tax amounts and profiles
+- Document reference numbers, dates, currency
+
+**Key gotchas:**
+- `sourceFile` is the field name (NOT `file`) — same pattern as bank statement endpoint
+- Only `INVOICE` and `BILL` accepted — `EXPENSE` returns 422
+- Response maps types: `INVOICE` → `SALE`, `BILL` → `PURCHASE`
+- JSON body with `sourceType: "FILE"` always fails (400) — MUST use multipart
+- `subscriptionFBPath` is the Firebase path for tracking extraction progress
+- All three fields (`sourceFile`/`sourceURL`, `businessTransactionType`, `sourceType`) are required — omitting any returns 422
+- File types confirmed: PDF, JPG/JPEG (handwritten documents accepted — extraction quality varies)
+
+---
+
 ## 15. Bank Records
 
 ### POST /api/v1/magic/importBankStatementFromAttachment (multipart)

package/assets/skills/api/references/feature-glossary.md

@@ -14,7 +14,7 @@ Key capabilities: draft/approval workflows, multi-currency (auto-fetch ECB rates
 
 If payment date equals invoice date, it's recorded as a cash transaction (not AR). Transaction fees are deducted from cash received. RGL = `(Invoice payment / Transaction Rate) - (Cash received / Payment Rate)`.
 
-**API**: CRUD `GET/POST/PUT/DELETE /invoices`, `POST /invoices/search`, `POST /invoices/:id/payments`, `GET /invoices/:id/payments`, `POST /invoices/:id/credits`, `GET /invoices/:id/download`, `POST/GET/DELETE /invoices/:id/attachments`, `PUT /invoices/:id/approve`, `POST /scheduled/invoices` (CRUD), `POST /scheduled/subscriptions` (recurring). Generic payment ops: `GET/PUT/DELETE /payments/:id`
+**API**: CRUD `GET/POST/PUT/DELETE /invoices`, `POST /invoices/search`, `POST /invoices/:id/payments`, `GET /invoices/:id/payments`, `POST /invoices/:id/credits`, `GET /invoices/:id/download`, `POST/GET/DELETE /invoices/:id/attachments`, `PUT /invoices/:id/approve`, `POST /scheduled/invoices` (CRUD), `POST /scheduled/subscriptions` (recurring). Generic payment ops: `GET/PUT/DELETE /payments/:id`. **Starting from a PDF/JPG attachment?** Use `POST /magic/createBusinessTransactionFromAttachment` instead — Jaz Magic handles extraction & autofill (see AI Agents section).
 
 ---
 
@@ -26,7 +26,7 @@ Key capabilities: bill receipts (short-form template creating bill + payment tog
 
 Transaction fees are added to cash spent (not deducted like invoices). RGL = `(Cash spent / Payment rate) - (Bill payment / Transaction rate)`.
 
-**API**: CRUD `GET/POST/PUT/DELETE /bills`, `POST /bills/search`, `POST /bills/:id/payments`, `GET /bills/:id/payments`, `POST /bills/:id/credits`, `POST/GET/DELETE /bills/:id/attachments`, `PUT /bills/:id/approve`, `POST /scheduled/bills` (CRUD). Generic payment ops: `GET/PUT/DELETE /payments/:id`
+**API**: CRUD `GET/POST/PUT/DELETE /bills`, `POST /bills/search`, `POST /bills/:id/payments`, `GET /bills/:id/payments`, `POST /bills/:id/credits`, `POST/GET/DELETE /bills/:id/attachments`, `PUT /bills/:id/approve`, `POST /scheduled/bills` (CRUD). Generic payment ops: `GET/PUT/DELETE /payments/:id`. **Starting from a PDF/JPG attachment?** Use `POST /magic/createBusinessTransactionFromAttachment` instead — Jaz Magic handles extraction & autofill (see AI Agents section).
 
 ---
 
@@ -173,9 +173,9 @@ Fixed assets lock their linked line items — cannot edit account, amounts, or e
 
 **Agent Builder**: Configure custom AI agents in Settings > Agent Builder with name, email (a-z, 0-9, + symbol), and workflow preferences.
 
-**Jaz Magic**: Contact-level setting controlling auto-extraction behavior — line items (detailed extraction), summary totals (single amount), or none. Up to 10 images can be merged into a single PDF.
+**Jaz Magic**: The extraction & autofill engine. When users start from an attachment (PDF, JPG, document image), Jaz Magic is the correct path — it handles OCR, line item detection, contact matching, and CoA auto-mapping via ML learning, producing a complete draft transaction. Contact-level settings control extraction behavior: line items (detailed extraction), summary totals (single amount), or none. Up to 10 images can be merged into a single PDF. **Do not manually parse attachments to construct `POST /invoices` or `POST /bills` — always use Jaz Magic when the input is a file.**
 
-**API**: `POST /magic/createBusinessTransactionFromAttachment` (OCR PDF → draft transaction), `POST /magic/importBankStatementFromAttachment`, `PUT /invoices/magic-update`, `PUT /bills/magic-update`, `PUT /journals/magic-update`, `GET /invoices/magic-search`, `GET /bills/magic-search` (all magic endpoints use `x-magic-api-key`)
+**API**: `POST /magic/createBusinessTransactionFromAttachment` (**attachment → draft transaction** — the primary endpoint for file-based creation), `POST /magic/importBankStatementFromAttachment` (bank statements), `PUT /invoices/magic-update`, `PUT /bills/magic-update`, `PUT /journals/magic-update`, `GET /invoices/magic-search`, `GET /bills/magic-search` (all magic endpoints use `x-magic-api-key`)
 
 ---
 

package/assets/skills/api/references/field-map.md

@@ -260,6 +260,23 @@ When POSTing, `classificationType` must be one of these exact strings (same as `
 
 ---
 
+## Jaz Magic — Extraction & Autofill
+
+| What You'd Guess | Actual API Field | Notes |
+|------------------|-------------------|-------|
+| `file` | `sourceFile` | Multipart blob — same pattern as bank statement |
+| `type: "BILL"` | `businessTransactionType: "BILL"` | Request accepts `INVOICE` or `BILL` only |
+| Response `"BILL"` | Response `"PURCHASE"` | Response maps: `BILL` → `PURCHASE`, `INVOICE` → `SALE` |
+| JSON body | multipart/form-data | FILE mode requires multipart — JSON returns 400 |
+| Sync response | Async extraction | Response = upload confirmation; extraction & autofill run async |
+| `status` field | `subscriptionFBPath` | Firebase path for tracking extraction progress |
+
+**Content-Type depends on sourceType:**
+- `sourceType: "FILE"` → `Content-Type: multipart/form-data` (MUST use multipart)
+- `sourceType: "URL"` → `Content-Type: application/json` (JSON body works)
+
+---
+
 ## Bank Records
 
 | What You'd Guess | Actual API Field | Notes |

package/assets/skills/api/references/full-api-surface.md

@@ -386,7 +386,7 @@
 
 | Method | Path | Description |
 |--------|------|-------------|
-| POST | `/magic/createBusinessTransactionFromAttachment` | OCR: Convert PDF → transaction |
+| POST | `/magic/createBusinessTransactionFromAttachment` | **Jaz Magic: Extraction & Autofill.** Upload PDF/JPG → full extraction pipeline (OCR, line items, contact matching, CoA ML learning) → draft invoice or bill with all fields autofilled. FILE mode = multipart (`sourceFile` blob), URL mode = JSON (`sourceURL`). Async — returns `subscriptionFBPath` for tracking extraction progress. Request `INVOICE` → response `SALE`, `BILL` → `PURCHASE`. |
 | POST | `/magic/importBankStatementFromAttachment` | Convert bank statement → entries |
 | PUT | `/invoices/magic-update` | AI-enhanced invoice update |
 | PUT | `/bills/magic-update` | AI-enhanced bill update |

package/assets/skills/conversion/SKILL.md

@@ -1,6 +1,6 @@
 ---
 name: conversion
-version: 2.6.0
+version: 2.7.0
 description: Accounting data conversion skill — migrates customer data from Xero, QuickBooks, Sage, MYOB, and Excel exports to Jaz. Covers config, quick, and full conversion workflows, Excel parsing, CoA/contact/tax/items mapping, clearing accounts, TTB, and TB verification.
 ---
 

package/assets/skills/transaction-recipes/SKILL.md

@@ -1,6 +1,6 @@
 ---
 name: transaction-recipes
-version: 2.6.0
+version: 2.7.0
 description: 16 IFRS-compliant recipes for complex multi-step accounting in Jaz — prepaid amortization, deferred revenue, loan schedules, IFRS 16 leases, hire purchase, fixed deposits, asset disposal, FX revaluation, ECL provisioning, IAS 37 provisions, dividends, intercompany, and capital WIP. Each recipe includes journal entries, capsule structure, and verification steps. Paired with 10 financial calculators that produce execution-ready blueprints with workings.
 license: MIT
 compatibility: Works with Claude Code, Claude Cowork, Claude.ai, and any agent that reads markdown. For API payloads, load the jaz-api skill alongside this one.

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();
+    });
+});

package/dist/__tests__/asset-disposal.test.js

@@ -0,0 +1,249 @@
+import { describe, it, expect } from 'vitest';
+import { calculateAssetDisposal } from '../calc/asset-disposal.js';
+import { CalcValidationError } from '../calc/validate.js';
+describe('calculateAssetDisposal (gain)', () => {
+    const base = {
+        cost: 50000,
+        salvageValue: 5000,
+        usefulLifeYears: 5,
+        acquisitionDate: '2022-01-01',
+        disposalDate: '2025-06-15',
+        proceeds: 20000,
+    };
+    it('NBV = cost - accumulated depreciation', () => {
+        const r = calculateAssetDisposal(base);
+        expect(r.netBookValue).toBe(r.inputs.cost - r.accumulatedDepreciation);
+    });
+    it('gainOrLoss = proceeds - NBV', () => {
+        const r = calculateAssetDisposal(base);
+        expect(r.gainOrLoss).toBe(r.inputs.proceeds - r.netBookValue);
+    });
+    it('isGain is true when proceeds > NBV', () => {
+        const r = calculateAssetDisposal(base);
+        expect(r.isGain).toBe(true);
+    });
+    it('monthsHeld is calculated correctly', () => {
+        const r = calculateAssetDisposal(base);
+        // Jan 2022 to Jun 2025 = 42 months, day 15 >= day 01 so +1 = 42
+        expect(r.monthsHeld).toBe(42);
+    });
+    it('journal is balanced', () => {
+        const r = calculateAssetDisposal(base);
+        const debits = r.disposalJournal.lines.reduce((s, l) => s + l.debit, 0);
+        const credits = r.disposalJournal.lines.reduce((s, l) => s + l.credit, 0);
+        expect(Math.abs(debits - credits)).toBeLessThan(0.01);
+    });
+    it('journal includes Cash, Accum Dep, FA at cost, and Gain', () => {
+        const r = calculateAssetDisposal(base);
+        const accounts = r.disposalJournal.lines.map(l => l.account);
+        expect(accounts).toContain('Cash / Bank Account');
+        expect(accounts).toContain('Accumulated Depreciation');
+        expect(accounts).toContain('Fixed Asset (at cost)');
+        expect(accounts).toContain('Gain on Disposal');
+    });
+});
+describe('calculateAssetDisposal (loss)', () => {
+    const base = {
+        cost: 50000,
+        salvageValue: 5000,
+        usefulLifeYears: 5,
+        acquisitionDate: '2022-01-01',
+        disposalDate: '2023-06-15',
+        proceeds: 5000, // low proceeds = loss
+    };
+    it('isGain is false when proceeds < NBV', () => {
+        const r = calculateAssetDisposal(base);
+        expect(r.isGain).toBe(false);
+        expect(r.gainOrLoss).toBeLessThan(0);
+    });
+    it('journal includes Loss on Disposal', () => {
+        const r = calculateAssetDisposal(base);
+        const accounts = r.disposalJournal.lines.map(l => l.account);
+        expect(accounts).toContain('Loss on Disposal');
+        expect(accounts).not.toContain('Gain on Disposal');
+    });
+    it('journal is balanced', () => {
+        const r = calculateAssetDisposal(base);
+        const debits = r.disposalJournal.lines.reduce((s, l) => s + l.debit, 0);
+        const credits = r.disposalJournal.lines.reduce((s, l) => s + l.credit, 0);
+        expect(Math.abs(debits - credits)).toBeLessThan(0.01);
+    });
+});
+describe('calculateAssetDisposal (scrap / write-off)', () => {
+    const base = {
+        cost: 50000,
+        salvageValue: 5000,
+        usefulLifeYears: 5,
+        acquisitionDate: '2022-01-01',
+        disposalDate: '2024-01-01',
+        proceeds: 0,
+    };
+    it('gainOrLoss is negative (loss) when proceeds = 0', () => {
+        const r = calculateAssetDisposal(base);
+        expect(r.isGain).toBe(false);
+        expect(r.gainOrLoss).toBeLessThan(0);
+    });
+    it('journal has no Cash line when proceeds = 0', () => {
+        const r = calculateAssetDisposal(base);
+        const accounts = r.disposalJournal.lines.map(l => l.account);
+        expect(accounts).not.toContain('Cash / Bank Account');
+    });
+    it('journal is still balanced', () => {
+        const r = calculateAssetDisposal(base);
+        const debits = r.disposalJournal.lines.reduce((s, l) => s + l.debit, 0);
+        const credits = r.disposalJournal.lines.reduce((s, l) => s + l.credit, 0);
+        expect(Math.abs(debits - credits)).toBeLessThan(0.01);
+    });
+});
+describe('calculateAssetDisposal (at book value)', () => {
+    it('gainOrLoss = 0 and isGain = true when proceeds = NBV', () => {
+        // Fully depreciated over 5 years: NBV = salvage = 5000
+        const r = calculateAssetDisposal({
+            cost: 50000,
+            salvageValue: 5000,
+            usefulLifeYears: 5,
+            acquisitionDate: '2020-01-01',
+            disposalDate: '2025-01-01',
+            proceeds: 5000, // exactly = salvage (fully depreciated)
+        });
+        expect(r.gainOrLoss).toBe(0);
+        expect(r.isGain).toBe(true);
+    });
+});
+describe('calculateAssetDisposal (fully depreciated)', () => {
+    it('accum dep capped at depreciable base (held past useful life)', () => {
+        const r = calculateAssetDisposal({
+            cost: 50000,
+            salvageValue: 5000,
+            usefulLifeYears: 5,
+            acquisitionDate: '2018-01-01', // held 7+ years
+            disposalDate: '2025-06-01',
+            proceeds: 3000,
+        });
+        expect(r.accumulatedDepreciation).toBe(45000); // max = cost - salvage
+        expect(r.netBookValue).toBe(5000);
+    });
+});
+describe('calculateAssetDisposal (DDB method)', () => {
+    it('DDB accumulated dep is correct', () => {
+        const r = calculateAssetDisposal({
+            cost: 50000,
+            salvageValue: 5000,
+            usefulLifeYears: 5,
+            acquisitionDate: '2022-01-01',
+            disposalDate: '2022-12-31', // ~12 months (monthsBetween rounds up partial)
+            proceeds: 30000,
+            method: 'ddb',
+        });
+        // DDB year 1: 50000 * 2/5 = 20000
+        expect(r.accumulatedDepreciation).toBe(20000);
+        expect(r.netBookValue).toBe(30000);
+        expect(r.gainOrLoss).toBe(0); // proceeds = NBV
+    });
+    it('DDB journal is balanced', () => {
+        const r = calculateAssetDisposal({
+            cost: 50000,
+            salvageValue: 5000,
+            usefulLifeYears: 5,
+            acquisitionDate: '2022-01-01',
+            disposalDate: '2024-06-15',
+            proceeds: 10000,
+            method: 'ddb',
+        });
+        const debits = r.disposalJournal.lines.reduce((s, l) => s + l.debit, 0);
+        const credits = r.disposalJournal.lines.reduce((s, l) => s + l.credit, 0);
+        expect(Math.abs(debits - credits)).toBeLessThan(0.01);
+    });
+});
+describe('calculateAssetDisposal (rounding)', () => {
+    it('normalizes inputs to 2dp and journals still balance', () => {
+        const r = calculateAssetDisposal({
+            cost: 50000.999,
+            salvageValue: 5000.111,
+            usefulLifeYears: 5,
+            acquisitionDate: '2022-01-01',
+            disposalDate: '2024-01-01',
+            proceeds: 20000.555,
+        });
+        // Inputs should be normalized
+        expect(r.inputs.cost).toBe(50001);
+        expect(r.inputs.salvageValue).toBe(5000.11);
+        expect(r.inputs.proceeds).toBe(20000.56);
+        // Journal must still balance
+        const debits = r.disposalJournal.lines.reduce((s, l) => s + l.debit, 0);
+        const credits = r.disposalJournal.lines.reduce((s, l) => s + l.credit, 0);
+        expect(Math.abs(debits - credits)).toBeLessThan(0.01);
+    });
+});
+describe('calculateAssetDisposal (blueprint)', () => {
+    const base = {
+        cost: 50000,
+        salvageValue: 5000,
+        usefulLifeYears: 5,
+        acquisitionDate: '2022-01-01',
+        disposalDate: '2025-06-15',
+        proceeds: 20000,
+    };
+    it('blueprint always present (no startDate needed)', () => {
+        const r = calculateAssetDisposal(base);
+        expect(r.blueprint).not.toBeNull();
+        expect(r.blueprint.capsuleDescription).toBeTruthy();
+    });
+    it('blueprint has 2 steps (journal + note)', () => {
+        const r = calculateAssetDisposal(base);
+        expect(r.blueprint.steps).toHaveLength(2);
+    });
+    it('step 1 = journal (disposal entry)', () => {
+        const r = calculateAssetDisposal(base);
+        expect(r.blueprint.steps[0].action).toBe('journal');
+    });
+    it('step 2 = note (FA register update)', () => {
+        const r = calculateAssetDisposal(base);
+        expect(r.blueprint.steps[1].action).toBe('note');
+    });
+    it('capsuleType is Asset Disposal', () => {
+        const r = calculateAssetDisposal(base);
+        expect(r.blueprint.capsuleType).toBe('Asset Disposal');
+    });
+    it('capsuleDescription contains IAS 16', () => {
+        const r = calculateAssetDisposal(base);
+        expect(r.blueprint.capsuleDescription).toContain('IAS 16');
+    });
+});
+describe('calculateAssetDisposal (validation)', () => {
+    const base = {
+        cost: 50000,
+        salvageValue: 5000,
+        usefulLifeYears: 5,
+        acquisitionDate: '2022-01-01',
+        disposalDate: '2025-06-15',
+        proceeds: 20000,
+    };
+    it('rejects zero cost', () => {
+        expect(() => calculateAssetDisposal({ ...base, cost: 0 })).toThrow(CalcValidationError);
+    });
+    it('rejects negative proceeds', () => {
+        expect(() => calculateAssetDisposal({ ...base, proceeds: -100 })).toThrow(CalcValidationError);
+    });
+    it('rejects salvage >= cost', () => {
+        expect(() => calculateAssetDisposal({ ...base, salvageValue: 50000 })).toThrow(CalcValidationError);
+    });
+    it('rejects disposal before acquisition', () => {
+        expect(() => calculateAssetDisposal({
+            ...base, acquisitionDate: '2025-01-01', disposalDate: '2024-01-01',
+        })).toThrow(CalcValidationError);
+    });
+    it('rejects invalid date format', () => {
+        expect(() => calculateAssetDisposal({
+            ...base, acquisitionDate: '01-01-2022',
+        })).toThrow(CalcValidationError);
+    });
+    it('allows zero salvage value', () => {
+        const r = calculateAssetDisposal({ ...base, salvageValue: 0 });
+        expect(r.accumulatedDepreciation).toBeGreaterThan(0);
+    });
+    it('allows zero proceeds (scrap)', () => {
+        const r = calculateAssetDisposal({ ...base, proceeds: 0 });
+        expect(r.isGain).toBe(false);
+    });
+});

package/dist/__tests__/blueprint.test.js

@@ -0,0 +1,72 @@
+import { describe, it, expect } from 'vitest';
+import { journalStep, billStep, invoiceStep, cashOutStep, cashInStep, fixedAssetStep, noteStep, fmtCapsuleAmount, fmtAmt, } from '../calc/blueprint.js';
+describe('step builders', () => {
+    const lines = [
+        { account: 'Cash', debit: 100, credit: 0 },
+        { account: 'Loan', debit: 0, credit: 100 },
+    ];
+    it('journalStep sets action to journal', () => {
+        const s = journalStep(1, 'Test', '2025-01-01', lines);
+        expect(s.action).toBe('journal');
+        expect(s.step).toBe(1);
+        expect(s.description).toBe('Test');
+        expect(s.date).toBe('2025-01-01');
+        expect(s.lines).toBe(lines);
+    });
+    it('billStep sets action to bill', () => {
+        const s = billStep(1, 'Supplier bill', '2025-01-01', lines);
+        expect(s.action).toBe('bill');
+    });
+    it('invoiceStep sets action to invoice', () => {
+        const s = invoiceStep(1, 'Customer invoice', '2025-01-01', lines);
+        expect(s.action).toBe('invoice');
+    });
+    it('cashOutStep sets action to cash-out', () => {
+        const s = cashOutStep(1, 'Payment', '2025-01-01', lines);
+        expect(s.action).toBe('cash-out');
+    });
+    it('cashInStep sets action to cash-in', () => {
+        const s = cashInStep(1, 'Receipt', '2025-01-01', lines);
+        expect(s.action).toBe('cash-in');
+    });
+    it('fixedAssetStep sets action to fixed-asset with empty lines', () => {
+        const s = fixedAssetStep(2, 'Register ROU', '2025-01-01');
+        expect(s.action).toBe('fixed-asset');
+        expect(s.lines).toEqual([]);
+    });
+    it('noteStep sets action to note with empty lines', () => {
+        const s = noteStep(3, 'Update FA register');
+        expect(s.action).toBe('note');
+        expect(s.lines).toEqual([]);
+        expect(s.date).toBeNull();
+    });
+    it('null date passes through', () => {
+        const s = journalStep(1, 'Test', null, lines);
+        expect(s.date).toBeNull();
+    });
+});
+describe('fmtCapsuleAmount', () => {
+    it('formats with currency', () => {
+        expect(fmtCapsuleAmount(100000, 'SGD')).toBe('SGD 100,000');
+    });
+    it('formats without currency', () => {
+        expect(fmtCapsuleAmount(100000)).toBe('100,000');
+    });
+    it('formats small amounts', () => {
+        expect(fmtCapsuleAmount(50, 'USD')).toBe('USD 50');
+    });
+});
+describe('fmtAmt', () => {
+    it('formats with currency and 2dp', () => {
+        expect(fmtAmt(1234.5, 'SGD')).toBe('SGD 1,234.50');
+    });
+    it('formats without currency', () => {
+        expect(fmtAmt(1234.56)).toBe('1,234.56');
+    });
+    it('formats zero', () => {
+        expect(fmtAmt(0)).toBe('0.00');
+    });
+    it('handles null currency', () => {
+        expect(fmtAmt(100, null)).toBe('100.00');
+    });
+});