flow_chat 0.4.1 → 0.5.1

data/examples/simulator_controller.rb

@@ -0,0 +1,95 @@
+# Example Simulator Controller
+# Add this to your Rails application as app/controllers/simulator_controller.rb
+
+class SimulatorController < ApplicationController
+  include FlowChat::Simulator::Controller
+
+  def index
+    flowchat_simulator
+  end
+
+  protected
+
+  # Define different local endpoints to test on the same server
+  def configurations
+    {
+      ussd_main: {
+        name: "Main USSD Endpoint",
+        description: "Primary USSD integration endpoint",
+        processor_type: "ussd",
+        provider: "nalo",
+        endpoint: "/ussd",
+        icon: "📱",
+        color: "#28a745"
+      },
+      whatsapp_main: {
+        name: "Main WhatsApp Endpoint", 
+        description: "Primary WhatsApp webhook endpoint",
+        processor_type: "whatsapp",
+        provider: "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",
+        processor_type: "whatsapp",
+        provider: "cloud_api",
+        endpoint: "/tenants/a/whatsapp/webhook",
+        icon: "🏢",
+        color: "#fd7e14"
+      },
+      whatsapp_legacy: {
+        name: "Legacy WhatsApp",
+        description: "Legacy WhatsApp endpoint for backward compatibility",
+        processor_type: "whatsapp",
+        provider: "cloud_api",
+        endpoint: "/legacy/whatsapp",
+        icon: "📦",
+        color: "#6c757d"
+      }
+    }
+  end
+
+  # Default configuration to start with
+  def default_config_key
+    :whatsapp_main
+  end
+
+  # Default test phone number
+  def default_phone_number
+    "+1234567890"
+  end
+
+  # Default test contact name  
+  def default_contact_name
+    "Test User"
+  end
+end
+
+# Add this route to your config/routes.rb:
+# get '/simulator' => 'simulator#index'
+
+# Usage:
+# 1. Start your Rails server: rails server
+# 2. Visit http://localhost:3000/simulator
+# 3. Select different endpoints from the dropdown to test
+# 4. Send test messages to see how each endpoint responds
+# 5. View request/response logs in real-time
+
+# This allows you to test:
+# - Different controller implementations on the same server
+# - Different API versions (v1, v2, etc.)
+# - Multi-tenant endpoints with different configurations  
+# - Legacy endpoints alongside new ones
+# - Different flow implementations for different endpoints 

data/examples/ussd_controller.rb

@@ -9,7 +9,7 @@ class UssdController < ApplicationController
       config.use_gateway FlowChat::Ussd::Gateway::Nalo
       # Use Rails session for USSD (shorter sessions)
       config.use_session_store FlowChat::Session::RailsSessionStore
-      
+
       # Enable resumable sessions (optional)
       config.use_resumable_sessions
     end
@@ -33,7 +33,7 @@ class WelcomeFlow < FlowChat::Flow
     choice = app.screen(:main_menu) do |prompt|
       prompt.select "Hi #{name}! Choose an option:", {
         "1" => "Account Info",
-        "2" => "Make Payment", 
+        "2" => "Make Payment",
         "3" => "Get Balance",
         "4" => "Customer Support"
       }
@@ -118,7 +118,7 @@ class WelcomeFlow < FlowChat::Flow
     support_choice = app.screen(:support_menu) do |prompt|
       prompt.select "Customer Support:", {
         "1" => "Report an Issue",
-        "2" => "Account Questions", 
+        "2" => "Account Questions",
         "3" => "Technical Support",
         "4" => "Speak to Agent",
         "0" => "Main Menu"
@@ -159,12 +159,12 @@ class WelcomeFlow < FlowChat::Flow
 
     # Save the issue (your business logic here)
     ticket_id = create_support_ticket(issue_type, description, app.phone_number)
-    
+
     app.say "Issue reported successfully!\\n\\nTicket ID: #{ticket_id}\\nWe'll contact you within 24 hours.\\n\\nThank you!"
   end
 
   # Helper methods (implement your business logic)
-  
+
   def process_payment(amount, recipient)
     # Your payment processing logic here
     # Return transaction ID
@@ -175,7 +175,7 @@ class WelcomeFlow < FlowChat::Flow
     # Your balance checking logic here
     {
       available: "150.75",
-      pending: "25.00", 
+      pending: "25.00",
       total: "175.75"
     }
   end
@@ -190,6 +190,7 @@ end
 # Configuration Examples:
 
 # 1. Basic configuration with custom pagination
+# rubocop:disable Lint/DuplicateMethods
 class UssdController < ApplicationController
   skip_forgery_protection
 
@@ -207,6 +208,7 @@ class UssdController < ApplicationController
     processor.run WelcomeFlow, :main_page
   end
 end
+# rubocop:enable Lint/DuplicateMethods
 
 # 2. Configuration with custom middleware
 class LoggingMiddleware
@@ -215,18 +217,19 @@ class LoggingMiddleware
   end
 
   def call(context)
-    Rails.logger.info "USSD Request from #{context['request.msisdn']}: #{context.input}"
+    Rails.logger.info "USSD Request from #{context["request.msisdn"]}: #{context.input}"
     start_time = Time.current
-    
+
     result = @app.call(context)
-    
+
     duration = Time.current - start_time
     Rails.logger.info "USSD Response (#{duration.round(3)}s): #{result[1]}"
-    
+
     result
   end
 end
 
+# rubocop:disable Lint/DuplicateMethods
 class UssdController < ApplicationController
   skip_forgery_protection
 
@@ -241,8 +244,10 @@ class UssdController < ApplicationController
     processor.run WelcomeFlow, :main_page
   end
 end
+# rubocop:enable Lint/DuplicateMethods
 
 # 3. Configuration with cache-based sessions for longer persistence
+# rubocop:disable Lint/DuplicateMethods
 class UssdController < ApplicationController
   skip_forgery_protection
 
@@ -256,9 +261,10 @@ class UssdController < ApplicationController
     processor.run WelcomeFlow, :main_page
   end
 end
+# rubocop:enable Lint/DuplicateMethods
 
 # Add this route to your config/routes.rb:
 # post '/ussd', to: 'ussd#process_request'
 
 # For Nsano gateway, use:
-# config.use_gateway FlowChat::Ussd::Gateway::Nsano 
+# config.use_gateway FlowChat::Ussd::Gateway::Nsano

data/examples/whatsapp_controller.rb

@@ -5,36 +5,125 @@ class WhatsappController < ApplicationController
   skip_forgery_protection
 
   def webhook
-    processor = FlowChat::Whatsapp::Processor.new(self) do |config|
+    # Enable simulator mode for local endpoint testing in development
+    processor = FlowChat::Whatsapp::Processor.new(self, enable_simulator: Rails.env.development?) do |config|
       config.use_gateway FlowChat::Whatsapp::Gateway::CloudApi
       # Use cache-based session store for longer WhatsApp conversations
       config.use_session_store FlowChat::Session::CacheSessionStore
     end
 
     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
 
-# Example with Custom Configuration
+# Example with Custom Configuration and Security
 class CustomWhatsappController < ApplicationController
   skip_forgery_protection
 
   def webhook
     # Create custom WhatsApp configuration for this endpoint
     custom_config = FlowChat::Whatsapp::Configuration.new
-    custom_config.access_token = ENV['MY_WHATSAPP_ACCESS_TOKEN']
-    custom_config.phone_number_id = ENV['MY_WHATSAPP_PHONE_NUMBER_ID']
-    custom_config.verify_token = ENV['MY_WHATSAPP_VERIFY_TOKEN']
-    custom_config.app_id = ENV['MY_WHATSAPP_APP_ID']
-    custom_config.app_secret = ENV['MY_WHATSAPP_APP_SECRET']
-    custom_config.business_account_id = ENV['MY_WHATSAPP_BUSINESS_ACCOUNT_ID']
-
-    processor = FlowChat::Whatsapp::Processor.new(self) do |config|
+    custom_config.access_token = ENV["MY_WHATSAPP_ACCESS_TOKEN"]
+    custom_config.phone_number_id = ENV["MY_WHATSAPP_PHONE_NUMBER_ID"]
+    custom_config.verify_token = ENV["MY_WHATSAPP_VERIFY_TOKEN"]
+    custom_config.app_id = ENV["MY_WHATSAPP_APP_ID"]
+    custom_config.app_secret = ENV["MY_WHATSAPP_APP_SECRET"]
+    custom_config.business_account_id = ENV["MY_WHATSAPP_BUSINESS_ACCOUNT_ID"]
+    
+    # Security configuration
+    custom_config.skip_signature_validation = !Rails.env.production? # Only skip in non-production
+
+    # Enable simulator for local endpoint testing in non-production environments  
+    processor = FlowChat::Whatsapp::Processor.new(self, enable_simulator: !Rails.env.production?) do |config|
       config.use_gateway FlowChat::Whatsapp::Gateway::CloudApi, custom_config
       config.use_session_store FlowChat::Session::CacheSessionStore
     end
 
     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
+
+# Example with Environment-Specific Security
+class EnvironmentAwareWhatsappController < ApplicationController
+  skip_forgery_protection
+
+  def webhook
+    # Configure security based on environment
+    custom_config = build_whatsapp_config
+    
+    # Enable simulator for local endpoint testing in development/staging
+    enable_simulator = Rails.env.development? || Rails.env.staging?
+
+    processor = FlowChat::Whatsapp::Processor.new(self, enable_simulator: enable_simulator) do |config|
+      config.use_gateway FlowChat::Whatsapp::Gateway::CloudApi, custom_config
+      config.use_session_store FlowChat::Session::CacheSessionStore
+    end
+
+    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
+
+  private
+
+  def build_whatsapp_config
+    config = FlowChat::Whatsapp::Configuration.new
+    
+    case Rails.env
+    when 'development'
+      # Development: More relaxed security for easier testing
+      config.access_token = ENV["WHATSAPP_ACCESS_TOKEN"]
+      config.phone_number_id = ENV["WHATSAPP_PHONE_NUMBER_ID"]
+      config.verify_token = ENV["WHATSAPP_VERIFY_TOKEN"]
+      config.app_id = ENV["WHATSAPP_APP_ID"]
+      config.app_secret = ENV["WHATSAPP_APP_SECRET"]  # Optional in development
+      config.business_account_id = ENV["WHATSAPP_BUSINESS_ACCOUNT_ID"]
+      config.skip_signature_validation = true  # Skip validation for easier development
+      
+    when 'test'
+      # Test: Use test credentials
+      config.access_token = "test_token"
+      config.phone_number_id = "test_phone_id"
+      config.verify_token = "test_verify_token"
+      config.app_id = "test_app_id"
+      config.app_secret = "test_app_secret"
+      config.business_account_id = "test_business_id"
+      config.skip_signature_validation = true  # Skip validation in tests
+      
+    when 'staging', 'production'
+      # Production: Full security enabled
+      config.access_token = ENV["WHATSAPP_ACCESS_TOKEN"]
+      config.phone_number_id = ENV["WHATSAPP_PHONE_NUMBER_ID"]
+      config.verify_token = ENV["WHATSAPP_VERIFY_TOKEN"]
+      config.app_id = ENV["WHATSAPP_APP_ID"]
+      config.app_secret = ENV["WHATSAPP_APP_SECRET"]  # Required for security
+      config.business_account_id = ENV["WHATSAPP_BUSINESS_ACCOUNT_ID"]
+      config.skip_signature_validation = false  # Always validate in production
+      
+      # Ensure required security configuration is present
+      if config.app_secret.blank?
+        raise FlowChat::Whatsapp::ConfigurationError, 
+          "WHATSAPP_APP_SECRET is required for webhook signature validation in #{Rails.env}"
+      end
+    end
+    
+    config
   end
 end
 
@@ -53,7 +142,7 @@ class WelcomeFlow < FlowChat::Flow
     choice = app.screen(:main_menu) do |prompt|
       prompt.select "Hi #{name}! What can I help you with today?", {
         "info" => "📋 Get Information",
-        "support" => "🆘 Contact Support", 
+        "support" => "🆘 Contact Support",
         "feedback" => "💬 Give Feedback"
       }
     end
@@ -94,7 +183,7 @@ class WelcomeFlow < FlowChat::Flow
     contact_method = app.screen(:contact_method) do |prompt|
       prompt.select "How would you like to contact support?", {
         "call" => "📞 Call Us",
-        "email" => "📧 Email Us", 
+        "email" => "📧 Email Us",
         "chat" => "💬 Live Chat"
       }
     end
@@ -113,7 +202,7 @@ class WelcomeFlow < FlowChat::Flow
     rating = app.screen(:rating) do |prompt|
       prompt.select "How would you rate our service?", {
         "5" => "⭐⭐⭐⭐⭐ Excellent",
-        "4" => "⭐⭐⭐⭐ Good", 
+        "4" => "⭐⭐⭐⭐ Good",
         "3" => "⭐⭐⭐ Average",
         "2" => "⭐⭐ Poor",
         "1" => "⭐ Very Poor"
@@ -137,4 +226,4 @@ class WelcomeFlow < FlowChat::Flow
 end
 
 # Add this route to your config/routes.rb:
-# post '/whatsapp/webhook', to: 'whatsapp#webhook' 
+# post '/whatsapp/webhook', to: 'whatsapp#webhook'