fix(documentation): Update readme to enhance installation instructions and expand feature documentation for Factur-X/ZUGFeRD, UBL, and FatturaPA support, including details on circular encoding/decoding.

changelog.md

@@ -1,5 +1,13 @@
 # Changelog
 
+## 2025-03-17 - 1.3.1 - fix(documentation)
+Update readme to enhance installation instructions and expand feature documentation for Factur-X/ZUGFeRD, UBL, and FatturaPA support, including details on circular encoding/decoding.
+
+- Added pnpm installation instructions
+- Expanded description of supported European e-invoicing standards
+- Clarified usage of FacturXEncoder and ZUGFeRDXmlDecoder for XML encoding/decoding
+- Included detailed feature summary for PDF integration, encoding/decoding, and format detection
+
 ## 2025-03-17 - 1.3.0 - feat(encoder)
 Rename encoder class from ZugferdXmlEncoder to FacturXEncoder to better reflect Factur-X compliance. All related imports, exports, and tests have been updated while maintaining backward compatibility.
 

readme.md

@@ -1,5 +1,5 @@
 # @fin.cx/xinvoice
-A module for creating, manipulating, and embedding XML data within PDF files for xinvoice packages.
+A module for creating, manipulating, and embedding XML invoice data within PDF files, supporting multiple European electronic invoice standards including ZUGFeRD, Factur-X, EN16931, UBL, and FatturaPA.
 
 ## Install
 
@@ -9,6 +9,12 @@ To install `@fin.cx/xinvoice`, you'll need npm (Node Package Manager). Run the f
 npm install @fin.cx/xinvoice
 ```
 
+Or if you're using pnpm:
+
+```shell
+pnpm add @fin.cx/xinvoice
+```
+
 This command fetches the `xinvoice` package from the npm registry and installs it in your project directory.
 
 ## Usage
@@ -154,37 +160,105 @@ Each invoice object encompasses seller and buyer information, invoice items and
 
 ### Custom Extensibility: Encoding and Decoding XML
 
-#### Custom XML Encoding
+#### Factur-X/ZUGFeRD XML Encoding
 
-Beyond pre-built functionalities, the module supports custom XML encoding of structured data into PDF attachments. Utilize `ZugferdXmlEncoder` for scenarios necessitating bespoke XML generation:
+Beyond pre-built functionalities, the module supports custom XML encoding of structured data into PDF attachments. Utilize `FacturXEncoder` for generating standards-compliant XML:
 
 ```typescript
-import { ZugferdXmlEncoder } from '@fin.cx/xinvoice';
+import { FacturXEncoder } from '@fin.cx/xinvoice';
 
-const encoder = new ZugferdXmlEncoder();
-const customXml = encoder.createZugferdXml(someLetterData);
+const encoder = new FacturXEncoder();
+const factorXXml = encoder.createFacturXXml(invoiceLetterData);
 ```
 
-This use-case implies transforming invoice data, specified in `ILetter`, into compliant ZUGFeRD/XML format.
+This encoder transforms invoice data into compliant Factur-X/ZUGFeRD XML format, following the European e-invoicing standard EN16931. The encoder handles all the complexities of creating valid XML including proper namespaces, required fields, and structured data elements.
 
-#### XML Decoding for Custom Handling
+For backward compatibility, you can also use:
 
-In instances requiring parsing of arbitrary XML content, the `ZUGFeRDXmlDecoder` class proves instrumental:
+```typescript
+const zugferdXml = encoder.createZugferdXml(invoiceLetterData);
+```
+
+#### XML Decoding for Multiple Invoice Formats
+
+The library supports decoding multiple electronic invoice formats through the `ZUGFeRDXmlDecoder` class:
 
 ```typescript
 import { ZUGFeRDXmlDecoder } from '@fin.cx/xinvoice';
 
-const decoder = new ZUGFeRDXmlDecoder(someXmlString);
+const decoder = new ZUGFeRDXmlDecoder(xmlString);
 const letterData = await decoder.getLetterData();
 ```
 
-This class mimics the behavior of extracting XML to a structured `ILetter` object, suitable for scenarios requiring XML inspection or interfacing with custom workflows.
+This decoder automatically detects the XML format (ZUGFeRD/Factur-X, UBL, or FatturaPA) and extracts relevant invoice data into a structured `ILetter` object, suitable for custom processing.
 
-### Comprehensive Feature Exploration
+#### Circular Encoding and Decoding
 
-The entirety of the module facilitates a wide spectrum of invoicing scenarios. From initial creation, embedding, and parsing tasks, to advanced encoding and decoding, every feature is crafted to accommodate complexities inherent in financial document management.
+A powerful feature of this library is the ability to perform circular encoding and decoding, allowing you to create XML from structured data and then extract the same data back from the XML:
 
-By embracing `@fin.cx/xinvoice`, you simplify the handling of xinvoice-standard documents, fostering seamless integration across different financial processes, thus empowering practitioners with robust, flexible tools for VAT invoices in ZUGFeRD compliance or equivalent digital formats.
+```typescript
+// Start with invoice data
+const invoiceData = { /* your structured invoice data */ };
+
+// Create XML
+const encoder = new FacturXEncoder();
+const xml = encoder.createFacturXXml(invoiceData);
+
+// Decode XML back to structured data
+const decoder = new ZUGFeRDXmlDecoder(xml);
+const extractedData = await decoder.getLetterData();
+
+// Now extractedData contains the same information as your original invoiceData
+```
+
+This circular capability ensures data integrity throughout the invoice processing lifecycle.
+
+### Supported Invoice Standards
+
+The library currently supports the following electronic invoice standards:
+
+- **ZUGFeRD/Factur-X** - The German and French implementations of the European e-invoicing standard EN16931, based on UN/CEFACT Cross Industry Invoice (CII) XML schema
+- **UBL (Universal Business Language)** - An OASIS standard for XML business documents
+- **FatturaPA** - The Italian electronic invoicing standard
+
+Each format is automatically detected during decoding, and the encoders create standards-compliant documents that pass validation.
+
+### Testing and Validation
+
+The library includes comprehensive test suites that verify:
+- XML creation capabilities
+- Format detection logic
+- XML encoding/decoding circularity
+- Special character handling
+- Different invoice types (invoices, credit notes)
+
+You can run the tests using:
+
+```shell
+pnpm test
+```
+
+### Comprehensive Feature Summary
+
+The entirety of the module facilitates a wide spectrum of invoicing scenarios. Key features include:
+
+1. **PDF Integration**
+   - Embed XML invoices in PDF documents
+   - Extract XML from existing PDF invoices
+   - Handle different XML attachment methods
+
+2. **Encoding & Decoding**
+   - Create standards-compliant XML from structured data
+   - Parse XML invoices back to structured data
+   - Support multiple format standards
+   - Circular encoding/decoding integrity
+
+3. **Format Detection**
+   - Automatic detection of invoice XML format
+   - Support for different XML namespaces
+   - Graceful handling of malformed XML
+
+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
 

ts/00_commitinfo_data.ts

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