@fin.cx/einvoice
Version:
A TypeScript module for creating, manipulating, and embedding XML data within PDF files specifically tailored for electronic invoice (einvoice) packages.
218 lines (217 loc) • 6.8 kB
TypeScript
import { business, finance } from './plugins.js';
import type { TInvoice, TAccountingDocItem } from '@tsclass/tsclass/dist_ts/finance/index.js';
import { InvoiceFormat, ValidationLevel } from './interfaces/common.js';
import type { ValidationResult, ValidationError, EInvoiceOptions, IPdf, ExportFormat } from './interfaces/common.js';
/**
* Main class for working with electronic invoices.
* Supports various invoice formats including Factur-X, ZUGFeRD, UBL, and XRechnung
* Extends the TInvoice interface for seamless integration with existing systems
*/
export declare class EInvoice implements TInvoice {
/**
* Creates an EInvoice instance from XML string
* @param xmlString XML string to parse
* @returns EInvoice instance
*/
static fromXml(xmlString: string): Promise<EInvoice>;
/**
* Creates an EInvoice instance from file
* @param filePath Path to the file
* @returns EInvoice instance
*/
static fromFile(filePath: string): Promise<EInvoice>;
/**
* Creates an EInvoice instance from PDF
* @param pdfBuffer PDF buffer
* @returns EInvoice instance
*/
static fromPdf(pdfBuffer: Buffer | string): Promise<EInvoice>;
type: 'accounting-doc';
accountingDocType: 'invoice';
accountingDocId: string;
accountingDocStatus: 'draft' | 'issued' | 'paid' | 'canceled' | 'refunded';
id: string;
date: number;
status: 'draft' | 'issued' | 'paid' | 'canceled' | 'refunded';
subject: string;
versionInfo: business.TDocumentEnvelope<string, any>['versionInfo'];
from: business.TContact;
to: business.TContact;
legalContact?: business.TContact;
incidenceId: string;
language: string;
objectActions: any[];
pdf: IPdf | null;
pdfAttachments: IPdf[] | null;
accentColor: string | null;
logoUrl: string | null;
items: TAccountingDocItem[];
dueInDays: number;
reverseCharge: boolean;
currency: finance.TCurrency;
notes: string[];
periodOfPerformance?: {
from: number;
to: number;
};
deliveryDate?: number;
buyerReference?: string;
electronicAddress?: {
scheme: string;
value: string;
};
paymentOptions?: finance.IPaymentOptionInfo;
relatedDocuments?: Array<{
relationType: 'corrects' | 'replaces' | 'references';
documentId: string;
issueDate?: number;
}>;
printResult?: {
pdfBufferString: string;
totalNet: number;
totalGross: number;
vatGroups: {
percentage: number;
items: TAccountingDocItem[];
}[];
};
get invoiceId(): string;
set invoiceId(value: string);
get invoiceType(): 'invoice' | 'creditnote' | 'debitnote';
set invoiceType(value: 'invoice' | 'creditnote' | 'debitnote');
get issueDate(): Date;
set issueDate(value: Date);
get totalNet(): number;
get totalVat(): number;
get totalGross(): number;
get taxBreakdown(): Array<{
taxPercent: number;
netAmount: number;
taxAmount: number;
}>;
metadata?: {
format?: InvoiceFormat;
version?: string;
profile?: string;
customizationId?: string;
extensions?: Record<string, any>;
};
private xmlString;
private detectedFormat;
private validationErrors;
private options;
private pdfEmbedder;
private pdfExtractor;
/**
* Creates a new EInvoice instance
* @param options Configuration options
*/
constructor(options?: EInvoiceOptions);
/**
* Creates an empty TContact object
*/
private createEmptyContact;
/**
* Exports the invoice as XML in the specified format
* @param format The export format
* @returns XML string
*/
exportXml(format: ExportFormat): Promise<string>;
/**
* Loads invoice data from XML (alias for fromXmlString)
* @param xmlString The XML string to parse
* @returns The EInvoice instance for chaining
*/
loadXml(xmlString: string): Promise<EInvoice>;
/**
* Loads invoice data from an XML string
* @param xmlString The XML string to parse
* @returns The EInvoice instance for chaining
*/
fromXmlString(xmlString: string): Promise<EInvoice>;
/**
* Loads invoice data from a file
* @param filePath Path to the file to load
* @returns The EInvoice instance for chaining
*/
fromFile(filePath: string): Promise<EInvoice>;
/**
* Loads invoice data from a PDF file
* @param filePath Path to the PDF file
* @returns The EInvoice instance for chaining
*/
fromPdfFile(filePath: string): Promise<EInvoice>;
/**
* Maps data from a TInvoice to this EInvoice instance
*/
private mapFromTInvoice;
/**
* Maps this EInvoice instance to a TInvoice
*/
private mapToTInvoice;
/**
* Exports the invoice to an XML string in the specified format
* @param format The target format
* @returns The XML string
*/
toXmlString(format: ExportFormat): Promise<string>;
/**
* Validates the invoice
* @param level The validation level to use
* @returns The validation result
*/
validate(level?: ValidationLevel): Promise<ValidationResult>;
/**
* Embeds the invoice XML into a PDF
* @param pdfBuffer The PDF buffer to embed into
* @param format The format to use for embedding
* @returns The PDF buffer with embedded XML
*/
embedInPdf(pdfBuffer: Buffer, format?: ExportFormat): Promise<Buffer>;
/**
* Saves the invoice to a file
* @param filePath The path to save to
* @param format The format to save in
*/
saveToFile(filePath: string, format?: ExportFormat): Promise<void>;
/**
* Gets the validation errors
* @returns Array of validation errors
*/
getValidationErrors(): ValidationError[];
/**
* Checks if the invoice is valid
* @returns True if valid, false otherwise
*/
isValid(): boolean;
/**
* Gets the detected format
* @returns The detected invoice format
*/
getFormat(): InvoiceFormat;
/**
* Gets the original XML string
* @returns The XML string
*/
getXml(): string;
/**
* Calculates the total net amount
*/
private calculateTotalNet;
/**
* Calculates the total VAT amount
*/
private calculateTotalVat;
/**
* Calculates tax breakdown by rate
*/
private calculateTaxBreakdown;
/**
* Creates a new invoice item
*/
createItem(data: Partial<TAccountingDocItem>): TAccountingDocItem;
/**
* Adds an item to the invoice
*/
addItem(item: Partial<TAccountingDocItem>): void;
}