aimeat 2.7.0 → 3.1.0

package/dist/src/services/finance/pnl.js

@@ -0,0 +1,51 @@
+import { FinanceError } from './errors.js';
+import { vatPeriodReport } from './vat-report.js';
+const MONTH_RE = /^\d{4}-\d{2}$/;
+function monthEnd(month) {
+    const [y, m] = month.split('-').map(Number);
+    return `${month}-${String(new Date(Date.UTC(y, m, 0)).getUTCDate()).padStart(2, '0')}`;
+}
+export async function pnlReport(storage, ownerGhii, fromMonth, toMonth) {
+    if (!MONTH_RE.test(fromMonth) || !MONTH_RE.test(toMonth)) {
+        throw new FinanceError('INVALID_PERIOD', 400, 'from and to must be months (yyyy-mm)');
+    }
+    if (fromMonth > toMonth)
+        throw new FinanceError('INVALID_PERIOD', 400, 'from must not be after to');
+    const from = `${fromMonth}-01`;
+    const to = monthEnd(toMonth);
+    const vouchers = await storage.listVouchers({ ownerGhii, from, to, limit: 10000 });
+    const income = new Map();
+    const expenses = new Map();
+    let transferCount = 0;
+    let transferMinor = 0;
+    for (const v of vouchers) {
+        if (v.direction === 'transfer') {
+            transferCount++;
+            transferMinor += v.amountMinor;
+            continue;
+        }
+        const bucket = v.direction === 'income' ? income : expenses;
+        const line = bucket.get(v.source) ?? { source: v.source, amountMinor: 0, count: 0 };
+        line.amountMinor += v.amountMinor;
+        line.count += 1;
+        bucket.set(v.source, line);
+    }
+    const incomeLines = [...income.values()].sort((a, b) => b.amountMinor - a.amountMinor);
+    const expenseLines = [...expenses.values()].sort((a, b) => b.amountMinor - a.amountMinor);
+    const totalIncomeMinor = incomeLines.reduce((s, l) => s + l.amountMinor, 0);
+    const totalExpenseMinor = expenseLines.reduce((s, l) => s + l.amountMinor, 0);
+    const vat = await vatPeriodReport(storage, ownerGhii, fromMonth, toMonth);
+    const usage = await storage.queryUsageDaily({ ownerGhii, from, to });
+    const aiCostUsd = usage.reduce((s, u) => s + (u.costUsd || 0), 0);
+    return {
+        from, to,
+        income: incomeLines, expenses: expenseLines,
+        totalIncomeMinor, totalExpenseMinor,
+        resultMinor: totalIncomeMinor - totalExpenseMinor,
+        vatPayableMinor: vat.vatPayableMinor,
+        transferCount, transferMinor,
+        aiCostUsd: Math.round(aiCostUsd * 10000) / 10000,
+        voucherCount: vouchers.length,
+    };
+}
+//# sourceMappingURL=pnl.js.map

package/dist/src/services/finance/pnl.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"pnl.js","sourceRoot":"","sources":["../../../../src/services/finance/pnl.ts"],"names":[],"mappings":"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"}

package/dist/src/services/finance/reference-number.d.ts

@@ -0,0 +1,28 @@
+/**
+ * @file src/services/finance/reference-number.ts
+ * @description Payment reference generation and validation: the Finnish national
+ *   reference (viitenumero, 7-3-1 check digit) and the international RF creditor
+ *   reference (ISO 11649, mod-97). Pure functions, no I/O.
+ *
+ *   The base digits are derived from the invoice's sequential number, so a reference
+ *   always resolves back to exactly one invoice of one seller (findInvoiceByReference).
+ *
+ * @usage finnishReference('2026' + '14') → '2026143'; rfReference('202614') → 'RF...'
+ * @version-history
+ *   v1.0.0 — 2026-08-06 — Company-in-a-box phase 1.
+ */
+/**
+ * Finnish viitenumero check digit: weights 7,3,1 repeating from the RIGHTMOST base digit,
+ * check = (10 − (sum mod 10)) mod 10, appended to the base. Base must be 3–19 digits.
+ */
+export declare function finnishReference(baseDigits: string): string;
+/** Validates a Finnish viitenumero (base + check digit). */
+export declare function isValidFinnishReference(ref: string): boolean;
+/**
+ * ISO 11649 RF creditor reference over the given alphanumeric reference: check digits
+ * are 98 − ((reference + "RF00") as digits mod 97), zero-padded to 2.
+ */
+export declare function rfReference(reference: string): string;
+/** Validates an RF creditor reference (ISO 11649). */
+export declare function isValidRfReference(ref: string): boolean;
+//# sourceMappingURL=reference-number.d.ts.map

package/dist/src/services/finance/reference-number.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"reference-number.d.ts","sourceRoot":"","sources":["../../../../src/services/finance/reference-number.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;GAYG;AAEH;;;GAGG;AACH,wBAAgB,gBAAgB,CAAC,UAAU,EAAE,MAAM,GAAG,MAAM,CAY3D;AAED,4DAA4D;AAC5D,wBAAgB,uBAAuB,CAAC,GAAG,EAAE,MAAM,GAAG,OAAO,CAG5D;AAED;;;GAGG;AACH,wBAAgB,WAAW,CAAC,SAAS,EAAE,MAAM,GAAG,MAAM,CAWrD;AAED,sDAAsD;AACtD,wBAAgB,kBAAkB,CAAC,GAAG,EAAE,MAAM,GAAG,OAAO,CAQvD"}

package/dist/src/services/finance/reference-number.js

@@ -0,0 +1,74 @@
+/**
+ * @file src/services/finance/reference-number.ts
+ * @description Payment reference generation and validation: the Finnish national
+ *   reference (viitenumero, 7-3-1 check digit) and the international RF creditor
+ *   reference (ISO 11649, mod-97). Pure functions, no I/O.
+ *
+ *   The base digits are derived from the invoice's sequential number, so a reference
+ *   always resolves back to exactly one invoice of one seller (findInvoiceByReference).
+ *
+ * @usage finnishReference('2026' + '14') → '2026143'; rfReference('202614') → 'RF...'
+ * @version-history
+ *   v1.0.0 — 2026-08-06 — Company-in-a-box phase 1.
+ */
+/**
+ * Finnish viitenumero check digit: weights 7,3,1 repeating from the RIGHTMOST base digit,
+ * check = (10 − (sum mod 10)) mod 10, appended to the base. Base must be 3–19 digits.
+ */
+export function finnishReference(baseDigits) {
+    if (!/^[0-9]{3,19}$/.test(baseDigits)) {
+        throw new Error(`viite base must be 3-19 digits, got "${baseDigits}"`);
+    }
+    const weights = [7, 3, 1];
+    let sum = 0;
+    const digits = baseDigits.split('').reverse();
+    for (let i = 0; i < digits.length; i++) {
+        sum += Number(digits[i]) * weights[i % 3];
+    }
+    const check = (10 - (sum % 10)) % 10;
+    return baseDigits + String(check);
+}
+/** Validates a Finnish viitenumero (base + check digit). */
+export function isValidFinnishReference(ref) {
+    if (!/^[0-9]{4,20}$/.test(ref))
+        return false;
+    return finnishReference(ref.slice(0, -1)) === ref;
+}
+/**
+ * ISO 11649 RF creditor reference over the given alphanumeric reference: check digits
+ * are 98 − ((reference + "RF00") as digits mod 97), zero-padded to 2.
+ */
+export function rfReference(reference) {
+    if (!/^[0-9A-Za-z]{1,21}$/.test(reference)) {
+        throw new Error(`RF reference base must be 1-21 alphanumerics, got "${reference}"`);
+    }
+    const upper = reference.toUpperCase();
+    const numeric = (upper + 'RF00').split('').map((ch) => {
+        if (ch >= '0' && ch <= '9')
+            return ch;
+        return String(ch.charCodeAt(0) - 55); // A=10 ... Z=35
+    }).join('');
+    const check = 98 - mod97(numeric);
+    return `RF${String(check).padStart(2, '0')}${upper}`;
+}
+/** Validates an RF creditor reference (ISO 11649). */
+export function isValidRfReference(ref) {
+    if (!/^RF[0-9]{2}[0-9A-Za-z]{1,21}$/.test(ref))
+        return false;
+    const rearranged = (ref.slice(4) + ref.slice(0, 4)).toUpperCase();
+    const numeric = rearranged.split('').map((ch) => {
+        if (ch >= '0' && ch <= '9')
+            return ch;
+        return String(ch.charCodeAt(0) - 55);
+    }).join('');
+    return mod97(numeric) === 1;
+}
+/** Chunked mod-97 over an arbitrarily long digit string (avoids BigInt for a hot path). */
+function mod97(digits) {
+    let remainder = 0;
+    for (let i = 0; i < digits.length; i += 7) {
+        remainder = Number(String(remainder) + digits.slice(i, i + 7)) % 97;
+    }
+    return remainder;
+}
+//# sourceMappingURL=reference-number.js.map

package/dist/src/services/finance/reference-number.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"reference-number.js","sourceRoot":"","sources":["../../../../src/services/finance/reference-number.ts"],"names":[],"mappings":"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"}

package/dist/src/services/finance/vat-codes.d.ts

@@ -0,0 +1,28 @@
+/**
+ * @file src/services/finance/vat-codes.ts
+ * @description The Finnish VAT-code seed registry and the resolution helpers. Rates are
+ *   DATA with validity windows, never hardcoded into calculations: the reduced rate
+ *   changed 14 % → 13.5 % on 2026-01-01 (verified against vero.fi 2026-08-06), so an
+ *   invoice dated 2025 books 14 % and one dated 2026 books 13.5 % — both codes exist
+ *   side by side and pickVatCode() selects by document date.
+ * @structure FI_VAT_SEED — the registry · ensureVatCodesSeeded() — idempotent boot seed ·
+ *   vatCodesValidOn() / requireVatCode() — resolution
+ * @usage const codes = await vatCodesValidOn(storage, '2026-08-06');
+ * @version-history
+ *   v1.0.0 — 2026-08-06 — Company-in-a-box phase 1.
+ */
+import type { Storage } from '../../storage/interface.js';
+import type { VatCodeRecord } from '../../models/finance-schemas.js';
+/**
+ * Idempotent seed of the Finnish registry. Upserts by id, so a re-boot updates labels but
+ * an operator's own added codes are untouched. Cached per process: the first finance
+ * request pays one round of upserts, the rest pay nothing.
+ */
+export declare function ensureVatCodesSeeded(storage: Storage): Promise<void>;
+/** Test hook: reset the per-process seed cache (used when the same process boots several storages). */
+export declare function resetVatSeedCache(): void;
+/** Codes whose validity window contains the given ISO date. */
+export declare function vatCodesValidOn(storage: Storage, isoDate: string): Promise<VatCodeRecord[]>;
+/** Resolves a VAT code id and checks it is valid on the document date. */
+export declare function requireVatCode(storage: Storage, id: string, isoDate: string): Promise<VatCodeRecord>;
+//# sourceMappingURL=vat-codes.d.ts.map

package/dist/src/services/finance/vat-codes.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"vat-codes.d.ts","sourceRoot":"","sources":["../../../../src/services/finance/vat-codes.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;GAYG;AACH,OAAO,KAAK,EAAE,OAAO,EAAE,MAAM,4BAA4B,CAAC;AAC1D,OAAO,KAAK,EAAE,aAAa,EAAE,MAAM,iCAAiC,CAAC;AA+CrE;;;;GAIG;AACH,wBAAgB,oBAAoB,CAAC,OAAO,EAAE,OAAO,GAAG,OAAO,CAAC,IAAI,CAAC,CAapE;AAED,uGAAuG;AACvG,wBAAgB,iBAAiB,IAAI,IAAI,CAExC;AAED,+DAA+D;AAC/D,wBAAsB,eAAe,CAAC,OAAO,EAAE,OAAO,EAAE,OAAO,EAAE,MAAM,GAAG,OAAO,CAAC,aAAa,EAAE,CAAC,CAIjG;AAED,0EAA0E;AAC1E,wBAAsB,cAAc,CAAC,OAAO,EAAE,OAAO,EAAE,EAAE,EAAE,MAAM,EAAE,OAAO,EAAE,MAAM,GAAG,OAAO,CAAC,aAAa,CAAC,CAQ1G"}

package/dist/src/services/finance/vat-codes.js

@@ -0,0 +1,84 @@
+import { FinanceError } from './errors.js';
+/**
+ * Finnish VAT codes as of 2026-08-06 (source: vero.fi / arvonlisäveroprosentit).
+ * createdAt/updatedAt are stamped at seed time.
+ */
+const FI_VAT_SEED = [
+    {
+        id: 'fi-std-2550', countryCode: 'FI', category: 'standard', rateBp: 2550,
+        label: { en: 'Standard rate 25.5 %', fi: 'Yleinen verokanta 25,5 %' },
+        validFrom: '2024-09-01', validTo: null,
+    },
+    {
+        id: 'fi-red-1400', countryCode: 'FI', category: 'reduced', rateBp: 1400,
+        label: { en: 'Reduced rate 14 % (until 2025-12-31)', fi: 'Alennettu verokanta 14 % (31.12.2025 asti)' },
+        validFrom: '2013-01-01', validTo: '2025-12-31',
+    },
+    {
+        id: 'fi-red-1350', countryCode: 'FI', category: 'reduced', rateBp: 1350,
+        label: { en: 'Reduced rate 13.5 % (food, books, medicine, transport...)', fi: 'Alennettu verokanta 13,5 % (ruoka, kirjat, lääkkeet, henkilökuljetus...)' },
+        validFrom: '2026-01-01', validTo: null,
+    },
+    {
+        id: 'fi-red-1000', countryCode: 'FI', category: 'reduced', rateBp: 1000,
+        label: { en: 'Reduced rate 10 % (newspapers and magazines)', fi: 'Alennettu verokanta 10 % (sanoma- ja aikakauslehdet)' },
+        validFrom: '2013-01-01', validTo: null,
+    },
+    {
+        id: 'fi-zero', countryCode: 'FI', category: 'zero', rateBp: 0,
+        label: { en: 'Zero rate 0 % (exports, intra-EU supplies)', fi: 'Nollaverokanta 0 % (vienti, yhteisömyynti)' },
+        validFrom: '2013-01-01', validTo: null,
+    },
+    {
+        id: 'fi-exempt', countryCode: 'FI', category: 'exempt', rateBp: 0,
+        label: { en: 'VAT exempt (healthcare, financial services...)', fi: 'Arvonlisäveroton (terveydenhuolto, rahoituspalvelut...)' },
+        validFrom: '2013-01-01', validTo: null,
+    },
+    {
+        id: 'fi-reverse', countryCode: 'FI', category: 'reverse_charge', rateBp: 0,
+        label: { en: 'Reverse charge (construction, EU services)', fi: 'Käännetty verovelvollisuus (rakentaminen, EU-palvelut)' },
+        validFrom: '2013-01-01', validTo: null,
+    },
+];
+let seeded = null;
+/**
+ * Idempotent seed of the Finnish registry. Upserts by id, so a re-boot updates labels but
+ * an operator's own added codes are untouched. Cached per process: the first finance
+ * request pays one round of upserts, the rest pay nothing.
+ */
+export function ensureVatCodesSeeded(storage) {
+    if (!seeded) {
+        seeded = (async () => {
+            const now = new Date().toISOString();
+            for (const code of FI_VAT_SEED) {
+                await storage.upsertVatCode({ ...code, createdAt: now, updatedAt: now });
+            }
+        })().catch((e) => {
+            seeded = null; // a failed seed retries on the next request instead of caching the failure
+            throw e;
+        });
+    }
+    return seeded;
+}
+/** Test hook: reset the per-process seed cache (used when the same process boots several storages). */
+export function resetVatSeedCache() {
+    seeded = null;
+}
+/** Codes whose validity window contains the given ISO date. */
+export async function vatCodesValidOn(storage, isoDate) {
+    await ensureVatCodesSeeded(storage);
+    const all = await storage.listVatCodes();
+    return all.filter((c) => c.validFrom <= isoDate && (c.validTo === null || isoDate <= c.validTo));
+}
+/** Resolves a VAT code id and checks it is valid on the document date. */
+export async function requireVatCode(storage, id, isoDate) {
+    await ensureVatCodesSeeded(storage);
+    const code = await storage.getVatCode(id);
+    if (!code)
+        throw new FinanceError('VAT_CODE_UNKNOWN', 422, `Unknown VAT code: ${id}`);
+    if (code.validFrom > isoDate || (code.validTo !== null && isoDate > code.validTo)) {
+        throw new FinanceError('VAT_CODE_NOT_VALID', 422, `VAT code ${id} is not valid on ${isoDate}`);
+    }
+    return code;
+}
+//# sourceMappingURL=vat-codes.js.map

package/dist/src/services/finance/vat-codes.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"vat-codes.js","sourceRoot":"","sources":["../../../../src/services/finance/vat-codes.ts"],"names":[],"mappings":"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"}

package/dist/src/services/finance/vat-report.d.ts

@@ -0,0 +1,41 @@
+/**
+ * @file src/services/finance/vat-report.ts
+ * @description VAT period summary (ALV-kausikooste) computed from booked vouchers —
+ *   the basis for the owner's OmaVero self-assessment. Nothing is filed anywhere from
+ *   here in v1; this is only the truth of the bookings, grouped by VAT code.
+ *   Credit notes and reversals net out naturally because expense-direction vouchers
+ *   subtract.
+ * @usage const report = await vatPeriodReport(storage, ownerGhii, '2026-01', '2026-03');
+ * @version-history
+ *   v1.0.0 — 2026-08-06 — Company-in-a-box phase 1.
+ */
+import type { Storage } from '../../storage/interface.js';
+export interface VatReportRow {
+    vatCodeId: string;
+    vatRateBp: number;
+    label: {
+        en: string;
+        fi: string;
+    } | null;
+    /** Sales side (income vouchers): net and VAT collected. */
+    salesNetMinor: number;
+    salesVatMinor: number;
+    /** Purchase side (expense vouchers with a VAT breakdown): net and deductible VAT. */
+    purchasesNetMinor: number;
+    purchasesVatMinor: number;
+}
+export interface VatPeriodReport {
+    from: string;
+    to: string;
+    rows: VatReportRow[];
+    totalSalesVatMinor: number;
+    totalPurchasesVatMinor: number;
+    /** VAT payable for the period: sales VAT − deductible purchase VAT. */
+    vatPayableMinor: number;
+    voucherCount: number;
+    /** Vouchers with no VAT breakdown — listed so the accountant sees what is unclassified. */
+    unclassifiedVouchers: number;
+}
+/** Period summary; from/to are months (yyyy-mm), inclusive. */
+export declare function vatPeriodReport(storage: Storage, ownerGhii: string, fromMonth: string, toMonth: string, organismId?: string): Promise<VatPeriodReport>;
+//# sourceMappingURL=vat-report.d.ts.map

package/dist/src/services/finance/vat-report.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"vat-report.d.ts","sourceRoot":"","sources":["../../../../src/services/finance/vat-report.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;GAUG;AACH,OAAO,KAAK,EAAE,OAAO,EAAE,MAAM,4BAA4B,CAAC;AAI1D,MAAM,WAAW,YAAY;IAC3B,SAAS,EAAE,MAAM,CAAC;IAClB,SAAS,EAAE,MAAM,CAAC;IAClB,KAAK,EAAE;QAAE,EAAE,EAAE,MAAM,CAAC;QAAC,EAAE,EAAE,MAAM,CAAA;KAAE,GAAG,IAAI,CAAC;IACzC,2DAA2D;IAC3D,aAAa,EAAE,MAAM,CAAC;IACtB,aAAa,EAAE,MAAM,CAAC;IACtB,qFAAqF;IACrF,iBAAiB,EAAE,MAAM,CAAC;IAC1B,iBAAiB,EAAE,MAAM,CAAC;CAC3B;AAED,MAAM,WAAW,eAAe;IAC9B,IAAI,EAAE,MAAM,CAAC;IACb,EAAE,EAAE,MAAM,CAAC;IACX,IAAI,EAAE,YAAY,EAAE,CAAC;IACrB,kBAAkB,EAAE,MAAM,CAAC;IAC3B,sBAAsB,EAAE,MAAM,CAAC;IAC/B,uEAAuE;IACvE,eAAe,EAAE,MAAM,CAAC;IACxB,YAAY,EAAE,MAAM,CAAC;IACrB,2FAA2F;IAC3F,oBAAoB,EAAE,MAAM,CAAC;CAC9B;AAUD,+DAA+D;AAC/D,wBAAsB,eAAe,CAAC,OAAO,EAAE,OAAO,EAAE,SAAS,EAAE,MAAM,EAAE,SAAS,EAAE,MAAM,EAAE,OAAO,EAAE,MAAM,EAAE,UAAU,CAAC,EAAE,MAAM,GAAG,OAAO,CAAC,eAAe,CAAC,CA2C5J"}

package/dist/src/services/finance/vat-report.js

@@ -0,0 +1,59 @@
+import { FinanceError } from './errors.js';
+import { ensureVatCodesSeeded } from './vat-codes.js';
+const MONTH_RE = /^\d{4}-\d{2}$/;
+function monthEnd(month) {
+    const [y, m] = month.split('-').map(Number);
+    const last = new Date(Date.UTC(y, m, 0)).getUTCDate();
+    return `${month}-${String(last).padStart(2, '0')}`;
+}
+/** Period summary; from/to are months (yyyy-mm), inclusive. */
+export async function vatPeriodReport(storage, ownerGhii, fromMonth, toMonth, organismId) {
+    if (!MONTH_RE.test(fromMonth) || !MONTH_RE.test(toMonth)) {
+        throw new FinanceError('INVALID_PERIOD', 400, 'from and to must be months (yyyy-mm)');
+    }
+    if (fromMonth > toMonth)
+        throw new FinanceError('INVALID_PERIOD', 400, 'from must not be after to');
+    await ensureVatCodesSeeded(storage);
+    const from = `${fromMonth}-01`;
+    const to = monthEnd(toMonth);
+    const vouchers = await storage.listVouchers({ ownerGhii, organismId, from, to, limit: 10000 });
+    const codes = new Map((await storage.listVatCodes()).map((c) => [c.id, c]));
+    const rows = new Map();
+    let unclassified = 0;
+    for (const v of vouchers) {
+        if (v.direction === 'transfer')
+            continue; // internal money movement — no VAT effect
+        if (v.vatBreakdown.length === 0) {
+            unclassified++;
+            continue;
+        }
+        for (const entry of v.vatBreakdown) {
+            const key = `${entry.vatCodeId}:${entry.vatRateBp}`;
+            const row = rows.get(key) ?? {
+                vatCodeId: entry.vatCodeId, vatRateBp: entry.vatRateBp,
+                label: codes.get(entry.vatCodeId)?.label ?? null,
+                salesNetMinor: 0, salesVatMinor: 0, purchasesNetMinor: 0, purchasesVatMinor: 0,
+            };
+            if (v.direction === 'income') {
+                row.salesNetMinor += entry.netMinor;
+                row.salesVatMinor += entry.vatMinor;
+            }
+            else {
+                row.purchasesNetMinor += entry.netMinor;
+                row.purchasesVatMinor += entry.vatMinor;
+            }
+            rows.set(key, row);
+        }
+    }
+    const sorted = [...rows.values()].sort((a, b) => b.vatRateBp - a.vatRateBp);
+    const totalSalesVatMinor = sorted.reduce((s, r) => s + r.salesVatMinor, 0);
+    const totalPurchasesVatMinor = sorted.reduce((s, r) => s + r.purchasesVatMinor, 0);
+    return {
+        from, to, rows: sorted,
+        totalSalesVatMinor, totalPurchasesVatMinor,
+        vatPayableMinor: totalSalesVatMinor - totalPurchasesVatMinor,
+        voucherCount: vouchers.length,
+        unclassifiedVouchers: unclassified,
+    };
+}
+//# sourceMappingURL=vat-report.js.map

package/dist/src/services/finance/vat-report.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"vat-report.js","sourceRoot":"","sources":["../../../../src/services/finance/vat-report.ts"],"names":[],"mappings":"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"}

package/dist/src/services/finance/vouchers.d.ts

@@ -0,0 +1,30 @@
+import type { Storage } from '../../storage/interface.js';
+import type { VoucherRecord, VoucherSource, VoucherDirection, VatBreakdownEntry } from '../../models/finance-schemas.js';
+export interface VoucherInput {
+    organismId?: string | null;
+    /** Booking date, ISO yyyy-mm-dd. */
+    date: string;
+    description: string;
+    direction: VoucherDirection;
+    source: VoucherSource;
+    /** Gross amount in cents, always positive; direction carries the sign. */
+    amountMinor: number;
+    currency?: string;
+    vatBreakdown?: VatBreakdownEntry[];
+    counterparty?: string | null;
+    invoiceId?: string | null;
+    trackingCode?: string | null;
+    externalRef?: string | null;
+    attachments?: string[];
+    reversesVoucherId?: string | null;
+}
+/** Books a voucher. Locked fiscal year → 409. externalRef reuse (webhook retry) returns the existing voucher. */
+export declare function bookVoucher(storage: Storage, ownerGhii: string, input: VoucherInput): Promise<VoucherRecord>;
+/**
+ * Books the counter-voucher that reverses an earlier booking (opposite direction, same
+ * amount). This is THE correction mechanism — the original row is never touched.
+ */
+export declare function reverseVoucher(storage: Storage, ownerGhii: string, voucherId: string, reason: string): Promise<VoucherRecord>;
+/** Adds evidence (storage keys) to a voucher — augments the record, never changes the booking. */
+export declare function attachEvidence(storage: Storage, ownerGhii: string, voucherId: string, keys: string[]): Promise<VoucherRecord>;
+//# sourceMappingURL=vouchers.d.ts.map

package/dist/src/services/finance/vouchers.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"vouchers.d.ts","sourceRoot":"","sources":["../../../../src/services/finance/vouchers.ts"],"names":[],"mappings":"AAYA,OAAO,KAAK,EAAE,OAAO,EAAE,MAAM,4BAA4B,CAAC;AAC1D,OAAO,KAAK,EAAE,aAAa,EAAE,aAAa,EAAE,gBAAgB,EAAE,iBAAiB,EAAE,MAAM,iCAAiC,CAAC;AAIzH,MAAM,WAAW,YAAY;IAC3B,UAAU,CAAC,EAAE,MAAM,GAAG,IAAI,CAAC;IAC3B,oCAAoC;IACpC,IAAI,EAAE,MAAM,CAAC;IACb,WAAW,EAAE,MAAM,CAAC;IACpB,SAAS,EAAE,gBAAgB,CAAC;IAC5B,MAAM,EAAE,aAAa,CAAC;IACtB,0EAA0E;IAC1E,WAAW,EAAE,MAAM,CAAC;IACpB,QAAQ,CAAC,EAAE,MAAM,CAAC;IAClB,YAAY,CAAC,EAAE,iBAAiB,EAAE,CAAC;IACnC,YAAY,CAAC,EAAE,MAAM,GAAG,IAAI,CAAC;IAC7B,SAAS,CAAC,EAAE,MAAM,GAAG,IAAI,CAAC;IAC1B,YAAY,CAAC,EAAE,MAAM,GAAG,IAAI,CAAC;IAC7B,WAAW,CAAC,EAAE,MAAM,GAAG,IAAI,CAAC;IAC5B,WAAW,CAAC,EAAE,MAAM,EAAE,CAAC;IACvB,iBAAiB,CAAC,EAAE,MAAM,GAAG,IAAI,CAAC;CACnC;AAID,iHAAiH;AACjH,wBAAsB,WAAW,CAAC,OAAO,EAAE,OAAO,EAAE,SAAS,EAAE,MAAM,EAAE,KAAK,EAAE,YAAY,GAAG,OAAO,CAAC,aAAa,CAAC,CA4ClH;AAED;;;GAGG;AACH,wBAAsB,cAAc,CAAC,OAAO,EAAE,OAAO,EAAE,SAAS,EAAE,MAAM,EAAE,SAAS,EAAE,MAAM,EAAE,MAAM,EAAE,MAAM,GAAG,OAAO,CAAC,aAAa,CAAC,CAkBnI;AAED,kGAAkG;AAClG,wBAAsB,cAAc,CAAC,OAAO,EAAE,OAAO,EAAE,SAAS,EAAE,MAAM,EAAE,SAAS,EAAE,MAAM,EAAE,IAAI,EAAE,MAAM,EAAE,GAAG,OAAO,CAAC,aAAa,CAAC,CAUnI"}

package/dist/src/services/finance/vouchers.js

@@ -0,0 +1,101 @@
+/**
+ * @file src/services/finance/vouchers.ts
+ * @description Voucher booking: the single door through which every tosite is created.
+ *   Resolves the fiscal year from the booking date (auto-creating a calendar year),
+ *   rejects a locked year, claims the sequential voucher number atomically, and keeps
+ *   the record append-only — corrections go through reverseVoucher(), never edits.
+ * @structure bookVoucher · reverseVoucher · attachEvidence
+ * @usage await bookVoucher(storage, ownerGhii, { date, description, direction, ... });
+ * @version-history
+ *   v1.0.0 — 2026-08-06 — Company-in-a-box phase 1.
+ */
+import { randomUUID } from 'node:crypto';
+import { FinanceError } from './errors.js';
+import { fiscalYearForDate } from './invoice-service.js';
+const DATE_RE = /^\d{4}-\d{2}-\d{2}$/;
+/** Books a voucher. Locked fiscal year → 409. externalRef reuse (webhook retry) returns the existing voucher. */
+export async function bookVoucher(storage, ownerGhii, input) {
+    if (!DATE_RE.test(input.date))
+        throw new FinanceError('INVALID_DATE', 400, 'date must be yyyy-mm-dd');
+    if (!input.description || typeof input.description !== 'string' || !input.description.trim()) {
+        throw new FinanceError('INVALID_VOUCHER', 400, 'description is required');
+    }
+    if (!Number.isInteger(input.amountMinor) || input.amountMinor <= 0) {
+        throw new FinanceError('INVALID_VOUCHER', 400, 'amountMinor must be a positive integer (cents); direction carries the sign');
+    }
+    if (input.direction !== 'income' && input.direction !== 'expense' && input.direction !== 'transfer') {
+        throw new FinanceError('INVALID_VOUCHER', 400, "direction must be 'income', 'expense' or 'transfer'");
+    }
+    if (input.direction === 'transfer' && (input.vatBreakdown?.length ?? 0) > 0) {
+        throw new FinanceError('INVALID_VOUCHER', 400, 'A transfer voucher carries no VAT breakdown');
+    }
+    // Idempotency for external events: a Stripe webhook retry must not double-book.
+    if (input.externalRef) {
+        const existing = await storage.findVoucherByExternalRef(ownerGhii, input.externalRef);
+        if (existing)
+            return existing;
+    }
+    const fiscalYear = await fiscalYearForDate(storage, ownerGhii, input.date, input.organismId ?? null);
+    if (fiscalYear.locked)
+        throw new FinanceError('FISCAL_YEAR_LOCKED', 409, `Fiscal year ${fiscalYear.label} is locked; new vouchers are rejected`);
+    const voucherNumber = await storage.nextFinanceCounter(ownerGhii, `voucher:${fiscalYear.id}`);
+    const now = new Date().toISOString();
+    const record = {
+        id: randomUUID(), ownerGhii,
+        organismId: input.organismId ?? null,
+        fiscalYearId: fiscalYear.id, voucherNumber,
+        date: input.date, description: input.description.trim(),
+        direction: input.direction, source: input.source,
+        amountMinor: input.amountMinor, currency: input.currency ?? 'EUR',
+        vatBreakdown: input.vatBreakdown ?? [],
+        counterparty: input.counterparty ?? null,
+        invoiceId: input.invoiceId ?? null,
+        trackingCode: input.trackingCode ?? null,
+        externalRef: input.externalRef ?? null,
+        attachments: input.attachments ?? [],
+        reversesVoucherId: input.reversesVoucherId ?? null,
+        createdAt: now, updatedAt: now,
+    };
+    await storage.createVoucher(record);
+    return record;
+}
+/**
+ * Books the counter-voucher that reverses an earlier booking (opposite direction, same
+ * amount). This is THE correction mechanism — the original row is never touched.
+ */
+export async function reverseVoucher(storage, ownerGhii, voucherId, reason) {
+    const original = await storage.getVoucher(voucherId);
+    if (!original || original.ownerGhii !== ownerGhii)
+        throw new FinanceError('NOT_FOUND', 404, 'Voucher not found');
+    if (original.reversesVoucherId)
+        throw new FinanceError('INVALID_REVERSAL', 422, 'A reversal voucher cannot itself be reversed');
+    return bookVoucher(storage, ownerGhii, {
+        organismId: original.organismId,
+        date: new Date().toISOString().slice(0, 10),
+        description: `Reversal of voucher #${original.voucherNumber}: ${reason}`,
+        direction: original.direction === 'transfer' ? 'transfer' : (original.direction === 'income' ? 'expense' : 'income'),
+        source: 'manual',
+        amountMinor: original.amountMinor,
+        currency: original.currency,
+        vatBreakdown: original.vatBreakdown,
+        counterparty: original.counterparty,
+        invoiceId: original.invoiceId,
+        trackingCode: original.trackingCode,
+        reversesVoucherId: original.id,
+    });
+}
+/** Adds evidence (storage keys) to a voucher — augments the record, never changes the booking. */
+export async function attachEvidence(storage, ownerGhii, voucherId, keys) {
+    const voucher = await storage.getVoucher(voucherId);
+    if (!voucher || voucher.ownerGhii !== ownerGhii)
+        throw new FinanceError('NOT_FOUND', 404, 'Voucher not found');
+    if (!Array.isArray(keys) || keys.some((k) => typeof k !== 'string' || !k.trim())) {
+        throw new FinanceError('INVALID_ATTACHMENTS', 400, 'attachments must be storage keys (non-empty strings)');
+    }
+    const merged = [...new Set([...voucher.attachments, ...keys])];
+    if (merged.length > 20)
+        throw new FinanceError('TOO_MANY_ATTACHMENTS', 422, 'A voucher holds at most 20 attachments');
+    await storage.setVoucherAttachments(voucherId, merged);
+    return { ...voucher, attachments: merged };
+}
+//# sourceMappingURL=vouchers.js.map

package/dist/src/services/finance/vouchers.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"vouchers.js","sourceRoot":"","sources":["../../../../src/services/finance/vouchers.ts"],"names":[],"mappings":"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"}