@kevludwig/lexware-office 0.1.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Kevin Ludwig
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,96 @@
+# @kevludwig/lexware-office
+
+A typed client and the domain logic for the [Lexware Office](https://www.lexware.de/lexware-office/) Public API (formerly lexoffice): contacts, vouchers, sales documents, posting categories, overdue receivables, and the rules behind payment reminders.
+
+No framework, no agent, no environment variables — you pass the key, the store, and the mailer. For an agent, see [`@kevludwig/eve-lexware-office`](../eve-lexware-office).
+
+```bash
+npm install @kevludwig/lexware-office
+```
+
+Node 24 or newer, ESM only.
+
+## The client
+
+```ts
+import { createLexwareClient } from "@kevludwig/lexware-office";
+
+const client = createLexwareClient({ apiKey: process.env.LEXWARE_API_KEY! });
+```
+
+One client is one rate-limit queue: requests are spaced (the API allows two per second), a 429 waits and is retried once, and each request has a time limit that starts when it actually fires. Several accounts are several clients — every function takes the client as its first argument.
+
+| Option | Default | What for |
+|---|---|---|
+| `apiKey` | — | Public API key, from Lexware Office under "Erweiterungen → Public API" |
+| `baseUrl` | `https://api.lexware.io/v1` | The old `api.lexoffice.io/v1` still works |
+| `appUrl` | `https://app.lexware.de` | Base of the links `voucherUrl()` builds |
+| `minSpacingMs` | `550` | Spacing between two requests |
+| `timeoutMs` | `20000` | Per request, counted from when it fires |
+| `rateLimitBackoffMs` | `1000` | Wait before the retry after a 429 |
+| `fetch` | global `fetch` | Your own implementation, e.g. in tests |
+
+A failed request throws `LexwareApiError` with `status` and `responseBody`; `describeError(error)` turns it into a sentence worth showing a person — a 403 says which permission the key lacks, a 406 what the API usually means by it.
+
+## What is in it
+
+**Contacts** — `getContact`, `findContactByNumber`, `findContactsByName`, `resolveContactByName` (exact name first, then the single candidate), `contactEmail`, `createCustomer`.
+
+**Sales documents** — `createSalesDocument` for quotations, order confirmations, and invoices, with `finalize`, a total discount, and `precedingSalesVoucherId` for a document chain; `getSalesDocument` (line items, totals, discounts, customer), `invoiceExists`, `findRecentSalesDocuments`, `findDuplicateSalesDocument` (same net total, same customer, within a window), `isPursueRejection` for the 406 an unusable chain answers with.
+
+**Purchase invoices** — `createVoucher`, `uploadVoucherFile` for the original, `findVouchers`, `findPurchaseInvoiceByNumber` for a document already captured, `findVendorCategoryHistory` for how this vendor's invoices were booked so far.
+
+**Posting categories** — `listPostingCategories` (cached per client), `resolveCategory` by name or id and direction, `isReverseChargeCategory` for §13b.
+
+**Receivables** — `findOverdueInvoices`, `findOverdueInvoice`, `downloadInvoicePdf`.
+
+**Payment reminders** — the rules below.
+
+**Money and dates** — `netTotal`, `round2`, `taxFromGross`, `taxFromNet`, the tolerances `ITEMS_TOTAL_TOLERANCE` and `DUPLICATE_TOTAL_TOLERANCE`, and `berlinDay`, `daysSince`, `addDays`.
+
+## Payment reminders
+
+`selectDueReminders` decides in code, not by judgment, which overdue invoices are due for a reminder:
+
+```ts
+import { defaultReminderMail, reminderLedger, selectDueReminders, sendReminder, vercelBlobStore } from "@kevludwig/lexware-office";
+
+const ledger = reminderLedger(vercelBlobStore({ prefix: "lexware-office" }), "reminders/live");
+const { due, held } = await selectDueReminders(client, ledger);
+
+for (const { invoice, customerEmail } of due) {
+  await sendReminder(
+    client,
+    ledger,
+    { ...invoice, invoiceId: invoice.id, to: customerEmail, test: false },
+    { render: defaultReminderMail({ name: "Beispiel GmbH" }), sendMail: yourMailer, owner: "nightly-run" },
+  );
+}
+```
+
+An invoice is offered when it is past its reminder due date by `minDaysOverdue`, has not been reminded, is not waiting for a decision somewhere else, was not declined recently, and its customer has an address. An invoice "due immediately" — Lexware Office sets the due date to the invoice date — gets `immediatePaymentTermDays` first. Everything else comes back in `held`, each with the reason.
+
+| Policy | Default | |
+|---|---|---|
+| `minDaysOverdue` | `3` | Buffer after the reminder due date |
+| `immediatePaymentTermDays` | `14` | Payment term assumed for an invoice due immediately |
+| `pendingValidHours` | `20` | How long a reminder waiting for approval blocks the invoice |
+| `declinedQuietDays` | `7` | Quiet after a declined reminder |
+
+`sendReminder` claims the send round in the ledger **before** the mail goes out, so "at most once per round" holds across parallel cards, a repeated schedule run, and a replayed step. If your mailer throws `MailNotSentError`, the claim is given back — anything else counts as possibly sent and stays claimed. The mail itself is yours: `sendMail` delivers it, `render` builds subject and body (the default is a friendly German reminder with the invoice PDF attached, signed by `sender`).
+
+## Storage
+
+The ledger needs somewhere to keep one small JSON record per invoice. `JsonStore` is four methods — `read`, `write`, `create` (which must fail when the key exists, that is what makes a claim a claim), `delete`:
+
+- `memoryStore()` — tests and scripts.
+- `vercelBlobStore({ prefix })` — Vercel Blob, needs `BLOB_READ_WRITE_TOKEN` (or a `token`). Imported from `@kevludwig/lexware-office/vercel-blob`, with `@vercel/blob` as an optional peer.
+- Your own, for Redis, S3, Postgres, a file — whatever makes `create` atomic.
+
+## Tests
+
+`npm test` runs 38 tests against a fake API — no account, no network. `test/fake-api.ts` shows the pattern: routes answer by method and path, and every call is recorded.
+
+## Not affiliated with Lexware
+
+An independent open-source project, MIT licensed. Not made, endorsed, or supported by Haufe-Lexware or its group; the names are used only to say which API this speaks to.

package/dist/categories.d.ts

@@ -0,0 +1,37 @@
+/**
+ * Posting categories (`/posting-categories`).
+ *
+ * Every voucher item carries a category. `income` applies to outgoing
+ * vouchers, `outgo` to incoming ones — the API rejects a purchase invoice with
+ * an income category. The list is per account and practically never changes;
+ * it is cached per client.
+ */
+import type { LexwareClient } from "./client.ts";
+export interface PostingCategory {
+    id: string;
+    name: string;
+    type: "income" | "outgo";
+    /** Whether the category demands a real contact on the voucher. */
+    contactRequired: boolean;
+    /** Whether items with different tax rates are allowed. */
+    splitAllowed: boolean;
+    groupName?: string;
+}
+/**
+ * The rate a reverse-charge item is booked with (§13b UStG): the recipient
+ * owes the VAT and deducts it again. Lexware Office books both sides through
+ * the category — the item carries this rate with a tax amount of 0, the gross
+ * is what the supplier was paid. A 0 % item is rejected (`invalid_taxrate_0`).
+ */
+export declare const REVERSE_CHARGE_TAX_RATE = 19;
+/** Whether a category books as reverse charge — the API has no flag, the name is the only marker ("… §13b …"). */
+export declare function isReverseChargeCategory(name: string | undefined): boolean;
+/** All posting categories of the account behind this client. */
+export declare function listPostingCategories(client: LexwareClient, signal?: AbortSignal): Promise<readonly PostingCategory[]>;
+/**
+ * A category of the given direction by name or id — exact name first, then a
+ * name containing it. A passed id is checked against the list, so a category
+ * of the wrong direction fails here, not with a 406 at creation. Null means
+ * "not resolvable", not "error".
+ */
+export declare function resolveCategory(client: LexwareClient, nameOrId: string, type: PostingCategory["type"], signal?: AbortSignal): Promise<PostingCategory | null>;

package/dist/categories.js

@@ -0,0 +1,48 @@
+/**
+ * Posting categories (`/posting-categories`).
+ *
+ * Every voucher item carries a category. `income` applies to outgoing
+ * vouchers, `outgo` to incoming ones — the API rejects a purchase invoice with
+ * an income category. The list is per account and practically never changes;
+ * it is cached per client.
+ */
+/**
+ * The rate a reverse-charge item is booked with (§13b UStG): the recipient
+ * owes the VAT and deducts it again. Lexware Office books both sides through
+ * the category — the item carries this rate with a tax amount of 0, the gross
+ * is what the supplier was paid. A 0 % item is rejected (`invalid_taxrate_0`).
+ */
+export const REVERSE_CHARGE_TAX_RATE = 19;
+/** Whether a category books as reverse charge — the API has no flag, the name is the only marker ("… §13b …"). */
+export function isReverseChargeCategory(name) {
+    return Boolean(name && /§\s*13b/i.test(name));
+}
+const cache = new WeakMap();
+/** All posting categories of the account behind this client. */
+export async function listPostingCategories(client, signal) {
+    const cached = cache.get(client);
+    if (cached)
+        return cached;
+    const categories = (await client.request("/posting-categories", { signal })) ?? [];
+    cache.set(client, categories);
+    return categories;
+}
+const UUID = /^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$/i;
+/**
+ * A category of the given direction by name or id — exact name first, then a
+ * name containing it. A passed id is checked against the list, so a category
+ * of the wrong direction fails here, not with a 406 at creation. Null means
+ * "not resolvable", not "error".
+ */
+export async function resolveCategory(client, nameOrId, type, signal) {
+    const needle = nameOrId.trim();
+    if (!needle)
+        return null;
+    const matching = (await listPostingCategories(client, signal)).filter((category) => category.type === type);
+    if (UUID.test(needle))
+        return matching.find((category) => category.id.toLowerCase() === needle.toLowerCase()) ?? null;
+    const lower = needle.toLowerCase();
+    return (matching.find((category) => category.name.toLowerCase() === lower) ??
+        matching.find((category) => category.name.toLowerCase().includes(lower)) ??
+        null);
+}

package/dist/client.d.ts

@@ -0,0 +1,74 @@
+/**
+ * The HTTP layer of the Lexware Office Public API.
+ *
+ * One client per account: the API allows two requests per second for the
+ * whole account, so every call of a client goes through one serial queue with
+ * a minimum spacing. A single retry on 429 covers the case that something else
+ * uses the same account at the same time. Share one client instead of creating
+ * one per call — separate clients do not know about each other's requests.
+ */
+export declare const DEFAULT_BASE_URL = "https://api.lexware.io/v1";
+/** Where a voucher opens in the Lexware Office web app. */
+export declare const DEFAULT_APP_URL = "https://app.lexware.de";
+export interface LexwareClientOptions {
+    /** A Public API key, created in Lexware Office under "Erweiterungen → Public API". */
+    apiKey: string;
+    /** API base URL. Default: https://api.lexware.io/v1 (the former api.lexoffice.io/v1 still works). */
+    baseUrl?: string;
+    /** Web app URL for links to vouchers. Default: https://app.lexware.de */
+    appUrl?: string;
+    /** Minimum spacing between two requests in ms. Default: 550 (the API allows 2 per second). */
+    minSpacingMs?: number;
+    /** Time limit per request in ms, counted from when it actually fires. Default: 20 000. */
+    timeoutMs?: number;
+    /** Wait before retrying a request answered with 429, in ms. Default: 1 000. */
+    rateLimitBackoffMs?: number;
+    /** A fetch implementation, e.g. for tests. Default: the global fetch. */
+    fetch?: typeof fetch;
+}
+export interface FileUpload {
+    bytes: Uint8Array;
+    filename: string;
+    mediaType: string;
+}
+export interface LexwareClient {
+    /** A JSON request. `json` sets the body and content type. */
+    request<T = unknown>(path: string, init?: RequestInit & {
+        json?: unknown;
+    }): Promise<T>;
+    /** A binary download, e.g. a document's PDF. */
+    download(path: string, init: RequestInit & {
+        accept: string;
+    }): Promise<{
+        bytes: Uint8Array;
+        mediaType: string;
+    }>;
+    /** A multipart file upload; the API calls the field `file`. */
+    upload<T = unknown>(path: string, file: FileUpload, init?: RequestInit): Promise<T>;
+    /** The link to a voucher or invoice in the web app. */
+    voucherUrl(id: string): string;
+}
+/**
+ * An error answer of the API, with status and body.
+ *
+ * The status matters most: 403 nearly always means "the key lacks a
+ * permission for this endpoint", not "the request was wrong".
+ */
+export declare class LexwareApiError extends Error {
+    readonly status: number;
+    readonly method: string;
+    readonly path: string;
+    readonly responseBody: string;
+    constructor(options: {
+        status: number;
+        statusText: string;
+        method: string;
+        path: string;
+        responseBody: string;
+    });
+}
+/** An error as a sentence, with the hint that is nearly always right for its status. */
+export declare function describeError(error: unknown): string;
+/** A query string from an object; empty values drop out. */
+export declare function query(params: Record<string, string | number | boolean | undefined>): string;
+export declare function createLexwareClient(options: LexwareClientOptions): LexwareClient;

package/dist/client.js

@@ -0,0 +1,143 @@
+/**
+ * The HTTP layer of the Lexware Office Public API.
+ *
+ * One client per account: the API allows two requests per second for the
+ * whole account, so every call of a client goes through one serial queue with
+ * a minimum spacing. A single retry on 429 covers the case that something else
+ * uses the same account at the same time. Share one client instead of creating
+ * one per call — separate clients do not know about each other's requests.
+ */
+export const DEFAULT_BASE_URL = "https://api.lexware.io/v1";
+/** Where a voucher opens in the Lexware Office web app. */
+export const DEFAULT_APP_URL = "https://app.lexware.de";
+/**
+ * An error answer of the API, with status and body.
+ *
+ * The status matters most: 403 nearly always means "the key lacks a
+ * permission for this endpoint", not "the request was wrong".
+ */
+export class LexwareApiError extends Error {
+    status;
+    method;
+    path;
+    responseBody;
+    constructor(options) {
+        super(`Lexware API ${options.status} ${options.statusText} bei ${options.method} ${options.path}` +
+            (options.responseBody ? `: ${options.responseBody.slice(0, 500)}` : ""));
+        this.name = "LexwareApiError";
+        this.status = options.status;
+        this.method = options.method;
+        this.path = options.path;
+        this.responseBody = options.responseBody;
+    }
+}
+/** An error as a sentence, with the hint that is nearly always right for its status. */
+export function describeError(error) {
+    if (!(error instanceof LexwareApiError))
+        return error instanceof Error ? error.message : String(error);
+    const hint = error.status === 403
+        ? " Ein 403 heißt: dem API-Schlüssel fehlt das Recht für diesen Endpunkt."
+        : error.status === 406
+            ? " Ein 406 heißt meist: ein Pflichtfeld fehlt oder ein Betrag passt nicht zur Summe."
+            : "";
+    return `${error.message}${hint}`;
+}
+/** A query string from an object; empty values drop out. */
+export function query(params) {
+    const search = new URLSearchParams();
+    for (const [key, value] of Object.entries(params)) {
+        if (value === undefined || value === "")
+            continue;
+        search.set(key, String(value));
+    }
+    const rendered = search.toString();
+    return rendered ? `?${rendered}` : "";
+}
+const sleep = (ms) => new Promise((resolve) => setTimeout(resolve, ms));
+export function createLexwareClient(options) {
+    if (!options.apiKey?.trim())
+        throw new Error("Lexware Office: apiKey fehlt.");
+    const baseUrl = (options.baseUrl ?? DEFAULT_BASE_URL).replace(/\/+$/, "");
+    const appUrl = (options.appUrl ?? DEFAULT_APP_URL).replace(/\/+$/, "");
+    const minSpacingMs = options.minSpacingMs ?? 550;
+    const timeoutMs = options.timeoutMs ?? 20_000;
+    const backoffMs = options.rateLimitBackoffMs ?? 1_000;
+    const fetchImpl = options.fetch ?? fetch;
+    // The queue: each request waits for the previous one to start plus the
+    // spacing. The time limit starts when the request fires, not when queued.
+    let chain = Promise.resolve();
+    let lastStart = 0;
+    function schedule(task) {
+        const run = chain.then(async () => {
+            const wait = minSpacingMs - (Date.now() - lastStart);
+            if (wait > 0)
+                await sleep(wait);
+            lastStart = Date.now();
+            return task();
+        });
+        // An error belongs to its caller, not to the queue.
+        chain = run.then(() => undefined, () => undefined);
+        return run;
+    }
+    /**
+     * One request, queued, with a single retry on 429 — then the API
+     * demonstrably did not run it. A transport error after a POST is never
+     * retried: the voucher may well exist already.
+     */
+    async function send(path, init) {
+        const method = init.method ?? "GET";
+        const fire = () => schedule(() => {
+            const timeout = AbortSignal.timeout(timeoutMs);
+            return fetchImpl(`${baseUrl}${path}`, {
+                ...init,
+                headers: { Authorization: `Bearer ${options.apiKey}`, Accept: "application/json", ...init.headers },
+                signal: init.signal ? AbortSignal.any([init.signal, timeout]) : timeout,
+            });
+        });
+        let response = await fire();
+        if (response.status === 429) {
+            await sleep(backoffMs);
+            response = await fire();
+        }
+        if (!response.ok) {
+            const body = await response.text().catch(() => "");
+            throw new LexwareApiError({ status: response.status, statusText: response.statusText, method, path, responseBody: body });
+        }
+        return response;
+    }
+    async function json(response) {
+        // Not every endpoint answers with a body (204).
+        const text = await response.text();
+        return (text ? JSON.parse(text) : undefined);
+    }
+    return {
+        async request(path, init = {}) {
+            const { json: body, ...rest } = init;
+            const response = await send(path, {
+                ...rest,
+                ...(body === undefined
+                    ? {}
+                    : { body: JSON.stringify(body), headers: { "Content-Type": "application/json", ...rest.headers } }),
+            });
+            return json(response);
+        },
+        async download(path, init) {
+            const { accept, ...rest } = init;
+            const response = await send(path, { ...rest, headers: { ...rest.headers, Accept: accept } });
+            return {
+                bytes: new Uint8Array(await response.arrayBuffer()),
+                mediaType: response.headers.get("content-type") ?? accept,
+            };
+        },
+        async upload(path, file, init = {}) {
+            const form = new FormData();
+            // An own ArrayBuffer: Blob refuses shared buffers.
+            form.set("file", new Blob([Uint8Array.from(file.bytes)], { type: file.mediaType }), file.filename);
+            // No Content-Type: fetch sets the multipart boundary.
+            return json(await send(path, { ...init, method: "POST", body: form }));
+        },
+        voucherUrl(id) {
+            return `${appUrl}/vouchers#!/VoucherDetail/${id}`;
+        },
+    };
+}

package/dist/contacts.d.ts

@@ -0,0 +1,78 @@
+/**
+ * Contacts — customers and vendors alike.
+ *
+ * Search is fuzzy on the API side: "Nordlicht" finds "Nordlicht Consulting
+ * GmbH", "Müller" may find three. Functions here return candidates and leave
+ * the choice to the caller; guessing one of several is the worse mistake.
+ */
+import { type LexwareClient } from "./client.ts";
+export interface Contact {
+    id: string;
+    /** Company name, or first and last name of a person. */
+    name: string;
+    /** Customer or vendor number, where assigned. */
+    number?: number;
+    isCustomer: boolean;
+    isVendor: boolean;
+}
+/** A contact by its id. */
+export declare function getContact(client: LexwareClient, id: string, signal?: AbortSignal): Promise<Contact>;
+/** The contact with this customer number, or null. */
+export declare function findContactByNumber(client: LexwareClient, customerNumber: number, signal?: AbortSignal): Promise<Contact | null>;
+/** Contacts whose name matches — fuzzy, up to `size` (default 10). */
+export declare function findContactsByName(client: LexwareClient, name: string, options?: {
+    customer?: boolean;
+    vendor?: boolean;
+    size?: number;
+    signal?: AbortSignal;
+}): Promise<Contact[]>;
+/**
+ * The one contact a name clearly means: an exact match, or the only
+ * candidate. Otherwise `match` is null and the candidates are for the caller
+ * to choose from.
+ */
+export declare function resolveContactByName(client: LexwareClient, name: string, options?: {
+    customer?: boolean;
+    vendor?: boolean;
+    signal?: AbortSignal;
+}): Promise<{
+    match: Contact | null;
+    candidates: Contact[];
+}>;
+/** Where a contact receives mail: a business address first, then office, other, private. */
+export declare function contactEmail(client: LexwareClient, id: string, signal?: AbortSignal): Promise<string | null>;
+export interface NewCustomer {
+    /** Exactly one of company or person. */
+    company?: {
+        name: string;
+    };
+    person?: {
+        firstName?: string;
+        lastName: string;
+    };
+    billingAddress?: {
+        supplement?: string;
+        street?: string;
+        zip?: string;
+        city?: string;
+        /** ISO 3166-1 alpha-2. Default: DE. */
+        countryCode?: string;
+    };
+    email?: string;
+    phone?: string;
+    /** Internal note, invisible on documents. */
+    note?: string;
+}
+export interface CreatedCustomer {
+    id: string;
+    /** Assigned by Lexware Office on creation; missing if the read-back failed. */
+    customerNumber?: number;
+    /** The name as stored. */
+    name: string;
+}
+/**
+ * Creates a customer and reads it back: the customer number is assigned
+ * server-side, and the stored name is what belongs in a confirmation. Needs
+ * the key permission "Kontakte bearbeiten".
+ */
+export declare function createCustomer(client: LexwareClient, input: NewCustomer, signal?: AbortSignal): Promise<CreatedCustomer>;

package/dist/contacts.js

@@ -0,0 +1,107 @@
+/**
+ * Contacts — customers and vendors alike.
+ *
+ * Search is fuzzy on the API side: "Nordlicht" finds "Nordlicht Consulting
+ * GmbH", "Müller" may find three. Functions here return candidates and leave
+ * the choice to the caller; guessing one of several is the worse mistake.
+ */
+import { query } from "./client.js";
+function nameOf(raw) {
+    return raw.company?.name ?? [raw.person?.firstName, raw.person?.lastName].filter(Boolean).join(" ");
+}
+function toContact(raw) {
+    return {
+        id: raw.id,
+        name: nameOf(raw) || "unbekannt",
+        number: raw.roles?.customer?.number ?? raw.roles?.vendor?.number,
+        isCustomer: raw.roles?.customer !== undefined,
+        isVendor: raw.roles?.vendor !== undefined,
+    };
+}
+/** A contact by its id. */
+export async function getContact(client, id, signal) {
+    return toContact(await client.request(`/contacts/${encodeURIComponent(id)}`, { signal }));
+}
+/** The contact with this customer number, or null. */
+export async function findContactByNumber(client, customerNumber, signal) {
+    const page = await client.request(`/contacts${query({ number: customerNumber })}`, { signal });
+    const raw = page.content?.[0];
+    return raw ? toContact(raw) : null;
+}
+/** Contacts whose name matches — fuzzy, up to `size` (default 10). */
+export async function findContactsByName(client, name, options = {}) {
+    const page = await client.request(`/contacts${query({ name, customer: options.customer, vendor: options.vendor, size: options.size ?? 10 })}`, { signal: options.signal });
+    return (page.content ?? []).map(toContact);
+}
+/**
+ * The one contact a name clearly means: an exact match, or the only
+ * candidate. Otherwise `match` is null and the candidates are for the caller
+ * to choose from.
+ */
+export async function resolveContactByName(client, name, options = {}) {
+    const needle = name.trim();
+    if (!needle)
+        return { match: null, candidates: [] };
+    const candidates = await findContactsByName(client, needle, options);
+    const exact = candidates.filter((contact) => contact.name.toLowerCase() === needle.toLowerCase());
+    if (exact.length === 1)
+        return { match: exact[0], candidates };
+    if (candidates.length === 1)
+        return { match: candidates[0], candidates };
+    return { match: null, candidates };
+}
+/** Where a contact receives mail: a business address first, then office, other, private. */
+export async function contactEmail(client, id, signal) {
+    const raw = await client.request(`/contacts/${encodeURIComponent(id)}`, { signal });
+    const addresses = raw.emailAddresses ?? {};
+    return ([...(addresses.business ?? []), ...(addresses.office ?? []), ...(addresses.other ?? []), ...(addresses.private ?? [])]
+        .map((address) => address.trim())
+        .find((address) => address.includes("@")) ?? null);
+}
+/**
+ * Creates a customer and reads it back: the customer number is assigned
+ * server-side, and the stored name is what belongs in a confirmation. Needs
+ * the key permission "Kontakte bearbeiten".
+ */
+export async function createCustomer(client, input, signal) {
+    if (Boolean(input.company) === Boolean(input.person)) {
+        throw new Error("Ein Kunde ist entweder eine Firma oder eine Person.");
+    }
+    const address = input.billingAddress;
+    const payload = {
+        version: 0,
+        roles: { customer: {} },
+        ...(input.company ? { company: { name: input.company.name } } : {}),
+        ...(input.person
+            ? { person: { ...(input.person.firstName ? { firstName: input.person.firstName } : {}), lastName: input.person.lastName } }
+            : {}),
+        ...(address
+            ? {
+                addresses: {
+                    billing: [
+                        {
+                            ...(address.supplement ? { supplement: address.supplement } : {}),
+                            ...(address.street ? { street: address.street } : {}),
+                            ...(address.zip ? { zip: address.zip } : {}),
+                            ...(address.city ? { city: address.city } : {}),
+                            countryCode: address.countryCode ?? "DE",
+                        },
+                    ],
+                },
+            }
+            : {}),
+        ...(input.email ? { emailAddresses: { business: [input.email] } } : {}),
+        ...(input.phone ? { phoneNumbers: { business: [input.phone] } } : {}),
+        ...(input.note ? { note: input.note } : {}),
+    };
+    const created = await client.request("/contacts", { method: "POST", json: payload, signal });
+    const fallbackName = input.company?.name ?? input.person?.lastName ?? "unbekannt";
+    try {
+        const detail = await client.request(`/contacts/${created.id}`, { signal });
+        return { id: created.id, customerNumber: detail.roles?.customer?.number, name: nameOf(detail) || fallbackName };
+    }
+    catch {
+        // The customer exists; a failed read-back must not look like a failed creation.
+        return { id: created.id, name: fallbackName };
+    }
+}

package/dist/dates.d.ts

@@ -0,0 +1,11 @@
+/**
+ * Calendar days as Lexware Office users count them: in Berlin. A due date is
+ * a day, not a moment — "3 days overdue" must not depend on whether the check
+ * runs at 00:30 or 23:30.
+ */
+/** Today (or `at`) as a day in Berlin, yyyy-MM-dd. */
+export declare function berlinDay(at?: Date): string;
+/** Days from a day (yyyy-MM-dd) to today in Berlin; negative while still ahead. */
+export declare function daysSince(day: string, today?: Date): number;
+/** A day (yyyy-MM-dd) moved by whole days. */
+export declare function addDays(day: string, days: number): string;

package/dist/dates.js

@@ -0,0 +1,21 @@
+/**
+ * Calendar days as Lexware Office users count them: in Berlin. A due date is
+ * a day, not a moment — "3 days overdue" must not depend on whether the check
+ * runs at 00:30 or 23:30.
+ */
+/** Today (or `at`) as a day in Berlin, yyyy-MM-dd. */
+export function berlinDay(at = new Date()) {
+    return at.toLocaleDateString("sv-SE", { timeZone: "Europe/Berlin" });
+}
+/** Days from a day (yyyy-MM-dd) to today in Berlin; negative while still ahead. */
+export function daysSince(day, today = new Date()) {
+    const from = Date.parse(`${day.slice(0, 10)}T00:00:00Z`);
+    const to = Date.parse(`${berlinDay(today)}T00:00:00Z`);
+    return Math.round((to - from) / 86_400_000);
+}
+/** A day (yyyy-MM-dd) moved by whole days. */
+export function addDays(day, days) {
+    const date = new Date(`${day.slice(0, 10)}T00:00:00Z`);
+    date.setUTCDate(date.getUTCDate() + days);
+    return date.toISOString().slice(0, 10);
+}

package/dist/index.d.ts

@@ -0,0 +1,11 @@
+export { DEFAULT_APP_URL, DEFAULT_BASE_URL, LexwareApiError, createLexwareClient, describeError, query, type FileUpload, type LexwareClient, type LexwareClientOptions, } from "./client.ts";
+export { contactEmail, createCustomer, findContactByNumber, findContactsByName, getContact, resolveContactByName, type Contact, type CreatedCustomer, type NewCustomer, } from "./contacts.ts";
+export { addDays, berlinDay, daysSince } from "./dates.ts";
+export { downloadInvoicePdf, findOverdueInvoice, findOverdueInvoices, type OverdueInvoice, } from "./receivables.ts";
+export { DEFAULT_REMINDER_POLICY, daysPastReminderDue, earliestReminderDate, isDueImmediately, isOpenForReminder, reminderDueDate, reminderLedger, selectDueReminders, type DueReminder, type ReminderHold, type ReminderLedger, type ReminderPolicy, type ReminderRecord, type ReminderSelection, type ReminderStatus, sendReminder, type ReminderTarget, type SendReminderOutcome, } from "./reminders.ts";
+export { MailNotSentError, defaultReminderMail, reminderSubject, type ReminderMail, type ReminderMailData, type ReminderSender, type RenderReminderMail, type SendReminderMail, } from "./reminder-mail.ts";
+export { keySegment, memoryStore, type JsonStore } from "./store.ts";
+export { DUPLICATE_TOTAL_TOLERANCE, ITEMS_TOTAL_TOLERANCE, netTotal, round2, taxFromGross, taxFromNet, type PricedLine, } from "./money.ts";
+export { REVERSE_CHARGE_TAX_RATE, isReverseChargeCategory, listPostingCategories, resolveCategory, type PostingCategory, } from "./categories.ts";
+export { createVoucher, findPurchaseInvoiceByNumber, findVendorCategoryHistory, findVouchers, uploadVoucherFile, type CategoryHistory, type CreateVoucherOptions, type CreatedVoucher, type VoucherItem, type VoucherListEntry, type VoucherListFilter, type VoucherStatus, type VoucherTaxType, type VoucherType, } from "./vouchers.ts";
+export { SALES_DOCUMENT_STATUSES, VOUCHERLIST_TYPE, createSalesDocument, findDuplicateSalesDocument, findRecentSalesDocuments, getSalesDocument, invoiceExists, isPursueRejection, type CreatedSalesDocument, type DuplicateSearchResult, type LineItem, type SalesDocumentDetail, type SalesDocumentKind, type SalesListEntry, } from "./sales-documents.ts";