Taskbot

Bot de tareas para WhatsApp con sincronización de grupos, recordatorios y control de acceso.

Taskbot ayuda a coordinar grupos en WhatsApp: crea y asigna tareas, recuerda pendientes y aplica gobierno de acceso por grupo. Está pensado para equipos y comunidades que ya operan en WhatsApp y quieren visibilidad ligera sin salir de la app.

Qué problema resuelve

• Tareas que se pierden en el chat y falta de responsables o fechas.
• Falta de visibilidad de pendientes por grupo o persona.
• Necesidad de limitar en qué grupos opera el bot (descubrir y aprobar).

Características

• Gestión de tareas: crear, asignar, reclamar/soltar, fechas límite y código corto de referencia.
• Edición desde la web: reclamar/soltar, editar descripción y actualizar fecha de vencimiento desde /app; completar tareas y ver “Completadas (24 h)”.
• Recordatorios configurables por usuario (frecuencia y hora, respetando zona horaria).
• Control de acceso por grupos: modos off, discover y enforce; aprobación y bloqueo por admins.
• Sincronización de grupos y miembros con cachés y schedulers configurables.
• Alias de identidad con normalización de IDs.
• Acceso web por token mágico (/t web) con página intermedia anti-preview y sesión por cookie (idle 2h); tokens de 10 min de un solo uso.
• Métricas listas para Prometheus en el endpoint /metrics.
• Acks por reacciones en WhatsApp: 🤖/⚠️ al procesar comandos y ✅ al completar tareas dentro de un TTL configurable; idempotencia y gating por grupo/alcance; requiere Evolution API sendReaction (key.fromMe=false).
• Rate limiting por usuario para evitar abuso.
• Persistencia simple con SQLite, migraciones automáticas y PRAGMAs seguros (WAL, FK, etc.).

Qué no es (limitaciones)

• No es un framework general de bots ni un CRM.
• No conecta directamente con WhatsApp: requiere Evolution API.
• No gestiona flujos conversacionales complejos ni multimedia avanzada.
• Panel web: login operativo, lista de tareas con acciones básicas (reclamar/soltar, editar texto y fecha, completar; sección “Completadas (24 h)”), vista de grupos (contadores "abiertas" y "sin responsable" con lista sin límite y botón “Reclamar”; tarjetas ordenadas por cantidad de “sin responsable”) y página de preferencias de recordatorios; la interacción principal sigue siendo WhatsApp.
• Está optimizado para un despliegue por comunidad/instancia (no multi-tenant masivo).

Cómo funciona (alto nivel)

1. Evolution API envía eventos al webhook de Taskbot.
2. El servidor normaliza el mensaje, aplica control de acceso por grupo y rate limit.
3. Los servicios de dominio (tareas, recordatorios, alias, colas) operan sobre SQLite.
4. Las respuestas y reacciones se encolan y se envían a través de Evolution API.
5. Schedulers ejecutan sincronización de grupos/miembros, recordatorios y tareas de mantenimiento.
6. Las métricas se exponen en /metrics (Prometheus o JSON).
7. Un proxy interno en Bun sirve web y bot bajo el mismo dominio: /webhook y /metrics → bot; el resto → web. Actualmente, la compresión HTTP está desactivada temporalmente (sin Content-Encoding).

Uso básico

• Los usuarios interactúan con comandos sencillos en WhatsApp para crear tareas, ver pendientes, asignarse o soltar.
• Los administradores pueden aprobar o bloquear grupos cuando el modo de acceso está en discover/enforce.
• Los recordatorios se configuran por usuario (frecuencia y hora) y respetan la zona horaria.
• Formato de fechas en comandos: se aceptan YYYY-MM-DD y YY-MM-DD (YY → 20YY). También se admiten los tokens "hoy" y "mañana". Las fechas se almacenan normalizadas como YYYY-MM-DD y se muestran como dd/MM en los listados.

Instalación rápida

Requisitos:

• Node.js LTS.
• Acceso a una instancia de Evolution API.
• URL pública para recibir el webhook.
• Almacenamiento local para SQLite (directorio data/).

Pasos:

• Clonar el repositorio e instalar dependencias.
• Configurar variables de entorno.
• Arrancar el servidor; la base de datos (data/tasks.db) y migraciones se gestionan automáticamente.

Recomendación: planificar copias de seguridad periódicas del directorio data/.

Nota (desarrollo): si al ejecutar bun run dev tienes problemas con la base de datos de la web, elimina el contenido del directorio apps/web/tmp para que se regenere por completo (se volverá a crear en el siguiente arranque).

Configuración esencial

Variables clave:

• EVOLUTION_API_URL, EVOLUTION_API_INSTANCE, EVOLUTION_API_KEY.
• ADMIN_USERS (lista de IDs/JIDs autorizados).
• GROUP_GATING_MODE: off | discover | enforce.
• REACTIONS_ENABLED: 'true'|'false' para activar reacciones (por defecto 'false').
• REACTIONS_SCOPE: 'groups'|'all' para limitar reacciones a grupos o permitir en DMs (por defecto 'groups').
• REACTIONS_TTL_DAYS: días para permitir la reacción ✅ tras completar (por defecto 14).
• RQ_REACTIONS_MAX_ATTEMPTS: reintentos máximos para jobs de reacción (si no se define, aplica el global).
• WHATSAPP_COMMUNITY_ID (para sincronización de grupos).
• TZ (por defecto Europe/Madrid).
• REMINDERS_GRACE_MINUTES (ventana de gracia tras la hora; por defecto 60).
• ALLOWED_GROUPS (semilla inicial), NOTIFY_ADMINS_ON_DISCOVERY.
• HEALTH_CHECK_INTERVAL_MS (ms, por defecto 60000) y HEALTH_CHECK_RESTART_COOLDOWN_MS (ms, por defecto 900000).
• METRICS_ENABLED, PORT.
• WEB_BASE_URL (host público de la web para generar enlaces absolutos; usado por /t web).
• Rate limit: RATE_LIMIT_PER_MIN, RATE_LIMIT_BURST.
• Intervalos y retención: GROUP_SYNC_INTERVAL_MS, GROUP_MEMBERS_SYNC_INTERVAL_MS, GROUP_MEMBERS_INACTIVE_RETENTION_DAYS.
• DB_PATH: ruta al archivo SQLite. Tiene prioridad sobre DATA_DIR y permite aislar BD por rama/entorno. Ej.: DB_PATH='./data/tasks.db'
• DATA_DIR: directorio raíz para la base de datos SQLite compartida (por defecto ./data).

Consulta:

• docs/operations.md para operación, endpoints y variables de entorno.
• docs/architecture.md para una visión técnica y responsabilidades por módulo.

Operación y mantenimiento

• /metrics expone contadores y gauges; puede deshabilitarse por configuración. Principales series:
  • evolution_instance_state{instance, state} (gauge): 1 para el estado actual de Evolution (open/connecting/closed/unreachable…), 0 al estado anterior en cada transición.
  • evolution_instance_last_state_change_ts{instance} (gauge): timestamp epoch (s) del último cambio de estado.
  • evolution_instance_state_changes_total{instance} (counter): número de transiciones de estado observadas.
  • evolution_instance_restart_attempts_total{instance} (counter): intentos de reinicio cuando el estado no es 'open'.
  • evolution_instance_restart_success_total{instance} (counter): reinicios exitosos.
  • evolution_health_check_errors_total{instance} (counter): errores HTTP/red al consultar estado.
• Schedulers configurables; se evitan en entornos de test.
• Migraciones up-only al arranque; logging de eventos de migración.
• Copias de seguridad: respaldar el directorio data/ y planificar retención.

Pruebas (bun:test)

• Suite web implementada con build programático: los tests construyen apps/web (adapter-node) una única vez, arrancan el servidor en un puerto efímero y hacen peticiones HTTP reales.
• Sin dependencias externas: bun:test, bun:sqlite y helpers propios.
• Cobertura actual: endpoints /api/me/tasks (gating, orden, búsqueda con ESCAPE, soonDays y paginación), /api/me/preferences (GET y POST) y página /app/preferences; además de helpers de servidor para build/arranque.
• Ejecución: bun test tests/web

Estado y licencia

• Nombre provisional: “Taskbot”.
• Licencia por definir (software libre; se evaluará GPLv3/AGPL/MIT/Apache-2.0).
• Etapa 1 (autenticación web): completada. /login (GET intermedio + POST), sesión con idle 2h, logout y ruta /app protegida; desplegado con proxy interno en Bun.
• Etapa 2 (lectura de datos - MVP): completada. GET /api/me/tasks (orden por due_date asc con NULL al final, búsqueda con ESCAPE, filtros soonDays/dueBefore, paginación page/limit), GET /api/me/groups (contadores open/unassigned) y GET /api/groups/:id/tasks (unassignedFirst, onlyUnassigned, limit). UI: /app (Mis tareas, filtros/búsqueda/paginación) y /app/groups (bloque “sin responsable” con prefetch).
• Etapa 3 (preferencias): completada. GET/POST /api/me/preferences y página /app/preferences con cálculo de “próximo recordatorio” coherente con la TZ y semántica del bot.
• Edición de tareas en web: completada. Reclamar/soltar, editar fecha y descripción desde /app; completar tareas y mostrar “Completadas (24 h)”; reclamar desde /app/groups; lista "sin responsable" sin límite y fichas ordenadas por cantidad de "sin responsable" (con gating y validación).
• Reacciones en WhatsApp: completadas. 🤖/⚠️ al procesar comandos y ✅ al completar dentro de TTL; idempotencia, gating por grupo (enforce) y alcance configurable (groups|all).
• Roadmap y contribuciones: pendientes de publicación.

Enlaces

• Documentación de arquitectura: docs/architecture.md
• Operación y configuración: docs/operations.md