TCRA Number Check

A comprehensive TypeScript library for validating Tanzanian phone numbers according to the TCRA (Tanzania Communications Regulatory Authority) National Numbering Plan and Signaling Point Codes Plan.

Features

• ✅ Mobile Number Validation - Supports all major Tanzanian mobile operators (Vodacom, Airtel, Tigo/Yas, Halotel, Zantel)
• ✅ Fixed Line Validation - Validates landline numbers with regional identification
• ✅ Emergency Services - Validates emergency numbers (112, 113, 114, 115, 116, 117, 118, 119)
• ✅ Short Codes - Supports short code validation (100-109, 150-159)
• ✅ Signaling Point Codes - Validates STP, HLR, VLR, MSC, SMSC, and other signaling point codes
• ✅ Special Service Numbers - Supports toll-free, premium rate, shared cost, VoIP, paging, and UAN numbers
• ✅ Number Portability - Checks portability status for mobile and fixed line numbers
• ✅ Carrier Selection - Validates carrier selection codes and automatic/manual selection
• ✅ International Format Support - Handles both national and international number formats
• ✅ Number Formatting - Convert between national, international, E.164, and RFC3966 formats
• ✅ Operator Identification - Automatically identifies the service provider with license information
• ✅ Regional Information - Provides regional information for fixed line numbers
• ✅ Numbering Plan Queries - Query the numbering plan by type, operator, region, and status
• ✅ Statistics and Reporting - Comprehensive numbering plan statistics and analysis
• ✅ TypeScript Support - Full TypeScript support with comprehensive type definitions
• ✅ Comprehensive Testing - Extensive test coverage for all number types and features

How It Works

The core logic of this library is implemented in the TCRANumberValidator class. This class provides a comprehensive, extensible, and configurable validator for Tanzanian phone numbers, supporting all number types and features defined by the TCRA National Numbering Plan.

Key Capabilities:

• Validates phone numbers for all Tanzanian number types: mobile, fixed line, emergency, short code, special service (toll-free, premium, shared cost, VoIP, paging, UAN), and signaling point codes.
• Identifies the operator and region for a given number, and checks for number portability and carrier selection codes.
• Supports multiple validation modes (basic, full, custom) and feature toggles for fine-grained control.
• Cleans and parses phone numbers, checks formats, and provides detailed error/warning messages.
• Formats numbers to international, national, E.164, and RFC3966 standards.
• Allows querying the numbering plan for prefixes, operators, and regions, and provides comprehensive statistics.

Main Methods:

• validate(phoneNumber, options): Validates a phone number and returns detailed information (type, operator, region, portability, errors, etc.).
• formatInternational(phoneNumber), formatNational(phoneNumber), formatNumber(phoneNumber, options): Format numbers in various styles.
• queryNumberingPlan(query): Query the numbering plan for specific types, operators, or regions.
• getNumberingPlanStatistics(): Get statistics on the numbering plan (total, by type/operator/region, assigned/available).
• validateCarrierSelection(carrierCode): Check if a carrier selection code is valid.
• isNumberPortabilitySupported(numberType): Check if portability is supported for a number type.
• getSignalingPointCodes(operator?): List signaling point codes, optionally filtered by operator.
• getEmergencyServices(): List all emergency services.

The validator is highly extensible and can be configured with custom numbering plans or feature sets, making it suitable for a wide range of Tanzanian telecom applications.

Installation

npm install tcra-num-check

Quick Start

import { TCRANumberValidator, NumberType, PortabilityStatus } from 'tcra-num-check';

const validator = new TCRANumberValidator();

// Validate a mobile number
const result = validator.validate('0712345678');
console.log(result.isValid); // true
console.log(result.numberType); // NumberType.MOBILE
console.log(result.operator); // 'Airtel Tanzania'

// Validate with portability check
const resultWithPortability = validator.validate('0712345678', { 
  checkPortability: true 
});
console.log(resultWithPortability.portabilityStatus); // PortabilityStatus.PORTABLE

// Format to international
const international = validator.formatInternational('0712345678');
console.log(international); // '+255712345678'

// Query numbering plan
const mobileNumbers = validator.queryNumberingPlan({ 
  numberType: NumberType.MOBILE 
});

// Get statistics
const stats = validator.getNumberingPlanStatistics();
console.log(stats.totalNumbers); // Total available numbers

API Reference

TCRANumberValidator

The main validator class for Tanzanian phone numbers.

Constructor

new TCRANumberValidator(numberingPlan?: NumberingPlan)

• numberingPlan (optional): Custom numbering plan configuration

Methods

validate(phoneNumber: string, options?: ValidationOptions): NumberValidationResult

Validates a Tanzanian phone number and returns detailed information.

Parameters:

• phoneNumber: The phone number to validate
• options: Validation options (optional)

Returns: NumberValidationResult object with validation details

Example:

const result = validator.validate('0712345678', { 
  checkPortability: true,
  validateSignalingPoint: true 
});
console.log(result);
// {
//   isValid: true,
//   numberType: NumberType.MOBILE,
//   operator: 'Airtel Tanzania',
//   region: undefined,
//   portabilityStatus: PortabilityStatus.PORTABLE,
//   numberStatus: NumberStatus.ACTIVE,
//   carrierSelection: CarrierSelection.AUTOMATIC,
//   errors: [],
//   warnings: []
// }

formatInternational(phoneNumber: string): string | null

Formats a valid number to international format.

Returns: International format string or null if invalid

Example:

const international = validator.formatInternational('0712345678');
console.log(international); // '+255712345678'

formatNational(phoneNumber: string): string | null

Formats a valid number to national format.

Returns: National format string or null if invalid

Example:

const national = validator.formatNational('+255712345678');
console.log(national); // '0712345678'

formatNumber(phoneNumber: string, options: NumberFormatOptions): string | null

Formats a number with various options.

Parameters:

• phoneNumber: The phone number to format
• options: Formatting options

Returns: Formatted string or null if invalid

Example:

const rfc3966 = validator.formatNumber('0712345678', { format: 'rfc3966' });
console.log(rfc3966); // 'tel:+255712345678'

queryNumberingPlan(query: NumberingPlanQuery): any[]

Queries the numbering plan for specific criteria.

Parameters:

• query: Query criteria

Returns: Array of matching numbering plan entries

Example:

const mobileNumbers = validator.queryNumberingPlan({ 
  numberType: NumberType.MOBILE 
});
const vodacomNumbers = validator.queryNumberingPlan({ 
  operator: 'Vodacom' 
});

getNumberingPlanStatistics(): NumberingPlanStatistics

Gets comprehensive numbering plan statistics.

Returns: Statistics object with detailed breakdowns

Example:

const stats = validator.getNumberingPlanStatistics();
console.log(stats.totalNumbers); // Total available numbers
console.log(stats.byType[NumberType.MOBILE]); // Mobile numbers count
console.log(stats.byOperator['Vodacom Tanzania']); // Vodacom numbers count

validateCarrierSelection(carrierCode: string): boolean

Validates a carrier selection code.

Returns: true if valid, false otherwise

Example:

const isValid = validator.validateCarrierSelection('10');
console.log(isValid); // true

isNumberPortabilitySupported(numberType: NumberType): boolean

Checks if number portability is supported for a number type.

Returns: true if supported, false otherwise

Example:

const isPortable = validator.isNumberPortabilitySupported(NumberType.MOBILE);
console.log(isPortable); // true

getSignalingPointCodes(operator?: string): SignalingPointCode[]

Gets signaling point codes, optionally filtered by operator.

Returns: Array of signaling point codes

Example:

const allSpcs = validator.getSignalingPointCodes();
const vodacomSpcs = validator.getSignalingPointCodes('Vodacom');

getEmergencyServices(): EmergencyService[]

Gets all emergency services.

Returns: Array of emergency services

Example:

const services = validator.getEmergencyServices();
console.log(services); // Array of emergency services with codes and descriptions

Types

NumberValidationResult

interface NumberValidationResult {
  isValid: boolean;
  numberType: NumberType;
  operator?: string;
  region?: string;
  signalingPointCode?: string;
  emergencyService?: string;
  portabilityStatus?: PortabilityStatus;
  numberStatus?: NumberStatus;
  carrierSelection?: CarrierSelection;
  errors: string[];
  warnings: string[];
}

NumberType

enum NumberType {
  MOBILE = 'mobile',
  FIXED_LINE = 'fixed_line',
  TOLL_FREE = 'toll_free',
  PREMIUM_RATE = 'premium_rate',
  SHARED_COST = 'shared_cost',
  VOIP = 'voip',
  PAGING = 'paging',
  UAN = 'uan',
  EMERGENCY = 'emergency',
  SHORT_CODE = 'short_code',
  SIGNALING_POINT = 'signaling_point',
  INVALID = 'invalid'
}

PortabilityStatus

enum PortabilityStatus {
  PORTABLE = 'portable',
  NON_PORTABLE = 'non_portable',
  UNKNOWN = 'unknown'
}

NumberStatus

enum NumberStatus {
  ACTIVE = 'active',
  RESERVED = 'reserved',
  ASSIGNED = 'assigned',
  UNASSIGNED = 'unassigned',
  BLOCKED = 'blocked'
}

CarrierSelection

enum CarrierSelection {
  AUTOMATIC = 'automatic',
  MANUAL = 'manual',
  NOT_APPLICABLE = 'not_applicable'
}

ValidationOptions

interface ValidationOptions {
  strict?: boolean;
  allowInternational?: boolean;
  allowExtensions?: boolean;
  checkPortability?: boolean;
  checkCarrierSelection?: boolean;
  validateSignalingPoint?: boolean;
  allowReservedNumbers?: boolean;
}

NumberFormatOptions

interface NumberFormatOptions {
  format: 'national' | 'international' | 'e164' | 'rfc3966';
  includeExtension?: boolean;
  includeCarrierSelection?: boolean;
}

SignalingPointCode

interface SignalingPointCode {
  code: string;
  description: string;
  type: 'STP' | 'SSP' | 'SCP' | 'HLR' | 'VLR' | 'MSC' | 'GMSC' | 'SMSC' | 'MMSC';
  operator: string;
  location?: string;
  status: 'active' | 'inactive' | 'reserved';
}

EmergencyService

interface EmergencyService {
  code: string;
  service: string;
  description: string;
  priority: 'high' | 'medium' | 'low';
}

Supported Number Types

Mobile Numbers

| Operator | Prefixes | Example | Portability | |----------|----------|---------|-------------| | Vodacom Tanzania | 74,75,76 | 0743456789 | ✅ Portable | | Airtel Tanzania | 68, 69, 78 | 0683456789| ✅ Portable | | Tigo/Yas Tanzania | 65, 67, 71, 77 | 0712345678 | ✅ Portable | | Halotel | 61, 62 | 0612345678 | ✅ Portable | | Smile | 66 | 0661234567 | ✅ Portable |

Fixed Line Numbers

| Region | Prefixes | Example | Portability | |--------|----------|---------|-------------| | Dar es Salaam | 22-29 | 0221234567 | ❌ Non-portable | | Arusha | 30-39 | 0271234567 | ❌ Non-portable | | Dodoma | 40-49 | 0401234567 | ❌ Non-portable | | Mbeya | 50-59 | 0501234567 | ❌ Non-portable | | Mwanza | 60, 70, 80, 90 | 0601234567 | ❌ Non-portable |

Emergency Numbers

| Code | Service | Description | Priority | |------|---------|-------------|----------| | 112 | Emergency Services | General emergency number | High | | 113 | Police | Police emergency services | High | | 114 | Fire Brigade | Fire and rescue services | High | | 115 | Ambulance | Medical emergency services | High | | 116 | Traffic Police | Traffic and road safety | Medium | | 117 | Coast Guard | Maritime emergency services | High | | 118 | Electricity Emergency | Power grid emergency services | Medium | | 119 | Water Emergency | Water supply emergency services | Medium |

Short Codes

| Range | Example | Description | |-------|---------|-------------| | 100-109 | 100 | Service short codes | | 150-159 | 150 | Additional short codes |

Special Service Numbers

| Service Type | Prefixes | Example | Format | |--------------|----------|---------|--------| | Toll-Free | 0800-0809 | 0800123456 | 4+6 digits | | Premium Rate | 0900-0909 | 0900123456 | 4+6 digits | | Shared Cost | 0700-0709 | 0700123456 | 4+6 digits | | VoIP | 0200-0209 | 0200123456 | 4+6 digits | | Paging | 0100-0109 | 0100123456 | 4+6 digits | | UAN | 0300-0309 | 0300123456 | 4+6 digits |

Signaling Point Codes

| Type | Description | Example | Operator | |------|-------------|---------|----------| | STP | Signal Transfer Point | 255-001-001 | Vodacom | | HLR | Home Location Register | 255-001-101 | Vodacom | | VLR | Visitor Location Register | 255-001-201 | Vodacom | | MSC | Mobile Switching Center | 255-001-301 | Vodacom | | SMSC | Short Message Service Center | 255-001-401 | Vodacom |

Examples

Basic Validation

import { TCRANumberValidator, NumberType } from 'tcra-num-check';

const validator = new TCRANumberValidator();

// Mobile number validation
const mobileResult = validator.validate('0712345678');
console.log(mobileResult.isValid); // true
console.log(mobileResult.numberType); // NumberType.MOBILE
console.log(mobileResult.operator); // 'Airtel Tanzania'

// Fixed line validation
const fixedResult = validator.validate('0221234567');
console.log(fixedResult.isValid); // true
console.log(fixedResult.numberType); // NumberType.FIXED_LINE
console.log(fixedResult.region); // 'Dar es Salaam'

// Emergency number validation
const emergencyResult = validator.validate('112');
console.log(emergencyResult.isValid); // true
console.log(emergencyResult.numberType); // NumberType.EMERGENCY
console.log(emergencyResult.emergencyService); // 'Emergency Services'

// Invalid number
const invalidResult = validator.validate('123456');
console.log(invalidResult.isValid); // false
console.log(invalidResult.numberType); // NumberType.INVALID

Advanced Validation

// Validation with portability check
const result = validator.validate('0712345678', { 
  checkPortability: true,
  validateSignalingPoint: true 
});

console.log(result.portabilityStatus); // PortabilityStatus.PORTABLE
console.log(result.numberStatus); // NumberStatus.ACTIVE
console.log(result.carrierSelection); // CarrierSelection.AUTOMATIC

// International format validation
const internationalResult = validator.validate('+255712345678', { 
  allowInternational: true 
});
console.log(internationalResult.isValid); // true

Number Formatting

// Different format options
const number = '0712345678';

console.log(validator.formatInternational(number)); // '+255712345678'
console.log(validator.formatNational('+255712345678')); // '0712345678'
console.log(validator.formatNumber(number, { format: 'e164' })); // '+255712345678'
console.log(validator.formatNumber(number, { format: 'rfc3966' })); // 'tel:+255712345678'

Numbering Plan Queries

// Query by number type
const mobileNumbers = validator.queryNumberingPlan({ 
  numberType: NumberType.MOBILE 
});
console.log(mobileNumbers.length); // Number of mobile prefixes

// Query by operator
const vodacomNumbers = validator.queryNumberingPlan({ 
  operator: 'Vodacom' 
});
console.log(vodacomNumbers[0].operator); // 'Vodacom Tanzania'

// Get statistics
const stats = validator.getNumberingPlanStatistics();
console.log(`Total numbers: ${stats.totalNumbers}`);
console.log(`Mobile numbers: ${stats.byType[NumberType.MOBILE]}`);
console.log(`Vodacom numbers: ${stats.byOperator['Vodacom Tanzania']}`);

Signaling Point Codes

// Get all signaling point codes
const allSpcs = validator.getSignalingPointCodes();
console.log(allSpcs.length); // Total number of SPCs

// Get SPCs by operator
const vodacomSpcs = validator.getSignalingPointCodes('Vodacom');
vodacomSpcs.forEach(spc => {
  console.log(`${spc.code}: ${spc.description} (${spc.type})`);
});

// Validate SPC
const spcResult = validator.validate('255001001', { 
  validateSignalingPoint: true 
});
console.log(spcResult.numberType); // NumberType.SIGNALING_POINT
console.log(spcResult.signalingPointCode); // '255-001-001'

Emergency Services

// Get all emergency services
const services = validator.getEmergencyServices();
services.forEach(service => {
  console.log(`${service.code}: ${service.service} (${service.priority} priority)`);
});

// Validate emergency number
const emergencyResult = validator.validate('113');
console.log(emergencyResult.emergencyService); // 'Police'

Carrier Selection

// Validate carrier selection codes
const validCodes = ['10', '11', '12', '13', '14', '15', '16', '17', '18', '19'];
validCodes.forEach(code => {
  console.log(`${code}: ${validator.validateCarrierSelection(code)}`);
});

Further Usage Examples

1. Bulk Validation of Numbers

You can validate a list of numbers efficiently using Array.map:

const numbers = ['0712345678', '0221234567', '112', '123456'];
const results = numbers.map(num => validator.validate(num));
results.forEach((result, idx) => {
  console.log(`${numbers[idx]}: ${result.isValid ? 'Valid' : 'Invalid'} (${result.numberType})`);
});

2. Handling Errors and Warnings

The validator provides detailed error and warning messages for each number:

const result = validator.validate('123456');
if (!result.isValid) {
  console.error('Validation failed:', result.errors);
  if (result.warnings.length) {
    console.warn('Warnings:', result.warnings);
  }
}

3. Customizing Features and Modes

You can enable or disable specific features, or switch between validation modes:

// Switch to 'full' mode for comprehensive validation
validator.setMode('full');

// Enable only mobile and emergency validation
validator.updateFeatures({
  validateMobile: true,
  validateEmergency: true,
  validateFixedLine: false,
  validateShortCode: false,
});

// Validate with per-call feature overrides
const result = validator.validate('0712345678', {
  features: { validatePortability: true, validateSignalingPoint: false }
});

4. Using a Custom Numbering Plan

You can provide your own numbering plan for special use cases:

import { TCRANumberValidator } from 'tcra-num-check';
import { myCustomPlan } from './myCustomPlan';

const customValidator = new TCRANumberValidator({ numberingPlan: myCustomPlan });
const result = customValidator.validate('0999999999');
console.log(result);

5. Troubleshooting Common Issues

• Number not recognized: Ensure the number matches the expected format and prefix for Tanzanian numbers.
• International numbers rejected: Set allowInternational: true in options or features.
• Missing portability or signaling point info: Enable validatePortability or validateSignalingPoint in features or options.
• Custom plan not working: Double-check your custom numbering plan structure matches the expected schema.

For more help, see the API reference and the source code in src/validator.ts.

Contributing

1. Create a feature branch
2. Make your changes
3. Add tests for new functionality
4. Run the test suite
5. Submit a pull request

Testing

npm test

Run tests in watch mode:

npm run test:watch

License

MIT License - see LICENSE file for details.

References

• TCRA National Numbering Plan
• ITU-T Q.700 Series - Signaling System No. 7
• E.164 International Numbering Plan
• RFC 3966 - The tel URI for Telephone Numbers