@defra/forms-engine-plugin 4.0.0 → 4.0.1

package/src/server/plugins/postcode-lookup/routes/index.js

@@ -0,0 +1,258 @@
+import Boom from '@hapi/boom'
+import { StatusCodes } from 'http-status-codes'
+import Joi from 'joi'
+
+import { EXTERNAL_STATE_APPENDAGE } from '~/src/server/constants.js'
+import {
+  JOURNEY_BASE_URL,
+  detailsPayloadSchema,
+  detailsViewModel,
+  manualPayloadSchema,
+  manualViewModel,
+  selectPayloadSchema,
+  selectViewModel,
+  stepSchema,
+  steps
+} from '~/src/server/plugins/postcode-lookup/models/index.js'
+import * as service from '~/src/server/plugins/postcode-lookup/service.js'
+
+const viewName = 'postcode-lookup-details'
+
+/**
+ * Get the session state associated with this journey
+ * @param {PostcodeLookupRequest} request
+ */
+function getSessionState(request) {
+  /**
+   * @type {PostcodeLookupSessionData | undefined}
+   */
+  const state = request.yar.get(JOURNEY_BASE_URL)
+
+  if (!state) {
+    throw Boom.internal(`No postcode lookup data found for ${JOURNEY_BASE_URL}`)
+  }
+
+  return state
+}
+
+/**
+ * Flash form component state
+ * @param {PostcodeLookupRequest} request - the request
+ * @param {string} componentName - the component name
+ * @param {Address | PostcodeLookupManualPayload} address - the address from ordnance survey or manually entered
+ */
+function flashComponentState(request, componentName, address) {
+  const addressState = {
+    addressLine1: address.addressLine1,
+    addressLine2: address.addressLine2,
+    town: address.town,
+    county: address.county,
+    postcode: address.postcode,
+    uprn: 'uprn' in address && address.uprn ? address.uprn : undefined
+  }
+
+  /**
+   * @type {ExternalStateAppendage}
+   */
+  const appendage = {
+    component: componentName,
+    data: addressState
+  }
+
+  request.yar.flash(EXTERNAL_STATE_APPENDAGE, appendage, true)
+}
+
+/**
+ * Initialises and dispatches the request to the postcode lookup journey
+ * @param {FormRequestPayload} request - the source page
+ * @param {FormResponseToolkit} h - the source page
+ * @param {PostcodeLookupDispatchData} initial - the source data
+ */
+export function dispatch(request, h, initial) {
+  /**
+   * @type {PostcodeLookupSessionData}
+   */
+  const data = {
+    initial,
+    details: { postcodeQuery: '', buildingNameQuery: '' }
+  }
+
+  request.yar.set(JOURNEY_BASE_URL, data)
+
+  const query = initial.step ? `?step=${initial.step}` : ''
+
+  return h.redirect(`${JOURNEY_BASE_URL}${query}`).code(StatusCodes.SEE_OTHER)
+}
+
+/**
+ * Gets the postcode lookup routes
+ * @param {PostcodeLookupConfiguration} options - ordnance survey api key
+ */
+export function getRoutes(options) {
+  return [getRoute(), postRoute(options)]
+}
+
+/**
+ * @returns {ServerRoute<PostcodeLookupGetRequestRefs>}
+ */
+function getRoute() {
+  return {
+    method: 'GET',
+    path: JOURNEY_BASE_URL,
+    handler(request, h) {
+      const { query } = request
+      const { step } = query
+      const session = getSessionState(request)
+
+      const model =
+        step === steps.manual
+          ? manualViewModel(session)
+          : detailsViewModel(session)
+
+      return h.view(viewName, model)
+    },
+    options: {
+      validate: {
+        query: Joi.object()
+          .keys({
+            step: Joi.string().allow(steps.details, steps.manual).optional()
+          })
+          .optional()
+      }
+    }
+  }
+}
+
+/**
+ * @param {PostcodeLookupConfiguration} options
+ * @returns {ServerRoute<PostcodeLookupPostRequestRefs>}
+ */
+function postRoute(options) {
+  return {
+    method: 'POST',
+    path: JOURNEY_BASE_URL,
+    async handler(request, h) {
+      const { payload } = request
+      const { step } = payload
+
+      switch (step) {
+        case steps.details: {
+          return detailsPostHandler(request, h, options)
+        }
+        case steps.select: {
+          return selectPostHandler(request, h, options)
+        }
+        case steps.manual: {
+          return manualPostHandler(request, h)
+        }
+        default:
+          throw Boom.badRequest(`Invalid step ${step}`)
+      }
+    },
+    options: {
+      validate: {
+        payload: Joi.object()
+          .keys({
+            step: stepSchema
+          })
+          .unknown(true)
+      }
+    }
+  }
+}
+
+/**
+ * Post handler for the details step
+ * @param {PostcodeLookupPostRequest} request
+ * @param {ResponseToolkit<PostcodeLookupPostRequestRefs>} h
+ * @param {PostcodeLookupConfiguration} options
+ */
+async function detailsPostHandler(request, h, options) {
+  const { payload } = request
+  const session = getSessionState(request)
+  const { ordnanceSurveyApiKey: apiKey } = options
+  const { value: details, error } = detailsPayloadSchema.validate(payload)
+
+  let model
+
+  if (error) {
+    model = detailsViewModel(session, details, error)
+
+    return h.view(viewName, model)
+  }
+
+  const { postcodeQuery, buildingNameQuery } = details
+  session.details = { postcodeQuery, buildingNameQuery }
+
+  // Store the updated session
+  request.yar.set(JOURNEY_BASE_URL, session)
+
+  model = await selectViewModel({ session, apiKey })
+
+  return h.view(viewName, model)
+}
+
+/**
+ * Post handler for the select step
+ * @param {PostcodeLookupPostRequest} request
+ * @param {ResponseToolkit<PostcodeLookupPostRequestRefs>} h
+ * @param {PostcodeLookupConfiguration} options
+ */
+async function selectPostHandler(request, h, options) {
+  const { payload } = request
+  const session = getSessionState(request)
+  const { ordnanceSurveyApiKey: apiKey } = options
+  const { value: select, error } = selectPayloadSchema.validate(payload)
+
+  if (error) {
+    const model = await selectViewModel({ session, apiKey }, select, error)
+
+    return h.view(viewName, model)
+  }
+
+  const addresses = await service.searchByUPRN(select.uprn, apiKey)
+  const property = addresses.at(0)
+
+  if (!property) {
+    throw Boom.internal(`UPRN ${property} not found`)
+  }
+
+  const { componentName, sourceUrl } = session.initial
+  flashComponentState(request, componentName, property)
+
+  // Redirect back to the source form page
+  return h.redirect(sourceUrl).code(StatusCodes.SEE_OTHER)
+}
+
+/**
+ * Post handler for the manual step
+ * @param {PostcodeLookupPostRequest} request
+ * @param {ResponseToolkit<PostcodeLookupPostRequestRefs>} h
+ */
+function manualPostHandler(request, h) {
+  const { payload } = request
+  const session = getSessionState(request)
+
+  const { value: manual, error } = manualPayloadSchema.validate(payload, {
+    abortEarly: false
+  })
+
+  if (error) {
+    const model = manualViewModel(session, manual, error)
+
+    return h.view(viewName, model)
+  }
+
+  const { componentName, sourceUrl } = session.initial
+  flashComponentState(request, componentName, manual)
+
+  // Redirect back to the source form page
+  return h.redirect(sourceUrl).code(StatusCodes.SEE_OTHER)
+}
+
+/**
+ * @import { ResponseToolkit, ServerRoute } from '@hapi/hapi'
+ * @import { PostcodeLookupManualPayload, Address, PostcodeLookupGetRequestRefs, PostcodeLookupPostRequestRefs, PostcodeLookupRequest, PostcodeLookupPostRequest, PostcodeLookupConfiguration, PostcodeLookupDispatchData, PostcodeLookupSessionData } from '~/src/server/plugins/postcode-lookup/types.js'
+ * @import { FormRequestPayload, FormResponseToolkit } from '~/src/server/routes/types.js'
+ * @import { ExternalStateAppendage } from '~/src/server/plugins/engine/types.js'
+ */

package/src/server/plugins/postcode-lookup/service.js

@@ -0,0 +1,188 @@
+import { getErrorMessage } from '@defra/forms-model'
+import Boom from '@hapi/boom'
+
+import { createLogger } from '~/src/server/common/helpers/logging/logger.js'
+import { getJson } from '~/src/server/services/httpService.js'
+
+const logger = createLogger()
+
+/**
+ * Returns an empty result set
+ */
+function empty() {
+  return []
+}
+
+/**
+ * Logs OS places errors
+ * @param {unknown} err - the error
+ * @param {string} endpoint - the OS api endpoint
+ */
+function logErrorAndReturnEmpty(err, endpoint) {
+  const msg = `${getErrorMessage(err)} ${(Boom.isBoom(err) && err.data?.payload?.error?.message) ?? ''}`
+
+  logger.error(err, `Exception occured calling OS places ${endpoint} - ${msg}}`)
+
+  return empty()
+}
+
+/**
+ * Fetch data from OS API
+ * @param {string} url - the url to get address json data from
+ * @param {string} endpoint - the url endpoint description for logging
+ */
+async function getAddressData(url, endpoint) {
+  const getJsonByType =
+    /** @type {typeof getJson<DeliveryPointAddressResult>} */ (getJson)
+
+  try {
+    const response = await getJsonByType(url)
+
+    if (response.error) {
+      return logErrorAndReturnEmpty(response.error, endpoint)
+    }
+
+    const results = response.payload.results
+
+    if (!Array.isArray(results)) {
+      return empty()
+    }
+
+    return results.map((result) => formatAddress(result.DPA))
+  } catch (err) {
+    return logErrorAndReturnEmpty(err, endpoint)
+  }
+}
+
+/**
+ * OS places search
+ * @param {string} query - the search term
+ * @param {string} apiKey - the OS api key
+ */
+export async function searchByQuery(query, apiKey) {
+  const endpoint = 'find'
+  const url = `https://api.os.uk/search/places/v1/${endpoint}?query=${encodeURIComponent(query)}&key=${apiKey}`
+
+  return getAddressData(url, endpoint)
+}
+
+/**
+ * OS postcode search
+ * @param {string} postcode - the postcode
+ * @param {string} apiKey - the OS api key
+ */
+export async function searchByPostcode(postcode, apiKey) {
+  const endpoint = 'postcode'
+  const url = `https://api.os.uk/search/places/v1/${endpoint}?postcode=${encodeURIComponent(postcode.replaceAll(/\s/g, ''))}&key=${apiKey}`
+
+  return getAddressData(url, endpoint)
+}
+
+/**
+ * OS UPRN search
+ * @param {string} uprn - the unique property reference number
+ * @param {string} apiKey - the OS api key
+ */
+export async function searchByUPRN(uprn, apiKey) {
+  const endpoint = 'uprn'
+  const url = `https://api.os.uk/search/places/v1/${endpoint}?uprn=${uprn}&key=${apiKey}`
+
+  return getAddressData(url, endpoint)
+}
+
+/**
+ * OS postcode and building name search
+ * @param {string} postcodeQuery - the postcode query
+ * @param {string} buildingNameQuery - the building name query
+ * @param {string} apiKey - the OS api key
+ */
+export async function search(postcodeQuery, buildingNameQuery, apiKey) {
+  let addresses = await searchByPostcode(postcodeQuery, apiKey)
+
+  if (buildingNameQuery) {
+    addresses = addresses.filter((item) =>
+      item.address.includes(buildingNameQuery.toUpperCase())
+    )
+  }
+
+  return addresses
+}
+
+/**
+ * Converts a delivery point address to an address
+ * Taken from http://github.com/dwp/find-an-address-plugin/blob/main/utils/getData.js
+ * @param {DeliveryPointAddress} dpa
+ */
+function formatAddress(dpa) {
+  const addressLine1 = formatAddressLine1(dpa)
+  const addressLine2 = formatAddressLine2(dpa)
+  const town = titleCase(dpa.POST_TOWN || '')
+  const postcode = dpa.POSTCODE || ''
+  const lines = [addressLine1, addressLine2, town]
+  const formatted = `${lines.filter((i) => !!i).join(', ')}, ${postcode}`
+
+  /**
+   * @type {Address}
+   */
+  const address = {
+    uprn: dpa.UPRN,
+    address: dpa.ADDRESS,
+    addressLine1,
+    addressLine2,
+    town,
+    county: '',
+    postcode,
+    formatted
+  }
+
+  return address
+}
+
+/**
+ * @param {DeliveryPointAddress} dpa
+ */
+function formatAddressLine1(dpa) {
+  return titleCase(
+    dpa.ORGANISATION_NAME ||
+      dpa.SUB_BUILDING_NAME ||
+      dpa.BUILDING_NAME ||
+      dpa.BUILDING_NUMBER
+      ? [
+          dpa.ORGANISATION_NAME || '',
+          dpa.SUB_BUILDING_NAME || '',
+          dpa.BUILDING_NAME || '',
+          dpa.BUILDING_NUMBER || ''
+        ]
+          .filter((item) => !!item)
+          .join(' ')
+      : ''
+  )
+}
+
+/**
+ * @param {DeliveryPointAddress} dpa
+ */
+function formatAddressLine2(dpa) {
+  return titleCase(
+    dpa.THOROUGHFARE_NAME || dpa.DEPENDENT_LOCALITY
+      ? [dpa.THOROUGHFARE_NAME || '', dpa.DEPENDENT_LOCALITY || '']
+          .filter((item) => !!item)
+          .join(', ')
+      : ''
+  )
+}
+
+/**
+ * Title case address
+ * @param {string} address
+ */
+function titleCase(address) {
+  return address
+    .split(' ')
+    .map((item) => item.charAt(0).toUpperCase() + item.slice(1).toLowerCase())
+    .join(' ')
+}
+
+/**
+ * @import { Address, DeliveryPointAddress, DeliveryPointAddressResult } from '~/src/server/plugins/postcode-lookup/types.js'
+ */

package/src/server/plugins/postcode-lookup/service.test.js

@@ -0,0 +1,177 @@
+import Boom from '@hapi/boom'
+
+import * as service from '~/src/server/plugins/postcode-lookup/service.js'
+import { result as postcodeResult } from '~/src/server/plugins/postcode-lookup/test/__stubs__/postcode.js'
+import { result as queryResult } from '~/src/server/plugins/postcode-lookup/test/__stubs__/query.js'
+import { result as uprnResult } from '~/src/server/plugins/postcode-lookup/test/__stubs__/uprn.js'
+import { getJson } from '~/src/server/services/httpService.js'
+
+jest.mock('~/src/server/services/httpService.ts')
+
+describe('Postcode lookup service', () => {
+  describe('searchByPostcode', () => {
+    it('should return formatted addresses', async () => {
+      jest.mocked(getJson).mockResolvedValueOnce({
+        res: /** @type {IncomingMessage} */ ({
+          statusCode: 200,
+          headers: {}
+        }),
+        payload: postcodeResult,
+        error: undefined
+      })
+
+      const results = await service.searchByPostcode('NW1 6XE', 'apikey')
+
+      expect(results).toHaveLength(10)
+      expect(results.at(0)).toEqual({
+        address: "EMILIA'S CRAFTED PASTA, 215, BAKER STREET, LONDON, NW1 6XE",
+        addressLine1: "Emilia's Crafted Pasta 215",
+        addressLine2: 'Baker Street',
+        county: '',
+        formatted: "Emilia's Crafted Pasta 215, Baker Street, London, NW1 6XE",
+        postcode: 'NW1 6XE',
+        town: 'London',
+        uprn: '10033619968'
+      })
+    })
+
+    it('should return an empty response when an error is encountered', async () => {
+      jest.mocked(getJson).mockResolvedValueOnce({
+        res: /** @type {IncomingMessage} */ ({
+          statusCode: 300,
+          headers: {}
+        }),
+        payload: undefined,
+        error: new Error('Unknown error')
+      })
+
+      const results = await service.searchByPostcode('NW1 6XE', 'apikey')
+
+      expect(results).toHaveLength(0)
+      expect(results).toEqual([])
+    })
+
+    it('should return an empty response when a non 200 response is encountered', async () => {
+      jest
+        .mocked(getJson)
+        .mockRejectedValueOnce(
+          Boom.badRequest(
+            'OS API error',
+            new Error('Invalid postcode segments')
+          )
+        )
+
+      const results = await service.searchByPostcode(
+        'invalid postcode',
+        'apikey'
+      )
+
+      expect(results).toHaveLength(0)
+      expect(results).toEqual([])
+    })
+
+    it('should return an empty response when no results are returned', async () => {
+      jest.mocked(getJson).mockResolvedValueOnce({
+        res: /** @type {IncomingMessage} */ ({
+          statusCode: 200,
+          headers: {}
+        }),
+        payload: { results: undefined },
+        error: undefined
+      })
+
+      const results = await service.searchByPostcode('NW1 6XE', 'apikey')
+
+      expect(results).toHaveLength(0)
+      expect(results).toEqual([])
+    })
+  })
+
+  describe('searchByUPRN', () => {
+    it('should return formatted addresses', async () => {
+      jest.mocked(getJson).mockResolvedValueOnce({
+        res: /** @type {IncomingMessage} */ ({
+          statusCode: 200,
+          headers: {}
+        }),
+        payload: uprnResult,
+        error: undefined
+      })
+
+      const results = await service.searchByUPRN('100023071949', 'apikey')
+
+      expect(results).toHaveLength(1)
+      expect(results.at(0)).toEqual({
+        address: 'SHERLOCK HOLMES MUSEUM, 221B, BAKER STREET, LONDON, NW1 6XE',
+        addressLine1: 'Sherlock Holmes Museum 221b',
+        addressLine2: 'Baker Street',
+        county: '',
+        formatted: 'Sherlock Holmes Museum 221b, Baker Street, London, NW1 6XE',
+        postcode: 'NW1 6XE',
+        town: 'London',
+        uprn: '100023071949'
+      })
+    })
+  })
+
+  describe('searchByQuery', () => {
+    it('should return formatted addresses', async () => {
+      jest.mocked(getJson).mockResolvedValueOnce({
+        res: /** @type {IncomingMessage} */ ({
+          statusCode: 200,
+          headers: {}
+        }),
+        payload: queryResult,
+        error: undefined
+      })
+
+      const results = await service.searchByQuery(
+        'Prime minister downing',
+        'apikey'
+      )
+
+      expect(results).toHaveLength(5)
+      expect(results.at(0)).toEqual({
+        address: 'BAKER STREET COTTAGE, BAKER STREET, FROME, BA11 3BL',
+        addressLine1: 'Baker Street Cottage',
+        addressLine2: 'Baker Street',
+        town: 'Frome',
+        county: '',
+        formatted: 'Baker Street Cottage, Baker Street, Frome, BA11 3BL',
+        postcode: 'BA11 3BL',
+        uprn: '250034655'
+      })
+    })
+  })
+
+  describe('search', () => {
+    it('should return formatted addresses', async () => {
+      jest.mocked(getJson).mockResolvedValueOnce({
+        res: /** @type {IncomingMessage} */ ({
+          statusCode: 200,
+          headers: {}
+        }),
+        payload: postcodeResult,
+        error: undefined
+      })
+
+      const results = await service.search('NW1 6XE', 'Emilia', 'apikey')
+
+      expect(results).toHaveLength(1)
+      expect(results.at(0)).toEqual({
+        address: "EMILIA'S CRAFTED PASTA, 215, BAKER STREET, LONDON, NW1 6XE",
+        addressLine1: "Emilia's Crafted Pasta 215",
+        addressLine2: 'Baker Street',
+        county: '',
+        formatted: "Emilia's Crafted Pasta 215, Baker Street, London, NW1 6XE",
+        postcode: 'NW1 6XE',
+        town: 'London',
+        uprn: '10033619968'
+      })
+    })
+  })
+})
+
+/**
+ * @import  { IncomingMessage } from 'node:http'
+ */