@defra/forms-engine-plugin 2.1.4 → 2.1.6

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

@@ -1,5 +1,6 @@
 import {
   hasComponentsEvenIfNoNext,
+  type FormMetadata,
   type Page,
   type SubmitPayload
 } from '@defra/forms-model'
@@ -8,7 +9,7 @@ import { type ResponseToolkit, type RouteOptions } from '@hapi/hapi'
 
 import { ComponentCollection } from '~/src/server/plugins/engine/components/ComponentCollection.js'
 import { FileUploadField } from '~/src/server/plugins/engine/components/FileUploadField.js'
-import { getAnswer } from '~/src/server/plugins/engine/components/helpers.js'
+import { getAnswer } from '~/src/server/plugins/engine/components/helpers/components.js'
 import {
   checkEmailAddressForLiveFormSubmission,
   checkFormStatus,
@@ -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/pageControllers/{helpers.test.ts → helpers/helpers.test.ts}

@@ -8,12 +8,12 @@ import {
 
 import { FormModel } from '~/src/server/plugins/engine/models/FormModel.js'
 import { PageController } from '~/src/server/plugins/engine/pageControllers/PageController.js'
+import { getProxyUrlForLocalDevelopment } from '~/src/server/plugins/engine/pageControllers/helpers/index.js'
 import {
   createPage,
-  getProxyUrlForLocalDevelopment,
   isPageController,
   type PageControllerType
-} from '~/src/server/plugins/engine/pageControllers/helpers.js'
+} from '~/src/server/plugins/engine/pageControllers/helpers/pages.js'
 import {
   FileUploadPageController,
   QuestionPageController,

package/src/server/plugins/engine/pageControllers/helpers/index.ts

@@ -0,0 +1,20 @@
+/**
+ * In local development environments, we sometimes need to rewrite the
+ * CDP upload URL to work with CSP/CORS restrictions.
+ * This helper function rewrites localhost URLs to use the sslip.io proxy
+ * This is only used when running locally with a development proxy.
+ * In non-local environments, this function returns null
+ * @param uploadUrl - The original upload URL from CDP
+ */
+export function getProxyUrlForLocalDevelopment(
+  uploadUrl?: string
+): string | null {
+  if (!uploadUrl?.includes('localhost:7337')) {
+    return null
+  }
+
+  return uploadUrl.replace(
+    /localhost:7337/g,
+    'uploader.127.0.0.1.sslip.io:7300'
+  )
+}

package/src/server/plugins/engine/pageControllers/{helpers.ts → helpers/pages.ts}

@@ -5,7 +5,7 @@ import {
   type Page
 } from '@defra/forms-model'
 
-import { type FormModel } from '~/src/server/plugins/engine/models/FormModel.js'
+import { type FormModel } from '~/src/server/plugins/engine/models/index.js'
 import * as PageControllers from '~/src/server/plugins/engine/pageControllers/index.js'
 
 export function isPageController(
@@ -78,24 +78,3 @@ export function createPage(model: FormModel, pageDef: Page) {
 
   return controller
 }
-
-/**
- * In local development environments, we sometimes need to rewrite the
- * CDP upload URL to work with CSP/CORS restrictions.
- * This helper function rewrites localhost URLs to use the sslip.io proxy
- * This is only used when running locally with a development proxy.
- * In non-local environments, this function returns null
- * @param uploadUrl - The original upload URL from CDP
- */
-export function getProxyUrlForLocalDevelopment(
-  uploadUrl?: string
-): string | null {
-  if (!uploadUrl?.includes('localhost:7337')) {
-    return null
-  }
-
-  return uploadUrl.replace(
-    /localhost:7337/g,
-    'uploader.127.0.0.1.sslip.io:7300'
-  )
-}

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

@@ -17,7 +17,7 @@ import {
   proceed
 } from '~/src/server/plugins/engine/helpers.js'
 import { FormModel } from '~/src/server/plugins/engine/models/index.js'
-import { type PageControllerClass } from '~/src/server/plugins/engine/pageControllers/helpers.js'
+import { type PageControllerClass } from '~/src/server/plugins/engine/pageControllers/helpers/pages.js'
 import { generateUniqueReference } from '~/src/server/plugins/engine/referenceNumbers.js'
 import * as defaultServices from '~/src/server/plugins/engine/services/index.js'
 import {

package/src/server/plugins/engine/routes/questions.test.ts

@@ -4,7 +4,7 @@ import { type ResponseObject, type ResponseToolkit } from '@hapi/hapi'
 import nock from 'nock'
 
 import { type FormModel } from '~/src/server/plugins/engine/models/FormModel.js'
-import { type PageControllerClass } from '~/src/server/plugins/engine/pageControllers/helpers.js'
+import { type PageControllerClass } from '~/src/server/plugins/engine/pageControllers/helpers/pages.js'
 import { redirectOrMakeHandler } from '~/src/server/plugins/engine/routes/index.js'
 import {
   makeGetHandler,

package/src/server/plugins/engine/routes/questions.ts

@@ -19,7 +19,7 @@ import {
 } from '~/src/server/plugins/engine/models/index.js'
 import { format } from '~/src/server/plugins/engine/outputFormatters/machine/v1.js'
 import { getFormSubmissionData } from '~/src/server/plugins/engine/pageControllers/SummaryPageController.js'
-import { type PageControllerClass } from '~/src/server/plugins/engine/pageControllers/helpers.js'
+import { type PageControllerClass } from '~/src/server/plugins/engine/pageControllers/helpers/pages.js'
 import {
   dispatchHandler,
   redirectOrMakeHandler

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/index.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,7 +1,11 @@
-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'
+import { escapeMarkdown } from '~/src/server/plugins/engine/components/helpers/index.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'
@@ -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()
+    })
+  })
+})