@defra/forms-engine-plugin 4.0.41 → 4.0.43

package/src/client/javascripts/shared.js

@@ -2,12 +2,16 @@ import { initAllAutocomplete as initAllAutocompleteImp } from '~/src/client/java
 import { initFileUpload as initFileUploadImp } from '~/src/client/javascripts/file-upload.js'
 import { initAllGovuk as initAllGovukImp } from '~/src/client/javascripts/govuk.js'
 import { initPreviewCloseLink as initPreviewCloseLinkImp } from '~/src/client/javascripts/preview-close-link.js'
+export { initMaps } from '~/src/client/javascripts/location-map.js'
 
 export const initAllGovuk = initAllGovukImp
 export const initAllAutocomplete = initAllAutocompleteImp
 export const initFileUpload = initFileUploadImp
 export const initPreviewCloseLink = initPreviewCloseLinkImp
 
+/**
+ * Initialise all clientside components (but not maps as this will be an opt-in for now given the additional UMD assets that are required)
+ */
 export function initAll() {
   initAllGovuk()
   initAllAutocomplete()

package/src/client/stylesheets/_location-fields.scss

@@ -3,3 +3,14 @@
 .govuk-form-group .app-location-field-inputs .govuk-form-group {
   margin-bottom: 0;
 }
+
+.map-container {
+  margin-top: 10px;
+}
+
+// Hides the location instructions text when JS (maps) is available
+.js-enabled .app-location-field {
+  details:last-child {
+    display: none;
+  }
+}

package/src/client/stylesheets/application.scss

@@ -2,7 +2,6 @@
 @use "shared";
 @use "code";
 @use "tag-env";
-@use "location-fields";
 
 //  An example of some user-supplied styling
 //  Not great practice but it illustrates the point

package/src/client/stylesheets/shared.scss

@@ -2,6 +2,7 @@
 @use "pkg:accessible-autocomplete";
 @use "prose";
 @use "summary-list";
+@use "location-fields";
 
 // Use default GDS Transport font for autocomplete
 .autocomplete__hint,

package/src/config/index.ts

@@ -255,7 +255,7 @@ export const config = convict({
   } as SchemaObj<string>,
 
   ordnanceSurveyApiKey: {
-    doc: 'The ordnance survey api key use by the postcode lookup plugin',
+    doc: 'The ordnance survey api key used by the postcode lookup and maps plugin',
     format: String,
     nullable: true,
     default: undefined,

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

@@ -22,7 +22,8 @@ export const configureEnginePlugin = async (
     preparePageEventRequestOptions,
     onRequest,
     saveAndExit,
-    ordnanceSurveyApiKey
+    ordnanceSurveyApiKey,
+    ordnanceSurveyApiSecret
   }: RouteConfig = {},
   cache?: CacheService
 ): Promise<{
@@ -65,7 +66,8 @@ export const configureEnginePlugin = async (
       onRequest,
       baseUrl: 'http://localhost:3009', // always runs locally
       saveAndExit,
-      ordnanceSurveyApiKey
+      ordnanceSurveyApiKey,
+      ordnanceSurveyApiSecret
     }
   }
 }

package/src/server/plugins/engine/options.js

@@ -26,7 +26,8 @@ const pluginRegistrationOptionsSchema = Joi.object({
   onRequest: Joi.function().optional(),
   baseUrl: Joi.string().uri().required(),
   saveAndExit: Joi.function().optional(),
-  ordnanceSurveyApiKey: Joi.string().optional()
+  ordnanceSurveyApiKey: Joi.string().optional(),
+  ordnanceSurveyApiSecret: Joi.string().optional()
 })
 
 /**

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

@@ -15,6 +15,7 @@ import { getRoutes as getRepeaterItemDeleteRoutes } from '~/src/server/plugins/e
 import { getRoutes as getRepeaterSummaryRoutes } from '~/src/server/plugins/engine/routes/repeaters/summary.js'
 import { type PluginOptions } from '~/src/server/plugins/engine/types.js'
 import { registerVision } from '~/src/server/plugins/engine/vision.js'
+import { mapPlugin } from '~/src/server/plugins/map/index.js'
 import { postcodeLookupPlugin } from '~/src/server/plugins/postcode-lookup/index.js'
 import {
   type FormRequestPayloadRefs,
@@ -37,7 +38,8 @@ export const plugin = {
       viewContext,
       preparePageEventRequestOptions,
       onRequest,
-      ordnanceSurveyApiKey
+      ordnanceSurveyApiKey,
+      ordnanceSurveyApiSecret
     } = options
 
     const cacheService =
@@ -57,6 +59,17 @@ export const plugin = {
       })
     }
 
+    // Register the maps plugin only if we have an OS api key & secret
+    if (ordnanceSurveyApiKey && ordnanceSurveyApiSecret) {
+      await server.register({
+        plugin: mapPlugin,
+        options: {
+          ordnanceSurveyApiKey,
+          ordnanceSurveyApiSecret
+        }
+      })
+    }
+
     server.expose('baseLayoutPath', nunjucksOptions.baseLayoutPath)
     server.expose('viewContext', viewContext)
     server.expose('cacheService', cacheService)

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

@@ -423,6 +423,7 @@ export interface PluginOptions {
   onRequest?: OnRequestCallback
   baseUrl: string // base URL of the application, protocol and hostname e.g. "https://myapp.com"
   ordnanceSurveyApiKey?: string
+  ordnanceSurveyApiSecret?: string
 }
 
 export interface FormAdapterSubmissionMessageMeta {

package/src/server/plugins/engine/views/components/_location-field-base.html

@@ -70,7 +70,7 @@
 
   {% set hasErrors = showFieldsetError and component.model.errorMessage %}
 
-  <div class="govuk-form-group {{ "govuk-form-group--error" if hasErrors }}">
+  <div class="govuk-form-group app-location-field {{ "govuk-form-group--error" if hasErrors }}" data-locationtype="{{component.type | lower}}">
     {{ govukFieldset({
       legend: {
         text: component.model.fieldset.legend.text,

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

@@ -3,8 +3,10 @@
 
 {% macro OsGridRefField(component) %}
   {% set hasErrors = component.model.errorMessage %}
-  <div class="govuk-form-group {{ "govuk-form-group--error" if hasErrors }}">
-    {{ TextField(component) }}
+  <div class="govuk-form-group app-location-field {{ "govuk-form-group--error" if hasErrors }}" data-locationtype="{{component.type | lower}}">
+    <div class="app-location-field-inputs">
+      {{ TextField(component) }}
+    </div>
 
     {% if component.model.instructionText %}
       {{ govukDetails({

package/src/server/plugins/map/index.js

@@ -0,0 +1,19 @@
+import { getRoutes } from '~/src/server/plugins/map/routes/index.js'
+
+/**
+ * @satisfies {NamedPlugin<MapConfiguration>}
+ */
+export const mapPlugin = {
+  name: '@defra/forms-engine-plugin/map',
+  dependencies: ['@hapi/inert'],
+  multiple: false,
+  register(server, options) {
+    // @ts-expect-error - Request typing
+    server.route(getRoutes(options))
+  }
+}
+
+/**
+ * @import { NamedPlugin } from '@hapi/hapi'
+ * @import { MapConfiguration } from '~/src/server/plugins/map/types.js'
+ */

package/src/server/plugins/map/routes/get-os-token.js

@@ -0,0 +1,41 @@
+import { post } from '~/src/server/services/httpService.js'
+
+/**
+ * @type {string}
+ */
+let cachedToken
+let tokenExpiry = 0
+
+/**
+ * Get Ordnance Survey OAuth token
+ * @param {MapConfiguration} options - Ordnance survey map options
+ */
+export async function getAccessToken(options) {
+  const { ordnanceSurveyApiKey: key, ordnanceSurveyApiSecret: secret } = options
+  const now = Date.now()
+
+  if (cachedToken && now < tokenExpiry) {
+    return cachedToken
+  }
+
+  const creds = `${key}:${secret}`
+  const result = await post('https://api.os.uk/oauth2/token/v1', {
+    headers: {
+      Authorization: `Basic ${btoa(creds)}`,
+      'Content-Type': 'application/x-www-form-urlencoded'
+    },
+    payload: 'grant_type=client_credentials',
+    json: true
+  })
+
+  const data = result.payload
+
+  cachedToken = data.access_token
+  tokenExpiry = now + (data.expires_in - 60) * 1000 // refresh early
+
+  return cachedToken
+}
+
+/**
+ * @import { MapConfiguration } from '~/src/server/plugins/map/types.js'
+ */

package/src/server/plugins/map/routes/get-os-token.test.js

@@ -0,0 +1,55 @@
+import { getAccessToken } from '~/src/server/plugins/map/routes/get-os-token.js'
+import { post } from '~/src/server/services/httpService.js'
+
+jest.mock('~/src/server/services/httpService.ts')
+
+describe('OS OAuth token', () => {
+  describe('getAccessToken', () => {
+    it('should get access token', async () => {
+      jest.mocked(post).mockResolvedValueOnce({
+        res: /** @type {IncomingMessage} */ ({
+          statusCode: 200,
+          headers: {}
+        }),
+        payload: {
+          access_token: 'access_token',
+          expires_in: '299',
+          issued_at: '1770036762387',
+          token_type: 'Bearer'
+        },
+        error: undefined
+      })
+
+      const token = await getAccessToken({
+        ordnanceSurveyApiKey: 'apikey',
+        ordnanceSurveyApiSecret: 'apisecret'
+      })
+
+      expect(token).toBe('access_token')
+
+      expect(post).toHaveBeenCalledWith('https://api.os.uk/oauth2/token/v1', {
+        headers: {
+          Authorization: `Basic ${btoa('apikey:apisecret')}`,
+          'Content-Type': 'application/x-www-form-urlencoded'
+        },
+        payload: 'grant_type=client_credentials',
+        json: true
+      })
+      expect(post).toHaveBeenCalledTimes(1)
+    })
+
+    it('should return an cached token', async () => {
+      const token = await getAccessToken({
+        ordnanceSurveyApiKey: 'apikey',
+        ordnanceSurveyApiSecret: 'apisecret'
+      })
+
+      expect(token).toBe('access_token')
+      expect(post).toHaveBeenCalledTimes(0)
+    })
+  })
+})
+
+/**
+ * @import  { IncomingMessage } from 'node:http'
+ */

package/src/server/plugins/map/routes/index.js

@@ -0,0 +1,192 @@
+import { resolve } from 'node:path'
+
+import { StatusCodes } from 'http-status-codes'
+import Joi from 'joi'
+
+import { getAccessToken } from '~/src/server/plugins/map/routes/get-os-token.js'
+import { find, nearest } from '~/src/server/plugins/map/service.js'
+import {
+  get,
+  request as httpRequest
+} from '~/src/server/services/httpService.js'
+
+/**
+ * Gets the map support routes
+ * @param {MapConfiguration} options - ordnance survey names api key
+ */
+export function getRoutes(options) {
+  return [
+    mapStyleResourceRoutes(),
+    mapProxyRoute(options),
+    tileProxyRoute(options),
+    geocodeProxyRoute(options),
+    reverseGeocodeProxyRoute(options)
+  ]
+}
+
+/**
+ * Proxies ordnance survey requests from the front end to api.os.com
+ * Used for the VTS map source by forwarding on the request
+ * and adding the auth token and SRS (spatial reference system)
+ * @param {MapConfiguration} options - the map options
+ * @returns {ServerRoute<MapProxyGetRequestRefs>}
+ */
+function mapProxyRoute(options) {
+  return {
+    method: 'GET',
+    path: '/api/map-proxy',
+    handler: async (request, h) => {
+      const { query } = request
+      const targetUrl = new URL(decodeURIComponent(query.url))
+      const token = await getAccessToken(options)
+
+      targetUrl.searchParams.set('srs', '3857')
+
+      const proxyResponse = await httpRequest('get', targetUrl.toString(), {
+        headers: {
+          Authorization: `Bearer ${token}`
+        }
+      })
+      const buffer = proxyResponse.payload
+      const contentType = proxyResponse.res.headers['content-type']
+      const response = h.response(buffer)
+
+      if (contentType) {
+        response.type(contentType)
+      }
+
+      return response
+    },
+    options: {
+      validate: {
+        query: Joi.object()
+          .keys({
+            url: Joi.string().required()
+          })
+          .optional()
+      }
+    }
+  }
+}
+
+/**
+ * Proxies ordnance survey requests from the front end to api.os.uk
+ * Used for VTS map tiles forwarding on the request and adding the auth token
+ * @param {MapConfiguration} options - the map options
+ * @returns {ServerRoute<MapProxyGetRequestRefs>}
+ */
+function tileProxyRoute(options) {
+  return {
+    method: 'GET',
+    path: '/api/tile/{z}/{y}/{x}.pbf',
+    handler: async (request, h) => {
+      const { z, y, x } = request.params
+      const token = await getAccessToken(options)
+
+      const url = `https://api.os.uk/maps/vector/v1/vts/tile/${z}/${y}/${x}.pbf?srs=3857`
+
+      const { payload, res } = await get(url, {
+        headers: {
+          Authorization: `Bearer ${token}`,
+          Accept: 'application/x-protobuf'
+        },
+        json: false,
+        gunzip: true
+      })
+
+      if (res.statusCode && res.statusCode !== StatusCodes.OK.valueOf()) {
+        return h.response('Tile fetch failed').code(res.statusCode)
+      }
+
+      return h
+        .response(payload)
+        .type('application/x-protobuf')
+        .header('Cache-Control', 'public, max-age=86400')
+    }
+  }
+}
+
+/**
+ * Proxies ordnance survey geocode requests from the front end to api.os.uk
+ * Used for the gazzeteer address lookup to find name from query strings like postcode and place names
+ * @param {MapConfiguration} options - the map options
+ * @returns {ServerRoute<MapGeocodeGetRequestRefs>}
+ */
+function geocodeProxyRoute(options) {
+  return {
+    method: 'GET',
+    path: '/api/geocode-proxy',
+    async handler(request, _h) {
+      const { query } = request
+      const data = await find(query.query, options.ordnanceSurveyApiKey)
+
+      return data
+    },
+    options: {
+      validate: {
+        query: Joi.object()
+          .keys({
+            query: Joi.string().required()
+          })
+          .required()
+      }
+    }
+  }
+}
+
+/**
+ * Proxies ordnance survey reverse geocode requests from the front end to api.os.uk
+ * Used to find name from easting and northing points.
+ * N.B this endpoint is currently not used by the front end but will be soon in "maps V2"
+ * @param {MapConfiguration} options - the map options
+ * @returns {ServerRoute<MapReverseGeocodeGetRequestRefs>}
+ */
+function reverseGeocodeProxyRoute(options) {
+  return {
+    method: 'GET',
+    path: '/api/reverse-geocode-proxy',
+    async handler(request, _h) {
+      const { query } = request
+      const data = await nearest(
+        query.easting,
+        query.northing,
+        options.ordnanceSurveyApiKey
+      )
+
+      return data
+    },
+    options: {
+      validate: {
+        query: Joi.object()
+          .keys({
+            easting: Joi.number().required(),
+            northing: Joi.number().required()
+          })
+          .required()
+      }
+    }
+  }
+}
+
+/**
+ * Resource routes to return sprites and glyphs
+ * @returns {ServerRoute<MapProxyGetRequestRefs>}
+ */
+function mapStyleResourceRoutes() {
+  return {
+    method: 'GET',
+    path: '/api/maps/vts/{path*}',
+    options: {
+      handler: {
+        directory: {
+          path: resolve(import.meta.dirname, './vts')
+        }
+      }
+    }
+  }
+}
+
+/**
+ * @import { ServerRoute } from '@hapi/hapi'
+ * @import { MapConfiguration, MapProxyGetRequestRefs, MapGeocodeGetRequestRefs, MapReverseGeocodeGetRequestRefs } from '~/src/server/plugins/map/types.js'
+ */