@fin.cx/einvoice 5.0.2

package/ts/formats/cii/zugferd/zugferd.v1.decoder.ts

@@ -0,0 +1,267 @@
+import { CIIBaseDecoder } from '../cii.decoder.js';
+import type { TInvoice, TCreditNote, TDebitNote } from '../../../interfaces/common.js';
+import { ZUGFERD_V1_NAMESPACES } from '../cii.types.js';
+import { business, finance } from '../../../plugins.js';
+import { EN16931Validator } from '../../validation/en16931.validator.js';
+
+/**
+ * Decoder for ZUGFeRD v1 invoice format
+ */
+export class ZUGFeRDV1Decoder extends CIIBaseDecoder {
+  /**
+   * Constructor
+   * @param xml XML string to decode
+   * @param skipValidation Whether to skip EN16931 validation
+   */
+  constructor(xml: string, skipValidation: boolean = false) {
+    super(xml, skipValidation);
+    // Override namespaces for ZUGFeRD v1
+    this.namespaces = {
+      rsm: ZUGFERD_V1_NAMESPACES.RSM,
+      ram: ZUGFERD_V1_NAMESPACES.RAM,
+      udt: ZUGFERD_V1_NAMESPACES.UDT
+    };
+  }
+
+  /**
+   * Decodes a ZUGFeRD v1 credit note
+   * @returns Promise resolving to a TCreditNote object
+   */
+  protected async decodeCreditNote(): Promise<TCreditNote> {
+    // Get common invoice data
+    const commonData = await this.extractCommonData();
+
+    // Create a credit note with the common data
+    return {
+      ...commonData,
+      accountingDocType: 'creditnote' as const
+    } as unknown as TCreditNote;
+  }
+
+  /**
+   * Decodes a ZUGFeRD v1 debit note (invoice)
+   * @returns Promise resolving to a TDebitNote object
+   */
+  protected async decodeDebitNote(): Promise<TDebitNote> {
+    // Get common invoice data
+    const commonData = await this.extractCommonData();
+
+    // Create a debit note with the common data
+    return {
+      ...commonData,
+      accountingDocType: 'debitnote' as const
+    } as unknown as TDebitNote;
+  }
+
+  /**
+   * Extracts common invoice data from ZUGFeRD v1 XML
+   * @returns Common invoice data
+   */
+  private async extractCommonData(): Promise<Partial<TInvoice>> {
+    // Extract invoice ID
+    const invoiceId = this.getText('//ram:ID');
+
+    // 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);
+
+    // Extract seller information
+    const seller = this.extractParty('//ram:SellerTradeParty');
+
+    // Extract buyer information
+    const buyer = this.extractParty('//ram:BuyerTradeParty');
+
+    // Extract items
+    const items = this.extractItems();
+
+    // Extract due date
+    const dueDateStr = this.getText('//ram:SpecifiedTradePaymentTerms/ram:DueDateDateTime/udt:DateTimeString');
+    const dueDate = dueDateStr ? new Date(dueDateStr).getTime() : Date.now();
+    const dueInDays = Math.round((dueDate - issueDate) / (1000 * 60 * 60 * 24));
+
+    // Extract currency
+    const currencyCode = this.getText('//ram:InvoiceCurrencyCode') || 'EUR';
+
+    // Extract total amount (not used in this implementation but could be useful)
+    // const totalAmount = this.getNumber('//ram:GrandTotalAmount');
+
+    // Extract notes
+    const allNotes = this.extractNotes();
+
+    // Extract subject and notes separately
+    // If we have notes, the first one might be the subject
+    let subject = `Invoice ${invoiceId}`;
+    let notes = [...allNotes];
+    
+    // If the first note doesn't look like a payment term or other standard note,
+    // treat it as the subject
+    if (allNotes.length > 0 && !allNotes[0].toLowerCase().includes('due in') && 
+        !allNotes[0].toLowerCase().includes('payment')) {
+      subject = allNotes[0];
+      notes = allNotes.slice(1); // Remove subject from notes
+    }
+
+    // Check for reverse charge
+    const reverseCharge = this.exists('//ram:SpecifiedTradeAllowanceCharge/ram:ReasonCode[text()="62"]');
+
+    // Create the common invoice data
+    const invoiceData = {
+      type: 'accounting-doc' as const,
+      accountingDocType: 'invoice' as const,
+      id: invoiceId,
+      accountingDocId: invoiceId,
+      date: issueDate,
+      accountingDocStatus: 'issued' as const,
+      versionInfo: {
+        type: 'final' as const,
+        version: '1.0.0'
+      },
+      language: 'en',
+      incidenceId: invoiceId,
+      from: seller,
+      to: buyer,
+      subject: subject,
+      items: items,
+      dueInDays: dueInDays,
+      reverseCharge: reverseCharge,
+      currency: currencyCode as finance.TCurrency,
+      notes: notes,
+      deliveryDate: issueDate,
+      objectActions: []
+    };
+    
+    return invoiceData;
+  }
+
+  /**
+   * Extracts party information from ZUGFeRD v1 XML
+   * @param partyXPath XPath to the party node
+   * @returns Party information as TContact
+   */
+  private extractParty(partyXPath: string): business.TContact {
+    // Extract name
+    const name = this.getText(`${partyXPath}/ram:Name`);
+
+    // Extract address
+    const streetName = this.getText(`${partyXPath}/ram:PostalTradeAddress/ram:LineOne`);
+    const city = this.getText(`${partyXPath}/ram:PostalTradeAddress/ram:CityName`);
+    const postalCode = this.getText(`${partyXPath}/ram:PostalTradeAddress/ram:PostcodeCode`);
+    const country = this.getText(`${partyXPath}/ram:PostalTradeAddress/ram:CountryID`);
+
+    // Try to extract house number from street if possible
+    let houseNumber = '';
+    const streetParts = streetName.match(/^(.*?)\s+(\d+.*)$/);
+    if (streetParts) {
+      // If we can split into street name and house number
+      houseNumber = streetParts[2];
+    }
+
+    // Create address object
+    const address = {
+      streetName: streetName,
+      houseNumber: houseNumber,
+      city: city,
+      postalCode: postalCode,
+      countryCode: country
+    };
+
+    // Extract VAT ID
+    const vatId = this.getText(`${partyXPath}/ram:SpecifiedTaxRegistration/ram:ID[@schemeID="VA"]`) || '';
+
+    // Extract registration ID
+    const registrationId = this.getText(`${partyXPath}/ram:SpecifiedTaxRegistration/ram:ID[@schemeID="FC"]`) || '';
+
+    // Create contact object
+    return {
+      type: 'company',
+      name: name,
+      description: '',
+      address: address,
+      status: 'active',
+      foundedDate: this.createDefaultDate(),
+      registrationDetails: {
+        vatId: vatId,
+        registrationId: registrationId,
+        registrationName: ''
+      }
+    } as business.TContact;
+  }
+
+  /**
+   * Extracts invoice items from ZUGFeRD v1 XML
+   * @returns Array of invoice items
+   */
+  private extractItems(): finance.TAccountingDocItem[] {
+    const items: finance.TAccountingDocItem[] = [];
+
+    // Get all item nodes
+    const itemNodes = this.select('//ram:IncludedSupplyChainTradeLineItem', this.doc);
+
+    // Process each item
+    if (Array.isArray(itemNodes)) {
+      for (let i = 0; i < itemNodes.length; i++) {
+        const itemNode = itemNodes[i];
+
+        // Extract item data
+        const name = this.getText('ram:SpecifiedTradeProduct/ram:Name', itemNode);
+        const articleNumber = this.getText('ram:SpecifiedTradeProduct/ram:SellerAssignedID', itemNode);
+        const unitQuantity = this.getNumber('ram:SpecifiedLineTradeDelivery/ram:BilledQuantity', itemNode);
+        const unitType = this.getText('ram:SpecifiedLineTradeDelivery/ram:BilledQuantity/@unitCode', itemNode) || 'EA';
+        const unitNetPrice = this.getNumber('ram:SpecifiedLineTradeAgreement/ram:NetPriceProductTradePrice/ram:ChargeAmount', itemNode);
+        const vatPercentage = this.getNumber('ram:SpecifiedLineTradeSettlement/ram:ApplicableTradeTax/ram:RateApplicablePercent', itemNode);
+
+        // Create item object
+        items.push({
+          position: i + 1,
+          name: name,
+          articleNumber: articleNumber,
+          unitType: unitType,
+          unitQuantity: unitQuantity,
+          unitNetPrice: unitNetPrice,
+          vatPercentage: vatPercentage
+        });
+      }
+    }
+
+    return items;
+  }
+
+  /**
+   * Extracts notes from ZUGFeRD v1 XML
+   * @returns Array of notes
+   */
+  private extractNotes(): string[] {
+    const notes: string[] = [];
+
+    // Get all note nodes
+    const noteNodes = this.select('//ram:IncludedNote', this.doc);
+
+    // Process each note
+    if (Array.isArray(noteNodes)) {
+      for (let i = 0; i < noteNodes.length; i++) {
+        const noteNode = noteNodes[i];
+        const noteText = this.getText('ram:Content', noteNode);
+
+        if (noteText) {
+          notes.push(noteText);
+        }
+      }
+    }
+
+    return notes;
+  }
+
+  /**
+   * Creates a default date for empty date fields
+   * @returns Default date object compatible with TContact
+   */
+  private createDefaultDate(): any {
+    // Create a date object that will be compatible with TContact
+    return {
+      year: 2000,
+      month: 1,
+      day: 1
+    };
+  }
+}

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

@@ -0,0 +1,31 @@
+import { CIIBaseValidator } from '../cii.validator.js';
+
+/**
+ * Validator for ZUGFeRD invoice format
+ */
+export class ZUGFeRDValidator extends CIIBaseValidator {
+  /**
+   * Validates ZUGFeRD XML structure
+   * @returns True if structure validation passed
+   */
+  protected validateStructure(): boolean {
+    // Check for required elements in ZUGFeRD structure
+    const invoiceId = this.getText('//rsm:ExchangedDocument/ram:ID');
+    if (!invoiceId) {
+      this.addError('ZUGFERD-STRUCT-1', 'Invoice ID is required', '//rsm:ExchangedDocument/ram:ID');
+      return false;
+    }
+
+    return true;
+  }
+
+  /**
+   * Validates ZUGFeRD XML against business rules
+   * @returns True if business validation passed
+   */
+  protected validateBusinessRules(): boolean {
+    // Implement ZUGFeRD-specific business rules
+    // For now, we'll just use the base CII validation
+    return true;
+  }
+}

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

@@ -0,0 +1,62 @@
+import { BaseDecoder } from '../base/base.decoder.js';
+import { InvoiceFormat } from '../../interfaces/common.js';
+import { FormatDetector } from '../utils/format.detector.js';
+
+// Import specific decoders
+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';
+
+/**
+ * Factory to create the appropriate decoder based on the XML format
+ */
+export class DecoderFactory {
+  /**
+   * Creates a decoder for the specified XML content
+   * @param xml XML content to decode
+   * @param skipValidation Whether to skip EN16931 validation
+   * @returns Appropriate decoder instance
+   */
+  public static createDecoder(xml: string, skipValidation: boolean = false): BaseDecoder {
+    const format = FormatDetector.detectFormat(xml);
+
+    switch (format) {
+      case InvoiceFormat.UBL:
+      case InvoiceFormat.XRECHNUNG:
+        return new XRechnungDecoder(xml, skipValidation);
+
+      case InvoiceFormat.CII:
+        // For now, use Factur-X decoder for generic CII
+        return new FacturXDecoder(xml, skipValidation);
+
+      case InvoiceFormat.ZUGFERD:
+        // Determine if it's ZUGFeRD v1 or v2 based on root element
+        if (xml.includes('CrossIndustryDocument') ||
+            xml.includes('urn:ferd:CrossIndustryDocument:invoice:1p0') ||
+            (xml.includes('ZUGFeRD') && !xml.includes('CrossIndustryInvoice'))) {
+          return new ZUGFeRDV1Decoder(xml, skipValidation);
+        } else {
+          return new ZUGFeRDDecoder(xml, skipValidation);
+        }
+
+      case InvoiceFormat.FACTURX:
+        return new FacturXDecoder(xml, skipValidation);
+
+      case InvoiceFormat.FATTURAPA:
+        // return new FatturaPADecoder(xml);
+        throw new Error('FatturaPA decoder not yet implemented');
+
+      default:
+        // If format is unknown but contains CrossIndustryInvoice, try ZUGFeRD decoder
+        if (xml.includes('CrossIndustryInvoice')) {
+          return new ZUGFeRDDecoder(xml, skipValidation);
+        }
+        // If format is unknown but contains CrossIndustryDocument, try ZUGFeRD v1 decoder
+        if (xml.includes('CrossIndustryDocument')) {
+          return new ZUGFeRDV1Decoder(xml, skipValidation);
+        }
+        throw new Error(`Unsupported invoice format: ${format}`);
+    }
+  }
+}

package/ts/formats/factories/encoder.factory.ts

@@ -0,0 +1,47 @@
+import { BaseEncoder } from '../base/base.encoder.js';
+import { InvoiceFormat } from '../../interfaces/common.js';
+import type { ExportFormat } from '../../interfaces/common.js';
+
+// Import specific encoders
+import { UBLEncoder } from '../ubl/generic/ubl.encoder.js';
+import { XRechnungEncoder } from '../ubl/xrechnung/xrechnung.encoder.js';
+import { FacturXEncoder } from '../cii/facturx/facturx.encoder.js';
+import { ZUGFeRDEncoder } from '../cii/zugferd/zugferd.encoder.js';
+
+/**
+ * Factory to create the appropriate encoder based on the target format
+ */
+export class EncoderFactory {
+  /**
+   * Creates an encoder for the specified format
+   * @param format Target format for encoding
+   * @returns Appropriate encoder instance
+   */
+  public static createEncoder(format: ExportFormat | InvoiceFormat): BaseEncoder {
+    switch (format.toLowerCase()) {
+      case InvoiceFormat.UBL:
+      case 'ubl':
+        return new UBLEncoder();
+
+      case InvoiceFormat.XRECHNUNG:
+      case 'xrechnung':
+        return new XRechnungEncoder();
+
+      case InvoiceFormat.CII:
+        // For now, use Factur-X encoder for generic CII
+        return new FacturXEncoder();
+
+      case InvoiceFormat.ZUGFERD:
+      case 'zugferd':
+        // Use dedicated ZUGFeRD encoder
+        return new ZUGFeRDEncoder();
+
+      case InvoiceFormat.FACTURX:
+      case 'facturx':
+        return new FacturXEncoder();
+
+      default:
+        throw new Error(`Unsupported invoice format for encoding: ${format}`);
+    }
+  }
+}

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

@@ -0,0 +1,134 @@
+import { BaseValidator } from '../base/base.validator.js';
+import { InvoiceFormat, ValidationLevel } from '../../interfaces/common.js';
+import type { ValidationResult } from '../../interfaces/common.js';
+import { FormatDetector } from '../utils/format.detector.js';
+
+// Import specific validators
+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';
+
+// The EN16931UBLValidator handles all UBL-based formats with proper business rules
+// No need for legacy validator implementations here
+
+/**
+ * FatturaPA validator implementation
+ * Basic implementation for Italian electronic invoices
+ */
+class FatturaPAValidator extends BaseValidator {
+  validate(level: ValidationLevel = ValidationLevel.SYNTAX): ValidationResult {
+    // Reset errors
+    this.errors = [];
+    
+    let valid = true;
+    
+    if (level === ValidationLevel.SYNTAX) {
+      valid = this.validateSchema();
+    } else if (level === ValidationLevel.SEMANTIC || level === ValidationLevel.BUSINESS) {
+      valid = this.validateSchema() && this.validateBusinessRules();
+    }
+    
+    return {
+      valid,
+      errors: this.errors,
+      level
+    };
+  }
+
+  protected validateSchema(): boolean {
+    // Basic schema validation for FatturaPA
+    if (!this.xml.includes('<FatturaElettronica')) {
+      this.addError('FATT-SCHEMA-1', 'Root element must be FatturaElettronica', '/');
+      return false;
+    }
+    return true;
+  }
+
+  protected validateBusinessRules(): boolean {
+    // Basic placeholder implementation - would need more detailed rules
+    // for a real implementation
+    return this.validateSchema();
+  }
+}
+
+/**
+ * Factory to create the appropriate validator based on the XML format
+ */
+export class ValidatorFactory {
+  /**
+   * Creates a validator for the specified XML content
+   * @param xml XML content to validate
+   * @returns Appropriate validator instance
+   */
+  public static createValidator(xml: string): BaseValidator {
+    try {
+      const format = FormatDetector.detectFormat(xml);
+
+      switch (format) {
+        case InvoiceFormat.UBL:
+          return new EN16931UBLValidator(xml);
+
+        case InvoiceFormat.XRECHNUNG:
+          return new XRechnungValidator(xml);
+
+        case InvoiceFormat.CII:
+          // For now, use Factur-X validator for generic CII
+          return new FacturXValidator(xml);
+
+        case InvoiceFormat.ZUGFERD:
+          return new ZUGFeRDValidator(xml);
+
+        case InvoiceFormat.FACTURX:
+          return new FacturXValidator(xml);
+
+        case InvoiceFormat.FATTURAPA:
+          return new FatturaPAValidator(xml);
+
+        default:
+          // For unknown formats, provide a generic validator that will
+          // mark the document as invalid but won't throw an exception
+          return new GenericValidator(xml, format);
+      }
+    } catch (error) {
+      // If an error occurs during validator creation, return a generic validator
+      // that will provide meaningful error information instead of throwing
+      console.error(`Error creating validator: ${error}`);
+      return new GenericValidator(xml, 'unknown');
+    }
+  }
+}
+
+/**
+ * Generic validator for unknown or unsupported formats
+ * Provides meaningful validation errors instead of throwing exceptions
+ */
+class GenericValidator extends BaseValidator {
+  private format: string;
+
+  constructor(xml: string, format: string) {
+    super(xml);
+    this.format = format;
+    this.addError(
+      'GEN-1',
+      `Unsupported invoice format: ${format}`,
+      '/'
+    );
+  }
+
+  validate(level: ValidationLevel = ValidationLevel.SYNTAX): ValidationResult {
+    return {
+      valid: false,
+      errors: this.errors,
+      level
+    };
+  }
+
+  protected validateSchema(): boolean {
+    return false;
+  }
+
+  protected validateBusinessRules(): boolean {
+    return false;
+  }
+}

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

@@ -0,0 +1,78 @@
+import { PDFDocument, PDFDict, PDFName, PDFRawStream, PDFArray, PDFString } from '../../../plugins.js';
+import { BaseXMLExtractor } from './base.extractor.js';
+
+/**
+ * Associated files extractor for PDF/A-3 documents
+ * Extracts XML from associated files (AF entry in the catalog)
+ * Particularly useful for ZUGFeRD v1 and some Factur-X documents
+ */
+export class AssociatedFilesExtractor extends BaseXMLExtractor {
+  /**
+   * Extract XML from a PDF buffer using associated files
+   * @param pdfBuffer PDF buffer
+   * @returns XML content or null if not found
+   */
+  public async extractXml(pdfBuffer: Uint8Array | Buffer): Promise<string | null> {
+    try {
+      const pdfDoc = await PDFDocument.load(pdfBuffer);
+
+      // Try to find associated files via the AF entry in the catalog
+      const afArray = pdfDoc.catalog.lookup(PDFName.of('AF'));
+      if (!(afArray instanceof PDFArray)) {
+        console.warn('No AF (Associated Files) entry found in PDF catalog');
+        return null;
+      }
+
+      // Process each associated file
+      for (let i = 0; i < afArray.size(); i++) {
+        const fileSpec = afArray.lookup(i);
+        if (!(fileSpec instanceof PDFDict)) {
+          continue;
+        }
+
+        // Get the file name
+        const fileNameObj = fileSpec.lookup(PDFName.of('F')) || fileSpec.lookup(PDFName.of('UF'));
+        if (!(fileNameObj instanceof PDFString)) {
+          continue;
+        }
+
+        const fileName = fileNameObj.decodeText();
+
+        // Check if it's a known invoice XML file name
+        const isKnownFileName = this.knownFileNames.some(
+          knownName => fileName.toLowerCase() === knownName.toLowerCase()
+        );
+
+        // Check if it's any XML file or has invoice-related keywords
+        const isXmlFile = fileName.toLowerCase().endsWith('.xml') ||
+                          fileName.toLowerCase().includes('zugferd') ||
+                          fileName.toLowerCase().includes('factur-x') ||
+                          fileName.toLowerCase().includes('xrechnung') ||
+                          fileName.toLowerCase().includes('invoice');
+
+        if (isKnownFileName || isXmlFile) {
+          // Get the embedded file dictionary
+          const efDict = fileSpec.lookup(PDFName.of('EF'));
+          if (!(efDict instanceof PDFDict)) {
+            continue;
+          }
+
+          // Get the file stream
+          const fileStream = efDict.lookup(PDFName.of('F'));
+          if (fileStream instanceof PDFRawStream) {
+            const xmlContent = await this.extractXmlFromStream(fileStream, fileName);
+            if (xmlContent) {
+              return xmlContent;
+            }
+          }
+        }
+      }
+
+      console.warn('No valid XML found in associated files');
+      return null;
+    } catch (error) {
+      console.error('Error in associated files extraction:', error);
+      return null;
+    }
+  }
+}