@enochmk/engrafi-client

Typed Engrafi API client for AirtelTigo SIM registration, customer-detail lookup, and MSISDN churn/recycling.

Installation

npm install @enochmk/engrafi-client

For local live-endpoint testing, copy .env.example to .env and set the endpoint values. The .env file is gitignored and must be loaded by your application or test runner.

cp .env.example .env

Run the live smoke tests from the package directory:

npm run test:get-details
npm run test:churn

Pass a different MSISDN as the first argument when needed:

node tests/manual/get-details.mjs 576795786
node tests/manual/churn.mjs 576795786

These commands build the library, load the gitignored .env, call the live endpoints, and exit with a failure status when the operation is unsuccessful.

Quick start

import { EngrafiClient } from '@enochmk/engrafi-client';

const client = new EngrafiClient({
  baseUrl: process.env.ENGRAFI_BASE_URL!,
  churnUrl: process.env.ENGRAFI_CHURN_URL,
  customerDetailsUrl: process.env.ENGRAFI_CUSTOMER_DETAILS_URL,
});

const result = await client.getDetails(process.env.ENGRAFI_TEST_MSISDN!);
if (result.success) {
  console.log(result.data?.responseMap.customerDetails);
} else {
  console.error(result.error);
}

The client does not load .env files automatically. Use the environment loader already used by your application, or pass the endpoint strings directly to EngrafiClient.

Configuration

| Option | Required | Default | Description | | -------------------- | -------- | --------------------------------- | ------------------------------------ | | baseUrl | Yes | — | Engrafi host URL | | churnUrl | No | ${baseUrl}/recycle | Churn/recycle endpoint URL | | customerDetailsUrl | No | ${baseUrl}/get-customer-details | Customer lookup endpoint URL | | timeout | No | 10000 | HTTP timeout in milliseconds | | successCodes | No | ['FL0000', 'SC0000'] | Successful registration status codes | | logger | No | {} | Optional compatible logger methods |

API

registerSim(input)

Registers a SIM through /mnp-registration. The request requires the identity and SIM fields shown below. The client supplies Engrafi defaults for optional fields, and explicit input values override those defaults.

const result = await client.registerSim({
  firstName: 'Ama',
  lastName: 'Mensah',
  msisdn: '233271234567',
  iccid: '8923300000000000001',
  gender: 'FEMALE',
  dateOfBirth: '1990-01-01',
  nationality: 'GHANAIAN',
  docType: 'Passport',
  docNumber: 'P0000001',
  userName: 'agent',
});

getCustomerDetails(msisdn) / getDetails(msisdn)

Queries the configured customer-details endpoint with { msisdn }. getDetails is an alias for getCustomerDetails. Any successful HTTP response is returned as a successful lookup result, including an empty customer list.

const result = await client.getDetails('576795786');

if (result.success) {
  const customers = result.data?.responseMap.customerDetails ?? [];
  console.log(customers);
}

churn(msisdn)

Recycles a number through /recycle. Only SC0000 is treated as success.

const client = new EngrafiClient({
  baseUrl: 'http://10.81.1.98:8000',
  churnUrl: 'http://10.81.1.105:29080/Middleware/api/adapter/v2/engrafi/recycle',
});

const result = await client.churn('576795786');

if (result.success) {
  console.log('MSISDN recycled');
} else {
  console.error(result.statusCode, result.error);
}

SC0000 is the only successful churn status code. For example, an HTTP 500 response with statusCode: "FL0000" is returned as { success: false } rather than thrown.

Result handling

Expected Engrafi rejection, HTTP, timeout, and network failures are returned rather than thrown. Check success before reading data:

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

License

MIT