feat(email): real SMTP delivery with durable idempotent send tracking

[snowrugar-beep]

Summary

Closes #17

Replaces the simulated email path in EmailJobProcessor with real, config-driven SMTP delivery via Nodemailer, real template rendering, and durable idempotent send tracking. The single most important design decision is the atomic Redis SET ... NX EX send-marker keyed by emailId: the claim is taken before sending and released only on failure, so a Bull retry or a duplicate enqueue of an already-sent email short-circuits (never double-sends), while a job whose SMTP call genuinely failed releases the claim and is re-sent by the queue's existing backoff. This is the same claim/release pattern used for the swap processor, kept consistent across the queue layer.

Why

The processor never sent anything: sendEmail simulated a 500ms delay, isEmailSent always returned false, markEmailAsSent only logged, and renderTemplate returned a hardcoded string. Because the idempotency check always reported "not sent", a Bull retry (the queue is configured with attempts: 3 and exponential backoff) after a transient SMTP failure would re-send an email the user already received — and, worse, every job's email was effectively "already sent" yet would be re-sent. A naive nodemailer.sendMail() drop-in would inherit exactly that double-send trap, so durable per-email tracking was a required part of the feature, not an optional extra. The claim-before-send ordering matters: checking first and marking after leaves a window where two workers both see "not sent" and both send; the atomic NX claim closes it.

What was built

src/queue/processors/email.processor.ts (rewritten; tests in src/queue/processors/email.processor.spec.ts):

File	What it contains
email.processor.ts	Real Nodemailer transport built in the constructor from ConfigService (SMTP_HOST, SMTP_PORT, SMTP_SECURE, SMTP_USER, SMTP_PASSWORD, EMAIL_FROM), sent with to, subject, rendered html, and attachments. Transport errors propagate out of processEmail (rethrown), so Bull's configured backoff retries. Idempotency: claimSend(emailId) does SET email:sent:{emailId} 1 EX 2592000 NX via the existing RedisPoolService; on failure releaseSend DELs the marker. Renders through renderEmailTemplate. The transport interface is explicitly typed (SmtpTransport) because the project declares nodemailer as an ambient module with no @types package — a narrow, honest typing of only the surface used rather than spreading any.
email.processor.spec.ts (new)	8 tests with a mocked Nodemailer transport + faithful in-memory Redis fake honoring NX/EX: one transport call with the correct recipient/subject/from/rendered body for a first send; zero transport calls for a duplicate emailId; SMTP failure throws and releases the claim so the retry re-sends (two calls total); welcome/trade-completed/test template resolution; unknown-template fallback; HTML-escaped context.

src/notifications/templates/email.templates.ts (new):

File

What it contains

email.templates.ts

The email template registry: welcome, trade-completed, test templates plus GENERIC_TEMPLATE fallback, and renderEmailTemplate(name, context) with {{key}} interpolation (the same placeholder syntax the i18n notification templates use). Values are HTML-escaped to prevent template injection. Templates are TS constants rather than loose .html files so they survive nest build (which emits only TS; src/ loose files would not reach dist/). Unknown template names fall back to the generic template so a misconfigured job produces a usable email instead of failing forever.

Integration changes outside src/queue/processors/

• README.md — adds SMTP_SECURE and EMAIL_FROM to the required env var block (they were only in .env.example) and documents template resolution rules and the idempotent-delivery marker under the configuration section.

Deliberately separate from NotificationsModule.EmailService: that service swallows transport errors and returns false for graceful degradation — which would defeat Bull retries — so the queue path owns its own throwing transport. The split is documented in the processor docstring.

Acceptance criteria coverage

• sendEmail invokes the real SMTP transport with the configured host/port/from and the job's recipients, subject, and rendered body. (email.processor.spec.ts — "sends a real transport call with recipient, subject, from, and rendered body" asserts the exact sendMail payload including from: 'noreply@peerx.com' and the rendered HTML; transport is built from ConfigService SMTP_* values)
• An SMTP failure throws and is retried via the queue's existing backoff. (email.processor.spec.ts — "throws on SMTP failure and releases the claim so a retry re-sends" rejects with the transport error; the processor rethrows out of processEmail, which Bull treats as a retryable failure)
• A retried job for an already-sent emailId is skipped, not re-sent. (email.processor.spec.ts — "skips a duplicate emailId with zero transport calls"; atomic SET NX EX claim held across the retry)
• A spec asserts one transport call for a first send and zero for a duplicate emailId. (email.processor.spec.ts — first test asserts toHaveBeenCalledTimes(1); duplicate test asserts zero additional calls)
• A spec asserts template resolution for at least the welcome and trade-completed templates. (email.processor.spec.ts — "renders the welcome template with context" and "renders the trade-completed template with context", plus the test template)
• The required SMTP_* and EMAIL_FROM variables and the template resolution rules are documented in the README configuration section. (README — env block updated with SMTP_SECURE/EMAIL_FROM; "Email template resolution" and "Idempotent email delivery" notes)

Test plan

• npm run build — succeeds
• npx jest src/queue/processors/email.processor.spec.ts — 8/8 passing (8 new tests)
• npm run test — 457/510 passing vs 449/502 on base; failing suites identical to base except one pre-existing flaky advanced-analytics spec (a "deterministic anomalyScore" test that asserts on random-bounded values and fails intermittently even in isolation on both base and this branch — unrelated to the email path); zero new failures
• npx eslint on changed source — 0 issues on all three new/changed files
• npx madge --circular --extensions ts src/ — same 3 pre-existing cycles, none involving queue or notifications
• Prettier — all changed files formatted; the README sections added are prettier-clean

Env vars / Notes

SMTP_HOST=smtp.gmail.com        # SMTP server hostname (required for delivery)
SMTP_PORT=587                   # SMTP port (default 587)
SMTP_SECURE=false               # true for implicit TLS (port 465)
SMTP_USER=your_email@gmail.com  # auth user; optional — auth omitted when unset
SMTP_PASSWORD=your_app_password # auth password; optional
EMAIL_FROM=notifications@peerx.com  # From header (default notifications@peerx.com)

Templates: names welcome, trade-completed, and test resolve from src/notifications/templates/email.templates.ts; {{key}} placeholders are HTML-escaped; unknown names fall back to a generic template. Idempotency: an atomic Redis SET email:sent:{emailId} 1 EX 2592000 NX marker (30-day TTL, matching DLQ retention) is claimed before send and released only on failure; Redis must be reachable for the guard to work (the queue already requires Redis). Jobs without to/subject/template fail fast with Invalid email data. This PR does not change the notification processor, SMS/push delivery, or the queue's retry policy (all out of scope per the issue).

[ameeribro4-sudo]

LGTM