@defra/forms-engine-plugin 4.0.27 → 4.0.29

package/.server/server/plugins/postcode-lookup/routes/index.js.map

@@ -1 +1 @@
-{"version":3,"file":"index.js","names":["Boom","StatusCodes","Joi","EXTERNAL_STATE_APPENDAGE","JOURNEY_BASE_URL","detailsPayloadSchema","detailsViewModel","manualPayloadSchema","manualViewModel","selectPayloadSchema","selectViewModel","stepSchema","steps","service","viewName","getSessionState","request","state","yar","get","internal","flashComponentState","componentName","address","addressState","addressLine1","addressLine2","town","county","postcode","uprn","undefined","appendage","component","data","flash","dispatch","h","initial","details","postcodeQuery","buildingNameQuery","set","query","step","redirect","code","SEE_OTHER","getRoutes","options","getRoute","postRoute","method","path","handler","session","model","manual","view","validate","object","keys","string","allow","optional","payload","detailsPostHandler","select","selectPostHandler","manualPostHandler","badRequest","unknown","ordnanceSurveyApiKey","apiKey","value","error","addresses","searchByUPRN","property","at","sourceUrl","abortEarly"],"sources":["../../../../../src/server/plugins/postcode-lookup/routes/index.js"],"sourcesContent":["import Boom from '@hapi/boom'\nimport { StatusCodes } from 'http-status-codes'\nimport Joi from 'joi'\n\nimport { EXTERNAL_STATE_APPENDAGE } from '~/src/server/constants.js'\nimport {\n  JOURNEY_BASE_URL,\n  detailsPayloadSchema,\n  detailsViewModel,\n  manualPayloadSchema,\n  manualViewModel,\n  selectPayloadSchema,\n  selectViewModel,\n  stepSchema,\n  steps\n} from '~/src/server/plugins/postcode-lookup/models/index.js'\nimport * as service from '~/src/server/plugins/postcode-lookup/service.js'\n\nconst viewName = 'postcode-lookup-details'\n\n/**\n * Get the session state associated with this journey\n * @param {PostcodeLookupRequest} request\n */\nfunction getSessionState(request) {\n  /**\n   * @type {PostcodeLookupSessionData | null | undefined}\n   */\n  const state = request.yar.get(JOURNEY_BASE_URL)\n\n  if (!state) {\n    throw Boom.internal(`No postcode lookup data found for ${JOURNEY_BASE_URL}`)\n  }\n\n  return state\n}\n\n/**\n * Flash form component state\n * @param {PostcodeLookupRequest} request - the request\n * @param {string} componentName - the component name\n * @param {Address | PostcodeLookupManualPayload} address - the address from ordnance survey or manually entered\n */\nfunction flashComponentState(request, componentName, address) {\n  const addressState = {\n    addressLine1: address.addressLine1,\n    addressLine2: address.addressLine2,\n    town: address.town,\n    county: address.county,\n    postcode: address.postcode,\n    uprn: 'uprn' in address && address.uprn ? address.uprn : undefined\n  }\n\n  /**\n   * @type {ExternalStateAppendage}\n   */\n  const appendage = {\n    component: componentName,\n    data: addressState\n  }\n\n  request.yar.flash(EXTERNAL_STATE_APPENDAGE, appendage, true)\n}\n\n/**\n * Initialises and dispatches the request to the postcode lookup journey\n * @param {FormRequestPayload} request - the source page\n * @param {FormResponseToolkit} h - the source page\n * @param {PostcodeLookupDispatchData} initial - the source data\n */\nexport function dispatch(request, h, initial) {\n  /**\n   * @type {PostcodeLookupSessionData}\n   */\n  const data = {\n    initial,\n    details: { postcodeQuery: '', buildingNameQuery: '' }\n  }\n\n  request.yar.set(JOURNEY_BASE_URL, data)\n\n  const query = initial.step ? `?step=${initial.step}` : ''\n\n  return h.redirect(`${JOURNEY_BASE_URL}${query}`).code(StatusCodes.SEE_OTHER)\n}\n\n/**\n * Gets the postcode lookup routes\n * @param {PostcodeLookupConfiguration} options - ordnance survey api key\n */\nexport function getRoutes(options) {\n  return [getRoute(), postRoute(options)]\n}\n\n/**\n * @returns {ServerRoute<PostcodeLookupGetRequestRefs>}\n */\nfunction getRoute() {\n  return {\n    method: 'GET',\n    path: JOURNEY_BASE_URL,\n    handler(request, h) {\n      const { query } = request\n      const { step } = query\n      const session = getSessionState(request)\n\n      const model =\n        step === steps.manual\n          ? manualViewModel(session)\n          : detailsViewModel(session)\n\n      return h.view(viewName, model)\n    },\n    options: {\n      validate: {\n        query: Joi.object()\n          .keys({\n            step: Joi.string().allow(steps.details, steps.manual).optional()\n          })\n          .optional()\n      }\n    }\n  }\n}\n\n/**\n * @param {PostcodeLookupConfiguration} options\n * @returns {ServerRoute<PostcodeLookupPostRequestRefs>}\n */\nfunction postRoute(options) {\n  return {\n    method: 'POST',\n    path: JOURNEY_BASE_URL,\n    async handler(request, h) {\n      const { payload } = request\n      const { step } = payload\n\n      switch (step) {\n        case steps.details: {\n          return detailsPostHandler(request, h, options)\n        }\n        case steps.select: {\n          return selectPostHandler(request, h, options)\n        }\n        case steps.manual: {\n          return manualPostHandler(request, h)\n        }\n        default:\n          throw Boom.badRequest(`Invalid step ${step}`)\n      }\n    },\n    options: {\n      validate: {\n        payload: Joi.object()\n          .keys({\n            step: stepSchema\n          })\n          .unknown(true)\n      }\n    }\n  }\n}\n\n/**\n * Post handler for the details step\n * @param {PostcodeLookupPostRequest} request\n * @param {ResponseToolkit<PostcodeLookupPostRequestRefs>} h\n * @param {PostcodeLookupConfiguration} options\n */\nasync function detailsPostHandler(request, h, options) {\n  const { payload } = request\n  const session = getSessionState(request)\n  const { ordnanceSurveyApiKey: apiKey } = options\n  const { value: details, error } = detailsPayloadSchema.validate(payload)\n\n  let model\n\n  if (error) {\n    model = detailsViewModel(session, details, error)\n\n    return h.view(viewName, model)\n  }\n\n  const { postcodeQuery, buildingNameQuery } = details\n  session.details = { postcodeQuery, buildingNameQuery }\n\n  // Store the updated session\n  request.yar.set(JOURNEY_BASE_URL, session)\n\n  model = await selectViewModel({ session, apiKey })\n\n  return h.view(viewName, model)\n}\n\n/**\n * Post handler for the select step\n * @param {PostcodeLookupPostRequest} request\n * @param {ResponseToolkit<PostcodeLookupPostRequestRefs>} h\n * @param {PostcodeLookupConfiguration} options\n */\nasync function selectPostHandler(request, h, options) {\n  const { payload } = request\n  const session = getSessionState(request)\n  const { ordnanceSurveyApiKey: apiKey } = options\n  const { value: select, error } = selectPayloadSchema.validate(payload)\n\n  if (error) {\n    const model = await selectViewModel({ session, apiKey }, select, error)\n\n    return h.view(viewName, model)\n  }\n\n  const addresses = await service.searchByUPRN(select.uprn, apiKey)\n  const property = addresses.at(0)\n\n  if (!property) {\n    throw Boom.internal(`UPRN ${property} not found`)\n  }\n\n  const { componentName, sourceUrl } = session.initial\n  flashComponentState(request, componentName, property)\n\n  // Redirect back to the source form page\n  return h.redirect(sourceUrl).code(StatusCodes.SEE_OTHER)\n}\n\n/**\n * Post handler for the manual step\n * @param {PostcodeLookupPostRequest} request\n * @param {ResponseToolkit<PostcodeLookupPostRequestRefs>} h\n */\nfunction manualPostHandler(request, h) {\n  const { payload } = request\n  const session = getSessionState(request)\n\n  const { value: manual, error } = manualPayloadSchema.validate(payload, {\n    abortEarly: false\n  })\n\n  if (error) {\n    const model = manualViewModel(session, manual, error)\n\n    return h.view(viewName, model)\n  }\n\n  const { componentName, sourceUrl } = session.initial\n  flashComponentState(request, componentName, manual)\n\n  // Redirect back to the source form page\n  return h.redirect(sourceUrl).code(StatusCodes.SEE_OTHER)\n}\n\n/**\n * @import { ResponseToolkit, ServerRoute } from '@hapi/hapi'\n * @import { PostcodeLookupManualPayload, Address, PostcodeLookupGetRequestRefs, PostcodeLookupPostRequestRefs, PostcodeLookupRequest, PostcodeLookupPostRequest, PostcodeLookupConfiguration, PostcodeLookupDispatchData, PostcodeLookupSessionData } from '~/src/server/plugins/postcode-lookup/types.js'\n * @import { FormRequestPayload, FormResponseToolkit } from '~/src/server/routes/types.js'\n * @import { ExternalStateAppendage } from '~/src/server/plugins/engine/types.js'\n */\n"],"mappings":"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","ignoreList":[]}
+{"version":3,"file":"index.js","names":["Boom","StatusCodes","Joi","EXTERNAL_STATE_APPENDAGE","JOURNEY_BASE_URL","detailsPayloadSchema","detailsViewModel","manualPayloadSchema","manualViewModel","selectPayloadSchema","selectViewModel","stepSchema","steps","service","viewName","getSessionState","request","state","yar","get","badRequest","flashComponentState","componentName","address","addressState","addressLine1","addressLine2","town","county","postcode","uprn","undefined","appendage","component","data","flash","dispatch","h","initial","details","postcodeQuery","buildingNameQuery","set","query","step","redirect","code","SEE_OTHER","getRoutes","options","getRoute","postRoute","method","path","handler","session","model","manual","view","validate","object","keys","string","allow","optional","payload","detailsPostHandler","select","selectPostHandler","manualPostHandler","unknown","ordnanceSurveyApiKey","apiKey","value","error","addresses","searchByUPRN","property","at","internal","sourceUrl","abortEarly"],"sources":["../../../../../src/server/plugins/postcode-lookup/routes/index.js"],"sourcesContent":["import Boom from '@hapi/boom'\nimport { StatusCodes } from 'http-status-codes'\nimport Joi from 'joi'\n\nimport { EXTERNAL_STATE_APPENDAGE } from '~/src/server/constants.js'\nimport {\n  JOURNEY_BASE_URL,\n  detailsPayloadSchema,\n  detailsViewModel,\n  manualPayloadSchema,\n  manualViewModel,\n  selectPayloadSchema,\n  selectViewModel,\n  stepSchema,\n  steps\n} from '~/src/server/plugins/postcode-lookup/models/index.js'\nimport * as service from '~/src/server/plugins/postcode-lookup/service.js'\n\nconst viewName = 'postcode-lookup-details'\n\n/**\n * Get the session state associated with this journey\n * @param {PostcodeLookupRequest} request\n */\nfunction getSessionState(request) {\n  /**\n   * @type {PostcodeLookupSessionData | null | undefined}\n   */\n  const state = request.yar.get(JOURNEY_BASE_URL)\n\n  if (!state) {\n    throw Boom.badRequest(\n      `No postcode lookup data found for ${JOURNEY_BASE_URL}`\n    )\n  }\n\n  return state\n}\n\n/**\n * Flash form component state\n * @param {PostcodeLookupRequest} request - the request\n * @param {string} componentName - the component name\n * @param {Address | PostcodeLookupManualPayload} address - the address from ordnance survey or manually entered\n */\nfunction flashComponentState(request, componentName, address) {\n  const addressState = {\n    addressLine1: address.addressLine1,\n    addressLine2: address.addressLine2,\n    town: address.town,\n    county: address.county,\n    postcode: address.postcode,\n    uprn: 'uprn' in address && address.uprn ? address.uprn : undefined\n  }\n\n  /**\n   * @type {ExternalStateAppendage}\n   */\n  const appendage = {\n    component: componentName,\n    data: addressState\n  }\n\n  request.yar.flash(EXTERNAL_STATE_APPENDAGE, appendage, true)\n}\n\n/**\n * Initialises and dispatches the request to the postcode lookup journey\n * @param {FormRequestPayload} request - the source page\n * @param {FormResponseToolkit} h - the source page\n * @param {PostcodeLookupDispatchData} initial - the source data\n */\nexport function dispatch(request, h, initial) {\n  /**\n   * @type {PostcodeLookupSessionData}\n   */\n  const data = {\n    initial,\n    details: { postcodeQuery: '', buildingNameQuery: '' }\n  }\n\n  request.yar.set(JOURNEY_BASE_URL, data)\n\n  const query = initial.step ? `?step=${initial.step}` : ''\n\n  return h.redirect(`${JOURNEY_BASE_URL}${query}`).code(StatusCodes.SEE_OTHER)\n}\n\n/**\n * Gets the postcode lookup routes\n * @param {PostcodeLookupConfiguration} options - ordnance survey api key\n */\nexport function getRoutes(options) {\n  return [getRoute(), postRoute(options)]\n}\n\n/**\n * @returns {ServerRoute<PostcodeLookupGetRequestRefs>}\n */\nfunction getRoute() {\n  return {\n    method: 'GET',\n    path: JOURNEY_BASE_URL,\n    handler(request, h) {\n      const { query } = request\n      const { step } = query\n      const session = getSessionState(request)\n\n      const model =\n        step === steps.manual\n          ? manualViewModel(session)\n          : detailsViewModel(session)\n\n      return h.view(viewName, model)\n    },\n    options: {\n      validate: {\n        query: Joi.object()\n          .keys({\n            step: Joi.string().allow(steps.details, steps.manual).optional()\n          })\n          .optional()\n      }\n    }\n  }\n}\n\n/**\n * @param {PostcodeLookupConfiguration} options\n * @returns {ServerRoute<PostcodeLookupPostRequestRefs>}\n */\nfunction postRoute(options) {\n  return {\n    method: 'POST',\n    path: JOURNEY_BASE_URL,\n    async handler(request, h) {\n      const { payload } = request\n      const { step } = payload\n\n      switch (step) {\n        case steps.details: {\n          return detailsPostHandler(request, h, options)\n        }\n        case steps.select: {\n          return selectPostHandler(request, h, options)\n        }\n        case steps.manual: {\n          return manualPostHandler(request, h)\n        }\n        default:\n          throw Boom.badRequest(`Invalid step ${step}`)\n      }\n    },\n    options: {\n      validate: {\n        payload: Joi.object()\n          .keys({\n            step: stepSchema\n          })\n          .unknown(true)\n      }\n    }\n  }\n}\n\n/**\n * Post handler for the details step\n * @param {PostcodeLookupPostRequest} request\n * @param {ResponseToolkit<PostcodeLookupPostRequestRefs>} h\n * @param {PostcodeLookupConfiguration} options\n */\nasync function detailsPostHandler(request, h, options) {\n  const { payload } = request\n  const session = getSessionState(request)\n  const { ordnanceSurveyApiKey: apiKey } = options\n  const { value: details, error } = detailsPayloadSchema.validate(payload)\n\n  let model\n\n  if (error) {\n    model = detailsViewModel(session, details, error)\n\n    return h.view(viewName, model)\n  }\n\n  const { postcodeQuery, buildingNameQuery } = details\n  session.details = { postcodeQuery, buildingNameQuery }\n\n  // Store the updated session\n  request.yar.set(JOURNEY_BASE_URL, session)\n\n  model = await selectViewModel({ session, apiKey })\n\n  return h.view(viewName, model)\n}\n\n/**\n * Post handler for the select step\n * @param {PostcodeLookupPostRequest} request\n * @param {ResponseToolkit<PostcodeLookupPostRequestRefs>} h\n * @param {PostcodeLookupConfiguration} options\n */\nasync function selectPostHandler(request, h, options) {\n  const { payload } = request\n  const session = getSessionState(request)\n  const { ordnanceSurveyApiKey: apiKey } = options\n  const { value: select, error } = selectPayloadSchema.validate(payload)\n\n  if (error) {\n    const model = await selectViewModel({ session, apiKey }, select, error)\n\n    return h.view(viewName, model)\n  }\n\n  const addresses = await service.searchByUPRN(select.uprn, apiKey)\n  const property = addresses.at(0)\n\n  if (!property) {\n    throw Boom.internal(`UPRN ${property} not found`)\n  }\n\n  const { componentName, sourceUrl } = session.initial\n  flashComponentState(request, componentName, property)\n\n  // Redirect back to the source form page\n  return h.redirect(sourceUrl).code(StatusCodes.SEE_OTHER)\n}\n\n/**\n * Post handler for the manual step\n * @param {PostcodeLookupPostRequest} request\n * @param {ResponseToolkit<PostcodeLookupPostRequestRefs>} h\n */\nfunction manualPostHandler(request, h) {\n  const { payload } = request\n  const session = getSessionState(request)\n\n  const { value: manual, error } = manualPayloadSchema.validate(payload, {\n    abortEarly: false\n  })\n\n  if (error) {\n    const model = manualViewModel(session, manual, error)\n\n    return h.view(viewName, model)\n  }\n\n  const { componentName, sourceUrl } = session.initial\n  flashComponentState(request, componentName, manual)\n\n  // Redirect back to the source form page\n  return h.redirect(sourceUrl).code(StatusCodes.SEE_OTHER)\n}\n\n/**\n * @import { ResponseToolkit, ServerRoute } from '@hapi/hapi'\n * @import { PostcodeLookupManualPayload, Address, PostcodeLookupGetRequestRefs, PostcodeLookupPostRequestRefs, PostcodeLookupRequest, PostcodeLookupPostRequest, PostcodeLookupConfiguration, PostcodeLookupDispatchData, PostcodeLookupSessionData } from '~/src/server/plugins/postcode-lookup/types.js'\n * @import { FormRequestPayload, FormResponseToolkit } from '~/src/server/routes/types.js'\n * @import { ExternalStateAppendage } from '~/src/server/plugins/engine/types.js'\n */\n"],"mappings":"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","ignoreList":[]}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@defra/forms-engine-plugin",
-  "version": "4.0.27",
+  "version": "4.0.29",
   "description": "Defra forms engine",
   "type": "module",
   "files": [
@@ -66,7 +66,7 @@
   },
   "engines": {
     "node": ">=22.11.0 <25.0.0",
-    "npm": "^10.9.0"
+    "npm": ">=10.9.0 <11.6.4"
   },
   "license": "SEE LICENSE IN LICENSE",
   "dependencies": {

package/src/server/plugins/engine/beta/form-context.test.ts

@@ -0,0 +1,359 @@
+import { type Request } from '@hapi/hapi'
+
+import {
+  getFirstJourneyPage,
+  getFormContext,
+  getFormModel,
+  resolveFormModel,
+  type FormModelOptions
+} from '~/src/server/plugins/engine/beta/form-context.js'
+import { PageController } from '~/src/server/plugins/engine/pageControllers/PageController.js'
+import { type PageControllerClass } from '~/src/server/plugins/engine/pageControllers/helpers/pages.js'
+import { type FormContext } from '~/src/server/plugins/engine/types.js'
+import { FormStatus } from '~/src/server/routes/types.js'
+import { type FormsService, type Services } from '~/src/server/types.js'
+
+const mockGetCacheService = jest.fn()
+const mockCacheService = { getState: jest.fn() }
+const mockCheckEmailAddressForLiveFormSubmission = jest.fn()
+
+jest.mock('../models/index.ts', () => ({
+  __esModule: true,
+  FormModel: jest.fn()
+}))
+
+jest.mock('~/src/server/plugins/engine/services/index.js', () => ({
+  __esModule: true,
+  formsService: {
+    getFormMetadata: jest.fn(),
+    getFormDefinition: jest.fn()
+  },
+  formSubmissionService: {},
+  outputService: {}
+}))
+
+jest.mock('../pageControllers/index.ts', () => {
+  class MockTerminalPageController {
+    path = ''
+  }
+
+  return {
+    __esModule: true,
+    TerminalPageController: MockTerminalPageController
+  }
+})
+
+jest.mock('../helpers.ts', () => ({
+  __esModule: true,
+  getCacheService: (...args: unknown[]) => mockGetCacheService(...args),
+  checkEmailAddressForLiveFormSubmission: (...args: unknown[]) =>
+    mockCheckEmailAddressForLiveFormSubmission(...args)
+}))
+
+const mockServices = jest.requireMock(
+  '~/src/server/plugins/engine/services/index.js'
+)
+const mockFormsService = mockServices.formsService
+const { FormModel } = jest.requireMock('../models/index.ts')
+const { TerminalPageController: MockTerminalPageController } = jest.requireMock(
+  '../pageControllers/index.ts'
+)
+
+describe('getFormContext helper', () => {
+  const request = {
+    yar: { set: jest.fn() } as unknown as Request['yar'],
+    server: {
+      app: {},
+      realm: { modifiers: { route: { prefix: '' } } }
+    } as unknown as Request['server']
+  } satisfies Pick<Request, 'yar' | 'server'>
+  const slug = 'tb-origin'
+  const cachedState = { answered: true }
+  const returnedContext = { errors: [] }
+  const metadata = {
+    id: 'metadata-123',
+    live: { updatedAt: new Date('2024-10-15T10:00:00Z') },
+    draft: { updatedAt: new Date('2024-10-10T10:00:00Z') },
+    versions: [{ versionNumber: 9 }],
+    notificationEmail: 'test@example.com'
+  }
+  const definition = { pages: [] }
+  let formModel: { getFormContext: jest.Mock }
+
+  beforeEach(() => {
+    jest.clearAllMocks()
+    formModel = { getFormContext: jest.fn().mockResolvedValue(returnedContext) }
+    FormModel.mockImplementation(
+      (_definition: unknown, modelOptions: FormModelOptions) =>
+        Object.assign(formModel, { basePath: modelOptions.basePath })
+    )
+    mockFormsService.getFormMetadata.mockResolvedValue(metadata)
+    mockFormsService.getFormDefinition.mockResolvedValue(definition)
+    mockGetCacheService.mockReturnValue(mockCacheService)
+    mockCacheService.getState.mockResolvedValue(cachedState)
+  })
+
+  test('passes preview state into the summary request and uses cached reference numbers', async () => {
+    const errors = [
+      { href: '#field', name: 'field', path: ['field'], text: 'is required' }
+    ]
+
+    mockCacheService.getState.mockResolvedValue({
+      ...cachedState,
+      $$__referenceNumber: 'CACHED-REF'
+    })
+
+    const context = await getFormContext(request, slug, 'preview', {
+      errors
+    })
+
+    const summaryRequest = mockCacheService.getState.mock.calls[0][0]
+
+    expect(summaryRequest.params).toEqual({
+      path: 'summary',
+      slug,
+      state: 'live'
+    })
+    expect(summaryRequest.path).toBe('/preview/live/tb-origin/summary')
+    expect(summaryRequest.url.toString()).toBe(
+      'https://form-context.local/preview/live/tb-origin/summary'
+    )
+
+    expect(formModel.getFormContext).toHaveBeenCalledWith(
+      summaryRequest,
+      expect.objectContaining({ $$__referenceNumber: 'CACHED-REF' }),
+      errors
+    )
+    expect(context).toBe(returnedContext)
+  })
+})
+
+describe('getFormModel helper', () => {
+  const slug = 'tb-origin'
+  const state = FormStatus.Draft
+  class CustomController extends PageController {}
+  const controllers = { CustomController }
+  const metadata = {
+    id: 'form-meta-123',
+    versions: [{ versionNumber: 17 }]
+  }
+  const definition = { pages: [{ path: '/start' }] }
+  let formsService: FormsService
+  let services: Services
+  let formModelInstance: { id: string }
+
+  beforeEach(() => {
+    jest.clearAllMocks()
+    formModelInstance = { id: 'form-model-instance' }
+    FormModel.mockImplementation(() => formModelInstance)
+    services = {
+      formsService: {
+        getFormMetadata: jest.fn().mockResolvedValue(metadata),
+        getFormMetadataById: jest.fn(),
+        getFormDefinition: jest.fn().mockResolvedValue(definition)
+      },
+      formSubmissionService: {
+        persistFiles: jest.fn(),
+        submit: jest.fn()
+      },
+      outputService: {
+        submit: jest.fn()
+      }
+    }
+    formsService = services.formsService
+  })
+
+  test('constructs a FormModel using fetched metadata and definition', async () => {
+    const model = await getFormModel(slug, state, { services, controllers })
+
+    expect(formsService.getFormMetadata).toHaveBeenCalledWith(slug)
+    expect(formsService.getFormDefinition).toHaveBeenCalledWith(
+      metadata.id,
+      state
+    )
+    expect(FormModel).toHaveBeenCalledWith(
+      definition,
+      {
+        basePath: slug,
+        versionNumber: metadata.versions[0].versionNumber,
+        ordnanceSurveyApiKey: undefined,
+        formId: metadata.id
+      },
+      services,
+      controllers
+    )
+    expect(model).toBe(formModelInstance)
+  })
+
+  test('maps preview state requests to the live form definition', async () => {
+    await getFormModel(slug, 'preview', { services, controllers })
+
+    expect(formsService.getFormDefinition).toHaveBeenCalledWith(
+      metadata.id,
+      'live'
+    )
+  })
+
+  test('throws when no form definition is available', async () => {
+    jest.mocked(formsService.getFormDefinition).mockResolvedValue(undefined)
+
+    await expect(
+      getFormModel(slug, state, { services, controllers })
+    ).rejects.toThrow(
+      `No definition found for form metadata ${metadata.id} (${slug}) ${state}`
+    )
+
+    expect(FormModel).not.toHaveBeenCalled()
+  })
+})
+
+describe('resolveFormModel helper', () => {
+  const slug = 'tb-origin'
+  const definition = { pages: [], outputEmail: 'fallback@example.com' }
+  const metadata = {
+    id: 'metadata-123',
+    live: { updatedAt: new Date('2024-10-15T10:00:00Z') },
+    versions: [{ versionNumber: 9 }]
+  }
+  let server: Request['server']
+  let formModelInstance: { id: string }
+
+  beforeEach(() => {
+    jest.clearAllMocks()
+    server = {
+      app: {},
+      realm: { modifiers: { route: { prefix: '/forms/' } } }
+    } as unknown as Request['server']
+    formModelInstance = { id: 'form-model-instance' }
+    FormModel.mockImplementation(() => formModelInstance)
+    mockFormsService.getFormMetadata.mockResolvedValue(metadata)
+    mockFormsService.getFormDefinition.mockResolvedValue(definition)
+  })
+
+  test('reuses cached models when metadata timestamps match', async () => {
+    const model = await resolveFormModel(server, slug, FormStatus.Live)
+    const cached = await resolveFormModel(server, slug, FormStatus.Live)
+
+    expect(model).toBe(formModelInstance)
+    expect(cached).toBe(model)
+    expect(server.app.models).toBeInstanceOf(Map)
+    expect(mockFormsService.getFormDefinition).toHaveBeenCalledTimes(1)
+    expect(FormModel).toHaveBeenCalledTimes(1)
+  })
+
+  test('rebuilds the model when metadata changes and uses preview routing', async () => {
+    const refreshedModel = { id: 'refreshed-model' }
+
+    FormModel.mockImplementationOnce(
+      () => formModelInstance
+    ).mockImplementationOnce(() => refreshedModel)
+    mockFormsService.getFormMetadata
+      .mockResolvedValueOnce({ ...metadata, notificationEmail: undefined })
+      .mockResolvedValueOnce({
+        ...metadata,
+        notificationEmail: undefined,
+        live: { updatedAt: new Date('2024-12-01T09:00:00Z') }
+      })
+
+    const model = await resolveFormModel(server, slug, 'preview', {
+      ordnanceSurveyApiKey: 'os-api-key'
+    })
+    const rebuilt = await resolveFormModel(server, slug, 'preview')
+
+    expect(model).toBe(formModelInstance)
+    expect(rebuilt).toBe(refreshedModel)
+    expect(FormModel).toHaveBeenCalledTimes(2)
+    expect(mockFormsService.getFormDefinition).toHaveBeenCalledTimes(2)
+    expect(mockCheckEmailAddressForLiveFormSubmission).toHaveBeenCalledWith(
+      definition.outputEmail,
+      true
+    )
+    expect(FormModel).toHaveBeenCalledWith(
+      definition,
+      expect.objectContaining({
+        basePath: 'forms/preview/live/tb-origin',
+        versionNumber: metadata.versions[0].versionNumber,
+        ordnanceSurveyApiKey: 'os-api-key',
+        formId: metadata.id
+      }),
+      mockServices,
+      undefined
+    )
+  })
+
+  test('throws when requested form state does not exist on metadata', async () => {
+    mockFormsService.getFormMetadata.mockResolvedValue({
+      id: 'metadata-123',
+      live: { updatedAt: new Date('2024-10-15T10:00:00Z') }
+    })
+
+    await expect(
+      resolveFormModel(server, slug, FormStatus.Draft)
+    ).rejects.toThrow("No 'draft' state for form metadata metadata-123")
+
+    expect(FormModel).not.toHaveBeenCalled()
+  })
+
+  test('throws when no form definition is available for the requested state', async () => {
+    mockFormsService.getFormDefinition.mockResolvedValue(undefined)
+
+    await expect(
+      resolveFormModel(server, slug, FormStatus.Live)
+    ).rejects.toThrow(
+      `No definition found for form metadata ${metadata.id} (${slug}) ${FormStatus.Live}`
+    )
+
+    expect(FormModel).not.toHaveBeenCalled()
+    expect(mockCheckEmailAddressForLiveFormSubmission).not.toHaveBeenCalled()
+  })
+})
+
+describe('getFirstJourneyPage helper', () => {
+  const buildPage = (path: string, keys: string[] = []) =>
+    ({ path, keys }) as unknown as PageControllerClass
+
+  test('returns undefined when no context or relevant target path is available', () => {
+    expect(getFirstJourneyPage()).toBeUndefined()
+    expect(getFirstJourneyPage({ relevantPages: [] })).toBeUndefined()
+  })
+
+  test('returns the page matching the last recorded path', () => {
+    const startPage = buildPage('/start')
+    const nextPage = buildPage('/animals')
+
+    const context: Pick<FormContext, 'relevantPages'> = {
+      relevantPages: [startPage, nextPage]
+    }
+
+    expect(getFirstJourneyPage(context)).toBe(nextPage)
+  })
+
+  test('steps back from terminal pages to the previous relevant page', () => {
+    const startPage = buildPage('/start')
+    const exitPage = Object.assign(new MockTerminalPageController(), {
+      path: '/stop'
+    }) as unknown as PageControllerClass
+
+    const context: Pick<FormContext, 'relevantPages'> = {
+      relevantPages: [startPage, exitPage]
+    }
+
+    expect(getFirstJourneyPage(context)).toBe(startPage)
+  })
+
+  test('returns the terminal page when it is the only relevant page available', () => {
+    const exitPage = Object.assign(new MockTerminalPageController(), {
+      path: '/stop'
+    }) as unknown as PageControllerClass
+
+    const context: Pick<FormContext, 'relevantPages'> = {
+      relevantPages: [exitPage]
+    }
+
+    expect(getFirstJourneyPage(context)).toBe(exitPage)
+  })
+})
+
+/**
+ * @import { FormContext } from '../types.js'
+ */