flow_chat 0.3.0 → 0.4.1

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
+          @client = FlowChat::Whatsapp::Client.new(@config)
+        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
+
+        # Expose client for out-of-band messaging
+        def client
+          @client
+        end
+
+        private
+
+        def determine_message_handler(context)
+          # Check for simulator parameter in request (highest priority)
+          if context["simulator_mode"] || context.controller.request.params["simulator_mode"]
+            return :simulator
+          end
+
+          # Use global WhatsApp configuration
+          FlowChat::Config.whatsapp.message_handling_mode
+        end
+
+        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)
+
+          # Check for simulator mode parameter in request
+          if body.dig("simulator_mode") || controller.request.params["simulator_mode"]
+            context["simulator_mode"] = true
+          end
+
+          # 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
+            extract_message_content(message, context)
+
+            # Determine message handling mode
+            handler_mode = determine_message_handler(context)
+
+            # Process the message based on handling mode
+            case handler_mode
+            when :inline
+              handle_message_inline(context, controller)
+            when :background
+              handle_message_background(context, controller)
+            when :simulator
+              # Return early from simulator mode to preserve the JSON response
+              return handle_message_simulator(context, controller)
+            end
+          end
+
+          # Handle message status updates
+          if value["statuses"]&.any?
+            Rails.logger.info "WhatsApp status update: #{value["statuses"]}"
+          end
+
+          controller.head :ok
+        end
+
+        def extract_message_content(message, context)
+          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")
+            }
+            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")
+            }
+            context.input = "$media$"
+          end
+        end
+
+        def handle_message_inline(context, controller)
+          response = @app.call(context)
+          if response
+            result = @client.send_message(context["request.msisdn"], response)
+            context["whatsapp.message_result"] = result
+          end
+        end
+
+        def handle_message_background(context, controller)
+          # Process the flow synchronously (maintaining controller context)
+          response = @app.call(context)
+          
+          if response
+            # Queue only the response delivery asynchronously
+            send_data = {
+              msisdn: context["request.msisdn"],
+              response: response,
+              config_name: @config.name
+            }
+
+            # Get job class from configuration
+            job_class_name = FlowChat::Config.whatsapp.background_job_class
+            
+            # Enqueue background job for sending only
+            begin
+              job_class = job_class_name.constantize
+              job_class.perform_later(send_data)
+            rescue NameError
+              # Fallback to inline sending if no job system
+              Rails.logger.warn "Background mode requested but no #{job_class_name} found. Falling back to inline sending."
+              result = @client.send_message(context["request.msisdn"], response)
+              context["whatsapp.message_result"] = result
+            end
+          end
+        end
+
+        def handle_message_simulator(context, controller)
+          response = @app.call(context)
+          
+          if response
+            # For simulator mode, return the response data in the HTTP response
+            # instead of actually sending via WhatsApp API
+            message_payload = @client.build_message_payload(response, context["request.msisdn"])
+            
+            simulator_response = {
+              mode: "simulator",
+              webhook_processed: true,
+              would_send: message_payload,
+              message_info: {
+                to: context["request.msisdn"],
+                contact_name: context["request.contact_name"],
+                timestamp: Time.now.iso8601
+              }
+            }
+
+            controller.render json: simulator_response
+            return
+          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,26 @@
+module FlowChat
+  module Whatsapp
+    class Processor < FlowChat::BaseProcessor
+      def use_whatsapp_config(config)
+        @whatsapp_config = config
+        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 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,251 @@
+module FlowChat
+  module Whatsapp
+    class Prompt
+      attr_reader :input
+
+      def initialize(input)
+        @input = input
+      end
+
+      def ask(message, transform: nil, validate: nil, convert: nil, media: nil)
+        if input.present?
+          begin
+            processed_input = process_input(input, transform, validate, convert)
+            return processed_input unless processed_input.nil?
+          rescue FlowChat::Interrupt::Prompt => validation_error
+            # If validation failed, include the error message with the original prompt
+            error_message = validation_error.prompt[1]
+            combined_message = "#{message}\n\n#{error_message}"
+            raise FlowChat::Interrupt::Prompt.new([:text, combined_message, {}])
+          end
+        end
+
+        # Send message and wait for response, optionally with media
+        if media
+          raise FlowChat::Interrupt::Prompt.new(build_media_prompt(message, media))
+        else
+          raise FlowChat::Interrupt::Prompt.new([:text, message, {}])
+        end
+      end
+
+      def say(message, media: nil)
+        if media
+          raise FlowChat::Interrupt::Terminate.new(build_media_prompt(message, media))
+        else
+          raise FlowChat::Interrupt::Terminate.new([:text, message, {}])
+        end
+      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)
+
+        # Standard selection without media support
+        interactive_prompt = build_selection_prompt(message, choices)
+        raise FlowChat::Interrupt::Prompt.new(interactive_prompt)
+      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 build_media_prompt(message, media)
+        media_type = media[:type] || :image
+        url = media[:url] || media[:path]
+        filename = media[:filename]
+
+        case media_type.to_sym
+        when :image
+          [:media_image, "", { url: url, caption: message }]
+        when :document
+          [:media_document, "", { url: url, caption: message, filename: filename }]
+        when :audio
+          [:media_audio, "", { url: url, caption: message }]
+        when :video
+          [:media_video, "", { url: url, caption: message }]
+        when :sticker
+          [:media_sticker, "", { url: url }] # Stickers don't support captions
+        else
+          raise ArgumentError, "Unsupported media type: #{media_type}"
+        end
+      end
+
+      def build_selection_prompt(message, 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] }
+          build_list_prompt(message, choice_hash)
+        elsif choices.is_a?(Hash)
+          if choices.length <= 3
+            # Use buttons for 3 or fewer choices
+            build_buttons_prompt(message, choices)
+          else
+            # Use list for more than 3 choices
+            build_list_prompt(message, choices)
+          end
+        else
+          raise ArgumentError, "choices must be an Array or Hash"
+        end
+      end
+
+      def build_buttons_prompt(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
+
+        [:interactive_buttons, message, { buttons: buttons }]
+      end
+
+      def build_list_prompt(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
+
+        [:interactive_list, message, { sections: sections }]
+      end
+
+      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 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 

data/lib/flow_chat/whatsapp/send_job_support.rb

@@ -0,0 +1,79 @@
+module FlowChat
+  module Whatsapp
+    # Module to be included in background jobs for WhatsApp response delivery
+    # Only handles sending responses, not processing flows
+    module SendJobSupport
+      extend ActiveSupport::Concern
+
+      included do
+        # Set up job configuration
+        queue_as :default
+        retry_on StandardError, wait: :exponentially_longer, attempts: 3
+      end
+
+      # Main job execution method for sending responses
+      def perform_whatsapp_send(send_data)
+        config = resolve_whatsapp_config(send_data)
+        client = FlowChat::Whatsapp::Client.new(config)
+        
+        result = client.send_message(send_data[:msisdn], send_data[:response])
+        
+        if result
+          Rails.logger.info "WhatsApp message sent successfully: #{result['messages']&.first&.dig('id')}"
+          on_whatsapp_send_success(send_data, result)
+        else
+          Rails.logger.error "Failed to send WhatsApp message to #{send_data[:msisdn]}"
+          raise "WhatsApp API call failed"
+        end
+      rescue => e
+        on_whatsapp_send_error(e, send_data)
+        handle_whatsapp_send_error(e, send_data, config)
+      end
+
+      private
+
+      # Resolve WhatsApp configuration by name or fallback
+      def resolve_whatsapp_config(send_data)
+        # Try to resolve by name first (preferred method)
+        if send_data[:config_name] && FlowChat::Whatsapp::Configuration.exists?(send_data[:config_name])
+          return FlowChat::Whatsapp::Configuration.get(send_data[:config_name])
+        end
+
+        # Final fallback to default configuration
+        FlowChat::Whatsapp::Configuration.from_credentials
+      end
+
+      # Handle errors with user notification
+      def handle_whatsapp_send_error(error, send_data, config = nil)
+        Rails.logger.error "WhatsApp send job error: #{error.message}"
+        Rails.logger.error error.backtrace&.join("\n") if error.backtrace
+        
+        # Try to send error message to user if we have config
+        if config
+          begin
+            client = FlowChat::Whatsapp::Client.new(config)
+            client.send_text(
+              send_data[:msisdn], 
+              "⚠️ We're experiencing technical difficulties. Please try again in a few minutes."
+            )
+          rescue => send_error
+            Rails.logger.error "Failed to send error message: #{send_error.message}"
+          end
+        end
+        
+        # Re-raise for job retry logic
+        raise error
+      end
+
+      # Override this method in your job for custom behavior
+      def on_whatsapp_send_success(send_data, result)
+        # Optional callback for successful message sending
+      end
+
+      # Override this method in your job for custom error handling
+      def on_whatsapp_send_error(error, send_data)
+        # Optional callback for error handling
+      end
+    end
+  end
+end