npm package: @invoicenavigator/einvoice-validator
Description: Free, open-source EU e-invoice validator. Detect formats and validate against EN 16931 core rules.
Author: Invoice Navigator
Latest version: 0.1.0

# @invoicenavigator/einvoice-validator

Free, open-source EU e-invoice validator. Detect formats and validate against EN 16931 core rules.

Supports UBL 2.1, CII D16B, Peppol BIS 3.0, XRechnung, and ZUGFeRD/Factur-X.

## Install

```bash
npm install @invoicenavigator/einvoice-validator
```

## Quick Start

```typescript
import { validate, detectFormat } from '@invoicenavigator/einvoice-validator'
import { readFileSync } from 'fs'

const xml = readFileSync('invoice.xml', 'utf-8')

// Detect the invoice format
const format = detectFormat(xml)
console.log(format)
// { format: 'peppol-bis-3.0', syntax: 'ubl', version: '2.1' }

// Validate against EN 16931 core rules
const result = validate(xml)

if (result.valid) {
  console.log('Basic validation passed')
} else {
  for (const error of result.errors) {
    console.log(`${error.rule}: ${error.message}`)
  }
}
```

## What This Validates

This library checks **EN 16931 core structural rules** (BR-01 through BR-10):

| Rule | Check |
|------|-------|
| BR-01 | Specification identifier is present (BT-24) |
| BR-02 | Invoice number is present (BT-1) |
| BR-03 | Invoice issue date is present and valid (BT-2) |
| BR-04 | Invoice type code is a valid UNTDID 1001 code (BT-3) |
| BR-05 | Invoice currency code is a valid ISO 4217 code (BT-5) |
| BR-06 | Seller name is present (BT-27) |
| BR-07 | Buyer name is present (BT-44) |
| BR-08 | Seller postal address is present (BG-5) |
| BR-09 | Seller country code is present and valid (BT-40) |
| BR-10 | Buyer postal address is present (BG-8) |

Plus structural checks: valid root element, correct namespace prefixes.

## Need More?

This library covers basic structural validation. For production e-invoicing pipelines, you likely also need:

- **Full EN 16931 business rules** (200+ rules including calculation checks)
- **Country-specific CIUS** (XRechnung, Peppol, Italian FatturaPA, etc.)
- **KoSIT/Schematron validation** (authoritative German validator)
- **Auto-remediation** (fix structural issues without changing commercial data)
- **Compliance evidence packs** (signed PDF/JSON audit trail)

[Invoice Navigator](https://www.invoicenavigator.eu) provides all of the above as an API. Free trial available — no credit card required.

```typescript
import { InvoiceNavigator } from '@invoicenavigator/sdk'

const client = new InvoiceNavigator({ apiKey: 'sk_test_...' })

// Full validation: 200+ rules, KoSIT, country CIUS
const result = await client.validate({ xml })

// Auto-fix compliance issues
const fixed = await client.validateAndFix({ xml })
```

## Supported Formats

| Format | Detection | Validation |
|--------|-----------|------------|
| UBL 2.1 Invoice | Yes | Yes |
| UBL 2.1 CreditNote | Yes | Yes |
| UN/CEFACT CII D16B | Yes | Yes |
| Peppol BIS Billing 3.0 | Yes | Yes |
| XRechnung 3.0 | Yes | Yes |
| ZUGFeRD 2.3 | Yes | Yes |
| Factur-X 1.0 | Yes | Yes |

## API

### `detectFormat(xml: string): FormatDetectionResult`

Detect the format and syntax of an e-invoice XML string.

```typescript
interface FormatDetectionResult {
  format: InvoiceFormat  // e.g. 'peppol-bis-3.0', 'xrechnung-ubl', 'cii'
  syntax: 'ubl' | 'cii' | 'unknown'
  version: string | null // e.g. '2.1', 'D16B'
}
```

### `validate(xml: string): ValidationResult`

Validate an e-invoice against EN 16931 core rules.

```typescript
interface ValidationResult {
  valid: boolean
  format: FormatDetectionResult
  errors: ValidationIssue[]
  summary: { errors: number; warnings: number }
}

interface ValidationIssue {
  rule: string      // e.g. 'BR-01', 'STRUCT-02'
  message: string
  severity: 'error' | 'warning'
}
```

## Contributing

See [CONTRIBUTING.md](./CONTRIBUTING.md). Issues and PRs welcome.

## License

MIT — use it however you want.