flow_chat 0.3.0 → 0.4.0

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 

data/examples/whatsapp_controller.rb

@@ -0,0 +1,141 @@
+# Example WhatsApp Controller
+# Add this to your Rails application as 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
+      # Use cache-based session store for longer WhatsApp conversations
+      config.use_session_store FlowChat::Session::CacheSessionStore
+    end
+
+    processor.run WelcomeFlow, :main_page
+  end
+end
+
+# Example with Custom Configuration
+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|
+      config.use_whatsapp_config(custom_config)  # Use custom config
+      config.use_gateway FlowChat::Whatsapp::Gateway::CloudApi
+      config.use_session_store FlowChat::Session::CacheSessionStore
+    end
+
+    processor.run WelcomeFlow, :main_page
+  end
+end
+
+# Example Flow for WhatsApp
+# 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 "Hello! Welcome to our WhatsApp service. What's your name?",
+        transform: ->(input) { input.strip.titleize }
+    end
+
+    # Show main menu
+    choice = app.screen(:main_menu) do |prompt|
+      prompt.select "Hi #{name}! What can I help you with today?", {
+        "info" => "📋 Get Information",
+        "support" => "🆘 Contact Support", 
+        "feedback" => "💬 Give Feedback"
+      }
+    end
+
+    case choice
+    when "info"
+      show_information_menu
+    when "support"
+      contact_support
+    when "feedback"
+      collect_feedback
+    end
+  end
+
+  private
+
+  def show_information_menu
+    info_choice = app.screen(:info_menu) do |prompt|
+      prompt.select "What information do you need?", {
+        "hours" => "🕒 Business Hours",
+        "location" => "📍 Our Location",
+        "services" => "🛠 Our Services"
+      }
+    end
+
+    case info_choice
+    when "hours"
+      app.say "We're open Monday-Friday 9AM-6PM, Saturday 9AM-2PM. Closed Sundays."
+    when "location"
+      app.say "📍 We're located at 123 Main Street, City, State 12345"
+    when "services"
+      app.say "Here are our main services:\\n\\n🌐 Web Development - Custom websites and applications\\n📱 Mobile Apps - iOS and Android development\\n🔧 Consulting - Technical consulting services"
+    end
+  end
+
+  def contact_support
+    # Use standard select menu instead of send_buttons
+    contact_method = app.screen(:contact_method) do |prompt|
+      prompt.select "How would you like to contact support?", {
+        "call" => "📞 Call Us",
+        "email" => "📧 Email Us", 
+        "chat" => "💬 Live Chat"
+      }
+    end
+
+    case contact_method
+    when "call"
+      app.say "📞 You can call us at (555) 123-4567"
+    when "email"
+      app.say "📧 Send us an email at support@example.com"
+    when "chat"
+      app.say "💬 Our live chat is available on our website: www.example.com"
+    end
+  end
+
+  def collect_feedback
+    rating = app.screen(:rating) do |prompt|
+      prompt.select "How would you rate our service?", {
+        "5" => "⭐⭐⭐⭐⭐ Excellent",
+        "4" => "⭐⭐⭐⭐ Good", 
+        "3" => "⭐⭐⭐ Average",
+        "2" => "⭐⭐ Poor",
+        "1" => "⭐ Very Poor"
+      }
+    end
+
+    feedback = app.screen(:feedback_text) do |prompt|
+      prompt.ask "Thank you for the #{rating}-star rating! Please share any additional feedback:"
+    end
+
+    # Save feedback (implement your logic here)
+    save_feedback(app.phone_number, rating, feedback)
+
+    app.say "Thank you for your feedback! We really appreciate it. 🙏"
+  end
+
+  def save_feedback(phone, rating, feedback)
+    # Implement your feedback saving logic here
+    Rails.logger.info "Feedback from #{phone}: #{rating} stars - #{feedback}"
+  end
+end
+
+# Add this route to your config/routes.rb:
+# post '/whatsapp/webhook', to: 'whatsapp#webhook' 

data/lib/flow_chat/base_processor.rb

@@ -0,0 +1,63 @@
+require "middleware"
+
+module FlowChat
+  class BaseProcessor
+    attr_reader :middleware, :gateway
+
+    def initialize(controller)
+      @context = FlowChat::Context.new
+      @context["controller"] = controller
+      @middleware = ::Middleware::Builder.new(name: middleware_name)
+
+      yield self if block_given?
+    end
+
+    def use_gateway(gateway)
+      @gateway = gateway
+      self
+    end
+
+    def use_session_store(session_store)
+      @context["session.store"] = session_store
+      self
+    end
+
+    def use_middleware(middleware)
+      @middleware.use middleware
+      self
+    end
+
+    def run(flow_class, action)
+      @context["flow.name"] = flow_class.name.underscore
+      @context["flow.class"] = flow_class
+      @context["flow.action"] = action
+
+      stack = build_middleware_stack
+      yield stack if block_given?
+
+      stack.call(@context)
+    end
+
+    protected
+
+    # Subclasses should override these methods
+    def middleware_name
+      raise NotImplementedError, "Subclasses must implement middleware_name"
+    end
+
+    def build_middleware_stack
+      raise NotImplementedError, "Subclasses must implement build_middleware_stack"
+    end
+
+    # Helper method for building stacks
+    def create_middleware_stack(name)
+      ::Middleware::Builder.new(name: name) do |b|
+        configure_middleware_stack(b)
+      end.inject_logger(Rails.logger)
+    end
+
+    def configure_middleware_stack(builder)
+      raise NotImplementedError, "Subclasses must implement configure_middleware_stack"
+    end
+  end
+end 

data/lib/flow_chat/session/cache_session_store.rb

@@ -0,0 +1,84 @@
+module FlowChat
+  module Session
+    class CacheSessionStore
+      def initialize(context, cache = nil)
+        @context = context
+        @cache = cache || FlowChat::Config.cache
+        
+        raise ArgumentError, "Cache is required. Set FlowChat::Config.cache or pass a cache instance." unless @cache
+      end
+
+      def get(key)
+        return nil unless @context
+
+        data = @cache.read(session_key)
+        return nil unless data
+
+        data[key.to_s]
+      end
+
+      def set(key, value)
+        return unless @context
+
+        data = @cache.read(session_key) || {}
+        data[key.to_s] = value
+        
+        @cache.write(session_key, data, expires_in: session_ttl)
+        value
+      end
+
+      def delete(key)
+        return unless @context
+
+        data = @cache.read(session_key)
+        return unless data
+
+        data.delete(key.to_s)
+        @cache.write(session_key, data, expires_in: session_ttl)
+      end
+
+      def clear
+        return unless @context
+
+        @cache.delete(session_key)
+      end
+
+      # Alias for compatibility
+      alias_method :destroy, :clear
+
+      def exists?
+        @cache.exist?(session_key)
+      end
+
+      private
+
+      def session_key
+        gateway = @context["request.gateway"]
+        msisdn = @context["request.msisdn"]
+        
+        case gateway
+        when :whatsapp_cloud_api
+          "flow_chat:session:whatsapp:#{msisdn}"
+        when :nalo, :nsano
+          session_id = @context["request.id"]
+          "flow_chat:session:ussd:#{session_id}:#{msisdn}"
+        else
+          "flow_chat:session:unknown:#{msisdn}"
+        end
+      end
+
+      def session_ttl
+        gateway = @context["request.gateway"]
+        
+        case gateway
+        when :whatsapp_cloud_api
+          7.days  # WhatsApp conversations can be long-lived
+        when :nalo, :nsano
+          1.hour  # USSD sessions are typically short
+        else
+          1.day   # Default
+        end
+      end
+    end
+  end
+end 

data/lib/flow_chat/session/middleware.rb

@@ -14,12 +14,20 @@ module FlowChat
       private
 
       def session_id(context)
-        context["request.id"]
-        # File.join(
-        #   context["PATH_INFO"],
-        #   (Config.resumable_sessions_enabled && Config.resumable_sessions_global) ? "global" : context["ussd.request"][:provider].to_s,
-        #   context["ussd.request"][:msisdn]
-        # )
+        gateway = context["request.gateway"]
+        flow_name = context["flow.name"]
+        case gateway
+        when :whatsapp_cloud_api
+          # For WhatsApp, use phone number + flow name for consistent sessions
+          phone = context["request.msisdn"]
+          "#{gateway}:#{flow_name}:#{phone}"
+        # when :nalo, :nsano
+        #   # For USSD, use the request ID from the gateway
+        #   "#{gateway}:#{flow_name}:#{context["request.id"]}"
+        else
+          # Fallback to request ID
+          "#{gateway}:#{flow_name}:#{context["request.id"]}"
+        end
       end
     end
   end

data/lib/flow_chat/ussd/app.rb

@@ -28,6 +28,31 @@ module FlowChat
       def say(msg)
         raise FlowChat::Interrupt::Terminate.new(msg)
       end
+
+      # WhatsApp-specific data accessors (not supported in USSD)
+      def contact_name
+        nil
+      end
+
+      def message_id
+        context["request.message_id"]
+      end
+
+      def timestamp
+        context["request.timestamp"]
+      end
+
+      def location
+        nil
+      end
+
+      def media
+        nil
+      end
+
+      def phone_number
+        context["request.msisdn"]
+      end
     end
   end
 end

data/lib/flow_chat/ussd/gateway/nalo.rb

@@ -12,6 +12,8 @@ module FlowChat
           params = context.controller.request.params
 
           context["request.id"] = params["USERID"]
+          context["request.message_id"] = SecureRandom.uuid
+          context["request.timestamp"] = Time.current.iso8601
           context["request.gateway"] = :nalo
           context["request.network"] = nil
           context["request.msisdn"] = Phonelib.parse(params["MSISDN"]).e164

data/lib/flow_chat/ussd/gateway/nsano.rb

@@ -12,6 +12,12 @@ module FlowChat
           controller = context["controller"]
           controller.request
 
+          # Add timestamp for all requests
+          context["request.timestamp"] = Time.current.iso8601
+          
+          # Set a basic message_id (can be enhanced based on actual Nsano implementation)
+          context["request.message_id"] = SecureRandom.uuid
+
           # input = context["rack.input"].read
           # context["rack.input"].rewind
           # if input.present?

data/lib/flow_chat/ussd/middleware/resumable_session.rb

@@ -29,7 +29,7 @@ module FlowChat
           return true unless FlowChat::Config.ussd.resumable_sessions_timeout_seconds
 
           last_active_at = Time.parse session.dig("context", "last_active_at")
-          (Time.now - FlowChat::Config.ussd.resumable_sessions_timeout_seconds) < last_active_at
+          (Time.current - FlowChat::Config.ussd.resumable_sessions_timeout_seconds) < last_active_at
         rescue
           false
         end