wappa 0.1.4__tar.gz → 0.2.4__tar.gz

{wappa-0.1.4 → wappa-0.2.4}/.gitignore

@@ -1,7 +1,7 @@
 # AI
 .claude/
 CLAUDE.md
-app/
+AGENTS.md
 logs/
 .ruff_cache
 # Python-related files

wappa-0.2.4/CHANGELOG.md

@@ -0,0 +1,76 @@
+# Changelog
+
+All notable changes to Wappa will be documented in this file.
+
+The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.0.0/),
+and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
+
+## [0.2.0] - 2025-01-11
+
+### Added
+- **PostgresDatabasePlugin**: Production-ready async PostgreSQL plugin with 30x-community inspired patterns
+  - Asyncpg-powered async engine for high-concurrency conversational apps
+  - Connection pooling with configurable pool_size, max_overflow, and timeouts
+  - Exponential backoff retry logic for transient database failures
+  - Auto-table creation at startup with SQLModel support
+  - Statement cache size configuration for Supabase pgBouncer compatibility
+  - Comprehensive error handling and health checks
+
+- **RedisPubSubPlugin**: Multi-tenant Redis PubSub messaging system
+  - Self-subscribing pattern for bot-to-bot communication
+  - Multi-tenant channel management with automatic subscription
+  - Channel-based event broadcasting and listening
+  - Graceful startup/shutdown with subscription cleanup
+  - Example implementation with tenant isolation
+
+- **AIState Pool and Cache System**: Multi-backend state management
+  - Pool 4 implementation with Redis, JSON, and Memory backends
+  - Conversation state tracking with TTL support
+  - Cache factory pattern for easy backend switching
+
+- **CLI Examples Showcase**: Two new production-ready examples
+  - `db_redis_echo_example`: PostgreSQL + Redis two-tier storage with SOLID architecture
+  - `redis_pubsub_example`: Multi-tenant PubSub with self-subscribing pattern
+  - Both now visible in `wappa examples` command
+
+### Changed
+- **SOLID Architecture Refactoring**: db_redis_echo_example refactored from monolithic to clean architecture
+  - Reduced master_event.py from 700 lines to 258 lines
+  - Separated concerns into handlers/, models/, utils/ structure
+  - Created comprehensive scaffolding guide documentation
+  - Improved testability and maintainability
+
+- **Configuration Management**: db_redis_echo_example now uses Settings class pattern
+  - Replaced os.getenv with DBRedisSettings extending base Settings
+  - Type-safe configuration with validation at startup
+  - Consistent with Wappa's configuration patterns
+
+### Fixed
+- **WhatsApp Media Message Schemas**: Added missing `url` field to all media types
+  - Fixed video, document, image, audio, and sticker message validation
+  - Support for WhatsApp's new direct download URLs in webhook payload
+  - Implemented missing abstract methods in WhatsAppVideoMessage
+
+- **Message Persistence**: Enhanced structured data storage for special message types
+  - Contact messages: Store full contact data in json_content JSONB field
+  - Location messages: Store coordinates and location metadata
+  - Interactive messages: Store button/list selections
+  - Reaction messages: Store emoji and target message reference
+
+### Documentation
+- Created wappa-project-scaffolding-guide.md with SOLID best practices
+- Created message-persistence-guide.md for database storage patterns
+- Updated db_redis_echo_example README with architecture documentation
+- Added comprehensive docstrings to PostgresDatabasePlugin
+
+### Dependencies
+- Added asyncpg>=0.31.0 for async PostgreSQL support
+
+## [0.1.10] - Previous Release
+
+Initial stable release with core WhatsApp webhook handling, messaging, and caching capabilities.
+
+---
+
+[0.2.0]: https://github.com/sashanclrp/wappa/compare/v0.1.10...v0.2.0
+[0.1.10]: https://github.com/sashanclrp/wappa/releases/tag/v0.1.10

{wappa-0.1.4 → wappa-0.2.4}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: wappa
-Version: 0.1.4
+Version: 0.2.4
 Summary: Open Source Framework to develop smart Workflows, Agents and full chat applications through WhatsApp
 Project-URL: Homepage, https://wappa.mimeia.com
 Project-URL: Documentation, https://wappa.mimeia.com/docs
@@ -223,48 +223,385 @@ Classifier: Topic :: Software Development :: Libraries :: Python Modules
 Requires-Python: >=3.12
 Requires-Dist: aiofiles>=24.1.0
 Requires-Dist: aiohttp>=3.11.0
+Requires-Dist: asyncpg>=0.31.0
 Requires-Dist: fastapi>=0.115.0
 Requires-Dist: hypercorn>=0.17.0
+Requires-Dist: numpy>=2.2.0
+Requires-Dist: openai>=1.69.0
+Requires-Dist: opencv-python-headless>=4.11.0
+Requires-Dist: pillow>=11.1.0
 Requires-Dist: pydantic-settings>=2.10.0
 Requires-Dist: pydantic>=2.8.0
 Requires-Dist: python-dotenv>=1.0.0
 Requires-Dist: python-multipart>=0.0.6
+Requires-Dist: redis>=5.2.0
 Requires-Dist: rich>=13.0.0
+Requires-Dist: sqlmodel>=0.0.24
 Requires-Dist: typer>=0.9.0
 Requires-Dist: uvicorn[standard]>=0.24.0
-Provides-Extra: ai
-Requires-Dist: numpy>=2.2.0; extra == 'ai'
-Requires-Dist: openai>=1.69.0; extra == 'ai'
-Provides-Extra: all
-Requires-Dist: numpy>=2.2.0; extra == 'all'
-Requires-Dist: openai>=1.69.0; extra == 'all'
-Requires-Dist: opencv-python-headless>=4.11.0; extra == 'all'
-Requires-Dist: pillow>=11.1.0; extra == 'all'
-Requires-Dist: redis>=5.2.0; extra == 'all'
-Requires-Dist: sqlmodel>=0.0.24; extra == 'all'
-Provides-Extra: database
-Requires-Dist: sqlmodel>=0.0.24; extra == 'database'
-Provides-Extra: dev
-Requires-Dist: black>=25.1.0; extra == 'dev'
-Requires-Dist: mypy>=1.0.0; extra == 'dev'
-Requires-Dist: pre-commit>=3.0.0; extra == 'dev'
-Requires-Dist: pytest-asyncio>=1.1.0; extra == 'dev'
-Requires-Dist: pytest>=8.4.0; extra == 'dev'
-Requires-Dist: ruff>=0.9.0; extra == 'dev'
-Provides-Extra: media
-Requires-Dist: opencv-python-headless>=4.11.0; extra == 'media'
-Requires-Dist: pillow>=11.1.0; extra == 'media'
-Provides-Extra: redis
-Requires-Dist: redis>=5.2.0; extra == 'redis'
 Description-Content-Type: text/markdown
 
-# wappa
-Open Source Framework to develop smart Workflows, Agents and full chat appllications through WhatsApp
+# Wappa 🤖
 
-So the idea of this project is to take the /app and refactor it to break this up and make it into an opensource project for example things I want: 
-1) from wapp import WhatsAppMessenger -> So then throughoutt flow in /events I can just initialize the WhatsAppMessenger and send all the messages
-2) have a terminal like ruff or black named wappa so when the user writes uvx wappa init or uv run wappa init a terminal opens to generate a clean project
+**Open Source Framework for WhatsApp Business Applications**
 
-and yeah I mean right now I have in this project, Airtable, Payment processor I want to delete does services and payment webhooks... just stick with the WhatsApp webhooks and the Messenger interface, have the event_dispatcher as the final destination of all webhooks... and literally All i want when the client hits init is just the webhooks dispatching to the eventhandler all the other folders and scaffolding shoudl be imported through the Wappa module!
+Build intelligent WhatsApp bots, workflows, and chat applications with clean architecture and modern Python.
 
-so yeah the purpose of this project is this
+[![Python 3.12+](https://img.shields.io/badge/python-3.12+-blue.svg)](https://www.python.org/downloads/)
+[![License: Apache 2.0](https://img.shields.io/badge/License-Apache%202.0-blue.svg)](https://opensource.org/licenses/Apache-2.0)
+[![FastAPI](https://img.shields.io/badge/FastAPI-0.115+-green.svg)](https://fastapi.tiangolo.com)
+[![WhatsApp Business API](https://img.shields.io/badge/WhatsApp-Business%20API-25D366.svg)](https://developers.facebook.com/docs/whatsapp)
+
+---
+
+## 🚀 What is Wappa?
+
+Wappa is a modern Python framework that transforms WhatsApp Business API into a powerful platform for building:
+
+- **🤖 Smart Chatbots** - AI-powered conversational experiences
+- **📋 Workflows** - Multi-step business processes  
+- **🎯 Agents** - Intelligent customer service automation
+- **💬 Chat Applications** - Full-featured messaging platforms
+
+**Built for developers who want clean code, not webhook complexity.**
+
+## ✨ Key Features
+
+### 🎯 **Simple & Clean**
+```python
+from wappa import Wappa, WappaEventHandler
+
+class MyBot(WappaEventHandler):
+    async def process_message(self, webhook):
+        await self.messenger.send_text("Hello!", webhook.user.user_id)
+
+app = Wappa()
+app.set_event_handler(MyBot())
+app.run()
+```
+
+### 🏗️ **Production-Ready Architecture**
+- **Clean Architecture** - Domain-driven design with dependency injection
+- **Type-Safe** - Full Pydantic models for all WhatsApp data structures
+- **Multi-Tenant** - Built for scaling across multiple business numbers
+- **Plugin System** - Extensible with Redis, CORS, rate limiting, and custom plugins
+
+### 📱 **Complete WhatsApp Support**
+- **All Message Types** - Text, media, interactive buttons, lists, templates
+- **Rich Interactions** - Buttons, lists, call-to-action messages
+- **Media Handling** - Images, videos, audio, documents with automatic upload/download
+- **Templates** - Pre-approved business message templates
+
+### 🛠️ **Developer Experience**
+```bash
+# Initialize new project
+wappa init my-bot
+
+# Start development server with auto-reload
+wappa dev app/main.py
+
+# Browse interactive examples
+wappa examples
+```
+
+### 💾 **Flexible State Management**
+```python
+# Memory, JSON file, or Redis caching
+app = Wappa(cache="redis")  # or "memory" or "json"
+
+# Automatic state persistence
+await self.state_cache.set("conversation", {"step": "greeting"})
+```
+
+## 📦 Installation
+
+### Using uv (Recommended)
+```bash
+# Create new project
+uv init my-wappa-project
+cd my-wappa-project
+
+# Add Wappa
+uv add wappa
+
+# Initialize project structure
+wappa init .
+```
+
+### Using pip
+```bash
+pip install wappa
+
+# Initialize new project
+wappa init my-wappa-project
+cd my-wappa-project
+```
+
+### Using Poetry
+```bash
+poetry new my-wappa-project
+cd my-wappa-project
+poetry add wappa
+
+# Initialize project structure  
+wappa init .
+```
+
+## 🏃‍♂️ Quick Start
+
+### 1. Get WhatsApp Business API Credentials
+
+1. Visit [Meta for Developers](https://developers.facebook.com)
+2. Create a WhatsApp Business App
+3. Get your credentials:
+   - **Access Token**
+   - **Phone Number ID** 
+   - **Business Account ID**
+
+### 2. Create Your Bot
+
+```bash
+# Initialize project
+wappa init my-bot
+cd my-bot
+
+# Configure environment
+cp .env.example .env
+# Edit .env with your WhatsApp credentials
+```
+
+### 3. Run Development Server
+
+```bash
+# Start with auto-reload
+wappa dev app/main.py
+
+# Or manually
+uv run python -m app.main
+```
+
+### 4. Test Your Bot
+
+Send a message to your WhatsApp Business number and watch it echo back!
+
+## 🎛️ Architecture Overview
+
+```mermaid
+graph TD
+    A[👤 WhatsApp User] -->|Message| B[📡 Webhook Endpoint]
+    B --> C[🔄 Event Dispatcher]
+    C --> D[⚡ Your Event Handler]
+    D --> E[💬 Messenger Interface]
+    E --> F[📱 WhatsApp API]
+
+    D --> G[💾 State Management]
+    D --> H[🧠 Business Logic]
+    G --> I[🗄️ Redis/Memory/JSON Cache]
+    H --> J[🔗 External Services]
+
+    style D fill:#333481,color:#fff,stroke:#333481,stroke-width:3px
+    style E fill:#4A90E2,color:#fff,stroke:#4A90E2,stroke-width:3px
+    style G fill:#333481,color:#fff,stroke:#333481,stroke-width:3px
+    style A fill:#25D366,color:#fff,stroke:#25D366,stroke-width:3px
+    style F fill:#25D366,color:#fff,stroke:#25D366,stroke-width:3px
+```
+
+- **Event-Driven**: Webhook → Event Handler → Response
+- **Type-Safe**: Full Pydantic models for all WhatsApp data structures  
+- **FastAPI Core**: Built on modern async Python with automatic OpenAPI docs
+- **Production Ready**: Docker support, Redis caching, structured logging
+
+## 📚 Documentation
+
+**📖 [Complete Documentation](https://wappa.mimeia.com/docs)**
+
+### Quick Links
+
+- **🚀 [Quick Start](https://wappa.mimeia.com/docs/getting-started)** - Get running in 5 minutes
+- **🏗️ [Architecture Guide](https://wappa.mimeia.com/docs/concepts/architecture)** - Understanding the framework
+- **📡 [API Reference](https://wappa.mimeia.com/docs/api/messaging)** - Complete messaging API
+- **💾 [State Management](https://wappa.mimeia.com/docs/concepts/state-management)** - Caching and persistence
+- **🚀 [Deploy to Railway](https://wappa.mimeia.com/docs/deployment/railway)** - Production deployment
+- **🛠️ [WhatsApp Setup](https://wappa.mimeia.com/docs/setup/whatsapp-setup)** - Configure WhatsApp Business API
+
+### Example Projects
+
+Explore 6 complete example applications:
+
+```bash
+# Browse examples interactively
+wappa examples
+
+# Copy specific example
+wappa examples redis-cache-demo
+```
+
+- **Simple Echo** - Basic message echoing
+- **JSON Cache Demo** - File-based state persistence
+- **Redis Cache Demo** - High-performance caching
+- **OpenAI Transcription** - Voice message processing
+- **Full-Featured Bot** - Complete production example
+- **Basic Project** - Minimal setup template
+
+## 🛠️ Advanced Usage
+
+### Builder Pattern for Complex Apps
+
+```python
+from wappa import WappaBuilder
+
+app = await (WappaBuilder()
+             .with_whatsapp(
+                 token="your_token",
+                 phone_id="your_phone_id", 
+                 business_id="your_business_id"
+             )
+             .with_redis_cache("redis://localhost:6379")
+             .with_cors_enabled()
+             .with_rate_limiting(requests_per_minute=100)
+             .build())
+
+app.set_event_handler(MyAdvancedHandler())
+app.run()
+```
+
+### Plugin System
+
+```python
+from wappa.plugins import DatabasePlugin, CorsPlugin
+
+app = Wappa(cache="redis")
+app.add_plugin(DatabasePlugin("postgresql://..."))
+app.add_plugin(CorsPlugin(allow_origins=["*"]))
+app.set_event_handler(MyHandler())
+app.run()
+```
+
+### CLI Commands
+
+```bash
+# Project management
+wappa init [directory]          # Initialize new project
+wappa examples [target]         # Browse/copy examples
+
+# Development
+wappa dev app/main.py           # Development server with auto-reload
+wappa prod app/main.py          # Production server
+
+# Help
+wappa --help                    # Show all commands
+```
+
+## 🚀 Deployment
+
+### Railway (Recommended)
+
+```bash
+# Install Railway CLI
+npm install -g @railway/cli
+
+# Login and deploy
+railway login
+railway init
+railway add redis
+railway up
+
+# Set environment variables
+railway variables set WP_ACCESS_TOKEN=your_token
+railway variables set WP_PHONE_ID=your_phone_id
+railway variables set WP_BID=your_business_id
+```
+
+See [complete Railway deployment guide](https://wappa.mimeia.com/docs/deployment/railway).
+
+### Docker
+
+```dockerfile
+FROM python:3.12-slim
+
+WORKDIR /app
+COPY . .
+
+RUN pip install uv
+RUN uv sync --frozen
+
+EXPOSE 8000
+CMD ["uv", "run", "python", "-m", "app.main"]
+```
+
+## 🧪 Development
+
+### Setup Development Environment
+
+```bash
+# Clone repository
+git clone https://github.com/sashanclrp/wappa.git
+cd wappa
+
+# Install dependencies
+uv sync --group dev
+
+# Run tests
+uv run pytest
+
+# Code formatting
+uv run ruff check .
+uv run ruff format .
+```
+
+### Project Structure
+
+```
+wappa/
+├── wappa/                  # Core framework
+│   ├── core/              # Application core & plugins
+│   ├── messaging/         # WhatsApp messaging implementation
+│   ├── persistence/       # Cache backends (Memory/JSON/Redis)
+│   ├── cli/               # CLI tools & project templates
+│   └── api/               # FastAPI routes & dependencies
+├── examples/              # Example applications
+├── docs/                  # Documentation source
+└── tests/                # Test suite
+```
+
+## 🤝 Community & Support
+
+### 💬 **Join the Community**
+- **💭 [Discord Community](https://discord.gg/wappa)** - Get help, share projects, and connect with other developers
+- **🐛 [GitHub Issues](https://github.com/sashanclrp/wappa/issues)** - Bug reports and feature requests
+- **📖 [GitHub Discussions](https://github.com/sashanclrp/wappa/discussions)** - Questions and community discussions
+
+### 📞 **Get Support**
+- **📚 [Documentation](https://wappa.mimeia.com/docs)** - Comprehensive guides and API reference
+- **💡 [Examples](https://wappa.mimeia.com/docs/resources/examples)** - 6 complete working examples
+- **🔧 [Configuration Guide](https://wappa.mimeia.com/docs/setup/whatsapp-setup)** - WhatsApp Business API setup
+
+### 🤝 **Contributing**
+We welcome contributions! Please see our [Contributing Guide](CONTRIBUTING.md) for details.
+
+- **🐛 Found a bug?** Open an [issue](https://github.com/sashanclrp/wappa/issues)
+- **💡 Have an idea?** Start a [discussion](https://github.com/sashanclrp/wappa/discussions)
+- **🔧 Want to contribute?** Check out [good first issues](https://github.com/sashanclrp/wappa/labels/good%20first%20issue)
+
+## 📋 Requirements
+
+- **Python 3.12+** - Modern Python with latest type hints
+- **WhatsApp Business API** - Meta for Developers account
+- **Redis** (optional) - For production caching and state management
+
+## 📄 License
+
+This project is licensed under the Apache License 2.0 - see the [LICENSE](LICENSE) file for details.
+
+## 🙏 Acknowledgments
+
+- **Meta** - For the WhatsApp Business API
+- **FastAPI** - For the excellent async Python framework
+- **Redis** - For high-performance caching
+- **Open Source Community** - For inspiration and contributions
+
+---
+
+**Built with ❤️ by [Mimeia](https://mimeia.com) • Open Source • Apache 2.0 License**
+
+*Transform your business communication with WhatsApp automation.*