From efac2187f2f309517c298866d4f5c43832799106 Mon Sep 17 00:00:00 2001 From: Philipp Kunz Date: Sat, 20 Apr 2024 23:17:35 +0200 Subject: [PATCH] update documentation --- npmextra.json | 27 ++++++++- package.json | 24 +++++++- readme.hints.md | 1 + readme.md | 145 ++++++++++++++++++++++++++++++++++++++++++++++-- 4 files changed, 187 insertions(+), 10 deletions(-) create mode 100644 readme.hints.md diff --git a/npmextra.json b/npmextra.json index c8be0a9..e03d2f0 100644 --- a/npmextra.json +++ b/npmextra.json @@ -2,19 +2,40 @@ "gitzone": { "projectType": "wcc", "module": { - "githost": "gitlab.com", + "githost": "code.foss.global", "gitscope": "designestate/private", "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", "license": "MIT", "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": { "npmGlobalTools": [], "npmAccessLevel": "private", "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" } } \ No newline at end of file diff --git a/package.json b/package.json index 065a872..a8203a6 100644 --- a/package.json +++ b/package.json @@ -2,7 +2,7 @@ "name": "@design.estate/dees-document", "version": "1.0.99", "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", "typings": "dist_ts_web/index.d.ts", "exports": { @@ -62,5 +62,23 @@ "bugs": { "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" + ] +} \ No newline at end of file diff --git a/readme.hints.md b/readme.hints.md new file mode 100644 index 0000000..0519ecb --- /dev/null +++ b/readme.hints.md @@ -0,0 +1 @@ + \ No newline at end of file diff --git a/readme.md b/readme.md index 21e926d..4bc2050 100644 --- a/readme.md +++ b/readme.md @@ -1,7 +1,144 @@ -# @design.estate/private/dedocument-catalog +# @design.estate/dees-document 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 -For further information read the linked docs at the top of this readme. +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. + +```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.