diff --git a/README.md b/README.md index 9b87522..c059815 100644 --- a/README.md +++ b/README.md @@ -1,13 +1,21 @@ # Task WhatsApp Chatbot -## Future Steps +A WhatsApp chatbot for task management, designed to work with Evolution API in a secure internal network environment. -### Core Principles -1. **Trust-but-Verify Approach**: Leverage WhatsApp's message metadata to minimize API calls while maintaining security -2. **Progressive Validation**: Verify users naturally through interactions rather than upfront checks -3. **Background Reconciliation**: Use periodic syncs to maintain data accuracy without impacting real-time performance +## ๐Ÿ“Œ 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 -### Message Processing Flow +## ๐Ÿ” 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 + +## ๐Ÿงฑ Architecture ```mermaid graph TD A[Webhook Received] --> B{Valid Payload?} @@ -24,25 +32,77 @@ graph TD H -->|No| J[Process Command] ``` -### Alias for actions - -- I want that, when an user sends `/tarea` to the bot, with no extra arguments, it should show all the pending tasks for the user in a private message (the same behaviour as calling `/tarea mostrar` - -### Periodic Sync Strategy -1. **Rotating Group Check**: - - Verify 1-2 groups per sync cycle - - Prioritize recently active groups -2. **User Reconciliation**: - - Add newly discovered users - - Update `last_confirmed` for active users -3. **Optimizations**: - - Cache active group IDs in memory - - Batch database writes - - Exponential backoff for API failures - -### Security Considerations -- Reject messages from: - - Non-community groups - - Unknown private chats -- Implement rate limiting -- Maintain audit logs of verification events +## โœ… 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 + +## ๐Ÿ› ๏ธ Setup +### Environment Variables +```env +EVOLUTION_API_URL=http://evolution-api:3000 +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 +``` + +### Development Setup +```bash +# Install dependencies +bun install + +# Start development server +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 + +## ๐Ÿงช Testing +### Running Tests +```bash +bun test +``` + +### Test Coverage +- Webhook validation +- Command parsing +- Environment checks +- Basic error handling +- Input validation + +## ๐Ÿง‘โ€๐Ÿ’ป Contributing +1. Fork the repository +2. Create a feature branch +3. Add tests for new functionality +4. Submit a pull request + +## ๐Ÿ“š Documentation +For detailed API documentation and architecture decisions, see the [docs/](docs/) directory.