@fin.cx/einvoice 5.0.2

package/ts/formats/cii/cii.types.ts

@@ -0,0 +1,44 @@
+/**
+ * CII-specific types and constants
+ */
+
+// 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',
+  COMFORT = 'COMFORT',
+  EXTENDED = 'EXTENDED',
+  EN16931 = 'EN16931',
+  MINIMUM = 'MINIMUM'
+}
+
+// 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 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'
+};

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

@@ -0,0 +1,171 @@
+import { BaseValidator } from '../base/base.validator.js';
+import { ValidationLevel } from '../../interfaces/common.js';
+import type { ValidationResult } from '../../interfaces/common.js';
+import { CII_NAMESPACES, CIIProfile } from './cii.types.js';
+import { DOMParser, xpath } from '../../plugins.js';
+
+/**
+ * Base validator for CII-based invoice formats
+ */
+export abstract class CIIBaseValidator extends BaseValidator {
+  protected doc: Document;
+  protected namespaces: Record<string, string>;
+  protected select: xpath.XPathSelect;
+  protected profile: CIIProfile = CIIProfile.EN16931;
+
+  constructor(xml: string) {
+    super(xml);
+
+    try {
+      // Parse XML document
+      this.doc = new DOMParser().parseFromString(xml, 'application/xml');
+
+      // Set up namespaces for XPath queries
+      this.namespaces = {
+        rsm: CII_NAMESPACES.RSM,
+        ram: CII_NAMESPACES.RAM,
+        udt: CII_NAMESPACES.UDT
+      };
+
+      // Create XPath selector with namespaces
+      this.select = xpath.useNamespaces(this.namespaces);
+
+      // Detect profile
+      this.detectProfile();
+    } catch (error) {
+      this.addError('CII-PARSE', `Failed to parse XML: ${error}`, '/');
+    }
+  }
+
+  /**
+   * Validates CII XML against the specified level of validation
+   * @param level Validation level
+   * @returns Result of validation
+   */
+  public validate(level: ValidationLevel = ValidationLevel.SYNTAX): ValidationResult {
+    // Reset errors
+    this.errors = [];
+
+    // Check if document was parsed successfully
+    if (!this.doc) {
+      return {
+        valid: false,
+        errors: this.errors,
+        level: level
+      };
+    }
+
+    // Perform validation based on level
+    let valid = true;
+
+    if (level === ValidationLevel.SYNTAX) {
+      valid = this.validateSchema();
+    } else if (level === ValidationLevel.SEMANTIC) {
+      valid = this.validateSchema() && this.validateStructure();
+    } else if (level === ValidationLevel.BUSINESS) {
+      valid = this.validateSchema() &&
+              this.validateStructure() &&
+              this.validateBusinessRules();
+    }
+
+    return {
+      valid,
+      errors: this.errors,
+      level
+    };
+  }
+
+  /**
+   * Validates CII XML against schema
+   * @returns True if schema validation passed
+   */
+  protected validateSchema(): boolean {
+    // Basic schema validation (simplified for now)
+    if (!this.doc) return false;
+
+    // Check for root element
+    const root = this.doc.documentElement;
+    if (!root || root.nodeName !== 'rsm:CrossIndustryInvoice') {
+      this.addError('CII-SCHEMA-1', 'Root element must be rsm:CrossIndustryInvoice', '/');
+      return false;
+    }
+
+    // Check for required namespaces
+    if (!root.lookupNamespaceURI('rsm') || !root.lookupNamespaceURI('ram')) {
+      this.addError('CII-SCHEMA-2', 'Required namespaces rsm and ram must be declared', '/');
+      return false;
+    }
+
+    return true;
+  }
+
+  /**
+   * Validates structure of the CII XML document
+   * @returns True if structure validation passed
+   */
+  protected abstract validateStructure(): boolean;
+
+  /**
+   * Detects the CII profile from the XML
+   */
+  protected detectProfile(): void {
+    // Look for profile identifier
+    const profileNode = this.select(
+      'string(//rsm:ExchangedDocumentContext/ram:GuidelineSpecifiedDocumentContextParameter/ram:ID)',
+      this.doc
+    );
+
+    if (profileNode) {
+      const profileText = profileNode.toString();
+
+      if (profileText.includes('BASIC')) {
+        this.profile = CIIProfile.BASIC;
+      } else if (profileText.includes('EN16931')) {
+        this.profile = CIIProfile.EN16931;
+      } else if (profileText.includes('EXTENDED')) {
+        this.profile = CIIProfile.EXTENDED;
+      } else if (profileText.includes('MINIMUM')) {
+        this.profile = CIIProfile.MINIMUM;
+      } else if (profileText.includes('COMFORT')) {
+        this.profile = CIIProfile.COMFORT;
+      }
+    }
+  }
+
+  /**
+   * Gets a text value from an XPath expression
+   * @param xpath XPath expression
+   * @param context Optional context node
+   * @returns Text value or empty string if not found
+   */
+  protected getText(xpathExpr: string, context?: Node): string {
+    const node = this.select(xpathExpr, context || this.doc)[0];
+    return node ? (node.textContent || '') : '';
+  }
+
+  /**
+   * Gets a number value from an XPath expression
+   * @param xpath XPath expression
+   * @param context Optional context node
+   * @returns Number value or 0 if not found or not a number
+   */
+  protected getNumber(xpathExpr: string, context?: Node): number {
+    const text = this.getText(xpathExpr, context);
+    const num = parseFloat(text);
+    return isNaN(num) ? 0 : num;
+  }
+
+  /**
+   * Checks if a node exists
+   * @param xpath XPath expression
+   * @param context Optional context node
+   * @returns True if node exists
+   */
+  protected exists(xpathExpr: string, context?: Node): boolean {
+    const nodes = this.select(xpathExpr, context || this.doc);
+    if (Array.isArray(nodes)) {
+      return nodes.length > 0;
+    }
+    return false;
+  }
+}

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

@@ -0,0 +1,243 @@
+import { CIIBaseDecoder } from '../cii.decoder.js';
+import type { TInvoice, TCreditNote, TDebitNote } from '../../../interfaces/common.js';
+import { FACTURX_PROFILE_IDS } from './facturx.types.js';
+import { business, finance, general } from '../../../plugins.js';
+import { EN16931Validator } from '../../validation/en16931.validator.js';
+
+/**
+ * Decoder for Factur-X invoice format
+ */
+export class FacturXDecoder extends CIIBaseDecoder {
+  /**
+   * Decodes a Factur-X 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 Factur-X 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 Factur-X 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 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 dueDateFormat = this.getText('//ram:SpecifiedTradePaymentTerms/ram:DueDateDateTime/udt:DateTimeString/@format');
+    const dueDate = dueDateStr ? this.parseCIIDate(dueDateStr, dueDateFormat) : issueDate;
+    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 allNotes = this.extractNotes();
+
+    // Extract subject and notes separately
+    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: []
+    };
+    
+    // Validate mandatory EN16931 fields unless validation is skipped
+    if (!this.skipValidation) {
+      EN16931Validator.validateMandatoryFields(invoiceData);
+    }
+    
+    return invoiceData;
+  }
+
+  /**
+   * Extracts party information from Factur-X 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 address: business.IAddress = {
+      streetName: this.getText(`${partyXPath}/ram:PostalTradeAddress/ram:LineOne`) || '',
+      houseNumber: this.getText(`${partyXPath}/ram:PostalTradeAddress/ram:LineTwo`) || '0',
+      postalCode: this.getText(`${partyXPath}/ram:PostalTradeAddress/ram:PostcodeCode`) || '',
+      city: this.getText(`${partyXPath}/ram:PostalTradeAddress/ram:CityName`) || '',
+      country: this.getText(`${partyXPath}/ram:PostalTradeAddress/ram:CountryID`) || '',
+      countryCode: this.getText(`${partyXPath}/ram:PostalTradeAddress/ram:CountryID`) || ''
+    };
+
+    // 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 Factur-X 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 Factur-X 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 object
+   * @returns Default date object
+   */
+  private createDefaultDate(): general.IDate {
+    return {
+      year: 2000,
+      month: 1,
+      day: 1
+    };
+  }
+}