@defra/forms-engine-plugin 4.0.42 → 4.0.44

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

@@ -1,9 +1,14 @@
 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 { request as httpRequest } from '~/src/server/services/httpService.js'
+import {
+  get,
+  request as httpRequest
+} from '~/src/server/services/httpService.js'
 
 /**
  * Gets the map support routes
@@ -11,17 +16,18 @@ import { request as httpRequest } from '~/src/server/services/httpService.js'
  */
 export function getRoutes(options) {
   return [
+    mapStyleResourceRoutes(),
     mapProxyRoute(options),
+    tileProxyRoute(options),
     geocodeProxyRoute(options),
-    reverseGeocodeProxyRoute(options),
-    ...tileRoutes()
+    reverseGeocodeProxyRoute(options)
   ]
 }
 
 /**
  * Proxies ordnance survey requests from the front end to api.os.com
- * Used for VTS map tiles, sprites and fonts by forwarding on the request
- * and adding the apikey and optionally an SRS (spatial reference system)
+ * 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>}
  */
@@ -32,14 +38,15 @@ function mapProxyRoute(options) {
     handler: async (request, h) => {
       const { query } = request
       const targetUrl = new URL(decodeURIComponent(query.url))
+      const token = await getAccessToken(options)
 
-      // Add API key server-side and set SRS
-      targetUrl.searchParams.set('key', options.ordnanceSurveyApiKey)
-      if (!targetUrl.searchParams.has('srs')) {
-        targetUrl.searchParams.set('srs', '3857')
-      }
+      targetUrl.searchParams.set('srs', '3857')
 
-      const proxyResponse = await httpRequest('get', targetUrl.toString())
+      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)
@@ -63,7 +70,44 @@ function mapProxyRoute(options) {
 }
 
 /**
- * Proxies ordnance survey geocode requests from the front end to api.os.com
+ * 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>}
@@ -91,7 +135,7 @@ function geocodeProxyRoute(options) {
 }
 
 /**
- * Proxies ordnance survey reverse geocode requests from the front end to api.os.com
+ * 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
@@ -124,20 +168,22 @@ function reverseGeocodeProxyRoute(options) {
   }
 }
 
-function tileRoutes() {
-  return [
-    {
-      method: 'GET',
-      path: '/api/maps/vts/{path*}',
-      options: {
-        handler: {
-          directory: {
-            path: resolve(import.meta.dirname, './vts')
-          }
+/**
+ * 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')
         }
       }
     }
-  ]
+  }
 }
 
 /**

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

@@ -1,6 +1,7 @@
 /**
  * @typedef {{
  *   ordnanceSurveyApiKey: string
+ *   ordnanceSurveyApiSecret: string
  * }} MapConfiguration
  */
 

package/src/server/plugins/payment/helper.js

@@ -0,0 +1,56 @@
+import { format } from 'date-fns'
+
+import { PaymentService } from '~/src/server/plugins/payment/service.js'
+
+export const DEFAULT_PAYMENT_HELP_URL =
+  'https://www.gov.uk/government/organisations/department-for-environment-food-rural-affairs'
+
+/**
+ * Determine which payment API key value to use.
+ * If a draft preview form or a live preview form, read the TEST API key value specific to that form.
+ * If a live (non-preview) form, read the LIVE API key value specific to that form.
+ * @param {boolean} isLivePayment - true if this is a live payment (as opposed to a test one)
+ * @param {string} formId - id of the form
+ * @returns {string}
+ */
+export function getPaymentApiKey(isLivePayment, formId) {
+  const apiKeyValue = isLivePayment
+    ? process.env[`PAYMENT_PROVIDER_API_KEY_LIVE_${formId}`]
+    : process.env[`PAYMENT_PROVIDER_API_KEY_TEST_${formId}`]
+
+  if (!apiKeyValue) {
+    throw new Error(
+      `Missing payment api key for ${isLivePayment ? 'live' : 'test'} form id ${formId}`
+    )
+  }
+  return apiKeyValue
+}
+
+/**
+ * Creates a PaymentService instance with the appropriate API key
+ * @param {boolean} isLivePayment - true if this is a live payment
+ * @param {string} formId - id of the form
+ * @returns {PaymentService}
+ */
+export function createPaymentService(isLivePayment, formId) {
+  const apiKey = getPaymentApiKey(isLivePayment, formId)
+  return new PaymentService(apiKey)
+}
+
+/**
+ * Formats a payment date for display
+ * @param {string} isoString - ISO date string
+ * @returns {string} Formatted date string (e.g., "26 January 2026 5:01pm")
+ */
+export function formatPaymentDate(isoString) {
+  return format(new Date(isoString), 'd MMMM yyyy h:mmaaa')
+}
+
+/**
+ * Formats a payment amount with two decimal places
+ * @param {number} amount - amount in pounds
+ * @returns {string} Formatted amount (e.g., "£10.00")
+ */
+export function formatPaymentAmount(amount) {
+  return `£${amount.toFixed(2)}`
+}

package/src/server/plugins/payment/helper.test.js

@@ -0,0 +1,52 @@
+import { config } from '~/src/config/index.js'
+import {
+  formatPaymentAmount,
+  formatPaymentDate,
+  getPaymentApiKey
+} from '~/src/server/plugins/payment/helper.js'
+
+describe('getPaymentApiKey', () => {
+  config.set('paymentProviderApiKeyTest', 'TEST-API-KEY')
+  const formId = 'form-id'
+  process.env['PAYMENT_PROVIDER_API_KEY_LIVE_form-id'] = 'LIVE-API-KEY'
+  process.env['PAYMENT_PROVIDER_API_KEY_TEST_form-id'] = 'TEST-API-KEY'
+
+  it('should read test key when non-live form', () => {
+    const apiKey = getPaymentApiKey(false, formId)
+    expect(apiKey).toBe('TEST-API-KEY')
+  })
+
+  it('should read live key when live form', () => {
+    const apiKey = getPaymentApiKey(true, formId)
+    expect(apiKey).toBe('LIVE-API-KEY')
+  })
+
+  it('should throw if TEST key is missing', () => {
+    expect(() => getPaymentApiKey(false, 'form-id-missing')).toThrow(
+      'Missing payment api key for test form id form-id-missing'
+    )
+  })
+
+  it('should throw if LIVE key is missing', () => {
+    expect(() => getPaymentApiKey(true, 'form-id-missing')).toThrow(
+      'Missing payment api key for live form id form-id-missing'
+    )
+  })
+})
+
+describe('formatPaymentDate', () => {
+  it('should format ISO date string to en-GB format', () => {
+    const result = formatPaymentDate('2025-11-10T17:01:29.000Z')
+    expect(result).toBe('10 November 2025 5:01pm')
+  })
+})
+
+describe('formatPaymentAmount', () => {
+  it('should format whole number with two decimal places', () => {
+    expect(formatPaymentAmount(10)).toBe('£10.00')
+  })
+
+  it('should format decimal amount', () => {
+    expect(formatPaymentAmount(99.5)).toBe('£99.50')
+  })
+})

package/src/server/plugins/payment/service.js

@@ -0,0 +1,171 @@
+import { StatusCodes } from 'http-status-codes'
+
+import { createLogger } from '~/src/server/common/helpers/logging/logger.js'
+import { get, post, postJson } from '~/src/server/services/httpService.js'
+
+const PAYMENT_BASE_URL = 'https://publicapi.payments.service.gov.uk'
+const PAYMENT_ENDPOINT = '/v1/payments'
+
+const logger = createLogger()
+
+/**
+ * @param {string} apiKey
+ * @returns {{ Authorization: string }}
+ */
+function getAuthHeaders(apiKey) {
+  return {
+    Authorization: `Bearer ${apiKey}`
+  }
+}
+
+export class PaymentService {
+  /** @type {string} */
+  #apiKey
+
+  /**
+   * @param {string} apiKey - API key to use (global config for test value, per-form config for live value)
+   */
+  constructor(apiKey) {
+    this.#apiKey = apiKey
+  }
+
+  /**
+   * Creates a payment with delayed capture (pre-authorisation)
+   * @param {number} amount - in pence
+   * @param {string} description
+   * @param {string} returnUrl
+   * @param {string} reference
+   * @param {{ formId: string, slug: string }} metadata
+   */
+  async createPayment(amount, description, returnUrl, reference, metadata) {
+    const response = await this.postToPayProvider({
+      amount,
+      description,
+      reference,
+      metadata,
+      return_url: returnUrl,
+      delayed_capture: true
+    })
+
+    return {
+      paymentId: response.payment_id,
+      paymentUrl: response._links.next_url.href
+    }
+  }
+
+  /**
+   * @param {string} paymentId
+   * @returns {Promise<GetPaymentResponse>}
+   */
+  async getPaymentStatus(paymentId) {
+    const getByType = /** @type {typeof get<GetPaymentApiResponse>} */ (get)
+
+    try {
+      const response = await getByType(
+        `${PAYMENT_BASE_URL}${PAYMENT_ENDPOINT}/${paymentId}`,
+        {
+          headers: getAuthHeaders(this.#apiKey),
+          json: true
+        }
+      )
+
+      if (response.error) {
+        const errorMessage =
+          response.error instanceof Error
+            ? response.error.message
+            : JSON.stringify(response.error)
+        throw new Error(`Failed to get payment status: ${errorMessage}`)
+      }
+
+      return {
+        state: response.payload.state,
+        _links: response.payload._links,
+        email: response.payload.email,
+        paymentId: response.payload.payment_id,
+        amount: response.payload.amount
+      }
+    } catch (err) {
+      const error = /** @type {Error} */ (err)
+      logger.error(
+        error,
+        `[payment] Error getting payment status for paymentId=${paymentId}: ${error.message}`
+      )
+      throw err
+    }
+  }
+
+  /**
+   * Captures a payment that is in 'capturable' status
+   * @param {string} paymentId
+   * @returns {Promise<boolean>}
+   */
+  async capturePayment(paymentId) {
+    try {
+      const response = await post(
+        `${PAYMENT_BASE_URL}${PAYMENT_ENDPOINT}/${paymentId}/capture`,
+        {
+          headers: getAuthHeaders(this.#apiKey)
+        }
+      )
+
+      const statusCode = response.res.statusCode
+
+      if (
+        statusCode === StatusCodes.OK ||
+        statusCode === StatusCodes.NO_CONTENT
+      ) {
+        logger.info(`[payment] Successfully captured payment ${paymentId}`)
+        return true
+      }
+
+      logger.error(
+        `[payment] Capture failed for paymentId=${paymentId}: HTTP ${statusCode}`
+      )
+      return false
+    } catch (err) {
+      const error = /** @type {Error} */ (err)
+      logger.error(
+        error,
+        `[payment] Error capturing payment for paymentId=${paymentId}: ${error.message}`
+      )
+      throw err
+    }
+  }
+
+  /**
+   * @param {CreatePaymentRequest} payload
+   */
+  async postToPayProvider(payload) {
+    const postJsonByType =
+      /** @type {typeof postJson<CreatePaymentResponse>} */ (postJson)
+
+    try {
+      const response = await postJsonByType(
+        `${PAYMENT_BASE_URL}${PAYMENT_ENDPOINT}`,
+        {
+          payload,
+          headers: getAuthHeaders(this.#apiKey)
+        }
+      )
+
+      if (response.payload?.state.status !== 'created') {
+        throw new Error(
+          `Failed to create payment for reference=${payload.reference}`
+        )
+      }
+
+      return response.payload
+    } catch (err) {
+      const error = /** @type {Error} */ (err)
+      logger.error(
+        error,
+        `[payment] Error creating payment for reference=${payload.reference}: ${error.message}`
+      )
+      throw err
+    }
+  }
+}
+
+/**
+ * @import { CreatePaymentRequest, CreatePaymentResponse, GetPaymentApiResponse, GetPaymentResponse } from '~/src/server/plugins/payment/types.js'
+ */

package/src/server/plugins/payment/service.test.js

@@ -0,0 +1,205 @@
+import { PaymentService } from '~/src/server/plugins/payment/service.js'
+import { get, post, postJson } from '~/src/server/services/httpService.js'
+
+jest.mock('~/src/server/services/httpService.ts')
+
+describe('payment service', () => {
+  const service = new PaymentService('my-api-key')
+  describe('constructor', () => {
+    it('should create instance', () => {
+      expect(service).toBeDefined()
+    })
+  })
+
+  describe('createPayment', () => {
+    it('should create a payment', async () => {
+      const createPaymentResult = {
+        payment_id: 'payment-id-12345',
+        _links: {
+          next_url: {
+            href: 'http://next-url-href/payment'
+          }
+        },
+        state: {
+          status: 'created'
+        }
+      }
+      jest.mocked(postJson).mockResolvedValueOnce({
+        res: /** @type {IncomingMessage} */ ({
+          statusCode: 200,
+          headers: {}
+        }),
+        payload: createPaymentResult,
+        error: undefined
+      })
+
+      const referenceNumber = 'ABC-DEF-123'
+      const returnUrl = 'http://localhost:3009/payment-callback-handler'
+      const metadata = { formId: 'form-id', slug: 'my-form-slug' }
+      const payment = await service.createPayment(
+        100,
+        'Payment description',
+        returnUrl,
+        referenceNumber,
+        metadata
+      )
+      expect(payment.paymentId).toBe('payment-id-12345')
+      expect(payment.paymentUrl).toBe('http://next-url-href/payment')
+    })
+
+    it('should throw if fails to create a payment - failed API call', async () => {
+      jest
+        .mocked(postJson)
+        .mockRejectedValueOnce(new Error('internal creation error'))
+
+      const referenceNumber = 'ABC-DEF-123'
+      const returnUrl = 'http://localhost:3009/payment-callback-handler'
+      const metadata = { formId: 'form-id', slug: 'my-form-slug' }
+      await expect(() =>
+        service.createPayment(
+          100,
+          'Payment description',
+          returnUrl,
+          referenceNumber,
+          metadata
+        )
+      ).rejects.toThrow('internal creation error')
+    })
+
+    it('should throw if fails to create a payment - bad result from API call', async () => {
+      const createPaymentResult = {
+        state: {
+          status: 'failed'
+        }
+      }
+      jest.mocked(postJson).mockResolvedValueOnce({
+        res: /** @type {IncomingMessage} */ ({
+          statusCode: 200,
+          headers: {}
+        }),
+        payload: createPaymentResult,
+        error: undefined
+      })
+
+      const referenceNumber = 'ABC-DEF-123'
+      const returnUrl = 'http://localhost:3009/payment-callback-handler'
+      const metadata = { formId: 'form-id', slug: 'my-form-slug' }
+      await expect(() =>
+        service.createPayment(
+          100,
+          'Payment description',
+          returnUrl,
+          referenceNumber,
+          metadata
+        )
+      ).rejects.toThrow('Failed to create payment')
+    })
+  })
+
+  describe('getPaymentStatus', () => {
+    it('should get payment status if exists', async () => {
+      const getPaymentStatusResult = {
+        payment_id: 'payment-id-12345',
+        _links: {
+          next_url: {
+            href: 'http://next-url-href/payment'
+          }
+        },
+        state: {
+          status: 'created'
+        }
+      }
+
+      jest.mocked(get).mockResolvedValueOnce({
+        res: /** @type {IncomingMessage} */ ({
+          statusCode: 200,
+          headers: {}
+        }),
+        payload: getPaymentStatusResult,
+        error: undefined
+      })
+
+      const paymentStatus = await service.getPaymentStatus('payment-id-12345')
+      expect(paymentStatus.paymentId).toBe('payment-id-12345')
+      expect(paymentStatus._links.next_url?.href).toBe(
+        'http://next-url-href/payment'
+      )
+    })
+
+    it('should handle payment status error', async () => {
+      jest.mocked(get).mockResolvedValueOnce({
+        res: /** @type {IncomingMessage} */ ({
+          statusCode: 200,
+          headers: {}
+        }),
+        payload: undefined,
+        error: new Error('some-error')
+      })
+
+      await expect(() =>
+        service.getPaymentStatus('payment-id-12345')
+      ).rejects.toThrow('Failed to get payment status: some-error')
+    })
+  })
+
+  describe('capturePayment', () => {
+    it('should return true when successful capture with statusCode 200', async () => {
+      const capturePaymentResult = {}
+      jest.mocked(post).mockResolvedValueOnce({
+        res: /** @type {IncomingMessage} */ ({
+          statusCode: 200,
+          headers: {}
+        }),
+        payload: capturePaymentResult,
+        error: undefined
+      })
+
+      const captureResult = await service.capturePayment('payment-id-12345')
+      expect(captureResult).toBe(true)
+    })
+
+    it('should return true when successful capture with statusCode 204', async () => {
+      const capturePaymentResult = {}
+      jest.mocked(post).mockResolvedValueOnce({
+        res: /** @type {IncomingMessage} */ ({
+          statusCode: 204,
+          headers: {}
+        }),
+        payload: capturePaymentResult,
+        error: undefined
+      })
+
+      const captureResult = await service.capturePayment('payment-id-12345')
+      expect(captureResult).toBe(true)
+    })
+
+    it('should return false when status code not 200 or 204', async () => {
+      const capturePaymentResult = {}
+      jest.mocked(post).mockResolvedValueOnce({
+        res: /** @type {IncomingMessage} */ ({
+          statusCode: 500,
+          headers: {}
+        }),
+        payload: capturePaymentResult,
+        error: undefined
+      })
+
+      const captureResult = await service.capturePayment('payment-id-12345')
+      expect(captureResult).toBe(false)
+    })
+
+    it('should throw when internal error', async () => {
+      jest
+        .mocked(post)
+        .mockRejectedValueOnce(new Error('internal capture error'))
+
+      await expect(() =>
+        service.capturePayment('payment-id-12345')
+      ).rejects.toThrow('internal capture error')
+    })
+  })
+})
+
+/**
+ * @import  { IncomingMessage } from 'node:http'
+ */