Add Create Sroc Bill Run endpoint (#51)

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

We need to create an endpoint for the UI to hit in order to create an sroc supplementary bill run.

This PR is to create our initial endpoint and apply validation. Creating the billing batch will be done in a future PR.

Note that we expect to receive the bill run type (ie. `supplementary`) in the payload as `type`, and the object it returns also contains this as `type`. This is in contrast to the `water-abstraction-service` which refers to this as `batchType`. We chose not to use `batchType` as we aim to be consistent within this repo as far as possible, and therefore we don't refer to batches if we can help it. It will therefore be necessary when updating the service to ensure that we send and receive it as `type`.

Since this is the first time we're validating incoming data, we needed to decide on how we will implement validation. The solution we have come up with is to create `app/validators`, with validators sitting in an appropriate subfolder. In this case, since the validation relates to bill runs and specifically the create bill run endpoint, we create the file `app/validators/bill-runs/create-bill-run.validator.js`

As part of this we also updated `ErrorPagesPlugin` to accept a `plainOutput` setting, which when set `true` in an endpoint's route will not attempt to change the response to be an HTML page. We did this so that our endpoint will return a standard JSON error response.

app/controllers/bill-runs.controller.js

@@ -0,0 +1,35 @@
+'use strict'
+
+/**
+ * Controller for /bill-runs endpoints
+ * @module BillRunsController
+ */
+
+const Boom = require('@hapi/boom')
+
+const CreateBillRunValidator = require('../validators/bill-runs/create-bill-run.validator')
+
+async function createBillRun (request, _h) {
+  const validatedData = CreateBillRunValidator.go(request.payload)
+
+  if (validatedData.error) {
+    return _formattedValidationError(validatedData.error)
+  }
+
+  return {
+    id: 'DUMMY_SROC_BATCH',
+    region: validatedData.value.region,
+    scheme: validatedData.value.scheme,
+    type: validatedData.value.type,
+    status: 'ready'
+  }
+}
+
+// Takes an error from a validator and returns a suitable Boom error
+function _formattedValidationError (e) {
+  return Boom.badRequest(e.details[0].message)
+}
+
+module.exports = {
+  createBillRun
+}

app/plugins/error-pages.plugin.js

@@ -1,7 +1,10 @@
 'use strict'
 
 /**
- * Add an `onPreResponse` listener to return error pages
+ * Add an `onPreResponse` listener to return HTML error pages for Boom errors.
+ *
+ * The plugin is configured in the route's `plugins.errorPages` object. If `plainOutput` is set to `true` then the
+ * output will not be put into an HTML template and will simply be returned as-is.
  *
  * The bulk of this is taken from https://github.com/DEFRA/hapi-web-boilerplate and tweaked to fit how we organise our
  * code. For now we have removed Google Analytics (which would have been added to the `context` option) as we can
@@ -17,7 +20,9 @@ const ErrorPagesPlugin = {
       server.ext('onPreResponse', (request, h) => {
         const { response } = request
 
-        if (response.isBoom) {
+        const { errorPages: pluginSettings } = request.route.settings.plugins
+
+        if (response.isBoom && !pluginSettings.plainOutput) {
           const { statusCode } = response.output
 
           if (statusCode === 404) {

app/plugins/router.plugin.js

@@ -13,6 +13,7 @@
 
 const AirbrakeRoutes = require('../routes/airbrake.routes.js')
 const AssetRoutes = require('../routes/assets.routes.js')
+const BillRunRoutes = require('../routes/bill-runs.routes')
 const DatabaseRoutes = require('../routes/database.routes.js')
 const FilterRoutesService = require('../services/plugins/filter-routes.service.js')
 const RootRoutes = require('../routes/root.routes.js')
@@ -24,6 +25,7 @@ const routes = [
   ...RootRoutes,
   ...AirbrakeRoutes,
   ...AssetRoutes,
+  ...BillRunRoutes,
   ...DatabaseRoutes,
   ...TestRoutes
 ]

app/routes/bill-runs.routes.js

@@ -0,0 +1,21 @@
+'use strict'
+
+const BillRunsController = require('../controllers/bill-runs.controller.js')
+
+const routes = [
+  {
+    method: 'POST',
+    path: '/bill-runs',
+    handler: BillRunsController.createBillRun,
+    options: {
+      description: 'Used to create a bill run',
+      plugins: {
+        errorPages: {
+          plainOutput: true
+        }
+      }
+    }
+  }
+]
+
+module.exports = routes

app/validators/bill-runs/create-bill-run.validator.js

@@ -0,0 +1,25 @@
+'use strict'
+
+/**
+ * @module CreateBillRunValidator
+ */
+
+const Joi = require('joi')
+
+/**
+ * Checks that the payload of a `create bill run` request is valid
+*/
+function go (data) {
+  const schema = Joi.object({
+    type: Joi.string().valid('supplementary').required(),
+    scheme: Joi.string().valid('sroc').required(),
+    region: Joi.string().guid().required(),
+    previousBillRunId: Joi.string().guid().optional()
+  })
+
+  return schema.validate(data)
+}
+
+module.exports = {
+  go
+}