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
@ -255,4 +378,4 @@ Registered at District court Bremen HRB 35230 HB, Germany

 For any legal inquiries or if you require further information, please contact us via email at hello@task.vc.

-By using this repository, you acknowledge that you have read this section, agree to comply with its terms, and understand that the licensing of the code does not imply endorsement by Task Venture Capital GmbH of any derivative works.
+By using this repository, you acknowledge that you have read this section, agree to comply with its terms, and understand that the licensing of the code does not imply endorsement by Task Venture Capital GmbH of any derivative works.
--- 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.'
 }