@kevludwig/lexware-office 0.1.3 → 0.2.0

package/README.md

@@ -36,7 +36,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, 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.
+**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.
 
 **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/index.d.ts

@@ -2,10 +2,10 @@ export { DEFAULT_APP_URL, DEFAULT_BASE_URL, LexwareApiError, createLexwareClient
 export { contactEmail, createCustomer, findContactByNumber, findContactsByName, MIN_NAME_SEARCH_LENGTH, 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, mailContentSha256, sendReminder, type ReminderTarget, type SendReminderOutcome, } from "./reminders.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, 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 { 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, createSalesDocument, findDuplicateSalesDocument, findRecentSalesDocuments, getSalesDocument, invoiceExists, isPursueRejection, type CreatedSalesDocument, type DuplicateSearchResult, type LineItem, type SalesDocumentDetail, type SalesDocumentKind, type SalesListEntry, } from "./sales-documents.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";

package/dist/index.js

@@ -2,10 +2,10 @@ export { DEFAULT_APP_URL, DEFAULT_BASE_URL, LexwareApiError, createLexwareClient
 export { contactEmail, createCustomer, findContactByNumber, findContactsByName, MIN_NAME_SEARCH_LENGTH, getContact, resolveContactByName, } from "./contacts.js";
 export { addDays, berlinDay, daysSince } from "./dates.js";
 export { downloadInvoicePdf, findOverdueInvoice, findOverdueInvoices, } from "./receivables.js";
-export { DEFAULT_REMINDER_POLICY, daysPastReminderDue, earliestReminderDate, isDueImmediately, isOpenForReminder, reminderDueDate, reminderLedger, selectDueReminders, mailContentSha256, sendReminder, } from "./reminders.js";
+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 { 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, createSalesDocument, findDuplicateSalesDocument, findRecentSalesDocuments, getSalesDocument, invoiceExists, isPursueRejection, } from "./sales-documents.js";
+export { SALES_DOCUMENT_STATUSES, VOUCHERLIST_TYPE, countsToTotal, createSalesDocument, findDuplicateSalesDocument, findRecentSalesDocuments, getSalesDocument, invoiceExists, isPricedLine, isPursueRejection, SALES_TEXT_LIMITS, } from "./sales-documents.js";

package/dist/reminders.d.ts

@@ -140,6 +140,34 @@ export type SendReminderOutcome = {
     sent: false;
     reason: "paid" | "taken";
 };
+/**
+ * What a sent payment reminder did, in a fixed shape an app's protocol keeps
+ * as it is. `amount` and `contentSha256` are null only when the effect is
+ * reconstructed after the fact and they are no longer known — never guessed.
+ */
+export interface PaymentReminderEffect {
+    kind: "payment_reminder";
+    to: string;
+    cc: string[];
+    test: boolean;
+    /** The invoice's voucher number. */
+    invoice: string;
+    invoiceId: string;
+    /** The open amount the mail stated. */
+    amount: number | null;
+    currency: string;
+    /** sha256 of the mail's content, see mailContentSha256. */
+    contentSha256: string | null;
+}
+/**
+ * The effect of a reminder sent to `target`. Pass the send's outcome; pass
+ * null to reconstruct it from the target alone, which leaves amount and hash
+ * unknown (null).
+ */
+export declare function paymentReminderEffect(target: ReminderTarget, sent: {
+    openAmount: number;
+    contentSha256: string;
+} | null): PaymentReminderEffect;
 /**
  * Sends one reminder, at most once per round: re-checks that the invoice is
  * still overdue, claims the round, renders and sends with the invoice PDF,

package/dist/reminders.js

@@ -122,6 +122,24 @@ export async function selectDueReminders(client, ledger, options = {}) {
         held: checked.flatMap(({ invoice, hold }) => (hold ? [{ invoice, hold }] : [])),
     };
 }
+/**
+ * The effect of a reminder sent to `target`. Pass the send's outcome; pass
+ * null to reconstruct it from the target alone, which leaves amount and hash
+ * unknown (null).
+ */
+export function paymentReminderEffect(target, sent) {
+    return {
+        kind: "payment_reminder",
+        to: target.to,
+        cc: [...(target.cc ?? [])],
+        test: target.test,
+        invoice: target.voucherNumber,
+        invoiceId: target.invoiceId,
+        amount: sent?.openAmount ?? null,
+        currency: target.currency,
+        contentSha256: sent?.contentSha256 ?? null,
+    };
+}
 /**
  * Sends one reminder, at most once per round: re-checks that the invoice is
  * still overdue, claims the round, renders and sends with the invoice PDF,

package/dist/sales-documents.d.ts

@@ -4,9 +4,12 @@
  */
 import { type LexwareClient } from "./client.ts";
 export type SalesDocumentKind = "quotation" | "order-confirmation" | "invoice";
-/** One line of a sales document. */
-export interface LineItem {
+/** A line with a price — counts towards the total unless it is optional. */
+export interface PricedLineItem {
+    type?: "custom";
     name: string;
+    /** Free text under the name; Markdown (bold, italic, lists). Max. 2000 characters. */
+    description?: string;
     quantity: number;
     /** e.g. "Stück", "Stunde". */
     unit: string;
@@ -14,7 +17,28 @@ export interface LineItem {
     netPrice: number;
     /** 0, 7, or 19. */
     taxRate: number;
+    /** Quotations only: printed as "Optionale Position", not part of the total. */
+    optional?: boolean;
+}
+/** A line without a price: a heading or a paragraph between positions. */
+export interface TextLineItem {
+    type: "text";
+    name: string;
+    description?: string;
 }
+/** One line of a sales document. */
+export type LineItem = PricedLineItem | TextLineItem;
+export declare const isPricedLine: (item: LineItem) => item is PricedLineItem;
+/** Whether a line adds to the document's total: priced and not optional. */
+export declare const countsToTotal: (item: LineItem) => item is PricedLineItem;
+/** Lexware's limits for the texts of a sales document (FAQ "Texts in Sales Vouchers"). */
+export declare const SALES_TEXT_LIMITS: {
+    readonly introduction: 2000;
+    readonly remark: 2000;
+    readonly title: 25;
+    readonly lineItemName: 255;
+    readonly lineItemDescription: 2000;
+};
 /** The type as the voucher list spells it. */
 export declare const VOUCHERLIST_TYPE: Record<SalesDocumentKind, string>;
 /**
@@ -29,8 +53,10 @@ export interface CreatedSalesDocument {
 }
 /**
  * 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.
+ * 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
@@ -49,6 +75,10 @@ export declare function createSalesDocument(client: LexwareClient, options: {
     /** Total discount in EUR on the net amount. */
     totalDiscountAbsolute?: number;
     precedingSalesVoucherId?: string;
+    /** Opening text; Markdown. Max. 2000 characters. */
+    introduction?: string;
+    /** Closing text; Markdown. Max. 2000 characters. */
+    remark?: 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;
@@ -59,16 +89,24 @@ export interface SalesDocumentDetail {
     voucherStatus?: string;
     contactId?: string;
     contactName?: string;
-    /** Net total over the priced lines — NaN for a document without any. */
+    /** Net total over the lines that count (priced, not optional) — NaN for a document without any. */
     lineItemsNet: number;
-    lineItems: LineItem[];
+    /** The lines that count towards the total. */
+    lineItems: PricedLineItem[];
+    /** Optional lines (quotations) — not in the total. */
+    optionalItems: PricedLineItem[];
+    /**
+     * Optional or alternative lines — an order confirmation cannot be pursued
+     * from such a quotation (the API answers 406).
+     */
+    hasOptionalOrAlternative: boolean;
     /** 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. */
+/** A document reduced to the fields a comparison needs. Text lines (no price) are left out, optional ones kept apart. */
 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>;

package/dist/sales-documents.js

@@ -4,6 +4,11 @@
  */
 import { LexwareApiError, query } from "./client.js";
 import { DUPLICATE_TOTAL_TOLERANCE, 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 };
 const ENDPOINTS = {
     quotation: "/quotations",
     "order-confirmation": "/order-confirmations",
@@ -26,8 +31,10 @@ 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. Neither `introduction` nor `remark`
- * is set: a value would replace the default texts of the account's settings.
+ * 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
@@ -35,23 +42,22 @@ 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;
     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 },
-        })),
+        lineItems: options.items.map(toApiLine),
         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) } : {}),
+        ...(options.introduction ? { introduction: options.introduction } : {}),
+        ...(options.remark ? { remark: options.remark } : {}),
     };
     const params = query({ finalize: options.finalize ? true : undefined, precedingSalesVoucherId: options.precedingSalesVoucherId });
     const result = await client.request(`${ENDPOINTS[options.kind]}${params}`, {
@@ -61,6 +67,20 @@ export async function createSalesDocument(client, options, signal) {
     });
     return { id: result.id, resourceUri: result.resourceUri, url: client.voucherUrl(result.id) };
 }
+function toApiLine(item) {
+    const description = item.description ? { description: item.description } : {};
+    if (!isPricedLine(item))
+        return { type: "text", name: item.name, ...description };
+    return {
+        type: "custom",
+        name: item.name,
+        ...description,
+        quantity: item.quantity,
+        unitName: item.unit,
+        unitPrice: { currency: "EUR", netAmount: item.netPrice, taxRatePercentage: item.taxRate },
+        ...(item.optional ? { optional: true } : {}),
+    };
+}
 /** 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);
@@ -72,18 +92,22 @@ function toIsoDateTime(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. */
+/** A document reduced to the fields a comparison needs. Text lines (no price) are left out, optional ones kept apart. */
 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)
+    const lines = raw.lineItems ?? [];
+    const priced = lines
+        .filter((item) => item.type !== "text" && item.unitPrice !== undefined)
         .map((item) => ({
         name: item.name ?? "",
+        ...(item.description ? { description: item.description } : {}),
         quantity: item.quantity ?? 0,
         unit: item.unitName ?? "Stück",
         netPrice: item.unitPrice?.netAmount ?? 0,
         taxRate: item.unitPrice?.taxRatePercentage ?? 19,
+        ...(item.optional ? { optional: true } : {}),
     }));
+    const items = priced.filter((item) => !item.optional);
     return {
         id: raw.id,
         url: client.voucherUrl(raw.id),
@@ -93,6 +117,8 @@ export async function getSalesDocument(client, kind, id, signal) {
         contactName: raw.address?.name,
         lineItemsNet: items.length === 0 ? Number.NaN : round2(items.reduce((sum, item) => sum + item.quantity * item.netPrice, 0)),
         lineItems: items,
+        optionalItems: priced.filter((item) => item.optional),
+        hasOptionalOrAlternative: lines.some((item) => item.optional === true || (item.subItems?.length ?? 0) > 0),
         totalNet: raw.totalPrice?.totalNetAmount,
         discountAbsolute: raw.totalPrice?.totalDiscountAbsolute,
         discountPercentage: raw.totalPrice?.totalDiscountPercentage,

package/package.json

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