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:**
```json
"dependencies": {
  "@fin.cx/xinvoice": "^4.3.0"
}
```

**New:**
```json
"dependencies": {
  "@fin.cx/einvoice": "^5.0.0"
}
```

### 2. Import Changes

**Old:**
```typescript
import { XInvoice } from '@fin.cx/xinvoice';
import type { XInvoiceOptions } from '@fin.cx/xinvoice';
```

**New:**
```typescript
import { EInvoice } from '@fin.cx/einvoice';
import type { EInvoiceOptions } from '@fin.cx/einvoice';
```

### 3. Class Name Changes

**Old:**
```typescript
const invoice = new XInvoice();
const invoiceFromXml = await XInvoice.fromXml(xmlString);
const invoiceFromPdf = await XInvoice.fromPdf(pdfBuffer);
```

**New:**
```typescript
const invoice = new EInvoice();
const invoiceFromXml = await EInvoice.fromXml(xmlString);
const invoiceFromPdf = await EInvoice.fromPdf(pdfBuffer);
```

### 4. Type/Interface Changes

**Old:**
```typescript
const options: XInvoiceOptions = {
  validateOnLoad: true,
  validationLevel: ValidationLevel.BUSINESS
};
```

**New:**
```typescript
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:

```typescript
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:

```typescript
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

```bash
# 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:**
```typescript
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:**
```typescript
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:**
```typescript
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:**
```typescript
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](./changelog.md) for detailed changes
2. Review the updated [documentation](./readme.md)
3. Report issues at [GitHub Issues](https://github.com/fin-cx/einvoice/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