brobert
/
taskbot
1
0
Fork 0
Code Issues Pull Requests Packages Projects Releases Wiki Activity

docs: Update README with current status and development plan

Browse Source
main
borja (aider) 2 months ago
parent dd32a3dd11
commit 5f457097b5
1 changed files with 116 additions and 60 deletions
Show Stats Download Patch File Download Diff File

176
README.md
Unescape Escape View File

@ -4,54 +4,87 @@ A WhatsApp chatbot for task management, designed to work with Evolution API in a
## 📌 Overview ## 📌 Overview
This service provides a WhatsApp interface for task management within WhatsApp groups. It: This service provides a WhatsApp interface for task management within WhatsApp groups. It:
- Listens for `/tarea` commands in WhatsApp groups - Listens for `/tarea` commands in WhatsApp groups via Evolution API webhooks.
- Stores tasks in a SQLite database - Stores tasks, users, and groups in a SQLite database.
- Manages user permissions and group membership - Synchronizes group information periodically from the Evolution API.
- Integrates with Evolution API for WhatsApp connectivity - Manages user permissions and group membership (partially implemented).
- Integrates with Evolution API for WhatsApp connectivity.
## 🔐 Security Model ## 🔐 Security Model
- **Internal Networking**: The webhook only accepts connections from Evolution API via internal Docker networking - **Internal Networking**: The webhook should ideally only accept connections from Evolution API via internal Docker networking (configuration dependent).
- **Environment Variables**: Sensitive configuration is managed through environment variables - **Environment Variables**: Sensitive configuration (API keys, URLs) is managed through environment variables.
- **Group Restrictions**: Only operates within pre-approved WhatsApp groups - **Group Restrictions**: Designed to operate within pre-approved WhatsApp groups (validation logic pending implementation).
- **Input Validation**: Sanitizes and validates all user inputs - **Input Validation**: Basic validation exists for webhook structure; needs enhancement for command arguments and user/group IDs.
## 🧱 Architecture ## 🧱 Architecture
```mermaid ```mermaid
graph TD graph TD
A[Webhook Received] --> B{Valid Payload?} A[Webhook Received] --> B{Valid Payload?}
B -->|No| C[Ignore] B -->|No| C[Ignore]
B -->|Yes| D{From Known Group?} B -->|Yes| D{Normalize IDs & Check Group Active?}
D -->|Yes| E[Update User Last Seen] D -->|No| C[Ignore/Log]
D -->|No| F{Private Chat + Known User?} D -->|Yes| E[Ensure User Exists in DB]
F -->|No| C
F -->|Yes| E
E --> G{/tarea Command?} E --> G{/tarea Command?}
G -->|No| C G -->|No| C
G -->|Yes| H{New User?} G -->|Yes| J[Process Command Logic]
H -->|Yes| I[Add to DB] J -- Success/Error --> K[Queue Response(s)]
H -->|No| J[Process Command] 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 Features
- Task creation with optional due dates ## ✅ Current Status (as of commit dd32a3d)
- Basic command parsing (`/tarea nueva`, `/tarea mostrar`) ### Implemented
- Group membership tracking - Webhook server setup (`src/server.ts`) receiving Evolution API events.
- SQLite database persistence - Database schema definition and initialization (`src/db.ts`).
- Health check endpoint - Group synchronization service (`src/services/group-sync.ts`) to fetch/store/cache groups.
- Environment validation - Webhook registration and verification with Evolution API (`src/services/webhook-manager.ts`).
- Input validation for dates and commands - 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 ## 🛠️ Setup
### Environment Variables ### Environment Variables
*(Ensure these are set correctly)*
```env ```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_KEY=your-api-key
EVOLUTION_API_INSTANCE=main EVOLUTION_API_INSTANCE=main # Your instance name
WHATSAPP_COMMUNITY_ID=your-community-id
CHATBOT_PHONE_NUMBER=1234567890 # WhatsApp Specific
WEBHOOK_URL=https://your-webhook.com WHATSAPP_COMMUNITY_ID=your-community-id # ID of the main community to sync groups from
PORT=3007 CHATBOT_PHONE_NUMBER=1234567890 # Bot's normalized phone number (e.g., for assigning tasks)
NODE_ENV=production
# 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 ### Development Setup
@ -59,31 +92,52 @@ NODE_ENV=production
# Install dependencies # Install dependencies
bun install 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 bun run dev
# Run tests # Run tests
bun test bun test
``` ```
## 📅 Roadmap ## 📅 Roadmap & Priorities (Plan)
### High Priority
- [ ] Implement ResponseQueue processing logic with retries ### Phase 1: User & Group Foundation (Highest Priority)
- [ ] Add database schema validation and migrations - [ ] **Create WhatsApp ID Normalization Utility:** (`src/utils/whatsapp.ts`) Handle different ID formats.
- [ ] Add error recovery with transaction rollback - [ ] **Implement `ensureUserExists`:** (`src/db.ts`) Add users to DB on first interaction.
- [ ] Implement group sync delta updates - [ ] **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.
### Medium Priority
- [ ] Add task assignment and ownership ### Phase 2: Implement `/tarea nueva` Command (High Priority)
- [ ] Implement user permissions system - [ ] **Update `TaskService.createTask`:** (`src/tasks/service.ts`) Handle `created_by` and assignments (including adding assigned users via `ensureUserExists`).
- [ ] Add rate limiting for API calls - [ ] **Implement `/tarea nueva` Logic:** (`src/services/command.ts`) Parse description, due date, mentions; call `TaskService`; generate response messages.
- [ ] Create task history tracking
### Phase 3: Implement Response Sending (High Priority)
### Low Priority - [ ] **Implement `ResponseQueue.process`:** (`src/services/response-queue.ts`) Send queued messages via Evolution API's send endpoint.
- [ ] Add task reminders system - [ ] **Trigger Queue Processing:** (`src/server.ts`) Call `ResponseQueue.process()` after command handling.
- [ ] Implement multi-language support
- [ ] Create analytics dashboard ### Phase 4: Further Commands & Refinements (Medium Priority)
- [ ] Add user-friendly task list UI - [ ] 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.
* **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 ## 🧪 Testing
### Running Tests ### Running Tests
@ -92,17 +146,19 @@ bun test
``` ```
### Test Coverage ### Test Coverage
- Webhook validation - Database initialization and basic operations.
- Command parsing - Webhook validation (basic).
- Environment checks - Command parsing (basic structure).
- Basic error handling - Environment checks.
- Input validation - Basic error handling.
- **Needed:** Tests for ID normalization, `ensureUserExists`, `isGroupActive`, `CommandService` logic, `ResponseQueue` processing (mocking API), `TaskService` operations.
## 🧑‍💻 Contributing ## 🧑‍💻 Contributing
1. Fork the repository 1. Fork the repository
2. Create a feature branch 2. Create a feature branch (`git checkout -b feature/implement-user-validation`)
3. Add tests for new functionality 3. Add/update tests for new functionality
4. Submit a pull request 4. Ensure tests pass (`bun test`)
5. Submit a pull request
## 📚 Documentation ## 📚 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).

Write Preview
Loading…
Cancel
Save