📱 @williamtessa27/cm-phone-lookup

Une librairie JavaScript professionnelle pour la détection d'opérateurs mobiles multi-pays avec API unifiée, validation avancée et métadonnées enrichies. Supporte 21 pays africains : Cameroun 🇨🇲, Sénégal 🇸🇳, Côte d'Ivoire 🇨🇮, Nigeria 🇳🇬, Ghana 🇬🇭, Kenya 🇰🇪, Afrique du Sud 🇿🇦, Maroc 🇲🇦, Éthiopie 🇪🇹, Égypte 🇪🇬, Tanzanie 🇹🇿, RDC 🇨🇩, Ouganda 🇺🇬, Rwanda 🇷🇼, Algérie 🇩🇿, Mali 🇲🇱, Soudan 🇸🇩, Mozambique 🇲🇿, Angola 🇦🇴, Burkina Faso 🇧🇫, Soudan du Sud 🇸🇸 avec plus de 80+ opérateurs (MTN, Orange, Vodacom, Safaricom, Airtel, Ethio Telecom, Vodafone Egypt, Halotel, Mobilis, Djezzy, Ooredoo, Zain Sudan, Movitel, Tmcel, Unitel, Movicel, Africell Angola, Telecel Faso, Zain South Sudan, etc.) à partir d'un numéro de téléphone.
Compatible JavaScript et TypeScript.

🚀 Installation

npm install @williamtessa27/cm-phone-lookup
# ou
yarn add @williamtessa27/cm-phone-lookup
# ou
pnpm add @williamtessa27/cm-phone-lookup

📖 Utilisation

🎯 NOUVEAU : API Unifiée avec PhoneLookup.analyze()

import { PhoneLookup } from '@williamtessa27/cm-phone-lookup';

// Analyse complète en une seule fonction !
const result = PhoneLookup.analyze('+233241234567');
console.log(`${result.country?.flag} ${result.country?.name}: ${result.operator}`);
// 🇬🇭 Ghana: GHANA_MTN

// Métadonnées complètes incluses
console.log(`Capitale: ${result.country?.capital}`);
console.log(`Population: ${result.country?.population}`);
console.log(`Devise: ${result.country?.currency}`);
console.log(`Fuseau: ${result.country?.timezone}`);

🔗 NOUVEAU : Méthodes Chainées (Fluent API)

import { PhoneLookup } from '@williamtessa27/cm-phone-lookup';

const result = new PhoneLookup('+237650123456')
  .validate()
  .format()
  .getInfo();

console.log(`${result.country?.flag} ${result.country?.name}`);
// 🇨🇲 Cameroon

⚙️ NOUVEAU : Configuration Flexible

import { PhoneLookup } from '@williamtessa27/cm-phone-lookup';

const lookup = new PhoneLookup('+233241234567', {
  strictMode: true,        // Validation stricte
  autoFormat: false,       // Désactiver le formatage automatique
  language: 'en',          // Langue anglaise
  includeMetadata: true,   // Inclure les métadonnées
  throwOnError: false      // Ne pas lancer d'exceptions
});

🚨 NOUVEAU : Gestion d'Erreurs Avancée

import { PhoneLookup, validatePhoneNumber } from '@williamtessa27/cm-phone-lookup';

try {
  const result = PhoneLookup.analyze('123', { throwOnError: true });
} catch (error) {
  if (error.code === 'INVALID_COUNTRY_CODE') {
    console.log('Codes supportés:', error.suggestions);
  }
}

// Validation avec messages d'erreur détaillés
const validation = validatePhoneNumber('123');
if (!validation.isValid) {
  validation.errors.forEach(error => {
    console.log(`${error.code}: ${error.message}`);
    if (error.suggestion) {
      console.log(`💡 Suggestion: ${error.suggestion}`);
    }
  });
}

📊 NOUVEAU : Statistiques Globales

import { PhoneLookup } from '@williamtessa27/cm-phone-lookup';

const stats = PhoneLookup.getStats();
console.log(`🌍 Total pays: ${stats.totalCountries}`);
console.log(`📱 Total opérateurs: ${stats.totalOperators}`);

stats.countries.forEach(country => {
  console.log(`${country.flag} ${country.name}: ${country.operators} opérateurs`);
});

🌍 NOUVEAU : Métadonnées des Pays

import { getCountryMetadata, getAllCountries } from '@williamtessa27/cm-phone-lookup';

// Obtenir les métadonnées d'un pays
const ghana = getCountryMetadata('233');
console.log(`${ghana?.flag} ${ghana?.name} (${ghana?.nameLocal})`);
console.log(`Capitale: ${ghana?.capital}`);
console.log(`Population: ${ghana?.population}`);
console.log(`Devise: ${ghana?.currency}`);

// 🇨🇲 Cameroun : Exemple de bilinguisme officiel
const cameroon = getCountryMetadata('237');
console.log(`${cameroon?.flag} ${cameroon?.name} (${cameroon?.nameLocal})`);
console.log(`Langues: ${Array.isArray(cameroon?.language) ? cameroon?.language.join(' + ') : cameroon?.language}`);
// Affiche: "Langues: fr + en" (Français + Anglais)

// Autres pays : Langue unique
const senegal = getCountryMetadata('221');
console.log(`Langue: ${senegal?.language}`); // "fr" (Français uniquement)

// Liste de tous les pays supportés
const countries = getAllCountries();
console.log('Pays supportés:', countries);

📱 API Classique (Toujours Disponible)

import { detectOperator, isValidNumber, getPhoneInfo, formatPhoneNumber } from '@williamtessa27/cm-phone-lookup';

// Cameroun
const operatorCM = detectOperator('+237650123456');
console.log(operatorCM); // "CAMEROON_MTN"

// Sénégal
const operatorSN = detectOperator('+221771234567');
console.log(operatorSN); // "SENEGAL_ORANGE"

// Éthiopie
const operatorET = detectOperator('+25191123456');
console.log(operatorET); // "ETHIOPIA_ETHIO_TELECOM"

// Égypte
const operatorEG = detectOperator('+201012345678');
console.log(operatorEG); // "EGYPT_VODAFONE"

// Tanzanie
const operatorTZ = detectOperator('+255741234567');
console.log(operatorTZ); // "TANZANIA_VODACOM"

// RDC (République Démocratique du Congo)
const operatorCD = detectOperator('+243811234567');
console.log(operatorCD); // "DRC_VODACOM"

// Angola
const operatorAO = detectOperator('+244911234567');
console.log(operatorAO); // "ANGOLA_UNITEL"

// Burkina Faso
const operatorBF = detectOperator('+22670123456');
console.log(operatorBF); // "BURKINA_FASO_ORANGE"

// Soudan du Sud
const operatorSS = detectOperator('+211921234567');
console.log(operatorSS); // "SOUTH_SUDAN_MTN"

// Ouganda
const operatorUG = detectOperator('+256771234567');
console.log(operatorUG); // "UGANDA_MTN"

// Rwanda
const operatorRW = detectOperator('+250781234567');
console.log(operatorRW); // "RWANDA_MTN"

// Algérie
const operatorDZ = detectOperator('+213512345678');
console.log(operatorDZ); // "ALGERIA_MOBILIS"

// Mali
const operatorML = detectOperator('+22370123456');
console.log(operatorML); // "MALI_ORANGE"

// Soudan
const operatorSD = detectOperator('+24991123456');
console.log(operatorSD); // "SUDAN_ZAIN"

// Mozambique
const operatorMZ = detectOperator('+25882123456');
console.log(operatorMZ); // "MOZAMBIQUE_VODACOM"

// Côte d'Ivoire
const operatorCI = detectOperator('+22501234567');
console.log(operatorCI); // "IVORY_COAST_ORANGE"

// Nigeria
const operatorNG = detectOperator('+2340803123456');
console.log(operatorNG); // "NIGERIA_MTN"

// Ghana
const operatorGH = detectOperator('+233241234567');
console.log(operatorGH); // "GHANA_MTN"

// Kenya
const operatorKE = detectOperator('+254700123456');
console.log(operatorKE); // "KENYA_SAFARICOM"

// Afrique du Sud
const operatorZA = detectOperator('+27721234567');
console.log(operatorZA); // "SOUTH_AFRICA_VODACOM"

// Maroc
const operatorMA = detectOperator('+212612345678');
console.log(operatorMA); // "MOROCCO_MAROC_TELECOM"

Validation de numéro

import { isValidNumber } from '@williamtessa27/cm-phone-lookup';

const isValid = isValidNumber('+237650123456');
console.log(isValid); // true

Information complète

import { getPhoneInfo } from '@williamtessa27/cm-phone-lookup';

const info = getPhoneInfo('+237650123456');
console.log(info);
// {
//   operator: "CAMEROON_MTN",
//   isValid: true,
//   countryCode: "+237",
//   localNumber: "650123456",
//   formattedNumber: "+237 650 123 456",
//   isMobile: true,
//   isFixed: false,
//   length: 9
// }

Formatage de numéro

import { formatPhoneNumber } from '@williamtessa27/cm-phone-lookup';

const formatted = formatPhoneNumber('+237650123456');
console.log(formatted); // "+237 650 123 456"

Obtenir les préfixes d'un opérateur

import { getOperatorPrefixes } from '@williamtessa27/cm-phone-lookup';

const mtnPrefixes = getOperatorPrefixes('CAMEROON_MTN');
console.log(mtnPrefixes); // ["650", "651", "652", "653", "654", "680", "681", "682", "683", "684"]

Vérifier si un préfixe appartient à un opérateur

import { isPrefixForOperator } from '@williamtessa27/cm-phone-lookup';

const isMtn = isPrefixForOperator('650', 'CAMEROON_MTN');
console.log(isMtn); // true

🏗️ Opérateurs supportés

🔧 API Reference

🆕 NOUVEAU : Classe PhoneLookup

PhoneLookup.analyze(phone: string, options?: PhoneLookupOptions): EnhancedPhoneInfo

Analyse complète d'un numéro de téléphone avec toutes les informations et métadonnées.

PhoneLookup.validate(phone: string, options?: PhoneLookupOptions): boolean

Validation rapide d'un numéro de téléphone.

PhoneLookup.getOperator(phone: string): string

Détection rapide de l'opérateur.

PhoneLookup.format(phone: string): string

Formatage rapide d'un numéro.

PhoneLookup.getStats()

Obtient les statistiques globales de la librairie.

Méthodes d'instance avec chaînage :

const result = new PhoneLookup('+233241234567')
  .validate()    // Valide le numéro
  .format()      // Formate le numéro
  .getInfo();    // Obtient toutes les informations

API Classique (Toujours Disponible)

detectOperator(phone: string): Operator

Détecte l'opérateur mobile à partir d'un numéro de téléphone multi-pays.

Paramètres:

• phone (string): Le numéro de téléphone (avec ou sans code pays)

Retourne:

• Operator: L'opérateur détecté ou "Unknown"

isValidNumber(phone: string): boolean

Valide si un numéro de téléphone multi-pays est valide.

Paramètres:

• phone (string): Le numéro de téléphone à valider

Retourne:

• boolean: true si le numéro est valide, false sinon

getPhoneInfo(phone: string): PhoneInfo

Obtient des informations complètes sur un numéro de téléphone.

Paramètres:

• phone (string): Le numéro de téléphone

Retourne:

• PhoneInfo: Un objet avec toutes les informations du numéro

formatPhoneNumber(phone: string): string

Formate un numéro de téléphone en format lisible.

Paramètres:

• phone (string): Le numéro de téléphone

Retourne:

• string: Le numéro formaté avec espaces

getOperatorPrefixes(operator: Operator): string[]

Obtient tous les préfixes d'un opérateur spécifique.

Paramètres:

• operator (Operator): L'opérateur

Retourne:

• string[]: Liste des préfixes de l'opérateur

getSupportedOperators(): Operator[]

Obtient la liste de tous les opérateurs supportés.

Retourne:

• Operator[]: Liste de tous les opérateurs

isPrefixForOperator(prefix: string, operator: Operator): boolean

Vérifie si un préfixe appartient à un opérateur spécifique.

Paramètres:

• prefix (string): Le préfixe à vérifier
• operator (Operator): L'opérateur

Retourne:

• boolean: true si le préfixe appartient à l'opérateur

🆕 NOUVEAU : Validation Avancée

validatePhoneNumber(phone: string): ValidationResult

Valide un numéro avec messages d'erreur détaillés et suggestions.

PhoneValidationError

Classe d'erreur personnalisée avec codes d'erreur et suggestions.

🆕 NOUVEAU : Métadonnées des Pays

getCountryMetadata(countryCode: string): CountryMetadata | null

Obtient les métadonnées complètes d'un pays.

💡 Note sur les langues : Le Cameroun 🇨🇲 est le seul pays bilingue officiel (français + anglais) dans notre librairie. Son champ language retourne ['fr', 'en'], tandis que les autres pays retournent une seule langue.

getAllCountries(): string[]

Obtient la liste de tous les codes pays supportés.

getCountryByCode(code: string): CountryMetadata | null

Recherche un pays par son code.

📱 Types

Operator

type Operator = "CAMEROON_MTN" | "CAMEROON_ORANGE" | "CAMEROON_CAMTEL" | "CAMEROON_NEXTTEL" | "SENEGAL_ORANGE" | "SENEGAL_TIGO" | "SENEGAL_EXPRESSO" | "IVORY_COAST_ORANGE" | "IVORY_COAST_MTN" | "IVORY_COAST_MOOV" | "IVORY_COAST_TELECOM" | "NIGERIA_MTN" | "NIGERIA_AIRTEL" | "NIGERIA_GLO" | "NIGERIA_9MOBILE" | "GHANA_MTN" | "GHANA_VODAFONE" | "GHANA_AIRTELTIGO" | "Unknown";

PhoneInfo

interface PhoneInfo {
  operator: Operator;
  isValid: boolean;
  countryCode: string;
  localNumber: string;
  formattedNumber: string;
  isMobile: boolean;
  isFixed: boolean;
  length: number;
}

🆕 NOUVEAU : EnhancedPhoneInfo

interface EnhancedPhoneInfo extends PhoneInfo {
  phone: string;
  country: CountryMetadata | undefined;
  errors: string[] | undefined;
  suggestions: string[] | undefined;
}

🆕 NOUVEAU : CountryMetadata

interface CountryMetadata {
  name: string;
  nameLocal: string;
  flag: string;
  language: string | string[]; // Support pour langues multiples (Cameroun bilingue)
  currency: string;
  timezone: string;
  population?: string;
  capital?: string;
}

🆕 NOUVEAU : PhoneLookupOptions

interface PhoneLookupOptions {
  strictMode?: boolean;
  autoFormat?: boolean;
  language?: 'fr' | 'en';
  includeMetadata?: boolean;
  throwOnError?: boolean;
}

🆕 NOUVEAU : ValidationError

interface ValidationError {
  code: string;
  message: string;
  field: string | undefined;
  value: string | undefined;
  suggestion: string | undefined;
}

🧪 Tests

# Construire le projet
npm run build

# Lancer les tests classiques
npm test

# Lancer les tests des nouvelles fonctionnalités
node dist/test-enhanced.js

# Mode développement
npm run dev

# Nettoyer le dossier dist
npm run clean

🚀 Développement

# Cloner le repository
git clone https://github.com/williamtessa27/cm-phone-lookup.git

# Installer les dépendances
npm install

# Mode développement avec rechargement automatique
npm run dev

# Construire le projet
npm run build

📋 Fonctionnalités

✅ Fonctionnalités Classiques

• Détection automatique des opérateurs multi-pays
• Support multi-pays : Cameroun (+237), Sénégal (+221), Côte d'Ivoire (+225), Nigeria (+234), Ghana (+233), Kenya (+254), Afrique du Sud (+27), Maroc (+212), Éthiopie (+251), Égypte (+20), Tanzanie (+255), RDC (+243), Ouganda (+256), Rwanda (+250), Algérie (+213)
• Validation complète des numéros de téléphone par pays
• Support TypeScript avec types complets
• Formatage automatique des numéros adapté au pays
• Informations détaillées sur chaque numéro
• Gestion des préfixes pour chaque opérateur
• Tests complets pour toutes les fonctionnalités
• Documentation complète en français et anglais
• Compatibilité Node.js et navigateurs

🆕 NOUVELLES FONCTIONNALITÉS V1.5.0

• API unifiée avec PhoneLookup.analyze() pour une analyse complète
• Méthodes chainées (Fluent API) pour un code plus lisible
• Configuration flexible avec options personnalisables
• Validation avancée avec messages d'erreur détaillés et suggestions
• Métadonnées enrichies des pays (drapeaux, capitales, populations, devises, fuseaux, langues officielles)
• Bilinguisme du Cameroun 🇨🇲 : Support officiel français + anglais avec language: ['fr', 'en']
• Gestion d'erreurs robuste avec codes d'erreur spécifiques
• Méthodes statiques pour un usage rapide et simple
• Statistiques globales de la librairie
• Interface utilisateur améliorée pour une meilleure expérience développeur

🌍 Cas d'usage

• Applications web nécessitant la validation de numéros multi-pays africains
• Formulaires avec vérification automatique d'opérateur par pays
• Systèmes de SMS avec routage par opérateur et par pays
• Analytics sur l'utilisation des opérateurs par pays
• Validation de numéros dans les bases de données multi-pays
• Applications internationales nécessitant le support de plusieurs pays africains
• Dashboards avec métadonnées pays et statistiques opérateurs
• Systèmes de support client avec détection automatique du pays et de l'opérateur

🤝 Contribution

Les contributions sont les bienvenues ! N'hésitez pas à :

1. Fork le projet
2. Créer une branche pour votre fonctionnalité
3. Commiter vos changements
4. Pousser vers la branche
5. Ouvrir une Pull Request

📄 Licence

Ce projet est sous licence MIT. Voir le fichier LICENSE pour plus de détails.

🙏 Remerciements

• Tous les opérateurs télécoms des 15 pays africains supportés
• Les communautés développeurs africaines
• Tous les contributeurs open-source

Made with ❤️ across Africa 🌍 - Supporting 15 African countries: 🇨🇲🇸🇳🇨🇮🇳🇬🇬🇭🇰🇪🇿🇦🇲🇦🇪🇹🇪🇬🇹🇿🇨🇩🇺🇬🇷🇼🇩🇿

Changelog

Toutes les modifications notables de ce projet seront documentées dans ce fichier.

Le format est basé sur Keep a Changelog, et ce projet adhère au Semantic Versioning.

[1.12.0] - 2024-12-19

✨ Ajouté

• 3 nouveaux pays africains supportés :
  • 🇦🇴 Angola (+244) avec 3 opérateurs :
    • Unitel (préfixes 91, 92)
    • Movicel (préfixe 93)
    • Africell Angola (préfixes 94, 95)
  • 🇧🇫 Burkina Faso (+226) avec 3 opérateurs :
    • Orange Burkina Faso (préfixes 70, 71, 72)
    • Moov Africa Burkina Faso (préfixes 74, 75)
    • Telecel Faso (préfixe 76)
  • 🇸🇸 Soudan du Sud (+211) avec 2 opérateurs :
    • MTN South Sudan (préfixes 92, 95)
    • Zain South Sudan (préfixes 91, 97)

📊 Statistiques mises à jour

• 21 pays africains supportés (était 18)
• 80+ opérateurs supportés (était 75+)
• 8 nouveaux opérateurs ajoutés

🔧 Améliorations

• Mise à jour de tous les fichiers de validation pour supporter les nouveaux codes pays
• Ajout des métadonnées complètes pour les nouveaux pays (capitale, population, devise, fuseau horaire)
• Mise à jour des statistiques globales dans PhoneLookup.getStats()
• Amélioration de la couverture de tests (250 tests passent)

📚 Documentation

• Mise à jour du README avec les nouveaux pays et opérateurs
• Ajout d'exemples pour les nouveaux pays dans usage.js et usage.ts
• Mise à jour des tableaux d'opérateurs dans la documentation
• Ajout des drapeaux 🇦🇴🇧🇫🇸🇸 dans tous les fichiers de documentation

🧪 Tests

• Ajout de tests complets pour les 3 nouveaux pays
• Tests de détection d'opérateur, validation, formatage et métadonnées
• Tests d'intégration avec l'API unifiée PhoneLookup
• Tous les tests passent (250/250) ✅

🚀 Compatibilité

• Compatibilité ascendante complète maintenue
• Aucun changement cassant (breaking change)
• Support TypeScript et JavaScript inchangé

[1.11.0] - 2024-11-XX

✨ Ajouté

• Support de 7 nouveaux pays africains : RDC, Ouganda, Rwanda, Algérie, Mali, Soudan, Mozambique
• API unifiée avec PhoneLookup.analyze()
• Métadonnées enrichies des pays
• Validation avancée avec gestion d'erreurs détaillée

📊 Statistiques

• 18 pays africains supportés
• 75+ opérateurs supportés

[1.10.0] et versions antérieures

Voir les releases GitHub pour l'historique complet des versions précédentes.