@design.estate/dees-document

a catalog for creating documents like invoices

Install

To install @design.estate/dees-document, run the following command in your project directory:

npm install @design.estate/dees-document --save

This will add @design.estate/dees-document to your project's dependencies and ensure it's installed into your node_modules folder.

Usage

The @design.estate/dees-document package is a comprehensive toolkit for creating various types of documents, such as invoices, with ease. It leverages modern ECMAScript (ES) modules and TypeScript for a type-safe, developer-friendly experience. Below, you'll find detailed examples covering how to utilize the package to its full potential.

Setting Up the Document Service

Before diving into creating documents, you first need to set up the document service. This involves importing the necessary modules and initializing the service instance.

import { PdfService, IPdfServiceConstructorOptions } from '@design.estate/dees-document';

async function setupPdfService() {
  const options: IPdfServiceConstructorOptions = {
    // Configuration options here
  };
  
  const pdfService = await PdfService.createAndStart(options);
  console.log('PDF Service started successfully.');
  return pdfService;
}

In the example above, we import PdfService from the package and use its createAndStart method to initialize it with optional configuration settings. Replace // Configuration options here with any specific options your project may require.

Creating a Simple Invoice

After setting up the document service, you can proceed to create documents such as invoices. Here, we'll demonstrate how to create a basic invoice.

Define the Invoice Data Structure

First, define the basic structure of your invoice. This involves specifying details like the sender, recipient, items, and more.

import { ILetter } from '@design.estate/dees-document';

const invoiceData: ILetter = {
  from: {
    name: "Your Company Name",
    address: {
      streetName: "Your Street",
      houseNumber: "123",
      city: "Your City",
      country: "Your Country",
      postalCode: "12345",
    },
    email: "your-email@example.com",
    phone: "123-456-7890",
  },
  to: {
    name: "Recipient Company Name",
    address: {
      streetName: "Recipient Street",
      houseNumber: "456",
      city: "Recipient City",
      country: "Recipient Country",
      postalCode: "67890",
    },
    email: "recipient-email@example.com",
    phone: "098-765-4321",
  },
  content: {
    invoiceData: {
      items: [
        {
          name: "Service or Product Name",
          unitQuantity: 2,
          unitNetPrice: 100.00,
          unitType: 'service',
          vatPercentage: 19,
          currency: 'EUR',
        }
      ]
    }
  },
  subject: "Invoice for Services Rendered",
  date: new Date().getTime(),
  versionInfo: {
    type: "final",
    version: "1.0.0"
  },
};

In this structure, invoiceData outlines essential details for an invoice document, using the ILetter interface. It includes information about both the sender (from) and the recipient (to), as well as the invoiced items under content.invoiceData.items.

Generate the Invoice PDF

With the invoice data ready, you can now generate the PDF using the PdfService instance.

async function generateInvoice(pdfService: PdfService, invoiceData: ILetter) {
  const pdfBuffer = await pdfService.createPdfFromLetterObject(invoiceData);
  console.log('Invoice PDF generated successfully.');

  // Here, you can save the PDF to a file, send it over a network, etc.
}

The method createPdfFromLetterObject receives the invoice data and returns a Buffer containing the PDF. You can then save this PDF to the filesystem, send it over email, or perform any other required actions.

Complete Example Integration

Combining everything, your complete script to set up the service, define invoice data, and generate a PDF invoice might look something like this:

async function main() {
  const pdfService = await setupPdfService();
  await generateInvoice(pdfService, invoiceData);
}

main().then(() => console.log('Invoice generation process completed.'));

Beyond Invoices

The @design.estate/dees-document package is not limited to invoices alone. It's designed to handle a wide range of document types. The modular architecture allows for the customizable construction of documents, enabling you to tailor the output to meet precise requirements.

For instance, you can create contracts, reports, and other document types using a similar approach—by defining the content structure and utilizing the PDF service to generate the document. The package's flexibility and extensibility make it an invaluable tool in any document generation workflow.

Advanced Usage

For more advanced scenarios, such as custom styling, embedding images, and handling more complex document structures, refer to the package's documentation. It provides comprehensive details and examples to help you fully leverage the capabilities of @design.estate/dees-document.

License and Legal Information

This repository contains open-source code that is licensed under the MIT License. A copy of the MIT License can be found in the license file within this repository.

Please note: The MIT License does not grant permission to use the trade names, trademarks, service marks, or product names of the project, except as required for reasonable and customary use in describing the origin of the work and reproducing the content of the NOTICE file.

Trademarks

This project is owned and maintained by Task Venture Capital GmbH. The names and logos associated with Task Venture Capital GmbH and any related products or services are trademarks of Task Venture Capital GmbH and are not included within the scope of the MIT license granted herein. Use of these trademarks must comply with Task Venture Capital GmbH's Trademark Guidelines, and any usage must be approved in writing by Task Venture Capital GmbH.

Company Information

Task Venture Capital GmbH
Registered at District court Bremen HRB 35230 HB, Germany

For any legal inquiries or if you require further information, please contact us via email at hello@task.vc.

By using this repository, you acknowledge that you have read this section, agree to comply with its terms, and understand that the licensing of the code does not imply endorsement by Task Venture Capital GmbH of any derivative works.