flow_chat 0.4.0 → 0.4.2

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: e4bd1ce536b9d214041fdd2926426449969918262f04829aca7f7e7251b8b4b6
-  data.tar.gz: 989238eac1d423e28d4139d2267200cea86e666992b400e8d2299b0ddc1ed8bf
+  metadata.gz: 004e0d3a8a9c9da83dfd6386b6e7684b7fea2b69daab7645e28d9a4767e80819
+  data.tar.gz: 85cf51f944ebb00aa7498106f88d60bfbdf060dcfe62762e3ab5a83784cff9f7
 SHA512:
-  metadata.gz: a26004d9e08aa4244f24f8ea57e6529699f827ca6d009042db0028bba611cbc5077ad39a11d654c9f4e6b3125881ff72893695f00c3d197a786770e484b209ac
-  data.tar.gz: e22bbf5a0ec53174e44b4eb1d5d453a6d9f3e5b2dd8107d1d14039fc315235aa28c3bbfb7877f882795fd3e978ddedf8deddd836a99d1c551f311c6410e55ea8
+  metadata.gz: c5a716d3345118c334899299367e1b7ef082e54651d75d7d92a24f01f03ea36a1e55df916aa14b6ddd0e75b353a0a37be08b0ce2681082df4f0d9768dc10a525
+  data.tar.gz: d533c33058573554f5c340460999c6d3b08332800ef33b521a0111ca44e8b4d10d4aa559e5d4f23f6575cffc86e8fa10d0e0850cefec5e18f075397ccb3d449d

data/Gemfile

@@ -7,3 +7,4 @@ gem "rake", "~> 12.0"
 gem "minitest", "~> 5.0"
 gem "minitest-reporters", "~> 1.4"
 gem "ostruct"
+gem "webmock", "~> 3.18"

data/README.md

@@ -8,8 +8,9 @@ FlowChat is a Rails framework designed for building sophisticated conversational
 - ✅ **Input Validation & Transformation** - Built-in validation and data conversion
 - 🌊 **Middleware Architecture** - Flexible request processing pipeline
 - 📱 **USSD Gateway Support** - Currently supports Nalo gateways
-- 💬 **WhatsApp Integration** - Full WhatsApp Cloud API support with interactive messages
-- 🧪 **Built-in Testing Tools** - USSD simulator for local development
+- 💬 **WhatsApp Integration** - Full WhatsApp Cloud API support with multiple processing modes
+- 🔧 **Reusable WhatsApp Client** - Standalone client for out-of-band messaging
+- 🧪 **Built-in Testing Tools** - Unified simulator for both USSD and WhatsApp testing
 
 ## Architecture Overview
 
@@ -154,17 +155,54 @@ custom_config.business_account_id = "your_specific_business_account_id"
 
 # Use in processor
 processor = FlowChat::Whatsapp::Processor.new(self) do |config|
-  config.use_whatsapp_config(custom_config)  # Pass custom config
-  config.use_gateway FlowChat::Whatsapp::Gateway::CloudApi
+  config.use_gateway FlowChat::Whatsapp::Gateway::CloudApi, custom_config
   config.use_session_store FlowChat::Session::CacheSessionStore
 end
 ```
 
 💡 **Tip**: See [examples/multi_tenant_whatsapp_controller.rb](examples/multi_tenant_whatsapp_controller.rb) for comprehensive multi-tenant and per-setup configuration examples.
 
-### 2. Create WhatsApp Controller
+### 2. Choose Message Handling Mode
 
+FlowChat offers three WhatsApp message handling modes. Configure them in an initializer:
+
+**Create an initializer** `config/initializers/flowchat.rb`:
+
+```ruby
+# config/initializers/flowchat.rb
+
+# Configure WhatsApp message handling mode
+FlowChat::Config.whatsapp.message_handling_mode = :inline  # or :background, :simulator
+FlowChat::Config.whatsapp.background_job_class = 'WhatsappMessageJob'
+```
+
+**Inline Mode (Default)** - Process messages synchronously:
 ```ruby
+# config/initializers/flowchat.rb
+FlowChat::Config.whatsapp.message_handling_mode = :inline
+
+# app/controllers/whatsapp_controller.rb
+class WhatsappController < ApplicationController
+  skip_forgery_protection
+
+  def webhook
+    processor = FlowChat::Whatsapp::Processor.new(self) do |config|
+      config.use_gateway FlowChat::Whatsapp::Gateway::CloudApi
+      config.use_session_store FlowChat::Session::CacheSessionStore
+    end
+
+    processor.run WelcomeFlow, :main_page
+  end
+end
+```
+
+**Background Mode** - Process flows synchronously, send responses asynchronously:
+```ruby
+# config/initializers/flowchat.rb
+FlowChat::Config.whatsapp.message_handling_mode = :background
+FlowChat::Config.whatsapp.background_job_class = 'WhatsappMessageJob'
+
+# app/controllers/whatsapp_controller.rb
 class WhatsappController < ApplicationController
   skip_forgery_protection
 
@@ -179,6 +217,28 @@ class WhatsappController < ApplicationController
 end
 ```
 
+**Simulator Mode** - Return response data instead of sending via WhatsApp API:
+```ruby
+# config/initializers/flowchat.rb
+FlowChat::Config.whatsapp.message_handling_mode = :simulator
+
+# app/controllers/whatsapp_controller.rb
+class WhatsappController < ApplicationController
+  skip_forgery_protection
+
+  def webhook
+    processor = FlowChat::Whatsapp::Processor.new(self) do |config|
+      config.use_gateway FlowChat::Whatsapp::Gateway::CloudApi
+      config.use_session_store FlowChat::Session::CacheSessionStore
+    end
+
+    processor.run WelcomeFlow, :main_page
+  end
+end
+```
+
+💡 **See [examples/README_whatsapp_modes.md](examples/README_whatsapp_modes.md) for detailed mode explanations and use cases.**
+
 ### 3. Add WhatsApp Route
 
 ```ruby
@@ -299,6 +359,86 @@ end
 
 For detailed WhatsApp setup instructions, see [WhatsApp Integration Guide](docs/whatsapp_setup.md).
 
+## 🔧 Reusable WhatsApp Client
+
+FlowChat provides a standalone WhatsApp client for out-of-band messaging:
+
+```ruby
+# Initialize client
+config = FlowChat::Whatsapp::Configuration.from_credentials
+client = FlowChat::Whatsapp::Client.new(config)
+
+# Send text message
+client.send_text("+1234567890", "Hello, World!")
+
+# Send interactive buttons
+client.send_buttons(
+  "+1234567890",
+  "Choose an option:",
+  [
+    { id: 'option1', title: 'Option 1' },
+    { id: 'option2', title: 'Option 2' }
+  ]
+)
+
+# Send interactive list
+client.send_list(
+  "+1234567890",
+  "Select from menu:",
+  [
+    {
+      title: "Services",
+      rows: [
+        { id: 'service1', title: 'Service 1', description: 'Description 1' },
+        { id: 'service2', title: 'Service 2', description: 'Description 2' }
+      ]
+    }
+  ]
+)
+
+# Handle media
+media_url = client.get_media_url("media_id_123")
+media_content = client.download_media("media_id_123")
+```
+
+### Out-of-Band Messaging Service Example
+
+```ruby
+class NotificationService
+  def initialize
+    @config = FlowChat::Whatsapp::Configuration.from_credentials
+    @client = FlowChat::Whatsapp::Client.new(@config)
+  end
+
+  def send_order_confirmation(phone_number, order_id, items, total)
+    item_list = items.map { |item| "• #{item[:name]} x#{item[:quantity]}" }.join("\n")
+    
+    @client.send_buttons(
+      phone_number,
+      "✅ Order Confirmed!\n\nOrder ##{order_id}\n\n#{item_list}\n\nTotal: $#{total}",
+      [
+        { id: 'track_order', title: '📦 Track Order' },
+        { id: 'contact_support', title: '💬 Contact Support' }
+      ]
+    )
+  end
+
+  def send_appointment_reminder(phone_number, appointment)
+    @client.send_buttons(
+      phone_number,
+      "🏥 Appointment Reminder\n\n#{appointment[:service]} with #{appointment[:provider]}\n📅 #{appointment[:date]}\n🕐 #{appointment[:time]}",
+      [
+        { id: 'confirm', title: '✅ Confirm' },
+        { id: 'reschedule', title: '📅 Reschedule' },
+        { id: 'cancel', title: '❌ Cancel' }
+      ]
+    )
+  end
+end
+```
+
+💡 **See [examples/whatsapp_controller_modes.rb](examples/whatsapp_controller_modes.rb) for comprehensive usage examples.**
+
 ## Cross-Platform Compatibility
 
 FlowChat provides a unified API that works across both USSD and WhatsApp platforms, with graceful degradation for platform-specific features:
@@ -321,6 +461,135 @@ FlowChat provides a unified API that works across both USSD and WhatsApp platfor
 
 This design allows you to write flows once and deploy them on both platforms, with WhatsApp users getting enhanced interactive features automatically.
 
+## 📱 Media Support
+
+FlowChat supports rich media attachments for enhanced conversational experiences. Media can be attached to `ask()` and `say()` prompts, with automatic cross-platform optimization.
+
+### Supported Media Types
+
+- **📷 Images** (`type: :image`) - Photos, screenshots, diagrams
+- **📄 Documents** (`type: :document`) - PDFs, forms, receipts  
+- **🎥 Videos** (`type: :video`) - Tutorials, demos, explanations
+- **🎵 Audio** (`type: :audio`) - Voice messages, recordings
+- **😊 Stickers** (`type: :sticker`) - Fun visual elements
+
+### Basic Usage
+
+```ruby
+class ProductFlow < FlowChat::Flow
+  def main_page
+    # ✅ Text input with context image
+    feedback = app.screen(:feedback) do |prompt|
+      prompt.ask "What do you think of our new product?",
+        media: {
+          type: :image,
+          url: "https://cdn.example.com/products/new_product.jpg"
+        }
+    end
+
+    # ✅ Send informational media
+    app.say "Thanks for your feedback! Here's what's coming next:",
+      media: {
+        type: :video,
+        url: "https://videos.example.com/roadmap.mp4"
+      }
+
+    # ✅ Document with filename
+    app.say "Here's your receipt:",
+      media: {
+        type: :document,
+        url: "https://api.example.com/receipt.pdf",
+        filename: "receipt.pdf"
+      }
+  end
+end
+```
+
+### Media Hash Format
+
+```ruby
+{
+  type: :image,        # Required: :image, :document, :audio, :video, :sticker
+  url: "https://...",  # Required: URL to the media file OR WhatsApp media ID
+  filename: "doc.pdf"  # Optional: Only for documents
+}
+```
+
+### Using WhatsApp Media IDs
+
+For better performance and to avoid external dependencies, you can upload files to WhatsApp and use the media ID:
+
+```ruby
+# Upload a file first
+client = FlowChat::Whatsapp::Client.new(config)
+media_id = client.upload_media('path/to/image.jpg', 'image/jpeg')
+
+# Then use the media ID in your flow
+app.screen(:product_demo) do |prompt|
+  prompt.ask "What do you think?",
+    media: {
+      type: :image,
+      url: media_id  # Use the media ID instead of URL
+    }
+end
+```
+
+### Client Media Methods
+
+The WhatsApp client provides methods for uploading and sending media:
+
+```ruby
+client = FlowChat::Whatsapp::Client.new(config)
+
+# Upload media and get media ID
+media_id = client.upload_media('image.jpg', 'image/jpeg')
+media_id = client.upload_media(file_io, 'image/jpeg', 'photo.jpg')
+
+# Send media directly
+client.send_image("+1234567890", "https://example.com/image.jpg", "Caption")
+client.send_image("+1234567890", media_id, "Caption")
+
+# Send document with MIME type and filename
+client.send_document("+1234567890", "https://example.com/doc.pdf", "Your receipt", "receipt.pdf", "application/pdf")
+
+# Send other media types
+client.send_video("+1234567890", "https://example.com/video.mp4", "Demo video", "video/mp4")
+client.send_audio("+1234567890", "https://example.com/audio.mp3", "audio/mpeg")
+client.send_sticker("+1234567890", "https://example.com/sticker.webp", "image/webp")
+```
+
+### Cross-Platform Behavior
+
+**WhatsApp Experience:**
+- Media is sent directly to the chat
+- Prompt text becomes the media caption
+- Rich, native messaging experience
+
+**USSD Experience:**  
+- Media URL is included in text message
+- Graceful degradation with clear media indicators
+- Users can access media via the provided link
+
+```ruby
+# This code works on both platforms:
+app.screen(:help) do |prompt|
+  prompt.ask "Describe your issue:",
+    media: {
+      type: :image,
+      url: "https://support.example.com/help_example.jpg"
+    }
+end
+```
+
+**WhatsApp Result:** Image sent with caption "Describe your issue:"
+
+**USSD Result:** 
+```
+Describe your issue:
+
+📷 Image: https://support.example.com/help_example.jpg
+```
+
 ## Core Concepts
 
 ### Flows and Screens
@@ -460,6 +729,68 @@ app.screen(:credit_card) do |prompt|
 end
 ```
 
+### Background Job Support
+
+For high-volume WhatsApp applications, use background response delivery:
+
+```ruby
+# app/jobs/whatsapp_message_job.rb
+class WhatsappMessageJob < ApplicationJob
+  include FlowChat::Whatsapp::SendJobSupport
+
+  def perform(send_data)
+    perform_whatsapp_send(send_data)
+  end
+end
+
+# config/initializers/flowchat.rb
+FlowChat::Config.whatsapp.message_handling_mode = :background
+FlowChat::Config.whatsapp.background_job_class = 'WhatsappMessageJob'
+
+# config/application.rb
+config.active_job.queue_adapter = :sidekiq
+```
+
+**The `SendJobSupport` module provides:**
+- ✅ **Automatic config resolution** - Resolves named configurations automatically
+- ✅ **Response delivery** - Handles sending responses to WhatsApp
+- ✅ **Error handling** - Comprehensive error handling with user notifications
+- ✅ **Retry logic** - Built-in exponential backoff retry
+- ✅ **Extensible** - Override methods for custom behavior
+
+**How it works:**
+1. **Controller receives webhook** - WhatsApp message arrives
+2. **Flow processes synchronously** - Maintains controller context and session state
+3. **Response queued for delivery** - Only the sending is moved to background
+4. **Job sends response** - Background job handles API call to WhatsApp
+
+**Advanced job with custom callbacks:**
+
+```ruby
+class AdvancedWhatsappMessageJob < ApplicationJob
+  include FlowChat::Whatsapp::SendJobSupport
+
+  def perform(send_data)
+    perform_whatsapp_send(send_data)
+  end
+
+  private
+
+  # Override for custom success handling
+  def on_whatsapp_send_success(send_data, result)
+    Rails.logger.info "Successfully sent WhatsApp message to #{send_data[:msisdn]}"
+    UserEngagementTracker.track_message_sent(phone: send_data[:msisdn])
+  end
+
+  # Override for custom error handling
+  def on_whatsapp_send_error(error, send_data)
+    ErrorTracker.notify(error, user_phone: send_data[:msisdn])
+  end
+end
+```
+
+💡 **See [examples/whatsapp_message_job.rb](examples/whatsapp_message_job.rb) for complete job implementation examples.**
+
 ### Middleware Configuration
 
 FlowChat uses a **middleware architecture** to process USSD requests through a configurable pipeline. Each request flows through multiple middleware layers in a specific order.
@@ -694,27 +1025,79 @@ class ProcessorMiddlewareTest < Minitest::Test
 end
 ```
 
-### USSD Simulator
+### FlowChat Unified Simulator
 
-Use the built-in simulator for interactive testing:
+Use the built-in unified simulator for interactive testing of both USSD and WhatsApp flows:
 
 ```ruby
-class UssdSimulatorController < ApplicationController
-  include FlowChat::Ussd::Simulator::Controller
+class SimulatorController < ApplicationController
+  include FlowChat::Simulator::Controller
+
+  def index
+    flowchat_simulator
+  end
 
   protected
 
-  def default_endpoint
-    '/ussd'
+  def configurations
+    {
+      production_ussd: {
+        name: "Production USSD",
+        icon: "🏭",
+        processor_type: "ussd",
+        provider: "nalo", 
+        endpoint: "/ussd",
+        color: "#28a745"
+      },
+      staging_whatsapp: {
+        name: "Staging WhatsApp", 
+        icon: "🧪",
+        processor_type: "whatsapp",
+        provider: "cloud_api",
+        endpoint: "/whatsapp/webhook",
+        color: "#17a2b8"
+      },
+      local_ussd: {
+        name: "Local USSD",
+        icon: "💻", 
+        processor_type: "ussd",
+        provider: "nalo",
+        endpoint: "http://localhost:3000/ussd",
+        color: "#6f42c1"
+      }
+    }
+  end
+
+  def default_config_key
+    :local_ussd
   end
 
-  def default_provider
-    :nalo
+  def default_phone_number
+    "+254712345678"
+  end
+
+  def default_contact_name
+    "John Doe"
   end
 end
 ```
 
-Add to routes and visit `http://localhost:3000/ussd_simulator`.
+Add to routes and visit `http://localhost:3000/simulator`.
+
+**Key Features:**
+- 🔄 **Platform Toggle** - Switch between USSD and WhatsApp modes with configuration selection
+- 📱 **USSD Mode** - Classic green-screen terminal simulation with provider support (Nalo, Nsano)
+- 💬 **WhatsApp Mode** - Full WhatsApp interface with interactive buttons, lists, and rich messaging
+- ⚙️ **Multi-Environment** - Support for different configurations (local, staging, production)
+- 🎨 **Modern UI** - Beautiful, responsive interface with real-time status indicators
+- 📊 **Request Logging** - View all HTTP requests and responses in real-time
+- 🔧 **Developer Tools** - Character counts, connection status, and comprehensive error handling
+
+The simulator automatically adapts its interface based on the selected configuration:
+- **USSD**: Shows traditional terminal-style interface with character limits and pagination
+- **WhatsApp**: Displays realistic WhatsApp chat interface with support for interactive elements
+
+💡 **Tip**: See [examples/simulator_controller.rb](examples/simulator_controller.rb) for advanced configurations including multi-tenant support and environment-specific endpoints.
 
 ## Best Practices
 
@@ -783,97 +1166,20 @@ def main_page
 end
 ```
 
-## Configuration
-
-### Cache Configuration
+### 5. Choose the Right WhatsApp Mode
 
-The `CacheSessionStore` requires a cache to be configured. Set it up in your Rails application:
+Configure the appropriate mode in your initializer:
 
 ```ruby
-# config/application.rb or config/environments/*.rb
-FlowChat::Config.cache = Rails.cache
-
-# Or use a specific cache store
-FlowChat::Config.cache = ActiveSupport::Cache::MemoryStore.new
-
-# For Redis (requires redis gem)
-FlowChat::Config.cache = ActiveSupport::Cache::RedisCacheStore.new(url: "redis://localhost:6379/1")
-```
-
-💡 **Tip**: See [examples/initializer.rb](examples/initializer.rb) for a complete configuration example.
-
-### Session Storage Options
-
-Configure different session storage backends:
-
-```ruby
-# Cache session store (default) - uses FlowChat::Config.cache
-config.use_session_store FlowChat::Session::CacheSessionStore
-
-# Rails session (for USSD)
-config.use_session_store FlowChat::Session::RailsSessionStore
-
-# Custom session store
-class MySessionStore
-  def initialize(context)
-    @context = context
-  end
-
-  def get(key)
-    # Your storage logic
-  end
-
-  def set(key, value)
-    # Your storage logic
-  end
-end
-
-config.use_session_store MySessionStore
-```
-
-## Development
-
-### Running Tests
-
-FlowChat uses Minitest for testing:
-
-```bash
-# Run all tests
-bundle exec rake test
-
-# Run specific test file
-bundle exec rake test TEST=test/unit/flow_test.rb
-
-# Run specific test
-bundle exec rake test TESTOPTS="--name=test_flow_initialization"
-```
-
-### Contributing
-
-1. Fork the repository
-2. Create your feature branch (`git checkout -b feature/amazing-feature`)
-3. Add tests for your changes
-4. Ensure all tests pass (`bundle exec rake test`)
-5. Commit your changes (`git commit -am 'Add amazing feature'`)
-6. Push to the branch (`git push origin feature/amazing-feature`)
-7. Open a Pull Request
-
-## Roadmap
-
-- 💬 **Telegram Bot Support** - Native Telegram bot integration  
-- 🔄 **Sub-flows** - Reusable conversation components and flow composition
-- 📊 **Analytics Integration** - Built-in conversation analytics and user journey tracking
-- 🌐 **Multi-language Support** - Internationalization and localization features
-- ⚡ **Performance Optimizations** - Improved middleware performance and caching
-- 🎯 **Advanced Validation** - More validation helpers and custom validators
-- 🔐 **Enhanced Security** - Rate limiting, input sanitization, and fraud detection
-
-## License
+# config/initializers/flowchat.rb
 
-FlowChat is available as open source under the terms of the [MIT License](https://opensource.org/licenses/MIT).
+# Development/Testing - use simulator mode
+FlowChat::Config.whatsapp.message_handling_mode = :simulator
 
-## Support
+# Low-volume Applications - use inline mode  
+FlowChat::Config.whatsapp.message_handling_mode = :inline
 
-- 📖 **Documentation**: [GitHub Repository](https://github.com/radioactive-labs/flow_chat)
-- 🐛 **Bug Reports**: [GitHub Issues](https://github.com/radioactive-labs/flow_chat/issues)
-- 💬 **Community**: Join our discussions for help and feature requests
+# High-volume Production - use background mode (sync processing + async sending)
+FlowChat::Config.whatsapp.message_handling_mode = :background
+FlowChat::Config.whatsapp.background_job_class = 'WhatsappMessageJob'
+```

data/examples/initializer.rb

@@ -28,4 +28,4 @@ FlowChat::Config.ussd.pagination_next_text = "More"
 
 # Configure resumable sessions (optional)
 FlowChat::Config.ussd.resumable_sessions_enabled = true
-FlowChat::Config.ussd.resumable_sessions_timeout_seconds = 300 # 5 minutes 
+FlowChat::Config.ussd.resumable_sessions_timeout_seconds = 300 # 5 minutes

data/examples/media_prompts_examples.rb

@@ -0,0 +1,27 @@
+# Media Prompts Examples
+# This file demonstrates how to attach media to prompts in FlowChat
+
+# ============================================================================
+# BASIC MEDIA PROMPTS
+# ============================================================================
+
+class MediaPromptFlow < FlowChat::Flow
+  def main_page
+    # ✅ Simple text input with attached image
+    # The prompt text becomes the image caption
+    app.screen(:feedback) do |prompt|
+      prompt.ask "What do you think of our new product?",
+        media: {
+          type: :image,
+          url: "https://cdn.example.com/products/new_product.jpg"
+        }
+    end
+
+    # ✅ Send media message with say
+    app.say "Thank you for your feedback! Here's what's coming next:",
+      media: {
+        type: :video,
+        url: "https://videos.example.com/roadmap.mp4"
+      }
+  end
+end