@wirecat/cli-core 0.556.0 → 0.557.0

package/CHANGELOG.md

@@ -7,6 +7,27 @@ shape of this file.
 
 ## Unreleased
 
+## 0.557.0 — 02.11.2026
+
+### Added
+
+- **Invoices and payments in the store (store version 45).** `store.finance` adds, lists and shows invoices with
+  their lines and payments, allocates a payment to invoices and sums what open invoices still owe per currency
+  (`openTotals`). Money is an integer in the currency's minor units (`CURRENCY_SCALES`, ISO 4217), passed and read as
+  decimal strings; an unknown currency is refused and nothing is converted. A total must equal its lines, and an
+  allocation never exceeds the payment or the invoice or crosses currencies; triggers back the code. The status
+  follows confirmed allocations; only the owner issues a draft or voids an invoice.
+- **An agent's or an import's invoice or payment is a proposal.** The owner's entry is confirmed at once; a bot's
+  waits as `invoice` or `payment` in `proposalRegistry`, and only the owner decides it. A pending payment's
+  allocations never count against an invoice, so they never block the owner's own. Confirming one counts them in the
+  same write, or is refused while other confirmed payments already cover the invoice; rejecting drops them.
+- **`invoice:<id>` and `payment:<id>` references,** with `refs.summaries` titles such as
+  `42 · 50 000.00 RUB to ООО Ромашка, due 15.11 (partly paid)`.
+
+### Fixed
+
+- **Mail `review` gives three examples**, as the command lint asks; `--waiting` stays in its help.
+
 ## 0.556.0 — 02.11.2026
 
 ### Added

package/dist/calendar/mcp/index.d.ts

@@ -10,13 +10,13 @@ export declare const calendarTools: ({
     inputSchema: {
         type: string;
         properties: {
-            limit?: undefined;
             account_id: {
                 type: string;
                 minimum: number;
             };
             query?: undefined;
             timezone?: undefined;
+            limit?: undefined;
             page?: undefined;
             event?: undefined;
         } | {
@@ -45,9 +45,9 @@ export declare const calendarTools: ({
             };
             event?: undefined;
         } | {
-            limit?: undefined;
             query?: undefined;
             timezone?: undefined;
+            limit?: undefined;
             page?: undefined;
             event: {
                 type: string;
@@ -58,9 +58,9 @@ export declare const calendarTools: ({
                 minimum: number;
             };
         } | {
-            limit?: undefined;
             query?: undefined;
             timezone?: undefined;
+            limit?: undefined;
             page?: undefined;
             event?: undefined;
             account_id?: undefined;
@@ -80,13 +80,13 @@ export declare const calendarTools: ({
     inputSchema: {
         type: string;
         properties: {
-            limit?: undefined;
             account_id: {
                 type: string;
                 minimum: number;
             };
             query?: undefined;
             timezone?: undefined;
+            limit?: undefined;
             page?: undefined;
             event?: undefined;
         } | {
@@ -115,9 +115,9 @@ export declare const calendarTools: ({
             };
             event?: undefined;
         } | {
-            limit?: undefined;
             query?: undefined;
             timezone?: undefined;
+            limit?: undefined;
             page?: undefined;
             event: {
                 type: string;
@@ -128,9 +128,9 @@ export declare const calendarTools: ({
                 minimum: number;
             };
         } | {
-            limit?: undefined;
             query?: undefined;
             timezone?: undefined;
+            limit?: undefined;
             page?: undefined;
             event?: undefined;
             account_id?: undefined;
@@ -150,13 +150,13 @@ export declare const calendarTools: ({
     inputSchema: {
         type: string;
         properties: {
-            limit?: undefined;
             account_id: {
                 type: string;
                 minimum: number;
             };
             query?: undefined;
             timezone?: undefined;
+            limit?: undefined;
             page?: undefined;
             event?: undefined;
         } | {
@@ -185,9 +185,9 @@ export declare const calendarTools: ({
             };
             event?: undefined;
         } | {
-            limit?: undefined;
             query?: undefined;
             timezone?: undefined;
+            limit?: undefined;
             page?: undefined;
             event: {
                 type: string;
@@ -198,9 +198,9 @@ export declare const calendarTools: ({
                 minimum: number;
             };
         } | {
-            limit?: undefined;
             query?: undefined;
             timezone?: undefined;
+            limit?: undefined;
             page?: undefined;
             event?: undefined;
             account_id?: undefined;
@@ -220,13 +220,13 @@ export declare const calendarTools: ({
     inputSchema: {
         type: string;
         properties: {
-            limit?: undefined;
             account_id: {
                 type: string;
                 minimum: number;
             };
             query?: undefined;
             timezone?: undefined;
+            limit?: undefined;
             page?: undefined;
             event?: undefined;
         } | {
@@ -255,9 +255,9 @@ export declare const calendarTools: ({
             };
             event?: undefined;
         } | {
-            limit?: undefined;
             query?: undefined;
             timezone?: undefined;
+            limit?: undefined;
             page?: undefined;
             event: {
                 type: string;
@@ -268,9 +268,9 @@ export declare const calendarTools: ({
                 minimum: number;
             };
         } | {
-            limit?: undefined;
             query?: undefined;
             timezone?: undefined;
+            limit?: undefined;
             page?: undefined;
             event?: undefined;
             account_id?: undefined;

package/dist/cli/messenger/store-maintenance-command.d.ts

@@ -3,9 +3,9 @@ import type { CacheDatabase } from "../../store/driver.js";
 import type { Messenger } from "./context.js";
 /** `doctor`'s short summary of the store. Must answer for a broken file, so an error is a field. */
 export declare const storeSummary: (env: NodeJS.ProcessEnv) => Promise<{
-    error?: undefined;
     path: string;
     exists: boolean;
+    error?: undefined;
 } | {
     path: string;
     exists: boolean;

package/dist/domain/finance.d.ts

@@ -0,0 +1,40 @@
+export declare const INVOICE_DIRECTIONS: readonly ["receivable", "payable"];
+export declare const INVOICE_STATUSES: readonly ["draft", "issued", "partly_paid", "paid", "void"];
+/** `in` is money to the owner, `out` money from the owner. */
+export declare const MONEY_DIRECTIONS: readonly ["in", "out"];
+/** The owner's entry is confirmed at once; an agent's or an import's waits as proposed. */
+export declare const FINANCE_REVIEWS: readonly ["proposed", "confirmed", "rejected"];
+export type InvoiceDirection = (typeof INVOICE_DIRECTIONS)[number];
+export type InvoiceStatus = (typeof INVOICE_STATUSES)[number];
+export type MoneyDirection = (typeof MONEY_DIRECTIONS)[number];
+export type FinanceReview = (typeof FINANCE_REVIEWS)[number];
+/** An invoice's status from what confirmed payments settle; `draft` and `void` are the owner's and stay. */
+export declare const settledStatus: (current: InvoiceStatus, total: number, paid: number) => InvoiceStatus;
+export interface InvoiceTitleFields {
+    id: number;
+    number: string | null;
+    direction: InvoiceDirection;
+    total: number;
+    currency: string;
+    counterpartyName: string | null;
+    dueDate: string | null;
+    status: InvoiceStatus;
+    review: FinanceReview;
+}
+/** "42 · 50 000.00 RUB to ООО Ромашка, due 15.11 (partly paid)": a ref summary's title, which `refLabel` prefixes. */
+export declare const invoiceLine: (invoice: InvoiceTitleFields) => string;
+export interface PaymentTitleFields {
+    direction: MoneyDirection;
+    amount: number;
+    currency: string;
+    /** Who paid the owner, or whom the owner paid. */
+    partyName: string | null;
+    date: string;
+    review: FinanceReview;
+}
+/** "50 000.00 RUB from ООО Ромашка, 14.11 (proposed)". */
+export declare const paymentLine: (payment: PaymentTitleFields) => string;
+/** "Invoice 42 · 50 000.00 RUB to ООО Ромашка, due 15.11 (partly paid)". */
+export declare const invoiceTitle: (invoice: InvoiceTitleFields) => string;
+/** "Payment · 50 000.00 RUB from ООО Ромашка, 14.11 (proposed)". */
+export declare const paymentEntryTitle: (payment: PaymentTitleFields) => string;

package/dist/domain/finance.js

@@ -0,0 +1,39 @@
+import { moneyLabel } from "./money.js";
+export const INVOICE_DIRECTIONS = ["receivable", "payable"];
+export const INVOICE_STATUSES = ["draft", "issued", "partly_paid", "paid", "void"];
+/** `in` is money to the owner, `out` money from the owner. */
+export const MONEY_DIRECTIONS = ["in", "out"];
+/** The owner's entry is confirmed at once; an agent's or an import's waits as proposed. */
+export const FINANCE_REVIEWS = ["proposed", "confirmed", "rejected"];
+/** An invoice's status from what confirmed payments settle; `draft` and `void` are the owner's and stay. */
+export const settledStatus = (current, total, paid) => {
+    if (current === "draft" || current === "void")
+        return current;
+    if (paid <= 0)
+        return "issued";
+    return paid < total ? "partly_paid" : "paid";
+};
+const dayMonth = (date) => (date === null ? null : `${date.slice(8, 10)}.${date.slice(5, 7)}`);
+const notes = (...words) => {
+    const kept = words.filter((word) => word !== null);
+    return kept.length === 0 ? "" : ` (${kept.join(", ")})`;
+};
+/** "42 · 50 000.00 RUB to ООО Ромашка, due 15.11 (partly paid)": a ref summary's title, which `refLabel` prefixes. */
+export const invoiceLine = (invoice) => {
+    const party = invoice.counterpartyName === null
+        ? ""
+        : `${invoice.direction === "receivable" ? " to" : " from"} ${invoice.counterpartyName}`;
+    const due = invoice.dueDate === null ? "" : `, due ${dayMonth(invoice.dueDate)}`;
+    return (`${invoice.number ?? `#${invoice.id}`} · ${moneyLabel(invoice.total, invoice.currency)}${party}${due}` +
+        notes(invoice.status.replace("_", " "), invoice.review === "confirmed" ? null : invoice.review));
+};
+/** "50 000.00 RUB from ООО Ромашка, 14.11 (proposed)". */
+export const paymentLine = (payment) => {
+    const party = payment.partyName === null ? "" : `${payment.direction === "in" ? " from" : " to"} ${payment.partyName}`;
+    return (`${moneyLabel(payment.amount, payment.currency)}${party}, ${dayMonth(payment.date)}` +
+        notes(payment.review === "confirmed" ? null : payment.review));
+};
+/** "Invoice 42 · 50 000.00 RUB to ООО Ромашка, due 15.11 (partly paid)". */
+export const invoiceTitle = (invoice) => `Invoice ${invoiceLine(invoice)}`;
+/** "Payment · 50 000.00 RUB from ООО Ромашка, 14.11 (proposed)". */
+export const paymentEntryTitle = (payment) => `Payment · ${paymentLine(payment)}`;

package/dist/domain/money.d.ts

@@ -0,0 +1,29 @@
+/**
+ * Minor-unit digits per ISO 4217 for the currencies the store keeps money in. A currency outside the list is refused
+ * rather than guessed: a wrong scale would store every amount 100 times off.
+ */
+export declare const CURRENCY_SCALES: Readonly<Record<string, number>>;
+/** An exact amount as callers read and write it: a decimal string with the currency's scale, never a float. */
+export interface Money {
+    amount: string;
+    currency: string;
+}
+/** A non-negative decimal as an integer of `scale` decimal places; `undefined` when it is not one. */
+export declare const parseDecimal: (text: string, scale: number) => bigint | undefined;
+export declare const formatDecimal: (units: bigint | number, scale: number) => string;
+/** `50000.00` as `50 000.00`: groups of three in the whole part, as a list prints an amount. */
+export declare const groupDigits: (decimal: string) => string;
+export declare const currencyOf: (text: unknown) => string;
+export declare const scaleOf: (currency: string) => number;
+/** Minor units of `currency` for a decimal string such as "50000.00"; refuses more decimals than the currency has. */
+export declare const minorUnits: (amount: unknown, currency: string, what?: string) => number;
+export declare const moneyOf: (units: number, currency: string) => Money;
+/** "50 000.00 RUB". */
+export declare const moneyLabel: (units: number, currency: string) => string;
+/** A quantity such as "1.5" (hours, days), kept as text: at most 3 decimals, more than 0. */
+export declare const quantityOf: (text: unknown) => {
+    text: string;
+    thousandths: bigint;
+};
+/** Quantity times unit price in minor units, half rounded up. */
+export declare const lineUnits: (thousandths: bigint, unitPrice: number) => number;

package/dist/domain/money.js

@@ -0,0 +1,98 @@
+import { CliError } from "@wirecat/cli-base";
+/**
+ * Minor-unit digits per ISO 4217 for the currencies the store keeps money in. A currency outside the list is refused
+ * rather than guessed: a wrong scale would store every amount 100 times off.
+ */
+export const CURRENCY_SCALES = {
+    AED: 2,
+    AMD: 2,
+    AUD: 2,
+    BHD: 3,
+    BYN: 2,
+    CAD: 2,
+    CHF: 2,
+    CLP: 0,
+    CNY: 2,
+    CZK: 2,
+    DKK: 2,
+    EUR: 2,
+    GBP: 2,
+    GEL: 2,
+    HUF: 2,
+    ILS: 2,
+    INR: 2,
+    ISK: 0,
+    JPY: 0,
+    KGS: 2,
+    KRW: 0,
+    KWD: 3,
+    KZT: 2,
+    NOK: 2,
+    PLN: 2,
+    RSD: 2,
+    RUB: 2,
+    SEK: 2,
+    THB: 2,
+    TRY: 2,
+    UAH: 2,
+    USD: 2,
+    UZS: 2,
+    VND: 0,
+};
+const refuse = (message, reason) => {
+    throw new CliError("validation_error", message, { reason });
+};
+const DECIMAL = /^(\d{1,15})(?:\.(\d+))?$/;
+/** A non-negative decimal as an integer of `scale` decimal places; `undefined` when it is not one. */
+export const parseDecimal = (text, scale) => {
+    const match = DECIMAL.exec(text.trim());
+    if (!match || (match[2] ?? "").length > scale)
+        return undefined;
+    return BigInt(`${match[1]}${(match[2] ?? "").padEnd(scale, "0")}`);
+};
+export const formatDecimal = (units, scale) => {
+    const digits = BigInt(units)
+        .toString()
+        .padStart(scale + 1, "0");
+    return scale === 0 ? digits : `${digits.slice(0, -scale)}.${digits.slice(-scale)}`;
+};
+/** `50000.00` as `50 000.00`: groups of three in the whole part, as a list prints an amount. */
+export const groupDigits = (decimal) => {
+    const [whole = "0", fraction] = decimal.split(".");
+    const grouped = whole.replace(/\B(?=(\d{3})+(?!\d))/g, " ");
+    return fraction === undefined ? grouped : `${grouped}.${fraction}`;
+};
+export const currencyOf = (text) => {
+    const code = typeof text === "string" ? text.trim().toUpperCase() : "";
+    if (CURRENCY_SCALES[code] === undefined)
+        return refuse(`${typeof text === "string" && text.trim() ? text.trim() : "an empty currency"} is not a currency the store keeps; ` +
+            `use one of ${Object.keys(CURRENCY_SCALES).join(", ")}`, "money.currency");
+    return code;
+};
+export const scaleOf = (currency) => CURRENCY_SCALES[currencyOf(currency)];
+/** Minor units of `currency` for a decimal string such as "50000.00"; refuses more decimals than the currency has. */
+export const minorUnits = (amount, currency, what = "an amount") => {
+    const scale = scaleOf(currency);
+    const units = typeof amount === "string" ? parseDecimal(amount, scale) : undefined;
+    if (units === undefined || units > BigInt(Number.MAX_SAFE_INTEGER))
+        return refuse(`${what} is a decimal string with at most ${scale} decimal${scale === 1 ? "" : "s"} for ${currency}, ` +
+            `such as "${formatDecimal(5_000 * 10 ** scale, scale)}"`, "money.amount");
+    return Number(units);
+};
+export const moneyOf = (units, currency) => ({
+    amount: formatDecimal(units, scaleOf(currency)),
+    currency,
+});
+/** "50 000.00 RUB". */
+export const moneyLabel = (units, currency) => `${groupDigits(formatDecimal(units, scaleOf(currency)))} ${currency}`;
+const QUANTITY_SCALE = 3;
+/** A quantity such as "1.5" (hours, days), kept as text: at most 3 decimals, more than 0. */
+export const quantityOf = (text) => {
+    const thousandths = typeof text === "string" ? parseDecimal(text, QUANTITY_SCALE) : undefined;
+    if (thousandths === undefined || thousandths === 0n)
+        return refuse('a quantity is a decimal string above 0 with at most 3 decimals, such as "1.5"', "money.quantity");
+    const plain = formatDecimal(thousandths, QUANTITY_SCALE).replace(/\.?0+$/, "");
+    return { text: plain, thousandths };
+};
+/** Quantity times unit price in minor units, half rounded up. */
+export const lineUnits = (thousandths, unitPrice) => Number((thousandths * BigInt(unitPrice) + 500n) / 1000n);

package/dist/domain/ref-summaries.js

@@ -49,6 +49,8 @@ const WORDS = {
     memory: "Memory",
     fact: "Fact",
     bot: "Bot",
+    invoice: "Invoice",
+    payment: "Payment",
     email: "Email",
     email_thread: "Email thread",
     unknown: "Unknown",

package/dist/domain/references.d.ts

@@ -33,7 +33,7 @@ export type Reference = {
  * Things named by their store id (a task also by its key or the task package's id). `entity` is the name
  * before organizations and projects: it still parses, so an old file's reference resolves as not found.
  */
-export declare const SIMPLE_REFERENCES: readonly ["note", "document", "person", "organization", "project", "task", "memory", "fact", "bot", "event", "entity"];
+export declare const SIMPLE_REFERENCES: readonly ["note", "document", "person", "organization", "project", "task", "memory", "fact", "bot", "event", "invoice", "payment", "entity"];
 export type SimpleReference = (typeof SIMPLE_REFERENCES)[number];
 export type RefKindName = Exclude<Reference["type"], "entity">;
 export interface RefKindSpec<R extends Reference = Reference> {

package/dist/domain/references.js

@@ -16,6 +16,8 @@ export const SIMPLE_REFERENCES = [
     "fact",
     "bot",
     "event",
+    "invoice",
+    "payment",
     "entity",
 ];
 const malformed = (text, shape) => new CliError("validation_error", `"${singleLine(text)}" is not a reference — expected ${shape}`, {

package/dist/errors/reasons.js

@@ -138,8 +138,23 @@ const OTHERS = [
     validation("input.required", "the command needs an answer and cannot ask for one"),
     validation("input.too-large", "the input is over its size limit"),
     ["meeting-project.stale", "configuration_error", "the meeting's project changed meanwhile"],
+    validation("finance.allocate", "the invoice or payment cannot take an allocation in its state"),
+    validation("finance.currency", "the payment and the invoice are in different currencies; nothing is converted"),
+    validation("finance.field", "a field of the invoice or payment is not valid"),
+    validation("finance.line-amount", "the line's amount is not its quantity times its unit price"),
+    validation("finance.lines", "the invoice's lines are not valid"),
+    validation("finance.over-invoice", "the allocation would settle more than the invoice's total"),
+    validation("finance.over-payment", "the allocation would use more than the payment's amount"),
+    ["finance.owner-only", "permission_error", "only the owner does this with money"],
+    validation("finance.party", "a party is a person: or organization: reference"),
+    validation("finance.ref", "the reference names no invoice or payment"),
+    validation("finance.status", "the invoice's status does not allow this"),
+    validation("finance.total", "the invoice's total is not the sum of its lines"),
     validation("memory.evidence-required", "a memory needs its evidence"),
     validation("memory.scope-required", "a memory needs its scope"),
+    validation("money.amount", "the amount is not a decimal string in the currency's scale"),
+    validation("money.currency", "the currency is not one the store keeps money in"),
+    validation("money.quantity", "the quantity is not a decimal above 0"),
     ["model.not-downloaded", "not_found", "the model is not downloaded on this machine"],
     ["person.no-owner", "not_found", "no person is marked as the owner in the store"],
     ["transcription.no-key", "authentication_error", "no OpenAI key is set for transcription"],

package/dist/index.d.ts

@@ -1,12 +1,14 @@
 export { bareCheck, type CheckWords, checkWords } from "./domain/checks.js";
 export type { CounterField, CounterObservation, CounterObservations, CounterState } from "./domain/counters.js";
 export { COUNTER_FIELDS, counterValue, observedCounters } from "./domain/counters.js";
+export { FINANCE_REVIEWS, type FinanceReview, INVOICE_DIRECTIONS, INVOICE_STATUSES, type InvoiceDirection, type InvoiceStatus, MONEY_DIRECTIONS, type MoneyDirection, } from "./domain/finance.js";
 export { type FormattedText, type HtmlFormatting, type MarkdownFormatting, type TextSpan, validateFormattedText, } from "./domain/formatting.js";
 export { formatLocator, isLocator, type MessageLocator, parseLocator } from "./domain/locator.js";
 export { type Markup, parseMarkdown } from "./domain/markdown.js";
 export { parseMarkdownSpans } from "./domain/markdown-spans.js";
 export type { MessageLink, MessagePermalink } from "./domain/message-link.js";
 export type * from "./domain/models.js";
+export { CURRENCY_SCALES, currencyOf, type Money, minorUnits, moneyLabel, moneyOf, } from "./domain/money.js";
 export { countedPoll } from "./domain/polls.js";
 export { FOLDER_PROVIDERS, isFolderProvider, isKind, KINDS, type Kind, kindIn, kindOf, PROVIDERS, type ProviderEntry, providerNamed, providers, UNKNOWN_PROVIDER, useProviders, } from "./domain/providers.js";
 export type { RankingGraphEvidence, RankingGraphLink } from "./domain/rankings-graph.js";

package/dist/index.js

@@ -1,9 +1,11 @@
 export { bareCheck, checkWords } from "./domain/checks.js";
 export { COUNTER_FIELDS, counterValue, observedCounters } from "./domain/counters.js";
+export { FINANCE_REVIEWS, INVOICE_DIRECTIONS, INVOICE_STATUSES, MONEY_DIRECTIONS, } from "./domain/finance.js";
 export { validateFormattedText, } from "./domain/formatting.js";
 export { formatLocator, isLocator, parseLocator } from "./domain/locator.js";
 export { parseMarkdown } from "./domain/markdown.js";
 export { parseMarkdownSpans } from "./domain/markdown-spans.js";
+export { CURRENCY_SCALES, currencyOf, minorUnits, moneyLabel, moneyOf, } from "./domain/money.js";
 export { countedPoll } from "./domain/polls.js";
 export { FOLDER_PROVIDERS, isFolderProvider, isKind, KINDS, kindIn, kindOf, PROVIDERS, providerNamed, providers, UNKNOWN_PROVIDER, useProviders, } from "./domain/providers.js";
 export { rankingOptions } from "./domain/rankings-options.js";

package/dist/mail/cli/review.js

@@ -188,7 +188,6 @@ export const mailReviewCommand = (mail) => annotate(new Command("review"), {
         `${mail.app.command} personal review "date>2h"`,
         `${mail.app.command} personal review --new`,
         `${mail.app.command} personal review --unanswered 1d`,
-        `${mail.app.command} personal review --waiting 7d`,
     ],
     effects: LOCAL_READ,
     partial: true,