@defra/forms-engine-plugin 2.1.4 → 2.1.5

package/src/server/plugins/engine/outputFormatters/adapter/v1.ts

@@ -0,0 +1,53 @@
+import {
+  type FormMetadata,
+  type SubmitResponsePayload
+} from '@defra/forms-model'
+
+import { type checkFormStatus } from '~/src/server/plugins/engine/helpers.js'
+import { type FormModel } from '~/src/server/plugins/engine/models/FormModel.js'
+import { type DetailItem } from '~/src/server/plugins/engine/models/types.js'
+import { format as machineV2 } from '~/src/server/plugins/engine/outputFormatters/machine/v2.js'
+import {
+  FormAdapterSubmissionSchemaVersion,
+  type FormAdapterSubmissionMessageData,
+  type FormAdapterSubmissionMessagePayload,
+  type FormContext
+} from '~/src/server/plugins/engine/types.js'
+import { FormStatus } from '~/src/server/routes/types.js'
+
+export function format(
+  context: FormContext,
+  items: DetailItem[],
+  model: FormModel,
+  submitResponse: SubmitResponsePayload,
+  formStatus: ReturnType<typeof checkFormStatus>,
+  formMetadata?: FormMetadata
+): string {
+  const v2DataString = machineV2(
+    context,
+    items,
+    model,
+    submitResponse,
+    formStatus
+  )
+  const v2DataParsed = JSON.parse(v2DataString) as {
+    data: FormAdapterSubmissionMessageData
+  }
+
+  const payload: FormAdapterSubmissionMessagePayload = {
+    meta: {
+      schemaVersion: FormAdapterSubmissionSchemaVersion.V1,
+      timestamp: new Date(),
+      referenceNumber: context.referenceNumber,
+      formName: model.name,
+      formId: formMetadata?.id ?? '',
+      formSlug: formMetadata?.slug ?? '',
+      status: formStatus.isPreview ? FormStatus.Draft : FormStatus.Live,
+      isPreview: formStatus.isPreview,
+      notificationEmail: formMetadata?.notificationEmail ?? ''
+    },
+    data: v2DataParsed.data
+  }
+
+  return JSON.stringify(payload)
+}

package/src/server/plugins/engine/outputFormatters/human/v1.ts

@@ -1,4 +1,7 @@
-import { type SubmitResponsePayload } from '@defra/forms-model'
+import {
+  type FormMetadata,
+  type SubmitResponsePayload
+} from '@defra/forms-model'
 import { addDays, format as dateFormat } from 'date-fns'
 
 import { config } from '~/src/config/index.js'
@@ -18,7 +21,8 @@ export function format(
   items: DetailItem[],
   model: FormModel,
   submitResponse: SubmitResponsePayload,
-  formStatus: ReturnType<typeof checkFormStatus>
+  formStatus: ReturnType<typeof checkFormStatus>,
+  _formMetadata?: FormMetadata
 ) {
   const { files } = submitResponse.result
 

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

@@ -1,8 +1,12 @@
-import { type SubmitResponsePayload } from '@defra/forms-model'
+import {
+  type FormMetadata,
+  type SubmitResponsePayload
+} from '@defra/forms-model'
 
 import { type 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'
+import { format as formatAdapterV1 } from '~/src/server/plugins/engine/outputFormatters/adapter/v1.js'
 import { format as formatHumanV1 } from '~/src/server/plugins/engine/outputFormatters/human/v1.js'
 import { format as formatMachineV1 } from '~/src/server/plugins/engine/outputFormatters/machine/v1.js'
 import { format as formatMachineV2 } from '~/src/server/plugins/engine/outputFormatters/machine/v2.js'
@@ -13,12 +17,13 @@ type Formatter = (
   items: DetailItem[],
   model: FormModel,
   submitResponse: SubmitResponsePayload,
-  formStatus: ReturnType<typeof checkFormStatus>
+  formStatus: ReturnType<typeof checkFormStatus>,
+  formMetadata?: FormMetadata
 ) => string
 
 const formatters: Record<
   string,
-  Record<string, Formatter | undefined> | undefined
+  Record<string, Formatter | typeof formatAdapterV1 | undefined> | undefined
 > = {
   human: {
     '1': formatHumanV1
@@ -26,6 +31,9 @@ const formatters: Record<
   machine: {
     '1': formatMachineV1,
     '2': formatMachineV2
+  },
+  adapter: {
+    '1': formatAdapterV1
   }
 }
 

package/src/server/plugins/engine/outputFormatters/machine/v1.ts

@@ -1,4 +1,7 @@
-import { type SubmitResponsePayload } from '@defra/forms-model'
+import {
+  type FormMetadata,
+  type SubmitResponsePayload
+} from '@defra/forms-model'
 
 import { config } from '~/src/config/index.js'
 import { getAnswer } from '~/src/server/plugins/engine/components/helpers.js'
@@ -19,7 +22,8 @@ export function format(
   items: DetailItem[],
   model: FormModel,
   _submitResponse: SubmitResponsePayload,
-  _formStatus: ReturnType<typeof checkFormStatus>
+  _formStatus: ReturnType<typeof checkFormStatus>,
+  _formMetadata?: FormMetadata
 ) {
   const now = new Date()
 

package/src/server/plugins/engine/outputFormatters/machine/v2.ts

@@ -150,7 +150,7 @@ type FileUploadFieldDetailitem = Omit<DetailItemField, 'field'> & {
   field: FileUploadField
 }
 
-type RichFormValue =
+export type RichFormValue =
   | FormValue
   | FormPayload
   | DatePartsState

package/src/server/plugins/engine/pageControllers/SummaryPageController.ts

@@ -1,5 +1,6 @@
 import {
   hasComponentsEvenIfNoNext,
+  type FormMetadata,
   type Page,
   type SubmitPayload
 } from '@defra/forms-model'
@@ -111,7 +112,8 @@ export class SummaryPageController extends QuestionPageController {
       const { getFormMetadata } = formsService
 
       // Get the form metadata using the `slug` param
-      const { notificationEmail } = await getFormMetadata(params.slug)
+      const formMetadata = await getFormMetadata(params.slug)
+      const { notificationEmail } = formMetadata
       const { isPreview } = checkFormStatus(request.params)
       const emailAddress = notificationEmail ?? this.model.def.outputEmail
 
@@ -120,7 +122,14 @@ export class SummaryPageController extends QuestionPageController {
       // Send submission email
       if (emailAddress) {
         const viewModel = this.getSummaryViewModel(request, context)
-        await submitForm(context, request, viewModel, model, emailAddress)
+        await submitForm(
+          context,
+          request,
+          viewModel,
+          model,
+          emailAddress,
+          formMetadata
+        )
       }
 
       await cacheService.setConfirmationState(request, { confirmed: true })
@@ -150,7 +159,8 @@ async function submitForm(
   request: FormRequestPayload,
   summaryViewModel: SummaryViewModel,
   model: FormModel,
-  emailAddress: string
+  emailAddress: string,
+  formMetadata: FormMetadata
 ) {
   await extendFileRetention(model, context.state, emailAddress)
 
@@ -184,7 +194,8 @@ async function submitForm(
     model,
     emailAddress,
     items,
-    submitResponse
+    submitResponse,
+    formMetadata
   )
 }
 

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()
+    })
+  })
+})