@defra/forms-engine-plugin 0.0.1

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

@@ -0,0 +1,46 @@
+import { formMetadataSchema } from '@defra/forms-model'
+
+import { config } from '~/src/config/index.js'
+import { FormStatus } from '~/src/server/routes/types.js'
+import { getJson } from '~/src/server/services/httpService.js'
+
+/**
+ * Retrieves a form definition from the form manager for a given slug
+ * @param {string} slug - the slug of the form
+ */
+export async function getFormMetadata(slug) {
+  const getJsonByType = /** @type {typeof getJson<FormMetadata>} */ (getJson)
+
+  const { payload: metadata } = await getJsonByType(
+    `${config.get('managerUrl')}/forms/slug/${slug}`
+  )
+
+  // Run it through the schema to coerce dates
+  const result = formMetadataSchema.validate(metadata)
+
+  if (result.error) {
+    throw result.error
+  }
+
+  return result.value
+}
+
+/**
+ * Retrieves a form definition from the form manager for a given id
+ * @param {string} id - the id of the form
+ * @param {FormStatus} state - the state of the form
+ */
+export async function getFormDefinition(id, state) {
+  const getJsonByType = /** @type {typeof getJson<FormDefinition>} */ (getJson)
+
+  const suffix = state === FormStatus.Draft ? `/${state}` : ''
+  const { payload: definition } = await getJsonByType(
+    `${config.get('managerUrl')}/forms/${id}/definition${suffix}`
+  )
+
+  return definition
+}
+
+/**
+ * @import { FormDefinition, FormMetadata } from '@defra/forms-model'
+ */

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

@@ -0,0 +1,90 @@
+import { StatusCodes } from 'http-status-codes'
+
+import {
+  getFormDefinition,
+  getFormMetadata
+} from '~/src/server/plugins/engine/services/formsService.js'
+import { FormStatus } from '~/src/server/routes/types.js'
+import { getJson } from '~/src/server/services/httpService.js'
+import * as fixtures from '~/test/fixtures/index.js'
+
+const { MANAGER_URL } = process.env
+
+jest.mock('~/src/server/services/httpService')
+
+describe('Forms service', () => {
+  const { definition, metadata } = fixtures.form
+
+  describe('getFormMetadata', () => {
+    beforeEach(() => {
+      jest.mocked(getJson).mockResolvedValue({
+        res: /** @type {IncomingMessage} */ ({
+          statusCode: StatusCodes.OK
+        }),
+        payload: metadata
+      })
+    })
+
+    it('requests JSON via form slug', async () => {
+      await getFormMetadata(metadata.slug)
+
+      expect(getJson).toHaveBeenCalledWith(
+        `${MANAGER_URL}/forms/slug/${metadata.slug}`
+      )
+    })
+
+    it('coerces timestamps from string to Date', async () => {
+      const payload = {
+        ...structuredClone(metadata),
+
+        // JSON payload uses string dates in transit
+        createdAt: metadata.createdAt.toISOString(),
+        updatedAt: metadata.updatedAt.toISOString()
+      }
+
+      jest.mocked(getJson).mockResolvedValue({
+        res: /** @type {IncomingMessage} */ ({
+          statusCode: StatusCodes.OK
+        }),
+        payload
+      })
+
+      await expect(getFormMetadata(metadata.slug)).resolves.toEqual({
+        ...metadata,
+        createdAt: expect.any(Date),
+        updatedAt: expect.any(Date)
+      })
+    })
+  })
+
+  describe('getFormDefinition', () => {
+    beforeEach(() => {
+      jest.mocked(getJson).mockResolvedValue({
+        res: /** @type {IncomingMessage} */ ({
+          statusCode: StatusCodes.OK
+        }),
+        payload: definition
+      })
+    })
+
+    it('requests JSON via form ID (draft)', async () => {
+      await getFormDefinition(metadata.id, FormStatus.Draft)
+
+      expect(getJson).toHaveBeenCalledWith(
+        `${MANAGER_URL}/forms/${metadata.id}/definition/draft`
+      )
+    })
+
+    it('requests JSON via form ID (live)', async () => {
+      await getFormDefinition(metadata.id, FormStatus.Live)
+
+      expect(getJson).toHaveBeenCalledWith(
+        `${MANAGER_URL}/forms/${metadata.id}/definition`
+      )
+    })
+  })
+})
+
+/**
+ * @import { IncomingMessage } from 'node:http'
+ */

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

@@ -0,0 +1,3 @@
+export * as formsService from '~/src/server/plugins/engine/services/formsService.js'
+export * as formSubmissionService from '~/src/server/plugins/engine/services/formSubmissionService.js'
+export * as outputService from '~/src/server/plugins/engine/services/notifyService.js'

package/src/server/plugins/engine/services/notifyService.test.ts

@@ -0,0 +1,132 @@
+import { checkFormStatus } from '~/src/server/plugins/engine/helpers.js'
+import { type FormModel } from '~/src/server/plugins/engine/models/index.js'
+import { type DetailItem } from '~/src/server/plugins/engine/models/types.js'
+import { getFormatter } from '~/src/server/plugins/engine/outputFormatters/index.js'
+import { submit } from '~/src/server/plugins/engine/services/notifyService.js'
+import {
+  FormStatus,
+  type FormRequestPayload
+} from '~/src/server/routes/types.js'
+import { sendNotification } from '~/src/server/utils/notify.js'
+
+jest.mock('~/src/server/utils/notify')
+jest.mock('~/src/server/plugins/engine/helpers')
+jest.mock('~/src/server/plugins/engine/outputFormatters/index')
+
+describe('notifyService', () => {
+  const submitResponse = {
+    message: 'Submit completed',
+    result: {
+      files: {
+        main: '00000000-0000-0000-0000-000000000000',
+        repeaters: {
+          pizza: '11111111-1111-1111-1111-111111111111'
+        }
+      }
+    }
+  }
+
+  const items: DetailItem[] = []
+
+  const mockRequest: FormRequestPayload = jest.mocked<FormRequestPayload>({
+    path: 'test',
+    logger: {
+      info: jest.fn()
+    }
+  } as unknown as FormRequestPayload)
+  let model: FormModel
+  const sendNotificationMock = jest.mocked(sendNotification)
+
+  beforeEach(() => {
+    jest.resetAllMocks()
+  })
+
+  it('creates a subject line for real forms', async () => {
+    model = {
+      name: 'foobar',
+      def: {
+        output: {
+          audience: 'human',
+          version: '1'
+        }
+      }
+    } as FormModel
+
+    jest.mocked(checkFormStatus).mockReturnValue({
+      isPreview: false,
+      state: FormStatus.Draft
+    })
+    jest.mocked(getFormatter).mockReturnValue(() => 'dummy-live')
+
+    await submit(mockRequest, model, 'test@defra.gov.uk', items, submitResponse)
+
+    expect(sendNotificationMock).toHaveBeenCalledWith(
+      expect.objectContaining({
+        personalisation: {
+          subject: `Form submission: foobar`,
+          body: 'dummy-live'
+        }
+      })
+    )
+  })
+
+  it('creates a subject line for preview forms', async () => {
+    model = {
+      name: 'foobar',
+      def: {
+        output: {
+          audience: 'human',
+          version: '1'
+        }
+      }
+    } as FormModel
+
+    jest.mocked(checkFormStatus).mockReturnValue({
+      isPreview: true,
+      state: FormStatus.Draft
+    })
+    jest.mocked(getFormatter).mockReturnValue(() => 'dummy-preview')
+
+    await submit(mockRequest, model, 'test@defra.gov.uk', items, submitResponse)
+
+    expect(sendNotificationMock).toHaveBeenCalledWith(
+      expect.objectContaining({
+        personalisation: {
+          subject: `TEST FORM SUBMISSION: foobar`,
+          body: 'dummy-preview'
+        }
+      })
+    )
+  })
+
+  it('base64 encodes form data when aimed at machines', async () => {
+    model = {
+      name: 'foobar',
+      def: {
+        output: {
+          audience: 'machine',
+          version: '1'
+        }
+      }
+    } as FormModel
+
+    jest.mocked(checkFormStatus).mockReturnValue({
+      isPreview: true,
+      state: FormStatus.Draft
+    })
+    jest
+      .mocked(getFormatter)
+      .mockReturnValue(() => 'dummy-preview " Hello world \' !@/')
+
+    await submit(mockRequest, model, 'test@defra.gov.uk', items, submitResponse)
+
+    expect(sendNotificationMock).toHaveBeenCalledWith(
+      expect.objectContaining({
+        personalisation: {
+          subject: `TEST FORM SUBMISSION: foobar`,
+          body: 'ZHVtbXktcHJldmlldyAiIEhlbGxvIHdvcmxkICcgIUAv'
+        }
+      })
+    )
+  })
+})

package/src/server/plugins/engine/services/notifyService.ts

@@ -0,0 +1,64 @@
+import { type SubmitResponsePayload } from '@defra/forms-model'
+
+import { config } from '~/src/config/index.js'
+import { escapeMarkdown } from '~/src/server/plugins/engine/components/helpers.js'
+import { checkFormStatus } from '~/src/server/plugins/engine/helpers.js'
+import { type FormModel } from '~/src/server/plugins/engine/models/index.js'
+import { type DetailItem } from '~/src/server/plugins/engine/models/types.js'
+import { getFormatter } from '~/src/server/plugins/engine/outputFormatters/index.js'
+import { type FormRequestPayload } from '~/src/server/routes/types.js'
+import { sendNotification } from '~/src/server/utils/notify.js'
+
+const templateId = config.get('notifyTemplateId')
+
+export async function submit(
+  request: FormRequestPayload,
+  model: FormModel,
+  emailAddress: string,
+  items: DetailItem[],
+  submitResponse: SubmitResponsePayload
+) {
+  const logTags = ['submit', 'email']
+  const { path } = request
+  const formStatus = checkFormStatus(path)
+
+  // Get submission email personalisation
+  request.logger.info(logTags, 'Getting personalisation data')
+
+  const formName = escapeMarkdown(model.name)
+  const subject = formStatus.isPreview
+    ? `TEST FORM SUBMISSION: ${formName}`
+    : `Form submission: ${formName}`
+
+  const outputAudience = model.def.output?.audience ?? 'human'
+  const outputVersion = model.def.output?.version ?? '1'
+
+  const outputFormatter = getFormatter(outputAudience, outputVersion)
+  let body = outputFormatter(items, model, submitResponse, formStatus)
+
+  // GOV.UK Notify transforms quotes into curly quotes, so we can't just send the raw payload
+  // This is logic specific to Notify, so we include the logic here rather than in the formatter
+  if (outputAudience === 'machine') {
+    body = Buffer.from(body).toString('base64')
+  }
+
+  request.logger.info(logTags, 'Sending email')
+
+  try {
+    // Send submission email
+    await sendNotification({
+      templateId,
+      emailAddress,
+      personalisation: {
+        subject,
+        body
+      }
+    })
+
+    request.logger.info(logTags, 'Email sent successfully')
+  } catch (err) {
+    request.logger.error(logTags, 'Error sending email', err)
+
+    throw err
+  }
+}

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

@@ -0,0 +1,60 @@
+import { config } from '~/src/config/index.js'
+import { getJson, postJson } from '~/src/server/services/httpService.js'
+
+const uploaderUrl = config.get('uploaderUrl')
+const submissionUrl = config.get('submissionUrl')
+const uploaderBucketName = config.get('uploaderBucketName')
+const stagingPrefix = config.get('stagingPrefix')
+
+/**
+ * Initiates a CDP file upload
+ * @param {string} path - the path of the page in the form
+ * @param {string} retrievalKey - the retrieval key for the files
+ * @param {string} [mimeTypes] - the csv string of accepted mimeTypes
+ */
+export async function initiateUpload(path, retrievalKey, mimeTypes) {
+  const postJsonByType =
+    /** @type {typeof postJson<UploadInitiateResponse>} */ (postJson)
+
+  const payload = {
+    redirect: path,
+    callback: `${submissionUrl}/file`,
+    s3Bucket: uploaderBucketName,
+    s3Path: stagingPrefix,
+    metadata: {
+      retrievalKey
+    },
+    mimeTypes: mimeTypes
+      ?.split(',')
+      .map((type) => type.trim())
+      .filter((type) => type !== '')
+    // maxFileSize: 25 * 1000 * 1000
+  }
+
+  const { payload: initiate } = await postJsonByType(
+    `${uploaderUrl}/initiate`,
+    { payload }
+  )
+
+  return initiate
+}
+
+/**
+ * Get the status of a CDP file upload
+ * @param {string} uploadId - the ID of the upload
+ */
+export async function getUploadStatus(uploadId) {
+  const getJsonByType = /** @type {typeof getJson<UploadStatusResponse>} */ (
+    getJson
+  )
+
+  const { payload: status } = await getJsonByType(
+    `${uploaderUrl}/status/${uploadId}`
+  )
+
+  return status
+}
+
+/**
+ * @import { UploadInitiateResponse, UploadStatusResponse } from '~/src/server/plugins/engine/types.js'
+ */

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

@@ -0,0 +1,315 @@
+import {
+  type ComponentDef,
+  type Item,
+  type List,
+  type Page
+} from '@defra/forms-model'
+import { type ValidationErrorItem } from 'joi'
+
+import { FormComponent } from '~/src/server/plugins/engine/components/FormComponent.js'
+import { type Component } from '~/src/server/plugins/engine/components/helpers.js'
+import {
+  type BackLink,
+  type ComponentText,
+  type ComponentViewModel
+} from '~/src/server/plugins/engine/components/types.js'
+import { type PageController } from '~/src/server/plugins/engine/pageControllers/PageController.js'
+import { type PageControllerClass } from '~/src/server/plugins/engine/pageControllers/helpers.js'
+import { type ViewContext } from '~/src/server/plugins/nunjucks/types.js'
+import { type FormAction, type FormRequest } from '~/src/server/routes/types.js'
+
+/**
+ * Form submission state stores the following in Redis:
+ * Props containing user's submitted values as `{ [inputId]: value }` or as `{ [sectionName]: { [inputName]: value } }`
+ *   a) . e.g:
+ * ```ts
+ *     {
+ *       _C9PRHmsgt: 'Ben',
+ *       WfLk9McjzX: 'Music',
+ *       IK7jkUFCBL: 'Royal Academy of Music'
+ *     }
+ * ```
+ *
+ *   b)
+ * ```ts
+ *   {
+ *         checkBeforeYouStart: { ukPassport: true },
+ *         applicantDetails: {
+ *           numberOfApplicants: 1,
+ *           phoneNumber: '77777777',
+ *           emailAddress: 'aaa@aaa.com'
+ *         },
+ *         applicantOneDetails: {
+ *           firstName: 'a',
+ *           middleName: 'a',
+ *           lastName: 'a',
+ *           address: { addressLine1: 'a', addressLine2: 'a', town: 'a', postcode: 'a' }
+ *         }
+ *     }
+ * ```
+ */
+
+/**
+ * Form submission state
+ */
+export type FormSubmissionState = {
+  upload?: Record<string, TempFileState>
+} & FormState
+
+export interface FormSubmissionError
+  extends Pick<ValidationErrorItem, 'context' | 'path'> {
+  href: string // e.g: '#dateField__day'
+  name: string // e.g: 'dateField__day'
+  text: string // e.g: 'Date field must be a real date'
+}
+
+export interface FormParams {
+  action?: FormAction
+  confirm?: true
+  crumb?: string
+  itemId?: string
+}
+
+/**
+ * Form POST for question pages
+ * (after Joi has converted value types)
+ */
+export type FormPayload = FormParams & Partial<Record<string, FormValue>>
+
+export type FormValue =
+  | Item['value']
+  | Item['value'][]
+  | UploadState
+  | RepeatListState
+  | undefined
+
+export type FormState = Partial<Record<string, FormStateValue>>
+export type FormStateValue = Exclude<FormValue, undefined> | null
+
+export interface FormValidationResult<
+  ValueType extends FormPayload | FormSubmissionState
+> {
+  value: ValueType
+  errors: FormSubmissionError[] | undefined
+}
+
+export interface FormContext {
+  /**
+   * Evaluation form state only (filtered by visited paths),
+   * with values formatted for condition evaluation using
+   * {@link FormComponent.getContextValueFromState}
+   */
+  evaluationState: FormState
+
+  /**
+   * Relevant form state only (filtered by visited paths)
+   */
+  relevantState: FormState
+
+  /**
+   * Relevant pages only (filtered by visited paths)
+   */
+  relevantPages: PageControllerClass[]
+
+  /**
+   * Form submission payload (single page)
+   */
+  payload: FormPayload
+
+  /**
+   * Form submission state (entire form)
+   */
+  state: FormSubmissionState
+
+  /**
+   * Validation errors (entire form)
+   */
+  errors?: FormSubmissionError[]
+
+  /**
+   * Visited paths evaluated from form state
+   */
+  paths: string[]
+
+  /**
+   * Preview URL direct access is allowed
+   */
+  isForceAccess: boolean
+
+  /**
+   * Miscellaneous extra data from event responses
+   */
+  data: object
+
+  pageDefMap: Map<string, Page>
+  listDefMap: Map<string, List>
+  componentDefMap: Map<string, ComponentDef>
+  pageMap: Map<string, PageControllerClass>
+  componentMap: Map<string, Component>
+}
+
+export type FormContextRequest = (
+  | {
+      method: 'get'
+      payload?: undefined
+    }
+  | {
+      method: 'post'
+      payload: FormPayload
+    }
+  | {
+      method: FormRequest['method']
+      payload?: object | undefined
+    }
+) &
+  Pick<FormRequest, 'app' | 'method' | 'params' | 'path' | 'query' | 'url'>
+
+export interface UploadInitiateResponse {
+  uploadId: string
+  uploadUrl: string
+  statusUrl: string
+}
+
+export enum UploadStatus {
+  initiated = 'initiated',
+  pending = 'pending',
+  ready = 'ready'
+}
+
+export enum FileStatus {
+  complete = 'complete',
+  rejected = 'rejected',
+  pending = 'pending'
+}
+
+export type UploadState = FileState[]
+
+export type FileUpload = {
+  fileId: string
+  filename: string
+  contentLength: number
+} & (
+  | {
+      fileStatus: FileStatus.complete | FileStatus.rejected | FileStatus.pending
+      errorMessage?: string
+    }
+  | {
+      fileStatus: FileStatus.complete
+      errorMessage?: undefined
+    }
+)
+
+export interface FileUploadMetadata {
+  retrievalKey: string
+}
+
+export type UploadStatusResponse =
+  | {
+      uploadStatus: UploadStatus.initiated
+      metadata: FileUploadMetadata
+      form: { file?: undefined }
+    }
+  | {
+      uploadStatus: UploadStatus.pending | UploadStatus.ready
+      metadata: FileUploadMetadata
+      form: { file: FileUpload }
+      numberOfRejectedFiles?: number
+    }
+  | {
+      uploadStatus: UploadStatus.ready
+      metadata: FileUploadMetadata
+      form: { file: FileUpload }
+      numberOfRejectedFiles: 0
+    }
+
+export type UploadStatusFileResponse = Exclude<
+  UploadStatusResponse,
+  { uploadStatus: UploadStatus.initiated }
+>
+
+export interface FileState {
+  uploadId: string
+  status: UploadStatusFileResponse
+}
+
+export interface TempFileState {
+  upload?: UploadInitiateResponse
+  files: UploadState
+}
+
+export interface RepeatItemState extends FormPayload {
+  itemId: string
+}
+
+export type RepeatListState = RepeatItemState[]
+
+export interface CheckAnswers {
+  title?: ComponentText
+  summaryList: SummaryList
+}
+
+export interface SummaryList {
+  classes?: string
+  rows: SummaryListRow[]
+}
+
+export interface SummaryListRow {
+  key: ComponentText
+  value: ComponentText
+  actions?: { items: SummaryListAction[] }
+}
+
+export type SummaryListAction = ComponentText & {
+  href: string
+  visuallyHiddenText: string
+}
+
+export interface PageViewModelBase extends Partial<ViewContext> {
+  page: PageController
+  name?: string
+  pageTitle: string
+  sectionTitle?: string
+  showTitle: boolean
+  isStartPage: boolean
+  backLink?: BackLink
+  feedbackLink?: string
+  serviceUrl: string
+  phaseTag?: string
+}
+
+export interface ItemDeletePageViewModel extends PageViewModelBase {
+  context: FormContext
+  itemTitle: string
+  confirmation?: ComponentText
+  buttonConfirm: ComponentText
+  buttonCancel: ComponentText
+}
+
+export interface FormPageViewModel extends PageViewModelBase {
+  components: ComponentViewModel[]
+  context: FormContext
+  errors?: FormSubmissionError[]
+  hasMissingNotificationEmail?: boolean
+}
+
+export interface RepeaterSummaryPageViewModel extends PageViewModelBase {
+  context: FormContext
+  errors?: FormSubmissionError[]
+  checkAnswers: CheckAnswers[]
+  repeatTitle: string
+}
+
+export interface FeaturedFormPageViewModel extends FormPageViewModel {
+  formAction?: string
+  formComponent: ComponentViewModel
+  componentsBefore: ComponentViewModel[]
+  uploadId: string | undefined
+  proxyUrl: string | null
+}
+
+export type PageViewModel =
+  | PageViewModelBase
+  | ItemDeletePageViewModel
+  | FormPageViewModel
+  | RepeaterSummaryPageViewModel
+  | FeaturedFormPageViewModel