Add new Charging Module ViewBillRunRequest (#830)

https://eaflood.atlassian.net/browse/WATER-4390

> Part of a series of changes to migrate the legacy [send a bill run](https://defra.github.io/sroc-charging-module-api-docs/#/bill-run/SendBillRun) to this project

The [Charging Module API](https://github.com/DEFRA/sroc-charging-module.api) generates transaction references for every bill in a bill run and creates the transaction files when it receives a `/send` request.

Once the process is complete we need to extract those transaction references and apply them to our bill records. When you [view a bill run](https://defra.github.io/sroc-charging-module-api-docs/#/bill-run/ViewBillRun) the top-level details for each bill are returned including the transaction reference. So, if we can make a view bill run request we can get the transaction references we need.

This change adds the new `ViewBillRunRequest`.

app/requests/charging-module/view-bill-run.request.js

@@ -0,0 +1,29 @@
+'use strict'
+
+/**
+ * Connects with the Charging Module to get a bill run summary
+ * @module ChargingModuleViewBillRunRequest
+ */
+
+const ChargingModuleRequest = require('../../requests/charging-module.request.js')
+
+/**
+ * View a bill run in the Charging Module API
+ *
+ * See {@link https://defra.github.io/sroc-charging-module-api-docs/#/bill-run/ViewBillRun | CHA API docs} for more
+ * details
+ *
+ * @param {string} billRunId - UUID of the charging module API bill run to view
+ *
+ * @returns {Promise<Object>} The result of the request; whether it succeeded and the response or error returned
+ */
+async function send (billRunId) {
+  const path = `v3/wrls/bill-runs/${billRunId}`
+  const result = await ChargingModuleRequest.get(path)
+
+  return result
+}
+
+module.exports = {
+  send
+}

test/requests/charging-module/view-bill-run.request.test.js

@@ -0,0 +1,124 @@
+'use strict'
+
+// Test framework dependencies
+const Lab = require('@hapi/lab')
+const Code = require('@hapi/code')
+const Sinon = require('sinon')
+
+const { describe, it, beforeEach, afterEach } = exports.lab = Lab.script()
+const { expect } = Code
+
+// Things we need to stub
+const ChargingModuleRequest = require('../../../app/requests/charging-module.request.js')
+
+// Thing under test
+const ChargingModuleViewBillRunRequest = require('../../../app/requests/charging-module/view-bill-run.request.js')
+
+describe('Charging Module View Bill Run request', () => {
+  const billRunId = 'db82bf38-638a-44d3-b1b3-1ae8524d9c38'
+
+  afterEach(() => {
+    Sinon.restore()
+  })
+
+  describe('when the service can view a bill run', () => {
+    beforeEach(async () => {
+      Sinon.stub(ChargingModuleRequest, 'get').resolves({
+        succeeded: true,
+        response: {
+          info: {
+            gitCommit: '273604040a47e0977b0579a0fef0f09726d95e39',
+            dockerTag: 'ghcr.io/defra/sroc-charging-module-api:v0.19.0'
+          },
+          statusCode: 200,
+          body: {
+            // truncated invoice, see CM docs for full invoice https://defra.github.io/sroc-charging-module-api-docs
+            invoice: {
+              id: '8e32a958-13f3-4ea3-a92d-651b764c2cbe',
+              billRunId
+            }
+          }
+        }
+      })
+    })
+
+    it('hits the correct endpoint', async () => {
+      await ChargingModuleViewBillRunRequest.send(billRunId)
+      const endpoint = ChargingModuleRequest.get.firstCall.firstArg
+
+      expect(endpoint).to.equal(`v3/wrls/bill-runs/${billRunId}`)
+    })
+
+    it('returns a `true` success status', async () => {
+      const result = await ChargingModuleViewBillRunRequest.send(billRunId)
+
+      expect(result.succeeded).to.be.true()
+    })
+
+    it('returns the bill run in the `response`', async () => {
+      const result = await ChargingModuleViewBillRunRequest.send(billRunId)
+
+      expect(result.response.body.invoice.billRunId).to.equal(billRunId)
+    })
+  })
+
+  describe('when the service cannot view a bill run', () => {
+    describe('because the request did not return a 2xx/3xx response', () => {
+      beforeEach(async () => {
+        Sinon.stub(ChargingModuleRequest, 'get').resolves({
+          succeeded: false,
+          response: {
+            info: {
+              gitCommit: '273604040a47e0977b0579a0fef0f09726d95e39',
+              dockerTag: 'ghcr.io/defra/sroc-charging-module-api:v0.19.0'
+            },
+            statusCode: 401,
+            body: {
+              statusCode: 401,
+              error: 'Unauthorized',
+              message: 'Invalid JWT: Token format not valid',
+              attributes: { error: 'Invalid JWT: Token format not valid' }
+            }
+          }
+        })
+      })
+
+      it('returns a `false` success status', async () => {
+        const result = await ChargingModuleViewBillRunRequest.send(billRunId)
+
+        expect(result.succeeded).to.be.false()
+      })
+
+      it('returns the error in the `response`', async () => {
+        const result = await ChargingModuleViewBillRunRequest.send(billRunId)
+
+        expect(result.response.body.statusCode).to.equal(401)
+        expect(result.response.body.error).to.equal('Unauthorized')
+        expect(result.response.body.message).to.equal('Invalid JWT: Token format not valid')
+      })
+    })
+
+    describe('because the request attempt returned an error, for example, TimeoutError', () => {
+      beforeEach(async () => {
+        Sinon.stub(ChargingModuleRequest, 'get').resolves({
+          succeeded: false,
+          response: new Error("Timeout awaiting 'request' for 5000ms")
+        })
+      })
+
+      it('returns a `false` success status', async () => {
+        const result = await ChargingModuleViewBillRunRequest.send(billRunId)
+
+        expect(result.succeeded).to.be.false()
+      })
+
+      it('returns the error in the `response`', async () => {
+        const result = await ChargingModuleViewBillRunRequest.send(billRunId)
+
+        expect(result.response.statusCode).not.to.exist()
+        expect(result.response.body).not.to.exist()
+        expect(result.response.message).to.equal("Timeout awaiting 'request' for 5000ms")
+      })
+    })
+  })
+})