@maestro-js/mail 1.0.0-alpha.0

package/README.md

@@ -0,0 +1,360 @@
+# @maestro-js/mail
+
+Driver-based email sending with queued delivery, scheduled sending, and reusable mailable templates. Follows the Maestro Provider pattern with pluggable drivers (SendGrid, SES, MailTrap, Stub).
+
+## Quick Setup
+
+```ts
+import { Mail } from '@maestro-js/mail'
+import { Queue } from '@maestro-js/queue'
+import { Log } from '@maestro-js/log'
+
+// Create a logger for mail records
+const mailLogger = Log.createLogger<[Mail.LogMessage]>({ transports: [Log.transports.console()] })
+
+// Create and register the mail service
+const mailService = Mail.Provider.create({
+  driver: Mail.drivers.sendGrid(sendGridClient),
+  name: 'default',
+  globalFrom: { email: 'noreply@example.com', name: 'MyApp' },
+  logger: mailLogger,
+  queueService: Queue.provider('default')
+})
+Mail.Provider.register('default', mailService)
+```
+
+## Drivers
+
+### SendGrid
+
+```ts
+import sgMail from '@sendgrid/mail'
+sgMail.setApiKey(process.env.SENDGRID_API_KEY)
+const driver = Mail.drivers.sendGrid(sgMail)
+```
+
+The SendGrid driver accepts the `@sendgrid/mail` client. It passes `envelope.extras` as `customArgs` and supports webhook event normalization via `driver.toMailEvent(sgEvent)`.
+
+### SES
+
+```ts
+import { SESv2Client, SendRawEmailCommand } from '@aws-sdk/client-sesv2'
+const sesClient = new SESv2Client({ region: 'us-east-1' })
+const driver = Mail.drivers.ses(sesClient, 'my-configuration-set')
+```
+
+The SES driver requires a client adapter with a `send()` method and a configuration set name. It uses `nodemailer/MailComposer` to build raw MIME messages, sends per-recipient with retry (5 attempts, 3s delay), and passes `envelope.extras` as SES message tags. Supports webhook event normalization via `driver.toMailEvent(sesEvent)`.
+
+### MailTrap
+
+```ts
+import { MailtrapClient } from 'mailtrap'
+const mailtrapClient = new MailtrapClient({ token: process.env.MAILTRAP_TOKEN })
+const driver = Mail.drivers.mailTrap(mailtrapClient)
+```
+
+The MailTrap driver retries up to 10 attempts with 10s delay. It passes `envelope.extras` as `custom_variables`. Supports webhook event normalization via `driver.toMailEvent(mtEvent)`.
+
+### Stub
+
+```ts
+const driver = Mail.drivers.stub()
+// Or with logging:
+const driver = Mail.drivers.stub({ logger: myLogger })
+```
+
+The Stub driver returns success with random UUIDs as message IDs. Use for testing and development. Optionally accepts a logger to record sent envelopes.
+
+## API Reference
+
+### Mail.Provider.create(config)
+
+Create a mail service instance. Config fields:
+
+| Field | Type | Description |
+|---|---|---|
+| `driver` | `Mail.Driver` | The mail driver instance |
+| `name` | `string` | Instance name, used for queue naming (`Maestro.Mail.{name}`) |
+| `globalFrom` | `Mail.Address` | Default sender, overridden by `envelope.from` |
+| `logger` | `Log.Logger<[Mail.LogMessage]>` | Logger for envelope and event records |
+| `queueService` | `Queue.QueueService` | Queue service for async delivery |
+| `onMessageSendFailure?` | `(envelope, error) => unknown` | Optional callback on send failure |
+
+### Mail.Provider.register(name, service)
+
+Register a service instance in the named registry.
+
+### Mail.send(envelope)
+
+Send an email immediately. Returns `{ success: boolean, messages: { id: string, email: string }[] }`. Addresses are trimmed, lowercased, and deduplicated automatically.
+
+```ts
+await Mail.send({
+  to: 'alice@example.com',
+  subject: 'Order Confirmed',
+  content: { html: '<h1>Thank you!</h1>' }
+})
+```
+
+### Mail.queue(envelope)
+
+Enqueue an email for immediate async processing by the queue worker. Does not block the current request.
+
+```ts
+Mail.queue({
+  to: 'bob@example.com',
+  subject: 'Password Reset',
+  content: { html: '<p>Click the link to reset your password.</p>' }
+})
+```
+
+### Mail.later(envelope, scheduledDate)
+
+Enqueue an email for delivery at a future date. The `scheduledDate` is an `Iso.Instant`.
+
+```ts
+Mail.later(
+  { to: 'user@example.com', subject: 'Reminder', content: { text: 'Your trial ends tomorrow.' } },
+  '2025-01-15T09:00:00Z' as Iso.Instant
+)
+```
+
+### Mail.provider(key)
+
+Resolve a named mail service instance. Returns `{ send, queue, later }`.
+
+```ts
+const transactional = Mail.provider('transactional')
+await transactional.send({ to: '...', subject: '...', content: { html: '...' } })
+```
+
+### Mail.mailable(name, renderFn)
+
+Register a reusable mailable template. The render function receives args and returns an `Envelope` or `Mail.EMPTY_ENVELOPE` to skip sending.
+
+```ts
+const OrderConfirmation = Mail.mailable('OrderConfirmation', async (args: { orderId: string }) => {
+  const order = await db.query('SELECT * FROM orders WHERE id = ?', [args.orderId])
+  return {
+    to: order.email,
+    subject: `Order #${order.id} Confirmed`,
+    content: { html: `<h1>Thank you, ${order.name}!</h1>` }
+  }
+})
+```
+
+#### Rendered Mailable Methods
+
+After calling `.render(args)`, the returned object provides:
+
+- **`send()`** -- Send immediately
+- **`queue()`** -- Enqueue for async processing
+- **`later(scheduledDate)`** -- Schedule for future delivery
+- **`content()`** -- Retrieve the generated content without sending
+- **`provider(key)`** -- Target a specific named mail service
+
+```ts
+// Send immediately
+await OrderConfirmation.render({ orderId: '1042' }).send()
+
+// Queue for async processing
+await OrderConfirmation.render({ orderId: '1042' }).queue()
+
+// Schedule for later
+await OrderConfirmation.render({ orderId: '1042' }).later('2025-06-01T12:00:00Z' as Iso.Instant)
+
+// Get content without sending
+const content = await OrderConfirmation.render({ orderId: '1042' }).content()
+
+// Use a specific provider
+await OrderConfirmation.render({ orderId: '1042' }).provider('transactional').send()
+```
+
+### Mail.EMPTY_ENVELOPE
+
+Return from a mailable render function to skip sending. Useful for conditional emails.
+
+```ts
+const WeeklyDigest = Mail.mailable('WeeklyDigest', async (args: { userId: string }) => {
+  const updates = await getUpdates(args.userId)
+  if (updates.length === 0) return Mail.EMPTY_ENVELOPE
+  return { to: '...', subject: 'Weekly Digest', content: { html: '...' } }
+})
+```
+
+### Mail.attachments.ics(options)
+
+Generate an ICS calendar attachment from structured options.
+
+```ts
+const attachment = Mail.attachments.ics({
+  title: 'Team Standup',
+  start: '2025-03-01T10:00:00Z' as Iso.Instant,
+  end: 'PT1H' as Iso.Duration, // 1-hour duration
+  location: 'Conference Room A',
+  organizer: { name: 'Alice', email: 'alice@example.com' },
+  attendees: [{ name: 'Bob', email: 'bob@example.com', rsvp: true }],
+  status: 'CONFIRMED',
+  alarms: [{ action: 'display', description: 'Standup in 15 min', trigger: '-PT15M' as Iso.Duration }]
+})
+
+await Mail.send({
+  to: 'bob@example.com',
+  subject: 'Team Standup Invite',
+  content: { html: '<p>You are invited to standup.</p>' },
+  attachments: [attachment]
+})
+```
+
+ICS options support `start` and `end` as `Iso.Instant`, `Iso.ZonedDateTime`, or `Iso.DateTime`. The `end` field also accepts `Iso.Duration`. Additional fields: `description`, `geo`, `url`, `busyStatus`, `categories`, `uid`, `method`, `recurrenceRule`, `sequence`, `calName`, `classification`, `created`, `lastModified`, `htmlContent`, `alarms`.
+
+## Envelope Type
+
+```ts
+interface Envelope {
+  to: Mail.Address | Mail.Address[]
+  from?: Mail.Address              // overrides globalFrom
+  cc?: Mail.Address | Mail.Address[]
+  bcc?: Mail.Address | Mail.Address[]
+  attachments?: Mail.Attachment[]
+  subject: string | null
+  content: { text: string } | { html: string }
+  headers?: {
+    listUnsubscribe?: string
+    listUnsubscribePost?: string
+    replyTo?: Mail.Address
+  }
+  category?: string | null
+  extras?: Record<string, string | null>
+}
+```
+
+The `Mail.Address` type is either a plain email string or `{ email: string, name?: string }`.
+
+## Common Patterns
+
+### Sending with Attachments
+
+```ts
+await Mail.send({
+  to: 'user@example.com',
+  subject: 'Your Invoice',
+  content: { html: '<p>Please find your invoice attached.</p>' },
+  attachments: [{
+    content: Buffer.from(pdfData).toString('base64'),
+    filename: 'invoice.pdf',
+    type: 'application/pdf',
+    disposition: 'attachment'
+  }]
+})
+```
+
+### Unsubscribe Headers
+
+```ts
+await Mail.send({
+  to: 'subscriber@example.com',
+  subject: 'Newsletter',
+  content: { html: '...' },
+  headers: {
+    listUnsubscribe: '<https://example.com/unsubscribe?id=123>',
+    listUnsubscribePost: 'List-Unsubscribe=One-Click'
+  },
+  category: 'newsletter'
+})
+```
+
+### Processing Webhook Events
+
+SendGrid, SES, and MailTrap drivers expose `toMailEvent()` to normalize provider-specific webhook payloads into a unified `Mail.Event` type.
+
+```ts
+// SendGrid webhook handler
+const sgDriver = Mail.drivers.sendGrid(sgMail) as SendGridMailDriver
+const event = sgDriver.toMailEvent(rawSendGridEvent) // returns MailEvent | null
+
+// SES webhook handler
+const sesDriver = Mail.drivers.ses(sesClient, 'config-set') as SesMailDriver
+const event = sesDriver.toMailEvent(rawSesEvent) // returns MailEvent | null
+
+// MailTrap webhook handler
+const mtDriver = Mail.drivers.mailTrap(mtClient) as MailTrapMailDriver
+const event = mtDriver.toMailEvent(rawMailTrapEvent) // returns MailEvent
+```
+
+The normalized `Mail.Event` includes: `eventId`, `event` (delivery, bounce, softBounce, open, click, unsubscribe, spamComplaint, reject, suspension), `email`, `messageId`, `timestamp`, `category`, `extras`, `driverName`.
+
+### Conditional Mailable with EMPTY_ENVELOPE
+
+```ts
+const InactivityReminder = Mail.mailable('InactivityReminder', async (args: { userId: string }) => {
+  const user = await getUser(args.userId)
+  if (user.lastActiveAt > thirtyDaysAgo) return Mail.EMPTY_ENVELOPE
+  return {
+    to: user.email,
+    subject: 'We miss you!',
+    content: { html: `<p>Hi ${user.name}, it has been a while...</p>` }
+  }
+})
+```
+
+### Error Handling with onMessageSendFailure
+
+```ts
+Mail.Provider.create({
+  driver: Mail.drivers.sendGrid(sgMail),
+  name: 'default',
+  globalFrom: { email: 'noreply@example.com' },
+  logger: mailLogger,
+  queueService: Queue.provider('default'),
+  onMessageSendFailure(envelope, error) {
+    Log.error({ message: 'Mail send failed', to: envelope.to, error })
+  }
+})
+```
+
+## Testing
+
+Use the Stub driver in tests to avoid real email delivery.
+
+```ts
+const stubDriver = Mail.drivers.stub()
+
+const mailService = Mail.Provider.create({
+  driver: stubDriver,
+  name: 'default',
+  globalFrom: { email: 'test@example.com' },
+  logger: testLogger,
+  queueService: testQueueService
+})
+Mail.Provider.register('default', mailService)
+
+// Emails go through the full pipeline but are not delivered
+await Mail.send({ to: 'user@example.com', subject: 'Test', content: { text: 'Hello' } })
+```
+
+To inspect sent envelopes, pass a logger to the stub driver:
+
+```ts
+const sent: Mail.Envelope[] = []
+const stubDriver = Mail.drivers.stub({
+  logger: { info: (envelope) => sent.push(envelope) } as any
+})
+```
+
+## Cross-Package Integration
+
+- **@maestro-js/service-registry** -- Provides the Provider pattern (`create`, `register`, `provider`, facade)
+- **@maestro-js/log** -- Used for structured mail logging (envelope records and webhook events)
+- **@maestro-js/queue** -- Powers `Mail.queue()` and `Mail.later()` for async and scheduled delivery. Queue names follow the pattern `Maestro.Mail.{name}` and `Maestro.Mailable.{name}`
+- **@maestro-js/helpers** -- Used by SES and MailTrap drivers for retry logic (`Helpers.retry()`)
+
+## Key Source Files
+
+- `packages/mail/src/index.ts` -- Main module, service creation, mailable system, facade export
+- `packages/mail/src/mail-types.ts` -- Type definitions (Envelope, Address, Content, Attachment, Event, Driver)
+- `packages/mail/src/send-grid-mail-driver.ts` -- SendGrid driver with webhook event mapping
+- `packages/mail/src/ses-mail-driver.ts` -- SES driver with raw MIME composition and retry
+- `packages/mail/src/mail-trap-mail-driver.ts` -- MailTrap driver with retry and webhook events
+- `packages/mail/src/stub-mail-driver.ts` -- Stub driver for testing
+- `packages/mail/src/ics-attachment.ts` -- ICS calendar attachment generator