@defra/forms-engine-plugin 2.1.10 → 3.0.1

package/src/server/plugins/engine/routes/repeaters/item-delete.ts

@@ -1,10 +1,6 @@
 import { slugSchema } from '@defra/forms-model'
 import Boom from '@hapi/boom'
-import {
-  type ResponseToolkit,
-  type RouteOptions,
-  type ServerRoute
-} from '@hapi/hapi'
+import { type RouteOptions, type ServerRoute } from '@hapi/hapi'
 import Joi from 'joi'
 
 import { FileUploadPageController } from '~/src/server/plugins/engine/pageControllers/FileUploadPageController.js'
@@ -14,7 +10,8 @@ import {
   type FormRequest,
   type FormRequestPayload,
   type FormRequestPayloadRefs,
-  type FormRequestRefs
+  type FormRequestRefs,
+  type FormResponseToolkit
 } from '~/src/server/routes/types.js'
 import {
   actionSchema,
@@ -26,10 +23,7 @@ import {
 } from '~/src/server/schemas/index.js'
 
 // Item delete GET route
-function getHandler(
-  request: FormRequest,
-  h: Pick<ResponseToolkit, 'redirect' | 'view'>
-) {
+function getHandler(request: FormRequest, h: FormResponseToolkit) {
   const { params } = request
 
   return redirectOrMakeHandler(request, h, (page, context) => {
@@ -46,10 +40,7 @@ function getHandler(
   })
 }
 
-function postHandler(
-  request: FormRequestPayload,
-  h: Pick<ResponseToolkit, 'redirect' | 'view'>
-) {
+function postHandler(request: FormRequestPayload, h: FormResponseToolkit) {
   const { params } = request
 
   return redirectOrMakeHandler(request, h, (page, context) => {

package/src/server/plugins/engine/routes/repeaters/summary.ts

@@ -1,11 +1,7 @@
 // List summary GET route
 import { slugSchema } from '@defra/forms-model'
 import Boom from '@hapi/boom'
-import {
-  type ResponseToolkit,
-  type RouteOptions,
-  type ServerRoute
-} from '@hapi/hapi'
+import { type RouteOptions, type ServerRoute } from '@hapi/hapi'
 import Joi from 'joi'
 
 import { RepeatPageController } from '~/src/server/plugins/engine/pageControllers/RepeatPageController.js'
@@ -14,7 +10,8 @@ import {
   type FormRequest,
   type FormRequestPayload,
   type FormRequestPayloadRefs,
-  type FormRequestRefs
+  type FormRequestRefs,
+  type FormResponseToolkit
 } from '~/src/server/routes/types.js'
 import {
   actionSchema,
@@ -23,10 +20,7 @@ import {
   stateSchema
 } from '~/src/server/schemas/index.js'
 
-function getHandler(
-  request: FormRequest,
-  h: Pick<ResponseToolkit, 'redirect' | 'view'>
-) {
+function getHandler(request: FormRequest, h: FormResponseToolkit) {
   const { params } = request
 
   return redirectOrMakeHandler(request, h, (page, context) => {
@@ -38,10 +32,7 @@ function getHandler(
   })
 }
 
-function postHandler(
-  request: FormRequestPayload,
-  h: Pick<ResponseToolkit, 'redirect' | 'view'>
-) {
+function postHandler(request: FormRequestPayload, h: FormResponseToolkit) {
   const { params } = request
 
   return redirectOrMakeHandler(request, h, (page, context) => {

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

@@ -1,4 +1,6 @@
 export type {
+  AnyFormRequest,
+  AnyRequest,
   CheckAnswers,
   ErrorMessageTemplate,
   ErrorMessageTemplateList,
@@ -74,7 +76,8 @@ export type {
   FormRequest,
   FormRequestPayload,
   FormRequestPayloadRefs,
-  FormRequestRefs
+  FormRequestRefs,
+  FormResponseToolkit
 } from '~/src/server/routes/types.js'
 
 export { FormAction, FormStatus } from '~/src/server/routes/types.js'

package/src/server/plugins/engine/types/schema.test.ts

@@ -156,5 +156,45 @@ describe('Schema validation', () => {
         formAdapterSubmissionMessagePayloadSchema.validate(payloadWithoutData)
       expect(error).toBeDefined()
     })
+
+    it('should validate payload with versionMetadata', () => {
+      const payloadWithVersion = {
+        ...validPayload,
+        meta: {
+          ...validPayload.meta,
+          versionMetadata: {
+            versionNumber: 19,
+            createdAt: new Date('2025-09-08T09:28:15.576Z')
+          }
+        }
+      }
+      const { error } =
+        formAdapterSubmissionMessagePayloadSchema.validate(payloadWithVersion)
+      expect(error).toBeUndefined()
+    })
+
+    it('should validate payload without versionMetadata', () => {
+      const { error } =
+        formAdapterSubmissionMessagePayloadSchema.validate(validPayload)
+      expect(error).toBeUndefined()
+    })
+
+    it('should reject invalid versionMetadata', () => {
+      const payloadWithInvalidVersion = {
+        ...validPayload,
+        meta: {
+          ...validPayload.meta,
+          versionMetadata: {
+            versionNumber: 'not-a-number', // Invalid - should be number
+            createdAt: new Date('2025-09-08T09:28:15.576Z')
+          }
+        }
+      }
+      const { error } = formAdapterSubmissionMessagePayloadSchema.validate(
+        payloadWithInvalidVersion
+      )
+      expect(error).toBeDefined()
+      expect(error?.message).toContain('must be a number')
+    })
   })
 })

package/src/server/plugins/engine/types/schema.ts

@@ -1,5 +1,6 @@
 import {
   FormStatus,
+  formVersionMetadataSchema,
   idSchema,
   notificationEmailAddressSchema,
   slugSchema,
@@ -29,7 +30,8 @@ export const formAdapterSubmissionMessageMetaSchema =
       .valid(...Object.values(FormStatus))
       .required(),
     isPreview: Joi.boolean().required(),
-    notificationEmail: notificationEmailAddressSchema.required()
+    notificationEmail: notificationEmailAddressSchema.required(),
+    versionMetadata: formVersionMetadataSchema.optional()
   })
 
 export const formAdapterSubmissionMessageDataSchema =

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

@@ -3,11 +3,16 @@ import {
   type Event,
   type FormDefinition,
   type FormMetadata,
+  type FormVersionMetadata,
   type Item,
   type List,
   type Page
 } from '@defra/forms-model'
-import { type PluginProperties, type Request } from '@hapi/hapi'
+import {
+  type PluginProperties,
+  type Request,
+  type ResponseObject
+} from '@hapi/hapi'
 import { type JoiExpression, type ValidationErrorItem } from 'joi'
 
 import { FormComponent } from '~/src/server/plugins/engine/components/FormComponent.js'
@@ -36,12 +41,15 @@ import {
   type FormParams,
   type FormRequest,
   type FormRequestPayload,
+  type FormResponseToolkit,
   type FormStatus
 } from '~/src/server/routes/types.js'
+import { type CacheService } from '~/src/server/services/cacheService.js'
 import { type RequestOptions } from '~/src/server/services/httpService.js'
 import { type Services } from '~/src/server/types.js'
 
-type RequestType = Request | FormRequest | FormRequestPayload
+export type AnyFormRequest = FormRequest | FormRequestPayload
+export type AnyRequest = Request | AnyFormRequest
 
 /**
  * Form submission state stores the following in Redis:
@@ -172,6 +180,7 @@ export interface FormContext {
   pageMap: Map<string, PageControllerClass>
   componentMap: Map<string, Component>
   referenceNumber: string
+  submittedVersionNumber?: number
 }
 
 export type FormContextRequest = (
@@ -312,7 +321,7 @@ export interface FormPageViewModel extends PageViewModelBase {
   context: FormContext
   errors?: FormSubmissionError[]
   hasMissingNotificationEmail?: boolean
-  allowSaveAndReturn: boolean
+  allowSaveAndExit: boolean
 }
 
 export interface RepeaterSummaryPageViewModel extends PageViewModelBase {
@@ -357,27 +366,26 @@ export type PreparePageEventRequestOptions = (
 ) => void
 
 export type OnRequestCallback = (
-  request: FormRequest | FormRequestPayload,
+  request: AnyFormRequest,
   params: FormParams,
   definition: FormDefinition,
   metadata: FormMetadata
 ) => void
 
+export type SaveAndExitHandler = (
+  request: FormRequestPayload,
+  h: FormResponseToolkit,
+  context: FormContext
+) => ResponseObject
+
 export interface PluginOptions {
   model?: FormModel
   services?: Services
   controllers?: Record<string, typeof PageController>
-  cacheName?: string
+  cache?: CacheService | string
   globals?: Record<string, GlobalFunction>
   filters?: Record<string, FilterFunction>
-  saveAndReturn?: {
-    keyGenerator: (request: RequestType) => string
-    sessionHydrator: (request: RequestType) => Promise<FormSubmissionState>
-    sessionPersister: (
-      state: FormSubmissionState,
-      request: RequestType
-    ) => Promise<void>
-  }
+  saveAndExit?: SaveAndExitHandler
   pluginPath?: string
   nunjucks: {
     baseLayoutPath: string
@@ -399,6 +407,7 @@ export interface FormAdapterSubmissionMessageMeta {
   status: FormStatus
   isPreview: boolean
   notificationEmail: string
+  versionMetadata?: FormVersionMetadata
 }
 
 export type FormAdapterSubmissionMessageMetaSerialised = Omit<

package/src/server/plugins/engine/views/partials/form.html

@@ -13,12 +13,12 @@
       preventDoubleClick: true
     }) }}
 
-    {% if allowSaveAndReturn %}
+    {% if allowSaveAndExit %}
       {{ govukButton({
-        text: "Save and return",
+        text: "Save and exit",
         classes: "govuk-button--secondary",
         name: "action",
-        value: "save-and-return",
+        value: "save-and-exit",
         preventDoubleClick: true
       }) }}
     {% endif %}

package/src/server/plugins/engine/views/summary.html

@@ -2,6 +2,7 @@
 
 {% from "govuk/components/error-summary/macro.njk" import govukErrorSummary %}
 {% from "govuk/components/summary-list/macro.njk" import govukSummaryList %}
+{% from "govuk/components/button/macro.njk" import govukButton %}
 {% from "partials/components.html" import componentList with context %}
 
 {% block content %}
@@ -31,7 +32,6 @@
 
       <form method="post" novalidate>
         <input type="hidden" name="crumb" value="{{ crumb }}">
-        <input type="hidden" name="action" value="send">
 
         {% if declaration %}
           <h2 class="govuk-heading-m" id="declaration">Declaration</h2>
@@ -42,10 +42,26 @@
 
         {{ componentList(components) }}
 
-        {% set isDeclaration = declaration or components | length %}
-        <button data-prevent-double-click="true" class="govuk-button" data-module="govuk-button">
-          {{ "Accept and send" if isDeclaration else "Send" }}
-        </button>
+        <div class="govuk-button-group">
+          {% set isDeclaration = declaration or components | length %}
+
+          {{ govukButton({
+            text: "Accept and send" if isDeclaration else "Send",
+            name: "action",
+            value: "send",
+            preventDoubleClick: true
+          }) }}
+
+          {% if allowSaveAndExit %}
+            {{ govukButton({
+              text: "Save and exit",
+              classes: "govuk-button--secondary",
+              name: "action",
+              value: "save-and-exit",
+              preventDoubleClick: true
+            }) }}
+          {% endif %}
+        </div>
       </form>
     </div>
   </div>

package/src/server/plugins/nunjucks/context.js

@@ -18,7 +18,7 @@ const logger = createLogger()
 let webpackManifest
 
 /**
- * @param {FormRequest | FormRequestPayload | null} request
+ * @param {AnyFormRequest | null} request
  */
 export async function context(request) {
   const { params, response } = request ?? {}
@@ -62,7 +62,7 @@ export async function context(request) {
 
 /**
  * Returns the context for the devtool. Consumers won't have access to this.
- * @param {FormRequest | FormRequestPayload | null} _request
+ * @param {AnyFormRequest | null} _request
  * @returns {Record<string, unknown> & { assetPath: string, getDxtAssetPath: (asset: string) => string }}
  */
 export function devtoolContext(_request) {
@@ -97,5 +97,5 @@ export function devtoolContext(_request) {
 
 /**
  * @import { ViewContext } from '~/src/server/plugins/nunjucks/types.js'
- * @import { FormRequest, FormRequestPayload } from '~/src/server/routes/types.js'
+ * @import { AnyFormRequest } from '~/src/server/plugins/engine/types.js'
  */

package/src/server/routes/types.ts

@@ -1,4 +1,8 @@
-import { type ReqRefDefaults, type Request } from '@hapi/hapi'
+import {
+  type ReqRefDefaults,
+  type Request,
+  type ResponseToolkit
+} from '@hapi/hapi'
 
 import { type FormPayload } from '~/src/server/plugins/engine/types.js'
 
@@ -33,6 +37,7 @@ export interface FormRequestPayloadRefs extends FormRequestRefs {
 
 export type FormRequest = Request<FormRequestRefs>
 export type FormRequestPayload = Request<FormRequestPayloadRefs>
+export type FormResponseToolkit = Pick<ResponseToolkit, 'redirect' | 'view'>
 
 export enum FormAction {
   Continue = 'continue',
@@ -40,7 +45,7 @@ export enum FormAction {
   Delete = 'delete',
   AddAnother = 'add-another',
   Send = 'send',
-  SaveAndReturn = 'save-and-return'
+  SaveAndExit = 'save-and-exit'
 }
 
 export enum FormStatus {

package/src/server/schemas/index.ts

@@ -14,7 +14,7 @@ export const actionSchema = Joi.string<FormAction>()
     FormAction.Delete,
     FormAction.AddAnother,
     FormAction.Send,
-    FormAction.SaveAndReturn
+    FormAction.SaveAndExit
   )
   .default(FormAction.Validate)
   .optional()

package/src/server/services/cacheService.test.ts

@@ -2,11 +2,7 @@ import { type Request, type Server } from '@hapi/hapi'
 
 import { config } from '~/src/config/index.js'
 import { type FormRequest } from '~/src/server/routes/types.js'
-import {
-  ADDITIONAL_IDENTIFIER,
-  CacheService,
-  merge
-} from '~/src/server/services/cacheService.js'
+import { CacheService, merge } from '~/src/server/services/cacheService.js'
 
 describe('CacheService', () => {
   let mockServer: Partial<Server>
@@ -76,63 +72,6 @@ describe('CacheService', () => {
         expect(result).toEqual({})
       })
     })
-
-    it('should rehydrate state using custom fetcher when cache is missed', async () => {
-      const rehydratedState = { rehydrated: true }
-
-      const customFetcher = jest.fn().mockResolvedValue(rehydratedState)
-
-      cacheService = new CacheService({
-        server: mockServer as Server,
-        cacheName: 'test-cache',
-        options: { sessionHydrator: customFetcher }
-      })
-
-      const mockRequest = {
-        yar: { id: 'session-id' },
-        params: { state: 's', slug: 'p' }
-      } as unknown as FormRequest
-
-      mockCache.get
-        .mockResolvedValueOnce(null)
-        .mockResolvedValueOnce(rehydratedState)
-
-      const result = await cacheService.getState(mockRequest)
-
-      expect(customFetcher).toHaveBeenCalledWith(mockRequest)
-      expect(mockCache.set).toHaveBeenCalledWith(
-        expect.objectContaining({
-          segment: 'cache',
-          id: expect.stringContaining('session-id')
-        }),
-        rehydratedState,
-        config.get('sessionTimeout')
-      )
-      expect(result).toEqual(rehydratedState)
-    })
-
-    it('should return empty object when custom fetcher returns null', async () => {
-      const customFetcher = jest.fn().mockResolvedValue(null)
-
-      cacheService = new CacheService({
-        server: mockServer as Server,
-        cacheName: 'test-cache',
-        options: { sessionHydrator: customFetcher }
-      })
-
-      const mockRequest = {
-        yar: { id: 'session-id' },
-        params: { state: 's', slug: 'p' }
-      } as unknown as FormRequest
-
-      mockCache.get.mockResolvedValue(null)
-
-      const result = await cacheService.getState(mockRequest)
-
-      expect(customFetcher).toHaveBeenCalledWith(mockRequest)
-      expect(mockCache.set).not.toHaveBeenCalled()
-      expect(result).toEqual({})
-    })
   })
 
   describe('setState', () => {
@@ -178,61 +117,6 @@ describe('CacheService', () => {
         )
       })
     })
-
-    it('should use custom key generator if provided', async () => {
-      const customKey = 'my-custom-key'
-      const customKeyGenerator = jest.fn().mockReturnValue(customKey)
-
-      cacheService = new CacheService({
-        server: mockServer as Server,
-        cacheName: 'test-cache',
-        options: { keyGenerator: customKeyGenerator }
-      })
-
-      const mockRequest = {
-        yar: { id: 'some-session' },
-        params: { state: 'form1', slug: 'page1' }
-      } as unknown as FormRequest
-
-      await cacheService.setState(mockRequest, { test: 'value' })
-
-      expect(mockCache.set).toHaveBeenCalledWith(
-        {
-          segment: 'cache',
-          id: 'my-custom-key'
-        },
-        { test: 'value' },
-        expect.any(Number)
-      )
-    })
-
-    it('should append additionalIdentifier to custom key', () => {
-      const customKey = 'custom:key:base:'
-      const customKeyGenerator = jest.fn().mockReturnValue(customKey)
-
-      cacheService = new CacheService({
-        server: mockServer as Server,
-        cacheName: 'test-cache',
-        options: { keyGenerator: customKeyGenerator }
-      })
-
-      const mockRequest = {
-        yar: { id: 'session-id' },
-        params: { state: 'formA', slug: 'step1' }
-      } as unknown as FormRequest
-
-      const result = cacheService.Key(
-        mockRequest,
-        ADDITIONAL_IDENTIFIER.Confirmation
-      )
-
-      expect(result).toEqual({
-        segment: 'cache',
-        id: 'custom:key:base::confirmation'
-      })
-
-      expect(customKeyGenerator).toHaveBeenCalledWith(mockRequest)
-    })
   })
 
   describe('merge', () => {