@kevludwig/lexware-office 0.1.0

package/dist/sales-documents.d.ts

@@ -0,0 +1,120 @@
+/**
+ * Sales documents — quotation, order confirmation, invoice. All three share
+ * one payload shape; only the endpoint and a few optional fields differ.
+ */
+import { type LexwareClient } from "./client.ts";
+export type SalesDocumentKind = "quotation" | "order-confirmation" | "invoice";
+/** One line of a sales document. */
+export interface LineItem {
+    name: string;
+    quantity: number;
+    /** e.g. "Stück", "Stunde". */
+    unit: string;
+    /** Net unit price in EUR. */
+    netPrice: number;
+    /** 0, 7, or 19. */
+    taxRate: number;
+}
+/** The type as the voucher list spells it. */
+export declare const VOUCHERLIST_TYPE: Record<SalesDocumentKind, string>;
+/**
+ * The live statuses of each kind in the voucher list. `voided` is left out: a
+ * cancelled document is neither a duplicate nor a source to derive from.
+ */
+export declare const SALES_DOCUMENT_STATUSES: Record<SalesDocumentKind, string>;
+export interface CreatedSalesDocument {
+    id: string;
+    resourceUri?: string;
+    url: string;
+}
+/**
+ * Creates a sales document. `finalize` gives it a number right away — it can
+ * then no longer be deleted like a draft. Neither `introduction` nor `remark`
+ * is set: a value would replace the default texts of the account's settings.
+ *
+ * `precedingSalesVoucherId` links the document to its predecessor (a pursued
+ * quotation becomes accepted) — only as a query parameter; in the body the API
+ * drops it silently. The content is not copied: this payload alone decides
+ * the new document. An invalid pursue answers 406, see isPursueRejection.
+ */
+export declare function createSalesDocument(client: LexwareClient, options: {
+    kind: SalesDocumentKind;
+    contactId: string;
+    items: readonly LineItem[];
+    /** Replaces the printed heading; Lexware's default when absent. Max. 25 characters. */
+    title?: string;
+    /** Quotations: valid until, yyyy-MM-dd or a timestamp. */
+    expirationDate?: string;
+    finalize?: boolean;
+    /** Total discount in EUR on the net amount. */
+    totalDiscountAbsolute?: number;
+    precedingSalesVoucherId?: string;
+}, signal?: AbortSignal): Promise<CreatedSalesDocument>;
+/** Whether a 406 rejects the pursue, not the payload — then a retry without the link makes sense. */
+export declare function isPursueRejection(error: unknown): boolean;
+export interface SalesDocumentDetail {
+    id: string;
+    url: string;
+    voucherNumber?: string;
+    voucherStatus?: string;
+    contactId?: string;
+    contactName?: string;
+    /** Net total over the priced lines — NaN for a document without any. */
+    lineItemsNet: number;
+    lineItems: LineItem[];
+    /** The final net total — after a total discount. */
+    totalNet?: number;
+    /** A total discount is invisible in the lines. */
+    discountAbsolute?: number;
+    discountPercentage?: number;
+}
+/** A document reduced to the fields a comparison needs. Text lines (no price) are left out. */
+export declare function getSalesDocument(client: LexwareClient, kind: SalesDocumentKind, id: string, signal?: AbortSignal): Promise<SalesDocumentDetail>;
+/** Whether an invoice still exists. Only a 404 counts as gone — any other error answers true. */
+export declare function invoiceExists(client: LexwareClient, id: string, signal?: AbortSignal): Promise<boolean>;
+export interface SalesListEntry {
+    id: string;
+    url: string;
+    voucherNumber?: string;
+    voucherDate?: string;
+    voucherStatus?: string;
+    contactId?: string;
+    contactName?: string;
+    totalAmount?: number;
+}
+/** The most recent documents of a kind, newest first — how "the current quotation for X" is found. */
+export declare function findRecentSalesDocuments(client: LexwareClient, options: {
+    kind: SalesDocumentKind;
+    contactId?: string;
+    statuses?: string;
+    lookbackDays?: number;
+    size?: number;
+    signal?: AbortSignal;
+}): Promise<SalesListEntry[]>;
+/** A search that could not check everything must not read as "nothing found". */
+export type DuplicateSearchResult<T> = {
+    status: "match";
+    match: T;
+    scanned: number;
+} | {
+    status: "clear";
+    scanned: number;
+} | {
+    status: "incomplete";
+    scanned: number;
+    reason: string;
+};
+/**
+ * A same-kind document for this contact with the same line-item net total —
+ * heuristic (sales documents carry no external reference), so a finding for
+ * the approval, never an automatic refusal. Each candidate is fetched in
+ * detail, capped at `maxCandidates`.
+ */
+export declare function findDuplicateSalesDocument(client: LexwareClient, options: {
+    kind: SalesDocumentKind;
+    contactId: string;
+    itemsTotalNet: number;
+    lookbackDays?: number;
+    maxCandidates?: number;
+    signal?: AbortSignal;
+}): Promise<DuplicateSearchResult<SalesListEntry>>;

package/dist/sales-documents.js

@@ -0,0 +1,149 @@
+/**
+ * Sales documents — quotation, order confirmation, invoice. All three share
+ * one payload shape; only the endpoint and a few optional fields differ.
+ */
+import { LexwareApiError, query } from "./client.js";
+import { DUPLICATE_TOTAL_TOLERANCE, round2 } from "./money.js";
+const ENDPOINTS = {
+    quotation: "/quotations",
+    "order-confirmation": "/order-confirmations",
+    invoice: "/invoices",
+};
+/** The type as the voucher list spells it. */
+export const VOUCHERLIST_TYPE = {
+    quotation: "quotation",
+    "order-confirmation": "orderconfirmation",
+    invoice: "invoice",
+};
+/**
+ * The live statuses of each kind in the voucher list. `voided` is left out: a
+ * cancelled document is neither a duplicate nor a source to derive from.
+ */
+export const SALES_DOCUMENT_STATUSES = {
+    quotation: "draft,open,accepted,rejected",
+    "order-confirmation": "draft,open",
+    invoice: "draft,open,paid,paidoff",
+};
+/**
+ * Creates a sales document. `finalize` gives it a number right away — it can
+ * then no longer be deleted like a draft. Neither `introduction` nor `remark`
+ * is set: a value would replace the default texts of the account's settings.
+ *
+ * `precedingSalesVoucherId` links the document to its predecessor (a pursued
+ * quotation becomes accepted) — only as a query parameter; in the body the API
+ * drops it silently. The content is not copied: this payload alone decides
+ * the new document. An invalid pursue answers 406, see isPursueRejection.
+ */
+export async function createSalesDocument(client, options, signal) {
+    const voucherDate = new Date().toISOString().replace("Z", "+00:00");
+    const discount = options.totalDiscountAbsolute ?? 0;
+    const payload = {
+        voucherDate,
+        address: { contactId: options.contactId },
+        lineItems: options.items.map((item) => ({
+            type: "custom",
+            name: item.name,
+            quantity: item.quantity,
+            unitName: item.unit,
+            unitPrice: { currency: "EUR", netAmount: item.netPrice, taxRatePercentage: item.taxRate },
+        })),
+        totalPrice: { currency: "EUR", ...(discount > 0 ? { totalDiscountAbsolute: round2(discount) } : {}) },
+        taxConditions: { taxType: "net" },
+        shippingConditions: { shippingType: "delivery", shippingDate: voucherDate },
+        ...(options.title ? { title: options.title } : {}),
+        ...(options.expirationDate ? { expirationDate: toIsoDateTime(options.expirationDate) } : {}),
+    };
+    const params = query({ finalize: options.finalize ? true : undefined, precedingSalesVoucherId: options.precedingSalesVoucherId });
+    const result = await client.request(`${ENDPOINTS[options.kind]}${params}`, {
+        method: "POST",
+        json: payload,
+        signal,
+    });
+    return { id: result.id, resourceUri: result.resourceUri, url: client.voucherUrl(result.id) };
+}
+/** Whether a 406 rejects the pursue, not the payload — then a retry without the link makes sense. */
+export function isPursueRejection(error) {
+    return error instanceof LexwareApiError && error.status === 406 && /preceding|pursue/i.test(error.responseBody);
+}
+/** yyyy-MM-dd as a timestamp at midnight in Berlin — the API expects datetimes. */
+function toIsoDateTime(date) {
+    if (!/^\d{4}-\d{2}-\d{2}$/.test(date))
+        return date;
+    const offset = /GMT([+-]\d{2}:\d{2})/.exec(new Intl.DateTimeFormat("en-US", { timeZone: "Europe/Berlin", timeZoneName: "longOffset" }).format(new Date(`${date}T12:00:00Z`)))?.[1] ?? "+01:00";
+    return `${date}T00:00:00.000${offset}`;
+}
+/** A document reduced to the fields a comparison needs. Text lines (no price) are left out. */
+export async function getSalesDocument(client, kind, id, signal) {
+    const raw = await client.request(`${ENDPOINTS[kind]}/${encodeURIComponent(id)}`, { signal });
+    const items = (raw.lineItems ?? [])
+        .filter((item) => item.unitPrice !== undefined)
+        .map((item) => ({
+        name: item.name ?? "",
+        quantity: item.quantity ?? 0,
+        unit: item.unitName ?? "Stück",
+        netPrice: item.unitPrice?.netAmount ?? 0,
+        taxRate: item.unitPrice?.taxRatePercentage ?? 19,
+    }));
+    return {
+        id: raw.id,
+        url: client.voucherUrl(raw.id),
+        voucherNumber: raw.voucherNumber,
+        voucherStatus: raw.voucherStatus,
+        contactId: raw.address?.contactId,
+        contactName: raw.address?.name,
+        lineItemsNet: items.length === 0 ? Number.NaN : round2(items.reduce((sum, item) => sum + item.quantity * item.netPrice, 0)),
+        lineItems: items,
+        totalNet: raw.totalPrice?.totalNetAmount,
+        discountAbsolute: raw.totalPrice?.totalDiscountAbsolute,
+        discountPercentage: raw.totalPrice?.totalDiscountPercentage,
+    };
+}
+/** Whether an invoice still exists. Only a 404 counts as gone — any other error answers true. */
+export async function invoiceExists(client, id, signal) {
+    try {
+        await client.request(`/invoices/${encodeURIComponent(id)}`, { signal });
+        return true;
+    }
+    catch (error) {
+        return !(error instanceof LexwareApiError && error.status === 404);
+    }
+}
+/** The most recent documents of a kind, newest first — how "the current quotation for X" is found. */
+export async function findRecentSalesDocuments(client, options) {
+    const from = new Date(Date.now() - (options.lookbackDays ?? 180) * 86_400_000).toISOString().slice(0, 10);
+    const list = await client.request(`/voucherlist${query({
+        voucherType: VOUCHERLIST_TYPE[options.kind],
+        voucherStatus: options.statuses ?? SALES_DOCUMENT_STATUSES[options.kind],
+        contactId: options.contactId,
+        voucherDateFrom: from,
+        sort: "voucherDate,DESC",
+        size: options.size ?? 25,
+    })}`, { signal: options.signal });
+    return (list.content ?? []).map((entry) => ({ ...entry, url: client.voucherUrl(entry.id) }));
+}
+/**
+ * A same-kind document for this contact with the same line-item net total —
+ * heuristic (sales documents carry no external reference), so a finding for
+ * the approval, never an automatic refusal. Each candidate is fetched in
+ * detail, capped at `maxCandidates`.
+ */
+export async function findDuplicateSalesDocument(client, options) {
+    const candidates = await findRecentSalesDocuments(client, {
+        kind: options.kind,
+        contactId: options.contactId,
+        lookbackDays: options.lookbackDays ?? 90,
+        size: 50,
+        signal: options.signal,
+    });
+    const checked = candidates.slice(0, options.maxCandidates ?? 10);
+    for (const [index, candidate] of checked.entries()) {
+        const detail = await getSalesDocument(client, options.kind, candidate.id, options.signal);
+        if (Math.abs(detail.lineItemsNet - round2(options.itemsTotalNet)) <= DUPLICATE_TOTAL_TOLERANCE) {
+            return { status: "match", match: candidate, scanned: index + 1 };
+        }
+    }
+    if (candidates.length > checked.length) {
+        return { status: "incomplete", scanned: checked.length, reason: `${candidates.length} Belege im Zeitfenster, nur die ${checked.length} neuesten geprüft` };
+    }
+    return { status: "clear", scanned: checked.length };
+}

package/dist/store.d.ts

@@ -0,0 +1,25 @@
+/**
+ * Where durable records live — the reminder ledger, send claims. A small JSON
+ * document store: read, write, create only if absent, delete.
+ *
+ * `create` must be atomic: two callers creating the same key, one wins. That
+ * is what keeps a reminder from going out twice. `memoryStore` is for tests
+ * and single-process use; `@kevludwig/lexware-office/vercel-blob` provides
+ * one on Vercel Blob.
+ */
+export interface JsonStore {
+    /** The document at `key`, or null if there is none. Throws when the store fails. */
+    read<T>(key: string): Promise<T | null>;
+    /** Writes the document, replacing what was there. */
+    write(key: string, value: unknown): Promise<void>;
+    /** Writes the document only if none exists; false when one does. */
+    create(key: string, value: unknown): Promise<boolean>;
+    /** Deletes the document; no error if there is none. */
+    delete(key: string): Promise<void>;
+}
+/** A key segment from an id: anything but word characters, dots, and dashes becomes "_". */
+export declare function keySegment(value: string): string;
+/** An in-memory store — for tests, or one process that never restarts. */
+export declare function memoryStore(): JsonStore & {
+    readonly size: number;
+};

package/dist/store.js

@@ -0,0 +1,38 @@
+/**
+ * Where durable records live — the reminder ledger, send claims. A small JSON
+ * document store: read, write, create only if absent, delete.
+ *
+ * `create` must be atomic: two callers creating the same key, one wins. That
+ * is what keeps a reminder from going out twice. `memoryStore` is for tests
+ * and single-process use; `@kevludwig/lexware-office/vercel-blob` provides
+ * one on Vercel Blob.
+ */
+/** A key segment from an id: anything but word characters, dots, and dashes becomes "_". */
+export function keySegment(value) {
+    return value.trim().replace(/[^\w.-]+/g, "_");
+}
+/** An in-memory store — for tests, or one process that never restarts. */
+export function memoryStore() {
+    const documents = new Map();
+    return {
+        get size() {
+            return documents.size;
+        },
+        async read(key) {
+            const value = documents.get(key);
+            return value === undefined ? null : JSON.parse(value);
+        },
+        async write(key, value) {
+            documents.set(key, JSON.stringify(value));
+        },
+        async create(key, value) {
+            if (documents.has(key))
+                return false;
+            documents.set(key, JSON.stringify(value));
+            return true;
+        },
+        async delete(key) {
+            documents.delete(key);
+        },
+    };
+}

package/dist/vercel-blob.d.ts

@@ -0,0 +1,13 @@
+/**
+ * A JsonStore on Vercel Blob. Documents are private, live at fixed pathnames
+ * under `prefix`, and are read past the CDN cache — records change within
+ * seconds of being read. `create` relies on Blob refusing to overwrite.
+ */
+import type { JsonStore } from "./store.ts";
+export interface VercelBlobStoreOptions {
+    /** Pathname prefix, e.g. "lexware-office/production". Empty: keys are pathnames. */
+    prefix: string;
+    /** Read-write token. Default: BLOB_READ_WRITE_TOKEN from the environment. */
+    token?: string;
+}
+export declare function vercelBlobStore(options: VercelBlobStoreOptions): JsonStore;

package/dist/vercel-blob.js

@@ -0,0 +1,48 @@
+/**
+ * A JsonStore on Vercel Blob. Documents are private, live at fixed pathnames
+ * under `prefix`, and are read past the CDN cache — records change within
+ * seconds of being read. `create` relies on Blob refusing to overwrite.
+ */
+import { BlobError, del, get, put } from "@vercel/blob";
+export function vercelBlobStore(options) {
+    const prefix = options.prefix.replace(/\/+$/, "");
+    const pathname = (key) => (prefix ? `${prefix}/${key}` : key);
+    const token = options.token;
+    return {
+        async read(key) {
+            const result = await get(pathname(key), { access: "private", useCache: false, token });
+            if (!result || result.statusCode !== 200)
+                return null;
+            return JSON.parse(await new Response(result.stream).text());
+        },
+        async write(key, value) {
+            await put(pathname(key), JSON.stringify(value), {
+                access: "private",
+                addRandomSuffix: false,
+                allowOverwrite: true,
+                contentType: "application/json",
+                token,
+            });
+        },
+        async create(key, value) {
+            try {
+                await put(pathname(key), JSON.stringify(value), {
+                    access: "private",
+                    addRandomSuffix: false,
+                    allowOverwrite: false,
+                    contentType: "application/json",
+                    token,
+                });
+                return true;
+            }
+            catch (error) {
+                if (error instanceof BlobError && /already exists/i.test(error.message))
+                    return false;
+                throw error;
+            }
+        },
+        async delete(key) {
+            await del(pathname(key), { token });
+        },
+    };
+}

package/dist/vouchers.d.ts

@@ -0,0 +1,125 @@
+/**
+ * Vouchers (`/vouchers`) — the bookkeeping side. A voucher carries amounts
+ * grouped by tax rate, no articles: a supplier invoice with 48 items at 19 %
+ * is one voucher item; the articles live in the attached original.
+ */
+import { type FileUpload, type LexwareClient } from "./client.ts";
+export type VoucherType = "purchaseinvoice" | "purchasecreditnote" | "salesinvoice" | "salescreditnote";
+/**
+ * Writable statuses. `unchecked` files the voucher under "Belege zur Prüfung"
+ * with several fields optional — the safe state for anything read from a
+ * document. `open` demands complete data. Other statuses are Lexware's own.
+ */
+export type VoucherStatus = "unchecked" | "open";
+export type VoucherTaxType = "net" | "gross";
+export interface VoucherItem {
+    /** Net or gross, per the voucher's taxType. */
+    amount: number;
+    taxAmount: number;
+    taxRatePercent: number;
+    categoryId?: string;
+}
+export interface CreateVoucherOptions {
+    type: VoucherType;
+    /** For purchase invoices: the supplier's invoice number. */
+    voucherNumber: string;
+    /** yyyy-MM-dd */
+    voucherDate: string;
+    /** yyyy-MM-dd */
+    dueDate?: string;
+    totalGrossAmount: number;
+    totalTaxAmount: number;
+    taxType: VoucherTaxType;
+    voucherStatus: VoucherStatus;
+    /** The collective contact ("Sammellieferant") instead of a real one. */
+    useCollectiveContact?: boolean;
+    /** A real contact; ignored with useCollectiveContact. */
+    contactId?: string;
+    /**
+     * The supplier's name — only with the collective contact, where it is the
+     * only mark. With a contactId the API answers 406
+     * (`custom_contact_name_for_referenced_contact_not_allowed`).
+     */
+    contactName?: string;
+    /** Free text; feeds Lexware's full-text search. */
+    remark?: string;
+    voucherItems: readonly VoucherItem[];
+}
+export interface CreatedVoucher {
+    id: string;
+    resourceUri?: string;
+    url: string;
+}
+/** Creates a voucher. `shippingDate` stays unset: the API allows it only for sales vouchers. */
+export declare function createVoucher(client: LexwareClient, options: CreateVoucherOptions, signal?: AbortSignal): Promise<CreatedVoucher>;
+/**
+ * Attaches a file (PDF, image, XML) to a voucher. Lexware keeps a checksum:
+ * the same file again returns the existing file id, no copy.
+ */
+export declare function uploadVoucherFile(client: LexwareClient, voucherId: string, file: FileUpload, signal?: AbortSignal): Promise<{
+    id: string;
+}>;
+export interface VoucherListEntry {
+    id: string;
+    voucherType: string;
+    voucherStatus: string;
+    voucherNumber?: string;
+    voucherDate?: string;
+    dueDate?: string;
+    contactId?: string;
+    contactName?: string;
+    totalAmount?: number;
+    openAmount?: number;
+    archived?: boolean;
+    /** Link into the web app. */
+    url: string;
+}
+export interface VoucherListFilter {
+    /** Comma-separated types, or `any`. Required by the API. */
+    voucherType: string;
+    /** Comma-separated statuses, or `any`. Required by the API. */
+    voucherStatus: string;
+    voucherNumber?: string;
+    contactId?: string;
+    voucherDateFrom?: string;
+    voucherDateTo?: string;
+    archived?: boolean;
+    size?: number;
+    sort?: string;
+}
+/** The voucher list — the one search across all voucher types. Newest first, 50 by default. */
+export declare function findVouchers(client: LexwareClient, filter: VoucherListFilter, signal?: AbortSignal): Promise<VoucherListEntry[]>;
+/**
+ * An already captured purchase invoice or credit note with this number, any
+ * status. Account-wide, not per vendor: two vendors with the same number
+ * match too, so the caller should compare `contactName` and warn rather than
+ * refuse.
+ */
+export declare function findPurchaseInvoiceByNumber(client: LexwareClient, voucherNumber: string, signal?: AbortSignal): Promise<VoucherListEntry | null>;
+export interface CategoryHistory {
+    /** Distinct categories of the vendor's booked vouchers, most recent first. */
+    categories: Array<{
+        id: string;
+        name: string;
+    }>;
+    scanned: number;
+    /** More booked vouchers existed than were checked. */
+    incomplete: boolean;
+    /**
+     * A single booked voucher was split across categories. Then the distinct
+     * list is no either/or choice: the vendor is categorized per position.
+     */
+    split: boolean;
+}
+/**
+ * The categories this vendor's booked purchase invoices were filed under —
+ * the basis for picking one automatically: always the same category means
+ * keep it; several mean the document has to decide. Only `open,paid,paidoff`
+ * count: an unchecked voucher may carry a wrong category. The voucher list has
+ * no categories, so each is fetched in detail — capped at `maxDetails`.
+ */
+export declare function findVendorCategoryHistory(client: LexwareClient, contactId: string, options?: {
+    signal?: AbortSignal;
+    maxDetails?: number;
+    lookbackDays?: number;
+}): Promise<CategoryHistory>;

package/dist/vouchers.js

@@ -0,0 +1,98 @@
+/**
+ * Vouchers (`/vouchers`) — the bookkeeping side. A voucher carries amounts
+ * grouped by tax rate, no articles: a supplier invoice with 48 items at 19 %
+ * is one voucher item; the articles live in the attached original.
+ */
+import { listPostingCategories } from "./categories.js";
+import { query } from "./client.js";
+import { round2 } from "./money.js";
+/** Creates a voucher. `shippingDate` stays unset: the API allows it only for sales vouchers. */
+export async function createVoucher(client, options, signal) {
+    if (options.voucherStatus === "unchecked" && options.taxType === "net") {
+        throw new Error("Ein Beleg mit Status 'unchecked' darf nicht taxType 'net' haben — die API verbietet die Kombination. " +
+            "Bruttobeträge übergeben (taxType 'gross') oder den Beleg mit Status 'open' vollständig erfassen.");
+    }
+    if (!options.useCollectiveContact && !options.contactId) {
+        throw new Error("Beleg ohne Kontakt: entweder useCollectiveContact setzen oder eine contactId übergeben.");
+    }
+    const payload = {
+        type: options.type,
+        voucherStatus: options.voucherStatus,
+        voucherNumber: options.voucherNumber,
+        voucherDate: options.voucherDate,
+        ...(options.dueDate ? { dueDate: options.dueDate } : {}),
+        totalGrossAmount: round2(options.totalGrossAmount),
+        totalTaxAmount: round2(options.totalTaxAmount),
+        taxType: options.taxType,
+        ...(options.useCollectiveContact
+            ? { useCollectiveContact: true, ...(options.contactName ? { contactName: options.contactName } : {}) }
+            : { useCollectiveContact: false, contactId: options.contactId }),
+        ...(options.remark ? { remark: options.remark } : {}),
+        voucherItems: options.voucherItems.map((item) => ({
+            amount: round2(item.amount),
+            taxAmount: round2(item.taxAmount),
+            taxRatePercent: item.taxRatePercent,
+            ...(item.categoryId ? { categoryId: item.categoryId } : {}),
+        })),
+        version: 0,
+    };
+    const result = await client.request("/vouchers", { method: "POST", json: payload, signal });
+    return { id: result.id, resourceUri: result.resourceUri, url: client.voucherUrl(result.id) };
+}
+/**
+ * Attaches a file (PDF, image, XML) to a voucher. Lexware keeps a checksum:
+ * the same file again returns the existing file id, no copy.
+ */
+export async function uploadVoucherFile(client, voucherId, file, signal) {
+    return client.upload(`/vouchers/${encodeURIComponent(voucherId)}/files`, file, { signal });
+}
+/** The voucher list — the one search across all voucher types. Newest first, 50 by default. */
+export async function findVouchers(client, filter, signal) {
+    const page = await client.request(`/voucherlist${query({ size: 50, sort: "voucherDate,DESC", ...filter })}`, { signal });
+    return (page.content ?? []).map((entry) => ({ ...entry, url: client.voucherUrl(entry.id) }));
+}
+/**
+ * An already captured purchase invoice or credit note with this number, any
+ * status. Account-wide, not per vendor: two vendors with the same number
+ * match too, so the caller should compare `contactName` and warn rather than
+ * refuse.
+ */
+export async function findPurchaseInvoiceByNumber(client, voucherNumber, signal) {
+    const matches = await findVouchers(client, { voucherType: "purchaseinvoice,purchasecreditnote", voucherStatus: "any", voucherNumber }, signal);
+    return matches[0] ?? null;
+}
+/**
+ * The categories this vendor's booked purchase invoices were filed under —
+ * the basis for picking one automatically: always the same category means
+ * keep it; several mean the document has to decide. Only `open,paid,paidoff`
+ * count: an unchecked voucher may carry a wrong category. The voucher list has
+ * no categories, so each is fetched in detail — capped at `maxDetails`.
+ */
+export async function findVendorCategoryHistory(client, contactId, options = {}) {
+    const from = new Date(Date.now() - (options.lookbackDays ?? 400) * 86_400_000).toISOString().slice(0, 10);
+    const booked = await findVouchers(client, { voucherType: "purchaseinvoice", voucherStatus: "open,paid,paidoff", contactId, voucherDateFrom: from, size: 20 }, options.signal);
+    const checked = booked.slice(0, options.maxDetails ?? 5);
+    const ids = [];
+    let split = false;
+    for (const entry of checked) {
+        const detail = await client.request(`/vouchers/${entry.id}`, { signal: options.signal });
+        const perVoucher = new Set();
+        for (const item of detail.voucherItems ?? []) {
+            if (!item.categoryId)
+                continue;
+            perVoucher.add(item.categoryId);
+            if (!ids.includes(item.categoryId))
+                ids.push(item.categoryId);
+        }
+        if (perVoucher.size > 1)
+            split = true;
+    }
+    const known = await listPostingCategories(client, options.signal);
+    return {
+        // An id the list does not know stays visible as the id.
+        categories: ids.map((id) => ({ id, name: known.find((category) => category.id === id)?.name ?? id })),
+        scanned: checked.length,
+        incomplete: booked.length > checked.length,
+        split,
+    };
+}