@kevludwig/lexware-office 0.2.0 → 0.4.0

package/README.md

@@ -27,7 +27,8 @@ One client is one rate-limit queue: requests are spaced (the API allows two per
 | `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 |
+| `rateLimitBackoffMs` | `1000` | Wait before a retry after a 429 without `Retry-After`, growing with each retry |
+| `rateLimitRetries` | `3` | How often a request answered with 429 is sent again; `Retry-After` is honoured (at most 10 s) |
 | `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.
@@ -36,7 +37,7 @@ A failed request throws `LexwareApiError` with `status` and `responseBody`; `des
 
 **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, `precedingSalesVoucherId` for a document chain, `introduction` and `remark`, and line items that are priced (with an optional `description`; `optional` on quotations) or `type: "text"` headings; `SALES_TEXT_LIMITS` holds the API's text lengths; `getSalesDocument` (the lines that count, optional lines apart, totals, discounts, customer), `invoiceExists`, `findRecentSalesDocuments`, `findDuplicateSalesDocument` (same net total, same customer, within a window), `isPursueRejection` for the 406 an unusable chain answers with.
+**Sales documents** — `createSalesDocument` for quotations, order confirmations, and invoices, with `finalize`, `voucherDate`, `shippingConditions` (service or delivery date or period), `paymentConditions` (`paymentTermLabel` phrases one as Lexware does), `taxConditions` (net, gross, and the vat-free types), a total discount in EUR or percent, `language`, `printLayoutId`, `deliveryTerms` (order confirmations), `xRechnung` (invoices), `precedingSalesVoucherId` for a document chain, `introduction` and `remark`, and line items that are priced (with an optional `description`, `discountPercentage`, `grossPrice`, an `article` reference; `optional` and `alternatives` on quotations) or `type: "text"` headings; `salesDocumentProblems` names what the API would drop or reject before anything is sent; `SALES_TEXT_LIMITS` holds the API's text lengths; `getSalesDocument` (the lines that count, optional lines apart, totals, discounts, customer), `invoiceExists`, `findRecentSalesDocuments`, `findDuplicateSalesDocument` (same net total, same customer, within a window), `isPursueRejection` for the 406 an unusable chain answers with. Account settings a document refers to: `listPrintLayouts` / `resolvePrintLayout`, `listPaymentConditions` / `defaultPaymentCondition`, `getProfile`, `listCountries` (with their tax classification), `getArticle`.
 
 **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.
 

package/dist/client.d.ts

@@ -3,9 +3,10 @@
  *
  * 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.
+ * a minimum spacing. Retries on 429 — honouring Retry-After — cover other
+ * clients on the same account: serverless instances, a second app. Share one
+ * client per process; separate clients do not know about each other's
+ * requests, the retries only soften that.
  */
 export declare const DEFAULT_BASE_URL = "https://api.lexware.io/v1";
 /** Where a voucher opens in the Lexware Office web app. */
@@ -27,8 +28,10 @@ export interface LexwareClientOptions {
      * a file that arrives anyway. Default: 120 000.
      */
     uploadTimeoutMs?: number;
-    /** Wait before retrying a request answered with 429, in ms. Default: 1 000. */
+    /** Wait before retrying a request answered with 429 without Retry-After, in ms; grows with each retry. Default: 1 000. */
     rateLimitBackoffMs?: number;
+    /** How often a request answered with 429 is sent again. Default: 3. */
+    rateLimitRetries?: number;
     /** A fetch implementation, e.g. for tests. Default: the global fetch. */
     fetch?: typeof fetch;
 }

package/dist/client.js

@@ -3,9 +3,10 @@
  *
  * 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.
+ * a minimum spacing. Retries on 429 — honouring Retry-After — cover other
+ * clients on the same account: serverless instances, a second app. Share one
+ * client per process; separate clients do not know about each other's
+ * requests, the retries only soften that.
  */
 export const DEFAULT_BASE_URL = "https://api.lexware.io/v1";
 /** Where a voucher opens in the Lexware Office web app. */
@@ -54,6 +55,15 @@ export function query(params) {
     return rendered ? `?${rendered}` : "";
 }
 const sleep = (ms) => new Promise((resolve) => setTimeout(resolve, ms));
+/** The server's Retry-After in ms (seconds or an HTTP date), capped at 10 s; null without one. */
+function retryAfterMs(response) {
+    const header = response.headers.get("retry-after")?.trim();
+    if (!header)
+        return null;
+    const seconds = Number(header);
+    const ms = Number.isFinite(seconds) ? seconds * 1_000 : Date.parse(header) - Date.now();
+    return Number.isFinite(ms) ? Math.min(Math.max(ms, 0), 10_000) : null;
+}
 export function createLexwareClient(options) {
     if (!options.apiKey?.trim())
         throw new Error("Lexware Office: apiKey fehlt.");
@@ -63,6 +73,7 @@ export function createLexwareClient(options) {
     const timeoutMs = options.timeoutMs ?? 20_000;
     const uploadTimeoutMs = options.uploadTimeoutMs ?? 120_000;
     const backoffMs = options.rateLimitBackoffMs ?? 1_000;
+    const retries = options.rateLimitRetries ?? 3;
     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.
@@ -81,9 +92,9 @@ export function createLexwareClient(options) {
         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.
+     * One request, queued, retried 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, limitMs = timeoutMs) {
         const method = init.method ?? "GET";
@@ -96,8 +107,9 @@ export function createLexwareClient(options) {
             });
         });
         let response = await fire();
-        if (response.status === 429) {
-            await sleep(backoffMs);
+        for (let attempt = 1; response.status === 429 && attempt <= retries; attempt++) {
+            await response.body?.cancel().catch(() => undefined);
+            await sleep(retryAfterMs(response) ?? backoffMs * attempt);
             response = await fire();
         }
         if (!response.ok) {

package/dist/contacts.d.ts

@@ -14,6 +14,14 @@ export interface Contact {
     number?: number;
     isCustomer: boolean;
     isVendor: boolean;
+    /** A company rather than a person. */
+    isCompany?: boolean;
+    /** The company's VAT ID (USt-IdNr.) — needed for the § 13b and intra-community tax types. */
+    vatRegistrationId?: string;
+    /** „Steuerfreie Rechnung erlauben" — needed for the third-country tax types. */
+    allowTaxFreeInvoices?: boolean;
+    /** ISO code of the first billing address. */
+    countryCode?: string;
 }
 /** A contact by its id. */
 export declare function getContact(client: LexwareClient, id: string, signal?: AbortSignal): Promise<Contact>;

package/dist/contacts.js

@@ -16,6 +16,10 @@ function toContact(raw) {
         number: raw.roles?.customer?.number ?? raw.roles?.vendor?.number,
         isCustomer: raw.roles?.customer !== undefined,
         isVendor: raw.roles?.vendor !== undefined,
+        isCompany: raw.company !== undefined,
+        ...(raw.company?.vatRegistrationId?.trim() ? { vatRegistrationId: raw.company.vatRegistrationId.trim() } : {}),
+        ...(raw.company?.allowTaxFreeInvoices !== undefined ? { allowTaxFreeInvoices: raw.company.allowTaxFreeInvoices } : {}),
+        ...(raw.addresses?.billing?.[0]?.countryCode ? { countryCode: raw.addresses.billing[0].countryCode } : {}),
     };
 }
 /** A contact by its id. */

package/dist/index.d.ts

@@ -5,7 +5,8 @@ export { downloadInvoicePdf, findOverdueInvoice, findOverdueInvoices, type Overd
 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, mailContentSha256, paymentReminderEffect, sendReminder, type PaymentReminderEffect, 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 { DUPLICATE_TOTAL_TOLERANCE, ITEMS_TOTAL_TOLERANCE, lineNet, 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, voucherFileIds, 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, countsToTotal, createSalesDocument, findDuplicateSalesDocument, findRecentSalesDocuments, getSalesDocument, invoiceExists, isPricedLine, isPursueRejection, SALES_TEXT_LIMITS, type CreatedSalesDocument, type DuplicateSearchResult, type LineItem, type PricedLineItem, type SalesDocumentDetail, type SalesDocumentKind, type SalesListEntry, type TextLineItem, } from "./sales-documents.ts";
+export { SALES_DOCUMENT_STATUSES, SALES_TAX_TYPES, VALID_TAX_RATES, VOUCHERLIST_TYPE, countsToTotal, createSalesDocument, isVatFreeTaxType, paymentTermLabel, salesDocumentProblems, findDuplicateSalesDocument, findRecentSalesDocuments, getSalesDocument, invoiceExists, isPricedLine, isPursueRejection, SALES_TEXT_LIMITS, type AlternativeLineItem, type CreatedSalesDocument, type DuplicateSearchResult, type LineItem, type NewSalesDocument, type PaymentConditions, type PricedLineItem, type SalesLanguage, type SalesTaxType, type ShippingConditions, type TaxConditions, type SalesDocumentDetail, type SalesDocumentKind, type SalesListEntry, type TextLineItem, } from "./sales-documents.ts";
+export { defaultPaymentCondition, getArticle, getProfile, listCountries, listPaymentConditions, listPrintLayouts, resolvePrintLayout, type Article, type Country, type CountryTaxClassification, type PaymentConditionTemplate, type PrintLayout, type Profile, } from "./settings.ts";

package/dist/index.js

@@ -5,7 +5,8 @@ export { downloadInvoicePdf, findOverdueInvoice, findOverdueInvoices, } from "./
 export { DEFAULT_REMINDER_POLICY, daysPastReminderDue, earliestReminderDate, isDueImmediately, isOpenForReminder, reminderDueDate, reminderLedger, selectDueReminders, mailContentSha256, paymentReminderEffect, sendReminder, } from "./reminders.js";
 export { MailNotSentError, defaultReminderMail, reminderSubject, } from "./reminder-mail.js";
 export { keySegment, memoryStore } from "./store.js";
-export { DUPLICATE_TOTAL_TOLERANCE, ITEMS_TOTAL_TOLERANCE, netTotal, round2, taxFromGross, taxFromNet, } from "./money.js";
+export { DUPLICATE_TOTAL_TOLERANCE, ITEMS_TOTAL_TOLERANCE, lineNet, netTotal, round2, taxFromGross, taxFromNet, } from "./money.js";
 export { REVERSE_CHARGE_TAX_RATE, isReverseChargeCategory, listPostingCategories, resolveCategory, } from "./categories.js";
 export { createVoucher, findPurchaseInvoiceByNumber, findVendorCategoryHistory, findVouchers, uploadVoucherFile, voucherFileIds, } from "./vouchers.js";
-export { SALES_DOCUMENT_STATUSES, VOUCHERLIST_TYPE, countsToTotal, createSalesDocument, findDuplicateSalesDocument, findRecentSalesDocuments, getSalesDocument, invoiceExists, isPricedLine, isPursueRejection, SALES_TEXT_LIMITS, } from "./sales-documents.js";
+export { SALES_DOCUMENT_STATUSES, SALES_TAX_TYPES, VALID_TAX_RATES, VOUCHERLIST_TYPE, countsToTotal, createSalesDocument, isVatFreeTaxType, paymentTermLabel, salesDocumentProblems, findDuplicateSalesDocument, findRecentSalesDocuments, getSalesDocument, invoiceExists, isPricedLine, isPursueRejection, SALES_TEXT_LIMITS, } from "./sales-documents.js";
+export { defaultPaymentCondition, getArticle, getProfile, listCountries, listPaymentConditions, listPrintLayouts, resolvePrintLayout, } from "./settings.js";

package/dist/money.d.ts

@@ -18,8 +18,12 @@ export declare function round2(value: number): number;
 export interface PricedLine {
     quantity: number;
     netPrice: number;
+    /** Discount on the line in percent. */
+    discountPercentage?: number;
 }
-/** Net total of line items, rounded to the cent. */
+/** Net amount of one line after its discount, unrounded. */
+export declare const lineNet: (line: PricedLine) => number;
+/** Net total of line items after their discounts, rounded to the cent. */
 export declare function netTotal(lines: readonly PricedLine[]): number;
 /** Tax contained in a gross amount. */
 export declare function taxFromGross(gross: number, taxRatePercent: number): number;

package/dist/money.js

@@ -16,9 +16,11 @@ export const DUPLICATE_TOTAL_TOLERANCE = 0.02;
 export function round2(value) {
     return Math.round((value + Number.EPSILON) * 100) / 100;
 }
-/** Net total of line items, rounded to the cent. */
+/** Net amount of one line after its discount, unrounded. */
+export const lineNet = (line) => line.quantity * line.netPrice * (1 - (line.discountPercentage ?? 0) / 100);
+/** Net total of line items after their discounts, rounded to the cent. */
 export function netTotal(lines) {
-    return round2(lines.reduce((sum, line) => sum + line.quantity * line.netPrice, 0));
+    return round2(lines.reduce((sum, line) => sum + lineNet(line), 0));
 }
 /** Tax contained in a gross amount. */
 export function taxFromGross(gross, taxRatePercent) {

package/dist/reminder-mail.d.ts

@@ -42,7 +42,7 @@ export declare class MailNotSentError extends Error {
     });
 }
 export interface ReminderSender {
-    /** Signature name, e.g. "Kevin Ludwig". */
+    /** Signature name, e.g. "Max Muster". */
     name: string;
     /** Lines under the name, e.g. the company and town. */
     signature?: readonly string[];

package/dist/sales-documents.d.ts

@@ -13,13 +13,32 @@ export interface PricedLineItem {
     quantity: number;
     /** e.g. "Stück", "Stunde". */
     unit: string;
-    /** Net unit price in EUR. */
+    /**
+     * Net unit price in EUR. On a document with tax type `gross` the totals
+     * still count in net — derive it from `grossPrice` there.
+     */
     netPrice: number;
-    /** 0, 7, or 19. */
+    /** Gross unit price in EUR — sent instead of `netPrice` when the document's tax type is `gross`. */
+    grossPrice?: number;
+    /** See VALID_TAX_RATES; 0 on every vat-free tax type. */
     taxRate: number;
+    /** Discount on this line in percent, up to 2 decimals. */
+    discountPercentage?: number;
+    /**
+     * A product or service from the account's articles. The line still carries
+     * all its fields — they may deviate from the article, which stays as it is.
+     */
+    article?: {
+        id: string;
+        type: "service" | "material";
+    };
     /** Quotations only: printed as "Optionale Position", not part of the total. */
     optional?: boolean;
+    /** Quotations only: alternatives offered instead of this line — printed under it, not part of the total. */
+    alternatives?: readonly AlternativeLineItem[];
 }
+/** An alternative to a priced line of a quotation: priced itself, never optional, without alternatives of its own. */
+export type AlternativeLineItem = Omit<PricedLineItem, "optional" | "alternatives">;
 /** A line without a price: a heading or a paragraph between positions. */
 export interface TextLineItem {
     type: "text";
@@ -35,10 +54,65 @@ export declare const countsToTotal: (item: LineItem) => item is PricedLineItem;
 export declare const SALES_TEXT_LIMITS: {
     readonly introduction: 2000;
     readonly remark: 2000;
+    readonly deliveryTerms: 255;
     readonly title: 25;
     readonly lineItemName: 255;
     readonly lineItemDescription: 2000;
 };
+/**
+ * The tax rates Lexware Office accepts on German sales documents (cookbook
+ * "Rechnungen"). EU destination rates for distance sales come on top, with a
+ * `taxSubType` only.
+ */
+export declare const VALID_TAX_RATES: readonly [0, 5, 7, 16, 19];
+/** How the document is taxed. Every type but `net` and `gross` needs a referenced contact and 0 % on every line. */
+export type SalesTaxType = "net" | "gross" | "vatfree" | "intraCommunitySupply" | "constructionService13b" | "externalService13b" | "thirdPartyCountryService" | "thirdPartyCountryDelivery" | "photovoltaicEquipment";
+export declare const SALES_TAX_TYPES: readonly SalesTaxType[];
+/** Whether a tax type charges no VAT — then every line must carry 0 %. */
+export declare const isVatFreeTaxType: (type: SalesTaxType) => boolean;
+export interface TaxConditions {
+    taxType: SalesTaxType;
+    /** B2C in the EU with `net` or `gross` only. */
+    taxSubType?: "distanceSales" | "electronicServices";
+    /** The printed note on a vat-free type; the account's default when absent. */
+    taxTypeNote?: string;
+}
+export interface PaymentConditions {
+    /** The printed text, e.g. „Zahlbar innerhalb von 14 Tagen ohne Abzug". */
+    paymentTermLabel?: string;
+    /** Days until payment is due. */
+    paymentTermDuration?: number;
+    /** Cash discount for payment within `discountRange` days. */
+    paymentDiscountConditions?: {
+        discountPercentage: number;
+        discountRange: number;
+    };
+}
+/**
+ * When the goods or the service are supplied — the date § 14 (4) No. 6 UStG
+ * asks of an invoice. `none` prints no date. The tax rates valid at
+ * `shippingDate` (a period: `shippingEndDate`) apply.
+ */
+export type ShippingConditions = {
+    shippingType: "service" | "delivery";
+    shippingDate: string;
+} | {
+    shippingType: "serviceperiod" | "deliveryperiod";
+    shippingDate: string;
+    shippingEndDate: string;
+} | {
+    shippingType: "none";
+};
+export type SalesLanguage = "de" | "en";
+/**
+ * The text Lexware Office prints for a payment term, in its own wording:
+ * „Zahlbar sofort, rein netto", „Zahlbar innerhalb von 14 Tagen ohne Abzug",
+ * „10 Tage 2 % Skonto, 30 Tage netto".
+ */
+export declare function paymentTermLabel(days: number, discount?: {
+    percentage: number;
+    days: number;
+}): string;
 /** The type as the voucher list spells it. */
 export declare const VOUCHERLIST_TYPE: Record<SalesDocumentKind, string>;
 /**
@@ -51,35 +125,63 @@ export interface CreatedSalesDocument {
     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. `introduction` and `remark` replace
- * the default texts of the account's settings — left out, the defaults stay.
- * Only quotations know optional lines; on other kinds this throws instead of
- * the API dropping the flag and counting the line.
- *
- * `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: {
+/** What a sales document is created with. Everything optional falls back to Lexware Office's defaults. */
+export interface NewSalesDocument {
     kind: SalesDocumentKind;
     contactId: string;
     items: readonly LineItem[];
+    /** yyyy-MM-dd or a timestamp. Default: now. */
+    voucherDate?: string;
     /** 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. */
+    /** Total discount in EUR. Not together with `totalDiscountPercentage`. */
     totalDiscountAbsolute?: number;
+    /** Total discount in percent of the net (or, on `gross`, the gross) total. Without either, a contact's default discount applies. */
+    totalDiscountPercentage?: number;
+    /** Default: `{ taxType: "net" }`. */
+    taxConditions?: TaxConditions;
+    /** Without them, Lexware takes the contact's payment term, else the account's default. */
+    paymentConditions?: PaymentConditions;
+    /**
+     * Order confirmations and invoices only — quotations have none. Default:
+     * delivery on the voucher date, which is what Lexware prints then.
+     */
+    shippingConditions?: ShippingConditions;
+    /** Print language and language of the default texts. Default: de. */
+    language?: SalesLanguage;
+    /** A print layout from listPrintLayouts; the account's default when absent. */
+    printLayoutId?: string;
+    /** Order confirmations only. Max. 255 characters; the contact's or account's default when absent. */
+    deliveryTerms?: string;
+    /** Invoices to an XRechnung contact: the Leitweg-ID, overriding the contact's. An empty string makes a standard invoice. */
+    xRechnung?: {
+        buyerReference: string;
+    };
     precedingSalesVoucherId?: string;
     /** Opening text; Markdown. Max. 2000 characters. */
     introduction?: string;
     /** Closing text; Markdown. Max. 2000 characters. */
     remark?: string;
-}, signal?: AbortSignal): Promise<CreatedSalesDocument>;
+}
+/**
+ * Creates a sales document. `finalize` gives it a number right away — it can
+ * then no longer be deleted like a draft. Texts, payment conditions, delivery
+ * terms, print layout and total discount left out take the account's (or the
+ * contact's) defaults. Combinations the API documents for another kind only —
+ * optional lines outside a quotation, shipping conditions on one, … — throw
+ * instead of reaching the API, which would drop or reject them.
+ *
+ * `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: NewSalesDocument, signal?: AbortSignal): Promise<CreatedSalesDocument>;
+/** The checks createSalesDocument runs before sending — exported so a caller can run them before an approval. */
+export declare function salesDocumentProblems(options: NewSalesDocument): string[];
 /** 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 {

package/dist/sales-documents.js

@@ -3,12 +3,42 @@
  * 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";
+import { DUPLICATE_TOTAL_TOLERANCE, netTotal, round2 } from "./money.js";
 export const isPricedLine = (item) => item.type !== "text";
 /** Whether a line adds to the document's total: priced and not optional. */
 export const countsToTotal = (item) => isPricedLine(item) && !item.optional;
 /** Lexware's limits for the texts of a sales document (FAQ "Texts in Sales Vouchers"). */
-export const SALES_TEXT_LIMITS = { introduction: 2000, remark: 2000, title: 25, lineItemName: 255, lineItemDescription: 2000 };
+export const SALES_TEXT_LIMITS = { introduction: 2000, remark: 2000, deliveryTerms: 255, title: 25, lineItemName: 255, lineItemDescription: 2000 };
+/**
+ * The tax rates Lexware Office accepts on German sales documents (cookbook
+ * "Rechnungen"). EU destination rates for distance sales come on top, with a
+ * `taxSubType` only.
+ */
+export const VALID_TAX_RATES = [0, 5, 7, 16, 19];
+export const SALES_TAX_TYPES = [
+    "net",
+    "gross",
+    "vatfree",
+    "intraCommunitySupply",
+    "constructionService13b",
+    "externalService13b",
+    "thirdPartyCountryService",
+    "thirdPartyCountryDelivery",
+    "photovoltaicEquipment",
+];
+/** Whether a tax type charges no VAT — then every line must carry 0 %. */
+export const isVatFreeTaxType = (type) => type !== "net" && type !== "gross";
+/**
+ * The text Lexware Office prints for a payment term, in its own wording:
+ * „Zahlbar sofort, rein netto", „Zahlbar innerhalb von 14 Tagen ohne Abzug",
+ * „10 Tage 2 % Skonto, 30 Tage netto".
+ */
+export function paymentTermLabel(days, discount) {
+    if (discount) {
+        return `${discount.days} Tage ${discount.percentage.toLocaleString("de-DE", { maximumFractionDigits: 2 })} % Skonto, ${days} Tage netto`;
+    }
+    return days === 0 ? "Zahlbar sofort, rein netto" : `Zahlbar innerhalb von ${days} ${days === 1 ? "Tag" : "Tagen"} ohne Abzug`;
+}
 const ENDPOINTS = {
     quotation: "/quotations",
     "order-confirmation": "/order-confirmations",
@@ -31,10 +61,11 @@ export const SALES_DOCUMENT_STATUSES = {
 };
 /**
  * Creates a sales document. `finalize` gives it a number right away — it can
- * then no longer be deleted like a draft. `introduction` and `remark` replace
- * the default texts of the account's settings — left out, the defaults stay.
- * Only quotations know optional lines; on other kinds this throws instead of
- * the API dropping the flag and counting the line.
+ * then no longer be deleted like a draft. Texts, payment conditions, delivery
+ * terms, print layout and total discount left out take the account's (or the
+ * contact's) defaults. Combinations the API documents for another kind only —
+ * optional lines outside a quotation, shipping conditions on one, … — throw
+ * instead of reaching the API, which would drop or reject them.
  *
  * `precedingSalesVoucherId` links the document to its predecessor (a pursued
  * quotation becomes accepted) — only as a query parameter; in the body the API
@@ -42,18 +73,27 @@ export const SALES_DOCUMENT_STATUSES = {
  * the new document. An invalid pursue answers 406, see isPursueRejection.
  */
 export async function createSalesDocument(client, options, signal) {
-    if (options.kind !== "quotation" && options.items.some((item) => isPricedLine(item) && item.optional)) {
-        throw new Error(`Optional line items exist only on quotations, not on ${options.kind}`);
-    }
-    const voucherDate = new Date().toISOString().replace("Z", "+00:00");
-    const discount = options.totalDiscountAbsolute ?? 0;
+    assertValidSalesDocument(options);
+    const voucherDate = options.voucherDate ? toIsoDateTime(options.voucherDate) : new Date().toISOString().replace("Z", "+00:00");
+    const taxConditions = options.taxConditions ?? { taxType: "net" };
+    const gross = taxConditions.taxType === "gross";
+    const totalPrice = {
+        currency: "EUR",
+        ...((options.totalDiscountAbsolute ?? 0) > 0 ? { totalDiscountAbsolute: round2(options.totalDiscountAbsolute) } : {}),
+        ...((options.totalDiscountPercentage ?? 0) > 0 ? { totalDiscountPercentage: round2(options.totalDiscountPercentage) } : {}),
+    };
     const payload = {
         voucherDate,
         address: { contactId: options.contactId },
-        lineItems: options.items.map(toApiLine),
-        totalPrice: { currency: "EUR", ...(discount > 0 ? { totalDiscountAbsolute: round2(discount) } : {}) },
-        taxConditions: { taxType: "net" },
-        shippingConditions: { shippingType: "delivery", shippingDate: voucherDate },
+        lineItems: options.items.map((item) => toApiLine(item, gross)),
+        totalPrice,
+        taxConditions,
+        ...(options.kind === "quotation" ? {} : { shippingConditions: toApiShipping(options.shippingConditions, voucherDate) }),
+        ...(options.paymentConditions ? { paymentConditions: options.paymentConditions } : {}),
+        ...(options.language ? { language: options.language } : {}),
+        ...(options.printLayoutId ? { printLayoutId: options.printLayoutId } : {}),
+        ...(options.deliveryTerms ? { deliveryTerms: options.deliveryTerms } : {}),
+        ...(options.xRechnung ? { xRechnung: options.xRechnung } : {}),
         ...(options.title ? { title: options.title } : {}),
         ...(options.expirationDate ? { expirationDate: toIsoDateTime(options.expirationDate) } : {}),
         ...(options.introduction ? { introduction: options.introduction } : {}),
@@ -67,18 +107,95 @@ export async function createSalesDocument(client, options, signal) {
     });
     return { id: result.id, resourceUri: result.resourceUri, url: client.voucherUrl(result.id) };
 }
-function toApiLine(item) {
+/** The checks createSalesDocument runs before sending — exported so a caller can run them before an approval. */
+export function salesDocumentProblems(options) {
+    const problems = [];
+    const { kind } = options;
+    const priced = options.items.filter(isPricedLine);
+    const lines = priced.flatMap((item) => [item, ...(item.alternatives ?? [])]);
+    const taxType = options.taxConditions?.taxType ?? "net";
+    if (kind !== "quotation" && priced.some((item) => item.optional))
+        problems.push(`Optional line items exist only on quotations, not on ${kind}`);
+    if (kind !== "quotation" && priced.some((item) => (item.alternatives?.length ?? 0) > 0))
+        problems.push(`Alternative line items exist only on quotations, not on ${kind}`);
+    if (priced.some((item) => item.optional && (item.alternatives?.length ?? 0) > 0))
+        problems.push("An optional line item cannot have alternatives");
+    if (kind === "quotation" && options.shippingConditions)
+        problems.push("Quotations have no shipping conditions");
+    if (kind !== "order-confirmation" && options.deliveryTerms)
+        problems.push(`Delivery terms exist only on order confirmations, not on ${kind}`);
+    if (kind !== "invoice" && options.xRechnung)
+        problems.push(`XRechnung properties exist only on invoices, not on ${kind}`);
+    if (kind !== "quotation" && options.expirationDate)
+        problems.push(`An expiration date exists only on quotations, not on ${kind}`);
+    if ((options.deliveryTerms?.length ?? 0) > SALES_TEXT_LIMITS.deliveryTerms)
+        problems.push(`Delivery terms longer than ${SALES_TEXT_LIMITS.deliveryTerms} characters`);
+    if ((options.totalDiscountAbsolute ?? 0) > 0 && (options.totalDiscountPercentage ?? 0) > 0)
+        problems.push("Either an absolute or a percentage total discount, not both");
+    if ((options.totalDiscountPercentage ?? 0) > 100)
+        problems.push("A total discount above 100 %");
+    if (isVatFreeTaxType(taxType) && lines.some((item) => item.taxRate !== 0))
+        problems.push(`Tax type ${taxType} needs 0 % on every line`);
+    if (options.taxConditions?.taxSubType && isVatFreeTaxType(taxType))
+        problems.push("A tax subtype goes with net or gross only");
+    if (!options.taxConditions?.taxSubType && lines.some((item) => !VALID_TAX_RATES.includes(item.taxRate))) {
+        problems.push(`Tax rates other than ${VALID_TAX_RATES.join(", ")} % need a tax subtype (EU distance sales)`);
+    }
+    if (taxType === "gross" && lines.some((item) => item.grossPrice === undefined))
+        problems.push("Tax type gross needs a gross price on every priced line");
+    if (lines.some((item) => (item.discountPercentage ?? 0) < 0 || (item.discountPercentage ?? 0) > 100))
+        problems.push("A line discount outside 0–100 %");
+    const shipping = options.shippingConditions;
+    if (shipping && shipping.shippingType !== "none") {
+        if (!isDate(shipping.shippingDate))
+            problems.push(`Shipping date ${shipping.shippingDate} is no date`);
+        if ("shippingEndDate" in shipping) {
+            if (!isDate(shipping.shippingEndDate))
+                problems.push(`Shipping end date ${shipping.shippingEndDate} is no date`);
+            else if (dayOf(shipping.shippingEndDate) < dayOf(shipping.shippingDate))
+                problems.push("The shipping period ends before it starts");
+        }
+    }
+    const payment = options.paymentConditions;
+    if (payment?.paymentDiscountConditions && payment.paymentTermDuration !== undefined && payment.paymentDiscountConditions.discountRange > payment.paymentTermDuration) {
+        problems.push("The cash discount runs longer than the payment term");
+    }
+    return problems;
+}
+function assertValidSalesDocument(options) {
+    const problems = salesDocumentProblems(options);
+    if (problems.length > 0)
+        throw new Error(problems.join("; "));
+}
+const isDate = (value) => !Number.isNaN(new Date(/^\d{4}-\d{2}-\d{2}$/.test(value) ? `${value}T12:00:00Z` : value).getTime());
+const dayOf = (value) => value.slice(0, 10);
+function toApiShipping(shipping, voucherDate) {
+    if (!shipping)
+        return { shippingType: "delivery", shippingDate: voucherDate };
+    if (shipping.shippingType === "none")
+        return { shippingType: "none" };
+    return {
+        shippingType: shipping.shippingType,
+        shippingDate: toIsoDateTime(shipping.shippingDate),
+        ...("shippingEndDate" in shipping ? { shippingEndDate: toIsoDateTime(shipping.shippingEndDate) } : {}),
+    };
+}
+function toApiLine(item, gross) {
     const description = item.description ? { description: item.description } : {};
     if (!isPricedLine(item))
         return { type: "text", name: item.name, ...description };
     return {
-        type: "custom",
+        ...(item.article ? { id: item.article.id, type: item.article.type } : { type: "custom" }),
         name: item.name,
         ...description,
         quantity: item.quantity,
         unitName: item.unit,
-        unitPrice: { currency: "EUR", netAmount: item.netPrice, taxRatePercentage: item.taxRate },
+        unitPrice: gross
+            ? { currency: "EUR", grossAmount: item.grossPrice, taxRatePercentage: item.taxRate }
+            : { currency: "EUR", netAmount: item.netPrice, taxRatePercentage: item.taxRate },
+        ...((item.discountPercentage ?? 0) > 0 ? { discountPercentage: item.discountPercentage } : {}),
         ...(item.optional ? { optional: true } : {}),
+        ...(item.alternatives?.length ? { subItems: item.alternatives.map((alternative) => ({ ...toApiLine(alternative, gross), alternative: true })) } : {}),
     };
 }
 /** Whether a 406 rejects the pursue, not the payload — then a retry without the link makes sense. */
@@ -105,6 +222,7 @@ export async function getSalesDocument(client, kind, id, signal) {
         unit: item.unitName ?? "Stück",
         netPrice: item.unitPrice?.netAmount ?? 0,
         taxRate: item.unitPrice?.taxRatePercentage ?? 19,
+        ...(item.discountPercentage ? { discountPercentage: item.discountPercentage } : {}),
         ...(item.optional ? { optional: true } : {}),
     }));
     const items = priced.filter((item) => !item.optional);
@@ -115,7 +233,7 @@ export async function getSalesDocument(client, kind, id, signal) {
         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)),
+        lineItemsNet: items.length === 0 ? Number.NaN : netTotal(items),
         lineItems: items,
         optionalItems: priced.filter((item) => item.optional),
         hasOptionalOrAlternative: lines.some((item) => item.optional === true || (item.subItems?.length ?? 0) > 0),

package/dist/settings.d.ts

@@ -0,0 +1,68 @@
+/**
+ * Account settings a sales document refers to: print layouts, payment
+ * conditions, the profile's tax setup, countries, articles. Read-only.
+ */
+import { type LexwareClient } from "./client.ts";
+export interface PrintLayout {
+    id: string;
+    name: string;
+    default: boolean;
+}
+export declare function listPrintLayouts(client: LexwareClient, signal?: AbortSignal): Promise<PrintLayout[]>;
+/** A print layout by id or by name (case-insensitive); null if none or several match. */
+export declare function resolvePrintLayout(client: LexwareClient, nameOrId: string, signal?: AbortSignal): Promise<PrintLayout | null>;
+export interface PaymentConditionTemplate {
+    id: string;
+    /** As configured, with placeholders such as {paymentRange}. */
+    paymentTermLabelTemplate: string;
+    paymentTermDuration?: number;
+    paymentDiscountConditions?: {
+        discountPercentage: number;
+        discountRange: number;
+    };
+    organizationDefault: boolean;
+}
+export declare function listPaymentConditions(client: LexwareClient, signal?: AbortSignal): Promise<PaymentConditionTemplate[]>;
+/**
+ * The account's default payment condition — what a document without payment
+ * conditions gets unless its contact has its own (which the API does not
+ * expose). The label with its placeholders filled in.
+ */
+export declare function defaultPaymentCondition(client: LexwareClient, signal?: AbortSignal): Promise<{
+    label: string;
+    duration?: number;
+    discount?: {
+        percentage: number;
+        days: number;
+    };
+} | null>;
+export interface Profile {
+    organizationId: string;
+    companyName?: string;
+    /** The account's tax type: net, gross, or vatfree. */
+    taxType?: "net" | "gross" | "vatfree";
+    /** Kleinunternehmer according to § 19 UStG. */
+    smallBusiness?: boolean;
+    distanceSalesPrinciple?: "ORIGIN" | "DESTINATION";
+}
+export declare function getProfile(client: LexwareClient, signal?: AbortSignal): Promise<Profile>;
+export type CountryTaxClassification = "de" | "intraCommunity" | "thirdPartyCountry";
+export interface Country {
+    countryCode: string;
+    countryNameDE?: string;
+    countryNameEN?: string;
+    taxClassification: CountryTaxClassification;
+}
+export declare function listCountries(client: LexwareClient, signal?: AbortSignal): Promise<Country[]>;
+export interface Article {
+    id: string;
+    title: string;
+    /** As a line item spells it. */
+    lineType: "service" | "material";
+    articleNumber?: string;
+    unitName?: string;
+    netPrice?: number;
+    grossPrice?: number;
+    taxRate?: number;
+}
+export declare function getArticle(client: LexwareClient, id: string, signal?: AbortSignal): Promise<Article>;

package/dist/settings.js

@@ -0,0 +1,60 @@
+/**
+ * Account settings a sales document refers to: print layouts, payment
+ * conditions, the profile's tax setup, countries, articles. Read-only.
+ */
+import {} from "./client.js";
+export async function listPrintLayouts(client, signal) {
+    return (await client.request("/print-layouts", { signal })) ?? [];
+}
+/** A print layout by id or by name (case-insensitive); null if none or several match. */
+export async function resolvePrintLayout(client, nameOrId, signal) {
+    const needle = nameOrId.trim().toLowerCase();
+    const layouts = await listPrintLayouts(client, signal);
+    const byId = layouts.find((layout) => layout.id.toLowerCase() === needle);
+    if (byId)
+        return byId;
+    const byName = layouts.filter((layout) => layout.name.trim().toLowerCase() === needle);
+    return byName.length === 1 ? byName[0] : null;
+}
+export async function listPaymentConditions(client, signal) {
+    return (await client.request("/payment-conditions", { signal })) ?? [];
+}
+/**
+ * The account's default payment condition — what a document without payment
+ * conditions gets unless its contact has its own (which the API does not
+ * expose). The label with its placeholders filled in.
+ */
+export async function defaultPaymentCondition(client, signal) {
+    const found = (await listPaymentConditions(client, signal)).find((condition) => condition.organizationDefault);
+    if (!found)
+        return null;
+    const discount = found.paymentDiscountConditions;
+    const label = found.paymentTermLabelTemplate
+        .replace(/\{paymentRange\}/g, String(found.paymentTermDuration ?? ""))
+        .replace(/\{discountRange\}/g, String(discount?.discountRange ?? ""))
+        .replace(/\{discount\}/g, discount ? `${discount.discountPercentage.toLocaleString("de-DE", { maximumFractionDigits: 2 })} %` : "");
+    return {
+        label,
+        ...(found.paymentTermDuration !== undefined ? { duration: found.paymentTermDuration } : {}),
+        ...(discount ? { discount: { percentage: discount.discountPercentage, days: discount.discountRange } } : {}),
+    };
+}
+export async function getProfile(client, signal) {
+    return client.request("/profile", { signal });
+}
+export async function listCountries(client, signal) {
+    return (await client.request("/countries", { signal })) ?? [];
+}
+export async function getArticle(client, id, signal) {
+    const raw = await client.request(`/articles/${encodeURIComponent(id)}`, { signal });
+    return {
+        id: raw.id,
+        title: raw.title ?? "",
+        lineType: raw.type === "PRODUCT" ? "material" : "service",
+        ...(raw.articleNumber ? { articleNumber: raw.articleNumber } : {}),
+        ...(raw.unitName ? { unitName: raw.unitName } : {}),
+        ...(raw.price?.netPrice !== undefined ? { netPrice: raw.price.netPrice } : {}),
+        ...(raw.price?.grossPrice !== undefined ? { grossPrice: raw.price.grossPrice } : {}),
+        ...(raw.price?.taxRate !== undefined ? { taxRate: raw.price.taxRate } : {}),
+    };
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@kevludwig/lexware-office",
-  "version": "0.2.0",
+  "version": "0.4.0",
   "description": "Typed client and domain logic for the Lexware Office Public API: contacts, receivables, payment reminder rules.",
   "type": "module",
   "license": "MIT",