flow_chat 0.3.0 → 0.4.1

data/examples/initializer.rb

@@ -0,0 +1,31 @@
+# Example FlowChat Initializer
+# Add this to your Rails application as config/initializers/flow_chat.rb
+
+# Configure cache for session storage
+# This is required when using FlowChat::Session::CacheSessionStore
+FlowChat::Config.cache = Rails.cache
+
+# Alternative cache configurations:
+
+# Use a specific cache store
+# FlowChat::Config.cache = ActiveSupport::Cache::MemoryStore.new
+
+# Use Redis (requires redis gem)
+# FlowChat::Config.cache = ActiveSupport::Cache::RedisCacheStore.new(url: "redis://localhost:6379/1")
+
+# Use Memcached (requires dalli gem)
+# FlowChat::Config.cache = ActiveSupport::Cache::MemCacheStore.new("localhost:11211")
+
+# Configure logger (optional)
+FlowChat::Config.logger = Rails.logger
+
+# Configure USSD pagination (optional)
+FlowChat::Config.ussd.pagination_page_size = 140
+FlowChat::Config.ussd.pagination_back_option = "0"
+FlowChat::Config.ussd.pagination_back_text = "Back"
+FlowChat::Config.ussd.pagination_next_option = "#"
+FlowChat::Config.ussd.pagination_next_text = "More"
+
+# Configure resumable sessions (optional)
+FlowChat::Config.ussd.resumable_sessions_enabled = true
+FlowChat::Config.ussd.resumable_sessions_timeout_seconds = 300 # 5 minutes 

data/examples/media_prompts_examples.rb

@@ -0,0 +1,28 @@
+# Media Prompts Examples
+# This file demonstrates how to attach media to prompts in FlowChat
+
+# ============================================================================
+# BASIC MEDIA PROMPTS
+# ============================================================================
+
+class MediaPromptFlow < FlowChat::Flow
+  def main_page
+    # ✅ Simple text input with attached image
+    # The prompt text becomes the image caption
+    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 media message with say
+    app.say "Thank you for your feedback! Here's what's coming next:",
+      media: {
+        type: :video,
+        url: "https://videos.example.com/roadmap.mp4"
+      }
+  end
+end
+

data/examples/multi_tenant_whatsapp_controller.rb

@@ -0,0 +1,244 @@
+# Example Multi-Tenant WhatsApp Controller
+# This shows how to configure different WhatsApp accounts per tenant/client
+
+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)
+    
+    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
+
+    # Use tenant-specific flow
+    flow_class = get_flow_for_tenant(tenant)
+    processor.run flow_class, :main_page
+  end
+
+  private
+
+  def determine_tenant(request)
+    # Option 1: From subdomain
+    return request.subdomain if request.subdomain.present?
+    
+    # Option 2: From path
+    tenant_from_path = request.path.match(%r{^/whatsapp/(\w+)/})&.captures&.first
+    return tenant_from_path if tenant_from_path
+    
+    # Option 3: From custom header
+    return request.headers['X-Tenant-ID'] if request.headers['X-Tenant-ID']
+    
+    # Fallback to default
+    'default'
+  end
+
+  def get_whatsapp_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_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'
+      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_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'
+      # 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_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
+
+  def get_flow_for_tenant(tenant)
+    case tenant
+    when 'acme_corp'
+      AcmeCorpFlow
+    when 'tech_startup'
+      TechStartupFlow
+    when 'retail_store'
+      RetailStoreFlow
+    else
+      WelcomeFlow  # Default flow
+    end
+  end
+end
+
+# Example: Dynamic Configuration from Database
+class DatabaseWhatsappController < ApplicationController
+  skip_forgery_protection
+
+  def webhook
+    # Get account from business phone number or other identifier
+    business_account = find_business_account(params)
+    
+    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|
+      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
+  end
+
+  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
+    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
+  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'
+#   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/ussd_controller.rb

@@ -0,0 +1,264 @@
+# Example USSD Controller
+# Add this to your Rails application as app/controllers/ussd_controller.rb
+
+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 Rails session for USSD (shorter sessions)
+      config.use_session_store FlowChat::Session::RailsSessionStore
+      
+      # Enable resumable sessions (optional)
+      config.use_resumable_sessions
+    end
+
+    processor.run WelcomeFlow, :main_page
+  end
+end
+
+# Example Flow for USSD
+# Add this to your Rails application as app/flow_chat/welcome_flow.rb
+
+class WelcomeFlow < FlowChat::Flow
+  def main_page
+    # Welcome the user
+    name = app.screen(:name) do |prompt|
+      prompt.ask "Welcome to our service! What's your name?",
+        transform: ->(input) { input.strip.titleize }
+    end
+
+    # Show main menu with numbered options (USSD style)
+    choice = app.screen(:main_menu) do |prompt|
+      prompt.select "Hi #{name}! Choose an option:", {
+        "1" => "Account Info",
+        "2" => "Make Payment", 
+        "3" => "Get Balance",
+        "4" => "Customer Support"
+      }
+    end
+
+    case choice
+    when "1"
+      show_account_info
+    when "2"
+      make_payment
+    when "3"
+      get_balance
+    when "4"
+      customer_support
+    end
+  end
+
+  private
+
+  def show_account_info
+    info_choice = app.screen(:account_info) do |prompt|
+      prompt.select "Account Information:", {
+        "1" => "Personal Details",
+        "2" => "Account Balance",
+        "3" => "Transaction History",
+        "0" => "Back to Main Menu"
+      }
+    end
+
+    case info_choice
+    when "1"
+      app.say "Name: John Doe\\nPhone: #{app.phone_number}\\nAccount: Active"
+    when "2"
+      app.say "Current Balance: $150.75\\nAvailable Credit: $1,000.00"
+    when "3"
+      app.say "Last 3 Transactions:\\n1. +$50.00 - Deposit\\n2. -$25.50 - Purchase\\n3. -$15.00 - Transfer"
+    when "0"
+      main_page  # Go back to main menu
+    end
+  end
+
+  def make_payment
+    amount = app.screen(:payment_amount) do |prompt|
+      prompt.ask "Enter amount to pay:",
+        convert: ->(input) { input.to_f },
+        validate: ->(amount) {
+          return "Amount must be greater than 0" unless amount > 0
+          return "Maximum payment is $500" unless amount <= 500
+          nil
+        }
+    end
+
+    recipient = app.screen(:payment_recipient) do |prompt|
+      prompt.ask "Enter recipient phone number:",
+        validate: ->(input) {
+          return "Phone number must be 10 digits" unless input.match?(/\\A\\d{10}\\z/)
+          nil
+        }
+    end
+
+    # Confirmation screen
+    confirmed = app.screen(:payment_confirmation) do |prompt|
+      prompt.yes? "Pay $#{amount} to #{recipient}?\\nConfirm payment?"
+    end
+
+    if confirmed
+      # Process payment (your business logic here)
+      transaction_id = process_payment(amount, recipient)
+      app.say "Payment successful!\\nTransaction ID: #{transaction_id}\\nAmount: $#{amount}\\nTo: #{recipient}"
+    else
+      app.say "Payment cancelled"
+    end
+  end
+
+  def get_balance
+    # Simulate balance check
+    balance = check_account_balance(app.phone_number)
+    app.say "Account Balance\\n\\nAvailable: $#{balance[:available]}\\nPending: $#{balance[:pending]}\\nTotal: $#{balance[:total]}"
+  end
+
+  def customer_support
+    support_choice = app.screen(:support_menu) do |prompt|
+      prompt.select "Customer Support:", {
+        "1" => "Report an Issue",
+        "2" => "Account Questions", 
+        "3" => "Technical Support",
+        "4" => "Speak to Agent",
+        "0" => "Main Menu"
+      }
+    end
+
+    case support_choice
+    when "1"
+      report_issue
+    when "2"
+      app.say "For account questions:\\nCall: 123-456-7890\\nEmail: support@company.com\\nHours: 9AM-5PM Mon-Fri"
+    when "3"
+      app.say "Technical Support:\\nCall: 123-456-7891\\nEmail: tech@company.com\\n24/7 Support Available"
+    when "4"
+      app.say "Connecting you to an agent...\\nPlease call 123-456-7890\\nOr visit our nearest branch"
+    when "0"
+      main_page
+    end
+  end
+
+  def report_issue
+    issue_type = app.screen(:issue_type) do |prompt|
+      prompt.select "Select issue type:", {
+        "1" => "Payment Problem",
+        "2" => "Account Access",
+        "3" => "Service Error",
+        "4" => "Other"
+      }
+    end
+
+    description = app.screen(:issue_description) do |prompt|
+      prompt.ask "Briefly describe the issue:",
+        validate: ->(input) {
+          return "Description must be at least 10 characters" unless input.length >= 10
+          nil
+        }
+    end
+
+    # 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
+    "TXN#{rand(100000..999999)}"
+  end
+
+  def check_account_balance(phone_number)
+    # Your balance checking logic here
+    {
+      available: "150.75",
+      pending: "25.00", 
+      total: "175.75"
+    }
+  end
+
+  def create_support_ticket(issue_type, description, phone_number)
+    # Your ticket creation logic here
+    Rails.logger.info "Support ticket created: #{issue_type} - #{description} from #{phone_number}"
+    "TICKET#{rand(10000..99999)}"
+  end
+end
+
+# Configuration Examples:
+
+# 1. Basic configuration with custom pagination
+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
+
+# 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
+
+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_resumable_sessions           # Enable resumable sessions
+    end
+
+    processor.run WelcomeFlow, :main_page
+  end
+end
+
+# 3. Configuration with cache-based sessions for longer persistence
+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
+
+# 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