@defra/fcp-sfd-frontend-engine 0.18.0 → 0.19.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@defra/fcp-sfd-frontend-engine",
-  "version": "0.18.0",
+  "version": "0.19.0",
   "description": "Shared frontend engine used by both the internal and external frontend applications.",
   "main": "./dist/index.cjs",
   "exports": {

package/src/constants/country-names.js

@@ -0,0 +1,8 @@
+export const COUNTRY_NAMES = {
+  E: 'ENGLAND',
+  W: 'WALES',
+  S: 'SCOTLAND',
+  N: 'NORTHERN IRELAND',
+  L: 'CHANNEL ISLANDS',
+  M: 'ISLE OF MAN'
+}

package/src/index.js

@@ -4,3 +4,4 @@ export { mutations } from './mutations/mutations.js'
 export { presenters } from './presenters/presenters.js'
 export { schemas } from './schemas/schemas.js'
 export { utils } from './utils/utils.js'
+export { services } from './services/services.js'

package/src/mappers/address-lookup-mapper.js

@@ -0,0 +1,79 @@
+/**
+ * Maps addresses returned by the OS Places API into a format suitable
+ * for front-end display and DAL updating.
+ * https://docs.os.uk/os-apis/accessing-os-apis/os-places-api/datasets as a reference for the datasets
+ *
+ * @module addressLookupMapper
+ */
+
+import { schemas } from '../schemas/schemas.js'
+import { COUNTRY_NAMES } from '../constants/country-names.js'
+
+const addressLookupMapper = (addresses) => {
+  // Guard against undefined or null addresses (e.g. from upstream bugs)
+  if (!Array.isArray(addresses)) {
+    return []
+  }
+
+  return addresses.map((address) => {
+    const { error } = schemas.osPlaces.addressLookup.validate(address)
+
+    if (error) {
+      return null
+    }
+
+    const {
+      UPRN,
+      ADDRESS,
+      PO_BOX_NUMBER,
+      ORGANISATION_NAME,
+      DEPARTMENT_NAME,
+      SUB_BUILDING_NAME,
+      BUILDING_NAME,
+      BUILDING_NUMBER,
+      DEPENDENT_THOROUGHFARE_NAME,
+      THOROUGHFARE_NAME,
+      DOUBLE_DEPENDENT_LOCALITY,
+      DEPENDENT_LOCALITY,
+      POST_TOWN,
+      POSTCODE,
+      LOCAL_CUSTODIAN_CODE_DESCRIPTION,
+      COUNTRY_CODE
+    } = address.properties
+
+    const buildingName = PO_BOX_NUMBER ? `PO BOX ${PO_BOX_NUMBER}` : BUILDING_NAME || null
+
+    return {
+      displayAddress: ADDRESS,
+      pafOrganisationName: filterAndJoin([ORGANISATION_NAME, DEPARTMENT_NAME]),
+      flatName: SUB_BUILDING_NAME ?? null,
+      buildingName,
+      buildingNumberRange: BUILDING_NUMBER ?? null,
+      street: filterAndJoin([DEPENDENT_THOROUGHFARE_NAME, THOROUGHFARE_NAME]),
+      dependentLocality: DEPENDENT_LOCALITY ?? null,
+      doubleDependentLocality: DOUBLE_DEPENDENT_LOCALITY ?? null,
+      city: POST_TOWN,
+      county: formatCounty(LOCAL_CUSTODIAN_CODE_DESCRIPTION, POST_TOWN),
+      postcode: POSTCODE,
+      country: COUNTRY_NAMES[COUNTRY_CODE] ?? null,
+      uprn: UPRN
+    }
+  }).filter(Boolean)
+}
+
+// Remove placeholder county values
+const formatCounty = (localCustodianCodeDescription, postTown) => {
+  if (localCustodianCodeDescription === 'ORDNANCE SURVEY' || localCustodianCodeDescription === postTown) {
+    return null
+  }
+
+  return localCustodianCodeDescription
+}
+
+const filterAndJoin = (addressesProperties) => {
+  return addressesProperties.filter(Boolean).join(', ') || null
+}
+
+export {
+  addressLookupMapper
+}

package/src/mappers/mappers.js

@@ -2,10 +2,12 @@ import { mapPersonalBusinessDetails } from './personal-business-details-mapper.j
 import { mapAddress } from './address-mapper.js'
 import { mapCustomerName } from './customer-name-mapper.js'
 import { mapBusinessDetails } from './business-details-mapper.js'
+import { addressLookupMapper } from './address-lookup-mapper.js'
 
 export const mappers = {
   personalBusinessDetails: mapPersonalBusinessDetails,
   address: mapAddress,
   customerName: mapCustomerName,
-  businessDetails: mapBusinessDetails
+  businessDetails: mapBusinessDetails,
+  addressLookup: addressLookupMapper
 }

package/src/mock-data/mock-os-places-addresses.js

@@ -0,0 +1,146 @@
+export const mockAddresses = [
+  {
+    properties: {
+      UPRN: '10000001',
+      ADDRESS: 'APARTMENT 1, REDBRIDGE HOUSE, 1 ROSE COURT, LONDON, SW1A 1AA',
+      SUB_BUILDING_NAME: 'APARTMENT 1',
+      BUILDING_NAME: 'REDBRIDGE HOUSE',
+      BUILDING_NUMBER: '1',
+      THOROUGHFARE_NAME: 'ROSE COURT',
+      POST_TOWN: 'LONDON',
+      POSTCODE: 'SW1A 1AA',
+      LOCAL_CUSTODIAN_CODE_DESCRIPTION: 'GREATER LONDON',
+      COUNTRY_CODE: 'E'
+    }
+  },
+  {
+    properties: {
+      UPRN: '10000002',
+      ADDRESS: 'FLAT 2B, KINGSLEY APARTMENTS, 12 VICTORIA SQUARE, LONDON, SW1A 1AA',
+      SUB_BUILDING_NAME: 'FLAT 2B',
+      BUILDING_NAME: 'KINGSLEY APARTMENTS',
+      BUILDING_NUMBER: '12',
+      THOROUGHFARE_NAME: 'VICTORIA SQUARE',
+      DEPENDENT_LOCALITY: '',
+      POST_TOWN: 'LONDON',
+      POSTCODE: 'SW1A 1AA',
+      LOCAL_CUSTODIAN_CODE_DESCRIPTION: 'GREATER LONDON',
+      COUNTRY_CODE: 'E'
+    }
+  },
+  {
+    properties: {
+      UPRN: '10000003',
+      ADDRESS: 'THE GROUND FLOOR, THE OLD GRANARY, 5 CHURCH LANE, LONDON, SW1A 1AA',
+      ORGANISATION_NAME: 'OLD GRANARY STUDIOS',
+      SUB_BUILDING_NAME: 'GROUND FLOOR',
+      BUILDING_NAME: 'THE OLD GRANARY',
+      BUILDING_NUMBER: '5',
+      THOROUGHFARE_NAME: 'CHURCH LANE',
+      POST_TOWN: 'LONDON',
+      POSTCODE: 'SW1A 1AA',
+      LOCAL_CUSTODIAN_CODE_DESCRIPTION: 'GREATER LONDON',
+      COUNTRY_CODE: 'E'
+    }
+  },
+  {
+    properties: {
+      UPRN: '10000004',
+      ADDRESS: 'SUITE 3, WELLINGTON HOUSE, 20 QUEEN STREET, LONDON, SW1A 1AA',
+      ORGANISATION_NAME: 'WELLINGTON CONSULTING LTD',
+      DEPARTMENT_NAME: 'CLIENT SERVICES',
+      SUB_BUILDING_NAME: 'SUITE 3',
+      BUILDING_NAME: 'WELLINGTON HOUSE',
+      BUILDING_NUMBER: '20',
+      THOROUGHFARE_NAME: 'QUEEN STREET',
+      POST_TOWN: 'LONDON',
+      POSTCODE: 'SW1A 1AA',
+      LOCAL_CUSTODIAN_CODE_DESCRIPTION: 'GREATER LONDON',
+      COUNTRY_CODE: 'E'
+    }
+  },
+  {
+    properties: {
+      UPRN: '10000005',
+      ADDRESS: 'UNIT 6, MARKET ROW, 3 MARKET YARD, LONDON, SW1A 1AA',
+      ORGANISATION_NAME: 'MARKET ROW TRADERS',
+      SUB_BUILDING_NAME: 'UNIT 6',
+      BUILDING_NAME: 'MARKET ROW',
+      BUILDING_NUMBER: '3',
+      THOROUGHFARE_NAME: 'MARKET YARD',
+      POST_TOWN: 'LONDON',
+      POSTCODE: 'SW1A 1AA',
+      LOCAL_CUSTODIAN_CODE_DESCRIPTION: 'GREATER LONDON',
+      COUNTRY_CODE: 'E'
+    }
+  },
+  {
+    properties: {
+      UPRN: '20000001',
+      ADDRESS: '1 ORCHARD COTTAGES, WESTFIELD LANE, SHEPTON MALLET, BS14 8XX',
+      BUILDING_NAME: 'ORCHARD COTTAGES',
+      BUILDING_NUMBER: '1',
+      THOROUGHFARE_NAME: 'WESTFIELD LANE',
+      POST_TOWN: 'SHEPTON MALLET',
+      POSTCODE: 'BS14 8XX',
+      LOCAL_CUSTODIAN_CODE_DESCRIPTION: 'SOMERSET',
+      COUNTRY_CODE: 'E'
+    }
+  },
+  {
+    properties: {
+      UPRN: '20000002',
+      ADDRESS: 'THE STABLES, MANOR FARM, HOLLOW ROAD, SHEPTON MALLET, BS14 8XX',
+      ORGANISATION_NAME: 'MANOR FARM',
+      SUB_BUILDING_NAME: 'THE STABLES',
+      BUILDING_NAME: 'MANOR FARM',
+      THOROUGHFARE_NAME: 'HOLLOW ROAD',
+      POST_TOWN: 'SHEPTON MALLET',
+      POSTCODE: 'BS14 8XX',
+      LOCAL_CUSTODIAN_CODE_DESCRIPTION: 'SOMERSET',
+      COUNTRY_CODE: 'E'
+    }
+  },
+  {
+    properties: {
+      UPRN: '30000001',
+      ADDRESS: 'FLAT 4, BISHOP COURT, 9 FLEET STREET, LONDON, EC1A 1BB',
+      SUB_BUILDING_NAME: 'FLAT 4',
+      BUILDING_NAME: 'BISHOP COURT',
+      BUILDING_NUMBER: '9',
+      THOROUGHFARE_NAME: 'FLEET STREET',
+      POST_TOWN: 'LONDON',
+      POSTCODE: 'EC1A 1BB',
+      LOCAL_CUSTODIAN_CODE_DESCRIPTION: 'CITY OF LONDON',
+      COUNTRY_CODE: 'E'
+    }
+  },
+  {
+    properties: {
+      UPRN: '40000001',
+      ADDRESS: '2A PICCADILLY ARCADE, MANCHESTER, M1 1AE',
+      ORGANISATION_NAME: 'PICCADILLY ARCADE LTD',
+      SUB_BUILDING_NAME: '2A',
+      BUILDING_NAME: 'PICCADILLY ARCADE',
+      BUILDING_NUMBER: '2A',
+      THOROUGHFARE_NAME: 'PICCADILLY',
+      POST_TOWN: 'MANCHESTER',
+      POSTCODE: 'M1 1AE',
+      LOCAL_CUSTODIAN_CODE_DESCRIPTION: 'GREATER MANCHESTER',
+      COUNTRY_CODE: 'E'
+    }
+  },
+  {
+    properties: {
+      UPRN: '50000001',
+      ADDRESS: '3 WESTBOURNE TERRACE, LONDON, W1A 0AX',
+      BUILDING_NAME: 'WESTBOURNE TERRACE',
+      BUILDING_NUMBER: '3',
+      THOROUGHFARE_NAME: 'WESTBOURNE TERRACE',
+      POST_TOWN: 'LONDON',
+      POSTCODE: 'W1A 0AX',
+      LOCAL_CUSTODIAN_CODE_DESCRIPTION: 'WESTMINSTER',
+      COUNTRY_CODE: 'E'
+    }
+  }
+]

package/src/services/os-places/address-lookup-service.js

@@ -0,0 +1,202 @@
+/**
+ * Service to fetch and map addresses from the OS Places API based on a UK postcode.
+ *
+ * The service:
+ * - Calls the OS Places API via the official `osdatahub` package to search for addresses for a given postcode
+ * - Maps the returned address properties into a format suitable for front-end display and for updating via the DAL.
+ *
+ * @module addressLookupService
+ */
+
+import { placesAPI } from 'osdatahub'
+import { addressLookupMapper } from '../../mappers/address-lookup-mapper.js'
+import { mockPostcode } from './os-places-stub.js'
+import { INTERNAL_SERVER_ERROR } from '../../constants/status-codes.js'
+
+/**
+ * Fetch and map addresses from OS Places API based on postcode.
+ *
+ * @param {string} postcode - The UK postcode to search for
+ * @param {object} osPlacesConfig - OS Places configuration object
+ * @param {string} osPlacesConfig.clientId - OS Places API client ID
+ * @param {boolean} osPlacesConfig.osPlacesStub - Whether to use mock data
+ * @returns {Promise<Array|object>} Array of addresses or error object
+ */
+const addressLookupService = async (postcode, osPlacesConfig) => {
+  const addresses = await fetchAddressesFromPostcodeLookup(postcode, osPlacesConfig)
+
+  // If the API call itself failed, return the error object
+  if (addresses.error) {
+    return addresses
+  }
+
+  // If the API returned successfully but found no addresses for the postcode
+  if (!addresses?.length) {
+    // Create a Joi-like error object to indicate that the postcode lookup returned no addresses
+    return {
+      error: [
+        {
+          message: 'No addresses found for this postcode',
+          path: ['postcode']
+        }
+      ]
+    }
+  }
+
+  // Map the raw API response into a format suitable for the front-end
+  const mappedAddresses = addressLookupMapper(addresses)
+
+  return mappedAddresses
+}
+
+/**
+ * Fetch addresses from the OS Places API or mock data based on configuration.
+ *
+ * Implements:
+ * - Retry logic (3 attempts) for transient errors (network timeouts, 5xx server errors)
+ * - Exponential backoff between retries (100ms, 200ms, 400ms)
+ * - Standard error formatting for all failures
+ *
+ * Note: The osdatahub package does not currently support request timeouts.
+ * If API calls hang indefinitely, they will eventually fail after 3 retry attempts.
+ *
+ * @private
+ * @param {string} postcode - The UK postcode to search for
+ * @param {object} osPlacesConfig - Configuration object containing clientId and osPlacesStub flag
+ * @returns {Promise<Array|object>} Array of address features or error object with error property
+ */
+const fetchAddressesFromPostcodeLookup = async (postcode, osPlacesConfig) => {
+  const MAX_RETRIES = 3
+  const INITIAL_BACKOFF_MS = 100
+
+  for (let attemptNumber = 1; attemptNumber <= MAX_RETRIES; attemptNumber++) {
+    try {
+      const { clientId, osPlacesStub } = osPlacesConfig
+
+      // Use mock data for testing if enabled, otherwise call the real OS Places API
+      if (osPlacesStub) {
+        const response = mockPostcode(postcode)
+
+        return response.features ?? []
+      }
+
+      const response = await fetchFromPlacesAPI(clientId, postcode)
+      return response.features ?? []
+    } catch (error) {
+      const shouldRetry = isRetryable(error) && (attemptNumber < MAX_RETRIES)
+
+      if (!shouldRetry) {
+        // Either error is permanent, or this was our last attempt
+        return buildErrorResponse(error.message)
+      }
+
+      // Wait before retrying with exponential backoff (gives the API time to recover)
+      const backoffMs = calculateExponentialBackoff(attemptNumber, INITIAL_BACKOFF_MS)
+      await delayBeforeRetry(backoffMs)
+    }
+  }
+}
+
+/**
+ * Calculate exponential backoff duration.
+ * Attempts: 1, 2, 3 → Wait: 100ms, 200ms, 400ms
+ *
+ * Example: attempt 2 with 100ms base
+ * - exponent = 2 - 1 = 1
+ * - powerOf2 = 2^1 = 2
+ * - backoff = 100 * 2 = 200ms
+ *
+ * @private
+ * @param {number} attemptNumber - Current attempt (1-indexed)
+ * @param {number} baseMs - Initial backoff in milliseconds
+ * @returns {number} Milliseconds to wait before next retry
+ */
+const calculateExponentialBackoff = (attemptNumber, baseMs) => {
+  const exponent = attemptNumber - 1
+  const powerOf2 = Math.pow(2, exponent)
+  const backoffDuration = baseMs * powerOf2
+  return backoffDuration
+}
+
+/**
+ * Delay before retrying (allows time for API to recover from transient errors).
+ *
+ * @private
+ * @param {number} ms - Milliseconds to wait
+ * @returns {Promise<void>}
+ */
+function delayBeforeRetry (ms) {
+  const callback = (resolve) => {
+    setTimeout(resolve, ms)
+  }
+
+  return new Promise(callback)
+}
+
+/**
+ * Build a standard error response object.
+ *
+ * @private
+ * @param {string} message - Error message
+ * @returns {object} Joi-like error object
+ */
+const buildErrorResponse = (message) => {
+  return {
+    error: [
+      {
+        message: message || 'Failed to fetch addresses',
+        path: ['postcode']
+      }
+    ]
+  }
+}
+
+/**
+ * Fetch from the OS Places API.
+ *
+ * @private
+ * @param {string} clientId - OS Places API client ID
+ * @param {string} postcode - The UK postcode to search for
+ * @returns {Promise<object>} API response
+ * @throws {Error} If API returns an error
+ */
+const fetchFromPlacesAPI = async (clientId, postcode) => {
+  const response = await placesAPI.postcode(clientId, postcode, { limit: 150 })
+
+  return response
+}
+
+/**
+ * Determine if an error is transient (temporary) and should trigger a retry.
+ *
+ * Transient errors include:
+ * - Network errors: ECONNRESET, ECONNREFUSED, ETIMEDOUT
+ * - Server errors: 5xx status codes (API is temporarily down)
+ *
+ * Permanent errors (should NOT retry):
+ * - Client errors: 4xx status codes (bad input, auth failure)
+ * - Logic errors (bad API key, invalid postcode format)
+ *
+ * @private
+ * @param {Error} error - The error to check
+ * @returns {boolean} True if error is transient and we should retry
+ */
+const isRetryable = (error) => {
+  // Network-level transient errors (temporary connection problems)
+  const networkErrors = ['ECONNRESET', 'ECONNREFUSED', 'ETIMEDOUT']
+  if (networkErrors.includes(error.code)) {
+    return true
+  }
+
+  // Server error (5xx status codes mean the API is temporarily unavailable)
+  if (error.status && error.status >= INTERNAL_SERVER_ERROR) {
+    return true
+  }
+
+  // All other errors are permanent (bad input, auth failure, etc.)
+  return false
+}
+
+export {
+  addressLookupService
+}

package/src/services/os-places/os-places-stub.js

@@ -0,0 +1,37 @@
+/**
+ * Mock address data and stub implementation for OS Places API.
+ *
+ * This module provides mock address data used during development and testing
+ * when OS Places API stubbing is enabled.
+ *
+ * @module osPlacesStub
+ */
+
+import { mockAddresses } from '../../mock-data/mock-os-places-addresses.js'
+
+/**
+ * Retrieves mock address data matching a given postcode.
+ *
+ * This function is used when OS Places API stubbing is enabled.
+ * It takes a postcode, formats it to uppercase, and removes all spaces.
+ * It then filters the mock address dataset to find all addresses whose
+ * postcodes (also normalized by removing spaces and converting to uppercase)
+ * match the given postcode.
+ *
+ * @param {string} postcode - The postcode to search for.
+ * @returns {{ features: Array<Object> }} An object containing a `features` array of matching addresses.
+ */
+export const mockPostcode = (postcode) => {
+  const formattedPostcode = postcode?.toUpperCase().replaceAll(' ', '')
+
+  // Find addresses that match the formatted postcode (ignoring spaces)
+  const matchingAddresses = mockAddresses.filter(address => {
+    const addressPostcode = address.properties.POSTCODE?.toUpperCase().replaceAll(' ', '')
+
+    return addressPostcode === formattedPostcode
+  })
+
+  return {
+    features: matchingAddresses
+  }
+}

package/src/services/services.js

@@ -0,0 +1,5 @@
+import { addressLookupService } from './os-places/address-lookup-service.js'
+
+export const services = {
+  addressLookup: addressLookupService
+}