whatsapp-crm-common/README.md

Componentes compartidos para servicios de WhatsApp CRM - Common utilities and types for WhatsApp CRM system

# whatsapp-crm-common

[![npm version](https://badge.fury.io/js/whatsapp-crm-common.svg)](https://badge.fury.io/js/whatsapp-crm-common)
[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)

Paquete compartido con tipos, utilidades e infraestructura común para los servicios WhatsApp CRM.

## 🚀 Características

- **Sistema Híbrido de Eventos**: BullMQ para persistencia + Redis Pub/Sub para tiempo real
- **Colas Especializadas**: 4 colas optimizadas (realtime, bulk, webhook, notifications)
- **Tipos TypeScript Completos**: Interfaces para todas las entidades de dominio
- **Logging Estructurado**: Sistema de logs con Pino y contexto automático
- **Gestión de Sesiones**: Soporte multi-tenant con agentes múltiples
- **Utilidades WhatsApp**: Formateo de números, extracción de contenido de mensajes

## 📦 Instalación

```bash
npm install whatsapp-crm-common
```

## 🔧 Configuración

### Opción 1: Variables de entorno (Recomendado)

Crea un archivo `.env` en tu proyecto:

```bash
# Copia el archivo de ejemplo desde el paquete
cp node_modules/whatsapp-crm-common/.env.example .env

# O crea tu propio .env con estas variables:
# Redis Configuration
REDIS_URL=redis://localhost:6379
REDIS_HOST=localhost
REDIS_PORT=6379
REDIS_PASSWORD=
REDIS_DB=0

# Database Configuration
DATABASE_URL=postgresql://user:password@localhost:5432/whatsapp_crm
DATABASE_HOST=localhost
DATABASE_PORT=5432
DATABASE_NAME=whatsapp_crm
DATABASE_USER=postgres
DATABASE_PASSWORD=

# Logging
LOG_LEVEL=info
NODE_ENV=development

# Queue Configuration
ENABLE_MESSAGE_QUEUE=true
WORKER_ENABLED=true
QUEUE_CONCURRENCY=5
MAX_SESSIONS_PER_PROCESS=100

# WhatsApp Configuration
WEBHOOK_URL=http://localhost:3000/webhook
MAX_RECONNECT_ATTEMPTS=5
QR_TIMEOUT_MS=60000
SYNC_FULL_HISTORY=false
```

### Opción 2: Configuración programática

```typescript
import { configureWhatsAppCommon } from 'whatsapp-crm-common';

configureWhatsAppCommon({
  redis: {
    url: 'redis://mi-servidor:6379',
    password: 'mi-password',
    db: 1
  },
  database: {
    url: 'postgresql://user:pass@localhost:5432/mi_db'
  },
  logging: {
    level: 'debug'
  },
  queue: {
    enabled: true,
    concurrency: 10
  },
  webhook: {
    url: 'https://mi-webhook.com/whatsapp'
  }
});
```

### Opción 3: Configuración mixta

El paquete seguirá esta **prioridad**:
1. **Configuración programática** (la más alta)
2. **Variables de entorno** de tu proyecto
3. **Valores por defecto** del paquete

```typescript
// Ejemplo: Configurar solo Redis programáticamente,
// el resto se tomará de variables de entorno o defaults
configureWhatsAppCommon({
  redis: {
    url: process.env.CUSTOM_REDIS_URL || 'redis://mi-redis:6379'
  }
});
```

### Inicialización básica

```typescript
import { 
  RedisClient, 
  WhatsAppMessageQueue,
  logger 
} from 'whatsapp-crm-common';

// Inicializar Redis (usa configuración global automáticamente)
const redisClient = RedisClient.getInstance();

// Inicializar cola de mensajes
const messageQueue = new WhatsAppMessageQueue(redisClient);

logger.info('Sistema inicializado correctamente');
```

## 💡 Ejemplos de Uso

### Manejo de Eventos

```typescript
import { 
  EventPublisher, 
  WhatsAppEventType,
  HybridEventRouter 
} from 'whatsapp-crm-common';

const eventPublisher = new EventPublisher();

// Publicar mensaje recibido
await eventPublisher.publishMessageReceived(
  'tenant-001', 
  1, 
  [message]
);

// Publicar código QR
await eventPublisher.publishQRCodeGenerated(
  'tenant-001',
  1,
  'data:image/png;base64,iVBORw0KGgoAAAANSUhEUgAA...'
);
```

### Formateo de Números

```typescript
import { formatPhoneNumber, isValidPhoneNumber } from 'whatsapp-crm-common';

const formattedNumber = formatPhoneNumber('5491155555555');
// Resultado: '5491155555555@s.whatsapp.net'

const isValid = isValidPhoneNumber('5491155555555');
// Resultado: true
```

### Logging Contextual

```typescript
import { logger } from 'whatsapp-crm-common';

logger.info({
  tenantId: 'tenant-001',
  agentId: 1,
  messageId: 'msg-123',
  msg: 'Mensaje procesado correctamente'
});
```

## 🏗️ Arquitectura

### Sistema Híbrido de Eventos

```typescript
// Eventos críticos → BullMQ (persistencia)
MESSAGE_NEW, MESSAGE_UPDATE, HISTORY_SYNC, CONTACT_UPDATE

// Eventos tiempo real → Redis Pub/Sub (velocidad)
QR_CODE_GENERATED, CONNECTION_UPDATE, PRESENCE_UPDATE, TYPING_START
```

### Colas Especializadas

- **`REALTIME`**: Mensajes nuevos, actualizaciones críticas
- **`BULK`**: Sincronización masiva de historial  
- **`WEBHOOK`**: Notificaciones HTTP externas
- **`NOTIFICATIONS`**: Actualizaciones de contactos, presencia

## 📋 API Principal

### Configuración
- `configureWhatsAppCommon()` - Configuración programática
- `getConfig()` - Obtener configuración actual mezclada
- `environment` - Variables de entorno centralizadas (legacy)
- `RedisClient` - Cliente Redis singleton
- `defaultRedisConfig` - Configuración Redis por defecto

### Eventos
- `EventPublisher` - Publicador de eventos tipado
- `HybridEventRouter` - Router inteligente de eventos
- `WhatsAppEventType` - Tipos de eventos disponibles

### Infraestructura
- `WhatsAppMessageQueue` - Sistema de colas BullMQ
- `WhatsAppPubSubSystem` - Sistema Pub/Sub Redis

### Utilidades
- `logger` - Logger estructurado con Pino
- `formatPhoneNumber()` - Formato números WhatsApp
- `extractMessageContent()` - Extrae contenido de mensajes

### Tipos de Dominio
- `IChat`, `IMessage`, `IContact`, `IGroup` - Interfaces de entidades
- `WhatsAppConfig`, `ChatInfo` - Tipos de configuración
- `HistoryOptions`, `MessageType` - Tipos de operaciones

## 🔧 Variables de Entorno

```bash
# Redis Configuration
REDIS_URL=redis://localhost:6379
REDIS_HOST=localhost
REDIS_PORT=6379

# Database
DATABASE_URL=postgresql://user:password@localhost:5432/whatsapp_crm

# Queue Configuration  
ENABLE_MESSAGE_QUEUE=true
QUEUE_CONCURRENCY=5
MAX_SESSIONS_PER_PROCESS=100

# WhatsApp Configuration
WEBHOOK_URL=http://localhost:3000/webhook
MAX_RECONNECT_ATTEMPTS=5
QR_TIMEOUT_MS=60000
```

## 🚀 Scripts de Desarrollo

```bash
# Construir el paquete
npm run build

# Desarrollo con watch
npm run dev

# Limpiar build
npm run clean

# Verificar tipos
npm run type-check
```

## 📊 Casos de Uso

Este paquete está optimizado para:

1. **Sistemas CRM de WhatsApp** - Gestión completa de conversaciones
2. **APIs de WhatsApp** - Envío y recepción de mensajes
3. **Automatización** - Bots y respuestas automáticas
4. **Analíticas** - Procesamiento de datos de conversación
5. **Webhooks** - Integración con sistemas externos

## 🤝 Contribución

Las contribuciones son bienvenidas. Por favor:

1. Fork el proyecto
2. Crea una branch para tu feature
3. Commit tus cambios
4. Push a la branch
5. Abre un Pull Request

## 📄 Licencia

MIT © [WhatsApp CRM Team](LICENSE)