@hmcts/cui-client

@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 {
  CUIActions,
  CUIClient,
  mergeCUIFlagItems,
  type CUIClientAuth,
  type CUIFlagDetails,
} 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);
const currentFlags: CUIFlagDetails = {
  partyName: 'Jane Doe',
  roleOnCase: 'Applicant',
  details: [],
};

if (journey.action === CUIActions.SUBMIT) {
  const mergedFlags = mergeCUIFlagItems(
    currentFlags.details,
    journey.replacementFlags?.details
  );

  await updateCaseFlags({
    ...currentFlags,
    details: mergedFlags,
  });
}

if (journey.action === CUIActions.CANCEL) {
  // Leave the existing case flags unchanged.
}

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.

Known flag status values are available as CUIFlagStatus.ACTIVE and CUIFlagStatus.INACTIVE. The CUIFlag.status field also accepts other service-defined strings.

Public API

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

Development

npm run build
npm run typecheck
npm test

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

Release Process

• Update the package version.

npm version patch

Use minor or major instead of patch when appropriate.

• Push the version commit and tag.

git push origin main --follow-tags

• 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.