taskbot/README.md

Task WhatsApp Chatbot

A WhatsApp chatbot for task management, designed to work with Evolution API in a secure internal network environment.

📌 Overview

This service provides a WhatsApp interface for task management within WhatsApp groups. It:

• Listens for /tarea commands in WhatsApp groups via Evolution API webhooks.
• Stores tasks, users, and groups in a SQLite database.
• Synchronizes group information periodically from the Evolution API.
• Manages user permissions and group membership (partially implemented).
• Integrates with Evolution API for WhatsApp connectivity.

🔐 Security Model

• Internal Networking: The webhook should ideally only accept connections from Evolution API via internal Docker networking (configuration dependent).
• Environment Variables: Sensitive configuration (API keys, URLs) is managed through environment variables.
• Group Restrictions: Designed to operate within pre-approved WhatsApp groups (validation logic pending integration).
• Input Validation: Basic validation exists for webhook structure; needs enhancement for command arguments and user/group IDs.

🧱 Architecture

graph TD
    A[Webhook Received] --> B{Valid Payload?}
    B -->|No| C[Ignore]
    B -->|Yes| D{Normalize IDs & Check Group Active?}
    D -->|No| C[Ignore/Log]
    D -->|Yes| E[Ensure User Exists in DB]
    E --> G{/tarea Command?}
    G -->|No| C
    G -->|Yes| J[Process Command Logic]
    J -- Success/Error --> K[Queue Response(s)]
    K --> L[Process Queue & Send Response via API]

    subgraph Database Interaction
        E --> DB[(SQLite DB)]
        J --> DB
    end
    subgraph Evolution API
        L --> EA((Evolution API))
        EA -- Webhook --> A
    end

(Diagram updated for planned flow)

✅ Current Status (as of commit 08e70ae, reviewed against code summaries)

Implemented

• Webhook server setup (src/server.ts) receiving Evolution API events.
• Database schema definition and initialization (src/db.ts).
• Group synchronization service (src/services/group-sync.ts) to fetch/store/cache groups. Includes active group caching.
• Webhook registration and verification with Evolution API (src/services/webhook-manager.ts).
• WhatsApp ID normalization utility (src/utils/whatsapp.ts).
• User creation function (src/db.ts::ensureUserExists).
• Basic /tarea command detection (src/server.ts) and processing structure (src/services/command.ts - logic is placeholder).
• Task data models (src/tasks/model.ts).
• Basic task creation service stub (src/tasks/service.ts - needs created_by and assignment logic).
• Response queue structure (src/services/response-queue.ts - process method is empty).
• Unit testing setup with in-memory database (tests/). Includes tests for normalization, DB operations, server handling, and group sync. All tests pass.
• Environment variable validation (src/server.ts, src/services/webhook-manager.ts).
• Health check endpoint (/health).

Incomplete / Missing Core Functionality

• User/Group Validation Integration: Although normalization (normalizeWhatsAppId) and user creation (ensureUserExists) functions exist, they are not yet integrated into the main request handling flow in src/server.ts to validate senders or automatically add users on first message. Similarly, the active group cache from group-sync.ts is not yet used in server.ts to filter messages from inactive/unknown groups.
• Core Command Logic: Actual processing of /tarea nueva (parsing args, calling TaskService) is missing in CommandService. Other commands (mostrar, completar) not implemented.
• Task Service Implementation: TaskService needs updating to handle created_by, assignments, and potentially methods for listing/completing tasks.
• Response Sending: ResponseQueue does not yet send messages back via the Evolution API.
• Database Migrations: No system in place to manage schema changes.
• Robust Error Handling: Comprehensive error handling, logging, and transaction management need improvement, especially around API calls and DB operations.

🛠️ Setup

Environment Variables

(Ensure these are set correctly)

# Evolution API Connection
EVOLUTION_API_URL=http://evolution-api:3000 # Or your API URL
EVOLUTION_API_KEY=your-api-key
EVOLUTION_API_INSTANCE=main # Your instance name

# WhatsApp Specific
WHATSAPP_COMMUNITY_ID=your-community-id # ID of the main community to sync groups from
CHATBOT_PHONE_NUMBER=1234567890 # Bot's normalized phone number (e.g., for assigning tasks)

# Webhook Configuration
WEBHOOK_URL=http://your-service-internal-url:3007 # URL Evolution API calls *back* to this service
PORT=3007 # Port this service listens on

# Runtime Environment
NODE_ENV=production # Or development

# Optional
# GROUP_SYNC_INTERVAL_MS=3600000 # Sync interval in ms (default: 24h)

Development Setup

# Install dependencies
bun install

# Copy .env.example to .env and fill in values
cp .env.example .env

# Start development server (watches for changes)
bun run dev

# Run tests
bun test

📅 Roadmap & Priorities (Plan)

Phase 1: User & Group Foundation (Highest Priority)

• Create WhatsApp ID Normalization Utility: (src/utils/whatsapp.ts) Handle different ID formats.
• Implement ensureUserExists: (src/db.ts) Add users to DB on first interaction.
• Implement isGroupActive Check: (src/services/group-sync.ts, src/server.ts) Cache exists in group-sync.ts. Needs integration into server.ts.
• Integrate Validation in Server: (src/server.ts) Use normalization, ensureUserExists, and active group check before processing commands.

Phase 2: Implement /tarea nueva Command (High Priority)

• Update TaskService.createTask: (src/tasks/service.ts) Handle created_by and assignments (including adding assigned users via ensureUserExists).
• Implement /tarea nueva Logic: (src/services/command.ts) Parse description, due date, mentions; call TaskService; generate response messages.

Phase 3: Implement Response Sending (High Priority)

• Implement ResponseQueue.process: (src/services/response-queue.ts) Send queued messages via Evolution API's send endpoint.
• Trigger Queue Processing: (src/server.ts) Call ResponseQueue.process() after command handling.
• Persist Response Queue in Database: (src/services/response-queue.ts, src/db.ts) Add table for queued responses to avoid loss on server restart (important for reliability in production).

Phase 4: Further Commands & Refinements (Medium Priority)

• Implement /tarea mostrar [group|mine] command.
• Implement /tarea completar <task_id> command.
• Add Database Migrations system.
• Improve Error Handling & Logging (API calls, DB transactions).
• Refine Group Sync (Delta updates).

Phase 5: Advanced Features (Low Priority)

• Add task reminders system.
• Implement user permissions system.
• Add rate limiting.
• Create task history tracking.

🔑 Key Considerations & Caveats

• WhatsApp ID Normalization: Crucial for consistently identifying users and groups. Needs careful implementation to handle edge cases. (Utility function exists).
• Response Latency: Sending responses requires an API call back to Evolution. Ensure the ResponseQueue processing is efficient.
• Response Queue Persistence: Currently in-memory; consider persisting in DB to prevent message loss on restarts (added to Phase 3 roadmap).
• Group Sync: The current full sync might be slow or rate-limited with many groups. Delta updates are recommended long-term.
• Error Handling: Failures in command processing or response sending should be logged clearly and potentially reported back to the user. Database operations should use transactions for atomicity (especially task+assignment creation).
• State Management: The current design is stateless. Complex interactions might require state persistence later.
• Security: Ensure group/user validation logic is robust once integrated.

🧪 Testing

Running Tests

bun test

Test Coverage

• Database initialization and basic operations (db.test.ts).
• Webhook validation (basic) (webhook-manager.test.ts).
• Command parsing (basic structure) (command.test.ts).
• Environment checks (server.test.ts).
• Basic error handling (server.test.ts).
• WhatsApp ID normalization (whatsapp.test.ts).
• Group sync operations (group-sync.test.ts).
• All tests pass (78 pass, 1 fixed in commit 08e70ae).

Test Coverage

• Database initialization and basic operations (db.test.ts).
• Webhook validation (basic) (webhook-manager.test.ts).
• Command parsing (basic structure) (command.test.ts).
• Environment checks (server.test.ts).
• Basic error handling (server.test.ts).
• WhatsApp ID normalization (whatsapp.test.ts).
• Group sync operations (group-sync.test.ts).
• Needed: Tests for ensureUserExists integration, isGroupActive integration, CommandService logic, ResponseQueue processing (mocking API), TaskService operations.

🧑‍💻 Contributing

1. Fork the repository
2. Create a feature branch (git checkout -b feature/implement-user-validation)
3. Add/update tests for new functionality
4. Ensure tests pass (bun test)
5. Submit a pull request

📚 Documentation

For detailed API documentation and architecture decisions, see the docs/ directory (if created).