@stackforge-eu/factur-x 1.3.1 → 1.4.0

package/CHANGELOG.md

@@ -7,6 +7,16 @@ and this project adheres to [Semantic Versioning](https://semver.org/).
 
 ## [Unreleased]
 
+## [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 +245,7 @@ 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.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

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.

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.

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

package/package.json

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