Add basic READMEs

2025-05-23 13:20:07 +02:00 · 2025-05-23 13:20:07 +02:00 · 3659a4ef38
commit 3659a4ef38
parent 58e713c98b
6 changed files with 864 additions and 50 deletions
--- a/apps/bridge-whatsapp/README.md
+++ b/apps/bridge-whatsapp/README.md
@ -0,0 +1,172 @@
+# Bridge WhatsApp
+
+WhatsApp integration service for the CDR Link communication bridge system.
+
+## Overview
+
+Bridge WhatsApp provides a REST API for sending and receiving WhatsApp messages using the Baileys library (WhatsApp Web API). It handles bot session management, message routing, and media processing for WhatsApp communication channels.
+
+## Features
+
+- **Bot Management**: Register and manage multiple WhatsApp bot sessions
+- **Message Handling**: Send and receive text messages with formatting
+- **Media Support**: Handle images, documents, audio, and video files
+- **QR Code Authentication**: Web-based WhatsApp authentication
+- **REST API**: Simple HTTP endpoints for integration
+
+## Development
+
+### Prerequisites
+
+- Node.js >= 20
+- npm >= 10
+- PostgreSQL database (for bot configuration)
+
+### Setup
+
+```bash
+# Install dependencies
+npm install
+
+# Build TypeScript
+npm run build
+
+# Run development server
+npm run dev
+
+# Start production server
+npm run start
+```
+
+### Environment Variables
+
+- `PORT` - Server port (default: 5000)
+- `DATABASE_URL` - PostgreSQL connection string (optional)
+- Additional WhatsApp-specific configuration as needed
+
+### Available Scripts
+
+- `npm run build` - Compile TypeScript
+- `npm run dev` - Development mode with auto-reload
+- `npm run start` - Start production server
+
+## API Endpoints
+
+### Bot Management
+
+- `POST /api/bots/:token` - Register/initialize a bot
+- `GET /api/bots/:token` - Get bot status and QR code
+
+### Messaging
+
+- `POST /api/bots/:token/send` - Send a message
+- `POST /api/bots/:token/receive` - Webhook for incoming messages
+
+### Request/Response Format
+
+#### Send Message
+
+```json
+{
+  "to": "1234567890@s.whatsapp.net",
+  "message": "Hello World",
+  "media": {
+    "url": "https://example.com/image.jpg",
+    "type": "image"
+  }
+}
+```
+
+#### Receive Message Webhook
+
+```json
+{
+  "from": "1234567890@s.whatsapp.net",
+  "message": "Hello",
+  "timestamp": "2024-01-01T00:00:00Z",
+  "media": {
+    "url": "https://...",
+    "type": "image",
+    "mimetype": "image/jpeg"
+  }
+}
+```
+
+## Architecture
+
+### Server Framework
+
+Built with Hapi.js for:
+
+- Route validation
+- Plugin architecture
+- Error handling
+- Request lifecycle
+
+### WhatsApp Integration
+
+Uses @whiskeysockets/baileys:
+
+- WhatsApp Web protocol
+- Multi-device support
+- Message encryption
+- Media handling
+
+### Session Management
+
+- File-based session storage
+- Automatic reconnection
+- QR code regeneration
+- Session cleanup
+
+## Media Handling
+
+Supported media types:
+
+- **Images**: JPEG, PNG, GIF
+- **Documents**: PDF, DOC, DOCX
+- **Audio**: MP3, OGG, WAV
+- **Video**: MP4, AVI
+
+Media is processed and uploaded before sending.
+
+## Error Handling
+
+- Connection errors trigger reconnection
+- Invalid sessions regenerate QR codes
+- API errors return appropriate HTTP status codes
+- Comprehensive logging for debugging
+
+## Security
+
+- Token-based bot authentication
+- Message validation
+- Rate limiting (configurable)
+- Secure session storage
+
+## Integration
+
+Designed to work with:
+
+- **bridge-worker**: Processes WhatsApp message jobs
+- **bridge-frontend**: Manages bot configuration
+- External webhooks for message routing
+
+## Docker Support
+
+```bash
+# Build image
+docker build -t link-stack/bridge-whatsapp .
+
+# Run container
+docker run -p 5000:5000 link-stack/bridge-whatsapp
+```
+
+## Testing
+
+While test configuration exists (jest.config.json), tests should be implemented for:
+
+- API endpoint validation
+- Message processing logic
+- Session management
+- Error scenarios