114 lines
5.1 KiB
Markdown
114 lines
5.1 KiB
Markdown
|
---
|
||
|
|
phase: 06-signing-flow
|
||
|
|
plan: "02"
|
||
|
|
subsystem: email-delivery
|
||
|
|
tags: [react-email, nodemailer, smtp, signing, audit, email]
|
||
|
|
|
||
|
|
# Dependency graph
|
||
|
|
requires:
|
||
|
|
- phase: 06-signing-flow
|
||
|
|
plan: "01"
|
||
|
|
provides: createSigningToken(), logAuditEvent(), signingTokens + auditEvents tables
|
||
|
|
|
||
|
|
provides:
|
||
|
|
- SigningRequestEmail React Email component (navy/gold brand, CTA button, expiry notice)
|
||
|
|
- sendSigningRequestEmail() — renders HTML email and delivers via SMTP
|
||
|
|
- sendAgentNotificationEmail() — plain-text notification to agent on signing completion
|
||
|
|
- POST /api/documents/[id]/send — token creation, email delivery, email_sent audit, status update
|
||
|
|
- document_prepared audit event logged in POST /api/documents/[id]/prepare
|
||
|
|
|
||
|
|
affects: [06-03, 06-04, 06-05]
|
||
|
|
|
||
|
|
# Tech tracking
|
||
|
|
tech-stack:
|
||
|
|
added: []
|
||
|
|
patterns:
|
||
|
|
- React Email render() + nodemailer sendMail() for HTML email delivery
|
||
|
|
- sendMail wrapped in try/catch — 502 returned without DB update on email failure
|
||
|
|
- Reuse CONTACT_SMTP_* env vars for signing emails (same SMTP provider)
|
||
|
|
|
||
|
|
key-files:
|
||
|
|
created:
|
||
|
|
- teressa-copeland-homes/src/emails/SigningRequestEmail.tsx
|
||
|
|
- teressa-copeland-homes/src/lib/signing/signing-mailer.tsx
|
||
|
|
- teressa-copeland-homes/src/app/api/documents/[id]/send/route.ts
|
||
|
|
modified:
|
||
|
|
- teressa-copeland-homes/src/app/api/documents/[id]/prepare/route.ts
|
||
|
|
|
||
|
|
key-decisions:
|
||
|
|
- "Sender address hardcoded as teressa@teressacopelandhomes.com — matches brand identity requirement in CONTEXT.md"
|
||
|
|
- "sendMail error triggers 502 without DB status update — document stays in Draft if email fails, preventing silent failures"
|
||
|
|
- "Status update in send/route.ts only when status=Draft — avoids downgrading Sent back to Sent (no-op) and never touches Signed documents"
|
||
|
|
- "logAuditEvent(document_prepared) placed after db.update .returning() in prepare route — ensures it only fires on success"
|
||
|
|
|
||
|
|
requirements-completed: [SIGN-01, LEGAL-01]
|
||
|
|
|
||
|
|
# Metrics
|
||
|
|
duration: 2min
|
||
|
|
completed: 2026-03-20
|
||
|
|
---
|
||
|
|
|
||
|
|
# Phase 6 Plan 02: Email Delivery Layer Summary
|
||
|
|
|
||
|
|
**Branded React Email signing request template, nodemailer SMTP mailer utilities, and POST /api/documents/[id]/send endpoint that creates a JWT signing token, sends the email, logs email_sent audit event, and updates document status**
|
||
|
|
|
||
|
|
## Performance
|
||
|
|
|
||
|
|
- **Duration:** 2 min
|
||
|
|
- **Started:** 2026-03-20T17:28:17Z
|
||
|
|
- **Completed:** 2026-03-20T17:30:01Z
|
||
|
|
- **Tasks:** 2
|
||
|
|
- **Files modified:** 4
|
||
|
|
|
||
|
|
## Accomplishments
|
||
|
|
|
||
|
|
- SigningRequestEmail.tsx created with navy/gold brand colors, document name, expiry date, and "Review & Sign" CTA button
|
||
|
|
- signing-mailer.tsx exports sendSigningRequestEmail() and sendAgentNotificationEmail()
|
||
|
|
- POST /api/documents/[id]/send creates signing token, sends branded email, logs email_sent, updates status to Sent
|
||
|
|
- prepare/route.ts now logs document_prepared audit event after successful PDF preparation
|
||
|
|
- npm run build passes cleanly
|
||
|
|
|
||
|
|
## Task Commits
|
||
|
|
|
||
|
|
Each task was committed atomically:
|
||
|
|
|
||
|
|
1. **Task 1: Branded signing request email + mailer** - `f41db49` (feat)
|
||
|
|
2. **Task 2: Send API route + document_prepared audit logging** - `877ad66` (feat)
|
||
|
|
|
||
|
|
**Plan metadata:** (docs commit — see below)
|
||
|
|
|
||
|
|
## Files Created/Modified
|
||
|
|
|
||
|
|
- `teressa-copeland-homes/src/emails/SigningRequestEmail.tsx` - React Email component: navy header, gold CTA button, document name, expiry date, "No account needed" instruction
|
||
|
|
- `teressa-copeland-homes/src/lib/signing/signing-mailer.tsx` - sendSigningRequestEmail() renders HTML via @react-email/render and sends via nodemailer; sendAgentNotificationEmail() sends plain-text notification to agent
|
||
|
|
- `teressa-copeland-homes/src/app/api/documents/[id]/send/route.ts` - POST handler: auth guard, token creation, email delivery, email_sent audit log, status update to Sent
|
||
|
|
- `teressa-copeland-homes/src/app/api/documents/[id]/prepare/route.ts` - Added logAuditEvent import and document_prepared event log after db.update success
|
||
|
|
|
||
|
|
## Decisions Made
|
||
|
|
|
||
|
|
- Sender address hardcoded as `teressa@teressacopelandhomes.com` — matches brand identity requirement locked in CONTEXT.md
|
||
|
|
- sendMail failure triggers 502 response without updating DB status — document stays in current state if email delivery fails, preventing silent failures where the client never receives a link but the status shows Sent
|
||
|
|
- Status update guarded by `if (doc.status === 'Draft')` — prevents no-op double-Sent writes and never downgrades Signed documents
|
||
|
|
- `logAuditEvent(document_prepared)` placed after `.returning()` in prepare route — ensures the audit event only fires when the DB update succeeds
|
||
|
|
|
||
|
|
## Deviations from Plan
|
||
|
|
|
||
|
|
None - plan executed exactly as written.
|
||
|
|
|
||
|
|
## Issues Encountered
|
||
|
|
|
||
|
|
None.
|
||
|
|
|
||
|
|
## Next Phase Readiness
|
||
|
|
|
||
|
|
Email delivery layer complete:
|
||
|
|
- sendSigningRequestEmail() and sendAgentNotificationEmail() exported from signing-mailer.tsx
|
||
|
|
- POST /api/documents/[id]/send live and returning 401 for unauthenticated requests
|
||
|
|
- document_prepared audit logging wired in prepare route
|
||
|
|
- Plan 06-03 (sign page) can import sendAgentNotificationEmail from signing-mailer.tsx
|
||
|
|
- Plan 06-04 (sign API) can call sendAgentNotificationEmail after signature submission
|
||
|
|
|
||
|
|
---
|
||
|
|
*Phase: 06-signing-flow*
|
||
|
|
*Completed: 2026-03-20*
|