@mbermeo/wa-blaster 0.1.0

package/README.md

@@ -0,0 +1,1060 @@
+# WA Blast — Sistema de Mensajes Masivos por WhatsApp
+
+Sistema para enviar mensajes masivos por WhatsApp con soporte multi-cuenta, plantillas con variables, imágenes con A/B testing, scheduling por hora/día, control de campañas y comportamiento anti-spam. Incluye API HTTP, interfaz web y CLI para uso por agentes de IA.
+
+---
+
+## Tabla de contenidos
+
+- [Requisitos](#requisitos)
+- [Instalación](#instalación)
+- [Configuración](#configuración)
+- [Arranque](#arranque)
+- [Despliegue con Docker](#despliegue-con-docker)
+- [CLI global (`wa-blast`)](#cli-global-wa-blast)
+- [Arquitectura](#arquitectura)
+- [Flujo de uso](#flujo-de-uso)
+- [Interfaz web](#interfaz-web)
+- [API HTTP](#api-http)
+- [CLI](#cli)
+- [Comportamiento anti-spam](#comportamiento-anti-spam)
+- [Scheduling y límites de envío](#scheduling-y-límites-de-envío)
+- [Imágenes y A/B testing](#imágenes-y-ab-testing)
+- [Campañas inbound](#campañas-inbound)
+- [Formato de archivos de contactos](#formato-de-archivos-de-contactos)
+- [Sistema de plantillas](#sistema-de-plantillas)
+- [Base de datos](#base-de-datos)
+- [Solución de problemas](#solución-de-problemas)
+
+---
+
+## Requisitos
+
+- **Node.js v24+** (recomendado via `nvm`)
+- **npm**
+- Chromium (Puppeteer lo descarga automáticamente al hacer `npm install`)
+- Un teléfono con WhatsApp para escanear el QR
+
+---
+
+## Instalación
+
+```bash
+git clone <repo>
+cd agente_whatsapp
+npm install
+```
+
+---
+
+## Configuración
+
+Crea un archivo `.env` en la raíz del proyecto:
+
+```env
+PORT=3000       # Puerto del servidor HTTP (default: 3000)
+DELAY_MS=3000   # Delay por defecto entre mensajes en ms (default: 3000)
+MAX_ACCOUNTS=3  # Máximo de cuentas WhatsApp activas simultáneas (default: 3)
+```
+
+> `DELAY_MS` es solo el default global. Cada campaña puede sobreescribirlo con su propio `delay_ms`.
+
+---
+
+## Arranque
+
+```bash
+# Modo producción
+npm start
+
+# Modo desarrollo (recarga automática ante cambios)
+npm run dev
+
+# Ejecutar tests
+npm test
+```
+
+El servidor arranca en `http://localhost:3000`.
+
+Al arrancar, el sistema reconecta automáticamente todas las cuentas que tienen sesión guardada en `./sessions/` — no es necesario volver a escanear el QR.
+
+---
+
+## Despliegue con Docker
+
+La opción recomendada para producción. El contenedor incluye Chromium del sistema (no descarga el suyo propio), lo que hace la imagen reproducible sin sorpresas de red.
+
+### Requisitos
+
+- Docker + Docker Compose
+
+### Levantar el servidor
+
+```bash
+# (Opcional) Copiar y ajustar variables de entorno
+cp .env.example .env
+
+# Primera vez — construir imagen y arrancar
+docker compose up -d --build
+
+# Ver logs
+docker compose logs -f
+```
+
+El servidor queda disponible en `http://localhost:3000`.
+
+### Verificar que funciona
+
+```bash
+curl http://localhost:3000/health
+# → {"status":"ok","timestamp":"..."}
+```
+
+### Persistencia de datos
+
+Los datos sobreviven reinicios mediante volúmenes montados en el directorio local:
+
+| Directorio local | Montura en contenedor | Contenido |
+|---|---|---|
+| `sessions/` | `/app/sessions` | Sesiones de WhatsApp (~500 MB por cuenta) |
+| `data/` | `/app/data` | Base de datos SQLite (`data.db`) |
+| `uploads/` | `/app/uploads` | Archivos CSV temporales |
+| `campaign_images/` | `/app/campaign_images` | Imágenes de campañas (A/B testing) |
+
+### Comandos útiles
+
+```bash
+docker compose restart            # Reiniciar sin reconstruir
+docker compose up -d --build      # Actualizar tras cambios de código
+docker compose down               # Detener y eliminar contenedor
+docker compose logs -f            # Seguir logs en tiempo real
+```
+
+---
+
+## CLI global (`wa-blast`)
+
+Tras instalar globalmente el CLI, el comando `wa-blast` queda disponible en el PATH para controlar cualquier servidor (local o remoto) desde scripts o desde otro equipo.
+
+### Instalación
+
+```bash
+# En el directorio del repo clonado
+npm install -g .
+
+# Verificar
+wa-blast accounts list
+```
+
+### Configurar la URL del servidor
+
+```bash
+# Via flag en cada comando
+wa-blast --url http://mi-servidor:3000 accounts list
+
+# Via variable de entorno (más cómodo para scripts)
+export WA_BLAST_URL=http://mi-servidor:3000
+wa-blast accounts list
+```
+
+---
+
+## Arquitectura
+
+```
+agente_whatsapp/
+├── src/
+│   ├── server.js              # Entry point: Express + arranque + auto-reconexión + scheduler
+│   ├── db.js                  # SQLite (better-sqlite3) + schema + migraciones automáticas
+│   ├── accountManager.js      # Gestión de clientes whatsapp-web.js en memoria
+│   ├── campaignRunner.js      # Motor de envío: round-robin, anti-spam, scheduling, A/B
+│   └── routes/
+│       ├── accounts.js        # Endpoints REST de cuentas
+│       ├── campaigns.js       # Endpoints REST de campañas e imágenes
+│       └── inbound.js         # Endpoints REST de campañas inbound
+│   └── utils/
+│       ├── csvParser.js       # Parseo de CSV y XLSX
+│       └── templateEngine.js  # Reemplazo de {{variables}}
+├── cli/
+│   └── index.js               # CLI para uso por agente (salida JSON, exit codes)
+├── sessions/                  # Sesiones de WhatsApp (LocalAuth, generado en runtime)
+├── uploads/                   # Archivos CSV temporales (se limpian tras importar)
+├── campaign_images/           # Imágenes de campañas (persisten)
+├── data.db                    # Base de datos SQLite (generada en runtime)
+├── public/
+│   └── index.html             # Frontend web (SPA estático)
+├── test/
+│   └── campaigns.test.js      # Tests de integración (node:test + supertest)
+├── package.json
+└── .env
+```
+
+### Componentes principales
+
+| Componente | Responsabilidad |
+|---|---|
+| `server.js` | Arranca Express, monta rutas, reconecta cuentas, ejecuta scheduler de campañas |
+| `db.js` | Conexión singleton a SQLite, schema y migraciones idempotentes |
+| `accountManager.js` | `Map` en memoria de clientes whatsapp-web.js con sus estados y QR |
+| `campaignRunner.js` | Distribuye contactos en round-robin, lanza un loop por cuenta, anti-spam, scheduling, A/B |
+| `csvParser.js` | Lee CSV/XLSX, normaliza columnas, valida columna `phone` |
+| `templateEngine.js` | Reemplaza `{{variable}}` con valores del objeto de datos del contacto |
+| `cli/index.js` | CLI sin dependencias extra, salida JSON limpia, exit codes claros |
+
+---
+
+## Flujo de uso
+
+```
+1. Agregar cuenta WhatsApp  →  POST /api/accounts
+        ↓
+2. Escanear QR con el teléfono  →  GET /api/accounts/:id/qr
+        ↓
+3. Crear campaña (nombre + cuentas + template + opciones)  →  POST /api/campaigns
+        ↓
+4. (Opcional) Subir imagen(es) para A/B testing  →  POST /api/campaigns/:id/images
+        ↓
+5. Subir CSV/XLSX con contactos  →  POST /api/campaigns/:id/contacts
+        ↓
+6. Iniciar campaña  →  POST /api/campaigns/:id/start
+        ↓
+7. Monitorear / pausar / cancelar  →  GET /api/campaigns/:id
+                                       POST /api/campaigns/:id/pause
+                                       POST /api/campaigns/:id/cancel
+```
+
+Si la campaña tiene límites de scheduling configurados, pasará automáticamente a estado `scheduled` al alcanzar el tope diario/horario o salir de la ventana de envío, y se reanudará sola cuando las condiciones lo permitan.
+
+---
+
+## Interfaz web
+
+Abre `http://localhost:3000` en el navegador.
+
+### Panel Cuentas
+
+- **Agregar cuenta**: ingresa un ID (ej. `micuenta`) y haz clic en AGREGAR
+- **Escanear QR**: el botón QR aparece mientras la cuenta espera autenticación
+- **LÍMITE/DÍA**: campo inline para configurar cuántos mensajes puede enviar esa cuenta por día (default 50)
+- El estado cambia automáticamente: `pending` → `authenticated` → `ready`
+
+### Panel Campañas
+
+- **Nueva campaña**: abre el modal con todos los parámetros (anti-spam + scheduling)
+- **UPLOAD CSV**: sube contactos (solo en estado `pending`)
+- **IMAGEN / 📷 N IMGS**: sube imágenes para A/B testing (hasta 5 variantes)
+- **START**: inicia el envío (requiere cuentas `ready` y contactos cargados)
+- **PAUSE / RESUME / CANCEL / DEL**: botones según estado
+- **EDIT**: edita cualquier parámetro de campañas `pending`
+- **TRACKING**: modal con funnel ACK en tiempo real, respuestas recibidas y stats por variante A/B
+
+### Estados de campaña en la UI
+
+| Badge | Significado |
+|---|---|
+| `PENDING` | Lista para configurar |
+| `RUNNING` | Enviando activamente |
+| `PAUSED` | Pausada manualmente |
+| `⏰ SCHEDULED` | Auto-suspendida por límite/horario; se reanuda sola |
+| `DONE` | Completada |
+| `CANCELLED` | Cancelada definitivamente |
+
+---
+
+## API HTTP
+
+Base URL: `http://localhost:3000`
+
+Todos los endpoints de recursos devuelven JSON. Los errores incluyen `{ "error": "..." }`.
+
+### Health check
+
+```
+GET /health
+```
+```json
+{ "status": "ok", "timestamp": "2026-03-31T10:00:00.000Z" }
+```
+
+---
+
+### Cuentas — `/api/accounts`
+
+#### Crear / inicializar cuenta
+
+```
+POST /api/accounts
+Content-Type: application/json
+
+{ "id": "micuenta" }
+```
+
+Respuesta `202`:
+```json
+{
+  "message": "Cuenta \"micuenta\" inicializando. Use GET /api/accounts/micuenta/qr para obtener el QR.",
+  "id": "micuenta",
+  "status": "pending"
+}
+```
+
+> La inicialización es asíncrona. El QR estará disponible en ~5-10 segundos.
+
+---
+
+#### Listar cuentas
+
+```
+GET /api/accounts
+```
+
+```json
+[
+  {
+    "id": "micuenta",
+    "phone": "5491112345678",
+    "status": "ready",
+    "daily_limit": 50,
+    "created_at": "2026-03-31T10:00:00",
+    "in_memory": true
+  }
+]
+```
+
+**Estados de cuenta:** `pending` → `authenticated` → `ready` | `disconnected`
+
+---
+
+#### Obtener QR
+
+```
+GET /api/accounts/:id/qr
+```
+
+```json
+{ "qr": "data:image/png;base64,iVBORw0KGgo..." }
+```
+
+---
+
+#### Estado de una cuenta
+
+```
+GET /api/accounts/:id/status
+```
+
+---
+
+#### Editar cuenta
+
+```
+PATCH /api/accounts/:id
+Content-Type: application/json
+
+{ "daily_limit": 30 }
+```
+
+Actualiza el límite diario de envío. Valor mínimo: 1.
+
+---
+
+#### Reset de cuenta
+
+```
+POST /api/accounts/:id/reset
+```
+
+Borra la sesión guardada y fuerza un QR nuevo. Útil si la sesión quedó corrupta.
+
+---
+
+#### Eliminar cuenta
+
+```
+DELETE /api/accounts/:id
+```
+
+Desconecta WhatsApp, destruye el cliente en memoria y elimina el registro de la DB.
+
+---
+
+### Campañas — `/api/campaigns`
+
+#### Crear campaña
+
+```
+POST /api/campaigns
+Content-Type: application/json
+
+{
+  "name": "Promo mayo",
+  "account_ids": ["cuenta1"],
+  "template": "Hola {{nombre}}, tu código es {{codigo}}",
+  "delay_ms": 4000,
+  "jitter_ms": 2000,
+  "typing_sim": 1,
+  "burst_size": 15,
+  "burst_pause_ms": 60000,
+  "daily_cap": 40,
+  "hourly_cap": 10,
+  "send_window_start": "09:00",
+  "send_window_end": "18:00",
+  "active_days": "1,2,3,4,5"
+}
+```
+
+**Campos:**
+
+| Campo | Tipo | Req. | Default | Descripción |
+|---|---|---|---|---|
+| `name` | string | ✓ | — | Nombre de la campaña |
+| `account_ids` | string[] | ✓ | — | IDs de cuentas WhatsApp asignadas |
+| `template` | string | ✓ | — | Texto con `{{variables}}` |
+| `delay_ms` | integer | — | env `DELAY_MS` | ms entre mensajes (mín. 1000) |
+| `jitter_ms` | integer | — | 2000 | Variación aleatoria del delay |
+| `typing_sim` | 0\|1 | — | 1 | Simular "escribiendo..." |
+| `burst_size` | integer | — | 0 | Pausa cada N mensajes (0=off) |
+| `burst_pause_ms` | integer | — | 60000 | Duración de la pausa periódica |
+| `daily_cap` | integer | — | 0 | Máx. mensajes por día para esta campaña (0=usa límite de cuenta) |
+| `hourly_cap` | integer | — | 0 | Máx. mensajes por hora (0=desactivado) |
+| `send_window_start` | string | — | null | Inicio de ventana de envío (`HH:MM`) |
+| `send_window_end` | string | — | null | Fin de ventana de envío (`HH:MM`) |
+| `active_days` | string | — | null | Días activos: `"1,2,3,4,5"` (1=Lun … 7=Dom). `null`=todos |
+
+> También se acepta `account_id` (string) para compatibilidad legacy con una sola cuenta.
+
+Respuesta `201`: campaña creada con todos sus campos.
+
+---
+
+#### Editar campaña
+
+Solo campañas en estado `pending`. Acepta todos los mismos campos de creación (todos opcionales).
+
+```
+PATCH /api/campaigns/:id
+```
+
+---
+
+#### Subir contactos (CSV/XLSX)
+
+Solo campañas en estado `pending`.
+
+```
+POST /api/campaigns/:id/contacts
+Content-Type: multipart/form-data
+
+file=<archivo.csv>
+```
+
+---
+
+#### Imágenes para A/B testing
+
+Ver sección [Imágenes y A/B testing](#imágenes-y-ab-testing).
+
+```
+GET    /api/campaigns/:id/images
+POST   /api/campaigns/:id/images        # multipart/form-data, campo: image
+DELETE /api/campaigns/:id/images/:imgId
+```
+
+---
+
+#### Iniciar / reanudar campaña
+
+```
+POST /api/campaigns/:id/start
+```
+
+Inicia o reanuda el envío. Funciona desde estados `pending`, `paused` y `scheduled`.
+
+Los contactos se distribuyen en round-robin entre las cuentas `ready`. Si hay imágenes, también se asignan en round-robin (A/B).
+
+---
+
+#### Pausar campaña
+
+```
+POST /api/campaigns/:id/pause
+```
+
+Funciona desde estados `running` y `scheduled`. Para reanudar, llama a `/start`.
+
+---
+
+#### Cancelar campaña
+
+```
+POST /api/campaigns/:id/cancel
+```
+
+---
+
+#### Eliminar campaña
+
+Solo en estados `pending`, `done`, `cancelled` y `scheduled`.
+
+```
+DELETE /api/campaigns/:id
+```
+
+Elimina en cascada contactos, imágenes del disco e mensajes entrantes asociados.
+
+---
+
+#### Listar campañas
+
+```
+GET /api/campaigns
+```
+
+Incluye `stats`, `accounts` e `images` (variantes A/B) por campaña.
+
+---
+
+#### Detalle de campaña
+
+```
+GET /api/campaigns/:id
+```
+
+---
+
+#### Tracking ACK
+
+```
+GET /api/campaigns/:id/tracking
+```
+
+```json
+{
+  "campaign": { "id": 1, "name": "Promo mayo", "status": "scheduled" },
+  "total": 500,
+  "sent": 80,
+  "ack": [
+    { "ack_status": "delivered", "count": 65 },
+    { "ack_status": "read",      "count": 15 }
+  ],
+  "replies": 3,
+  "image_variants": [
+    {
+      "label": "A", "image_id": 1, "original_name": "promo_verano.jpg",
+      "total": 250, "sent": 40, "failed": 0, "delivered": 35, "read": 8
+    },
+    {
+      "label": "B", "image_id": 2, "original_name": "promo_invierno.jpg",
+      "total": 250, "sent": 40, "failed": 0, "delivered": 30, "read": 7
+    }
+  ]
+}
+```
+
+`image_variants` solo aparece si la campaña tiene imágenes configuradas.
+
+---
+
+#### Respuestas recibidas
+
+```
+GET /api/campaigns/:id/replies
+```
+
+---
+
+## CLI
+
+```bash
+# Instalado globalmente
+wa-blast <resource> <action> [args] [flags]
+
+# Directo
+node cli/index.js <resource> <action> [args] [flags]
+```
+
+### CLI: Cuentas
+
+```bash
+wa-blast accounts list
+wa-blast accounts add micuenta
+wa-blast accounts status micuenta
+wa-blast accounts qr micuenta
+wa-blast accounts edit micuenta --daily-limit 30
+wa-blast accounts reset micuenta
+wa-blast accounts delete micuenta
+wa-blast accounts messages micuenta
+```
+
+---
+
+### CLI: Campañas
+
+```bash
+# Listar y ver detalle
+wa-blast campaigns list
+wa-blast campaigns show 1
+
+# Crear campaña básica
+wa-blast campaigns create \
+  --name "Promo mayo" \
+  --accounts "cuenta1" \
+  --template "Hola {{nombre}}, tu oferta: {{oferta}}" \
+  --delay 4000
+
+# Crear campaña con scheduling completo
+wa-blast campaigns create \
+  --name "Campaña semana laboral" \
+  --accounts "cuenta1" \
+  --template "Hola {{nombre}}" \
+  --delay 4000 \
+  --jitter 2000 \
+  --typing 1 \
+  --burst-size 15 \
+  --burst-pause 60000 \
+  --daily-cap 40 \
+  --hourly-cap 10 \
+  --window-start 09:00 \
+  --window-end 18:00 \
+  --active-days "1,2,3,4,5"
+
+# Subir contactos
+wa-blast campaigns upload 1 ./contactos.csv
+
+# Imágenes A/B testing
+wa-blast campaigns images 1
+wa-blast campaigns image-add 1 ./imagen_verano.jpg
+wa-blast campaigns image-add 1 ./imagen_invierno.jpg
+wa-blast campaigns image-delete 1 2
+
+# Ciclo de vida
+wa-blast campaigns start 1
+wa-blast campaigns pause 1
+wa-blast campaigns cancel 1
+wa-blast campaigns delete 1
+
+# Editar campaña pending
+wa-blast campaigns edit 1 \
+  --daily-cap 30 \
+  --window-start 10:00 \
+  --window-end 17:00 \
+  --active-days "1,2,3,4,5"
+
+# Esperar resultado (imprime puntos hasta done/paused/cancelled)
+wa-blast campaigns wait 1
+wa-blast campaigns wait 1 --interval 10
+
+# Stats y respuestas
+wa-blast campaigns tracking 1
+wa-blast campaigns replies 1
+```
+
+---
+
+### Flags de `campaigns create` y `campaigns edit`
+
+**Anti-spam:**
+
+| Flag | Descripción | Default |
+|---|---|---|
+| `--name <texto>` | Nombre | — |
+| `--accounts <c1,c2>` | Cuentas separadas por coma | — |
+| `--template <texto>` | Plantilla del mensaje | — |
+| `--delay <ms>` | Delay base entre mensajes | 3000 |
+| `--jitter <ms>` | Variación aleatoria del delay | 2000 |
+| `--typing <0\|1>` | Simular "escribiendo..." | 1 |
+| `--burst-size <n>` | Pausa cada N mensajes (0=off) | 0 |
+| `--burst-pause <ms>` | Duración de la pausa periódica | 60000 |
+
+**Scheduling:**
+
+| Flag | Descripción | Default |
+|---|---|---|
+| `--daily-cap <n>` | Máx. mensajes/día para esta campaña (0=usa cuenta) | 0 |
+| `--hourly-cap <n>` | Máx. mensajes/hora (0=desactivado) | 0 |
+| `--window-start HH:MM` | Inicio de ventana de envío | null |
+| `--window-end HH:MM` | Fin de ventana de envío | null |
+| `--active-days <1,2,3,4,5>` | Días activos (1=Lun … 7=Dom) | null (todos) |
+
+---
+
+### Ejemplo completo con CLI (uso por agente)
+
+```bash
+export WA_BLAST_URL=http://mi-servidor:3000
+
+# 1. Verificar cuenta lista
+wa-blast accounts status cuenta1
+
+# 2. Crear campaña con límite 50/día, solo días hábiles 9-18h
+CAMPAIGN=$(wa-blast campaigns create \
+  --name "Promo 500 contactos" \
+  --accounts "cuenta1" \
+  --template "Hola {{nombre}}, tu descuento es {{descuento}}%" \
+  --delay 4000 --jitter 2000 --typing 1 \
+  --daily-cap 50 --window-start 09:00 --window-end 18:00 \
+  --active-days "1,2,3,4,5")
+
+ID=$(echo $CAMPAIGN | jq '.id')
+
+# 3. Agregar imagen (opcional)
+wa-blast campaigns image-add $ID ./promo.jpg
+
+# 4. Subir 500 contactos
+wa-blast campaigns upload $ID ./contactos.csv
+
+# 5. Iniciar — enviará 50 hoy, quedará en 'scheduled', se reanuda sola mañana
+wa-blast campaigns start $ID
+
+# 6. Monitorear
+wa-blast campaigns show $ID | jq '{status: .status, stats: .stats}'
+
+# 7. Ver tracking con stats por variante
+wa-blast campaigns tracking $ID
+```
+
+---
+
+## Comportamiento anti-spam
+
+El sistema implementa cuatro capas de humanización para reducir el riesgo de ban por parte de Meta.
+
+### 1. Jitter en el delay
+
+```
+delay_final = delay_ms + random(0, jitter_ms)
+```
+
+Ejemplo: `delay_ms=4000` + `jitter_ms=2000` → espera entre **4s y 6s** por mensaje.
+
+### 2. Simulación de escritura (`typing_sim`)
+
+Antes de enviar: activa "escribiendo...", espera proporcional al largo del mensaje (±30%), detiene el estado, envía.
+
+```
+base   = clamp(largo × 60ms, 1500ms, 7000ms)
+tiempo = base × (0.7 + random × 0.6)
+```
+
+### 3. Presencia online
+
+Al inicio de cada loop de cuenta se llama `sendPresenceAvailable()`.
+
+### 4. Pausa periódica (burst pause)
+
+Cada `burst_size` mensajes, pausa de `burst_pause_ms`. Ejemplo: `burst_size=15` + `burst_pause_ms=60000` → pausa de 1 minuto cada 15 mensajes.
+
+### Valores recomendados por volumen
+
+| Volumen | `delay_ms` | `jitter_ms` | `typing_sim` | `burst_size` | `burst_pause_ms` |
+|---|---|---|---|---|---|
+| Bajo (<100/día) | 3000 | 1000 | 1 | 0 | — |
+| Medio (100-500/día) | 4000 | 2000 | 1 | 20 | 60000 |
+| Alto (500+/día) | 5000 | 3000 | 1 | 15 | 90000 |
+
+---
+
+## Scheduling y límites de envío
+
+Permite que una campaña se distribuya automáticamente en varios días respetando límites de WhatsApp.
+
+### Límite diario por cuenta
+
+Cada cuenta tiene un `daily_limit` (default: **50**). Cuando una cuenta alcanza su límite del día, la campaña pasa automáticamente a estado `scheduled` y el scheduler la reanuda al día siguiente.
+
+Configurar via UI (campo "LÍMITE/DÍA" en la tarjeta de cuenta) o CLI:
+
+```bash
+wa-blast accounts edit cuenta1 --daily-limit 40
+```
+
+### Parámetros de scheduling por campaña
+
+| Parámetro | Descripción |
+|---|---|
+| `daily_cap` | Tope diario de la campaña. Si `0`, usa el `daily_limit` de la cuenta. Útil para usar solo una parte del cupo cuando hay varias campañas activas. |
+| `hourly_cap` | Tope por hora. `0` = sin límite horario. |
+| `send_window_start` / `send_window_end` | Solo envía dentro de este rango horario (formato `HH:MM`). |
+| `active_days` | Días de la semana activos: `"1,2,3,4,5"` = lunes a viernes. `1`=Lun, `2`=Mar, … `7`=Dom. `null` o vacío = todos los días. |
+
+### Estado `scheduled`
+
+Cuando cualquier límite se alcanza o la campaña está fuera de ventana, el runner cambia automáticamente el estado a `scheduled`:
+
+```
+running → [límite alcanzado o fuera de ventana] → scheduled
+scheduled → [condiciones ok, scheduler cada 60s] → running
+```
+
+Desde la UI/CLI también se puede resumir manualmente una campaña `scheduled`.
+
+### Ejemplo: 500 contactos con cuenta de 50/día
+
+Con `daily_cap=50`, ventana `09:00-18:00`, días `1,2,3,4,5`:
+
+- **Día 1 (lunes)**: runner envía 50 → `scheduled`
+- **Día 2 (martes)**: scheduler detecta nuevo día, ventana activa → `running` → envía 50 → `scheduled`
+- …10 días hábiles después → `done`
+
+> **Nota**: Si la campaña usa múltiples cuentas y una de ellas alcanza su `daily_limit`, la campaña completa pasa a `scheduled`. El scheduler la reanudará cuando al menos una cuenta tenga capacidad.
+
+---
+
+## Imágenes y A/B testing
+
+Permite adjuntar hasta **5 imágenes** (variantes A-E) a una campaña. Se distribuyen en round-robin entre los contactos y se trackea la performance de cada variante.
+
+### Subir imágenes
+
+```bash
+# Subir variante A
+wa-blast campaigns image-add 1 ./imagen_a.jpg
+# → { "id": 1, "label": "A", "original_name": "imagen_a.jpg", ... }
+
+# Subir variante B
+wa-blast campaigns image-add 1 ./imagen_b.png
+# → { "id": 2, "label": "B", ... }
+```
+
+Formatos aceptados: `.jpg`, `.jpeg`, `.png`, `.gif`, `.webp`. Máximo 5MB por imagen.
+
+### Distribución
+
+Al iniciar la campaña, los contactos se asignan en round-robin a las variantes:
+
+- 9 contactos + 3 variantes → 3 contactos por variante (A, B, C, A, B, C, ...)
+- Si hay solo 1 imagen → todos los contactos reciben esa imagen (imagen única sin A/B)
+
+### Envío
+
+La imagen se envía con el texto del template como **caption**.
+
+### Tracking por variante
+
+El endpoint `GET /api/campaigns/:id/tracking` incluye `image_variants` con métricas separadas por variante: total, sent, delivered, read.
+
+En la UI, el tab "A/B IMAGES" en el modal de tracking muestra estas métricas.
+
+### Eliminar imagen
+
+```bash
+wa-blast campaigns image-delete 1 2   # elimina imagen con id=2
+```
+
+Al eliminar, los labels se reordenan automáticamente (A, B, C, ... consecutivos).
+
+> Las imágenes solo se pueden agregar/eliminar en campañas en estado `pending`.
+
+---
+
+## Campañas inbound
+
+Las campañas inbound son auto-respuestas que se envían automáticamente cuando un contacto escribe a una cuenta WhatsApp. Soportan distribución de cupones únicos por contacto.
+
+### Endpoints
+
+```
+GET    /api/inbound
+POST   /api/inbound
+GET    /api/inbound/:id
+POST   /api/inbound/:id/activate
+POST   /api/inbound/:id/pause
+DELETE /api/inbound/:id
+POST   /api/inbound/:id/coupons          # multipart, campo: file (.txt/.csv)
+GET    /api/inbound/:id/coupons
+GET    /api/inbound/:id/contacts
+GET    /api/inbound/:id/contacts/export  # descarga CSV
+POST   /api/inbound/:id/to-campaign      # crear campaña outbound con los contactos inbound
+```
+
+### Parámetros
+
+| Campo | Descripción |
+|---|---|
+| `account_id` | Cuenta que recibirá mensajes entrantes |
+| `name` | Nombre descriptivo |
+| `template` | Mensaje de respuesta (soporta `{{nombre}}` y `{{cupon}}`) |
+| `max_uses` | Máximo de usos (0=ilimitado) |
+| `reply_mode` | `once_per_campaign` (default), `always`, `new_contacts_only` |
+
+### CLI inbound
+
+```bash
+wa-blast inbound list
+wa-blast inbound create --account cuenta1 --name "Promo QR" --template "Tu cupón: {{cupon}}"
+wa-blast inbound coupons-upload 1 ./cupones.txt
+wa-blast inbound coupons 1
+wa-blast inbound contacts 1
+wa-blast inbound export 1 > contactos.csv
+wa-blast inbound to-campaign 1 --name "Follow-up" --template "Hola {{nombre}}" --accounts "cuenta1"
+wa-blast inbound activate 1
+wa-blast inbound pause 1
+wa-blast inbound delete 1
+```
+
+---
+
+## Formato de archivos de contactos
+
+Se aceptan **CSV** y **Excel (.xlsx, .xls)**. Tamaño máximo: 10MB.
+
+La columna de teléfono puede llamarse: `phone`, `telefono`, `numero`, `número`.
+
+El resto de columnas se convierten en variables para el template.
+
+### Ejemplo
+
+```csv
+phone,nombre,empresa,descuento
+5491112345678,Juan García,Acme SA,20%
+5491133445566,María López,Tech Corp,15%
+5491144556677,Carlos Martínez,StartupXYZ,30%
+```
+
+### Formato de teléfonos
+
+- Incluir **código de país** sin el símbolo `+`
+- Se eliminan automáticamente: espacios, guiones, paréntesis, `+`
+- Argentina: `54` + `9` + código de área + número → `5491112345678`
+
+---
+
+## Sistema de plantillas
+
+```
+Hola {{nombre}}, te contactamos de {{empresa}}.
+Tu código es {{codigo}} válido hasta {{vencimiento}}.
+```
+
+Si una variable no existe para ese contacto, el placeholder queda tal cual.
+
+Cuando la campaña tiene imagen, el template se envía como **caption** de la imagen.
+
+---
+
+## Base de datos
+
+El archivo `data.db` (SQLite) se crea automáticamente. Las migraciones son idempotentes.
+
+### `accounts`
+
+| Columna | Tipo | Default | Descripción |
+|---|---|---|---|
+| `id` | TEXT PK | — | Identificador de cuenta |
+| `phone` | TEXT | — | Número de teléfono (disponible tras autenticar) |
+| `status` | TEXT | `pending` | `pending` / `authenticated` / `ready` / `disconnected` |
+| `daily_limit` | INTEGER | 50 | Máx. mensajes que esta cuenta puede enviar por día |
+| `created_at` | TEXT | now | |
+
+### `campaigns`
+
+| Columna | Tipo | Default | Descripción |
+|---|---|---|---|
+| `id` | INTEGER PK | autoincrement | |
+| `name` | TEXT | — | Nombre |
+| `template` | TEXT | — | Plantilla con `{{...}}` |
+| `status` | TEXT | `pending` | `pending` / `running` / `paused` / `scheduled` / `done` / `cancelled` |
+| `delay_ms` | INTEGER | 3000 | Delay base entre mensajes |
+| `jitter_ms` | INTEGER | 2000 | Variación aleatoria del delay |
+| `typing_sim` | INTEGER | 1 | Simular escritura (0/1) |
+| `burst_size` | INTEGER | 0 | Pausa cada N mensajes |
+| `burst_pause_ms` | INTEGER | 60000 | Duración de pausa periódica |
+| `daily_cap` | INTEGER | 0 | Tope diario de campaña (0=usa daily_limit de cuenta) |
+| `hourly_cap` | INTEGER | 0 | Tope por hora (0=desactivado) |
+| `send_window_start` | TEXT | null | Inicio de ventana horaria (`HH:MM`) |
+| `send_window_end` | TEXT | null | Fin de ventana horaria (`HH:MM`) |
+| `active_days` | TEXT | null | Días activos como CSV de números 1-7 |
+| `created_at` | TEXT | now | |
+
+### `campaign_accounts`
+
+Relación N:N entre campañas y cuentas.
+
+### `campaign_images`
+
+| Columna | Tipo | Descripción |
+|---|---|---|
+| `id` | INTEGER PK | |
+| `campaign_id` | INTEGER FK | |
+| `label` | TEXT | `A`, `B`, `C`, `D` o `E` |
+| `file_path` | TEXT | Ruta relativa en `campaign_images/` |
+| `original_name` | TEXT | Nombre original del archivo |
+| `created_at` | TEXT | |
+
+### `contacts`
+
+| Columna | Tipo | Descripción |
+|---|---|---|
+| `id` | INTEGER PK | |
+| `campaign_id` | INTEGER FK | |
+| `phone` | TEXT | Número destino |
+| `data` | TEXT | JSON con variables del CSV |
+| `status` | TEXT | `pending` / `sent` / `failed` |
+| `error` | TEXT | Mensaje de error si falló |
+| `sent_at` | TEXT | Timestamp de envío exitoso |
+| `assigned_account_id` | TEXT | Cuenta asignada (round-robin) |
+| `image_id` | INTEGER FK | Variante de imagen asignada (A/B testing) |
+| `message_id` | TEXT | ID interno del mensaje en WhatsApp |
+| `ack_status` | TEXT | `sent` / `delivered` / `read` / `played` |
+| `delivered_at` | TEXT | Timestamp de entrega |
+| `read_at` | TEXT | Timestamp de lectura |
+
+### `incoming_messages`
+
+Mensajes recibidos de contactos durante campañas activas.
+
+### `inbound_campaigns`, `inbound_coupons`, `inbound_replies`
+
+Tablas para el sistema de auto-respuesta inbound con distribución de cupones.
+
+---
+
+## Solución de problemas
+
+### El QR no aparece
+
+- Esperar ~10 segundos después de `accounts add`
+- Verificar que el servidor esté corriendo: `npm start`
+- Revisar logs: buscar `[clientId] QR generado`
+
+### "Ninguna cuenta asignada está lista (ready)"
+
+- La cuenta debe estar en estado `ready` antes de iniciar
+- Verificar: `wa-blast accounts status <id>`
+
+### La campaña queda en `scheduled` y no reanuda
+
+- Verificar que la hora actual esté dentro de `send_window_start` y `send_window_end`
+- Verificar que hoy sea un `active_day`
+- Verificar que la cuenta no haya alcanzado su `daily_limit`: `wa-blast campaigns tracking <id>`
+- El scheduler corre cada 60s; esperar o resumir manualmente con `wa-blast campaigns start <id>`
+
+### La campaña queda en `running` indefinidamente
+
+- Si todas las cuentas asignadas se desconectaron, el loop no termina
+- Pausar o cancelar manualmente, reconectar cuentas y reiniciar
+
+### Error de compilación de `better-sqlite3`
+
+- Requiere `better-sqlite3 v12+` con Node.js v24
+- Reinstalar: `npm install better-sqlite3@latest`
+
+### Sesiones perdidas tras reiniciar
+
+- Las sesiones se guardan en `./sessions/` via `LocalAuth`
+- El servidor reconecta automáticamente al arrancar
+- Si se borra `sessions/`, hay que escanear QR de nuevo
+- Usar `POST /api/accounts/:id/reset` para forzar un QR nuevo
+
+### Cuenta baneada o mensajes no entregados
+
+- Aumentar `delay_ms` y `jitter_ms`
+- Activar `typing_sim=1`
+- Configurar `burst_size` para pausas periódicas
+- Respetar el `daily_limit` de 50 mensajes/día por cuenta
+- Una cuenta nueva necesita warm-up gradual (no enviar 100 el primer día)
+
+### Límite de cuentas activas superado
+
+- Default es `MAX_ACCOUNTS=3` en `.env`
+- Aumentar o eliminar cuentas inactivas: `wa-blast accounts delete <id>`