diff --git a/README.md b/README.md index c059815..37cf1b3 100644 --- a/README.md +++ b/README.md @@ -4,54 +4,87 @@ A WhatsApp chatbot for task management, designed to work with Evolution API in a ## ๐Ÿ“Œ Overview This service provides a WhatsApp interface for task management within WhatsApp groups. It: -- Listens for `/tarea` commands in WhatsApp groups -- Stores tasks in a SQLite database -- Manages user permissions and group membership -- Integrates with Evolution API for WhatsApp connectivity +- 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 only accepts connections from Evolution API via internal Docker networking -- **Environment Variables**: Sensitive configuration is managed through environment variables -- **Group Restrictions**: Only operates within pre-approved WhatsApp groups -- **Input Validation**: Sanitizes and validates all user inputs +- **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 implementation). +- **Input Validation**: Basic validation exists for webhook structure; needs enhancement for command arguments and user/group IDs. ## ๐Ÿงฑ Architecture ```mermaid graph TD A[Webhook Received] --> B{Valid Payload?} B -->|No| C[Ignore] - B -->|Yes| D{From Known Group?} - D -->|Yes| E[Update User Last Seen] - D -->|No| F{Private Chat + Known User?} - F -->|No| C - F -->|Yes| E + 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| H{New User?} - H -->|Yes| I[Add to DB] - H -->|No| J[Process Command] + 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 ``` - -## โœ… Current Features -- Task creation with optional due dates -- Basic command parsing (`/tarea nueva`, `/tarea mostrar`) -- Group membership tracking -- SQLite database persistence -- Health check endpoint -- Environment validation -- Input validation for dates and commands +*(Diagram updated for planned flow)* + +## โœ… Current Status (as of commit dd32a3d) +### 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. +- Webhook registration and verification with Evolution API (`src/services/webhook-manager.ts`). +- Basic `/tarea` command detection and argument parsing structure (`src/server.ts`). +- 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/`). +- Environment variable validation (`src/server.ts`, `src/services/webhook-manager.ts`). +- Health check endpoint (`/health`). + +### Incomplete / Missing Core Functionality +- **User/Group Validation:** No normalization of WhatsApp IDs or checking if messages originate from active, known groups. Users are not automatically added to the DB. +- **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)* ```env -EVOLUTION_API_URL=http://evolution-api:3000 +# Evolution API Connection +EVOLUTION_API_URL=http://evolution-api:3000 # Or your API URL EVOLUTION_API_KEY=your-api-key -EVOLUTION_API_INSTANCE=main -WHATSAPP_COMMUNITY_ID=your-community-id -CHATBOT_PHONE_NUMBER=1234567890 -WEBHOOK_URL=https://your-webhook.com -PORT=3007 -NODE_ENV=production +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 @@ -59,31 +92,52 @@ NODE_ENV=production # Install dependencies bun install -# Start development server +# 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 -### High Priority -- [ ] Implement ResponseQueue processing logic with retries -- [ ] Add database schema validation and migrations -- [ ] Add error recovery with transaction rollback -- [ ] Implement group sync delta updates - -### Medium Priority -- [ ] Add task assignment and ownership -- [ ] Implement user permissions system -- [ ] Add rate limiting for API calls -- [ ] Create task history tracking - -### Low Priority -- [ ] Add task reminders system -- [ ] Implement multi-language support -- [ ] Create analytics dashboard -- [ ] Add user-friendly task list UI +## ๐Ÿ“… 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`) Validate incoming messages are from known, active groups. +- [ ] **Integrate Validation in Server:** (`src/server.ts`) Use normalization and validation 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. + +### Phase 4: Further Commands & Refinements (Medium Priority) +- [ ] Implement `/tarea mostrar [group|mine]` command. +- [ ] Implement `/tarea completar ` 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. +* **Response Latency:** Sending responses requires an API call back to Evolution. Ensure the `ResponseQueue` processing is efficient. +* **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. ## ๐Ÿงช Testing ### Running Tests @@ -92,17 +146,19 @@ bun test ``` ### Test Coverage -- Webhook validation -- Command parsing -- Environment checks -- Basic error handling -- Input validation +- Database initialization and basic operations. +- Webhook validation (basic). +- Command parsing (basic structure). +- Environment checks. +- Basic error handling. +- **Needed:** Tests for ID normalization, `ensureUserExists`, `isGroupActive`, `CommandService` logic, `ResponseQueue` processing (mocking API), `TaskService` operations. ## ๐Ÿง‘โ€๐Ÿ’ป Contributing 1. Fork the repository -2. Create a feature branch -3. Add tests for new functionality -4. Submit a pull request +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/](docs/) directory. +For detailed API documentation and architecture decisions, see the [docs/](docs/) directory (if created).