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.

2025-03-20 13:57:45 +00:00 · 2025-03-20 13:57:45 +00:00 · 6906e2f778
commit 6906e2f778
parent 75b720a98d
8 changed files with 164 additions and 31 deletions
--- 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

--- 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.'
 }
--- 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<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,
-      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) {
--- 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
--- 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
--- 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
--- 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
--- 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();