@defra-fish/sales-api-service 1.75.0-rc.2 → 1.75.0-rc.3

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@defra-fish/sales-api-service",
-  "version": "1.75.0-rc.2",
+  "version": "1.75.0-rc.3",
   "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.75.0-rc.2",
-    "@defra-fish/connectors-lib": "1.75.0-rc.2",
-    "@defra-fish/dynamics-lib": "1.75.0-rc.2",
+    "@defra-fish/business-rules-lib": "1.75.0-rc.3",
+    "@defra-fish/connectors-lib": "1.75.0-rc.3",
+    "@defra-fish/dynamics-lib": "1.75.0-rc.3",
     "@hapi/boom": "9.1.2",
     "@hapi/hapi": "20.1.3",
     "@hapi/inert": "6.0.3",
@@ -53,5 +53,5 @@
     "moment-timezone": "0.5.34",
     "uuid": "8.3.2"
   },
-  "gitHead": "4e154247f5b5a430aa7e6c26e71d75546d8d2411"
+  "gitHead": "0f6912bc7a73c58e2d3494529adc62ce8d65e9e5"
 }

package/src/schema/__tests__/recurring-payments.schema.spec.js

@@ -168,50 +168,29 @@ describe('cancelRecurringPaymentRequestParamsSchema', () => {
   })
 })
 
-describe('cancelRecurringPaymentRequestParamsSchema', () => {
-  it('validates expected object', async () => {
-    const sampleData = { id: 'abc123' }
-    expect(() => cancelRecurringPaymentRequestParamsSchema.validateAsync(sampleData)).not.toThrow()
-  })
-
-  it('throws an error if id missing', async () => {
-    expect(() => cancelRecurringPaymentRequestParamsSchema.validateAsync({}).rejects.toThrow())
-  })
-
-  it('throws an error if id is not the correct type', async () => {
-    const sampleData = { id: 99 }
-    expect(() => cancelRecurringPaymentRequestParamsSchema.validateAsync(sampleData).rejects.toThrow())
-  })
-})
-
 describe('cancelRecurringPaymentRequestQuerySchema', () => {
-  it('validates expected object if the reason is Payment Failure', async () => {
-    const sampleData = { reason: 'Payment Failure' }
-    expect(() => cancelRecurringPaymentRequestQuerySchema.validateAsync(sampleData)).not.toThrow()
-  })
-
-  it('validates expected object if the reason is User Cancelled', async () => {
-    const sampleData = { reason: 'User Cancelled' }
-    expect(() => cancelRecurringPaymentRequestQuerySchema.validateAsync(sampleData)).not.toThrow()
+  it.each(['Payment Failure', 'User Cancelled', 'Business Cancelled'])('successfully validates when reason is %s', async reason => {
+    const sampleData = { reason }
+    await expect(cancelRecurringPaymentRequestQuerySchema.validateAsync(sampleData)).resolves.toEqual(sampleData)
   })
 
   it('throws an error if query is empty', async () => {
     const sampleData = {}
-    expect(() => cancelRecurringPaymentRequestQuerySchema.validateAsync(sampleData)).rejects.toThrow()
+    await expect(cancelRecurringPaymentRequestQuerySchema.validateAsync(sampleData)).rejects.toThrow()
   })
 
   it('throws an error if reason is not the correct type', async () => {
     const sampleData = { reason: 99 }
-    expect(() => cancelRecurringPaymentRequestQuerySchema.validateAsync(sampleData).rejects.toThrow())
+    await expect(cancelRecurringPaymentRequestQuerySchema.validateAsync(sampleData)).rejects.toThrow()
   })
 
-  it('throws an error if reason is not the correct value', async () => {
-    const sampleData = { reason: 'Because I said so' }
-    expect(() => cancelRecurringPaymentRequestQuerySchema.validateAsync(sampleData).rejects.toThrow())
+  it('throws an error if reason is invalid', async () => {
+    const sampleData = { reason: 'Not A Valid Reason' }
+    await expect(cancelRecurringPaymentRequestQuerySchema.validateAsync(sampleData)).rejects.toThrow()
   })
 
   it('throws an error if an incorrect key is provided', async () => {
     const sampleData = { foo: 'Payment Failure' }
-    expect(() => cancelRecurringPaymentRequestQuerySchema.validateAsync(sampleData).rejects.toThrow())
+    await expect(cancelRecurringPaymentRequestQuerySchema.validateAsync(sampleData)).rejects.toThrow()
   })
 })

package/src/schema/recurring-payments.schema.js

@@ -35,5 +35,5 @@ export const cancelRecurringPaymentRequestParamsSchema = Joi.object({
 })
 
 export const cancelRecurringPaymentRequestQuerySchema = Joi.object({
-  reason: Joi.string().required().valid('Payment Failure', 'User Cancelled')
+  reason: Joi.string().required().valid('Payment Failure', 'User Cancelled', 'Business Cancelled')
 })

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

@@ -3,7 +3,7 @@ import {
   executeQuery,
   findDueRecurringPayments,
   findRecurringPaymentsByAgreementId,
-  findById,
+  findRecurringPaymentById,
   Permission,
   persist,
   RecurringPayment,
@@ -48,7 +48,6 @@ const { docClient, sqs } = AWS.mock.results[0].value
 jest.mock('@defra-fish/dynamics-lib', () => ({
   ...jest.requireActual('@defra-fish/dynamics-lib'),
   executeQuery: jest.fn(),
-  findById: jest.fn(),
   findDueRecurringPayments: jest.fn(),
   findRecurringPaymentsByAgreementId: jest.fn(() => ({ toRetrieveRequest: () => {} })),
   dynamicsClient: {
@@ -56,6 +55,7 @@ jest.mock('@defra-fish/dynamics-lib', () => ({
   },
   persist: jest.fn(),
   findRecurringPaymentByPermissionId: jest.fn(() => ({ toRetrieveRequest: () => {} })),
+  findRecurringPaymentById: jest.fn(() => ({ toRetrieveRequest: () => {} })),
   retrieveGlobalOptionSets: jest.fn()
 }))
 
@@ -70,7 +70,8 @@ jest.mock('@defra-fish/connectors-lib', () => ({
     }
   })),
   govUkPayApi: {
-    getRecurringPaymentAgreementInformation: jest.fn()
+    getRecurringPaymentAgreementInformation: jest.fn(),
+    cancelRecurringPaymentAgreement: jest.fn()
   }
 }))
 
@@ -895,93 +896,237 @@ 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, 'Payment Failure')
-      expect(findById).toHaveBeenCalledWith(RecurringPayment, id)
+    const createLinkedPermission = (overrides = {}) => {
+      const permission = new Permission()
+      permission.isRecurringPayment = true
+      return Object.assign(permission, overrides)
+    }
+
+    const arrangeCancelRecurringPayment = ({
+      recurringPayment = getMockRecurringPayment(),
+      permissionOverrides = {},
+      govUkPayResponse = { ok: true, status: 204 },
+      linkedPermission = createLinkedPermission(permissionOverrides)
+    } = {}) => {
+      govUkPayApi.cancelRecurringPaymentAgreement.mockResolvedValueOnce(govUkPayResponse)
+      executeQuery.mockResolvedValueOnce([{ entity: recurringPayment, expanded: { activePermission: { entity: linkedPermission } } }])
+      return { recurringPayment, linkedPermission }
+    }
+
+    it.each(['92207e2c-0aa2-4600-a9c4-a7eb2276e404', 'f794dd0d-b80a-4d51-b738-479c87b4765b', 'b437d543-430f-4eb1-830d-539148c8b440'])(
+      'passes recurring payment id to findRecurringPaymentById when id is %s',
+      async id => {
+        arrangeCancelRecurringPayment()
+
+        await cancelRecurringPayment(id, 'Payment Failure')
+
+        expect(findRecurringPaymentById).toHaveBeenCalledWith(id)
+      }
+    )
+
+    it('passes query created by findRecurringPaymentById to executeQuery', async () => {
+      const query = Symbol('query')
+      findRecurringPaymentById.mockReturnValueOnce(query)
+      arrangeCancelRecurringPayment()
+
+      await cancelRecurringPayment('id', 'User Cancelled')
+
+      expect(executeQuery).toHaveBeenCalledWith(query)
     })
 
-    it('should set the reason based on the provided argument', async () => {
-      retrieveGlobalOptionSets.mockReturnValueOnce({ cached: jest.fn().mockResolvedValue({ definition: 'mock-def' }) })
-      findById.mockReturnValueOnce(getMockRecurringPayment())
+    it('passes reason to getGlobalOptionSetValue', async () => {
+      arrangeCancelRecurringPayment()
       const reason = Symbol('unique-reason')
+
       await cancelRecurringPayment('abc123', reason)
+
       expect(getGlobalOptionSetValue).toHaveBeenCalledWith(RecurringPayment.definition.mappings.cancelledReason.ref, reason)
     })
 
-    it('should set cancelledDate when reason is not User Cancelled and 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'
-              }
-            }
-          }
+    it('sets cancelledReason on the persisted recurring payment', async () => {
+      const cancelledReason = { description: 'User Cancelled', id: 910400003, label: 'User Cancelled' }
+      const recurringPayment = { ...getMockRecurringPayment(), cancelledDate: null }
+      const { linkedPermission } = arrangeCancelRecurringPayment({ recurringPayment })
+
+      getGlobalOptionSetValue.mockReturnValueOnce(cancelledReason)
+
+      await cancelRecurringPayment('id', 'User Cancelled')
+
+      expect(persist).toHaveBeenCalledWith([
+        expect.objectContaining({
+          ...recurringPayment,
+          cancelledReason
+        }),
+        linkedPermission
+      ])
+    })
+
+    it('returns the updated recurring payment', async () => {
+      const recurringPayment = getMockRecurringPayment()
+      arrangeCancelRecurringPayment({ recurringPayment })
+
+      const result = await cancelRecurringPayment('id', 'User Cancelled')
+
+      expect(result).toEqual(
+        expect.objectContaining({
+          ...recurringPayment,
+          cancelledDate: expect.any(String),
+          cancelledReason: expect.any(Object)
         })
-      })
+      )
+    })
+
+    it.each(['2026-05-20T09:10:11.123Z', '2027-01-01T00:00:00.000Z'])(
+      'sets cancelledDate to current ISO date-time when now is %s',
+      async nowIsoString => {
+        const recurringPayment = getMockRecurringPayment()
+        const { linkedPermission } = arrangeCancelRecurringPayment({ recurringPayment })
+        jest.useFakeTimers().setSystemTime(new Date(nowIsoString))
+
+        try {
+          await cancelRecurringPayment('id', 'User Cancelled')
+
+          expect(persist).toHaveBeenCalledWith([
+            expect.objectContaining({
+              ...recurringPayment,
+              cancelledDate: nowIsoString
+            }),
+            linkedPermission
+          ])
+        } finally {
+          jest.useRealTimers()
+        }
+      }
+    )
 
+    it('calls GovUKPay cancellation with agreement id', async () => {
       const recurringPayment = getMockRecurringPayment()
-      findById.mockReturnValueOnce(recurringPayment)
+      arrangeCancelRecurringPayment({ recurringPayment })
 
-      const cancelledReason = { description: 'Payment Failure', id: 910400002, label: 'Payment Failure' }
+      await cancelRecurringPayment('id', 'User Cancelled')
 
-      await cancelRecurringPayment('id', 'Payment Failure')
+      expect(govUkPayApi.cancelRecurringPaymentAgreement).toHaveBeenCalledWith(recurringPayment.agreementId)
+    })
+
+    it('debug outputs success message with agreement id when GovUKPay cancellation succeeds', async () => {
+      const recurringPayment = getMockRecurringPayment()
+      arrangeCancelRecurringPayment({ recurringPayment })
+
+      await cancelRecurringPayment('id', 'User Cancelled')
+
+      expect(debug).toHaveBeenCalledWith('Successfully cancelled GovUkPay agreement: %s', recurringPayment.agreementId)
+    })
+
+    it.each([
+      ['404 not found', 404, 'GovUkPay agreement not found (already cancelled or does not exist): %s'],
+      ['400 bad request', 400, 'GovUkPay agreement cannot be cancelled (invalid state): %s']
+    ])('debug outputs message with agreement id when GovUKPay returns %s', async (_description, status, expectedMessage) => {
+      const recurringPayment = getMockRecurringPayment()
+      arrangeCancelRecurringPayment({ recurringPayment, govUkPayResponse: { ok: false, status } })
+
+      await cancelRecurringPayment('id', 'User Cancelled')
+
+      expect(debug).toHaveBeenCalledWith(expectedMessage, recurringPayment.agreementId)
+    })
+
+    it('throws when recurring payment has no agreement id', async () => {
+      const recurringPayment = getMockRecurringPayment({ agreementId: undefined })
+
+      executeQuery.mockResolvedValueOnce([
+        { entity: recurringPayment, expanded: { activePermission: { entity: createLinkedPermission() } } }
+      ])
+
+      await expect(cancelRecurringPayment('recurring-payment-id', 'Payment Failure')).rejects.toThrow(
+        'Cannot cancel a recurring payment without an agreement ID: recurring-payment-id'
+      )
+    })
+
+    it.each([
+      ['404 not found', 404, 'Not Found'],
+      ['400 bad request', 400, 'Bad Request']
+    ])('does not throw when GovUKPay returns %s', async (_description, status, statusText) => {
+      arrangeCancelRecurringPayment({ govUkPayResponse: { ok: false, status, statusText } })
+
+      await expect(cancelRecurringPayment('id', 'User Cancelled')).resolves.toBeDefined()
+    })
+
+    it.each([
+      ['404 not found', 404, 'Not Found'],
+      ['400 bad request', 400, 'Bad Request']
+    ])('persists cancellation in CRM when GovUKPay returns %s', async (_description, status, statusText) => {
+      const recurringPayment = getMockRecurringPayment()
+      const { linkedPermission } = arrangeCancelRecurringPayment({ recurringPayment, govUkPayResponse: { ok: false, status, statusText } })
+
+      await cancelRecurringPayment('id', 'User Cancelled')
 
       expect(persist).toHaveBeenCalledWith([
         expect.objectContaining({
           ...recurringPayment,
-          cancelledReason,
-          cancelledDate: expect.stringMatching(/^\d{4}-\d{2}-\d{2}$/)
-        })
+          cancelledDate: expect.any(String),
+          cancelledReason: expect.any(Object)
+        }),
+        linkedPermission
       ])
     })
 
-    it('should not set cancelledDate when reason is User Cancelled', async () => {
-      retrieveGlobalOptionSets.mockReturnValueOnce({
-        cached: jest.fn().mockResolvedValue({
-          defra_cancelledreasons: {
-            options: {
-              910400003: {
-                id: 910400003,
-                label: 'User Cancelled',
-                description: 'User Cancelled'
-              }
-            }
-          }
-        })
+    it('throws when GovUKPay returns unexpected status', async () => {
+      arrangeCancelRecurringPayment()
+      govUkPayApi.cancelRecurringPaymentAgreement.mockReset().mockResolvedValueOnce({
+        ok: false,
+        status: 500,
+        statusText: 'Internal Server Error',
+        text: jest.fn().mockResolvedValue('Server error')
       })
 
-      const cancelledReason = { description: 'User Cancelled', id: 910400003, label: 'User Cancelled' }
+      await expect(cancelRecurringPayment('id', 'User Cancelled')).rejects.toThrow('Failed to cancel GovUkPay agreement')
+    })
 
-      const recurringPayment = { ...getMockRecurringPayment(), cancelledDate: null }
-      findById.mockReturnValueOnce(recurringPayment)
+    it('sets linked permission isRecurringPayment to false', async () => {
+      const { linkedPermission } = arrangeCancelRecurringPayment()
 
-      getGlobalOptionSetValue.mockReturnValueOnce(cancelledReason)
+      await cancelRecurringPayment('id', 'User Cancelled')
+
+      expect(linkedPermission.isRecurringPayment).toBe(false)
+    })
+
+    it('persists linked permission alongside recurring payment', async () => {
+      const recurringPayment = getMockRecurringPayment()
+      const { linkedPermission } = arrangeCancelRecurringPayment({ recurringPayment })
 
       await cancelRecurringPayment('id', 'User Cancelled')
 
       expect(persist).toHaveBeenCalledWith([
         expect.objectContaining({
           ...recurringPayment,
-          cancelledReason,
-          cancelledDate: null
-        })
+          cancelledDate: expect.any(String),
+          cancelledReason: expect.any(Object)
+        }),
+        linkedPermission
       ])
     })
 
-    it('should raise an error when there are no matches', async () => {
-      findById.mockReturnValueOnce(undefined)
+    it('throws when recurring payment id is invalid', async () => {
+      executeQuery.mockResolvedValueOnce([])
 
-      await expect(cancelRecurringPayment('id', 'Payment Failure')).rejects.toThrow(
-        'Invalid id provided for recurring payment cancellation'
+      await expect(cancelRecurringPayment('recurring-payment-id', 'Payment Failure')).rejects.toThrow(
+        'Invalid id provided for recurring payment cancellation: recurring-payment-id'
       )
     })
+
+    it('throws when no active permission is linked to the recurring payment', async () => {
+      executeQuery.mockResolvedValueOnce([{ entity: getMockRecurringPayment(), expanded: {} }])
+
+      await expect(cancelRecurringPayment('recurring-payment-id', 'Payment Failure')).rejects.toThrow(
+        'No active permission linked to recurring payment: recurring-payment-id'
+      )
+    })
+
+    it('propagates persist error after successful GovUKPay cancellation', async () => {
+      arrangeCancelRecurringPayment()
+      persist.mockRejectedValueOnce(new Error('CRM unavailable'))
+
+      await expect(cancelRecurringPayment('id', 'User Cancelled')).rejects.toThrow('CRM unavailable')
+    })
   })
 
   describe('findLinkedRecurringPayment', () => {

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

@@ -1,9 +1,9 @@
 import {
   dynamicsClient,
   executeQuery,
-  findById,
   findDueRecurringPayments,
   findRecurringPaymentsByAgreementId,
+  findRecurringPaymentById,
   persist,
   RecurringPayment,
   findRecurringPaymentByPermissionId,
@@ -21,6 +21,7 @@ import { getGlobalOptionSetValue } from './reference-data.service.js'
 import moment from 'moment'
 import { AWS, govUkPayApi } from '@defra-fish/connectors-lib'
 import db from 'debug'
+import { StatusCodes } from 'http-status-codes'
 const debug = db('sales:recurring')
 const { sqs, docClient } = AWS()
 
@@ -167,21 +168,43 @@ export const findNewestExistingRecurringPaymentInCrm = async agreementId => {
 }
 
 export const cancelRecurringPayment = async (id, reason) => {
-  const recurringPayment = await findById(RecurringPayment, id)
-  if (recurringPayment) {
-    const data = recurringPayment
-    const isUserCancelled = reason === 'User Cancelled'
+  const [result] = await executeQuery(findRecurringPaymentById(id))
+  if (!result) {
+    throw new Error(`Invalid id provided for recurring payment cancellation: ${id}`)
+  }
 
-    if (!isUserCancelled) {
-      data.cancelledDate = new Date().toISOString().split('T')[0]
-    }
+  const recurringPayment = result.entity
+  const linkedPermission = result.expanded?.activePermission?.entity
+  if (!linkedPermission) {
+    throw new Error(`No active permission linked to recurring payment: ${id}`)
+  }
+  if (!recurringPayment.agreementId) {
+    throw new Error(`Cannot cancel a recurring payment without an agreement ID: ${id}`)
+  }
+
+  recurringPayment.cancelledDate = new Date().toISOString()
+  recurringPayment.cancelledReason = await getGlobalOptionSetValue(RecurringPayment.definition.mappings.cancelledReason.ref, reason)
 
-    data.cancelledReason = await getGlobalOptionSetValue(RecurringPayment.definition.mappings.cancelledReason.ref, reason)
-    const updatedRecurringPayment = Object.assign(new RecurringPayment(), data)
-    await persist([updatedRecurringPayment])
-    return updatedRecurringPayment
+  await cancelGovUkPayAgreement(recurringPayment.agreementId)
+
+  const updatedRecurringPayment = Object.assign(new RecurringPayment(), recurringPayment)
+  linkedPermission.isRecurringPayment = false
+
+  await persist([updatedRecurringPayment, linkedPermission])
+  return updatedRecurringPayment
+}
+
+const cancelGovUkPayAgreement = async agreementId => {
+  const response = await govUkPayApi.cancelRecurringPaymentAgreement(agreementId)
+  if (response.ok) {
+    debug('Successfully cancelled GovUkPay agreement: %s', agreementId)
+  } else if (response.status === StatusCodes.NOT_FOUND) {
+    debug('GovUkPay agreement not found (already cancelled or does not exist): %s', agreementId)
+  } else if (response.status === StatusCodes.BAD_REQUEST) {
+    debug('GovUkPay agreement cannot be cancelled (invalid state): %s', agreementId)
   } else {
-    throw new Error('Invalid id provided for recurring payment cancellation')
+    const body = await response.text().catch(() => 'Unable to read response body')
+    throw new Error(`Failed to cancel GovUkPay agreement ${agreementId}: ${response.status} ${response.statusText} - ${body}`)
   }
 }