@defra/forms-engine-plugin 4.0.43 → 4.0.44

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

@@ -11,133 +11,135 @@ import { buildFormContextRequest } from '~/src/server/plugins/engine/pageControl
 import { FormStatus } from '~/src/server/routes/types.js'
 import definition from '~/test/form/definitions/repeat-mixed.js'
 
-const itemId1 = 'abc-123'
-const itemId2 = 'xyz-987'
-
-const submitResponse = {
-  message: 'Submit completed',
-  result: {
-    files: {
-      main: '00000000-0000-0000-0000-000000000000',
-      repeaters: {
-        pizza: '11111111-1111-1111-1111-111111111111'
+describe('v1 human formatter', () => {
+  const itemId1 = 'abc-123'
+  const itemId2 = 'xyz-987'
+
+  const submitResponse = {
+    message: 'Submit completed',
+    result: {
+      files: {
+        main: '00000000-0000-0000-0000-000000000000',
+        repeaters: {
+          pizza: '11111111-1111-1111-1111-111111111111'
+        }
       }
     }
   }
-}
 
-const model = new FormModel(definition, {
-  basePath: 'test'
-})
+  const model = new FormModel(definition, {
+    basePath: 'test'
+  })
 
-const state = {
-  $$__referenceNumber: 'foobar',
-  orderType: 'delivery',
-  pizza: [
-    {
-      toppings: 'Ham',
-      quantity: 2,
-      itemId: itemId1
-    },
-    {
-      toppings: 'Pepperoni',
-      quantity: 1,
-      itemId: itemId2
-    }
-  ]
-}
-
-const pageDef = definition.pages[2]
-const pageUrl = new URL('http://example.com/repeat/pizza-order/summary')
-
-const controller = new SummaryPageController(model, pageDef)
-
-const request = buildFormContextRequest({
-  method: 'get',
-  url: pageUrl,
-  path: pageUrl.pathname,
-  params: {
-    path: 'pizza-order',
-    slug: 'repeat'
-  },
-  query: {},
-  app: { model }
-})
+  const state = {
+    $$__referenceNumber: 'foobar',
+    orderType: 'delivery',
+    pizza: [
+      {
+        toppings: 'Ham',
+        quantity: 2,
+        itemId: itemId1
+      },
+      {
+        toppings: 'Pepperoni',
+        quantity: 1,
+        itemId: itemId2
+      }
+    ]
+  }
 
-const context = model.getFormContext(request, state)
-const summaryViewModel = controller.getSummaryViewModel(request, context)
+  const pageDef = definition.pages[2]
+  const pageUrl = new URL('http://example.com/repeat/pizza-order/summary')
 
-const items = getFormSubmissionData(
-  summaryViewModel.context,
-  summaryViewModel.details
-)
+  const controller = new SummaryPageController(model, pageDef)
 
-describe('getPersonalisation', () => {
-  it.each([
-    {
-      state: FormStatus.Live,
-      isPreview: false
+  const request = buildFormContextRequest({
+    method: 'get',
+    url: pageUrl,
+    path: pageUrl.pathname,
+    params: {
+      path: 'pizza-order',
+      slug: 'repeat'
     },
-    {
-      state: FormStatus.Draft,
-      isPreview: true
-    }
-  ])('should personalise $state email', (formStatus) => {
-    const body = format(context, items, model, submitResponse, formStatus)
-
-    const dateNow = new Date()
-    const dateExpiry = addDays(dateNow, 90)
+    query: {},
+    app: { model }
+  })
 
-    // Check for link expiry message
-    expect(body).toContain(
-      `^ For security reasons, the links in this email expire at ${dateFormat(dateExpiry, 'h:mmaaa')} on ${dateFormat(dateExpiry, 'eeee d MMMM yyyy')}`
-    )
+  const context = model.getFormContext(request, state)
+  const summaryViewModel = controller.getSummaryViewModel(request, context)
+
+  const items = getFormSubmissionData(
+    summaryViewModel.context,
+    summaryViewModel.details
+  )
+
+  describe('getPersonalisation', () => {
+    it.each([
+      {
+        state: FormStatus.Live,
+        isPreview: false
+      },
+      {
+        state: FormStatus.Draft,
+        isPreview: true
+      }
+    ])('should personalise $state email', (formStatus) => {
+      const body = format(context, items, model, submitResponse, formStatus)
 
-    expect(body).toContain(
-      outdent`
-            ${definition.name} form received at ${dateFormat(dateNow, 'h:mmaaa')} on ${dateFormat(dateNow, 'd MMMM yyyy')}.
+      const dateNow = new Date()
+      const dateExpiry = addDays(dateNow, 90)
 
-            ---
+      // Check for link expiry message
+      expect(body).toContain(
+        `^ For security reasons, the links in this email expire at ${dateFormat(dateExpiry, 'h:mmaaa')} on ${dateFormat(dateExpiry, 'eeee d MMMM yyyy')}`
+      )
 
-            ## How would you like to receive your pizza?
+      expect(body).toContain(
+        outdent`
+              ${definition.name} form received at ${dateFormat(dateNow, 'h:mmaaa')} on ${dateFormat(dateNow, 'd MMMM yyyy')}.
 
-            Delivery
+              ---
 
-            ---
+              ## How would you like to receive your pizza?
 
-            ## Pizza
+              Delivery
 
-            [Download Pizza \\(CSV\\)](https://forms-designer/file-download/11111111-1111-1111-1111-111111111111)
+              ---
 
-            ---
+              ## Pizza
 
-            [Download main form \\(CSV\\)](https://forms-designer/file-download/00000000-0000-0000-0000-000000000000)
-          `
-    )
-  })
+              [Download Pizza \\(CSV\\)](https://forms-designer/file-download/11111111-1111-1111-1111-111111111111)
 
-  it('should add test warnings to preview email only', () => {
-    const formStatus = {
-      state: FormStatus.Draft,
-      isPreview: true
-    }
+              ---
 
-    const body1 = format(context, items, model, submitResponse, {
-      state: FormStatus.Live,
-      isPreview: false
+              [Download main form \\(CSV\\)](https://forms-designer/file-download/00000000-0000-0000-0000-000000000000)
+            `
+      )
     })
 
-    const body2 = format(context, items, model, submitResponse, {
-      state: FormStatus.Draft,
-      isPreview: true
-    })
+    it('should add test warnings to preview email only', () => {
+      const formStatus = {
+        state: FormStatus.Draft,
+        isPreview: true
+      }
+
+      const body1 = format(context, items, model, submitResponse, {
+        state: FormStatus.Live,
+        isPreview: false
+      })
 
-    expect(body1).not.toContain(
-      `This is a test of the ${definition.name} ${formStatus.state} form`
-    )
+      const body2 = format(context, items, model, submitResponse, {
+        state: FormStatus.Draft,
+        isPreview: true
+      })
 
-    expect(body2).toContain(
-      `This is a test of the ${definition.name} ${formStatus.state} form`
-    )
+      expect(body1).not.toContain(
+        `This is a test of the ${definition.name} ${formStatus.state} form`
+      )
+
+      expect(body2).toContain(
+        `This is a test of the ${definition.name} ${formStatus.state} form`
+      )
+    })
   })
 })

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

@@ -7,10 +7,18 @@ import { addDays, format as dateFormat } from 'date-fns'
 import { config } from '~/src/config/index.js'
 import { getAnswer } from '~/src/server/plugins/engine/components/helpers/components.js'
 import { escapeMarkdown } from '~/src/server/plugins/engine/components/helpers/index.js'
+import { PaymentField } from '~/src/server/plugins/engine/components/index.js'
 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 {
+  type DetailItem,
+  type DetailItemField
+} from '~/src/server/plugins/engine/models/types.js'
 import { type FormContext } from '~/src/server/plugins/engine/types.js'
+import {
+  formatPaymentAmount,
+  formatPaymentDate
+} from '~/src/server/plugins/payment/helper.js'
 
 const designerUrl = config.get('designerUrl')
 
@@ -49,7 +57,10 @@ export function format(
   lines.push(`${formName} form received at ${escapeMarkdown(formattedNow)}.\n`)
   lines.push('---\n')
 
-  items.forEach((item) => {
+  const regularItems = items.filter((item) => !isPaymentItem(item))
+  const paymentItems = items.filter((item) => isPaymentItem(item))
+
+  regularItems.forEach((item) => {
     const label = escapeMarkdown(item.label)
 
     lines.push(`## ${label}\n`)
@@ -73,5 +84,53 @@ export function format(
   const filename = escapeMarkdown('Download main form (CSV)')
   lines.push(`[${filename}](${designerUrl}/file-download/${files.main})\n`)
 
+  appendPaymentSection(paymentItems, lines)
+
   return lines.join('\n')
 }
+
+/**
+ * Check if an item is a PaymentField
+ */
+function isPaymentItem(item: DetailItem): boolean {
+  if ('subItems' in item) {
+    return false
+  }
+  return item.field instanceof PaymentField
+}
+
+/**
+ * Appends the payment details section to the email lines if payment exists
+ */
+function appendPaymentSection(paymentItems: DetailItem[], lines: string[]) {
+  if (paymentItems.length === 0) {
+    return
+  }
+
+  const paymentItem = paymentItems[0] as DetailItemField
+  const paymentField = paymentItem.field as PaymentField
+  const paymentState = paymentField.getPaymentStateFromState(paymentItem.state)
+
+  if (!paymentState) {
+    return
+  }
+
+  const formattedAmount = formatPaymentAmount(paymentState.amount)
+  const dateOfPayment = paymentState.preAuth?.createdAt
+    ? formatPaymentDate(paymentState.preAuth.createdAt)
+    : ''
+
+  lines.push(
+    '---\n',
+    `# Your payment of ${formattedAmount} was successful\n`,
+    '## Payment for\n',
+    `${escapeMarkdown(paymentState.description)}\n`,
+    '---\n',
+    '## Total amount\n',
+    `${formattedAmount}\n`,
+    '---\n',
+    '## Date of payment\n',
+    `${escapeMarkdown(dateOfPayment)}\n`,
+    '---\n'
+  )
+}

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

@@ -0,0 +1,115 @@
+/* eslint-disable @typescript-eslint/no-unsafe-member-access */
+
+import { type PaymentState } from '~/src/server/plugins/engine/components/PaymentField.types.js'
+import { FormModel } from '~/src/server/plugins/engine/models/index.js'
+import { format } from '~/src/server/plugins/engine/outputFormatters/machine/v2.js'
+import {
+  SummaryPageController,
+  getFormSubmissionData
+} from '~/src/server/plugins/engine/pageControllers/SummaryPageController.js'
+import { buildFormContextRequest } from '~/src/server/plugins/engine/pageControllers/__stubs__/request.js'
+import { type FormSubmissionState } from '~/src/server/plugins/engine/types.js'
+import { FormStatus } from '~/src/server/routes/types.js'
+import definition from '~/test/form/definitions/payment.js'
+
+const submitResponse = {
+  message: 'Submit completed',
+  result: {
+    files: {
+      main: '00000000-0000-0000-0000-000000000000',
+      repeaters: {
+        pizza: '11111111-1111-1111-1111-111111111111'
+      }
+    }
+  }
+}
+
+const model = new FormModel(definition, {
+  basePath: 'test'
+})
+
+const formStatus = {
+  isPreview: false,
+  state: FormStatus.Live
+}
+
+const state = {
+  $$__referenceNumber: 'foobar',
+  licenceLength: 365,
+  fullName: 'John Smith',
+  paymentField: {
+    paymentId: 'payment-id',
+    reference: 'payment-ref',
+    amount: 250,
+    description: 'Payment desc',
+    uuid: 'uuid',
+    formId: 'form-id',
+    isLivePayment: false,
+    preAuth: {
+      status: 'success',
+      createdAt: '2026-01-02T11:00:04+0000'
+    }
+  } as PaymentState
+}
+
+const pageUrl = new URL('http://example.com/repeat/pizza-order/summary')
+
+const request = buildFormContextRequest({
+  method: 'get',
+  url: pageUrl,
+  path: pageUrl.pathname,
+  params: {
+    path: 'summary',
+    slug: 'payment'
+  },
+  query: {},
+  app: { model }
+})
+
+const context = model.getFormContext(
+  request,
+  state as unknown as FormSubmissionState
+)
+
+const pageDef = definition.pages[2]
+
+const controller = new SummaryPageController(model, pageDef)
+
+const summaryViewModel = controller.getSummaryViewModel(request, context)
+
+const items = getFormSubmissionData(
+  summaryViewModel.context,
+  summaryViewModel.details
+)
+
+describe('getPersonalisation', () => {
+  it('should return the machine output', () => {
+    model.def = definition
+
+    const body = format(context, items, model, submitResponse, formStatus)
+
+    const parsedBody = JSON.parse(body)
+
+    const expectedData = {
+      main: {
+        licenceLength: 365,
+        fullName: 'John Smith'
+      },
+      payment: {
+        amount: 250,
+        createdAt: '2026-01-02T11:00:04+0000',
+        description: 'Payment desc',
+        paymentId: 'payment-id',
+        reference: 'payment-ref'
+      },
+      repeaters: {},
+      files: {}
+    }
+
+    expect(parsedBody.meta.schemaVersion).toBe('2')
+    expect(parsedBody.meta.timestamp).toBeDateString()
+    expect(parsedBody.meta.definition).toEqual(definition)
+    expect(parsedBody.meta.referenceNumber).toBe('foobar')
+    expect(parsedBody.data).toEqual(expectedData)
+  })
+})

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

@@ -1,7 +1,10 @@
 import { type SubmitResponsePayload } from '@defra/forms-model'
 
 import { config } from '~/src/config/index.js'
-import { FileUploadField } from '~/src/server/plugins/engine/components/index.js'
+import {
+  FileUploadField,
+  PaymentField
+} from '~/src/server/plugins/engine/components/index.js'
 import { type checkFormStatus } from '~/src/server/plugins/engine/helpers.js'
 import { type FormModel } from '~/src/server/plugins/engine/models/index.js'
 import {
@@ -16,6 +19,18 @@ import {
   type RichFormValue
 } from '~/src/server/plugins/engine/types.js'
 
+/**
+ * Payment data for the machine output format
+ * Defined locally to avoid circular dependency with types.ts
+ */
+interface PaymentOutput {
+  paymentId: string
+  reference: string
+  amount: number
+  description: string
+  createdAt: string
+}
+
 const designerUrl = config.get('designerUrl')
 
 export function format(
@@ -71,6 +86,15 @@ export function format(
  *          userDownloadLink: 'https://forms-designer/file-download/123-456-789'
  *        }
  *      ]
+ *    },
+ *    payments: {
+ *      paymentComponentName: {
+ *        paymentId: 'abc123',
+ *        reference: 'REF-123',
+ *        amount: 10.00,
+ *        description: 'Application fee',
+ *        createdAt: '2025-01-23T10:30:00.000Z'
+ *      }
  *    }
  * }
  */
@@ -82,6 +106,7 @@ export function categoriseData(items: DetailItem[]) {
       string,
       { fileId: string; fileName: string; userDownloadLink: string }[]
     >
+    payment?: PaymentOutput
   } = { main: {}, repeaters: {}, files: {} }
 
   items.forEach((item) => {
@@ -91,6 +116,11 @@ export function categoriseData(items: DetailItem[]) {
       output.repeaters[name] = extractRepeaters(item)
     } else if (isFileUploadFieldItem(item)) {
       output.files[name] = extractFileUploads(item)
+    } else if (isPaymentFieldItem(item)) {
+      const payment = extractPayment(item)
+      if (payment) {
+        output.payment = payment
+      }
     } else {
       output.main[name] = item.field.getFormValueFromState(state)
     }
@@ -148,3 +178,32 @@ function isFileUploadFieldItem(
 ): item is FileUploadFieldDetailitem {
   return item.field instanceof FileUploadField
 }
+
+function isPaymentFieldItem(item: DetailItemField): item is DetailItemField & {
+  field: PaymentField
+} {
+  return item.field instanceof PaymentField
+}
+
+/**
+ * Returns the "payments" section of the response body
+ * @param item - the payment item in the form
+ * @returns the payment data
+ */
+function extractPayment(
+  item: DetailItemField & { field: PaymentField }
+): PaymentOutput | undefined {
+  const paymentState = item.field.getPaymentStateFromState(item.state)
+
+  if (!paymentState) {
+    return undefined
+  }
+
+  return {
+    paymentId: paymentState.paymentId,
+    reference: paymentState.reference,
+    amount: paymentState.amount,
+    description: paymentState.description,
+    createdAt: paymentState.preAuth?.createdAt ?? ''
+  }
+}

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

@@ -15,12 +15,14 @@ import { type ValidationErrorItem } from 'joi'
 import {
   COMPONENT_STATE_ERROR,
   EXTERNAL_STATE_APPENDAGE,
-  EXTERNAL_STATE_PAYLOAD
+  EXTERNAL_STATE_PAYLOAD,
+  PAYMENT_EXPIRED_NOTIFICATION
 } from '~/src/server/constants.js'
 import { ComponentCollection } from '~/src/server/plugins/engine/components/ComponentCollection.js'
 import { optionalText } from '~/src/server/plugins/engine/components/constants.js'
 import { type BackLink } from '~/src/server/plugins/engine/components/types.js'
 import {
+  checkFormStatus,
   getCacheService,
   getErrors,
   getSaveAndExitHelpers,
@@ -47,6 +49,7 @@ import {
 import { getComponentsByType } from '~/src/server/plugins/engine/validationHelpers.js'
 import {
   FormAction,
+  FormStatus,
   type FormRequest,
   type FormRequestPayload,
   type FormRequestPayloadRefs,
@@ -182,6 +185,16 @@ export class QuestionPageController extends PageController {
       }
     }
 
+    const hasIncompletePayment = components.some(({ model }) => {
+      if ('paymentState' in model) {
+        const paymentState = model.paymentState as
+          | { preAuth?: { status?: string } }
+          | undefined
+        return !paymentState?.preAuth?.status
+      }
+      return false
+    })
+
     return {
       ...viewModel,
       backLink: this.getBackLink(request, context),
@@ -189,7 +202,8 @@ export class QuestionPageController extends PageController {
       showTitle,
       components,
       errors,
-      allowSaveAndExit: this.shouldShowSaveAndExit(request.server)
+      allowSaveAndExit: this.shouldShowSaveAndExit(request.server),
+      showSubmitButton: !hasIncompletePayment
     }
   }
 
@@ -423,6 +437,12 @@ export class QuestionPageController extends PageController {
 
       viewModel.errors = (viewModel.errors ?? []).concat(flashedErrors)
 
+      const paymentExpiredFlash = request.yar.flash(
+        PAYMENT_EXPIRED_NOTIFICATION
+      )
+      viewModel.showPaymentExpiredNotification =
+        !Array.isArray(paymentExpiredFlash)
+
       /**
        * Content components can be hidden based on a condition. If the condition evaluates to true, it is safe to be kept, otherwise discard it
        */
@@ -517,7 +537,7 @@ export class QuestionPageController extends PageController {
       const action = request.payload.action
 
       if (action?.startsWith(FormAction.External)) {
-        return this.dispatchExternal(request, h, context)
+        return await this.dispatchExternal(request, h, context)
       }
 
       /**
@@ -551,7 +571,7 @@ export class QuestionPageController extends PageController {
     }
   }
 
-  private dispatchExternal(
+  private async dispatchExternal(
     request: FormRequestPayload,
     h: FormResponseToolkit,
     context: FormContext
@@ -602,11 +622,17 @@ export class QuestionPageController extends PageController {
     // Clear any previous state appendage
     request.yar.clear(EXTERNAL_STATE_APPENDAGE)
 
-    return selectedComponent.dispatcher(request, h, {
+    // Determine if this is a live form (not preview/draft)
+    const { state, isPreview } = checkFormStatus(request.params)
+    const isLive = state === FormStatus.Live
+
+    return await selectedComponent.dispatcher(request, h, {
       component,
       controller: this,
       sourceUrl: request.url.toString(),
-      actionArgs: args
+      actionArgs: args,
+      isLive,
+      isPreview
     })
   }