flow_chat 0.6.1 → 0.7.0

data/README.md

@@ -1,43 +1,33 @@
 # FlowChat
 
-FlowChat is a Rails framework designed for building sophisticated conversational workflows for both USSD (Unstructured Supplementary Service Data) systems and WhatsApp messaging. It provides an intuitive Ruby DSL for creating multi-step, menu-driven conversations with automatic session management, input validation, and flow control.
+[![CI](https://github.com/radioactive-labs/flow_chat/actions/workflows/ci.yml/badge.svg?branch=master)](https://github.com/radioactive-labs/flow_chat/actions/workflows/ci.yml)
+[![Gem Version](https://badge.fury.io/rb/flow_chat.svg)](https://badge.fury.io/rb/flow_chat)
+[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)
+[![Ruby](https://img.shields.io/badge/ruby-%3E%3D%202.3.0-red.svg)](https://www.ruby-lang.org/)
+[![Rails](https://img.shields.io/badge/rails-%3E%3D%206.0-red.svg)](https://rubyonrails.org/)
 
-**Key Features:**
-- 🎯 **Declarative Flow Definition** - Define conversation flows as Ruby classes
-- 🔄 **Automatic Session Management** - Persistent state across requests  
-- ✅ **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 multiple processing modes and webhook signature validation
-- 🔧 **Reusable WhatsApp Client** - Standalone client for out-of-band messaging
-- 🧪 **Built-in Testing Tools** - Unified simulator for both USSD and WhatsApp testing
-
-## Architecture Overview
-
-FlowChat uses a **request-per-interaction** model where each user input creates a new request. The framework maintains conversation state through session storage while processing each interaction through a middleware pipeline.
+FlowChat is a Rails framework for building sophisticated conversational workflows for USSD and WhatsApp messaging. Define multi-step conversations as Ruby classes with automatic session management, input validation, and cross-platform compatibility.
 
-```
-User Input → Gateway → Session → Pagination → Custom → Executor → Flow → Response
-                ↓
-         Session Storage
-```
+## Key Features
 
-**Middleware Pipeline:**
-- **Gateway**: Communication with providers (USSD: Nalo, WhatsApp: Cloud API)
-- **Session**: Load/save conversation state  
-- **Pagination**: Split long responses into pages (USSD only)
-- **Custom**: Your application middleware (logging, auth, etc.)
-- **Executor**: Execute flow methods and handle interrupts
+- 🎯 **Declarative Flow Definition** - Define conversations as Ruby classes
+- 🔄 **Automatic Session Management** - Persistent state across requests  
+- ✅ **Input Validation & Transformation** - Built-in validation and data conversion
+- 📱 **USSD & WhatsApp Support** - Single codebase, multiple platforms
+- 💬 **Rich WhatsApp Features** - Interactive buttons, lists, media support
+- 🔧 **Standalone WhatsApp Client** - Send messages outside of flows
+- 📊 **Built-in Instrumentation** - Monitoring and metrics out of the box
+- 🧪 **Testing Tools** - Built-in simulator for development and testing
 
 ## Installation
 
-Add FlowChat to your Rails application's Gemfile:
+Add to your Gemfile:
 
 ```ruby
 gem 'flow_chat'
 ```
 
-Then execute:
+Then run:
 
 ```bash
 bundle install
@@ -45,30 +35,28 @@ bundle install
 
 ## Quick Start
 
-FlowChat supports both USSD and WhatsApp. Choose the platform that fits your needs:
+### USSD Example
 
-### USSD Setup
-
-### 1. Create Your First Flow
-
-Create a flow class in `app/flow_chat/welcome_flow.rb`:
+Create a flow in `app/flow_chat/welcome_flow.rb`:
 
 ```ruby
 class WelcomeFlow < FlowChat::Flow
   def main_page
     name = app.screen(:name) do |prompt|
-      prompt.ask "Welcome! What's your name?",
+      prompt.ask "What's your name?",
         transform: ->(input) { input.strip.titleize }
     end
 
-    app.say "Hello, #{name}! Welcome to FlowChat."
+    language = app.screen(:language) do |prompt|
+      prompt.select "Choose language:", ["English", "French", "Spanish"]
+    end
+
+    app.say "Hello #{name}! Language set to #{language}."
   end
 end
 ```
 
-### 2. Set Up the USSD Controller
-
-Create a controller to handle USSD requests:
+Create a controller:
 
 ```ruby
 class UssdController < ApplicationController
@@ -85,193 +73,27 @@ class UssdController < ApplicationController
 end
 ```
 
-### 3. Configure Routes
-
-Add the route to `config/routes.rb`:
+Add route in `config/routes.rb`:
 
 ```ruby
-Rails.application.routes.draw do
   post 'ussd' => 'ussd#process_request'
-end
 ```
 
-💡 **Tip**: See [examples/ussd_controller.rb](examples/ussd_controller.rb) for a complete USSD controller example with payment flows, customer support, and custom middleware.
+### WhatsApp Example
 
-### WhatsApp Setup
-
-### 1. Configure WhatsApp Credentials
-
-FlowChat supports two ways to configure WhatsApp credentials:
-
-**Option A: Using Rails Credentials**
-
-Add your WhatsApp credentials to Rails credentials:
-
-```bash
-rails credentials:edit
-```
+Configure credentials in `config/credentials.yml.enc`:
 
 ```yaml
 whatsapp:
   access_token: "your_access_token"
   phone_number_id: "your_phone_number_id"
   verify_token: "your_verify_token"
-  app_id: "your_app_id"
   app_secret: "your_app_secret"
-  business_account_id: "your_business_account_id"
-  skip_signature_validation: false  # Set to true only for development/testing
 ```
 
-**Option B: Using Environment Variables**
-
-Alternatively, you can use environment variables:
-
-```bash
-# Add to your .env file or environment
-export WHATSAPP_ACCESS_TOKEN="your_access_token"
-export WHATSAPP_PHONE_NUMBER_ID="your_phone_number_id" 
-export WHATSAPP_VERIFY_TOKEN="your_verify_token"
-export WHATSAPP_APP_ID="your_app_id"
-export WHATSAPP_APP_SECRET="your_app_secret"
-export WHATSAPP_BUSINESS_ACCOUNT_ID="your_business_account_id"
-export WHATSAPP_SKIP_SIGNATURE_VALIDATION="false"  # Set to "true" only for development/testing
-```
-
-FlowChat will automatically use Rails credentials first, falling back to environment variables if credentials are not available.
-
-**Option C: Per-Setup Configuration**
-
-For multi-tenant applications or when you need different WhatsApp accounts per endpoint:
+Create a controller:
 
 ```ruby
-# Create custom configuration
-custom_config = FlowChat::Whatsapp::Configuration.new
-custom_config.access_token = "your_specific_access_token"
-custom_config.phone_number_id = "your_specific_phone_number_id"
-custom_config.verify_token = "your_specific_verify_token"
-custom_config.app_id = "your_specific_app_id"
-custom_config.app_secret = "your_specific_app_secret"
-custom_config.business_account_id = "your_specific_business_account_id"
-custom_config.skip_signature_validation = false  # Security setting
-
-# Use in processor
-processor = FlowChat::Whatsapp::Processor.new(self) do |config|
-  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. Security Configuration
-
-FlowChat includes robust security features for WhatsApp webhook validation:
-
-**Webhook Signature Validation** (Recommended for Production)
-
-FlowChat automatically validates WhatsApp webhook signatures using your app secret:
-
-```ruby
-# config/initializers/flowchat.rb
-
-# Global security configuration
-FlowChat::Config.simulator_secret = "your_secure_random_secret_for_simulator"
-
-# WhatsApp security is configured per-configuration
-# The app_secret from your WhatsApp configuration is used for webhook validation
-```
-
-**Security Options:**
-
-```ruby
-# Option 1: Full security (recommended for production)
-custom_config.app_secret = "your_whatsapp_app_secret"  # Required for signature validation
-custom_config.skip_signature_validation = false       # Default: enforce validation
-
-# Option 2: Disable validation (development/testing only)
-custom_config.app_secret = nil                        # Not required when disabled
-custom_config.skip_signature_validation = true        # Explicitly disable validation
-```
-
-⚠️ **Security Warning**: Only disable signature validation in development/testing environments. Production environments should always validate webhook signatures using your WhatsApp app secret.
-
-**Simulator Authentication**
-
-The simulator mode requires authentication:
-
-```ruby
-# config/initializers/flowchat.rb
-FlowChat::Config.simulator_secret = Rails.application.secret_key_base + "_simulator"
-
-# Or use a dedicated secret
-FlowChat::Config.simulator_secret = "your_secure_random_secret_here"
-```
-
-The simulator uses HMAC-SHA256 signed cookies for authentication with 24-hour expiration.
-
-📚 **For comprehensive security documentation, see [SECURITY.md](SECURITY.md)**
-
-### 3. 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
-
-  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
-```
-
-**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
 
@@ -286,1068 +108,101 @@ class WhatsappController < ApplicationController
 end
 ```
 
-### 4. Add WhatsApp Route
+Add route:
 
 ```ruby
-Rails.application.routes.draw do
   match '/whatsapp/webhook', to: 'whatsapp#webhook', via: [:get, :post]
-end
-```
-
-### 5. Enhanced Simulator Setup
-
-FlowChat provides a powerful built-in simulator for testing flows in both USSD and WhatsApp modes. The simulator allows you to test different endpoints on your local server without needing actual USSD or WhatsApp infrastructure.
-
-**Setup Simulator Controller:**
-
-```ruby
-# app/controllers/simulator_controller.rb
-class SimulatorController < ApplicationController
-  include FlowChat::Simulator::Controller
-
-  def index
-    flowchat_simulator
-  end
-
-  protected
-
-  def configurations
-    {
-      ussd: {
-        name: "USSD Integration",
-        icon: "📱",
-        processor_type: "ussd",
-        provider: "nalo",
-        endpoint: "/ussd",
-        color: "#007bff"
-      },
-      whatsapp: {
-        name: "WhatsApp Integration", 
-        icon: "💬",
-        processor_type: "whatsapp",
-        provider: "cloud_api",
-        endpoint: "/whatsapp/webhook",
-        color: "#25D366"
-      },
-      alternative_whatsapp: {
-        name: "Alternative WhatsApp Endpoint",
-        icon: "🔄",
-        processor_type: "whatsapp", 
-        provider: "cloud_api",
-        endpoint: "/alternative_whatsapp/webhook",
-        color: "#17a2b8"
-      }
-    }
-  end
-
-  def default_config_key
-    :local_whatsapp
-  end
-
-  def default_phone_number
-    "+1234567890"
-  end
-
-  def default_contact_name
-    "John Doe"
-  end
-end
-```
-
-**Add Simulator Route:**
-
-```ruby
-# config/routes.rb
-Rails.application.routes.draw do
-  get '/simulator' => 'simulator#index'
-  # ... other routes
-end
-```
-
-**Configure Simulator Security:**
-
-```ruby
-# config/initializers/flowchat.rb
-FlowChat::Config.simulator_secret = Rails.application.secret_key_base + "_simulator"
-```
-
-**Enable Simulator Mode in Controllers:**
-
-For controllers that should support simulator mode, enable it in the processor:
-
-```ruby
-# app/controllers/whatsapp_controller.rb
-class WhatsappController < ApplicationController
-  skip_forgery_protection
-
-  def webhook
-    processor = FlowChat::Whatsapp::Processor.new(self, enable_simulator: Rails.env.local?) do |config|
-      config.use_gateway FlowChat::Whatsapp::Gateway::CloudApi
-      config.use_session_store FlowChat::Session::CacheSessionStore
-    end
-
-    processor.run WelcomeFlow, :main_page
-  end
-end
-```
-
-This is enabled by default in `Rails.env.local?` (development and testing) environments.
-
-**Simulator Features:**
-- 🔄 **Endpoint Toggle** - Switch between different integration endpoints
-- 📱 **USSD Mode** - Classic terminal simulation with pagination
-- 💬 **WhatsApp Mode** - Full WhatsApp interface with interactive elements
-- 🎨 **Modern UI** - Beautiful, responsive interface
-- 📊 **Request Logging** - View HTTP requests and responses in real-time
-- 🔧 **Developer Tools** - Character counts, connection status, error handling
-- 🔒 **Secure Authentication** - HMAC-signed cookies with expiration
-
-Visit `http://localhost:3000/simulator` to access the simulator interface and test your local endpoints.
-
-## 🔧 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
-```
-
-
-## Cross-Platform Compatibility
-
-FlowChat provides a unified API that works across both USSD and WhatsApp platforms, with graceful degradation for platform-specific features. Under the hood, FlowChat uses a unified prompt architecture that ensures consistent behavior across platforms while optimizing the user experience for each channel.
-
-### Shared Features (Both USSD & WhatsApp)
-- ✅ `app.screen()` - Interactive screens with prompts
-- ✅ `app.say()` - Send messages to users  
-- ✅ `prompt.ask()` - Text input collection
-- ✅ `prompt.select()` - Menu selection (renders as numbered list in USSD, interactive buttons/lists in WhatsApp)
-- ✅ `prompt.yes?()` - Yes/no questions
-- ✅ `app.phone_number` - User's phone number
-- ✅ `app.message_id` - Unique message identifier  
-- ✅ `app.timestamp` - Message timestamp
-
-### WhatsApp-Only Features
-- ✅ `app.contact_name` - WhatsApp contact name (returns `nil` in USSD)
-- ✅ `app.location` - Location sharing data (returns `nil` in USSD)  
-- ✅ `app.media` - Media file attachments (returns `nil` in USSD)
-- ✅ Rich interactive elements (buttons, lists) automatically generated from `prompt.select()`
-
-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
 
-**Flows** are Ruby classes that define conversation logic. **Screens** represent individual interaction points where you collect user input.
+**Flows** define conversation logic. **Screens** collect user input with automatic validation:
 
 ```ruby
 class RegistrationFlow < FlowChat::Flow
   def main_page
-    # Each screen captures one piece of user input
-    phone = app.screen(:phone) do |prompt|
-      prompt.ask "Enter your phone number:",
-        validate: ->(input) { "Invalid phone number" unless valid_phone?(input) }
-    end
-
-    age = app.screen(:age) do |prompt|
-      prompt.ask "Enter your age:",
-        convert: ->(input) { input.to_i },
-        validate: ->(input) { "Must be 18 or older" unless input >= 18 }
+email = app.screen(:email) do |prompt|
+      prompt.ask "Enter email:",
+        validate: ->(input) { "Invalid email" unless input.include?("@") },
+        transform: ->(input) { input.downcase.strip }
     end
 
-    # Process the collected data
-    create_user(phone: phone, age: age)
-    app.say "Registration complete!"
-  end
-
-  private
-
-  def valid_phone?(phone)
-    phone.match?(/\A\+?[\d\s\-\(\)]+\z/)
-  end
-
-  def create_user(phone:, age:)
-    # Your user creation logic here
-  end
-end
-```
-
-### Input Validation and Transformation
-
-FlowChat provides powerful input processing capabilities:
-
-```ruby
-app.screen(:email) do |prompt|
-  prompt.ask "Enter your email:",
-    # Transform input before validation
-    transform: ->(input) { input.strip.downcase },
-    
-    # Validate the input
-    validate: ->(input) { 
-      "Invalid email format" unless input.match?(/\A[\w+\-.]+@[a-z\d\-]+(\.[a-z\d\-]+)*\.[a-z]+\z/i)
-    },
-    
-    # Convert to final format
-    convert: ->(input) { input }
-end
-```
-
-### Menu Selection
-
-Create selection menus with automatic validation:
-
-```ruby
-# Array-based choices
-language = app.screen(:language) do |prompt|
-  prompt.select "Choose your language:", ["English", "French", "Spanish"]
-end
-
-# Hash-based choices (keys are returned values)
-plan = app.screen(:plan) do |prompt|
-  prompt.select "Choose a plan:", {
-    "basic" => "Basic Plan ($10/month)",
-    "premium" => "Premium Plan ($25/month)",
-    "enterprise" => "Enterprise Plan ($100/month)"
-  }
-end
-```
-
-### Yes/No Prompts
-
-Simplified boolean input collection:
-
-```ruby
-confirmed = app.screen(:confirmation) do |prompt|
-  prompt.yes? "Do you want to proceed with the payment?"
+confirmed = app.screen(:confirm) do |prompt|
+      prompt.yes? "Create account for #{email}?"
 end
 
 if confirmed
-  process_payment
-  app.say "Payment processed successfully!"
-else
-  app.say "Payment cancelled."
-end
-```
-
-## Advanced Features
-
-### Session Management and Flow State
-
-FlowChat automatically manages session state across requests. Each screen's result is cached, so users can navigate back and forth without losing data:
-
-```ruby
-class OrderFlow < FlowChat::Flow
-  def main_page
-    # These values persist across requests
-    product = app.screen(:product) { |p| p.select "Choose product:", products }
-    quantity = app.screen(:quantity) { |p| p.ask "Quantity:", convert: :to_i }
-    
-    # Show summary
-    total = calculate_total(product, quantity)
-    confirmed = app.screen(:confirm) do |prompt|
-      prompt.yes? "Order #{quantity}x #{product} for $#{total}. Confirm?"
-    end
-
-    if confirmed
-      process_order(product, quantity)
-      app.say "Order placed successfully!"
+      create_account(email)
+      app.say "Account created successfully!"
     else
-      app.say "Order cancelled."
-    end
-  end
-end
-```
-
-### Error Handling
-
-Handle validation errors gracefully:
-
-```ruby
-app.screen(:credit_card) do |prompt|
-  prompt.ask "Enter credit card number:",
-    validate: ->(input) {
-      return "Card number must be 16 digits" unless input.length == 16
-      return "Invalid card number" unless luhn_valid?(input)
-      nil # Return nil for valid input
-    }
-end
-```
-
-### Validation Error Display
-
-Configure how validation errors are displayed to users:
-
-```ruby
-# config/initializers/flowchat.rb
-
-# Default behavior: combine error with original message
-FlowChat::Config.combine_validation_error_with_message = true
-# User sees: "Card number must be 16 digits\n\nEnter credit card number:"
-
-# Show only the error message
-FlowChat::Config.combine_validation_error_with_message = false  
-# User sees: "Card number must be 16 digits"
-```
-
-**Use cases for each approach:**
-
-- **Combined (default)**: Better for first-time users who need context about what they're entering
-- **Error only**: Cleaner UX for experienced users, reduces message length for USSD character limits
-
-**Example with both approaches:**
-
-```ruby
-# This validation code works the same way regardless of config
-age = app.screen(:age) do |prompt|
-  prompt.ask "How old are you?",
-    convert: ->(input) { input.to_i },
-    validate: ->(input) { "You must be at least 18 years old" unless input >= 18 }
-end
-
-# With combine_validation_error_with_message = true (default):
-# "You must be at least 18 years old
-# 
-# How old are you?"
-
-# With combine_validation_error_with_message = false:
-# "You must be at least 18 years old"
-```
-
-### 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.
-
-#### Default Middleware Stack
-
-When you run a flow, FlowChat automatically builds this middleware stack:
-
-```
-User Input → Gateway → Session → Pagination → Custom Middleware → Executor → Flow
-```
-
-1. **Gateway Middleware** - Handles USSD provider communication (Nalo)
-2. **Session Middleware** - Manages session storage and retrieval
-3. **Pagination Middleware** - Automatically splits long responses across pages
-4. **Custom Middleware** - Your application-specific middleware (optional)
-5. **Executor Middleware** - Executes the actual flow logic
-
-#### Basic Configuration
-
-```ruby
-processor = FlowChat::Ussd::Processor.new(self) do |config|
-  # Gateway configuration (required)
-  config.use_gateway FlowChat::Ussd::Gateway::Nalo
-  
-  # Session storage (required)
-  config.use_session_store FlowChat::Session::CacheSessionStore
-  
-  # Add custom middleware (optional)
-  config.use_middleware MyLoggingMiddleware
-  
-  # Enable resumable sessions (optional)
-  config.use_resumable_sessions
-end
-```
-
-#### Runtime Middleware Modification
-
-You can modify the middleware stack at runtime for advanced use cases:
-
-```ruby
-processor.run(MyFlow, :main_page) do |stack|
-  # Add authentication middleware
-  stack.use AuthenticationMiddleware
-  
-  # Insert rate limiting before execution
-  stack.insert_before FlowChat::Ussd::Middleware::Executor, RateLimitMiddleware
-  
-  # Add logging after gateway
-  stack.insert_after gateway, RequestLoggingMiddleware
-end
-```
-
-#### Built-in Middleware
-
-**Pagination Middleware** automatically handles responses longer than 182 characters (configurable):
-
-```ruby
-# Configure pagination behavior
-FlowChat::Config.ussd.pagination_page_size = 140        # Default: 140 characters
-FlowChat::Config.ussd.pagination_next_option = "#"      # Default: "#"
-FlowChat::Config.ussd.pagination_next_text = "More"     # Default: "More"
-FlowChat::Config.ussd.pagination_back_option = "0"      # Default: "0"
-FlowChat::Config.ussd.pagination_back_text = "Back"     # Default: "Back"
-```
-
-**Resumable Sessions** allow users to continue interrupted conversations:
-
-```ruby
-processor = FlowChat::Ussd::Processor.new(self) do |config|
-  config.use_gateway FlowChat::Ussd::Gateway::Nalo
-  config.use_session_store FlowChat::Session::CacheSessionStore
-  config.use_resumable_sessions  # Enable resumable sessions
-end
-```
-
-#### Creating Custom Middleware
-
-```ruby
-class LoggingMiddleware
-  def initialize(app)
-    @app = app
-  end
-
-  def call(context)
-    Rails.logger.info "Processing USSD request: #{context.input}"
-    
-    # Call the next middleware in the stack
-    result = @app.call(context)
-    
-    Rails.logger.info "Response: #{result[1]}"
-    result
-  end
-end
-
-# Use your custom middleware
-processor = FlowChat::Ussd::Processor.new(self) do |config|
-  config.use_gateway FlowChat::Ussd::Gateway::Nalo
-  config.use_session_store FlowChat::Session::CacheSessionStore
-  config.use_middleware LoggingMiddleware
-end
-```
-
-### Multiple Gateways
-
-FlowChat supports multiple USSD gateways:
-
-```ruby
-# Nalo Solutions Gateway
-config.use_gateway FlowChat::Ussd::Gateway::Nalo
-```
-
-## Testing
-
-FlowChat provides comprehensive testing capabilities for both USSD and WhatsApp flows. This section covers all testing approaches from simple unit tests to complex integration scenarios.
-
-### Testing Approaches Overview
-
-FlowChat supports two main testing strategies:
-
-**🎯 Option 1: Simulator Mode (Recommended)**
-- Bypasses WhatsApp API entirely
-- No webhook signature validation required  
-- Responses returned as JSON instead of sent to WhatsApp
-- Perfect for unit and integration testing
-- Works with built-in web simulator interface
-
-**🔒 Option 2: Skip Signature Validation**
-- Tests real webhook endpoints without security complexity
-- Useful for staging environments
-- Set `skip_signature_validation = true`
-
-### Environment-Specific Testing Configuration
-
-Configure testing behavior per environment:
-
-```ruby
-# config/initializers/flowchat.rb
-case Rails.env
-when 'development'
-  # Enable simulator mode for testing
-  FlowChat::Config.whatsapp.message_handling_mode = :simulator
-  FlowChat::Config.simulator_secret = Rails.application.secret_key_base + "_dev"
-  
-when 'test'
-  # Enable simulator mode for automated testing
-  FlowChat::Config.whatsapp.message_handling_mode = :simulator
-  FlowChat::Config.simulator_secret = "test_secret"
-  
-when 'staging'
-  # Use inline mode but allow simulator for testing
-  FlowChat::Config.whatsapp.message_handling_mode = :inline
-  FlowChat::Config.simulator_secret = ENV['FLOWCHAT_SIMULATOR_SECRET']
-  
-when 'production'
-  # Background processing in production, no simulator
-  FlowChat::Config.whatsapp.message_handling_mode = :background
-  FlowChat::Config.whatsapp.background_job_class = 'WhatsappMessageJob'
-  FlowChat::Config.simulator_secret = nil
-end
-```
-
-### Unit Testing Flows
-
-Test your flows in isolation using the provided test helpers:
-
-```ruby
-require 'test_helper'
-
-class WelcomeFlowTest < Minitest::Test
-  def setup
-    @context = FlowChat::Context.new
-    @context.session = create_test_session_store
-  end
-
-  def test_welcome_flow_with_name
-    @context.input = "John Doe"
-    app = FlowChat::Ussd::App.new(@context)
-    
-    error = assert_raises(FlowChat::Interrupt::Terminate) do
-      flow = WelcomeFlow.new(app)
-      flow.main_page
+      app.say "Registration cancelled."
     end
-    
-    assert_equal "Hello, John Doe! Welcome to FlowChat.", error.prompt
   end
 end
 ```
 
-### Integration Testing
-
-#### Simulator Mode Testing
-
-```ruby
-test "complete flow via simulator" do
-  # Generate valid simulator cookie for authentication
-  valid_cookie = generate_simulator_cookie
-  
-  webhook_payload = {
-    entry: [{ changes: [{ value: { messages: [{ from: "1234567890", text: { body: "Hello" }, type: "text" }] } }] }],
-    simulator_mode: true
-  }
-
-  post "/whatsapp/webhook", params: webhook_payload, cookies: { flowchat_simulator: valid_cookie }
-  assert_response :success
-end
-```
-
-#### Testing with Skipped Validation
-
-```ruby
-test "webhook processing with skipped validation" do
-  config = FlowChat::Whatsapp::Configuration.new
-  config.skip_signature_validation = true  # Skip for testing
-  
-  # No signature required when validation is skipped
-  post "/whatsapp/webhook", params: webhook_payload.to_json
-  assert_response :success
-end
-```
-
-### Test Helper Methods
-
-```ruby
-private
+### Input Methods
 
-def generate_webhook_signature(payload_json, secret = @app_secret)
-  OpenSSL::HMAC.hexdigest(OpenSSL::Digest.new("sha256"), secret, payload_json)
-end
-
-def generate_simulator_cookie(secret = FlowChat::Config.simulator_secret)
-  timestamp = Time.now.to_i
-  message = "simulator:#{timestamp}"
-  signature = OpenSSL::HMAC.hexdigest(OpenSSL::Digest.new("sha256"), secret, message)
-  "#{timestamp}:#{signature}"
-end
-```
+- **`prompt.ask()`** - Free-form input with optional validation
+- **`prompt.select()`** - Force selection from predefined options  
+- **`prompt.yes?()`** - Simple yes/no questions
 
-## Configuration Reference
+## WhatsApp Client
 
-### Framework Configuration
+Send messages outside of flows:
 
 ```ruby
-# config/initializers/flowchat.rb
-
-# Core configuration
-FlowChat::Config.logger = Rails.logger
-FlowChat::Config.cache = Rails.cache
-FlowChat::Config.simulator_secret = "your_secure_secret_here"
-
-# Validation error display behavior
-# When true (default), validation errors are combined with the original message.
-# When false, only the validation error message is shown to the user.
-FlowChat::Config.combine_validation_error_with_message = true
-
-# USSD configuration
-FlowChat::Config.ussd.pagination_page_size = 140
-FlowChat::Config.ussd.pagination_next_option = "#"
-FlowChat::Config.ussd.pagination_next_text = "More"
-FlowChat::Config.ussd.pagination_back_option = "0"
-FlowChat::Config.ussd.pagination_back_text = "Back"
-FlowChat::Config.ussd.resumable_sessions_enabled = true
-FlowChat::Config.ussd.resumable_sessions_timeout_seconds = 300
-
-# WhatsApp configuration
-FlowChat::Config.whatsapp.message_handling_mode = :inline  # :inline, :background, :simulator
-FlowChat::Config.whatsapp.background_job_class = 'WhatsappMessageJob'
-```
-
-### WhatsApp Security Configuration
-
-```ruby
-# Per-configuration security settings
-config = FlowChat::Whatsapp::Configuration.new
-config.app_secret = "your_whatsapp_app_secret"          # Required for signature validation
-config.skip_signature_validation = false                # Default: false (enforce validation)
-
-# Security modes:
-# 1. Full security (production)
-config.app_secret = "secret"
-config.skip_signature_validation = false
-
-# 2. Development mode (disable validation)
-config.app_secret = nil
-config.skip_signature_validation = true
-```
-
-## Best Practices
-
-### 1. Security Best Practices
-
-**Production Security Checklist:**
-
-✅ **Always configure app_secret** for webhook validation
-```ruby
-config.app_secret = "your_whatsapp_app_secret"  # Never leave empty in production
-config.skip_signature_validation = false        # Never disable in production
-```
-
-✅ **Use secure simulator secrets**
-```ruby
-# Use Rails secret_key_base + suffix for uniqueness
-FlowChat::Config.simulator_secret = Rails.application.secret_key_base + "_simulator"
-
-# Or use environment variables
-FlowChat::Config.simulator_secret = ENV['FLOWCHAT_SIMULATOR_SECRET']
-```
-
-✅ **Environment-specific configuration**
-```ruby
-# Different security levels per environment
-if Rails.env.production?
-  config.skip_signature_validation = false  # Enforce validation
-else
-  config.skip_signature_validation = true   # Allow for development
-end
-```
-
-✅ **Enable simulator only when needed**
-```ruby
-# Only enable simulator in development/staging (default)
-enable_simulator = Rails.env.development? || Rails.env.staging?
-processor = FlowChat::Whatsapp::Processor.new(self, enable_simulator: enable_simulator)
-```
-
-### 5. Choose the Right WhatsApp Mode
-
-Configure the appropriate mode based on your environment and requirements:
-
-```ruby
-# config/initializers/flowchat.rb
-
-# Development/Testing - use simulator mode with security
-if Rails.env.development? || Rails.env.test?
-  FlowChat::Config.whatsapp.message_handling_mode = :simulator
-  FlowChat::Config.simulator_secret = Rails.application.secret_key_base + "_dev"
-end
-
-# Staging - use inline mode with full security
-if Rails.env.staging?
-  FlowChat::Config.whatsapp.message_handling_mode = :inline
-  FlowChat::Config.simulator_secret = ENV['FLOWCHAT_SIMULATOR_SECRET']
-end
-
-# Production - use background mode with full security
-if Rails.env.production?
-  FlowChat::Config.whatsapp.message_handling_mode = :background
-  FlowChat::Config.whatsapp.background_job_class = 'WhatsappMessageJob'
-  FlowChat::Config.simulator_secret = ENV['FLOWCHAT_SIMULATOR_SECRET']
-end
-```
-
-### 6. Error Handling Best Practices
-
-Handle security and configuration errors gracefully:
-
-```ruby
-def webhook
-  begin
-    processor = FlowChat::Whatsapp::Processor.new(self, enable_simulator: Rails.env.development?) do |config|
-      config.use_gateway FlowChat::Whatsapp::Gateway::CloudApi
-      config.use_session_store FlowChat::Session::CacheSessionStore
-    end
+config = FlowChat::Whatsapp::Configuration.from_credentials
+client = FlowChat::Whatsapp::Client.new(config)
 
-    processor.run WelcomeFlow, :main_page
-    
-  rescue FlowChat::Whatsapp::ConfigurationError => e
-    Rails.logger.error "WhatsApp configuration error: #{e.message}"
-    head :internal_server_error
-    
-  rescue => e
-    Rails.logger.error "Unexpected error processing WhatsApp webhook: #{e.message}"
-    head :internal_server_error
-  end
-end
+# Send messages
+client.send_text("+1234567890", "Hello!")
+client.send_buttons("+1234567890", "Choose:", [
+  { id: 'option1', title: 'Option 1' },
+  { id: 'option2', title: 'Option 2' }
+])
 ```
 
-## Appendix
-
-### Context Variables Reference
-
-FlowChat provides a rich set of context variables that are available throughout your flows. These variables are automatically populated based on the gateway and message type.
-
-#### Core Context Variables
-
-**Request Variables**
-
-| Variable | Description |
-|----------|-------------|
-| `context.input` | Current user input |
-| `context["request.id"]` | Unique request ID |
-| `context["request.timestamp"]` | Request timestamp |
-| `context["request.msisdn"]` | User's phone number |
-| `context["request.gateway"]` | Current gateway (`:whatsapp_cloud_api`, `:ussd_nalo`) |
-| `context["enable_simulator"]` | Whether simulator mode is enabled for this request |
-| `context["simulator_mode"]` | Whether simulator mode is active |
-
-**Flow Variables**
-
-| Variable | Description |
-|----------|-------------|
-| `context["flow.name"]` | Current flow name |
-| `context["flow.class"]` | Current flow class |
-| `context["flow.action"]` | Current flow action/method |
-
-**Session Variables**
-
-| Variable | Description |
-|----------|-------------|
-| `context["session.id"]` | Current session ID |
-| `context["session.store"]` | Session data store |
-
-**Controller Variables**
-
-| Variable | Description |
-|----------|-------------|
-| `context.controller` | Current controller instance |
+## Testing Simulator
 
-#### WhatsApp-Specific Variables
+FlowChat includes a powerful built-in simulator with a modern web interface for testing both USSD and WhatsApp flows:
 
-| Variable | Description |
-|----------|-------------|
-| `context["whatsapp.message_result"]` | Result of last message send |
-| `context["whatsapp.message_id"]` | WhatsApp message ID |
-| `context["whatsapp.contact_name"]` | WhatsApp contact name |
-| `context["whatsapp.location"]` | Location data if shared |
-| `context["whatsapp.media"]` | Media data if attached |
+![FlowChat Simulator](docs/images/simulator.png)
 
-#### USSD-Specific Variables
+Features:
+- 📱 **Visual Interface** - Phone-like display with real conversation flow
+- 🔄 **Environment Switching** - Toggle between USSD and WhatsApp modes
+- 📊 **Request Logging** - Real-time HTTP request/response monitoring
+- 🎯 **Interactive Testing** - Test flows with character counting and validation
+- 🛠️ **Developer Tools** - Session management and connection status
 
-| Variable | Description |
-|----------|-------------|
-| `context["ussd.request"]` | Original USSD request |
-| `context["ussd.response"]` | USSD response object |
-| `context["ussd.pagination"]` | Pagination data for long messages |
+See the [Testing Guide](docs/testing.md) for complete setup instructions and testing strategies.
 
-#### Session Data Variables
 
-| Variable | Description |
-|----------|-------------|
-| `context["$started_at$"]` | When the conversation started |
+## Documentation
 
-#### Usage Notes
+- **[WhatsApp Setup](docs/whatsapp-setup.md)** - Comprehensive WhatsApp configuration
+- **[USSD Setup](docs/ussd-setup.md)** - USSD gateway configuration and examples
+- **[Flow Development](docs/flows.md)** - Advanced flow patterns and techniques
+- **[Media Support](docs/media.md)** - Rich media handling for WhatsApp
+- **[Testing Guide](docs/testing.md)** - Complete testing strategies
+- **[Configuration Reference](docs/configuration.md)** - All configuration options
+- **[Instrumentation](docs/instrumentation.md)** - Monitoring and metrics
+- **[Security](docs/security.md)** - Security best practices
+- **[Examples](examples/)** - Complete working examples
 
-1. **Access Methods:**
-   ```ruby
-   # Direct access
-   context.input
-   context["request.msisdn"]
-   
-   # Through app object in flows
-   app.phone_number
-   app.contact_name
-   app.message_id
-   ```
+## Examples
 
-2. **Gateway-Specific Variables:**
-   - WhatsApp variables are only available when using WhatsApp gateway
-   - USSD variables are only available when using USSD gateway
-   - Core variables are available across all gateways
+See the [examples directory](examples/) for complete implementations:
 
-3. **Session Persistence:**
-   - Session data persists across requests
-   - WhatsApp sessions expire after 7 days
-   - USSD sessions expire after 1 hour
-   - Default session TTL is 1 day
+- **[USSD Controller](examples/ussd_controller.rb)** - Full USSD implementation
+- **[WhatsApp Controller](examples/whatsapp_controller.rb)** - Basic WhatsApp setup
+- **[Multi-tenant WhatsApp](examples/multi_tenant_whatsapp_controller.rb)** - Advanced WhatsApp
+- **[Background Jobs](examples/whatsapp_message_job.rb)** - Async message processing
+- **[Simulator Controller](examples/simulator_controller.rb)** - Testing setup
 
-4. **Security:**
-   - Webhook signatures are validated for WhatsApp requests
-   - Simulator mode requires valid simulator cookie
-   - Session data is encrypted at rest
+## License
 
-5. **Flow Control:**
-   - Context variables can be used to control flow logic
-   - Session data can be used to maintain state
-   - Request data can be used for validation
+The gem is available as open source under the terms of the [MIT License](https://opensource.org/licenses/MIT).