einvoice/MIGRATION.md

Migration Guide: XInvoice to EInvoice (v4.x to v5.x)

This guide helps you migrate from @fin.cx/xinvoice v4.x to @fin.cx/einvoice v5.x.

Overview

Version 5.0.0 introduces a complete rebranding from XInvoice to EInvoice. The name change better reflects the library's purpose as a comprehensive electronic invoice (e-invoice) processing solution that supports multiple international standards.

Breaking Changes

1. Package Name Change

Old:

"dependencies": {
  "@fin.cx/xinvoice": "^4.3.0"
}

New:

"dependencies": {
  "@fin.cx/einvoice": "^5.0.0"
}

2. Import Changes

Old:

import { XInvoice } from '@fin.cx/xinvoice';
import type { XInvoiceOptions } from '@fin.cx/xinvoice';

New:

import { EInvoice } from '@fin.cx/einvoice';
import type { EInvoiceOptions } from '@fin.cx/einvoice';

3. Class Name Changes

Old:

const invoice = new XInvoice();
const invoiceFromXml = await XInvoice.fromXml(xmlString);
const invoiceFromPdf = await XInvoice.fromPdf(pdfBuffer);

New:

const invoice = new EInvoice();
const invoiceFromXml = await EInvoice.fromXml(xmlString);
const invoiceFromPdf = await EInvoice.fromPdf(pdfBuffer);

4. Type/Interface Changes

Old:

const options: XInvoiceOptions = {
  validateOnLoad: true,
  validationLevel: ValidationLevel.BUSINESS
};

New:

const options: EInvoiceOptions = {
  validateOnLoad: true,
  validationLevel: ValidationLevel.BUSINESS
};

New Features in v5.x

Enhanced Error Handling

Version 5.0.0 introduces specialized error classes for better error handling:

import {
  EInvoiceError,
  EInvoiceParsingError,
  EInvoiceValidationError,
  EInvoicePDFError,
  EInvoiceFormatError
} from '@fin.cx/einvoice';

try {
  const invoice = await EInvoice.fromXml(xmlString);
} catch (error) {
  if (error instanceof EInvoiceParsingError) {
    console.error('Parsing failed:', error.getLocationMessage());
    console.error('Suggestions:', error.getDetailedMessage());
  } else if (error instanceof EInvoiceValidationError) {
    console.error('Validation report:', error.getValidationReport());
  } else if (error instanceof EInvoicePDFError) {
    console.error('PDF operation failed:', error.message);
    console.error('Recovery suggestions:', error.getRecoverySuggestions());
  }
}

Error Recovery

The new version includes error recovery capabilities:

import { ErrorRecovery } from '@fin.cx/einvoice';

// Attempt to recover from XML parsing errors
const recovery = await ErrorRecovery.attemptXMLRecovery(xmlString, parsingError);
if (recovery.success && recovery.cleanedXml) {
  const invoice = await EInvoice.fromXml(recovery.cleanedXml);
}

Step-by-Step Migration

1. Update your package.json

# Remove old package
pnpm remove @fin.cx/xinvoice

# Install new package
pnpm add @fin.cx/einvoice

2. Update imports using find and replace

Find all occurrences of:

• @fin.cx/xinvoice → @fin.cx/einvoice
• XInvoice → EInvoice
• XInvoiceOptions → EInvoiceOptions

3. Update your code

Example migration:

Before:

import { XInvoice, ValidationLevel } from '@fin.cx/xinvoice';

async function processInvoice(xmlData: string) {
  try {
    const xinvoice = await XInvoice.fromXml(xmlData);
    const validation = await xinvoice.validate(ValidationLevel.BUSINESS);
    
    if (!validation.valid) {
      throw new Error('Validation failed');
    }
    
    return xinvoice;
  } catch (error) {
    console.error('Error:', error);
    throw error;
  }
}

After:

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

async function processInvoice(xmlData: string) {
  try {
    const einvoice = await EInvoice.fromXml(xmlData);
    const validation = await einvoice.validate(ValidationLevel.BUSINESS);
    
    if (!validation.valid) {
      throw new EInvoiceValidationError(
        'Invoice validation failed',
        validation.errors
      );
    }
    
    return einvoice;
  } catch (error) {
    if (error instanceof EInvoiceValidationError) {
      console.error('Validation Report:', error.getValidationReport());
    }
    throw error;
  }
}

4. Update your tests

Update test imports and class names:

Before:

import { XInvoice } from '@fin.cx/xinvoice';
import { expect } from '@push.rocks/tapbundle';

test('should create invoice', async () => {
  const invoice = new XInvoice();
  expect(invoice).toBeInstanceOf(XInvoice);
});

After:

import { EInvoice } from '@fin.cx/einvoice';
import { expect } from '@push.rocks/tapbundle';

test('should create invoice', async () => {
  const invoice = new EInvoice();
  expect(invoice).toBeInstanceOf(EInvoice);
});

Compatibility

Unchanged APIs

The following APIs remain unchanged:

• All method signatures on the main class
• All validation levels and invoice formats
• All export formats
• The structure of validation results
• PDF handling capabilities

Deprecated Features

None. This is a pure rebranding release with enhanced error handling.

Need Help?

If you encounter any issues during migration:

1. Check the changelog for detailed changes
2. Review the updated documentation
3. Report issues at GitHub Issues

Why the Name Change?

• EInvoice (electronic invoice) is more universally recognized
• Better represents support for multiple international standards
• Aligns with industry terminology (e-invoicing, e-invoice)
• More intuitive for new users discovering the library