┌─────────────────────────────────────────────┐
│  Application Code                           │
│  import { getEmailDriver }                  │
│    from '@toast/drivers'                    │
└──────────────┬──────────────────────────────┘
               │
               ▼
┌──────────────────────────────────────────────┐
│  @toast/drivers (packages/drivers)           │
│  ┌────────────┐  ┌────────────────────────┐  │
│  │ Interfaces │  │ Loaders                │  │
│  │ EmailDriver│  │ getEmailDriver()       │  │
│  │ Storage    │  │ getStorageDriver()     │  │
│  │ Driver     │  │                        │  │
│  └────────────┘  └───────────┬────────────┘  │
│                              │               │
│  ┌────────────────┐          │               │
│  │ ConsoleEmail   │◄─────────┤ (built-in)    │
│  │ Driver         │          │               │
│  └────────────────┘          │               │
└──────────────────────────────┼───────────────┘
                               │ (dynamic import)
               ┌───────────────┴─────────────┐
               ▼                             ▼
┌──────────────────────┐  ┌──────────────────────┐
│ toast-driver-email-  │  │ toast-driver-storage- │
│ mailgun              │  │ s3                    │
│ (drivers/email-      │  │ (drivers/storage-s3)  │
│  mailgun)            │  │                       │
└──────────────────────┘  └──────────────────────┘

import { createRequire } from 'node:module';

const appRequire = createRequire(`${process.cwd()}/package.json`);
const driverPath = appRequire.resolve(driverName);
const module = await import(driverPath);
return module.default; // Driver class

interface EmailDriver {
  readonly name: string;
  send(message: EmailMessage): Promise<SendResult>;
}

interface EmailMessage {
  to: string;
  from?: string;
  subject: string;
  html: string;
  text?: string;
}

interface SendResult {
  success: boolean;
  messageId?: string;
  error?: string;
}

import { getEmailDriver, ConsoleEmailDriver } from '@toast/drivers';

// Automatic in development
const driver = await getEmailDriver();
await driver.send({
  to: 'user@example.com',
  subject: 'Magic Link',
  html: '<a href="...">Sign in</a>',
});

// In tests: verify emails were sent
const console = driver as ConsoleEmailDriver;
const sent = console.getSentEmails();
expect(sent[0].message.to).toBe('user@example.com');
console.clearSent(); // Clean up between tests

============================================================
EMAIL SENT (console driver)
============================================================
Message ID: console-1708000000000-1
To:         user@example.com
Subject:    Magic Link
------------------------------------------------------------
HTML:
<a href="...">Sign in</a>
============================================================

pnpm add toast-driver-email-mailgun

// Just set environment variables — the driver loads automatically
const driver = await getEmailDriver();
const result = await driver.send({
  to: 'user@example.com',
  subject: 'Welcome',
  html: '<p>Hello!</p>',
});

if (!result.success) {
  console.error('Email failed:', result.error);
}

# Error: EMAIL_DRIVER must be configured in production
EMAIL_DRIVER=toast-driver-email-mailgun

# Install in the app that calls getEmailDriver()
cd apps/api
pnpm add toast-driver-email-mailgun

interface StorageDriver {
  readonly name: string;
  upload(input: UploadInput): Promise<UploadResult>;
  delete(key: string): Promise<void>;
  exists(key: string): Promise<boolean>;
}

interface UploadInput {
  data: Buffer | Readable;
  key: string; // e.g., "site-id/images/abc123.jpg"
  contentType: string; // e.g., "image/jpeg"
}

interface UploadResult {
  key: string;
  url: string; // Public URL
  size: number; // Bytes
}

pnpm add toast-driver-storage-s3

import { getStorageDriver } from '@toast/drivers';

const driver = await getStorageDriver();
if (driver) {
  // Upload
  const result = await driver.upload({
    data: fileBuffer,
    key: `${siteId}/images/${nanoid()}.jpg`,
    contentType: 'image/jpeg',
  });
  console.log('Public URL:', result.url);

  // Check existence
  const exists = await driver.exists('site-id/images/abc123.jpg');

  // Delete
  await driver.delete('site-id/images/abc123.jpg');
}

# MinIO (local development)
S3_ENDPOINT=http://localhost:9000
S3_ACCESS_KEY_ID=minioadmin
S3_SECRET_ACCESS_KEY=minioadmin
S3_BUCKET=toast-uploads
S3_PUBLIC_URL=http://localhost:9000/toast-uploads

# Cloudflare R2
S3_ENDPOINT=https://<account-id>.r2.cloudflarestorage.com
S3_ACCESS_KEY_ID=<r2-access-key>
S3_SECRET_ACCESS_KEY=<r2-secret-key>
S3_BUCKET=toast-uploads
S3_REGION=auto
S3_PUBLIC_URL=https://cdn.example.com

# AWS S3
S3_ENDPOINT=https://s3.us-east-1.amazonaws.com
S3_ACCESS_KEY_ID=<aws-access-key>
S3_SECRET_ACCESS_KEY=<aws-secret-key>
S3_BUCKET=toast-uploads
S3_REGION=us-east-1
S3_PUBLIC_URL=https://toast-uploads.s3.us-east-1.amazonaws.com

mkdir drivers/email-resend
cd drivers/email-resend
pnpm init

// src/resend.driver.ts
import type { EmailDriver, EmailMessage, SendResult } from '@toast/drivers';

export default class ResendEmailDriver implements EmailDriver {
  readonly name = 'resend';

  private readonly apiKey: string;

  constructor() {
    const apiKey = process.env['RESEND_API_KEY'];
    if (!apiKey) {
      throw new Error('RESEND_API_KEY is required');
    }
    this.apiKey = apiKey;
  }

  async send(message: EmailMessage): Promise<SendResult> {
    try {
      const response = await fetch('https://api.resend.com/emails', {
        method: 'POST',
        headers: {
          Authorization: `Bearer ${this.apiKey}`,
          'Content-Type': 'application/json',
        },
        body: JSON.stringify({
          from: message.from ?? 'noreply@example.com',
          to: message.to,
          subject: message.subject,
          html: message.html,
          text: message.text,
        }),
      });

      if (!response.ok) {
        const error = await response.text();
        return {
          success: false,
          error: `Resend API error: ${error}`,
        };
      }

      const data = (await response.json()) as { id: string };
      return { success: true, messageId: data.id };
    } catch (error) {
      return {
        success: false,
        error: error instanceof Error ? error.message : String(error),
      };
    }
  }
}

// src/index.ts
export { default } from './resend.driver.js';

EMAIL_DRIVER=toast-driver-email-resend
RESEND_API_KEY=re_xxxxx