feat(core): improve in-memory validation, FatturaPA detection coverage, and published type compatibility

2026-04-16 20:30:56 +00:00
parent 55bee02a2e
commit 3f37f6538c
60 changed files with 5723 additions and 6678 deletions
@@ -0,0 +1,55 @@
+# @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