@narrow-os/document-templates 1.0.0

package/README.md

@@ -0,0 +1,177 @@
+# @bizflow/document-templates
+
+Universal, framework-agnostic document templates and HTML/PDF generators for **Invoices**, **Quotations**, **Retail POS Receipts**, and **Delivery Notes**.
+
+Designed to run seamlessly across:
+
+- **Node.js / NestJS** (for automated background emails, cron jobs, and Puppeteer PDF generation)
+- **Next.js Server & Client** (App Router, Pages, SSR, API routes)
+- **Browsers & POS Terminals** (Direct printing, thermal receipt printing, live canvas-free preview)
+
+---
+
+## Features
+
+- 🎨 **10 Distinct A4 Design Presets**: `classic`, `modern`, `minimal`, `corporate`, `bold`, `elegant`, `tech`, `vibrant`, `compact`, and `mono`.
+- 🧾 **10 Thermal Receipt Presets**: `classic`, `compact`, `wide`, `dense`, `sparse`, `boxed`, `lined`, `split`, `monobold`, and `elegant` (for 80mm & 58mm thermal receipt printers).
+- 🇿🇦 **South African 15% VAT & Multi-Currency Ready**: Built-in compliant tax calculation, deposit breakdowns, installment terms, and banking payment instructions.
+- ⚡ **Zero DOM Canvas Crashes**: Built-in vector SVG Code 128 barcode and QR code generators that run headlessly in pure Node.js without requiring `<canvas>` or native DOM bindings.
+- 📦 **Framework Agnostic**: Pure TypeScript returning clean HTML strings ready for `puppeteer.page.setContent(html)` or `window.open().document.write(html)`.
+
+---
+
+## Installation
+
+### Local Installation in Monorepo / Relative Path
+
+```bash
+npm install ../packages/document-templates
+# or from root
+npm install ./packages/document-templates
+```
+
+### When Published to npm
+
+```bash
+npm install @bizflow/document-templates
+```
+
+---
+
+## Quick Start
+
+### 1. Generating an Invoice HTML
+
+```typescript
+import {
+  InvoiceReportGenerator,
+  generateInvoiceHTML,
+} from "@bizflow/document-templates";
+
+const invoiceHtml = await generateInvoiceHTML(
+  {
+    id: "inv-001",
+    invoiceNumber: "INV-2026-001",
+    issueDate: new Date(),
+    dueDate: new Date(Date.now() + 30 * 24 * 60 * 60 * 1000),
+    status: "SENT",
+    client: {
+      name: "Acme Industrial Pty Ltd",
+      email: "accounts@acme.co.za",
+      address: "10 Industrial Way",
+      city: "Johannesburg",
+      province: "Gauteng",
+      taxNumber: "4990123456",
+    },
+    items: [
+      {
+        id: "item-1",
+        description: "Industrial Water Pump Installation",
+        quantity: 1,
+        unitPrice: 15000,
+        amount: 15000,
+        taxRate: 15,
+      },
+      {
+        id: "item-2",
+        description: "Standard Fitting & Labor",
+        quantity: 4,
+        unitPrice: 850,
+        amount: 3400,
+        taxRate: 15,
+      },
+    ],
+  },
+  {
+    templateId: "modern", // 'classic' | 'modern' | 'minimal' | 'corporate' | 'bold' | 'elegant' | 'tech' | 'vibrant' | 'compact' | 'mono'
+    companyInfo: {
+      companyName: "NECS Engineers Pty Ltd",
+      taxId: "4001234567",
+      address: "45 Technology Park",
+      city: "Pretoria",
+      phone: "+27 12 345 6789",
+      email: "billing@necs.co.za",
+      bankName: "First National Bank",
+      bankAccount: "62000012345",
+    },
+    combineServices: true,
+  },
+);
+```
+
+### 2. Generating Quotations
+
+```typescript
+import { generateQuotationHTML } from "@bizflow/document-templates";
+
+const quoteHtml = await generateQuotationHTML(quotationData, {
+  templateId: "corporate",
+  companyInfo: myCompany,
+});
+```
+
+### 3. Printing POS Receipts (A4 & Thermal 80mm)
+
+```typescript
+import { receiptGenerator } from "@bizflow/document-templates";
+
+// Thermal 80mm
+const thermalHtml = await receiptGenerator.generateReceiptHTML(
+  saleData,
+  "thermal",
+  true,
+);
+
+// Standard A4 Tax Receipt
+const a4ReceiptHtml = await receiptGenerator.generateReceiptHTML(
+  saleData,
+  "A4",
+  false,
+);
+```
+
+### 4. Headless PDF Generation in Node.js / NestJS
+
+```typescript
+import puppeteer from "puppeteer";
+import { generateInvoiceHTML } from "@bizflow/document-templates";
+
+const html = await generateInvoiceHTML(invoice, { companyInfo });
+
+const browser = await puppeteer.launch({ args: ["--no-sandbox"] });
+const page = await browser.newPage();
+await page.setContent(html, { waitUntil: "load" });
+const pdfBuffer = await page.pdf({
+  format: "A4",
+  printBackground: true,
+  margin: { top: "0.5in", right: "0.5in", bottom: "0.5in", left: "0.5in" },
+});
+await browser.close();
+
+// pdfBuffer is ready to attach to Resend, SendGrid, or nodemailer!
+```
+
+---
+
+## Publishing to npm
+
+To publish this package to npm:
+
+1. Build the distribution bundle:
+   ```bash
+   npm run build
+   ```
+2. Login to npm:
+   ```bash
+   npm login
+   ```
+3. Publish:
+   ```bash
+   npm publish --access public
+   ```
+
+---
+
+## License
+
+MIT © Rethynk Web Studio