feat: add onboarding email (#883)

## Details
- Add onboarding email flow for new users 3 days after they logged in
(FOR PROD ONLY)
- Add backend tests for it since it is hard to test just for prod

Note:
An old user is defined to be created before the release of the
onboarding email date
- Scenario 1: old user haven’t login since forever (no last_login_at)
- Scenario 2: old user logged in recently (last_login_at present)
- Scenario 3: new user failed to login —> then login at a later time
- Scenario 4: new user login again after (last_login_at present)
Only scenario 3 will send the onboarding email

## Before Release
- [x] Make sure the pipe is set up, tested and published
- [x] Add the `ONBOARDING_EMAIL_WEBHOOK_URL` on AWS before deploying
- [x] Edit code back to `isProd`

## Tests
- [x] Old user who hasn't login since 03/10 will not trigger the webhook
- [x] Old user who logged in recently will not trigger the webhook
- [x] New user after 03/10 will trigger the webhook, subsequent logins
will not trigger

Author: m0nggh

ecs/env.json

@@ -213,6 +213,10 @@
     {
       "name": "ADMIN_JWT_SECRET_KEY",
       "valueFrom": "plumber-<ENVIRONMENT>-admin-jwt-secret-key"
+    },
+    {
+      "name": "ONBOARDING_EMAIL_WEBHOOK_URL",
+      "valueFrom": "plumber-onboarding-email-webhook-url"
     }
   ]
 }

packages/backend/.env-example

@@ -32,6 +32,7 @@ M365_SG_GOVT_ALLOWED_SENSITIVITY_LABEL_GUIDS_CSV=11111111-1111-1111-1111-1111111
 LAUNCH_DARKLY_SDK_KEY=...
 MAX_JOB_ATTEMPTS=3
 POSTMAN_SMS_QPS_LIMIT_PER_CAMPAIGN=3
+ONBOARDING_EMAIL_WEBHOOK_URL=test-webhook-url
 
 # LOCAL DEV
 SERVE_WEB_APP_SEPARATELY=true

packages/backend/src/config/app.ts

@@ -46,6 +46,7 @@ type AppConfig = {
   }
   launchDarklySdkKey: string
   maxJobAttempts: number
+  onboardingEmailWebhookUrl: string
 }
 
 const port = process.env.PORT || '3000'
@@ -105,6 +106,7 @@ const appConfig: AppConfig = {
   },
   launchDarklySdkKey: process.env.LAUNCH_DARKLY_SDK_KEY,
   maxJobAttempts: Number(process.env.MAX_JOB_ATTEMPTS ?? '10'),
+  onboardingEmailWebhookUrl: process.env.ONBOARDING_EMAIL_WEBHOOK_URL || '',
 }
 
 if (!appConfig.encryptionKey) {

packages/backend/src/controllers/webhooks/handler.ts

@@ -47,7 +47,7 @@ export default async (request: IRequest, response: Response) => {
   const flow = await Flow.query().findById(flowId).withGraphJoined('user')
 
   if (!flow) {
-    logger.info(`Flow not found for webhook id ${flowId}}`)
+    logger.info(`Flow not found for webhook id ${flowId}`)
     return response.sendStatus(404)
   }
 

packages/backend/src/graphql/__tests__/mutations/login-with-selected-sgid.test.ts

@@ -8,6 +8,7 @@ import type Context from '@/types/express/context'
 const mocks = vi.hoisted(() => ({
   setAuthCookie: vi.fn(),
   getOrCreateUser: vi.fn(),
+  sendOnboardingEmail: vi.fn(),
   updateLastLogin: vi.fn(),
   logError: vi.fn(),
   verifyJwt: vi.fn(),
@@ -16,6 +17,7 @@ const mocks = vi.hoisted(() => ({
 vi.mock('@/helpers/auth', () => ({
   setAuthCookie: mocks.setAuthCookie,
   getOrCreateUser: mocks.getOrCreateUser,
+  sendOnboardingEmail: mocks.sendOnboardingEmail,
   updateLastLogin: mocks.updateLastLogin,
 }))
 
@@ -81,6 +83,7 @@ describe('Login with selected SGID', () => {
     expect(mocks.getOrCreateUser).toHaveBeenCalledWith(
       '[email protected]',
     )
+    expect(mocks.sendOnboardingEmail).toHaveBeenCalledWith({ id: 'abc-def' })
     expect(mocks.updateLastLogin).toHaveBeenCalledWith('abc-def')
     expect(mocks.setAuthCookie).toHaveBeenCalledWith(expect.anything(), {
       userId: 'abc-def',
@@ -121,6 +124,7 @@ describe('Login with selected SGID', () => {
     ).rejects.toThrowError('Invalid work email')
 
     expect(mocks.getOrCreateUser).not.toBeCalled()
+    expect(mocks.sendOnboardingEmail).not.toBeCalled()
     expect(mocks.updateLastLogin).not.toBeCalled()
     expect(mocks.setAuthCookie).not.toBeCalled()
   })

packages/backend/src/graphql/__tests__/mutations/login-with-sgid.test.ts

@@ -9,6 +9,7 @@ const mocks = vi.hoisted(() => ({
   sgidUserInfo: vi.fn(),
   setAuthCookie: vi.fn(),
   getOrCreateUser: vi.fn(),
+  sendOnboardingEmail: vi.fn(),
   updateLastLogin: vi.fn(),
   isWhitelistedEmail: vi.fn(),
   logError: vi.fn(),
@@ -45,6 +46,7 @@ vi.mock('@opengovsg/sgid-client', () => ({
 vi.mock('@/helpers/auth', () => ({
   setAuthCookie: mocks.setAuthCookie,
   getOrCreateUser: mocks.getOrCreateUser,
+  sendOnboardingEmail: mocks.sendOnboardingEmail,
   updateLastLogin: mocks.updateLastLogin,
 }))
 
@@ -91,6 +93,7 @@ describe('Login with SGID', () => {
     expect(mocks.getOrCreateUser).toHaveBeenCalledWith(
       '[email protected]',
     )
+    expect(mocks.sendOnboardingEmail).toHaveBeenCalledWith({ id: 'abc-def' })
     expect(mocks.updateLastLogin).toHaveBeenCalledWith('abc-def')
     expect(mocks.setAuthCookie).toHaveBeenCalledWith(expect.anything(), {
       userId: 'abc-def',
@@ -142,6 +145,7 @@ describe('Login with SGID', () => {
     const result = await loginWithSgid(null, STUB_PARAMS, STUB_CONTEXT)
 
     expect(mocks.getOrCreateUser).not.toBeCalled()
+    expect(mocks.sendOnboardingEmail).not.toBeCalled()
     expect(mocks.updateLastLogin).not.toBeCalled()
     expect(mocks.setAuthCookie).not.toBeCalled()
     expect(result.publicOfficerEmployments).toEqual([])
@@ -180,6 +184,7 @@ describe('Login with SGID', () => {
     const result = await loginWithSgid(null, STUB_PARAMS, STUB_CONTEXT)
 
     expect(mocks.getOrCreateUser).toHaveBeenCalledWith('[email protected]')
+    expect(mocks.sendOnboardingEmail).toHaveBeenCalledWith({ id: 'abc-def' })
     expect(mocks.updateLastLogin).toHaveBeenCalledWith('abc-def')
     expect(mocks.setAuthCookie).toHaveBeenCalledWith(expect.anything(), {
       userId: 'abc-def',
@@ -259,6 +264,7 @@ describe('Login with SGID', () => {
       },
     )
     expect(mocks.getOrCreateUser).not.toBeCalled()
+    expect(mocks.sendOnboardingEmail).not.toBeCalled()
     expect(mocks.updateLastLogin).not.toBeCalled()
     expect(mocks.setAuthCookie).not.toBeCalled()
   })
@@ -276,6 +282,7 @@ describe('Login with SGID', () => {
       event: 'sgid-login-failed-user-info',
     })
     expect(mocks.getOrCreateUser).not.toBeCalled()
+    expect(mocks.sendOnboardingEmail).not.toBeCalled()
     expect(mocks.updateLastLogin).not.toBeCalled()
     expect(mocks.setAuthCookie).not.toBeCalled()
   })

packages/backend/src/graphql/mutations/login-with-selected-sgid.ts

@@ -2,7 +2,12 @@ import { type Request } from 'express'
 import { verify as verifyJwt } from 'jsonwebtoken'
 
 import appConfig from '@/config/app'
-import { getOrCreateUser, setAuthCookie, updateLastLogin } from '@/helpers/auth'
+import {
+  getOrCreateUser,
+  sendOnboardingEmail,
+  setAuthCookie,
+  updateLastLogin,
+} from '@/helpers/auth'
 import logger from '@/helpers/logger'
 import {
   type PublicOfficerEmployment,
@@ -44,6 +49,7 @@ const loginWithSelectedSgid: MutationResolvers['loginWithSelectedSgid'] =
     }
 
     const user = await getOrCreateUser(workEmail)
+    await sendOnboardingEmail(user)
     await updateLastLogin(user.id)
     setAuthCookie(context.res, { userId: user.id })
 

packages/backend/src/graphql/mutations/login-with-sgid.ts

@@ -3,7 +3,12 @@ import { type Response } from 'express'
 import { sign as signJwt } from 'jsonwebtoken'
 
 import appConfig from '@/config/app'
-import { getOrCreateUser, setAuthCookie, updateLastLogin } from '@/helpers/auth'
+import {
+  getOrCreateUser,
+  sendOnboardingEmail,
+  setAuthCookie,
+  updateLastLogin,
+} from '@/helpers/auth'
 import { validateAndParseEmail } from '@/helpers/email-validator'
 import logger from '@/helpers/logger'
 import {
@@ -129,6 +134,7 @@ const loginWithSgid: MutationResolvers['loginWithSgid'] = async (
   // Log user in directly if there is only 1 employment.
   if (publicOfficerEmployments.length === 1) {
     const user = await getOrCreateUser(publicOfficerEmployments[0].workEmail)
+    await sendOnboardingEmail(user)
     await updateLastLogin(user.id)
     setAuthCookie(context.res, { userId: user.id })
 

packages/backend/src/graphql/mutations/verify-otp.ts

@@ -1,7 +1,7 @@
 import crypto from 'crypto'
 
 import BaseError from '@/errors/base'
-import { setAuthCookie } from '@/helpers/auth'
+import { sendOnboardingEmail, setAuthCookie } from '@/helpers/auth'
 import { validateAndParseEmail } from '@/helpers/email-validator'
 import User from '@/models/user'
 
@@ -51,14 +51,15 @@ const verifyOtp: MutationResolvers['verifyOtp'] = async (
   ) {
     throw new BaseError('Invalid OTP')
   }
+  await sendOnboardingEmail(user)
+
   // reset otp columns
   await user.$query().patch({
     otpHash: null,
     otpAttempts: 0,
     otpSentAt: null,
     lastLoginAt: new Date(),
   })
-
   // set auth jwt as cookie
   setAuthCookie(context.res, { userId: user.id })
 

packages/backend/src/helpers/__tests__/auth.test.ts

@@ -1,12 +1,15 @@
+import axios from 'axios'
 import jwt from 'jsonwebtoken'
 import { afterEach, beforeEach, describe, expect, it, vi } from 'vitest'
 
 import appConfig from '@/config/app'
+import User from '@/models/user'
 
 import {
   getAdminTokenUser,
   getOrCreateUser,
   parseAdminToken,
+  sendOnboardingEmail,
   updateLastLogin,
 } from '../auth'
 
@@ -23,6 +26,7 @@ const mocks = vi.hoisted(() => ({
   patch: vi.fn(() => ({
     where: mockPatchWhere,
   })),
+  findById: vi.fn(),
 }))
 
 vi.mock('@/models/user', () => ({
@@ -32,10 +36,24 @@ vi.mock('@/models/user', () => ({
       findOne: mocks.findOne,
       insertAndFetch: mocks.insertAndFetch,
       patch: mocks.patch,
+      findById: mocks.findById,
     })),
   },
 }))
 
+vi.mock('axios', () => ({
+  default: {
+    post: vi.fn(),
+  },
+}))
+vi.mock('@/config/app', () => ({
+  default: {
+    isProd: false,
+    onboardingEmailWebhookUrl: 'https://test-webhook.com',
+    adminJwtSecretKey: 'test-secret-key',
+  },
+}))
+
 describe('Auth helpers', () => {
   afterEach(() => {
     vi.restoreAllMocks()
@@ -202,4 +220,93 @@ describe('Auth helpers', () => {
       )
     })
   })
+
+  describe('sendOnboardingEmail', () => {
+    beforeEach(() => {
+      vi.clearAllMocks()
+    })
+
+    afterEach(() => {
+      vi.restoreAllMocks()
+    })
+    it('does not send email if user has logged in before', async () => {
+      const mockUser = {
+        id: 'test-id',
+        email: '[email protected]',
+        lastLoginAt: new Date(),
+        createdAt: new Date(),
+      } as unknown as User
+
+      mocks.findById.mockResolvedValueOnce(mockUser)
+
+      await sendOnboardingEmail(mockUser)
+      expect(axios.post).not.toHaveBeenCalled()
+    })
+
+    it('does not send email if user was created before release date', async () => {
+      const mockUser = {
+        id: 'test-id',
+        email: '[email protected]',
+        createdAt: new Date('2024-01-01'), // Before release date
+      } as unknown as User
+
+      mocks.findById.mockResolvedValueOnce(mockUser)
+
+      await sendOnboardingEmail(mockUser)
+      expect(axios.post).not.toHaveBeenCalled()
+    })
+
+    it('does not send email in non-prod environment', async () => {
+      const mockUser = {
+        id: 'test-id',
+        email: '[email protected]',
+        createdAt: new Date('2025-03-11'), // After release date
+      } as unknown as User
+
+      mocks.findById.mockResolvedValueOnce(mockUser)
+
+      await sendOnboardingEmail(mockUser)
+      expect(axios.post).not.toHaveBeenCalled()
+    })
+
+    it('sends email in prod for eligible users', async () => {
+      appConfig.isProd = true
+
+      const mockUser = {
+        id: 'test-id',
+        email: '[email protected]',
+        lastLoginAt: null,
+        createdAt: new Date('2025-03-11'), // After release date
+      } as unknown as User
+
+      mocks.findById.mockResolvedValueOnce(mockUser)
+      vi.mocked(axios.post).mockResolvedValueOnce({ data: {} })
+
+      await sendOnboardingEmail(mockUser)
+
+      expect(axios.post).toHaveBeenCalledWith(
+        appConfig.onboardingEmailWebhookUrl,
+        {
+          email: mockUser.email,
+        },
+      )
+    })
+
+    it('does not send email if webhook URL is not configured', async () => {
+      vi.mocked(appConfig).isProd = true
+      vi.mocked(appConfig).onboardingEmailWebhookUrl = ''
+
+      const mockUser = {
+        id: 'test-id',
+        email: '[email protected]',
+        lastLoginAt: null,
+        createdAt: new Date('2025-03-11'), // After release date
+      } as unknown as User
+
+      mocks.findById.mockResolvedValueOnce(mockUser)
+
+      await sendOnboardingEmail(mockUser)
+      expect(axios.post).not.toHaveBeenCalled()
+    })
+  })
 })