flow_chat 0.6.1 → 0.8.0

data/docs/ussd-setup.md

@@ -0,0 +1,322 @@
+# USSD Setup Guide
+
+This guide covers USSD configuration and implementation patterns for FlowChat.
+
+## Basic Setup
+
+### 1. Create a Flow
+
+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?",
+        transform: ->(input) { input.strip.titleize }
+    end
+
+    service = app.screen(:service) do |prompt|
+      prompt.select "Choose a service:", {
+        "balance" => "Check Balance",
+        "transfer" => "Transfer Money",
+        "history" => "Transaction History"
+      }
+    end
+
+    case service
+    when "balance"
+      show_balance
+    when "transfer"
+      transfer_money
+    when "history"
+      show_history
+    end
+  end
+
+  private
+
+  def show_balance
+    # Simulate balance check
+    balance = fetch_user_balance(app.phone_number)
+    app.say "Hello #{app.session.get(:name)}! Your balance is $#{balance}."
+  end
+end
+```
+
+### 2. Create Controller
+
+```ruby
+class UssdController < ApplicationController
+  skip_forgery_protection
+
+  def process_request
+    processor = FlowChat::Ussd::Processor.new(self) do |config|
+      config.use_gateway FlowChat::Ussd::Gateway::Nalo
+      config.use_session_store FlowChat::Session::CacheSessionStore
+    end
+
+    processor.run WelcomeFlow, :main_page
+  end
+end
+```
+
+### 3. Configure Routes
+
+```ruby
+# config/routes.rb
+Rails.application.routes.draw do
+  post 'ussd' => 'ussd#process_request'
+end
+```
+
+## Gateway Configuration
+
+### Nalo Gateway
+
+FlowChat currently supports Nalo USSD gateways:
+
+```ruby
+processor = FlowChat::Ussd::Processor.new(self) do |config|
+  config.use_gateway FlowChat::Ussd::Gateway::Nalo
+  config.use_session_store FlowChat::Session::CacheSessionStore
+end
+```
+
+The Nalo gateway expects these parameters in the request:
+- `msisdn` - User's phone number
+- `input` - User's input text
+- `session_id` - Session identifier
+
+## Pagination
+
+USSD messages are automatically paginated when they exceed character limits:
+
+```ruby
+# Configure pagination behavior
+FlowChat::Config.ussd.pagination_page_size = 140        # characters per page
+FlowChat::Config.ussd.pagination_next_option = "#"      # option for next page
+FlowChat::Config.ussd.pagination_next_text = "More"     # text for next option
+FlowChat::Config.ussd.pagination_back_option = "0"      # option for previous page
+FlowChat::Config.ussd.pagination_back_text = "Back"     # text for back option
+```
+
+### Example Long Message
+
+```ruby
+def show_terms
+  terms = "Very long terms and conditions text that exceeds 140 characters..."
+  app.say terms  # Automatically paginated
+end
+```
+
+**USSD Output:**
+```
+Terms and Conditions:
+Lorem ipsum dolor sit amet, consectetur adipiscing elit. Sed do eiusmod tempor incididunt...
+
+# More
+0 Back
+```
+
+## Session Management
+
+Configure session behavior for better user experience:
+
+```ruby
+processor = FlowChat::Ussd::Processor.new(self) do |config|
+  config.use_gateway FlowChat::Ussd::Gateway::Nalo
+  config.use_session_store FlowChat::Session::CacheSessionStore
+  
+  # Enable durable sessions (shorthand)
+  config.use_durable_sessions
+end
+```
+
+### Session Boundaries
+
+Session boundaries control how session IDs are constructed:
+
+- **`:flow`** - Separate sessions per flow class
+- **`:platform`** - Separate USSD from WhatsApp sessions  
+- **`:gateway`** - Separate sessions per gateway
+- **`[]`** - Global sessions (no boundaries)
+
+Session identifier options:
+
+- **`nil`** - Platform chooses default (`:request_id` for USSD, `:msisdn` for WhatsApp)
+- **`:msisdn`** - Use phone number (durable sessions)
+- **`:request_id`** - Use request ID (ephemeral sessions)
+- **`hash_phone_numbers`** - Hash phone numbers for privacy (recommended)
+
+## Middleware
+
+### Custom Middleware
+
+```ruby
+class AuthenticationMiddleware
+  def initialize(app)
+    @app = app
+  end
+
+  def call(context)
+    phone = context["request.msisdn"]
+    
+    unless user_exists?(phone)
+      # Return appropriate response for unregistered user
+      return [:prompt, "Please register first. Visit our website to sign up.", nil, nil]
+    end
+    
+    @app.call(context)
+  end
+
+  private
+
+  def user_exists?(phone)
+    User.exists?(phone: phone)
+  end
+end
+
+# Use 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 AuthenticationMiddleware
+end
+```
+
+## Advanced Patterns
+
+### Menu-Driven Navigation
+
+```ruby
+class MenuFlow < FlowChat::Flow
+  def main_page
+    choice = app.screen(:main_menu) do |prompt|
+      prompt.select "Main Menu:", {
+        "1" => "Account Services",
+        "2" => "Transfer Services", 
+        "3" => "Customer Support"
+      }
+    end
+
+    case choice
+    when "1"
+      account_services
+    when "2"
+      transfer_services
+    when "3"
+      customer_support
+    end
+  end
+
+  def account_services
+    choice = app.screen(:account_menu) do |prompt|
+      prompt.select "Account Services:", {
+        "1" => "Check Balance",
+        "2" => "Mini Statement",
+        "0" => "Back to Main Menu"
+      }
+    end
+
+    case choice
+    when "1"
+      check_balance
+    when "2"
+      mini_statement
+    when "0"
+      main_page  # Return to main menu
+    end
+  end
+end
+```
+
+### Error Handling
+
+```ruby
+def transfer_money
+  begin
+    amount = app.screen(:amount) do |prompt|
+      prompt.ask "Enter amount:",
+        validate: ->(input) {
+          return "Amount must be numeric" unless input.match?(/^\d+(\.\d{2})?$/)
+          return "Minimum transfer is $1" unless input.to_f >= 1.0
+          nil
+        },
+        transform: ->(input) { input.to_f }
+    end
+
+    recipient = app.screen(:recipient) do |prompt|
+      prompt.ask "Enter recipient phone number:",
+        validate: ->(input) {
+          return "Invalid phone number" unless valid_phone?(input)
+          nil
+        }
+    end
+
+    process_transfer(amount, recipient)
+    app.say "Transfer of $#{amount} to #{recipient} successful!"
+
+  rescue TransferError => e
+    app.say "Transfer failed: #{e.message}. Please try again."
+    transfer_money  # Retry
+  end
+end
+```
+
+### Session Data Management
+
+```ruby
+class RegistrationFlow < FlowChat::Flow
+  def main_page
+    collect_personal_info
+    collect_preferences
+    confirm_and_save
+  end
+
+  private
+
+  def collect_personal_info
+    app.screen(:first_name) { |p| p.ask "First name:" }
+    app.screen(:last_name) { |p| p.ask "Last name:" }
+    app.screen(:email) { |p| p.ask "Email address:" }
+  end
+
+  def collect_preferences
+    app.screen(:language) { |p| p.select "Language:", ["English", "French"] }
+    app.screen(:notifications) { |p| p.yes? "Enable SMS notifications?" }
+  end
+
+  def confirm_and_save
+    summary = build_summary_from_session
+    confirmed = app.screen(:confirm) { |p| p.yes? "Save profile?\n\n#{summary}" }
+
+    if confirmed
+      save_user_profile
+      app.say "Registration complete!"
+    else
+      app.say "Registration cancelled."
+    end
+  end
+
+  def build_summary_from_session
+    first_name = app.session.get(:first_name)
+    last_name = app.session.get(:last_name)
+    email = app.session.get(:email)
+    language = app.session.get(:language)
+    
+    "Name: #{first_name} #{last_name}\nEmail: #{email}\nLanguage: #{language}"
+  end
+end
+```
+
+## Testing USSD Flows
+
+Use the built-in simulator for testing USSD flows:
+
+```ruby
+# config/initializers/flowchat.rb
+FlowChat::Config.simulator_secret = "your_secure_secret"
+```
+
+See [Testing Guide](testing.md) for comprehensive testing strategies and [examples/ussd_controller.rb](../examples/ussd_controller.rb) for complete implementation examples. 

data/docs/whatsapp-setup.md

@@ -0,0 +1,162 @@
+# WhatsApp Setup Guide
+
+This guide covers comprehensive WhatsApp configuration for FlowChat, including security, multi-tenant setups, and different processing modes.
+
+## Credential Configuration
+
+FlowChat supports multiple ways to configure WhatsApp credentials:
+
+### Option 1: Rails Credentials
+
+```bash
+rails credentials:edit
+```
+
+```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 2: Environment Variables
+
+```bash
+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"
+```
+
+### Option 3: Per-Setup Configuration
+
+For multi-tenant applications:
+
+```ruby
+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
+
+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
+```
+
+## Message Handling Modes
+
+Configure message processing behavior in `config/initializers/flowchat.rb`:
+
+### Inline Mode (Default)
+
+Process messages synchronously:
+
+```ruby
+FlowChat::Config.whatsapp.message_handling_mode = :inline
+```
+
+### Background Mode
+
+Process flows synchronously, send responses asynchronously:
+
+```ruby
+FlowChat::Config.whatsapp.message_handling_mode = :background
+FlowChat::Config.whatsapp.background_job_class = 'WhatsappMessageJob'
+```
+
+### Simulator Mode
+
+Return response data instead of sending via WhatsApp API:
+
+```ruby
+FlowChat::Config.whatsapp.message_handling_mode = :simulator
+```
+
+## Security Configuration
+
+### Webhook Signature Validation (Production)
+
+```ruby
+custom_config.app_secret = "your_whatsapp_app_secret"
+custom_config.skip_signature_validation = false  # Default: enforce validation
+```
+
+### Development Mode
+
+```ruby
+custom_config.app_secret = nil
+custom_config.skip_signature_validation = true  # Disable validation
+```
+
+⚠️ **Security Warning**: Only disable signature validation in development/testing environments.
+
+## Multi-Tenant Setup
+
+See [examples/multi_tenant_whatsapp_controller.rb](../examples/multi_tenant_whatsapp_controller.rb) for a complete multi-tenant implementation.
+
+## Background Job Setup
+
+When using background jobs with programmatic WhatsApp configurations, you must register configurations in an initializer so they're available to background jobs:
+
+```ruby
+# config/initializers/whatsapp_configs.rb
+tenant_a_config = FlowChat::Whatsapp::Configuration.new(:tenant_a)
+tenant_a_config.access_token = "tenant_a_token"
+tenant_a_config.phone_number_id = "tenant_a_phone"
+tenant_a_config.verify_token = "tenant_a_verify"
+tenant_a_config.app_secret = "tenant_a_secret"
+# Configuration is automatically registered as :tenant_a
+
+tenant_b_config = FlowChat::Whatsapp::Configuration.new(:tenant_b)
+tenant_b_config.access_token = "tenant_b_token"
+tenant_b_config.phone_number_id = "tenant_b_phone"
+tenant_b_config.verify_token = "tenant_b_verify"
+tenant_b_config.app_secret = "tenant_b_secret"
+# Configuration is automatically registered as :tenant_b
+```
+
+Then reference the named configuration in your controller:
+
+```ruby
+processor = FlowChat::Whatsapp::Processor.new(self) do |config|
+  # Use registered configuration by name
+  tenant_config = FlowChat::Whatsapp::Configuration.get(:tenant_a)
+  config.use_gateway FlowChat::Whatsapp::Gateway::CloudApi, tenant_config
+  config.use_session_store FlowChat::Session::CacheSessionStore
+end
+```
+
+**Why this is required:** Background jobs run in a separate context and cannot access configurations created in controller actions. Registered configurations are globally available.
+
+**Alternative:** Override the job's configuration resolution logic (see examples).
+
+See [examples/whatsapp_message_job.rb](../examples/whatsapp_message_job.rb) for job implementation and [Background Jobs Guide](background-jobs.md) for detailed setup.
+
+## Troubleshooting
+
+### Common Issues
+
+**Configuration Error**: Check that all required credentials are set
+**Signature Validation Failed**: Verify app_secret matches your WhatsApp app
+**Timeout Issues**: Consider using background mode for high-volume applications
+
+### Debug Mode
+
+Enable debug logging in development:
+
+```ruby
+# config/environments/development.rb
+config.log_level = :debug
+``` 

data/examples/multi_tenant_whatsapp_controller.rb

@@ -1,26 +1,19 @@
 # Example Multi-Tenant WhatsApp Controller
 # This shows how to configure different WhatsApp accounts per tenant/client
 
+# Controller supporting multiple WhatsApp accounts per tenant
 class MultiTenantWhatsappController < ApplicationController
   skip_forgery_protection
 
   def webhook
-    # Determine tenant from subdomain, path, or other logic
     tenant = determine_tenant(request)
-
-    # Get tenant-specific WhatsApp configuration
     whatsapp_config = get_whatsapp_config_for_tenant(tenant)
 
-    # Enable simulator for local endpoint testing during development
-    # This allows testing different tenant endpoints via the simulator interface
-    enable_simulator = Rails.env.development? || Rails.env.staging?
-
-    processor = FlowChat::Whatsapp::Processor.new(self, enable_simulator: enable_simulator) do |config|
+    processor = FlowChat::Whatsapp::Processor.new(self, enable_simulator: !Rails.env.production?) do |config|
       config.use_gateway FlowChat::Whatsapp::Gateway::CloudApi, whatsapp_config
       config.use_session_store FlowChat::Session::CacheSessionStore
     end
 
-    # Use tenant-specific flow
     flow_class = get_flow_for_tenant(tenant)
     processor.run flow_class, :main_page
   end
@@ -31,14 +24,13 @@ class MultiTenantWhatsappController < ApplicationController
     # Option 1: From subdomain
     return request.subdomain if request.subdomain.present?
 
-    # Option 2: From path
+    # Option 2: From path (e.g., /whatsapp/acme/webhook)
     tenant_from_path = request.path.match(%r{^/whatsapp/(\w+)/})&.captures&.first
     return tenant_from_path if tenant_from_path
 
-    # Option 3: From custom header
+    # Option 3: From header
     return request.headers["X-Tenant-ID"] if request.headers["X-Tenant-ID"]
 
-    # Fallback to default
     "default"
   end
 
@@ -49,9 +41,7 @@ class MultiTenantWhatsappController < ApplicationController
         config.access_token = ENV["ACME_WHATSAPP_ACCESS_TOKEN"]
         config.phone_number_id = ENV["ACME_WHATSAPP_PHONE_NUMBER_ID"]
         config.verify_token = ENV["ACME_WHATSAPP_VERIFY_TOKEN"]
-        config.app_id = ENV["ACME_WHATSAPP_APP_ID"]
         config.app_secret = ENV["ACME_WHATSAPP_APP_SECRET"]
-        config.business_account_id = ENV["ACME_WHATSAPP_BUSINESS_ACCOUNT_ID"]
       end
 
     when "tech_startup"
@@ -59,9 +49,7 @@ class MultiTenantWhatsappController < ApplicationController
         config.access_token = ENV["TECHSTARTUP_WHATSAPP_ACCESS_TOKEN"]
         config.phone_number_id = ENV["TECHSTARTUP_WHATSAPP_PHONE_NUMBER_ID"]
         config.verify_token = ENV["TECHSTARTUP_WHATSAPP_VERIFY_TOKEN"]
-        config.app_id = ENV["TECHSTARTUP_WHATSAPP_APP_ID"]
         config.app_secret = ENV["TECHSTARTUP_WHATSAPP_APP_SECRET"]
-        config.business_account_id = ENV["TECHSTARTUP_WHATSAPP_BUSINESS_ACCOUNT_ID"]
       end
 
     when "retail_store"
@@ -71,13 +59,10 @@ class MultiTenantWhatsappController < ApplicationController
         config.access_token = tenant_config.access_token
         config.phone_number_id = tenant_config.phone_number_id
         config.verify_token = tenant_config.verify_token
-        config.app_id = tenant_config.app_id
         config.app_secret = tenant_config.app_secret
-        config.business_account_id = tenant_config.business_account_id
       end
 
     else
-      # Use default/global configuration
       FlowChat::Whatsapp::Configuration.from_credentials
     end
   end
@@ -91,7 +76,7 @@ class MultiTenantWhatsappController < ApplicationController
     when "retail_store"
       RetailStoreFlow
     else
-      WelcomeFlow  # Default flow
+      WelcomeFlow
     end
   end
 end
@@ -101,21 +86,14 @@ class DatabaseWhatsappController < ApplicationController
   skip_forgery_protection
 
   def webhook
-    # Get account from business phone number or other identifier
     business_account = find_business_account(params)
+    return head :not_found if business_account.nil?
 
-    if business_account.nil?
-      return head :not_found
-    end
-
-    # Create configuration from database record
     whatsapp_config = FlowChat::Whatsapp::Configuration.new.tap do |config|
       config.access_token = business_account.whatsapp_access_token
       config.phone_number_id = business_account.whatsapp_phone_number_id
       config.verify_token = business_account.whatsapp_verify_token
-      config.app_id = business_account.whatsapp_app_id
       config.app_secret = business_account.whatsapp_app_secret
-      config.business_account_id = business_account.whatsapp_business_account_id
     end
 
     processor = FlowChat::Whatsapp::Processor.new(self) do |config|
@@ -129,20 +107,14 @@ class DatabaseWhatsappController < ApplicationController
   private
 
   def find_business_account(params)
-    # You could identify the account by:
-    # 1. Phone number ID from webhook
-    # 2. Business account ID from webhook
-    # 3. Custom routing parameter
-
-    # Example: Find by phone number ID in webhook
+    # Find by phone number ID from webhook
     phone_number_id = extract_phone_number_id_from_webhook(params)
     BusinessAccount.find_by(whatsapp_phone_number_id: phone_number_id)
   end
 
   def extract_phone_number_id_from_webhook(params)
-    # Extract from webhook payload structure
-    # This would need to be implemented based on your webhook structure
-    nil
+    # Extract from webhook payload - implement based on your structure
+    params.dig(:entry, 0, :changes, 0, :value, :metadata, :phone_number_id)
   end
 end
 

data/examples/simulator_controller.rb

@@ -10,50 +10,41 @@ class SimulatorController < ApplicationController
 
   protected
 
-  # Define different local endpoints to test on the same server
+  # Define different endpoints to test
   def configurations
     {
       ussd_main: {
         name: "Main USSD Endpoint",
-        description: "Primary USSD integration endpoint",
+        description: "Primary USSD integration",
         processor_type: "ussd",
-        provider: "nalo",
+        gateway: "nalo",
         endpoint: "/ussd",
         icon: "📱",
         color: "#28a745"
       },
       whatsapp_main: {
-        name: "Main WhatsApp Endpoint", 
-        description: "Primary WhatsApp webhook endpoint",
+        name: "Main WhatsApp Endpoint",
+        description: "Primary WhatsApp webhook",
         processor_type: "whatsapp",
-        provider: "cloud_api",
+        gateway: "cloud_api",
         endpoint: "/whatsapp/webhook",
         icon: "💬",
         color: "#25D366"
       },
-      whatsapp_v2: {
-        name: "WhatsApp API v2",
-        description: "Alternative WhatsApp endpoint (v2 API)",
-        processor_type: "whatsapp",
-        provider: "cloud_api", 
-        endpoint: "/api/v2/whatsapp/webhook",
-        icon: "🔄",
-        color: "#17a2b8"
-      },
       whatsapp_tenant_a: {
         name: "Tenant A WhatsApp",
-        description: "Multi-tenant WhatsApp endpoint for Tenant A",
+        description: "Multi-tenant endpoint for Tenant A",
         processor_type: "whatsapp",
-        provider: "cloud_api",
+        gateway: "cloud_api",
         endpoint: "/tenants/a/whatsapp/webhook",
         icon: "🏢",
         color: "#fd7e14"
       },
       whatsapp_legacy: {
         name: "Legacy WhatsApp",
-        description: "Legacy WhatsApp endpoint for backward compatibility",
+        description: "Legacy endpoint for compatibility",
         processor_type: "whatsapp",
-        provider: "cloud_api",
+        gateway: "cloud_api",
         endpoint: "/legacy/whatsapp",
         icon: "📦",
         color: "#6c757d"
@@ -71,7 +62,7 @@ class SimulatorController < ApplicationController
     "+1234567890"
   end
 
-  # Default test contact name  
+  # Default test contact name
   def default_contact_name
     "Test User"
   end
@@ -90,6 +81,6 @@ end
 # This allows you to test:
 # - Different controller implementations on the same server
 # - Different API versions (v1, v2, etc.)
-# - Multi-tenant endpoints with different configurations  
+# - Multi-tenant endpoints with different configurations
 # - Legacy endpoints alongside new ones
-# - Different flow implementations for different endpoints 
+# - Different flow implementations for different endpoints