@stackforge-eu/factur-x 1.0.7 → 1.1.0

package/CHANGELOG.md

@@ -7,6 +7,46 @@ and this project adheres to [Semantic Versioning](https://semver.org/).
 
 ## [Unreleased]
 
+## [1.1.0] — 2026-05-27
+
+- **BREAKING:** Every `ram:GlobalID` and the legal-organization `ram:ID` now
+  carry the `@schemeID` attribute required by EN 16931. The XSD-canonical CII
+  mapping makes the scheme mandatory on `ram:GlobalID` (BT-29-1 / BT-46-1 for
+  parties, BT-157-1 for line items) and conditional on
+  `ram:SpecifiedLegalOrganization/ram:ID` (BT-30-1 / BT-47-1); without these
+  attributes Mustang / KoSIT / veraPDF's Factur-X profile reject the invoice
+  even though the embedded CII looked superficially correct. Three input
+  fields changed:
+  - `TradePartyInput.globalId` is now `IdentifierWithSchemeInput`
+    (`{ value: string; schemeID: string }`) instead of a bare `string`
+  - `InvoiceLineInput.standardIdentifier` is now `IdentifierWithSchemeInput`
+    instead of a bare `string` (sibling fix on top of #4 — the line-item
+    `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).
+
+## [1.0.8] — 2026-05-27
+
+- **PDF trailer was missing the `/ID` entry required by PDF/A-3.** ISO 19005-3
+  (and PDF 1.7 §14.4) require the trailer dictionary to carry an `/ID` array of
+  two byte strings: the first immutable identifier of the original document,
+  the second updated on every modification. `pdf-lib` initializes
+  `trailerInfo = {}` and never writes one on save, so veraPDF and the FNFE-MPE
+  Factur-X profile rejected every PDF this library produced as non-conformant.
+  Added `ensureIdTrailer` in `src/core/embed.ts` which runs after the first
+  `pdfDoc.save()` when `addPdfA3Metadata` is on: it computes an MD5 over the
+  serialized bytes (per PDF 1.7 §14.4 — uniqueness, not cryptographic strength,
+  is what matters), preserves any pre-existing first identifier, and writes the
+  pair before re-saving. Regression tests added in `tests/embed.test.ts`
+  covering both the no-existing-trailer and existing-trailer paths (thanks
+  @sco-indy, #3).
+
 ## [1.0.7] — 2026-05-27
 
 - **`fx:ConformanceLevel` in the XMP metadata used the raw `Profile` enum
@@ -113,6 +153,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.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
 [1.0.7]: https://github.com/StackForge-EU/factur-x/compare/v1.0.6...v1.0.7
 [1.0.6]: https://github.com/StackForge-EU/factur-x/compare/v1.0.5...v1.0.6
 [1.0.5]: https://github.com/StackForge-EU/factur-x/compare/v1.0.4...v1.0.5

package/dist/index.cjs

@@ -4,6 +4,7 @@ var fs = require('fs');
 var path = require('path');
 var url = require('url');
 var console = require('console');
+var crypto = require('crypto');
 var pdfLib = require('pdf-lib');
 
 function _interopDefault (e) { return e && e.__esModule ? e : { default: e }; }
@@ -339,13 +340,21 @@ function buildParty(p, profile) {
     const ids = Array.isArray(p.id) ? p.id : [p.id];
     for (const id of ids) x += tag("ram:ID", escapeXml(id));
   }
-  if (p.globalId) x += tag("ram:GlobalID", escapeXml(p.globalId));
+  if (p.globalId) {
+    x += tag("ram:GlobalID", escapeXml(p.globalId.value), { schemeID: p.globalId.schemeID });
+  }
   x += tag("ram:Name", escapeXml(p.name));
   if (p.description && atLeast(profile, "EN16931" /* EN16931 */))
     x += tag("ram:Description", escapeXml(p.description));
   if (p.legalOrganization) {
     let lo = "";
-    if (p.legalOrganization.id) lo += tag("ram:ID", escapeXml(p.legalOrganization.id));
+    if (p.legalOrganization.id) {
+      lo += tag(
+        "ram:ID",
+        escapeXml(p.legalOrganization.id),
+        p.legalOrganization.schemeID ? { schemeID: p.legalOrganization.schemeID } : void 0
+      );
+    }
     if (p.legalOrganization.tradingName)
       lo += tag("ram:TradingBusinessName", escapeXml(p.legalOrganization.tradingName));
     x += tag("ram:SpecifiedLegalOrganization", lo);
@@ -373,7 +382,11 @@ function buildLineItem(line, profile) {
   let doc = tag("ram:LineID", escapeXml(line.id));
   if (line.note) doc += tag("ram:IncludedNote", tag("ram:Content", escapeXml(line.note)));
   let prod = "";
-  if (line.standardIdentifier) prod += tag("ram:GlobalID", escapeXml(line.standardIdentifier));
+  if (line.standardIdentifier) {
+    prod += tag("ram:GlobalID", escapeXml(line.standardIdentifier.value), {
+      schemeID: line.standardIdentifier.schemeID
+    });
+  }
   if (line.sellerAssignedId) prod += tag("ram:SellerAssignedID", escapeXml(line.sellerAssignedId));
   if (line.buyerAssignedId) prod += tag("ram:BuyerAssignedID", escapeXml(line.buyerAssignedId));
   prod += tag("ram:Name", escapeXml(line.name));
@@ -1122,6 +1135,17 @@ function resolveXmpConformanceLevel(profile, flavor) {
   if (flavor === "xrechnung" /* XRECHNUNG */) return "XRECHNUNG";
   return XMP_CONFORMANCE_LEVEL[profile];
 }
+function ensureIdTrailer(pdfDoc, pdfContentBytes) {
+  const existingIdTrailer = pdfDoc.context.trailerInfo.ID;
+  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);
+    pdfDoc.context.trailerInfo.ID = pdfDoc.context.obj([existingFirstId, currentContentHash]);
+  } else {
+    pdfDoc.context.trailerInfo.ID = pdfDoc.context.obj([currentContentHash, currentContentHash]);
+  }
+}
 function ensureOutputIntent(pdfDoc, iccBytes, identifier) {
   const existing = pdfDoc.catalog.lookup(pdfLib.PDFName.of("OutputIntents"));
   if (existing instanceof pdfLib.PDFArray && existing.size() > 0) return;
@@ -1397,9 +1421,13 @@ async function embedFacturX(options) {
     const metadataRef = pdfDoc.context.register(metadataStream);
     pdfDoc.catalog.set(pdfLib.PDFName.of("Metadata"), metadataRef);
   }
-  const resultPdf = await pdfDoc.save();
+  let pdfContentBytes = await pdfDoc.save();
+  if (addPdfA3Metadata) {
+    ensureIdTrailer(pdfDoc, pdfContentBytes);
+    pdfContentBytes = await pdfDoc.save();
+  }
   return {
-    pdf: resultPdf,
+    pdf: pdfContentBytes,
     xml,
     ...validation ? { validation } : {},
     ...xsdValidation ? { xsdValidation } : {}

package/dist/index.d.cts

@@ -448,9 +448,18 @@ interface TaxRegistrationInput {
 interface LegalOrganizationInput {
     /** Registration identifier */
     id?: string;
+    /** Registration identifier scheme (ICD code list value, e.g. `"0002"` for SIRENE) */
+    schemeID?: string;
     /** Trading business name */
     tradingName?: string;
 }
+/**
+ * Identifier value with its scheme identifier.
+ */
+interface IdentifierWithSchemeInput {
+    value: string;
+    schemeID: string;
+}
 /**
  * Trade party (seller, buyer, payee, etc.).
  *
@@ -468,10 +477,14 @@ interface TradePartyInput {
      */
     id?: string | string[];
     /**
-     * Global identifier with scheme (e.g. GLN `"0088:1234567890123"`).
+     * Global identifier with scheme (e.g. GLN value `"4000001000005"` and
+     * ICD scheme `"0088"`).
+     *
+     * `schemeID` is required by EN 16931 for `ram:GlobalID`.
+     *
      * @see EN 16931 BT-29-1 / BT-46-1
      */
-    globalId?: string;
+    globalId?: IdentifierWithSchemeInput;
     /** Postal address — mandatory for BASIC_WL and above */
     address?: AddressInput;
     /**
@@ -581,10 +594,14 @@ interface InvoiceLineInput {
      */
     description?: string;
     /**
-     * Item standard identifier (e.g. GTIN/EAN).
+     * Item standard identifier (e.g. GTIN value `"4012345678901"` and ICD
+     * scheme `"0160"` for GS1).
+     *
+     * `schemeID` is required by EN 16931 for `ram:GlobalID` (BT-157-1).
+     *
      * @see EN 16931 BT-157
      */
-    standardIdentifier?: string;
+    standardIdentifier?: IdentifierWithSchemeInput;
     /**
      * Seller-assigned item identifier.
      * @see EN 16931 BT-155
@@ -1435,4 +1452,4 @@ interface XRechnungResult {
  */
 declare function toXRechnung(input: FacturXInvoiceInput, options?: XRechnungOptions): XRechnungResult;
 
-export { type AddressInput, type AllowanceChargeInput, type BillingPeriodInput, type ContactInput, type DeliveryInput, type DocumentReferenceInput, DocumentTypeCode, type EmbedOptions, type EmbedResult, type ExtractOptions, type ExtractResult, FLAVOR_CONFIGS, FLAVOR_DEFAULT_TYPE_CODES, type FacturXInvoiceInput, Flavor, type FlavorConfig, type InvoiceDocumentInput, type InvoiceLineInput, type InvoiceTotalsInput, type LegalOrganizationInput, type NoteInput, PROFILE_MAIN_XSD, PROFILE_SCHEMA_DIRS, PROFILE_URNS, type PaymentInput, Profile, type TaxRegistrationInput, type TradePartyInput, UnitCode, type ValidationError, type ValidationResult, type VatBreakdownInput, VatCategoryCode, XRECHNUNG_PROFILE_URN, type XRechnungOptions, type XRechnungResult, type XsdValidateOptions, type XsdValidationError, type XsdValidationResult, buildXml, embedFacturX, escapeXml, extractXml, getFlavorConfig, resolveBusinessProcessUrn, resolveTypeCode, toXRechnung, validateFlavorProfile, validateInput, validateXsd };
+export { type AddressInput, type AllowanceChargeInput, type BillingPeriodInput, type ContactInput, type DeliveryInput, type DocumentReferenceInput, DocumentTypeCode, type EmbedOptions, type EmbedResult, type ExtractOptions, type ExtractResult, FLAVOR_CONFIGS, FLAVOR_DEFAULT_TYPE_CODES, type FacturXInvoiceInput, Flavor, type FlavorConfig, type IdentifierWithSchemeInput, type InvoiceDocumentInput, type InvoiceLineInput, type InvoiceTotalsInput, type LegalOrganizationInput, type NoteInput, PROFILE_MAIN_XSD, PROFILE_SCHEMA_DIRS, PROFILE_URNS, type PaymentInput, Profile, type TaxRegistrationInput, type TradePartyInput, UnitCode, type ValidationError, type ValidationResult, type VatBreakdownInput, VatCategoryCode, XRECHNUNG_PROFILE_URN, type XRechnungOptions, type XRechnungResult, type XsdValidateOptions, type XsdValidationError, type XsdValidationResult, buildXml, embedFacturX, escapeXml, extractXml, getFlavorConfig, resolveBusinessProcessUrn, resolveTypeCode, toXRechnung, validateFlavorProfile, validateInput, validateXsd };

package/dist/index.d.ts

@@ -448,9 +448,18 @@ interface TaxRegistrationInput {
 interface LegalOrganizationInput {
     /** Registration identifier */
     id?: string;
+    /** Registration identifier scheme (ICD code list value, e.g. `"0002"` for SIRENE) */
+    schemeID?: string;
     /** Trading business name */
     tradingName?: string;
 }
+/**
+ * Identifier value with its scheme identifier.
+ */
+interface IdentifierWithSchemeInput {
+    value: string;
+    schemeID: string;
+}
 /**
  * Trade party (seller, buyer, payee, etc.).
  *
@@ -468,10 +477,14 @@ interface TradePartyInput {
      */
     id?: string | string[];
     /**
-     * Global identifier with scheme (e.g. GLN `"0088:1234567890123"`).
+     * Global identifier with scheme (e.g. GLN value `"4000001000005"` and
+     * ICD scheme `"0088"`).
+     *
+     * `schemeID` is required by EN 16931 for `ram:GlobalID`.
+     *
      * @see EN 16931 BT-29-1 / BT-46-1
      */
-    globalId?: string;
+    globalId?: IdentifierWithSchemeInput;
     /** Postal address — mandatory for BASIC_WL and above */
     address?: AddressInput;
     /**
@@ -581,10 +594,14 @@ interface InvoiceLineInput {
      */
     description?: string;
     /**
-     * Item standard identifier (e.g. GTIN/EAN).
+     * Item standard identifier (e.g. GTIN value `"4012345678901"` and ICD
+     * scheme `"0160"` for GS1).
+     *
+     * `schemeID` is required by EN 16931 for `ram:GlobalID` (BT-157-1).
+     *
      * @see EN 16931 BT-157
      */
-    standardIdentifier?: string;
+    standardIdentifier?: IdentifierWithSchemeInput;
     /**
      * Seller-assigned item identifier.
      * @see EN 16931 BT-155
@@ -1435,4 +1452,4 @@ interface XRechnungResult {
  */
 declare function toXRechnung(input: FacturXInvoiceInput, options?: XRechnungOptions): XRechnungResult;
 
-export { type AddressInput, type AllowanceChargeInput, type BillingPeriodInput, type ContactInput, type DeliveryInput, type DocumentReferenceInput, DocumentTypeCode, type EmbedOptions, type EmbedResult, type ExtractOptions, type ExtractResult, FLAVOR_CONFIGS, FLAVOR_DEFAULT_TYPE_CODES, type FacturXInvoiceInput, Flavor, type FlavorConfig, type InvoiceDocumentInput, type InvoiceLineInput, type InvoiceTotalsInput, type LegalOrganizationInput, type NoteInput, PROFILE_MAIN_XSD, PROFILE_SCHEMA_DIRS, PROFILE_URNS, type PaymentInput, Profile, type TaxRegistrationInput, type TradePartyInput, UnitCode, type ValidationError, type ValidationResult, type VatBreakdownInput, VatCategoryCode, XRECHNUNG_PROFILE_URN, type XRechnungOptions, type XRechnungResult, type XsdValidateOptions, type XsdValidationError, type XsdValidationResult, buildXml, embedFacturX, escapeXml, extractXml, getFlavorConfig, resolveBusinessProcessUrn, resolveTypeCode, toXRechnung, validateFlavorProfile, validateInput, validateXsd };
+export { type AddressInput, type AllowanceChargeInput, type BillingPeriodInput, type ContactInput, type DeliveryInput, type DocumentReferenceInput, DocumentTypeCode, type EmbedOptions, type EmbedResult, type ExtractOptions, type ExtractResult, FLAVOR_CONFIGS, FLAVOR_DEFAULT_TYPE_CODES, type FacturXInvoiceInput, Flavor, type FlavorConfig, type IdentifierWithSchemeInput, type InvoiceDocumentInput, type InvoiceLineInput, type InvoiceTotalsInput, type LegalOrganizationInput, type NoteInput, PROFILE_MAIN_XSD, PROFILE_SCHEMA_DIRS, PROFILE_URNS, type PaymentInput, Profile, type TaxRegistrationInput, type TradePartyInput, UnitCode, type ValidationError, type ValidationResult, type VatBreakdownInput, VatCategoryCode, XRECHNUNG_PROFILE_URN, type XRechnungOptions, type XRechnungResult, type XsdValidateOptions, type XsdValidationError, type XsdValidationResult, buildXml, embedFacturX, escapeXml, extractXml, getFlavorConfig, resolveBusinessProcessUrn, resolveTypeCode, toXRechnung, validateFlavorProfile, validateInput, validateXsd };

package/dist/index.js

@@ -2,7 +2,8 @@ import * as fs from 'fs';
 import * as path from 'path';
 import { fileURLToPath } from 'url';
 import console from 'console';
-import { AFRelationship, PDFDocument, PDFName, PDFArray, PDFDict, PDFStream, PDFRawStream, decodePDFRawStream, PDFString, PDFRef, PDFHexString } from 'pdf-lib';
+import { createHash } from 'crypto';
+import { AFRelationship, PDFDocument, PDFName, PDFArray, PDFDict, PDFStream, PDFRawStream, decodePDFRawStream, PDFString, PDFHexString, PDFRef } from 'pdf-lib';
 
 // src/types/input.ts
 var DocumentTypeCode = /* @__PURE__ */ ((DocumentTypeCode2) => {
@@ -309,13 +310,21 @@ function buildParty(p, profile) {
     const ids = Array.isArray(p.id) ? p.id : [p.id];
     for (const id of ids) x += tag("ram:ID", escapeXml(id));
   }
-  if (p.globalId) x += tag("ram:GlobalID", escapeXml(p.globalId));
+  if (p.globalId) {
+    x += tag("ram:GlobalID", escapeXml(p.globalId.value), { schemeID: p.globalId.schemeID });
+  }
   x += tag("ram:Name", escapeXml(p.name));
   if (p.description && atLeast(profile, "EN16931" /* EN16931 */))
     x += tag("ram:Description", escapeXml(p.description));
   if (p.legalOrganization) {
     let lo = "";
-    if (p.legalOrganization.id) lo += tag("ram:ID", escapeXml(p.legalOrganization.id));
+    if (p.legalOrganization.id) {
+      lo += tag(
+        "ram:ID",
+        escapeXml(p.legalOrganization.id),
+        p.legalOrganization.schemeID ? { schemeID: p.legalOrganization.schemeID } : void 0
+      );
+    }
     if (p.legalOrganization.tradingName)
       lo += tag("ram:TradingBusinessName", escapeXml(p.legalOrganization.tradingName));
     x += tag("ram:SpecifiedLegalOrganization", lo);
@@ -343,7 +352,11 @@ function buildLineItem(line, profile) {
   let doc = tag("ram:LineID", escapeXml(line.id));
   if (line.note) doc += tag("ram:IncludedNote", tag("ram:Content", escapeXml(line.note)));
   let prod = "";
-  if (line.standardIdentifier) prod += tag("ram:GlobalID", escapeXml(line.standardIdentifier));
+  if (line.standardIdentifier) {
+    prod += tag("ram:GlobalID", escapeXml(line.standardIdentifier.value), {
+      schemeID: line.standardIdentifier.schemeID
+    });
+  }
   if (line.sellerAssignedId) prod += tag("ram:SellerAssignedID", escapeXml(line.sellerAssignedId));
   if (line.buyerAssignedId) prod += tag("ram:BuyerAssignedID", escapeXml(line.buyerAssignedId));
   prod += tag("ram:Name", escapeXml(line.name));
@@ -1092,6 +1105,17 @@ function resolveXmpConformanceLevel(profile, flavor) {
   if (flavor === "xrechnung" /* XRECHNUNG */) return "XRECHNUNG";
   return XMP_CONFORMANCE_LEVEL[profile];
 }
+function ensureIdTrailer(pdfDoc, pdfContentBytes) {
+  const existingIdTrailer = pdfDoc.context.trailerInfo.ID;
+  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);
+    pdfDoc.context.trailerInfo.ID = pdfDoc.context.obj([existingFirstId, currentContentHash]);
+  } else {
+    pdfDoc.context.trailerInfo.ID = pdfDoc.context.obj([currentContentHash, currentContentHash]);
+  }
+}
 function ensureOutputIntent(pdfDoc, iccBytes, identifier) {
   const existing = pdfDoc.catalog.lookup(PDFName.of("OutputIntents"));
   if (existing instanceof PDFArray && existing.size() > 0) return;
@@ -1367,9 +1391,13 @@ async function embedFacturX(options) {
     const metadataRef = pdfDoc.context.register(metadataStream);
     pdfDoc.catalog.set(PDFName.of("Metadata"), metadataRef);
   }
-  const resultPdf = await pdfDoc.save();
+  let pdfContentBytes = await pdfDoc.save();
+  if (addPdfA3Metadata) {
+    ensureIdTrailer(pdfDoc, pdfContentBytes);
+    pdfContentBytes = await pdfDoc.save();
+  }
   return {
-    pdf: resultPdf,
+    pdf: pdfContentBytes,
     xml,
     ...validation ? { validation } : {},
     ...xsdValidation ? { xsdValidation } : {}

package/package.json

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