@defra/forms-engine-plugin 3.0.0 → 3.0.2

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/RepeatPageController.ts

@@ -34,6 +34,7 @@ export class RepeatPageController extends QuestionPageController {
   listSummaryViewName = 'repeat-list-summary'
   listDeleteViewName = 'item-delete'
   repeat: Repeat
+  allowSaveAndExit = true
 
   constructor(model: FormModel, pageDef: PageRepeat) {
     super(model, pageDef)
@@ -257,6 +258,11 @@ export class RepeatPageController extends QuestionPageController {
         return super.proceed(request, h, nextPath)
       }
 
+      // Check if this is a save-and-exit action
+      if (action === FormAction.SaveAndExit) {
+        return this.handleSaveAndExit(request, context, h)
+      }
+
       const nextPath = this.getNextPath(context)
       return super.proceed(request, h, nextPath)
     }
@@ -433,7 +439,8 @@ export class RepeatPageController extends QuestionPageController {
       showTitle: true,
       context,
       errors,
-      checkAnswers: [{ summaryList }]
+      checkAnswers: [{ summaryList }],
+      allowSaveAndExit: this.shouldShowSaveAndExit(request.server)
     }
   }
 

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

@@ -151,10 +151,12 @@ export function makeLoadFormPreHandler(server: Server, options: PluginOptions) {
           : `${prefix}/${slug}`
       ).substring(1)
 
+      const versionNumber = metadata.versions?.[0]?.versionNumber
+
       // Construct the form model
       const model = new FormModel(
         definition,
-        { basePath },
+        { basePath, versionNumber },
         services,
         controllers
       )