@wirecat/cli-core 0.555.0 → 0.557.0

package/dist/store/sqlite/finance.js

@@ -0,0 +1,514 @@
+import { CliError } from "@wirecat/cli-base";
+import { FINANCE_REVIEWS, INVOICE_DIRECTIONS, INVOICE_STATUSES, invoiceTitle, MONEY_DIRECTIONS, paymentEntryTitle, settledStatus, } from "../../domain/finance.js";
+import { currencyOf, formatDecimal, lineUnits, minorUnits, moneyLabel, moneyOf, quantityOf, scaleOf, } from "../../domain/money.js";
+import { assertMayDecide, botKey, deciderAuthor } from "../decisions.js";
+import { proposedBySql, proposerOf } from "./actors.js";
+import { authorActor, authorOf, projectId, projectOf, subjectOf } from "./memories.js";
+import { requiredThing } from "./notes.js";
+import { write } from "./transaction.js";
+const refuse = (message, reason, code = "validation_error") => {
+    throw new CliError(code, message, { reason });
+};
+const oneOf = (value, allowed, what) => {
+    if (typeof value !== "string" || !allowed.includes(value))
+        return refuse(`${what} is one of ${allowed.join(", ")}`, "finance.field");
+    return value;
+};
+const text = (value, what, limit) => {
+    if (value === undefined || value === null)
+        return null;
+    if (typeof value !== "string" || !value.trim() || value.length > limit || value.includes("\0"))
+        return refuse(`${what} takes 1–${limit} characters`, "finance.field");
+    return value.trim();
+};
+const isoDate = (value, what) => {
+    if (value === undefined || value === null)
+        return null;
+    const date = typeof value === "string" ? value.trim() : "";
+    if (!/^\d{4}-\d{2}-\d{2}$/.test(date) || new Date(`${date}T00:00:00Z`).toISOString().slice(0, 10) !== date)
+        return refuse(`${what} is a date such as 2026-11-15`, "finance.field");
+    return date;
+};
+const iso = (value) => new Date(Number(value)).toISOString();
+const MAX_LINES = 500;
+const reasonOf = (metadata) => {
+    if (metadata == null)
+        return null;
+    try {
+        const { reason } = JSON.parse(String(metadata));
+        return typeof reason === "string" ? reason : null;
+    }
+    catch {
+        return null;
+    }
+};
+/** Money settled by confirmed payments only: a proposed payment promises nothing yet. */
+const PAID = "(SELECT coalesce(sum(a.amount), 0) FROM payment_allocations a JOIN payments p ON p.id = a.payment_id " +
+    "WHERE a.invoice_id = i.id AND p.review = 'confirmed' AND p.deleted_at IS NULL)";
+const INVOICES = `SELECT i.*, ${PAID} AS paid, b.name AS author_name, b.kind AS author_kind FROM invoices i ` +
+    "LEFT JOIN bots b ON i.author_type = 'bot' AND b.id = i.author_id";
+const PAYMENTS = "SELECT p.*, (SELECT coalesce(sum(amount), 0) FROM payment_allocations WHERE payment_id = p.id) AS allocated, " +
+    "b.name AS author_name, b.kind AS author_kind FROM payments p LEFT JOIN bots b ON p.author_type = 'bot' AND b.id = p.author_id";
+export const financeOperationsOver = (context) => {
+    const { database, now } = context;
+    const partyOf = (type, id) => {
+        if (type == null)
+            return null;
+        const { subject, subjectName, subjectIsOwner } = subjectOf(database, { subject_type: type, subject_id: id });
+        return subject === null ? null : { ref: subject, name: subjectName, owner: subjectIsOwner };
+    };
+    const partyThing = (reference, what) => {
+        if (reference === undefined)
+            return undefined;
+        const thing = requiredThing(database, reference, what);
+        if (thing.type !== "person" && thing.type !== "organization")
+            return refuse(`${what} is a person: or organization: reference, not ${reference}`, "finance.party");
+        return thing;
+    };
+    const reviewedOf = (row) => ({
+        review: row.review,
+        author: authorOf(row),
+        model: row.model == null ? null : String(row.model),
+        confirmedBy: row.confirmed_by_type == null
+            ? null
+            : { type: row.confirmed_by_type, id: String(row.confirmed_by_id) },
+        source: String(row.source),
+        reason: reasonOf(row.metadata),
+        ...projectOf(database, row),
+        createdAt: iso(row.created_at),
+        updatedAt: iso(row.updated_at),
+    });
+    const invoiceOf = (row) => {
+        const currency = String(row.currency);
+        const scale = scaleOf(currency);
+        const [total, paid] = [Number(row.total), Number(row.paid)];
+        const counterparty = partyOf(row.counterparty_type, row.counterparty_id);
+        const fields = {
+            id: Number(row.id),
+            number: row.number == null ? null : String(row.number),
+            direction: row.direction,
+            total,
+            currency,
+            counterpartyName: counterparty?.name ?? null,
+            dueDate: row.due_date == null ? null : String(row.due_date),
+            status: row.status,
+            review: row.review,
+        };
+        return {
+            id: String(row.id),
+            ref: `invoice:${row.id}`,
+            title: invoiceTitle(fields),
+            direction: fields.direction,
+            number: fields.number,
+            issuer: partyOf(row.issuer_type, row.issuer_id),
+            counterparty,
+            currency,
+            total: formatDecimal(total, scale),
+            paid: formatDecimal(paid, scale),
+            open: formatDecimal(Math.max(total - paid, 0), scale),
+            issueDate: row.issue_date == null ? null : String(row.issue_date),
+            dueDate: fields.dueDate,
+            status: fields.status,
+            ...reviewedOf(row),
+        };
+    };
+    const paymentOf = (row) => {
+        const currency = String(row.currency);
+        const scale = scaleOf(currency);
+        const [amount, allocated] = [Number(row.amount), Number(row.allocated)];
+        const direction = row.direction;
+        const payer = partyOf(row.payer_type, row.payer_id);
+        const payee = partyOf(row.payee_type, row.payee_id);
+        const date = String(row.payment_date);
+        return {
+            id: String(row.id),
+            ref: `payment:${row.id}`,
+            title: paymentEntryTitle({
+                direction,
+                amount,
+                currency,
+                partyName: (direction === "in" ? payer : payee)?.name ?? null,
+                date,
+                review: row.review,
+            }),
+            direction,
+            payer,
+            payee,
+            amount: formatDecimal(amount, scale),
+            currency,
+            date,
+            reference: row.reference == null ? null : String(row.reference),
+            allocated: formatDecimal(allocated, scale),
+            unallocated: formatDecimal(amount - allocated, scale),
+            ...reviewedOf(row),
+        };
+    };
+    const allocationsWhere = (column, id) => database
+        .prepare("SELECT a.*, p.currency FROM payment_allocations a JOIN payments p ON p.id = a.payment_id " +
+        `WHERE a.${column} = ? ORDER BY a.id`)
+        .all(id)
+        .map((row) => ({
+        payment: `payment:${row.payment_id}`,
+        invoice: `invoice:${row.invoice_id}`,
+        amount: formatDecimal(Number(row.amount), scaleOf(String(row.currency))),
+        currency: String(row.currency),
+        createdAt: iso(row.created_at),
+    }));
+    const rowOf = (reference, type) => {
+        const thing = requiredThing(database, reference.includes(":") ? reference : `${type}:${reference}`, `the ${type}`);
+        if (thing.type !== type)
+            return refuse(`${reference} is not an ${type}`, "finance.ref");
+        return database.prepare(`${type === "invoice" ? INVOICES : PAYMENTS} WHERE ${type[0]}.id = ?`).get(thing.id);
+    };
+    const invoiceDetail = (reference) => {
+        const row = rowOf(reference, "invoice");
+        const scale = scaleOf(String(row.currency));
+        const lines = database
+            .prepare("SELECT * FROM invoice_lines WHERE invoice_id = ? ORDER BY position")
+            .all(Number(row.id))
+            .map((line) => ({
+            position: Number(line.position),
+            description: String(line.description),
+            quantity: String(line.quantity),
+            unitPrice: line.unit_price == null ? null : formatDecimal(Number(line.unit_price), scale),
+            amount: formatDecimal(Number(line.amount), scale),
+        }));
+        return { ...invoiceOf(row), lines, allocations: allocationsWhere("invoice_id", Number(row.id)) };
+    };
+    const paymentDetail = (reference) => {
+        const row = rowOf(reference, "payment");
+        return { ...paymentOf(row), allocations: allocationsWhere("payment_id", Number(row.id)) };
+    };
+    const settle = (invoiceId) => {
+        const row = database
+            .prepare(`SELECT i.status, i.total, ${PAID} AS paid FROM invoices i WHERE i.id = ?`)
+            .get(invoiceId);
+        if (!row)
+            return;
+        const status = settledStatus(row.status, Number(row.total), Number(row.paid));
+        database
+            .prepare("UPDATE invoices SET status = ?, updated_at = ? WHERE id = ? AND status <> ?")
+            .run(status, now(), invoiceId, status);
+    };
+    const allocateRow = (payment, reference, units, actor) => {
+        const invoice = rowOf(reference, "invoice");
+        const [paymentRef, invoiceRef] = [`payment:${payment.id}`, `invoice:${invoice.id}`];
+        if (invoice.deleted_at != null || invoice.review === "rejected")
+            refuse(`${invoiceRef} is ${invoice.review === "rejected" ? "rejected" : "deleted"}`, "finance.allocate");
+        if (invoice.status === "draft" || invoice.status === "void")
+            refuse(`${invoiceRef} is ${invoice.status}; only an issued invoice is paid`, "finance.allocate");
+        const currency = String(payment.currency);
+        if (invoice.currency !== currency)
+            refuse(`${paymentRef} is in ${currency} and ${invoiceRef} in ${String(invoice.currency)}; the store converts nothing`, "finance.currency");
+        const fromPayment = Number(database
+            .prepare("SELECT coalesce(sum(amount), 0) AS n FROM payment_allocations WHERE payment_id = ?")
+            .get(Number(payment.id))?.n);
+        if (fromPayment + units > Number(payment.amount))
+            refuse(`${paymentRef} is ${moneyLabel(Number(payment.amount), currency)} and ` +
+                `${moneyLabel(fromPayment, currency)} of it is already allocated; ${moneyLabel(units, currency)} more is too much`, "finance.over-payment");
+        const toInvoice = Number(database
+            .prepare("SELECT coalesce(sum(a.amount), 0) AS n FROM payment_allocations a JOIN payments p ON p.id = a.payment_id " +
+            "WHERE a.invoice_id = ? AND ((p.review = 'confirmed' AND p.deleted_at IS NULL) OR a.payment_id = ?)")
+            .get(Number(invoice.id), Number(payment.id))?.n);
+        if (toInvoice + units > Number(invoice.total))
+            refuse(`${invoiceRef} totals ${moneyLabel(Number(invoice.total), currency)} and ` +
+                `${moneyLabel(toInvoice, currency)} is already allocated to it; ${moneyLabel(units, currency)} more is too much`, "finance.over-invoice");
+        const at = now();
+        database
+            .prepare("INSERT INTO payment_allocations (payment_id, invoice_id, amount, author_type, author_id, created_at, updated_at) " +
+            "VALUES (?, ?, ?, ?, ?, ?, ?) ON CONFLICT (payment_id, invoice_id) " +
+            "DO UPDATE SET amount = amount + excluded.amount, updated_at = excluded.updated_at")
+            .run(Number(payment.id), Number(invoice.id), units, actor.type, actor.id, at, at);
+        return Number(invoice.id);
+    };
+    const written = (input) => {
+        const owner = input.by === "owner";
+        const { actor, model } = authorActor(context, input.by);
+        const source = owner ? "owner" : (text(input.source, "a source", 80) ?? "agent");
+        const reason = owner ? null : text(input.reason, "a reason", 2000);
+        return {
+            owner,
+            actor,
+            model,
+            source,
+            review: owner ? "confirmed" : "proposed",
+            confirmedType: owner ? actor.type : null,
+            confirmedId: owner ? actor.id : null,
+            metadata: reason === null ? null : JSON.stringify({ reason }),
+            project: input.project === undefined ? null : projectId(database, input.project),
+        };
+    };
+    const ownerOnly = (by, what) => {
+        if (by !== "owner")
+            refuse(`only the owner ${what}`, "finance.owner-only", "permission_error");
+    };
+    const keepDecision = (table, id, by, reason) => {
+        const why = [by === "owner" ? undefined : by.reason.trim(), reason?.trim() || undefined].filter(Boolean).join(": ");
+        if (by === "owner" && !why)
+            return;
+        const decision = by === "owner" ? { by: "owner", reason: why } : { by: "agent", bot: by.bot, reason: why };
+        database
+            .prepare(`UPDATE ${table} SET metadata = json_set(coalesce(metadata, '{}'), '$.decision', json(?)) WHERE id = ?`)
+            .run(JSON.stringify(decision), id);
+    };
+    /** A proposed payment's allocations count once confirmed; by then other confirmed payments may cover the invoice. */
+    const coveredElsewhere = (paymentId) => {
+        const over = database
+            .prepare("SELECT a.invoice_id, a.amount, i.total, i.currency, (SELECT coalesce(sum(o.amount), 0) FROM payment_allocations o " +
+            "JOIN payments p ON p.id = o.payment_id WHERE o.invoice_id = a.invoice_id AND o.payment_id <> a.payment_id " +
+            "AND p.review = 'confirmed' AND p.deleted_at IS NULL) AS others FROM payment_allocations a " +
+            "JOIN invoices i ON i.id = a.invoice_id WHERE a.payment_id = ? AND a.amount + others > i.total LIMIT 1")
+            .get(paymentId);
+        if (!over)
+            return;
+        const currency = String(over.currency);
+        refuse(`invoice:${over.invoice_id} is already covered by other payments: ${moneyLabel(Number(over.others), currency)} ` +
+            `of ${moneyLabel(Number(over.total), currency)}; payment:${paymentId} would add ` +
+            `${moneyLabel(Number(over.amount), currency)}, so it stays proposed`, "finance.over-invoice");
+    };
+    const decide = (reference, by, reason, confirm) => {
+        const thing = requiredThing(database, reference, "the proposal");
+        if (thing.type !== "invoice" && thing.type !== "payment")
+            return refuse(`${reference} is not an invoice: or payment:`, "finance.ref");
+        const type = thing.type;
+        const table = type === "invoice" ? "invoices" : "payments";
+        const row = rowOf(reference, type);
+        const ref = `${type}:${row.id}`;
+        assertMayDecide({ id: ref, proposedBy: proposerOf(database, row.author_type, row.author_id), ownerOnly: true }, by, context.decisions);
+        if (row.review !== "proposed")
+            refuse(`${ref} is already ${String(row.review)}`, "proposal.wrong-state");
+        const id = Number(row.id);
+        write(database, () => {
+            const at = now();
+            if (confirm && type === "payment")
+                coveredElsewhere(id);
+            if (confirm) {
+                const { actor } = authorActor(context, deciderAuthor(by));
+                database
+                    .prepare(`UPDATE ${table} SET review = 'confirmed', confirmed_by_type = ?, confirmed_by_id = ?, updated_at = ? WHERE id = ?`)
+                    .run(actor.type, actor.id, at, id);
+            }
+            else
+                database.prepare(`UPDATE ${table} SET review = 'rejected', updated_at = ? WHERE id = ?`).run(at, id);
+            keepDecision(table, id, by, reason);
+            const touched = type === "invoice"
+                ? [id]
+                : database
+                    .prepare("SELECT invoice_id FROM payment_allocations WHERE payment_id = ?")
+                    .all(id)
+                    .map((one) => Number(one.invoice_id));
+            if (!confirm)
+                database
+                    .prepare(`DELETE FROM payment_allocations WHERE ${type === "invoice" ? "invoice_id" : "payment_id"} = ?`)
+                    .run(id);
+            for (const invoice of touched)
+                settle(invoice);
+        });
+        return type === "invoice" ? invoiceDetail(ref) : paymentDetail(ref);
+    };
+    const limitOf = (limit) => Math.min(Math.max(limit ?? 100, 1), 500);
+    return {
+        addInvoice: (input) => {
+            const direction = oneOf(input.direction, INVOICE_DIRECTIONS, "an invoice's direction");
+            const currency = currencyOf(input.currency);
+            if (!Array.isArray(input.lines) || input.lines.length === 0 || input.lines.length > MAX_LINES)
+                refuse(`an invoice has 1–${MAX_LINES} lines`, "finance.lines");
+            const lines = input.lines.map((line, at) => {
+                const what = `line ${at + 1}`;
+                const quantity = quantityOf(line.quantity ?? "1");
+                const unitPrice = line.unitPrice === undefined ? null : minorUnits(line.unitPrice, currency, `${what}'s unit price`);
+                const computed = unitPrice === null ? null : lineUnits(quantity.thousandths, unitPrice);
+                const amount = line.amount === undefined ? computed : minorUnits(line.amount, currency, `${what}'s amount`);
+                if (amount === null)
+                    return refuse(`${what} takes a unit price, an amount or both`, "finance.lines");
+                if (computed !== null && computed !== amount)
+                    refuse(`${what}: ${quantity.text} × ${moneyLabel(unitPrice, currency)} is ` +
+                        `${moneyLabel(computed, currency)}, not ${moneyLabel(amount, currency)}`, "finance.line-amount");
+                return {
+                    description: text(line.description, `${what}'s description`, 500) ??
+                        refuse(`${what} needs a description`, "finance.lines"),
+                    quantity: quantity.text,
+                    unitPrice: unitPrice ?? (quantity.thousandths === 1000n ? amount : null),
+                    amount,
+                };
+            });
+            const total = lines.reduce((sum, line) => sum + line.amount, 0);
+            if (!Number.isSafeInteger(total))
+                refuse("an invoice's total is too large", "finance.total");
+            if (total <= 0)
+                refuse("an invoice totals more than 0", "finance.total");
+            if (input.total !== undefined) {
+                const printed = minorUnits(input.total, currency, "an invoice's total");
+                if (printed !== total)
+                    refuse(`the invoice's total ${moneyLabel(printed, currency)} is not the sum of its lines, ${moneyLabel(total, currency)}`, "finance.total");
+            }
+            const number = text(input.number, "an invoice's number", 80);
+            const issueDate = isoDate(input.issueDate, "an invoice's issue date");
+            const dueDate = isoDate(input.dueDate, "an invoice's due date");
+            const id = write(database, () => {
+                const issuer = partyThing(input.issuer, "the issuer");
+                const counterparty = partyThing(input.counterparty, "the counterparty") ??
+                    refuse("an invoice names its counterparty, a person: or organization:", "finance.party");
+                const by = written(input);
+                const at = now();
+                const made = Number(database
+                    .prepare("INSERT INTO invoices (direction, number, issuer_type, issuer_id, counterparty_type, counterparty_id, project_id, " +
+                    "currency, total, issue_date, due_date, status, review, author_type, author_id, model, confirmed_by_type, " +
+                    "confirmed_by_id, source, metadata, created_at, updated_at) " +
+                    "VALUES (?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?) RETURNING id")
+                    .get(direction, number, issuer?.type ?? null, issuer?.id ?? null, counterparty.type, counterparty.id, by.project, currency, total, issueDate, dueDate, input.draft ? "draft" : "issued", by.review, by.actor.type, by.actor.id, by.model, by.confirmedType, by.confirmedId, by.source, by.metadata, at, at)?.id);
+                const insert = database.prepare("INSERT INTO invoice_lines (invoice_id, position, description, quantity, unit_price, amount, created_at, updated_at) " +
+                    "VALUES (?, ?, ?, ?, ?, ?, ?, ?)");
+                for (const [index, line] of lines.entries())
+                    insert.run(made, index + 1, line.description, line.quantity, line.unitPrice, line.amount, at, at);
+                return made;
+            });
+            return invoiceDetail(`invoice:${id}`);
+        },
+        invoice: (reference) => invoiceDetail(reference),
+        invoices: (filter = {}) => {
+            const project = filter.project === undefined ? null : projectId(database, filter.project);
+            const counterparty = partyThing(filter.counterparty, "the counterparty");
+            const by = proposedBySql("i.author_type", "i.author_id", filter.proposedBy);
+            const status = filter.status === undefined ? null : oneOf(filter.status, INVOICE_STATUSES, "a status");
+            const review = filter.review === undefined ? null : oneOf(filter.review, FINANCE_REVIEWS, "a review");
+            return database
+                .prepare(`${INVOICES} WHERE i.deleted_at IS NULL AND (? IS NULL OR i.direction = ?) AND (? IS NULL OR i.status = ?) ` +
+                "AND (? IS NULL OR i.review = ?) AND (? IS NULL OR i.project_id = ?) " +
+                "AND (? IS NULL OR (i.counterparty_type = ? AND i.counterparty_id = ?)) " +
+                `${filter.open ? "AND i.status IN ('issued', 'partly_paid') " : ""}AND ${by.sql} ` +
+                "ORDER BY i.created_at DESC, i.id DESC LIMIT ?")
+                .all(filter.direction ?? null, filter.direction ?? null, status, status, review, review, project, project, counterparty?.type ?? null, counterparty?.type ?? null, counterparty?.id ?? null, ...by.params, limitOf(filter.limit))
+                .map(invoiceOf);
+        },
+        issueInvoice: (reference, by) => {
+            ownerOnly(by, "issues an invoice");
+            const row = rowOf(reference, "invoice");
+            if (row.status !== "draft")
+                refuse(`invoice:${row.id} is ${String(row.status)}, not a draft`, "finance.status");
+            write(database, () => {
+                database
+                    .prepare("UPDATE invoices SET status = 'issued', updated_at = ? WHERE id = ?")
+                    .run(now(), Number(row.id));
+                settle(Number(row.id));
+            });
+            return invoiceDetail(`invoice:${row.id}`);
+        },
+        voidInvoice: (reference, by) => {
+            ownerOnly(by, "voids an invoice");
+            const row = rowOf(reference, "invoice");
+            if (row.status === "void")
+                refuse(`invoice:${row.id} is already void`, "finance.status");
+            const allocated = database
+                .prepare("SELECT 1 FROM payment_allocations a JOIN payments p ON p.id = a.payment_id " +
+                "WHERE a.invoice_id = ? AND p.review = 'confirmed' AND p.deleted_at IS NULL LIMIT 1")
+                .get(Number(row.id));
+            if (allocated)
+                refuse(`payments are allocated to invoice:${row.id}; a paid invoice is not voided`, "finance.status");
+            write(database, () => {
+                database
+                    .prepare("DELETE FROM payment_allocations WHERE invoice_id = ? " +
+                    "AND payment_id IN (SELECT id FROM payments WHERE review = 'proposed')")
+                    .run(Number(row.id));
+                database.prepare("UPDATE invoices SET status = 'void', updated_at = ? WHERE id = ?").run(now(), Number(row.id));
+            });
+            return invoiceDetail(`invoice:${row.id}`);
+        },
+        addPayment: (input) => {
+            const direction = oneOf(input.direction, MONEY_DIRECTIONS, "a payment's direction");
+            const currency = currencyOf(input.currency);
+            const amount = minorUnits(input.amount, currency, "a payment's amount");
+            if (amount <= 0)
+                refuse("a payment's amount is more than 0", "money.amount");
+            const date = isoDate(input.date, "a payment's date") ?? refuse("a payment has a date", "finance.field");
+            const reference = text(input.reference, "a payment's reference", 500);
+            const allocations = (input.allocations ?? []).map(({ invoice, amount: share }) => ({
+                invoice,
+                units: minorUnits(share, currency, `the amount allocated to ${invoice}`),
+            }));
+            const id = write(database, () => {
+                const payer = partyThing(input.payer, "the payer");
+                const payee = partyThing(input.payee, "the payee");
+                const by = written(input);
+                const at = now();
+                const made = database
+                    .prepare("INSERT INTO payments (direction, payer_type, payer_id, payee_type, payee_id, amount, currency, payment_date, " +
+                    "reference, project_id, review, author_type, author_id, model, confirmed_by_type, confirmed_by_id, source, " +
+                    "metadata, created_at, updated_at) VALUES (?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?) RETURNING *")
+                    .get(direction, payer?.type ?? null, payer?.id ?? null, payee?.type ?? null, payee?.id ?? null, amount, currency, date, reference, by.project, by.review, by.actor.type, by.actor.id, by.model, by.confirmedType, by.confirmedId, by.source, by.metadata, at, at);
+                const touched = allocations.map(({ invoice, units }) => allocateRow(made, invoice, units, by.actor));
+                for (const invoice of touched)
+                    settle(invoice);
+                return Number(made.id);
+            });
+            return paymentDetail(`payment:${id}`);
+        },
+        payment: (reference) => paymentDetail(reference),
+        payments: (filter = {}) => {
+            const project = filter.project === undefined ? null : projectId(database, filter.project);
+            const party = partyThing(filter.party, "the party");
+            const by = proposedBySql("p.author_type", "p.author_id", filter.proposedBy);
+            const review = filter.review === undefined ? null : oneOf(filter.review, FINANCE_REVIEWS, "a review");
+            return database
+                .prepare(`${PAYMENTS} WHERE p.deleted_at IS NULL AND (? IS NULL OR p.direction = ?) AND (? IS NULL OR p.review = ?) ` +
+                "AND (? IS NULL OR p.project_id = ?) AND (? IS NULL OR (p.payer_type = ? AND p.payer_id = ?) " +
+                `OR (p.payee_type = ? AND p.payee_id = ?)) AND ${by.sql} ORDER BY p.created_at DESC, p.id DESC LIMIT ?`)
+                .all(filter.direction ?? null, filter.direction ?? null, review, review, project, project, party?.type ?? null, party?.type ?? null, party?.id ?? null, party?.type ?? null, party?.id ?? null, ...by.params, limitOf(filter.limit))
+                .map(paymentOf);
+        },
+        allocate: ({ payment, invoice, amount, by }) => {
+            const row = rowOf(payment, "payment");
+            const ref = `payment:${row.id}`;
+            if (by !== "owner") {
+                const own = row.author_type === "bot" && row.author_name != null && botKey(String(row.author_name)) === botKey(by.bot);
+                if (row.review !== "proposed" || !own)
+                    refuse(`only the owner allocates ${ref}; a bot allocates only from a payment it proposed that is still proposed`, "finance.owner-only", "permission_error");
+            }
+            if (row.review === "rejected" || row.deleted_at != null)
+                refuse(`${ref} is ${String(row.review)}`, "finance.allocate");
+            const currency = String(row.currency);
+            const units = minorUnits(amount, currency, "an allocation");
+            if (units <= 0)
+                refuse("an allocation is more than 0", "money.amount");
+            const invoiceId = write(database, () => {
+                const { actor } = authorActor(context, by);
+                const made = allocateRow(row, invoice, units, actor);
+                settle(made);
+                return made;
+            });
+            const found = allocationsWhere("payment_id", Number(row.id)).find((one) => one.invoice === `invoice:${invoiceId}`);
+            return found;
+        },
+        confirm: (reference, by, reason) => decide(reference, by, reason, true),
+        reject: (reference, by, reason) => decide(reference, by, reason, false),
+        openTotals: (filter = {}) => {
+            const project = filter.project === undefined ? null : projectId(database, filter.project);
+            const rows = database
+                .prepare(`SELECT i.direction, i.currency, sum(i.total - ${PAID}) AS open, count(*) AS n FROM invoices i ` +
+                "WHERE i.review = 'confirmed' AND i.deleted_at IS NULL AND i.status IN ('issued', 'partly_paid') " +
+                "AND (? IS NULL OR i.project_id = ?) GROUP BY i.direction, i.currency ORDER BY i.currency")
+                .all(project, project);
+            const totals = (direction) => rows
+                .filter((row) => row.direction === direction)
+                .map((row) => ({ ...moneyOf(Number(row.open), String(row.currency)), invoices: Number(row.n) }));
+            return { receivable: totals("receivable"), payable: totals("payable") };
+        },
+    };
+};
+export const financeStoreOver = (context) => {
+    const operations = financeOperationsOver(context);
+    return {
+        addInvoice: async (input) => operations.addInvoice(input),
+        invoice: async (reference) => operations.invoice(reference),
+        invoices: async (filter) => operations.invoices(filter),
+        issueInvoice: async (reference, by) => operations.issueInvoice(reference, by),
+        voidInvoice: async (reference, by) => operations.voidInvoice(reference, by),
+        addPayment: async (input) => operations.addPayment(input),
+        payment: async (reference) => operations.payment(reference),
+        payments: async (filter) => operations.payments(filter),
+        allocate: async (input) => operations.allocate(input),
+        confirm: async (reference, by, reason) => operations.confirm(reference, by, reason),
+        reject: async (reference, by, reason) => operations.reject(reference, by, reason),
+        openTotals: async (filter) => operations.openTotals(filter),
+    };
+};

package/dist/store/sqlite/knowledge.js

@@ -148,7 +148,9 @@ export const knowledgeStoreOver = (context) => {
             parsed.type === "fact" ||
             parsed.type === "bot" ||
             parsed.type === "event" ||
-            parsed.type === "meeting")
+            parsed.type === "meeting" ||
+            parsed.type === "invoice" ||
+            parsed.type === "payment")
             return undefined;
         return { type: parsed.type, id: parsed.id };
     };

package/dist/store/sqlite/manifest.js

@@ -59,6 +59,8 @@ export const MANIFEST = [
     { name: "20261101011859_version-43-memory-project", version: 43, minCompatible: 34 },
     { name: "20261102050533_version-44-relationship-purpose", version: 44, minCompatible: 34 },
     { name: "20261102050534_version-44-suggested-links-move", version: 44, minCompatible: 34 },
+    { name: "20261102173102_version-45-finance", version: 45, minCompatible: 34 },
+    { name: "20261102173113_version-45-finance-rules", version: 45, minCompatible: 34 },
 ];
 export const generatedMigrations = (manifest = MANIFEST, generated = GENERATED) => {
     const migrations = [];

package/dist/store/sqlite/migrations.generated.js

@@ -889,5 +889,40 @@ export const GENERATED = [
         "statements": [
             "-- A suggestion's references (chat:, msg:) need the store's own encoding, which SQL cannot write, so the next writable\n-- open moves the unconfirmed agent and rule links into `proposed_actions` and deletes this key (moveSuggestedLinks).\nINSERT OR REPLACE INTO store_settings (key, value, at) VALUES ('suggested_links_to_move', '1', unixepoch() * 1000);"
         ]
+    },
+    {
+        "name": "20261102173102_version-45-finance",
+        "statements": [
+            "CREATE TABLE `invoice_lines` (\n\t`id` integer PRIMARY KEY,\n\t`invoice_id` integer NOT NULL,\n\t`position` integer NOT NULL,\n\t`description` text NOT NULL,\n\t`quantity` text NOT NULL,\n\t`unit_price` integer,\n\t`amount` integer NOT NULL,\n\t`created_at` integer NOT NULL,\n\t`updated_at` integer NOT NULL,\n\tCONSTRAINT `fk_invoice_lines_invoice_id_invoices_id_fk` FOREIGN KEY (`invoice_id`) REFERENCES `invoices`(`id`),\n\tCONSTRAINT `invoice_lines_invoice_id_position_unique` UNIQUE(`invoice_id`,`position`)\n);",
+            "CREATE TABLE `invoices` (\n\t`id` integer PRIMARY KEY,\n\t`direction` text NOT NULL,\n\t`number` text,\n\t`issuer_type` text,\n\t`issuer_id` integer,\n\t`counterparty_type` text NOT NULL,\n\t`counterparty_id` integer NOT NULL,\n\t`project_id` integer,\n\t`currency` text NOT NULL,\n\t`total` integer NOT NULL,\n\t`issue_date` text,\n\t`due_date` text,\n\t`status` text NOT NULL,\n\t`review` text NOT NULL,\n\t`author_type` text NOT NULL,\n\t`author_id` integer NOT NULL,\n\t`model` text,\n\t`confirmed_by_type` text,\n\t`confirmed_by_id` integer,\n\t`source` text NOT NULL,\n\t`metadata` text,\n\t`created_at` integer NOT NULL,\n\t`updated_at` integer NOT NULL,\n\t`deleted_at` integer,\n\tCONSTRAINT `fk_invoices_project_id_projects_id_fk` FOREIGN KEY (`project_id`) REFERENCES `projects`(`id`)\n);",
+            "CREATE TABLE `payment_allocations` (\n\t`id` integer PRIMARY KEY,\n\t`payment_id` integer NOT NULL,\n\t`invoice_id` integer NOT NULL,\n\t`amount` integer NOT NULL,\n\t`author_type` text NOT NULL,\n\t`author_id` integer NOT NULL,\n\t`created_at` integer NOT NULL,\n\t`updated_at` integer NOT NULL,\n\tCONSTRAINT `fk_payment_allocations_payment_id_payments_id_fk` FOREIGN KEY (`payment_id`) REFERENCES `payments`(`id`),\n\tCONSTRAINT `fk_payment_allocations_invoice_id_invoices_id_fk` FOREIGN KEY (`invoice_id`) REFERENCES `invoices`(`id`),\n\tCONSTRAINT `payment_allocations_payment_id_invoice_id_unique` UNIQUE(`payment_id`,`invoice_id`)\n);",
+            "CREATE TABLE `payments` (\n\t`id` integer PRIMARY KEY,\n\t`direction` text NOT NULL,\n\t`payer_type` text,\n\t`payer_id` integer,\n\t`payee_type` text,\n\t`payee_id` integer,\n\t`amount` integer NOT NULL,\n\t`currency` text NOT NULL,\n\t`payment_date` text NOT NULL,\n\t`reference` text,\n\t`project_id` integer,\n\t`review` text NOT NULL,\n\t`author_type` text NOT NULL,\n\t`author_id` integer NOT NULL,\n\t`model` text,\n\t`confirmed_by_type` text,\n\t`confirmed_by_id` integer,\n\t`source` text NOT NULL,\n\t`metadata` text,\n\t`created_at` integer NOT NULL,\n\t`updated_at` integer NOT NULL,\n\t`deleted_at` integer,\n\tCONSTRAINT `fk_payments_project_id_projects_id_fk` FOREIGN KEY (`project_id`) REFERENCES `projects`(`id`)\n);",
+            "CREATE INDEX `invoices_by_issuer_type_issuer_id` ON `invoices` (`issuer_type`,`issuer_id`);",
+            "CREATE INDEX `invoices_by_counterparty_type_counterparty_id` ON `invoices` (`counterparty_type`,`counterparty_id`);",
+            "CREATE INDEX `invoices_by_project_id` ON `invoices` (`project_id`);",
+            "CREATE INDEX `invoices_by_author_type_author_id` ON `invoices` (`author_type`,`author_id`);",
+            "CREATE INDEX `invoices_by_confirmed_by_type_confirmed_by_id` ON `invoices` (`confirmed_by_type`,`confirmed_by_id`);",
+            "CREATE INDEX `payment_allocations_by_invoice_id` ON `payment_allocations` (`invoice_id`);",
+            "CREATE INDEX `payment_allocations_by_author_type_author_id` ON `payment_allocations` (`author_type`,`author_id`);",
+            "CREATE INDEX `payments_by_payer_type_payer_id` ON `payments` (`payer_type`,`payer_id`);",
+            "CREATE INDEX `payments_by_payee_type_payee_id` ON `payments` (`payee_type`,`payee_id`);",
+            "CREATE INDEX `payments_by_project_id` ON `payments` (`project_id`);",
+            "CREATE INDEX `payments_by_author_type_author_id` ON `payments` (`author_type`,`author_id`);",
+            "CREATE INDEX `payments_by_confirmed_by_type_confirmed_by_id` ON `payments` (`confirmed_by_type`,`confirmed_by_id`);"
+        ]
+    },
+    {
+        "name": "20261102173113_version-45-finance-rules",
+        "statements": [
+            "-- The store's code checks these first and says why; the triggers keep a stray write from another build or a hand\n-- edit from storing money that does not add up. An invoice's limit counts confirmed payments only, so an agent's\n-- pending proposal never blocks the owner; confirming a payment checks the limit again.\nCREATE TRIGGER invoices_valid_bi BEFORE INSERT ON invoices\n  WHEN new.direction NOT IN ('receivable', 'payable') OR new.total < 0\n    OR new.status NOT IN ('draft', 'issued', 'partly_paid', 'paid', 'void')\n    OR new.review NOT IN ('proposed', 'confirmed', 'rejected') BEGIN\n  SELECT RAISE(ABORT, 'invoices: direction receivable or payable, a total of 0 or more, a known status and review');\nEND;",
+            "CREATE TRIGGER invoices_valid_bu BEFORE UPDATE ON invoices\n  WHEN new.direction NOT IN ('receivable', 'payable') OR new.total < 0\n    OR new.status NOT IN ('draft', 'issued', 'partly_paid', 'paid', 'void')\n    OR new.review NOT IN ('proposed', 'confirmed', 'rejected')\n    OR (new.currency IS NOT old.currency AND EXISTS (SELECT 1 FROM payment_allocations WHERE invoice_id = new.id))\n    OR new.total < (SELECT coalesce(sum(a.amount), 0) FROM payment_allocations a JOIN payments p ON p.id = a.payment_id\n      WHERE a.invoice_id = new.id AND p.review = 'confirmed' AND p.deleted_at IS NULL) BEGIN\n  SELECT RAISE(ABORT, 'invoices: the total stays at or above what is allocated to it, in the same currency');\nEND;",
+            "CREATE TRIGGER invoice_lines_valid_bi BEFORE INSERT ON invoice_lines\n  WHEN new.amount < 0 OR new.unit_price < 0 BEGIN\n  SELECT RAISE(ABORT, 'invoice_lines: an amount and a unit price of 0 or more');\nEND;",
+            "CREATE TRIGGER invoice_lines_valid_bu BEFORE UPDATE ON invoice_lines\n  WHEN new.amount < 0 OR new.unit_price < 0 BEGIN\n  SELECT RAISE(ABORT, 'invoice_lines: an amount and a unit price of 0 or more');\nEND;",
+            "CREATE TRIGGER payments_valid_bi BEFORE INSERT ON payments\n  WHEN new.direction NOT IN ('in', 'out') OR new.amount <= 0\n    OR new.review NOT IN ('proposed', 'confirmed', 'rejected') BEGIN\n  SELECT RAISE(ABORT, 'payments: direction in or out, an amount above 0 and a known review');\nEND;",
+            "CREATE TRIGGER payments_valid_bu BEFORE UPDATE ON payments\n  WHEN new.direction NOT IN ('in', 'out') OR new.amount <= 0\n    OR new.review NOT IN ('proposed', 'confirmed', 'rejected')\n    OR (new.currency IS NOT old.currency AND EXISTS (SELECT 1 FROM payment_allocations WHERE payment_id = new.id))\n    OR new.amount < (SELECT coalesce(sum(amount), 0) FROM payment_allocations WHERE payment_id = new.id) BEGIN\n  SELECT RAISE(ABORT, 'payments: the amount stays at or above what is allocated from it, in the same currency');\nEND;",
+            "CREATE TRIGGER payments_confirm_bu BEFORE UPDATE OF review ON payments\n  WHEN new.review = 'confirmed' AND old.review IS NOT 'confirmed' AND EXISTS (\n    SELECT 1 FROM payment_allocations a JOIN invoices i ON i.id = a.invoice_id WHERE a.payment_id = new.id\n      AND a.amount + (SELECT coalesce(sum(o.amount), 0) FROM payment_allocations o JOIN payments p ON p.id = o.payment_id\n        WHERE o.invoice_id = a.invoice_id AND o.payment_id <> new.id AND p.review = 'confirmed' AND p.deleted_at IS NULL)\n      > i.total) BEGIN\n  SELECT RAISE(ABORT, 'payments: confirming it would settle more than an invoice''s total');\nEND;",
+            "CREATE TRIGGER payment_allocations_valid_bi BEFORE INSERT ON payment_allocations\n  WHEN new.amount <= 0\n    OR (SELECT currency FROM payments WHERE id = new.payment_id)\n      IS NOT (SELECT currency FROM invoices WHERE id = new.invoice_id)\n    OR (SELECT coalesce(sum(amount), 0) FROM payment_allocations WHERE payment_id = new.payment_id) + new.amount\n      > (SELECT amount FROM payments WHERE id = new.payment_id)\n    OR (SELECT coalesce(sum(a.amount), 0) FROM payment_allocations a JOIN payments p ON p.id = a.payment_id\n      WHERE a.invoice_id = new.invoice_id\n        AND ((p.review = 'confirmed' AND p.deleted_at IS NULL) OR a.payment_id = new.payment_id)) + new.amount\n      > (SELECT total FROM invoices WHERE id = new.invoice_id) BEGIN\n  SELECT RAISE(ABORT, 'payment_allocations: above 0, one currency, within the payment and within the invoice');\nEND;",
+            "CREATE TRIGGER payment_allocations_valid_bu BEFORE UPDATE ON payment_allocations\n  WHEN new.amount <= 0 OR new.payment_id IS NOT old.payment_id OR new.invoice_id IS NOT old.invoice_id\n    OR (SELECT coalesce(sum(amount), 0) FROM payment_allocations WHERE payment_id = new.payment_id AND id <> old.id)\n      + new.amount > (SELECT amount FROM payments WHERE id = new.payment_id)\n    OR (SELECT coalesce(sum(a.amount), 0) FROM payment_allocations a JOIN payments p ON p.id = a.payment_id\n      WHERE a.invoice_id = new.invoice_id AND a.id <> old.id\n        AND ((p.review = 'confirmed' AND p.deleted_at IS NULL) OR a.payment_id = new.payment_id)) + new.amount\n      > (SELECT total FROM invoices WHERE id = new.invoice_id) BEGIN\n  SELECT RAISE(ABORT, 'payment_allocations: above 0, within the payment and within the invoice, sides unchanged');\nEND;"
+        ]
     }
 ];

package/dist/store/sqlite/ref-summaries.js

@@ -1,3 +1,4 @@
+import { invoiceLine, paymentLine } from "../../domain/finance.js";
 import { filesAccountSql, providerLabel, providerNamed } from "../../domain/providers.js";
 import { oneLine } from "../../domain/ref-summaries.js";
 import { formatReference, parseReference } from "../../domain/references.js";
@@ -181,6 +182,23 @@ const READERS = {
         body: bodyOr(body, "x.statement"),
     })),
     bot: byId("bot", "bots", () => ({ title: "x.name" })),
+    // Money is formatted with its currency's scale in JS, so SQL hands `titleOf` the fields as JSON.
+    invoice: byId("invoice", "invoices", () => ({
+        title: "json_object('id', x.id, 'number', x.number, 'direction', x.direction, 'total', x.total, " +
+            `'currency', x.currency, 'counterpartyName', ${subjectName("x.counterparty_type", "x.counterparty_id")}, ` +
+            "'dueDate', x.due_date, 'status', x.status, 'review', x.review)",
+        holder: "(SELECT name FROM projects WHERE id = x.project_id)",
+        at: "x.created_at",
+        deleted: "x.deleted_at",
+    })),
+    payment: byId("payment", "payments", () => ({
+        title: "json_object('direction', x.direction, 'amount', x.amount, 'currency', x.currency, 'partyName', " +
+            `CASE x.direction WHEN 'in' THEN ${subjectName("x.payer_type", "x.payer_id")} ` +
+            `ELSE ${subjectName("x.payee_type", "x.payee_id")} END, 'date', x.payment_date, 'review', x.review)`,
+        holder: "(SELECT name FROM projects WHERE id = x.project_id)",
+        at: "x.created_at",
+        deleted: "x.deleted_at",
+    })),
 };
 /** Mail saved before the mail tables existed is still messages, so a miss there is read again as a message. */
 const FALLBACK = { email: "message", email_thread: "chat" };
@@ -262,6 +280,17 @@ const refOfAccount = (reference) => reference.type === "message" || reference.ty
     : reference.type === "contact"
         ? { provider: reference.provider, account: null }
         : { provider: null, account: null };
+/** A summary never throws: fields that no longer parse, after `flat` made them one line, read as no title. */
+const fieldsOf = (json, line) => {
+    if (json === null)
+        return null;
+    try {
+        return line(JSON.parse(json));
+    }
+    catch {
+        return null;
+    }
+};
 const titleOf = (kind, reference, found) => {
     switch (kind) {
         case "message": {
@@ -271,6 +300,10 @@ const titleOf = (kind, reference, found) => {
         case "memory":
         case "fact":
             return cut(found.title, MEMORY_TITLE_CHARS);
+        case "invoice":
+            return fieldsOf(found.title, invoiceLine);
+        case "payment":
+            return fieldsOf(found.title, paymentLine);
         case "folder":
             return reference.type === "folder" && reference.path !== null && found.title !== null
                 ? `${found.title}/${reference.path}`