@defra/forms-engine-plugin 4.0.42 → 4.0.44

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

@@ -7,9 +7,12 @@ import {
 import Boom from '@hapi/boom'
 import { type RouteOptions } from '@hapi/hapi'
 
-import { COMPONENT_STATE_ERROR } from '~/src/server/constants.js'
+import {
+  COMPONENT_STATE_ERROR,
+  PAYMENT_EXPIRED_NOTIFICATION
+} from '~/src/server/constants.js'
 import { ComponentCollection } from '~/src/server/plugins/engine/components/ComponentCollection.js'
-import { getAnswer } from '~/src/server/plugins/engine/components/helpers/components.js'
+import { PaymentField } from '~/src/server/plugins/engine/components/PaymentField.js'
 import {
   checkEmailAddressForLiveFormSubmission,
   checkFormStatus,
@@ -22,15 +25,30 @@ import {
 } from '~/src/server/plugins/engine/models/index.js'
 import {
   type Detail,
-  type DetailItem
+  type DetailItem,
+  type DetailItemField
 } from '~/src/server/plugins/engine/models/types.js'
 import { QuestionPageController } from '~/src/server/plugins/engine/pageControllers/QuestionPageController.js'
-import { InvalidComponentStateError } from '~/src/server/plugins/engine/pageControllers/errors.js'
+import {
+  InvalidComponentStateError,
+  PaymentErrorTypes,
+  PaymentPreAuthError,
+  PaymentSubmissionError
+} from '~/src/server/plugins/engine/pageControllers/errors.js'
+import {
+  buildMainRecords,
+  buildRepeaterRecords
+} from '~/src/server/plugins/engine/pageControllers/helpers/submission.js'
 import {
   type FormConfirmationState,
   type FormContext,
   type FormContextRequest
 } from '~/src/server/plugins/engine/types.js'
+import {
+  DEFAULT_PAYMENT_HELP_URL,
+  formatPaymentAmount,
+  formatPaymentDate
+} from '~/src/server/plugins/payment/helper.js'
 import {
   FormAction,
   type FormRequest,
@@ -65,11 +83,25 @@ export class SummaryPageController extends QuestionPageController {
     const viewModel = new SummaryViewModel(request, this, context)
 
     const { query } = request
-    const { payload, errors } = context
+    const { payload, errors, state } = context
+
+    const paymentField = context.relevantPages
+      .flatMap((page) => page.collection.fields)
+      .find((field): field is PaymentField => field instanceof PaymentField)
+
+    if (paymentField) {
+      const paymentState = paymentField.getPaymentStateFromState(state)
+      if (paymentState) {
+        viewModel.paymentState = paymentState
+        viewModel.paymentDetails = this.buildPaymentDetails(
+          paymentField,
+          paymentState
+        )
+      }
+    }
+
     const components = this.collection.getViewModel(payload, errors, query)
 
-    // We already figure these out in the base page controller. Take them and apply them to our page-specific model.
-    // This is a stop-gap until we can add proper inheritance in place.
     viewModel.backLink = this.getBackLink(request, context)
     viewModel.feedbackLink = this.feedbackLink
     viewModel.phaseTag = this.phaseTag
@@ -80,6 +112,40 @@ export class SummaryPageController extends QuestionPageController {
     return viewModel
   }
 
+  private buildPaymentDetails(
+    paymentField: PaymentField,
+    paymentState: NonNullable<
+      ReturnType<PaymentField['getPaymentStateFromState']>
+    >
+  ) {
+    const rows = [
+      {
+        key: { text: 'Payment for' },
+        value: { text: paymentState.description }
+      },
+      {
+        key: { text: 'Total amount' },
+        value: { text: formatPaymentAmount(paymentState.amount) }
+      },
+      {
+        key: { text: 'Reference' },
+        value: { text: paymentState.reference }
+      }
+    ]
+
+    if (paymentState.preAuth?.createdAt) {
+      rows.push({
+        key: { text: 'Date of payment' },
+        value: { text: formatPaymentDate(paymentState.preAuth.createdAt) }
+      })
+    }
+
+    return {
+      title: { text: 'Payment details' },
+      summaryList: { rows }
+    }
+  }
+
   /**
    * Returns an async function. This is called in plugin.ts when there is a GET request at `/{id}/{path*}`,
    */
@@ -110,7 +176,6 @@ export class SummaryPageController extends QuestionPageController {
       context: FormContext,
       h: FormResponseToolkit
     ) => {
-      // Check if this is a save-and-exit action
       const { action } = request.payload
       if (action === FormAction.SaveAndExit) {
         return this.handleSaveAndExit(request, context, h)
@@ -133,14 +198,12 @@ export class SummaryPageController extends QuestionPageController {
     const { formsService } = this.model.services
     const { getFormMetadata } = formsService
 
-    // Get the form metadata using the `slug` param
     const formMetadata = await getFormMetadata(params.slug)
     const { notificationEmail } = formMetadata
     const { isPreview } = checkFormStatus(request.params)
 
     checkEmailAddressForLiveFormSubmission(notificationEmail, isPreview)
 
-    // Send submission email
     if (notificationEmail) {
       const viewModel = this.getSummaryViewModel(request, context)
 
@@ -155,20 +218,7 @@ export class SummaryPageController extends QuestionPageController {
           formMetadata
         )
       } catch (error) {
-        if (error instanceof InvalidComponentStateError) {
-          const govukError = createError(
-            error.component.name,
-            error.userMessage
-          )
-
-          request.yar.flash(COMPONENT_STATE_ERROR, govukError, true)
-
-          await cacheService.resetComponentStates(request, error.getStateKeys())
-
-          return this.proceed(request, h, error.component.page?.path)
-        }
-
-        throw error
+        return this.handleSubmissionError(error, request, h)
       }
     }
 
@@ -178,12 +228,103 @@ export class SummaryPageController extends QuestionPageController {
       referenceNumber: context.referenceNumber
     } as FormConfirmationState)
 
-    // Clear all form data
     await cacheService.clearState(request)
 
     return this.proceed(request, h, this.getStatusPath())
   }
 
+  /**
+   * Handles errors during form submission
+   */
+  private async handleSubmissionError(
+    error: unknown,
+    request: FormRequestPayload,
+    h: FormResponseToolkit
+  ) {
+    if (error instanceof InvalidComponentStateError) {
+      return this.handleInvalidComponentStateError(error, request, h)
+    }
+
+    if (error instanceof PaymentPreAuthError) {
+      return this.handlePaymentPreAuthError(error, request, h)
+    }
+
+    if (error instanceof PaymentSubmissionError) {
+      return this.handlePaymentSubmissionError(error, request, h)
+    }
+
+    throw error
+  }
+
+  /**
+   * Handles InvalidComponentStateError during submission
+   */
+  private async handleInvalidComponentStateError(
+    error: InvalidComponentStateError,
+    request: FormRequestPayload,
+    h: FormResponseToolkit
+  ) {
+    const cacheService = getCacheService(request.server)
+
+    const govukError = createError(error.component.name, error.userMessage)
+
+    request.yar.flash(COMPONENT_STATE_ERROR, govukError, true)
+
+    await cacheService.resetComponentStates(request, error.getStateKeys())
+
+    return this.proceed(request, h, error.component.page?.path)
+  }
+
+  /**
+   * Handles PaymentPreAuthError during submission
+   */
+  private async handlePaymentPreAuthError(
+    error: PaymentPreAuthError,
+    request: FormRequestPayload,
+    h: FormResponseToolkit
+  ) {
+    const cacheService = getCacheService(request.server)
+
+    if (error.shouldResetState) {
+      await cacheService.resetComponentStates(request, error.getStateKeys())
+
+      if (error.errorType === PaymentErrorTypes.PaymentExpired) {
+        request.yar.flash(PAYMENT_EXPIRED_NOTIFICATION, true, true)
+        return this.proceed(request, h, error.component.page?.path)
+      }
+    }
+
+    const govukError = createError(error.component.name, error.userMessage)
+    request.yar.flash(COMPONENT_STATE_ERROR, govukError, true)
+
+    const redirectPath = error.shouldResetState
+      ? error.component.page?.path
+      : undefined
+
+    return this.proceed(request, h, redirectPath)
+  }
+
+  /**
+   * Handles PaymentSubmissionError during submission
+   */
+  private handlePaymentSubmissionError(
+    error: PaymentSubmissionError,
+    request: FormRequestPayload,
+    h: FormResponseToolkit
+  ) {
+    const helpUrl = error.helpLink ?? DEFAULT_PAYMENT_HELP_URL
+    const helpLinkHtml = ` or you can <a href="${helpUrl}" target="_blank" rel="noopener noreferrer" class="govuk-link">contact us (opens in new tab)</a> and quote your reference number to arrange a refund`
+
+    const govukError = createError(
+      'submission',
+      `There was a problem and your form was not submitted. Try submitting the form again${helpLinkHtml}.`
+    )
+
+    request.yar.flash(COMPONENT_STATE_ERROR, govukError, true)
+
+    return this.proceed(request, h)
+  }
+
   get postRouteOptions(): RouteOptions<FormRequestPayloadRefs> {
     return {
       ext: {
@@ -208,39 +349,66 @@ export async function submitForm(
 ) {
   await finaliseComponents(request, metadata, context)
 
+  const paymentWasCaptured = hasPaymentBeenCaptured(context)
+
   const formStatus = checkFormStatus(request.params)
   const logTags = ['submit', 'submissionApi']
 
   request.logger.info(logTags, 'Preparing email', formStatus)
 
-  // Get detail items
   const items = getFormSubmissionData(
     summaryViewModel.context,
     summaryViewModel.details
   )
 
-  // Submit data
-  request.logger.info(logTags, 'Submitting data')
-  const submitResponse = await submitData(
-    model,
-    items,
-    emailAddress,
-    request.yar.id
-  )
+  try {
+    request.logger.info(logTags, 'Submitting data')
+    const submitResponse = await submitData(
+      model,
+      items,
+      emailAddress,
+      request.yar.id
+    )
 
-  if (submitResponse === undefined) {
-    throw Boom.badRequest('Unexpected empty response from submit api')
+    if (submitResponse === undefined) {
+      throw Boom.badRequest('Unexpected empty response from submit api')
+    }
+
+    await model.services.outputService.submit(
+      context,
+      request,
+      model,
+      emailAddress,
+      items,
+      submitResponse,
+      formMetadata
+    )
+  } catch (err) {
+    if (paymentWasCaptured) {
+      throw new PaymentSubmissionError(
+        context.referenceNumber,
+        formMetadata.contact?.online?.url
+      )
+    }
+    throw err
   }
+}
 
-  return model.services.outputService.submit(
-    context,
-    request,
-    model,
-    emailAddress,
-    items,
-    submitResponse,
-    formMetadata
-  )
+/**
+ * Checks if any payment component has been captured
+ */
+function hasPaymentBeenCaptured(context: FormContext): boolean {
+  for (const page of context.relevantPages) {
+    for (const field of page.collection.fields) {
+      if (field instanceof PaymentField) {
+        const paymentState = field.getPaymentStateFromState(context.state)
+        if (paymentState?.capture?.status === 'success') {
+          return true
+        }
+      }
+    }
+  }
+  return false
 }
 
 /**
@@ -280,43 +448,50 @@ function submitData(
   const payload: SubmitPayload = {
     sessionId,
     retrievalKey,
-
-    // Main form answers
-    main: items
-      .filter((item) => 'field' in item)
-      .map((item) => ({
-        name: item.name,
-        title: item.label,
-        value: getAnswer(item.field, item.state, { format: 'data' })
-      })),
-
-    // Repeater form answers
-    repeaters: items
-      .filter((item) => 'subItems' in item)
-      .map((item) => ({
-        name: item.name,
-        title: item.label,
-
-        // Repeater item values
-        value: item.subItems.map((detailItems) =>
-          detailItems.map((subItem) => ({
-            name: subItem.name,
-            title: subItem.label,
-            value: getAnswer(subItem.field, subItem.state, { format: 'data' })
-          }))
-        )
-      }))
+    main: buildMainRecords(items),
+    repeaters: buildRepeaterRecords(items)
   }
 
   return submit(payload)
 }
 
 export function getFormSubmissionData(context: FormContext, details: Detail[]) {
-  return context.relevantPages
+  const items = context.relevantPages
     .map(({ href }) =>
       details.flatMap(({ items }) =>
         items.filter(({ page }) => page.href === href)
       )
     )
     .flat()
+
+  const paymentItems = getPaymentFieldItems(context)
+
+  return [...items, ...paymentItems]
+}
+
+/**
+ * Gets DetailItems for PaymentField components
+ * PaymentField is excluded from summaryDetails for UI but needs to be in submission data
+ */
+function getPaymentFieldItems(context: FormContext): DetailItemField[] {
+  const items: DetailItemField[] = []
+
+  for (const page of context.relevantPages) {
+    for (const field of page.collection.fields) {
+      if (field instanceof PaymentField) {
+        items.push({
+          name: field.name,
+          page,
+          title: field.title,
+          label: field.label,
+          field,
+          state: context.state,
+          href: page.href,
+          value: field.getDisplayStringFromState(context.state)
+        })
+      }
+    }
+  }
+
+  return items
 }

package/src/server/plugins/engine/pageControllers/errors.test.ts

@@ -3,7 +3,10 @@ import { ComponentType } from '@defra/forms-model'
 import { FileUploadField } from '~/src/server/plugins/engine/components/FileUploadField.js'
 import { TextField } from '~/src/server/plugins/engine/components/TextField.js'
 import { FormModel } from '~/src/server/plugins/engine/models/FormModel.js'
-import { InvalidComponentStateError } from '~/src/server/plugins/engine/pageControllers/errors.js'
+import {
+  InvalidComponentStateError,
+  PaymentSubmissionError
+} from '~/src/server/plugins/engine/pageControllers/errors.js'
 import definition from '~/test/form/definitions/file-upload-basic.js'
 
 describe('InvalidComponentStateError', () => {
@@ -63,4 +66,13 @@ describe('InvalidComponentStateError', () => {
       expect(stateKeys).toEqual(['textField'])
     })
   })
+
+  describe('PaymentSubmissionError', () => {
+    it('should instantiate', () => {
+      const error = new PaymentSubmissionError('reference-number', '/help-link')
+      expect(error).toBeDefined()
+      expect(error.referenceNumber).toBe('reference-number')
+      expect(error.helpLink).toBe('/help-link')
+    })
+  })
 })

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

@@ -1,5 +1,83 @@
 import { type FormComponent } from '~/src/server/plugins/engine/components/FormComponent.js'
 
+export enum PaymentErrorTypes {
+  PaymentExpired = 'PaymentExpired',
+  PaymentIncomplete = 'PaymentIncomplete',
+  PaymentAmountMismatch = 'PaymentAmountMismatch'
+}
+
+function getStateKeys(component: FormComponent) {
+  const extraStateKeys = component.page?.getStateKeys(component) ?? []
+
+  return [component.name].concat(extraStateKeys)
+}
+
+export class PaymentPreAuthError extends Error {
+  public readonly component: FormComponent
+  public readonly userMessage: string
+
+  /**
+   * Whether to reset the component state and redirect to the component's page.
+   * - `true`: Reset state and redirect (e.g., payment expired - user must re-enter)
+   * - `false`: Keep state and stay on current page with error (e.g., capture failed - user can retry)
+   */
+  public readonly shouldResetState: boolean
+
+  /**
+   * When supplied, an "Important" notification banner will be shown based on the value.
+   */
+  public readonly errorType: PaymentErrorTypes | undefined
+
+  constructor(
+    component: FormComponent,
+    userMessage: string,
+    shouldResetState: boolean,
+    errorType?: PaymentErrorTypes
+  ) {
+    super('Payment capture failed')
+    this.name = 'PaymentPreAuthError'
+    this.component = component
+    this.userMessage = userMessage
+    this.shouldResetState = shouldResetState
+    this.errorType = errorType
+  }
+
+  getStateKeys() {
+    return getStateKeys(this.component)
+  }
+}
+
+/**
+ * Thrown when form submission fails after payment has been captured.
+ * User needs to retry or contact support for a refund.
+ */
+export class PaymentSubmissionError extends Error {
+  public readonly referenceNumber: string
+  public readonly helpLink?: string
+
+  constructor(referenceNumber: string, helpLink?: string) {
+    super('Form submission failed after payment capture')
+    this.name = 'PaymentSubmissionError'
+    this.referenceNumber = referenceNumber
+    this.helpLink = helpLink
+  }
+
+  static checkPaymentAmount(
+    stateAmount: number,
+    definitionAmount: number | undefined,
+    component: FormComponent
+  ) {
+    if (stateAmount / 100 !== definitionAmount) {
+      throw new PaymentPreAuthError(
+        component,
+        'The pre-authorised payment amount is somehow different from that requested. Try adding payment details again.',
+        true,
+        PaymentErrorTypes.PaymentIncomplete
+      )
+    }
+  }
+}
+
 /**
  * Thrown when a component has an invalid state. This is typically only required where state needs
  * to be checked against an external source upon submission of a form. For example: file upload
@@ -21,9 +99,6 @@ export class InvalidComponentStateError extends Error {
   }
 
   getStateKeys() {
-    const extraStateKeys =
-      this.component.page?.getStateKeys(this.component) ?? []
-
-    return [this.component.name].concat(extraStateKeys)
+    return getStateKeys(this.component)
   }
 }