Stash

Author: jbarnsley10

src/server/plugins/engine/components/PaymentField.ts

@@ -10,7 +10,10 @@ import joi, { type ObjectSchema } from 'joi'
 import { FormComponent } from '~/src/server/plugins/engine/components/FormComponent.js'
 import { type PaymentState } from '~/src/server/plugins/engine/components/PaymentField.types.js'
 import { getPluginOptions } from '~/src/server/plugins/engine/helpers.js'
-import { InvalidComponentStateError } from '~/src/server/plugins/engine/pageControllers/errors.js'
+import {
+  PaymentErrorTypes,
+  PrePaymentError
+} from '~/src/server/plugins/engine/pageControllers/errors.js'
 import {
   type AnyFormRequest,
   type FormContext,
@@ -248,10 +251,11 @@ export class PaymentField extends FormComponent {
     const paymentState = this.getPaymentStateFromState(context.state)
 
     if (!paymentState) {
-      throw new InvalidComponentStateError(
+      throw new PrePaymentError(
         this,
         'Complete the payment to continue',
-        { shouldResetState: true }
+        true,
+        PaymentErrorTypes.PaymentIncomplete
       )
     }
 
@@ -273,20 +277,21 @@ export class PaymentField extends FormComponent {
     }
 
     if (status.state.status !== 'capturable') {
-      throw new InvalidComponentStateError(
+      throw new PrePaymentError(
         this,
         'Your payment authorisation has expired. Please add your payment details again.',
-        { shouldResetState: true, isPaymentExpired: true }
+        true,
+        PaymentErrorTypes.PaymentExpired
       )
     }
 
     const captured = await paymentService.capturePayment(paymentId)
 
     if (!captured) {
-      throw new InvalidComponentStateError(
+      throw new PrePaymentError(
         this,
         'There was a problem and your form was not submitted. Try submitting the form again.',
-        { shouldResetState: false }
+        false
       )
     }
 

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

@@ -31,7 +31,9 @@ import {
 import { QuestionPageController } from '~/src/server/plugins/engine/pageControllers/QuestionPageController.js'
 import {
   InvalidComponentStateError,
-  PostPaymentSubmissionError
+  PaymentErrorTypes,
+  PostPaymentSubmissionError,
+  PrePaymentError
 } from '~/src/server/plugins/engine/pageControllers/errors.js'
 import {
   buildMainRecords,
@@ -243,6 +245,10 @@ export class SummaryPageController extends QuestionPageController {
       return this.handleInvalidComponentStateError(error, request, h)
     }
 
+    if (error instanceof PrePaymentError) {
+      return this.handlePrePaymentError(error, request, h)
+    }
+
     if (error instanceof PostPaymentSubmissionError) {
       return this.handlePostPaymentSubmissionError(error, request, h)
     }
@@ -260,10 +266,29 @@ export class SummaryPageController extends QuestionPageController {
   ) {
     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 PrePaymentError during submission
+   */
+  private async handlePrePaymentError(
+    error: PrePaymentError,
+    request: FormRequestPayload,
+    h: FormResponseToolkit
+  ) {
+    const cacheService = getCacheService(request.server)
+
     if (error.shouldResetState) {
       await cacheService.resetComponentStates(request, error.getStateKeys())
 
-      if (error.isPaymentExpired) {
+      if (error.errorType === PaymentErrorTypes.PaymentExpired) {
         request.yar.flash(PAYMENT_EXPIRED_NOTIFICATION, true, true)
         return this.proceed(request, h, error.component.page?.path)
       }

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

@@ -1,5 +1,47 @@
 import { type FormComponent } from '~/src/server/plugins/engine/components/FormComponent.js'
 
+export enum PaymentErrorTypes {
+  PaymentExpired = 'PaymentExpired',
+  PaymentIncomplete = 'PaymentIncomplete'
+}
+export class PrePaymentError 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 = 'PrePaymentError'
+    this.component = component
+    this.userMessage = userMessage
+    this.shouldResetState = shouldResetState
+    this.errorType = errorType
+  }
+
+  getStateKeys() {
+    const extraStateKeys =
+      this.component.page?.getStateKeys(this.component) ?? []
+
+    return [this.component.name].concat(extraStateKeys)
+  }
+}
+
 /**
  * Thrown when form submission fails after payment has been captured.
  * User needs to retry or contact support for a refund.
@@ -16,23 +58,6 @@ export class PostPaymentSubmissionError extends Error {
   }
 }
 
-export interface InvalidComponentStateErrorOptions {
-  /**
-   * 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)
-   * @default true
-   */
-  shouldResetState?: boolean
-
-  /**
-   * Whether this error is due to payment expiry.
-   * When true, an "Important" notification banner will be shown on the payment page.
-   * @default false
-   */
-  isPaymentExpired?: boolean
-}
-
 /**
  * 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
@@ -44,21 +69,13 @@ export interface InvalidComponentStateErrorOptions {
 export class InvalidComponentStateError extends Error {
   public readonly component: FormComponent
   public readonly userMessage: string
-  public readonly shouldResetState: boolean
-  public readonly isPaymentExpired: boolean
 
-  constructor(
-    component: FormComponent,
-    userMessage: string,
-    options: InvalidComponentStateErrorOptions = {}
-  ) {
+  constructor(component: FormComponent, userMessage: string) {
     const message = `Invalid component state for: ${component.name}`
     super(message)
     this.name = 'InvalidComponentStateError'
     this.component = component
     this.userMessage = userMessage
-    this.shouldResetState = options.shouldResetState ?? true
-    this.isPaymentExpired = options.isPaymentExpired ?? false
   }
 
   getStateKeys() {