@stackforge-eu/factur-x 1.2.0 → 1.3.0

package/CHANGELOG.md

@@ -7,6 +7,31 @@ and this project adheres to [Semantic Versioning](https://semver.org/).
 
 ## [Unreleased]
 
+## [1.3.0] — 2026-09-01
+
+- **Added item price base quantity (BT-149/BT-150).** New optional
+  `basisQuantity` and `basisQuantityUnitCode` fields on `InvoiceLineInput`
+  emit `ram:BasisQuantity` inside the net (and, when present, gross) price
+  element, so a unit price can state the quantity it refers to — e.g.
+  `12.50` per 10 m². The unit code defaults to the line's `unitCode`, as
+  EN 16931 requires BT-150 to match BT-130. Omitting the field keeps the
+  output byte-for-byte identical (#12).
+- CI now requires every PR to add a `CHANGELOG.md` entry (or carry the
+  `skip-changelog` label), so contributor fixes always reach the release notes.
+
+## [1.2.1] — 2026-08-27
+
+- **Fixed XSD validation on Windows.** Schema `<xsd:import>` resolution built a
+  malformed `file://` URL from backslash paths and keyed the schema lookup by
+  a percent-encoded href that libxml2 normalises differently. Now uses
+  `pathToFileURL()` and matches imported schemas by filename. Windows added
+  to the CI matrix (thanks @muratkorkmaztr-cmyk, #6).
+- **Embedded `factur-x.xml` now uses the `application/xml` MIME type** instead
+  of the deprecated `text/xml` (RFC 7303), which current Factur-X conformance
+  checkers flag (thanks @muratkorkmaztr-cmyk, #7).
+- Expanded npm `keywords` (e.g. `e-rechnung`, `pdfa`, `chorus-pro`, `un-cefact`,
+  spelling variants) so the package is easier to find on npm (#8).
+
 ## [1.2.0] — 2026-07-11
 
 - **Updated to Factur-X 1.09 / ZUGFeRD 2.5** (spec dated 2026-06-10). Factur-X
@@ -70,12 +95,12 @@ and this project adheres to [Semantic Versioning](https://semver.org/).
     `ram:GlobalID` had the same defect as the party one)
   - `LegalOrganizationInput.schemeID?: string` added (optional, mirrors the
     conditional spec rule)
-  Migration: `globalId: "4000001000005"` →
-  `globalId: { value: "4000001000005", schemeID: "0088" }` (and the analogous
-  rewrite for `standardIdentifier`). The new `IdentifierWithSchemeInput` type
-  is exported from `src/index.ts`. Regression test added in
-  `tests/xsd-validator.test.ts` that drives all three schemed identifiers
-  through the EN16931 XSD in one go (thanks @sco-indy, #4).
+    Migration: `globalId: "4000001000005"` →
+    `globalId: { value: "4000001000005", schemeID: "0088" }` (and the analogous
+    rewrite for `standardIdentifier`). The new `IdentifierWithSchemeInput` type
+    is exported from `src/index.ts`. Regression test added in
+    `tests/xsd-validator.test.ts` that drives all three schemed identifiers
+    through the EN16931 XSD in one go (thanks @sco-indy, #4).
 
 ## [1.0.8] — 2026-05-27
 
@@ -122,7 +147,7 @@ and this project adheres to [Semantic Versioning](https://semver.org/).
   debtor account last. Any invoice combining a SEPA direct debit
   (`payment.meansCode = "59"`) with `payment.debtorIban` plus a payee
   IBAN/BIC failed XSD validation with `Element 'PayerPartyDebtorFinancialAccount':
-  This element is not expected`. Reordered the three blocks in
+This element is not expected`. Reordered the three blocks in
   `src/core/xml-builder.ts`; regression test added in
   `tests/xml-builder.test.ts`.
 
@@ -199,6 +224,8 @@ and this project adheres to [Semantic Versioning](https://semver.org/).
 - Deno compatibility test suite
 
 [Unreleased]: https://github.com/StackForge-EU/factur-x/commits/main
+[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
 [1.2.0]: https://github.com/StackForge-EU/factur-x/compare/v1.1.0...v1.2.0
 [1.1.0]: https://github.com/StackForge-EU/factur-x/compare/v1.0.8...v1.1.0
 [1.0.8]: https://github.com/StackForge-EU/factur-x/compare/v1.0.7...v1.0.8

package/dist/index.cjs

@@ -402,13 +402,19 @@ function buildLineItem(line, profile) {
       "ram:BuyerOrderReferencedDocument",
       tag("ram:LineID", escapeXml(line.buyerOrderLineId))
     );
+  const unitCode = line.unitCode ?? "C62" /* UNIT */;
+  const basisQuantity = line.basisQuantity !== void 0 ? tag("ram:BasisQuantity", line.basisQuantity.toString(), {
+    unitCode: line.basisQuantityUnitCode ?? unitCode
+  }) : "";
   if (line.grossUnitPrice !== void 0)
     agree += tag(
       "ram:GrossPriceProductTradePrice",
-      tag("ram:ChargeAmount", fmtAmt(line.grossUnitPrice))
+      tag("ram:ChargeAmount", fmtAmt(line.grossUnitPrice)) + basisQuantity
     );
-  agree += tag("ram:NetPriceProductTradePrice", tag("ram:ChargeAmount", fmtAmt(line.unitPrice)));
-  const unitCode = line.unitCode ?? "C62" /* UNIT */;
+  agree += tag(
+    "ram:NetPriceProductTradePrice",
+    tag("ram:ChargeAmount", fmtAmt(line.unitPrice)) + basisQuantity
+  );
   const delivery = tag("ram:BilledQuantity", line.quantity.toString(), {
     unitCode
   });
@@ -509,10 +515,7 @@ function buildXml(input, profile, flavor) {
       tag("ram:ID", escapeXml(doc.businessProcessId))
     );
   const profileUrn = fl === "xrechnung" /* XRECHNUNG */ ? XRECHNUNG_PROFILE_URN : PROFILE_URNS[profile];
-  ctx += tag(
-    "ram:GuidelineSpecifiedDocumentContextParameter",
-    tag("ram:ID", profileUrn)
-  );
+  ctx += tag("ram:GuidelineSpecifiedDocumentContextParameter", tag("ram:ID", profileUrn));
   let edoc = tag("ram:ID", escapeXml(doc.id));
   if (doc.name && atLeast(profile, "EXTENDED" /* EXTENDED */)) edoc += tag("ram:Name", escapeXml(doc.name));
   edoc += tag("ram:TypeCode", typeCode);
@@ -1100,26 +1103,42 @@ async function validateXsd(xml, profile, options) {
     XmlValidateError,
     xmlRegisterInputProvider,
     xmlCleanupInputProvider,
-    XmlBufferInputProvider
+    openBuffer,
+    readBuffer,
+    closeBuffer
   } = await import('libxml2-wasm');
   const schemaDir = path__namespace.dirname(xsdPath);
   const files = fs__namespace.readdirSync(schemaDir).filter((f) => f.endsWith(".xsd"));
   const buffers = {};
   for (const file of files) {
-    const filePath = path__namespace.join(schemaDir, file);
-    buffers[filePath] = fs__namespace.readFileSync(filePath);
-    buffers[`file://${filePath}`] = buffers[filePath];
-    buffers[file] = buffers[filePath];
-  }
+    buffers[file] = fs__namespace.readFileSync(path__namespace.join(schemaDir, file));
+  }
+  const schemaFileFor = (requested) => {
+    const start = Math.max(requested.lastIndexOf("/"), requested.lastIndexOf("\\")) + 1;
+    const segment = requested.slice(start);
+    let name = segment;
+    try {
+      name = decodeURIComponent(segment);
+    } catch {
+    }
+    return files.includes(name) ? name : void 0;
+  };
   xmlCleanupInputProvider();
-  const provider = new XmlBufferInputProvider(buffers);
-  xmlRegisterInputProvider(provider);
+  xmlRegisterInputProvider({
+    match: (filename) => schemaFileFor(filename) !== void 0,
+    open: (filename) => openBuffer(buffers[schemaFileFor(filename)]),
+    read: readBuffer,
+    close: (fd) => {
+      closeBuffer(fd);
+      return true;
+    }
+  });
   let xsdDoc;
   let validator;
   let xmlDoc;
   try {
     const xsdContent = fs__namespace.readFileSync(xsdPath, "utf-8");
-    xsdDoc = XmlDocument.fromString(xsdContent, { url: `file://${xsdPath}` });
+    xsdDoc = XmlDocument.fromString(xsdContent, { url: url.pathToFileURL(xsdPath).href });
     validator = XsdValidator.fromDoc(xsdDoc);
     xmlDoc = XmlDocument.fromString(xml);
     validator.validate(xmlDoc);
@@ -1162,7 +1181,9 @@ function resolveXmpConformanceLevel(profile, flavor) {
 }
 function ensureIdTrailer(pdfDoc, pdfContentBytes) {
   const existingIdTrailer = pdfDoc.context.trailerInfo.ID;
-  const currentContentHash = pdfLib.PDFHexString.of(crypto.createHash("md5").update(pdfContentBytes).digest("hex"));
+  const currentContentHash = pdfLib.PDFHexString.of(
+    crypto.createHash("md5").update(pdfContentBytes).digest("hex")
+  );
   const hasValidIdTrailer = existingIdTrailer instanceof pdfLib.PDFArray && existingIdTrailer.size() === 2;
   if (hasValidIdTrailer) {
     const existingFirstId = existingIdTrailer.lookup(0);
@@ -1191,11 +1212,7 @@ function ensureOutputIntent(pdfDoc, iccBytes, identifier) {
 function findUnembeddedFonts(pdfDoc) {
   const seen = /* @__PURE__ */ new Set();
   const unembedded = /* @__PURE__ */ new Set();
-  const FONT_FILE_KEYS = [
-    pdfLib.PDFName.of("FontFile"),
-    pdfLib.PDFName.of("FontFile2"),
-    pdfLib.PDFName.of("FontFile3")
-  ];
+  const FONT_FILE_KEYS = [pdfLib.PDFName.of("FontFile"), pdfLib.PDFName.of("FontFile2"), pdfLib.PDFName.of("FontFile3")];
   const inspectFontDict = (font) => {
     const subtype = font.lookup(pdfLib.PDFName.of("Subtype"));
     const baseFont = font.lookup(pdfLib.PDFName.of("BaseFont"));
@@ -1391,7 +1408,7 @@ async function embedFacturX(options) {
   const xmlBytes = new TextEncoder().encode(xml);
   const afRel = resolveAfRelationship(profile, options.afRelationship);
   await pdfDoc.attach(xmlBytes, flavorConfig.attachmentFilename, {
-    mimeType: "text/xml",
+    mimeType: "application/xml",
     afRelationship: afRel,
     description: "Factur-X Invoice"
   });

package/dist/index.d.cts

@@ -573,6 +573,20 @@ interface InvoiceLineInput {
      * @see EN 16931 BT-148
      */
     grossUnitPrice?: 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.
+     * @see EN 16931 BT-149
+     */
+    basisQuantity?: number;
+    /**
+     * Unit of measure for `basisQuantity` (UN/CEFACT Rec 20).
+     *
+     * @default the line's `unitCode` when omitted, as EN 16931 requires
+     *   BT-150 to match the invoiced quantity's unit (BT-130)
+     * @see EN 16931 BT-150
+     */
+    basisQuantityUnitCode?: UnitCode | (string & Record<never, never>);
     /**
      * Line total (net) — can be derived from `quantity * unitPrice`.
      * @see EN 16931 BT-131

package/dist/index.d.ts

@@ -573,6 +573,20 @@ interface InvoiceLineInput {
      * @see EN 16931 BT-148
      */
     grossUnitPrice?: 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.
+     * @see EN 16931 BT-149
+     */
+    basisQuantity?: number;
+    /**
+     * Unit of measure for `basisQuantity` (UN/CEFACT Rec 20).
+     *
+     * @default the line's `unitCode` when omitted, as EN 16931 requires
+     *   BT-150 to match the invoiced quantity's unit (BT-130)
+     * @see EN 16931 BT-150
+     */
+    basisQuantityUnitCode?: UnitCode | (string & Record<never, never>);
     /**
      * Line total (net) — can be derived from `quantity * unitPrice`.
      * @see EN 16931 BT-131

package/dist/index.js

@@ -1,6 +1,6 @@
 import * as fs from 'fs';
 import * as path from 'path';
-import { fileURLToPath } from 'url';
+import { pathToFileURL, fileURLToPath } from 'url';
 import console from 'console';
 import { createHash } from 'crypto';
 import { AFRelationship, PDFDocument, PDFName, PDFArray, PDFDict, PDFStream, PDFRawStream, decodePDFRawStream, PDFString, PDFHexString, PDFRef } from 'pdf-lib';
@@ -372,13 +372,19 @@ function buildLineItem(line, profile) {
       "ram:BuyerOrderReferencedDocument",
       tag("ram:LineID", escapeXml(line.buyerOrderLineId))
     );
+  const unitCode = line.unitCode ?? "C62" /* UNIT */;
+  const basisQuantity = line.basisQuantity !== void 0 ? tag("ram:BasisQuantity", line.basisQuantity.toString(), {
+    unitCode: line.basisQuantityUnitCode ?? unitCode
+  }) : "";
   if (line.grossUnitPrice !== void 0)
     agree += tag(
       "ram:GrossPriceProductTradePrice",
-      tag("ram:ChargeAmount", fmtAmt(line.grossUnitPrice))
+      tag("ram:ChargeAmount", fmtAmt(line.grossUnitPrice)) + basisQuantity
     );
-  agree += tag("ram:NetPriceProductTradePrice", tag("ram:ChargeAmount", fmtAmt(line.unitPrice)));
-  const unitCode = line.unitCode ?? "C62" /* UNIT */;
+  agree += tag(
+    "ram:NetPriceProductTradePrice",
+    tag("ram:ChargeAmount", fmtAmt(line.unitPrice)) + basisQuantity
+  );
   const delivery = tag("ram:BilledQuantity", line.quantity.toString(), {
     unitCode
   });
@@ -479,10 +485,7 @@ function buildXml(input, profile, flavor) {
       tag("ram:ID", escapeXml(doc.businessProcessId))
     );
   const profileUrn = fl === "xrechnung" /* XRECHNUNG */ ? XRECHNUNG_PROFILE_URN : PROFILE_URNS[profile];
-  ctx += tag(
-    "ram:GuidelineSpecifiedDocumentContextParameter",
-    tag("ram:ID", profileUrn)
-  );
+  ctx += tag("ram:GuidelineSpecifiedDocumentContextParameter", tag("ram:ID", profileUrn));
   let edoc = tag("ram:ID", escapeXml(doc.id));
   if (doc.name && atLeast(profile, "EXTENDED" /* EXTENDED */)) edoc += tag("ram:Name", escapeXml(doc.name));
   edoc += tag("ram:TypeCode", typeCode);
@@ -1070,26 +1073,42 @@ async function validateXsd(xml, profile, options) {
     XmlValidateError,
     xmlRegisterInputProvider,
     xmlCleanupInputProvider,
-    XmlBufferInputProvider
+    openBuffer,
+    readBuffer,
+    closeBuffer
   } = await import('libxml2-wasm');
   const schemaDir = path.dirname(xsdPath);
   const files = fs.readdirSync(schemaDir).filter((f) => f.endsWith(".xsd"));
   const buffers = {};
   for (const file of files) {
-    const filePath = path.join(schemaDir, file);
-    buffers[filePath] = fs.readFileSync(filePath);
-    buffers[`file://${filePath}`] = buffers[filePath];
-    buffers[file] = buffers[filePath];
-  }
+    buffers[file] = fs.readFileSync(path.join(schemaDir, file));
+  }
+  const schemaFileFor = (requested) => {
+    const start = Math.max(requested.lastIndexOf("/"), requested.lastIndexOf("\\")) + 1;
+    const segment = requested.slice(start);
+    let name = segment;
+    try {
+      name = decodeURIComponent(segment);
+    } catch {
+    }
+    return files.includes(name) ? name : void 0;
+  };
   xmlCleanupInputProvider();
-  const provider = new XmlBufferInputProvider(buffers);
-  xmlRegisterInputProvider(provider);
+  xmlRegisterInputProvider({
+    match: (filename) => schemaFileFor(filename) !== void 0,
+    open: (filename) => openBuffer(buffers[schemaFileFor(filename)]),
+    read: readBuffer,
+    close: (fd) => {
+      closeBuffer(fd);
+      return true;
+    }
+  });
   let xsdDoc;
   let validator;
   let xmlDoc;
   try {
     const xsdContent = fs.readFileSync(xsdPath, "utf-8");
-    xsdDoc = XmlDocument.fromString(xsdContent, { url: `file://${xsdPath}` });
+    xsdDoc = XmlDocument.fromString(xsdContent, { url: pathToFileURL(xsdPath).href });
     validator = XsdValidator.fromDoc(xsdDoc);
     xmlDoc = XmlDocument.fromString(xml);
     validator.validate(xmlDoc);
@@ -1132,7 +1151,9 @@ function resolveXmpConformanceLevel(profile, flavor) {
 }
 function ensureIdTrailer(pdfDoc, pdfContentBytes) {
   const existingIdTrailer = pdfDoc.context.trailerInfo.ID;
-  const currentContentHash = PDFHexString.of(createHash("md5").update(pdfContentBytes).digest("hex"));
+  const currentContentHash = PDFHexString.of(
+    createHash("md5").update(pdfContentBytes).digest("hex")
+  );
   const hasValidIdTrailer = existingIdTrailer instanceof PDFArray && existingIdTrailer.size() === 2;
   if (hasValidIdTrailer) {
     const existingFirstId = existingIdTrailer.lookup(0);
@@ -1161,11 +1182,7 @@ function ensureOutputIntent(pdfDoc, iccBytes, identifier) {
 function findUnembeddedFonts(pdfDoc) {
   const seen = /* @__PURE__ */ new Set();
   const unembedded = /* @__PURE__ */ new Set();
-  const FONT_FILE_KEYS = [
-    PDFName.of("FontFile"),
-    PDFName.of("FontFile2"),
-    PDFName.of("FontFile3")
-  ];
+  const FONT_FILE_KEYS = [PDFName.of("FontFile"), PDFName.of("FontFile2"), PDFName.of("FontFile3")];
   const inspectFontDict = (font) => {
     const subtype = font.lookup(PDFName.of("Subtype"));
     const baseFont = font.lookup(PDFName.of("BaseFont"));
@@ -1361,7 +1378,7 @@ async function embedFacturX(options) {
   const xmlBytes = new TextEncoder().encode(xml);
   const afRel = resolveAfRelationship(profile, options.afRelationship);
   await pdfDoc.attach(xmlBytes, flavorConfig.attachmentFilename, {
-    mimeType: "text/xml",
+    mimeType: "application/xml",
     afRelationship: afRel,
     description: "Factur-X Invoice"
   });

package/package.json

@@ -1,21 +1,39 @@
 {
   "name": "@stackforge-eu/factur-x",
-  "version": "1.2.0",
+  "version": "1.3.0",
   "type": "module",
   "description": "Embed Factur-X, ZUGFeRD, and XRechnung structured invoice XML into PDF/A-3 documents",
   "keywords": [
     "factur-x",
+    "facturx",
     "zugferd",
     "xrechnung",
+    "e-rechnung",
+    "chorus-pro",
     "en16931",
+    "en-16931",
     "cii",
+    "un-cefact",
+    "cross-industry-invoice",
     "pdf",
+    "pdfa",
+    "pdf-a",
     "pdf-a3",
+    "pdfa3",
+    "xmp",
     "invoice",
     "e-invoice",
     "e-invoicing",
+    "einvoice",
+    "e-invoice-eu",
+    "electronic-invoice",
+    "b2g",
     "eu",
-    "xml"
+    "germany",
+    "france",
+    "xml",
+    "typescript",
+    "deno"
   ],
   "license": "EUPL-1.2",
   "author": "StackForge UG",