@enochmk/mfs-client

Typed MFS SOAP API client for AirtelTigo profile management and subscriber registration.

Installation

npm install @enochmk/mfs-client

Quick start

import { MfsClient } from '@enochmk/mfs-client';

const client = new MfsClient({
  baseUrl: process.env.MFS_BASE_URL!,
  profileLogin: process.env.MFS_PROFILE_LOGIN!,
  profilePassword: process.env.MFS_PROFILE_PASSWORD!,
  apiUsername: process.env.MFS_API_USERNAME!,
  apiPassword: process.env.MFS_API_PASSWORD!,
});

const result = await client.getProfile('271234567');
if (result.success) {
  console.log(result.data);
} else if (result.notFound) {
  console.log('Profile not found');
} else {
  console.error(result.code, result.error);
}

Configuration

| Option | Required | Default | Description | | ----------------------- | -------- | ---------- | ----------------------------------------- | | baseUrl | Yes | — | MFS host without a port or trailing slash | | profileLogin | Yes | — | Profile service login | | profilePassword | Yes | — | Profile service password | | apiUsername | Yes | — | Registration API username | | apiPassword | Yes | — | Registration API password | | balanceUrl | No* | — | Full GetBalance SOAP endpoint | | balanceUsername | No* | — | GetBalance WS-Security username | | balancePassword | No* | — | GetBalance WS-Security password | | balanceWalletPassword | No* | — | GetBalance wallet password | | balanceWallet | No | e-wallet | Wallet name sent in the request | | balanceConsumerId | No | Tigo | Consumer ID sent in the request | | balanceCountry | No | GHA | Country sent in the request | | balanceDebugFlag | No | true | Debug flag sent in the request | | profilePort | No | 5268 | Profile management service port | | registrationPort | No | 2340 | Registration service port | | timeout | No | 15000 | HTTP timeout in milliseconds | | successCode | No | 200 | Successful MFS result code | | notFoundCode | No | 00066 | Profile-not-found MFS code | | logger | No | {} | Optional compatible logger methods |

balanceUrl, balanceUsername, and balancePassword are required when using getBalance. balanceWalletPassword is also required and should be loaded from the environment.

MSISDN formatting

All client methods require the MSISDN as exactly nine local digits. Profile lookup, profile update, and registration send those nine digits; GetBalance adds the 233 country code before sending the request. Responses from MFS are normalized back to nine digits.

API

getProfile(msisdn)

Returns MfsResult<MfsProfileData>. A missing profile sets notFound: true.

updateProfile(input)

Updates the subscriber's KYC profile and returns MfsResult<MfsProfileData>.

register(input)

Registers a subscriber and returns MfsResult<MfsRegistrationData>.

getBalance(msisdn, options?)

Retrieves the subscriber wallet balances and returns MfsResult<MfsBalanceData>. The balance endpoint and WS-Security credentials must be configured before calling this method.

const result = await client.getBalance('262975369');

Wallet, consumer, country, debug, transaction ID, and correlation ID values can be overridden with the optional second argument. Transaction and correlation IDs are generated automatically when omitted.

MfsBalanceData.wallets contains each returned wallet name and balance. Wallet passwords and WS-Security credentials are excluded from the returned audit request context.

Manual testing

With .env configured, run both live checks with:

npm run test:manual

Run only one operation when needed:

node --env-file=.env scripts/manual-test.mjs profile
node --env-file=.env scripts/manual-test.mjs balance

The latest observed results for MSISDN 262975369 are documented in docs/manual-test-262975369.md.

Result handling

All expected MFS, SOAP, malformed-response, timeout, and network failures are returned as typed results rather than thrown:

export interface MfsResult<T> {
  success: boolean;
  notFound?: boolean;
  code?: string;
  data?: T;
  request?: unknown;
  response?: unknown;
  httpStatus?: number;
  error?: string;
}

request is safe audit context and never contains credentials. Avoid logging raw outbound XML, because registration credentials are part of that SOAP payload.

License

MIT