BREAKING CHANGE(core): Rebrand XInvoice to EInvoice: update package name, class names, imports, and documentation

MIGRATION.md

@@ -0,0 +1,243 @@
+# 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