feat(ZUGFERD): Add dedicated ZUGFERD v1/v2 support and refine invoice format detection logic

ts/formats/cii/cii.types.ts

@@ -2,13 +2,20 @@
  * CII-specific types and constants
  */
 
-// CII namespaces
+// CII namespaces (ZUGFeRD v2/Factur-X)
 export const CII_NAMESPACES = {
   RSM: 'urn:un:unece:uncefact:data:standard:CrossIndustryInvoice:100',
   RAM: 'urn:un:unece:uncefact:data:standard:ReusableAggregateBusinessInformationEntity:100',
   UDT: 'urn:un:unece:uncefact:data:standard:UnqualifiedDataType:100'
 };
 
+// ZUGFeRD v1 namespaces
+export const ZUGFERD_V1_NAMESPACES = {
+  RSM: 'urn:ferd:CrossIndustryDocument:invoice:1p0',
+  RAM: 'urn:un:unece:uncefact:data:standard:ReusableAggregateBusinessInformationEntity:12',
+  UDT: 'urn:un:unece:uncefact:data:standard:UnqualifiedDataType:15'
+};
+
 // CII profiles
 export enum CIIProfile {
   BASIC = 'BASIC',
@@ -20,10 +27,18 @@ export enum CIIProfile {
 
 // CII profile IDs for different formats
 export const CII_PROFILE_IDS = {
+  // Factur-X profiles
   FACTURX_MINIMUM: 'urn:factur-x.eu:1p0:minimum',
   FACTURX_BASIC: 'urn:factur-x.eu:1p0:basicwl',
   FACTURX_EN16931: 'urn:cen.eu:en16931:2017',
+
+  // ZUGFeRD v2 profiles
   ZUGFERD_BASIC: 'urn:zugferd:basic',
   ZUGFERD_COMFORT: 'urn:zugferd:comfort',
-  ZUGFERD_EXTENDED: 'urn:zugferd:extended'
+  ZUGFERD_EXTENDED: 'urn:zugferd:extended',
+
+  // ZUGFeRD v1 profiles
+  ZUGFERD_V1_BASIC: 'urn:ferd:CrossIndustryDocument:invoice:1p0:basic',
+  ZUGFERD_V1_COMFORT: 'urn:ferd:CrossIndustryDocument:invoice:1p0:comfort',
+  ZUGFERD_V1_EXTENDED: 'urn:ferd:CrossIndustryDocument:invoice:1p0:extended'
 };

ts/formats/cii/zugferd/zugferd.decoder.ts

@@ -0,0 +1,220 @@
+import { CIIBaseDecoder } from '../cii.decoder.js';
+import type { TInvoice, TCreditNote, TDebitNote } from '../../../interfaces/common.js';
+import { ZUGFERD_PROFILE_IDS } from './zugferd.types.js';
+import { business, finance, general } from '@tsclass/tsclass';
+
+/**
+ * Decoder for ZUGFeRD invoice format
+ */
+export class ZUGFeRDDecoder extends CIIBaseDecoder {
+  /**
+   * Decodes a ZUGFeRD 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,
+      invoiceType: 'creditnote'
+    } as TCreditNote;
+  }
+
+  /**
+   * Decodes a ZUGFeRD 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,
+      invoiceType: 'debitnote'
+    } as TDebitNote;
+  }
+
+  /**
+   * Extracts common invoice data from ZUGFeRD XML
+   * @returns Common invoice data
+   */
+  private async extractCommonData(): Promise<Partial<TInvoice>> {
+    // Extract invoice ID
+    const invoiceId = this.getText('//rsm:ExchangedDocument/ram:ID');
+
+    // Extract issue date
+    const issueDateStr = this.getText('//ram:IssueDateTime/udt:DateTimeString');
+    const issueDate = issueDateStr ? new Date(issueDateStr).getTime() : Date.now();
+
+    // 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
+    const totalAmount = this.getNumber('//ram:GrandTotalAmount');
+
+    // Extract notes
+    const notes = this.extractNotes();
+
+    // Check for reverse charge
+    const reverseCharge = this.exists('//ram:SpecifiedTradeAllowanceCharge/ram:ReasonCode[text()="62"]');
+
+    // Create the common invoice data
+    return {
+      type: 'invoice',
+      id: invoiceId,
+      date: issueDate,
+      status: 'invoice',
+      versionInfo: {
+        type: 'final',
+        version: '1.0.0'
+      },
+      language: 'en',
+      incidenceId: invoiceId,
+      from: seller,
+      to: buyer,
+      subject: `Invoice ${invoiceId}`,
+      items: items,
+      dueInDays: dueInDays,
+      reverseCharge: reverseCharge,
+      currency: currencyCode as finance.TCurrency,
+      notes: notes,
+      deliveryDate: issueDate,
+      objectActions: [],
+      invoiceType: 'debitnote' // Default to debit note, will be overridden in decode methods
+    };
+  }
+
+  /**
+   * Extracts party information from ZUGFeRD 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 street = this.getText(`${partyXPath}/ram:PostalTradeAddress/ram:LineOne`);
+    const city = this.getText(`${partyXPath}/ram:PostalTradeAddress/ram:CityName`);
+    const zip = this.getText(`${partyXPath}/ram:PostalTradeAddress/ram:PostcodeCode`);
+    const country = this.getText(`${partyXPath}/ram:PostalTradeAddress/ram:CountryID`);
+
+    // Create address object
+    const address = {
+      street: street,
+      city: city,
+      zip: zip,
+      country: 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 XML
+   * @returns Array of invoice items
+   */
+  private extractItems(): finance.TInvoiceItem[] {
+    const items: finance.TInvoiceItem[] = [];
+
+    // 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 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 as timestamp
+   */
+  private createDefaultDate(): number {
+    return new Date('2000-01-01').getTime();
+  }
+}

ts/formats/cii/zugferd/zugferd.encoder.ts

@@ -0,0 +1,21 @@
+import { CIIBaseEncoder } from '../cii.encoder.js';
+import type { TInvoice } from '../../../interfaces/common.js';
+import { ZUGFERD_PROFILE_IDS } from './zugferd.types.js';
+
+/**
+ * Encoder for ZUGFeRD invoice format
+ */
+export class ZUGFeRDEncoder extends CIIBaseEncoder {
+  /**
+   * Creates ZUGFeRD XML from invoice data
+   * @param invoice Invoice data
+   * @returns ZUGFeRD XML string
+   */
+  public async createXml(invoice: TInvoice): Promise<string> {
+    // Set ZUGFeRD-specific profile ID
+    this.profileId = ZUGFERD_PROFILE_IDS.BASIC;
+    
+    // Use the base CII encoder to create the XML
+    return super.createXml(invoice);
+  }
+}

ts/formats/cii/zugferd/zugferd.types.ts

@@ -0,0 +1,18 @@
+import { CIIProfile, CII_PROFILE_IDS } from '../cii.types.js';
+
+/**
+ * ZUGFeRD specific constants and types
+ */
+
+// ZUGFeRD profile IDs
+export const ZUGFERD_PROFILE_IDS = {
+  BASIC: CII_PROFILE_IDS.ZUGFERD_BASIC,
+  COMFORT: CII_PROFILE_IDS.ZUGFERD_COMFORT,
+  EXTENDED: CII_PROFILE_IDS.ZUGFERD_EXTENDED
+};
+
+// ZUGFeRD PDF attachment filename
+export const ZUGFERD_ATTACHMENT_FILENAME = 'zugferd-invoice.xml';
+
+// ZUGFeRD PDF attachment description
+export const ZUGFERD_ATTACHMENT_DESCRIPTION = 'ZUGFeRD XML Invoice';

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

@@ -0,0 +1,234 @@
+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, general } from '@tsclass/tsclass';
+
+/**
+ * Decoder for ZUGFeRD v1 invoice format
+ */
+export class ZUGFeRDV1Decoder extends CIIBaseDecoder {
+  /**
+   * Constructor
+   * @param xml XML string to decode
+   */
+  constructor(xml: string) {
+    super(xml);
+    // 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,
+      invoiceType: 'creditnote'
+    } 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,
+      invoiceType: 'debitnote'
+    } 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 issueDate = issueDateStr ? new Date(issueDateStr).getTime() : Date.now();
+
+    // 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
+    const totalAmount = this.getNumber('//ram:GrandTotalAmount');
+
+    // Extract notes
+    const notes = this.extractNotes();
+
+    // Check for reverse charge
+    const reverseCharge = this.exists('//ram:SpecifiedTradeAllowanceCharge/ram:ReasonCode[text()="62"]');
+
+    // Create the common invoice data
+    return {
+      type: 'invoice',
+      id: invoiceId,
+      date: issueDate,
+      status: 'invoice',
+      versionInfo: {
+        type: 'final',
+        version: '1.0.0'
+      },
+      language: 'en',
+      incidenceId: invoiceId,
+      from: seller,
+      to: buyer,
+      subject: `Invoice ${invoiceId}`,
+      items: items,
+      dueInDays: dueInDays,
+      reverseCharge: reverseCharge,
+      currency: currencyCode as finance.TCurrency,
+      notes: notes,
+      deliveryDate: issueDate,
+      objectActions: [],
+      invoiceType: 'debitnote' // Default to debit note, will be overridden in decode methods
+    };
+  }
+
+  /**
+   * 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 street = this.getText(`${partyXPath}/ram:PostalTradeAddress/ram:LineOne`);
+    const city = this.getText(`${partyXPath}/ram:PostalTradeAddress/ram:CityName`);
+    const zip = this.getText(`${partyXPath}/ram:PostalTradeAddress/ram:PostcodeCode`);
+    const country = this.getText(`${partyXPath}/ram:PostalTradeAddress/ram:CountryID`);
+
+    // Create address object
+    const address = {
+      street: street,
+      city: city,
+      zip: zip,
+      country: 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.TInvoiceItem[] {
+    const items: finance.TInvoiceItem[] = [];
+
+    // 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 as timestamp
+   */
+  private createDefaultDate(): number {
+    return new Date('2000-01-01').getTime();
+  }
+}

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

@@ -0,0 +1,18 @@
+import { CIIBaseValidator } from '../cii.validator.js';
+import { ValidationLevel } from '../../../interfaces/common.js';
+import type { ValidationResult } from '../../../interfaces/common.js';
+
+/**
+ * Validator for ZUGFeRD invoice format
+ */
+export class ZUGFeRDValidator extends CIIBaseValidator {
+  /**
+   * 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;
+  }
+}