jaz-cli 2.6.0 → 2.8.0

package/dist/jobs/format.js

@@ -0,0 +1,102 @@
+/**
+ * Output formatters for job blueprints.
+ * Checklist table for human reading, JSON for programmatic use.
+ */
+import chalk from 'chalk';
+const line = (w) => chalk.dim('─'.repeat(w));
+const CATEGORY_LABELS = {
+    verify: 'Verify',
+    accrue: 'Accrue',
+    adjust: 'Adjust',
+    value: 'Value',
+    report: 'Report',
+    lock: 'Lock',
+    resolve: 'Resolve',
+    export: 'Export',
+    review: 'Review',
+};
+const CATEGORY_COLORS = {
+    verify: chalk.cyan,
+    accrue: chalk.yellow,
+    adjust: chalk.yellow,
+    value: chalk.magenta,
+    report: chalk.blue,
+    lock: chalk.red,
+    resolve: chalk.green,
+    export: chalk.blue,
+    review: chalk.cyan,
+};
+function categoryBadge(cat) {
+    const label = CATEGORY_LABELS[cat] ?? cat;
+    const color = CATEGORY_COLORS[cat] ?? chalk.white;
+    return color(`[${label}]`);
+}
+function printStep(step) {
+    const badge = categoryBadge(step.category);
+    const cond = step.conditional ? chalk.dim(` (${step.conditional})`) : '';
+    console.log(`    ${String(step.order).padStart(2)}. ${badge} ${step.description}${cond}`);
+    if (step.apiCall) {
+        console.log(chalk.dim(`        API: ${step.apiCall}`));
+    }
+    if (step.recipeRef) {
+        console.log(chalk.dim(`        Recipe: ${step.recipeRef}`));
+    }
+    if (step.calcCommand) {
+        console.log(chalk.dim(`        Calc: ${step.calcCommand}`));
+    }
+    if (step.verification) {
+        console.log(chalk.dim(`        Check: ${step.verification}`));
+    }
+    if (step.notes) {
+        console.log(chalk.dim(`        Note: ${step.notes}`));
+    }
+}
+function printPhase(phase) {
+    console.log();
+    console.log(chalk.bold(`  ${phase.name}`));
+    console.log(chalk.dim(`  ${phase.description}`));
+    console.log();
+    for (const step of phase.steps) {
+        printStep(step);
+    }
+}
+const JOB_TITLES = {
+    'month-end-close': 'Month-End Close',
+    'quarter-end-close': 'Quarter-End Close',
+    'year-end-close': 'Year-End Close',
+    'bank-recon': 'Bank Reconciliation',
+    'gst-vat-filing': 'GST/VAT Filing Preparation',
+    'payment-run': 'Payment Run',
+    'credit-control': 'Credit Control',
+    'supplier-recon': 'Supplier Reconciliation',
+    'audit-prep': 'Audit Preparation',
+    'fa-review': 'Fixed Asset Review',
+};
+export function printBlueprint(bp) {
+    const W = 80;
+    const title = JOB_TITLES[bp.jobType] ?? bp.jobType;
+    const modeLabel = bp.mode === 'incremental' ? ' (Incremental)' : '';
+    const currLabel = bp.currency ? ` — ${bp.currency}` : '';
+    console.log();
+    console.log(chalk.bold(`${title}${modeLabel}${currLabel}`));
+    console.log(chalk.bold(`Period: ${bp.period}`));
+    console.log(line(W));
+    for (const phase of bp.phases) {
+        printPhase(phase);
+    }
+    console.log();
+    console.log(line(W));
+    console.log(chalk.bold('Summary'));
+    console.log(`  Total steps:     ${bp.summary.totalSteps}`);
+    if (bp.summary.recipeReferences.length > 0) {
+        console.log(`  Recipes:         ${bp.summary.recipeReferences.join(', ')}`);
+    }
+    if (bp.summary.calcReferences.length > 0) {
+        console.log(`  Calculators:     ${bp.summary.calcReferences.join(', ')}`);
+    }
+    console.log(`  API calls:       ${bp.summary.apiCalls.length} unique endpoints`);
+    console.log();
+}
+export function printBlueprintJson(bp) {
+    console.log(JSON.stringify(bp, null, 2));
+}

package/dist/jobs/gst-vat.js

@@ -0,0 +1,187 @@
+/**
+ * GST/VAT Filing Preparation blueprint generator.
+ * Produces a structured JobBlueprint for quarterly GST/VAT return preparation —
+ * no actual API calls, just an actionable checklist for accountants.
+ */
+import { buildSummary } from './types.js';
+import { parseQuarterPeriod } from './validate.js';
+export function generateGstVatBlueprint(opts) {
+    const qp = parseQuarterPeriod(opts.period);
+    const currency = opts.currency ?? 'SGD';
+    // Phase 1: Generate Tax Ledger
+    const generateLedger = {
+        name: 'Generate Tax Ledger',
+        description: `Generate the tax ledger for ${qp.label} to identify all taxable transactions.`,
+        steps: [
+            {
+                order: 1,
+                description: `Generate tax ledger for ${qp.label}`,
+                category: 'report',
+                apiCall: 'POST /generate-reports/vat-ledger',
+                apiBody: {
+                    startDate: qp.startDate,
+                    endDate: qp.endDate,
+                },
+                verification: 'Tax ledger generated — review total output tax and input tax',
+            },
+            {
+                order: 2,
+                description: 'Export tax ledger for offline review',
+                category: 'export',
+                apiCall: 'POST /data-exports/vat-ledger',
+                apiBody: {
+                    startDate: qp.startDate,
+                    endDate: qp.endDate,
+                },
+                notes: 'Optional — export for working paper or external review',
+            },
+        ],
+    };
+    // Phase 2: Review Output Tax (Sales)
+    const reviewOutputTax = {
+        name: 'Review Output Tax',
+        description: 'Cross-reference invoices against tax ledger to verify output tax completeness.',
+        steps: [
+            {
+                order: 3,
+                description: 'Cross-reference invoices with tax ledger entries',
+                category: 'verify',
+                apiCall: 'POST /invoices/search',
+                apiBody: {
+                    filters: {
+                        dateFrom: qp.startDate,
+                        dateTo: qp.endDate,
+                        status: ['APPROVED', 'PAID'],
+                    },
+                },
+                verification: 'Every taxable invoice should appear in the tax ledger with correct tax code',
+                notes: 'Check for invoices missing tax profiles or using incorrect rates',
+            },
+            {
+                order: 4,
+                description: 'Check for missing or incorrect tax profiles on invoices',
+                category: 'verify',
+                apiCall: 'POST /invoices/search',
+                apiBody: {
+                    filters: {
+                        dateFrom: qp.startDate,
+                        dateTo: qp.endDate,
+                    },
+                },
+                notes: 'Look for zero-rated, exempt, or out-of-scope transactions that may be miscategorized',
+                verification: 'All invoices have appropriate tax profiles assigned',
+            },
+        ],
+    };
+    // Phase 3: Review Input Tax (Purchases)
+    const reviewInputTax = {
+        name: 'Review Input Tax',
+        description: 'Cross-reference bills against tax ledger to verify input tax claims.',
+        steps: [
+            {
+                order: 5,
+                description: 'Cross-reference bills with tax ledger entries',
+                category: 'verify',
+                apiCall: 'POST /bills/search',
+                apiBody: {
+                    filters: {
+                        dateFrom: qp.startDate,
+                        dateTo: qp.endDate,
+                        status: ['APPROVED', 'PAID'],
+                    },
+                },
+                verification: 'Every claimable bill should appear in the tax ledger with correct input tax',
+                notes: 'Ensure supplier tax invoice numbers are recorded for audit trail',
+            },
+            {
+                order: 6,
+                description: 'Identify blocked input tax claims',
+                category: 'review',
+                notes: 'Review expenses that are non-claimable under local GST/VAT rules (e.g., entertainment, motor vehicles, medical). These should be coded to a non-claimable tax profile.',
+                verification: 'Blocked input tax items correctly excluded from claimable total',
+            },
+        ],
+    };
+    // Phase 4: Error Checks
+    const errorChecks = {
+        name: 'Error Checks',
+        description: 'Run common GST/VAT error checks before filing.',
+        steps: [
+            {
+                order: 7,
+                description: 'Review common GST/VAT errors',
+                category: 'review',
+                notes: [
+                    'Check for: (1) transactions with wrong tax period,',
+                    '(2) reverse charge not applied on imported services,',
+                    '(3) credit notes not linked to original invoices,',
+                    '(4) inter-company transactions missing tax,',
+                    '(5) capital goods above threshold without separate declaration',
+                ].join(' '),
+                verification: 'All common error patterns reviewed and resolved',
+            },
+        ],
+    };
+    // Phase 5: GST Return Summary
+    const returnSummary = {
+        name: 'GST Return Summary',
+        description: 'Compile the GST F5 return boxes and generate supporting reports.',
+        steps: [
+            {
+                order: 8,
+                description: 'Compile F5 box mapping (Boxes 1-16)',
+                category: 'report',
+                notes: [
+                    'Box 1: Total value of standard-rated supplies,',
+                    'Box 2: Total value of zero-rated supplies,',
+                    'Box 3: Total value of exempt supplies,',
+                    'Box 5: Total value of taxable purchases,',
+                    'Box 6: Output tax due,',
+                    'Box 7: Input tax and refunds claimed,',
+                    'Box 8: Net GST payable/refundable',
+                ].join(' '),
+                verification: 'F5 boxes balance: Box 6 - Box 7 = Box 8',
+            },
+            {
+                order: 9,
+                description: 'Generate supporting reports for filing',
+                category: 'report',
+                apiCall: 'POST /generate-reports/profit-and-loss',
+                apiBody: {
+                    primarySnapshotDate: qp.endDate,
+                    secondarySnapshotDate: qp.startDate,
+                },
+                notes: 'P&L cross-check: revenue should tie to output tax base, expenses to input tax base',
+                verification: 'Supporting reports consistent with GST return numbers',
+            },
+        ],
+    };
+    // Phase 6: Export & File
+    const exportAndFile = {
+        name: 'Export & File',
+        description: 'Export the final tax ledger and prepare for e-filing.',
+        steps: [
+            {
+                order: 10,
+                description: 'Export final tax ledger for submission',
+                category: 'export',
+                apiCall: 'POST /data-exports/vat-ledger',
+                apiBody: {
+                    startDate: qp.startDate,
+                    endDate: qp.endDate,
+                },
+                notes: 'Export tax ledger as CSV/PDF for IRAS e-filing or manual submission. Archive working papers.',
+                verification: 'Tax ledger exported and filed. Filing deadline noted.',
+            },
+        ],
+    };
+    const phases = [generateLedger, reviewOutputTax, reviewInputTax, errorChecks, returnSummary, exportAndFile];
+    return {
+        jobType: 'gst-vat-filing',
+        period: qp.label,
+        currency,
+        mode: 'standalone',
+        phases,
+        summary: buildSummary(phases),
+    };
+}

package/dist/jobs/month-end.js

@@ -0,0 +1,232 @@
+/**
+ * Month-end close blueprint generator.
+ * Produces a phased checklist with API calls, recipe references, and calc
+ * commands populated with the correct dates for the given period.
+ */
+import { parseMonthPeriod } from './validate.js';
+import { buildSummary } from './types.js';
+/**
+ * Compute the prior month's start and end dates from a YYYY-MM period.
+ * Rolls back to December of the prior year when month is January.
+ */
+function priorMonthDates(year, month) {
+    let pYear = year;
+    let pMonth = month - 1;
+    if (pMonth < 1) {
+        pMonth = 12;
+        pYear -= 1;
+    }
+    const endDay = new Date(pYear, pMonth, 0).getDate();
+    const fmt = (y, m, d) => `${y}-${String(m).padStart(2, '0')}-${String(d).padStart(2, '0')}`;
+    return { start: fmt(pYear, pMonth, 1), end: fmt(pYear, pMonth, endDay) };
+}
+/**
+ * Build the five standard month-end close phases.
+ * Exposed for reuse by quarter-end and year-end generators.
+ */
+export function buildMonthEndPhases(startDate, endDate, year, month, phasePrefix) {
+    const pfx = phasePrefix ? `${phasePrefix} — ` : '';
+    const prior = priorMonthDates(year, month);
+    let order = 0;
+    const step = (partial) => ({ order: ++order, ...partial });
+    // Phase 1 — Pre-Close Preparation
+    const preClose = {
+        name: `${pfx}Phase 1: Pre-Close Preparation`,
+        description: 'Verify completeness of source data before making adjustments.',
+        steps: [
+            step({
+                description: 'Verify all invoices entered for the period',
+                category: 'verify',
+                apiCall: 'POST /invoices/search',
+                apiBody: {
+                    filter: {
+                        valueDate: { from: startDate, to: endDate },
+                    },
+                },
+                verification: 'Cross-check count with source documents',
+            }),
+            step({
+                description: 'Verify all bills entered for the period',
+                category: 'verify',
+                apiCall: 'POST /bills/search',
+                apiBody: {
+                    filter: {
+                        valueDate: { from: startDate, to: endDate },
+                    },
+                },
+                verification: 'Cross-check count with supplier invoices received',
+            }),
+            step({
+                description: 'Complete bank reconciliation',
+                category: 'verify',
+                apiCall: 'POST /bank-records/{accountResourceId}/search',
+                apiBody: {
+                    filter: { status: 'UNRECONCILED' },
+                },
+                verification: 'Zero unreconciled items for the period',
+                notes: 'Repeat for each bank account',
+            }),
+            step({
+                description: 'Review AR aging report',
+                category: 'verify',
+                apiCall: 'POST /generate-reports/ar-report',
+                apiBody: { endDate },
+                verification: 'Flag overdue balances > 90 days',
+            }),
+            step({
+                description: 'Review AP aging report',
+                category: 'verify',
+                apiCall: 'POST /generate-reports/ap-report',
+                apiBody: { endDate },
+                verification: 'Ensure no missed supplier payments',
+            }),
+        ],
+    };
+    // Phase 2 — Accruals & Adjustments
+    const accruals = {
+        name: `${pfx}Phase 2: Accruals & Adjustments`,
+        description: 'Record accruals, amortizations, and depreciation for the period.',
+        steps: [
+            step({
+                description: 'Record accrued expenses',
+                category: 'accrue',
+                apiCall: 'POST /journals',
+                recipeRef: 'accrued-expenses',
+                conditional: 'If unbilled expenses exist',
+                notes: 'Reverse in the following period',
+            }),
+            step({
+                description: 'Amortize prepaid expenses',
+                category: 'accrue',
+                apiCall: 'POST /journals/search',
+                recipeRef: 'prepaid-amortization',
+                calcCommand: 'jaz calc prepaid-expense',
+                conditional: 'If prepaid capsules exist',
+                verification: 'Prepaid balance matches remaining schedule',
+            }),
+            step({
+                description: 'Recognize deferred revenue',
+                category: 'accrue',
+                recipeRef: 'deferred-revenue',
+                calcCommand: 'jaz calc deferred-revenue',
+                conditional: 'If deferred revenue exists',
+                verification: 'Deferred revenue balance matches remaining obligation',
+            }),
+            step({
+                description: 'Record depreciation for the period',
+                category: 'accrue',
+                recipeRef: 'declining-balance',
+                calcCommand: 'jaz calc depreciation',
+                conditional: 'If fixed assets exist',
+                verification: 'Accumulated depreciation matches schedule',
+            }),
+            step({
+                description: 'Accrue employee benefits (leave, CPF)',
+                category: 'accrue',
+                recipeRef: 'employee-accruals',
+                conditional: 'If tracking leave or benefit obligations',
+            }),
+            step({
+                description: 'Accrue loan interest for the period',
+                category: 'accrue',
+                recipeRef: 'bank-loan',
+                calcCommand: 'jaz calc loan',
+                conditional: 'If active loans',
+                verification: 'Interest accrual matches amortization schedule',
+            }),
+        ],
+    };
+    // Phase 3 — Period-End Valuations
+    const valuations = {
+        name: `${pfx}Phase 3: Period-End Valuations`,
+        description: 'Revalue balances to reflect period-end rates and provisions.',
+        steps: [
+            step({
+                description: 'FX revaluation of foreign currency balances',
+                category: 'value',
+                recipeRef: 'fx-revaluation',
+                calcCommand: 'jaz calc fx-reval',
+                conditional: 'If multi-currency org',
+                verification: 'Unrealised gain/loss posted to P&L',
+            }),
+            step({
+                description: 'Bad debt provision (ECL assessment)',
+                category: 'value',
+                recipeRef: 'bad-debt-provision',
+                calcCommand: 'jaz calc ecl',
+                conditional: 'If material AR balance change',
+                verification: 'Provision balance reflects current ECL estimate',
+            }),
+        ],
+    };
+    // Phase 4 — Verification
+    const verification = {
+        name: `${pfx}Phase 4: Verification`,
+        description: 'Generate financial reports and compare to prior period.',
+        steps: [
+            step({
+                description: 'Review trial balance',
+                category: 'report',
+                apiCall: 'POST /generate-reports/trial-balance',
+                apiBody: { startDate, endDate },
+                verification: 'Total debits equal total credits',
+            }),
+            step({
+                description: 'Generate profit & loss statement',
+                category: 'report',
+                apiCall: 'POST /generate-reports/profit-and-loss',
+                apiBody: { primarySnapshotDate: endDate, secondarySnapshotDate: startDate },
+            }),
+            step({
+                description: 'Generate balance sheet',
+                category: 'report',
+                apiCall: 'POST /generate-reports/balance-sheet',
+                apiBody: { primarySnapshotDate: endDate },
+                verification: 'Assets = Liabilities + Equity',
+            }),
+            step({
+                description: 'Compare P&L to prior month',
+                category: 'report',
+                apiCall: 'POST /generate-reports/profit-and-loss',
+                apiBody: {
+                    primarySnapshotDate: endDate,
+                    secondarySnapshotDate: prior.start,
+                },
+                notes: `Prior month: ${prior.start} to ${prior.end}`,
+                verification: 'Investigate material variances (> 10%)',
+            }),
+        ],
+    };
+    // Phase 5 — Close & Lock
+    const closeLock = {
+        name: `${pfx}Phase 5: Close & Lock`,
+        description: 'Lock the period to prevent further changes.',
+        steps: [
+            step({
+                description: `Set accounting lock date to ${endDate}`,
+                category: 'lock',
+                notes: 'Navigate to Settings > General > Lock Date and move it forward to ' +
+                    `${endDate}. This prevents any transactions from being posted to this period.`,
+            }),
+        ],
+    };
+    return [preClose, accruals, valuations, verification, closeLock];
+}
+/**
+ * Generate a month-end close blueprint for a given period.
+ *
+ * @param opts.period - Month in YYYY-MM format (e.g. "2025-01")
+ * @param opts.currency - Optional base currency code (e.g. "SGD")
+ */
+export function generateMonthEndBlueprint(opts) {
+    const parsed = parseMonthPeriod(opts.period);
+    const phases = buildMonthEndPhases(parsed.startDate, parsed.endDate, parsed.year, parsed.month);
+    return {
+        jobType: 'month-end-close',
+        period: parsed.label,
+        currency: opts.currency ?? 'SGD',
+        mode: 'standalone',
+        phases,
+        summary: buildSummary(phases),
+    };
+}