# @fin.cx/einvoice

Source module for the main `@fin.cx/einvoice` package.

This directory contains the public TypeScript API for loading, validating, converting, and embedding European e-invoice XML.

## Issue Reporting and Security

For reporting bugs, issues, or security vulnerabilities, please visit [community.foss.global/](https://community.foss.global/). This is the central community hub for all issue reporting. Developers who sign and comply with our contribution agreement and go through identification can also get a [code.foss.global/](https://code.foss.global/) account to submit Pull Requests directly.

## What this module exports

- `EInvoice`
- `createEInvoice()`
- `validateXml(xml, level?)`
- `FormatDetector`
- `PDFExtractor`, `PDFEmbedder`
- `DecoderFactory`, `EncoderFactory`, `ValidatorFactory`
- `BaseDecoder`, `BaseEncoder`, `BaseValidator`
- `UBLBase*` and `CIIBase*` extension points
- Factur-X and ZUGFeRD format-specific classes
- root types such as `TInvoice`, `ValidationResult`, `ExportFormat`, `IPdf`

## Main workflow

```ts
import { EInvoice, ValidationLevel } from '@fin.cx/einvoice';

const invoice = await EInvoice.fromFile('./invoice.xml');
const validation = await invoice.validate(ValidationLevel.BUSINESS);
const xml = await invoice.exportXml('facturx');
```

## Format support

| Format | Detect | Import | Export | Notes |
| --- | --- | --- | --- | --- |
| `ubl` | Yes | Yes | Yes | Generic UBL flow |
| `xrechnung` | Yes | Yes | Yes | UBL-based profile |
| `cii` | Yes | Yes | Yes | Generic export currently routes through the Factur-X encoder path |
| `facturx` | Yes | Yes | Yes | Main CII generation path |
| `zugferd` | Yes | Yes | Yes | Input supports v1 and v2+ |
| `fatturapa` | Yes | No | No | Detection only at the moment |

## Important implementation notes

- `peppol` is not a root-level XML export target.
- `FatturaPA` is not fully implemented for import/export.
- PDF support means extracting or embedding XML into existing PDFs, not generating invoice PDFs from scratch.
- Validation is useful and extensive, but should not be documented as blanket certification.

## Related directories

- `../readme.md`: full package README for end users
- `../ts_install/readme.md`: install-time resource bootstrap module