HMPPS Non-associations API NodeJS REST Client

This library is designed to be used by DPS/HMPPS front-end applications that are based on hmpps-typescript-template and need to access the non-associations api.

Using the library

Typescript applications can install the library in several ways:

Install from npmjs.com

This is the simplest method.

npm install --save @ministryofjustice/hmpps-non-associations-api

Pros:

• uses the most standard, public registry
• dependency upgrade tools will process new releases

Cons:

• publishing requires access token

Install from GitHub Releases

This is a fallback method in case we lose ability to publish to npmjs.com.

Find the latest release version and copy the link to the node-client.tgz asset.

npm install --save [link to asset]

Pros:

• easy to install and requires no authentication

Cons:

• dependency upgrade tools are unlikely to notice new releases

Install from GitHub Packages – npm registry

Unfortunately, GitHub Packages requires authentication to pull from public npm registries, so the setup here is more complex.

In the application repository, create .npmrc with:

registry=https://registry.npmjs.org/
@ministryofjustice:registry=https://npm.pkg.github.com

Create a classic GitHub personal access token with at least read:packages scope, adding it to ~/.npmrc:

//npm.pkg.github.com/:_authToken=[token]

Install library by adding the latest release version to package.json:

"@ministryofjustice/hmpps-non-associations-api": "[latest version number]"

Cons:

• requires authentication when using locally and in CI other than GitHub Actions
• it’s unclear whether dependency upgrade tools can process new releases

Usage

Applications would usually subclass the client:

export class Client extends NonAssociationsApi {
  constructor(systemToken: string) {
    super(
      /**
       * Provide a system token with necessary roles, not a user token
       * READ_NON_ASSOCIATIONS and optionally WRITE_NON_ASSOCIATIONS
       */
      systemToken,

      /**
       * API configuration standard in DPS front-end apps
       */
      config.apis.hmppsNonAssociationsApi,

      /**
       * Logger such as standard library’s `console` or `bunyan` instance
       */
      logger,

      /**
       * Plugins for superagent requests, e.g. restClientMetricsMiddleware
       */
      [restClientMetricsMiddleware],
    )
  }
}

…and use the client in a request handler:

async (req, res) => {
  const { user } = res.locals
  const systemToken = await hmppsAuthClient.getSystemClientToken(user.username)
  const api = new Client(systemToken)
  const nonAssociation = await api.getNonAssociation(nonAssociationId)
}

NB: It is left to the application to determine which actions a user is allowed to perfom!

General notes regarding permissions and roles:

• All prison users, i.e. those with the PRISON role, can view all non-associations
• Users with the NON_ASSOCIATIONS role can add, update and close non-associations for prisoners both in a prison in any of their caseloads
• Users also having the GLOBAL_SEARCH role can also add, update and close non-associations for prisoners in transfer and where one prisoner is not in a prison that’s not in their caseloads
• Users also having the INACTIVE_BOOKINGS role can also add, update and close non-associations for prisoners outside any establishment / released
• Users must close rather than delete non-associations
• Users must add new non-associations rather than reopen closed ones
• No users should be able to add, update or close non-associations for prisoners without a booking / with a null location

Release a new version

Do not change the version set in package.json, it should remain "0.0.0".

• Check the latest release version and choose the next semantic versioning numbers to use
• Tag the commit (on the main branch) to release with node-client-[version] replacing [version] with the next version, e.g. "node-client-0.1.7"
• Create a release from the tag on GitHub