@fin.cx/einvoice 5.1.3 → 5.2.0

package/ts/interfaces/common.ts

@@ -1,5 +1,3 @@
-import { business, finance } from '../plugins.js';
-
 /**
  * Supported electronic invoice formats
  */
@@ -88,4 +86,4 @@ export type { TCreditNote } from '@tsclass/tsclass/dist_ts/finance/index.js';
 export type { TDebitNote } from '@tsclass/tsclass/dist_ts/finance/index.js';
 export type { TContact } from '@tsclass/tsclass/dist_ts/business/index.js';
 export type { TLetterEnvelope } from '@tsclass/tsclass/dist_ts/business/index.js';
-export type { TDocumentEnvelope } from '@tsclass/tsclass/dist_ts/business/index.js';
+export type { TDocumentEnvelope } from '@tsclass/tsclass/dist_ts/business/index.js';

package/ts/plugins.ts

@@ -21,15 +21,14 @@ import {
 } from 'pdf-lib';
 
 // XML-related imports
-import { DOMParser, XMLSerializer } from 'xmldom';
-import * as xmldom from 'xmldom';
+import { DOMParser, XMLSerializer, xmldom } from './vendor/xmldom.js';
 import * as xpath from 'xpath';
 
 // XSLT/Schematron imports
-import * as SaxonJS from 'saxon-js';
+import { SaxonJS } from './vendor/saxonjs.js';
 
 // Compression-related imports
-import * as pako from 'pako';
+import { pako } from './vendor/pako.js';
 
 // Business model imports
 import { business, finance, general } from '@tsclass/tsclass';

package/ts/readme.md

@@ -0,0 +1,55 @@
+# @fin.cx/einvoice
+
+Source module for the main `@fin.cx/einvoice` package.
+
+This directory contains the public TypeScript API for loading, validating, converting, and embedding European e-invoice XML.
+
+## Issue Reporting and Security
+
+For reporting bugs, issues, or security vulnerabilities, please visit [community.foss.global/](https://community.foss.global/). This is the central community hub for all issue reporting. Developers who sign and comply with our contribution agreement and go through identification can also get a [code.foss.global/](https://code.foss.global/) account to submit Pull Requests directly.
+
+## What this module exports
+
+- `EInvoice`
+- `createEInvoice()`
+- `validateXml(xml, level?)`
+- `FormatDetector`
+- `PDFExtractor`, `PDFEmbedder`
+- `DecoderFactory`, `EncoderFactory`, `ValidatorFactory`
+- `BaseDecoder`, `BaseEncoder`, `BaseValidator`
+- `UBLBase*` and `CIIBase*` extension points
+- Factur-X and ZUGFeRD format-specific classes
+- root types such as `TInvoice`, `ValidationResult`, `ExportFormat`, `IPdf`
+
+## Main workflow
+
+```ts
+import { EInvoice, ValidationLevel } from '@fin.cx/einvoice';
+
+const invoice = await EInvoice.fromFile('./invoice.xml');
+const validation = await invoice.validate(ValidationLevel.BUSINESS);
+const xml = await invoice.exportXml('facturx');
+```
+
+## Format support
+
+| Format | Detect | Import | Export | Notes |
+| --- | --- | --- | --- | --- |
+| `ubl` | Yes | Yes | Yes | Generic UBL flow |
+| `xrechnung` | Yes | Yes | Yes | UBL-based profile |
+| `cii` | Yes | Yes | Yes | Generic export currently routes through the Factur-X encoder path |
+| `facturx` | Yes | Yes | Yes | Main CII generation path |
+| `zugferd` | Yes | Yes | Yes | Input supports v1 and v2+ |
+| `fatturapa` | Yes | No | No | Detection only at the moment |
+
+## Important implementation notes
+
+- `peppol` is not a root-level XML export target.
+- `FatturaPA` is not fully implemented for import/export.
+- PDF support means extracting or embedding XML into existing PDFs, not generating invoice PDFs from scratch.
+- Validation is useful and extensive, but should not be documented as blanket certification.
+
+## Related directories
+
+- `../readme.md`: full package README for end users
+- `../ts_install/readme.md`: install-time resource bootstrap module

package/ts/vendor/modules.d.ts

@@ -0,0 +1,32 @@
+declare module 'xmldom' {
+  export class DOMParser {
+    parseFromString(source: string, mimeType: string): Document;
+  }
+
+  export class XMLSerializer {
+    serializeToString(node: Node): string;
+  }
+}
+
+declare module 'pako' {
+  export function inflate(input: Uint8Array | ArrayBuffer | string, options?: unknown): Uint8Array;
+}
+
+declare module 'saxon-js' {
+  export function compile(options: {
+    stylesheetText: string;
+    warnings?: string;
+    [key: string]: unknown;
+  }): Promise<unknown>;
+
+  export function transform(options: {
+    stylesheetInternal?: unknown;
+    sourceText: string;
+    destination?: string;
+    stylesheetParams?: Record<string, unknown>;
+    [key: string]: unknown;
+  }): Promise<{
+    principalResult: string;
+    [key: string]: unknown;
+  }>;
+}

package/ts/vendor/pako.ts

@@ -0,0 +1,8 @@
+import * as pakoRuntime from 'pako';
+
+export interface IPakoModule {
+  inflate(input: Uint8Array | ArrayBuffer | string, options?: unknown): Uint8Array;
+  [key: string]: unknown;
+}
+
+export const pako: IPakoModule = pakoRuntime as unknown as IPakoModule;

package/ts/vendor/saxonjs.ts

@@ -0,0 +1,28 @@
+import * as saxonJSRuntime from 'saxon-js';
+
+export interface ISaxonJSCompileOptions {
+  stylesheetText: string;
+  warnings?: string;
+  [key: string]: unknown;
+}
+
+export interface ISaxonJSTransformOptions {
+  stylesheetInternal?: unknown;
+  sourceText: string;
+  destination?: string;
+  stylesheetParams?: Record<string, unknown>;
+  [key: string]: unknown;
+}
+
+export interface ISaxonJSTransformResult {
+  principalResult: string;
+  [key: string]: unknown;
+}
+
+export interface ISaxonJSModule {
+  compile(options: ISaxonJSCompileOptions): Promise<unknown>;
+  transform(options: ISaxonJSTransformOptions): Promise<ISaxonJSTransformResult>;
+  [key: string]: unknown;
+}
+
+export const SaxonJS: ISaxonJSModule = saxonJSRuntime as unknown as ISaxonJSModule;

package/ts/vendor/xmldom.ts

@@ -0,0 +1,27 @@
+import * as xmldomRuntime from 'xmldom';
+
+export interface IDOMParser {
+  parseFromString(source: string, mimeType: string): Document;
+}
+
+export interface IDOMParserConstructor {
+  new (): IDOMParser;
+}
+
+export interface IXMLSerializer {
+  serializeToString(node: Node): string;
+}
+
+export interface IXMLSerializerConstructor {
+  new (): IXMLSerializer;
+}
+
+export interface IXmlDomModule {
+  DOMParser: IDOMParserConstructor;
+  XMLSerializer: IXMLSerializerConstructor;
+  [key: string]: unknown;
+}
+
+export const DOMParser: IDOMParserConstructor = xmldomRuntime.DOMParser as unknown as IDOMParserConstructor;
+export const XMLSerializer: IXMLSerializerConstructor = xmldomRuntime.XMLSerializer as unknown as IXMLSerializerConstructor;
+export const xmldom: IXmlDomModule = xmldomRuntime as unknown as IXmlDomModule;