@fin.cx/einvoice 6.1.1 → 6.2.0

package/ts/formats/base/base.decoder.ts

@@ -1,6 +1,7 @@
 import type { TInvoice } from '../../interfaces/common.js';
 import { ValidationLevel } from '../../interfaces/common.js';
 import type { ValidationResult } from '../../interfaces/common.js';
+import { EInvoiceParsingError } from '../../errors.js';
 
 /**
  * Base decoder class that defines common decoding functionality
@@ -72,4 +73,123 @@ export abstract class BaseDecoder {
     const parsed = Date.parse(dateStr);
     return isNaN(parsed) ? Date.now() : parsed;
   }
+
+  /**
+   * Parses a required CII date without inventing a fallback value.
+   */
+  protected parseRequiredCIIDate(dateStr: string, format?: string): number {
+    const value = dateStr.trim();
+    if (!value) {
+      throw new EInvoiceParsingError('Missing required CII invoice issue date', {
+        format: 'cii',
+      });
+    }
+
+    if (format === '102') {
+      const match = /^(\d{4})(\d{2})(\d{2})$/.exec(value);
+      if (!match) {
+        throw this.createInvalidDateError(value, 'CII format 102');
+      }
+      return this.createStrictUtcTimestamp(
+        Number(match[1]),
+        Number(match[2]),
+        Number(match[3]),
+        value,
+        'CII format 102',
+      );
+    }
+
+    if (format === '610') {
+      const match = /^(\d{4})(\d{2})$/.exec(value);
+      if (!match) {
+        throw this.createInvalidDateError(value, 'CII format 610');
+      }
+      return this.createStrictUtcTimestamp(
+        Number(match[1]),
+        Number(match[2]),
+        1,
+        value,
+        'CII format 610',
+      );
+    }
+
+    const parsed = Date.parse(value);
+    if (Number.isNaN(parsed)) {
+      throw this.createInvalidDateError(value, 'CII');
+    }
+    return parsed;
+  }
+
+  /**
+   * Parses a required UBL xsd:date value strictly and deterministically.
+   */
+  protected parseRequiredUblDate(dateStr: string): number {
+    const value = dateStr.trim();
+    const match =
+      /^(\d{4})-(\d{2})-(\d{2})(?:(Z)|([+-])(\d{2}):(\d{2}))?$/.exec(value);
+    if (!match) {
+      throw this.createInvalidDateError(value, 'UBL xsd:date');
+    }
+
+    const timestamp = this.createStrictUtcTimestamp(
+      Number(match[1]),
+      Number(match[2]),
+      Number(match[3]),
+      value,
+      'UBL xsd:date',
+    );
+
+    if (!match[5]) {
+      return timestamp;
+    }
+
+    const offsetHours = Number(match[6]);
+    const offsetMinutes = Number(match[7]);
+    if (
+      offsetHours > 14 ||
+      offsetMinutes > 59 ||
+      (offsetHours === 14 && offsetMinutes !== 0)
+    ) {
+      throw this.createInvalidDateError(value, 'UBL xsd:date');
+    }
+
+    const direction = match[5] === '+' ? 1 : -1;
+    return timestamp - direction * (offsetHours * 60 + offsetMinutes) * 60_000;
+  }
+
+  private createStrictUtcTimestamp(
+    year: number,
+    month: number,
+    day: number,
+    sourceValue: string,
+    format: string,
+  ): number {
+    if (year < 1 || month < 1 || month > 12 || day < 1 || day > 31) {
+      throw this.createInvalidDateError(sourceValue, format);
+    }
+
+    const date = new Date(0);
+    date.setUTCHours(0, 0, 0, 0);
+    date.setUTCFullYear(year, month - 1, day);
+
+    if (
+      date.getUTCFullYear() !== year ||
+      date.getUTCMonth() !== month - 1 ||
+      date.getUTCDate() !== day
+    ) {
+      throw this.createInvalidDateError(sourceValue, format);
+    }
+
+    return date.getTime();
+  }
+
+  private createInvalidDateError(
+    value: string,
+    format: string,
+  ): EInvoiceParsingError {
+    return new EInvoiceParsingError(
+      `Invalid required invoice issue date "${value}" for ${format}`,
+      { format },
+    );
+  }
 }

package/ts/formats/cii/cii.decoder.ts

@@ -2,6 +2,7 @@ import { BaseDecoder } from '../base/base.decoder.js';
 import type { TInvoice, TCreditNote, TDebitNote } from '../../interfaces/common.js';
 import { CII_NAMESPACES, CIIProfile } from './cii.types.js';
 import { DOMParser, xpath } from '../../plugins.js';
+import { EInvoiceParsingError } from '../../errors.js';
 
 const ciiParser = new DOMParser();
 const ciiNamespaces = {
@@ -106,6 +107,23 @@ export abstract class CIIBaseDecoder extends BaseDecoder {
     return node ? (node.textContent || '') : '';
   }
 
+  /**
+   * Gets a required CII text value and rejects missing content.
+   */
+  protected getRequiredText(
+    xpathExpr: string,
+    fieldName: string,
+    context?: Node,
+  ): string {
+    const value = this.getText(xpathExpr, context).trim();
+    if (!value) {
+      throw new EInvoiceParsingError(`Missing required CII ${fieldName}`, {
+        format: 'cii',
+      });
+    }
+    return value;
+  }
+
   /**
    * Gets a number value from an XPath expression
    * @param xpath XPath expression

package/ts/formats/cii/cii.validator.ts

@@ -89,7 +89,11 @@ export abstract class CIIBaseValidator extends BaseValidator {
 
     // Check for root element
     const root = this.doc.documentElement;
-    if (!root || root.nodeName !== 'rsm:CrossIndustryInvoice') {
+    if (
+      !root ||
+      root.localName !== 'CrossIndustryInvoice' ||
+      root.namespaceURI !== CII_NAMESPACES.RSM
+    ) {
       this.addError('CII-SCHEMA-1', 'Root element must be rsm:CrossIndustryInvoice', '/');
       return false;
     }

package/ts/formats/cii/facturx/facturx.decoder.ts

@@ -44,12 +44,20 @@ export class FacturXDecoder extends CIIBaseDecoder {
    */
   private async extractCommonData(): Promise<Partial<TInvoice>> {
     // Extract invoice ID
-    const invoiceId = this.getText('//rsm:ExchangedDocument/ram:ID');
+    const invoiceId = this.getRequiredText(
+      '/rsm:CrossIndustryInvoice/rsm:ExchangedDocument/ram:ID',
+      'invoice identifier',
+    );
 
     // Extract issue date
-    const issueDateStr = this.getText('//ram:IssueDateTime/udt:DateTimeString');
-    const issueDateFormat = this.getText('//ram:IssueDateTime/udt:DateTimeString/@format');
-    const issueDate = this.parseCIIDate(issueDateStr, issueDateFormat);
+    const issueDatePath =
+      '/rsm:CrossIndustryInvoice/rsm:ExchangedDocument/ram:IssueDateTime/udt:DateTimeString';
+    const issueDateStr = this.getRequiredText(
+      issueDatePath,
+      'invoice issue date',
+    );
+    const issueDateFormat = this.getText(`${issueDatePath}/@format`).trim();
+    const issueDate = this.parseRequiredCIIDate(issueDateStr, issueDateFormat);
 
     // Extract seller information
     const seller = this.extractParty('//ram:SellerTradeParty');

package/ts/formats/factories/decoder.factory.ts

@@ -7,6 +7,7 @@ import { XRechnungDecoder } from '../ubl/xrechnung/xrechnung.decoder.js';
 import { FacturXDecoder } from '../cii/facturx/facturx.decoder.js';
 import { ZUGFeRDDecoder } from '../cii/zugferd/zugferd.decoder.js';
 import { ZUGFeRDV1Decoder } from '../cii/zugferd/zugferd.v1.decoder.js';
+import { detectInvoiceXmlSyntax } from '../utils/xml.syntax.js';
 
 /**
  * Factory to create the appropriate decoder based on the XML format
@@ -28,9 +29,19 @@ export class DecoderFactory {
 
     switch (format) {
       case InvoiceFormat.UBL:
-      case InvoiceFormat.XRECHNUNG:
         return new XRechnungDecoder(xml, skipValidation);
 
+      case InvoiceFormat.XRECHNUNG: {
+        const syntax = detectInvoiceXmlSyntax(xml);
+        if (syntax === 'cii') {
+          return new FacturXDecoder(xml, skipValidation);
+        }
+        if (syntax === 'ubl') {
+          return new XRechnungDecoder(xml, skipValidation);
+        }
+        throw new Error('Unsupported or malformed XRechnung XML syntax');
+      }
+
       case InvoiceFormat.CII:
         // For now, use Factur-X decoder for generic CII
         return new FacturXDecoder(xml, skipValidation);

package/ts/formats/factories/validator.factory.ts

@@ -8,6 +8,7 @@ import { EN16931UBLValidator } from '../ubl/en16931.ubl.validator.js';
 import { XRechnungValidator } from '../ubl/xrechnung.validator.js';
 import { FacturXValidator } from '../cii/facturx/facturx.validator.js';
 import { ZUGFeRDValidator } from '../cii/zugferd/zugferd.validator.js';
+import { detectInvoiceXmlSyntax } from '../utils/xml.syntax.js';
 
 // The EN16931UBLValidator handles all UBL-based formats with proper business rules
 // No need for legacy validator implementations here
@@ -75,8 +76,16 @@ export class ValidatorFactory {
         case InvoiceFormat.UBL:
           return new EN16931UBLValidator(xml, parsedDocument);
 
-        case InvoiceFormat.XRECHNUNG:
-          return new XRechnungValidator(xml, parsedDocument);
+        case InvoiceFormat.XRECHNUNG: {
+          const syntax = detectInvoiceXmlSyntax(xml);
+          if (syntax === 'cii') {
+            return new FacturXValidator(xml, parsedDocument);
+          }
+          if (syntax === 'ubl') {
+            return new XRechnungValidator(xml, parsedDocument);
+          }
+          return new GenericValidator(xml, format);
+        }
 
         case InvoiceFormat.CII:
           // For now, use Factur-X validator for generic CII

package/ts/formats/pdf/extractors/associated.extractor.ts

@@ -14,7 +14,15 @@ export class AssociatedFilesExtractor extends BaseXMLExtractor {
    */
   public async extractXml(pdfBuffer: Uint8Array | Buffer): Promise<string | null> {
     try {
-      const { PDFDocument, PDFDict, PDFName, PDFRawStream, PDFArray, PDFString } = await loadPdfLib();
+      const {
+        PDFDocument,
+        PDFDict,
+        PDFName,
+        PDFRawStream,
+        PDFArray,
+        PDFString,
+        PDFHexString,
+      } = await loadPdfLib();
       const pdfDoc = await PDFDocument.load(pdfBuffer);
 
       // Try to find associated files via the AF entry in the catalog
@@ -32,8 +40,13 @@ export class AssociatedFilesExtractor extends BaseXMLExtractor {
         }
 
         // Get the file name
-        const fileNameObj = fileSpec.lookup(PDFName.of('F')) || fileSpec.lookup(PDFName.of('UF'));
-        if (!(fileNameObj instanceof PDFString)) {
+        const asciiFileName = fileSpec.lookup(PDFName.of('F'));
+        const unicodeFileName = fileSpec.lookup(PDFName.of('UF'));
+        const fileNameObj =
+          asciiFileName instanceof PDFString || asciiFileName instanceof PDFHexString
+            ? asciiFileName
+            : unicodeFileName;
+        if (!(fileNameObj instanceof PDFString) && !(fileNameObj instanceof PDFHexString)) {
           continue;
         }
 

package/ts/formats/pdf/extractors/standard.extractor.ts

@@ -13,7 +13,15 @@ export class StandardXMLExtractor extends BaseXMLExtractor {
    */
   public async extractXml(pdfBuffer: Uint8Array | Buffer): Promise<string | null> {
     try {
-      const { PDFDocument, PDFDict, PDFName, PDFRawStream, PDFArray, PDFString } = await loadPdfLib();
+      const {
+        PDFDocument,
+        PDFDict,
+        PDFName,
+        PDFRawStream,
+        PDFArray,
+        PDFString,
+        PDFHexString,
+      } = await loadPdfLib();
       const pdfDoc = await PDFDocument.load(pdfBuffer);
 
       // Get the document's metadata dictionary
@@ -42,7 +50,9 @@ export class StandardXMLExtractor extends BaseXMLExtractor {
         const fileNameObj = filesSpecObj.lookup(i);
         const fileSpecObj = filesSpecObj.lookup(i + 1);
 
-        if (!(fileNameObj instanceof PDFString) || !(fileSpecObj instanceof PDFDict)) {
+        const isFileNameString =
+          fileNameObj instanceof PDFString || fileNameObj instanceof PDFHexString;
+        if (!isFileNameString || !(fileSpecObj instanceof PDFDict)) {
           continue;
         }
 

package/ts/formats/ubl/ubl.decoder.ts

@@ -2,6 +2,7 @@ import { BaseDecoder } from '../base/base.decoder.js';
 import type { TInvoice, TCreditNote, TDebitNote } from '../../interfaces/common.js';
 import { UBLDocumentType, UBL_NAMESPACES } from './ubl.types.js';
 import { DOMParser, xpath } from '../../plugins.js';
+import { EInvoiceParsingError } from '../../errors.js';
 
 const ublParser = new DOMParser();
 const ublNamespaces = {
@@ -55,13 +56,24 @@ export abstract class UBLBaseDecoder extends BaseDecoder {
    * @returns UBL document type
    */
   protected getDocumentType(): UBLDocumentType {
-    const rootName = this.doc.documentElement.nodeName;
+    const root = this.doc.documentElement;
 
-    if (rootName === UBLDocumentType.CREDIT_NOTE) {
+    if (
+      root.localName === UBLDocumentType.CREDIT_NOTE &&
+      root.namespaceURI === UBL_NAMESPACES.CREDIT_NOTE
+    ) {
       return UBLDocumentType.CREDIT_NOTE;
-    } else {
+    }
+    if (
+      root.localName === UBLDocumentType.INVOICE &&
+      root.namespaceURI === UBL_NAMESPACES.INVOICE
+    ) {
       return UBLDocumentType.INVOICE;
     }
+
+    throw new EInvoiceParsingError('Unsupported UBL document root', {
+      format: 'ubl',
+    });
   }
 
   /**
@@ -88,6 +100,23 @@ export abstract class UBLBaseDecoder extends BaseDecoder {
     return node ? (node.textContent || '') : '';
   }
 
+  /**
+   * Gets a required UBL text value and rejects missing content.
+   */
+  protected getRequiredText(
+    xpathExpr: string,
+    fieldName: string,
+    context?: Node,
+  ): string {
+    const value = this.getText(xpathExpr, context).trim();
+    if (!value) {
+      throw new EInvoiceParsingError(`Missing required UBL ${fieldName}`, {
+        format: 'ubl',
+      });
+    }
+    return value;
+  }
+
   /**
    * Gets a number value from an XPath expression
    * @param xpath XPath expression

package/ts/formats/ubl/ubl.types.ts

@@ -6,7 +6,9 @@
 export const UBL_NAMESPACES = {
   CBC: 'urn:oasis:names:specification:ubl:schema:xsd:CommonBasicComponents-2',
   CAC: 'urn:oasis:names:specification:ubl:schema:xsd:CommonAggregateComponents-2',
-  UBL: 'urn:oasis:names:specification:ubl:schema:xsd:Invoice-2'
+  UBL: 'urn:oasis:names:specification:ubl:schema:xsd:Invoice-2',
+  INVOICE: 'urn:oasis:names:specification:ubl:schema:xsd:Invoice-2',
+  CREDIT_NOTE: 'urn:oasis:names:specification:ubl:schema:xsd:CreditNote-2',
 };
 
 // UBL document types

package/ts/formats/ubl/ubl.validator.ts

@@ -1,7 +1,7 @@
 import { BaseValidator } from '../base/base.validator.js';
 import { ValidationLevel } from '../../interfaces/common.js';
 import type { ValidationResult } from '../../interfaces/common.js';
-import { UBLDocumentType } from './ubl.types.js';
+import { UBLDocumentType, UBL_NAMESPACES } from './ubl.types.js';
 import { DOMParser, xpath } from '../../plugins.js';
 
 const ublValidatorParser = new DOMParser();
@@ -84,7 +84,13 @@ export abstract class UBLBaseValidator extends BaseValidator {
 
     // Check for root element
     const root = this.doc.documentElement;
-    if (!root || (root.nodeName !== UBLDocumentType.INVOICE && root.nodeName !== UBLDocumentType.CREDIT_NOTE)) {
+    const isInvoice =
+      root?.localName === UBLDocumentType.INVOICE &&
+      root.namespaceURI === UBL_NAMESPACES.INVOICE;
+    const isCreditNote =
+      root?.localName === UBLDocumentType.CREDIT_NOTE &&
+      root.namespaceURI === UBL_NAMESPACES.CREDIT_NOTE;
+    if (!isInvoice && !isCreditNote) {
       this.addError('UBL-SCHEMA-1', `Root element must be ${UBLDocumentType.INVOICE} or ${UBLDocumentType.CREDIT_NOTE}`, '/');
       return false;
     }

package/ts/formats/ubl/xrechnung/xrechnung.decoder.ts

@@ -45,10 +45,18 @@ export class XRechnungDecoder extends UBLBaseDecoder {
    */
   private async extractCommonData(): Promise<Partial<TInvoice>> {
     try {
-      // Default values
-      const invoiceId = this.getText('//cbc:ID', this.doc) || `INV-${Date.now()}`;
-      const issueDateText = this.getText('//cbc:IssueDate', this.doc);
-      const issueDate = issueDateText ? new Date(issueDateText).getTime() : Date.now();
+      const root = this.doc.documentElement;
+      const invoiceId = this.getRequiredText(
+        './cbc:ID',
+        'invoice identifier',
+        root,
+      );
+      const issueDateText = this.getRequiredText(
+        './cbc:IssueDate',
+        'invoice issue date',
+        root,
+      );
+      const issueDate = this.parseRequiredUblDate(issueDateText);
       const currencyCode = this.getText('//cbc:DocumentCurrencyCode', this.doc) || 'EUR';
 
       // Extract payment terms
@@ -267,36 +275,7 @@ export class XRechnungDecoder extends UBLBaseDecoder {
       
       return invoiceData;
     } catch (error) {
-      // Re-throw validation errors
-      if (error instanceof Error && error.message.includes('EN16931 validation failed')) {
-        throw error;
-      }
-      
-      console.error('Error extracting common data:', error);
-      // Return default data
-      return {
-        type: 'accounting-doc' as const,
-        accountingDocType: 'invoice' as const,
-        id: `INV-${Date.now()}`,
-        accountingDocId: `INV-${Date.now()}`,
-        date: Date.now(),
-        accountingDocStatus: 'issued' as const,
-        versionInfo: {
-          type: 'final',
-          version: '1.0.0'
-        },
-        language: 'en',
-        incidenceId: `INV-${Date.now()}`,
-        from: this.createEmptyContact(),
-        to: this.createEmptyContact(),
-        subject: 'Invoice',
-        items: [],
-        dueInDays: 30,
-        reverseCharge: false,
-        currency: 'EUR',
-        notes: [],
-        objectActions: []
-      };
+      throw error;
     }
   }
 

package/ts/formats/utils/xml.syntax.ts

@@ -0,0 +1,47 @@
+import { DOMParser } from '../../plugins.js';
+import { CII_NAMESPACES } from '../cii/cii.types.js';
+import { UBL_NAMESPACES } from '../ubl/ubl.types.js';
+
+export type TInvoiceXmlSyntax = 'cii' | 'ubl' | 'unknown';
+
+/**
+ * Detects the XML syntax independently from the invoice profile.
+ */
+export const detectInvoiceXmlSyntax = (xml: string): TInvoiceXmlSyntax => {
+  const parseDiagnostics: string[] = [];
+  const parser = new DOMParser({
+    onError: (level, message) =>
+      parseDiagnostics.push(`${level}: ${message}`),
+  });
+  let document: Document;
+  try {
+    document = parser.parseFromString(xml, 'application/xml');
+  } catch {
+    return 'unknown';
+  }
+
+  if (parseDiagnostics.length > 0) {
+    return 'unknown';
+  }
+
+  const root = document.documentElement;
+  if (!root) {
+    return 'unknown';
+  }
+
+  if (
+    root.localName === 'CrossIndustryInvoice' &&
+    root.namespaceURI === CII_NAMESPACES.RSM
+  ) {
+    return 'cii';
+  }
+
+  const isUblInvoice =
+    root.localName === 'Invoice' &&
+    root.namespaceURI === UBL_NAMESPACES.INVOICE;
+  const isUblCreditNote =
+    root.localName === 'CreditNote' &&
+    root.namespaceURI === UBL_NAMESPACES.CREDIT_NOTE;
+
+  return isUblInvoice || isUblCreditNote ? 'ubl' : 'unknown';
+};

package/ts/readme.md

@@ -36,7 +36,7 @@ const xml = await invoice.exportXml('facturx');
 | Format | Detect | Import | Export | Notes |
 | --- | --- | --- | --- | --- |
 | `ubl` | Yes | Yes | Yes | Generic UBL flow |
-| `xrechnung` | Yes | Yes | Yes | UBL-based profile |
+| `xrechnung` | Yes | Yes | Yes | UBL export; UBL and CII import |
 | `cii` | Yes | Yes | Yes | Generic export currently routes through the Factur-X encoder path |
 | `facturx` | Yes | Yes | Yes | Main CII generation path |
 | `zugferd` | Yes | Yes | Yes | Input supports v1 and v2+ |
@@ -45,6 +45,8 @@ const xml = await invoice.exportXml('facturx');
 ## Important implementation notes
 
 - `peppol` is not a root-level XML export target.
+- XRechnung import routes UBL and CII by the namespace-qualified XML root.
+  Missing or invalid document-level invoice IDs and issue dates are rejected.
 - `FatturaPA` is not fully implemented for import/export.
 - PDF support means extracting or embedding XML into existing PDFs, not generating invoice PDFs from scratch.
 - Validation is useful and extensive, but should not be documented as blanket certification.

package/ts/vendor/xmldom.ts

@@ -1,11 +1,22 @@
-import * as xmldomRuntime from 'xmldom';
+import * as xmldomRuntime from '@xmldom/xmldom';
 
 export interface IDOMParser {
   parseFromString(source: string, mimeType: string): Document;
 }
 
+export type TDOMParserErrorLevel = 'warning' | 'error' | 'fatalError';
+
+export type TDOMParserErrorHandler = (
+  level: TDOMParserErrorLevel,
+  message: string,
+) => void;
+
+export interface IDOMParserOptions {
+  onError?: TDOMParserErrorHandler;
+}
+
 export interface IDOMParserConstructor {
-  new (): IDOMParser;
+  new (options?: IDOMParserOptions): IDOMParser;
 }
 
 export interface IXMLSerializer {