@hmcts/cui-client

Small TypeScript client for the HMCTS CUI API.

Install

npm install @hmcts/cui-client axios

Usage

CUIClient accepts a required CUIClientConfig object and an optional CUIClientOptions object.

import {
  CUIClient,
  type CUIStartJourneyRequest,
  type CUIStartJourneyAuth,
} from '@hmcts/cui-client';

const client = new CUIClient({
  endpoint: 'https://cui-api.internal.hmcts.net',
  hmctsServiceId: 'your-service-id',
  logoutUrl: 'https://your-app/logout',
});

const request: CUIStartJourneyRequest = {
  callbackUrl: 'https://your-app/callback',
  correlationId: 'a-correlation-id',
  language: 'en',
  masterFlagCode: 'RA0042',
  existingFlags: {
    partyName: 'Jane Doe',
    roleOnCase: 'Applicant',
    details: [],
  },
};

const auth: CUIStartJourneyAuth = {
  idamToken: 'idam-access-token',
  serviceToken: 'service-token',
};

const { url } = await client.startJourney(request, auth);

import { CUIClient, type CUIClientAuth } from '@hmcts/cui-client';

const client = new CUIClient({
  endpoint: 'https://cui-api.internal.hmcts.net',
  hmctsServiceId: 'your-service-id',
});

const auth: CUIClientAuth = {
  serviceToken: 'service-token',
};

const journey = await client.getJourneyData('journey-id', auth);

To pass custom axios request options such as timeouts or a self-signed HTTPS agent:

import { Agent } from 'https';
import { CUIClient, type CUIClientOptions } from '@hmcts/cui-client';

const options: CUIClientOptions = {
  axiosConfig: {
    timeout: 10000,
    httpsAgent: new Agent({
      rejectUnauthorized: false,
    }),
  },
};

const client = new CUIClient({
  endpoint: 'https://cui-api.internal.hmcts.net',
  hmctsServiceId: 'your-service-id',
}, options);

These request options are applied whether the client uses the built-in axios instance or a custom httpClient.

Use relaxed TLS settings only in test or non-production environments.

Public API

• CUIClient
• CUIConfigError
• CUIRequestError
• CUIYesNo
• CUIFlagPath
• CUIFlag
• CUIFlagItem
• CUIFlagDetails
• CUIStartJourneyRequest
• CUIJourneyData
• CUIStartJourneyResponse
• CUIClientAuth
• CUIStartJourneyAuth
• CUIClientConfig
• CUIClientOptions

Development

npm run build
npm run typecheck
npm test

CI and publishing are handled by .github/workflows/npm_build.yml.

Release Process

1. Update the package version.

npm version patch

Use minor or major instead of patch when appropriate.

2. Push the version commit and tag.

git push origin main --follow-tags

3. Create a GitHub Release from the pushed tag.

If the GitHub Release is marked as a prerelease, the workflow publishes to npm with the next dist-tag. Otherwise it publishes with latest.

The publish step uses npm Trusted Publishing with GitHub Actions OIDC. It does not use an NPM_TOKEN.

GitHub And npm Setup

• GitHub Actions must be enabled for this repository.
• npm Trusted Publishing must be configured for this GitHub repository and the npm_build.yml workflow filename.
• The npm package @hmcts/cui-client must exist in the target npm organisation/account.
• Creating a GitHub Release is the publishing trigger; pushes and pull requests only run validation.