@fin.cx/einvoice 5.0.2

package/ts/errors.ts

@@ -0,0 +1,341 @@
+/**
+ * Base error class for all EInvoice-related errors
+ */
+export class EInvoiceError extends Error {
+  public code: string;
+  public details?: any;
+  public cause?: Error;
+
+  constructor(message: string, code: string, details?: any, cause?: Error) {
+    super(message);
+    this.name = 'EInvoiceError';
+    this.code = code;
+    this.details = details;
+    this.cause = cause;
+    
+    // Maintains proper stack trace for where our error was thrown (only available on V8)
+    if (Error.captureStackTrace) {
+      Error.captureStackTrace(this, this.constructor);
+    }
+  }
+
+  /**
+   * Returns a detailed error message including cause if available
+   */
+  public getDetailedMessage(): string {
+    let message = `${this.name} [${this.code}]: ${this.message}`;
+    if (this.details) {
+      message += `\nDetails: ${JSON.stringify(this.details, null, 2)}`;
+    }
+    if (this.cause) {
+      message += `\nCaused by: ${this.cause.message}`;
+    }
+    return message;
+  }
+}
+
+/**
+ * Error thrown when XML parsing fails
+ */
+export class EInvoiceParsingError extends EInvoiceError {
+  public line?: number;
+  public column?: number;
+  public xmlSnippet?: string;
+
+  constructor(
+    message: string,
+    details?: {
+      line?: number;
+      column?: number;
+      xmlSnippet?: string;
+      format?: string;
+    },
+    cause?: Error
+  ) {
+    super(message, 'PARSE_ERROR', details, cause);
+    this.name = 'EInvoiceParsingError';
+    this.line = details?.line;
+    this.column = details?.column;
+    this.xmlSnippet = details?.xmlSnippet;
+  }
+
+  /**
+   * Returns a user-friendly error message with location information
+   */
+  public getLocationMessage(): string {
+    let message = this.message;
+    if (this.line !== undefined && this.column !== undefined) {
+      message += ` at line ${this.line}, column ${this.column}`;
+    }
+    if (this.xmlSnippet) {
+      message += `\nNear: ${this.xmlSnippet}`;
+    }
+    return message;
+  }
+}
+
+/**
+ * Error thrown when validation fails
+ */
+export class EInvoiceValidationError extends EInvoiceError {
+  public validationErrors: Array<{
+    code: string;
+    message: string;
+    location?: string;
+    severity?: 'error' | 'warning';
+  }>;
+
+  constructor(
+    message: string,
+    validationErrors: Array<{
+      code: string;
+      message: string;
+      location?: string;
+      severity?: 'error' | 'warning';
+    }>,
+    details?: any
+  ) {
+    super(message, 'VALIDATION_ERROR', details);
+    this.name = 'EInvoiceValidationError';
+    this.validationErrors = validationErrors;
+  }
+
+  /**
+   * Returns a formatted validation report
+   */
+  public getValidationReport(): string {
+    let report = `${this.message}\n\nValidation errors:\n`;
+    for (const error of this.validationErrors) {
+      report += `- [${error.code}] ${error.message}`;
+      if (error.location) {
+        report += ` (at ${error.location})`;
+      }
+      if (error.severity) {
+        report += ` [${error.severity.toUpperCase()}]`;
+      }
+      report += '\n';
+    }
+    return report;
+  }
+
+  /**
+   * Gets validation errors by severity
+   */
+  public getErrorsBySeverity(severity: 'error' | 'warning'): typeof this.validationErrors {
+    return this.validationErrors.filter(e => (e.severity || 'error') === severity);
+  }
+}
+
+/**
+ * Error thrown during PDF operations
+ */
+export class EInvoicePDFError extends EInvoiceError {
+  public operation: 'extract' | 'embed' | 'create' | 'validate';
+  public pdfInfo?: {
+    filename?: string;
+    size?: number;
+    pageCount?: number;
+  };
+
+  constructor(
+    message: string,
+    operation: 'extract' | 'embed' | 'create' | 'validate',
+    details?: any,
+    cause?: Error
+  ) {
+    super(message, `PDF_${operation.toUpperCase()}_ERROR`, details, cause);
+    this.name = 'EInvoicePDFError';
+    this.operation = operation;
+    this.pdfInfo = details?.pdfInfo;
+  }
+
+  /**
+   * Returns recovery suggestions based on the operation
+   */
+  public getRecoverySuggestions(): string[] {
+    const suggestions: string[] = [];
+    
+    switch (this.operation) {
+      case 'extract':
+        suggestions.push(
+          'Ensure the PDF contains embedded XML data',
+          'Check if the PDF is a valid PDF/A-3 document',
+          'Try using a different extraction method',
+          'Verify the PDF is not corrupted'
+        );
+        break;
+      case 'embed':
+        suggestions.push(
+          'Ensure the source PDF is valid',
+          'Check that the XML data is well-formed',
+          'Verify sufficient memory is available',
+          'Try with a smaller XML payload'
+        );
+        break;
+      case 'create':
+        suggestions.push(
+          'Verify all required invoice data is provided',
+          'Check that the template PDF exists',
+          'Ensure write permissions for output directory'
+        );
+        break;
+      case 'validate':
+        suggestions.push(
+          'Check PDF/A-3 compliance',
+          'Verify XML attachment structure',
+          'Ensure proper PDF metadata'
+        );
+        break;
+    }
+    
+    return suggestions;
+  }
+}
+
+/**
+ * Error thrown for format-specific issues
+ */
+export class EInvoiceFormatError extends EInvoiceError {
+  public sourceFormat?: string;
+  public targetFormat?: string;
+  public unsupportedFeatures?: string[];
+
+  constructor(
+    message: string,
+    details: {
+      sourceFormat?: string;
+      targetFormat?: string;
+      unsupportedFeatures?: string[];
+      conversionPath?: string;
+    },
+    cause?: Error
+  ) {
+    super(message, 'FORMAT_ERROR', details, cause);
+    this.name = 'EInvoiceFormatError';
+    this.sourceFormat = details.sourceFormat;
+    this.targetFormat = details.targetFormat;
+    this.unsupportedFeatures = details.unsupportedFeatures;
+  }
+
+  /**
+   * Returns a compatibility report
+   */
+  public getCompatibilityReport(): string {
+    let report = this.message;
+    if (this.sourceFormat && this.targetFormat) {
+      report += `\n\nConversion: ${this.sourceFormat} → ${this.targetFormat}`;
+    }
+    if (this.unsupportedFeatures && this.unsupportedFeatures.length > 0) {
+      report += '\n\nUnsupported features:';
+      for (const feature of this.unsupportedFeatures) {
+        report += `\n- ${feature}`;
+      }
+    }
+    return report;
+  }
+}
+
+/**
+ * Error recovery helper class
+ */
+export class ErrorRecovery {
+  /**
+   * Attempts to recover from a parsing error by cleaning the XML
+   */
+  public static async attemptXMLRecovery(
+    xmlString: string,
+    error: EInvoiceParsingError
+  ): Promise<{ success: boolean; cleanedXml?: string; message: string }> {
+    try {
+      let cleanedXml = xmlString;
+      
+      // Remove BOM if present
+      if (cleanedXml.charCodeAt(0) === 0xFEFF) {
+        cleanedXml = cleanedXml.slice(1);
+      }
+      
+      // Fix common encoding issues
+      cleanedXml = cleanedXml
+        .replace(/&(?!(amp|lt|gt|apos|quot);)/g, '&amp;')
+        .replace(/</g, (match, offset) => {
+          // Don't replace if it's part of <![CDATA[
+          const before = cleanedXml.substring(Math.max(0, offset - 10), offset);
+          if (before.includes('CDATA[')) return match;
+          return '&lt;';
+        });
+      
+      // Try to fix unclosed tags if we have location info
+      if (error.line && error.xmlSnippet) {
+        // This is a simplified approach - real implementation would be more sophisticated
+        const lines = cleanedXml.split('\n');
+        if (lines[error.line - 1]) {
+          // Attempt basic fixes based on the error
+          // This is just a placeholder for more sophisticated recovery
+        }
+      }
+      
+      return {
+        success: true,
+        cleanedXml,
+        message: 'Applied basic XML cleaning and encoding fixes'
+      };
+    } catch (recoveryError) {
+      return {
+        success: false,
+        message: `Recovery failed: ${recoveryError instanceof Error ? recoveryError.message : String(recoveryError)}`
+      };
+    }
+  }
+
+  /**
+   * Provides partial data extraction on validation failure
+   */
+  public static extractPartialData(
+    xmlString: string,
+    format: string
+  ): { success: boolean; partialData?: any; message: string } {
+    try {
+      // This would implement format-specific partial extraction
+      // For now, returning a placeholder
+      return {
+        success: false,
+        message: 'Partial data extraction not yet implemented'
+      };
+    } catch (error) {
+      return {
+        success: false,
+        message: `Partial extraction failed: ${error instanceof Error ? error.message : String(error)}`
+      };
+    }
+  }
+}
+
+/**
+ * Error context builder for detailed error information
+ */
+export class ErrorContext {
+  private context: Map<string, any> = new Map();
+
+  public add(key: string, value: any): this {
+    this.context.set(key, value);
+    return this;
+  }
+
+  public addTimestamp(): this {
+    this.context.set('timestamp', new Date().toISOString());
+    return this;
+  }
+
+  public addEnvironment(): this {
+    this.context.set('environment', {
+      nodeVersion: process.version,
+      platform: process.platform,
+      arch: process.arch
+    });
+    return this;
+  }
+
+  public build(): Record<string, any> {
+    return Object.fromEntries(this.context);
+  }
+}

package/ts/formats/base/base.decoder.ts

@@ -0,0 +1,68 @@
+import type { TInvoice } from '../../interfaces/common.js';
+import { ValidationLevel } from '../../interfaces/common.js';
+import type { ValidationResult } from '../../interfaces/common.js';
+
+/**
+ * Base decoder class that defines common decoding functionality
+ * for all invoice format decoders
+ */
+export abstract class BaseDecoder {
+  protected xml: string;
+  protected skipValidation: boolean;
+
+  constructor(xml: string, skipValidation: boolean = false) {
+    this.xml = xml;
+    this.skipValidation = skipValidation;
+  }
+
+  /**
+   * Decodes XML into a TInvoice object
+   * @returns Promise resolving to a TInvoice object
+   */
+  abstract decode(): Promise<TInvoice>;
+
+  /**
+   * Gets letter data in the standard format
+   * @returns Promise resolving to a TInvoice object
+   */
+  public async getLetterData(): Promise<TInvoice> {
+    return this.decode();
+  }
+
+  /**
+   * Gets the raw XML content
+   * @returns XML string
+   */
+  public getXml(): string {
+    return this.xml;
+  }
+
+  /**
+   * Parses a CII date string based on format code
+   * @param dateStr Date string
+   * @param format Format code (e.g., '102' for YYYYMMDD)
+   * @returns Timestamp in milliseconds
+   */
+  protected parseCIIDate(dateStr: string, format?: string): number {
+    if (!dateStr) return Date.now();
+
+    // Format 102 is YYYYMMDD
+    if (format === '102' && dateStr.length === 8) {
+      const year = parseInt(dateStr.substring(0, 4));
+      const month = parseInt(dateStr.substring(4, 6)) - 1; // Month is 0-indexed in JS
+      const day = parseInt(dateStr.substring(6, 8));
+      return new Date(year, month, day).getTime();
+    }
+    
+    // Format 610 is YYYYMM  
+    if (format === '610' && dateStr.length === 6) {
+      const year = parseInt(dateStr.substring(0, 4));
+      const month = parseInt(dateStr.substring(4, 6)) - 1;
+      return new Date(year, month, 1).getTime();
+    }
+
+    // Try to parse as ISO date or other standard formats
+    const parsed = Date.parse(dateStr);
+    return isNaN(parsed) ? Date.now() : parsed;
+  }
+}

package/ts/formats/base/base.encoder.ts

@@ -0,0 +1,14 @@
+import type { TInvoice } from '../../interfaces/common.js';
+
+/**
+ * Base encoder class that defines common encoding functionality
+ * for all invoice format encoders
+ */
+export abstract class BaseEncoder {
+  /**
+   * Encodes a TInvoice object into XML
+   * @param invoice TInvoice object to encode
+   * @returns XML string
+   */
+  abstract encode(invoice: TInvoice): Promise<string>;
+}

package/ts/formats/base/base.validator.ts

@@ -0,0 +1,64 @@
+import { ValidationLevel } from '../../interfaces/common.js';
+import type { ValidationResult, ValidationError } from '../../interfaces/common.js';
+
+/**
+ * Base validator class that defines common validation functionality
+ * for all invoice format validators
+ */
+export abstract class BaseValidator {
+  protected xml: string;
+  protected errors: ValidationError[] = [];
+
+  constructor(xml: string) {
+    this.xml = xml;
+  }
+
+  /**
+   * Validates XML against the specified level of validation
+   * @param level Validation level (syntax, semantic, business)
+   * @returns Result of validation
+   */
+  abstract validate(level?: ValidationLevel): ValidationResult;
+
+  /**
+   * Gets all validation errors found during validation
+   * @returns Array of validation errors
+   */
+  public getValidationErrors(): ValidationError[] {
+    return this.errors;
+  }
+
+  /**
+   * Checks if the document is valid
+   * @returns True if no validation errors were found
+   */
+  public isValid(): boolean {
+    return this.errors.length === 0;
+  }
+
+  /**
+   * Validates XML against schema
+   * @returns True if schema validation passed
+   */
+  protected abstract validateSchema(): boolean;
+
+  /**
+   * Validates business rules
+   * @returns True if business rule validation passed
+   */
+  protected abstract validateBusinessRules(): boolean;
+
+  /**
+   * Adds an error to the validation errors list
+   * @param code Error code
+   * @param message Error message
+   * @param location Location in the XML where the error occurred
+   */
+  protected addError(code: string, message: string, location: string = ''): void {
+    this.errors.push({
+      code,
+      message,
+      location
+    });
+  }
+}

package/ts/formats/cii/cii.decoder.ts

@@ -0,0 +1,139 @@
+import { BaseDecoder } from '../base/base.decoder.js';
+import type { TInvoice, TCreditNote, TDebitNote } from '../../interfaces/common.js';
+import { CII_NAMESPACES, CIIProfile } from './cii.types.js';
+import { DOMParser, xpath } from '../../plugins.js';
+
+/**
+ * Base decoder for CII-based invoice formats
+ */
+export abstract class CIIBaseDecoder extends BaseDecoder {
+  protected doc: Document;
+  protected namespaces: Record<string, string>;
+  protected select: xpath.XPathSelect;
+  protected profile: CIIProfile = CIIProfile.EN16931;
+
+  constructor(xml: string, skipValidation: boolean = false) {
+    super(xml, skipValidation);
+
+    // Parse XML document
+    this.doc = new DOMParser().parseFromString(xml, 'application/xml');
+
+    // Set up namespaces for XPath queries
+    this.namespaces = {
+      rsm: CII_NAMESPACES.RSM,
+      ram: CII_NAMESPACES.RAM,
+      udt: CII_NAMESPACES.UDT
+    };
+
+    // Create XPath selector with namespaces
+    this.select = xpath.useNamespaces(this.namespaces);
+
+    // Detect profile
+    this.detectProfile();
+  }
+
+  /**
+   * Decodes CII XML into a TInvoice object
+   * @returns Promise resolving to a TInvoice object
+   */
+  public async decode(): Promise<TInvoice> {
+    // Determine if it's a credit note or debit note based on type code
+    const typeCode = this.getText('//ram:TypeCode');
+
+    if (typeCode === '381') { // Credit note type code
+      return this.decodeCreditNote() as unknown as TInvoice;
+    } else {
+      return this.decodeDebitNote() as unknown as TInvoice;
+    }
+  }
+
+  /**
+   * Detects the CII profile from the XML
+   */
+  protected detectProfile(): void {
+    // Look for profile identifier
+    const profileNode = this.select(
+      'string(//rsm:ExchangedDocumentContext/ram:GuidelineSpecifiedDocumentContextParameter/ram:ID)',
+      this.doc
+    );
+
+    if (profileNode) {
+      const profileText = profileNode.toString();
+
+      if (profileText.includes('BASIC')) {
+        this.profile = CIIProfile.BASIC;
+      } else if (profileText.includes('EN16931')) {
+        this.profile = CIIProfile.EN16931;
+      } else if (profileText.includes('EXTENDED')) {
+        this.profile = CIIProfile.EXTENDED;
+      } else if (profileText.includes('MINIMUM')) {
+        this.profile = CIIProfile.MINIMUM;
+      } else if (profileText.includes('COMFORT')) {
+        this.profile = CIIProfile.COMFORT;
+      }
+    }
+  }
+
+  /**
+   * Decodes a CII credit note
+   * @returns Promise resolving to a TCreditNote object
+   */
+  protected abstract decodeCreditNote(): Promise<TCreditNote>;
+
+  /**
+   * Decodes a CII debit note (invoice)
+   * @returns Promise resolving to a TDebitNote object
+   */
+  protected abstract decodeDebitNote(): Promise<TDebitNote>;
+
+  /**
+   * Gets a text value from an XPath expression
+   * @param xpath XPath expression
+   * @param context Optional context node
+   * @returns Text value or empty string if not found
+   */
+  protected getText(xpathExpr: string, context?: Node): string {
+    const node = this.select(xpathExpr, context || this.doc)[0];
+    return node ? (node.textContent || '') : '';
+  }
+
+  /**
+   * Gets a number value from an XPath expression
+   * @param xpath XPath expression
+   * @param context Optional context node
+   * @returns Number value or 0 if not found or not a number
+   */
+  protected getNumber(xpathExpr: string, context?: Node): number {
+    const text = this.getText(xpathExpr, context);
+    const num = parseFloat(text);
+    return isNaN(num) ? 0 : num;
+  }
+
+  /**
+   * Gets a date value from an XPath expression
+   * @param xpath XPath expression
+   * @param context Optional context node
+   * @returns Date timestamp or current time if not found or invalid
+   */
+  protected getDate(xpathExpr: string, context?: Node): number {
+    const text = this.getText(xpathExpr, context);
+    if (!text) return Date.now();
+
+    const date = new Date(text);
+    return isNaN(date.getTime()) ? Date.now() : date.getTime();
+  }
+
+  /**
+   * Checks if a node exists
+   * @param xpath XPath expression
+   * @param context Optional context node
+   * @returns True if node exists
+   */
+  protected exists(xpathExpr: string, context?: Node): boolean {
+    const nodes = this.select(xpathExpr, context || this.doc);
+    if (Array.isArray(nodes)) {
+      return nodes.length > 0;
+    }
+    return false;
+  }
+}

package/ts/formats/cii/cii.encoder.ts

@@ -0,0 +1,64 @@
+import { BaseEncoder } from '../base/base.encoder.js';
+import type { TInvoice, TCreditNote, TDebitNote } from '../../interfaces/common.js';
+import { CII_NAMESPACES, CIIProfile } from './cii.types.js';
+
+/**
+ * Base encoder for CII-based invoice formats
+ */
+export abstract class CIIBaseEncoder extends BaseEncoder {
+  protected profile: CIIProfile = CIIProfile.EN16931;
+
+  /**
+   * Sets the CII profile to use for encoding
+   * @param profile CII profile
+   */
+  public setProfile(profile: CIIProfile): void {
+    this.profile = profile;
+  }
+
+  /**
+   * Encodes a TInvoice object into CII XML
+   * @param invoice TInvoice object to encode
+   * @returns CII XML string
+   */
+  public async encode(invoice: TInvoice): Promise<string> {
+    // TInvoice is always an invoice, treat it as debit note for encoding
+    return this.encodeDebitNote(invoice as unknown as TDebitNote);
+  }
+
+  /**
+   * Encodes a TCreditNote object into CII XML
+   * @param creditNote TCreditNote object to encode
+   * @returns CII XML string
+   */
+  protected abstract encodeCreditNote(creditNote: TCreditNote): Promise<string>;
+
+  /**
+   * Encodes a TDebitNote object into CII XML
+   * @param debitNote TDebitNote object to encode
+   * @returns CII XML string
+   */
+  protected abstract encodeDebitNote(debitNote: TDebitNote): Promise<string>;
+
+  /**
+   * Creates the XML declaration and root element
+   * @returns XML string with declaration and root element
+   */
+  protected createXmlRoot(): string {
+    return `<?xml version="1.0" encoding="UTF-8"?>
+<rsm:CrossIndustryInvoice xmlns:rsm="${CII_NAMESPACES.RSM}"
+  xmlns:ram="${CII_NAMESPACES.RAM}"
+  xmlns:udt="${CII_NAMESPACES.UDT}">
+</rsm:CrossIndustryInvoice>`;
+  }
+
+  /**
+   * Formats a date as an ISO string (YYYY-MM-DD)
+   * @param timestamp Timestamp to format
+   * @returns Formatted date string
+   */
+  protected formatDate(timestamp: number): string {
+    const date = new Date(timestamp);
+    return date.toISOString().split('T')[0];
+  }
+}