@stackforge-eu/factur-x 1.3.1 → 1.4.1

package/CHANGELOG.md

@@ -7,6 +7,28 @@ and this project adheres to [Semantic Versioning](https://semver.org/).
 
 ## [Unreleased]
 
+## [1.4.1] — 2026-09-14
+
+- **Added the rounding amount (BT-114).** A new optional `roundingAmount`
+  field on `InvoiceTotalsInput` emits `ram:RoundingAmount` between the tax
+  total and the grand total, so an invoice can state the amount that takes
+  the grand total (BT-112) to the payable figure (BT-115). Emitted for
+  EN 16931 and EXTENDED only, as the lower-profile XSDs do not define the
+  element. `validateInput` now also checks BR-CO-16
+  (`duePayableAmount = grandTotal - prepaidAmount + roundingAmount`), which
+  the schematron already enforced. Omitting the field keeps the output
+  byte-for-byte identical (#17).
+
+## [1.4.0] — 2026-09-03
+
+- **Added the item price discount (BT-147).** A new optional `priceDiscount`
+  field on `InvoiceLineInput` emits `ram:AppliedTradeAllowanceCharge` inside
+  the gross price element, so a line can state the discount that connects the
+  gross unit price (BT-148) to the net unit price (BT-146) instead of leaving
+  it implied by their difference. Requires `grossUnitPrice` to be set; the
+  amount keeps up to four decimals for sub-cent discounts. Omitting the field
+  keeps the output byte-for-byte identical (#15).
+
 ## [1.3.1] — 2026-09-01
 
 - **Dropped the unused `schema/cii-d22b/` code-list XSDs from the npm and JSR
@@ -235,6 +257,8 @@ This element is not expected`. Reordered the three blocks in
 - Deno compatibility test suite
 
 [Unreleased]: https://github.com/StackForge-EU/factur-x/commits/main
+[1.4.1]: https://github.com/StackForge-EU/factur-x/compare/v1.4.0...v1.4.1
+[1.4.0]: https://github.com/StackForge-EU/factur-x/compare/v1.3.1...v1.4.0
 [1.3.1]: https://github.com/StackForge-EU/factur-x/compare/v1.3.0...v1.3.1
 [1.3.0]: https://github.com/StackForge-EU/factur-x/compare/v1.2.1...v1.3.0
 [1.2.1]: https://github.com/StackForge-EU/factur-x/compare/v1.2.0...v1.2.1

package/dist/index.cjs

@@ -307,6 +307,12 @@ function fmtAmt(n) {
   }
   return n.toFixed(2);
 }
+function fmtPrice(n) {
+  if (!Number.isFinite(n)) {
+    throw new Error(`Invalid amount value: ${n}. Expected a finite number.`);
+  }
+  return n.toFixed(4).replace(/(\.\d{2}\d*?)0+$/, "$1");
+}
 function tag(name, content, attrs) {
   const a = attrs ? Object.entries(attrs).map(([k, v]) => ` ${k}="${escapeXml(v)}"`).join("") : "";
   return `<${name}${a}>${content}</${name}>`;
@@ -406,11 +412,21 @@ function buildLineItem(line, profile) {
   const basisQuantity = line.basisQuantity !== void 0 ? tag("ram:BasisQuantity", line.basisQuantity.toString(), {
     unitCode: line.basisQuantityUnitCode ?? unitCode
   }) : "";
-  if (line.grossUnitPrice !== void 0)
+  if (line.priceDiscount !== void 0 && line.grossUnitPrice === void 0) {
+    throw new Error(
+      `buildXml: line "${line.id}" sets "priceDiscount" (BT-147) without "grossUnitPrice" (BT-148).`
+    );
+  }
+  if (line.grossUnitPrice !== void 0) {
+    const discount = line.priceDiscount !== void 0 ? tag(
+      "ram:AppliedTradeAllowanceCharge",
+      tag("ram:ChargeIndicator", tag("udt:Indicator", "false")) + tag("ram:ActualAmount", fmtPrice(line.priceDiscount))
+    ) : "";
     agree += tag(
       "ram:GrossPriceProductTradePrice",
-      tag("ram:ChargeAmount", fmtAmt(line.grossUnitPrice)) + basisQuantity
+      tag("ram:ChargeAmount", fmtAmt(line.grossUnitPrice)) + basisQuantity + discount
     );
+  }
   agree += tag(
     "ram:NetPriceProductTradePrice",
     tag("ram:ChargeAmount", fmtAmt(line.unitPrice)) + basisQuantity
@@ -480,6 +496,8 @@ function buildMonetarySummation(t, profile) {
   x += tag("ram:TaxTotalAmount", fmtAmt(t.taxTotal), {
     currencyID: t.currency
   });
+  if (atLeast(profile, "EN16931" /* EN16931 */) && t.roundingAmount !== void 0)
+    x += tag("ram:RoundingAmount", fmtAmt(t.roundingAmount));
   x += tag("ram:GrandTotalAmount", fmtAmt(t.grandTotal));
   if (atLeast(profile, "BASIC_WL" /* BASIC_WL */) && t.prepaidAmount !== void 0)
     x += tag("ram:TotalPrepaidAmount", fmtAmt(t.prepaidAmount));
@@ -920,6 +938,22 @@ function validateInput(input, profile, flavor) {
       }
     }
   }
+  if (req("BASIC_WL" /* BASIC_WL */) && input.totals) {
+    const t = input.totals;
+    if (t.grandTotal != null && t.duePayableAmount != null) {
+      const prepaid = t.prepaidAmount ?? 0;
+      const rounding = t.roundingAmount ?? 0;
+      const expected = round2(t.grandTotal - prepaid + rounding);
+      if (Math.abs(round2(t.duePayableAmount) - expected) > 0.01) {
+        addError(
+          errors,
+          "totals.duePayableAmount",
+          `duePayableAmount ${t.duePayableAmount} does not equal grandTotal - prepaidAmount + roundingAmount (${expected}) (BR-CO-16).`,
+          "BASIC_WL" /* BASIC_WL */
+        );
+      }
+    }
+  }
   if (req("BASIC_WL" /* BASIC_WL */) && input.totals) {
     const t = input.totals;
     if (t.lineTotal != null && t.taxBasisTotal != null) {

package/dist/index.d.cts

@@ -573,6 +573,14 @@ interface InvoiceLineInput {
      * @see EN 16931 BT-148
      */
     grossUnitPrice?: number;
+    /**
+     * Item price discount — the amount subtracted from `grossUnitPrice`
+     * (BT-148) to arrive at `unitPrice` (BT-146). Emitted as
+     * `ram:AppliedTradeAllowanceCharge` inside the gross price element,
+     * so `grossUnitPrice` must be set alongside it.
+     * @see EN 16931 BT-147
+     */
+    priceDiscount?: number;
     /**
      * Item price base quantity — the quantity the unit price (BT-146)
      * applies to, e.g. a price per 10 square metres or per 1000 prints.
@@ -851,6 +859,14 @@ interface InvoiceTotalsInput {
      * @see EN 16931 BT-113
      */
     prepaidAmount?: number;
+    /**
+     * Rounding amount — the amount added to the grand total (BT-112) to round
+     * the amount due (BT-115) to a payable figure, e.g. `0.02` to take
+     * `29.95` to `29.97`. Emitted as `ram:RoundingAmount` for EN 16931 and
+     * EXTENDED only; the BASIC / BASIC WL XSDs do not define the element.
+     * @see EN 16931 BT-114, BR-CO-16
+     */
+    roundingAmount?: number;
     /**
      * Due payable amount.
      * @see EN 16931 BT-115

package/dist/index.d.ts

@@ -573,6 +573,14 @@ interface InvoiceLineInput {
      * @see EN 16931 BT-148
      */
     grossUnitPrice?: number;
+    /**
+     * Item price discount — the amount subtracted from `grossUnitPrice`
+     * (BT-148) to arrive at `unitPrice` (BT-146). Emitted as
+     * `ram:AppliedTradeAllowanceCharge` inside the gross price element,
+     * so `grossUnitPrice` must be set alongside it.
+     * @see EN 16931 BT-147
+     */
+    priceDiscount?: number;
     /**
      * Item price base quantity — the quantity the unit price (BT-146)
      * applies to, e.g. a price per 10 square metres or per 1000 prints.
@@ -851,6 +859,14 @@ interface InvoiceTotalsInput {
      * @see EN 16931 BT-113
      */
     prepaidAmount?: number;
+    /**
+     * Rounding amount — the amount added to the grand total (BT-112) to round
+     * the amount due (BT-115) to a payable figure, e.g. `0.02` to take
+     * `29.95` to `29.97`. Emitted as `ram:RoundingAmount` for EN 16931 and
+     * EXTENDED only; the BASIC / BASIC WL XSDs do not define the element.
+     * @see EN 16931 BT-114, BR-CO-16
+     */
+    roundingAmount?: number;
     /**
      * Due payable amount.
      * @see EN 16931 BT-115

package/dist/index.js

@@ -277,6 +277,12 @@ function fmtAmt(n) {
   }
   return n.toFixed(2);
 }
+function fmtPrice(n) {
+  if (!Number.isFinite(n)) {
+    throw new Error(`Invalid amount value: ${n}. Expected a finite number.`);
+  }
+  return n.toFixed(4).replace(/(\.\d{2}\d*?)0+$/, "$1");
+}
 function tag(name, content, attrs) {
   const a = attrs ? Object.entries(attrs).map(([k, v]) => ` ${k}="${escapeXml(v)}"`).join("") : "";
   return `<${name}${a}>${content}</${name}>`;
@@ -376,11 +382,21 @@ function buildLineItem(line, profile) {
   const basisQuantity = line.basisQuantity !== void 0 ? tag("ram:BasisQuantity", line.basisQuantity.toString(), {
     unitCode: line.basisQuantityUnitCode ?? unitCode
   }) : "";
-  if (line.grossUnitPrice !== void 0)
+  if (line.priceDiscount !== void 0 && line.grossUnitPrice === void 0) {
+    throw new Error(
+      `buildXml: line "${line.id}" sets "priceDiscount" (BT-147) without "grossUnitPrice" (BT-148).`
+    );
+  }
+  if (line.grossUnitPrice !== void 0) {
+    const discount = line.priceDiscount !== void 0 ? tag(
+      "ram:AppliedTradeAllowanceCharge",
+      tag("ram:ChargeIndicator", tag("udt:Indicator", "false")) + tag("ram:ActualAmount", fmtPrice(line.priceDiscount))
+    ) : "";
     agree += tag(
       "ram:GrossPriceProductTradePrice",
-      tag("ram:ChargeAmount", fmtAmt(line.grossUnitPrice)) + basisQuantity
+      tag("ram:ChargeAmount", fmtAmt(line.grossUnitPrice)) + basisQuantity + discount
     );
+  }
   agree += tag(
     "ram:NetPriceProductTradePrice",
     tag("ram:ChargeAmount", fmtAmt(line.unitPrice)) + basisQuantity
@@ -450,6 +466,8 @@ function buildMonetarySummation(t, profile) {
   x += tag("ram:TaxTotalAmount", fmtAmt(t.taxTotal), {
     currencyID: t.currency
   });
+  if (atLeast(profile, "EN16931" /* EN16931 */) && t.roundingAmount !== void 0)
+    x += tag("ram:RoundingAmount", fmtAmt(t.roundingAmount));
   x += tag("ram:GrandTotalAmount", fmtAmt(t.grandTotal));
   if (atLeast(profile, "BASIC_WL" /* BASIC_WL */) && t.prepaidAmount !== void 0)
     x += tag("ram:TotalPrepaidAmount", fmtAmt(t.prepaidAmount));
@@ -890,6 +908,22 @@ function validateInput(input, profile, flavor) {
       }
     }
   }
+  if (req("BASIC_WL" /* BASIC_WL */) && input.totals) {
+    const t = input.totals;
+    if (t.grandTotal != null && t.duePayableAmount != null) {
+      const prepaid = t.prepaidAmount ?? 0;
+      const rounding = t.roundingAmount ?? 0;
+      const expected = round2(t.grandTotal - prepaid + rounding);
+      if (Math.abs(round2(t.duePayableAmount) - expected) > 0.01) {
+        addError(
+          errors,
+          "totals.duePayableAmount",
+          `duePayableAmount ${t.duePayableAmount} does not equal grandTotal - prepaidAmount + roundingAmount (${expected}) (BR-CO-16).`,
+          "BASIC_WL" /* BASIC_WL */
+        );
+      }
+    }
+  }
   if (req("BASIC_WL" /* BASIC_WL */) && input.totals) {
     const t = input.totals;
     if (t.lineTotal != null && t.taxBasisTotal != null) {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@stackforge-eu/factur-x",
-  "version": "1.3.1",
+  "version": "1.4.1",
   "type": "module",
   "description": "Embed Factur-X, ZUGFeRD, and XRechnung structured invoice XML into PDF/A-3 documents",
   "keywords": [