xinvoice/readme.md

# @fin.cx/xinvoice

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.

## 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
- **Conversion**: Convert between different invoice formats
- **TypeScript**: Fully typed API with TypeScript definitions
- **Modular architecture**: Extensible design with specialized components

## Install

To install `@fin.cx/xinvoice`, you'll need a package manager. We recommend using pnpm:

```shell
# Using pnpm (recommended)
pnpm add @fin.cx/xinvoice

# Using npm
npm install @fin.cx/xinvoice

# Using yarn
yarn add @fin.cx/xinvoice
```

## 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.

### Basic Usage

```typescript
import { XInvoice } from '@fin.cx/xinvoice';
import { promises as fs } from 'fs';

// Create a new invoice
const invoice = new XInvoice();
invoice.id = 'INV-2023-001';
invoice.from = {
  name: 'Supplier Company',
  // Add more details...
};
invoice.to = {
  name: 'Customer Company',
  // Add more details...
};
// Add more invoice details...

// Export to XML
const xml = await invoice.exportXml('zugferd');

// Load from XML
const loadedInvoice = await XInvoice.fromXml(xml);

// Load from PDF
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);
```

### Working with Different Invoice Formats

```typescript
// Load a ZUGFeRD invoice
const zugferdXml = await fs.readFile('zugferd-invoice.xml', 'utf8');
const zugferdInvoice = await XInvoice.fromXml(zugferdXml);

// Load a Factur-X invoice
const facturxXml = await fs.readFile('facturx-invoice.xml', 'utf8');
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);
```

### PDF Handling

```typescript
// Extract XML from PDF
const pdfBuffer = await fs.readFile('invoice.pdf');
const invoice = await XInvoice.fromPdf(pdfBuffer);

// 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);
```

### Validating Invoices

```typescript
// Validate an invoice
const validationResult = await invoice.validate();
if (validationResult.valid) {
  console.log('Invoice is valid');
} else {
  console.log('Validation errors:', validationResult.errors);
}
```

## Architecture

XInvoice uses a modular architecture with specialized components:

### Core Components

- **XInvoice**: 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

### PDF Processing

- **PDF Extractors**: 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

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

## 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 | ✅ | ✅ | ✅ |

## Advanced Usage

### Custom Encoders and Decoders

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

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

// Create Factur-X XML
const facturxEncoder = new FacturXEncoder();
const facturxXml = await facturxEncoder.createXml(invoiceData);

// Using specific decoders
import { ZUGFeRDDecoder, FacturXDecoder } from '@fin.cx/xinvoice';

// Decode ZUGFeRD XML
const zugferdDecoder = new ZUGFeRDDecoder(zugferdXml);
const zugferdData = await zugferdDecoder.decode();

// Decode Factur-X XML
const facturxDecoder = new FacturXDecoder(facturxXml);
const facturxData = await facturxDecoder.decode();
```

### Circular Encoding and Decoding

```typescript
// Start with invoice data
const invoiceData = { /* your structured invoice data */ };

// Create XML
const encoder = new FacturXEncoder();
const xml = await encoder.createXml(invoiceData);

// Decode XML back to structured data
const decoder = new FacturXDecoder(xml);
const extractedData = await decoder.decode();

// Now extractedData contains the same information as your original invoiceData
```

## Development

### Building the Project

```bash
# Install dependencies
pnpm install

# Build the project
pnpm run build
```

### Running Tests

```bash
# Run all tests
pnpm test

# Run specific test
pnpm test test/test.xinvoice.ts
```

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

## 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

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

4. **Validation**
   - Validate invoices against format-specific rules
   - Detailed error reporting
   - Support for different validation levels

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

This repository contains open-source code that is licensed under the MIT License. A copy of the MIT License can be found in the [license](license) file within this repository.

**Please note:** The MIT License does not grant permission to use the trade names, trademarks, service marks, or product names of the project, except as required for reasonable and customary use in describing the origin of the work and reproducing the content of the NOTICE file.

### Trademarks

This project is owned and maintained by Task Venture Capital GmbH. The names and logos associated with Task Venture Capital GmbH and any related products or services are trademarks of Task Venture Capital GmbH and are not included within the scope of the MIT license granted herein. Use of these trademarks must comply with Task Venture Capital GmbH's Trademark Guidelines, and any usage must be approved in writing by Task Venture Capital GmbH.

### Company Information

Task Venture Capital GmbH  
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.