flow_chat 0.8.2 → 0.10.0

data/examples/multi_tenant_whatsapp_controller.rb

@@ -1,220 +1,115 @@
 # Example Multi-Tenant WhatsApp Controller
-# This shows how to configure different WhatsApp accounts per tenant/client
+# Shows how to run different WhatsApp accounts per tenant on one endpoint.
+
+# A single helper builds a Configuration from a set of environment variables,
+# so each tenant is one line instead of a repeated block. Pass an anonymous
+# configuration name (nil); Configuration#initialize requires a name argument.
+module WhatsappConfigBuilder
+  def whatsapp_config_from_env(prefix)
+    FlowChat::Whatsapp::Configuration.new(nil).tap do |config|
+      config.access_token = ENV["#{prefix}_WHATSAPP_ACCESS_TOKEN"]
+      config.phone_number_id = ENV["#{prefix}_WHATSAPP_PHONE_NUMBER_ID"]
+      config.verify_token = ENV["#{prefix}_WHATSAPP_VERIFY_TOKEN"]
+      config.app_secret = ENV["#{prefix}_WHATSAPP_APP_SECRET"]
+    end
+  end
+end
 
-# Controller supporting multiple WhatsApp accounts per tenant
+# Controller supporting multiple WhatsApp accounts per tenant.
 class MultiTenantWhatsappController < ApplicationController
+  include WhatsappConfigBuilder
+
   skip_forgery_protection
 
   def webhook
     tenant = determine_tenant(request)
-    whatsapp_config = get_whatsapp_config_for_tenant(tenant)
+    whatsapp_config = config_for_tenant(tenant)
 
-    processor = FlowChat::Whatsapp::Processor.new(self, enable_simulator: !Rails.env.production?) do |config|
+    processor = FlowChat::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
 
-    flow_class = get_flow_for_tenant(tenant)
-    processor.run flow_class, :main_page
+    processor.run flow_for_tenant(tenant), :main_page
   end
 
   private
 
   def determine_tenant(request)
-    # Option 1: From subdomain
     return request.subdomain if request.subdomain.present?
 
-    # 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 header
-    return request.headers["X-Tenant-ID"] if request.headers["X-Tenant-ID"]
-
-    "default"
+    request.headers["X-Tenant-ID"].presence || "default"
   end
 
-  def get_whatsapp_config_for_tenant(tenant)
+  def config_for_tenant(tenant)
     case tenant
-    when "acme_corp"
-      FlowChat::Whatsapp::Configuration.new.tap do |config|
-        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_secret = ENV["ACME_WHATSAPP_APP_SECRET"]
-      end
-
-    when "tech_startup"
-      FlowChat::Whatsapp::Configuration.new.tap do |config|
-        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_secret = ENV["TECHSTARTUP_WHATSAPP_APP_SECRET"]
-      end
-
-    when "retail_store"
-      # Load from database
-      tenant_config = WhatsappConfiguration.find_by(tenant: tenant)
-      FlowChat::Whatsapp::Configuration.new.tap do |config|
-        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_secret = tenant_config.app_secret
-      end
-
-    else
-      FlowChat::Whatsapp::Configuration.from_credentials
+    when "acme_corp" then whatsapp_config_from_env("ACME")
+    when "tech_startup" then whatsapp_config_from_env("TECHSTARTUP")
+    when "retail_store" then config_from_database(tenant)
+    else FlowChat::Whatsapp::Configuration.from_credentials
     end
   end
 
-  def get_flow_for_tenant(tenant)
-    case tenant
-    when "acme_corp"
-      AcmeCorpFlow
-    when "tech_startup"
-      TechStartupFlow
-    when "retail_store"
-      RetailStoreFlow
-    else
-      WelcomeFlow
+  # Load a tenant's credentials from your own model.
+  def config_from_database(tenant)
+    record = WhatsappConfiguration.find_by!(tenant: tenant)
+    FlowChat::Whatsapp::Configuration.new(nil).tap do |config|
+      config.access_token = record.access_token
+      config.phone_number_id = record.phone_number_id
+      config.verify_token = record.verify_token
+      config.app_secret = record.app_secret
     end
   end
+
+  def flow_for_tenant(tenant)
+    {
+      "acme_corp" => AcmeCorpFlow,
+      "tech_startup" => TechStartupFlow,
+      "retail_store" => RetailStoreFlow
+    }.fetch(tenant, WhatsappWelcomeFlow)
+  end
 end
 
-# Example: Dynamic Configuration from Database
+# Resolve the account from the webhook's own phone_number_id, rather than the URL.
 class DatabaseWhatsappController < ApplicationController
+  include WhatsappConfigBuilder
+
   skip_forgery_protection
 
   def webhook
-    business_account = find_business_account(params)
-    return head :not_found if business_account.nil?
-
-    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_secret = business_account.whatsapp_app_secret
+    account = find_business_account(params)
+    return head :not_found if account.nil?
+
+    whatsapp_config = FlowChat::Whatsapp::Configuration.new(nil).tap do |config|
+      config.access_token = account.whatsapp_access_token
+      config.phone_number_id = account.whatsapp_phone_number_id
+      config.verify_token = account.whatsapp_verify_token
+      config.app_secret = account.whatsapp_app_secret
     end
 
-    processor = FlowChat::Whatsapp::Processor.new(self) do |config|
+    processor = FlowChat::Processor.new(self) do |config|
       config.use_gateway FlowChat::Whatsapp::Gateway::CloudApi, whatsapp_config
       config.use_session_store FlowChat::Session::CacheSessionStore
     end
 
-    processor.run business_account.flow_class.constantize, :main_page
+    processor.run account.flow_class.constantize, :main_page
   end
 
   private
 
   def find_business_account(params)
-    # Find by phone number ID from webhook
-    phone_number_id = extract_phone_number_id_from_webhook(params)
+    phone_number_id = params.dig(:entry, 0, :changes, 0, :value, :metadata, :phone_number_id)
     BusinessAccount.find_by(whatsapp_phone_number_id: phone_number_id)
   end
-
-  def extract_phone_number_id_from_webhook(params)
-    # Extract from webhook payload - implement based on your structure
-    params.dig(:entry, 0, :changes, 0, :value, :metadata, :phone_number_id)
-  end
-end
-
-# Example: Environment-based Configuration
-class EnvironmentWhatsappController < ApplicationController
-  skip_forgery_protection
-
-  def webhook
-    # Different configurations for different environments
-    whatsapp_config = case Rails.env
-    when "production"
-      production_whatsapp_config
-    when "staging"
-      staging_whatsapp_config
-    when "development"
-      development_whatsapp_config
-    else
-      FlowChat::Whatsapp::Configuration.from_credentials
-    end
-
-    processor = FlowChat::Whatsapp::Processor.new(self) do |config|
-      config.use_gateway FlowChat::Whatsapp::Gateway::CloudApi, whatsapp_config
-      config.use_session_store FlowChat::Session::CacheSessionStore
-    end
-
-    processor.run WelcomeFlow, :main_page
-  end
-
-  private
-
-  def production_whatsapp_config
-    FlowChat::Whatsapp::Configuration.new.tap do |config|
-      config.access_token = ENV["PROD_WHATSAPP_ACCESS_TOKEN"]
-      config.phone_number_id = ENV["PROD_WHATSAPP_PHONE_NUMBER_ID"]
-      config.verify_token = ENV["PROD_WHATSAPP_VERIFY_TOKEN"]
-      config.app_id = ENV["PROD_WHATSAPP_APP_ID"]
-      config.app_secret = ENV["PROD_WHATSAPP_APP_SECRET"]
-      config.business_account_id = ENV["PROD_WHATSAPP_BUSINESS_ACCOUNT_ID"]
-    end
-  end
-
-  def staging_whatsapp_config
-    FlowChat::Whatsapp::Configuration.new.tap do |config|
-      config.access_token = ENV["STAGING_WHATSAPP_ACCESS_TOKEN"]
-      config.phone_number_id = ENV["STAGING_WHATSAPP_PHONE_NUMBER_ID"]
-      config.verify_token = ENV["STAGING_WHATSAPP_VERIFY_TOKEN"]
-      config.app_id = ENV["STAGING_WHATSAPP_APP_ID"]
-      config.app_secret = ENV["STAGING_WHATSAPP_APP_SECRET"]
-      config.business_account_id = ENV["STAGING_WHATSAPP_BUSINESS_ACCOUNT_ID"]
-    end
-  end
-
-  def development_whatsapp_config
-    FlowChat::Whatsapp::Configuration.new.tap do |config|
-      config.access_token = ENV["DEV_WHATSAPP_ACCESS_TOKEN"]
-      config.phone_number_id = ENV["DEV_WHATSAPP_PHONE_NUMBER_ID"]
-      config.verify_token = ENV["DEV_WHATSAPP_VERIFY_TOKEN"]
-      config.app_id = ENV["DEV_WHATSAPP_APP_ID"]
-      config.app_secret = ENV["DEV_WHATSAPP_APP_SECRET"]
-      config.business_account_id = ENV["DEV_WHATSAPP_BUSINESS_ACCOUNT_ID"]
-    end
-  end
-end
-
-# Example: Simple Custom Configuration
-class CustomWhatsappController < ApplicationController
-  skip_forgery_protection
-
-  def webhook
-    # Create custom configuration for this specific endpoint
-    my_config = FlowChat::Whatsapp::Configuration.new
-    my_config.access_token = "EAABs..." # Your specific access token
-    my_config.phone_number_id = "123456789"
-    my_config.verify_token = "my_verify_token"
-    my_config.app_id = "your_app_id"
-    my_config.app_secret = "your_app_secret"
-    my_config.business_account_id = "your_business_account_id"
-
-    processor = FlowChat::Whatsapp::Processor.new(self) do |config|
-      config.use_gateway FlowChat::Whatsapp::Gateway::CloudApi, my_config
-      config.use_session_store FlowChat::Session::CacheSessionStore
-    end
-
-    processor.run CustomFlow, :main_page
-  end
 end
 
-# Add routes for different tenants:
-# Rails.application.routes.draw do
-#   # Subdomain-based routing
-#   constraints subdomain: /\w+/ do
-#     post '/whatsapp/webhook', to: 'multi_tenant_whatsapp#webhook'
+# Add routes for the tenant endpoints, for example:
+#   Rails.application.routes.draw do
+#     constraints subdomain: /\w+/ do
+#       post "/whatsapp/webhook", to: "multi_tenant_whatsapp#webhook"
+#     end
+#     post "/whatsapp/:tenant/webhook", to: "multi_tenant_whatsapp#webhook"
 #   end
-#
-#   # Path-based routing
-#   post '/whatsapp/:tenant/webhook', to: 'multi_tenant_whatsapp#webhook'
-#
-#   # Environment-specific
-#   post '/whatsapp/env/webhook', to: 'environment_whatsapp#webhook'
-#
-#   # Custom endpoint
-#   post '/whatsapp/custom/webhook', to: 'custom_whatsapp#webhook'
-# end

data/examples/simulator_controller.rb

@@ -102,5 +102,4 @@ end
 # - Different API versions (v1, v2, etc.)
 # - Multi-tenant endpoints with different configurations
 # - Legacy endpoints alongside new ones
-# - External HTTP servers (run examples/http_simulator_test.rb)
 # - Different flow implementations for different endpoints

data/examples/ussd_controller.rb

@@ -5,49 +5,83 @@ class UssdController < ApplicationController
   skip_forgery_protection
 
   def process_request
-    processor = FlowChat::Ussd::Processor.new(self) do |config|
+    processor = FlowChat::Processor.new(self) do |config|
       config.use_gateway FlowChat::Ussd::Gateway::Nalo
-      # Use Rails session for USSD (shorter sessions)
-      config.use_session_store FlowChat::Session::RailsSessionStore
+      config.use_session_store FlowChat::Session::CacheSessionStore
+
+      # Durable sessions key on the phone number, so a conversation survives the
+      # telco rotating its session id on timeout. Optional.
+      config.use_durable_sessions
 
-      # Enable durable sessions (optional)
-      config.use_durable_sessions  # Configures flow+platform isolation with durable sessions
+      # Other options you can set here:
+      #
+      #   config.use_middleware LoggingMiddleware        # custom middleware (see below)
+      #   config.use_session_config(                     # explicit session boundaries
+      #     boundaries: [:flow, :platform],
+      #     hash_identifiers: true                       # hash phone numbers for privacy
+      #   )
     end
 
-    processor.run WelcomeFlow, :main_page
+    processor.run UssdWelcomeFlow, :main_page
+  end
+end
+
+# Add this route to your config/routes.rb:
+#   post "/ussd", to: "ussd#process_request"
+
+# Pagination is configured globally, not per processor. USSD messages are
+# length-limited, so long output is split into pages with navigation options:
+#
+#   FlowChat::Config.ussd.pagination_page_size = 120
+#   FlowChat::Config.ussd.pagination_next_option = "#"
+#   FlowChat::Config.ussd.pagination_back_option = "0"
+
+# A custom middleware, added above with config.use_middleware. It sees the
+# normalized context on the way in and the [type, prompt, choices, media] result
+# on the way out.
+class LoggingMiddleware
+  def initialize(app)
+    @app = app
+  end
+
+  def call(context)
+    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
 
-# Example Flow for USSD
-# Add this to your Rails application as app/flow_chat/welcome_flow.rb
+# Example flow for USSD
+# Add this to your Rails application as app/flow_chat/ussd_welcome_flow.rb
 
-class WelcomeFlow < FlowChat::Flow
+class UssdWelcomeFlow < FlowChat::Flow
   def main_page
-    # Welcome the user
     name = app.screen(:name) do |prompt|
       prompt.ask "Welcome! What's your name?",
         transform: ->(input) { input.strip.titleize }
     end
 
-    # Show main menu with numbered options (USSD style)
+    # Choices render as a numbered list; the flow works in the choice keys.
     choice = app.screen(:main_menu) do |prompt|
       prompt.select "Hi #{name}! Choose:", {
-        "1" => "Account Info",
-        "2" => "Make Payment",
-        "3" => "Get Balance",
-        "4" => "Support"
+        "info" => "Account Info",
+        "payment" => "Make Payment",
+        "balance" => "Get Balance",
+        "support" => "Support"
       }
     end
 
     case choice
-    when "1"
-      show_account_info
-    when "2"
-      make_payment
-    when "3"
-      get_balance
-    when "4"
-      customer_support
+    when "info" then show_account_info
+    when "payment" then make_payment
+    when "balance" then get_balance
+    when "support" then customer_support
     end
   end
 
@@ -56,21 +90,21 @@ class WelcomeFlow < FlowChat::Flow
   def show_account_info
     info_choice = app.screen(:account_info) do |prompt|
       prompt.select "Account Info:", {
-        "1" => "Personal Details",
-        "2" => "Balance",
-        "3" => "Transaction History",
-        "0" => "Main Menu"
+        "details" => "Personal Details",
+        "balance" => "Balance",
+        "history" => "Transaction History",
+        "back" => "Main Menu"
       }
     end
 
     case info_choice
-    when "1"
-      app.say "Name: John Doe\nPhone: #{app.phone_number}\nStatus: Active"
-    when "2"
+    when "details"
+      app.say "Name: John Doe\nPhone: #{app.msisdn}\nStatus: Active"
+    when "balance"
       app.say "Balance: $150.75\nCredit: $1,000.00"
-    when "3"
+    when "history"
       app.say "Recent:\n+$50.00 Deposit\n-$25.50 Purchase\n-$15.00 Transfer"
-    when "0"
+    when "back"
       main_page
     end
   end
@@ -79,9 +113,9 @@ class WelcomeFlow < FlowChat::Flow
     amount = app.screen(:payment_amount) do |prompt|
       prompt.ask "Enter amount:",
         validate: ->(input) {
-          amt = input.to_f
-          return "Invalid amount" unless amt > 0
-          return "Max $500" unless amt <= 500
+          amount = input.to_f
+          next "Invalid amount" unless amount > 0
+          next "Max $500" unless amount <= 500
           nil
         },
         transform: ->(input) { input.to_f }
@@ -89,19 +123,14 @@ class WelcomeFlow < FlowChat::Flow
 
     recipient = app.screen(:payment_recipient) do |prompt|
       prompt.ask "Recipient phone:",
-        validate: ->(input) {
-          return "10 digits required" unless input.match?(/\A\d{10}\z/)
-          nil
-        }
+        validate: ->(input) { "10 digits required" unless input.match?(/\A\d{10}\z/) }
     end
 
-    # Confirmation screen
     confirmed = app.screen(:payment_confirmation) do |prompt|
       prompt.yes? "Pay $#{amount} to #{recipient}?"
     end
 
     if confirmed
-      # Process payment (your business logic here)
       transaction_id = process_payment(amount, recipient)
       app.say "Payment successful!\nID: #{transaction_id}\nAmount: $#{amount}"
     else
@@ -110,26 +139,25 @@ class WelcomeFlow < FlowChat::Flow
   end
 
   def get_balance
-    # Simulate balance check
-    balance = check_account_balance(app.phone_number)
+    balance = check_account_balance(app.msisdn)
     app.say "Balance\n\nAvailable: $#{balance[:available]}\nPending: $#{balance[:pending]}"
   end
 
   def customer_support
     support_choice = app.screen(:support_menu) do |prompt|
       prompt.select "Support:", {
-        "1" => "Report Issue",
-        "2" => "Contact Info",
-        "0" => "Main Menu"
+        "report" => "Report Issue",
+        "contact" => "Contact Info",
+        "back" => "Main Menu"
       }
     end
 
     case support_choice
-    when "1"
+    when "report"
       report_issue
-    when "2"
+    when "contact"
       app.say "Support:\nCall: 123-456-7890\nEmail: support@company.com\nHours: 9AM-5PM"
-    when "0"
+    when "back"
       main_page
     end
   end
@@ -137,134 +165,34 @@ class WelcomeFlow < FlowChat::Flow
   def report_issue
     issue_type = app.screen(:issue_type) do |prompt|
       prompt.select "Issue type:", {
-        "1" => "Payment Problem",
-        "2" => "Account Access",
-        "3" => "Service Error",
-        "4" => "Other"
+        "payment" => "Payment Problem",
+        "access" => "Account Access",
+        "error" => "Service Error",
+        "other" => "Other"
       }
     end
 
     description = app.screen(:issue_description) do |prompt|
       prompt.ask "Describe issue:",
-        validate: ->(input) {
-          return "Min 10 characters" if input.length < 10
-          nil
-        }
+        validate: ->(input) { "Min 10 characters" if input.length < 10 }
     end
 
-    # Save the issue (your business logic here)
-    ticket_id = create_support_ticket(issue_type, description, app.phone_number)
-
+    ticket_id = create_support_ticket(issue_type, description, app.msisdn)
     app.say "Issue reported!\n\nTicket: #{ticket_id}\nWe'll contact you within 24hrs"
   end
 
-  # Helper methods (implement your business logic)
+  # Replace these with your own business logic.
 
   def process_payment(amount, recipient)
-    # Your payment processing logic here
-    # Return transaction ID
     "TXN#{rand(100000..999999)}"
   end
 
-  def check_account_balance(phone_number)
-    # Your balance checking logic here
-    {
-      available: "150.75",
-      pending: "25.00"
-    }
+  def check_account_balance(msisdn)
+    {available: "150.75", pending: "25.00"}
   end
 
-  def create_support_ticket(issue_type, description, phone_number)
-    # Your ticket creation logic here
-    Rails.logger.info "Ticket: #{issue_type} - #{description} from #{phone_number}"
+  def create_support_ticket(issue_type, description, msisdn)
+    Rails.logger.info "Ticket: #{issue_type} - #{description} from #{msisdn}"
     "TICKET#{rand(10000..99999)}"
   end
 end
-
-# Configuration Examples:
-
-# 1. Basic configuration with custom pagination
-# rubocop:disable Lint/DuplicateMethods
-class UssdController < ApplicationController
-  skip_forgery_protection
-
-  def process_request
-    # Configure pagination for shorter messages
-    FlowChat::Config.ussd.pagination_page_size = 120
-    FlowChat::Config.ussd.pagination_next_option = "#"
-    FlowChat::Config.ussd.pagination_back_option = "*"
-
-    processor = FlowChat::Ussd::Processor.new(self) do |config|
-      config.use_gateway FlowChat::Ussd::Gateway::Nalo
-      config.use_session_store FlowChat::Session::RailsSessionStore
-    end
-
-    processor.run WelcomeFlow, :main_page
-  end
-end
-# rubocop:enable Lint/DuplicateMethods
-
-# 2. Configuration with custom middleware
-class LoggingMiddleware
-  def initialize(app)
-    @app = app
-  end
-
-  def call(context)
-    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
-
-  def process_request
-    processor = FlowChat::Ussd::Processor.new(self) do |config|
-      config.use_gateway FlowChat::Ussd::Gateway::Nalo
-      config.use_session_store FlowChat::Session::RailsSessionStore
-      config.use_middleware LoggingMiddleware  # Add custom logging
-      config.use_durable_sessions           # Enable durable sessions
-      
-      # Or configure session boundaries explicitly:
-      # config.use_session_config(
-      #   boundaries: [:flow, :platform],     # which boundaries to enforce
-      #   hash_identifiers: true            # hash phone numbers for privacy
-      # )
-    end
-
-    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
-
-  def process_request
-    processor = FlowChat::Ussd::Processor.new(self) do |config|
-      config.use_gateway FlowChat::Ussd::Gateway::Nalo
-      # Use cache store for longer session persistence
-      config.use_session_store FlowChat::Session::CacheSessionStore
-    end
-
-    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