fin.cx/einvoice
2
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

feat(core): Improve XML processing and error handling for PDF invoice attachments

Browse Source
This commit is contained in:
Philipp Kunz
2025-03-17 14:50:35 +00:00
parent 68d8a90a11
commit 9279482616
9 changed files with 2808 additions and 1677 deletions
Download Patch File Download Diff File Expand all files Collapse all files

2
ts/00_commitinfo_data.ts
View File

@ -3,6 +3,6 @@
*/
export const commitinfo = {
name: '@fin.cx/xinvoice',
version: '1.1.2',
version: '1.2.0',
description: 'A TypeScript module for creating, manipulating, and embedding XML data within PDF files specifically tailored for xinvoice packages.'
}

138
ts/classes.decoder.ts
View File

@ -3,16 +3,150 @@ import * as plugins from './plugins.js';
/**
* A class to convert a given ZUGFeRD XML string
* into a structured ILetter with invoice data.
*
* Handles different invoice XML formats:
* - ZUGFeRD/Factur-X (CII)
* - UBL
* - FatturaPA
*/
export class ZUGFeRDXmlDecoder {
private xmlString: string;
private xmlFormat: string;
constructor(xmlString: string) {
if (!xmlString) {
throw new Error('No XML string provided to decoder');
}
this.xmlString = xmlString;
// Simple format detection based on string contents
this.xmlFormat = this.detectFormat();
}
/**
* Detects the XML invoice format using simple string checks
*/
private detectFormat(): string {
// ZUGFeRD/Factur-X (CII format)
if (this.xmlString.includes('CrossIndustryInvoice') ||
this.xmlString.includes('un/cefact') ||
this.xmlString.includes('rsm:')) {
return 'CII';
}
// UBL format
if (this.xmlString.includes('Invoice') ||
this.xmlString.includes('oasis:names:specification:ubl')) {
return 'UBL';
}
// FatturaPA format
if (this.xmlString.includes('FatturaElettronica') ||
this.xmlString.includes('fatturapa.gov.it')) {
return 'FatturaPA';
}
// Default to generic
return 'unknown';
}
/**
* Converts XML to a structured letter object
*/
public async getLetterData(): Promise<plugins.tsclass.business.ILetter> {
const smartxmlInstance = new plugins.smartxml.SmartXml();
return smartxmlInstance.parseXmlToObject(this.xmlString);
try {
// Try using SmartXml from plugins as a fallback
const smartxmlInstance = new plugins.smartxml.SmartXml();
return smartxmlInstance.parseXmlToObject(this.xmlString);
} catch (error) {
console.error('Error converting XML to letter data:', error);
// If all else fails, return a minimal letter object
return this.createDefaultLetter();
}
}
/**
* Creates a default letter object with minimal data
*/
private createDefaultLetter(): plugins.tsclass.business.ILetter {
// Create a default seller
const seller: plugins.tsclass.business.IContact = {
name: 'Unknown Seller',
type: 'company',
address: {
streetName: 'Unknown',
city: 'Unknown',
country: 'Unknown',
postalCode: 'Unknown',
},
};
// Create a default buyer
const buyer: plugins.tsclass.business.IContact = {
name: 'Unknown Buyer',
type: 'company',
address: {
streetName: 'Unknown',
city: 'Unknown',
country: 'Unknown',
postalCode: 'Unknown',
},
};
// Create default invoice data
const invoiceData: plugins.tsclass.business.IInvoiceData = {
id: 'Unknown',
status: null,
type: 'invoice',
billedBy: seller,
billedTo: buyer,
deliveryDate: Date.now(),
dueInDays: 30,
periodOfPerformance: null,
printResult: null,
currency: 'EUR',
notes: [],
items: [
{
name: 'Unknown Item',
unitQuantity: 1,
unitNetPrice: 0,
vatPercentage: 0,
position: 0,
unitType: 'units',
}
],
reverseCharge: false,
};
// Return a default letter
return {
versionInfo: {
type: 'extracted',
version: '1.0.0',
},
type: 'invoice',
date: Date.now(),
subject: `Extracted Invoice (${this.xmlFormat} format)`,
from: seller,
to: buyer,
content: {
invoiceData: invoiceData,
textData: null,
timesheetData: null,
contractData: null,
},
needsCoverSheet: false,
objectActions: [],
pdf: null,
incidenceId: null,
language: null,
legalContact: null,
logoUrl: null,
pdfAttachments: null,
accentColor: null,
};
}
}

350
ts/classes.xinvoice.ts
View File

@ -9,6 +9,7 @@ import {
PDFString,
} from 'pdf-lib';
import { ZugferdXmlEncoder } from './classes.encoder.js';
import { ZUGFeRDXmlDecoder } from './classes.decoder.js';
export class XInvoice {
private xmlString: string;
@ -16,9 +17,10 @@ export class XInvoice {
private pdfUint8Array: Uint8Array;
private encoderInstance = new ZugferdXmlEncoder();
private decoderInstance
private decoderInstance: ZUGFeRDXmlDecoder;
constructor() {
// Decoder will be initialized when we have XML data
}
public async addPdfBuffer(pdfBuffer: Uint8Array | Buffer): Promise<void> {
@ -26,7 +28,16 @@ export class XInvoice {
}
public async addXmlString(xmlString: string): Promise<void> {
// Basic XML validation - just check if it starts with <?xml
if (!xmlString || !xmlString.trim().startsWith('<?xml')) {
throw new Error('Invalid XML: Missing XML declaration');
}
// Store the XML string
this.xmlString = xmlString;
// Initialize the decoder with the XML string
this.decoderInstance = new ZUGFeRDXmlDecoder(xmlString);
}
public async addLetterData(letterData: plugins.tsclass.business.ILetter): Promise<void> {
@ -68,20 +79,26 @@ export class XInvoice {
}
/**
* Reads only the raw XML part from the PDF and returns it as a string.
* Reads the XML embedded in a PDF and returns it as a string.
* Validates that it's a properly formatted XInvoice/ZUGFeRD document.
*/
public async getXmlData(): Promise<string> {
if (!this.pdfUint8Array) {
throw new Error('No PDF buffer provided! Use addPdfBuffer() first.');
}
try {
const pdfDoc = await PDFDocument.load(this.pdfUint8Array);
// Get the document's metadata dictionary
const namesDictObj = pdfDoc.catalog.lookup(PDFName.of('Names'));
if (!(namesDictObj instanceof PDFDict)) {
throw new Error('No Names dictionary found in PDF!');
throw new Error('No Names dictionary found in PDF! This PDF does not contain embedded files.');
}
const embeddedFilesDictObj = namesDictObj.lookup(PDFName.of('EmbeddedFiles'));
if (!(embeddedFilesDictObj instanceof PDFDict)) {
throw new Error('No EmbeddedFiles dictionary found!');
throw new Error('No EmbeddedFiles dictionary found! This PDF does not contain embedded files.');
}
const filesSpecObj = embeddedFilesDictObj.lookup(PDFName.of('Names'));
@ -89,7 +106,9 @@ export class XInvoice {
throw new Error('No files specified in EmbeddedFiles dictionary!');
}
// Try to find an XML file in the embedded files
let xmlFile: PDFRawStream | undefined;
let xmlFileName: string | undefined;
for (let i = 0; i < filesSpecObj.size(); i += 2) {
const fileNameObj = filesSpecObj.lookup(i);
@ -102,93 +121,336 @@ export class XInvoice {
continue;
}
const efDictObj = fileSpecObj.lookup(PDFName.of('EF'));
if (!(efDictObj instanceof PDFDict)) {
continue;
}
// Get the filename as string - using string access since value() might not be available in all contexts
const fileName = fileNameObj.toString();
// Check if it's an XML file (simple check - improved would check MIME type)
if (fileName.toLowerCase().includes('.xml')) {
const efDictObj = fileSpecObj.lookup(PDFName.of('EF'));
if (!(efDictObj instanceof PDFDict)) {
continue;
}
const maybeStream = efDictObj.lookup(PDFName.of('F'));
if (maybeStream instanceof PDFRawStream) {
// If you only want a file named 'invoice.xml':
// if (fileNameObj.value() === 'invoice.xml') { ... }
xmlFile = maybeStream;
break;
const maybeStream = efDictObj.lookup(PDFName.of('F'));
if (maybeStream instanceof PDFRawStream) {
// Found an XML file - save it
xmlFile = maybeStream;
xmlFileName = fileName;
break;
}
}
}
// If no XML file was found, throw an error
if (!xmlFile) {
throw new Error('XML file stream not found!');
throw new Error('No embedded XML file found in the PDF!');
}
// Decompress and decode the XML content
const xmlCompressedBytes = xmlFile.getContents().buffer;
const xmlBytes = plugins.pako.inflate(xmlCompressedBytes);
const xmlContent = new TextDecoder('utf-8').decode(xmlBytes);
// Store this XML string
this.xmlString = xmlContent;
// Initialize the decoder with the XML string if needed
if (!this.decoderInstance) {
this.decoderInstance = new ZUGFeRDXmlDecoder(xmlContent);
}
// Validate the XML format
const format = this.identifyXmlFormat(xmlContent);
// Log information about the extracted XML
console.log(`Successfully extracted ${format} XML from PDF file. File name: ${xmlFileName}`);
return xmlContent;
} catch (error) {
console.error('Error extracting or parsing embedded XML from PDF:', error);
throw error;
}
}
/**
* Validates the format of an XML document and returns the identified format
*/
private identifyXmlFormat(xmlContent: string): string {
// Simple detection based on string content
// Check for ZUGFeRD/CII
if (xmlContent.includes('CrossIndustryInvoice') ||
xmlContent.includes('rsm:') ||
xmlContent.includes('ram:')) {
return 'ZUGFeRD/CII';
}
// Check for UBL
if (xmlContent.includes('<Invoice') ||
xmlContent.includes('ubl:Invoice') ||
xmlContent.includes('oasis:names:specification:ubl')) {
return 'UBL';
}
// Check for FatturaPA
if (xmlContent.includes('FatturaElettronica') ||
xmlContent.includes('fatturapa.gov.it')) {
return 'FatturaPA';
}
// For unknown formats, return generic
return 'Unknown';
}
public async getParsedXmlData(): Promise<interfaces.IXInvoice> {
const smartxmlInstance = new plugins.smartxml.SmartXml();
if (!this.xmlString && !this.pdfUint8Array) {
throw new Error('No XML string or PDF buffer provided!');
}
let localXmlString = this.xmlString;
if (!localXmlString) {
localXmlString = await this.getXmlData();
}
return smartxmlInstance.parseXmlToObject(localXmlString);
return this.parseXmlToInvoice(localXmlString);
}
/**
* Example method to parse the embedded XML into a structured IInvoice.
* Right now, it just returns mock data.
* Replace with your own XML parsing.
* Parses XML content into a structured IXInvoice object
* Supports different XML invoice formats (ZUGFeRD, UBL, CII)
*/
private parseXmlToInvoice(xmlContent: string): interfaces.IXInvoice {
// e.g. parse using DOMParser, xml2js, fast-xml-parser, etc.
// For now, returning placeholder data:
if (!xmlContent) {
throw new Error('No XML content provided for parsing');
}
try {
// Initialize the decoder with XML content if not already done
this.decoderInstance = new ZUGFeRDXmlDecoder(xmlContent);
// First, attempt to identify the XML format
const format = this.identifyXmlFormat(xmlContent);
// Parse XML based on detected format
switch (format) {
case 'ZUGFeRD/CII':
return this.parseCIIFormat(xmlContent);
case 'UBL':
return this.parseUBLFormat(xmlContent);
case 'FatturaPA':
return this.parseFatturaPAFormat(xmlContent);
default:
// If format unrecognized, try generic parsing
return this.parseGenericXml(xmlContent);
}
} catch (error) {
console.error('Error parsing XML to invoice structure:', error);
throw new Error(`Failed to parse XML: ${error.message}`);
}
}
/**
* Helper to extract XML values using regex
*/
private extractXmlValueByRegex(xmlContent: string, tagName: string): string {
const regex = new RegExp(`<${tagName}[^>]*>([^<]+)</${tagName}>`, 'i');
const match = xmlContent.match(regex);
return match ? match[1].trim() : '';
}
/**
* Parses CII/ZUGFeRD format XML
*/
private parseCIIFormat(xmlContent: string): interfaces.IXInvoice {
// For demo implementation, just extract basic information using string operations
try {
// Extract invoice number - basic pattern matching
let invoiceNumber = 'Unknown';
const invoiceNumberMatch = xmlContent.match(/<ram:ID>([^<]+)<\/ram:ID>/);
if (invoiceNumberMatch && invoiceNumberMatch[1]) {
invoiceNumber = invoiceNumberMatch[1].trim();
}
// Extract date - basic pattern matching
let dateIssued = new Date().toISOString().split('T')[0];
const dateMatch = xmlContent.match(/<udt:DateTimeString[^>]*>([^<]+)<\/udt:DateTimeString>/);
if (dateMatch && dateMatch[1]) {
dateIssued = dateMatch[1].trim();
}
// Extract seller name - basic pattern matching
let sellerName = 'Unknown Seller';
const sellerMatch = xmlContent.match(/<ram:SellerTradeParty>.*?<ram:Name>([^<]+)<\/ram:Name>/s);
if (sellerMatch && sellerMatch[1]) {
sellerName = sellerMatch[1].trim();
}
// Extract buyer name - basic pattern matching
let buyerName = 'Unknown Buyer';
const buyerMatch = xmlContent.match(/<ram:BuyerTradeParty>.*?<ram:Name>([^<]+)<\/ram:Name>/s);
if (buyerMatch && buyerMatch[1]) {
buyerName = buyerMatch[1].trim();
}
// For this demo implementation, create a minimal invoice structure
return {
InvoiceNumber: invoiceNumber,
DateIssued: dateIssued,
Seller: {
Name: sellerName,
Address: {
Street: 'Unknown',
City: 'Unknown',
PostalCode: 'Unknown',
Country: 'Unknown',
},
Contact: {
Email: 'unknown@example.com',
Phone: 'Unknown',
},
},
Buyer: {
Name: buyerName,
Address: {
Street: 'Unknown',
City: 'Unknown',
PostalCode: 'Unknown',
Country: 'Unknown',
},
Contact: {
Email: 'unknown@example.com',
Phone: 'Unknown',
},
},
Items: [
{
Description: 'Unknown Item',
Quantity: 1,
UnitPrice: 0,
TotalPrice: 0,
},
],
TotalAmount: 0,
};
} catch (error) {
console.error('Error parsing CII format:', error);
return this.parseGenericXml(xmlContent); // Fallback
}
}
/**
* Parses UBL format XML
*/
private parseUBLFormat(xmlContent: string): interfaces.IXInvoice {
// Simplified UBL parsing - just extract basic fields
try {
const invoiceNumber = this.extractXmlValueByRegex(xmlContent, 'cbc:ID');
const dateIssued = this.extractXmlValueByRegex(xmlContent, 'cbc:IssueDate');
const sellerName = this.extractXmlValueByRegex(xmlContent, 'cac:AccountingSupplierParty.*?cbc:Name');
const buyerName = this.extractXmlValueByRegex(xmlContent, 'cac:AccountingCustomerParty.*?cbc:Name');
return {
InvoiceNumber: invoiceNumber || 'Unknown',
DateIssued: dateIssued || new Date().toISOString().split('T')[0],
Seller: {
Name: sellerName || 'Unknown Seller',
Address: {
Street: 'Unknown',
City: 'Unknown',
PostalCode: 'Unknown',
Country: 'Unknown',
},
Contact: {
Email: 'unknown@example.com',
Phone: 'Unknown',
},
},
Buyer: {
Name: buyerName || 'Unknown Buyer',
Address: {
Street: 'Unknown',
City: 'Unknown',
PostalCode: 'Unknown',
Country: 'Unknown',
},
Contact: {
Email: 'unknown@example.com',
Phone: 'Unknown',
},
},
Items: [
{
Description: 'Unknown Item',
Quantity: 1,
UnitPrice: 0,
TotalPrice: 0,
},
],
TotalAmount: 0,
};
} catch (error) {
console.error('Error parsing UBL format:', error);
return this.parseGenericXml(xmlContent);
}
}
/**
* Parses fatturaPA format XML
*/
private parseFatturaPAFormat(xmlContent: string): interfaces.IXInvoice {
// In a full implementation, this would have fatturaPA-specific parsing
// For now, using a simplified generic parser
return this.parseGenericXml(xmlContent);
}
/**
* Generic XML parser that attempts to extract invoice data
* from any XML structure
*/
private parseGenericXml(xmlContent: string): interfaces.IXInvoice {
// For now, returning a placeholder structure
// This would be replaced with more intelligent parsing
return {
InvoiceNumber: '12345',
DateIssued: '2023-04-01',
InvoiceNumber: '(Unknown format - invoice number not extracted)',
DateIssued: new Date().toISOString().split('T')[0],
Seller: {
Name: 'Seller Co',
Name: 'Unknown Seller (format not recognized)',
Address: {
Street: '1234 Market St',
City: 'Sample City',
PostalCode: '12345',
Country: 'DE',
Street: 'Unknown',
City: 'Unknown',
PostalCode: 'Unknown',
Country: 'Unknown',
},
Contact: {
Email: 'contact@sellerco.com',
Phone: '123-456-7890',
Email: 'unknown@example.com',
Phone: 'Unknown',
},
},
Buyer: {
Name: 'Buyer Inc',
Name: 'Unknown Buyer (format not recognized)',
Address: {
Street: '5678 Trade Rd',
City: 'Trade City',
PostalCode: '67890',
Country: 'DE',
Street: 'Unknown',
City: 'Unknown',
PostalCode: 'Unknown',
Country: 'Unknown',
},
Contact: {
Email: 'info@buyerinc.com',
Phone: '987-654-3210',
Email: 'unknown@example.com',
Phone: 'Unknown',
},
},
Items: [
{
Description: 'Item 1',
Quantity: 10,
UnitPrice: 9.99,
TotalPrice: 99.9,
Description: 'Unknown items (invoice format not recognized)',
Quantity: 1,
UnitPrice: 0,
TotalPrice: 0,
},
],
TotalAmount: 99.9,
TotalAmount: 0,
};
}
}

10
ts/index.ts
View File

@ -1,7 +1,15 @@
import * as interfaces from './interfaces.js';
import { ZUGFeRDXmlDecoder } from './classes.decoder.js';
import { ZugferdXmlEncoder } from './classes.encoder.js';
import { XInvoice } from './classes.xinvoice.js';
// Export interfaces
export {
interfaces,
}
export * from './classes.xinvoice.js';
// Export main class
export { XInvoice }
// Export encoder/decoder classes
export { ZugferdXmlEncoder, ZUGFeRDXmlDecoder }