@zola_do/email 0.2.4 → 0.2.6

package/README.md

@@ -1,6 +1,20 @@
 # @zola_do/email
 
-Email service for NestJS applications with SMTP and Handlebars template support.
+[![npm version](https://img.shields.io/npm/v/@zola_do/email.svg)](https://www.npmjs.com/package/@zola_do/email)
+[![npm downloads](https://img.shields.io/npm/dm/@zola_do/email.svg)](https://www.npmjs.com/package/@zola_do/email)
+[![License: ISC](https://img.shields.io/badge/License-ISC-blue.svg)](https://opensource.org/licenses/ISC)
+
+Email service for NestJS applications with SMTP transport and Handlebars template support.
+
+## Overview
+
+`@zola_do/email` provides:
+
+- **SMTP Transport** — Configurable via environment variables
+- **Handlebars Templates** — Server-side template rendering
+- **HTML Emails** — Send rich HTML content
+- **Connection Verification** — Test SMTP connection
+- **NestJS Integration** — Module-based setup
 
 ## Installation
 
@@ -12,13 +26,31 @@ npm install @zola_do/email
 npm install @zola_do/nestjs-shared
 ```
 
-## Usage
+### Dependencies
+
+```bash
+npm install @nestjs-modules/mailer nodemailer
+npm install @types/nodemailer --save-dev
+```
+
+## Quick Start
 
-### Module Setup
+### 1. Configure Environment
+
+```bash
+# .env
+EMAIL_SMTP=smtp.example.com
+EMAIL_SMTP_PORT=587
+EMAIL_SMTP_USERNAME=your-username
+EMAIL_SMTP_PASSWORD=your-password
+EMAIL_SMTP_DISPLAY_NAME=My App <noreply@example.com>
+```
+
+### 2. Register Module
 
 ```typescript
-import { Module } from '@nestjs/common';
-import { EmailModule } from '@zola_do/email';
+import { Module } from "@nestjs/common";
+import { EmailModule } from "@zola_do/email";
 
 @Module({
   imports: [EmailModule],
@@ -26,50 +58,415 @@ import { EmailModule } from '@zola_do/email';
 export class AppModule {}
 ```
 
-### Sending Emails
-
-Inject `EmailService` and send emails:
+### 3. Send Emails
 
 ```typescript
-import { Injectable } from '@nestjs/common';
-import { EmailService } from '@zola_do/email';
+import { Injectable } from "@nestjs/common";
+import { EmailService } from "@zola_do/email";
 
 @Injectable()
 export class NotificationService {
   constructor(private readonly emailService: EmailService) {}
 
   async sendWelcomeEmail(userEmail: string, userName: string) {
-    const body = `<h1>Welcome, ${userName}!</h1><p>Thanks for signing up.</p>`;
-    await this.emailService.sendEmail(userEmail, 'Welcome', body);
+    await this.emailService.sendEmail({
+      to: userEmail,
+      subject: "Welcome to Our App",
+      html: `
+        <h1>Welcome, ${userName}!</h1>
+        <p>Thanks for signing up.</p>
+      `,
+    });
+  }
+}
+```
+
+## Email Architecture
+
+```
+┌─────────────────────────────────────────────────────────────────────┐
+│                        Email Flow                                    │
+├─────────────────────────────────────────────────────────────────────┤
+│                                                                      │
+│  Controller/Service                                                  │
+│       │                                                              │
+│       │ 1. Prepare email data                                        │
+│       ▼                                                              │
+│  ┌─────────────────────────────────────┐                            │
+│  │  EmailService                       │                            │
+│  │                                     │                            │
+│  │  sendEmail({ to, subject, html })   │                            │
+│  └──────────────────┬──────────────────┘                            │
+│                     │                                                 │
+│                     │ 2. Render template (optional)                  │
+│                     ▼                                                 │
+│  ┌─────────────────────────────────────┐                            │
+│  │  templates/                          │                            │
+│  │  welcome.hbs                         │                            │
+│  └──────────────────┬──────────────────┘                            │
+│                     │                                                 │
+│                     │ 3. Send via SMTP                               │
+│                     ▼                                                 │
+│  ┌─────────────────────────────────────┐                            │
+│  │  nodemailer                          │                            │
+│  │  (SMTP Transport)                    │                            │
+│  └──────────────────┬──────────────────┘                            │
+│                     │                                                 │
+│                     ▼                                                 │
+│              ┌──────────────┐                                        │
+│              │   SMTP       │                                        │
+│              │   Server     │                                        │
+│              └──────────────┘                                        │
+│                                                                      │
+└─────────────────────────────────────────────────────────────────────┘
+```
+
+## EmailService
+
+### Send HTML Email
+
+```typescript
+async sendEmail(options: {
+  to: string | string[];
+  subject: string;
+  html: string;
+  from?: string;
+  replyTo?: string;
+  cc?: string | string[];
+  bcc?: string | string[];
+  attachments?: Attachment[];
+}): Promise<SentMessageInfo>
+```
+
+### Send with Template
+
+```typescript
+import { MailerService } from "@nestjs-modules/mailer";
+import { context } from "@handlebars/noder";
+
+@Injectable()
+export class NotificationService {
+  constructor(
+    private readonly emailService: EmailService,
+    private readonly mailerService: MailerService,
+  ) {}
+
+  async sendWelcomeWithTemplate(user: User) {
+    await this.mailerService.sendMail({
+      to: user.email,
+      subject: "Welcome!",
+      template: "welcome", // Looks for templates/welcome.hbs
+      context: {
+        name: user.name,
+        verifyUrl: `https://example.com/verify/${user.token}`,
+      },
+    });
   }
 }
 ```
 
-### Handlebars Templates
+### Verify Connection
+
+```typescript
+async testConnection() {
+  const isConnected = await this.emailService.verify();
+  if (!isConnected) {
+    throw new Error('Email service not available');
+  }
+}
+```
+
+## Handlebars Templates
+
+### Template Location
+
+Templates should be placed in `process.cwd() + '/templates/'`:
+
+```
+project/
+├── templates/
+│   ├── welcome.hbs
+│   ├── reset-password.hbs
+│   └── invoice.hbs
+├── src/
+│   └── app.module.ts
+└── package.json
+```
+
+### Template Example
 
-The module uses `@nestjs-modules/mailer` with a Handlebars adapter. Place templates in `process.cwd() + '/templates/'` and use the MailerService directly for template-based emails (inject `MailerService` from `@nestjs-modules/mailer`).
+```handlebars
+{{! templates/welcome.hbs }}
+
+<html>
+  <head>
+    <meta charset="utf-8" />
+    <title>Welcome</title>
+    <style>
+      body {
+        font-family: Arial, sans-serif;
+      }
+      .container {
+        max-width: 600px;
+        margin: 0 auto;
+      }
+    </style>
+  </head>
+  <body>
+    <div class="container">
+      <h1>Welcome, {{name}}!</h1>
+      <p>Thank you for joining {{appName}}.</p>
+      <a href="{{verifyUrl}}">Verify your email</a>
+      <p>Best,<br />The Team</p>
+    </div>
+  </body>
+</html>
+```
+
+### Template Features
+
+```handlebars
+{{! Conditionals }}
+{{#if user.isPremium}}
+  <p>You have premium access!</p>
+{{else}}
+  <p>Upgrade to premium for more features.</p>
+{{/if}}
+
+{{! Loops }}
+{{#each items}}
+  <li>{{ this.name }} - {{ this.price }}</li>
+{{/each}}
+
+{{! Partials }}
+{{> header }}
+{{> footer }}
+
+{{! Helpers }}
+{{formatDate date 'MMMM Do YYYY'}}
+{{currency amount}}
+{{uppercase name}}
+```
+
+## EmailConfig
+
+### Default Configuration
+
+```typescript
+{
+  transport: {
+    host: process.env.EMAIL_SMTP,
+    port: parseInt(process.env.EMAIL_SMTP_PORT, 10),
+    secure: false, // true for 465, false for other ports
+    auth: {
+      user: process.env.EMAIL_SMTP_USERNAME,
+      pass: process.env.EMAIL_SMTP_PASSWORD,
+    },
+  },
+  defaults: {
+    from: process.env.EMAIL_SMTP_DISPLAY_NAME || 'noreply@example.com',
+  },
+  template: {
+    dir: process.cwd() + '/templates/',
+    adapter: new HandlebarsAdapter(),
+    options: {
+      strict: true,
+    },
+  },
+}
+```
 
-### Verifying Connection
+### Custom Configuration
 
 ```typescript
-await this.emailService.verify();
+import { Module } from "@nestjs/common";
+import { EmailModule, EmailConfig } from "@zola_do/email";
+
+@Module({
+  imports: [
+    EmailModule.forRoot({
+      transport: {
+        host: "smtp.gmail.com",
+        port: 465,
+        secure: true,
+        auth: {
+          user: "your-email@gmail.com",
+          pass: "your-app-password",
+        },
+      },
+      defaults: {
+        from: '"My App" <noreply@myapp.com>',
+      },
+      template: {
+        dir: __dirname + "/templates",
+        adapter: new HandlebarsAdapter(),
+      },
+    } as EmailConfig),
+  ],
+})
+export class AppModule {}
 ```
 
 ## Environment Variables
 
-| Variable | Description |
-|----------|-------------|
-| `EMAIL_SMTP` | SMTP host |
-| `EMAIL_SMTP_PORT` | SMTP port |
-| `EMAIL_SMTP_USERNAME` | SMTP username |
-| `EMAIL_SMTP_PASSWORD` | SMTP password |
-| `EMAIL_SMTP_DISPLAY_NAME` | From display name (defaults) |
+| Variable                  | Description       | Default               |
+| ------------------------- | ----------------- | --------------------- |
+| `EMAIL_SMTP`              | SMTP host         | Required              |
+| `EMAIL_SMTP_PORT`         | SMTP port         | `587`                 |
+| `EMAIL_SMTP_USERNAME`     | SMTP username     | Required              |
+| `EMAIL_SMTP_PASSWORD`     | SMTP password     | Required              |
+| `EMAIL_SMTP_DISPLAY_NAME` | Default from name | `noreply@example.com` |
+
+## SMTP Ports
+
+| Port   | Use         | Secure   |
+| ------ | ----------- | -------- |
+| `25`   | Legacy      | No       |
+| `465`  | SMTPS       | Yes      |
+| `587`  | Submission  | No (TLS) |
+| `2525` | Alternative | No       |
+
+## Common Email Patterns
+
+### Welcome Email
+
+```typescript
+async sendWelcomeEmail(user: User) {
+  await this.mailerService.sendMail({
+    to: user.email,
+    subject: 'Welcome to Our Platform!',
+    template: 'welcome',
+    context: {
+      name: user.firstName,
+      verifyUrl: `${BASE_URL}/verify/${user.verificationToken}`,
+    },
+  });
+}
+```
+
+### Password Reset
+
+```typescript
+async sendPasswordReset(user: User) {
+  await this.mailerService.sendMail({
+    to: user.email,
+    subject: 'Password Reset Request',
+    template: 'reset-password',
+    context: {
+      name: user.name,
+      resetUrl: `${BASE_URL}/reset-password/${user.resetToken}`,
+      expiresIn: '1 hour',
+    },
+  });
+}
+```
+
+### Invoice Email
+
+```typescript
+async sendInvoice(user: User, invoice: Invoice) {
+  await this.mailerService.sendMail({
+    to: user.email,
+    subject: `Invoice #${invoice.number}`,
+    template: 'invoice',
+    context: {
+      invoiceNumber: invoice.number,
+      amount: invoice.amount,
+      dueDate: invoice.dueDate,
+      items: invoice.items,
+      total: invoice.total,
+    },
+    attachments: [
+      {
+        filename: `invoice-${invoice.number}.pdf`,
+        path: invoice.pdfPath,
+      },
+    ],
+  });
+}
+```
+
+## API Reference
+
+### EmailModule
+
+```typescript
+// Default configuration from environment
+EmailModule.forRoot()
+
+// Custom configuration
+EmailModule.forRoot(config: EmailConfig)
+```
+
+### EmailService
+
+```typescript
+class EmailService {
+  constructor(private readonly mailerService: MailerService) {}
+
+  async sendEmail(options: SendEmailOptions): Promise<SentMessageInfo>;
+  async verify(): Promise<boolean>;
+}
+```
+
+### SendEmailOptions
+
+```typescript
+interface SendEmailOptions {
+  to: string | string[];
+  subject: string;
+  html?: string;
+  text?: string;
+  from?: string;
+  replyTo?: string;
+  cc?: string | string[];
+  bcc?: string | string[];
+  attachments?: Attachment[];
+}
+```
+
+## Troubleshooting
+
+### Q: Emails not sending?
+
+1. Check SMTP credentials in environment
+2. Verify SMTP server is accessible
+3. Test connection: `await emailService.verify()`
+
+### Q: Templates not found?
+
+Ensure templates are in `process.cwd() + '/templates/'`:
+
+```typescript
+// Check template path
+console.log(process.cwd() + "/templates/");
+```
+
+### Q: Handlebars syntax errors?
+
+Enable strict mode to see detailed errors:
+
+```typescript
+template: {
+  options: { strict: true },
+}
+```
+
+### Q: Gmail authentication fails?
+
+If using Gmail with 2FA, create an App Password:
+
+1. Google Account → Security
+2. 2-Step Verification → App Passwords
+3. Generate new app password for your app
+
+## Related Packages
+
+None - standalone email package
 
-## Exports
+## License
 
-- `EmailModule` — Register the email module
-- `EmailService` — Send emails and verify connection
-- `EmailConfig` — Mailer configuration factory
+ISC
 
 ## Community
 

package/dist/email-transport.interface.d.ts

@@ -0,0 +1,10 @@
+export interface ZolaEmailMessage {
+    to: string | string[];
+    subject: string;
+    html?: string;
+    text?: string;
+    from?: string;
+}
+export interface ZolaEmailTransport {
+    send(mail: ZolaEmailMessage): Promise<unknown>;
+}

package/dist/email-transport.interface.js

@@ -0,0 +1,3 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+//# sourceMappingURL=email-transport.interface.js.map

package/dist/email-transport.interface.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"email-transport.interface.js","sourceRoot":"","sources":["../src/email-transport.interface.ts"],"names":[],"mappings":""}

package/dist/index.d.ts

@@ -1,3 +1,4 @@
 export * from './email.config';
 export * from './email.service';
 export * from './email.module';
+export * from './email-transport.interface';

package/dist/index.js

@@ -17,4 +17,5 @@ Object.defineProperty(exports, "__esModule", { value: true });
 __exportStar(require("./email.config"), exports);
 __exportStar(require("./email.service"), exports);
 __exportStar(require("./email.module"), exports);
+__exportStar(require("./email-transport.interface"), exports);
 //# sourceMappingURL=index.js.map

package/dist/index.js.map

@@ -1 +1 @@
-{"version":3,"file":"index.js","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":";;;;;;;;;;;;;;;;AAAA,iDAA+B;AAC/B,kDAAgC;AAChC,iDAA+B"}
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":";;;;;;;;;;;;;;;;AAAA,iDAA+B;AAC/B,kDAAgC;AAChC,iDAA+B;AAC/B,8DAA4C"}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@zola_do/email",
-  "version": "0.2.4",
+  "version": "0.2.6",
   "description": "Email service for NestJS",
   "author": "zolaDO",
   "license": "ISC",