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.

Typescript applications can install the library in several ways:

This is the recommended method currently.

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

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

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 can view all non-associations
• Users with the NON_ASSOCIATIONS role can add, update and close non-associations for prisoners in any of their caseloads
• Users also having the GLOBAL_SEARCH role can add, update and close non-associations for prisoners in transfer
• Users also having the INACTIVE_BOOKINGS role can add, update and close non-associations for prisoners outside any establishment / released
• Users should close rather than delete non-associations

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