simujs/README.md

Tanzanian phone number detection library based on public TCRA numbering data (not affiliated with TCRA).

# **SimuJS**

> 🇹🇿 Tanzanian phone number detection & classification library

**SimuJS** is a lightweight TypeScript library that identifies Tanzanian phone numbers and determines their mobile network, service type, and validity — based on official **TCRA's** National Numbering and Signaling Point Codes Plans.

---

## 📄 Disclaimer

> **Important Notice**

This package is **not affiliated with, endorsed by, or officially supported by** the Tanzania Communications Regulatory Authority (TCRA).

The data and logic used in this library are **derived from publicly available information** contained in the following official document:

**Document Title:** _National Numbering and Signaling Point Codes Plans_
**Institution:** Tanzania Communications Regulatory Authority (TCRA)
**Document Number:** TCRA/DICT/CRTM/PLA-GUD/001
**Version:** 1.15
**Release Date:** July 2025
**Classification:** Public

This package is an **independent implementation** created for developer convenience and educational use.
While reasonable effort has been made to ensure accuracy, **no guarantee is provided** that the information is complete, current, or suitable for regulatory or commercial decision-making.

For official and authoritative information, always refer directly to publications issued by the **Tanzania Communications Regulatory Authority (TCRA)**.

---

## ✨ Features

-   ✅ Detect Tanzanian mobile operators (Vodacom, Airtel, Yas, Halotel, TTCL, etc.)
-   ✅ Supports M2M, toll-free & special services
-   ✅ Normalizes phone numbers safely
-   ✅ Predictable, typed results (no throwing)
-   ✅ Built on official TCRA allocations as of July 2025
-   ✅ TypeScript-first

---

## 📦 Installation

Using npm:

```bash
npm install simujs
```

Via yarn:

```bash
yarn add simujs
```

---

## 🚀 Usage

### Basic usage

```ts
import { simu } from 'simujs';

const result = simu('0754123456');

if (result.ok) {
    console.log(result.operator.name);
    // Vodacom Tanzania
} else {
    console.error(result.reason);
}
```

---

## 🧠 Return Type

`simu()` never throws — it always returns a predictable result:

```ts
type SimuResult = { ok: true; operator: Operator } | { ok: false; reason: 'INVALID_NUMBER' | 'UNKNOWN_OPERATOR' };
```

---

## 📱 Supported Number Formats

All of the following are accepted:

-   `+255754123456`
-   `0754123456`
-   `754123456`

The number **must belong to Tanzania**.

---

## 🧾 Example Output

```ts
{
  ok: true,
  operator: {
    name: "Vodacom Tanzania",
    company: "Vodacom Tanzania PLC",
    service: "Mobile",
    financialService: "M-Pesa",
    status: "Operational"
  }
}
```

---

## 🔍 Supported Operators

| Operator          | Service               |
| ----------------- | --------------------- |
| Vodacom Tanzania  | Mobile / M-Pesa       |
| Airtel Tanzania   | Mobile / Airtel Money |
| Yas Tanzania      | Mobile / Mixx         |
| Halotel           | Mobile / HaloPesa     |
| TTCL              | Mobile / T-Pesa       |
| M2M Services      | Machine-to-Machine    |
| Toll-Free Numbers | Special Services      |

---

## 🧪 Validation & Errors

```ts
simu('123');
// { ok: false, reason: "INVALID_NUMBER" }

simu('0700000000');
// { ok: false, reason: "UNKNOWN_OPERATOR" }
```

---

## 🧰 Advanced Usage

### Normalize a number

```ts
import { normalize } from 'simu';

normalize('+255754123456'); // "754123456"
```

---

## 📦 Package Info

-   Fully typed
-   Tree-shakeable
-   ESM compatible
-   Zero runtime dependencies (except google-libphonenumber)

---

## 🧱 Built With

-   [`google-libphonenumber`](https://github.com/google/libphonenumber)
-   TypeScript

---

## 🧑‍💻 Author

**Adeodatus Ludan**

---

## 🔄 Changelog

### v2.0.0

-   New result-based API (`{ ok, operator }`)
-   Improved normalization
-   Support for M2M and special services
-   Safer error handling
-   Full test coverage

---

## 📄 License

MIT