From 6906e2f778439541ac495eb64cef66701ef593bf Mon Sep 17 00:00:00 2001 From: Philipp Kunz Date: Thu, 20 Mar 2025 13:57:45 +0000 Subject: [PATCH] BREAKING CHANGE(core): Refactor contact and PDF handling across the library by replacing IContact with TContact and updating PDF processing to use a structured IPdf object. These changes ensure that empty contact objects include registration details, founded/closed dates, and status, and that PDF loading/exporting uniformly wraps buffers in a proper object. --- changelog.md | 8 ++++++ ts/00_commitinfo_data.ts | 2 +- ts/classes.xinvoice.ts | 49 +++++++++++++++++++++++++++------- ts/formats/base.decoder.ts | 44 +++++++++++++++++++++++++----- ts/formats/facturx.decoder.ts | 38 +++++++++++++++++++++++--- ts/formats/facturx.encoder.ts | 4 +-- ts/formats/xinvoice.decoder.ts | 38 +++++++++++++++++++++++--- ts/formats/xinvoice.encoder.ts | 12 ++++----- 8 files changed, 164 insertions(+), 31 deletions(-) diff --git a/changelog.md b/changelog.md index 9754125..bcb025c 100644 --- a/changelog.md +++ b/changelog.md @@ -1,5 +1,13 @@ # Changelog +## 2025-03-20 - 2.0.0 - BREAKING CHANGE(core) +Refactor contact and PDF handling across the library by replacing IContact with TContact and updating PDF processing to use a structured IPdf object. These changes ensure that empty contact objects include registration details, founded/closed dates, and status, and that PDF loading/exporting uniformly wraps buffers in a proper object. + +- Updated createEmptyContact (renamed in documentation to reflect TContact) to return a complete TContact object with registrationDetails, foundedDate, closedDate, and status. +- Modified loadPdf and exportPdf in XInvoice to wrap PDF buffers in an IPdf object with name, id, and metadata instead of using a raw Uint8Array. +- Replaced IContact with TContact in FacturXEncoder, FacturXDecoder, and XInvoiceDecoder to standardize contact structure. +- Aligned address and contact data across decoders and encoders for consistency. + ## 2025-03-17 - 1.3.3 - fix(commitinfo) Synchronize commit info version with package.json version diff --git a/ts/00_commitinfo_data.ts b/ts/00_commitinfo_data.ts index 792a77a..353ee83 100644 --- a/ts/00_commitinfo_data.ts +++ b/ts/00_commitinfo_data.ts @@ -3,6 +3,6 @@ */ export const commitinfo = { name: '@fin.cx/xinvoice', - version: '1.3.3', + version: '2.0.0', description: 'A TypeScript module for creating, manipulating, and embedding XML data within PDF files specifically tailored for xinvoice packages.' } diff --git a/ts/classes.xinvoice.ts b/ts/classes.xinvoice.ts index c728d8d..61aa2c7 100644 --- a/ts/classes.xinvoice.ts +++ b/ts/classes.xinvoice.ts @@ -90,7 +90,7 @@ export class XInvoice implements plugins.tsclass.business.ILetter { } /** - * Creates an empty IContact object + * Creates an empty TContact object */ private createEmptyContact(): plugins.tsclass.business.TContact { return { @@ -103,7 +103,23 @@ export class XInvoice implements plugins.tsclass.business.ILetter { city: '', country: '', postalCode: '' - } + }, + registrationDetails: { + vatId: '', + registrationId: '', + registrationName: '' + }, + foundedDate: { + year: 2000, + month: 1, + day: 1 + }, + closedDate: { + year: 9999, + month: 12, + day: 31 + }, + status: 'active' }; } @@ -198,7 +214,15 @@ export class XInvoice implements plugins.tsclass.business.ILetter { * @param pdfBuffer PDF buffer */ public async loadPdf(pdfBuffer: Uint8Array | Buffer): Promise { - this.pdf = Uint8Array.from(pdfBuffer); + // Create a valid IPdf object + this.pdf = { + name: 'invoice.pdf', + id: `invoice-${Date.now()}`, + metadata: { + textExtraction: '' + }, + buffer: Uint8Array.from(pdfBuffer) + }; try { // Try to extract embedded XML @@ -224,7 +248,7 @@ export class XInvoice implements plugins.tsclass.business.ILetter { } try { - const pdfDoc = await PDFDocument.load(this.pdf); + const pdfDoc = await PDFDocument.load(this.pdf.buffer); // Get the document's metadata dictionary const namesDictObj = pdfDoc.catalog.lookup(PDFName.of('Names')); @@ -313,9 +337,9 @@ export class XInvoice implements plugins.tsclass.business.ILetter { this.to = { ...letter.to }; this.content = { invoiceData: letter.content.invoiceData ? { ...letter.content.invoiceData } : this.createEmptyInvoice(), - textData: letter.content.textData, - timesheetData: letter.content.timesheetData, - contractData: letter.content.contractData + textData: null, + timesheetData: null, + contractData: null }; this.needsCoverSheet = letter.needsCoverSheet; this.objectActions = [...letter.objectActions]; @@ -412,7 +436,7 @@ export class XInvoice implements plugins.tsclass.business.ILetter { const xmlContent = await this.exportXml(format); // Load the PDF - const pdfDoc = await PDFDocument.load(this.pdf); + const pdfDoc = await PDFDocument.load(this.pdf.buffer); // Convert the XML string to a Uint8Array const xmlBuffer = new TextEncoder().encode(xmlContent); @@ -452,8 +476,13 @@ export class XInvoice implements plugins.tsclass.business.ILetter { // Save the modified PDF const modifiedPdfBytes = await pdfDoc.save(); - // Update the pdf property - this.pdf = modifiedPdfBytes; + // Update the pdf property with a proper IPdf object + this.pdf = { + name: this.pdf.name, + id: this.pdf.id, + metadata: this.pdf.metadata, + buffer: modifiedPdfBytes + }; return modifiedPdfBytes; } catch (error) { diff --git a/ts/formats/base.decoder.ts b/ts/formats/base.decoder.ts index 827ee0c..2d64775 100644 --- a/ts/formats/base.decoder.ts +++ b/ts/formats/base.decoder.ts @@ -27,31 +27,63 @@ export abstract class BaseDecoder { */ protected createDefaultLetter(): plugins.tsclass.business.ILetter { // Create a default seller - const seller: plugins.tsclass.business.IContact = { + const seller: plugins.tsclass.business.TContact = { name: 'Unknown Seller', type: 'company', - description: 'Unknown Seller', // Required by IContact interface + description: 'Unknown Seller', address: { streetName: 'Unknown', - houseNumber: '0', // Required by IAddress interface + houseNumber: '0', city: 'Unknown', country: 'Unknown', postalCode: 'Unknown', }, + registrationDetails: { + vatId: 'Unknown', + registrationId: 'Unknown', + registrationName: 'Unknown' + }, + foundedDate: { + year: 2000, + month: 1, + day: 1 + }, + closedDate: { + year: 9999, + month: 12, + day: 31 + }, + status: 'active' }; // Create a default buyer - const buyer: plugins.tsclass.business.IContact = { + const buyer: plugins.tsclass.business.TContact = { name: 'Unknown Buyer', type: 'company', - description: 'Unknown Buyer', // Required by IContact interface + description: 'Unknown Buyer', address: { streetName: 'Unknown', - houseNumber: '0', // Required by IAddress interface + houseNumber: '0', city: 'Unknown', country: 'Unknown', postalCode: 'Unknown', }, + registrationDetails: { + vatId: 'Unknown', + registrationId: 'Unknown', + registrationName: 'Unknown' + }, + foundedDate: { + year: 2000, + month: 1, + day: 1 + }, + closedDate: { + year: 9999, + month: 12, + day: 31 + }, + status: 'active' }; // Create default invoice data diff --git a/ts/formats/facturx.decoder.ts b/ts/formats/facturx.decoder.ts index 260171b..dd48a0e 100644 --- a/ts/formats/facturx.decoder.ts +++ b/ts/formats/facturx.decoder.ts @@ -97,21 +97,37 @@ export class FacturXDecoder extends BaseDecoder { } // Create seller - const seller: plugins.tsclass.business.IContact = { + const seller: plugins.tsclass.business.TContact = { name: sellerName, type: 'company', description: sellerName, address: { streetName: this.getElementText('ram:LineOne') || 'Unknown', - houseNumber: '0', // Required by IAddress interface + houseNumber: '0', city: this.getElementText('ram:CityName') || 'Unknown', country: this.getElementText('ram:CountryID') || 'Unknown', postalCode: this.getElementText('ram:PostcodeCode') || 'Unknown', }, + registrationDetails: { + vatId: this.getElementText('ram:ID') || 'Unknown', + registrationId: this.getElementText('ram:ID') || 'Unknown', + registrationName: sellerName + }, + foundedDate: { + year: 2000, + month: 1, + day: 1 + }, + closedDate: { + year: 9999, + month: 12, + day: 31 + }, + status: 'active' }; // Create buyer - const buyer: plugins.tsclass.business.IContact = { + const buyer: plugins.tsclass.business.TContact = { name: buyerName, type: 'company', description: buyerName, @@ -122,6 +138,22 @@ export class FacturXDecoder extends BaseDecoder { country: 'Unknown', postalCode: 'Unknown', }, + registrationDetails: { + vatId: 'Unknown', + registrationId: 'Unknown', + registrationName: buyerName + }, + foundedDate: { + year: 2000, + month: 1, + day: 1 + }, + closedDate: { + year: 9999, + month: 12, + day: 31 + }, + status: 'active' }; // Extract invoice type diff --git a/ts/formats/facturx.encoder.ts b/ts/formats/facturx.encoder.ts index d6b9a63..f266180 100644 --- a/ts/formats/facturx.encoder.ts +++ b/ts/formats/facturx.encoder.ts @@ -32,8 +32,8 @@ export class FacturXEncoder { } const invoice: plugins.tsclass.finance.IInvoice = letterArg.content.invoiceData; - const billedBy: plugins.tsclass.business.IContact = invoice.billedBy; - const billedTo: plugins.tsclass.business.IContact = invoice.billedTo; + const billedBy: plugins.tsclass.business.TContact = invoice.billedBy; + const billedTo: plugins.tsclass.business.TContact = invoice.billedTo; // 2) Start building the document const doc = smartxmlInstance diff --git a/ts/formats/xinvoice.decoder.ts b/ts/formats/xinvoice.decoder.ts index e5f59a1..fb6dc65 100644 --- a/ts/formats/xinvoice.decoder.ts +++ b/ts/formats/xinvoice.decoder.ts @@ -118,21 +118,37 @@ export class XInvoiceDecoder extends BaseDecoder { 'Unknown Buyer'; // Create seller contact - const seller: plugins.tsclass.business.IContact = { + const seller: plugins.tsclass.business.TContact = { name: sellerName, type: 'company', description: sellerName, address: { streetName: sellerStreet, - houseNumber: '0', // Required by IAddress interface + houseNumber: '0', city: sellerCity, country: sellerCountry, postalCode: sellerPostcode, }, + registrationDetails: { + vatId: this.getElementText('cac:AccountingSupplierParty/cac:Party/cac:PartyTaxScheme/cbc:CompanyID') || 'Unknown', + registrationId: this.getElementText('cac:AccountingSupplierParty/cac:Party/cac:PartyLegalEntity/cbc:CompanyID') || 'Unknown', + registrationName: sellerName + }, + foundedDate: { + year: 2000, + month: 1, + day: 1 + }, + closedDate: { + year: 9999, + month: 12, + day: 31 + }, + status: 'active' }; // Create buyer contact - const buyer: plugins.tsclass.business.IContact = { + const buyer: plugins.tsclass.business.TContact = { name: buyerName, type: 'company', description: buyerName, @@ -143,6 +159,22 @@ export class XInvoiceDecoder extends BaseDecoder { country: 'Unknown', postalCode: 'Unknown', }, + registrationDetails: { + vatId: this.getElementText('cac:AccountingCustomerParty/cac:Party/cac:PartyTaxScheme/cbc:CompanyID') || 'Unknown', + registrationId: this.getElementText('cac:AccountingCustomerParty/cac:Party/cac:PartyLegalEntity/cbc:CompanyID') || 'Unknown', + registrationName: buyerName + }, + foundedDate: { + year: 2000, + month: 1, + day: 1 + }, + closedDate: { + year: 9999, + month: 12, + day: 31 + }, + status: 'active' }; // Extract invoice type diff --git a/ts/formats/xinvoice.encoder.ts b/ts/formats/xinvoice.encoder.ts index 7cf15a3..169826b 100644 --- a/ts/formats/xinvoice.encoder.ts +++ b/ts/formats/xinvoice.encoder.ts @@ -23,8 +23,8 @@ export class XInvoiceEncoder { } const invoice: plugins.tsclass.finance.IInvoice = letterArg.content.invoiceData; - const billedBy: plugins.tsclass.business.IContact = invoice.billedBy; - const billedTo: plugins.tsclass.business.IContact = invoice.billedTo; + const billedBy: plugins.tsclass.business.TContact = invoice.billedBy; + const billedTo: plugins.tsclass.business.TContact = invoice.billedTo; // Create the XML document const doc = smartxmlInstance @@ -76,9 +76,9 @@ export class XInvoiceEncoder { const supplierPartyDetails = supplierParty.ele('cac:Party'); // Seller VAT ID - if (billedBy.vatId) { + if (billedBy.type === 'company' && billedBy.registrationDetails?.vatId) { const partyTaxScheme = supplierPartyDetails.ele('cac:PartyTaxScheme'); - partyTaxScheme.ele('cbc:CompanyID').txt(billedBy.vatId).up(); + partyTaxScheme.ele('cbc:CompanyID').txt(billedBy.registrationDetails.vatId).up(); partyTaxScheme.ele('cac:TaxScheme') .ele('cbc:ID').txt('VAT').up() .up(); @@ -117,9 +117,9 @@ export class XInvoiceEncoder { const customerPartyDetails = customerParty.ele('cac:Party'); // Buyer VAT ID - if (billedTo.vatId) { + if (billedTo.type === 'company' && billedTo.registrationDetails?.vatId) { const partyTaxScheme = customerPartyDetails.ele('cac:PartyTaxScheme'); - partyTaxScheme.ele('cbc:CompanyID').txt(billedTo.vatId).up(); + partyTaxScheme.ele('cbc:CompanyID').txt(billedTo.registrationDetails.vatId).up(); partyTaxScheme.ele('cac:TaxScheme') .ele('cbc:ID').txt('VAT').up() .up();