wappa 0.1.5__py3-none-any.whl → 0.1.7__py3-none-any.whl

wappa/__init__.py

@@ -3,83 +3,27 @@ Wappa - Open Source WhatsApp Business Framework
 
 A clean, modern Python library for building WhatsApp Business applications
 with minimal setup and maximum flexibility.
-"""
-
-from .core.config.settings import settings
-from .core.events import (
-    DefaultErrorHandler,
-    DefaultHandlerFactory,
-    DefaultMessageHandler,
-    DefaultStatusHandler,
-    ErrorLogStrategy,
-    MessageLogStrategy,
-    StatusLogStrategy,
-    WappaEventHandler,
-    WebhookURLFactory,
-    webhook_url_factory,
-)
 
-# Factory System
-from .core.factory import WappaBuilder, WappaPlugin
+Clean Import Interface (SRP Compliance):
+- Only framework essentials exposed at top level
+- Domain-specific imports available via wappa.domain paths
+- Follows Clean Architecture principles
+"""
 
-# Core Plugins
-from .core.plugins import (
-    AuthPlugin,
-    CORSPlugin,
-    CustomMiddlewarePlugin,
-    DatabasePlugin,
-    RateLimitPlugin,
-    RedisPlugin,
-    WebhookPlugin,
-)
+# Framework Essentials Only (SRP: Framework Foundation)
 from .core.wappa_app import Wappa
+from .core.events.event_handler import WappaEventHandler
+from .core.factory import WappaBuilder, WappaPlugin
 
-# Database System
-from .database import DatabaseAdapter, MySQLAdapter, PostgreSQLAdapter, SQLiteAdapter
-
-# Messaging Interface
-from .domain.interfaces.messaging_interface import IMessenger
-from .messaging.whatsapp.messenger.whatsapp_messenger import WhatsAppMessenger
-
-# Redis System
-from .persistence.redis import RedisClient, RedisManager
+# Dynamic version from pyproject.toml
+from .core.config.settings import settings
 
 __version__ = settings.version
+
 __all__ = [
-    # Core Framework
+    # Core Framework Components
     "Wappa",
-    "WappaEventHandler",
-    # Factory System
+    "WappaEventHandler", 
     "WappaBuilder",
     "WappaPlugin",
-    # Core Plugins
-    "DatabasePlugin",
-    "RedisPlugin",
-    "WebhookPlugin",
-    "CORSPlugin",
-    "AuthPlugin",
-    "RateLimitPlugin",
-    "CustomMiddlewarePlugin",
-    # Database Adapters
-    "DatabaseAdapter",
-    "PostgreSQLAdapter",
-    "SQLiteAdapter",
-    "MySQLAdapter",
-    # Redis System
-    "RedisClient",
-    "RedisManager",
-    # Webhook Management
-    "WebhookURLFactory",
-    "webhook_url_factory",
-    # Default Handlers
-    "DefaultMessageHandler",
-    "DefaultStatusHandler",
-    "DefaultErrorHandler",
-    "DefaultHandlerFactory",
-    "MessageLogStrategy",
-    "StatusLogStrategy",
-    "ErrorLogStrategy",
-    # Messaging
-    "WhatsAppMessenger",
-    "IMessenger",
 ]

wappa/cli/examples/init/.gitignore

@@ -0,0 +1,69 @@
+# Wappa
+logs/
+
+# Environment variables
+.env
+.env.local
+.env.development
+.env.production
+
+# Python
+__pycache__/
+*.py[cod]
+*$py.class
+*.so
+.Python
+build/
+develop-eggs/
+dist/
+downloads/
+eggs/
+.eggs/
+lib/
+lib64/
+parts/
+sdist/
+var/
+wheels/
+share/python-wheels/
+*.egg-info/
+.installed.cfg
+*.egg
+MANIFEST
+
+# Virtual environments
+.venv/
+venv/
+ENV/
+env/
+
+# IDE
+.vscode/
+.idea/
+*.swp
+*.swo
+
+# OS
+.DS_Store
+Thumbs.db
+
+# Logs
+app/logs/
+logs/
+*.log
+
+# Redis dumps
+dump.rdb
+
+# Temporary files
+.tmp/
+temp/
+tmp/
+
+# Coverage reports
+htmlcov/
+.tox/
+.coverage
+.coverage.*
+.cache
+.pytest_cache/

wappa/cli/examples/init/pyproject.toml

@@ -0,0 +1,7 @@
+[project]
+name = "wappa-init"
+version = "0.1.0"
+requires-python = ">=3.12"
+dependencies = [
+    "wappa>=0.1.6",
+]

wappa/cli/examples/json_cache_example/.gitignore

@@ -0,0 +1,69 @@
+# Wappa
+logs/
+
+# Environment variables
+.env
+.env.local
+.env.development
+.env.production
+
+# Python
+__pycache__/
+*.py[cod]
+*$py.class
+*.so
+.Python
+build/
+develop-eggs/
+dist/
+downloads/
+eggs/
+.eggs/
+lib/
+lib64/
+parts/
+sdist/
+var/
+wheels/
+share/python-wheels/
+*.egg-info/
+.installed.cfg
+*.egg
+MANIFEST
+
+# Virtual environments
+.venv/
+venv/
+ENV/
+env/
+
+# IDE
+.vscode/
+.idea/
+*.swp
+*.swo
+
+# OS
+.DS_Store
+Thumbs.db
+
+# Logs
+app/logs/
+logs/
+*.log
+
+# Redis dumps
+dump.rdb
+
+# Temporary files
+.tmp/
+temp/
+tmp/
+
+# Coverage reports
+htmlcov/
+.tox/
+.coverage
+.coverage.*
+.cache
+.pytest_cache/

wappa/cli/examples/json_cache_example/README.md

@@ -0,0 +1,190 @@
+# Wappa JSON Cache Example
+
+This example demonstrates how to use Wappa's JSON cache backend with a complete WhatsApp bot implementation following SOLID architecture principles.
+
+## Overview
+
+The JSON Cache Example shows how to build a WhatsApp bot that uses JSON file-based caching for:
+- **User Cache**: User profiles and session data (JSON files)
+- **Table Cache**: Message history and structured data (JSON files) 
+- **State Cache**: Application state management (JSON files)
+
+## Architecture
+
+This example follows **SOLID principles** with a modular score-based architecture:
+
+```
+app/
+├── main.py                 # FastAPI application with JSON cache
+├── master_event.py         # Main event handler using SOLID architecture
+├── models/                 # Pydantic data models
+│   └── json_demo_models.py # User, MessageLog, StateHandler, CacheStats
+├── scores/                 # Business logic modules (Single Responsibility)
+│   ├── score_base.py       # Abstract base for all scores
+│   ├── score_user_management.py      # User profile management
+│   ├── score_message_history.py      # Message logging & /HISTORY
+│   ├── score_state_commands.py       # /WAPPA, /EXIT commands
+│   └── score_cache_statistics.py     # /STATS command & monitoring
+└── utils/                  # Utility functions
+    ├── cache_utils.py      # Cache key generation & TTL management
+    └── message_utils.py    # Message parsing & formatting
+```
+
+## Features
+
+### Cache Operations
+- **JSON File Storage**: All data stored in JSON files on disk
+- **TTL Support**: Automatic expiration of cached data
+- **Persistence**: Data survives application restarts
+- **Performance**: Fast file-based operations with JSON serialization
+
+### Available Commands
+- `/WAPPA` - Enter special state mode (cached in state layer)
+- `/EXIT` - Exit special state mode  
+- `/HISTORY` - View your message history (from table cache)
+- `/STATS` - View JSON cache statistics and health
+
+### Score Modules (SOLID Architecture)
+Each score handles a single responsibility:
+
+1. **UserManagementScore**: User profiles, welcome messages
+2. **MessageHistoryScore**: Message logging, history retrieval  
+3. **StateCommandsScore**: State management, special commands
+4. **CacheStatisticsScore**: Cache monitoring, performance metrics
+
+## Configuration
+
+### Environment Variables
+```bash
+# WhatsApp Business API (required)
+WHATSAPP_API_URL=https://graph.facebook.com/v18.0
+WHATSAPP_ACCESS_TOKEN=your_access_token
+WHATSAPP_PHONE_NUMBER_ID=your_phone_number_id
+WHATSAPP_VERIFY_TOKEN=your_webhook_verify_token
+WHATSAPP_WEBHOOK_SECRET=your_webhook_secret
+
+# Application Settings
+PORT=8000
+LOG_LEVEL=INFO
+ENVIRONMENT=development
+```
+
+**Note**: No Redis configuration needed - JSON cache uses the file system!
+
+## Running the Example
+
+1. **Install Dependencies**:
+```bash
+cd json_cache_example
+uv sync
+```
+
+2. **Set Environment Variables**:
+```bash
+# Copy and edit .env file with your WhatsApp credentials
+cp .env.example .env
+```
+
+3. **Run the Application**:
+```bash
+uv run python -m app.main
+```
+
+4. **Test via WhatsApp**:
+   - Send any message to get welcomed
+   - Try `/WAPPA` to enter special state
+   - Send `/HISTORY` to view message history  
+   - Send `/STATS` to see JSON cache statistics
+   - Send `/EXIT` to leave special state
+
+## JSON Cache Behavior
+
+### File Structure
+```
+cache_data/
+├── user_cache/
+│   └── user_profile_{phone_number}.json
+├── table_cache/  
+│   └── msg_history_{phone_number}.json
+└── state_cache/
+    └── wappa_state_{phone_number}.json
+```
+
+### Cache Operations
+- **Set**: Creates/updates JSON files with serialized Pydantic models
+- **Get**: Reads and deserializes JSON files back to Pydantic models
+- **Delete**: Removes JSON files from disk
+- **TTL**: Files older than TTL are automatically cleaned up
+
+### Performance Characteristics
+- **Speed**: Fast for small to medium datasets
+- **Persistence**: Data survives restarts and crashes
+- **Scalability**: Good for moderate traffic (hundreds of users)
+- **Reliability**: No external dependencies, always available
+
+## Development
+
+### Adding New Score Modules
+1. Create new score in `app/scores/`
+2. Inherit from `ScoreBase` 
+3. Implement `can_handle()` and `process()` methods
+4. Register in `master_event.py`
+
+### Cache Usage Patterns
+```python
+# User cache example
+user = User(phone_number="1234567890", user_name="John")
+await self.user_cache.set("user_profile:1234567890", user, ttl=3600)
+cached_user = await self.user_cache.get("user_profile:1234567890", models=User)
+
+# Table cache example  
+message_log = MessageLog(user_id="1234567890")
+await self.table_cache.set("msg_history:1234567890", message_log)
+
+# State cache example
+state = StateHandler()
+state.activate_wappa()
+await self.state_cache.set("wappa_state:1234567890", state, ttl=1800)
+```
+
+## Monitoring
+
+### Cache Statistics
+Use `/STATS` command to monitor:
+- File system connectivity
+- Total operations count
+- Cache hit/miss ratios
+- Error rates and health status
+
+### Logging
+Comprehensive logging with structured output:
+- User operations (cache hits/misses)
+- Message processing (success/failure)  
+- Command handling (state changes)
+- Cache statistics (performance metrics)
+
+## Comparison with Redis
+
+| Feature | JSON Cache | Redis Cache |
+|---------|------------|-------------|
+| **Setup** | No dependencies | Requires Redis server |
+| **Persistence** | Always persistent | Configurable |  
+| **Performance** | Good (file I/O) | Excellent (memory) |
+| **Scalability** | Moderate | High |
+| **Reliability** | High (no external deps) | High (with proper setup) |
+| **Development** | Simple | Requires Redis knowledge |
+
+## Use Cases
+
+**JSON Cache is ideal for**:
+- Development and testing environments
+- Small to medium WhatsApp bots (< 1000 active users)
+- Applications requiring guaranteed persistence
+- Deployments without external dependencies
+- Scenarios where setup simplicity is important
+
+**Consider Redis for**:
+- High-traffic applications (> 1000 concurrent users)
+- Applications requiring sub-millisecond cache responses
+- Distributed deployments
+- Advanced Redis features (pub/sub, streams, etc.)

wappa/cli/examples/openai_transcript/.gitignore

@@ -0,0 +1,10 @@
+# Python-generated files
+__pycache__/
+*.py[oc]
+build/
+dist/
+wheels/
+*.egg-info
+
+# Virtual environments
+.venv

wappa/cli/examples/redis_cache_example/.gitignore

@@ -0,0 +1,69 @@
+# Wappa
+logs/
+
+# Environment variables
+.env
+.env.local
+.env.development
+.env.production
+
+# Python
+__pycache__/
+*.py[cod]
+*$py.class
+*.so
+.Python
+build/
+develop-eggs/
+dist/
+downloads/
+eggs/
+.eggs/
+lib/
+lib64/
+parts/
+sdist/
+var/
+wheels/
+share/python-wheels/
+*.egg-info/
+.installed.cfg
+*.egg
+MANIFEST
+
+# Virtual environments
+.venv/
+venv/
+ENV/
+env/
+
+# IDE
+.vscode/
+.idea/
+*.swp
+*.swo
+
+# OS
+.DS_Store
+Thumbs.db
+
+# Logs
+app/logs/
+logs/
+*.log
+
+# Redis dumps
+dump.rdb
+
+# Temporary files
+.tmp/
+temp/
+tmp/
+
+# Coverage reports
+htmlcov/
+.tox/
+.coverage
+.coverage.*
+.cache
+.pytest_cache/

wappa/cli/examples/simple_echo_example/.gitignore

@@ -0,0 +1,69 @@
+# Wappa
+logs/
+
+# Environment variables
+.env
+.env.local
+.env.development
+.env.production
+
+# Python
+__pycache__/
+*.py[cod]
+*$py.class
+*.so
+.Python
+build/
+develop-eggs/
+dist/
+downloads/
+eggs/
+.eggs/
+lib/
+lib64/
+parts/
+sdist/
+var/
+wheels/
+share/python-wheels/
+*.egg-info/
+.installed.cfg
+*.egg
+MANIFEST
+
+# Virtual environments
+.venv/
+venv/
+ENV/
+env/
+
+# IDE
+.vscode/
+.idea/
+*.swp
+*.swo
+
+# OS
+.DS_Store
+Thumbs.db
+
+# Logs
+app/logs/
+logs/
+*.log
+
+# Redis dumps
+dump.rdb
+
+# Temporary files
+.tmp/
+temp/
+tmp/
+
+# Coverage reports
+htmlcov/
+.tox/
+.coverage
+.coverage.*
+.cache
+.pytest_cache/

wappa/cli/examples/simple_echo_example/.python-version

@@ -0,0 +1 @@
+3.12

wappa/cli/examples/simple_echo_example/pyproject.toml

@@ -0,0 +1,9 @@
+[project]
+name = "simple-echo-example"
+version = "0.1.0"
+description = "Simple WhatsApp echo bot example using Wappa framework"
+readme = "README.md"
+requires-python = ">=3.12"
+dependencies = [
+    "wappa>=0.1.6",
+]