jaz-cli 2.7.0 → 2.8.0

package/dist/jobs/payment-run.js

@@ -0,0 +1,199 @@
+/**
+ * Payment Run blueprint generator.
+ * Produces a structured JobBlueprint for processing supplier payments —
+ * no actual API calls, just an actionable checklist for accountants.
+ */
+import { buildSummary } from './types.js';
+import { validateDateString } from './validate.js';
+export function generatePaymentRunBlueprint(opts = {}) {
+    validateDateString(opts.dueBefore, 'dueBefore');
+    const currency = opts.currency ?? 'SGD';
+    const period = opts.dueBefore ? `Due before ${opts.dueBefore}` : 'current';
+    const dueDateFilter = opts.dueBefore
+        ? { dueDateTo: opts.dueBefore }
+        : {};
+    // Phase 1: Identify Outstanding Bills
+    const identifyOutstanding = {
+        name: 'Identify Outstanding Bills',
+        description: 'List all unpaid bills and filter by due date if specified.',
+        steps: [
+            {
+                order: 1,
+                description: 'List all unpaid bills',
+                category: 'verify',
+                apiCall: 'POST /bills/search',
+                apiBody: {
+                    filters: {
+                        status: ['APPROVED'],
+                        ...dueDateFilter,
+                    },
+                },
+                verification: 'Total outstanding amount noted',
+            },
+            {
+                order: 2,
+                description: 'Filter bills by due date priority',
+                category: 'verify',
+                apiCall: 'POST /bills/search',
+                apiBody: {
+                    filters: {
+                        status: ['APPROVED'],
+                        ...dueDateFilter,
+                    },
+                    sort: { field: 'dueDate', direction: 'ASC' },
+                },
+                notes: opts.dueBefore
+                    ? `Only bills due before ${opts.dueBefore}`
+                    : 'Sorted by due date — prioritize overdue and upcoming',
+                verification: 'Bills sorted by payment urgency',
+            },
+        ],
+    };
+    // Phase 2: Summarize by Supplier
+    const summarize = {
+        name: 'Summarize by Supplier',
+        description: 'Group outstanding bills by supplier and generate AP aging.',
+        steps: [
+            {
+                order: 3,
+                description: 'Group outstanding amounts by supplier',
+                category: 'report',
+                apiCall: 'POST /bills/search',
+                notes: 'Aggregate total owed per supplier for batch grouping',
+                verification: 'Supplier summary matches total outstanding from step 1',
+            },
+            {
+                order: 4,
+                description: 'Generate AP aging report',
+                category: 'report',
+                apiCall: 'POST /generate-reports/ap-aging',
+                notes: 'Current, 1-30, 31-60, 61-90, 90+ day buckets',
+                verification: 'AP aging total ties to unpaid bills total',
+            },
+        ],
+    };
+    // Phase 3: Select & Approve Payment Batch
+    const selectApprove = {
+        name: 'Select & Approve Payment Batch',
+        description: 'Build the payment batch and verify cash availability.',
+        steps: [
+            {
+                order: 5,
+                description: 'Build payment batch and check cash availability',
+                category: 'review',
+                apiCall: 'POST /generate-reports/trial-balance',
+                notes: 'Compare total payment batch amount against bank account balance on TB. Ensure sufficient funds before proceeding.',
+                verification: 'Bank balance >= total payment batch amount',
+            },
+        ],
+    };
+    // Phase 4: Record Payments
+    const recordPayments = {
+        name: 'Record Payments',
+        description: 'Record full and partial payments against approved bills.',
+        steps: [
+            {
+                order: 6,
+                description: 'Record full payments for each approved bill',
+                category: 'resolve',
+                apiCall: 'POST /bills/{id}/payments',
+                apiBody: {
+                    payments: [
+                        {
+                            paymentAmount: '{{paymentAmount}}',
+                            transactionAmount: '{{transactionAmount}}',
+                            accountResourceId: '{{bankAccountResourceId}}',
+                            paymentMethod: '{{paymentMethod}}',
+                            reference: '{{reference}}',
+                            valueDate: '{{today}}',
+                        },
+                    ],
+                },
+                recipeRef: 'bill-payment',
+                notes: 'Payments endpoint requires { payments: [...] } wrapping. Fields: paymentAmount, transactionAmount, accountResourceId, valueDate.',
+                verification: 'Each bill status changes to PAID after payment',
+            },
+            {
+                order: 7,
+                description: 'Record partial payments where applicable',
+                category: 'resolve',
+                apiCall: 'POST /bills/{id}/payments',
+                apiBody: {
+                    payments: [
+                        {
+                            paymentAmount: '{{partialAmount}}',
+                            transactionAmount: '{{partialAmount}}',
+                            accountResourceId: '{{bankAccountResourceId}}',
+                            paymentMethod: '{{paymentMethod}}',
+                            reference: '{{reference}}',
+                            valueDate: '{{today}}',
+                        },
+                    ],
+                },
+                notes: 'For bills being partially paid — record the agreed amount. Bill remains APPROVED with reduced balance.',
+                verification: 'Partial payment recorded, outstanding balance updated',
+            },
+        ],
+    };
+    // Phase 5: FX Payments
+    const fxPayments = {
+        name: 'FX Payments',
+        description: 'Handle multi-currency bill payments with exchange rate considerations.',
+        steps: [
+            {
+                order: 8,
+                description: 'Process foreign currency bill payments',
+                category: 'resolve',
+                apiCall: 'POST /bills/{id}/payments',
+                apiBody: {
+                    payments: [
+                        {
+                            paymentAmount: '{{fxPaymentAmount}}',
+                            transactionAmount: '{{fxTransactionAmount}}',
+                            accountResourceId: '{{fxBankAccountResourceId}}',
+                            paymentMethod: '{{paymentMethod}}',
+                            reference: '{{reference}}',
+                            valueDate: '{{today}}',
+                            currency: { sourceCurrency: '{{foreignCurrency}}' },
+                        },
+                    ],
+                },
+                conditional: 'If multi-currency bills exist in the payment batch',
+                recipeRef: 'fx-bill-payment',
+                calcCommand: 'jaz calc fx-reval',
+                notes: 'Use currency: { sourceCurrency } object form for FX — string currencyCode is silently ignored. Platform auto-fetches ECB rates.',
+                verification: 'FX payments recorded with correct exchange rates, FX gain/loss recognized',
+            },
+        ],
+    };
+    // Phase 6: Verification
+    const verification = {
+        name: 'Verification',
+        description: 'Confirm all payments processed and balances updated.',
+        steps: [
+            {
+                order: 9,
+                description: 'Verify AP aging after payment run',
+                category: 'verify',
+                apiCall: 'POST /generate-reports/ap-aging',
+                verification: 'AP aging reduced by total payments made. No unexpected outstanding items.',
+            },
+            {
+                order: 10,
+                description: 'Verify bank balance after payment run',
+                category: 'verify',
+                apiCall: 'POST /generate-reports/trial-balance',
+                verification: 'Bank account balance reduced by total payment amount. TB still balances.',
+            },
+        ],
+    };
+    const phases = [identifyOutstanding, summarize, selectApprove, recordPayments, fxPayments, verification];
+    return {
+        jobType: 'payment-run',
+        period,
+        currency,
+        mode: 'standalone',
+        phases,
+        summary: buildSummary(phases),
+    };
+}

package/dist/jobs/quarter-end.js

@@ -0,0 +1,135 @@
+/**
+ * Quarter-end close blueprint generator.
+ * Builds on month-end phases with additional quarterly review steps.
+ * Supports standalone (full) and incremental (quarterly extras only) modes.
+ */
+import { parseQuarterPeriod } from './validate.js';
+import { buildMonthEndPhases } from './month-end.js';
+import { buildSummary } from './types.js';
+/**
+ * Build the quarterly extras phase (Phase 6).
+ * These steps only apply at quarter boundaries, beyond normal month-end work.
+ */
+function buildQuarterlyExtrasPhase(startDate, endDate, startOrder) {
+    let order = startOrder;
+    const step = (partial) => ({
+        order: ++order,
+        ...partial,
+    });
+    return {
+        name: 'Phase 6: Quarterly Extras',
+        description: 'Additional reviews and filings required at quarter boundaries.',
+        steps: [
+            step({
+                description: 'GST/VAT filing preparation',
+                category: 'report',
+                apiCall: 'POST /generate-reports/vat-ledger',
+                apiBody: { startDate, endDate },
+                conditional: 'If GST-registered',
+                verification: 'Output tax minus input tax matches F5/F7 boxes',
+            }),
+            step({
+                description: 'ECL / bad debt provision formal review',
+                category: 'value',
+                recipeRef: 'bad-debt-provision',
+                calcCommand: 'jaz calc ecl',
+                verification: 'Provision movement disclosed in notes',
+            }),
+            step({
+                description: 'Bonus accrual true-up',
+                category: 'accrue',
+                recipeRef: 'employee-accruals',
+                conditional: 'If bonus schemes exist',
+                notes: 'Adjust accrual to reflect year-to-date actual performance vs. budget',
+            }),
+            step({
+                description: 'Intercompany reconciliation',
+                category: 'verify',
+                recipeRef: 'intercompany',
+                conditional: 'If multi-entity',
+                verification: 'Intercompany balances net to zero across all entities',
+            }),
+            step({
+                description: 'Provision unwinding (IAS 37 / FRS 37)',
+                category: 'value',
+                recipeRef: 'provisions',
+                calcCommand: 'jaz calc provision',
+                conditional: 'If IAS 37 provisions exist',
+                notes: 'Unwind discount on non-current provisions',
+            }),
+        ],
+    };
+}
+/**
+ * Build the quarterly verification phase (Phase 7).
+ * Full-quarter financial reports for consolidated review.
+ */
+function buildQuarterlyVerificationPhase(startDate, endDate, label, startOrder) {
+    let order = startOrder;
+    const step = (partial) => ({
+        order: ++order,
+        ...partial,
+    });
+    return {
+        name: 'Phase 7: Quarterly Verification',
+        description: `Full-quarter financial report review for ${label}.`,
+        steps: [
+            step({
+                description: `Review trial balance for ${label}`,
+                category: 'report',
+                apiCall: 'POST /generate-reports/trial-balance',
+                apiBody: { startDate, endDate },
+                verification: 'Total debits equal total credits',
+            }),
+            step({
+                description: `Generate P&L for ${label}`,
+                category: 'report',
+                apiCall: 'POST /generate-reports/profit-and-loss',
+                apiBody: { primarySnapshotDate: endDate, secondarySnapshotDate: startDate },
+            }),
+            step({
+                description: `Generate balance sheet as at ${endDate}`,
+                category: 'report',
+                apiCall: 'POST /generate-reports/balance-sheet',
+                apiBody: { primarySnapshotDate: endDate },
+                verification: 'Assets = Liabilities + Equity',
+            }),
+        ],
+    };
+}
+/**
+ * Generate a quarter-end close blueprint.
+ *
+ * @param opts.period       Quarter in YYYY-QN format (e.g. "2025-Q1")
+ * @param opts.currency     Optional base currency code (e.g. "SGD")
+ * @param opts.incremental  If true, generate only the quarterly extras (skip month-end phases)
+ */
+export function generateQuarterEndBlueprint(opts) {
+    const parsed = parseQuarterPeriod(opts.period);
+    const mode = opts.incremental ? 'incremental' : 'standalone';
+    const phases = [];
+    if (!opts.incremental) {
+        // Standalone: include month-end phases for each of the 3 months
+        for (const month of parsed.months) {
+            const monthPhases = buildMonthEndPhases(month.startDate, month.endDate, month.year, month.month, month.label);
+            phases.push(...monthPhases);
+        }
+    }
+    // Count the highest step order from existing phases
+    const maxOrder = phases.reduce((max, phase) => phase.steps.reduce((m, s) => Math.max(m, s.order), max), 0);
+    // Add quarterly extras (Phase 6)
+    const extras = buildQuarterlyExtrasPhase(parsed.startDate, parsed.endDate, maxOrder);
+    phases.push(extras);
+    // Add quarterly verification (Phase 7)
+    const lastExtraOrder = extras.steps.reduce((max, s) => Math.max(max, s.order), 0);
+    const verification = buildQuarterlyVerificationPhase(parsed.startDate, parsed.endDate, parsed.label, lastExtraOrder);
+    phases.push(verification);
+    return {
+        jobType: 'quarter-end-close',
+        period: parsed.label,
+        currency: opts.currency ?? 'SGD',
+        mode,
+        phases,
+        summary: buildSummary(phases),
+    };
+}

package/dist/jobs/supplier-recon.js

@@ -0,0 +1,132 @@
+/**
+ * Supplier Reconciliation blueprint generator.
+ * Produces a structured JobBlueprint for reconciling supplier statements —
+ * no actual API calls, just an actionable checklist for accountants.
+ */
+import { buildSummary } from './types.js';
+import { parseMonthPeriod } from './validate.js';
+export function generateSupplierReconBlueprint(opts = {}) {
+    const currency = opts.currency ?? 'SGD';
+    const period = opts.period ?? 'current';
+    const supplierFilter = opts.supplier
+        ? { supplierName: opts.supplier }
+        : {};
+    const periodFilter = opts.period
+        ? (() => {
+            const mp = parseMonthPeriod(opts.period);
+            return { dateFrom: mp.startDate, dateTo: mp.endDate };
+        })()
+        : {};
+    // Phase 1: Pull AP Data
+    const pullApData = {
+        name: 'Pull AP Data',
+        description: 'Generate AP aging and pull bills for the supplier.',
+        steps: [
+            {
+                order: 1,
+                description: 'Generate AP aging report',
+                category: 'report',
+                apiCall: 'POST /generate-reports/ap-aging',
+                notes: opts.supplier
+                    ? `Filtered to supplier: ${opts.supplier}`
+                    : 'Full AP aging — filter to target supplier(s) for comparison',
+                verification: 'AP aging total for supplier noted as starting reference',
+            },
+            {
+                order: 2,
+                description: 'List all bills for the supplier',
+                category: 'verify',
+                apiCall: 'POST /bills/search',
+                apiBody: {
+                    filters: {
+                        ...supplierFilter,
+                        ...periodFilter,
+                    },
+                },
+                notes: 'Include all statuses (DRAFT, APPROVED, PAID) for complete picture',
+                verification: 'Bill list pulled — note total count and amounts',
+            },
+        ],
+    };
+    // Phase 2: Compare Against Supplier Statement
+    const compare = {
+        name: 'Compare Against Supplier Statement',
+        description: 'Match internal records against the supplier statement to identify discrepancies.',
+        steps: [
+            {
+                order: 3,
+                description: 'Match bills against supplier statement line items',
+                category: 'verify',
+                notes: [
+                    'Compare each supplier statement line to internal bills by:',
+                    '(1) invoice/reference number, (2) amount, (3) date.',
+                    'Mark items as matched, missing internally, or missing on statement.',
+                ].join(' '),
+                verification: 'Every statement line has been compared to internal records',
+            },
+            {
+                order: 4,
+                description: 'Identify and document mismatches',
+                category: 'review',
+                notes: [
+                    'Common mismatch types:',
+                    '(a) Bill in books but not on statement — timing difference or supplier error,',
+                    '(b) On statement but not in books — missing bill, needs to be entered,',
+                    '(c) Amount difference — pricing dispute, currency conversion, or data entry error,',
+                    '(d) Payment not reflected — check payment clearing dates.',
+                ].join(' '),
+                verification: 'All mismatches documented with root cause and proposed resolution',
+            },
+        ],
+    };
+    // Phase 3: Resolve Discrepancies
+    const resolve = {
+        name: 'Resolve Discrepancies',
+        description: 'Create missing bills and record adjustments to align balances.',
+        steps: [
+            {
+                order: 5,
+                description: 'Create missing bills from supplier statement',
+                category: 'resolve',
+                apiCall: 'POST /bills',
+                recipeRef: 'standard-bill',
+                notes: 'For items on supplier statement but missing from books — create and approve the bill. Attach supplier invoice as supporting document.',
+                verification: 'All missing bills created and approved',
+            },
+            {
+                order: 6,
+                description: 'Record adjustments for amount differences',
+                category: 'adjust',
+                apiCall: 'POST /journals',
+                notes: 'For amount mismatches — create adjustment journals (e.g., price adjustments, rounding differences). For disputed amounts, create debit notes via POST /bills/credit-notes.',
+                verification: 'All adjustments journaled, disputed amounts documented',
+            },
+        ],
+    };
+    // Phase 4: Verification
+    const verification = {
+        name: 'Verification',
+        description: 'Confirm AP balance now matches supplier statement.',
+        steps: [
+            {
+                order: 7,
+                description: 'Re-check AP aging for supplier after resolution',
+                category: 'verify',
+                apiCall: 'POST /generate-reports/ap-aging',
+                notes: opts.supplier
+                    ? `Verify ${opts.supplier} balance matches their statement closing balance`
+                    : 'Verify each reconciled supplier balance matches their statement',
+                verification: 'AP balance per books agrees with supplier statement balance. Any remaining differences are documented and accepted.',
+            },
+        ],
+    };
+    const phases = [pullApData, compare, resolve, verification];
+    return {
+        jobType: 'supplier-recon',
+        period,
+        currency,
+        mode: 'standalone',
+        phases,
+        summary: buildSummary(phases),
+    };
+}

package/dist/jobs/types.js

@@ -0,0 +1,36 @@
+/**
+ * Shared types for jaz jobs blueprint generators.
+ */
+export const JOB_TYPES = [
+    'month-end-close',
+    'quarter-end-close',
+    'year-end-close',
+    'bank-recon',
+    'gst-vat-filing',
+    'payment-run',
+    'credit-control',
+    'supplier-recon',
+    'audit-prep',
+    'fa-review',
+];
+/** Build the summary from phases. */
+export function buildSummary(phases) {
+    const allSteps = phases.flatMap(p => p.steps);
+    const recipeSet = new Set();
+    const calcSet = new Set();
+    const apiSet = new Set();
+    for (const step of allSteps) {
+        if (step.recipeRef)
+            recipeSet.add(step.recipeRef);
+        if (step.calcCommand)
+            calcSet.add(step.calcCommand);
+        if (step.apiCall)
+            apiSet.add(step.apiCall);
+    }
+    return {
+        totalSteps: allSteps.length,
+        recipeReferences: [...recipeSet].sort(),
+        calcReferences: [...calcSet].sort(),
+        apiCalls: [...apiSet].sort(),
+    };
+}

package/dist/jobs/validate.js

@@ -0,0 +1,115 @@
+/**
+ * Input validation for jaz jobs blueprint generators.
+ * Parses period strings and validates flags.
+ */
+export class JobValidationError extends Error {
+    constructor(message) {
+        super(message);
+        this.name = 'JobValidationError';
+    }
+}
+/** Last day of a given month (1-indexed). */
+function lastDay(year, month) {
+    return new Date(year, month, 0).getDate();
+}
+/** Format YYYY-MM-DD from components. */
+function fmtDate(y, m, d) {
+    return `${y}-${String(m).padStart(2, '0')}-${String(d).padStart(2, '0')}`;
+}
+/** Short month name (Jan, Feb, etc.) */
+const MONTH_NAMES = ['Jan', 'Feb', 'Mar', 'Apr', 'May', 'Jun', 'Jul', 'Aug', 'Sep', 'Oct', 'Nov', 'Dec'];
+/** Parse a month period string like "2025-01". */
+export function parseMonthPeriod(period) {
+    const match = period.match(/^(\d{4})-(\d{2})$/);
+    if (!match) {
+        throw new JobValidationError(`Invalid month period: "${period}". Expected YYYY-MM (e.g., 2025-01)`);
+    }
+    const year = parseInt(match[1], 10);
+    const month = parseInt(match[2], 10);
+    if (month < 1 || month > 12) {
+        throw new JobValidationError(`Invalid month: ${month}. Must be 01-12`);
+    }
+    const end = lastDay(year, month);
+    return {
+        type: 'month',
+        year,
+        month,
+        startDate: fmtDate(year, month, 1),
+        endDate: fmtDate(year, month, end),
+        label: `${MONTH_NAMES[month - 1]} ${year}`,
+    };
+}
+/** Parse a quarter period string like "2025-Q1". */
+export function parseQuarterPeriod(period) {
+    const match = period.match(/^(\d{4})-Q([1-4])$/i);
+    if (!match) {
+        throw new JobValidationError(`Invalid quarter period: "${period}". Expected YYYY-QN (e.g., 2025-Q1)`);
+    }
+    const year = parseInt(match[1], 10);
+    const quarter = parseInt(match[2], 10);
+    const firstMonth = (quarter - 1) * 3 + 1;
+    const lastMonth = firstMonth + 2;
+    const endDay = lastDay(year, lastMonth);
+    const months = [];
+    for (let m = firstMonth; m <= lastMonth; m++) {
+        months.push({
+            type: 'month',
+            year,
+            month: m,
+            startDate: fmtDate(year, m, 1),
+            endDate: fmtDate(year, m, lastDay(year, m)),
+            label: `${MONTH_NAMES[m - 1]} ${year}`,
+        });
+    }
+    return {
+        type: 'quarter',
+        year,
+        quarter,
+        startDate: fmtDate(year, firstMonth, 1),
+        endDate: fmtDate(year, lastMonth, endDay),
+        months,
+        label: `Q${quarter} ${year}`,
+    };
+}
+/** Parse a year period string like "2025". */
+export function parseYearPeriod(period) {
+    const match = period.match(/^(\d{4})$/);
+    if (!match) {
+        throw new JobValidationError(`Invalid year period: "${period}". Expected YYYY (e.g., 2025)`);
+    }
+    const year = parseInt(match[1], 10);
+    const quarters = [];
+    for (let q = 1; q <= 4; q++) {
+        quarters.push(parseQuarterPeriod(`${year}-Q${q}`));
+    }
+    return {
+        type: 'year',
+        year,
+        startDate: fmtDate(year, 1, 1),
+        endDate: fmtDate(year, 12, 31),
+        quarters,
+        label: `FY${year}`,
+    };
+}
+/** Validate an optional date string (YYYY-MM-DD). Round-trip checks components. */
+export function validateDateString(date, name) {
+    if (!date)
+        return;
+    const m = date.match(/^(\d{4})-(\d{2})-(\d{2})$/);
+    if (!m) {
+        throw new JobValidationError(`${name} must be YYYY-MM-DD format (got "${date}")`);
+    }
+    const y = Number(m[1]);
+    const mo = Number(m[2]);
+    const da = Number(m[3]);
+    const d = new Date(Date.UTC(y, mo - 1, da));
+    if (d.getUTCFullYear() !== y || d.getUTCMonth() !== mo - 1 || d.getUTCDate() !== da) {
+        throw new JobValidationError(`Invalid ${name}: "${date}"`);
+    }
+}
+/** Validate overdue-days is a positive integer. */
+export function validateOverdueDays(days) {
+    if (!Number.isInteger(days) || days < 1) {
+        throw new JobValidationError(`Overdue days must be a positive integer (got ${days})`);
+    }
+}