Initial Commit

openspec/changes/enterprise-server-emailer/proposal.md

@@ -0,0 +1,155 @@
+# OpenSpec Change: enterprise-server-emailer
+
+- **Change ID**: enterprise-server-emailer
+- **Package**: `@suaveplan/emailer`
+- **Category**: server/services
+- **Target path**: `server/services/emailer`
+- **Status**: PROPOSED
+- **Date**: 2026-04-24
+- **Reference spec**: `/mnt/s/web/suaveplan/enterprise/emailer.md`
+
+---
+
+## Summary
+
+Deliver `@suaveplan/emailer` on the genesis branch from scratch at enterprise quality. The package provides transactional email sending with a pluggable `EmailProvider` interface. It ships an `Emailer` facade, an `InMemoryProvider` for testing, an SMTP provider using `nodemailer`, HTML + text body composition via `@suaveplan/templates`, bounce/unsubscribe suppression via `@suaveplan/suppression`, idempotency via `@suaveplan/idempotency`, retry + circuit breaker via `@suaveplan/retry`, and OTel spans. Supports attachments, CC/BCC, reply-to, inline images, and batch sends with rate-limit awareness.
+
+---
+
+## Current-state audit (genesis)
+
+Does not exist on genesis — fresh build.
+
+---
+
+## Available workspace deps on genesis
+
+| Package | Role |
+|---|---|
+| `@suaveplan/error` (`workspace:^`) | Typed `EMAILER.*` error codes |
+| `@suaveplan/types` (`workspace:^`) | `LoggerLike` |
+| `@suaveplan/retry` (`workspace:^`) | Retry + circuit breaker |
+| `@suaveplan/suppression` (`workspace:^`) | Bounce/unsubscribe suppression |
+| `@suaveplan/idempotency` (`workspace:^`) | Dedup retried sends |
+| `@suaveplan/templates` (`workspace:^`) | HTML + text body templating |
+| `@suaveplan/logger` (`workspace:^`) | Structured logs |
+| `zod` (`catalog:forms`) | Options + message schemas |
+| `@opentelemetry/api` (`catalog:observability`) | Spans + counters |
+| `nodemailer` (`catalog:services`) | SMTP transport |
+| `tslib` (`catalog:build`) | Runtime helpers |
+
+---
+
+## Public API surface
+
+```ts
+class Emailer {
+  constructor(options: EmailerOptions)
+  send(message: EmailMessage): Promise<EmailSendResult>
+  sendBatch(messages: EmailMessage[]): Promise<EmailSendResult[]>
+}
+
+function createEmailer(options: EmailerOptions): Emailer
+
+interface EmailProvider {
+  name: string
+  send(message: EmailMessage): Promise<EmailSendResult>
+}
+
+interface EmailMessage {
+  to: string | string[]
+  from: string
+  subject: string
+  html?: string
+  text?: string
+  templateId?: string
+  templateContext?: Record<string, unknown>
+  cc?: string | string[]
+  bcc?: string | string[]
+  replyTo?: string
+  attachments?: EmailAttachment[]
+  idempotencyKey?: string
+}
+
+interface EmailAttachment {
+  filename: string
+  content: Uint8Array | string
+  contentType?: string
+  inline?: boolean
+  cid?: string
+}
+
+interface EmailSendResult {
+  messageId: string
+  provider: string
+  status: 'queued' | 'sent' | 'failed'
+  accepted: string[]
+  rejected: string[]
+  error?: string
+}
+
+interface EmailerOptions {
+  provider: EmailProvider
+  suppressionStore?: SuppressionStore
+  fromDefault?: string
+  maxRetries?: number
+  logger?: LoggerLike
+}
+
+type EmailerErrorCode =
+  | 'EMAILER_SEND_FAILED'
+  | 'EMAILER_INVALID_ADDRESS'
+  | 'EMAILER_SUPPRESSED'
+  | 'EMAILER_TEMPLATE_NOT_FOUND'
+  | 'EMAILER_PROVIDER_UNAVAILABLE'
+  | 'EMAILER_ATTACHMENT_TOO_LARGE'
+
+function registerEmailerErrorCodes(): void
+```
+
+---
+
+## File layout
+
+```text
+server/services/emailer/
+  package.json
+  tsconfig.json
+  vitest.config.ts
+  src/
+    index.ts
+    error-codes.ts
+    constants/index.ts
+    types/
+      emailer.types.ts
+      emailer.types.md
+    emailer/
+      emailer/
+        emailer.ts
+        emailer.md
+        emailer.types.ts
+        emailer.test.ts
+        index.ts
+    providers/
+      in-memory-provider/
+        in-memory-provider.ts
+        in-memory-provider.md
+        in-memory-provider.test.ts
+        index.ts
+      smtp-provider/
+        smtp-provider.ts
+        smtp-provider.md
+        smtp-provider.types.ts
+        smtp-provider.test.ts
+        index.ts
+  tests/
+    integration.test.ts
+```
+
+---
+
+## Impact
+
+Downstream: auth verification emails, order confirmations, notifications.
+
+**Prerequisites on Verdaccio**: `@suaveplan/error`, `@suaveplan/types`, `@suaveplan/retry`, `@suaveplan/suppression`, `@suaveplan/idempotency`, `@suaveplan/templates`, `@suaveplan/logger`.

openspec/changes/enterprise-server-emailer/tasks.md

@@ -0,0 +1,79 @@
+# Tasks: enterprise-server-emailer
+
+**Change ID**: enterprise-server-emailer
+**Package**: `@suaveplan/emailer`
+**Target path**: `server/services/emailer`
+**Prerequisites on Verdaccio**: `@suaveplan/error`, `@suaveplan/types`, `@suaveplan/retry`, `@suaveplan/suppression`, `@suaveplan/idempotency`, `@suaveplan/templates`, `@suaveplan/logger`
+
+---
+
+## 0. Pre-flight (non-negotiable)
+
+- [ ] 0.1 Confirm clean working tree (`git status` reports nothing) and no in-flight worktrees with uncommitted work (`git worktree list` then `git status` in each)
+- [ ] 0.2 If any worktrees exist under `.claude/worktrees/`, account for each one: still-active agent, work-pending-merge, or stale-and-prune. Stale worktrees MUST be removed (`git worktree remove`) before opening a new one — code that has been lost twice on main is the failure mode this guards against.
+- [ ] 0.3 Confirm the package set in `MANIFEST.md` matches `find packages -maxdepth 3 -name package.json` count. Drift here means a prior change archived without regenerating the manifest.
+
+## 1. Scaffold
+
+- [ ] Create directory tree per `proposal.md`.
+- [ ] `package.json` at `0.1.0`, `"sideEffects": false`, exports `"."` + `emailer` + `providers/in-memory` + `providers/smtp`.
+- [ ] Deps: all workspace + catalog deps listed in proposal.
+- [ ] DevDeps: `vitest catalog:testing`, `@vitest/coverage-istanbul catalog:testing`, `@suaveplan/testing workspace:^`.
+- [ ] `tsconfig.json` extending `library-node.json`; `vitest.config.ts` with `createTestConfig()`.
+- [ ] Scripts: `lint`, `typecheck`, `test`, `test:coverage`, `build`, `docs:check`.
+
+## 2. Types and errors
+
+- [ ] Define all interfaces and Zod schemas (`EmailMessageSchema`, `EmailerOptionsSchema`, `EmailAttachmentSchema`) in `src/types/emailer.types.ts`.
+- [ ] Write `emailer.types.md` (≥200 words, both examples, API reference).
+- [ ] `src/error-codes.ts`: six codes; `registerEmailerErrorCodes()`; eager call.
+
+## 3. InMemory provider
+
+- [ ] Implement `InMemoryProvider` in `src/providers/in-memory-provider/in-memory-provider.ts`:
+  - `send(message)`: store in internal `sent[]`; return `{ messageId: uuid, status: 'sent', accepted: message.to, rejected: [] }`.
+  - `getSent()` / `clearSent()`: testing helpers.
+- [ ] Write `in-memory-provider.test.ts`: send + getSent; clearSent; attachment round-trip.
+- [ ] Write `in-memory-provider.md` (≥200 words).
+
+## 4. SMTP provider
+
+- [ ] Implement `SmtpProvider` in `src/providers/smtp-provider/smtp-provider.ts`:
+  - Constructor creates nodemailer `Transporter`.
+  - `send(message)`: build `Mail.Options` from `EmailMessage`; call `transporter.sendMail()`; map result.
+  - Attachment handling: convert `Uint8Array` to `Buffer` for nodemailer.
+  - Throw `EMAILER_PROVIDER_UNAVAILABLE` on transport error; `EMAILER_SEND_FAILED` on send error.
+  - Guard nodemailer import; throw if unavailable.
+- [ ] `smtp-provider.types.ts` with `SmtpProviderOptions`.
+- [ ] Write `smtp-provider.test.ts` (≤500 lines): skip if `SKIP_SMTP=1`; use `smtp-tester` or `nodemailer-mock`; send and verify received; attachments; `{ timeout: 15000 }`.
+- [ ] Write `smtp-provider.md` (≥200 words).
+
+## 5. Emailer facade
+
+- [ ] Implement `Emailer` in `src/emailer/emailer/emailer.ts`:
+  - `send(message)`:
+    1. Validate `to` addresses (basic `@` check); throw `EMAILER_INVALID_ADDRESS` on invalid.
+    2. Validate attachment sizes against configurable limit (default 25 MB each); throw `EMAILER_ATTACHMENT_TOO_LARGE`.
+    3. Check suppression for each recipient; build filtered `accepted` list; throw `EMAILER_SUPPRESSED` if all suppressed.
+    4. If `templateId` provided: render via `@suaveplan/templates`; populate `html`/`text`.
+    5. Idempotency guard when `idempotencyKey` present.
+    6. `provider.send()` with `@suaveplan/retry`; throw `EMAILER_SEND_FAILED` on exhaustion.
+    7. OTel span `emailer.send`; counter `emailer.sends_total` with `status`.
+  - `sendBatch(messages)`: parallel with `Promise.allSettled`.
+- [ ] Write `emailer.types.ts`.
+- [ ] Write `emailer.test.ts` (≤500 lines): successful send; suppressed recipient; invalid address; template rendering; attachment too large; retry; idempotency dedup; batch with partial failures.
+- [ ] Write `emailer.md` (≥200 words, simple + advanced, API reference).
+
+## 6. Integration tests
+
+- [ ] `tests/integration.test.ts`: `Emailer` + `InMemoryProvider` + real `@suaveplan/suppression` store; add address to suppression; send batch; verify sent/suppressed split; `{ timeout: 10000 }`.
+
+## 7. Docs + verify + publish
+
+- [ ] Root `README.md`: quick-start with InMemoryProvider, SMTP setup, suppression workflow, template usage, API table.
+- [ ] `bunx turbo lint --filter=@suaveplan/emailer` — zero errors.
+- [ ] `bunx turbo typecheck --filter=@suaveplan/emailer` — zero errors.
+- [ ] `bunx turbo test --filter=@suaveplan/emailer` — all pass.
+- [ ] `bunx turbo test:coverage --filter=@suaveplan/emailer` — 100%.
+- [ ] `bun scripts/publish.ts --package @suaveplan/emailer`.
+- [ ] Update `CLAUDE.md`; archive to `openspec/archive/2026-04-24-enterprise-server-emailer/`.