@defra/forms-engine-plugin 0.0.4 → 0.0.6

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

@@ -0,0 +1,46 @@
+import { config } from '~/src/config/index.js'
+import { postJson } from '~/src/server/services/httpService.js'
+
+const submissionUrl = config.get('submissionUrl')
+
+/**
+ * Persist files by extending the time-to-live to 30 days
+ * @param {{fileId: string, initiatedRetrievalKey: string}[]} files - batch of files to persist
+ * @param {string} persistedRetrievalKey - final retrieval key when submitting
+ */
+export async function persistFiles(files, persistedRetrievalKey) {
+  const postJsonByType = /** @type {typeof postJson<object>} */ (postJson)
+
+  const payload = {
+    files,
+    persistedRetrievalKey
+  }
+
+  const result = await postJsonByType(`${submissionUrl}/files/persist`, {
+    payload
+  })
+
+  return result
+}
+
+/**
+ * Submit form
+ * @param {SubmitPayload} data - submission data
+ */
+export async function submit(data) {
+  const postJsonByType = /** @type {typeof postJson<SubmitResponsePayload>} */ (
+    postJson
+  )
+
+  const payload = data
+
+  const result = await postJsonByType(`${submissionUrl}/submit`, {
+    payload
+  })
+
+  return result.payload
+}
+
+/**
+ * @import { SubmitPayload, SubmitResponsePayload } from '@defra/forms-model'
+ */

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'
+ */