@fin.cx/einvoice 5.0.2

package/ts/formats/pdf/pdf.embedder.ts

@@ -0,0 +1,242 @@
+import { PDFDocument, AFRelationship } from '../../plugins.js';
+import type { IPdf } from '../../interfaces/common.js';
+
+/**
+ * Error types for PDF embedding operations
+ */
+export enum PDFEmbedError {
+  LOAD_ERROR = 'PDF loading failed',
+  EMBED_ERROR = 'XML embedding failed',
+  SAVE_ERROR = 'PDF saving failed',
+  INVALID_INPUT = 'Invalid input parameters'
+}
+
+/**
+ * Result of a PDF embedding operation
+ */
+export interface PDFEmbedResult {
+  success: boolean;
+  data?: Uint8Array;
+  pdf?: IPdf;
+  error?: {
+    type: PDFEmbedError;
+    message: string;
+    originalError?: Error;
+  };
+}
+
+/**
+ * Class for embedding XML into PDF files
+ * Provides robust error handling and support for different PDF formats
+ */
+export class PDFEmbedder {
+  /**
+   * Embeds XML into a PDF
+   * @param pdfBuffer PDF buffer
+   * @param xmlContent XML content to embed
+   * @param filename Filename for the embedded XML
+   * @param description Description for the embedded XML
+   * @returns Result with either modified PDF buffer or error information
+   */
+  public async embedXml(
+    pdfBuffer: Uint8Array | Buffer,
+    xmlContent: string,
+    filename: string = 'invoice.xml',
+    description: string = 'XML Invoice'
+  ): Promise<PDFEmbedResult> {
+    try {
+      // Validate inputs
+      if (!pdfBuffer || pdfBuffer.length === 0) {
+        return this.createErrorResult(PDFEmbedError.INVALID_INPUT, 'PDF buffer is empty or undefined');
+      }
+      
+      if (!xmlContent) {
+        return this.createErrorResult(PDFEmbedError.INVALID_INPUT, 'XML content is empty or undefined');
+      }
+
+      // Ensure buffer is Uint8Array
+      const pdfBufferArray = Buffer.isBuffer(pdfBuffer) ? new Uint8Array(pdfBuffer) : pdfBuffer;
+
+      // Load the PDF
+      let pdfDoc: PDFDocument;
+      try {
+        pdfDoc = await PDFDocument.load(pdfBufferArray, {
+          ignoreEncryption: true,  // Try to load encrypted PDFs
+          updateMetadata: false    // Don't automatically update metadata
+        });
+      } catch (error) {
+        return this.createErrorResult(
+          PDFEmbedError.LOAD_ERROR,
+          `Failed to load PDF: ${error instanceof Error ? error.message : String(error)}`,
+          error instanceof Error ? error : undefined
+        );
+      }
+
+      // Normalize filename (lowercase with XML extension)
+      filename = this.normalizeFilename(filename);
+
+      // Convert the XML string to a Uint8Array
+      const xmlBuffer = new TextEncoder().encode(xmlContent);
+
+      try {
+        // Use pdf-lib's .attach() to embed the XML
+        pdfDoc.attach(xmlBuffer, filename, {
+          mimeType: 'text/xml',
+          description: description,
+          creationDate: new Date(),
+          modificationDate: new Date(),
+          afRelationship: AFRelationship.Alternative,
+        });
+      } catch (error) {
+        return this.createErrorResult(
+          PDFEmbedError.EMBED_ERROR,
+          `Failed to embed XML: ${error instanceof Error ? error.message : String(error)}`,
+          error instanceof Error ? error : undefined
+        );
+      }
+
+      // Save the modified PDF
+      let modifiedPdfBytes: Uint8Array;
+      try {
+        modifiedPdfBytes = await pdfDoc.save({
+          addDefaultPage: false,           // Don't add a page if the document is empty
+          useObjectStreams: false,        // Better compatibility with older PDF readers
+          updateFieldAppearances: false   // Don't update form fields
+        });
+      } catch (error) {
+        return this.createErrorResult(
+          PDFEmbedError.SAVE_ERROR,
+          `Failed to save modified PDF: ${error instanceof Error ? error.message : String(error)}`,
+          error instanceof Error ? error : undefined
+        );
+      }
+
+      return {
+        success: true,
+        data: modifiedPdfBytes
+      };
+    } catch (error) {
+      // Catch any uncaught errors
+      return this.createErrorResult(
+        PDFEmbedError.EMBED_ERROR,
+        `Unexpected error during XML embedding: ${error instanceof Error ? error.message : String(error)}`,
+        error instanceof Error ? error : undefined
+      );
+    }
+  }
+
+  /**
+   * Creates an IPdf object with embedded XML
+   * @param pdfBuffer PDF buffer
+   * @param xmlContent XML content to embed
+   * @param filename Filename for the embedded XML
+   * @param description Description for the embedded XML
+   * @param pdfName Name for the PDF
+   * @param pdfId ID for the PDF
+   * @returns Result with either IPdf object or error information
+   */
+  public async createPdfWithXml(
+    pdfBuffer: Uint8Array | Buffer,
+    xmlContent: string,
+    filename: string = 'invoice.xml',
+    description: string = 'XML Invoice',
+    pdfName: string = 'invoice.pdf',
+    pdfId: string = `invoice-${Date.now()}`
+  ): Promise<PDFEmbedResult> {
+    // Embed XML into PDF
+    const embedResult = await this.embedXml(pdfBuffer, xmlContent, filename, description);
+    
+    // If embedding failed, return the error
+    if (!embedResult.success || !embedResult.data) {
+      return embedResult;
+    }
+
+    // Create IPdf object
+    const pdfObject: IPdf = {
+      name: pdfName,
+      id: pdfId,
+      metadata: {
+        textExtraction: '',
+        format: this.detectPdfFormat(xmlContent),
+        embeddedXml: {
+          filename: filename,
+          description: description
+        }
+      },
+      buffer: embedResult.data
+    };
+
+    return {
+      success: true,
+      pdf: pdfObject
+    };
+  }
+
+  /**
+   * Ensures the filename is normalized according to PDF/A requirements
+   * @param filename Filename to normalize
+   * @returns Normalized filename
+   */
+  private normalizeFilename(filename: string): string {
+    // Convert to lowercase
+    let normalized = filename.toLowerCase();
+    
+    // Ensure it has .xml extension
+    if (!normalized.endsWith('.xml')) {
+      normalized = normalized.replace(/\.[^/.]+$/, '') + '.xml';
+    }
+    
+    // Replace invalid characters
+    normalized = normalized.replace(/[^a-z0-9_.-]/g, '_');
+    
+    return normalized;
+  }
+
+  /**
+   * Tries to detect the format of the XML content
+   * @param xmlContent XML content
+   * @returns Format string or undefined
+   */
+  private detectPdfFormat(xmlContent: string): string | undefined {
+    if (xmlContent.includes('factur-x.eu') || xmlContent.includes('factur-x.xml')) {
+      return 'factur-x';
+    } else if (xmlContent.includes('zugferd') || xmlContent.includes('ZUGFeRD')) {
+      return 'zugferd';
+    } else if (xmlContent.includes('xrechnung')) {
+      return 'xrechnung';
+    } else if (xmlContent.includes('<Invoice') || xmlContent.includes('<CreditNote')) {
+      return 'ubl';
+    } else if (xmlContent.includes('FatturaElettronica')) {
+      return 'fatturapa';
+    }
+    
+    return undefined;
+  }
+
+  /**
+   * Creates an error result object
+   * @param type Error type
+   * @param message Error message
+   * @param originalError Original error object
+   * @returns Error result
+   */
+  private createErrorResult(
+    type: PDFEmbedError,
+    message: string,
+    originalError?: Error
+  ): PDFEmbedResult {
+    console.error(`PDF Embedder Error (${type}): ${message}`);
+    if (originalError) {
+      console.error(originalError);
+    }
+    
+    return {
+      success: false,
+      error: {
+        type,
+        message,
+        originalError
+      }
+    };
+  }
+}

package/ts/formats/pdf/pdf.extractor.ts

@@ -0,0 +1,141 @@
+import {
+  BaseXMLExtractor,
+  StandardXMLExtractor,
+  AssociatedFilesExtractor,
+  TextXMLExtractor
+} from './extractors/index.js';
+import { FormatDetector } from '../utils/format.detector.js';
+import { InvoiceFormat } from '../../interfaces/common.js';
+
+/**
+ * Error types for PDF extraction operations
+ */
+export enum PDFExtractError {
+  EXTRACT_ERROR = 'XML extraction failed',
+  INVALID_INPUT = 'Invalid input parameters',
+  NO_XML_FOUND = 'No XML found in PDF'
+}
+
+/**
+ * Result of a PDF extraction operation
+ */
+export interface PDFExtractResult {
+  success: boolean;
+  xml?: string;
+  format?: InvoiceFormat;
+  extractorUsed?: string;
+  error?: {
+    type: PDFExtractError;
+    message: string;
+    originalError?: Error;
+  };
+}
+
+/**
+ * Main PDF extractor class that orchestrates the extraction process
+ * Uses multiple specialized extractors in sequence to maximize success rate
+ */
+export class PDFExtractor {
+  private extractors: BaseXMLExtractor[] = [];
+
+  /**
+   * Constructor initializes the chain of extractors
+   */
+  constructor() {
+    // Add extractors in order of preference/likelihood of success
+    this.extractors.push(
+      new StandardXMLExtractor(),      // Standard PDF/A-3 embedded files
+      new AssociatedFilesExtractor(),  // Associated files (ZUGFeRD v1, some Factur-X)
+      new TextXMLExtractor()           // Text-based extraction (fallback)
+    );
+  }
+
+  /**
+   * Extract XML from a PDF buffer
+   * Tries multiple extraction methods in sequence
+   * @param pdfBuffer PDF buffer
+   * @returns Result with either the extracted XML or error information
+   */
+  public async extractXml(pdfBuffer: Uint8Array | Buffer): Promise<PDFExtractResult> {
+    try {
+      console.log('Starting XML extraction from PDF...');
+
+      // Validate input
+      if (!pdfBuffer || pdfBuffer.length === 0) {
+        return this.createErrorResult(PDFExtractError.INVALID_INPUT, 'PDF buffer is empty or undefined');
+      }
+
+      // Ensure buffer is Uint8Array
+      const pdfBufferArray = Buffer.isBuffer(pdfBuffer) ? new Uint8Array(pdfBuffer) : pdfBuffer;
+
+      // Try each extractor in sequence
+      for (const extractor of this.extractors) {
+        const extractorName = extractor.constructor.name;
+        console.log(`Trying extraction with ${extractorName}...`);
+
+        try {
+          const xml = await extractor.extractXml(pdfBufferArray);
+          
+          if (xml) {
+            console.log(`Successfully extracted XML using ${extractorName}`);
+            
+            // Detect format of the extracted XML
+            const format = FormatDetector.detectFormat(xml);
+            
+            return {
+              success: true,
+              xml,
+              format,
+              extractorUsed: extractorName
+            };
+          }
+          
+          console.log(`Extraction with ${extractorName} failed, trying next method...`);
+        } catch (error) {
+          // Log error but continue with next extractor
+          console.warn(`Error using ${extractorName}: ${error instanceof Error ? error.message : String(error)}`);
+        }
+      }
+
+      // If all extractors fail, return a no XML found error
+      return this.createErrorResult(
+        PDFExtractError.NO_XML_FOUND,
+        'All extraction methods failed, no valid XML found in PDF'
+      );
+    } catch (error) {
+      // Handle any unexpected errors
+      return this.createErrorResult(
+        PDFExtractError.EXTRACT_ERROR,
+        `Unexpected error during XML extraction: ${error instanceof Error ? error.message : String(error)}`,
+        error instanceof Error ? error : undefined
+      );
+    }
+  }
+
+  /**
+   * Create a PDF extract result with error information
+   * @param type Error type
+   * @param message Error message
+   * @param originalError Original error object
+   * @returns Error result
+   */
+  private createErrorResult(
+    type: PDFExtractError,
+    message: string,
+    originalError?: Error
+  ): PDFExtractResult {
+    console.error(`PDF Extractor Error (${type}): ${message}`);
+    if (originalError) {
+      console.error(originalError);
+    }
+    
+    return {
+      success: false,
+      error: {
+        type,
+        message,
+        originalError
+      }
+    };
+  }
+}

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

@@ -0,0 +1,216 @@
+import { UBLBaseValidator } from './ubl.validator.js';
+import { ValidationLevel } from '../../interfaces/common.js';
+import { xpath } from '../../plugins.js';
+
+/**
+ * EN16931-compliant UBL validator that implements all business rules
+ */
+export class EN16931UBLValidator extends UBLBaseValidator {
+  /**
+   * Validates the structure of the UBL document
+   */
+  protected validateStructure(): boolean {
+    let valid = true;
+
+    // Check for required elements
+    const requiredElements = [
+      { path: '//cbc:ID', error: 'Required element cbc:ID is missing' },
+      { path: '//cbc:IssueDate', error: 'Required element cbc:IssueDate is missing' },
+      { path: '//cbc:CustomizationID', error: 'Required element cbc:CustomizationID is missing' }
+    ];
+
+    for (const element of requiredElements) {
+      if (!this.exists(element.path)) {
+        this.addError('STRUCT-REQUIRED', element.error, element.path);
+        valid = false;
+      }
+    }
+
+    // Check for at least one invoice line or credit note line
+    const invoiceLines = this.select('//cac:InvoiceLine', this.doc) as Node[];
+    const creditNoteLines = this.select('//cac:CreditNoteLine', this.doc) as Node[];
+    
+    if (invoiceLines.length === 0 && creditNoteLines.length === 0) {
+      this.addError('STRUCT-LINE', 'At least one invoice line or credit note line is required', '/');
+      valid = false;
+    }
+
+    return valid;
+  }
+
+  /**
+   * Validates EN16931 business rules
+   */
+  protected validateBusinessRules(): boolean {
+    let valid = true;
+
+    // BR-01: An Invoice shall have a Specification identifier (BT-24).
+    if (!this.exists('//cbc:CustomizationID')) {
+      this.addError('BR-01', 'An Invoice shall have a Specification identifier', '//cbc:CustomizationID');
+      valid = false;
+    }
+
+    // BR-02: An Invoice shall have an Invoice number (BT-1).
+    if (!this.exists('//cbc:ID')) {
+      this.addError('BR-02', 'An Invoice shall have an Invoice number', '//cbc:ID');
+      valid = false;
+    }
+
+    // BR-03: An Invoice shall have an Invoice issue date (BT-2).
+    if (!this.exists('//cbc:IssueDate')) {
+      this.addError('BR-03', 'An Invoice shall have an Invoice issue date', '//cbc:IssueDate');
+      valid = false;
+    }
+
+    // BR-04: An Invoice shall have an Invoice type code (BT-3).
+    const isInvoice = this.doc.documentElement.localName === 'Invoice';
+    if (isInvoice && !this.exists('//cbc:InvoiceTypeCode')) {
+      this.addError('BR-04', 'An Invoice shall have an Invoice type code', '//cbc:InvoiceTypeCode');
+      valid = false;
+    }
+
+    // BR-05: An Invoice shall have an Invoice currency code (BT-5).
+    if (!this.exists('//cbc:DocumentCurrencyCode')) {
+      this.addError('BR-05', 'An Invoice shall have an Invoice currency code', '//cbc:DocumentCurrencyCode');
+      valid = false;
+    }
+
+    // BR-06: An Invoice shall contain the Seller name (BT-27).
+    if (!this.exists('//cac:AccountingSupplierParty//cbc:RegistrationName') && 
+        !this.exists('//cac:AccountingSupplierParty//cbc:Name')) {
+      this.addError('BR-06', 'An Invoice shall contain the Seller name', '//cac:AccountingSupplierParty');
+      valid = false;
+    }
+
+    // BR-07: An Invoice shall contain the Buyer name (BT-44).
+    if (!this.exists('//cac:AccountingCustomerParty//cbc:RegistrationName') && 
+        !this.exists('//cac:AccountingCustomerParty//cbc:Name')) {
+      this.addError('BR-07', 'An Invoice shall contain the Buyer name', '//cac:AccountingCustomerParty');
+      valid = false;
+    }
+
+    // BR-08: An Invoice shall contain the Seller postal address (BG-5).
+    const sellerAddress = this.select('//cac:AccountingSupplierParty//cac:PostalAddress', this.doc)[0];
+    if (!sellerAddress || !this.exists('.//cbc:IdentificationCode', sellerAddress)) {
+      this.addError('BR-08', 'An Invoice shall contain the Seller postal address', '//cac:AccountingSupplierParty//cac:PostalAddress');
+      valid = false;
+    }
+
+    // BR-09: The Seller postal address (BG-5) shall contain a Seller country code (BT-40).
+    if (sellerAddress && !this.exists('.//cac:Country/cbc:IdentificationCode', sellerAddress)) {
+      this.addError('BR-09', 'The Seller postal address shall contain a Seller country code', '//cac:AccountingSupplierParty//cac:PostalAddress//cac:Country');
+      valid = false;
+    }
+
+    // BR-10: An Invoice shall contain the Buyer postal address (BG-8).
+    const buyerAddress = this.select('//cac:AccountingCustomerParty//cac:PostalAddress', this.doc)[0];
+    if (!buyerAddress || !this.exists('.//cbc:IdentificationCode', buyerAddress)) {
+      this.addError('BR-10', 'An Invoice shall contain the Buyer postal address', '//cac:AccountingCustomerParty//cac:PostalAddress');
+      valid = false;
+    }
+
+    // BR-11: The Buyer postal address (BG-8) shall contain a Buyer country code (BT-55).
+    if (buyerAddress && !this.exists('.//cac:Country/cbc:IdentificationCode', buyerAddress)) {
+      this.addError('BR-11', 'The Buyer postal address shall contain a Buyer country code', '//cac:AccountingCustomerParty//cac:PostalAddress//cac:Country');
+      valid = false;
+    }
+
+    // BR-12: An Invoice shall have the Sum of Invoice line net amount (BT-106).
+    if (!this.exists('//cac:LegalMonetaryTotal/cbc:LineExtensionAmount')) {
+      this.addError('BR-12', 'An Invoice shall have the Sum of Invoice line net amount', '//cac:LegalMonetaryTotal/cbc:LineExtensionAmount');
+      valid = false;
+    }
+
+    // BR-13: An Invoice shall have the Invoice total amount without VAT (BT-109).
+    if (!this.exists('//cac:LegalMonetaryTotal/cbc:TaxExclusiveAmount')) {
+      this.addError('BR-13', 'An Invoice shall have the Invoice total amount without VAT', '//cac:LegalMonetaryTotal/cbc:TaxExclusiveAmount');
+      valid = false;
+    }
+
+    // BR-14: An Invoice shall have the Invoice total amount with VAT (BT-112).
+    if (!this.exists('//cac:LegalMonetaryTotal/cbc:TaxInclusiveAmount')) {
+      this.addError('BR-14', 'An Invoice shall have the Invoice total amount with VAT', '//cac:LegalMonetaryTotal/cbc:TaxInclusiveAmount');
+      valid = false;
+    }
+
+    // BR-15: An Invoice shall have the Amount due for payment (BT-115).
+    if (!this.exists('//cac:LegalMonetaryTotal/cbc:PayableAmount')) {
+      this.addError('BR-15', 'An Invoice shall have the Amount due for payment', '//cac:LegalMonetaryTotal/cbc:PayableAmount');
+      valid = false;
+    }
+
+    // BR-16: An Invoice shall have at least one Invoice line (BG-25).
+    const lines = this.select('//cac:InvoiceLine | //cac:CreditNoteLine', this.doc) as Node[];
+    if (lines.length === 0) {
+      this.addError('BR-16', 'An Invoice shall have at least one Invoice line', '//cac:InvoiceLine');
+      valid = false;
+    }
+
+    // Validate calculation rules if we have the necessary data
+    if (this.exists('//cac:LegalMonetaryTotal/cbc:LineExtensionAmount')) {
+      valid = this.validateCalculationRules() && valid;
+    }
+
+    return valid;
+  }
+
+  /**
+   * Validates calculation rules (BR-CO-*)
+   */
+  private validateCalculationRules(): boolean {
+    let valid = true;
+
+    // BR-CO-10: Sum of Invoice line net amount = Σ Invoice line net amount.
+    const lineExtensionAmount = this.getNumber('//cac:LegalMonetaryTotal/cbc:LineExtensionAmount');
+    const lines = this.select('//cac:InvoiceLine | //cac:CreditNoteLine', this.doc) as Node[];
+    
+    let calculatedSum = 0;
+    for (const line of lines) {
+      const lineAmount = this.getNumber('.//cbc:LineExtensionAmount', line);
+      calculatedSum += lineAmount;
+    }
+
+    // Allow for small rounding differences (0.01)
+    if (Math.abs(lineExtensionAmount - calculatedSum) > 0.01) {
+      this.addError(
+        'BR-CO-10', 
+        `Sum of Invoice line net amount (${lineExtensionAmount}) must equal sum of line amounts (${calculatedSum})`,
+        '//cac:LegalMonetaryTotal/cbc:LineExtensionAmount'
+      );
+      valid = false;
+    }
+
+    // BR-CO-13: Invoice total amount without VAT = Σ Invoice line net amount - Sum of allowances on document level + Sum of charges on document level.
+    const taxExclusiveAmount = this.getNumber('//cac:LegalMonetaryTotal/cbc:TaxExclusiveAmount');
+    const allowanceTotal = this.getNumber('//cac:LegalMonetaryTotal/cbc:AllowanceTotalAmount') || 0;
+    const chargeTotal = this.getNumber('//cac:LegalMonetaryTotal/cbc:ChargeTotalAmount') || 0;
+    
+    const calculatedTaxExclusive = lineExtensionAmount - allowanceTotal + chargeTotal;
+    
+    if (Math.abs(taxExclusiveAmount - calculatedTaxExclusive) > 0.01) {
+      this.addError(
+        'BR-CO-13',
+        `Invoice total amount without VAT (${taxExclusiveAmount}) must equal calculated amount (${calculatedTaxExclusive})`,
+        '//cac:LegalMonetaryTotal/cbc:TaxExclusiveAmount'
+      );
+      valid = false;
+    }
+
+    // BR-CO-15: Invoice total amount with VAT = Invoice total amount without VAT + Invoice total VAT amount.
+    const taxInclusiveAmount = this.getNumber('//cac:LegalMonetaryTotal/cbc:TaxInclusiveAmount');
+    const totalTaxAmount = this.getNumber('//cac:TaxTotal/cbc:TaxAmount') || 0;
+    
+    const calculatedTaxInclusive = taxExclusiveAmount + totalTaxAmount;
+    
+    if (Math.abs(taxInclusiveAmount - calculatedTaxInclusive) > 0.01) {
+      this.addError(
+        'BR-CO-15',
+        `Invoice total amount with VAT (${taxInclusiveAmount}) must equal calculated amount (${calculatedTaxInclusive})`,
+        '//cac:LegalMonetaryTotal/cbc:TaxInclusiveAmount'
+      );
+      valid = false;
+    }
+
+    return valid;
+  }
+}