@enochmk/nms-client

Reusable NMS (Number Management System) MySQL client extracted from the AT eSIM and biosimreg provisioning flows.

Install

npm install @enochmk/nms-client

Usage

import { NmsClient, NmsDatabaseConnectionError } from "@enochmk/nms-client";

const nms = new NmsClient({
  host: "10.81.0.11",
  user: "your-user",
  password: "your-password",
  database: "ECHELON",
});

try {
  const sim = await nms.getSimDetailsByIccid("your-iccid");
  await nms.linkMsisdnToSim(sim.id, "your-msisdn");
} catch (error) {
  if (error instanceof NmsDatabaseConnectionError) {
    console.error(error.message);
    console.error("Database error code:", error.originalCode);
  }
  throw error;
} finally {
  await nms.disconnect();
}

For environment-based configuration:

const nms = NmsClient.fromEnv();

Supported functionality

• connect() / disconnect() — pooled MySQL connections.
• getSimDetailsByIccid(iccid) — returns NMS row ID, ICCID, IMSI, KI, and current MSISDN.
• getSimDetailsByMsisdn(msisdn) — finds the SIM currently holding a number.
• linkMsisdnToSim(simId, msisdn) — assigns a number to a SIM row.
• unlinkMsisdnFromSim(simId, msisdn?) — clears a number, optionally only when it matches the expected value.
• getAvailableMsisdns(limit?) — returns available entries from NUMBER_POOL.
• markMsisdnAsUsed(msisdn) — changes a number-pool entry to USED.
• swapMsisdnBetweenIccids(msisdn, targetIccid) — atomically clears the current SIM, marks it with STATUS = 12 (available), and links the number to the target ICCID.

All values are sent as MySQL parameters. The swap operation uses a transaction and row locks so a partial swap is rolled back. The target SIM must exist and must not already have a different MSISDN.

Error handling

If the database cannot be reached or initialized, the client throws NmsDatabaseConnectionError with the human-readable message:

Unable to connect to the NMS database. Verify the database host, port, network access, credentials, and SSL settings.

The error also exposes code (NMS_DATABASE_CONNECTION_FAILED), originalCode (for example, ETIMEDOUT or ECONNREFUSED), and the original driver error as cause. Not-found, conflict, and invalid-input conditions are returned as specific HTTP errors with status codes 404, 409, and 400.

Environment

Copy .env.example to .env. The local .env is ignored by git. NmsClient.fromEnv() requires:

NMS_DB_HOST
NMS_DB_USER
NMS_DB_PASSWORD
NMS_DB_DATABASE

NMS_DB_PORT, NMS_DB_CONNECTION_LIMIT, and the other connection options are optional.

Manual tests

Install dependencies, then run the read-only checks first:

npm install
npm run test:connection
npm run test:get-sim -- 8988...
npm run test:available-numbers -- 10

npm run test:link -- <nms-row-id> <msisdn>
npm run test:unlink -- <nms-row-id> <msisdn>
npm run test:swap -- <msisdn> <target-iccid>
npm run test:mark-used -- <msisdn>

The scripts also accept ICCID, MSISDN, and TARGET_ICCID from .env. These scripts change NMS data, so verify the identifiers before running them.

Build

npm run typecheck
npm run build