waitlist-mailer/CUSTOMIZATION.md

Modern, modular TypeScript library for managing waitlists with pluggable storage and mail providers. Supports MongoDB, SQL databases, and custom adapters with zero required dependencies for basic usage.

# WaitlistMailer - Customization Guide

Learn how to customize emails, create custom adapters, and extend WaitlistMailer for your needs.

## Table of Contents

- [Email Customization](#email-customization)
  
- [Custom Storage Adapters](#custom-storage-adapters)
  
- [Custom Mail Providers](#custom-mail-providers)
  
- [TypeScript Generics](#typescript-generics)
  

## Email Customization

### Option 1: Simple HTML String

Pass custom HTML directly when joining a user to the waitlist:

```
await manager.join('user@example.com', {
  name: 'Alice',
  customHtml: `
    <h1>Welcome Alice!</h1>
    <p>Thanks for joining our waitlist.</p>
    <a href="[https://app.example.com/confirm](https://app.example.com/confirm)">Confirm Email</a>
  `
});
```

### Option 2: Handlebars Templates

For more complex emails, use a template engine like **Handlebars**:

**1. Install Handlebars:**

```
npm install handlebars
```

**2. Create a template file (`templates/welcome.hbs`):**

```
<h1>Welcome {{name}}!</h1>
<p>Thanks for joining {{company}} waitlist.</p>
```

**3. Load and compile the template:**

```
import Handlebars from 'handlebars';
import fs from 'fs/promises';

const source = await fs.readFile('./templates/welcome.hbs', 'utf-8');
const template = Handlebars.compile(source);

const html = template({
  name: 'Alice',
  company: 'My Startup'
});

await manager.join('alice@example.com', {
  customHtml: html,
  subject: 'Welcome to the club!'
});
```

## Custom Storage Adapters

Implement `StorageProvider` interface to create your own storage adapter (e.g., Redis, Firebase).

```
import { StorageProvider, WaitlistEntry } from 'waitlist-mailer';

class MyCustomStorage implements StorageProvider<any> {
  async add(email: string, data?: any): Promise<void> {
    // Your implementation
  }

  // ... implement other methods
}

const manager = new WaitlistManager({
  storage: new MyCustomStorage(),
  companyName: 'My App'
});
```

## Custom Mail Providers

Implement `MailProvider` interface to create your own mail provider (e.g., SendGrid API, Mailgun).

```
import { MailProvider, EmailContext } from 'waitlist-mailer';

class MyMailProvider implements MailProvider {
  async sendConfirmation(email: string, context: EmailContext): Promise<boolean> {
    // Call your email API here
    return true;
  }
}

const manager = new WaitlistManager({
  mailer: new MyMailProvider(),
  companyName: 'My App'
});
```

## TypeScript Generics

Use TypeScript generics to enforce type-safe custom metadata throughout your application.

```
interface UserMetadata {
  name: string;
  source: 'twitter' | 'productHunt';
  plan: 'free' | 'pro';
}

const manager = new WaitlistManager<UserMetadata>({
  companyName: 'My App'
});

// Type-safe join
await manager.join('user@example.com', {
  name: 'Alice',
  source: 'twitter',
  plan: 'pro'
});
```