flow_chat 0.3.0 → 0.4.0

data/lib/flow_chat/ussd/processor.rb

@@ -1,55 +1,28 @@
-require "middleware"
-
 module FlowChat
   module Ussd
-    class Processor
-      attr_reader :middleware, :gateway
-
-      def initialize(controller)
-        @context = FlowChat::Context.new
-        @context["controller"] = controller
-        @middleware = ::Middleware::Builder.new(name: "ussd.middleware")
-
-        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
-
+    class Processor < FlowChat::BaseProcessor
       def use_resumable_sessions
         middleware.insert_before 0, FlowChat::Ussd::Middleware::ResumableSession
         self
       end
 
-      def run(flow_class, action)
-        @context["flow.name"] = flow_class.name.underscore
-        @context["flow.class"] = flow_class
-        @context["flow.action"] = action
+      protected
 
-        stack = ::Middleware::Builder.new name: "ussd" do |b|
-          b.use gateway
-          b.use FlowChat::Session::Middleware
-          b.use FlowChat::Ussd::Middleware::Pagination
-          b.use middleware
-          b.use FlowChat::Ussd::Middleware::Executor
-        end.inject_logger(Rails.logger)
+      def middleware_name
+        "ussd.middleware"
+      end
 
-        yield stack if block_given?
+      def build_middleware_stack
+        create_middleware_stack("ussd")
+      end
 
-        stack.call(@context)
+      def configure_middleware_stack(builder)
+        builder.use gateway
+        builder.use FlowChat::Session::Middleware
+        builder.use FlowChat::Ussd::Middleware::Pagination
+        builder.use middleware
+        builder.use FlowChat::Ussd::Middleware::Executor
       end
     end
   end
-end
+end 

data/lib/flow_chat/version.rb

@@ -1,3 +1,3 @@
 module FlowChat
-  VERSION = "0.3.0"
+  VERSION = "0.4.0"
 end

data/lib/flow_chat/whatsapp/app.rb

@@ -0,0 +1,58 @@
+module FlowChat
+  module Whatsapp
+    class App
+      attr_reader :session, :input, :context, :navigation_stack
+
+      def initialize(context)
+        @context = context
+        @session = context.session
+        @input = context.input
+        @navigation_stack = []
+      end
+
+      def screen(key)
+        raise ArgumentError, "a block is expected" unless block_given?
+        raise ArgumentError, "screen has been presented" if navigation_stack.include?(key)
+
+        navigation_stack << key
+        return session.get(key) if session.get(key).present?
+
+        prompt = FlowChat::Whatsapp::Prompt.new input
+        @input = nil # input is being submitted to prompt so we clear it
+
+        value = yield prompt
+        session.set(key, value)
+        value
+      end
+
+      def say(msg)
+        raise FlowChat::Interrupt::Terminate.new([:text, msg, {}])
+      end
+
+      # WhatsApp-specific data accessors (read-only)
+      def contact_name
+        context["request.contact_name"]
+      end
+
+      def message_id
+        context["request.message_id"]
+      end
+
+      def timestamp
+        context["request.timestamp"]
+      end
+
+      def location
+        context["request.location"]
+      end
+
+      def media
+        context["request.media"]
+      end
+
+      def phone_number
+        context["request.msisdn"]
+      end
+    end
+  end
+end 

data/lib/flow_chat/whatsapp/configuration.rb

@@ -0,0 +1,75 @@
+module FlowChat
+  module Whatsapp
+    class Configuration
+      attr_accessor :access_token, :phone_number_id, :verify_token, :app_id, :app_secret,
+                    :webhook_url, :webhook_verify_token, :business_account_id
+
+      def initialize
+        @access_token = nil
+        @phone_number_id = nil
+        @verify_token = nil
+        @app_id = nil
+        @app_secret = nil
+        @webhook_url = nil
+        @webhook_verify_token = nil
+        @business_account_id = nil
+      end
+
+      # Load configuration from Rails credentials or environment variables
+      def self.from_credentials
+        config = new
+        
+        if defined?(Rails) && Rails.application.credentials.whatsapp
+          credentials = Rails.application.credentials.whatsapp
+          config.access_token = credentials[:access_token]
+          config.phone_number_id = credentials[:phone_number_id]
+          config.verify_token = credentials[:verify_token]
+          config.app_id = credentials[:app_id]
+          config.app_secret = credentials[:app_secret]
+          config.webhook_url = credentials[:webhook_url]
+          config.business_account_id = credentials[:business_account_id]
+        else
+          # Fallback to environment variables
+          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']
+          config.webhook_url = ENV['WHATSAPP_WEBHOOK_URL']
+          config.business_account_id = ENV['WHATSAPP_BUSINESS_ACCOUNT_ID']
+        end
+
+        config
+      end
+
+      def valid?
+        access_token.present? && phone_number_id.present? && verify_token.present?
+      end
+
+      def webhook_configured?
+        webhook_url.present? && verify_token.present?
+      end
+
+      # API endpoints
+      def messages_url
+        "https://graph.facebook.com/v18.0/#{phone_number_id}/messages"
+      end
+
+      def media_url(media_id)
+        "https://graph.facebook.com/v18.0/#{media_id}"
+      end
+
+      def phone_numbers_url
+        "https://graph.facebook.com/v18.0/#{business_account_id}/phone_numbers"
+      end
+
+      # Headers for API requests
+      def api_headers
+        {
+          "Authorization" => "Bearer #{access_token}",
+          "Content-Type" => "application/json"
+        }
+      end
+    end
+  end
+end 

data/lib/flow_chat/whatsapp/gateway/cloud_api.rb

@@ -0,0 +1,213 @@
+require "net/http"
+require "json"
+require "phonelib"
+
+module FlowChat
+  module Whatsapp
+    module Gateway
+      class CloudApi
+        WHATSAPP_API_URL = "https://graph.facebook.com/v18.0"
+
+        def initialize(app, config = nil)
+          @app = app
+          @config = config || FlowChat::Whatsapp::Configuration.from_credentials
+        end
+
+        def call(context)
+          controller = context.controller
+          request = controller.request
+
+          # Handle webhook verification
+          if request.get? && request.params["hub.mode"] == "subscribe"
+            return handle_verification(context)
+          end
+
+          # Handle webhook messages
+          if request.post?
+            return handle_webhook(context)
+          end
+
+          controller.head :bad_request
+        end
+
+        private
+
+        def handle_verification(context)
+          controller = context.controller
+          params = controller.request.params
+
+          verify_token = @config.verify_token
+          
+          if params["hub.verify_token"] == verify_token
+            controller.render plain: params["hub.challenge"]
+          else
+            controller.head :forbidden
+          end
+        end
+
+        def handle_webhook(context)
+          controller = context.controller
+          body = JSON.parse(controller.request.body.read)
+
+          # Extract message data from WhatsApp webhook
+          entry = body.dig("entry", 0)
+          return controller.head :ok unless entry
+
+          changes = entry.dig("changes", 0)
+          return controller.head :ok unless changes
+
+          value = changes["value"]
+          return controller.head :ok unless value
+
+          # Handle incoming messages
+          if value["messages"]&.any?
+            message = value["messages"].first
+            contact = value["contacts"]&.first
+
+            context["request.id"] = message["from"]
+            context["request.gateway"] = :whatsapp_cloud_api
+            context["request.message_id"] = message["id"]
+            context["request.msisdn"] = Phonelib.parse(message["from"]).e164
+            context["request.contact_name"] = contact&.dig("profile", "name")
+            context["request.timestamp"] = message["timestamp"]
+
+            # Extract message content based on type
+            case message["type"]
+            when "text"
+              context.input = message.dig("text", "body")
+            when "interactive"
+              # Handle button/list replies
+              if message.dig("interactive", "type") == "button_reply"
+                context.input = message.dig("interactive", "button_reply", "id")
+              elsif message.dig("interactive", "type") == "list_reply"
+                context.input = message.dig("interactive", "list_reply", "id")
+              end
+            when "location"
+              context["request.location"] = {
+                latitude: message.dig("location", "latitude"),
+                longitude: message.dig("location", "longitude"),
+                name: message.dig("location", "name"),
+                address: message.dig("location", "address")
+              }
+              # Set input so screen can proceed
+              context.input = "$location$"
+            when "image", "document", "audio", "video"
+              context["request.media"] = {
+                type: message["type"],
+                id: message.dig(message["type"], "id"),
+                mime_type: message.dig(message["type"], "mime_type"),
+                caption: message.dig(message["type"], "caption")
+              }
+              # Set input so screen can proceed
+              context.input = "$media$"
+            end
+
+            response = @app.call(context)
+            send_whatsapp_message(context, response)
+          end
+
+          # Handle message status updates
+          if value["statuses"]&.any?
+            # Log status updates but don't process them
+            Rails.logger.info "WhatsApp status update: #{value["statuses"]}"
+          end
+
+          controller.head :ok
+        end
+
+        def send_whatsapp_message(context, response)
+          return unless response
+
+          phone_number_id = @config.phone_number_id
+          access_token = @config.access_token
+          to = context["request.msisdn"]
+
+          message_data = build_message_payload(response, to)
+
+          uri = URI("#{WHATSAPP_API_URL}/#{phone_number_id}/messages")
+          http = Net::HTTP.new(uri.host, uri.port)
+          http.use_ssl = true
+
+          request = Net::HTTP::Post.new(uri)
+          request["Authorization"] = "Bearer #{access_token}"
+          request["Content-Type"] = "application/json"
+          request.body = message_data.to_json
+
+          response = http.request(request)
+          
+          unless response.is_a?(Net::HTTPSuccess)
+            Rails.logger.error "WhatsApp API error: #{response.body}"
+          end
+        end
+
+        def build_message_payload(response, to)
+          type, content, options = response
+
+          case type
+          when :text
+            {
+              messaging_product: "whatsapp",
+              to: to,
+              type: "text",
+              text: { body: content }
+            }
+          when :interactive_buttons
+            {
+              messaging_product: "whatsapp",
+              to: to,
+              type: "interactive",
+              interactive: {
+                type: "button",
+                body: { text: content },
+                action: {
+                  buttons: options[:buttons].map.with_index do |button, index|
+                    {
+                      type: "reply",
+                      reply: {
+                        id: button[:id] || index.to_s,
+                        title: button[:title]
+                      }
+                    }
+                  end
+                }
+              }
+            }
+          when :interactive_list
+            {
+              messaging_product: "whatsapp",
+              to: to,
+              type: "interactive",
+              interactive: {
+                type: "list",
+                body: { text: content },
+                action: {
+                  button: options[:button_text] || "Choose",
+                  sections: options[:sections]
+                }
+              }
+            }
+          when :template
+            {
+              messaging_product: "whatsapp",
+              to: to,
+              type: "template",
+              template: {
+                name: options[:template_name],
+                language: { code: options[:language] || "en_US" },
+                components: options[:components] || []
+              }
+            }
+          else
+            # Default to text message
+            {
+              messaging_product: "whatsapp",
+              to: to,
+              type: "text",
+              text: { body: content.to_s }
+            }
+          end
+        end
+      end
+    end
+  end
+end 

data/lib/flow_chat/whatsapp/middleware/executor.rb

@@ -0,0 +1,30 @@
+module FlowChat
+  module Whatsapp
+    module Middleware
+      class Executor
+        def initialize(app)
+          @app = app
+        end
+
+        def call(context)
+          whatsapp_app = build_whatsapp_app context
+          flow = context.flow.new whatsapp_app
+          flow.send context["flow.action"]
+        rescue FlowChat::Interrupt::Prompt => e
+          # Return the interrupt data for WhatsApp message formatting
+          e.prompt
+        rescue FlowChat::Interrupt::Terminate => e
+          # Clean up session and return terminal message
+          context.session.destroy
+          e.prompt
+        end
+
+        private
+
+        def build_whatsapp_app(context)
+          FlowChat::Whatsapp::App.new(context)
+        end
+      end
+    end
+  end
+end 

data/lib/flow_chat/whatsapp/processor.rb

@@ -0,0 +1,36 @@
+module FlowChat
+  module Whatsapp
+    class Processor < FlowChat::BaseProcessor
+      def use_whatsapp_config(config)
+        @whatsapp_config = config
+        self
+      end
+
+      def use_gateway(gateway_class)
+        if gateway_class == FlowChat::Whatsapp::Gateway::CloudApi
+          @gateway = @whatsapp_config ? gateway_class.new(nil, @whatsapp_config) : gateway_class.new(nil)
+        else
+          @gateway = gateway_class.new(nil)
+        end
+        self
+      end
+
+      protected
+
+      def middleware_name
+        "whatsapp.middleware"
+      end
+
+      def build_middleware_stack
+        create_middleware_stack("whatsapp")
+      end
+
+      def configure_middleware_stack(builder)
+        builder.use gateway
+        builder.use FlowChat::Session::Middleware
+        builder.use middleware
+        builder.use FlowChat::Whatsapp::Middleware::Executor
+      end
+    end
+  end
+end 

data/lib/flow_chat/whatsapp/prompt.rb

@@ -0,0 +1,206 @@
+module FlowChat
+  module Whatsapp
+    class Prompt
+      attr_reader :input
+
+      def initialize(input)
+        @input = input
+      end
+
+      def ask(message, transform: nil, validate: nil, convert: nil)
+        if input.present?
+          processed_input = process_input(input, transform, validate, convert)
+          return processed_input unless processed_input.nil?
+        end
+
+        # Send message and wait for response
+        raise FlowChat::Interrupt::Prompt.new([:text, message, {}])
+      end
+
+      def select(message, choices, transform: nil, validate: nil, convert: nil)
+        if input.present?
+          processed_input = process_selection(input, choices, transform, validate, convert)
+          return processed_input unless processed_input.nil?
+        end
+
+        # Validate choices
+        validate_choices(choices)
+
+        # Determine the best way to present choices
+        if choices.is_a?(Array)
+          # Convert array to hash with index-based keys
+          choice_hash = choices.each_with_index.to_h { |choice, index| [index.to_s, choice] }
+          present_choices_as_list(message, choice_hash)
+        elsif choices.is_a?(Hash)
+          if choices.length <= 3
+            # Use buttons for 3 or fewer choices
+            present_choices_as_buttons(message, choices)
+          else
+            # Use list for more than 3 choices
+            present_choices_as_list(message, choices)
+          end
+        else
+          raise ArgumentError, "choices must be an Array or Hash"
+        end
+      end
+
+      def yes?(message, transform: nil, validate: nil, convert: nil)
+        if input.present?
+          processed_input = process_boolean(input, transform, validate, convert)
+          return processed_input unless processed_input.nil?
+        end
+
+        buttons = [
+          { id: "yes", title: "Yes" },
+          { id: "no", title: "No" }
+        ]
+
+        raise FlowChat::Interrupt::Prompt.new([:interactive_buttons, message, { buttons: buttons }])
+      end
+
+      private
+
+      def process_input(input, transform, validate, convert)
+        # Apply transformation
+        transformed_input = transform ? transform.call(input) : input
+
+        # Apply conversion first, then validation
+        converted_input = convert ? convert.call(transformed_input) : transformed_input
+
+        # Apply validation on converted value
+        if validate
+          error_message = validate.call(converted_input)
+          if error_message
+            raise FlowChat::Interrupt::Prompt.new([:text, error_message, {}])
+          end
+        end
+
+        converted_input
+      end
+
+      def process_selection(input, choices, transform, validate, convert)
+        choice_hash = choices.is_a?(Array) ? 
+          choices.each_with_index.to_h { |choice, index| [index.to_s, choice] } : 
+          choices
+
+        # Check if input matches a valid choice
+        if choice_hash.key?(input)
+          selected_value = choice_hash[input]
+          process_input(selected_value, transform, validate, convert)
+        elsif choice_hash.value?(input)
+          # Input matches a choice value directly
+          process_input(input, transform, validate, convert)
+        else
+          # Invalid choice
+          choice_list = choice_hash.map { |key, value| "#{key}: #{value}" }.join("\n")
+          error_message = "Invalid choice. Please select one of:\n#{choice_list}"
+          raise FlowChat::Interrupt::Prompt.new([:text, error_message, {}])
+        end
+      end
+
+      def process_boolean(input, transform, validate, convert)
+        boolean_value = case input.to_s.downcase
+                       when "yes", "y", "1", "true"
+                         true
+                       when "no", "n", "0", "false"
+                         false
+                       else
+                         nil
+                       end
+
+        if boolean_value.nil?
+          raise FlowChat::Interrupt::Prompt.new([:text, "Please answer with Yes or No.", {}])
+        end
+
+        process_input(boolean_value, transform, validate, convert)
+      end
+
+      def present_choices_as_buttons(message, choices)
+        buttons = choices.map do |key, value|
+          {
+            id: key.to_s,
+            title: truncate_text(value.to_s, 20) # WhatsApp button titles have a 20 character limit
+          }
+        end
+
+        raise FlowChat::Interrupt::Prompt.new([:interactive_buttons, message, { buttons: buttons }])
+      end
+
+      def present_choices_as_list(message, choices)
+        items = choices.map do |key, value|
+          original_text = value.to_s
+          truncated_title = truncate_text(original_text, 24)
+          
+          # If title was truncated, put full text in description (up to 72 chars)
+          description = if original_text.length > 24
+                         truncate_text(original_text, 72)
+                       else
+                         nil
+                       end
+          
+          {
+            id: key.to_s,
+            title: truncated_title,
+            description: description
+          }.compact
+        end
+
+        # If 10 or fewer items, use single section
+        if items.length <= 10
+          sections = [
+            {
+              title: "Options",
+              rows: items
+            }
+          ]
+        else
+          # Paginate into multiple sections (max 10 items per section)
+          sections = items.each_slice(10).with_index.map do |section_items, index|
+            start_num = (index * 10) + 1
+            end_num = start_num + section_items.length - 1
+            
+            {
+              title: "#{start_num}-#{end_num}",
+              rows: section_items
+            }
+          end
+        end
+
+        raise FlowChat::Interrupt::Prompt.new([:interactive_list, message, { sections: sections }])
+      end
+
+      def validate_choices(choices)
+        # Check for empty choices
+        if choices.nil? || choices.empty?
+          raise ArgumentError, "choices cannot be empty"
+        end
+
+        choice_count = choices.is_a?(Array) ? choices.length : choices.length
+
+        # WhatsApp supports max 100 total items across all sections
+        if choice_count > 100
+          raise ArgumentError, "WhatsApp supports maximum 100 choice options, got #{choice_count}"
+        end
+
+        # Validate individual choice values
+        choices_to_validate = choices.is_a?(Array) ? choices : choices.values
+
+        choices_to_validate.each_with_index do |choice, index|
+          if choice.nil? || choice.to_s.strip.empty?
+            raise ArgumentError, "choice at index #{index} cannot be empty"
+          end
+
+          choice_text = choice.to_s
+          if choice_text.length > 100
+            raise ArgumentError, "choice '#{choice_text[0..20]}...' is too long (#{choice_text.length} chars). Maximum is 100 characters"
+          end
+        end
+      end
+
+      def truncate_text(text, length)
+        return text if text.length <= length
+        text[0, length - 3] + "..."
+      end
+    end
+  end
+end