Add new NoBillingPeriodsError as a reminder (#1257)

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

As part of the work to add support for SROC two-part tariff bill runs to the service, we needed to amend the set-up bill run journey. We took this opportunity to rewrite it!

This meant copying some of the existing restrictions, one of which being that you cannot generate a supplementary until the annual has been created and sent.

We then replaced the legacy SROC annual with a new engine, which was much more performant and reliable. Because of this, the billing & data team was able to bring forward the month they generated the bill runs in.

However, they are still blocked from running supplementary until they are ready to generate the annual bill run each year.

So, we were asked to tweak our version, allowing them to generate a supplementary bill run even when the annual has not yet been done.

The old logic for supplementary always took the current financial year as the starting point. The new logic we implemented works by finding the last annual bill run for a region and using its year.

Already run the annual bill? Then, the result would be the current financial year. Not yet run it? Then we'll find last year's and start from there.

That is, however, when working in pre-prod or production where there is a complete history of annual bill runs. Working locally, or perhaps in `dev` or `tst`, you may find the last annual was in 2021 or simply doesn't exist at all!

When this happens, the SROC engine is unable to determine the billing periods for the supplementary bill run being requested, and an error is thrown. At the time, coding to handle this situation 'gracefully' was discussed but rejected. We'd be writing code and building screens for a situation that could _never_ happen in production.

The problem is that we forget this every now and again. We then attempt to create a supplementary in one of these non-production environments and start panicking when it appears broken.

This is a 'low-fi' attempt to try and remind us devs _why_ supplementary may appear to be broken. 😁

app/errors/no-billing-periods.error.js

@@ -0,0 +1,13 @@
+'use strict'
+
+class NoBillingPeriodsError extends Error {
+  constructor (year = null) {
+    super(
+      "No billing periods could be determined. Perhaps you are trying to create a supplementary in an environment where the last annual doesn't exist or was in a PRESROC year."
+    )
+
+    this.year = year
+  }
+}
+
+module.exports = NoBillingPeriodsError

app/services/bill-runs/start-bill-run-process.service.js

@@ -9,6 +9,7 @@ const AnnualProcessBillRunService = require('./annual/process-bill-run.service.j
 const DetermineBillingPeriodsService = require('./determine-billing-periods.service.js')
 const CreateBillRunPresenter = require('../../presenters/bill-runs/create-bill-run.presenter.js')
 const InitiateBillRunService = require('./initiate-bill-run.service.js')
+const NoBillingPeriodsError = require('../../errors/no-billing-periods.error.js')
 const SupplementaryProcessBillRunService = require('./supplementary/process-bill-run.service.js')
 const TwoPartTariffProcessBillRunService = require('./two-part-tariff/process-bill-run.service.js')
 
@@ -24,8 +25,12 @@ const TwoPartTariffProcessBillRunService = require('./two-part-tariff/process-bi
  */
 async function go (regionId, batchType, userEmail, financialYearEnding) {
   const billingPeriods = DetermineBillingPeriodsService.go(batchType, financialYearEnding)
-  const financialYearEndings = _financialYearEndings(billingPeriods)
 
+  if (billingPeriods.length === 0) {
+    throw new NoBillingPeriodsError(financialYearEnding)
+  }
+
+  const financialYearEndings = _financialYearEndings(billingPeriods)
   const billRun = await InitiateBillRunService.go(financialYearEndings, regionId, batchType, userEmail)
 
   _processBillRun(billRun, billingPeriods)

test/services/bill-runs/start-bill-run-process.service.test.js

@@ -8,6 +8,9 @@ const Sinon = require('sinon')
 const { describe, it, beforeEach, afterEach } = exports.lab = Lab.script()
 const { expect } = Code
 
+// Test helpers
+const NoBillingPeriodsError = require('../../../app/errors/no-billing-periods.error.js')
+
 // Things we need to stub
 const AnnualProcessBillRunService = require('../../../app/services/bill-runs/annual/process-bill-run.service.js')
 const DetermineBillingPeriodsService = require('../../../app/services/bill-runs/determine-billing-periods.service.js')
@@ -179,12 +182,26 @@ describe('Start Bill Run Process service', () => {
   })
 
   describe('when calling the service fails', () => {
-    beforeEach(() => {
-      Sinon.stub(DetermineBillingPeriodsService, 'go').throws()
+    describe('because of an unexpected error', () => {
+      beforeEach(() => {
+        Sinon.stub(DetermineBillingPeriodsService, 'go').throws()
+      })
+
+      it('throws an error', async () => {
+        await expect(StartBillRunProcessService.go(regionId, userEmail)).to.reject()
+      })
     })
 
-    it('throws an error', async () => {
-      await expect(StartBillRunProcessService.go(regionId, userEmail)).to.reject()
+    describe('because no billing periods could be determined', () => {
+      beforeEach(() => {
+        Sinon.stub(DetermineBillingPeriodsService, 'go').returns([])
+      })
+
+      it('throws a NoBillingPeriodsError', async () => {
+        const result = await expect(StartBillRunProcessService.go(regionId, userEmail)).to.reject()
+
+        expect(result).to.be.instanceOf(NoBillingPeriodsError)
+      })
     })
   })
 })