@defra/forms-engine-plugin 4.0.25 → 4.0.27

package/src/server/plugins/engine/pageControllers/helpers/state.test.ts

@@ -0,0 +1,221 @@
+import { ComponentType, type Page } from '@defra/forms-model'
+
+import { type FormModel } from '~/src/server/plugins/engine/models/FormModel.js'
+import { type PageControllerClass } from '~/src/server/plugins/engine/pageControllers/helpers/pages.js'
+import {
+  prefillStateFromQueryParameters,
+  stripParam
+} from '~/src/server/plugins/engine/pageControllers/helpers/state.js'
+import { type AnyFormRequest } from '~/src/server/plugins/engine/types.js'
+import { type FormsService, type Services } from '~/src/server/types.js'
+
+function buildMockPage(
+  pagesOverride = {},
+  stateOverride = {},
+  servicesOverride = {} as Services
+) {
+  return {
+    model: {
+      def: {
+        metadata: {
+          submission: { code: 'TEST-CODE' }
+        } as { submission: { code: string } },
+        pages: pagesOverride
+      },
+      getFormContext: jest.fn().mockReturnValue({
+        isForceAccess: false,
+        data: {}
+      }),
+      services: servicesOverride
+    } as unknown as FormModel,
+    ...stateOverride
+  } as unknown as PageControllerClass
+}
+
+describe('State helpers', () => {
+  describe('prefillStateFromQueryParameters', () => {
+    const mockGetState = jest.fn()
+    const mockMergeState = jest.fn()
+    const mockRequestPrefill: AnyFormRequest = {
+      app: {},
+      yar: { flash: () => [] },
+      params: { path: 'test-path' },
+      query: {}
+    } as unknown as AnyFormRequest
+
+    it('should not add any state if no params', async () => {
+      const mockPagePrefill = buildMockPage([], {
+        getState: mockGetState,
+        mergeState: mockMergeState
+      })
+
+      expect(
+        await prefillStateFromQueryParameters(
+          mockRequestPrefill,
+          mockPagePrefill
+        )
+      ).toBeFalse()
+      expect(mockMergeState).not.toHaveBeenCalled()
+    })
+
+    it('should ignore if no params (but some hidden fields)', async () => {
+      const mockRequest2 = {
+        ...mockRequestPrefill,
+        query: {}
+      } as unknown as AnyFormRequest
+
+      const mockPagePrefill = buildMockPage(
+        [
+          {
+            components: [
+              {
+                type: ComponentType.HiddenField,
+                name: 'param2'
+              },
+              {
+                type: ComponentType.HiddenField,
+                name: 'param4'
+              }
+            ],
+            next: []
+          } as unknown as Page
+        ],
+        {
+          getState: mockGetState,
+          mergeState: mockMergeState
+        }
+      )
+
+      expect(
+        await prefillStateFromQueryParameters(mockRequest2, mockPagePrefill)
+      ).toBeFalse()
+      expect(mockMergeState).not.toHaveBeenCalled()
+    })
+
+    it('should only add state where param names match hidden field names', async () => {
+      const mockRequest2 = {
+        ...mockRequestPrefill,
+        query: {
+          param1: 'val1',
+          param2: 'val2',
+          param3: 'val3',
+          param4: 'val4'
+        }
+      } as unknown as AnyFormRequest
+
+      const mockPagePrefill = buildMockPage(
+        [
+          {
+            components: [
+              {
+                type: ComponentType.HiddenField,
+                name: 'param2'
+              },
+              {
+                type: ComponentType.HiddenField,
+                name: 'param4'
+              }
+            ],
+            next: []
+          } as unknown as Page
+        ],
+        {
+          getState: mockGetState.mockResolvedValue({}),
+          mergeState: mockMergeState
+        }
+      )
+
+      expect(
+        await prefillStateFromQueryParameters(mockRequest2, mockPagePrefill)
+      ).toBe(true)
+      expect(mockMergeState).toHaveBeenCalledWith(
+        expect.anything(),
+        expect.anything(),
+        {
+          param2: 'val2',
+          param4: 'val4'
+        }
+      )
+    })
+
+    it('should call lookup function for formId', async () => {
+      const mockRequest3 = {
+        ...mockRequestPrefill,
+        query: {
+          formId: 'c644804b-2f23-4c96-a2fc-ad4975974723'
+        }
+      } as unknown as AnyFormRequest
+
+      const mockPagePrefill = buildMockPage(
+        [
+          {
+            components: [
+              {
+                type: ComponentType.HiddenField,
+                name: 'formId'
+              }
+            ],
+            next: []
+          } as unknown as Page
+        ],
+        {
+          getState: mockGetState.mockResolvedValue({}),
+          mergeState: mockMergeState
+        },
+        {
+          formsService: {
+            getFormMetadata: jest.fn(),
+            getFormMetadataById: jest
+              .fn()
+              .mockResolvedValue({ title: 'My looked-up form name' }),
+            getFormDefinition: jest.fn()
+          } as unknown as FormsService
+        } as Services
+      )
+
+      await prefillStateFromQueryParameters(mockRequest3, mockPagePrefill)
+      expect(mockMergeState).toHaveBeenCalledWith(
+        expect.anything(),
+        expect.anything(),
+        {
+          formId: 'c644804b-2f23-4c96-a2fc-ad4975974723',
+          formName: 'My looked-up form name'
+        }
+      )
+    })
+  })
+
+  describe('stripParam', () => {
+    it('should remove param when exists', () => {
+      const params = {
+        paramName1: 'val1',
+        returnUrl: 'http://somesite.com',
+        paramName2: 'val2',
+        paramName3: undefined
+      }
+      expect(stripParam(params, 'returnUrl')).toStrictEqual({
+        paramName1: 'val1',
+        paramName2: 'val2',
+        paramName3: ''
+      })
+    })
+
+    it('should handle param missing', () => {
+      const params = {
+        paramName1: 'val1',
+        returnUrl: 'http://somesite.com',
+        paramName2: 'val2'
+      }
+      expect(stripParam(params, 'paramNotThere')).toStrictEqual({
+        paramName1: 'val1',
+        returnUrl: 'http://somesite.com',
+        paramName2: 'val2'
+      })
+    })
+
+    it('should handle no params', () => {
+      const params = {}
+      expect(stripParam(params, 'anyParam')).toBeUndefined()
+    })
+  })
+})

package/src/server/plugins/engine/pageControllers/helpers/state.ts

@@ -0,0 +1,93 @@
+import { getHiddenFields } from '@defra/forms-model'
+
+import { type PageControllerClass } from '~/src/server/plugins/engine/pageControllers/helpers/pages.js'
+import {
+  type AnyFormRequest,
+  type FormStateValue
+} from '~/src/server/plugins/engine/types.js'
+import { type FormQuery } from '~/src/server/routes/types.js'
+import { type Services } from '~/src/server/types.js'
+
+/**
+ * A series of functions that can transform a pre-fill input parameter e.g lookup a form title based on form id
+ */
+const paramLookupFunctions = {
+  formId: async (val: string, services: Services) => {
+    let formTitle
+    if (val) {
+      const meta = await services.formsService.getFormMetadataById(val)
+      formTitle = meta.title
+    }
+    return {
+      key: 'formName',
+      value: formTitle
+    }
+  }
+} as Partial<
+  Record<
+    string,
+    (
+      val: string,
+      services: Services
+    ) => Promise<{ key: string; value: string | undefined }>
+  >
+>
+
+export function stripParam(query: FormQuery, paramToRemove: string) {
+  const params = {} as Record<string, FormStateValue | undefined>
+  for (const [key, value = ''] of Object.entries(query)) {
+    if (key !== paramToRemove) {
+      params[key] = value
+    }
+  }
+  return Object.keys(params).length ? (params as FormQuery) : undefined
+}
+
+/**
+ * Any hidden parameters defined in the FormDefinition may be pre-filled by URL parameter values.
+ * Other parameters are ignored for security reasons.
+ * @param request
+ * @param model
+ */
+export async function prefillStateFromQueryParameters(
+  request: AnyFormRequest,
+  page: PageControllerClass
+): Promise<boolean> {
+  const { model } = page
+
+  const hiddenFieldNames = new Set(
+    getHiddenFields(model.def).map((field) => field.name)
+  )
+
+  if (!hiddenFieldNames.size) {
+    return false
+  }
+
+  // Remove 'returnUrl' param
+  const query = stripParam(request.query, 'returnUrl')
+
+  if (!query) {
+    return false
+  }
+
+  const params = {} as Record<string, FormStateValue | undefined>
+
+  for (const [key, value = ''] of Object.entries(query)) {
+    if (hiddenFieldNames.has(key)) {
+      const lookupFunc = paramLookupFunctions[key]
+      if (lookupFunc) {
+        const res = await lookupFunc(value, model.services)
+        // Store original value and result
+        params[key] = value
+        params[res.key] = res.value
+      } else {
+        params[key] = value
+      }
+    }
+  }
+
+  const formData = await page.getState(request)
+  await page.mergeState(request, formData, params)
+
+  return true
+}

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

@@ -1,3 +1,4 @@
+import { type Page } from '@defra/forms-model'
 import Boom from '@hapi/boom'
 import { type ResponseObject, type ResponseToolkit } from '@hapi/hapi'
 
@@ -15,9 +16,31 @@ import {
   type OnRequestCallback
 } from '~/src/server/plugins/engine/types.js'
 import { type FormResponseToolkit } from '~/src/server/routes/types.js'
+import { type Services } from '~/src/server/types.js'
 
 jest.mock('~/src/server/plugins/engine/helpers')
 
+function buildMockModel(
+  pagesOverride = [] as Page[],
+  pagesControllerOverride = [] as PageControllerClass[],
+  servicesOverride = {} as Services
+) {
+  return {
+    def: {
+      metadata: {
+        submission: { code: 'TEST-CODE' }
+      } as { submission: { code: string } },
+      pages: pagesOverride
+    },
+    getFormContext: jest.fn().mockReturnValue({
+      isForceAccess: false,
+      data: {}
+    }),
+    pages: pagesControllerOverride,
+    services: servicesOverride
+  } as unknown as FormModel
+}
+
 describe('redirectOrMakeHandler', () => {
   const mockServer = {} as unknown as Parameters<
     typeof redirectOrMakeHandler
@@ -38,17 +61,7 @@ describe('redirectOrMakeHandler', () => {
 
   let mockPage: PageControllerClass
 
-  const mockModel: FormModel = {
-    def: {
-      metadata: {
-        submission: { code: 'TEST-CODE' }
-      } as { submission: { code: string } }
-    },
-    getFormContext: jest.fn().mockReturnValue({
-      isForceAccess: false,
-      data: {}
-    })
-  } as unknown as FormModel
+  const mockModel = buildMockModel()
 
   const mockMakeHandler = jest
     .fn()

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

@@ -244,7 +244,7 @@ export function makeLoadFormPreHandler(server: Server, options: PluginOptions) {
       // Construct the form model
       const model = new FormModel(
         definition,
-        { basePath, versionNumber, ordnanceSurveyApiKey },
+        { basePath, versionNumber, ordnanceSurveyApiKey, formId: id },
         services,
         controllers
       )

package/src/server/plugins/engine/services/formsService.js

@@ -12,6 +12,16 @@ export function getFormMetadata(_slug) {
   throw error
 }
 
+// eslint-disable-next-line jsdoc/require-returns-check
+/**
+ * Dummy function to get form metadata.
+ * @param {string} _id - the id of the form
+ * @returns {Promise<FormMetadata>}
+ */
+export function getFormMetadataById(_id) {
+  throw error
+}
+
 // eslint-disable-next-line jsdoc/require-returns-check
 /**
  * Dummy function to get form metadata.

package/src/server/plugins/engine/services/formsService.test.js

@@ -0,0 +1,21 @@
+import { FormStatus } from '@defra/forms-model'
+
+import {
+  getFormDefinition,
+  getFormMetadata,
+  getFormMetadataById
+} from '~/src/server/plugins/engine/services/formsService.js'
+
+describe('formsService', () => {
+  it('getFormMetadata should throw error', () => {
+    expect(() => getFormMetadata('slug')).toThrow()
+  })
+
+  it('getFormMetadataById should throw error', () => {
+    expect(() => getFormMetadataById('id')).toThrow()
+  })
+
+  it('getFormDefinition should throw error', () => {
+    expect(() => getFormDefinition('id', FormStatus.Draft)).toThrow()
+  })
+})

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

@@ -97,6 +97,11 @@ export interface FormSubmissionError
   text: string // e.g: 'Date field must be a real date'
 }
 
+export interface FormConfirmationState {
+  confirmed?: true
+  formId?: string
+}
+
 export interface FormPayloadParams {
   action?: FormAction
   confirm?: true

package/src/server/plugins/engine/views/components/hiddenfield.html

@@ -0,0 +1,3 @@
+{% macro HiddenField(component) %}
+  <input type="hidden" id="{{ component.model.name }}" name="{{ component.model.name }}" value="{{ component.model.value }}" />
+{% endmacro %}

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

@@ -14,6 +14,11 @@
       <div class="app-prose-scope">
         {{ submissionGuidance | markdown(3) | safe }}
       </div>
+      {% if feedbackLink %}
+        <p class="govuk-body">
+          <a href="{{ feedbackLink }}" class="govuk-link govuk-link--no-visited-state">What do you think of this service?</a> (takes 30 seconds)
+        </p>
+      {% endif %}
     </div>
   </div>
 {% endblock %}

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

@@ -6,9 +6,17 @@
 
   {{ componentList(components) }}
 
+  {% if isStartPage %}
+    {% set buttonText = "Start now" %}
+  {% elif submitButtonText %}
+    {% set buttonText = submitButtonText %}
+  {% else %}
+    {% set buttonText = "Continue" %}
+  {% endif %}
+
   <div class="govuk-button-group">
     {{ govukButton({
-      text: "Start now" if isStartPage else "Continue",
+      text: buttonText,
       isStartButton: isStartPage,
       preventDoubleClick: true
     }) }}

package/src/server/services/cacheService.ts

@@ -6,6 +6,7 @@ import { type createServer } from '~/src/server/index.js'
 import {
   type AnyFormRequest,
   type AnyRequest,
+  type FormConfirmationState,
   type FormPayload,
   type FormState,
   type FormSubmissionError,
@@ -55,7 +56,7 @@ export class CacheService {
 
   async getConfirmationState(
     request: AnyFormRequest
-  ): Promise<{ confirmed?: true }> {
+  ): Promise<FormConfirmationState> {
     const key = this.Key(request, ADDITIONAL_IDENTIFIER.Confirmation)
     const value = await this.cache.get(key)
 
@@ -64,7 +65,7 @@ export class CacheService {
 
   async setConfirmationState(
     request: AnyFormRequest,
-    confirmationState: { confirmed?: true }
+    confirmationState: FormConfirmationState
   ) {
     const key = this.Key(request, ADDITIONAL_IDENTIFIER.Confirmation)
     const ttl = config.get('confirmationSessionTimeout')

package/src/server/types.ts

@@ -23,6 +23,7 @@ import { type CacheService } from '~/src/server/services/cacheService.js'
 
 export interface FormsService {
   getFormMetadata: (slug: string) => Promise<FormMetadata>
+  getFormMetadataById: (id: string) => Promise<FormMetadata>
   getFormDefinition: (
     id: string,
     state: FormStatus

package/src/server/utils/file-form-service.js

@@ -97,6 +97,23 @@ export class FileFormService {
     return metadata
   }
 
+  /**
+   * Get the form metadata by form id
+   * @param {string} id - the form id
+   * @returns {FormMetadata}
+   */
+  getFormMetadataById(id) {
+    const metadata = Array.from(this.#metadata.values()).find(
+      (form) => form.id === id
+    )
+
+    if (!metadata) {
+      throw new Error(`Form metadata id '${id}' not found`)
+    }
+
+    return metadata
+  }
+
   /**
    * Get the form defintion by id
    * @param {string} id - the form id
@@ -127,6 +144,15 @@ export class FileFormService {
         return Promise.resolve(this.getFormMetadata(slug))
       },
 
+      /**
+       * Get the form metadata by form id
+       * @param {string} id
+       * @returns {Promise<FormMetadata>}
+       */
+      getFormMetadataById: (id) => {
+        return Promise.resolve(this.getFormMetadataById(id))
+      },
+
       /**
        * Get the form defintion by id
        * @param {string} id
@@ -140,5 +166,5 @@ export class FileFormService {
 }
 
 /**
- * @import { FormMetadata, FormDefinition } from '@defra/forms-model'
+ * @import { FormMetadata, FormDefinition, FormStatus } from '@defra/forms-model'
  */

package/src/server/utils/file-form-service.test.js

@@ -0,0 +1,114 @@
+import { join } from 'node:path'
+
+import { FormStatus } from '~/src/server/routes/types.js'
+import { FileFormService } from '~/src/server/utils/file-form-service.js'
+
+describe('File-form-service', () => {
+  /** @type {FileFormService} */
+  let service
+  beforeEach(async () => {
+    const now = new Date()
+    const user = { id: 'user', displayName: 'Username' }
+    const author = {
+      createdAt: now,
+      createdBy: user,
+      updatedAt: now,
+      updatedBy: user
+    }
+    service = new FileFormService()
+    const metadata = {
+      organisation: 'Defra',
+      teamName: 'Team name',
+      teamEmail: 'team@defra.gov.uk',
+      submissionGuidance: "Thanks for your submission, we'll be in touch",
+      notificationEmail: 'email@domain.com',
+      ...author,
+      live: author
+    }
+    await service.addForm(
+      `${join(import.meta.dirname, '../../../test/form/definitions')}/components.json`,
+      {
+        ...metadata,
+        id: '95e92559-968d-44ae-8666-2b1ad3dffd31',
+        title: 'Form test',
+        slug: 'form-test'
+      }
+    )
+  })
+
+  describe('metadata by slug', () => {
+    it('should get form metadata by slug', () => {
+      const meta = service.getFormMetadata('form-test')
+      expect(meta.id).toBe('95e92559-968d-44ae-8666-2b1ad3dffd31')
+      expect(meta.title).toBe('Form test')
+    })
+
+    it('should throw if not found', () => {
+      expect(() => service.getFormMetadata('form-test-missing')).toThrow(
+        "Form metadata 'form-test-missing' not found"
+      )
+    })
+  })
+
+  describe('metadata by id', () => {
+    it('should get form metadata by id', () => {
+      const meta = service.getFormMetadataById(
+        '95e92559-968d-44ae-8666-2b1ad3dffd31'
+      )
+      expect(meta.id).toBe('95e92559-968d-44ae-8666-2b1ad3dffd31')
+      expect(meta.title).toBe('Form test')
+    })
+
+    it('should throw if not found', () => {
+      expect(() => service.getFormMetadataById('id-missing')).toThrow(
+        "Form metadata id 'id-missing' not found"
+      )
+    })
+  })
+
+  describe('definition by id', () => {
+    it('should get form definition by id', () => {
+      const form = service.getFormDefinition(
+        '95e92559-968d-44ae-8666-2b1ad3dffd31'
+      )
+      expect(form.name).toBe('All components')
+      expect(form.startPage).toBe('/all-components')
+    })
+
+    it('should throw if not found', () => {
+      expect(() => service.getFormDefinition('id-missing')).toThrow(
+        "Form definition 'id-missing' not found"
+      )
+    })
+  })
+
+  describe('toFormsService', () => {
+    it('should create interface', async () => {
+      const interfaceImpl = service.toFormsService()
+      const res1 = await interfaceImpl.getFormMetadata('form-test')
+      expect(res1.id).toBe('95e92559-968d-44ae-8666-2b1ad3dffd31')
+      expect(res1.title).toBe('Form test')
+
+      const res2 = await interfaceImpl.getFormMetadataById(
+        '95e92559-968d-44ae-8666-2b1ad3dffd31'
+      )
+      expect(res2.id).toBe('95e92559-968d-44ae-8666-2b1ad3dffd31')
+      expect(res2.title).toBe('Form test')
+
+      const res3 = await interfaceImpl.getFormDefinition(
+        '95e92559-968d-44ae-8666-2b1ad3dffd31',
+        FormStatus.Draft
+      )
+      expect(res3?.name).toBe('All components')
+      expect(res3?.startPage).toBe('/all-components')
+    })
+  })
+
+  describe('readForm', () => {
+    it('should throw if invalid extension', async () => {
+      await expect(
+        service.readForm('/some-folder/some-file.bad')
+      ).rejects.toThrow("Invalid file extension '.bad'")
+    })
+  })
+})