suaveplan/openspec/archive/2026-05-19-add-emailer/proposal.md

# Ship @suaveplan/emailer (Wave Emails)

**Package**: `@suaveplan/emailer`
**Status**: PROPOSED
**Type**: new-package
**Design**: ./design.md
**Spec delta**: ./specs/emailer/spec.md

## Why

The upstream `@suaveplan/emailer` (server-tier, 76.11% coverage, no spec, no OTel,
no defineCodes, no Zod boundaries, nodemailer + googleapis hard deps) is the only
remaining gap in the emails plugin family before `enterprise-email-templates`,
`notification-channel`, and `delivery-tracking` can light up email channels in
genesis. The genesis rewrite consolidates the upstream `EmailService` plus the
`DummyProvider` and `GmailProvider` plugins into a universal-tier package with
zero hard transport deps: every transport is structural (`EmailTransport`) and
test- or runtime-injectable, the SMTP path takes a caller-supplied `SmtpClientLike`
adapter (so consumers bundle nodemailer/etc. only when they need real SMTP), and
Gmail is reached through Gmail's REST API over an injectable `FetchLike` (no
`googleapis` dependency).

## What changes

- ADDED: `EmailService<TTransport>` — hook-driven sender with stats, retry,
  AbortSignal, OTel instrumentation, optional asynchronous queue dispatch.
- ADDED: `EmailTransport` interface, `BaseEmailTransport` abstract helper, and
  `EmailTransportLifecycle` (initialize / verify / close) — pluggable transport
  contract every emitter (dummy, smtp, gmail-rest) implements.
- ADDED: `DummyTransport` — deterministic in-memory transport for tests and
  development; records every send, supports forced failures, configurable delay
  via injectable `TimersLike`, deterministic message-id suffix via injectable
  `Rng`.
- ADDED: `SmtpTransport` — universal SMTP transport that accepts an injectable
  `SmtpClientLike` adapter (caller supplies the concrete implementation, e.g.
  nodemailer wired up in their own app shell), so the emailer package stays free
  of Node-tier deps.
- ADDED: `GmailRestTransport` — calls Gmail's REST `users.messages.send` endpoint
  over an injectable `FetchLike` with caller-supplied bearer access tokens; covers
  every upstream auth mode by treating token acquisition as the caller's concern.
- ADDED: `EmailerHooks` — nine lifecycle hooks (`beforeValidate`, `afterValidate`,
  `beforeSend`, `afterSend`, `onError`, `afterError`, `beforeRetry`, `beforeQueue`,
  `afterQueue`) with typed contexts.
- ADDED: `EMAILER_CODES` via `defineCodes("EMAILER", [...])` — 12 stable error
  codes, each thrown by ≥1 production path.
- ADDED: Zod schemas at every options boundary (`EmailMessage`,
  `EmailerOptionsSchema`, transport-specific schemas) — validated via `safeParse`.
- ADDED: OTel metrics (`emailer.send.total`, `emailer.send.errors`,
  `emailer.send.latency_ms`, `emailer.queue.depth`, `emailer.retry.total`).
- ADDED: Subpath exports for every public module (`./error-codes`,
  `./schemas/schemas`, `./types/emailer`, `./core/email-service`,
  `./transports/dummy`, `./transports/smtp`, `./transports/gmail-rest`,
  `./fakes/fake-smtp-client`, `./otel/metrics`).

## Out of scope

- Hard `nodemailer` / `googleapis` dependencies — replaced with structural
  `SmtpClientLike` injection and direct Gmail REST calls over `FetchLike`.
- IMAP / POP3 / inbound parsing — outbound only.
- Address-book / template engines — `@suaveplan/templates`,
  `enterprise-email-templates`, and `@suaveplan/contacts` own those concerns.
- Suppression-list enforcement — `@suaveplan/suppression` is consulted via a
  caller-supplied `beforeSend` hook; this package does not re-implement it.

## Source mapping

This change derives from `../suaveplan/enterprise/emailer.md` and the upstream
implementation under `../suaveplan/packages/server/emailer/src/`.

| Requirement | Source lines | Notes |
|---|---|---|
| EmailService lifecycle (initialize/send/queue/close) | `EmailService.ts` L36-L348 | reworded: AbortSignal added, OTel added, FSM state machine implicit |
| Nine lifecycle hooks (`beforeValidate` ... `afterQueue`) | `types/core.ts` L176-L195 + `EmailService.ts` L44-L54 | verbatim |
| Stats (`sent`, `failed`, `queued`, `retries`, `startTime`, `lastSendTime`) | `types/core.ts` L200-L213 + `EmailService.ts` L56-L63, L133, L153, L191, L252 | verbatim |
| Retry with linear / exponential backoff | `EmailService.ts` L171-L225 | extended: deterministic via `TimersLike` injection + AbortSignal |
| Asynchronous queue dispatch via injectable `add(fn)` shim | `EmailService.ts` L29-L31, L230-L255 | reworded as structural `QueueLike` |
| `EmailMessage` shape (to/from/cc/bcc/replyTo/subject/html/text/attachments/headers/priority/messageId) | `types/core.ts` L31-L58 | verbatim, plus Zod schema |
| `BaseEmailTransport` helpers (formatAddress, formatSingleAddress, createSuccessResult, createErrorResult, validateMessage, toEmailArray, extractEmail) | `providers/BaseEmailProvider.ts` L75-L188 | renamed Provider→Transport; the body is genesis-rewritten |
| `DummyTransport` — sentEmails, sendCount, simulated failure, simulated delay, message-id prefix, verify control, EventEmitter hooks | `providers/DummyProvider.ts` L23-L158 | extended: delay via injectable TimersLike; message-id suffix via injectable Rng |
| Gmail provider (OAuth2 / app-password / service-account) | `providers/GmailProvider.ts` L1-L316 | rewritten as `GmailRestTransport` — token acquisition is caller's concern; sends via REST over FetchLike |

### Requirements with no source line

| Requirement | Justification |
|---|---|
| OTel metrics emitted from production paths and asserted with in-memory MeterProvider | Genesis-wide observability policy; upstream had none |
| Zod boundary validation on every option bundle | Genesis-wide schema-driven boundary policy |
| Universal-tier purity (no hard Node deps) | Genesis emails plugin is universal-tier; upstream was server-only |
| AbortSignal propagation through send / retry / queue paths | Genesis-wide cancellation policy |
| `defineCodes("EMAILER", [...])` typed error registry, every code thrown by ≥1 prod path | Genesis-wide error-code policy |
| `FakeSmtpClient` exported for downstream tests | Genesis-wide injectable-fake policy |
| 100% Istanbul coverage | Genesis-wide policy |

## Verification approach

- `src/core/email-service/email-service.test.ts` — lifecycle, hooks, stats, retry, queue, AbortSignal, error paths.
- `src/core/retry/retry.test.ts` — linear + exponential backoff, deterministic via injected timers + clock.
- `src/core/validate/validate.test.ts` — `validateMessage`, `formatAddress`, `formatSingleAddress`, `extractEmail`, `toEmailArray`.
- `src/transports/dummy/dummy-transport.test.ts` — initialise, send, verify, close, forced failure, simulated delay, message-id suffix, EventEmitter forwarding.
- `src/transports/smtp/smtp-transport.test.ts` — happy-path send + verify + close via `FakeSmtpClient`; init / verify failure paths.
- `src/transports/gmail-rest/gmail-rest-transport.test.ts` — MIME build, base64url encoding, success + failure paths against `FakeFetch`.
- `src/fakes/fake-smtp-client.test.ts` — scripted responses, FIFO consumption, abort, capture inspection.
- `src/error-codes.test.ts` — every code reachable; literal-type union assertion via `expectTypeOf`.
- `src/schemas/schemas.test.ts` — each Zod schema safeParse happy + sad path.
- `src/otel/metrics.test.ts` — real `MeterProvider` collects every instrument.
- `src/emailer.spec-conformance.test.ts` — observability, AbortSignal, generic threading, lifecycle dedup.
- `tests/dep-graph.test.ts` — package.json invariants (deps, sideEffects, exports).
- `tests/no-disallowed.test.ts` — no `vi.mock`, no `console.log`, no `export *` in feature barrels.

## Migration impact

None — additive only. No consumer in genesis imports `@suaveplan/emailer` yet.