@defra/forms-engine-plugin 4.0.43 → 4.0.44

package/src/server/plugins/engine/pageControllers/helpers/submission.test.ts

@@ -0,0 +1,299 @@
+import { PaymentField } from '~/src/server/plugins/engine/components/PaymentField.js'
+import { TextField } from '~/src/server/plugins/engine/components/TextField.js'
+import { type DetailItemField } from '~/src/server/plugins/engine/models/types.js'
+import {
+  buildMainRecords,
+  buildPaymentRecords,
+  buildRepeaterRecords
+} from '~/src/server/plugins/engine/pageControllers/helpers/submission.js'
+import { type FormSubmissionState } from '~/src/server/plugins/engine/types.js'
+
+describe('Submission helpers', () => {
+  describe('buildPaymentRecords', () => {
+    it('should return empty array when no payment state exists', () => {
+      const mockPaymentField = Object.create(PaymentField.prototype)
+      mockPaymentField.getPaymentStateFromState = jest
+        .fn()
+        .mockReturnValue(undefined)
+
+      const item = {
+        name: 'payment',
+        label: 'Payment',
+        field: mockPaymentField,
+        state: {} as FormSubmissionState
+      } as unknown as DetailItemField
+
+      const result = buildPaymentRecords(item)
+
+      expect(result).toEqual([])
+      expect(mockPaymentField.getPaymentStateFromState).toHaveBeenCalledWith(
+        item.state
+      )
+    })
+
+    it('should return four records when payment state exists', () => {
+      const mockPaymentState = {
+        paymentId: 'pay_123',
+        description: 'Application fee',
+        amount: 150,
+        reference: 'REF-ABC-123',
+        preAuth: {
+          status: 'success',
+          createdAt: '2026-01-26T14:30:00.000Z'
+        }
+      }
+
+      const mockPaymentField = Object.create(PaymentField.prototype)
+      mockPaymentField.getPaymentStateFromState = jest
+        .fn()
+        .mockReturnValue(mockPaymentState)
+
+      const item = {
+        name: 'payment',
+        label: 'Payment',
+        field: mockPaymentField,
+        state: {} as FormSubmissionState
+      } as unknown as DetailItemField
+
+      const result = buildPaymentRecords(item)
+
+      expect(result).toHaveLength(4)
+      expect(result[0]).toEqual({
+        name: 'payment_paymentDescription',
+        title: 'Payment description',
+        value: 'Application fee'
+      })
+      expect(result[1]).toEqual({
+        name: 'payment_paymentAmount',
+        title: 'Payment amount',
+        value: '£150.00'
+      })
+      expect(result[2]).toEqual({
+        name: 'payment_paymentReference',
+        title: 'Payment reference',
+        value: 'REF-ABC-123'
+      })
+      expect(result[3].name).toBe('payment_paymentDate')
+      expect(result[3].title).toBe('Payment date')
+      // Date will be formatted, just check it's not empty
+      expect(result[3].value).not.toBe('')
+    })
+
+    it('should return empty date when preAuth.createdAt is missing', () => {
+      const mockPaymentState = {
+        paymentId: 'pay_123',
+        description: 'Application fee',
+        amount: 150,
+        reference: 'REF-ABC-123',
+        preAuth: {
+          status: 'success'
+          // createdAt is missing
+        }
+      }
+
+      const mockPaymentField = Object.create(PaymentField.prototype)
+      mockPaymentField.getPaymentStateFromState = jest
+        .fn()
+        .mockReturnValue(mockPaymentState)
+
+      const item = {
+        name: 'payment',
+        label: 'Payment',
+        field: mockPaymentField,
+        state: {} as FormSubmissionState
+      } as unknown as DetailItemField
+
+      const result = buildPaymentRecords(item)
+
+      expect(result[3]).toEqual({
+        name: 'payment_paymentDate',
+        title: 'Payment date',
+        value: ''
+      })
+    })
+  })
+
+  describe('buildMainRecords', () => {
+    it('should return empty array for empty items', () => {
+      const result = buildMainRecords([])
+      expect(result).toEqual([])
+    })
+
+    it('should process regular fields correctly', () => {
+      const mockTextField = Object.create(TextField.prototype)
+      mockTextField.getDisplayStringFromState = jest
+        .fn()
+        .mockReturnValue('John Doe')
+      mockTextField.getContextValueFromState = jest
+        .fn()
+        .mockReturnValue('John Doe')
+
+      const items = [
+        {
+          name: 'fullName',
+          label: 'Full name',
+          field: mockTextField,
+          state: { fullName: 'John Doe' } as FormSubmissionState
+        }
+      ] as unknown as DetailItemField[]
+
+      const result = buildMainRecords(items)
+
+      expect(result).toHaveLength(1)
+      expect(result[0]).toEqual({
+        name: 'fullName',
+        title: 'Full name',
+        value: 'John Doe'
+      })
+    })
+
+    it('should expand PaymentField into four records', () => {
+      const mockPaymentState = {
+        paymentId: 'pay_123',
+        description: 'Licence fee',
+        amount: 75.5,
+        reference: 'LIC-999',
+        preAuth: {
+          status: 'success',
+          createdAt: '2026-01-26T10:00:00.000Z'
+        }
+      }
+
+      const mockPaymentField = Object.create(PaymentField.prototype)
+      mockPaymentField.getPaymentStateFromState = jest
+        .fn()
+        .mockReturnValue(mockPaymentState)
+
+      const items = [
+        {
+          name: 'licencePayment',
+          label: 'Licence Payment',
+          field: mockPaymentField,
+          state: {} as FormSubmissionState
+        }
+      ] as unknown as DetailItemField[]
+
+      const result = buildMainRecords(items)
+
+      expect(result).toHaveLength(4)
+      expect(result.map((r) => r.name)).toEqual([
+        'licencePayment_paymentDescription',
+        'licencePayment_paymentAmount',
+        'licencePayment_paymentReference',
+        'licencePayment_paymentDate'
+      ])
+    })
+
+    it('should handle mixed regular and payment fields', () => {
+      const mockTextField = Object.create(TextField.prototype)
+      mockTextField.getDisplayStringFromState = jest
+        .fn()
+        .mockReturnValue('test@example.com')
+      mockTextField.getContextValueFromState = jest
+        .fn()
+        .mockReturnValue('test@example.com')
+
+      const mockPaymentState = {
+        paymentId: 'pay_456',
+        description: 'Registration fee',
+        amount: 25,
+        reference: 'REG-001',
+        preAuth: { status: 'success', createdAt: '2026-01-26T12:00:00.000Z' }
+      }
+
+      const mockPaymentField = Object.create(PaymentField.prototype)
+      mockPaymentField.getPaymentStateFromState = jest
+        .fn()
+        .mockReturnValue(mockPaymentState)
+
+      const items = [
+        {
+          name: 'email',
+          label: 'Email address',
+          field: mockTextField,
+          state: { email: 'test@example.com' } as FormSubmissionState
+        },
+        {
+          name: 'payment',
+          label: 'Payment',
+          field: mockPaymentField,
+          state: {} as FormSubmissionState
+        }
+      ] as unknown as DetailItemField[]
+
+      const result = buildMainRecords(items)
+
+      // 1 regular field + 4 payment fields = 5 records
+      expect(result).toHaveLength(5)
+      expect(result[0].name).toBe('email')
+      expect(result[1].name).toBe('payment_paymentDescription')
+    })
+
+    it('should skip repeater items (items with subItems)', () => {
+      const repeaterItem = {
+        name: 'addresses',
+        label: 'Addresses',
+        subItems: [[]]
+      }
+
+      const result = buildMainRecords([
+        repeaterItem as unknown as DetailItemField
+      ])
+
+      expect(result).toEqual([])
+    })
+  })
+
+  describe('buildRepeaterRecords', () => {
+    it('should return empty array when no repeater items', () => {
+      const mockField = Object.create(TextField.prototype)
+
+      const items = [
+        {
+          name: 'textField',
+          label: 'Text',
+          field: mockField,
+          state: {} as FormSubmissionState
+        }
+      ]
+
+      const result = buildRepeaterRecords(items as unknown as DetailItemField[])
+
+      expect(result).toEqual([])
+    })
+
+    it('should process repeater items correctly', () => {
+      const mockSubField = Object.create(TextField.prototype)
+      mockSubField.getDisplayStringFromState = jest
+        .fn()
+        .mockReturnValue('123 Main St')
+      mockSubField.getContextValueFromState = jest
+        .fn()
+        .mockReturnValue('123 Main St')
+
+      const items = [
+        {
+          name: 'addresses',
+          label: 'Addresses',
+          subItems: [
+            [
+              {
+                name: 'street',
+                label: 'Street',
+                field: mockSubField,
+                state: { street: '123 Main St' } as FormSubmissionState
+              }
+            ]
+          ]
+        }
+      ]
+
+      const result = buildRepeaterRecords(items as unknown as DetailItemField[])
+
+      expect(result).toHaveLength(1)
+      expect(result[0].name).toBe('addresses')
+      expect(result[0].title).toBe('Addresses')
+      expect(result[0].value).toHaveLength(1)
+    })
+  })
+})

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

@@ -0,0 +1,110 @@
+import { type SubmitPayload } from '@defra/forms-model'
+
+import { PaymentField } from '~/src/server/plugins/engine/components/PaymentField.js'
+import { getAnswer } from '~/src/server/plugins/engine/components/helpers/components.js'
+import {
+  type DetailItem,
+  type DetailItemField
+} from '~/src/server/plugins/engine/models/types.js'
+import {
+  formatPaymentAmount,
+  formatPaymentDate
+} from '~/src/server/plugins/payment/helper.js'
+
+export interface SubmitRecord {
+  name: string
+  title: string
+  value: string
+}
+
+/**
+ * Builds the main submission records from field items.
+ * Regular fields are converted to single records, while PaymentField
+ * components are expanded into four separate records.
+ */
+export function buildMainRecords(items: DetailItem[]): SubmitRecord[] {
+  const fieldItems = items.filter(
+    (item): item is DetailItemField => 'field' in item
+  )
+
+  const records: SubmitRecord[] = []
+
+  for (const item of fieldItems) {
+    if (item.field instanceof PaymentField) {
+      records.push(...buildPaymentRecords(item))
+    } else {
+      records.push({
+        name: item.name,
+        title: item.label,
+        value: getAnswer(item.field, item.state, { format: 'data' })
+      })
+    }
+  }
+
+  return records
+}
+
+/**
+ * Expands a PaymentField into four submission records:
+ * - Payment description
+ * - Payment amount (formatted with currency symbol)
+ * - Payment reference
+ * - Payment date (formatted date/time)
+ *
+ * Returns an empty array if no payment state exists.
+ */
+export function buildPaymentRecords(item: DetailItemField): SubmitRecord[] {
+  const paymentState = (item.field as PaymentField).getPaymentStateFromState(
+    item.state
+  )
+
+  if (!paymentState) {
+    return []
+  }
+
+  return [
+    {
+      name: `${item.name}_paymentDescription`,
+      title: 'Payment description',
+      value: paymentState.description
+    },
+    {
+      name: `${item.name}_paymentAmount`,
+      title: 'Payment amount',
+      value: formatPaymentAmount(paymentState.amount)
+    },
+    {
+      name: `${item.name}_paymentReference`,
+      title: 'Payment reference',
+      value: paymentState.reference
+    },
+    {
+      name: `${item.name}_paymentDate`,
+      title: 'Payment date',
+      value: paymentState.preAuth?.createdAt
+        ? formatPaymentDate(paymentState.preAuth.createdAt)
+        : ''
+    }
+  ]
+}
+
+/**
+ * Builds the repeater submission records from repeater items.
+ */
+export function buildRepeaterRecords(
+  items: DetailItem[]
+): SubmitPayload['repeaters'] {
+  return items
+    .filter((item) => 'subItems' in item)
+    .map((item) => ({
+      name: item.name,
+      title: item.label,
+      value: item.subItems.map((detailItems) =>
+        detailItems.map((subItem) => ({
+          name: subItem.name,
+          title: subItem.label,
+          value: getAnswer(subItem.field, subItem.state, { format: 'data' })
+        }))
+      )
+    }))
+}

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

@@ -10,6 +10,7 @@ import { type FormModel } from '~/src/server/plugins/engine/models/index.js'
 import { validatePluginOptions } from '~/src/server/plugins/engine/options.js'
 import { getRoutes as getFileUploadStatusRoutes } from '~/src/server/plugins/engine/routes/file-upload.js'
 import { makeLoadFormPreHandler } from '~/src/server/plugins/engine/routes/index.js'
+import { getRoutes as getPaymentRoutes } from '~/src/server/plugins/engine/routes/payment.js'
 import { getRoutes as getQuestionRoutes } from '~/src/server/plugins/engine/routes/questions.js'
 import { getRoutes as getRepeaterItemDeleteRoutes } from '~/src/server/plugins/engine/routes/repeaters/item-delete.js'
 import { getRoutes as getRepeaterSummaryRoutes } from '~/src/server/plugins/engine/routes/repeaters/summary.js'
@@ -39,6 +40,7 @@ export const plugin = {
       preparePageEventRequestOptions,
       onRequest,
       ordnanceSurveyApiKey,
+      baseUrl,
       ordnanceSurveyApiSecret
     } = options
 
@@ -74,6 +76,7 @@ export const plugin = {
     server.expose('viewContext', viewContext)
     server.expose('cacheService', cacheService)
     server.expose('saveAndExit', saveAndExit)
+    server.expose('baseUrl', baseUrl)
 
     server.app.model = model
 
@@ -106,19 +109,21 @@ export const plugin = {
     }
 
     const routes = [
-      ...getQuestionRoutes(
+      ...getPaymentRoutes(),
+      ...getFileUploadStatusRoutes(),
+      ...getRepeaterSummaryRoutes(getRouteOptions, postRouteOptions, onRequest),
+      ...getRepeaterItemDeleteRoutes(
         getRouteOptions,
         postRouteOptions,
-        preparePageEventRequestOptions,
         onRequest
       ),
-      ...getRepeaterSummaryRoutes(getRouteOptions, postRouteOptions, onRequest),
-      ...getRepeaterItemDeleteRoutes(
+
+      ...getQuestionRoutes(
         getRouteOptions,
         postRouteOptions,
+        preparePageEventRequestOptions,
         onRequest
-      ),
-      ...getFileUploadStatusRoutes()
+      )
     ]
 
     server.route(routes as unknown as ServerRoute[]) // TODO

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

@@ -119,6 +119,7 @@ async function importExternalComponentState(
   const typedStateAppendage = externalComponentData as ExternalStateAppendage
   const componentName = typedStateAppendage.component
   const stateAppendage = typedStateAppendage.data
+
   const component = request.app.model?.componentMap.get(componentName)
 
   if (!component) {
@@ -137,22 +138,22 @@ async function importExternalComponentState(
     throw new Error(`State for component ${componentName} is invalid`)
   }
 
-  const componentState = isFormState(stateAppendage)
-    ? Object.fromEntries(
-        Object.entries(stateAppendage).map(([key, value]) => [
-          `${componentName}__${key}`,
-          value
-        ])
-      )
-    : { [componentName]: stateAppendage }
-
-  // Save the external component state immediately
-  const pageState = page.getStateFromValidForm(
-    request,
-    state,
-    componentState as FormPayload
-  )
-  const savedState = await page.mergeState(request, state, pageState)
+  // Create state structure from appendage state
+  // Some components use a record structure with properties of the format of '<compName>__<fieldName>'
+  // e.g. UKAddressField
+  // Some components use a single object structure e.g. PaymentField
+  const componentState =
+    isFormState(stateAppendage) && !component.isAppendageStateSingleObject
+      ? Object.fromEntries(
+          Object.entries(stateAppendage).map(([key, value]) => [
+            `${componentName}__${key}`,
+            value
+          ])
+        )
+      : { [componentName]: stateAppendage }
+
+  // Save the external component state directly (already has correct key format)
+  const savedState = await page.mergeState(request, state, componentState)
 
   // Merge any stashed payload into the local state
   const payload = request.yar.flash(EXTERNAL_STATE_PAYLOAD)

package/src/server/plugins/engine/routes/payment-helper.js

@@ -0,0 +1,39 @@
+import Boom from '@hapi/boom'
+
+import { PAYMENT_SESSION_PREFIX } from '~/src/server/plugins/engine/routes/payment.js'
+import { getPaymentApiKey } from '~/src/server/plugins/payment/helper.js'
+import { PaymentService } from '~/src/server/plugins/payment/service.js'
+
+/**
+ * Validates session data and retrieves payment status
+ * @param {Request} request - the request
+ * @param {string} uuid - the payment UUID
+ * @returns {Promise<{ session: PaymentSessionData, sessionKey: string, paymentStatus: GetPaymentResponse }>}
+ */
+export async function getPaymentContext(request, uuid) {
+  const sessionKey = `${PAYMENT_SESSION_PREFIX}${uuid}`
+  const session = /** @type {PaymentSessionData | null} */ (
+    request.yar.get(sessionKey)
+  )
+
+  if (!session) {
+    throw Boom.badRequest(`No payment session found for uuid=${uuid}`)
+  }
+
+  const { paymentId, isLivePayment, formId } = session
+
+  if (!paymentId) {
+    throw Boom.badRequest('No paymentId in session')
+  }
+
+  const apiKey = getPaymentApiKey(isLivePayment, formId)
+  const paymentService = new PaymentService(apiKey)
+  const paymentStatus = await paymentService.getPaymentStatus(paymentId)
+
+  return { session, sessionKey, paymentStatus }
+}
+
+/**
+ * @import { Request } from '@hapi/hapi'
+ * @import { GetPaymentResponse, PaymentSessionData } from '~/src/server/plugins/payment/types.js'
+ */

package/src/server/plugins/engine/routes/payment-helper.test.js

@@ -0,0 +1,90 @@
+import { getPaymentContext } from '~/src/server/plugins/engine/routes/payment-helper.js'
+import { get } from '~/src/server/services/httpService.js'
+
+jest.mock('~/src/server/services/httpService.ts')
+
+describe('payment helper', () => {
+  const uuid = '5a54c2fe-da49-4202-8cd3-2121eaca03c3'
+  it('should throw if no session', async () => {
+    const mockRequest = {
+      yar: {
+        get: jest.fn().mockReturnValueOnce(undefined)
+      }
+    }
+    // @ts-expect-error - partial request mock
+    await expect(() => getPaymentContext(mockRequest, uuid)).rejects.toThrow(
+      'No payment session found for uuid=5a54c2fe-da49-4202-8cd3-2121eaca03c3'
+    )
+  })
+
+  it('should throw if no payment id', async () => {
+    const mockRequest = {
+      yar: {
+        get: jest.fn().mockReturnValueOnce({})
+      }
+    }
+    // @ts-expect-error - partial request mock
+    await expect(() => getPaymentContext(mockRequest, uuid)).rejects.toThrow(
+      'No paymentId in session'
+    )
+  })
+
+  it('should get context successfully', async () => {
+    const mockRequest = {
+      yar: {
+        get: jest.fn().mockReturnValueOnce({
+          paymentId: 'payment-id',
+          isLivePayment: false,
+          formId: 'formid'
+        })
+      }
+    }
+
+    const getPaymentStatusApiResult = {
+      payment_id: 'payment-id-12345',
+      _links: {
+        next_url: {
+          href: 'http://next-url-href/payment'
+        }
+      },
+      state: {
+        status: 'created'
+      }
+    }
+
+    jest.mocked(get).mockResolvedValueOnce({
+      res: /** @type {IncomingMessage} */ ({
+        statusCode: 200,
+        headers: {}
+      }),
+      payload: getPaymentStatusApiResult,
+      error: undefined
+    })
+
+    // @ts-expect-error - partial request mock
+    const res = await getPaymentContext(mockRequest, uuid)
+    expect(res).toEqual({
+      paymentStatus: {
+        paymentId: 'payment-id-12345',
+        _links: {
+          next_url: {
+            href: 'http://next-url-href/payment'
+          }
+        },
+        state: {
+          status: 'created'
+        }
+      },
+      session: {
+        formId: 'formid',
+        isLivePayment: false,
+        paymentId: 'payment-id'
+      },
+      sessionKey: 'payment-5a54c2fe-da49-4202-8cd3-2121eaca03c3'
+    })
+  })
+})
+
+/**
+ * @import  { IncomingMessage } from 'node:http'
+ */