MSPCA-21 Bulk Notifications by Yurika-Kan · Pull Request #24 · Code-4-Community/mspca

Yurika-Kan · 2026-10-27T07:47:15Z

ℹ️ Issue

📝 Description

Foster Coordinators can notify all or a filtered group of volunteers via email sent immediately or at a scheduled time.

immediate:  POST /notifications --> sendNow() --> SES
scheduled:  POST /notifications --> Scheduler (waits until sendAt) --> Lambda --> POST /notifications/send-scheduled --> sendNow() --> SES

POST /notifications (new notifications/ controller, service, module, DTO)
- body: subject, body, optional filters, optional sendAt
- goes to active volunteers only, matching any filter. No filters = all active
- BCC'd in batches of 49 - skips duplicates/malformed emails
- 202 sent/scheduled · 400 bad body · 500 SES/Scheduler not configured
Scheduled sends: sendAt creates a one time AWS schedule.
- AWS remembers that time & when it fires, a Lambda calls POST /notifications/send-scheduled, and the schedule deletes itself
- volunteer recipients are looked up at send time so we filter for all current active volunteers.
POST /notifications/send-scheduled: Lambda only
- Lambda has no Cognito token, so this route checks a shared secret header (NotificationsDispatchGuard)
- 204 sent · 400 bad body · 401 bad/missing secret
AWS infra + setup guide: dispatch Lambda, IAM roles, @aws-sdk/client-scheduler, new env vars in example.env, and setup steps in infra/notification-dispatch-lambda/README.md

✔️ Verification

unit: npx jest apps/backend/src/notifications: 43/43 pass (email + Scheduler mocked)
live: dev AWS and SES, backend run locally behind my exposed local ngrok endpoint~ steps are in the README.

Test	Result
Send now, `filters: ["Dog"]`	202, only the Dog volunteer got it
Scheduled send, full chain	all 4 Active volunteers got it about 2 min later
Lambda --> backend	200, only the Cat volunteer got it
Lambda retries, backend down	3 attempts (1 + 2 retries), no email
Wrong/missing secret	401
Bad body (past `sendAt`, bad filter, missing field, line break in subject)	400

AWS resources, IAM roles + permissions created via CLI (see README), verified in AWS console
tested with 4 of my email addresses

Notes

scheduled sends need 3 values in your .env: AWS_NOTIFICATION_DISPATCH_LAMBDA_ARN, AWS_SCHEDULER_ROLE_ARN and NOTIFICATIONS_DISPATCH_SECRET. shared via slackington

emails go to spam: Gmail sender via SES. prod should send from a verified domain (e.g. c4cneu.com)

🏕️ Future Work

lambda endpoint auth/token - before prod: add @Public() to /send-scheduled Cognito guard is global, so the Lambda gets a 401 once auth is on. It works locally only because AUTH_DISABLED=true.
Role gating: coordinators only. Cognito groups or DB role?
rollback/failed bulk send - failed SES batches are only logged, with no retry or rollback, and a retry can double-send.

returns active volunteers matching any of the given foster types, or all active volunteers when the list is empty. pending and inactive are excluded.

- post /notifications emails active volunteers, filtered by foster type, bcc'd in batches of 49 - with sendAt, creates a one-time eventbridge scheduler schedule instead - post /notifications/send-scheduled is called by the dispatch lambda and guarded by a shared secret header - service, controller, guard and module tests

lambda forwards a fired schedule to /notifications/send-scheduled. readme covers the aws resources, env vars, local testing via tunnel, dev test results and the prod checklist.

Copilot

Copilot was unable to review this pull request because the user who requested the review has insufficient remaining quota.

An organization owner can choose the repository organization as the billing source for reviews requested by members with a paid Copilot license. Learn about Copilot code review billing.

sendNow already drops malformed addresses and dedupes case-insensitively.

…ode-4-Community/mspca into yk/mspca-21-bulk-notifications

coordinators module now imports cognito, so the module spec pulls in jwks-rsa and its esm jose dependency, which jest cannot parse.

teammates only need the env vars to connect. creation steps move below local testing as create from scratch, for prod or a rebuild. notes that the single lambda url is shared.

merge test results into the test table, collapse setup into one script block, trim checklist, troubleshooting and refs.

Juwang110

first pass comments, looks good overall tho!

dburkhart07

okay, wow! this is so well written im amazed yurika! such good documentation, such thorough research done, absolutely wonderful. i havent looked at the tests much since they will likely need updates pending my small changes. id recommend you move everything in the notifs folder aside from the dto, controller, and service (and their respective tests), and put those into a separate aws folder that i recommended. if need be, we can create a new notifications module too if thats necessary, but it shouldnt need much in it.

let me know if you have any confusion, i will thoroughly test and look at each of the tests after the comments are resolved.

also, i have asked max about cleaning up some of our roles within IAM, so be prepared to potentially adjust those within AWS. i wonder now if using terraform may actually be beneficial for us due to how much infrastructure we have setup

dburkhart07 · 2026-10-28T05:21:30Z

@@ -0,0 +1,38 @@
+/**


is there a reason why we put this here instead of in the backend? maybe in an aws/client-scheduler/lambda-functions directory?

there would be a better spot for this if we were using terraform, but we arent, so i think the above suggestion may be better, lmk your thoughts

dburkhart07 · 2026-10-28T05:22:23Z

+  // retries (up to 2 by default, set in the function's async invocation config).
+  if (!response.ok) {
+    throw new Error(
+      `Dispatch failed: ${response.status} ${await response.text()}`,


is there are way we could potentially include how many retries are left on this?

lowkey no, lambda doesn't expose attempt # for async retries. workaround is to add a id to the error so we can count the lines with the same id

dburkhart07 · 2026-10-28T05:26:34Z

+    return this.repo.find({
+      where: {
+        status: VolunteerStatus.ACTIVE,
+        ...(fosterTypes.length > 0 && { fosterType: In(fosterTypes) }),


Do not Resolve until complete:

note that foster types for each volunteer is going to be made into a list pending the merge of #11, so this will need to change later

dburkhart07 · 2026-10-28T06:05:10Z

+# AWS_NOTIFICATION_DISPATCH_LAMBDA_ARN=
+# The role Scheduler assumes to invoke that Lambda (needs lambda:InvokeFunction):
+# AWS_SCHEDULER_ROLE_ARN=
+# Shared secret the Lambda presents to POST /notifications/send-scheduled. Must match the


do we not need to provide the full url that this is to be sent at? for right now, id imagine its localhost:3000/api/notifications/send-scheduled, correct? if so, can we update this?

dburkhart07 · 2026-10-28T06:08:32Z

+      );
+    }
+
+    await this.scheduler.send(


can this be in a try catch block with some error handling?

dburkhart07 · 2026-10-28T06:08:50Z

+    const targetArn = process.env.AWS_NOTIFICATION_DISPATCH_LAMBDA_ARN;
+    const roleArn = process.env.AWS_SCHEDULER_ROLE_ARN;
+
+    if (!targetArn || !roleArn) {


this shouldnt be needed pending module init changes

dburkhart07 · 2026-10-28T06:21:02Z

@@ -0,0 +1,130 @@
+# Scheduled notifications: AWS setup


i think this README can also go into the new aws folder

dburkhart07 · 2026-10-28T06:22:19Z

+  --policy-document "{\"Version\":\"2012-10-17\",\"Statement\":[{\"Effect\":\"Allow\",\"Action\":\"scheduler:CreateSchedule\",\"Resource\":\"arn:aws:scheduler:${AWS_REGION}:${ACCOUNT_ID}:schedule/default/notification-*\"},{\"Effect\":\"Allow\",\"Action\":\"iam:PassRole\",\"Resource\":\"arn:aws:iam::${ACCOUNT_ID}:role/mspca-notif-scheduler-role\",\"Condition\":{\"StringEquals\":{\"iam:PassedToService\":\"scheduler.amazonaws.com\"}}}]}"
+
+# 5. backend env: paste into .env or the host's config, then restart
+echo "AWS_NOTIFICATION_DISPATCH_LAMBDA_ARN=arn:aws:lambda:${AWS_REGION}:${ACCOUNT_ID}:function:mspca-notif-dispatch"


can we add step by step instructions for where to get each of these env variables here?

dburkhart07 · 2026-10-28T18:53:43Z

+  body!: string;
+
+  // Omitted/empty = every active Volunteer regardless of foster type.
+  @IsOptional()


can we add the validateIf that replaced all of our other IsOptional ones so that we cant put in null here? same with sendAt

match foster types with ArrayOverlap now that fosterType is a list (#11)

… require env vars at boot - move infra/notification-dispatch-lambda to apps/backend/src/aws/scheduler/lambda/notif - fail boot when any notifications env var is missing instead of logging - test findActiveByFosterTypes filtering against array foster types

Yurika-Kan added 4 commits October 27, 2026 03:32

feat(volunteers): add findActiveByFosterTypes query

dd31c65

returns active volunteers matching any of the given foster types, or all active volunteers when the list is empty. pending and inactive are excluded.

chore(deps): add @aws-sdk/client-scheduler

5ef68ce

feat(infra): add notification dispatch lambda and aws setup docs

7a6e642

lambda forwards a fired schedule to /notifications/send-scheduled. readme covers the aws resources, env vars, local testing via tunnel, dev test results and the prod checklist.

Copilot AI balanced review requested due to automatic review settings October 27, 2026 07:47

Copilot AI reviewed Oct 27, 2026

Yurika-Kan and others added 7 commits October 27, 2026 03:47

Merge branch 'main' into yk/mspca-21-bulk-notifications

4da10e2

docs(infra): correct known gaps for invalid and duplicate emails

23e608f

sendNow already drops malformed addresses and dedupes case-insensitively.

Merge branch 'yk/mspca-21-bulk-notifications' of https://github.com/C…

f5ef851

…ode-4-Community/mspca into yk/mspca-21-bulk-notifications

test(notifications): stub jwks-rsa in module spec

46f3ff5

coordinators module now imports cognito, so the module spec pulls in jwks-rsa and its esm jose dependency, which jest cannot parse.

docs(infra): lead readme with using the existing dev setup

2f87513

teammates only need the env vars to connect. creation steps move below local testing as create from scratch, for prod or a rebuild. notes that the single lambda url is shared.

docs(infra): drop tunnel options, dev lambda points at owner's tunnel

dc3227b

docs(infra): cut readme down to the essentials

2356370

merge test results into the test table, collapse setup into one script block, trim checklist, troubleshooting and refs.

dburkhart07 requested review from Juwang110 and dburkhart07 October 27, 2026 18:30

dburkhart07 assigned dburkhart07 and Juwang110 Oct 27, 2026

Juwang110 requested changes Oct 27, 2026

View reviewed changes

addressed comments

88c97f7

dburkhart07 requested changes Oct 28, 2026

View reviewed changes

Yurika-Kan added 2 commits November 7, 2026 23:19

merge main into yk/mspca-21-bulk-notifications

3ef491a

match foster types with ArrayOverlap now that fosterType is a list (#11)

Conversation

Yurika-Kan commented Oct 27, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

ℹ️ Issue

📝 Description

✔️ Verification

Notes

🏕️ Future Work

Uh oh!

Copilot AI left a comment

Choose a reason for hiding this comment

Uh oh!

Juwang110 left a comment

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

dburkhart07 left a comment • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Reviewers

Uh oh!

Assignees

Labels

Projects

Milestone

Development

Uh oh!

4 participants

Yurika-Kan commented Oct 27, 2026 •

edited

Loading

dburkhart07 left a comment •

edited

Loading