Gpesa NPM Package

gpesa is a lightweight JavaScript/TypeScript library designed to help developers identify the mobile network and mobile money service associated with Tanzanian phone numbers. It also provides regex patterns to validate Tanzanian phone numbers easily. Additionally, you can use the hosted website at Gpesa Website for quick manual checks.

Installation

Install the gpesa package via npm:

npm install gpesa

Or via yarn:

yarn add gpesa

Features

• Identify Mobile Networks: Determine the mobile network and associated mobile money service for a Tanzanian phone number.
• Validate Phone Numbers: Use predefined regex patterns to validate Tanzanian phone numbers.
• Easy Integration: Simple and intuitive API.
• Hosted Website: Use the Gpesa Website to manually determine mobile networks.

Usage

Importing the Package

import { matchNetwork } from 'gpesa';

Example: Determining Mobile Network

const phoneNumber = '255765123456';
const result = matchNetwork(phoneNumber);

if (result) {
  console.log(`Network: ${result.name}`);
  console.log(`Mobile Money: ${result.mobile_money || 'Not Available'}`);
} else {
  console.log('Invalid or unrecognized phone number');
}

// Output:
// Network: VODACOM
// Mobile Money: M-PESA

Example: Validating Full Phone Numbers

The package also exposes regex patterns for full phone number validation. For example, you can validate that a number matches the required structure:

import MOBILE_NETWORKS from 'gpesa';

const phoneNumber = '255713456789';
const isValid = MOBILE_NETWORKS.some(network => network.full_msisdn_pattern.test(phoneNumber));

console.log(isValid ? 'Valid Tanzanian Phone Number' : 'Invalid Phone Number');

Example: Custom Validation with Regex Patterns

You can use the predefined msisdn_pattern for partial matches (e.g., prefix-only checks):

import MOBILE_NETWORKS from 'gpesa';

const phoneNumber = '067';
const network = MOBILE_NETWORKS.find(net => net.msisdn_pattern.test(phoneNumber));

if (network) {
  console.log(`Prefix belongs to: ${network.name}`);
} else {
  console.log('Unrecognized prefix');
}

API

matchNetwork(mobileNumber: string): { name: string; mobile_money: string } | null

• Description: Identifies the mobile network and associated mobile money service for a given phone number.
• Parameters:
  • mobileNumber: The Tanzanian phone number to check (e.g., 255765123456, 0765123456).
• Returns:
  • An object containing name (the network name) and mobile_money (the mobile money service) if a match is found.
  • null if no match is found.

MOBILE_NETWORKS

• Description: An array of objects containing details about all supported Tanzanian mobile networks.
• Properties:
  • name: The name of the mobile network (e.g., AIRTEL).
  • mobile_money: The name of the mobile money service (if available).
  • msisdn_pattern: Regex pattern for validating prefixes.
  • full_msisdn_pattern: Regex pattern for validating full phone numbers.

Supported Networks

| Network | Mobile Money Service | Example Prefixes | |-----------|-------------------------|------------------| | AIRTEL | AIRTEL MONEY | 0678, 0789 | | HALOTEL | HALO PESA | 0612, 0621 | | SMILE | N/A | 0666 | | TTCL | T-PESA | 0731 | | VODACOM | M-PESA | 0765, 0754 | | YAS | MIXX BY YAS / TIGO PESA| 0657, 0671 | | ZANTEL | MIXX BY YAS / EZY PESA | 0777 |

Website

Visit the Gpesa Website to manually determine the mobile network of a Tanzanian phone number. It uses the same logic as the gpesa npm package.

License

This project is licensed under the MIT License.