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

BREAKING CHANGE(core): Rebrand XInvoice to EInvoice: update package name, class names, imports, and documentation

Browse Source
This commit is contained in:
Philipp Kunz
2025-05-24 16:33:58 +00:00
parent 805adc6d5c
commit a93ea090ce
27 changed files with 3172 additions and 295 deletions
Download Patch File Download Diff File Expand all files Collapse all files

44
readme.md
View File

@ -1,4 +1,4 @@
# @fin.cx/xinvoice
# @fin.cx/einvoice
A comprehensive TypeScript library for creating, manipulating, and embedding XML invoice data within PDF files, supporting multiple European electronic invoice standards including ZUGFeRD (v1 & v2), Factur-X, XRechnung, UBL, and FatturaPA.
@ -14,31 +14,31 @@ A comprehensive TypeScript library for creating, manipulating, and embedding XML
## Install
To install `@fin.cx/xinvoice`, you'll need a package manager. We recommend using pnpm:
To install `@fin.cx/einvoice`, you'll need a package manager. We recommend using pnpm:
```shell
# Using pnpm (recommended)
pnpm add @fin.cx/xinvoice
pnpm add @fin.cx/einvoice
# Using npm
npm install @fin.cx/xinvoice
npm install @fin.cx/einvoice
# Using yarn
yarn add @fin.cx/xinvoice
yarn add @fin.cx/einvoice
```
## Usage
The `@fin.cx/xinvoice` 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.
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.
### Basic Usage
```typescript
import { XInvoice } from '@fin.cx/xinvoice';
import { EInvoice } from '@fin.cx/einvoice';
import { promises as fs } from 'fs';
// Create a new invoice
const invoice = new XInvoice();
const invoice = new EInvoice();
invoice.id = 'INV-2023-001';
invoice.from = {
name: 'Supplier Company',
@ -108,11 +108,11 @@ invoice.items = [
const xml = await invoice.exportXml('zugferd');
// Load from XML
const loadedInvoice = await XInvoice.fromXml(xml);
const loadedInvoice = await EInvoice.fromXml(xml);
// Load from PDF
const pdfBuffer = await fs.readFile('invoice.pdf');
const invoiceFromPdf = await XInvoice.fromPdf(pdfBuffer);
const invoiceFromPdf = await EInvoice.fromPdf(pdfBuffer);
// Export to PDF with embedded XML
const pdfWithXml = await invoice.exportPdf('facturx');
@ -124,15 +124,15 @@ await fs.writeFile('invoice-with-xml.pdf', pdfWithXml.buffer);
```typescript
// Load a ZUGFeRD invoice
const zugferdXml = await fs.readFile('zugferd-invoice.xml', 'utf8');
const zugferdInvoice = await XInvoice.fromXml(zugferdXml);
const zugferdInvoice = await EInvoice.fromXml(zugferdXml);
// Load a Factur-X invoice
const facturxXml = await fs.readFile('facturx-invoice.xml', 'utf8');
const facturxInvoice = await XInvoice.fromXml(facturxXml);
const facturxInvoice = await EInvoice.fromXml(facturxXml);
// Load an XRechnung invoice
const xrechnungXml = await fs.readFile('xrechnung-invoice.xml', 'utf8');
const xrechnungInvoice = await XInvoice.fromXml(xrechnungXml);
const xrechnungInvoice = await EInvoice.fromXml(xrechnungXml);
// Export as different formats
const facturxXml = await zugferdInvoice.exportXml('facturx');
@ -145,7 +145,7 @@ const xrechnungXml = await zugferdInvoice.exportXml('xrechnung');
```typescript
// Extract XML from PDF
const pdfBuffer = await fs.readFile('invoice.pdf');
const invoice = await XInvoice.fromPdf(pdfBuffer);
const invoice = await EInvoice.fromPdf(pdfBuffer);
// Check the detected format
console.log(`Detected format: ${invoice.getFormat()}`);
@ -181,11 +181,11 @@ const businessValidation = await invoice.validate(ValidationLevel.BUSINESS);
## Architecture
XInvoice uses a modular architecture with specialized components:
EInvoice uses a modular architecture with specialized components:
### Core Components
- **XInvoice**: The main class that provides a high-level API for working with invoices
- **EInvoice**: The main class that provides a high-level API for working with invoices
- **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
@ -219,7 +219,7 @@ This modular approach ensures maximum compatibility with different PDF implement
```typescript
// Using specific encoders
import { ZUGFeRDEncoder, FacturXEncoder, UBLEncoder } from '@fin.cx/xinvoice';
import { ZUGFeRDEncoder, FacturXEncoder, UBLEncoder } from '@fin.cx/einvoice';
// Create ZUGFeRD XML
const zugferdEncoder = new ZUGFeRDEncoder();
@ -234,7 +234,7 @@ const ublEncoder = new UBLEncoder();
const ublXml = await ublEncoder.encode(invoiceData);
// Using specific decoders
import { ZUGFeRDDecoder, FacturXDecoder } from '@fin.cx/xinvoice';
import { ZUGFeRDDecoder, FacturXDecoder } from '@fin.cx/einvoice';
// Decode ZUGFeRD XML
const zugferdDecoder = new ZUGFeRDDecoder(zugferdXml);
@ -248,7 +248,7 @@ const facturxData = await facturxDecoder.decode();
### Working with PDF Extraction and Embedding
```typescript
import { PDFExtractor, PDFEmbedder } from '@fin.cx/xinvoice';
import { PDFExtractor, PDFEmbedder } from '@fin.cx/einvoice';
// Extract XML from PDF
const extractor = new PDFExtractor();
@ -283,7 +283,7 @@ if (embedResult.success && embedResult.pdf) {
### Format Detection
```typescript
import { FormatDetector, InvoiceFormat } from '@fin.cx/xinvoice';
import { FormatDetector, InvoiceFormat } from '@fin.cx/einvoice';
// Detect format from XML
const format = FormatDetector.detectFormat(xmlString);
@ -319,7 +319,7 @@ pnpm run build
pnpm test
# Run specific test
pnpm test test/test.xinvoice.ts
pnpm test test/test.einvoice.ts
```
The library includes comprehensive test suites that verify:
@ -359,7 +359,7 @@ The library includes comprehensive test suites that verify:
- 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.
By embracing `@fin.cx/einvoice`, 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