Skip to content

feat(email): notify active monthly plan donors when receiving account is replaced (Refs #291) - #307

Merged
JOY (JOY) merged 1 commit into
devfrom
antigravity/give-291-plan-swap-notice
Nov 22, 2026
Merged

JOY (JOY) merged 1 commit into
devfrom
antigravity/give-291-plan-swap-notice

Conversation

@JOY

@JOY JOY (JOY) commented Nov 22, 2026 •

Copy link
Copy Markdown
Contributor

Summary

Phase 2 app template and admin outbox labels for plan_account_swapped (follows Phase 1 DB migration DOS/DOS.Me#1871 20261130130000_give_plan_account_swap_notice.sql, merged and verified on Beta at 4dd78004d).

  • Email template (apps/web/src/server/email/templates.ts):
    • Adds plan_account_swapped to EMAIL_KINDS and STOP_LINK_KINDS so every outgoing swap notice carries both a signed one-click plan stop link (/plans/stop?t=... & RFC 8058 List-Unsubscribe: </api/plans/stop?t=...>) and a notification unsubscribe link (/email/unsubscribe?t=...), refusing to send if either token is missing or malformed.
    • Clear Vietnamese copy stating the date of the change (DD/MM/YYYY, Vietnam time), the new account holder name, bank short name (or crypto chain), and masked last 4 digits only (•••• XXXX), with strict regex validation (maskedLast4) so raw account numbers can never render even from a malformed payload.
    • Explicitly states the email does not ask the donor to transfer, explains that future monthly reminders will automatically use the new account's QR, warns to delete any saved bank transfer template pointing to the old account (design §4.3.4), and links to /campaigns/<slug>.
    • Uses kind-appropriate unsubscribe wording (Không muốn nhận các email thông báo như thế này?) instead of email tổng kết for non-summary notifications.
  • Admin outbox metadata (apps/web/src/lib/email-outbox.ts):
    • Adds OUTBOX_KIND_LABELS.plan_account_swapped, OUTBOX_SKIP_LABELS.plan_not_active, OUTBOX_SKIP_LABELS.account_superseded, and mirrors give.outbox_max_age('plan_account_swapped') (14 days) in outboxMaxAgeDays.
  • Unit tests (email-outbox.test.ts, templates.test.ts, outbox.test.ts):
    • Covers normal bank swap, crypto swap, Vietnam-time fallback when changed_date is absent, defense-in-depth anti-leak of raw account numbers, HTML escaping, missing stop/unsubscribe token rejection, sendDueEmails header/body wiring, and admin kind/skip/max-age parity.

Verification

  • pnpm test: 180/180 files, 2629/2629 tests passed.
  • pnpm lint, pnpm typecheck, pnpm format:check, pnpm build: all passed.

Refs #291


📌 TL;DR

Introduces a new plan_account_swapped email notification to inform monthly donors when a campaign's receiving bank or crypto account changes. The implementation includes strict input validation to prevent PII leakage (e.g., full account numbers), supports both bank and crypto channels, and integrates the email into the existing outbox lifecycle with appropriate retention and unsubscribe logic.

🎯 Type of Change

  • 🚀 New feature
  • 🐛 Bugfix
  • 🧹 Refactor
  • ⚡ Performance
  • 📚 Documentation
  • ⚙️ CI / Configuration

🔍 Changes Walkthrough

File Summary of Changes
apps/web/src/lib/email-outbox.ts Adds plan_account_swapped to the outbox kind labels, skip labels, and max-age configuration (14 days).
apps/web/src/lib/email-outbox.test.ts Updates unit tests to verify the new kind's max age and label presence.
apps/web/src/server/email/templates.ts Implements the planAccountSwapped email template. Adds strict regex validation for account last-4 digits and crypto chains to prevent PII leakage. Integrates the new kind into the EMAIL_KINDS list and STOP_LINK_KINDS. Refactors the unsubscribe prompt text to be generic for non-campaign-ended emails.
apps/web/src/server/email/templates.test.ts Adds comprehensive tests for the new template, covering bank/crypto formatting, date localization, PII sanitization (rejecting full account numbers), HTML escaping, and error handling for missing tokens.
apps/web/src/server/email/outbox.test.ts Adds integration tests for the outbox sender to verify that plan_account_swapped emails include signed stop tokens and unsubscribe headers, and are marked as "dead" if required tokens are missing.

📊 Architectural Flow

sequenceDiagram
    participant Outbox as Email Outbox
    participant Sender as sendDueEmails
    participant Renderer as renderEmail
    participant Validator as maskedLast4/swapDateLabel
    participant Transport as Email Transport

    Outbox->>Sender: Claim due email (kind: plan_account_swapped)
    Sender->>Renderer: renderEmail(email, origin, {signedStopToken})
    
    Renderer->>Validator: Validate payload (last4, chain, dates)
    alt Invalid PII or Missing Tokens
        Validator-->>Renderer: Throw EmailRenderError
        Renderer-->>Sender: Error (stop_token_missing / unsubscribe_token_missing)
        Sender->>Outbox: Mark as dead (permanent error)
    else Valid Payload
        Validator-->>Renderer: Sanitized strings (•••• 0002)
        Renderer->>Renderer: Build HTML/Text content
        Renderer-->>Sender: Content + Unsubscribe/Stop URLs
        Sender->>Transport: Send email with List-Unsubscribe headers
        Transport-->>Sender: Success
        Sender->>Outbox: Mark as sent
    end
Loading

@claude claude Bot left a comment

Copy link
Copy Markdown

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

⚠️ Code review skipped — your organization has no extra usage available to pay for this review.

If your organization's extra usage balance is empty, an organization admin can add extra usage credits at claude.ai/admin-settings/usage. If its monthly spend limit was reached, an admin can raise it on the same page. If neither applies, contact Anthropic support.

Once extra usage is available, someone with write access to this repository can comment @claude review on this pull request to trigger a review.

@vercel

vercel Bot commented Nov 22, 2026

Copy link
Copy Markdown

The latest updates on your projects. Learn more about Vercel for GitHub.

Project Deployment Actions Updated
give Ready Ready Preview Nov 22, 2026 9:28am UTC

Request Review

@coderabbitai

coderabbitai Bot commented Nov 22, 2026

Copy link
Copy Markdown

Important

Review skipped

Auto reviews are disabled on base/target branches other than the default branch.

Please check the settings in the CodeRabbit UI or the .coderabbit.yaml file in this repository. To trigger a single review, invoke the @coderabbitai review command.

Run configuration

  • Source mode: Auto
  • Repository: Unavailable
  • Branch: Unavailable
  • File: No configuration file from this repository applied
  • Commit: Unavailable
  • Layers: Organization UI
  • Review profile: CHILL
  • Plan: Advanced
  • Run ID: 52ca40f6-52f8-459b-bd73-cd6fecd003c7

You can disable this status message by setting the reviews.review_status to false in the CodeRabbit configuration file.

Use the checkbox below for a quick retry:

  • Trigger review
  • Autofix · Keep fixing CodeRabbit findings and required CI, and resolving merge conflicts

Thanks for using CodeRabbit! It's free for OSS, and your support helps us grow. If you like it, consider giving us a shout-out.

Share

dos[bot]
dos Bot approved these changes Nov 22, 2026

@dos dos Bot left a comment

Copy link
Copy Markdown

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

⏱️ Code Review completed (5 eligible files · 18,698 chars · 3 model call(s) · 1 PR unit(s))

Whole diff with bounded context at base 6c69036 / head 7481687.

✅ CLEAN_PASS: Complete diff reviewed

Context investigation was bounded to the explicitly requested snapshot paths.

@JOY JOY (JOY) added line:money Product line: money po:agy Owned by Antigravity PO (mutual-exclusion parallel PO label) labels Nov 22, 2026
@JOY

Copy link
Copy Markdown
Contributor Author

PO acceptance: merge at 7481687

Verified on GitHub:

  • Required checks green: Verify build/Lint, Verify build/Build all apps (plus Vercel preview & DOScout green)
  • mergeStateStatus: CLEAN, 0 unresolved review threads; dos[bot] APPROVED
  • Two independent fresh-context flagship money-domain reviews approved at 7481687cdcaa99376746cb23d72d2faa10d47f75 (zero blocking findings; strict maskedLast4 anti-leak guard, anti-scam copy, HTML/header escaping, fail-closed stop_token/unsubscribe_token, and DB #1871 parity verified).

@JOY
JOY (JOY) merged commit 98d9558 into dev Nov 22, 2026
6 checks passed
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

line:money Product line: money po:agy Owned by Antigravity PO (mutual-exclusion parallel PO label)

Projects

None yet

Development

Successfully merging this pull request may close these issues.

1 participant