@defra/forms-engine-plugin 2.1.3 → 2.1.5

package/src/server/plugins/engine/services/notifyService.test.ts

@@ -1,3 +1,6 @@
+import { type FormMetadata } from '@defra/forms-model'
+
+import { escapeMarkdown } from '~/src/server/plugins/engine/components/helpers.js'
 import { checkFormStatus } from '~/src/server/plugins/engine/helpers.js'
 import { type FormModel } from '~/src/server/plugins/engine/models/index.js'
 import { type DetailItem } from '~/src/server/plugins/engine/models/types.js'
@@ -13,6 +16,7 @@ import { sendNotification } from '~/src/server/utils/notify.js'
 jest.mock('~/src/server/utils/notify')
 jest.mock('~/src/server/plugins/engine/helpers')
 jest.mock('~/src/server/plugins/engine/outputFormatters/index')
+jest.mock('~/src/server/plugins/engine/components/helpers')
 
 describe('notifyService', () => {
   const submitResponse = {
@@ -32,7 +36,8 @@ describe('notifyService', () => {
   const mockRequest: FormRequestPayload = jest.mocked<FormRequestPayload>({
     path: 'test',
     logger: {
-      info: jest.fn()
+      info: jest.fn(),
+      error: jest.fn()
     }
   } as unknown as FormRequestPayload)
   let model: FormModel
@@ -41,6 +46,7 @@ describe('notifyService', () => {
 
   beforeEach(() => {
     jest.resetAllMocks()
+    jest.mocked(escapeMarkdown).mockImplementation((text) => text)
   })
 
   it('creates a subject line for real forms', async () => {
@@ -152,4 +158,153 @@ describe('notifyService', () => {
       })
     )
   })
+
+  it('calls outputFormatter with all correct arguments', async () => {
+    const mockFormatter = jest.fn().mockReturnValue('formatted-output')
+    jest.mocked(getFormatter).mockReturnValue(mockFormatter)
+
+    const formMetadata: FormMetadata = {
+      id: 'form-id',
+      slug: 'form-slug',
+      title: 'Form Title'
+    } as FormMetadata
+
+    const formStatus = {
+      isPreview: false,
+      state: FormStatus.Live
+    }
+
+    jest.mocked(checkFormStatus).mockReturnValue(formStatus)
+
+    model = {
+      name: 'foobar',
+      def: {
+        output: {
+          audience: 'human',
+          version: '1'
+        }
+      }
+    } as FormModel
+
+    await submit(
+      formContext,
+      mockRequest,
+      model,
+      'test@defra.gov.uk',
+      items,
+      submitResponse,
+      formMetadata
+    )
+
+    expect(getFormatter).toHaveBeenCalledWith('human', '1')
+
+    expect(mockFormatter).toHaveBeenCalledWith(
+      formContext,
+      items,
+      model,
+      submitResponse,
+      formStatus,
+      formMetadata
+    )
+
+    expect(sendNotificationMock).toHaveBeenCalledWith(
+      expect.objectContaining({
+        personalisation: {
+          subject: 'Form submission: foobar',
+          body: 'formatted-output'
+        }
+      })
+    )
+  })
+
+  it('calls outputFormatter without formMetadata when not provided', async () => {
+    const mockFormatter = jest.fn().mockReturnValue('formatted-output')
+    jest.mocked(getFormatter).mockReturnValue(mockFormatter)
+
+    const formStatus = {
+      isPreview: true,
+      state: FormStatus.Draft
+    }
+
+    jest.mocked(checkFormStatus).mockReturnValue(formStatus)
+
+    model = {
+      name: 'foobar',
+      def: {
+        output: {
+          audience: 'machine',
+          version: '2'
+        }
+      }
+    } as FormModel
+
+    await submit(
+      formContext,
+      mockRequest,
+      model,
+      'test@defra.gov.uk',
+      items,
+      submitResponse
+    )
+
+    expect(getFormatter).toHaveBeenCalledWith('machine', '2')
+
+    expect(mockFormatter).toHaveBeenCalledWith(
+      formContext,
+      items,
+      model,
+      submitResponse,
+      formStatus,
+      undefined
+    )
+
+    expect(sendNotificationMock).toHaveBeenCalledWith(
+      expect.objectContaining({
+        personalisation: {
+          subject: 'TEST FORM SUBMISSION: foobar',
+          body: Buffer.from('formatted-output').toString('base64')
+        }
+      })
+    )
+  })
+
+  it('should handle sendNotification errors and rethrow', async () => {
+    const mockFormatter = jest.fn().mockReturnValue('formatted-output')
+    jest.mocked(getFormatter).mockReturnValue(mockFormatter)
+    jest.mocked(checkFormStatus).mockReturnValue({
+      isPreview: false,
+      state: FormStatus.Live
+    })
+
+    const testError = new Error('Notification service unavailable')
+    sendNotificationMock.mockRejectedValue(testError)
+
+    model = {
+      name: 'foobar',
+      def: {
+        output: {
+          audience: 'human',
+          version: '1'
+        }
+      }
+    } as FormModel
+
+    await expect(
+      submit(
+        formContext,
+        mockRequest,
+        model,
+        'test@defra.gov.uk',
+        items,
+        submitResponse
+      )
+    ).rejects.toThrow('Notification service unavailable')
+
+    expect(mockRequest.logger.error).toHaveBeenCalledWith(
+      'Notification service unavailable',
+      expect.stringContaining(
+        '[emailSendFailed] Error sending notification email'
+      )
+    )
+  })
 })

package/src/server/plugins/engine/services/notifyService.ts

@@ -1,4 +1,8 @@
-import { getErrorMessage, type SubmitResponsePayload } from '@defra/forms-model'
+import {
+  getErrorMessage,
+  type FormMetadata,
+  type SubmitResponsePayload
+} from '@defra/forms-model'
 
 import { config } from '~/src/config/index.js'
 import { escapeMarkdown } from '~/src/server/plugins/engine/components/helpers.js'
@@ -12,14 +16,24 @@ import { sendNotification } from '~/src/server/utils/notify.js'
 
 const templateId = config.get('notifyTemplateId')
 
+/**
+ * Optional GOV.UK Notify service for consumers who want email notifications
+ * Can be disabled by not providing notifyTemplateId in config
+ * Can be overridden by providing a custom outputService in the services config
+ */
 export async function submit(
   context: FormContext,
   request: FormRequestPayload,
   model: FormModel,
   emailAddress: string,
   items: DetailItem[],
-  submitResponse: SubmitResponsePayload
+  submitResponse: SubmitResponsePayload,
+  formMetadata?: FormMetadata
 ) {
+  if (!templateId) {
+    return Promise.resolve()
+  }
+
   const logTags = ['submit', 'email']
   const formStatus = checkFormStatus(request.params)
 
@@ -35,7 +49,14 @@ export async function submit(
   const outputVersion = model.def.output?.version ?? '1'
 
   const outputFormatter = getFormatter(outputAudience, outputVersion)
-  let body = outputFormatter(context, items, model, submitResponse, formStatus)
+  let body = outputFormatter(
+    context,
+    items,
+    model,
+    submitResponse,
+    formStatus,
+    formMetadata
+  )
 
   // GOV.UK Notify transforms quotes into curly quotes, so we can't just send the raw payload
   // This is logic specific to Notify, so we include the logic here rather than in the formatter

package/src/server/plugins/engine/types/index.ts

@@ -0,0 +1,96 @@
+export type {
+  CheckAnswers,
+  ErrorMessageTemplate,
+  ErrorMessageTemplateList,
+  FeaturedFormPageViewModel,
+  FileState,
+  FilterFunction,
+  FormAdapterSubmissionMessage,
+  FormAdapterSubmissionMessageData,
+  FormAdapterSubmissionMessageMeta,
+  FormAdapterSubmissionMessageMetaSerialised,
+  FormAdapterSubmissionMessagePayload,
+  FormAdapterSubmissionService,
+  FormContext,
+  FormContextRequest,
+  FormPageViewModel,
+  FormPayload,
+  FormPayloadParams,
+  FormState,
+  FormStateValue,
+  FormSubmissionError,
+  FormSubmissionState,
+  FormValidationResult,
+  FormValue,
+  GlobalFunction,
+  ItemDeletePageViewModel,
+  OnRequestCallback,
+  PageViewModel,
+  PageViewModelBase,
+  PluginOptions,
+  PreparePageEventRequestOptions,
+  RepeatItemState,
+  RepeatListState,
+  RepeaterSummaryPageViewModel,
+  SummaryList,
+  SummaryListAction,
+  SummaryListRow,
+  TempFileState,
+  UploadInitiateResponse,
+  UploadStatusFileResponse,
+  UploadStatusResponse
+} from '~/src/server/plugins/engine/types.js'
+
+export {
+  FileStatus,
+  FormAdapterSubmissionSchemaVersion,
+  UploadStatus
+} from '~/src/server/plugins/engine/types.js'
+
+export type {
+  Detail,
+  DetailItem,
+  DetailItemBase,
+  DetailItemField,
+  DetailItemRepeat,
+  ExecutableCondition
+} from '~/src/server/plugins/engine/models/types.js'
+
+export type {
+  BackLink,
+  ComponentText,
+  ComponentViewModel,
+  Content,
+  DateInputItem,
+  DatePartsState,
+  Label,
+  ListItem,
+  ListItemLabel,
+  MonthYearState,
+  ViewModel
+} from '~/src/server/plugins/engine/components/types.js'
+
+export type { UkAddressState } from '~/src/server/plugins/engine/components/UkAddressField.js'
+
+export type {
+  FormParams,
+  FormQuery,
+  FormRequest,
+  FormRequestPayload,
+  FormRequestPayloadRefs,
+  FormRequestRefs
+} from '~/src/server/routes/types.js'
+
+export { FormAction, FormStatus } from '~/src/server/routes/types.js'
+
+export type {
+  FormSubmissionService,
+  FormsService,
+  OutputService,
+  RouteConfig,
+  Services
+} from '~/src/server/types.js'
+
+export type { RichFormValue } from '~/src/server/plugins/engine/outputFormatters/machine/v2.js'
+
+export * from '~/src/server/plugins/engine/types/schema.js'

package/src/server/plugins/engine/types/schema.test.ts

@@ -0,0 +1,152 @@
+import { FormStatus } from '@defra/forms-model'
+
+import {
+  formAdapterSubmissionMessageDataSchema,
+  formAdapterSubmissionMessageMetaSchema,
+  formAdapterSubmissionMessagePayloadSchema
+} from '~/src/server/plugins/engine/types/schema.js'
+import {
+  FormAdapterSubmissionSchemaVersion,
+  type FormAdapterSubmissionMessageData,
+  type FormAdapterSubmissionMessageMeta,
+  type FormAdapterSubmissionMessagePayload
+} from '~/src/server/plugins/engine/types.js'
+
+describe('Schema validation', () => {
+  describe('formAdapterSubmissionMessageMetaSchema', () => {
+    const validMeta: FormAdapterSubmissionMessageMeta = {
+      schemaVersion: FormAdapterSubmissionSchemaVersion.V1,
+      timestamp: new Date('2025-08-22T18:15:10.785Z'),
+      referenceNumber: '576-225-943',
+      formName: 'Order a pizza',
+      formId: '68a8b0449ab460290c28940a',
+      formSlug: 'order-a-pizza',
+      status: FormStatus.Live,
+      isPreview: false,
+      notificationEmail: 'info@example.com'
+    }
+
+    it('should validate valid meta object', () => {
+      const { error } =
+        formAdapterSubmissionMessageMetaSchema.validate(validMeta)
+      expect(error).toBeUndefined()
+    })
+
+    it('should reject invalid schema version', () => {
+      const invalidMeta = { ...validMeta, schemaVersion: 'invalid' }
+      const { error } =
+        formAdapterSubmissionMessageMetaSchema.validate(invalidMeta)
+      expect(error).toBeDefined()
+    })
+
+    it('should reject missing required fields', () => {
+      // eslint-disable-next-line @typescript-eslint/no-unused-vars
+      const { timestamp: _, ...metaWithoutTimestamp } = validMeta
+      const { error } =
+        formAdapterSubmissionMessageMetaSchema.validate(metaWithoutTimestamp)
+      expect(error).toBeDefined()
+    })
+  })
+
+  describe('formAdapterSubmissionMessageDataSchema', () => {
+    const validData: FormAdapterSubmissionMessageData = {
+      main: {
+        QMwMir: 'Roman Pizza',
+        duOEvZ: 'Small',
+        DzEODf: ['Mozzarella'],
+        juiCfC: ['Pepperoni', 'Sausage', 'Onions', 'Basil'],
+        YEpypP: 'None',
+        JumNVc: 'Joe Bloggs',
+        ALNehP: '+441234567890',
+        vAqTmg: {
+          addressLine1: '1 Anywhere Street',
+          town: 'Anywhereville',
+          postcode: 'AN1 2WH'
+        },
+        IbXVGY: {
+          day: 22,
+          month: 8,
+          year: 2025
+        },
+        HGBWLt: ['Garlic sauce']
+      },
+      repeaters: {},
+      files: {}
+    }
+
+    it('should validate valid data object', () => {
+      const { error } =
+        formAdapterSubmissionMessageDataSchema.validate(validData)
+      expect(error).toBeUndefined()
+    })
+
+    it('should validate empty objects', () => {
+      const emptyData = { main: {}, repeaters: {}, files: {} }
+      const { error } =
+        formAdapterSubmissionMessageDataSchema.validate(emptyData)
+      expect(error).toBeUndefined()
+    })
+  })
+
+  describe('formAdapterSubmissionMessagePayloadSchema', () => {
+    const validPayload: FormAdapterSubmissionMessagePayload = {
+      meta: {
+        schemaVersion: FormAdapterSubmissionSchemaVersion.V1,
+        timestamp: new Date('2025-08-22T18:15:10.785Z'),
+        referenceNumber: '576-225-943',
+        formName: 'Order a pizza',
+        formId: '68a8b0449ab460290c28940a',
+        formSlug: 'order-a-pizza',
+        status: FormStatus.Live,
+        isPreview: false,
+        notificationEmail: 'info@example.com'
+      },
+      data: {
+        main: {
+          QMwMir: 'Roman Pizza',
+          duOEvZ: 'Small',
+          DzEODf: ['Mozzarella'],
+          juiCfC: ['Pepperoni', 'Sausage', 'Onions', 'Basil'],
+          YEpypP: 'None',
+          JumNVc: 'Joe Bloggs',
+          ALNehP: '+441234567890',
+          vAqTmg: {
+            addressLine1: '1 Anywhere Street',
+            town: 'Anywhereville',
+            postcode: 'AN1 2WH'
+          },
+          IbXVGY: {
+            day: 22,
+            month: 8,
+            year: 2025
+          },
+          HGBWLt: ['Garlic sauce']
+        },
+        repeaters: {},
+        files: {}
+      }
+    }
+
+    it('should validate complete payload', () => {
+      const { error } =
+        formAdapterSubmissionMessagePayloadSchema.validate(validPayload)
+      expect(error).toBeUndefined()
+    })
+
+    it('should reject payload without meta', () => {
+      // eslint-disable-next-line @typescript-eslint/no-unused-vars
+      const { meta: _, ...payloadWithoutMeta } = validPayload
+      const { error } =
+        formAdapterSubmissionMessagePayloadSchema.validate(payloadWithoutMeta)
+      expect(error).toBeDefined()
+    })
+
+    it('should reject payload without data', () => {
+      // eslint-disable-next-line @typescript-eslint/no-unused-vars
+      const { data: _, ...payloadWithoutData } = validPayload
+      const { error } =
+        formAdapterSubmissionMessagePayloadSchema.validate(payloadWithoutData)
+      expect(error).toBeDefined()
+    })
+  })
+})

package/src/server/plugins/engine/types/schema.ts

@@ -0,0 +1,45 @@
+import {
+  FormStatus,
+  idSchema,
+  notificationEmailAddressSchema,
+  slugSchema,
+  titleSchema
+} from '@defra/forms-model'
+import Joi from 'joi'
+
+import {
+  FormAdapterSubmissionSchemaVersion,
+  type FormAdapterSubmissionMessageData,
+  type FormAdapterSubmissionMessageMeta,
+  type FormAdapterSubmissionMessagePayload
+} from '~/src/server/plugins/engine/types.js'
+
+export const formAdapterSubmissionMessageMetaSchema =
+  Joi.object<FormAdapterSubmissionMessageMeta>().keys({
+    schemaVersion: Joi.string().valid(
+      ...Object.values(FormAdapterSubmissionSchemaVersion)
+    ),
+    timestamp: Joi.date().required(),
+    referenceNumber: Joi.string().required(),
+    formName: titleSchema,
+    formId: idSchema,
+    formSlug: slugSchema,
+    status: Joi.string()
+      .valid(...Object.values(FormStatus))
+      .required(),
+    isPreview: Joi.boolean().required(),
+    notificationEmail: notificationEmailAddressSchema.required()
+  })
+
+export const formAdapterSubmissionMessageDataSchema =
+  Joi.object<FormAdapterSubmissionMessageData>().keys({
+    main: Joi.object(),
+    repeaters: Joi.object(),
+    files: Joi.object()
+  })
+
+export const formAdapterSubmissionMessagePayloadSchema =
+  Joi.object<FormAdapterSubmissionMessagePayload>().keys({
+    meta: formAdapterSubmissionMessageMetaSchema.required(),
+    data: formAdapterSubmissionMessageDataSchema.required()
+  })

package/src/server/plugins/engine/types.ts

@@ -18,6 +18,7 @@ import {
   type ComponentViewModel
 } from '~/src/server/plugins/engine/components/types.js'
 import { type FormModel } from '~/src/server/plugins/engine/models/index.js'
+import { type RichFormValue } from '~/src/server/plugins/engine/outputFormatters/machine/v2.js'
 import { type PageController } from '~/src/server/plugins/engine/pageControllers/PageController.js'
 import { type PageControllerClass } from '~/src/server/plugins/engine/pageControllers/helpers.js'
 import { type ViewContext } from '~/src/server/plugins/nunjucks/types.js'
@@ -25,7 +26,8 @@ import {
   type FormAction,
   type FormParams,
   type FormRequest,
-  type FormRequestPayload
+  type FormRequestPayload,
+  type FormStatus
 } from '~/src/server/routes/types.js'
 import { type RequestOptions } from '~/src/server/services/httpService.js'
 import { type Services } from '~/src/server/types.js'
@@ -384,3 +386,51 @@ export interface PluginOptions {
   onRequest?: OnRequestCallback
   baseUrl: string // base URL of the application, protocol and hostname e.g. "https://myapp.com"
 }
+
+export interface FormAdapterSubmissionMessageMeta {
+  schemaVersion: FormAdapterSubmissionSchemaVersion
+  timestamp: Date
+  referenceNumber: string
+  formName: string
+  formId: string
+  formSlug: string
+  status: FormStatus
+  isPreview: boolean
+  notificationEmail: string
+}
+
+export type FormAdapterSubmissionMessageMetaSerialised = Omit<
+  FormAdapterSubmissionMessageMeta,
+  'schemaVersion' | 'timestamp' | 'status'
+> & {
+  schemaVersion: string
+  status: string
+  timestamp: string
+}
+
+export interface FormAdapterSubmissionMessageData {
+  main: Record<string, RichFormValue>
+  repeaters: Record<string, Record<string, RichFormValue>[]>
+  files: Record<string, Record<string, string>[]>
+}
+
+export enum FormAdapterSubmissionSchemaVersion {
+  V1 = 1
+}
+
+export interface FormAdapterSubmissionMessagePayload {
+  meta: FormAdapterSubmissionMessageMeta
+  data: FormAdapterSubmissionMessageData
+}
+
+export interface FormAdapterSubmissionMessage
+  extends FormAdapterSubmissionMessagePayload {
+  messageId: string
+  recordCreatedAt: Date
+}
+
+export interface FormAdapterSubmissionService {
+  handleFormSubmission: (
+    submissionMessage: FormAdapterSubmissionMessage
+  ) => unknown
+}

package/src/server/types.ts

@@ -59,6 +59,7 @@ export interface OutputService {
     model: FormModel,
     emailAddress: string,
     items: DetailItem[],
-    submitResponse: SubmitResponsePayload
+    submitResponse: SubmitResponsePayload,
+    formMetadata?: FormMetadata
   ) => Promise<void>
 }