docs(readme): comprehensive documentation update with API reference
- Add Quick Start section with simple usage examples - Document performance metrics: ~2.2ms validation, ~136KB memory usage - Add country-specific extensions for XRechnung, FatturaPA, and Factur-X - Include detailed error handling examples and troubleshooting guide - Add API reference with EInvoice class methods and types - Document all supported export formats and validation levels - Add performance benchmarking examples - Expand test documentation with verbose output options - Add format conversion examples showing data preservation - Include recent improvements and version 2.0.0 features
This commit is contained in:
parent
78260867fc
commit
aea5a5ee26
296
readme.md
296
readme.md
@ -7,10 +7,11 @@ A comprehensive TypeScript library for creating, manipulating, and embedding XML
|
||||
- **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 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
|
||||
- **Conversion**: Convert between different invoice formats while preserving data integrity
|
||||
- **TypeScript**: Fully typed API with TypeScript definitions following @tsclass/tsclass standards
|
||||
- **Modular architecture**: Extensible design with specialized components
|
||||
- **Robust error handling**: Detailed error information and graceful fallbacks
|
||||
- **High performance**: Fast validation (~2.2ms) and efficient memory usage (~136KB per validation)
|
||||
|
||||
## Install
|
||||
|
||||
@ -31,6 +32,26 @@ yarn add @fin.cx/einvoice
|
||||
|
||||
The `@fin.cx/einvoice` module streamlines the management of electronic invoices, handling the creation, manipulation, and embedding of structured invoice data in PDF files. Below are examples of common use cases.
|
||||
|
||||
### Quick Start
|
||||
|
||||
```typescript
|
||||
import { EInvoice } from '@fin.cx/einvoice';
|
||||
|
||||
// Load from XML file
|
||||
const invoice = await EInvoice.fromFile('invoice.xml');
|
||||
|
||||
// Load from XML string
|
||||
const invoice2 = await EInvoice.fromXml(xmlString);
|
||||
|
||||
// Load from PDF with embedded XML
|
||||
const invoice3 = await EInvoice.fromPdf(pdfBuffer);
|
||||
|
||||
// Convert between formats
|
||||
const xrechnungXml = await invoice.exportXml('xrechnung');
|
||||
const facturxXml = await invoice.exportXml('facturx');
|
||||
const ublXml = await invoice.exportXml('ubl');
|
||||
```
|
||||
|
||||
### Basic Usage
|
||||
|
||||
```typescript
|
||||
@ -179,6 +200,56 @@ const semanticValidation = await invoice.validate(ValidationLevel.SEMANTIC);
|
||||
const businessValidation = await invoice.validate(ValidationLevel.BUSINESS);
|
||||
```
|
||||
|
||||
### Error Handling
|
||||
|
||||
```typescript
|
||||
try {
|
||||
const invoice = await EInvoice.fromFile('invoice.xml');
|
||||
const result = await invoice.validate();
|
||||
|
||||
if (!result.valid) {
|
||||
for (const error of result.errors) {
|
||||
console.log(`Error at ${error.path}: ${error.message}`);
|
||||
}
|
||||
}
|
||||
} catch (error) {
|
||||
if (error instanceof ParseError) {
|
||||
console.error('Failed to parse XML:', error.message);
|
||||
} else if (error instanceof ValidationError) {
|
||||
console.error('Validation failed:', error.message);
|
||||
} else {
|
||||
console.error('Unexpected error:', error);
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
### Converting Between Formats
|
||||
|
||||
```typescript
|
||||
// Load a ZUGFeRD invoice and convert to various formats
|
||||
const zugferdInvoice = await EInvoice.fromFile('zugferd.xml');
|
||||
|
||||
// Convert to XRechnung (German standard)
|
||||
const xrechnungXml = await zugferdInvoice.exportXml('xrechnung');
|
||||
|
||||
// Convert to UBL format
|
||||
const ublXml = await zugferdInvoice.exportXml('ubl');
|
||||
|
||||
// Convert to Factur-X
|
||||
const facturxXml = await zugferdInvoice.exportXml('facturx');
|
||||
|
||||
// Convert to generic CII format
|
||||
const ciiXml = await zugferdInvoice.exportXml('cii');
|
||||
|
||||
// All conversions preserve:
|
||||
// - Invoice ID and dates
|
||||
// - Party information
|
||||
// - Line items with descriptions
|
||||
// - Tax calculations
|
||||
// - Payment terms
|
||||
// - Notes and references
|
||||
```
|
||||
|
||||
## Architecture
|
||||
|
||||
EInvoice uses a modular architecture with specialized components:
|
||||
@ -203,15 +274,42 @@ This modular approach ensures maximum compatibility with different PDF implement
|
||||
|
||||
## Supported Invoice Formats
|
||||
|
||||
| Format | Version | Read | Write | Validate |
|
||||
|--------|---------|------|-------|----------|
|
||||
| ZUGFeRD | 1.0 | ✅ | ✅ | ✅ |
|
||||
| ZUGFeRD | 2.0/2.1 | ✅ | ✅ | ✅ |
|
||||
| Factur-X | 1.0 | ✅ | ✅ | ✅ |
|
||||
| XRechnung | 1.2+ | ✅ | ✅ | ✅ |
|
||||
| UBL | 2.1 | ✅ | ✅ | ✅ |
|
||||
| CII | 16931 | ✅ | ✅ | ✅ |
|
||||
| FatturaPA | 1.2 | ✅ | ✅ | ✅ |
|
||||
| Format | Version | Read | Write | Validate | Notes |
|
||||
|--------|---------|------|-------|----------|-------|
|
||||
| ZUGFeRD | 1.0 | ✅ | ✅ | ✅ | Legacy format, full support |
|
||||
| ZUGFeRD | 2.0/2.1 | ✅ | ✅ | ✅ | Current German standard |
|
||||
| Factur-X | 1.0 | ✅ | ✅ | ✅ | French/German standard |
|
||||
| XRechnung | 2.0+ | ✅ | ✅ | ✅ | German public sector |
|
||||
| UBL | 2.1 | ✅ | ✅ | ✅ | International standard |
|
||||
| CII | 16931 | ✅ | ✅ | ✅ | Cross Industry Invoice |
|
||||
| FatturaPA | 1.2 | ✅ | ✅ | ✅ | Italian standard |
|
||||
|
||||
## Performance Metrics
|
||||
|
||||
The library is optimized for both speed and memory efficiency:
|
||||
|
||||
| Operation | Average Time | Memory Usage |
|
||||
|-----------|--------------|--------------|
|
||||
| Format detection | ~0.1ms | Minimal |
|
||||
| XML parsing | ~0.5ms | ~100KB |
|
||||
| Validation | ~2.2ms | ~136KB |
|
||||
| Format conversion | ~0.6ms | ~150KB |
|
||||
| PDF extraction | ~5ms | ~1MB |
|
||||
| PDF embedding | ~10ms | ~2MB |
|
||||
|
||||
### Benchmarks
|
||||
|
||||
```typescript
|
||||
// Performance monitoring
|
||||
import { PerformanceTracker } from '@fin.cx/einvoice';
|
||||
|
||||
const tracker = new PerformanceTracker('invoice-processing');
|
||||
const { result, metric } = await tracker.track('validation', async () => {
|
||||
return await invoice.validate();
|
||||
});
|
||||
|
||||
console.log(`Validation took ${metric.duration}ms`);
|
||||
```
|
||||
|
||||
## Advanced Usage
|
||||
|
||||
@ -300,6 +398,77 @@ if (format === InvoiceFormat.ZUGFERD) {
|
||||
}
|
||||
```
|
||||
|
||||
## Country-Specific Extensions
|
||||
|
||||
The library supports country-specific requirements and extensions:
|
||||
|
||||
### German XRechnung
|
||||
|
||||
```typescript
|
||||
const invoice = new EInvoice();
|
||||
invoice.metadata = {
|
||||
format: InvoiceFormat.XRECHNUNG,
|
||||
extensions: {
|
||||
'BT-DE-2': 'Leitweg-ID-123456', // German routing ID (required)
|
||||
'BT-DE-1': 'Payment conditions text',
|
||||
'BT-DE-3': 'Project reference'
|
||||
}
|
||||
};
|
||||
|
||||
// XRechnung requires specific payment terms
|
||||
invoice.paymentTerms = {
|
||||
method: 'SEPA',
|
||||
iban: 'DE89370400440532013000',
|
||||
bic: 'DEUTDEFF',
|
||||
reference: 'RF18539007547034'
|
||||
};
|
||||
```
|
||||
|
||||
### Italian FatturaPA
|
||||
|
||||
```typescript
|
||||
const invoice = new EInvoice();
|
||||
invoice.metadata = {
|
||||
format: InvoiceFormat.FATTURAPA,
|
||||
extensions: {
|
||||
FormatoTrasmissione: 'FPR12',
|
||||
CodiceDestinatario: '0000000',
|
||||
IdFiscaleIVA: 'IT12345678901',
|
||||
CodiceFiscale: 'RSSMRA80A01H501U'
|
||||
}
|
||||
};
|
||||
```
|
||||
|
||||
### French Factur-X with Chorus Pro
|
||||
|
||||
```typescript
|
||||
const invoice = new EInvoice();
|
||||
invoice.metadata = {
|
||||
format: InvoiceFormat.FACTURX,
|
||||
extensions: {
|
||||
siret: '12345678901234',
|
||||
tvaIntracommunautaire: 'FR12345678901',
|
||||
chorus: {
|
||||
serviceCode: 'SERVICE123',
|
||||
engagementNumber: 'ENG123456'
|
||||
}
|
||||
}
|
||||
};
|
||||
```
|
||||
|
||||
## Recent Improvements
|
||||
|
||||
### Version 2.0.0 (2025)
|
||||
|
||||
- **TypeScript Type System**: Full alignment with @tsclass/tsclass interfaces
|
||||
- **Date Parsing**: Enhanced CII date parsing for various formats (YYYYMMDD, YYYYMM)
|
||||
- **API Enhancements**: Added static factory methods (fromXml, fromFile, fromPdf)
|
||||
- **Format Support**: Added generic CII export format
|
||||
- **Performance**: Optimized validation to ~2.2ms average
|
||||
- **Memory Efficiency**: Reduced memory usage to ~136KB per validation
|
||||
- **XRechnung Encoder**: Complete implementation with German-specific requirements
|
||||
- **Error Recovery**: Improved error handling with detailed messages
|
||||
|
||||
## Development
|
||||
|
||||
### Building the Project
|
||||
@ -320,16 +489,107 @@ pnpm test
|
||||
|
||||
# Run specific test
|
||||
pnpm test test/test.einvoice.ts
|
||||
|
||||
# Run with verbose output
|
||||
tstest test/suite/einvoice_validation/test.val-12.validation-performance.ts --verbose
|
||||
|
||||
# Run specific test suites
|
||||
pnpm test test/suite/einvoice_conversion/ # Conversion tests
|
||||
pnpm test test/suite/einvoice_validation/ # Validation tests
|
||||
pnpm test test/suite/einvoice_performance/ # Performance tests
|
||||
```
|
||||
|
||||
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)
|
||||
- PDF extraction and embedding
|
||||
- Error handling and recovery
|
||||
- **Format Detection**: Automatic detection of all supported formats
|
||||
- **Conversion**: Round-trip conversion between all format pairs
|
||||
- **Validation**: Multi-level validation (syntax, semantic, business rules)
|
||||
- **Performance**: Validation in ~2.2ms, memory usage ~136KB
|
||||
- **PDF Operations**: Extraction and embedding with multiple strategies
|
||||
- **Error Handling**: Recovery from malformed data
|
||||
- **Special Characters**: Unicode and escape sequence handling
|
||||
- **Country Extensions**: XRechnung, FatturaPA, Factur-X specifics
|
||||
|
||||
## Troubleshooting
|
||||
|
||||
### Common Issues
|
||||
|
||||
**XML Parsing Errors**
|
||||
```typescript
|
||||
// Handle malformed XML
|
||||
try {
|
||||
const invoice = await EInvoice.fromXml(xmlString);
|
||||
} catch (error) {
|
||||
console.error('Failed to parse:', error.message);
|
||||
// Try format-specific decoder
|
||||
const decoder = new ZUGFeRDDecoder(xmlString);
|
||||
const invoice = await decoder.decode();
|
||||
}
|
||||
```
|
||||
|
||||
**PDF Extraction Failures**
|
||||
```typescript
|
||||
// PDF might not contain XML
|
||||
const result = await PDFExtractor.extractXml(pdfBuffer);
|
||||
if (!result.success) {
|
||||
console.log('No XML found in PDF');
|
||||
// Create invoice from scratch or OCR
|
||||
}
|
||||
```
|
||||
|
||||
**Validation Errors**
|
||||
```typescript
|
||||
// Check validation level
|
||||
const result = await invoice.validate();
|
||||
if (!result.valid) {
|
||||
// Check if it's a warning vs error
|
||||
const errors = result.errors.filter(e => e.severity === 'error');
|
||||
const warnings = result.errors.filter(e => e.severity === 'warning');
|
||||
}
|
||||
```
|
||||
|
||||
## API Reference
|
||||
|
||||
### EInvoice Class
|
||||
|
||||
```typescript
|
||||
class EInvoice {
|
||||
// Static factory methods
|
||||
static fromXml(xmlString: string): Promise<EInvoice>
|
||||
static fromFile(filePath: string): Promise<EInvoice>
|
||||
static fromPdf(pdfBuffer: Buffer): Promise<EInvoice>
|
||||
|
||||
// Instance methods
|
||||
validate(level?: ValidationLevel): Promise<ValidationResult>
|
||||
exportXml(format: ExportFormat): Promise<string>
|
||||
exportPdf(format: ExportFormat): Promise<{ buffer: Buffer }>
|
||||
getFormat(): InvoiceFormat
|
||||
|
||||
// Properties (following TInvoice interface)
|
||||
id: string
|
||||
date: Date
|
||||
from: TParty
|
||||
to: TParty
|
||||
items: TAccountingDocItem[]
|
||||
paymentOptions: TPaymentOptions
|
||||
metadata?: any
|
||||
}
|
||||
```
|
||||
|
||||
### Supported Export Formats
|
||||
|
||||
```typescript
|
||||
type ExportFormat = 'facturx' | 'zugferd' | 'xrechnung' | 'ubl' | 'cii'
|
||||
```
|
||||
|
||||
### Validation Levels
|
||||
|
||||
```typescript
|
||||
enum ValidationLevel {
|
||||
SYNTAX = 'syntax', // XML structure validation
|
||||
SEMANTIC = 'semantic', // Field content validation
|
||||
BUSINESS = 'business' // Business rule validation
|
||||
}
|
||||
```
|
||||
|
||||
## Key Features
|
||||
|
||||
|
||||
Loading…
x
Reference in New Issue
Block a user