@defra/forms-engine-plugin 3.0.9 → 4.0.1

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

@@ -12,6 +12,10 @@ import Boom from '@hapi/boom'
 import { type RouteOptions } from '@hapi/hapi'
 import { type ValidationErrorItem } from 'joi'
 
+import {
+  EXTERNAL_STATE_APPENDAGE,
+  EXTERNAL_STATE_PAYLOAD
+} 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'
@@ -35,6 +39,7 @@ import {
   type FormStateValue,
   type FormSubmissionState
 } from '~/src/server/plugins/engine/types.js'
+import { getComponentsByType } from '~/src/server/plugins/engine/validationHelpers.js'
 import {
   FormAction,
   type FormRequest,
@@ -492,6 +497,11 @@ export class QuestionPageController extends PageController {
     ) => {
       const { collection, viewName, model } = this
       const { isForceAccess, state, evaluationState } = context
+      const action = request.payload.action
+
+      if (action?.startsWith(FormAction.External)) {
+        return this.dispatchExternal(request, h, context)
+      }
 
       /**
        * If there are any errors, render the page with the parsed errors
@@ -515,7 +525,6 @@ export class QuestionPageController extends PageController {
       await this.setState(request, state)
 
       // Check if this is a save-and-exit action
-      const { action } = request.payload
       if (action === FormAction.SaveAndExit) {
         return this.handleSaveAndExit(request, context, h)
       }
@@ -525,6 +534,65 @@ export class QuestionPageController extends PageController {
     }
   }
 
+  private dispatchExternal(
+    request: FormRequestPayload,
+    h: FormResponseToolkit,
+    context: FormContext
+  ) {
+    const { externalComponents } = getComponentsByType()
+    const action = request.payload.action ?? ''
+
+    // Find the external action and arguments
+    // `external-{componentName}--{argname1}:{argvalue1}--{argname2}:{argvalue2}`
+    // E.g. external-abcdef--amount:10--step:manual
+    const externalActionsWithArgs = action
+      .slice(`${FormAction.External}-`.length)
+      .split('--')
+
+    const externalActionArgs = externalActionsWithArgs
+      .slice(1)
+      .map((arg) => arg.split(':'))
+
+    const args = Object.fromEntries(externalActionArgs) as Record<
+      string,
+      string
+    >
+
+    const componentName = externalActionsWithArgs[0]
+    const component = this.model.componentDefMap.get(componentName)
+    const componentType = component?.type
+
+    if (!componentType) {
+      throw Boom.internal(
+        `External component of type ${componentType} not found`
+      )
+    }
+
+    const selectedComponent = externalComponents.get(componentType)
+
+    if (!selectedComponent) {
+      throw Boom.internal(`External component ${componentName} not found`)
+    }
+
+    // Stash payload without crumb and action
+    const stashedPayload = {
+      ...context.payload,
+      crumb: undefined,
+      action: undefined
+    }
+    request.yar.flash(EXTERNAL_STATE_PAYLOAD, stashedPayload, true)
+
+    // Clear any previous state appendage
+    request.yar.clear(EXTERNAL_STATE_APPENDAGE)
+
+    return selectedComponent.dispatcher(request, h, {
+      component,
+      controller: this,
+      sourceUrl: request.url.toString(),
+      actionArgs: args
+    })
+  }
+
   proceed(
     request: FormContextRequest,
     h: FormResponseToolkit,

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

@@ -20,7 +20,8 @@ describe('SummaryPageController', () => {
   }
   const h: FormResponseToolkit = {
     redirect: jest.fn().mockReturnValue(response),
-    view: jest.fn()
+    view: jest.fn(),
+    continue: Symbol('continue')
   }
 
   beforeEach(() => {

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

@@ -15,6 +15,7 @@ import { getRoutes as getRepeaterItemDeleteRoutes } from '~/src/server/plugins/e
 import { getRoutes as getRepeaterSummaryRoutes } from '~/src/server/plugins/engine/routes/repeaters/summary.js'
 import { type PluginOptions } from '~/src/server/plugins/engine/types.js'
 import { registerVision } from '~/src/server/plugins/engine/vision.js'
+import { postcodeLookupPlugin } from '~/src/server/plugins/postcode-lookup/index.js'
 import {
   type FormRequestPayloadRefs,
   type FormRequestRefs
@@ -34,7 +35,9 @@ export const plugin = {
       saveAndExit,
       nunjucks: nunjucksOptions,
       viewContext,
-      preparePageEventRequestOptions
+      preparePageEventRequestOptions,
+      onRequest,
+      ordnanceSurveyApiKey
     } = options
 
     const cacheService =
@@ -44,6 +47,16 @@ export const plugin = {
 
     await registerVision(server, options)
 
+    // Register the postcode lookup plugin only if we have an OS api key
+    if (ordnanceSurveyApiKey) {
+      await server.register({
+        plugin: postcodeLookupPlugin,
+        options: {
+          ordnanceSurveyApiKey
+        }
+      })
+    }
+
     server.expose('baseLayoutPath', nunjucksOptions.baseLayoutPath)
     server.expose('viewContext', viewContext)
     server.expose('cacheService', cacheService)
@@ -83,10 +96,15 @@ export const plugin = {
       ...getQuestionRoutes(
         getRouteOptions,
         postRouteOptions,
-        preparePageEventRequestOptions
+        preparePageEventRequestOptions,
+        onRequest
+      ),
+      ...getRepeaterSummaryRoutes(getRouteOptions, postRouteOptions, onRequest),
+      ...getRepeaterItemDeleteRoutes(
+        getRouteOptions,
+        postRouteOptions,
+        onRequest
       ),
-      ...getRepeaterSummaryRoutes(getRouteOptions, postRouteOptions),
-      ...getRepeaterItemDeleteRoutes(getRouteOptions, postRouteOptions),
       ...getFileUploadStatusRoutes()
     ]
 

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

@@ -0,0 +1,317 @@
+import Boom from '@hapi/boom'
+import { type ResponseObject, type ResponseToolkit } from '@hapi/hapi'
+
+import {
+  findPage,
+  getCacheService,
+  getPage,
+  proceed
+} from '~/src/server/plugins/engine/helpers.js'
+import { type FormModel } from '~/src/server/plugins/engine/models/FormModel.js'
+import { type PageControllerClass } from '~/src/server/plugins/engine/pageControllers/helpers/pages.js'
+import { redirectOrMakeHandler } from '~/src/server/plugins/engine/routes/index.js'
+import {
+  type AnyFormRequest,
+  type OnRequestCallback
+} from '~/src/server/plugins/engine/types.js'
+import { type FormResponseToolkit } from '~/src/server/routes/types.js'
+
+jest.mock('~/src/server/plugins/engine/helpers')
+
+describe('redirectOrMakeHandler', () => {
+  const mockServer = {} as unknown as Parameters<
+    typeof redirectOrMakeHandler
+  >[0]['server']
+  const mockRequest: AnyFormRequest = {
+    server: mockServer,
+    app: {},
+    yar: { flash: () => [] },
+    params: { path: 'test-path' },
+    query: {}
+  } as unknown as AnyFormRequest
+
+  const mockH: FormResponseToolkit = {
+    redirect: jest.fn(),
+    view: jest.fn(),
+    continue: Symbol('continue')
+  } as unknown as FormResponseToolkit
+
+  let mockPage: PageControllerClass
+
+  const mockModel: FormModel = {
+    def: {
+      metadata: {
+        submission: { code: 'TEST-CODE' }
+      } as { submission: { code: string } }
+    },
+    getFormContext: jest.fn().mockReturnValue({
+      isForceAccess: false,
+      data: {}
+    })
+  } as unknown as FormModel
+
+  const mockMakeHandler = jest
+    .fn()
+    .mockResolvedValue({ statusCode: 200 } as ResponseObject)
+
+  beforeEach(() => {
+    jest.clearAllMocks()
+    mockRequest.app = { model: mockModel }
+
+    // Reset mock page
+    mockPage = {
+      getState: jest.fn().mockResolvedValue({ $$__referenceNumber: 'REF-123' }),
+      mergeState: jest
+        .fn()
+        .mockResolvedValue({ $$__referenceNumber: 'REF-123' }),
+      getRelevantPath: jest.fn().mockReturnValue('/test-path'),
+      getSummaryPath: jest.fn().mockReturnValue('/summary'),
+      getHref: jest.fn().mockReturnValue('/test-href'),
+      path: '/test-path'
+    } as unknown as PageControllerClass
+
+    // Reset mock model
+    mockModel.getFormContext = jest.fn().mockReturnValue({
+      isForceAccess: false,
+      data: {}
+    })
+
+    // Setup mocks
+    ;(getCacheService as jest.Mock).mockReturnValue({
+      getFlash: jest.fn().mockReturnValue({ errors: [] })
+    })
+    ;(getPage as jest.Mock).mockReturnValue(mockPage)
+    ;(findPage as jest.Mock).mockReturnValue({ next: [] })
+    ;(proceed as jest.Mock).mockReturnValue({ statusCode: 302 })
+  })
+
+  describe('onRequest callback functionality', () => {
+    it('should call onRequest callback when provided', async () => {
+      const onRequestCallback: OnRequestCallback = jest
+        .fn()
+        .mockResolvedValue(undefined)
+
+      await redirectOrMakeHandler(
+        mockRequest,
+        mockH,
+        onRequestCallback,
+        mockMakeHandler
+      )
+
+      expect(onRequestCallback).toHaveBeenCalledWith(
+        mockRequest,
+        mockH as ResponseToolkit,
+        expect.objectContaining({
+          isForceAccess: false,
+          data: {}
+        })
+      )
+    })
+
+    it('should not call onRequest callback when not provided', async () => {
+      const onRequestCallback = jest.fn()
+
+      await redirectOrMakeHandler(
+        mockRequest,
+        mockH,
+        undefined,
+        mockMakeHandler
+      )
+
+      expect(onRequestCallback).not.toHaveBeenCalled()
+    })
+
+    it('should return takeover response when onRequest returns takeover response', async () => {
+      const takeoverResponse = {
+        statusCode: 302,
+        headers: { location: '/redirect-url' },
+        _takeover: true
+      } as unknown as ResponseObject
+
+      const onRequestCallback: OnRequestCallback = jest
+        .fn()
+        .mockResolvedValue(takeoverResponse)
+
+      const result = await redirectOrMakeHandler(
+        mockRequest,
+        mockH,
+        onRequestCallback,
+        mockMakeHandler
+      )
+
+      expect(result).toBe(takeoverResponse)
+      expect(mockMakeHandler).not.toHaveBeenCalled()
+    })
+
+    it('should continue processing when onRequest returns h.continue', async () => {
+      const onRequestCallback: OnRequestCallback = jest
+        .fn()
+        .mockResolvedValue(mockH.continue)
+
+      await redirectOrMakeHandler(
+        mockRequest,
+        mockH,
+        onRequestCallback,
+        mockMakeHandler
+      )
+
+      expect(mockMakeHandler).toHaveBeenCalledWith(mockPage, expect.any(Object))
+    })
+
+    it('should handle onRequest callback errors', async () => {
+      const error = new Error('onRequest callback error')
+      const onRequestCallback: OnRequestCallback = jest
+        .fn()
+        .mockRejectedValue(error)
+
+      await expect(
+        redirectOrMakeHandler(
+          mockRequest,
+          mockH,
+          onRequestCallback,
+          mockMakeHandler
+        )
+      ).rejects.toThrow('onRequest callback error')
+    })
+  })
+
+  describe('existing functionality', () => {
+    it('should throw error when model is missing', async () => {
+      mockRequest.app = {}
+
+      await expect(
+        redirectOrMakeHandler(mockRequest, mockH, undefined, mockMakeHandler)
+      ).rejects.toThrow(Boom.notFound('No model found for /test-path'))
+    })
+
+    it('should call makeHandler when page is relevant', async () => {
+      const testPage = {
+        getState: jest
+          .fn()
+          .mockResolvedValue({ $$__referenceNumber: 'REF-123' }),
+        mergeState: jest
+          .fn()
+          .mockResolvedValue({ $$__referenceNumber: 'REF-123' }),
+        getSummaryPath: jest.fn().mockReturnValue('/summary'),
+        getHref: jest.fn().mockReturnValue('/test-href'),
+        getRelevantPath: jest.fn().mockReturnValue('/test-path'),
+        path: '/test-path'
+      } as unknown as PageControllerClass
+      ;(getPage as jest.Mock).mockReturnValue(testPage)
+
+      await redirectOrMakeHandler(
+        mockRequest,
+        mockH,
+        undefined,
+        mockMakeHandler
+      )
+
+      expect(mockMakeHandler).toHaveBeenCalledWith(testPage, expect.any(Object))
+    })
+
+    it('should call makeHandler when context has force access', async () => {
+      mockModel.getFormContext = jest.fn().mockReturnValue({
+        isForceAccess: true,
+        data: {}
+      })
+
+      await redirectOrMakeHandler(
+        mockRequest,
+        mockH,
+        undefined,
+        mockMakeHandler
+      )
+
+      expect(mockMakeHandler).toHaveBeenCalledWith(mockPage, expect.any(Object))
+    })
+
+    it('should redirect when page is not relevant', async () => {
+      const testPage = {
+        getState: jest
+          .fn()
+          .mockResolvedValue({ $$__referenceNumber: 'REF-123' }),
+        mergeState: jest
+          .fn()
+          .mockResolvedValue({ $$__referenceNumber: 'REF-123' }),
+        getSummaryPath: jest.fn().mockReturnValue('/summary'),
+        getHref: jest.fn().mockReturnValue('/test-href'),
+        getRelevantPath: jest.fn().mockReturnValue('/other-path'),
+        path: '/test-path'
+      } as unknown as PageControllerClass
+      ;(getPage as jest.Mock).mockReturnValue(testPage)
+
+      await redirectOrMakeHandler(
+        mockRequest,
+        mockH,
+        undefined,
+        mockMakeHandler
+      )
+
+      expect(proceed).toHaveBeenCalledWith(mockRequest, mockH, '/test-href')
+      expect(mockMakeHandler).not.toHaveBeenCalled()
+    })
+
+    it('should set returnUrl when redirecting and next pages exist', async () => {
+      const testPage = {
+        getState: jest
+          .fn()
+          .mockResolvedValue({ $$__referenceNumber: 'REF-123' }),
+        mergeState: jest
+          .fn()
+          .mockResolvedValue({ $$__referenceNumber: 'REF-123' }),
+        getSummaryPath: jest.fn().mockReturnValue('/summary'),
+        getRelevantPath: jest.fn().mockReturnValue('/other-path'),
+        path: '/test-path',
+        getHref: jest
+          .fn()
+          .mockReturnValueOnce('/summary-href') // First call: for summaryPath (returnUrl)
+          .mockReturnValueOnce('/relevant-path-href') // Second call: for relevantPath (redirect)
+      } as unknown as PageControllerClass
+      ;(getPage as jest.Mock).mockReturnValue(testPage)
+      ;(findPage as jest.Mock).mockReturnValue({ next: ['next-page'] })
+
+      await redirectOrMakeHandler(
+        mockRequest,
+        mockH,
+        undefined,
+        mockMakeHandler
+      )
+
+      expect(mockRequest.query.returnUrl).toBe('/summary-href')
+      expect(proceed).toHaveBeenCalledWith(
+        mockRequest,
+        mockH,
+        '/relevant-path-href'
+      )
+    })
+
+    it('should not set returnUrl when redirecting and no next pages exist', async () => {
+      const testPage = {
+        getState: jest
+          .fn()
+          .mockResolvedValue({ $$__referenceNumber: 'REF-123' }),
+        mergeState: jest
+          .fn()
+          .mockResolvedValue({ $$__referenceNumber: 'REF-123' }),
+        getSummaryPath: jest.fn().mockReturnValue('/summary'),
+        getHref: jest.fn().mockReturnValue('/test-href'),
+        getRelevantPath: jest.fn().mockReturnValue('/other-path'),
+        path: '/test-path'
+      } as unknown as PageControllerClass
+      ;(getPage as jest.Mock).mockReturnValue(testPage)
+      const returnUrlBefore = mockRequest.query.returnUrl
+      ;(findPage as jest.Mock).mockReturnValue({ next: [] })
+
+      await redirectOrMakeHandler(
+        mockRequest,
+        mockH,
+        undefined,
+        mockMakeHandler
+      )
+
+      // returnUrl should not be set if next pages don't exist
+      expect(mockRequest.query.returnUrl).toBe(returnUrlBefore)
+      expect(proceed).toHaveBeenCalledWith(mockRequest, mockH, '/test-href')
+    })
+  })
+})

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

@@ -6,7 +6,15 @@ import {
 } from '@hapi/hapi'
 import { isEqual } from 'date-fns'
 
-import { PREVIEW_PATH_PREFIX } from '~/src/server/constants.js'
+import {
+  EXTERNAL_STATE_APPENDAGE,
+  EXTERNAL_STATE_PAYLOAD,
+  PREVIEW_PATH_PREFIX
+} from '~/src/server/constants.js'
+import {
+  FormComponent,
+  isFormState
+} from '~/src/server/plugins/engine/components/FormComponent.js'
 import {
   checkEmailAddressForLiveFormSubmission,
   checkFormStatus,
@@ -22,7 +30,11 @@ import { generateUniqueReference } from '~/src/server/plugins/engine/referenceNu
 import * as defaultServices from '~/src/server/plugins/engine/services/index.js'
 import {
   type AnyFormRequest,
+  type ExternalStateAppendage,
   type FormContext,
+  type FormPayload,
+  type FormSubmissionState,
+  type OnRequestCallback,
   type PluginOptions
 } from '~/src/server/plugins/engine/types.js'
 import {
@@ -33,6 +45,7 @@ import {
 export async function redirectOrMakeHandler(
   request: AnyFormRequest,
   h: FormResponseToolkit,
+  onRequest: OnRequestCallback | undefined,
   makeHandler: (
     page: PageControllerClass,
     context: FormContext
@@ -64,11 +77,21 @@ export async function redirectOrMakeHandler(
     })
   }
 
+  state = await importExternalComponentState(request, page, state)
+
   const flash = cacheService.getFlash(request)
   const context = model.getFormContext(request, state, flash?.errors)
   const relevantPath = page.getRelevantPath(request, context)
   const summaryPath = page.getSummaryPath()
 
+  // Call the onRequest callback if it has been supplied
+  if (onRequest) {
+    const result = await onRequest(request, h, context)
+    if (result !== h.continue) {
+      return result
+    }
+  }
+
   // Return handler for relevant pages or preview URL direct access
   if (relevantPath.startsWith(page.path) || context.isForceAccess) {
     return makeHandler(page, context)
@@ -85,11 +108,66 @@ export async function redirectOrMakeHandler(
   return proceed(request, h, page.getHref(relevantPath))
 }
 
+async function importExternalComponentState(
+  request: AnyFormRequest,
+  page: PageControllerClass,
+  state: FormSubmissionState
+): Promise<FormSubmissionState> {
+  const externalComponentData = request.yar.flash(EXTERNAL_STATE_APPENDAGE)
+
+  if (Array.isArray(externalComponentData)) {
+    return state
+  }
+
+  const typedStateAppendage = externalComponentData as ExternalStateAppendage
+  const componentName = typedStateAppendage.component
+  const stateAppendage = typedStateAppendage.data
+  const component = request.app.model?.componentMap.get(componentName)
+
+  if (!component) {
+    throw new Error(`Component ${componentName} not found in form`)
+  }
+
+  if (!(component instanceof FormComponent)) {
+    throw new TypeError(
+      `Component ${componentName} is not a FormComponent and does not support isState`
+    )
+  }
+
+  const isStateValid = component.isState(stateAppendage)
+
+  if (!isStateValid) {
+    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 updatedState = await page.mergeState(request, state, componentState)
+
+  // Merge the stashed payload into the local state
+  const payload = request.yar.flash(EXTERNAL_STATE_PAYLOAD)
+  const stashedPayload = Array.isArray(payload) ? {} : (payload as FormPayload)
+
+  return { ...stashedPayload, ...updatedState }
+}
+
 export function makeLoadFormPreHandler(server: Server, options: PluginOptions) {
   // eslint-disable-next-line @typescript-eslint/no-unnecessary-condition -- hapi types are wrong
   const prefix = server.realm.modifiers.route.prefix ?? ''
 
-  const { services = defaultServices, controllers, onRequest } = options
+  const {
+    services = defaultServices,
+    controllers,
+    ordnanceSurveyApiKey
+  } = options
 
   const { formsService } = services
 
@@ -156,7 +234,7 @@ export function makeLoadFormPreHandler(server: Server, options: PluginOptions) {
       // Construct the form model
       const model = new FormModel(
         definition,
-        { basePath, versionNumber },
+        { basePath, versionNumber, ordnanceSurveyApiKey },
         services,
         controllers
       )
@@ -166,11 +244,6 @@ export function makeLoadFormPreHandler(server: Server, options: PluginOptions) {
       server.app.models.set(key, item)
     }
 
-    // Call the onRequest callback if it has been supplied
-    if (onRequest) {
-      onRequest(request, params, item.model.def, metadata)
-    }
-
     // Assign the model to the request data
     // for use in the downstream handler
     request.app.model = item.model