@defra-fish/sales-api-service 1.64.0-rc.8 → 1.65.0-rc.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@defra-fish/sales-api-service",
-  "version": "1.64.0-rc.8",
+  "version": "1.65.0-rc.0",
   "description": "Rod Licensing Sales API",
   "type": "module",
   "engines": {
@@ -35,9 +35,9 @@
     "test": "echo \"Error: run tests from root\" && exit 1"
   },
   "dependencies": {
-    "@defra-fish/business-rules-lib": "1.64.0-rc.8",
-    "@defra-fish/connectors-lib": "1.64.0-rc.8",
-    "@defra-fish/dynamics-lib": "1.64.0-rc.8",
+    "@defra-fish/business-rules-lib": "1.65.0-rc.0",
+    "@defra-fish/connectors-lib": "1.65.0-rc.0",
+    "@defra-fish/dynamics-lib": "1.65.0-rc.0",
     "@hapi/boom": "9.1.2",
     "@hapi/hapi": "20.1.3",
     "@hapi/inert": "6.0.3",
@@ -52,5 +52,5 @@
     "moment-timezone": "0.5.34",
     "uuid": "8.3.2"
   },
-  "gitHead": "88a60cab95e119b46cec17336d784aec1aeabae8"
+  "gitHead": "cdf9253964871c4afe0ff85d085364ffe4e890cf"
 }

package/src/schema/authenticate.schema.js

@@ -20,10 +20,29 @@ export const authenticateRenewalRequestQuerySchema = Joi.object({
 }).label('authenticate-renewal-request-query')
 
 export const authenticateRenewalResponseSchema = Joi.object({
-  permission: {
+  permission: Joi.object({
     ...finalisedPermissionSchemaContent,
     licensee: contactResponseSchema,
     concessions: concessionProofSchema,
     permit: permitSchema
-  }
+  })
 }).label('authenticate-renewal-response')
+
+export const rcpAuthenticateRenewalResponseSchema = Joi.object({
+  permission: Joi.object({
+    ...finalisedPermissionSchemaContent,
+    licensee: contactResponseSchema,
+    concessions: concessionProofSchema,
+    permit: permitSchema
+  }),
+  recurringPayment: Joi.object({
+    id: Joi.string().uuid().required(),
+    agreementId: Joi.string().required(),
+    status: Joi.alternatives().try(Joi.number(), Joi.string()).required(),
+    nextDueDate: Joi.date().required(),
+    cancelledDate: Joi.date().allow(null),
+    cancelledReason: Joi.string().allow(null),
+    endDate: Joi.date().required(),
+    lastDigitsCardNumbers: Joi.string().required()
+  }).optional()
+}).label('rcp-authenticate-renewal-response')

package/src/server/routes/__tests__/authenticate-new.spec.js

@@ -1,31 +1,37 @@
-import { contactForLicenseeNoReference, executeQuery } from '@defra-fish/dynamics-lib'
-import db from 'debug'
-jest.mock('@defra-fish/dynamics-lib')
-jest.mock('debug')
+import '@defra-fish/dynamics-lib'
 
 describe('executeWithErrorLog', () => {
-  it('throws error', async () => {
-    const debug = jest.fn()
-    db.mockReturnValueOnce(debug)
-    executeQuery.mockImplementation(() => {
-      throw new Error()
+  it('logs the filter when executeQuery fails via the handler', async () => {
+    jest.resetModules()
+
+    const debugSpy = jest.fn()
+    jest.doMock('debug', () => jest.fn(() => debugSpy))
+
+    jest.doMock('@defra-fish/dynamics-lib', () => {
+      const actual = jest.requireActual('@defra-fish/dynamics-lib')
+      return {
+        ...actual,
+        executeQuery: jest.fn().mockRejectedValueOnce(new Error('boom')),
+        contactForLicenseeNoReference: jest.fn(() => ({ filter: 'query filter test' })),
+        permissionForContacts: jest.fn(() => [])
+      }
     })
-    contactForLicenseeNoReference.mockReturnValueOnce({ filter: 'query filter test' })
-    const authenticate = require('../authenticate.js').default
+
+    const authenticate = (await import('../authenticate.js')).default
     const [
       {
         options: { handler }
       }
     ] = authenticate
-    const mockRequest = {
+
+    const request = {
       query: { licenseeBirthDate: '', licenseePostcode: '' },
       params: { referenceNumber: '' }
     }
+    const h = { response: () => ({ code: () => {} }) }
 
-    try {
-      await handler(mockRequest)
-    } catch {}
+    await handler(request, h).catch(() => {})
 
-    expect(debug).toHaveBeenCalledWith('Error executing query with filter query filter test')
+    expect(debugSpy).toHaveBeenCalledWith('Error executing query with filter query filter test')
   })
 })

package/src/server/routes/__tests__/authenticate.spec.js

@@ -7,6 +7,14 @@ import {
   MOCK_CONCESSION_PROOF_ENTITY,
   MOCK_CONCESSION
 } from '../../../__mocks__/test-data.js'
+import authenticate from '../authenticate.js'
+import { findLinkedRecurringPayment } from '../../../services/recurring-payments.service.js'
+
+const [
+  {
+    options: { handler }
+  }
+] = authenticate
 
 jest.mock('@defra-fish/dynamics-lib', () => ({
   ...jest.requireActual('@defra-fish/dynamics-lib'),
@@ -15,6 +23,10 @@ jest.mock('@defra-fish/dynamics-lib', () => ({
   permissionForContacts: jest.fn()
 }))
 
+jest.mock('../../../services/recurring-payments.service.js', () => ({
+  findLinkedRecurringPayment: jest.fn()
+}))
+
 let server = null
 
 describe('authenticate handler', () => {
@@ -26,7 +38,13 @@ describe('authenticate handler', () => {
     await server.stop()
   })
 
+  beforeEach(() => {
+    jest.clearAllMocks()
+  })
+
   describe('authenticateRenewal', () => {
+    const baseUrl = '/authenticate/renewal/CD379B?licenseeBirthDate=2000-01-01&licenseePostcode=AB123CD'
+
     it('authenticates a renewal request', async () => {
       executeQuery.mockResolvedValueOnce([
         {
@@ -47,7 +65,7 @@ describe('authenticate handler', () => {
       executeQuery.mockResolvedValueOnce([{ entity: MOCK_CONCESSION_PROOF_ENTITY, expanded: { concession: { entity: MOCK_CONCESSION } } }])
       const result = await server.inject({
         method: 'GET',
-        url: '/authenticate/renewal/CD379B?licenseeBirthDate=2000-01-01&licenseePostcode=AB12 3CD'
+        url: baseUrl
       })
       expect(result.statusCode).toBe(200)
       expect(JSON.parse(result.payload)).toMatchObject({
@@ -88,7 +106,7 @@ describe('authenticate handler', () => {
       it('should call contactForLicenseeNoReference with dob and postcode for a renewal request', async () => {
         await server.inject({
           method: 'GET',
-          url: '/authenticate/renewal/CD379B?licenseeBirthDate=2000-01-01&licenseePostcode=AB12 3CD'
+          url: baseUrl
         })
         expect(contactForLicenseeNoReference).toHaveBeenCalledWith('2000-01-01', 'AB12 3CD')
       })
@@ -96,7 +114,7 @@ describe('authenticate handler', () => {
       it('should call permissionForContacts with contact ids from contactForLicenseeNoReference', async () => {
         await server.inject({
           method: 'GET',
-          url: '/authenticate/renewal/CD379B?licenseeBirthDate=2000-01-01&licenseePostcode=AB12 3CD'
+          url: baseUrl
         })
         expect(permissionForContacts).toHaveBeenCalledWith([MOCK_EXISTING_CONTACT_ENTITY.id])
       })
@@ -104,7 +122,7 @@ describe('authenticate handler', () => {
       it('returns 200 from a renewal request', async () => {
         const result = await server.inject({
           method: 'GET',
-          url: '/authenticate/renewal/CD379B?licenseeBirthDate=2000-01-01&licenseePostcode=AB12 3CD'
+          url: baseUrl
         })
         expect(result.statusCode).toBe(200)
       })
@@ -112,7 +130,7 @@ describe('authenticate handler', () => {
       it('returns permission from a renewal request', async () => {
         const result = await server.inject({
           method: 'GET',
-          url: '/authenticate/renewal/CD379B?licenseeBirthDate=2000-01-01&licenseePostcode=AB12 3CD'
+          url: baseUrl
         })
         expect(JSON.parse(result.payload)).toMatchObject({
           permission: expect.objectContaining({
@@ -135,7 +153,7 @@ describe('authenticate handler', () => {
       const consoleErrorSpy = jest.spyOn(console, 'error').mockImplementation(jest.fn())
       const result = await server.inject({
         method: 'GET',
-        url: '/authenticate/renewal/CD379B?licenseeBirthDate=2000-01-01&licenseePostcode=AB12 3CD'
+        url: baseUrl
       })
       expect(result.statusCode).toBe(500)
       expect(JSON.parse(result.payload)).toMatchObject({
@@ -144,6 +162,7 @@ describe('authenticate handler', () => {
         statusCode: 500
       })
       expect(consoleErrorSpy).toHaveBeenCalled()
+      consoleErrorSpy.mockRestore()
     })
 
     it('throws 401 errors if the renewal could not be authenticated', async () => {
@@ -156,7 +175,7 @@ describe('authenticate handler', () => {
       executeQuery.mockResolvedValueOnce([])
       const result = await server.inject({
         method: 'GET',
-        url: '/authenticate/renewal/CD379B?licenseeBirthDate=2000-01-01&licenseePostcode=AB12 3CD'
+        url: baseUrl
       })
       expect(result.statusCode).toBe(401)
       expect(JSON.parse(result.payload)).toMatchObject({
@@ -170,7 +189,7 @@ describe('authenticate handler', () => {
       executeQuery.mockResolvedValueOnce([])
       const result = await server.inject({
         method: 'GET',
-        url: '/authenticate/renewal/CD379B?licenseeBirthDate=2000-01-01&licenseePostcode=AB12 3CD'
+        url: baseUrl
       })
       expect(result.statusCode).toBe(401)
       expect(JSON.parse(result.payload)).toMatchObject({
@@ -190,4 +209,230 @@ describe('authenticate handler', () => {
       })
     })
   })
+
+  describe('authenticateRecurringPayment', () => {
+    const baseUrl = '/authenticate/rcp/CD379B?licenseeBirthDate=2000-01-01&licenseePostcode=AB12 3CD'
+
+    it('authenticates a recurring payment request and returns recurringPayment', async () => {
+      executeQuery
+        .mockResolvedValueOnce([{ entity: MOCK_EXISTING_CONTACT_ENTITY, expanded: {} }])
+        .mockResolvedValueOnce([
+          {
+            entity: MOCK_EXISTING_PERMISSION_ENTITY,
+            expanded: {
+              licensee: { entity: MOCK_EXISTING_CONTACT_ENTITY, expanded: {} },
+              concessionProofs: [{ entity: MOCK_CONCESSION_PROOF_ENTITY, expanded: { concession: { entity: MOCK_CONCESSION } } }],
+              permit: { entity: MOCK_1DAY_SENIOR_PERMIT_ENTITY, expanded: {} }
+            }
+          }
+        ])
+        .mockResolvedValueOnce([{ entity: MOCK_CONCESSION_PROOF_ENTITY, expanded: { concession: { entity: MOCK_CONCESSION } } }])
+
+      findLinkedRecurringPayment.mockResolvedValueOnce({
+        id: 'rcp-123',
+        status: 1
+      })
+
+      const result = await server.inject({ method: 'GET', url: baseUrl })
+      const body = JSON.parse(result.payload)
+
+      expect({
+        statusCode: result.statusCode,
+        body
+      }).toMatchObject({
+        statusCode: 200,
+        body: {
+          permission: expect.objectContaining({
+            ...MOCK_EXISTING_PERMISSION_ENTITY.toJSON(),
+            licensee: MOCK_EXISTING_CONTACT_ENTITY.toJSON(),
+            concessions: [
+              {
+                id: MOCK_CONCESSION.id,
+                proof: MOCK_CONCESSION_PROOF_ENTITY.toJSON()
+              }
+            ],
+            permit: MOCK_1DAY_SENIOR_PERMIT_ENTITY.toJSON()
+          }),
+          recurringPayment: expect.objectContaining({ id: 'rcp-123', status: 1 })
+        }
+      })
+    })
+
+    it('calls findLinkedRecurringPayment with permission id', async () => {
+      executeQuery.mockResolvedValueOnce([{ entity: MOCK_EXISTING_CONTACT_ENTITY, expanded: {} }]).mockResolvedValueOnce([
+        {
+          entity: MOCK_EXISTING_PERMISSION_ENTITY,
+          expanded: {
+            licensee: { entity: MOCK_EXISTING_CONTACT_ENTITY, expanded: {} },
+            concessionProofs: [],
+            permit: { entity: MOCK_1DAY_SENIOR_PERMIT_ENTITY, expanded: {} }
+          }
+        }
+      ])
+
+      findLinkedRecurringPayment.mockResolvedValueOnce({ id: 'rcp-123' })
+
+      await server.inject({ method: 'GET', url: baseUrl })
+
+      expect(findLinkedRecurringPayment).toHaveBeenCalledWith(MOCK_EXISTING_PERMISSION_ENTITY.id)
+    })
+
+    it('returns 401 when no contacts found', async () => {
+      executeQuery.mockResolvedValueOnce([])
+
+      const result = await server.inject({ method: 'GET', url: baseUrl })
+      const body = JSON.parse(result.payload)
+
+      expect({
+        statusCode: result.statusCode,
+        body
+      }).toMatchObject({
+        statusCode: 401,
+        body: {
+          error: 'Unauthorized',
+          message: 'The licensee could not be authenticated'
+        }
+      })
+    })
+
+    it('returns 401 when no permissions match', async () => {
+      executeQuery.mockResolvedValueOnce([{ entity: MOCK_EXISTING_CONTACT_ENTITY, expanded: {} }]).mockResolvedValueOnce([])
+
+      const result = await server.inject({ method: 'GET', url: baseUrl })
+      const body = JSON.parse(result.payload)
+
+      expect({
+        statusCode: result.statusCode,
+        body
+      }).toMatchObject({
+        statusCode: 401,
+        body: {
+          error: 'Unauthorized',
+          message: 'The licensee could not be authenticated'
+        }
+      })
+    })
+
+    it('returns 500 when multiple permissions match', async () => {
+      executeQuery.mockResolvedValueOnce([{ entity: MOCK_EXISTING_CONTACT_ENTITY, expanded: {} }]).mockResolvedValueOnce([
+        {
+          entity: { id: 'p1', referenceNumber: 'CD379B' },
+          expanded: { concessionProofs: [], licensee: { entity: {}, expanded: {} }, permit: { entity: {}, expanded: {} } }
+        },
+        {
+          entity: { id: 'p2', referenceNumber: 'CD379B' },
+          expanded: { concessionProofs: [], licensee: { entity: {}, expanded: {} }, permit: { entity: {}, expanded: {} } }
+        }
+      ])
+
+      const consoleErrorSpy = jest.spyOn(console, 'error').mockImplementation(jest.fn())
+
+      const result = await server.inject({ method: 'GET', url: baseUrl })
+      const body = JSON.parse(result.payload)
+
+      expect({
+        statusCode: result.statusCode,
+        body
+      }).toMatchObject({
+        statusCode: 500,
+        body: {
+          error: 'Internal Server Error',
+          message: 'Unable to authenticate, non-unique results for query'
+        }
+      })
+      expect(consoleErrorSpy).toHaveBeenCalled()
+      consoleErrorSpy.mockRestore()
+    })
+
+    it('returns 400 when query params are missing', async () => {
+      const result = await server.inject({ method: 'GET', url: '/authenticate/rcp/CD379B?' })
+      const body = JSON.parse(result.payload)
+
+      expect({
+        statusCode: result.statusCode,
+        body
+      }).toMatchObject({
+        statusCode: 400,
+        body: {
+          error: 'Bad Request',
+          message: 'Invalid query: "licenseeBirthDate" is required'
+        }
+      })
+    })
+
+    describe('if no concessions are returned', () => {
+      it('returns permission and recurringPayment without concessions', async () => {
+        executeQuery.mockResolvedValueOnce([{ entity: MOCK_EXISTING_CONTACT_ENTITY, expanded: {} }]).mockResolvedValueOnce([
+          {
+            entity: MOCK_EXISTING_PERMISSION_ENTITY,
+            expanded: {
+              licensee: { entity: MOCK_EXISTING_CONTACT_ENTITY, expanded: {} },
+              concessionProofs: [],
+              permit: { entity: MOCK_1DAY_SENIOR_PERMIT_ENTITY, expanded: {} }
+            }
+          }
+        ])
+
+        findLinkedRecurringPayment.mockResolvedValueOnce({
+          id: 'rcp-789',
+          status: 1
+        })
+
+        const result = await server.inject({ method: 'GET', url: baseUrl })
+        const body = JSON.parse(result.payload)
+
+        expect({
+          statusCode: result.statusCode,
+          body
+        }).toMatchObject({
+          statusCode: 200,
+          body: {
+            permission: expect.objectContaining({
+              ...MOCK_EXISTING_PERMISSION_ENTITY.toJSON(),
+              licensee: MOCK_EXISTING_CONTACT_ENTITY.toJSON(),
+              concessions: [],
+              permit: MOCK_1DAY_SENIOR_PERMIT_ENTITY.toJSON()
+            }),
+            recurringPayment: expect.objectContaining({ id: 'rcp-789', status: 1 })
+          }
+        })
+      })
+    })
+  })
+
+  it('changes reference number to uppercase', async () => {
+    const sampleQueryReferenceNumber = 'abc123'
+    const sampleResultReferenceNumber = sampleQueryReferenceNumber.toUpperCase()
+    const makeMockEntity = (obj = {}) => ({
+      ...obj,
+      toJSON: () => obj
+    })
+    executeQuery.mockReturnValueOnce([{ entity: { id: 'hgk-999' } }]).mockReturnValueOnce([
+      {
+        entity: makeMockEntity({
+          referenceNumber: sampleResultReferenceNumber
+        }),
+        expanded: {
+          concessionProofs: [],
+          licensee: { entity: makeMockEntity() },
+          permit: { entity: makeMockEntity() }
+        }
+      }
+    ])
+    const mockRequest = {
+      query: { licenseeBirthDate: '', licenseePostcode: '' },
+      params: { referenceNumber: sampleQueryReferenceNumber }
+    }
+    const mockResponseToolkit = { response: jest.fn(() => ({ code: () => {} })) }
+
+    await handler(mockRequest, mockResponseToolkit)
+
+    expect(mockResponseToolkit.response).toHaveBeenCalledWith(
+      expect.objectContaining({
+        permission: expect.objectContaining({
+          referenceNumber: sampleResultReferenceNumber
+        })
+      })
+    )
+  })
 })

package/src/server/routes/authenticate.js

@@ -2,12 +2,16 @@ import Boom from '@hapi/boom'
 import {
   authenticateRenewalRequestParamsSchema,
   authenticateRenewalRequestQuerySchema,
-  authenticateRenewalResponseSchema
+  authenticateRenewalResponseSchema,
+  rcpAuthenticateRenewalResponseSchema
 } from '../../schema/authenticate.schema.js'
 import db from 'debug'
 import { permissionForContacts, concessionsByIds, executeQuery, contactForLicenseeNoReference } from '@defra-fish/dynamics-lib'
+import { findLinkedRecurringPayment } from '../../services/recurring-payments.service.js'
+
 const debug = db('sales:renewal-authentication')
 const failAuthenticate = 'The licensee could not be authenticated'
+const HTTP_OK = 200
 
 const executeWithErrorLog = async query => {
   try {
@@ -18,45 +22,51 @@ const executeWithErrorLog = async query => {
   }
 }
 
+const getAuthenticatedPermission = async request => {
+  const { licenseeBirthDate, licenseePostcode } = request.query
+  const contacts = await executeWithErrorLog(contactForLicenseeNoReference(licenseeBirthDate, licenseePostcode))
+
+  if (!contacts.length) {
+    throw Boom.unauthorized(failAuthenticate)
+  }
+
+  const contactIds = contacts.map(contact => contact.entity.id)
+  const permissions = await executeWithErrorLog(permissionForContacts(contactIds))
+  const results = permissions.filter(p => p.entity.referenceNumber.endsWith(request.params.referenceNumber.toUpperCase()))
+
+  if (results.length === 0) {
+    throw Boom.unauthorized(failAuthenticate)
+  }
+
+  if (results.length > 1) {
+    throw new Error('Unable to authenticate, non-unique results for query')
+  }
+
+  const [permission] = results
+  const concessionIds = permission.expanded.concessionProofs.map(f => f.entity.id)
+  const concessionProofs = permission.expanded.concessionProofs.length ? await executeWithErrorLog(concessionsByIds(concessionIds)) : []
+
+  return {
+    permission: {
+      ...permission.entity.toJSON(),
+      licensee: permission.expanded.licensee.entity.toJSON(),
+      concessions: concessionProofs.map(c => ({
+        id: c.expanded.concession.entity.id,
+        proof: c.entity.toJSON()
+      })),
+      permit: permission.expanded.permit.entity.toJSON()
+    }
+  }
+}
+
 export default [
   {
     method: 'GET',
     path: '/authenticate/renewal/{referenceNumber}',
     options: {
       handler: async (request, h) => {
-        const { licenseeBirthDate, licenseePostcode } = request.query
-        const contacts = await executeWithErrorLog(contactForLicenseeNoReference(licenseeBirthDate, licenseePostcode))
-        if (contacts.length > 0) {
-          const contactIds = contacts.map(contact => contact.entity.id)
-          const permissions = await executeWithErrorLog(permissionForContacts(contactIds))
-          const results = permissions.filter(p => p.entity.referenceNumber.endsWith(request.params.referenceNumber))
-          if (results.length === 1) {
-            let concessionProofs = []
-            if (results[0].expanded.concessionProofs.length > 0) {
-              const ids = results[0].expanded.concessionProofs.map(f => f.entity.id)
-              concessionProofs = await executeWithErrorLog(concessionsByIds(ids))
-            }
-            return h
-              .response({
-                permission: {
-                  ...results[0].entity.toJSON(),
-                  licensee: results[0].expanded.licensee.entity.toJSON(),
-                  concessions: concessionProofs.map(c => ({
-                    id: c.expanded.concession.entity.id,
-                    proof: c.entity.toJSON()
-                  })),
-                  permit: results[0].expanded.permit.entity.toJSON()
-                }
-              })
-              .code(200)
-          } else if (results.length === 0) {
-            throw Boom.unauthorized(failAuthenticate)
-          } else {
-            throw new Error('Unable to authenticate, non-unique results for query')
-          }
-        } else {
-          throw Boom.unauthorized(failAuthenticate)
-        }
+        const permissionData = await getAuthenticatedPermission(request)
+        return h.response(permissionData).code(HTTP_OK)
       },
       description: 'Authenticate a licensee by checking the licence number corresponds with the provided contact details',
       notes: `
@@ -77,5 +87,40 @@ export default [
         }
       }
     }
+  },
+  {
+    method: 'GET',
+    path: '/authenticate/rcp/{referenceNumber}',
+    options: {
+      handler: async (request, h) => {
+        const { permission } = await getAuthenticatedPermission(request)
+        const recurringPayment = await findLinkedRecurringPayment(permission.id)
+        return h.response({ permission, recurringPayment }).code(HTTP_OK)
+      },
+      description:
+        'Authenticate a licensee by checking the licence number corresponds with the provided contact details. Checking agreement id exists and recurring payment is active and not cancelled',
+      notes: `
+        Authenticate a licensee by checking the licence number corresponds with the provided contact details. Checking agreement id exists and recurring payment is active and not cancelled
+      `,
+      tags: ['api', 'authenticate'],
+      validate: {
+        params: authenticateRenewalRequestParamsSchema,
+        query: authenticateRenewalRequestQuerySchema
+      },
+      plugins: {
+        'hapi-swagger': {
+          responses: {
+            200: {
+              description: 'The licensee was successfully authenticated',
+              schema: rcpAuthenticateRenewalResponseSchema
+            },
+            401: { description: failAuthenticate }
+          },
+          order: 2
+        }
+      }
+    }
   }
 ]
+
+export const errorLogTest = { executeWithErrorLog }

package/src/services/__tests__/recurring-payments.service.spec.js

@@ -6,7 +6,9 @@ import {
   findById,
   Permission,
   persist,
-  RecurringPayment
+  RecurringPayment,
+  findRecurringPaymentByPermissionId,
+  retrieveGlobalOptionSets
 } from '@defra-fish/dynamics-lib'
 import {
   getRecurringPayments,
@@ -15,7 +17,8 @@ import {
   processRPResult,
   findNewestExistingRecurringPaymentInCrm,
   getRecurringPaymentAgreement,
-  cancelRecurringPayment
+  cancelRecurringPayment,
+  findLinkedRecurringPayment
 } from '../recurring-payments.service.js'
 import { calculateEndDate, generatePermissionNumber } from '../permissions.service.js'
 import { getObfuscatedDob } from '../contacts.service.js'
@@ -50,7 +53,9 @@ jest.mock('@defra-fish/dynamics-lib', () => ({
   dynamicsClient: {
     retrieveMultipleRequest: jest.fn(() => ({ value: [] }))
   },
-  persist: jest.fn()
+  persist: jest.fn(),
+  findRecurringPaymentByPermissionId: jest.fn(() => ({ toRetrieveRequest: () => {} })),
+  retrieveGlobalOptionSets: jest.fn()
 }))
 
 jest.mock('@defra-fish/connectors-lib', () => ({
@@ -720,8 +725,8 @@ describe('recurring payments service', () => {
         status: expect.objectContaining({ id: TRANSACTION_STATUS.FINALISED }),
         payment: expect.objectContaining({
           amount: mockTransaction.cost,
-          method: TRANSACTION_SOURCE.govPay,
-          source: PAYMENT_TYPE.debit,
+          source: TRANSACTION_SOURCE.govPay,
+          method: PAYMENT_TYPE.debit,
           timestamp: fakeNow
         })
       })
@@ -776,8 +781,8 @@ describe('recurring payments service', () => {
     it('returns a Recurring Payment (not a plain object)', async () => {
       jest.spyOn(RecurringPayment, 'fromResponse')
       dynamicsClient.retrieveMultipleRequest.mockReturnValueOnce(getMockResponse())
-      const rcp = await findNewestExistingRecurringPaymentInCrm()
-      expect(RecurringPayment.fromResponse.mock.results[0].value).toBe(rcp)
+      const recurringPayment = await findNewestExistingRecurringPaymentInCrm()
+      expect(RecurringPayment.fromResponse.mock.results[0].value).toBe(recurringPayment)
     })
 
     it.each([
@@ -811,14 +816,14 @@ describe('recurring payments service', () => {
       ]
     ])('returns most recent existing recurring payment from %s', async (_desc, mockResponseData, expectedId) => {
       dynamicsClient.retrieveMultipleRequest.mockReturnValueOnce({ value: mockResponseData })
-      const rcp = await findNewestExistingRecurringPaymentInCrm()
-      expect(rcp.id).toBe(expectedId)
+      const recurringPayment = await findNewestExistingRecurringPaymentInCrm()
+      expect(recurringPayment.id).toBe(expectedId)
     })
 
     it('returns boolean false if no recurring payments found', async () => {
       dynamicsClient.retrieveMultipleRequest.mockReturnValueOnce({ value: [] })
-      const rcp = await findNewestExistingRecurringPaymentInCrm()
-      expect(rcp).toBeFalsy()
+      const recurringPayment = await findNewestExistingRecurringPaymentInCrm()
+      expect(recurringPayment).toBeFalsy()
     })
   })
 
@@ -882,6 +887,7 @@ describe('recurring payments service', () => {
 
   describe('cancelRecurringPayment', () => {
     it('should call findById with RecurringPayment and the provided id', async () => {
+      retrieveGlobalOptionSets.mockReturnValueOnce({ cached: jest.fn().mockResolvedValue({ definition: 'mock-def' }) })
       findById.mockReturnValueOnce(getMockRecurringPayment())
       const id = 'abc123'
       await cancelRecurringPayment(id)
@@ -889,6 +895,20 @@ describe('recurring payments service', () => {
     })
 
     it('should call persist with the updated RecurringPayment', async () => {
+      retrieveGlobalOptionSets.mockReturnValueOnce({
+        cached: jest.fn().mockResolvedValue({
+          defra_cancelledreasons: {
+            options: {
+              910400002: {
+                id: 910400002,
+                label: 'Payment Failure',
+                description: 'Payment Failure'
+              }
+            }
+          }
+        })
+      })
+
       const recurringPayment = getMockRecurringPayment()
       findById.mockReturnValueOnce(recurringPayment)
 
@@ -907,4 +927,71 @@ describe('recurring payments service', () => {
       await expect(cancelRecurringPayment('id')).rejects.toThrow('Invalid id provided for recurring payment cancellation')
     })
   })
+
+  describe('findLinkedRecurringPayment', () => {
+    const arrangeLinkedRcpSuccess = mockResponse => {
+      jest.spyOn(RecurringPayment, 'fromResponse')
+      dynamicsClient.retrieveMultipleRequest.mockReturnValueOnce(mockResponse)
+      retrieveGlobalOptionSets.mockReturnValueOnce({
+        cached: jest.fn().mockResolvedValue({ definition: 'mock-def' })
+      })
+    }
+
+    it('passes permission id to findRecurringPaymentByPermissionId', async () => {
+      const permissionId = Symbol('permission-id')
+      await findLinkedRecurringPayment(permissionId)
+      expect(findRecurringPaymentByPermissionId).toHaveBeenCalledWith(permissionId)
+    })
+
+    it('passes query created by findRecurringPaymentByPermissionId to retrieveMultipleRequest', async () => {
+      const retrieveRequest = Symbol('retrieve request')
+      findRecurringPaymentByPermissionId.mockReturnValueOnce({ toRetrieveRequest: () => retrieveRequest })
+      await findLinkedRecurringPayment()
+      expect(dynamicsClient.retrieveMultipleRequest).toHaveBeenCalledWith(retrieveRequest)
+    })
+
+    it('calls RecurringPayment.fromResponse with response and definitions', async () => {
+      arrangeLinkedRcpSuccess(getMockResponse())
+      await findLinkedRecurringPayment('abc123')
+      expect(RecurringPayment.fromResponse).toHaveBeenCalledWith(expect.any(Object), expect.anything())
+    })
+
+    it('returns the RecurringPayment produced by fromResponse', async () => {
+      arrangeLinkedRcpSuccess(getMockResponse())
+      const recurringPayment = await findLinkedRecurringPayment('abc123')
+      expect(RecurringPayment.fromResponse.mock.results[0].value).toBe(recurringPayment)
+    })
+
+    it.each([
+      [
+        'two with last most recent',
+        [
+          { defra_recurringpaymentid: 'rcp-123', defra_enddate: '2024-01-01T00:00:00Z' },
+          { defra_recurringpaymentid: 'rcp-234', defra_enddate: '2025-01-01T00:00:00Z' }
+        ],
+        'rcp-234'
+      ],
+      [
+        'three with middle most recent',
+        [
+          { defra_recurringpaymentid: 'rcp-345', defra_enddate: '2023-01-01T00:00:00Z' },
+          { defra_recurringpaymentid: 'rcp-456', defra_enddate: '2026-01-01T00:00:00Z' },
+          { defra_recurringpaymentid: 'rcp-567', defra_enddate: '2025-01-01T00:00:00Z' }
+        ],
+        'rcp-456'
+      ]
+    ])('returns the most recent linked recurring payment (%s)', async (_desc, mockData, expectedId) => {
+      dynamicsClient.retrieveMultipleRequest.mockReturnValueOnce({ value: mockData })
+      retrieveGlobalOptionSets.mockReturnValueOnce({ cached: jest.fn().mockResolvedValue({ def: 'mock' }) })
+
+      const recurringPayment = await findLinkedRecurringPayment('abc123')
+      expect(recurringPayment.id).toBe(expectedId)
+    })
+
+    it('returns false if no linked recurring payments found', async () => {
+      dynamicsClient.retrieveMultipleRequest.mockReturnValueOnce({ value: [] })
+      const recurringPayment = await findLinkedRecurringPayment('abc123')
+      expect(recurringPayment).toBeFalsy()
+    })
+  })
 })

package/src/services/recurring-payments.service.js

@@ -5,7 +5,9 @@ import {
   findDueRecurringPayments,
   findRecurringPaymentsByAgreementId,
   persist,
-  RecurringPayment
+  RecurringPayment,
+  findRecurringPaymentByPermissionId,
+  retrieveGlobalOptionSets
 } from '@defra-fish/dynamics-lib'
 import { calculateEndDate, generatePermissionNumber } from './permissions.service.js'
 import { getObfuscatedDob } from './contacts.service.js'
@@ -136,8 +138,8 @@ export const processRPResult = async (transactionId, paymentId, createdDate) =>
       status: { id: TRANSACTION_STATUS.FINALISED },
       payment: {
         amount: transactionRecord.cost,
-        method: TRANSACTION_SOURCE.govPay,
-        source: PAYMENT_TYPE.debit,
+        method: PAYMENT_TYPE.debit,
+        source: TRANSACTION_SOURCE.govPay,
         timestamp: new Date().toISOString()
       }
     }),
@@ -182,3 +184,14 @@ const determineRecurringPaymentName = (transactionRecord, contact) => {
   const [dueYear] = transactionRecord.payment.recurring.nextDueDate.split('-')
   return [contact.firstName, contact.lastName, dueYear].join(' ')
 }
+
+export const findLinkedRecurringPayment = async permissionId => {
+  const query = findRecurringPaymentByPermissionId(permissionId)
+  const response = await dynamicsClient.retrieveMultipleRequest(query.toRetrieveRequest())
+  if (response.value.length) {
+    const [rcpResponseData] = response.value.sort((a, b) => Date.parse(b.defra_enddate) - Date.parse(a.defra_enddate))
+    const definition = await retrieveGlobalOptionSets().cached()
+    return RecurringPayment.fromResponse(rcpResponseData, definition)
+  }
+  return false
+}