@kevludwig/eve-lexware-office 0.1.0

package/dist/extension/lib/findings.mjs

@@ -0,0 +1,176 @@
+import { fileURLToPath as __eveFileURLToPath } from "node:url";
+import { dirname as __eveDirname } from "node:path";
+import { createRequire as __eveCreateRequire } from "node:module";
+const __filename = __eveFileURLToPath(import.meta.url);
+__eveDirname(__filename);
+__eveCreateRequire(import.meta.url);
+import { eur, shortDate } from "./format.mjs";
+import { round2 } from "@kevludwig/lexware-office";
+import { defineState } from "eve/context";
+const warnings = defineState("warnings", () => ({}));
+const rejected = defineState("rejected-signatures", () => ({}));
+function saveWarnings(callId, list) {
+	try {
+		warnings.update((all) => ({
+			...all,
+			[callId]: list
+		}));
+	} catch (error) {
+		console.warn(`[lexware] Cannot store findings: ${String(error)}`);
+	}
+}
+function warningsOf(callId) {
+	try {
+		return warnings.get()[callId] ?? [];
+	} catch {
+		return [];
+	}
+}
+function findingsOf(callId) {
+	return warningsOf(callId).map(describeWarning);
+}
+function notesOf(callId) {
+	return findingsOf(callId).map((finding) => `${finding.title}: ${finding.value}`);
+}
+function wasShownOnCard(callId, url) {
+	return warningsOf(callId).some((warning) => (warning.kind === "sales-duplicate" || warning.kind === "voucher-duplicate") && warning.url === url);
+}
+function isCorrectable(warning) {
+	return warning.kind === "voucher-total-mismatch" || warning.kind === "category-ambiguous" || warning.kind === "category-no-history" || warning.kind === "category-split" || warning.kind === "category-deviation";
+}
+function wasRejected(signature) {
+	try {
+		return rejected.get()[signature] === true;
+	} catch {
+		return false;
+	}
+}
+function rememberRejection(signature) {
+	try {
+		rejected.update((all) => ({
+			...all,
+			[signature]: true
+		}));
+	} catch {}
+}
+const amountIn = (value, currency) => eur(value, currency);
+function describeWarning(warning) {
+	switch (warning.kind) {
+		case "note": return {
+			title: warning.title,
+			value: warning.value
+		};
+		case "sales-duplicate": return {
+			title: "⚠ Dublette",
+			value: `${warning.documentLabel} mit gleicher Positionssumme existiert bereits` + (warning.voucherNumber ? ` (${warning.voucherNumber}` : " (") + (warning.voucherDate ? `, ${shortDate(warning.voucherDate)}` : "") + (warning.voucherStatus ? `, ${warning.voucherStatus}` : "") + `): ${warning.url}`
+		};
+		case "sales-duplicate-check-failed": return {
+			title: "⚠ Dublettenprüfung",
+			value: `fehlgeschlagen — ${warning.reason}`
+		};
+		case "duplicate-check-incomplete": return {
+			title: "⚠ Dublettenprüfung",
+			value: `unvollständig — ${warning.reason}`
+		};
+		case "sales-contact": return {
+			title: "⚠ Kunde",
+			value: warning.reason
+		};
+		case "customer-resolved": return {
+			title: "Kunde",
+			value: warning.number !== void 0 ? `${warning.name} (Nr. ${warning.number})` : warning.name
+		};
+		case "source-resolved": return {
+			title: "Bezugsbeleg",
+			value: warning.contactName ? `${warning.sourceLabel} (${warning.contactName})` : warning.sourceLabel
+		};
+		case "source-mismatch": return {
+			title: "⚠ Bezugsbeleg",
+			value: `Positionen ergeben ${eur(warning.itemsNet)}, ${warning.sourceLabel} hat ${eur(warning.sourceNet)} (Differenz ${eur(warning.difference)}) — Abweichung kann gewollt sein (geänderte Positionen)`
+		};
+		case "source-discount": {
+			const parts = [warning.discountAbsolute ? eur(warning.discountAbsolute) : null, warning.discountPercentage ? `${warning.discountPercentage} %` : null].filter(Boolean);
+			return {
+				title: "⚠ Rabatt im Bezugsbeleg",
+				value: `${warning.sourceLabel} enthält einen Gesamtrabatt (${parts.join(" / ")})` + (warning.sourceNet !== void 0 ? `, End-Netto ${eur(warning.sourceNet)}` : "") + " — der neue Beleg übernimmt ihn NICHT; ohne eigenen Rabatt entsteht er zum vollen Preis"
+			};
+		}
+		case "source-check-failed": return {
+			title: "⚠ Bezugsbeleg",
+			value: `nicht prüfbar — ${warning.reason}`
+		};
+		case "voucher-total-mismatch": return {
+			title: "⚠ Summenabgleich",
+			value: `Steuergruppen ergeben ${amountIn(warning.computed, warning.currency)} brutto, angegeben ist ${amountIn(warning.expected, warning.currency)} (Differenz ${amountIn(warning.difference, warning.currency)})`
+		};
+		case "voucher-reverse-charge": {
+			const booking = `${warning.categories.join(", ")}: gebucht mit ${warning.rate} % ohne Steuerbetrag — die Umsatzsteuer schuldest du selbst und ziehst sie als Vorsteuer wieder ab`;
+			return warning.invoiceChargesTax ? {
+				title: "⚠ Reverse Charge",
+				value: `${booking}. Die Rechnung weist aber Umsatzsteuer aus — Kategorie oder Rechnung prüfen`
+			} : {
+				title: "Reverse Charge",
+				value: booking
+			};
+		}
+		case "voucher-foreign-currency": {
+			const rate = warning.rate.toLocaleString("de-DE", {
+				minimumFractionDigits: 4,
+				maximumFractionDigits: 4
+			});
+			const conversion = `${amountIn(warning.original, warning.currency)} laut Rechnung, gebucht mit ${eur(warning.booked)} laut Kontoauszug (1 ${warning.currency} = ${rate} EUR)`;
+			return round2(warning.booked) === round2(warning.original) ? {
+				title: "⚠ Fremdwährung",
+				value: `${conversion} — Kurs 1:1, vermutlich nicht umgerechnet`
+			} : {
+				title: "Fremdwährung",
+				value: conversion
+			};
+		}
+		case "voucher-duplicate": return {
+			title: "⚠ Dublette",
+			value: `Rechnung ${warning.voucherNumber} ist bereits als Eingangsbeleg erfasst` + (warning.contactName ? ` (${warning.contactName}` : " (") + (warning.voucherDate ? `, ${shortDate(warning.voucherDate)}` : "") + (warning.voucherStatus ? `, ${warning.voucherStatus}` : "") + `): ${warning.url}`
+		};
+		case "voucher-duplicate-check-failed": return {
+			title: "⚠ Dublettenprüfung",
+			value: `fehlgeschlagen — ${warning.reason}`
+		};
+		case "voucher-category-missing": return {
+			title: "⚠ Buchungskategorie",
+			value: warning.reason
+		};
+		case "voucher-attachment-missing": return {
+			title: "⚠ Anhang",
+			value: warning.reason
+		};
+		case "voucher-contact-fallback": return {
+			title: "⚠ Lieferant",
+			value: warning.reason
+		};
+		case "voucher-contact-explicit": return {
+			title: "⚠ Kontakt",
+			value: `Beleg geht per contact_id an „${warning.contactName}" (${warning.contactId}) — auf der Rechnung steht „${warning.extractedName}"`
+		};
+		case "category-history": return {
+			title: "Buchungskategorie",
+			value: `${warning.name} (${warning.basis})`
+		};
+		case "category-ambiguous": return {
+			title: "⚠ Buchungskategorie",
+			value: `dieser Lieferant wurde bisher auf mehrere Kategorien gebucht (${warning.candidates.join(", ")}) — wähle anhand des Dokumentinhalts eine davon und übergib sie als category; ist der Inhalt nicht eindeutig, frage den Nutzer. Ohne Wahl wird der Beleg ohne Kategorie erfasst`
+		};
+		case "category-no-history": return {
+			title: "⚠ Buchungskategorie",
+			value: "keine gebuchten Belege dieses Lieferanten als Vorlage — sieh mit dem Lese-Tool unter /posting-categories nach, wähle eine fachlich passende Kategorie und übergib sie als category; bei Unsicherheit frage den Nutzer. Ohne Wahl wird der Beleg ohne Kategorie erfasst"
+		};
+		case "category-split": return {
+			title: "⚠ Buchungskategorie",
+			value: `gebuchte Belege dieses Lieferanten sind innerhalb eines Belegs auf mehrere Kategorien aufgeteilt (${warning.candidates.join(", ")}) — eine Einzelwahl wäre falsch. Teile den Beleg anhand des Dokumentinhalts auf: eine tax_group je Kategorie (auch bei gleichem Steuersatz), jeweils mit category. Ist die Aufteilung nicht ableitbar, frage den Nutzer; ohne Aufteilung wird der Beleg ohne Kategorie erfasst`
+		};
+		case "category-deviation": return {
+			title: "⚠ Buchungskategorie",
+			value: `„${warning.chosen}" weicht von der bisher üblichen Kategorie dieses Lieferanten ab („${warning.usual}")`
+		};
+	}
+}
+export { describeWarning, findingsOf, isCorrectable, notesOf, rememberRejection, saveWarnings, warningsOf, wasRejected, wasShownOnCard };

package/dist/extension/lib/format.d.ts

@@ -0,0 +1,3 @@
+/** How amounts and dates read on cards and in answers: „761,60 EUR", „1.9.2026". */
+export declare function eur(value: number, currency?: string): string;
+export declare function shortDate(value: string): string;

package/dist/extension/lib/format.mjs

@@ -0,0 +1,16 @@
+import { fileURLToPath as __eveFileURLToPath } from "node:url";
+import { dirname as __eveDirname } from "node:path";
+import { createRequire as __eveCreateRequire } from "node:module";
+const __filename = __eveFileURLToPath(import.meta.url);
+__eveDirname(__filename);
+__eveCreateRequire(import.meta.url);
+function eur(value, currency = "EUR") {
+	return `${value.toLocaleString("de-DE", {
+		minimumFractionDigits: 2,
+		maximumFractionDigits: 2
+	})} ${currency}`;
+}
+function shortDate(value) {
+	return new Date(/^\d{4}-\d{2}-\d{2}$/.test(value) ? `${value}T12:00:00Z` : value).toLocaleDateString("de-DE", { timeZone: "Europe/Berlin" });
+}
+export { eur, shortDate };

package/dist/extension/lib/journal.d.ts

@@ -0,0 +1,15 @@
+/**
+ * Idempotency journal, per tool call. Tools run as durable steps and may run
+ * again after a crash — even after a successful write, if the step's commit
+ * was lost. `pending` before the write, `created` after it: a replay finds
+ * the entry and does not write twice.
+ *
+ * Never throws: an unwritable journal must not block an approved action.
+ */
+export interface JournalEntry {
+    status: "pending" | "created" | "attached";
+    resourceId?: string;
+    at: string;
+}
+export declare function readJournal(kind: string, callId: string): Promise<JournalEntry | null>;
+export declare function writeJournal(kind: string, callId: string, entry: Omit<JournalEntry, "at">): Promise<void>;

package/dist/extension/lib/journal.mjs

@@ -0,0 +1,27 @@
+import { fileURLToPath as __eveFileURLToPath } from "node:url";
+import { dirname as __eveDirname } from "node:path";
+import { createRequire as __eveCreateRequire } from "node:module";
+const __filename = __eveFileURLToPath(import.meta.url);
+__eveDirname(__filename);
+__eveCreateRequire(import.meta.url);
+import { key, store } from "./runtime.mjs";
+async function readJournal(kind, callId) {
+	try {
+		const entry = await store().read(key("journal", kind, callId));
+		return entry && typeof entry.status === "string" ? entry : null;
+	} catch (error) {
+		console.warn(`[lexware] Cannot read journal ${kind}/${callId}: ${String(error)}`);
+		return null;
+	}
+}
+async function writeJournal(kind, callId, entry) {
+	try {
+		await store().write(key("journal", kind, callId), {
+			...entry,
+			at: new Date().toISOString()
+		});
+	} catch (error) {
+		console.warn(`[lexware] Cannot write journal ${kind}/${callId}: ${String(error)}`);
+	}
+}
+export { readJournal, writeJournal };

package/dist/extension/lib/purchase-card.d.ts

@@ -0,0 +1,3 @@
+/** The purchase invoice on the approval card — from the tool input; the findings come from the checks. */
+import type { ApprovalCard } from "./types";
+export declare function purchaseCard(raw: Record<string, unknown>): Omit<ApprovalCard, "tool" | "findings">;

package/dist/extension/lib/purchase-card.mjs

@@ -0,0 +1,66 @@
+import { fileURLToPath as __eveFileURLToPath } from "node:url";
+import { dirname as __eveDirname } from "node:path";
+import { createRequire as __eveCreateRequire } from "node:module";
+const __filename = __eveFileURLToPath(import.meta.url);
+__eveDirname(__filename);
+__eveCreateRequire(import.meta.url);
+import { eur } from "./format.mjs";
+import { bookedGroupsOf, invoiceCurrencyOf, isForeignCurrency, totalsOf } from "./purchase.mjs";
+const basename = (path) => path.split("/").pop() || path;
+function purchaseCard(raw) {
+	const input = raw;
+	const groups = bookedGroupsOf(input);
+	const totals = totalsOf(groups);
+	const currency = invoiceCurrencyOf(input);
+	const invoiceGross = totalsOf(input.tax_groups).gross;
+	const supplier = input.supplier_name?.trim() || "unbekannter Lieferant";
+	const number = input.voucher_number?.trim() || "ohne Nummer";
+	const facts = [{
+		title: "Lieferant",
+		value: supplier
+	}, {
+		title: "Rechnungsnummer",
+		value: number
+	}];
+	if (input.voucher_date) facts.push({
+		title: "Belegdatum",
+		value: input.voucher_date
+	});
+	if (groups.length > 0) {
+		facts.push({
+			title: "Brutto",
+			value: eur(totals.gross)
+		});
+		facts.push({
+			title: "davon USt.",
+			value: `${eur(totals.tax)} (${groups.map((group) => `${eur(group.gross_amount ?? 0)} zu ${group.tax_rate_percent ?? 0} %`).join(", ")})`
+		});
+		facts.push({
+			title: "Netto",
+			value: eur(totals.net)
+		});
+	}
+	if (typeof input.total_gross_amount === "number") {
+		const difference = Math.round((invoiceGross - input.total_gross_amount) * 100) / 100;
+		facts.push({
+			title: "Rechnungsendbetrag",
+			value: difference === 0 ? `${eur(input.total_gross_amount, currency)} — passt` : `${eur(input.total_gross_amount, currency)} — Abweichung ${eur(difference, currency)}`
+		});
+	}
+	const groupCategories = groups.map((group) => group.category?.trim()).filter((name) => Boolean(name));
+	facts.push({
+		title: "Buchungskategorie",
+		value: groupCategories.length > 0 ? groupCategories.map((name, index) => `${name} (${eur(groups[index]?.gross_amount ?? 0)})`).join(", ") : input.category?.trim() || "automatisch nach Lieferanten-Historie — siehe Befunde"
+	});
+	facts.push({
+		title: "Original",
+		value: input.attachment_path ? basename(input.attachment_path) : "kein Anhang"
+	});
+	return {
+		title: "Eingangsrechnung erfassen?",
+		subtitle: `${supplier} · Rechnung ${number} · ${eur(totals.gross)} brutto` + (isForeignCurrency(input) ? ` (${eur(invoiceGross, currency)})` : ""),
+		facts,
+		note: "Wird als Beleg zur Prüfung angelegt und in Lexware Office noch bestätigt."
+	};
+}
+export { purchaseCard };

package/dist/extension/lib/purchase.d.ts

@@ -0,0 +1,112 @@
+/**
+ * The purchase invoice: foreign currency, supplier, posting category, and the
+ * checks before the card.
+ *
+ * Lexware Office books in EUR. For an invoice in another currency the right
+ * amount is the one actually debited — fees and the bank's rate included —
+ * so the user supplies it from the bank statement and the conversion happens
+ * here, deterministically; the totals check stays in the invoice currency.
+ */
+import { type PostingCategory } from "@kevludwig/lexware-office";
+import type { Warning } from "./findings";
+export declare const BOOKING_CURRENCY = "EUR";
+export interface TaxGroupInput {
+    gross_amount?: number;
+    tax_rate_percent?: number;
+    /** Category of this group — only for a voucher split across categories. */
+    category?: string;
+}
+export interface PurchaseInput {
+    supplier_name?: string;
+    voucher_number?: string;
+    voucher_date?: string;
+    due_date?: string;
+    currency?: string;
+    bank_statement_eur_amount?: number;
+    total_gross_amount?: number;
+    tax_groups?: readonly TaxGroupInput[];
+    category?: string;
+    contact_id?: string;
+    remark?: string;
+    attachment_path?: string;
+}
+export declare const MISSING_EUR_AMOUNT_INSTRUCTION: string;
+export declare const invoiceCurrencyOf: (input: PurchaseInput) => string;
+export declare const isForeignCurrency: (input: PurchaseInput) => boolean;
+export declare const lacksEurAmount: (input: PurchaseInput) => boolean;
+/**
+ * The tax groups as they are booked: in EUR. A foreign invoice's groups are
+ * scaled to the debited amount; the last group takes the rounding remainder,
+ * so the groups meet the bank line to the cent.
+ */
+export declare function bookedGroupsOf<G extends TaxGroupInput>(input: PurchaseInput & {
+    tax_groups?: readonly G[];
+}): G[];
+/** EUR per unit of the invoice currency, implied by the debit — shown on the card. Null for EUR. */
+export declare function impliedRateOf(input: PurchaseInput): number | null;
+export declare function totalsOf(groups?: readonly TaxGroupInput[]): {
+    gross: number;
+    tax: number;
+    net: number;
+};
+export declare const isAllowedAttachmentPath: (path: string) => boolean;
+export interface SupplierTarget {
+    contactId?: string;
+    /** The name on the voucher — also for the collective vendor. */
+    contactName: string;
+    warnings: Warning[];
+}
+/**
+ * The vendor contact for the name on the invoice. The collective vendor is
+ * the fallback — and always a finding, so a voucher never lands there
+ * silently. A passed contact_id is verified, and the card carries the
+ * contact's real name.
+ */
+export declare function resolveSupplier(input: PurchaseInput, signal?: AbortSignal): Promise<SupplierTarget>;
+/** Supplier and categories the card showed, bound to the call — execute writes exactly that. */
+export interface ApprovedPurchaseTarget {
+    contactId?: string;
+    contactName: string;
+    categoryId?: string;
+    categoryName?: string;
+    /** Per-group categories of a split voucher, aligned with tax_groups. */
+    groupCategories?: Array<{
+        id?: string;
+        name?: string;
+    }>;
+}
+export declare function rememberPurchaseTarget(callId: string, target: ApprovedPurchaseTarget): void;
+export declare function approvedPurchaseTarget(callId: string): ApprovedPurchaseTarget | null;
+/** One concrete capture — same numbers and same category choice: each new choice runs the correction cycle once. */
+export declare function purchaseSignatureOf(input: PurchaseInput): string;
+/**
+ * Totals, currency, supplier, category, reverse charge, duplicate, and
+ * attachment. Network errors become findings. Returns supplier and category
+ * too, so the approval can bind them to the call.
+ */
+export declare function runPurchasePreflight(input: PurchaseInput, options?: {
+    signal?: AbortSignal;
+    readFileSize?: (path: string) => Promise<number | null>;
+}): Promise<{
+    warnings: Warning[];
+    supplier: SupplierTarget;
+    category: PostingCategory | null;
+    groupCategories: Array<PostingCategory | null> | null;
+}>;
+/** Per-group categories when a group names one, otherwise the single pick. */
+export declare function resolveCategories(input: PurchaseInput, contactId: string | undefined, signal?: AbortSignal): Promise<{
+    category: PostingCategory | null;
+    groupCategories: Array<PostingCategory | null> | null;
+    warnings: Warning[];
+}>;
+/**
+ * The posting category, in this order: the one the call names (checked
+ * against the account, a deviation from the vendor's usual one is a finding);
+ * the vendor's history — one category is taken over, several are for the
+ * model to choose from; no history — the model looks one up or asks. A
+ * vendor whose vouchers are split within one voucher gets no single pick.
+ */
+export declare function pickCategory(input: PurchaseInput, contactId: string | undefined, signal?: AbortSignal): Promise<{
+    category: PostingCategory | null;
+    warnings: Warning[];
+}>;