feat: notification v3

app/(gcforms)/[locale]/(app administration)/admin/(with nav)/accounts/[id]/manage-forms/actions.ts

@@ -6,7 +6,7 @@ import { TemplateHasUnprocessedSubmissions } from "@lib/templates/internal/error
 import { revalidatePath } from "next/cache";
 import { AuthenticatedAction } from "@lib/actions";
 import { getTemplateWithAssignedUsers } from "@lib/templates/queries/getTemplateWithAssignedUsers";
-import { sendArchivedFormNotifications } from "@lib/notifications";
+import { sendArchivedFormNotifications } from "@lib/formEmailOrchestration";
 
 // Public facing functions - they can be used by anyone who finds the associated server action identifer
 

app/(gcforms)/[locale]/(form administration)/form-builder/[id]/settings/manage/page.tsx

@@ -9,7 +9,7 @@ import { Notifications } from "./components/notifications/Notifications";
 import {
   getNotificationsUsersForForm,
   getUserNotificationSettingsForForm,
-} from "@lib/notifications";
+} from "@lib/formEmailOrchestration";
 
 export async function generateMetadata(props: {
   params: Promise<{ locale: string }>;

app/(gcforms)/[locale]/(form administration)/forms/actions.ts

@@ -8,7 +8,7 @@ import { restoreTemplate } from "@lib/templates/mutations/restoreTemplate";
 import { revalidatePath } from "next/cache";
 import { FormRecord } from "@lib/types";
 import { AuthenticatedAction } from "@lib/actions";
-import { sendArchivedFormNotifications } from "@lib/notifications";
+import { sendArchivedFormNotifications } from "@lib/formEmailOrchestration";
 import { getTemplateWithAssignedUsers } from "@lib/templates/queries/getTemplateWithAssignedUsers";
 
 // Public facing functions - they can be used by anyone who finds the associated server action identifer

app/(gcforms)/[locale]/(form filler)/id/[...props]/actions.test.ts

@@ -32,8 +32,14 @@ vi.mock("@root/i18n", () => ({
   serverTranslation: vi.fn(),
 }));
 
-vi.mock("@lib/notifications", () => ({
-  sendNotifications: vi.fn(),
+vi.mock("@lib/formEmailOrchestration", () => ({
+  isFormEligibleForEmails: vi.fn(),
+  updateNotificationMarker: vi.fn(),
+  prepareFormSubmissionEmail: vi.fn(),
+}));
+
+vi.mock("@lib/integration/notifyConnector", () => ({
+  sendEmail: vi.fn(),
 }));
 
 vi.mock("./lib/server/normalizeFormResponses", () => ({
@@ -52,7 +58,8 @@ import { checkOne } from "@lib/cache/flags";
 import { dateHasPast } from "@lib/utils";
 import { validateVisibleElements, valuesMatchErrorContainsElementType } from "@gcforms/core";
 import { serverTranslation } from "@root/i18n";
-import { sendNotifications } from "@lib/notifications";
+import { isFormEligibleForEmails, prepareFormSubmissionEmail, updateNotificationMarker } from "@lib/formEmailOrchestration";
+import { sendEmail } from "@lib/integration/notifyConnector";
 import { normalizeFormResponses } from "./lib/server/normalizeFormResponses";
 import { processFormData } from "./lib/server/processFormData";
 
@@ -93,7 +100,10 @@ describe("submitForm", () => {
       submissionId: "test-submission-id",
       fileURLMap: {}
     });
-    (sendNotifications as Mock).mockResolvedValue(undefined);
+    (isFormEligibleForEmails as Mock).mockResolvedValue(false);
+    (updateNotificationMarker as Mock).mockResolvedValue(null);
+    (prepareFormSubmissionEmail as Mock).mockResolvedValue(null);
+    (sendEmail as Mock).mockResolvedValue(undefined);
   });
 
   it("should return MissingFormDataError when file input validation fails", async () => {
@@ -144,12 +154,110 @@ describe("submitForm", () => {
       securityAttribute: mockTemplate.securityAttribute,
       formId: mockFormId,
       language: mockLanguage,
-      fileChecksums: undefined
+      fileChecksums: undefined,
+      notificationId: undefined,
+    });
+    expect(isFormEligibleForEmails).toHaveBeenCalledWith(mockFormId);
+    expect(prepareFormSubmissionEmail).not.toHaveBeenCalled();
+    expect(sendEmail).not.toHaveBeenCalled();
+  });
+
+  it("should send a first submission notification when form is eligible and no prior marker exists", async () => {
+    const mockEmailData = {
+      emails: ["user@example.com"],
+      subject: "You have a new submission",
+      formResponse: "Email body",
+    };
+    (checkOne as Mock).mockResolvedValue(true);
+    (isFormEligibleForEmails as Mock).mockResolvedValue(true);
+    (updateNotificationMarker as Mock).mockResolvedValue("FIRST_EMAIL");
+    (prepareFormSubmissionEmail as Mock).mockResolvedValue(mockEmailData);
+
+    const result = await submitForm(mockValues, mockLanguage, mockFormId);
+
+    expect(result).toEqual({
+      id: mockFormId,
+      submissionId: "test-submission-id",
+      fileURLMap: {}
+    });
+
+    expect(updateNotificationMarker).toHaveBeenCalledWith(mockFormId);
+
+    expect(prepareFormSubmissionEmail).toHaveBeenCalledWith(
+      mockFormId,
+      mockTemplate.form.titleEn,
+      mockTemplate.form.titleFr,
+      "FIRST_EMAIL"
+    );
+
+    const notificationId = (processFormData as Mock).mock.calls[0][0].notificationId;
+    expect(notificationId).toBeTypeOf("string");
+
+    expect(sendEmail).toHaveBeenCalledWith(
+      mockEmailData.emails,
+      { subject: mockEmailData.subject, formResponse: mockEmailData.formResponse },
+      "formSubmissionNotification",
+      { mode: "deferred", notificationId }
+    );
+    expect(processFormData).toHaveBeenCalledWith(
+      expect.objectContaining({ notificationId })
+    );
+  });
+
+  it("should send a second submission notification when form is eligible and first marker already set", async () => {
+    const mockEmailData = {
+      emails: ["user@example.com"],
+      subject: "You have multiple new submissions",
+      formResponse: "Email body",
+    };
+    (checkOne as Mock).mockResolvedValue(true);
+    (isFormEligibleForEmails as Mock).mockResolvedValue(true);
+    (updateNotificationMarker as Mock).mockResolvedValue("SECOND_EMAIL");
+    (prepareFormSubmissionEmail as Mock).mockResolvedValue(mockEmailData);
+
+    const result = await submitForm(mockValues, mockLanguage, mockFormId);
+
+    expect(result).toEqual({
+      id: mockFormId,
+      submissionId: "test-submission-id",
+      fileURLMap: {}
     });
-    expect(sendNotifications).toHaveBeenCalledWith(
+
+    expect(updateNotificationMarker).toHaveBeenCalledWith(mockFormId);
+
+    expect(prepareFormSubmissionEmail).toHaveBeenCalledWith(
       mockFormId,
       mockTemplate.form.titleEn,
-      mockTemplate.form.titleFr
+      mockTemplate.form.titleFr,
+      "SECOND_EMAIL"
+    );
+
+    const notificationId = (processFormData as Mock).mock.calls[0][0].notificationId;
+    expect(notificationId).toBeTypeOf("string");
+
+    expect(sendEmail).toHaveBeenCalledWith(
+      mockEmailData.emails,
+      { subject: mockEmailData.subject, formResponse: mockEmailData.formResponse },
+      "formSubmissionNotification",
+      { mode: "deferred", notificationId }
+    );
+    expect(processFormData).toHaveBeenCalledWith(
+      expect.objectContaining({ notificationId })
+    );
+  });
+
+  it("should not send a notification when form is eligible but marker limit is reached", async () => {
+    (checkOne as Mock).mockResolvedValue(true);
+    (isFormEligibleForEmails as Mock).mockResolvedValue(true);
+    (updateNotificationMarker as Mock).mockResolvedValue(null);
+
+    await submitForm(mockValues, mockLanguage, mockFormId);
+
+    expect(updateNotificationMarker).toHaveBeenCalledWith(mockFormId);
+    expect(prepareFormSubmissionEmail).not.toHaveBeenCalled();
+    expect(sendEmail).not.toHaveBeenCalled();
+    expect(processFormData).toHaveBeenCalledWith(
+      expect.objectContaining({ notificationId: undefined })
     );
   });
 

app/(gcforms)/[locale]/(form filler)/id/[...props]/actions.ts

@@ -13,12 +13,18 @@ import { FeatureFlags } from "@lib/cache/types";
 import { dateHasPast } from "@lib/utils";
 import { validateVisibleElements } from "@gcforms/core";
 import { serverTranslation } from "@root/i18n";
-import { sendNotifications } from "@lib/notifications";
+import {
+  isFormEligibleForEmails,
+  prepareFormSubmissionEmail,
+  updateNotificationMarker,
+} from "@lib/formEmailOrchestration";
+import { sendEmail } from "@lib/integration/notifyConnector";
 import { traceFunction } from "@lib/otel";
 
 import { MissingFormDataError } from "./lib/client/exceptions";
 import { valuesMatchErrorContainsElementType } from "@gcforms/core";
 import { shouldCheckCaptcha } from "@lib/utils/shouldCheckCaptcha";
+import { randomUUID } from "crypto";
 
 // Public facing functions - they can be used by anyone who finds the associated server action identifer
 
@@ -113,16 +119,22 @@ export async function submitForm(
 
       const formData = normalizeFormResponses(template, values);
 
+      const notificationId = await scheduleFormSubmissionNotification(
+        formId,
+        template.form.titleEn,
+        template.form.titleFr
+      );
+
       const { submissionId, fileURLMap } = await processFormData({
         responses: formData,
         securityAttribute: template.securityAttribute,
         formId,
         language,
         fileChecksums,
+        // If non-null will be used in the reliability lambda to kick off the deferred notification pipeline
+        notificationId,
       });
 
-      sendNotifications(formId, template.form.titleEn, template.form.titleFr);
-
       return { id: formId, submissionId, fileURLMap };
     } catch (e) {
       logMessage.error(
@@ -133,3 +145,42 @@ export async function submitForm(
     }
   });
 }
+
+const scheduleFormSubmissionNotification = async (
+  formId: string,
+  formTitleEn: string,
+  formTitleFr: string
+): Promise<string | undefined> => {
+  try {
+    const shouldSendNotification = await isFormEligibleForEmails(formId);
+    if (!shouldSendNotification) return undefined;
+
+    const notificationEmailType = await updateNotificationMarker(formId);
+    if (!notificationEmailType) return undefined;
+
+    const emailData = await prepareFormSubmissionEmail(
+      formId,
+      formTitleEn,
+      formTitleFr,
+      notificationEmailType
+    );
+    if (!emailData) return undefined;
+
+    const notificationId = randomUUID();
+
+    // Await to avoid a race condition where if the DB write fails, the reliability
+    // lambda will be given a reference to a non-existent record
+    await sendEmail(
+      emailData.emails,
+      { subject: emailData.subject, formResponse: emailData.formResponse },
+      "formSubmissionNotification",
+      { mode: "deferred", notificationId }
+    );
+    return notificationId;
+  } catch (error) {
+    logMessage.warn(
+      `scheduleFormSubmissionNotification failed for form ${formId}: ${(error as Error).message}`
+    );
+    return undefined;
+  }
+};

app/(gcforms)/[locale]/(form filler)/id/[...props]/lib/server/invokeSubmissionLambda.ts

@@ -10,7 +10,8 @@ export const invokeSubmissionLambda = async (
   fields: Responses,
   language: string,
   securityAttribute: string,
-  fileChecksums?: Record<string, string>
+  fileChecksums?: Record<string, string>,
+  notificationId?: string
 ): Promise<{
   submissionId: string;
   fileURLMap?: SignedURLMap;
@@ -22,6 +23,7 @@ export const invokeSubmissionLambda = async (
       responses: fields,
       securityAttribute,
       ...(fileChecksums && Object.keys(fileChecksums).length > 0 && { fileChecksums }),
+      ...(notificationId && { notificationId }),
     };
 
     const lambdaInvokeResponse = await lambdaClient.send(

app/(gcforms)/[locale]/(form filler)/id/[...props]/lib/server/processFormData.ts

@@ -11,6 +11,7 @@ type ProcessFormDataParams = {
   formId: string;
   language?: string;
   fileChecksums?: Record<string, string>;
+  notificationId?: string;
 };
 
 export const processFormData = async ({
@@ -19,6 +20,7 @@ export const processFormData = async ({
   formId,
   language,
   fileChecksums,
+  notificationId,
 }: ProcessFormDataParams): Promise<{
   submissionId: string;
   fileURLMap?: SignedURLMap;
@@ -59,7 +61,8 @@ export const processFormData = async ({
       responses,
       language ? language : "en",
       securityAttribute ? securityAttribute : "Protected A",
-      fileChecksums
+      fileChecksums,
+      notificationId
     );
 
     logMessage.info(`Response submitted for Form ID: ${form.id}`);

i18n/translations/en/admin-flags.json

@@ -45,6 +45,10 @@
     "templateVersioning": {
       "title": "Template versioning",
       "description": "Enable draft versions and re-publishing flow for form templates"
+    },
+    "notification": {
+      "title": "Notification",
+      "description": "Enable sending emails immediately or deferred using the Notification flow. Disabling this will send emails directly to GC Notify."
     }
   },
   "addFlag": "Add user feature flag",

i18n/translations/fr/admin-flags.json

@@ -45,6 +45,10 @@
     "templateVersioning": {
       "title": "Gestion des versions de formulaires",
       "description": "Activer le flux de version d'ébauches et de republication pour les modèles de formulaire"
+    },
+    "notification": {
+      "title": "[FR]Notification",
+      "description": "[FR]Enable sending emails immediately or deferred using the Notification flow. Disabling this will send emails directly to GC Notify."
     }
   },
   "addFlag": "Ajouter un indicateur de fonctionnalité",

lib/cache/types.ts

@@ -10,6 +10,7 @@ export const UserFeatureFlags = {
 export const FeatureFlags = {
   formTimer: "formTimer",
   hCaptcha: "hCaptcha",
+  notification: "notification",
   topBanner: "topBanner",
   zitadelLogin: "zitadelLogin",
   ...UserFeatureFlags,

lib/flags/default_flag_settings.json

@@ -2,6 +2,7 @@
   "addressComplete": false,
   "formTimer": false,
   "hCaptcha": false,
+  "notification": false,
   "templateVersioning": false,
   "topBanner": false,
   "responsesPilot": false,