fix(documentation): Updated documentation to reflect accurate module description and usage guidance

changelog.md

@@ -1,5 +1,12 @@
 # Changelog
 
+## 2024-12-31 - 1.1.1 - fix(documentation)
+Updated documentation to reflect accurate module description and usage guidance
+
+- Corrected description in package.json to better reflect the module's functionalities.
+- Enhanced README with detailed setup and usage instructions.
+- Included examples for embedding XML into PDFs and parsing XML data.
+
 ## 2024-12-30 - 1.1.0 - feat(core)
 Add EInvoiceCreator class for generating ZUGFeRD/Factur-X XML
 

npmextra.json

@@ -5,19 +5,23 @@
       "githost": "gitea.nevermind.cloud",
       "gitscope": "fin.cx",
       "gitrepo": "xinvoice",
-      "description": "A module for creating, manipulating, and embedding XML data within PDF files for xinvoice packages.",
+      "description": "A TypeScript module for creating, manipulating, and embedding XML data within PDF files specifically tailored for xinvoice packages.",
       "npmPackagename": "@fin.cx/xinvoice",
       "license": "MIT",
       "projectDomain": "fin.cx",
       "keywords": [
-        "invoice processing",
-        "PDF manipulation",
-        "XML embedding",
-        "financial documents",
         "xinvoice",
+        "XML embedding",
+        "PDF manipulation",
+        "invoice processing",
+        "financial documents",
         "document generation",
+        "typescript",
+        "ZUGFeRD",
+        "XML parsing",
         "PDF library",
-        "typescript"
+        "esm",
+        "financial technology"
       ]
     }
   },

package.json

@@ -2,7 +2,7 @@
   "name": "@fin.cx/xinvoice",
   "version": "1.1.0",
   "private": false,
-  "description": "A module for creating, manipulating, and embedding XML data within PDF files for xinvoice packages.",
+  "description": "A TypeScript module for creating, manipulating, and embedding XML data within PDF files specifically tailored for xinvoice packages.",
   "main": "dist_ts/index.js",
   "typings": "dist_ts/index.d.ts",
   "type": "module",
@@ -52,13 +52,17 @@
     "readme.md"
   ],
   "keywords": [
-    "invoice processing",
-    "PDF manipulation",
-    "XML embedding",
-    "financial documents",
     "xinvoice",
+    "XML embedding",
+    "PDF manipulation",
+    "invoice processing",
+    "financial documents",
     "document generation",
+    "typescript",
+    "ZUGFeRD",
+    "XML parsing",
     "PDF library",
-    "typescript"
+    "esm",
+    "financial technology"
   ]
 }

readme.md

@@ -1,23 +1,24 @@
+```markdown
 # @fin.cx/xinvoice
-a module for working with xinvoice packages.
+A module for creating, manipulating, and embedding XML data within PDF files for xinvoice packages.
 
 ## Install
 
-To install `@fin.cx/xinvoice`, you'll need npm (Node Package Manager). Run this command in your terminal:
+To install `@fin.cx/xinvoice`, you'll need npm (Node Package Manager). Run the following command in your terminal:
 
 ```shell
 npm install @fin.cx/xinvoice
 ```
 
-This command fetches the xinvoice package from the npm registry and installs it in your project.
+This command fetches the `xinvoice` package from the npm registry and installs it in your project directory.
 
 ## Usage
 
-The `@fin.cx/xinvoice` module is designed to work with xinvoice packages, specifically aimed at managing invoices with ease. This document will guide you through using all the features offered by the module, ensuring you can effectively incorporate it into your projects.
+The `@fin.cx/xinvoice` module is designed for handling and embedding XML data specifically tailored for xinvoice formats within PDF files. It streamlines the management of financial documents, typically involving the creation, manipulation, and embedding of structured invoice data. This section will cover a comprehensive usage guide, providing in-depth explanations of using each feature in a TypeScript environment with ESM syntax.
 
-### Getting Started with ESM and TypeScript
+### Setting Up Your TypeScript Environment
 
-To use `@fin.cx/xinvoice` in a TypeScript project, first, make sure you have configured TypeScript to support ECMAScript modules (ESM). Here's a basic `tsconfig.json` for reference:
+Before diving into the module’s functionalities, configure your TypeScript setup to handle ECMAScript modules. Here’s an example of a `tsconfig.json` configuration:
 
 ```json
 {
@@ -36,58 +37,157 @@ To use `@fin.cx/xinvoice` in a TypeScript project, first, make sure you have con
 }
 ```
 
-### Importing the Module
+This configuration ensures that TypeScript compiles your code using the latest ES module syntax, enabling direct and type-safe imports.
 
-With TypeScript configured, import the module into your project using ESM syntax:
+### Importing the `@fin.cx/xinvoice` Module
+
+With your TypeScript environment configured, import the `@fin.cx/xinvoice` module as follows:
 
 ```typescript
 import { XInvoice } from '@fin.cx/xinvoice';
 ```
 
-### Working with Invoices
+### Core Functionality: XInvoice Class
 
-The core functionality revolves around creating and managing XInvoice instances, which represent your invoices. Let's dive into how we can create and manipulate these instances.
+#### Introduction to XInvoice
+
+The `XInvoice` class stands at the heart of our module, enabling the creation, manipulation, and management of invoices. It allows you to incorporate XML data into PDF files seamlessly, providing a bridge between human-readable PDF formats and machine-readable XML specifications required for financial documents.
 
 #### Creating an XInvoice Instance
 
-To create a new instance of `XInvoice`, you'll need a PDF path, an XML path (which contains the invoice data), and an output path where the processed file will be saved:
+To harness the power of `XInvoice`, instantiate it with a path to the necessary file locations for your invoice processing needs:
 
 ```typescript
-const pdfPath = './path/to/your/invoice.pdf';
+const xInvoice = new XInvoice();
-const xmlPath = './path/to/your/invoice.xml';
-const outputPath = './path/to/save/processed_invoice.pdf';
-
-const xInvoice = new XInvoice(pdfPath, xmlPath, outputPath);
 ```
 
-#### Embedding XML into a PDF
+Here, we just initialize an `XInvoice` object that we can later configure with necessary inputs.
 
-One of the key features is embedding XML data into a PDF. This is crucial for ensuring that your invoice contains all necessary data in a format that's both human-readable and machine-processable. Here’s how to embed XML into a PDF:
+#### Adding PDF and XML Data
+
+Before embedding XML data into a PDF or extracting such information, provide the `XInvoice` instance with the required PDF and XML data:
 
 ```typescript
-await xInvoice.embedXml();
+import { promises as fs } from 'fs';
+
+async function loadFiles() {
+  const pdfBuffer = await fs.readFile('./path/to/your/invoice.pdf');
+  const xmlString = await fs.readFile('./path/to/your/invoice.xml', 'utf-8');
+
+  await xInvoice.addPdfBuffer(pdfBuffer);
+  await xInvoice.addXmlString(xmlString);
+}
 ```
 
-This method asynchronously processes the PDF and XML files, embedding the XML data into the PDF. Upon completion, it saves the modified PDF to the specified `outputPath`.
+The method `addPdfBuffer` takes a `Buffer` or `Uint8Array` of the PDF file, while `addXmlString` accepts the invoice's XML representation in string format.
 
-### Parsing XML to Create an Invoice Object
+#### Embedding XML into PDF
 
-While the provided example doesn't directly expose a parsing method, `@fin.cx/xinvoice` is designed to facilitate the extension and customization of such functionalities. If parsing from XML to a structured invoice object is necessary, consider implementing a parser that utilizes the interfaces provided by the module.
+Embedding XML data into a PDF is a significant capability of this module. Once you've loaded the PDF and XML data, invoke the `getXInvoice` method:
-
-For illustrative purposes, if there was a method `parseXmlToInvoice(xmlContent: string)` within `XInvoice`, it could be used like this:
 
 ```typescript
-const xmlContent = `<Your XML content here>`;
+await xInvoice.getXInvoice();
-const invoiceData = xInvoice.parseXmlToInvoice(xmlContent);
-
-console.log(invoiceData);
 ```
 
-### Conclusion
+This process attaches the XML to the PDF document, creating a structured combination that can be saved, shared, or further processed.
 
-The `@fin.cx/xinvoice` module provides a foundational framework for working with xinvoices, focusing on embedding XML data into PDFs and facilitating the potential parsing of XML to structured invoice data. Its usage in a TypeScript environment ensures type safety and enhances the development experience.
+#### Retrieving Embedded XML from PDF
+
+To access previously embedded XML data from a PDF, use the `getXmlData` method:
+
+```typescript
+const embeddedXml = await xInvoice.getXmlData();
+console.log(embeddedXml);
+```
+
+This method extracts the XML content directly from the PDF file, decoding it into a string.
+
+### Advanced Usage: XML Parsing and Data Extraction
+
+#### Parsing XML into Structured Invoice Data
+
+When dealing with complex financial documents, converting XML into possible structured data reflects prudent practice. If your focus is analyzing invoice contents, the module offers parsing into TypeScript interfaces:
+
+```typescript
+const parsedInvoiceData = await xInvoice.getParsedXmlData();
+console.log(parsedInvoiceData);
+```
+
+The retrieval produces an object conforming to the following structure defined by `IXInvoice`:
+
+```typescript
+interface IXInvoice {
+  InvoiceNumber: string;
+  DateIssued: string;
+  Seller: IParty;
+  Buyer: IParty;
+  Items: IInvoiceItem[];
+  TotalAmount: number;
+}
+
+interface IParty {
+  Name: string;
+  Address: IAddress;
+  Contact: IContact;
+}
+
+interface IAddress {
+  Street: string;
+  City: string;
+  PostalCode: string;
+  Country: string;
+}
+
+interface IContact {
+  Email: string;
+  Phone: string;
+}
+
+interface IInvoiceItem {
+  Description: string;
+  Quantity: number;
+  UnitPrice: number;
+  TotalPrice: number;
+}
+```
+
+Each invoice object encompasses seller and buyer information, invoice items and their quantities, collectively synthesizing a comprehensive view of the document's content.
+
+### Custom Extensibility: Encoding and Decoding XML
+
+#### Custom XML Encoding
+
+Beyond pre-built functionalities, the module supports custom XML encoding of structured data into PDF attachments. Utilize `ZugferdXmlEncoder` for scenarios necessitating bespoke XML generation:
+
+```typescript
+import { ZugferdXmlEncoder } from '@fin.cx/xinvoice';
+
+const encoder = new ZugferdXmlEncoder();
+const customXml = encoder.createZugferdXml(someLetterData);
+```
+
+This use-case implies transforming invoice data, specified in `ILetter`, into compliant ZUGFeRD/XML format.
+
+#### XML Decoding for Custom Handling
+
+In instances requiring parsing of arbitrary XML content, the `ZUGFeRDXmlDecoder` class proves instrumental:
+
+```typescript
+import { ZUGFeRDXmlDecoder } from '@fin.cx/xinvoice';
+
+const decoder = new ZUGFeRDXmlDecoder(someXmlString);
+const letterData = await decoder.getLetterData();
+```
+
+This class mimics the behavior of extracting XML to a structured `ILetter` object, suitable for scenarios requiring XML inspection or interfacing with custom workflows.
+
+### Comprehensive Feature Exploration
+
+The entirety of the module facilitates a wide spectrum of invoicing scenarios. From initial creation, embedding, and parsing tasks, to advanced encoding and decoding, every feature is crafted to accommodate complexities inherent in financial document management.
+
+By embracing `@fin.cx/xinvoice`, you simplify the handling of xinvoice-standard documents, fostering seamless integration across different financial processes, thus empowering practitioners with robust, flexible tools for VAT invoices in ZUGFeRD compliance or equivalent digital formats.
+```
 
-This guide covered installing the module, setting up a TypeScript project to use ESM syntax, creating an `XInvoice` instance, and embedding XML into PDFs. With these capabilities, `@fin.cx/xinvoice` is a robust tool for managing xinvoice packages within your application.
 
 ## License and Legal Information
 

ts/00_commitinfo_data.ts

@@ -3,6 +3,6 @@
  */
 export const commitinfo = {
   name: '@fin.cx/xinvoice',
-  version: '1.1.0',
+  version: '1.1.1',
-  description: 'A module for creating, manipulating, and embedding XML data within PDF files for xinvoice packages.'
+  description: 'A TypeScript module for creating, manipulating, and embedding XML data within PDF files specifically tailored for xinvoice packages.'
 }