update documentation

This commit is contained in:
Philipp Kunz 2024-04-20 23:17:35 +02:00
parent 12c1d92ec4
commit efac2187f2
4 changed files with 187 additions and 10 deletions

View File

@ -2,19 +2,40 @@
"gitzone": { "gitzone": {
"projectType": "wcc", "projectType": "wcc",
"module": { "module": {
"githost": "gitlab.com", "githost": "code.foss.global",
"gitscope": "designestate/private", "gitscope": "designestate/private",
"gitrepo": "dedocument-catalog", "gitrepo": "dedocument-catalog",
"description": "a catalog for creating documents like invoices", "description": "A comprehensive solution for generating documents like invoices, integrating elements, templates, and services to streamline document creation.",
"npmPackagename": "@designestate_private/dedocument-catalog", "npmPackagename": "@designestate_private/dedocument-catalog",
"license": "MIT", "license": "MIT",
"projectDomain": "design.estate", "projectDomain": "design.estate",
"shortDescription": "undefined variable" "shortDescription": "undefined variable",
"keywords": [
"document generation",
"invoices",
"PDF creation",
"typescript",
"web components",
"custom elements",
"QR code",
"smart contracts",
"templating",
"dynamic rendering",
"responsive design",
"modular development",
"lightweight",
"efficient",
"finance",
"business"
]
} }
}, },
"npmci": { "npmci": {
"npmGlobalTools": [], "npmGlobalTools": [],
"npmAccessLevel": "private", "npmAccessLevel": "private",
"npmRegistryUrl": "verdaccio2.lossless.one" "npmRegistryUrl": "verdaccio2.lossless.one"
},
"tsdoc": {
"legal": "\n## License and Legal Information\n\nThis 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. \n\n**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.\n\n### Trademarks\n\nThis 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.\n\n### Company Information\n\nTask Venture Capital GmbH \nRegistered at District court Bremen HRB 35230 HB, Germany\n\nFor any legal inquiries or if you require further information, please contact us via email at hello@task.vc.\n\nBy 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.\n"
} }
} }

View File

@ -2,7 +2,7 @@
"name": "@design.estate/dees-document", "name": "@design.estate/dees-document",
"version": "1.0.99", "version": "1.0.99",
"private": false, "private": false,
"description": "a catalog for creating documents like invoices", "description": "A comprehensive solution for generating documents like invoices, integrating elements, templates, and services to streamline document creation.",
"main": "dist_ts_web/index.js", "main": "dist_ts_web/index.js",
"typings": "dist_ts_web/index.d.ts", "typings": "dist_ts_web/index.d.ts",
"exports": { "exports": {
@ -62,5 +62,23 @@
"bugs": { "bugs": {
"url": "https://gitlab.com/designestate/private/dedocument-catalog/issues" "url": "https://gitlab.com/designestate/private/dedocument-catalog/issues"
}, },
"homepage": "https://gitlab.com/designestate/private/dedocument-catalog#readme" "homepage": "https://gitlab.com/designestate/private/dedocument-catalog#readme",
} "keywords": [
"document generation",
"invoices",
"PDF creation",
"typescript",
"web components",
"custom elements",
"QR code",
"smart contracts",
"templating",
"dynamic rendering",
"responsive design",
"modular development",
"lightweight",
"efficient",
"finance",
"business"
]
}

1
readme.hints.md Normal file
View File

@ -0,0 +1 @@

145
readme.md
View File

@ -1,7 +1,144 @@
# @design.estate/private/dedocument-catalog # @design.estate/dees-document
a catalog for creating documents like invoices a catalog for creating documents like invoices
## Usage ## Install
To install `@design.estate/dees-document`, run the following command in your project directory:
```shell
npm install @design.estate/dees-document --save
```
Use TypeScript for best in class intellisense This will add `@design.estate/dees-document` to your project's dependencies and ensure it's installed into your `node_modules` folder.
For further information read the linked docs at the top of this readme.
## 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.
```typescript
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.
```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"
},
};
```
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.
```typescript
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:
```typescript
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](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.