HMAI 99 - Implement GET /v1/prison/{prisonId}/prisoners/{hmppsId}/balances/{accountCode} (#572)

emmalanigan · web-flow · commit 005b80730afb · 2025-01-13T16:42:17.000Z
* Add concept of accountCodes to GetBalancesForPersonService so we can bring back a single balance

* add logic to handle 3 possible account codes otherwise throw a bad request error

* add test to check prison filter is still respected when account code provided

* add new endpoint on BalancesController which calls getBalancesForPersonService; add endpoint on relevant yml files

* getBalanceForPerson in balance controller handles 404 responses

* getBalanceForPerson in balance controller handles 400 responses

* getBalanceForPerson in balance controller handles 500 responses

* amend logic in GetBalancesForPersonService to throw an exception within the getBalance function so that exception is only thrown if relevant account code is null

* add integration test

* Rename balance to balances

* Change flow to call getBalance from controller

* Remove unused argument.

* Replace confusing it.equals with ==

* Make account code non optional.
diff --git a/src/main/kotlin/uk/gov/justice/digital/hmpps/hmppsintegrationapi/controllers/v1/BalancesController.kt b/src/main/kotlin/uk/gov/justice/digital/hmpps/hmppsintegrationapi/controllers/v1/BalancesController.kt
@@ -45,17 +45,52 @@ class BalancesController(
     @PathVariable prisonId: String,
     @RequestAttribute filters: ConsumerFilters?,
   ): DataResponse<Balances?> {
-    val response = getBalancesForPersonService.execute(prisonId, hmppsId, filters)
+    val response = getBalancesForPersonService.execute(prisonId, hmppsId, filters = filters)
 
     if (response.hasError(UpstreamApiError.Type.ENTITY_NOT_FOUND)) {
       throw EntityNotFoundException("Could not find person with id: $hmppsId")
     }
 
     if (response.hasError(UpstreamApiError.Type.BAD_REQUEST)) {
-      throw ValidationException("Either invalid HMPPS ID: $hmppsId at or incorrect prison: $prisonId")
+      throw ValidationException("Either invalid HMPPS ID: $hmppsId or incorrect prison: $prisonId")
     }
 
     auditService.createEvent("GET_BALANCES_FOR_PERSON", mapOf("hmppsId" to hmppsId, "prisonId" to prisonId))
     return DataResponse(response.data)
   }
+
+  @GetMapping("/{accountCode}")
+  @Operation(
+    summary = "Returns a specific account for a prisoner that they have at a prison, based on the account code provided.",
+    description = "<b>Applicable filters</b>: <ul><li>prisons</li></ul>",
+    responses = [
+      ApiResponse(responseCode = "200", useReturnTypeSchema = true, description = "Successfully found a prisoner's account."),
+      ApiResponse(
+        responseCode = "400",
+        description = "The HMPPS ID provided has an invalid format, the account code is not one of the allowable accounts or the prisoner does hot have accounts at the specified prison.",
+        content = [Content(schema = Schema(ref = "#/components/schemas/BadRequest"))],
+      ),
+      ApiResponse(responseCode = "404", content = [Content(schema = Schema(ref = "#/components/schemas/PersonNotFound"))]),
+      ApiResponse(responseCode = "500", content = [Content(schema = Schema(ref = "#/components/schemas/InternalServerError"))]),
+    ],
+  )
+  fun getBalanceForPerson(
+    @PathVariable hmppsId: String,
+    @PathVariable prisonId: String,
+    @PathVariable accountCode: String,
+    @RequestAttribute filters: ConsumerFilters?,
+  ): DataResponse<Balances?> {
+    val response = getBalancesForPersonService.getBalance(prisonId, hmppsId, accountCode, filters = filters)
+
+    if (response.hasError(UpstreamApiError.Type.ENTITY_NOT_FOUND)) {
+      throw EntityNotFoundException("Could not find person with id: $hmppsId")
+    }
+
+    if (response.hasError(UpstreamApiError.Type.BAD_REQUEST)) {
+      throw ValidationException("Either invalid HMPPS ID: $hmppsId, invalid Account Code: $accountCode or incorrect prison: $prisonId")
+    }
+
+    auditService.createEvent("GET_BALANCE_FOR_PERSON", mapOf("hmppsId" to hmppsId, "accountCode" to accountCode, "prisonId" to prisonId))
+    return DataResponse(response.data)
+  }
 }
diff --git a/src/main/kotlin/uk/gov/justice/digital/hmpps/hmppsintegrationapi/services/GetBalancesForPersonService.kt b/src/main/kotlin/uk/gov/justice/digital/hmpps/hmppsintegrationapi/services/GetBalancesForPersonService.kt
@@ -71,4 +71,36 @@ class GetBalancesForPersonService(
       errors = emptyList(),
     )
   }
+
+  fun getBalance(
+    prisonId: String,
+    hmppsId: String,
+    accountCode: String,
+    filters: ConsumerFilters? = null,
+  ): Response<Balances?> {
+    if (!listOf("spends", "savings", "cash").any { it == accountCode }) {
+      return Response(
+        data = null,
+        errors = listOf(UpstreamApiError(type = UpstreamApiError.Type.BAD_REQUEST, causedBy = UpstreamApi.NOMIS)),
+      )
+    }
+
+    val response = execute(prisonId, hmppsId, filters)
+
+    if (response.errors.isNotEmpty()) {
+      return Response(
+        data = null,
+        errors = response.errors,
+      )
+    }
+
+    val accountBalance = response.data?.balances?.filter { it.accountCode == accountCode }?.firstOrNull()
+
+    if (accountBalance == null) {
+      throw IllegalStateException("Error occurred while trying to get accounts for person with id: $hmppsId")
+    }
+
+    val balance = Balances(balances = listOf(accountBalance))
+    return Response(data = balance, errors = emptyList())
+  }
 }
diff --git a/src/main/resources/application-dev.yml b/src/main/resources/application-dev.yml
@@ -129,6 +129,7 @@ authorisation:
         - "/v1/prison/prisoners/[^/]*$"
         - "/v1/prison/prisoners"
         - "/v1/prison/.*/prisoners/.*/balances$"
+        - "/v1/prison/.*/prisoners/.*/balances/[^/]*$"
       filters:
     kilco:
       include:
@@ -137,6 +138,7 @@ authorisation:
         - "/v1/prison/prisoners"
         - "/v1/prison/prisoners/[^/]*$"
         - "/v1/prison/.*/prisoners/.*/balances$"
+        - "/v1/prison/.*/prisoners/.*/balances/[^/]*$"
       filters:
     meganexus:
       include:
@@ -153,6 +155,7 @@ authorisation:
         - "/v1/prison/prisoners/[^/]*$"
         - "/v1/prison/prisoners"
         - "/v1/prison/.*/prisoners/.*/balances$"
+        - "/v1/prison/.*/prisoners/.*/balances/[^/]*$"
       filters:
     serco:
       include:
diff --git a/src/main/resources/application-integration-test.yml b/src/main/resources/application-integration-test.yml
@@ -85,6 +85,7 @@ authorisation:
         - "/v1/prison/prisoners/[^/]*$"
         - "/v1/prison/prisoners"
         - "/v1/prison/.*/prisoners/.*/balances$"
+        - "/v1/prison/.*/prisoners/.*/balances/[^/]*$"
       filters:
     config-test:
       include:
diff --git a/src/main/resources/application-test.yml b/src/main/resources/application-test.yml
@@ -87,6 +87,7 @@ authorisation:
         - "/v1/prison/prisoners/[^/]*$"
         - "/v1/prison/prisoners"
         - "/v1/prison/.*/prisoners/.*/balances$"
+        - "/v1/prison/.*/prisoners/.*/balances/[^/]*$"
     config-test:
       include:
         - "/v1/config/authorisation"
@@ -96,6 +97,7 @@ authorisation:
     limited-prisons:
       include:
         - "/v1/prison/.*/prisoners/.*/balances$"
+        - "/v1/prison/.*/prisoners/.*/balances/[^/]*$"
       filters:
         prisons:
           - XYZ
diff --git a/src/test/kotlin/uk/gov/justice/digital/hmpps/hmppsintegrationapi/controllers/v1/BalancesControllerTest.kt b/src/test/kotlin/uk/gov/justice/digital/hmpps/hmppsintegrationapi/controllers/v1/BalancesControllerTest.kt
@@ -1,6 +1,5 @@
 package uk.gov.justice.digital.hmpps.hmppsintegrationapi.controllers.v1
 
-import com.fasterxml.jackson.databind.ObjectMapper
 import io.kotest.core.spec.style.DescribeSpec
 import io.kotest.matchers.shouldBe
 import io.kotest.matchers.string.shouldContain
@@ -36,10 +35,11 @@ class BalancesControllerTest(
 ) : DescribeSpec({
     val hmppsId = "200313116M"
     val prisonId = "ABC"
+    val accountCode = "spends"
 
-    val basePath = "/v1/prison/$prisonId/prisoners/$hmppsId/balances"
+    val balancesPath = "/v1/prison/$prisonId/prisoners/$hmppsId/balances"
+    val accountCodePath = "/v1/prison/$prisonId/prisoners/$hmppsId/balances/$accountCode"
     val mockMvc = IntegrationAPIMockMvc(springMockMvc)
-    val objectMapper = ObjectMapper()
     val balance =
       Balances(
         balances =
@@ -49,20 +49,27 @@ class BalancesControllerTest(
             AccountBalance(accountCode = "cash", amount = 103),
           ),
       )
+    val singleBalance =
+      Balances(
+        balances =
+          listOf(
+            AccountBalance(accountCode = "spends", amount = 201),
+          ),
+      )
 
     it("gets the balances for a person with the matching ID") {
-      mockMvc.performAuthorised(basePath)
+      mockMvc.performAuthorised(balancesPath)
 
-      verify(getBalancesForPersonService, VerificationModeFactory.times(1)).execute(prisonId, hmppsId, null)
+      verify(getBalancesForPersonService, VerificationModeFactory.times(1)).execute(prisonId, hmppsId, filters = null)
     }
 
     it("returns the correct balances data") {
-      whenever(getBalancesForPersonService.execute(prisonId, hmppsId, null)).thenReturn(
+      whenever(getBalancesForPersonService.execute(prisonId, hmppsId, filters = null)).thenReturn(
         Response(
           data = balance,
         ),
       )
-      val result = mockMvc.performAuthorised(basePath)
+      val result = mockMvc.performAuthorised(balancesPath)
       result.response.contentAsString.shouldContain(
         """
           "data": {
@@ -86,8 +93,8 @@ class BalancesControllerTest(
     }
 
     it("calls the API with the correct filters") {
-      mockMvc.performAuthorisedWithCN(basePath, "limited-prisons")
-      verify(getBalancesForPersonService, times(1)).execute(prisonId, hmppsId, ConsumerFilters(prisons = listOf("XYZ")))
+      mockMvc.performAuthorisedWithCN(balancesPath, "limited-prisons")
+      verify(getBalancesForPersonService, times(1)).execute(prisonId, hmppsId, filters = ConsumerFilters(prisons = listOf("XYZ")))
     }
 
     it("returns a 404 NOT FOUND status code when person isn't found in probation offender search") {
@@ -104,13 +111,13 @@ class BalancesControllerTest(
         ),
       )
 
-      val result = mockMvc.performAuthorised(basePath)
+      val result = mockMvc.performAuthorised(balancesPath)
 
       result.response.status.shouldBe(HttpStatus.NOT_FOUND.value())
     }
 
     it("returns a 404 NOT FOUND status code when person isn't found in Nomis") {
-      whenever(getBalancesForPersonService.execute(prisonId, hmppsId, null)).thenReturn(
+      whenever(getBalancesForPersonService.execute(prisonId, hmppsId, filters = null)).thenReturn(
         Response(
           data = null,
           errors =
@@ -123,13 +130,112 @@ class BalancesControllerTest(
         ),
       )
 
-      val result = mockMvc.performAuthorised(basePath)
+      val result = mockMvc.performAuthorised(balancesPath)
 
       result.response.status.shouldBe(HttpStatus.NOT_FOUND.value())
     }
 
     it("returns a 400 BAD REQUEST status code when account isn't found in the upstream API") {
-      whenever(getBalancesForPersonService.execute(prisonId, hmppsId, null)).thenReturn(
+      whenever(getBalancesForPersonService.execute(prisonId, hmppsId, filters = null)).thenReturn(
+        Response(
+          data = null,
+          errors =
+            listOf(
+              UpstreamApiError(
+                type = UpstreamApiError.Type.BAD_REQUEST,
+                causedBy = UpstreamApi.NOMIS,
+              ),
+            ),
+        ),
+      )
+
+      val result = mockMvc.performAuthorised(balancesPath)
+
+      result.response.status.shouldBe(HttpStatus.BAD_REQUEST.value())
+    }
+
+    it("returns a 500 INTERNAL SERVER ERROR status code when balance isn't found in the upstream API") {
+      whenever(getBalancesForPersonService.execute(prisonId, hmppsId, filters = null)).thenThrow(
+        IllegalStateException("Error occurred while trying to get accounts for person with id: $hmppsId"),
+      )
+
+      val result = mockMvc.performAuthorised(balancesPath)
+
+      result.response.status.shouldBe(HttpStatus.INTERNAL_SERVER_ERROR.value())
+    }
+
+    it("gets the balance for the relevant account code for a person with the matching ID") {
+      mockMvc.performAuthorised(accountCodePath)
+
+      verify(getBalancesForPersonService, VerificationModeFactory.times(1)).getBalance(prisonId, hmppsId, accountCode, null)
+    }
+
+    it("returns the correct balance data when given an account code") {
+      whenever(getBalancesForPersonService.getBalance(prisonId, hmppsId, accountCode, filters = null)).thenReturn(
+        Response(
+          data = singleBalance,
+        ),
+      )
+      val result = mockMvc.performAuthorised(accountCodePath)
+      result.response.contentAsString.shouldContain(
+        """
+          "data": {
+            "balances": [
+              {
+                "accountCode": "spends",
+                "amount": 201
+              }
+            ]
+          }
+        """.removeWhitespaceAndNewlines(),
+      )
+    }
+
+    it("calls the API with the correct filters") {
+      mockMvc.performAuthorisedWithCN(accountCodePath, "limited-prisons")
+      verify(getBalancesForPersonService, times(1)).getBalance(prisonId, hmppsId, accountCode, filters = ConsumerFilters(prisons = listOf("XYZ")))
+    }
+
+    it("returns a 404 NOT FOUND status code when person isn't found in probation offender search") {
+      whenever(getBalancesForPersonService.getBalance(prisonId, hmppsId, accountCode)).thenReturn(
+        Response(
+          data = null,
+          errors =
+            listOf(
+              UpstreamApiError(
+                causedBy = UpstreamApi.PROBATION_OFFENDER_SEARCH,
+                type = UpstreamApiError.Type.ENTITY_NOT_FOUND,
+              ),
+            ),
+        ),
+      )
+
+      val result = mockMvc.performAuthorised(accountCodePath)
+
+      result.response.status.shouldBe(HttpStatus.NOT_FOUND.value())
+    }
+
+    it("returns a 404 NOT FOUND status code when person isn't found in Nomis") {
+      whenever(getBalancesForPersonService.getBalance(prisonId, hmppsId, accountCode, filters = null)).thenReturn(
+        Response(
+          data = null,
+          errors =
+            listOf(
+              UpstreamApiError(
+                causedBy = UpstreamApi.NOMIS,
+                type = UpstreamApiError.Type.ENTITY_NOT_FOUND,
+              ),
+            ),
+        ),
+      )
+
+      val result = mockMvc.performAuthorised(accountCodePath)
+
+      result.response.status.shouldBe(HttpStatus.NOT_FOUND.value())
+    }
+
+    it("returns a 400 BAD REQUEST status code when account isn't found in the upstream API") {
+      whenever(getBalancesForPersonService.getBalance(prisonId, hmppsId, accountCode, filters = null)).thenReturn(
         Response(
           data = null,
           errors =
@@ -142,17 +248,17 @@ class BalancesControllerTest(
         ),
       )
 
-      val result = mockMvc.performAuthorised(basePath)
+      val result = mockMvc.performAuthorised(accountCodePath)
 
       result.response.status.shouldBe(HttpStatus.BAD_REQUEST.value())
     }
 
     it("returns a 500 INTERNAL SERVER ERROR status code when balance isn't found in the upstream API") {
-      whenever(getBalancesForPersonService.execute(prisonId, hmppsId, null)).thenThrow(
+      whenever(getBalancesForPersonService.getBalance(prisonId, hmppsId, accountCode, filters = null)).thenThrow(
         IllegalStateException("Error occurred while trying to get accounts for person with id: $hmppsId"),
       )
 
-      val result = mockMvc.performAuthorised(basePath)
+      val result = mockMvc.performAuthorised(accountCodePath)
 
       result.response.status.shouldBe(HttpStatus.INTERNAL_SERVER_ERROR.value())
     }
diff --git a/src/test/kotlin/uk/gov/justice/digital/hmpps/hmppsintegrationapi/integration/prison/BalanceIntegrationTest.kt b/src/test/kotlin/uk/gov/justice/digital/hmpps/hmppsintegrationapi/integration/prison/BalanceIntegrationTest.kt
diff --git a/src/test/kotlin/uk/gov/justice/digital/hmpps/hmppsintegrationapi/services/GetBalancesForPersonServiceTest.kt b/src/test/kotlin/uk/gov/justice/digital/hmpps/hmppsintegrationapi/services/GetBalancesForPersonServiceTest.kt
