@defra/forms-engine-plugin 3.0.0 → 3.0.1

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/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
       )

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,6 +3,7 @@ import {
   type Event,
   type FormDefinition,
   type FormMetadata,
+  type FormVersionMetadata,
   type Item,
   type List,
   type Page
@@ -179,6 +180,7 @@ export interface FormContext {
   pageMap: Map<string, PageControllerClass>
   componentMap: Map<string, Component>
   referenceNumber: string
+  submittedVersionNumber?: number
 }
 
 export type FormContextRequest = (
@@ -405,6 +407,7 @@ export interface FormAdapterSubmissionMessageMeta {
   status: FormStatus
   isPreview: boolean
   notificationEmail: string
+  versionMetadata?: FormVersionMetadata
 }
 
 export type FormAdapterSubmissionMessageMetaSerialised = Omit<