flow_chat 0.5.2 → 0.6.0

data/config/routes_demo.rb

@@ -0,0 +1,59 @@
+# Demo Routes Configuration for FlowChat Comprehensive Demo
+# 
+# Add these routes to your config/routes.rb file to enable the demo endpoints
+# 
+# Example integration:
+# Rails.application.routes.draw do
+#   # Your existing routes...
+#   
+#   # FlowChat Demo Routes
+#   scope :demo do
+#     post 'ussd' => 'demo#ussd_demo'
+#     match 'whatsapp' => 'demo#whatsapp_demo', via: [:get, :post]
+#     match 'whatsapp_custom' => 'demo#whatsapp_custom_demo', via: [:get, :post]
+#     match 'whatsapp_background' => 'demo#whatsapp_background_demo', via: [:get, :post]
+#     match 'whatsapp_simulator' => 'demo#whatsapp_simulator_demo', via: [:get, :post]
+#   end
+# end
+
+Rails.application.routes.draw do
+  # FlowChat Comprehensive Demo Routes
+  scope :demo do
+    # USSD Demo
+    # Endpoint: POST /demo/ussd
+    # Purpose: Demonstrates USSD integration with all features
+    # Features: Pagination, session management, complex workflows
+    post 'ussd' => 'demo#ussd_demo'
+
+    # WhatsApp Demo (Standard)
+    # Endpoint: GET/POST /demo/whatsapp  
+    # Purpose: Standard WhatsApp integration with media support
+    # Features: Rich media, interactive elements, buttons/lists
+    match 'whatsapp' => 'demo#whatsapp_demo', via: [:get, :post]
+
+    # WhatsApp Demo (Custom Configuration)
+    # Endpoint: GET/POST /demo/whatsapp_custom
+    # Purpose: Shows multi-tenant configuration capabilities
+    # Features: Custom credentials, per-endpoint configuration
+    match 'whatsapp_custom' => 'demo#whatsapp_custom_demo', via: [:get, :post]
+
+    # WhatsApp Demo (Background Processing)
+    # Endpoint: GET/POST /demo/whatsapp_background
+    # Purpose: Demonstrates background job integration
+    # Features: Asynchronous response delivery, job queuing
+    match 'whatsapp_background' => 'demo#whatsapp_background_demo', via: [:get, :post]
+
+    # WhatsApp Demo (Simulator Mode)
+    # Endpoint: GET/POST /demo/whatsapp_simulator
+    # Purpose: Testing mode that returns response data as JSON
+    # Features: No actual WhatsApp API calls, perfect for testing
+    match 'whatsapp_simulator' => 'demo#whatsapp_simulator_demo', via: [:get, :post]
+  end
+
+  # Optional: Simulator interface for testing
+  # Uncomment if you want to add the simulator UI
+  # get '/simulator' => 'simulator#index'
+  
+  # Optional: API documentation endpoint
+  # get '/demo' => 'demo#index'
+end 

data/lib/flow_chat/config.rb

@@ -4,6 +4,9 @@ module FlowChat
     mattr_accessor :logger, default: Logger.new($stdout)
     mattr_accessor :cache, default: nil
     mattr_accessor :simulator_secret, default: nil
+    # When true (default), validation errors are combined with the original message.
+    # When false, only the validation error message is shown to the user.
+    mattr_accessor :combine_validation_error_with_message, default: true
 
     # USSD-specific configuration object
     def self.ussd

data/lib/flow_chat/interrupt.rb

@@ -2,11 +2,12 @@ module FlowChat
   module Interrupt
     # standard:disable Lint/InheritException
     class Base < Exception
-      attr_reader :prompt
+      attr_reader :prompt, :media
 
-      def initialize(prompt)
+      def initialize(prompt, media: nil)
         @prompt = prompt
-        super
+        @media = media
+        super(prompt)
       end
     end
     # standard:enable Lint/InheritException
@@ -14,9 +15,9 @@ module FlowChat
     class Prompt < Base
       attr_reader :choices
 
-      def initialize(*args, choices: nil)
+      def initialize(prompt, choices: nil, media: nil)
         @choices = choices
-        super(*args)
+        super(prompt, media: media)
       end
     end
 

data/lib/flow_chat/prompt.rb

@@ -0,0 +1,91 @@
+module FlowChat
+  class Prompt
+    attr_reader :user_input
+
+    def initialize(input)
+      @user_input = input
+    end
+
+    def ask(msg, choices: nil, convert: nil, validate: nil, transform: nil, media: nil)
+      # Validate media and choices compatibility
+      validate_media_choices_compatibility(media, choices)
+
+      if user_input.present?
+        input = user_input
+        input = convert.call(input) if convert.present?
+        validation_error = validate.call(input) if validate.present?
+
+        if validation_error.present?
+          # Use config to determine whether to combine validation error with original message
+          message = if FlowChat::Config.combine_validation_error_with_message
+            [validation_error, msg].join("\n\n")
+          else
+            validation_error
+          end
+          prompt!(message, choices: choices, media: media)
+        end
+
+        input = transform.call(input) if transform.present?
+        return input
+      end
+
+      # Pass raw message and media separately to the renderer
+      prompt! msg, choices: choices, media: media
+    end
+
+    def say(message, media: nil)
+      # Pass raw message and media separately to the renderer
+      terminate! message, media: media
+    end
+
+    def select(msg, choices, media: nil)
+      # Validate media and choices compatibility
+      validate_media_choices_compatibility(media, choices)
+
+      choices, choices_prompt = build_select_choices choices
+      ask(
+        msg,
+        choices: choices_prompt,
+        convert: lambda { |choice| choice.to_i },
+        validate: lambda { |choice| "Invalid selection:" unless (1..choices.size).cover?(choice) },
+        transform: lambda { |choice| choices[choice - 1] },
+        media: media
+      )
+    end
+
+    def yes?(msg)
+      select(msg, ["Yes", "No"]) == "Yes"
+    end
+
+    private
+
+    def validate_media_choices_compatibility(media, choices)
+      return unless media && choices
+
+      if choices.length > 3
+        raise ArgumentError, "Media with more than 3 choices is not supported. Please use either media OR choices for more than 3 options."
+      end
+    end
+
+    def build_select_choices(choices)
+      case choices
+      when Array
+        choices_prompt = choices.map.with_index { |c, i| [i + 1, c] }.to_h
+      when Hash
+        choices_prompt = choices.values.map.with_index { |c, i| [i + 1, c] }.to_h
+        choices = choices.keys
+      else
+        raise ArgumentError, "choices must be an array or hash"
+      end
+      [choices, choices_prompt]
+    end
+
+    def prompt!(msg, choices: nil, media: nil)
+      raise FlowChat::Interrupt::Prompt.new(msg, choices: choices, media: media)
+    end
+
+    def terminate!(msg, media: nil)
+      raise FlowChat::Interrupt::Terminate.new(msg, media: media)
+    end
+  end
+end 

data/lib/flow_chat/simulator/views/simulator.html.erb

@@ -395,8 +395,6 @@
         box-shadow: 0 1px 3px rgba(0,0,0,0.1);
         font-size: 14px;
         line-height: 1.4;
-        max-height: 300px;
-        overflow-y: auto;
         overflow-x: hidden;
       }
 

data/lib/flow_chat/ussd/app.rb

@@ -17,7 +17,7 @@ module FlowChat
         navigation_stack << key
         return session.get(key) if session.get(key).present?
 
-        prompt = FlowChat::Ussd::Prompt.new input
+        prompt = FlowChat::Prompt.new input
         @input = nil # input is being submitted to prompt so we clear it
 
         value = yield prompt
@@ -25,7 +25,7 @@ module FlowChat
         value
       end
 
-      def say(msg)
+      def say(msg, media: nil)
         raise FlowChat::Interrupt::Terminate.new(msg)
       end
 

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

@@ -20,20 +20,20 @@ module FlowChat
           # context["request.type"] = params["MSGTYPE"] ? :initial : :response
           context.input = params["USERDATA"].presence
 
-          type, prompt, choices = @app.call(context)
+          type, prompt, choices, media = @app.call(context)
 
           context.controller.render json: {
             USERID: params["USERID"],
             MSISDN: params["MSISDN"],
-            MSG: render_prompt(prompt, choices),
+            MSG: render_prompt(prompt, choices, media),
             MSGTYPE: type == :prompt
           }
         end
 
         private
 
-        def render_prompt(prompt, choices)
-          FlowChat::Ussd::Renderer.new(prompt, choices).render
+        def render_prompt(prompt, choices, media)
+          FlowChat::Ussd::Renderer.new(prompt, choices: choices, media: media).render
         end
       end
     end

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

@@ -11,10 +11,10 @@ module FlowChat
           flow = context.flow.new ussd_app
           flow.send context["flow.action"]
         rescue FlowChat::Interrupt::Prompt => e
-          [:prompt, e.prompt, e.choices]
+          [:prompt, e.prompt, e.choices, e.media]
         rescue FlowChat::Interrupt::Terminate => e
           context.session.destroy
-          [:terminate, e.prompt, nil]
+          [:terminate, e.prompt, nil, e.media]
         end
 
         private

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

@@ -12,14 +12,16 @@ module FlowChat
 
           if intercept?
             type, prompt = handle_intercepted_request
+            [type, prompt, []]
           else
             @session.delete "ussd.pagination"
-            type, prompt, choices = @app.call(context)
+            type, prompt, choices, media = @app.call(context)
 
-            prompt = FlowChat::Ussd::Renderer.new(prompt, choices).render
+            prompt = FlowChat::Ussd::Renderer.new(prompt, choices: choices, media: media).render
             type, prompt = maybe_paginate(type, prompt) if prompt.present?
+
+            [type, prompt, []]
           end
-          [type, prompt, []]
         end
 
         private
@@ -34,7 +36,7 @@ module FlowChat
           FlowChat::Config.logger&.info "FlowChat::Middleware::Pagination :: Intercepted to handle pagination"
           start, finish, has_more = calculate_offsets
           type = (pagination_state["type"].to_sym == :terminal && !has_more) ? :terminal : :prompt
-          prompt = pagination_state["prompt"][start..finish].strip + build_pagination_options(type, has_more)
+          prompt = pagination_state["prompt"][start..finish] + build_pagination_options(type, has_more)
           set_pagination_state(current_page, start, finish)
 
           [type, prompt]
@@ -44,11 +46,11 @@ module FlowChat
           if prompt.length > FlowChat::Config.ussd.pagination_page_size
             original_prompt = prompt
             FlowChat::Config.logger&.info "FlowChat::Middleware::Pagination :: Response length (#{prompt.length}) exceeds page size (#{FlowChat::Config.ussd.pagination_page_size}). Paginating."
-            prompt = prompt[0..single_option_slice_size]
+            slice_end = single_option_slice_size
             # Ensure we do not cut words and options off in the middle.
-            current_pagebreak = prompt[single_option_slice_size + 1].blank? ? single_option_slice_size : prompt.rindex("\n") || prompt.rindex(" ") || single_option_slice_size
+            current_pagebreak = original_prompt[slice_end + 1].blank? ? slice_end : original_prompt[0..slice_end].rindex("\n") || original_prompt[0..slice_end].rindex(" ") || slice_end
             set_pagination_state(1, 0, current_pagebreak, original_prompt, type)
-            prompt = prompt[0..current_pagebreak].strip + "\n\n" + next_option
+            prompt = original_prompt[0..current_pagebreak] + "\n\n" + next_option
             type = :prompt
           end
           [type, prompt]
@@ -72,13 +74,27 @@ module FlowChat
             finish = start + len
             if start > pagination_state["prompt"].length
               FlowChat::Config.logger&.debug "FlowChat::Middleware::Pagination :: No content exists for page: #{page}. Reverting to page: #{page - 1}"
+              page -= 1
               has_more = false
               start = previous_offset["start"]
               finish = previous_offset["finish"]
             else
-              prompt = pagination_state["prompt"][start..finish]
-              current_pagebreak = pagination_state["prompt"][finish + 1].blank? ? len : prompt.rindex("\n") || prompt.rindex(" ") || len
-              finish = start + current_pagebreak
+              # Apply word boundary logic for the new page
+              full_prompt = pagination_state["prompt"]
+              if finish < full_prompt.length
+                # Look for word boundary within the slice
+                slice_text = full_prompt[start..finish]
+                # Check if the character after our slice point is a word boundary
+                next_char = full_prompt[finish + 1]
+                if next_char && !next_char.match(/\s/)
+                  # We're in the middle of a word, find the last word boundary
+                  boundary_pos = slice_text.rindex("\n") || slice_text.rindex(" ")
+                  if boundary_pos
+                    finish = start + boundary_pos
+                  end
+                  # If no boundary found, we'll have to break mid-word (fallback)
+                end
+              end
             end
           end
           [start, finish, has_more]
@@ -134,21 +150,22 @@ module FlowChat
         end
 
         def pagination_state
-          @pagination_state ||= @context.session.get("ussd.pagination") || {}
+          @context.session.get("ussd.pagination") || {}
         end
 
         def set_pagination_state(page, offset_start, offset_finish, prompt = nil, type = nil)
-          offsets = pagination_state["offsets"] || {}
-          offsets[page] = {start: offset_start, finish: offset_finish}
-          prompt ||= pagination_state["prompt"]
-          type ||= pagination_state["type"]
-          @pagination_state = {
+          current_state = pagination_state
+          offsets = current_state["offsets"] || {}
+          offsets[page.to_s] = {"start" => offset_start, "finish" => offset_finish}
+          prompt ||= current_state["prompt"]
+          type ||= current_state["type"]
+          new_state = {
             "page" => page,
             "offsets" => offsets,
             "prompt" => prompt,
-            "type" => type
+            "type" => type.to_s
           }
-          @session.set "ussd.pagination", @pagination_state
+          @session.set "ussd.pagination", new_state
         end
       end
     end

data/lib/flow_chat/ussd/renderer.rb

@@ -1,11 +1,12 @@
 module FlowChat
   module Ussd
     class Renderer
-      attr_reader :prompt, :choices
+      attr_reader :prompt, :choices, :media
 
-      def initialize(prompt, choices)
+      def initialize(prompt, choices: nil, media: nil)
         @prompt = prompt
         @choices = choices
+        @media = media
       end
 
       def render = build_prompt
@@ -13,7 +14,8 @@ module FlowChat
       private
 
       def build_prompt
-        [prompt, build_choices].compact.join "\n\n"
+        parts = [prompt, build_media, build_choices].compact
+        parts.join "\n\n"
       end
 
       def build_choices
@@ -21,6 +23,29 @@ module FlowChat
 
         choices.map { |i, c| "#{i}. #{c}" }.join "\n"
       end
+
+      def build_media
+        return unless media.present?
+
+        media_url = media[:url] || media[:path]
+        media_type = media[:type] || :image
+
+        # For USSD, we append the media URL to the message
+        case media_type.to_sym
+        when :image
+          "📷 Image: #{media_url}"
+        when :document
+          "📄 Document: #{media_url}"
+        when :audio
+          "🎵 Audio: #{media_url}"
+        when :video
+          "🎥 Video: #{media_url}"
+        when :sticker
+          "😊 Sticker: #{media_url}"
+        else
+          "📎 Media: #{media_url}"
+        end
+      end
     end
   end
 end

data/lib/flow_chat/version.rb

@@ -1,3 +1,3 @@
 module FlowChat
-  VERSION = "0.5.2"
+  VERSION = "0.6.0"
 end

data/lib/flow_chat/whatsapp/app.rb

@@ -23,7 +23,7 @@ module FlowChat
           user_input = nil
         end
 
-        prompt = FlowChat::Whatsapp::Prompt.new user_input
+        prompt = FlowChat::Prompt.new user_input
         @input = nil # input is being submitted to prompt so we clear it
 
         value = yield prompt
@@ -31,8 +31,8 @@ module FlowChat
         value
       end
 
-      def say(msg)
-        raise FlowChat::Interrupt::Terminate.new([:text, msg, {}])
+      def say(msg, media: nil)
+        raise FlowChat::Interrupt::Terminate.new(msg, media: media)
       end
 
       # WhatsApp-specific data accessors (read-only)

data/lib/flow_chat/whatsapp/client.rb

@@ -192,25 +192,32 @@ module FlowChat
             text: {body: content}
           }
         when :interactive_buttons
+          interactive_payload = {
+            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
+            }
+          }
+
+          # Add header if provided (for media support)
+          if options[:header]
+            interactive_payload[:header] = options[:header]
+          end
+
           {
             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
-              }
-            }
+            interactive: interactive_payload
           }
         when :interactive_list
           {

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

@@ -114,14 +114,26 @@ module FlowChat
             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)
+            begin
+              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
+            rescue => e
+              # Log the error and set appropriate HTTP status
+              Rails.logger.error "Error processing WhatsApp message: #{e.message}"
+              Rails.logger.error e.backtrace&.join("\n") if e.backtrace
+              
+              # Return error status to WhatsApp so they know processing failed
+              controller.head :internal_server_error
+              
+              # Re-raise the error to bubble it up for proper error tracking/monitoring
+              raise e
             end
           end
 
@@ -217,7 +229,9 @@ module FlowChat
         def handle_message_inline(context, controller)
           response = @app.call(context)
           if response
-            result = @client.send_message(context["request.msisdn"], response)
+            _type, prompt, choices, media = response
+            rendered_message = render_response(prompt, choices, media)
+            result = @client.send_message(context["request.msisdn"], rendered_message)
             context["whatsapp.message_result"] = result
           end
         end
@@ -227,10 +241,13 @@ module FlowChat
           response = @app.call(context)
 
           if response
+            _type, prompt, choices, media = response
+            rendered_message = render_response(prompt, choices, media)
+            
             # Queue only the response delivery asynchronously
             send_data = {
               msisdn: context["request.msisdn"],
-              response: response,
+              response: rendered_message,
               config_name: @config.name
             }
 
@@ -244,7 +261,7 @@ module FlowChat
             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)
+              result = @client.send_message(context["request.msisdn"], rendered_message)
               context["whatsapp.message_result"] = result
             end
           end
@@ -254,9 +271,12 @@ module FlowChat
           response = @app.call(context)
 
           if response
+            _type, prompt, choices, media = response
+            rendered_message = render_response(prompt, choices, media)
+            
             # 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"])
+            message_payload = @client.build_message_payload(rendered_message, context["request.msisdn"])
 
             simulator_response = {
               mode: "simulator",
@@ -317,6 +337,10 @@ module FlowChat
         def parse_request_body(request)
           @body ||= JSON.parse(request.body.read)
         end
+
+        def render_response(prompt, choices, media)
+          FlowChat::Whatsapp::Renderer.new(prompt, choices: choices, media: media).render
+        end
       end
     end
   end

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

@@ -11,12 +11,12 @@ module FlowChat
           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
+          # Return the same triplet format as USSD for consistency
+          [:prompt, e.prompt, e.choices, e.media]
         rescue FlowChat::Interrupt::Terminate => e
           # Clean up session and return terminal message
           context.session.destroy
-          e.prompt
+          [:terminate, e.prompt, nil, e.media]
         end
 
         private