@kevludwig/eve-lexware-office 0.1.0

package/dist/extension/lib/purchase.mjs

@@ -0,0 +1,346 @@
+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 { client } from "./runtime.mjs";
+import { ITEMS_TOTAL_TOLERANCE, REVERSE_CHARGE_TAX_RATE, describeError, findPurchaseInvoiceByNumber, findVendorCategoryHistory, getContact, isReverseChargeCategory, resolveCategory, resolveContactByName, round2, taxFromGross } from "@kevludwig/lexware-office";
+import { defineState } from "eve/context";
+const BOOKING_CURRENCY = "EUR";
+const MISSING_EUR_AMOUNT_INSTRUCTION = "Die Rechnung ist nicht in EUR. Lexware Office bucht in EUR, maßgeblich ist der tatsächlich abgebuchte Betrag. Frage den Nutzer (Freitext) nach dem EUR-Betrag laut Kontoauszug — nicht selbst umrechnen, keinen Kurs schätzen — und rufe das Tool dann mit bank_statement_eur_amount erneut auf. Beträge und tax_groups bleiben in Rechnungswährung.";
+const invoiceCurrencyOf = (input) => input.currency?.trim().toUpperCase() || "EUR";
+const isForeignCurrency = (input) => invoiceCurrencyOf(input) !== "EUR";
+const lacksEurAmount = (input) => isForeignCurrency(input) && !(typeof input.bank_statement_eur_amount === "number" && input.bank_statement_eur_amount > 0);
+function bookedGroupsOf(input) {
+	const groups = [...input.tax_groups ?? []];
+	if (!isForeignCurrency(input) || lacksEurAmount(input)) return groups;
+	const target = round2(input.bank_statement_eur_amount);
+	const original = groups.reduce((sum, group) => sum + (group.gross_amount ?? 0), 0);
+	if (original <= 0) return groups;
+	let assigned = 0;
+	return groups.map((group, index) => {
+		const amount = index === groups.length - 1 ? round2(target - assigned) : round2((group.gross_amount ?? 0) * target / original);
+		assigned = round2(assigned + amount);
+		return {
+			...group,
+			gross_amount: amount
+		};
+	});
+}
+function impliedRateOf(input) {
+	if (!isForeignCurrency(input) || lacksEurAmount(input)) return null;
+	const original = (input.tax_groups ?? []).reduce((sum, group) => sum + (group.gross_amount ?? 0), 0);
+	return original > 0 ? input.bank_statement_eur_amount / original : null;
+}
+function totalsOf(groups = []) {
+	let gross = 0;
+	let tax = 0;
+	for (const group of groups) {
+		gross += group.gross_amount ?? 0;
+		tax += taxFromGross(group.gross_amount ?? 0, group.tax_rate_percent ?? 0);
+	}
+	return {
+		gross: round2(gross),
+		tax: round2(tax),
+		net: round2(gross - tax)
+	};
+}
+const ATTACHMENT_PATH = /^\/workspace\/attachments\/[0-9a-f]{8,64}\/[\w.-]+$/;
+const isAllowedAttachmentPath = (path) => ATTACHMENT_PATH.test(path);
+async function resolveSupplier(input, signal) {
+	const name = input.supplier_name?.trim() || "unbekannter Lieferant";
+	const fallback = (reason) => ({
+		contactName: name,
+		warnings: [{
+			kind: "voucher-contact-fallback",
+			reason
+		}]
+	});
+	if (input.contact_id) try {
+		const contact = await getContact(client(), input.contact_id, signal);
+		if (!contact.isVendor) return fallback(`contact_id ${input.contact_id} („${contact.name}") ist kein Lieferantenkontakt — der Beleg geht an den Sammellieferanten`);
+		return {
+			contactId: contact.id,
+			contactName: contact.name,
+			warnings: contact.name.toLowerCase() === name.toLowerCase() ? [] : [{
+				kind: "voucher-contact-explicit",
+				contactName: contact.name,
+				contactId: contact.id,
+				extractedName: name
+			}]
+		};
+	} catch (error) {
+		return fallback(`contact_id ${input.contact_id} ließ sich nicht verifizieren (${describeError(error)}) — der Beleg geht an den Sammellieferanten`);
+	}
+	try {
+		const { match, candidates } = await resolveContactByName(client(), name, {
+			vendor: true,
+			signal
+		});
+		if (match) return {
+			contactId: match.id,
+			contactName: match.name,
+			warnings: []
+		};
+		if (candidates.length > 1) return fallback(`„${name}" passt auf ${candidates.length} Lieferantenkontakte (${candidates.map((contact) => contact.name).join(", ")}) — der Beleg geht an den Sammellieferanten. Mit contact_id lässt sich einer davon festlegen.`);
+		return fallback(`kein Lieferantenkontakt „${name}" — der Beleg geht an den Sammellieferanten`);
+	} catch (error) {
+		return fallback(`Kontaktsuche fehlgeschlagen (${describeError(error)}) — der Beleg geht an den Sammellieferanten`);
+	}
+}
+const approvedTargets = defineState("purchase-targets", () => ({}));
+function rememberPurchaseTarget(callId, target) {
+	try {
+		approvedTargets.update((all) => ({
+			...all,
+			[callId]: target
+		}));
+	} catch (error) {
+		console.warn(`[lexware] Cannot bind purchase target: ${String(error)}`);
+	}
+}
+function approvedPurchaseTarget(callId) {
+	try {
+		return approvedTargets.get()[callId] ?? null;
+	} catch {
+		return null;
+	}
+}
+function purchaseSignatureOf(input) {
+	const groups = input.tax_groups ?? [];
+	return [
+		"voucher",
+		input.voucher_number?.trim() ?? "-",
+		input.voucher_date ?? "-",
+		invoiceCurrencyOf(input),
+		(input.bank_statement_eur_amount ?? 0).toFixed(2),
+		(input.total_gross_amount ?? 0).toFixed(2),
+		groups.length,
+		totalsOf(groups).gross.toFixed(2),
+		input.category?.trim().toLowerCase() ?? "-",
+		groups.map((group) => group.category?.trim().toLowerCase() ?? "").join(",")
+	].join("|");
+}
+async function runPurchasePreflight(input, options = {}) {
+	const warnings = [];
+	const groups = input.tax_groups ?? [];
+	if (groups.length > 0 && typeof input.total_gross_amount === "number") {
+		const computed = totalsOf(groups).gross;
+		const difference = round2(computed - input.total_gross_amount);
+		if (Math.abs(difference) > ITEMS_TOTAL_TOLERANCE) warnings.push({
+			kind: "voucher-total-mismatch",
+			computed,
+			expected: input.total_gross_amount,
+			difference,
+			currency: invoiceCurrencyOf(input)
+		});
+	}
+	const rate = impliedRateOf(input);
+	if (rate !== null) warnings.push({
+		kind: "voucher-foreign-currency",
+		currency: invoiceCurrencyOf(input),
+		original: totalsOf(groups).gross,
+		booked: round2(input.bank_statement_eur_amount),
+		rate
+	});
+	const supplier = await resolveSupplier(input, options.signal);
+	warnings.push(...supplier.warnings);
+	const picked = await resolveCategories(input, supplier.contactId, options.signal);
+	warnings.push(...picked.warnings);
+	warnings.push(...reverseChargeFindings(groups, picked));
+	warnings.push(...await checkDuplicate(input, options.signal));
+	warnings.push(...await checkAttachment(input, options.readFileSize));
+	return {
+		warnings,
+		supplier,
+		category: picked.category,
+		groupCategories: picked.groupCategories
+	};
+}
+function reverseChargeFindings(groups, picked) {
+	const nameOf = (index) => picked.groupCategories ? picked.groupCategories[index]?.name : picked.category?.name;
+	const affected = groups.map((group, index) => ({
+		group,
+		name: nameOf(index)
+	})).filter((entry) => isReverseChargeCategory(entry.name));
+	if (affected.length === 0) return [];
+	return [{
+		kind: "voucher-reverse-charge",
+		categories: [...new Set(affected.map((entry) => entry.name))],
+		rate: REVERSE_CHARGE_TAX_RATE,
+		invoiceChargesTax: affected.some((entry) => (entry.group.tax_rate_percent ?? 0) > 0)
+	}];
+}
+async function resolveCategories(input, contactId, signal) {
+	const groups = input.tax_groups ?? [];
+	if (!groups.some((group) => group.category?.trim())) return {
+		...await pickCategory(input, contactId, signal),
+		groupCategories: null
+	};
+	const warnings = [];
+	const resolved = [];
+	for (const [index, group] of groups.entries()) {
+		const name = group.category?.trim();
+		if (!name) {
+			resolved.push(null);
+			continue;
+		}
+		try {
+			const match = await resolveCategory(client(), name, "outgo", signal);
+			if (!match) warnings.push({
+				kind: "voucher-category-missing",
+				reason: `„${name}" (Gruppe ${index + 1}) ist keine Ausgabenkategorie dieses Kontos — Name wörtlich aus /posting-categories übernehmen; die Gruppe wird sonst ohne Kategorie erfasst`
+			});
+			resolved.push(match);
+		} catch (error) {
+			warnings.push({
+				kind: "voucher-category-missing",
+				reason: `Kategorien nicht abrufbar (${describeError(error)}) — Gruppe ${index + 1} wird ohne Kategorie erfasst`
+			});
+			resolved.push(null);
+		}
+	}
+	return {
+		category: null,
+		groupCategories: resolved,
+		warnings
+	};
+}
+async function pickCategory(input, contactId, signal) {
+	const requested = input.category?.trim();
+	const warnings = [];
+	let history = null;
+	let historyError = null;
+	if (contactId) try {
+		history = await findVendorCategoryHistory(client(), contactId, { signal });
+	} catch (error) {
+		historyError = describeError(error);
+	}
+	try {
+		if (requested) {
+			const match = await resolveCategory(client(), requested, "outgo", signal);
+			if (match) {
+				if (history?.split) warnings.push({
+					kind: "category-split",
+					candidates: history.categories.map((category) => category.name)
+				});
+				const usual = history?.categories ?? [];
+				if (usual.length > 0 && !usual.some((category) => category.id === match.id)) warnings.push({
+					kind: "category-deviation",
+					chosen: match.name,
+					usual: usual.map((category) => category.name).join(", ")
+				});
+				return {
+					category: match,
+					warnings
+				};
+			}
+			warnings.push({
+				kind: "voucher-category-missing",
+				reason: `„${requested}" ist keine Ausgabenkategorie dieses Kontos — Name wörtlich aus /posting-categories übernehmen`
+			});
+		}
+		if (history) {
+			if (history.split) {
+				warnings.push({
+					kind: "category-split",
+					candidates: history.categories.map((category) => category.name)
+				});
+				return {
+					category: null,
+					warnings
+				};
+			}
+			if (history.categories.length === 1) {
+				const match = await resolveCategory(client(), history.categories[0].id, "outgo", signal);
+				if (match) {
+					warnings.push({
+						kind: "category-history",
+						name: match.name,
+						basis: `wie die ${history.scanned === 1 ? "letzte gebuchte Rechnung" : `letzten ${history.scanned} gebuchten Rechnungen`} dieses Lieferanten` + (history.incomplete ? " (ältere ungeprüft)" : "")
+					});
+					return {
+						category: match,
+						warnings
+					};
+				}
+			}
+			if (history.categories.length > 1) {
+				warnings.push({
+					kind: "category-ambiguous",
+					candidates: history.categories.map((category) => category.name)
+				});
+				return {
+					category: null,
+					warnings
+				};
+			}
+		}
+		if (historyError) {
+			warnings.push({
+				kind: "voucher-category-missing",
+				reason: `Lieferanten-Historie nicht abrufbar (${historyError}) — der Beleg wird ohne Kategorie erfasst`
+			});
+			return {
+				category: null,
+				warnings
+			};
+		}
+		warnings.push({ kind: "category-no-history" });
+		return {
+			category: null,
+			warnings
+		};
+	} catch (error) {
+		warnings.push({
+			kind: "voucher-category-missing",
+			reason: `Kategorien nicht abrufbar (${describeError(error)}) — der Beleg wird ohne Kategorie erfasst`
+		});
+		return {
+			category: null,
+			warnings
+		};
+	}
+}
+async function checkDuplicate(input, signal) {
+	const number = input.voucher_number?.trim();
+	if (!number) return [];
+	try {
+		const existing = await findPurchaseInvoiceByNumber(client(), number, signal);
+		return existing ? [{
+			kind: "voucher-duplicate",
+			url: existing.url,
+			voucherNumber: existing.voucherNumber ?? number,
+			voucherDate: existing.voucherDate,
+			voucherStatus: existing.voucherStatus,
+			contactName: existing.contactName
+		}] : [];
+	} catch (error) {
+		return [{
+			kind: "voucher-duplicate-check-failed",
+			reason: describeError(error)
+		}];
+	}
+}
+async function checkAttachment(input, readFileSize) {
+	const path = input.attachment_path?.trim();
+	if (!path) return [];
+	if (!isAllowedAttachmentPath(path)) return [{
+		kind: "voucher-attachment-missing",
+		reason: `„${path}" liegt nicht unter /workspace/attachments/ — es wird kein Original angehängt`
+	}];
+	if (!readFileSize) return [];
+	try {
+		return await readFileSize(path) === null ? [{
+			kind: "voucher-attachment-missing",
+			reason: `${path} existiert nicht — es wird kein Original angehängt`
+		}] : [];
+	} catch (error) {
+		return [{
+			kind: "voucher-attachment-missing",
+			reason: `${path} nicht lesbar (${describeError(error)})`
+		}];
+	}
+}
+export { BOOKING_CURRENCY, MISSING_EUR_AMOUNT_INSTRUCTION, approvedPurchaseTarget, bookedGroupsOf, impliedRateOf, invoiceCurrencyOf, isAllowedAttachmentPath, isForeignCurrency, lacksEurAmount, pickCategory, purchaseSignatureOf, rememberPurchaseTarget, resolveCategories, resolveSupplier, runPurchasePreflight, totalsOf };

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

@@ -0,0 +1,18 @@
+/**
+ * The mount's configuration turned into working parts — one API client (one
+ * rate-limit queue) and one store per mount, created on first use.
+ */
+import { type JsonStore, type LexwareClient, type ReminderLedger } from "@kevludwig/lexware-office";
+import type { ApprovalResponseContext, ApprovalResponseDecision } from "eve/tools/approval";
+import extension from "../extension";
+type Config = typeof extension.config;
+export declare const config: () => Config;
+export declare const client: () => LexwareClient;
+export declare const store: () => JsonStore;
+/** A key of this mount's own documents in the store, e.g. the journal. */
+export declare function key(...segments: string[]): string;
+export declare function ledger(): ReminderLedger;
+export declare function renderReminder(): import("@kevludwig/lexware-office").RenderReminderMail;
+/** The response policy of every writing tool: the mount's canApprove, if any. */
+export declare function approverPolicy<T>({ responder }: ApprovalResponseContext<T>): Promise<ApprovalResponseDecision>;
+export {};

package/dist/extension/lib/runtime.mjs

@@ -0,0 +1,47 @@
+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 extension_default from "../extension.mjs";
+import { createLexwareClient, defaultReminderMail, keySegment, reminderLedger } from "@kevludwig/lexware-office";
+import { vercelBlobStore } from "@kevludwig/lexware-office/vercel-blob";
+let cached;
+function parts() {
+	const config = extension_default.config;
+	if (cached?.config !== config) cached = {
+		config,
+		client: config.client ?? createLexwareClient({
+			apiKey: config.apiKey ?? "",
+			baseUrl: config.baseUrl,
+			appUrl: config.appUrl
+		}),
+		store: config.storage.store ?? vercelBlobStore({ prefix: config.storage.prefix })
+	};
+	return cached;
+}
+const config = () => extension_default.config;
+const client = () => parts().client;
+const store = () => parts().store;
+function key(...segments) {
+	return segments.map(keySegment).join("/");
+}
+function ledger() {
+	const reminders = config().reminders;
+	return reminderLedger(store(), reminders.namespace ?? `reminders/${reminders.mode}`);
+}
+function renderReminder() {
+	const reminders = config().reminders;
+	if (reminders.render) return reminders.render;
+	return defaultReminderMail(reminders.sender ?? { name: "Ihr Team" });
+}
+async function approverPolicy({ responder }) {
+	const canApprove = config().canApprove;
+	if (!canApprove || await canApprove(responder)) return { status: "allowed" };
+	return {
+		status: "rejected",
+		reason: "Nur berechtigte Personen dürfen freigeben."
+	};
+}
+export { approverPolicy, client, config, key, ledger, renderReminder, store };

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

@@ -0,0 +1,72 @@
+/**
+ * What quotation, order confirmation, and invoice share: the line-item
+ * schema, finding the customer, the checks before the card, and creating the
+ * document — so the three cannot drift apart.
+ *
+ * None of these findings can be fixed by the model: behind a chat order there
+ * is no document with a total to check against. They all go to the card.
+ */
+import { type Contact, type LineItem, type SalesDocumentKind } from "@kevludwig/lexware-office";
+import { z } from "zod";
+import { type Warning } from "./findings";
+export declare const DOCUMENT_LABEL: Record<SalesDocumentKind, string>;
+/** Amounts must be cent-exact — more digits are a reading artefact. */
+export declare function isCentExact(value: number): boolean;
+/** Lexware accepts at most 300 line items per document. */
+export declare const MAX_LINE_ITEMS = 300;
+export declare const lineItemSchema: z.ZodObject<{
+    name: z.ZodString;
+    quantity: z.ZodNumber;
+    unit: z.ZodString;
+    net_price: z.ZodNumber;
+    tax_rate: z.ZodUnion<readonly [z.ZodLiteral<0>, z.ZodLiteral<7>, z.ZodLiteral<19>]>;
+}, z.core.$strict>;
+export type LineItemInput = z.infer<typeof lineItemSchema>;
+export declare const toLineItems: (items?: readonly Partial<LineItemInput>[]) => LineItem[];
+export declare function isDocumentTypeLabel(title: string): boolean;
+/** Whether yyyy-MM-dd names a real day — the pattern alone accepts 2026-02-30. */
+export declare function isCalendarDate(value: string): boolean;
+/** Title as the API allows it: max. 25 characters (a longer one answers 406), and no document type. */
+export declare const titleSchema: (what: string) => z.ZodOptional<z.ZodString>;
+export declare const customerFields: {
+    customer_number: z.ZodOptional<z.ZodNumber>;
+    contact_id: z.ZodOptional<z.ZodString>;
+};
+export interface SalesInput {
+    customer_number?: number;
+    contact_id?: string;
+    items?: readonly Partial<LineItemInput>[];
+    title?: string;
+    valid_until?: string;
+    source_document_id?: string;
+    source_document_type?: SalesDocumentKind;
+}
+/**
+ * The customer behind a number or contact id. There is no collective customer:
+ * a document to the wrong contact is wrong, not slightly off — an unresolvable
+ * one is a warning on the card and an error when writing.
+ */
+export declare function resolveCustomer(input: SalesInput, signal?: AbortSignal): Promise<{
+    contact: Contact | null;
+    warnings: Warning[];
+}>;
+/** Customer, duplicates, and the source document — network errors become findings, not exceptions. */
+export declare function runSalesPreflight(kind: SalesDocumentKind, input: SalesInput, signal?: AbortSignal): Promise<Warning[]>;
+/** The approval policy of a sales tool: checks to state, then the card decides. */
+export declare function salesApproval(kind: SalesDocumentKind, normalize?: (input: SalesInput) => SalesInput): (ctx: {
+    toolInput?: unknown;
+    callId: string;
+    abortSignal?: AbortSignal;
+}) => Promise<"user-approval">;
+/** Default validity of a quotation when the user names none. */
+export declare const QUOTATION_VALIDITY_DAYS = 30;
+/**
+ * Creates the document: quotations and order confirmations finalized (they
+ * get their number now), invoices as drafts — finalized and sent in Lexware
+ * Office. A replay of the same call does not create twice; a document that
+ * appeared between card and click stops the write.
+ */
+export declare function executeSalesDocument(kind: SalesDocumentKind, input: SalesInput, ctx: {
+    callId: string;
+    abortSignal?: AbortSignal;
+}): Promise<Record<string, unknown>>;