npm package: @srttk/email
Description: Maintainable email & templates
Author: Sarath TK
Latest version: 1.0.1

# @srttk/email 📬

A type-safe email templating and sending solution for Node.js applications. This package helps you manage email templates and send emails with proper TypeScript support.

## Features

- 🔒 Type-safe email templates
- 📝 Support for HTML and plain text emails
- 🎨 Template compilation with data binding
- ⚡ Built-in HTML to text conversion
- 🛠️ Customizable template engine settings

## Installation

```bash
npm install @srttk/email nodemailer
```

## Quick Start

### 1. Define Email Templates

Create type-safe email templates with full TypeScript support:

```typescript
import { IEmailTemplateRecord } from "@srttk/email";

// Define a template with typed data requirements
const welcome: IEmailTemplateRecord<{ name: string }> = {
  subject: "Welcome to Our Platform",
  body: (data) => `
    <div>
      <h1>Welcome ${data.name}!</h1>
      <p>We're excited to have you on board.</p>
    </div>
  `,
};

// Create a template collection
const templates = new EmailTemplateCollection({ welcome });
```

### 2. Set Up the Mailer

Configure your email transport settings:

```typescript
import { Mailer } from "@srttk/email";

const mailer = new Mailer({
  templates: templates,
  config: {
    frommail: "noreply@yourcompany.com",
    fromname: "Your Company",
    host: "smtp.yourprovider.com",
    port: 587,
    username: "your-username",
    password: "your-password",
  },
});
```

### 3. Send Emails

Send emails using your templates:

```typescript
// Using templates
await mailer
  .useTemplate("welcome", { name: "John Doe" })
  .send({ to: "john@example.com" });

// Or create without sending
const emailData = mailer
  .useTemplate("welcome", { name: "John Doe" })
  .create({ to: "john@example.com" });
```

## Advanced Usage

### Custom Template Files

You can use external template files:

```typescript
const passwordReset: IEmailTemplateRecord<{ resetLink: string }> = {
  subject: "Password Reset Request",
  body: { path: "./templates/password-reset.html" },
};
```

### Template Collection Options

Configure template collection settings:

```typescript
const templates = new EmailTemplateCollection(
  { welcome },
  {
    templatePath: "./email-templates",
    defaultExtension: ".html",
    htmlToText: customHtmlToTextParser, // Optional custom parser
  }
);
```

### Custom Transport

Use a custom nodemailer transport:

```typescript
const customTransport = createTransport({
  // Your custom transport configuration
});

mailer.setTransport(customTransport);
```

### Test Connection

Verify your email configuration:

```typescript
const isConnected = await mailer.testConnection();
if (isConnected) {
  console.log("Email service is ready!");
}
```

## API Reference

### `EmailTemplateCollection`

- `constructor(templates, options?)`: Create a new template collection
- `compile(name, data?)`: Compile a template with data
- `setHtmlToText(parser)`: Set custom HTML to text parser

### `Mailer`

- `constructor(settings?)`: Create a new mailer instance
- `setup(config)`: Configure SMTP settings
- `testConnection()`: Test SMTP connection
- `send(options)`: Send an email
- `useTemplate(name, data?)`: Use a template for sending
- `setTransport(transport)`: Set custom nodemailer transport

## Type Definitions

```typescript
interface IEmailTemplateRecord<T = any> {
  subject: string | ((data: T) => string);
  body: string | ((data: T) => string) | { path: string };
}

interface SetupOptions {
  host: string;
  port: string | number;
  secure?: boolean;
  username: string;
  password: string;
  fromname?: string;
  frommail?: string;
}
```

## License

MIT

## Contributing

Contributions are welcome! Please feel free to submit a Pull Request.