dees-document/readme.md

# @design.estate/dees-document

A comprehensive solution for generating documents like invoices, integrating elements, templates, and services to streamline document creation.

## Install

To add `@design.estate/dees-document` to your project, run the following command in your terminal:

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

This will install the package and add it to your project's dependencies, ensuring all required modules are available in your `node_modules` directory.

## Usage

The `@design.estate/dees-document` package provides a robust framework for creating documents including invoices, contracts, and various other business-related documents. It is built on modern web technologies including TypeScript and ES modules to ensure a type-safe and easy-to-integrate experience. Below, we will guide you through the comprehensive usage of this package, from setting up your environment to generating PDF documents. 

### Getting Started

Before creating documents, initialize the document service which is central to this package. This is typically done at the beginning of your application.

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

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

This script initializes `PdfService`. Modify the options to tailor the service to your needs.

### Creating Documents

With the PDF service ready, you can proceed to generate documents. The following section provides a detailed example of creating an invoice. This example is applicable to various document types with necessary adjustments.

#### Step-by-Step: Create an Invoice

1. **Define the Data Structure**: Describe the invoice details. This includes sender and recipient information, the items being invoiced, and more.

   ```typescript
   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"
     },
   };
   ```

   Here, `ILetter` interface details all components of an invoice including sender (`from`) and recipient (`to`) information, as well as the invoiced items.

2. **Generate the PDF**: Transform the invoice details into a PDF.

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

     // Save the PDF, send it via email, etc.
   }
   ```

   The function `createPdfFromLetterObject` returns a `Buffer` containing the generated PDF. From here, you can save this PDF to a file, send it to clients, or archive it.

3. **Integrate It All**: Here's how everything ties together into a complete script for generating an invoice:

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

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

   This script initiates the PDF service and generates the invoice PDF with the provided information.

### Advanced Document Features

The package is designed to create not only invoices but a wide range of document types. Leverage its modular architecture to build and customize documents to fit specific needs.

#### Advanced Scenarios

1. **Custom Styling**: Customize the appearance of elements within your documents, such as headers, footers, and more.

   ```typescript
   import { DeDocumentViewer } from '@design.estate/dees-element';

   const customStyledViewer = new DeDocumentViewer();
   customStyledViewer.style.setProperty('--main-bg-color', 'lightblue');
   document.body.appendChild(customStyledViewer);
   ```

   Customize via CSS or dynamically through TypeScript where necessary.

2. **Interactive Document Elements**: Incorporate UI components like buttons, input fields, or visualizations tailored for your document needs.

3. **Multi-page Document Generation**: Handle overflow of content and automatic page generation while maintaining headers and footers.

   ```typescript
   pdfService.adjustDePageScaling();
   ```

   Toggle between print and digital formats and handle scaling.

4. **Embedding Images and Logos**: Add company logos, graphics, or auxiliary content to enhance document presentation.

### Additional Capabilities

Beyond these examples, delve deeper into advanced functionalities such as:

- **Document Management**: Manage multiple document templates, manage versions, and add annotations or notes.
- **Dynamic Rendering**: Use templating for dynamic content rendering based on variable inputs.
- **Responsive Design for Digital Documents**: Ensure documents are displayed correctly across devices.

### Concluding Remarks

The `@design.estate/dees-document` package is an essential tool in the modern document generation ecosystem. Its expansive capabilities, from basic invoices to complex document templates, make it a versatile solution for businesses of all scales. Implementing this service broadly simplifies document management workflows and enhances document presentation precision and quality. For further depth, consult the package's documentation or explore the examples included in the module.

## 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](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.