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

@@ -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
 

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.'
 }

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<void> {
-    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,
+      textData: null,
-      timesheetData: letter.content.timesheetData,
+      timesheetData: null,
-      contractData: letter.content.contractData
+      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
+      // Update the pdf property with a proper IPdf object
-      this.pdf = modifiedPdfBytes;
+      this.pdf = {
+        name: this.pdf.name,
+        id: this.pdf.id,
+        metadata: this.pdf.metadata,
+        buffer: modifiedPdfBytes
+      };
       
       return modifiedPdfBytes;
     } catch (error) {

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

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

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 billedBy: plugins.tsclass.business.TContact = invoice.billedBy;
-    const billedTo: plugins.tsclass.business.IContact = invoice.billedTo;
+    const billedTo: plugins.tsclass.business.TContact = invoice.billedTo;
 
     // 2) Start building the document
     const doc = smartxmlInstance

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

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 billedBy: plugins.tsclass.business.TContact = invoice.billedBy;
-    const billedTo: plugins.tsclass.business.IContact = invoice.billedTo;
+    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();