Compare commits
4 Commits
Author | SHA1 | Date | |
---|---|---|---|
fcbe8151b7 | |||
a106d66a10 | |||
cdb30d867d | |||
bc3028af55 |
243
MIGRATION.md
243
MIGRATION.md
@@ -1,243 +0,0 @@
|
||||
# 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
|
@@ -1,5 +1,14 @@
|
||||
# Changelog
|
||||
|
||||
## 2025-08-11 - 5.1.1 - fix(build/publishing)
|
||||
Remove migration guide and update publishing and schematron download configurations
|
||||
|
||||
- Deleted MIGRATION.md as migration instructions are no longer needed in v5.x
|
||||
- Updated .claude/settings.local.json to include new permission settings
|
||||
- Changed import in ts_install/download-schematron.ts to use 'dist_ts' instead of 'ts'
|
||||
- Added tspublish.json files in both ts and ts_install with an explicit order configuration
|
||||
- Refined publishing configuration (ts/tspublish.json) to align with new build process
|
||||
|
||||
## 2025-01-11 - 5.1.0 - feat(compliance)
|
||||
Achieve 100% EN16931 compliance with comprehensive validation support
|
||||
|
||||
|
@@ -1,6 +1,6 @@
|
||||
{
|
||||
"name": "@fin.cx/einvoice",
|
||||
"version": "5.1.0",
|
||||
"version": "5.1.1",
|
||||
"private": false,
|
||||
"description": "A TypeScript module for creating, manipulating, and embedding XML data within PDF files specifically tailored for electronic invoice (einvoice) packages.",
|
||||
"main": "dist_ts/index.js",
|
||||
@@ -10,10 +10,10 @@
|
||||
"license": "MIT",
|
||||
"scripts": {
|
||||
"test": "(tstest test/ --verbose --logfile --timeout 60)",
|
||||
"build": "(tsbuild --web --allowimplicitany)",
|
||||
"build": "(tsbuild tsfolders --allowimplicitany)",
|
||||
"buildDocs": "(tsdoc)",
|
||||
"download-schematron": "tsx scripts/download-schematron.ts",
|
||||
"download-test-samples": "tsx scripts/download-test-samples.ts",
|
||||
"download-schematron": "tsx ts_install/download-schematron.ts",
|
||||
"download-test-samples": "tsx ts_install/download-test-samples.ts",
|
||||
"test:conformance": "tstest test/test.conformance-harness.ts"
|
||||
},
|
||||
"devDependencies": {
|
||||
|
10
readme.md
10
readme.md
@@ -178,13 +178,13 @@ No more floating-point errors! Built-in arbitrary precision arithmetic:
|
||||
|
||||
```typescript
|
||||
// Perfect financial calculations every time
|
||||
const calculator = new DecimalCurrencyCalculator();
|
||||
const result = calculator.calculateLineTotal(
|
||||
'999.99', // Unit price
|
||||
const calculator = new DecimalCurrencyCalculator('EUR');
|
||||
const result = calculator.calculateLineNet(
|
||||
'3.14159', // Quantity
|
||||
'EUR' // Currency-aware rounding
|
||||
'999.99', // Unit price
|
||||
'0' // Discount (optional)
|
||||
);
|
||||
// Result: 3141.49 (correctly rounded for EUR)
|
||||
// Result: 3141.56 (correctly rounded for EUR)
|
||||
```
|
||||
|
||||
### 🔍 Multi-Level Validation
|
||||
|
@@ -3,6 +3,6 @@
|
||||
*/
|
||||
export const commitinfo = {
|
||||
name: '@fin.cx/einvoice',
|
||||
version: '5.0.0',
|
||||
version: '5.1.1',
|
||||
description: 'A TypeScript module for creating, manipulating, and embedding XML data within PDF files specifically tailored for electronic invoice (einvoice) packages.'
|
||||
}
|
||||
|
3
ts/tspublish.json
Normal file
3
ts/tspublish.json
Normal file
@@ -0,0 +1,3 @@
|
||||
{
|
||||
"order": 1
|
||||
}
|
@@ -4,7 +4,7 @@
|
||||
* Script to download official Schematron files for e-invoice validation
|
||||
*/
|
||||
|
||||
import { SchematronDownloader } from '../ts/formats/validation/schematron.downloader.js';
|
||||
import { SchematronDownloader } from '../dist_ts/formats/validation/schematron.downloader.js';
|
||||
|
||||
async function main() {
|
||||
console.log('📥 Starting Schematron download...\n');
|
3
ts_install/tspublish.json
Normal file
3
ts_install/tspublish.json
Normal file
@@ -0,0 +1,3 @@
|
||||
{
|
||||
"order": 1
|
||||
}
|
Reference in New Issue
Block a user