jaz-cli 2.6.0 → 2.8.0

package/dist/jobs/audit-prep.js

@@ -0,0 +1,211 @@
+/**
+ * Audit Preparation blueprint generator.
+ * Produces a structured JobBlueprint for compiling audit-ready financial packs —
+ * no actual API calls, just an actionable checklist for accountants.
+ */
+import { buildSummary } from './types.js';
+import { parseQuarterPeriod, parseYearPeriod } from './validate.js';
+function parsePeriod(period) {
+    if (/^\d{4}-Q[1-4]$/i.test(period)) {
+        return parseQuarterPeriod(period);
+    }
+    return parseYearPeriod(period);
+}
+export function generateAuditPrepBlueprint(opts) {
+    const p = parsePeriod(opts.period);
+    const currency = opts.currency ?? 'SGD';
+    // Phase 1: Financial Statements
+    const financialStatements = {
+        name: 'Financial Statements',
+        description: `Generate the core financial statements for ${p.label}.`,
+        steps: [
+            {
+                order: 1,
+                description: 'Generate Trial Balance',
+                category: 'report',
+                apiCall: 'POST /generate-reports/trial-balance',
+                apiBody: {
+                    startDate: p.startDate,
+                    endDate: p.endDate,
+                },
+                verification: 'TB balances (total debits = total credits)',
+            },
+            {
+                order: 2,
+                description: 'Generate Balance Sheet',
+                category: 'report',
+                apiCall: 'POST /generate-reports/balance-sheet',
+                apiBody: {
+                    primarySnapshotDate: p.endDate,
+                },
+                verification: 'Assets = Liabilities + Equity',
+            },
+            {
+                order: 3,
+                description: 'Generate Profit & Loss',
+                category: 'report',
+                apiCall: 'POST /generate-reports/profit-and-loss',
+                apiBody: {
+                    primarySnapshotDate: p.endDate,
+                    secondarySnapshotDate: p.startDate,
+                },
+                verification: 'Net profit/loss ties to retained earnings movement on BS',
+            },
+            {
+                order: 4,
+                description: 'Generate Cash Flow Statement',
+                category: 'report',
+                apiCall: 'POST /generate-reports/cashflow',
+                apiBody: {
+                    primaryStartDate: p.startDate,
+                    primaryEndDate: p.endDate,
+                },
+                verification: 'Closing cash ties to bank balances on BS',
+            },
+            {
+                order: 5,
+                description: 'Generate Statement of Changes in Equity',
+                category: 'report',
+                apiCall: 'POST /generate-reports/equity-movement',
+                apiBody: {
+                    primarySnapshotStartDate: p.startDate,
+                    primarySnapshotEndDate: p.endDate,
+                },
+                verification: 'Closing equity ties to BS equity section',
+            },
+        ],
+    };
+    // Phase 2: Supporting Schedules
+    const supportingSchedules = {
+        name: 'Supporting Schedules',
+        description: 'Generate detailed schedules that support the financial statements.',
+        steps: [
+            {
+                order: 6,
+                description: 'Generate AR aging schedule',
+                category: 'report',
+                apiCall: 'POST /generate-reports/ar-aging',
+                apiBody: {
+                    endDate: p.endDate,
+                },
+                verification: 'AR aging total ties to trade receivables on BS',
+            },
+            {
+                order: 7,
+                description: 'Generate AP aging schedule',
+                category: 'report',
+                apiCall: 'POST /generate-reports/ap-aging',
+                apiBody: {
+                    endDate: p.endDate,
+                },
+                verification: 'AP aging total ties to trade payables on BS',
+            },
+            {
+                order: 8,
+                description: 'Generate Fixed Asset register',
+                category: 'report',
+                apiCall: 'POST /generate-reports/fixed-assets',
+                apiBody: {
+                    endDate: p.endDate,
+                },
+                notes: 'Include cost, accumulated depreciation, and NBV per asset. Should show additions, disposals, and depreciation for the period.',
+                verification: 'FA register NBV total ties to property/equipment on BS',
+            },
+            {
+                order: 9,
+                description: 'Generate Tax Ledger',
+                category: 'report',
+                apiCall: 'POST /generate-reports/vat-ledger',
+                apiBody: {
+                    startDate: p.startDate,
+                    endDate: p.endDate,
+                },
+                notes: 'Full tax ledger for the audit period — auditors will test-check individual entries',
+                verification: 'Tax ledger totals consistent with GST returns filed',
+            },
+        ],
+    };
+    // Phase 3: Reconciliations
+    const reconciliations = {
+        name: 'Reconciliations',
+        description: 'Perform key reconciliations for audit evidence.',
+        steps: [
+            {
+                order: 10,
+                description: 'Bank reconciliation for all accounts',
+                category: 'verify',
+                apiCall: 'POST /bank-records/search',
+                apiBody: {
+                    filters: {
+                        reconciliationStatus: 'UNRECONCILED',
+                    },
+                },
+                recipeRef: 'bank-reconciliation',
+                notes: 'Reconcile all bank accounts as at period end. Document any reconciling items (outstanding cheques, deposits in transit).',
+                verification: 'All bank accounts reconciled — GL balance agrees with bank statements',
+            },
+            {
+                order: 11,
+                description: 'Intercompany reconciliation',
+                category: 'verify',
+                apiCall: 'POST /generate-reports/trial-balance',
+                conditional: 'If intercompany transactions exist',
+                notes: 'Compare intercompany receivables and payables across entities. Eliminate for consolidated accounts.',
+                verification: 'Intercompany balances net to zero across group entities',
+            },
+            {
+                order: 12,
+                description: 'Loan schedule reconciliation',
+                category: 'verify',
+                calcCommand: 'jaz calc loan',
+                conditional: 'If loan facilities exist',
+                notes: 'Compare loan amortization schedule to GL balances. Verify principal, interest, and current/non-current split.',
+                verification: 'Loan balances per GL match lender statements and amortization schedule',
+            },
+        ],
+    };
+    // Phase 4: Export & Compile
+    const exportCompile = {
+        name: 'Export & Compile Audit Pack',
+        description: 'Export all reports and compile the audit-ready pack.',
+        steps: [
+            {
+                order: 13,
+                description: 'Export all data for audit working papers',
+                category: 'export',
+                notes: [
+                    'Export the following as CSV/PDF:',
+                    '(1) Chart of accounts with balances,',
+                    '(2) General ledger detail for the period,',
+                    '(3) All reports generated in phases 1-2,',
+                    '(4) Bank statements and reconciliations,',
+                    '(5) Supporting invoices/bills for sample testing.',
+                ].join(' '),
+                verification: 'All data exports completed successfully',
+            },
+            {
+                order: 14,
+                description: 'Compile audit preparation pack',
+                category: 'report',
+                notes: [
+                    'Organize into audit pack structure:',
+                    '(a) Financial statements (TB, BS, P&L, Cash Flow, Equity),',
+                    '(b) Supporting schedules (AR, AP, FA, Tax),',
+                    '(c) Reconciliations (Bank, Intercompany, Loans),',
+                    '(d) Data exports and sample documents.',
+                    'Include index/table of contents for auditor reference.',
+                ].join(' '),
+                verification: 'Audit pack complete, indexed, and ready for auditor handoff',
+            },
+        ],
+    };
+    const phases = [financialStatements, supportingSchedules, reconciliations, exportCompile];
+    return {
+        jobType: 'audit-prep',
+        period: p.label,
+        currency,
+        mode: 'standalone',
+        phases,
+        summary: buildSummary(phases),
+    };
+}

package/dist/jobs/bank-recon.js

@@ -0,0 +1,163 @@
+/**
+ * Bank Reconciliation blueprint generator.
+ * Produces a structured JobBlueprint describing the bank recon workflow —
+ * no actual API calls, just an actionable checklist for accountants.
+ */
+import { buildSummary } from './types.js';
+import { parseMonthPeriod } from './validate.js';
+export function generateBankReconBlueprint(opts = {}) {
+    const currency = opts.currency ?? 'SGD';
+    const period = opts.period ?? 'current';
+    const accountFilter = opts.account
+        ? { accountName: opts.account }
+        : {};
+    const periodFilter = opts.period
+        ? (() => {
+            const mp = parseMonthPeriod(opts.period);
+            return { valueDateFrom: mp.startDate, valueDateTo: mp.endDate };
+        })()
+        : {};
+    // Phase 1: Identify bank accounts
+    const identify = {
+        name: 'Identify Bank Accounts',
+        description: 'List all bank accounts in the chart of accounts.',
+        steps: [
+            {
+                order: 1,
+                description: 'List bank accounts from chart of accounts',
+                category: 'verify',
+                apiCall: 'POST /chart-of-accounts/search',
+                apiBody: {
+                    filters: {
+                        classificationType: 'Bank Accounts',
+                        ...accountFilter,
+                    },
+                },
+                notes: opts.account
+                    ? `Filtered to account: ${opts.account}`
+                    : 'Returns all bank accounts — pick which to reconcile',
+            },
+        ],
+    };
+    // Phase 2: Pull unreconciled records
+    const pullUnreconciled = {
+        name: 'Pull Unreconciled Records',
+        description: 'Retrieve all unreconciled bank records and check for duplicates.',
+        steps: [
+            {
+                order: 2,
+                description: 'Search unreconciled bank records',
+                category: 'verify',
+                apiCall: 'POST /bank-records/search',
+                apiBody: {
+                    filters: {
+                        reconciliationStatus: 'UNRECONCILED',
+                        ...accountFilter,
+                        ...periodFilter,
+                    },
+                },
+                verification: 'Note total count and amount of unreconciled items',
+            },
+            {
+                order: 3,
+                description: 'Check for duplicate bank records',
+                category: 'verify',
+                apiCall: 'POST /bank-records/search',
+                apiBody: {
+                    filters: {
+                        reconciliationStatus: 'UNRECONCILED',
+                        ...accountFilter,
+                    },
+                },
+                notes: 'Compare reference numbers, amounts, and dates to identify duplicates',
+                verification: 'Flag any records with matching amount + date + reference',
+            },
+        ],
+    };
+    // Phase 3: Resolve unreconciled items
+    const resolve = {
+        name: 'Resolve Unreconciled Items',
+        description: 'Match, create, or flag each unreconciled bank record.',
+        steps: [
+            {
+                order: 4,
+                description: 'Match bank records to existing transactions',
+                category: 'resolve',
+                apiCall: 'POST /bank-records/{id}/reconcile',
+                notes: 'Match by reference, amount, and date against open invoices/bills/journals',
+                recipeRef: 'bank-reconciliation',
+            },
+            {
+                order: 5,
+                description: 'Create transactions from bank statement (Jaz Magic)',
+                category: 'resolve',
+                apiCall: 'POST /bank-records/import-from-attachment',
+                apiBody: {
+                    sourceType: 'FILE',
+                    businessTransactionType: 'BANK_STATEMENT',
+                },
+                notes: 'Import CSV/OFX files — uses sourceFile, accountResourceId fields',
+            },
+            {
+                order: 6,
+                description: 'Create cash receipt/payment journals for unmatched items',
+                category: 'resolve',
+                apiCall: 'POST /journals',
+                recipeRef: 'cash-receipt',
+                notes: 'For bank records with no matching transaction — create cash journal entries',
+            },
+            {
+                order: 7,
+                description: 'Flag remaining items for investigation',
+                category: 'review',
+                notes: 'Items that cannot be matched or journaled need manual investigation — document reason for each',
+                verification: 'All unreconciled items should be resolved or flagged',
+            },
+        ],
+    };
+    // Phase 4: Verification
+    const verification = {
+        name: 'Verification',
+        description: 'Confirm reconciliation is complete and bank balances agree.',
+        steps: [
+            {
+                order: 8,
+                description: 'Re-check unreconciled count',
+                category: 'verify',
+                apiCall: 'POST /bank-records/search',
+                apiBody: {
+                    filters: {
+                        reconciliationStatus: 'UNRECONCILED',
+                        ...accountFilter,
+                    },
+                },
+                verification: 'Unreconciled count should be zero (or only flagged items remain)',
+            },
+            {
+                order: 9,
+                description: 'Review bank balance summary',
+                category: 'verify',
+                apiCall: 'POST /generate-reports/trial-balance',
+                notes: 'Compare GL bank balance to bank statement closing balance',
+                verification: 'GL balance must equal bank statement balance after reconciling items',
+            },
+            {
+                order: 10,
+                description: 'Generate reconciliation report',
+                category: 'report',
+                apiCall: 'POST /generate-reports/trial-balance',
+                notes: 'Document: opening balance, reconciled items, outstanding items, closing balance',
+                verification: 'Reconciliation report balances and is saved for audit trail',
+            },
+        ],
+    };
+    const phases = [identify, pullUnreconciled, resolve, verification];
+    return {
+        jobType: 'bank-recon',
+        period,
+        currency,
+        mode: 'standalone',
+        phases,
+        summary: buildSummary(phases),
+    };
+}

package/dist/jobs/credit-control.js

@@ -0,0 +1,126 @@
+/**
+ * Credit Control blueprint generator.
+ * Produces a structured JobBlueprint for managing overdue receivables —
+ * no actual API calls, just an actionable checklist for accountants.
+ */
+import { buildSummary } from './types.js';
+import { validateOverdueDays } from './validate.js';
+export function generateCreditControlBlueprint(opts = {}) {
+    const overdueDays = opts.overdueDays ?? 30;
+    if (opts.overdueDays !== undefined) {
+        validateOverdueDays(opts.overdueDays);
+    }
+    const currency = opts.currency ?? 'SGD';
+    const period = `Overdue > ${overdueDays} days`;
+    // Phase 1: AR Analysis
+    const arAnalysis = {
+        name: 'AR Analysis',
+        description: 'Generate AR aging and identify overdue invoices beyond the threshold.',
+        steps: [
+            {
+                order: 1,
+                description: 'Generate AR aging report',
+                category: 'report',
+                apiCall: 'POST /generate-reports/ar-aging',
+                notes: 'Current, 1-30, 31-60, 61-90, 90+ day buckets. Focus on buckets beyond threshold.',
+                verification: 'AR aging report generated — note total receivables and overdue amount',
+            },
+            {
+                order: 2,
+                description: `Identify invoices overdue by more than ${overdueDays} days`,
+                category: 'verify',
+                apiCall: 'POST /invoices/search',
+                apiBody: {
+                    filters: {
+                        status: ['APPROVED'],
+                        overdue: true,
+                    },
+                },
+                notes: `Filter to invoices past due by ${overdueDays}+ days. Record customer name, invoice number, amount, and days overdue.`,
+                verification: 'Overdue invoice list matches AR aging report totals',
+            },
+        ],
+    };
+    // Phase 2: Chase List
+    const chaseList = {
+        name: 'Chase List',
+        description: 'Prioritize customers and generate a follow-up action list.',
+        steps: [
+            {
+                order: 3,
+                description: 'Group overdue invoices by customer priority',
+                category: 'review',
+                apiCall: 'POST /invoices/search',
+                apiBody: {
+                    filters: {
+                        status: ['APPROVED'],
+                        overdue: true,
+                    },
+                },
+                notes: 'Rank customers by: (1) total overdue amount, (2) days overdue, (3) payment history. Top customers get priority outreach.',
+                verification: 'Customer priority list established',
+            },
+            {
+                order: 4,
+                description: 'Generate follow-up action list',
+                category: 'report',
+                notes: [
+                    'For each overdue customer, assign action:',
+                    '(a) 30-60 days: friendly reminder email/call,',
+                    '(b) 60-90 days: formal demand letter,',
+                    '(c) 90+ days: escalate to management / external collection.',
+                    'Document contact attempts and agreed payment plans.',
+                ].join(' '),
+                verification: 'Every overdue customer has an assigned follow-up action and owner',
+            },
+        ],
+    };
+    // Phase 3: Bad Debt Assessment
+    const badDebtAssessment = {
+        name: 'Bad Debt Assessment',
+        description: 'Assess doubtful debts and calculate expected credit losses if needed.',
+        steps: [
+            {
+                order: 5,
+                description: 'Identify doubtful debts',
+                category: 'review',
+                apiCall: 'POST /generate-reports/ar-aging',
+                notes: 'Review 90+ day bucket for potential bad debts. Consider: customer financial health, dispute status, collateral, historical write-off rates.',
+                verification: 'Doubtful debt candidates identified and documented',
+            },
+            {
+                order: 6,
+                description: 'Calculate expected credit loss (ECL) provision',
+                category: 'value',
+                calcCommand: 'jaz calc ecl',
+                recipeRef: 'bad-debt-provision',
+                notes: 'ECL model: apply loss rates per aging bucket (e.g., current 0.5%, 30d 2%, 60d 5%, 90d 10%, 120+ 50%). Book provision journal if ECL differs from existing allowance.',
+                verification: 'ECL calculated and compared to existing provision balance. Adjustment journal prepared if needed.',
+            },
+        ],
+    };
+    // Phase 4: Verification
+    const verification = {
+        name: 'Verification',
+        description: 'Review AR aging after all credit control actions.',
+        steps: [
+            {
+                order: 7,
+                description: 'Review AR aging after credit control actions',
+                category: 'verify',
+                apiCall: 'POST /generate-reports/ar-aging',
+                notes: 'Compare to opening AR aging. Document: payments received, payment plans agreed, write-offs processed, provisions updated.',
+                verification: 'AR aging reviewed, all actions documented, follow-up dates set',
+            },
+        ],
+    };
+    const phases = [arAnalysis, chaseList, badDebtAssessment, verification];
+    return {
+        jobType: 'credit-control',
+        period,
+        currency,
+        mode: 'standalone',
+        phases,
+        summary: buildSummary(phases),
+    };
+}

package/dist/jobs/fa-review.js

@@ -0,0 +1,121 @@
+/**
+ * Fixed Asset Review blueprint generator.
+ * Produces a structured JobBlueprint for reviewing the fixed asset register —
+ * no actual API calls, just an actionable checklist for accountants.
+ */
+import { buildSummary } from './types.js';
+export function generateFaReviewBlueprint(opts = {}) {
+    const currency = opts.currency ?? 'SGD';
+    // Phase 1: Register Review
+    const registerReview = {
+        name: 'Register Review',
+        description: 'Pull the fixed asset summary and verify against general ledger balances.',
+        steps: [
+            {
+                order: 1,
+                description: 'Pull fixed asset summary report',
+                category: 'report',
+                apiCall: 'POST /generate-reports/fixed-assets',
+                notes: 'Review: asset description, cost, accumulated depreciation, NBV, useful life remaining, depreciation method per asset',
+                verification: 'FA register generated — note total cost, total accumulated depreciation, total NBV',
+            },
+            {
+                order: 2,
+                description: 'Verify FA register against GL balances',
+                category: 'verify',
+                apiCall: 'POST /generate-reports/trial-balance',
+                notes: 'Compare FA register totals to TB: (1) total cost should match FA cost accounts, (2) total accumulated depreciation should match contra accounts, (3) NBV should match net FA on BS',
+                verification: 'FA register totals agree with GL. Any differences investigated and resolved.',
+            },
+        ],
+    };
+    // Phase 2: Depreciation Check
+    const depreciationCheck = {
+        name: 'Depreciation Check',
+        description: 'Verify depreciation has been run correctly and review fully depreciated assets.',
+        steps: [
+            {
+                order: 3,
+                description: 'Verify depreciation runs are up to date',
+                category: 'verify',
+                apiCall: 'POST /generate-reports/fixed-assets',
+                calcCommand: 'jaz calc depreciation',
+                notes: 'Check that monthly/annual depreciation has been posted for all assets through the current period. Recalculate sample of assets to verify amounts.',
+                verification: 'Depreciation is current — no missed periods. Sample recalculations match posted amounts.',
+            },
+            {
+                order: 4,
+                description: 'Check fully depreciated assets',
+                category: 'review',
+                apiCall: 'POST /generate-reports/fixed-assets',
+                notes: 'Identify assets with NBV = 0 or NBV = salvage value. Review whether: (1) asset is still in use, (2) asset should be disposed/written off, (3) useful life estimate needs revision.',
+                verification: 'All fully depreciated assets reviewed — disposals and write-offs identified',
+            },
+        ],
+    };
+    // Phase 3: Disposals & Write-offs
+    const disposalsWriteoffs = {
+        name: 'Disposals & Write-offs',
+        description: 'Process asset disposals and calculate gain/loss on disposal.',
+        steps: [
+            {
+                order: 5,
+                description: 'Process asset disposals',
+                category: 'adjust',
+                apiCall: 'POST /journals',
+                recipeRef: 'asset-disposal',
+                calcCommand: 'jaz calc asset-disposal',
+                notes: 'For each disposal: (1) calculate NBV at disposal date, (2) compare to sale proceeds, (3) recognize gain or loss. Journal: Dr Bank/Receivable, Dr Accumulated Depreciation, Cr Asset Cost, Cr/Dr Gain/Loss on Disposal.',
+                verification: 'Disposal journals balanced. Gain/loss correctly calculated. Asset removed from register.',
+            },
+            {
+                order: 6,
+                description: 'Process asset write-offs',
+                category: 'adjust',
+                apiCall: 'POST /journals',
+                recipeRef: 'asset-disposal',
+                notes: 'For write-offs (zero proceeds): Dr Accumulated Depreciation, Dr Loss on Write-off (for remaining NBV), Cr Asset Cost. Document reason for write-off (obsolescence, damage, etc.).',
+                verification: 'Write-off journals balanced. Assets removed from register. Reasons documented.',
+            },
+        ],
+    };
+    // Phase 4: Verification
+    const verification = {
+        name: 'Verification',
+        description: 'Final reconciliation of fixed assets to trial balance and reasonableness check.',
+        steps: [
+            {
+                order: 7,
+                description: 'Reconcile updated FA register to trial balance',
+                category: 'verify',
+                apiCall: 'POST /generate-reports/trial-balance',
+                notes: 'After all disposals and write-offs, re-pull TB and FA register. Verify they agree.',
+                verification: 'FA register totals match TB. All movements accounted for (additions, depreciation, disposals, write-offs).',
+            },
+            {
+                order: 8,
+                description: 'Check NBV reasonableness',
+                category: 'review',
+                apiCall: 'POST /generate-reports/fixed-assets',
+                notes: [
+                    'Review remaining NBV for reasonableness:',
+                    '(1) No negative NBV,',
+                    '(2) NBV does not exceed replacement cost,',
+                    '(3) Useful lives are appropriate for asset type,',
+                    '(4) Salvage values are reasonable,',
+                    '(5) No impairment indicators (market value decline, physical damage, change in use).',
+                ].join(' '),
+                verification: 'All NBV values reasonable. No impairment indicators identified, or impairment review initiated where needed.',
+            },
+        ],
+    };
+    const phases = [registerReview, depreciationCheck, disposalsWriteoffs, verification];
+    return {
+        jobType: 'fa-review',
+        period: 'current',
+        currency,
+        mode: 'standalone',
+        phases,
+        summary: buildSummary(phases),
+    };
+}