ch‑emailer

Reusable Node.js/TypeScript package for sending SMTP emails with attachments, download links, HTML bodies, and OAuth2 support.

Features

• ⚙️ Config‑driven: All settings via a simple ConfigProperties map (no .env required)
• 📧 SMTP: Standard SMTP with optional SSL or STARTTLS
• 🔒 Auth: Plain username/password or OAuth2 flows (Gmail, Office 365, etc.)
• 📎 Attachments: Automatic size‑check (skip >10 MB) and path‑ or buffer‑based attachments
• 🔗 Links: Append named URLs to both text and HTML bodies
• 🔄 Extensible: Swap in HTTP‑API providers (SendGrid, Mailgun) by implementing the same EmailService interface

Install

npm install ch-emailer
# or scoped version if published:
npm install @chtsinc/ch-emailer

## Usage

import { SMTPEmailService } from 'ch-emailer';
import type { ConfigProperties, EmailOptions } from 'ch-emailer/types';

// 1) Build your config map (e.g., from your app settings)
const config: ConfigProperties = {
  MAIL_SMTP_AUTH_ENABLE:     'true',
  MAIL_SMTP_SSL_ENABLE:      'false',
  MAIL_SMTP_STARTTLS_ENABLE: 'true',
  SESSION_DEBUG_ENABLE:      'false',

  MAIL_SMTP_HOST:            'smtp.example.com',
  MAIL_SMTP_PORT:            '587',
  FROM_ADDRESS:              '[email protected]',
  TO_RECIPIENTS:             '[email protected]',

  USER:                      'your_smtp_username',
  PASSWORD:                  'your_smtp_password'
};

// 2) Instantiate the service
const emailer = new SMTPEmailService(config);

// 3) Prepare your email options
const options: EmailOptions = {
  subject: 'Test Email',
  body: 'Hello there!',
  htmlBody: '<p>Hello <strong>there</strong>!</p>',
  attachments: [
    { filename: 'report.pdf', path: './reports/summary.pdf' }
  ],
  links: [
    { name: 'Dashboard', url: 'https://example.com/dashboard' }
  ]
};

// 4) Send!
emailer.sendEmail(options)
  .then(info => console.log('Message sent, id:', info.messageId))
  .catch(err => console.error('Error sending email:', err));
Configuration Properties

Key	Description
MAIL_SMTP_HOST	SMTP server hostname
MAIL_SMTP_PORT	SMTP port (e.g. "587")
MAIL_SMTP_AUTH_ENABLE	"true" to enable auth
MAIL_SMTP_SSL_ENABLE	"true" for SSL (port 465)
MAIL_SMTP_STARTTLS_ENABLE	"true" for STARTTLS (port 587)
SESSION_DEBUG_ENABLE	"true" to enable transporter debug
FROM_ADDRESS	Default “from” address
TO_RECIPIENTS	Default “to” recipient(s)
USER	SMTP username (if auth)
PASSWORD	SMTP password (if auth)
CLIENT_ID, CLIENT_SECRET,
REFRESH_TOKEN, ACCESS_TOKEN	OAuth2 credentials (optional)

## Advanced: OAuth2
If you need OAuth2 (Gmail, Office 365), include:

const config: ConfigProperties = {
  // ...standard keys...
  CLIENT_ID:     'your_client_id',
  CLIENT_SECRET: 'your_client_secret',
  REFRESH_TOKEN: 'your_refresh_token',
  ACCESS_TOKEN:  'optional_initial_access_token',
  USER:          '[email protected]'
};
The library will detect these and configure Nodemailer’s OAuth2 transport automatically.

# Extending to HTTP‑API Providers

Implement the same EmailService interface for services like SendGrid:
import sgMail from '@sendgrid/mail';
import type { EmailService, EmailOptions } from 'ch-emailer/types';

export class SendGridEmailService implements EmailService {
  constructor(apiKey: string) {
    sgMail.setApiKey(apiKey);
  }

  async sendEmail(opts: EmailOptions) {
    // map opts → sgMail.send parameters
    return sgMail.send({ /* ... */ });
  }
}