@kevludwig/lexware-office 0.1.0

package/dist/index.js

@@ -0,0 +1,11 @@
+export { DEFAULT_APP_URL, DEFAULT_BASE_URL, LexwareApiError, createLexwareClient, describeError, query, } from "./client.js";
+export { contactEmail, createCustomer, findContactByNumber, findContactsByName, getContact, resolveContactByName, } from "./contacts.js";
+export { addDays, berlinDay, daysSince } from "./dates.js";
+export { downloadInvoicePdf, findOverdueInvoice, findOverdueInvoices, } from "./receivables.js";
+export { DEFAULT_REMINDER_POLICY, daysPastReminderDue, earliestReminderDate, isDueImmediately, isOpenForReminder, reminderDueDate, reminderLedger, selectDueReminders, sendReminder, } from "./reminders.js";
+export { MailNotSentError, defaultReminderMail, reminderSubject, } from "./reminder-mail.js";
+export { keySegment, memoryStore } from "./store.js";
+export { DUPLICATE_TOTAL_TOLERANCE, ITEMS_TOTAL_TOLERANCE, netTotal, round2, taxFromGross, taxFromNet, } from "./money.js";
+export { REVERSE_CHARGE_TAX_RATE, isReverseChargeCategory, listPostingCategories, resolveCategory, } from "./categories.js";
+export { createVoucher, findPurchaseInvoiceByNumber, findVendorCategoryHistory, findVouchers, uploadVoucherFile, } from "./vouchers.js";
+export { SALES_DOCUMENT_STATUSES, VOUCHERLIST_TYPE, createSalesDocument, findDuplicateSalesDocument, findRecentSalesDocuments, getSalesDocument, invoiceExists, isPursueRejection, } from "./sales-documents.js";

package/dist/money.d.ts

@@ -0,0 +1,27 @@
+/**
+ * Amounts, taxes, and tolerances — one source, so a check and the card that
+ * shows it can never disagree about "matches".
+ */
+/**
+ * Tolerance when reconciling line items with a total read off a document.
+ * Covers the rounding of the document, nothing more.
+ */
+export declare const ITEMS_TOTAL_TOLERANCE = 0.02;
+/**
+ * Tolerance when comparing two already-rounded line-item totals, as the
+ * duplicate searches do. The same size as ITEMS_TOTAL_TOLERANCE, but a
+ * different question — hence its own name.
+ */
+export declare const DUPLICATE_TOTAL_TOLERANCE = 0.02;
+export declare function round2(value: number): number;
+/** A priced line, as far as totals need it. */
+export interface PricedLine {
+    quantity: number;
+    netPrice: number;
+}
+/** Net total of line items, rounded to the cent. */
+export declare function netTotal(lines: readonly PricedLine[]): number;
+/** Tax contained in a gross amount. */
+export declare function taxFromGross(gross: number, taxRatePercent: number): number;
+/** Tax on a net amount. */
+export declare function taxFromNet(net: number, taxRatePercent: number): number;

package/dist/money.js

@@ -0,0 +1,30 @@
+/**
+ * Amounts, taxes, and tolerances — one source, so a check and the card that
+ * shows it can never disagree about "matches".
+ */
+/**
+ * Tolerance when reconciling line items with a total read off a document.
+ * Covers the rounding of the document, nothing more.
+ */
+export const ITEMS_TOTAL_TOLERANCE = 0.02;
+/**
+ * Tolerance when comparing two already-rounded line-item totals, as the
+ * duplicate searches do. The same size as ITEMS_TOTAL_TOLERANCE, but a
+ * different question — hence its own name.
+ */
+export const DUPLICATE_TOTAL_TOLERANCE = 0.02;
+export function round2(value) {
+    return Math.round((value + Number.EPSILON) * 100) / 100;
+}
+/** Net total of line items, rounded to the cent. */
+export function netTotal(lines) {
+    return round2(lines.reduce((sum, line) => sum + line.quantity * line.netPrice, 0));
+}
+/** Tax contained in a gross amount. */
+export function taxFromGross(gross, taxRatePercent) {
+    return round2(gross - gross / (1 + taxRatePercent / 100));
+}
+/** Tax on a net amount. */
+export function taxFromNet(net, taxRatePercent) {
+    return round2(net * (taxRatePercent / 100));
+}

package/dist/receivables.d.ts

@@ -0,0 +1,40 @@
+/**
+ * Open receivables: overdue invoices and their PDF.
+ *
+ * The voucher list carries what a reminder needs — due date, open amount,
+ * customer — so choosing which invoice to remind is a list call and date
+ * arithmetic, not a model decision.
+ */
+import { type LexwareClient } from "./client.ts";
+export interface OverdueInvoice {
+    id: string;
+    voucherNumber: string;
+    /** yyyy-MM-dd */
+    voucherDate: string;
+    /** yyyy-MM-dd. Equal to the voucher date for an invoice due immediately. */
+    dueDate: string;
+    contactId?: string;
+    contactName: string;
+    totalAmount: number;
+    openAmount: number;
+    currency: string;
+}
+/**
+ * Every invoice Lexware Office counts as overdue. `overdue` has to stand alone
+ * in the status filter — the API rejects it combined with other statuses.
+ */
+export declare function findOverdueInvoices(client: LexwareClient, options?: {
+    signal?: AbortSignal;
+    maxPages?: number;
+}): Promise<OverdueInvoice[]>;
+/** One overdue invoice, or null once it no longer is (paid, voided). */
+export declare function findOverdueInvoice(client: LexwareClient, id: string, signal?: AbortSignal): Promise<OverdueInvoice | null>;
+/** An invoice as Lexware Office renders it — the PDF the customer received. */
+export declare function downloadInvoicePdf(client: LexwareClient, invoice: {
+    id: string;
+    voucherNumber: string;
+}, signal?: AbortSignal): Promise<{
+    bytes: Uint8Array;
+    filename: string;
+    mediaType: "application/pdf";
+}>;

package/dist/receivables.js

@@ -0,0 +1,45 @@
+/**
+ * Open receivables: overdue invoices and their PDF.
+ *
+ * The voucher list carries what a reminder needs — due date, open amount,
+ * customer — so choosing which invoice to remind is a list call and date
+ * arithmetic, not a model decision.
+ */
+import { query } from "./client.js";
+/**
+ * Every invoice Lexware Office counts as overdue. `overdue` has to stand alone
+ * in the status filter — the API rejects it combined with other statuses.
+ */
+export async function findOverdueInvoices(client, options = {}) {
+    const invoices = [];
+    for (let page = 0; page < (options.maxPages ?? 20); page++) {
+        const result = await client.request(`/voucherlist${query({ voucherType: "invoice", voucherStatus: "overdue", size: 100, page, sort: "voucherDate,ASC" })}`, { signal: options.signal });
+        for (const entry of result.content ?? []) {
+            if (!entry.voucherNumber || !entry.dueDate)
+                continue;
+            invoices.push({
+                id: entry.id,
+                voucherNumber: entry.voucherNumber,
+                voucherDate: entry.voucherDate?.slice(0, 10) ?? "",
+                dueDate: entry.dueDate.slice(0, 10),
+                contactId: entry.contactId,
+                contactName: entry.contactName?.trim() || "unbekannter Kunde",
+                totalAmount: entry.totalAmount ?? 0,
+                openAmount: entry.openAmount ?? entry.totalAmount ?? 0,
+                currency: entry.currency ?? "EUR",
+            });
+        }
+        if (result.last !== false || (result.content ?? []).length === 0)
+            break;
+    }
+    return invoices;
+}
+/** One overdue invoice, or null once it no longer is (paid, voided). */
+export async function findOverdueInvoice(client, id, signal) {
+    return (await findOverdueInvoices(client, { signal })).find((invoice) => invoice.id === id) ?? null;
+}
+/** An invoice as Lexware Office renders it — the PDF the customer received. */
+export async function downloadInvoicePdf(client, invoice, signal) {
+    const file = await client.download(`/invoices/${encodeURIComponent(invoice.id)}/file`, { accept: "application/pdf", signal });
+    return { bytes: file.bytes, filename: `${invoice.voucherNumber}.pdf`, mediaType: "application/pdf" };
+}

package/dist/reminder-mail.d.ts

@@ -0,0 +1,63 @@
+/**
+ * The payment reminder as a mail: what is sent, how it is rendered, and the
+ * default text — a friendly first reminder that assumes an oversight.
+ *
+ * Bring your own look with `render`; the default is plain, inline-styled
+ * HTML that every mail client shows. Sender details (name, address, legal
+ * notes) are yours to pass: a business letter needs them.
+ */
+export interface ReminderMailData {
+    voucherNumber: string;
+    /** yyyy-MM-dd */
+    voucherDate: string;
+    /** yyyy-MM-dd */
+    dueDate: string;
+    openAmount: number;
+    currency: string;
+    /** Set in test mode: whom the mail would reach live. */
+    testRecipientFor?: string;
+}
+export interface ReminderMail {
+    to: string;
+    cc: readonly string[];
+    subject: string;
+    html: string;
+    text?: string;
+    attachments: readonly {
+        filename: string;
+        mediaType: string;
+        bytes: Uint8Array;
+    }[];
+}
+/** Sends one mail. Throw MailNotSentError when it certainly did not go out. */
+export type SendReminderMail = (mail: ReminderMail, signal?: AbortSignal) => Promise<void>;
+/**
+ * The mail certainly did not leave: sign-in failed, the mail service refused
+ * it. Anything else thrown while sending counts as "may have left" — the send
+ * round then stays taken, since a second reminder is worse than none.
+ */
+export declare class MailNotSentError extends Error {
+    constructor(message: string, options?: {
+        cause?: unknown;
+    });
+}
+export interface ReminderSender {
+    /** Signature name, e.g. "Kevin Ludwig". */
+    name: string;
+    /** Lines under the name, e.g. the company and town. */
+    signature?: readonly string[];
+    /** Legal details below the mail: name, form, address, VAT id, links. */
+    legal?: readonly string[];
+}
+export type RenderReminderMail = (data: ReminderMailData) => {
+    subject: string;
+    html: string;
+    text?: string;
+} | Promise<{
+    subject: string;
+    html: string;
+    text?: string;
+}>;
+export declare function reminderSubject(voucherNumber: string, test: boolean): string;
+/** The default reminder: German, friendly, marked as sent automatically. */
+export declare function defaultReminderMail(sender: ReminderSender): RenderReminderMail;

package/dist/reminder-mail.js

@@ -0,0 +1,76 @@
+/**
+ * The payment reminder as a mail: what is sent, how it is rendered, and the
+ * default text — a friendly first reminder that assumes an oversight.
+ *
+ * Bring your own look with `render`; the default is plain, inline-styled
+ * HTML that every mail client shows. Sender details (name, address, legal
+ * notes) are yours to pass: a business letter needs them.
+ */
+/**
+ * The mail certainly did not leave: sign-in failed, the mail service refused
+ * it. Anything else thrown while sending counts as "may have left" — the send
+ * round then stays taken, since a second reminder is worse than none.
+ */
+export class MailNotSentError extends Error {
+    constructor(message, options) {
+        super(message, options);
+        this.name = "MailNotSentError";
+    }
+}
+const escape = (value) => value.replace(/[&<>"']/g, (char) => ({ "&": "&amp;", "<": "&lt;", ">": "&gt;", '"': "&quot;", "'": "&#39;" })[char]);
+const longDate = (day) => new Date(`${day.slice(0, 10)}T12:00:00Z`).toLocaleDateString("de-DE", {
+    day: "numeric",
+    month: "long",
+    year: "numeric",
+    timeZone: "Europe/Berlin",
+});
+const money = (value, currency) => value.toLocaleString("de-DE", { style: "currency", currency });
+export function reminderSubject(voucherNumber, test) {
+    return `${test ? "[Test] " : ""}Zahlungserinnerung zur Rechnung ${voucherNumber}`;
+}
+/** The default reminder: German, friendly, marked as sent automatically. */
+export function defaultReminderMail(sender) {
+    return (data) => {
+        const amount = money(data.openAmount, data.currency);
+        const lines = [
+            "Guten Tag,",
+            "",
+            `vielleicht ist es im Alltag untergegangen: Für unsere Rechnung ${data.voucherNumber} vom ${longDate(data.voucherDate)} ` +
+                `haben wir noch keinen Zahlungseingang gesehen. Sie war am ${longDate(data.dueDate)} fällig.`,
+            "",
+            "Die Rechnung hängt noch einmal an. Wir freuen uns, wenn Sie den offenen Betrag in den nächsten Tagen " +
+                "überweisen; die Bankverbindung steht auf der Rechnung.",
+            "",
+            `Rechnung: ${data.voucherNumber}`,
+            `Rechnungsdatum: ${longDate(data.voucherDate)}`,
+            `Fällig seit: ${longDate(data.dueDate)}`,
+            `Offener Betrag: ${amount}`,
+            "",
+            "Hat sich Ihre Zahlung mit dieser Nachricht überschnitten, betrachten Sie sie bitte als erledigt.",
+            "",
+            "Mit besten Grüßen",
+            sender.name,
+            ...(sender.signature ?? []),
+        ];
+        const footer = [
+            "Diese Zahlungserinnerung wurde automatisch erstellt und versendet.",
+            ...(sender.legal ?? []),
+        ];
+        const paragraph = (text) => `<p style="margin:0 0 12px">${escape(text)}</p>`;
+        const html = [
+            `<div style="font-family:-apple-system,Segoe UI,Helvetica,Arial,sans-serif;font-size:15px;line-height:1.6;color:#1a1a1a;max-width:600px">`,
+            data.testRecipientFor
+                ? `<p style="margin:0 0 16px;padding:8px 12px;background:#fff1c2">Testversand. Im Echtbetrieb ginge diese Mail an ${escape(data.testRecipientFor)}.</p>`
+                : "",
+            lines
+                .join("\n")
+                .split("\n\n")
+                .map((block) => paragraph(block).replaceAll("\n", "<br>"))
+                .join(""),
+            `<p style="margin:24px 0 0;font-size:12px;color:#666">${footer.map(escape).join("<br>")}</p>`,
+            "</div>",
+        ].join("");
+        const text = [...(data.testRecipientFor ? [`[Testversand, im Echtbetrieb an ${data.testRecipientFor}]`, ""] : []), ...lines, "", "--", ...footer].join("\n");
+        return { subject: reminderSubject(data.voucherNumber, Boolean(data.testRecipientFor)), html, text };
+    };
+}

package/dist/reminders.d.ts

@@ -0,0 +1,156 @@
+/**
+ * Payment reminders: when an overdue invoice is due for one, and what has
+ * happened per invoice.
+ *
+ * The selection is code, not judgment: an invoice is offered once it is a
+ * number of days past its reminder due date, has not been reminded, is not
+ * waiting for a decision elsewhere, was not declined lately, and its customer
+ * has an address. An invoice due immediately ("sofort fällig" — Lexware Office
+ * sets the due date to the invoice date) gets a payment term first.
+ *
+ * The ledger keeps one record per invoice, and one claim per send round: a
+ * round is the first reminder, or a deliberate repeat after the reminder sent
+ * at a given time. Claiming before sending makes "at most once per round"
+ * hold across cards, duplicate schedule runs, and replays.
+ */
+import type { LexwareClient } from "./client.ts";
+import { type OverdueInvoice } from "./receivables.ts";
+import { type RenderReminderMail, type SendReminderMail } from "./reminder-mail.ts";
+import { type JsonStore } from "./store.ts";
+export interface ReminderPolicy {
+    /** Days past the reminder due date before a first reminder. Default: 3. */
+    minDaysOverdue: number;
+    /** Payment term assumed for an invoice due immediately, in days. Default: 14. */
+    immediatePaymentTermDays: number;
+    /** A waiting reminder is offered again after this many hours. Default: 20. */
+    pendingValidHours: number;
+    /** A declined reminder stays quiet this many days. Default: 7. */
+    declinedQuietDays: number;
+}
+export declare const DEFAULT_REMINDER_POLICY: ReminderPolicy;
+interface Dated {
+    voucherDate: string;
+    dueDate: string;
+}
+/** Whether the due date is the invoice date itself. */
+export declare function isDueImmediately(invoice: Dated): boolean;
+/** The day from which lateness counts (yyyy-MM-dd). */
+export declare function reminderDueDate(invoice: Dated, policy?: ReminderPolicy): string;
+/** Days past the reminder due date. */
+export declare function daysPastReminderDue(invoice: Dated, policy?: ReminderPolicy, today?: Date): number;
+/** The first day a reminder is offered (yyyy-MM-dd). */
+export declare function earliestReminderDate(invoice: Dated, policy?: ReminderPolicy): string;
+export type ReminderStatus = "pending" | "sent" | "declined";
+export interface ReminderRecord {
+    invoiceId: string;
+    voucherNumber: string;
+    status: ReminderStatus;
+    /** ISO timestamp of the last change. */
+    at: string;
+    /** Where the reminder waits or was decided, e.g. an agent session. */
+    sessionId?: string;
+    recipient?: string;
+}
+/** Whether a record still lets a reminder be offered. */
+export declare function isOpenForReminder(record: ReminderRecord | null, policy?: ReminderPolicy, now?: number): boolean;
+/** One record per invoice and one claim per send round, in a JsonStore. */
+export interface ReminderLedger {
+    /** The record, or null. Throws when the store fails: unknown is not "never reminded". */
+    read(invoiceId: string): Promise<ReminderRecord | null>;
+    write(record: Omit<ReminderRecord, "at">): Promise<void>;
+    /** Marks the invoice as waiting — unless it was sent: "sent" is final. */
+    markPending(invoice: {
+        id: string;
+        voucherNumber: string;
+    }, sessionId?: string): Promise<void>;
+    /**
+     * Takes the one send of a round before the mail goes out. `round` is
+     * "first", or the time of the reminder a deliberate repeat follows. False
+     * when another send holds the round.
+     */
+    claimSend(invoiceId: string, round: string, owner: string): Promise<boolean>;
+    /** Gives a round back when its mail certainly did not go out. */
+    releaseSend(invoiceId: string, round: string): Promise<void>;
+}
+/**
+ * A ledger under `namespace` in the store. Keep separate namespaces for test
+ * and live sending, and per environment, so a test never stands in for a real
+ * reminder.
+ */
+export declare function reminderLedger(store: JsonStore, namespace: string): ReminderLedger;
+/** Why an overdue invoice is not offered now. */
+export type ReminderHold = {
+    kind: "too-early";
+    earliest: string;
+    immediate: boolean;
+} | {
+    kind: "sent" | "pending" | "declined";
+    at: string;
+    sessionId?: string;
+} | {
+    kind: "no-address";
+} | {
+    kind: "unreadable";
+    reason: string;
+};
+export interface DueReminder {
+    invoice: OverdueInvoice;
+    /** The customer's address as Lexware Office has it. */
+    customerEmail: string;
+}
+export interface ReminderSelection {
+    due: DueReminder[];
+    held: {
+        invoice: OverdueInvoice;
+        hold: ReminderHold;
+    }[];
+}
+/**
+ * Which overdue invoices get a reminder now. An invoice whose record or
+ * address cannot be read is held back, never offered as "never reminded".
+ */
+export declare function selectDueReminders(client: LexwareClient, ledger: ReminderLedger, options?: {
+    policy?: Partial<ReminderPolicy>;
+    signal?: AbortSignal;
+    today?: Date;
+}): Promise<ReminderSelection>;
+/** Everything a send needs, fixed when the reminder was decided on. */
+export interface ReminderTarget {
+    invoiceId: string;
+    voucherNumber: string;
+    voucherDate: string;
+    dueDate: string;
+    currency: string;
+    /** The recipient — the customer live, someone else in test mode. */
+    to: string;
+    cc?: readonly string[];
+    test: boolean;
+    /** The customer's address, for the test banner. */
+    customer?: string | null;
+    /** When a deliberate repeat follows an earlier reminder: that reminder's time — its send round. */
+    earlierSentAt?: string;
+}
+export type SendReminderOutcome = {
+    sent: true;
+    openAmount: number;
+    attachment: string;
+} | {
+    sent: false;
+    reason: "paid" | "taken";
+};
+/**
+ * Sends one reminder, at most once per round: re-checks that the invoice is
+ * still overdue, claims the round, renders and sends with the invoice PDF,
+ * and records it. Up to the mail call nothing has left, so a failure there
+ * frees the round; so does MailNotSentError. Any other failure while sending
+ * keeps the round taken.
+ */
+export declare function sendReminder(client: LexwareClient, ledger: ReminderLedger, target: ReminderTarget, options: {
+    render: RenderReminderMail;
+    sendMail: SendReminderMail;
+    /** Who sends — recorded with the claim, e.g. a tool call id. */
+    owner: string;
+    sessionId?: string;
+    signal?: AbortSignal;
+}): Promise<SendReminderOutcome>;
+export {};

package/dist/reminders.js

@@ -0,0 +1,175 @@
+/**
+ * Payment reminders: when an overdue invoice is due for one, and what has
+ * happened per invoice.
+ *
+ * The selection is code, not judgment: an invoice is offered once it is a
+ * number of days past its reminder due date, has not been reminded, is not
+ * waiting for a decision elsewhere, was not declined lately, and its customer
+ * has an address. An invoice due immediately ("sofort fällig" — Lexware Office
+ * sets the due date to the invoice date) gets a payment term first.
+ *
+ * The ledger keeps one record per invoice, and one claim per send round: a
+ * round is the first reminder, or a deliberate repeat after the reminder sent
+ * at a given time. Claiming before sending makes "at most once per round"
+ * hold across cards, duplicate schedule runs, and replays.
+ */
+import { contactEmail } from "./contacts.js";
+import { addDays, daysSince } from "./dates.js";
+import { downloadInvoicePdf, findOverdueInvoice, findOverdueInvoices } from "./receivables.js";
+import { MailNotSentError } from "./reminder-mail.js";
+import { keySegment } from "./store.js";
+export const DEFAULT_REMINDER_POLICY = {
+    minDaysOverdue: 3,
+    immediatePaymentTermDays: 14,
+    pendingValidHours: 20,
+    declinedQuietDays: 7,
+};
+/** Whether the due date is the invoice date itself. */
+export function isDueImmediately(invoice) {
+    return invoice.voucherDate !== "" && invoice.dueDate.slice(0, 10) <= invoice.voucherDate.slice(0, 10);
+}
+/** The day from which lateness counts (yyyy-MM-dd). */
+export function reminderDueDate(invoice, policy = DEFAULT_REMINDER_POLICY) {
+    return isDueImmediately(invoice)
+        ? addDays(invoice.voucherDate, policy.immediatePaymentTermDays)
+        : invoice.dueDate.slice(0, 10);
+}
+/** Days past the reminder due date. */
+export function daysPastReminderDue(invoice, policy = DEFAULT_REMINDER_POLICY, today) {
+    return daysSince(reminderDueDate(invoice, policy), today);
+}
+/** The first day a reminder is offered (yyyy-MM-dd). */
+export function earliestReminderDate(invoice, policy = DEFAULT_REMINDER_POLICY) {
+    return addDays(reminderDueDate(invoice, policy), policy.minDaysOverdue);
+}
+/** Whether a record still lets a reminder be offered. */
+export function isOpenForReminder(record, policy = DEFAULT_REMINDER_POLICY, now = Date.now()) {
+    if (!record)
+        return true;
+    const age = now - Date.parse(record.at);
+    switch (record.status) {
+        case "sent":
+            return false;
+        case "pending":
+            return age > policy.pendingValidHours * 3_600_000;
+        case "declined":
+            return age > policy.declinedQuietDays * 86_400_000;
+    }
+}
+/**
+ * A ledger under `namespace` in the store. Keep separate namespaces for test
+ * and live sending, and per environment, so a test never stands in for a real
+ * reminder.
+ */
+export function reminderLedger(store, namespace) {
+    const base = namespace.replace(/\/+$/, "");
+    const recordKey = (invoiceId) => `${base}/${keySegment(invoiceId)}`;
+    const claimKey = (invoiceId, round) => `${recordKey(invoiceId)}.send-${keySegment(round)}`;
+    return {
+        read: (invoiceId) => store.read(recordKey(invoiceId)),
+        write: (record) => store.write(recordKey(record.invoiceId), { ...record, at: new Date().toISOString() }),
+        async markPending(invoice, sessionId) {
+            if ((await store.read(recordKey(invoice.id)))?.status === "sent")
+                return;
+            await store.write(recordKey(invoice.id), {
+                invoiceId: invoice.id,
+                voucherNumber: invoice.voucherNumber,
+                status: "pending",
+                at: new Date().toISOString(),
+                ...(sessionId ? { sessionId } : {}),
+            });
+        },
+        claimSend: (invoiceId, round, owner) => store.create(claimKey(invoiceId, round), { owner, at: new Date().toISOString() }),
+        releaseSend: (invoiceId, round) => store.delete(claimKey(invoiceId, round)),
+    };
+}
+/**
+ * Which overdue invoices get a reminder now. An invoice whose record or
+ * address cannot be read is held back, never offered as "never reminded".
+ */
+export async function selectDueReminders(client, ledger, options = {}) {
+    const policy = { ...DEFAULT_REMINDER_POLICY, ...options.policy };
+    const overdue = await findOverdueInvoices(client, { signal: options.signal });
+    const now = (options.today ?? new Date()).getTime();
+    const checked = await Promise.all(overdue.map(async (invoice) => {
+        if (daysPastReminderDue(invoice, policy, options.today) < policy.minDaysOverdue) {
+            return {
+                invoice,
+                hold: { kind: "too-early", earliest: earliestReminderDate(invoice, policy), immediate: isDueImmediately(invoice) },
+            };
+        }
+        let record;
+        try {
+            record = await ledger.read(invoice.id);
+        }
+        catch (error) {
+            return { invoice, hold: { kind: "unreadable", reason: String(error) } };
+        }
+        if (record && !isOpenForReminder(record, policy, now)) {
+            return { invoice, hold: { kind: record.status, at: record.at, sessionId: record.sessionId } };
+        }
+        try {
+            const email = invoice.contactId ? await contactEmail(client, invoice.contactId, options.signal) : null;
+            return email ? { invoice, hold: null, email } : { invoice, hold: { kind: "no-address" } };
+        }
+        catch (error) {
+            return { invoice, hold: { kind: "unreadable", reason: String(error) } };
+        }
+    }));
+    return {
+        due: checked.flatMap(({ invoice, hold, email }) => (hold === null && email ? [{ invoice, customerEmail: email }] : [])),
+        held: checked.flatMap(({ invoice, hold }) => (hold ? [{ invoice, hold }] : [])),
+    };
+}
+/**
+ * Sends one reminder, at most once per round: re-checks that the invoice is
+ * still overdue, claims the round, renders and sends with the invoice PDF,
+ * and records it. Up to the mail call nothing has left, so a failure there
+ * frees the round; so does MailNotSentError. Any other failure while sending
+ * keeps the round taken.
+ */
+export async function sendReminder(client, ledger, target, options) {
+    const still = await findOverdueInvoice(client, target.invoiceId, options.signal);
+    if (!still)
+        return { sent: false, reason: "paid" };
+    const round = target.earlierSentAt ?? "first";
+    if (!(await ledger.claimSend(target.invoiceId, round, options.owner)))
+        return { sent: false, reason: "taken" };
+    const release = () => ledger.releaseSend(target.invoiceId, round).catch(() => { });
+    let mail;
+    try {
+        const pdf = await downloadInvoicePdf(client, { id: target.invoiceId, voucherNumber: target.voucherNumber }, options.signal);
+        const rendered = await options.render({
+            voucherNumber: target.voucherNumber,
+            voucherDate: target.voucherDate,
+            dueDate: target.dueDate,
+            openAmount: still.openAmount,
+            currency: target.currency,
+            testRecipientFor: target.test ? (target.customer ?? "den Kunden (keine Adresse hinterlegt)") : undefined,
+        });
+        mail = { to: target.to, cc: target.cc ?? [], ...rendered, attachments: [pdf] };
+    }
+    catch (error) {
+        await release();
+        throw error;
+    }
+    try {
+        await options.sendMail(mail, options.signal);
+    }
+    catch (error) {
+        if (error instanceof MailNotSentError)
+            await release();
+        throw error;
+    }
+    // The mail is out; the claim alone already keeps a second one away.
+    await ledger
+        .write({
+        invoiceId: target.invoiceId,
+        voucherNumber: target.voucherNumber,
+        status: "sent",
+        recipient: target.to,
+        ...(options.sessionId ? { sessionId: options.sessionId } : {}),
+    })
+        .catch(() => { });
+    return { sent: true, openAmount: still.openAmount, attachment: mail.attachments[0].filename };
+}