@stackforge-eu/factur-x 1.4.3 → 1.4.5

package/CHANGELOG.md

@@ -7,6 +7,33 @@ and this project adheres to [Semantic Versioning](https://semver.org/).
 
 ## [Unreleased]
 
+## [1.4.5] — 2026-11-14
+
+- **Fixed derived line net amount ignoring `basisQuantity`.** When a line
+  omits `lineTotal`, `buildXml` and the BR-CO-10 check in `validateInput`
+  computed it as `quantity * unitPrice`, so a price per 100 units produced a
+  line total 100× too high and a correct `totals.lineTotal` was rejected. The
+  amount is now `quantity * unitPrice / basisQuantity` (EN 16931 BT-131),
+  rounded per line in both places. Reported by @trackoor (#26).
+- **`validateInput` rejects a `basisQuantity` that is not greater than zero.**
+
+## [1.4.4] — 2026-11-09
+
+- **Fixed header reference element order.** `buildXml` emitted
+  `input.references` in input order, so an `order` reference listed before a
+  `seller-order` (or `contract`) reference produced XML that failed XSD
+  validation. References are now emitted in the CII sequence (SellerOrder →
+  BuyerOrder → Contract → SpecifiedProcuringProject); input order is only
+  kept among references of the same type. Reported by @SCPAU100 (#23).
+- **Fixed `project` references failing XSD validation.** `SpecifiedProcuringProject`
+  requires a `ram:Name` child that was never emitted. A new optional `name`
+  field on `DocumentReferenceInput` fills it, defaulting to `"Project"`.
+- **`validateInput` rejects duplicate single-occurrence references.** The
+  schema allows `order`, `contract`, `seller-order`, `project` and `despatch`
+  references at most once each, and `delivery.despatchAdviceReference` and a
+  `despatch` reference target the same element. Both cases used to surface
+  only as an XSD error after building.
+
 ## [1.4.3] — 2026-09-28
 
 - **Fixed half-cent rounding.** `Math.round(n * 100) / 100` turns
@@ -274,6 +301,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.5]: https://github.com/StackForge-EU/factur-x/compare/v1.4.4...v1.4.5
+[1.4.4]: https://github.com/StackForge-EU/factur-x/compare/v1.4.3...v1.4.4
 [1.4.3]: https://github.com/StackForge-EU/factur-x/compare/v1.4.2...v1.4.3
 [1.4.2]: https://github.com/StackForge-EU/factur-x/compare/v1.4.1...v1.4.2
 [1.4.1]: https://github.com/StackForge-EU/factur-x/compare/v1.4.0...v1.4.1

package/dist/index.cjs

@@ -289,6 +289,9 @@ function toCents(n) {
 function roundHalfUp(n) {
   return toCents(n) / 100;
 }
+function deriveLineNet(line) {
+  return roundHalfUp(line.quantity * line.unitPrice / (line.basisQuantity ?? 1));
+}
 
 // src/core/xml-builder.ts
 var PROFILE_LEVEL = {
@@ -451,7 +454,7 @@ function buildLineItem(line, profile) {
       tx += tag("ram:RateApplicablePercent", line.vatRatePercent.toString());
     settle += tag("ram:ApplicableTradeTax", tx);
   }
-  const lineTotal = line.lineTotal ?? roundHalfUp(line.quantity * line.unitPrice);
+  const lineTotal = line.lineTotal ?? deriveLineNet(line);
   settle += tag(
     "ram:SpecifiedTradeSettlementLineMonetarySummation",
     tag("ram:LineTotalAmount", fmtAmt(lineTotal))
@@ -570,27 +573,21 @@ function buildXml(input, profile, flavor) {
       buildParty(input.sellerTaxRepresentative, profile)
     );
   if (input.references && atLeast(profile, "BASIC_WL" /* BASIC_WL */)) {
-    for (const ref of input.references) {
-      const refType = ref.type ?? "order";
-      if (refType === "preceding" || refType === "despatch") continue;
-      const inner = tag("ram:IssuerAssignedID", escapeXml(ref.id)) + (ref.issueDate ? dateEl("ram:FormattedIssueDateTime", ref.issueDate) : "");
-      switch (refType) {
-        case "order":
-          agree += tag("ram:BuyerOrderReferencedDocument", inner);
-          break;
-        case "contract":
-          agree += tag("ram:ContractReferencedDocument", inner);
-          break;
-        case "seller-order":
-          if (atLeast(profile, "EN16931" /* EN16931 */))
-            agree += tag("ram:SellerOrderReferencedDocument", inner);
-          break;
-        case "project":
-          if (atLeast(profile, "EN16931" /* EN16931 */))
-            agree += tag("ram:SpecifiedProcuringProject", tag("ram:ID", escapeXml(ref.id)));
-          break;
-      }
-    }
+    const refsOfType = (type) => input.references.filter((ref) => (ref.type ?? "order") === type);
+    const refDoc = (ref) => tag("ram:IssuerAssignedID", escapeXml(ref.id)) + (ref.issueDate ? dateEl("ram:FormattedIssueDateTime", ref.issueDate) : "");
+    if (atLeast(profile, "EN16931" /* EN16931 */))
+      for (const ref of refsOfType("seller-order"))
+        agree += tag("ram:SellerOrderReferencedDocument", refDoc(ref));
+    for (const ref of refsOfType("order"))
+      agree += tag("ram:BuyerOrderReferencedDocument", refDoc(ref));
+    for (const ref of refsOfType("contract"))
+      agree += tag("ram:ContractReferencedDocument", refDoc(ref));
+    if (atLeast(profile, "EN16931" /* EN16931 */))
+      for (const ref of refsOfType("project"))
+        agree += tag(
+          "ram:SpecifiedProcuringProject",
+          tag("ram:ID", escapeXml(ref.id)) + tag("ram:Name", escapeXml(ref.name ?? "Project"))
+        );
   }
   tx += tag("ram:ApplicableHeaderTradeAgreement", agree);
   let del = "";
@@ -885,6 +882,14 @@ function validateInput(input, profile, flavor) {
         if (line.unitPrice == null) {
           addError(errors, `lines[${i}].unitPrice`, "Line unit price is required", "BASIC" /* BASIC */);
         }
+        if (line.basisQuantity != null && !(line.basisQuantity > 0)) {
+          addError(
+            errors,
+            `lines[${i}].basisQuantity`,
+            "Line price base quantity (BT-149) must be greater than zero",
+            "BASIC" /* BASIC */
+          );
+        }
       });
     }
   }
@@ -981,8 +986,8 @@ function validateInput(input, profile, flavor) {
   }
   if (req("BASIC" /* BASIC */) && input.totals && input.lines) {
     const sumLineNets = input.lines.reduce((sum, l) => {
-      const lineNet = l.lineTotal ?? (typeof l.quantity === "number" && typeof l.unitPrice === "number" ? l.quantity * l.unitPrice : 0);
-      return sum + lineNet;
+      const lineNet = l.lineTotal ?? deriveLineNet(l);
+      return sum + (Number.isFinite(lineNet) ? lineNet : 0);
     }, 0);
     if (input.totals.lineTotal != null) {
       if (amountsDiffer(input.totals.lineTotal, sumLineNets)) {
@@ -1036,6 +1041,28 @@ function validateInput(input, profile, flavor) {
       }
     }
   }
+  if (req("BASIC_WL" /* BASIC_WL */) && input.references) {
+    const singleOccurrence = ["order", "contract", "seller-order", "project", "despatch"];
+    for (const type of singleOccurrence) {
+      const count = input.references.filter((ref) => (ref.type ?? "order") === type).length;
+      if (count > 1) {
+        addError(
+          errors,
+          "references",
+          `Only one "${type}" reference is allowed, got ${count}.`,
+          "BASIC_WL" /* BASIC_WL */
+        );
+      }
+    }
+    if (input.delivery?.despatchAdviceReference && input.references.some((ref) => ref.type === "despatch")) {
+      addError(
+        errors,
+        "references",
+        'Use either delivery.despatchAdviceReference or a "despatch" reference, not both.',
+        "BASIC_WL" /* BASIC_WL */
+      );
+    }
+  }
   if (flavor === "xrechnung" /* XRECHNUNG */) {
     if (!input.document?.buyerReference) {
       addError(

package/dist/index.d.cts

@@ -596,7 +596,8 @@ interface InvoiceLineInput {
      */
     basisQuantityUnitCode?: UnitCode | (string & Record<never, never>);
     /**
-     * Line total (net) — can be derived from `quantity * unitPrice`.
+     * Line total (net). Derived as `quantity * unitPrice / (basisQuantity ?? 1)`,
+     * rounded to two decimals, when omitted.
      * @see EN 16931 BT-131
      */
     lineTotal?: number;
@@ -947,6 +948,12 @@ interface DocumentReferenceInput {
     type?: "order" | "contract" | "despatch" | "preceding" | "seller-order" | "project";
     /** Issue date of the referenced document */
     issueDate?: string;
+    /**
+     * Project name, only used for `"project"` references. The CII schema
+     * requires a `ram:Name` next to the project ID (BT-11); falls back to
+     * `"Project"` when omitted.
+     */
+    name?: string;
 }
 /**
  * Billing/invoicing period.

package/dist/index.d.ts

@@ -596,7 +596,8 @@ interface InvoiceLineInput {
      */
     basisQuantityUnitCode?: UnitCode | (string & Record<never, never>);
     /**
-     * Line total (net) — can be derived from `quantity * unitPrice`.
+     * Line total (net). Derived as `quantity * unitPrice / (basisQuantity ?? 1)`,
+     * rounded to two decimals, when omitted.
      * @see EN 16931 BT-131
      */
     lineTotal?: number;
@@ -947,6 +948,12 @@ interface DocumentReferenceInput {
     type?: "order" | "contract" | "despatch" | "preceding" | "seller-order" | "project";
     /** Issue date of the referenced document */
     issueDate?: string;
+    /**
+     * Project name, only used for `"project"` references. The CII schema
+     * requires a `ram:Name` next to the project ID (BT-11); falls back to
+     * `"Project"` when omitted.
+     */
+    name?: string;
 }
 /**
  * Billing/invoicing period.

package/dist/index.js

@@ -259,6 +259,9 @@ function toCents(n) {
 function roundHalfUp(n) {
   return toCents(n) / 100;
 }
+function deriveLineNet(line) {
+  return roundHalfUp(line.quantity * line.unitPrice / (line.basisQuantity ?? 1));
+}
 
 // src/core/xml-builder.ts
 var PROFILE_LEVEL = {
@@ -421,7 +424,7 @@ function buildLineItem(line, profile) {
       tx += tag("ram:RateApplicablePercent", line.vatRatePercent.toString());
     settle += tag("ram:ApplicableTradeTax", tx);
   }
-  const lineTotal = line.lineTotal ?? roundHalfUp(line.quantity * line.unitPrice);
+  const lineTotal = line.lineTotal ?? deriveLineNet(line);
   settle += tag(
     "ram:SpecifiedTradeSettlementLineMonetarySummation",
     tag("ram:LineTotalAmount", fmtAmt(lineTotal))
@@ -540,27 +543,21 @@ function buildXml(input, profile, flavor) {
       buildParty(input.sellerTaxRepresentative, profile)
     );
   if (input.references && atLeast(profile, "BASIC_WL" /* BASIC_WL */)) {
-    for (const ref of input.references) {
-      const refType = ref.type ?? "order";
-      if (refType === "preceding" || refType === "despatch") continue;
-      const inner = tag("ram:IssuerAssignedID", escapeXml(ref.id)) + (ref.issueDate ? dateEl("ram:FormattedIssueDateTime", ref.issueDate) : "");
-      switch (refType) {
-        case "order":
-          agree += tag("ram:BuyerOrderReferencedDocument", inner);
-          break;
-        case "contract":
-          agree += tag("ram:ContractReferencedDocument", inner);
-          break;
-        case "seller-order":
-          if (atLeast(profile, "EN16931" /* EN16931 */))
-            agree += tag("ram:SellerOrderReferencedDocument", inner);
-          break;
-        case "project":
-          if (atLeast(profile, "EN16931" /* EN16931 */))
-            agree += tag("ram:SpecifiedProcuringProject", tag("ram:ID", escapeXml(ref.id)));
-          break;
-      }
-    }
+    const refsOfType = (type) => input.references.filter((ref) => (ref.type ?? "order") === type);
+    const refDoc = (ref) => tag("ram:IssuerAssignedID", escapeXml(ref.id)) + (ref.issueDate ? dateEl("ram:FormattedIssueDateTime", ref.issueDate) : "");
+    if (atLeast(profile, "EN16931" /* EN16931 */))
+      for (const ref of refsOfType("seller-order"))
+        agree += tag("ram:SellerOrderReferencedDocument", refDoc(ref));
+    for (const ref of refsOfType("order"))
+      agree += tag("ram:BuyerOrderReferencedDocument", refDoc(ref));
+    for (const ref of refsOfType("contract"))
+      agree += tag("ram:ContractReferencedDocument", refDoc(ref));
+    if (atLeast(profile, "EN16931" /* EN16931 */))
+      for (const ref of refsOfType("project"))
+        agree += tag(
+          "ram:SpecifiedProcuringProject",
+          tag("ram:ID", escapeXml(ref.id)) + tag("ram:Name", escapeXml(ref.name ?? "Project"))
+        );
   }
   tx += tag("ram:ApplicableHeaderTradeAgreement", agree);
   let del = "";
@@ -855,6 +852,14 @@ function validateInput(input, profile, flavor) {
         if (line.unitPrice == null) {
           addError(errors, `lines[${i}].unitPrice`, "Line unit price is required", "BASIC" /* BASIC */);
         }
+        if (line.basisQuantity != null && !(line.basisQuantity > 0)) {
+          addError(
+            errors,
+            `lines[${i}].basisQuantity`,
+            "Line price base quantity (BT-149) must be greater than zero",
+            "BASIC" /* BASIC */
+          );
+        }
       });
     }
   }
@@ -951,8 +956,8 @@ function validateInput(input, profile, flavor) {
   }
   if (req("BASIC" /* BASIC */) && input.totals && input.lines) {
     const sumLineNets = input.lines.reduce((sum, l) => {
-      const lineNet = l.lineTotal ?? (typeof l.quantity === "number" && typeof l.unitPrice === "number" ? l.quantity * l.unitPrice : 0);
-      return sum + lineNet;
+      const lineNet = l.lineTotal ?? deriveLineNet(l);
+      return sum + (Number.isFinite(lineNet) ? lineNet : 0);
     }, 0);
     if (input.totals.lineTotal != null) {
       if (amountsDiffer(input.totals.lineTotal, sumLineNets)) {
@@ -1006,6 +1011,28 @@ function validateInput(input, profile, flavor) {
       }
     }
   }
+  if (req("BASIC_WL" /* BASIC_WL */) && input.references) {
+    const singleOccurrence = ["order", "contract", "seller-order", "project", "despatch"];
+    for (const type of singleOccurrence) {
+      const count = input.references.filter((ref) => (ref.type ?? "order") === type).length;
+      if (count > 1) {
+        addError(
+          errors,
+          "references",
+          `Only one "${type}" reference is allowed, got ${count}.`,
+          "BASIC_WL" /* BASIC_WL */
+        );
+      }
+    }
+    if (input.delivery?.despatchAdviceReference && input.references.some((ref) => ref.type === "despatch")) {
+      addError(
+        errors,
+        "references",
+        'Use either delivery.despatchAdviceReference or a "despatch" reference, not both.',
+        "BASIC_WL" /* BASIC_WL */
+      );
+    }
+  }
   if (flavor === "xrechnung" /* XRECHNUNG */) {
     if (!input.document?.buyerReference) {
       addError(

package/package.json

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