contact-co (JavaScript)

Librería de validación sociodemográfica y legal para contacto en Colombia. Puerto JavaScript del paquete Python contact-co publicado en PyPI.

Instalación

npm install contact-co

O localmente durante desarrollo:

npm install ../contact-co

Uso

import { ContactScorer } from 'contact-co';

const scorer = new ContactScorer();

const resultado = scorer.getContactScore('+573001234567');
console.log(resultado);
// {
//   score: 95,
//   status: 'EXCELLENT',
//   reason: 'Franja Alta Efectividad (General)',
//   region: 'General'
// }

Exportaciones disponibles

| Clase | Equivalente Python | Descripción | |----------------------|-----------------------|------------------------------------------------------| | ContactScorer | ContactScorer | Clase principal — evalúa el score de contacto | | LegalCheck | LegalCheck | Valida horarios y festivos colombianos | | ZoneDetector | ZoneDetector | Detecta región por número telefónico | | ColombiaDataFetcher| ColombiaDataFetcher | Descarga datos ENUT de datos.gov.co |

API

ContactScorer.getContactScore(phone, regionHint?, timestamp?)

| Parámetro | Tipo | Descripción | |--------------|------------------|-------------------------------------------------------| | phone | string | Número telefónico colombiano | | regionHint | string \| null | Región conocida ('Caribe', 'Andina'). Opcional. | | timestamp | Date \| null | Fecha/hora a evaluar. Si es null usa el momento actual. |

Retorna:

{
  score: 0 | 20 | 60 | 95,         // Puntaje de efectividad
  status: 'PROHIBITED' | 'POOR' | 'NORMAL' | 'EXCELLENT',
  reason: string,                   // Explicación
  region: string                    // Región detectada
}

Ejecutar pruebas

node src/test_manual.js

Dependencias

• google-libphonenumber — equivalente a phonenumbers de Python
• Festivos colombianos calculados internamente — equivalente a holidays de Python
• fetch nativo de Node.js ≥18 — equivalente a sodapy + requests de Python

Licencia

Licencia Propietaria — Todos los Derechos Reservados. Ver archivo LICENSE para más detalles.

© Copyright 2026 Alejandro Galicia [email protected]
Todos los derechos reservados. Protegido bajo la Ley 23 de 1982 (Colombia) y el Convenio de Berna.