@defra/forms-engine-plugin 2.1.10 → 3.0.1

package/src/server/plugins/engine/outputFormatters/adapter/v1.test.ts

@@ -11,7 +11,10 @@ import {
   type DetailItemField,
   type DetailItemRepeat
 } from '~/src/server/plugins/engine/models/types.js'
-import { format } from '~/src/server/plugins/engine/outputFormatters/adapter/v1.js'
+import {
+  format,
+  getVersionMetadata
+} from '~/src/server/plugins/engine/outputFormatters/adapter/v1.js'
 import { buildFormContextRequest } from '~/src/server/plugins/engine/pageControllers/__stubs__/request.js'
 import { FormAdapterSubmissionSchemaVersion } from '~/src/server/plugins/engine/types/index.js'
 import {
@@ -207,7 +210,7 @@ describe('Adapter v1 formatter', () => {
   })
 
   it('should return the adapter v1 output with complete formMetadata', () => {
-    const formMetadata: FormMetadata = {
+    const formMetadata: Partial<FormMetadata> = {
       id: 'form-123',
       slug: 'test-form',
       title: 'Test Form',
@@ -225,7 +228,7 @@ describe('Adapter v1 formatter', () => {
       model,
       submitResponse,
       formStatus,
-      formMetadata
+      formMetadata as FormMetadata
     )
     const parsedBody = JSON.parse(body) as FormAdapterSubmissionMessagePayload
 
@@ -284,7 +287,7 @@ describe('Adapter v1 formatter', () => {
   })
 
   it('should handle preview form status correctly', () => {
-    const formMetadata: FormMetadata = {
+    const formMetadata: Partial<FormMetadata> = {
       id: 'form-123',
       slug: 'test-form',
       title: 'Test Form',
@@ -302,7 +305,7 @@ describe('Adapter v1 formatter', () => {
       model,
       submitResponse,
       formStatus,
-      formMetadata
+      formMetadata as FormMetadata
     )
     const parsedBody = JSON.parse(body) as FormAdapterSubmissionMessagePayload
 
@@ -327,7 +330,7 @@ describe('Adapter v1 formatter', () => {
   })
 
   it('should handle partial formMetadata', () => {
-    const formMetadata: FormMetadata = {
+    const formMetadata: Partial<FormMetadata> = {
       id: 'form-456',
       slug: 'partial-form',
       title: 'Partial Form'
@@ -344,7 +347,7 @@ describe('Adapter v1 formatter', () => {
       model,
       submitResponse,
       formStatus,
-      formMetadata
+      formMetadata as FormMetadata
     )
     const parsedBody = JSON.parse(body) as FormAdapterSubmissionMessagePayload
 
@@ -452,7 +455,7 @@ describe('Adapter v1 formatter', () => {
   })
 
   it('should handle formMetadata with only id', () => {
-    const formMetadata: FormMetadata = {
+    const formMetadata: Partial<FormMetadata> = {
       id: 'only-id-form'
     } as FormMetadata
 
@@ -467,7 +470,7 @@ describe('Adapter v1 formatter', () => {
       model,
       submitResponse,
       formStatus,
-      formMetadata
+      formMetadata as FormMetadata
     )
     const parsedBody = JSON.parse(body) as FormAdapterSubmissionMessagePayload
 
@@ -477,7 +480,7 @@ describe('Adapter v1 formatter', () => {
   })
 
   it('should handle formMetadata with only slug', () => {
-    const formMetadata: FormMetadata = {
+    const formMetadata: Partial<FormMetadata> = {
       slug: 'only-slug-form'
     } as FormMetadata
 
@@ -492,7 +495,7 @@ describe('Adapter v1 formatter', () => {
       model,
       submitResponse,
       formStatus,
-      formMetadata
+      formMetadata as FormMetadata
     )
     const parsedBody = JSON.parse(body) as FormAdapterSubmissionMessagePayload
 
@@ -502,7 +505,7 @@ describe('Adapter v1 formatter', () => {
   })
 
   it('should handle formMetadata with only notificationEmail', () => {
-    const formMetadata: FormMetadata = {
+    const formMetadata: Partial<FormMetadata> = {
       notificationEmail: 'only-email@example.com'
     } as FormMetadata
 
@@ -517,7 +520,7 @@ describe('Adapter v1 formatter', () => {
       model,
       submitResponse,
       formStatus,
-      formMetadata
+      formMetadata as FormMetadata
     )
     const parsedBody = JSON.parse(body) as FormAdapterSubmissionMessagePayload
 
@@ -693,4 +696,434 @@ describe('Adapter v1 formatter', () => {
       }
     })
   })
+
+  it('should handle missing versionMetadata gracefully', () => {
+    const formMetadata: Partial<FormMetadata> = {
+      id: 'form-123',
+      slug: 'test-form',
+      title: 'Test Form',
+      notificationEmail: 'test@example.com'
+    } as FormMetadata
+
+    const formStatus = {
+      isPreview: false,
+      state: FormStatus.Live
+    }
+
+    const body = format(
+      context,
+      items,
+      model,
+      submitResponse,
+      formStatus,
+      formMetadata as FormMetadata
+    )
+    const parsedBody = JSON.parse(body) as FormAdapterSubmissionMessagePayload
+
+    expect(parsedBody.meta.versionMetadata).toBeUndefined()
+  })
+
+  describe('version metadata handling', () => {
+    it('should include versionMetadata when context has submittedVersionNumber and formMetadata has versions', () => {
+      const formMetadata: Partial<FormMetadata> = {
+        id: 'form-123',
+        slug: 'test-form',
+        title: 'Test Form',
+        notificationEmail: 'test@example.com',
+        versions: [
+          {
+            versionNumber: 1,
+            createdAt: new Date('2024-01-01T00:00:00.000Z')
+          },
+          {
+            versionNumber: 2,
+            createdAt: new Date('2024-01-15T00:00:00.000Z')
+          }
+        ]
+      }
+
+      const modelWithVersion = new FormModel(definition, {
+        basePath: 'test',
+        versionNumber: 2
+      })
+
+      const contextWithVersion = modelWithVersion.getFormContext(request, state)
+
+      const formStatus = {
+        isPreview: false,
+        state: FormStatus.Live
+      }
+
+      const body = format(
+        contextWithVersion,
+        items,
+        modelWithVersion,
+        submitResponse,
+        formStatus,
+        formMetadata as FormMetadata
+      )
+      const parsedBody = JSON.parse(body) as FormAdapterSubmissionMessagePayload
+
+      expect(parsedBody.meta.versionMetadata).toEqual({
+        versionNumber: 2,
+        createdAt: '2024-01-15T00:00:00.000Z'
+      })
+    })
+
+    it('should use first version as fallback when submittedVersionNumber is undefined', () => {
+      const formMetadata: Partial<FormMetadata> = {
+        id: 'form-123',
+        slug: 'test-form',
+        title: 'Test Form',
+        notificationEmail: 'test@example.com',
+        versions: [
+          {
+            versionNumber: 1,
+            createdAt: new Date('2024-01-01T00:00:00.000Z')
+          },
+          {
+            versionNumber: 2,
+            createdAt: new Date('2024-01-15T00:00:00.000Z')
+          }
+        ]
+      }
+
+      const formStatus = {
+        isPreview: false,
+        state: FormStatus.Live
+      }
+
+      const body = format(
+        context,
+        items,
+        model,
+        submitResponse,
+        formStatus,
+        formMetadata as FormMetadata
+      )
+      const parsedBody = JSON.parse(body) as FormAdapterSubmissionMessagePayload
+
+      expect(parsedBody.meta.versionMetadata).toEqual({
+        versionNumber: 1,
+        createdAt: '2024-01-01T00:00:00.000Z'
+      })
+    })
+
+    it('should not include versionMetadata when submittedVersionNumber is undefined and no versions exist', () => {
+      const formMetadata: Partial<FormMetadata> = {
+        id: 'form-123',
+        slug: 'test-form',
+        title: 'Test Form',
+        notificationEmail: 'test@example.com'
+      }
+
+      const formStatus = {
+        isPreview: false,
+        state: FormStatus.Live
+      }
+
+      const body = format(
+        context,
+        items,
+        model,
+        submitResponse,
+        formStatus,
+        formMetadata as FormMetadata
+      )
+      const parsedBody = JSON.parse(body) as FormAdapterSubmissionMessagePayload
+
+      expect(parsedBody.meta.versionMetadata).toBeUndefined()
+    })
+
+    it('should not include versionMetadata when submittedVersionNumber is undefined and versions array is empty', () => {
+      const formMetadata: Partial<FormMetadata> = {
+        id: 'form-123',
+        slug: 'test-form',
+        title: 'Test Form',
+        notificationEmail: 'test@example.com',
+        versions: []
+      }
+
+      const formStatus = {
+        isPreview: false,
+        state: FormStatus.Live
+      }
+
+      const body = format(
+        context,
+        items,
+        model,
+        submitResponse,
+        formStatus,
+        formMetadata as FormMetadata
+      )
+      const parsedBody = JSON.parse(body) as FormAdapterSubmissionMessagePayload
+
+      expect(parsedBody.meta.versionMetadata).toBeUndefined()
+    })
+
+    it('should not include versionMetadata when submittedVersionNumber does not match any version', () => {
+      const formMetadata: Partial<FormMetadata> = {
+        id: 'form-123',
+        slug: 'test-form',
+        title: 'Test Form',
+        notificationEmail: 'test@example.com',
+        versions: [
+          {
+            versionNumber: 1,
+            createdAt: new Date('2024-01-01T00:00:00.000Z')
+          },
+          {
+            versionNumber: 2,
+            createdAt: new Date('2024-01-15T00:00:00.000Z')
+          }
+        ]
+      }
+
+      const modelWithVersion = new FormModel(definition, {
+        basePath: 'test',
+        versionNumber: 99 // Non-existent version
+      })
+
+      const contextWithVersion = modelWithVersion.getFormContext(request, state)
+
+      const formStatus = {
+        isPreview: false,
+        state: FormStatus.Live
+      }
+
+      const body = format(
+        contextWithVersion,
+        items,
+        modelWithVersion,
+        submitResponse,
+        formStatus,
+        formMetadata as FormMetadata
+      )
+      const parsedBody = JSON.parse(body) as FormAdapterSubmissionMessagePayload
+
+      // Should fall back to first version since submittedVersionNumber doesn't match
+      expect(parsedBody.meta.versionMetadata).toEqual({
+        versionNumber: 1,
+        createdAt: '2024-01-01T00:00:00.000Z'
+      })
+    })
+
+    it('should use first version as fallback when submittedVersionNumber does not match any version', () => {
+      const formMetadata: Partial<FormMetadata> = {
+        id: 'form-123',
+        slug: 'test-form',
+        title: 'Test Form',
+        notificationEmail: 'test@example.com',
+        versions: [
+          {
+            versionNumber: 1,
+            createdAt: new Date('2024-01-01T00:00:00.000Z')
+          },
+          {
+            versionNumber: 2,
+            createdAt: new Date('2024-01-15T00:00:00.000Z')
+          }
+        ]
+      }
+
+      const modelWithVersion = new FormModel(definition, {
+        basePath: 'test',
+        versionNumber: 99 // Non-existent version
+      })
+
+      const contextWithVersion = modelWithVersion.getFormContext(request, state)
+
+      const formStatus = {
+        isPreview: false,
+        state: FormStatus.Live
+      }
+
+      const body = format(
+        contextWithVersion,
+        items,
+        modelWithVersion,
+        submitResponse,
+        formStatus,
+        formMetadata as FormMetadata
+      )
+      const parsedBody = JSON.parse(body) as FormAdapterSubmissionMessagePayload
+
+      // Should fall back to first version since submittedVersionNumber doesn't match
+      expect(parsedBody.meta.versionMetadata).toEqual({
+        versionNumber: 1,
+        createdAt: '2024-01-01T00:00:00.000Z'
+      })
+    })
+
+    it('should handle single version in versions array', () => {
+      const formMetadata: Partial<FormMetadata> = {
+        id: 'form-123',
+        slug: 'test-form',
+        title: 'Test Form',
+        notificationEmail: 'test@example.com',
+        versions: [
+          {
+            versionNumber: 5,
+            createdAt: new Date('2024-02-01T00:00:00.000Z')
+          }
+        ]
+      }
+
+      const formStatus = {
+        isPreview: false,
+        state: FormStatus.Live
+      }
+
+      const body = format(
+        context,
+        items,
+        model,
+        submitResponse,
+        formStatus,
+        formMetadata as FormMetadata
+      )
+      const parsedBody = JSON.parse(body) as FormAdapterSubmissionMessagePayload
+
+      expect(parsedBody.meta.versionMetadata).toEqual({
+        versionNumber: 5,
+        createdAt: '2024-02-01T00:00:00.000Z'
+      })
+    })
+  })
+
+  describe('getVersionMetadata', () => {
+    const mockFormMetadata: Partial<FormMetadata> = {
+      id: 'form-123',
+      slug: 'test-form',
+      title: 'Test Form',
+      notificationEmail: 'test@example.com',
+      versions: [
+        {
+          versionNumber: 1,
+          createdAt: new Date('2024-01-01T00:00:00.000Z')
+        },
+        {
+          versionNumber: 2,
+          createdAt: new Date('2024-01-02T00:00:00.000Z')
+        },
+        {
+          versionNumber: 3,
+          createdAt: new Date('2024-01-03T00:00:00.000Z')
+        }
+      ]
+    }
+
+    it('should return undefined when no form metadata provided', () => {
+      const result = getVersionMetadata(1, undefined)
+      expect(result).toBeUndefined()
+    })
+
+    it('should return undefined when form metadata has no versions', () => {
+      const formMetadataWithoutVersions: Partial<FormMetadata> = {
+        ...mockFormMetadata,
+        versions: undefined
+      }
+
+      const result = getVersionMetadata(
+        1,
+        formMetadataWithoutVersions as FormMetadata
+      )
+      expect(result).toBeUndefined()
+    })
+
+    it('should return undefined when versions array is empty', () => {
+      const formMetadataWithEmptyVersions: Partial<FormMetadata> = {
+        ...mockFormMetadata,
+        versions: []
+      }
+
+      const result = getVersionMetadata(
+        1,
+        formMetadataWithEmptyVersions as FormMetadata
+      )
+      expect(result).toBeUndefined()
+    })
+
+    it('should return specific version when submittedVersionNumber matches', () => {
+      const result = getVersionMetadata(2, mockFormMetadata as FormMetadata)
+      expect(result).toEqual({
+        versionNumber: 2,
+        createdAt: new Date('2024-01-02T00:00:00.000Z')
+      })
+    })
+
+    it('should return first version when submittedVersionNumber not found', () => {
+      const result = getVersionMetadata(999, mockFormMetadata as FormMetadata)
+      expect(result).toEqual({
+        versionNumber: 1,
+        createdAt: new Date('2024-01-01T00:00:00.000Z')
+      })
+    })
+
+    it('should return first version when no submittedVersionNumber provided', () => {
+      const result = getVersionMetadata(
+        undefined,
+        mockFormMetadata as FormMetadata
+      )
+      expect(result).toEqual({
+        versionNumber: 1,
+        createdAt: new Date('2024-01-01T00:00:00.000Z')
+      })
+    })
+
+    it('should handle single version in versions array', () => {
+      const singleVersionMetadata: Partial<FormMetadata> = {
+        ...mockFormMetadata,
+        versions: [
+          {
+            versionNumber: 5,
+            createdAt: new Date('2024-02-01T00:00:00.000Z')
+          }
+        ]
+      }
+
+      const result = getVersionMetadata(
+        undefined,
+        singleVersionMetadata as FormMetadata
+      )
+      expect(result).toEqual({
+        versionNumber: 5,
+        createdAt: new Date('2024-02-01T00:00:00.000Z')
+      })
+    })
+
+    it('should return correct version when submittedVersionNumber is 0', () => {
+      const metadataWithVersionZero: Partial<FormMetadata> = {
+        ...mockFormMetadata,
+        versions: [
+          {
+            versionNumber: 0,
+            createdAt: new Date('2024-01-01T00:00:00.000Z')
+          },
+          {
+            versionNumber: 1,
+            createdAt: new Date('2024-01-02T00:00:00.000Z')
+          }
+        ]
+      }
+
+      const result = getVersionMetadata(
+        0,
+        metadataWithVersionZero as FormMetadata
+      )
+      expect(result).toEqual({
+        versionNumber: 0,
+        createdAt: new Date('2024-01-01T00:00:00.000Z')
+      })
+    })
+
+    it('should handle negative submittedVersionNumber by falling back to first version', () => {
+      const result = getVersionMetadata(-1, mockFormMetadata as FormMetadata)
+      expect(result).toEqual({
+        versionNumber: 1,
+        createdAt: new Date('2024-01-01T00:00:00.000Z')
+      })
+    })
+  })
 })

package/src/server/plugins/engine/outputFormatters/adapter/v1.ts

@@ -40,6 +40,11 @@ export function format(
 
   const transformedData = v2DataParsed.data
 
+  const versionMetadata = getVersionMetadata(
+    context.submittedVersionNumber,
+    formMetadata
+  )
+
   const meta: FormAdapterSubmissionMessageMeta = {
     schemaVersion: FormAdapterSubmissionSchemaVersion.V1,
     timestamp: new Date(),
@@ -51,6 +56,10 @@ export function format(
     isPreview: formStatus.isPreview,
     notificationEmail: formMetadata?.notificationEmail ?? ''
   }
+
+  if (versionMetadata) {
+    meta.versionMetadata = versionMetadata
+  }
   const data: FormAdapterSubmissionMessageData = transformedData
 
   const result: FormAdapterSubmissionMessageResult = {
@@ -66,6 +75,34 @@ export function format(
   return JSON.stringify(payload)
 }
 
+export function getVersionMetadata(
+  submittedVersionNumber: number | undefined,
+  formMetadata?: FormMetadata
+): { versionNumber: number; createdAt: Date } | undefined {
+  if (!formMetadata?.versions?.length) {
+    return undefined
+  }
+
+  if (submittedVersionNumber !== undefined) {
+    const submittedVersion = formMetadata.versions.find(
+      (v) => v.versionNumber === submittedVersionNumber
+    )
+    if (submittedVersion) {
+      return {
+        versionNumber: submittedVersion.versionNumber,
+        createdAt: submittedVersion.createdAt
+      }
+    }
+  }
+
+  // fallback to first available version
+  const firstVersion = formMetadata.versions[0]
+  return {
+    versionNumber: firstVersion.versionNumber,
+    createdAt: firstVersion.createdAt
+  }
+}
+
 function extractCsvFiles(
   submitResponse: SubmitResponsePayload
 ): FormAdapterSubmissionMessageResult['files'] {

package/src/server/plugins/engine/outputFormatters/machine/v2.ts

@@ -29,13 +29,15 @@ export function format(
 
   const categorisedData = categoriseData(items)
 
+  const meta: Record<string, unknown> = {
+    schemaVersion: '2',
+    timestamp: now.toISOString(),
+    definition: model.def,
+    referenceNumber: context.referenceNumber
+  }
+
   const data = {
-    meta: {
-      schemaVersion: '2',
-      timestamp: now.toISOString(),
-      definition: model.def,
-      referenceNumber: context.referenceNumber
-    },
+    meta,
     data: categorisedData
   }
 

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

@@ -1,6 +1,5 @@
 /* eslint-disable @typescript-eslint/dot-notation */
 import { ComponentType, type ComponentDef } from '@defra/forms-model'
-import { type ResponseToolkit } from '@hapi/hapi'
 import { type ValidationErrorItem, type ValidationResult } from 'joi'
 
 import { tempItemSchema } from '~/src/server/plugins/engine/components/FileUploadField.js'
@@ -14,7 +13,7 @@ import {
   prepareStatus
 } from '~/src/server/plugins/engine/pageControllers/FileUploadPageController.js'
 import { QuestionPageController } from '~/src/server/plugins/engine/pageControllers/QuestionPageController.js'
-import { serverWithSaveAndReturn } from '~/src/server/plugins/engine/pageControllers/__stubs__/server.js'
+import { serverWithSaveAndExit } from '~/src/server/plugins/engine/pageControllers/__stubs__/server.js'
 import * as pageHelpers from '~/src/server/plugins/engine/pageControllers/helpers/index.js'
 import * as uploadService from '~/src/server/plugins/engine/services/uploadService.js'
 import {
@@ -30,7 +29,8 @@ import {
 } from '~/src/server/plugins/engine/types.js'
 import {
   type FormRequest,
-  type FormRequestPayload
+  type FormRequestPayload,
+  type FormResponseToolkit
 } from '~/src/server/routes/types.js'
 import { type CacheService } from '~/src/server/services/index.js'
 import definition from '~/test/form/definitions/file-upload-basic.js'
@@ -1040,7 +1040,7 @@ describe('FileUploadPageController', () => {
       } as unknown as FormRequest
 
       const context = { state } as unknown as FormContext
-      const h = {} as unknown as Pick<ResponseToolkit, 'redirect' | 'view'>
+      const h = {} as unknown as FormResponseToolkit
 
       const handler = controller.makeGetItemDeleteRouteHandler()
 
@@ -1058,7 +1058,7 @@ describe('FileUploadPageController', () => {
 
       const h = {
         redirect: jest.fn()
-      } as unknown as Pick<ResponseToolkit, 'redirect' | 'view'>
+      } as unknown as FormResponseToolkit
 
       const context = {
         state: {}
@@ -1119,11 +1119,9 @@ describe('FileUploadPageController', () => {
     })
   })
 
-  describe('shouldShowSaveAndReturn', () => {
-    it('should return true when save and return is enabled', () => {
-      expect(controller.shouldShowSaveAndReturn(serverWithSaveAndReturn)).toBe(
-        true
-      )
+  describe('shouldShowSaveAndExit', () => {
+    it('should return true when save and exit is enabled', () => {
+      expect(controller.shouldShowSaveAndExit(serverWithSaveAndExit)).toBe(true)
     })
   })
 })