fix(documentation): Improve readme documentation for better clarity on PDF handling, XML validation and error reporting

2025-04-04 13:34:30 +00:00 · 2025-04-04 13:34:30 +00:00 · 17e2b2d6dd
commit 17e2b2d6dd
parent df836502ce
3 changed files with 162 additions and 31 deletions
--- a/changelog.md
+++ b/changelog.md
@ -1,5 +1,13 @@
 # Changelog

+## 2025-04-04 - 4.2.2 - fix(documentation)
+Improve readme documentation for better clarity on PDF handling, XML validation and error reporting
+
+- Clarify that PDF extraction now includes multiple fallback strategies and robust error handling
+- Update usage examples to include payment options, detailed invoice item specifications and proper PDF embedding procedures
+- Enhance description of invoice format detection and validation with detailed error reporting
+- Improve overall readme clarity by updating instructions and code snippet examples
+
 ## 2025-04-04 - 4.2.1 - fix(release)
 No changes detected in project files; project remains in sync.

--- a/readme.md
+++ b/readme.md
@ -5,11 +5,12 @@ A comprehensive TypeScript library for creating, manipulating, and embedding XML
 ## Features

 - **Multi-format support**: Process invoices in ZUGFeRD (v1 & v2), Factur-X, XRechnung, UBL, and FatturaPA
- **PDF handling**: Extract XML from PDF/A-3 invoices and embed XML into PDFs
- **Validation**: Validate invoices against format-specific rules
+- **PDF handling**: Extract XML from PDF/A-3 invoices and embed XML into PDFs with robust error handling
+- **Validation**: Validate invoices against format-specific rules with detailed error reporting
 - **Conversion**: Convert between different invoice formats
 - **TypeScript**: Fully typed API with TypeScript definitions
 - **Modular architecture**: Extensible design with specialized components
+- **Robust error handling**: Detailed error information and graceful fallbacks

 ## Install

@ -41,13 +42,67 @@ const invoice = new XInvoice();
 invoice.id = 'INV-2023-001';
 invoice.from = {
  name: 'Supplier Company',
-  // Add more details...
+  type: 'company',
+  address: {
+    streetName: 'Main Street',
+    houseNumber: '123',
+    city: 'Berlin',
+    postalCode: '10115',
+    country: 'Germany',
+    countryCode: 'DE'
+  },
+  registrationDetails: {
+    vatId: 'DE123456789',
+    registrationId: 'HRB 123456'
+  }
 };
 invoice.to = {
  name: 'Customer Company',
-  // Add more details...
+  type: 'company',
+  address: {
+    streetName: 'Customer Street',
+    houseNumber: '456',
+    city: 'Paris',
+    postalCode: '75001',
+    country: 'France',
+    countryCode: 'FR'
+  },
+  registrationDetails: {
+    vatId: 'FR87654321',
+    registrationId: 'RCS 654321'
+  }
 };
-// Add more invoice details...
+
+// Add payment options
+invoice.paymentOptions = {
+  info: 'Please transfer to our bank account',
+  sepaConnection: {
+    iban: 'DE89370400440532013000',
+    bic: 'COBADEFFXXX'
+  }
+};
+
+// Add invoice items
+invoice.items = [
+  {
+    position: 1,
+    name: 'Product A',
+    articleNumber: 'PROD-001',
+    unitQuantity: 2,
+    unitNetPrice: 100,
+    vatPercentage: 19,
+    unitType: 'EA'
+  },
+  {
+    position: 2,
+    name: 'Service B',
+    articleNumber: 'SERV-001',
+    unitQuantity: 1,
+    unitNetPrice: 200,
+    vatPercentage: 19,
+    unitType: 'EA'
+  }
+];

 // Export to XML
 const xml = await invoice.exportXml('zugferd');
@ -59,9 +114,9 @@ const loadedInvoice = await XInvoice.fromXml(xml);
 const pdfBuffer = await fs.readFile('invoice.pdf');
 const invoiceFromPdf = await XInvoice.fromPdf(pdfBuffer);

-// Export to PDF
-const pdfWithXml = await invoice.exportPdf(pdfBuffer);
-await fs.writeFile('invoice-with-xml.pdf', pdfWithXml);
+// Export to PDF with embedded XML
+const pdfWithXml = await invoice.exportPdf('facturx');
+await fs.writeFile('invoice-with-xml.pdf', pdfWithXml.buffer);
 ```

 ### Working with Different Invoice Formats
@ -78,6 +133,11 @@ const facturxInvoice = await XInvoice.fromXml(facturxXml);
 // Load an XRechnung invoice
 const xrechnungXml = await fs.readFile('xrechnung-invoice.xml', 'utf8');
 const xrechnungInvoice = await XInvoice.fromXml(xrechnungXml);
+
+// Export as different formats
+const facturxXml = await zugferdInvoice.exportXml('facturx');
+const ublXml = await facturxInvoice.exportXml('ubl');
+const xrechnungXml = await zugferdInvoice.exportXml('xrechnung');
 ```

 ### PDF Handling
@ -87,10 +147,19 @@ const xrechnungInvoice = await XInvoice.fromXml(xrechnungXml);
 const pdfBuffer = await fs.readFile('invoice.pdf');
 const invoice = await XInvoice.fromPdf(pdfBuffer);

+// Check the detected format
+console.log(`Detected format: ${invoice.getFormat()}`);
+
 // Embed XML into PDF
-const existingPdf = await fs.readFile('document.pdf');
-const pdfWithInvoice = await invoice.exportPdf(existingPdf);
-await fs.writeFile('invoice-with-xml.pdf', pdfWithInvoice);
+invoice.pdf = {
+  name: 'invoice.pdf',
+  id: 'invoice-1234',
+  metadata: { textExtraction: '' },
+  buffer: await fs.readFile('document.pdf')
+};
+
+const pdfWithInvoice = await invoice.exportPdf('facturx');
+await fs.writeFile('invoice-with-xml.pdf', pdfWithInvoice.buffer);
 ```

 ### Validating Invoices
@ -103,6 +172,11 @@ if (validationResult.valid) {
 } else {
  console.log('Validation errors:', validationResult.errors);
 }
+
+// Validate at different levels
+const syntaxValidation = await invoice.validate(ValidationLevel.SYNTAX);
+const semanticValidation = await invoice.validate(ValidationLevel.SEMANTIC);
+const businessValidation = await invoice.validate(ValidationLevel.BUSINESS);
 ```

 ## Architecture
@ -115,14 +189,15 @@ XInvoice uses a modular architecture with specialized components:
 - **Decoders**: Convert format-specific XML to a common invoice model
 - **Encoders**: Convert the common invoice model to format-specific XML
 - **Validators**: Validate invoices against format-specific rules
+- **FormatDetector**: Automatically detects invoice formats

 ### PDF Processing

- **PDF Extractors**: Extract XML from PDF files using multiple strategies:
+- **PDFExtractor**: Extract XML from PDF files using multiple strategies:
  - Standard Extraction: Extracts XML from standard PDF/A-3 embedded files
  - Associated Files Extraction: Extracts XML from associated files (AF entry)
  - Text-based Extraction: Extracts XML by searching for patterns in the PDF text
- **PDF Embedders**: Embed XML into PDF files
+- **PDFEmbedder**: Embed XML into PDF files with robust error handling

 This modular approach ensures maximum compatibility with different PDF implementations and invoice formats.

@ -144,15 +219,19 @@ This modular approach ensures maximum compatibility with different PDF implement

 ```typescript
 // Using specific encoders
-import { ZUGFeRDEncoder, FacturXEncoder } from '@fin.cx/xinvoice';
+import { ZUGFeRDEncoder, FacturXEncoder, UBLEncoder } from '@fin.cx/xinvoice';

 // Create ZUGFeRD XML
 const zugferdEncoder = new ZUGFeRDEncoder();
-const zugferdXml = await zugferdEncoder.createXml(invoiceData);
+const zugferdXml = await zugferdEncoder.encode(invoiceData);

 // Create Factur-X XML
 const facturxEncoder = new FacturXEncoder();
-const facturxXml = await facturxEncoder.createXml(invoiceData);
+const facturxXml = await facturxEncoder.encode(invoiceData);
+
+// Create UBL XML
+const ublEncoder = new UBLEncoder();
+const ublXml = await ublEncoder.encode(invoiceData);

 // Using specific decoders
 import { ZUGFeRDDecoder, FacturXDecoder } from '@fin.cx/xinvoice';
@ -166,21 +245,59 @@ const facturxDecoder = new FacturXDecoder(facturxXml);
 const facturxData = await facturxDecoder.decode();
 ```

-### Circular Encoding and Decoding
+### Working with PDF Extraction and Embedding

 ```typescript
-// Start with invoice data
-const invoiceData = { /* your structured invoice data */ };
+import { PDFExtractor, PDFEmbedder } from '@fin.cx/xinvoice';

-// Create XML
-const encoder = new FacturXEncoder();
-const xml = await encoder.createXml(invoiceData);
+// Extract XML from PDF
+const extractor = new PDFExtractor();
+const extractResult = await extractor.extractXml(pdfBuffer);

-// Decode XML back to structured data
-const decoder = new FacturXDecoder(xml);
-const extractedData = await decoder.decode();
+if (extractResult.success) {
+  console.log('Extracted XML:', extractResult.xml);
+  console.log('Detected format:', extractResult.format);
+  console.log('Extraction method used:', extractResult.extractorUsed);
+} else {
+  console.error('Extraction failed:', extractResult.error?.message);
+}

-// Now extractedData contains the same information as your original invoiceData
+// Embed XML into PDF
+const embedder = new PDFEmbedder();
+const embedResult = await embedder.createPdfWithXml(
+  pdfBuffer,
+  xmlContent,
+  'factur-x.xml',
+  'Factur-X XML Invoice',
+  'invoice.pdf',
+  'invoice-123456'
+);
+
+if (embedResult.success && embedResult.pdf) {
+  await fs.writeFile('output.pdf', embedResult.pdf.buffer);
+} else {
+  console.error('Embedding failed:', embedResult.error?.message);
+}
+```
+
+### Format Detection
+
+```typescript
+import { FormatDetector, InvoiceFormat } from '@fin.cx/xinvoice';
+
+// Detect format from XML
+const format = FormatDetector.detectFormat(xmlString);
+
+// Check format
+if (format === InvoiceFormat.ZUGFERD) {
+  console.log('This is a ZUGFeRD invoice');
+} else if (format === InvoiceFormat.FACTURX) {
+  console.log('This is a Factur-X invoice');
+} else if (format === InvoiceFormat.XRECHNUNG) {
+  console.log('This is an XRechnung invoice');
+} else if (format === InvoiceFormat.UBL) {
+  console.log('This is a UBL invoice');
+}
 ```

 ## Development
@ -212,13 +329,14 @@ The library includes comprehensive test suites that verify:
 - Special character handling
 - Different invoice types (invoices, credit notes)
 - PDF extraction and embedding
+- Error handling and recovery

 ## Key Features

 1. **PDF Integration**
-   - Embed XML invoices in PDF documents
-   - Extract XML from existing PDF invoices using multiple strategies
-   - Handle different XML attachment methods
+   - Embed XML invoices in PDF documents with detailed error reporting
+   - Extract XML from existing PDF invoices using multiple fallback strategies
+   - Handle different XML attachment methods and encodings

 2. **Encoding & Decoding**
   - Create standards-compliant XML from structured data
@ -236,6 +354,11 @@ The library includes comprehensive test suites that verify:
   - Detailed error reporting
   - Support for different validation levels

+5. **Error Handling**
+   - Robust error recovery mechanisms
+   - Detailed error information
+   - Type-safe error reporting
+
 By embracing `@fin.cx/xinvoice`, you simplify the handling of electronic invoice documents, fostering seamless integration across different financial processes, thus empowering practitioners with robust, flexible tools for VAT invoices in ZUGFeRD/Factur-X compliance or equivalent digital formats.

 ## License and Legal Information
--- a/ts/00_commitinfo_data.ts
+++ b/ts/00_commitinfo_data.ts
@ -3,6 +3,6 @@
 */
 export const commitinfo = {
  name: '@fin.cx/xinvoice',
-  version: '4.2.1',
+  version: '4.2.2',
  description: 'A TypeScript module for creating, manipulating, and embedding XML data within PDF files specifically tailored for xinvoice packages.'
 }