flow_chat 0.6.1 → 0.8.0

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

@@ -4,11 +4,16 @@ module FlowChat
   module Ussd
     module Gateway
       class Nsano
+        include FlowChat::Instrumentation
+
+        attr_reader :context
+
         def initialize(app)
           @app = app
         end
 
         def call(context)
+          @context = context
           controller = context["controller"]
           controller.request
 
@@ -17,6 +22,35 @@ module FlowChat
 
           # Set a basic message_id (can be enhanced based on actual Nsano implementation)
           context["request.message_id"] = SecureRandom.uuid
+          context["request.platform"] = :ussd
+
+          # TODO: Implement Nsano-specific parameter parsing
+          # For now, add basic instrumentation structure for when this is implemented
+
+          # Placeholder instrumentation - indicates Nsano implementation is needed
+          instrument(Events::MESSAGE_RECEIVED, {
+            from: "TODO",  # Would be parsed from Nsano params
+            message: "TODO",  # Would be actual user input
+            session_id: "TODO",  # Would be Nsano session ID
+            gateway: :nsano,
+            platform: :ussd,
+            timestamp: context["request.timestamp"]
+          })
+
+          # Process request with placeholder app call
+          _, _, _, _ = @app.call(context) if @app
+
+          # Placeholder response instrumentation
+          instrument(Events::MESSAGE_SENT, {
+            to: "TODO",  # Would be actual phone number
+            session_id: "TODO",  # Would be Nsano session ID
+            message: "TODO",  # Would be actual response message
+            message_type: "prompt",  # Would depend on actual response type
+            gateway: :nsano,
+            platform: :ussd,
+            content_length: 0,  # Would be actual content length
+            timestamp: context["request.timestamp"]
+          })
 
           # input = context["rack.input"].read
           # context["rack.input"].rewind
@@ -25,7 +59,7 @@ module FlowChat
           #   if params["network"].present? && params["UserSessionID"].present?
           #     request_id = "nsano::request_id::#{params["UserSessionID"]}"
           #     context["ussd.request"] = {
-          #       provider: :nsano,
+          #       gateway: :nsano,
           #       network: params["network"].to_sym,
           #       msisdn: Phonelib.parse(params["msisdn"]).e164,
           #       type: Config.cache&.read(request_id).present? ? :response : :initial,
@@ -37,7 +71,7 @@ module FlowChat
 
           # status, headers, response = @app.call(context)
 
-          # if context["ussd.response"].present? && context["ussd.request"][:provider] == :nsano
+          # if context["ussd.response"].present? && context["ussd.request"][:gateway] == :nsano
           #   if context["ussd.response"][:type] == :terminal
           #     Config.cache&.write(request_id, nil)
           #   else

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

@@ -0,0 +1,109 @@
+module FlowChat
+  module Ussd
+    module Middleware
+      class ChoiceMapper
+        def initialize(app)
+          @app = app
+          FlowChat.logger.debug { "Ussd::ChoiceMapper: Initialized USSD choice mapping middleware" }
+        end
+
+        def call(context)
+          @context = context
+          @session = context.session
+
+          session_id = context["session.id"]
+          FlowChat.logger.debug { "Ussd::ChoiceMapper: Processing request for session #{session_id}" }
+
+          if intercept?
+            FlowChat.logger.info { "Ussd::ChoiceMapper: Intercepting request for choice resolution - session #{session_id}" }
+            handle_choice_input
+          end
+
+          # Clear choice mapping state for new flows
+          clear_choice_state_if_needed
+          type, prompt, choices, media = @app.call(context)
+
+          if choices.present?
+            FlowChat.logger.debug { "Ussd::ChoiceMapper: Found choices, creating number mapping" }
+            choices = create_numbered_mapping(choices)
+          end
+
+          [type, prompt, choices, media]
+        end
+
+        private
+
+        def intercept?
+          # Intercept if we have choice mapping state and user input is a number that maps to a choice
+          choice_mapping = get_choice_mapping
+          should_intercept = choice_mapping.present? &&
+            @context.input.present? &&
+            choice_mapping.key?(@context.input.to_s)
+
+          if should_intercept
+            FlowChat.logger.debug { "Ussd::ChoiceMapper: Intercepting - input: #{@context.input}, mapped to: #{choice_mapping[@context.input.to_s]}" }
+          end
+
+          should_intercept
+        end
+
+        def handle_choice_input
+          choice_mapping = get_choice_mapping
+          original_choice = choice_mapping[@context.input.to_s]
+
+          FlowChat.logger.info { "Ussd::ChoiceMapper: Resolving choice input #{@context.input} to #{original_choice}" }
+
+          # Replace the numeric input with the original choice
+          @context.input = original_choice
+        end
+
+        def create_numbered_mapping(choices)
+          # Choices are always a hash after normalize_choices
+          numbered_choices = {}
+          choice_mapping = {}
+
+          choices.each_with_index do |(key, value), index|
+            number = (index + 1).to_s
+            numbered_choices[number] = value
+            choice_mapping[number] = key.to_s
+          end
+
+          store_choice_mapping(choice_mapping)
+          FlowChat.logger.debug { "Ussd::ChoiceMapper: Created mapping: #{choice_mapping}" }
+          numbered_choices
+        end
+
+        def store_choice_mapping(mapping)
+          @session.set("ussd.choice_mapping", mapping)
+          FlowChat.logger.debug { "Ussd::ChoiceMapper: Stored choice mapping: #{mapping}" }
+        end
+
+        def get_choice_mapping
+          @session.get("ussd.choice_mapping") || {}
+        end
+
+        def clear_choice_mapping
+          @session.delete("ussd.choice_mapping")
+          FlowChat.logger.debug { "Ussd::ChoiceMapper: Cleared choice mapping" }
+        end
+
+        def clear_choice_state_if_needed
+          # Clear choice mapping if this is a new flow (no input or fresh start)
+          if @context.input.blank? || should_clear_for_new_flow?
+            clear_choice_mapping
+          end
+        end
+
+        def should_clear_for_new_flow?
+          # Clear mapping if this input doesn't match any stored mapping
+          # This indicates we're in a new flow step
+          choice_mapping = get_choice_mapping
+          return false if choice_mapping.empty?
+
+          # If input is present but doesn't match any mapping, we're in a new flow
+          @context.input.present? && !choice_mapping.key?(@context.input.to_s)
+        end
+      end
+    end
+  end
+end

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

@@ -4,22 +4,44 @@ module FlowChat
       class Executor
         def initialize(app)
           @app = app
+          FlowChat.logger.debug { "Ussd::Executor: Initialized USSD executor middleware" }
         end
 
         def call(context)
+          flow_class = context.flow
+          action = context["flow.action"]
+          session_id = context["session.id"]
+
+          FlowChat.logger.info { "Ussd::Executor: Executing flow #{flow_class.name}##{action} for session #{session_id}" }
+
           ussd_app = build_ussd_app context
-          flow = context.flow.new ussd_app
-          flow.send context["flow.action"]
+          FlowChat.logger.debug { "Ussd::Executor: USSD app built for flow execution" }
+
+          flow = flow_class.new ussd_app
+          FlowChat.logger.debug { "Ussd::Executor: Flow instance created, invoking #{action} method" }
+
+          flow.send action
+          FlowChat.logger.warn { "Ussd::Executor: Flow execution failed to interact with user for #{flow_class.name}##{action}" }
+          raise FlowChat::Interrupt::Terminate, "Unexpected end of flow."
         rescue FlowChat::Interrupt::Prompt => e
+          FlowChat.logger.info { "Ussd::Executor: Flow prompted user - Session: #{session_id}, Prompt: '#{e.prompt.truncate(100)}'" }
+          FlowChat.logger.debug { "Ussd::Executor: Prompt details - Choices: #{e.choices&.size || 0}, Has media: #{!e.media.nil?}" }
           [:prompt, e.prompt, e.choices, e.media]
         rescue FlowChat::Interrupt::Terminate => e
+          FlowChat.logger.info { "Ussd::Executor: Flow terminated - Session: #{session_id}, Message: '#{e.prompt.truncate(100)}'" }
+          FlowChat.logger.debug { "Ussd::Executor: Destroying session #{session_id}" }
           context.session.destroy
           [:terminate, e.prompt, nil, e.media]
+        rescue => error
+          FlowChat.logger.error { "Ussd::Executor: Flow execution failed - #{flow_class.name}##{action}, Session: #{session_id}, Error: #{error.class.name}: #{error.message}" }
+          FlowChat.logger.debug { "Ussd::Executor: Stack trace: #{error.backtrace.join("\n")}" }
+          raise
         end
 
         private
 
         def build_ussd_app(context)
+          FlowChat.logger.debug { "Ussd::Executor: Building USSD app instance" }
           FlowChat::Ussd::App.new(context)
         end
       end

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

@@ -2,23 +2,44 @@ module FlowChat
   module Ussd
     module Middleware
       class Pagination
+        include FlowChat::Instrumentation
+
+        attr_reader :context
+
         def initialize(app)
           @app = app
+          FlowChat.logger.debug { "Ussd::Pagination: Initialized USSD pagination middleware" }
         end
 
         def call(context)
           @context = context
           @session = context.session
 
+          session_id = context["session.id"]
+          FlowChat.logger.debug { "Ussd::Pagination: Processing request for session #{session_id}" }
+
           if intercept?
+            FlowChat.logger.info { "Ussd::Pagination: Intercepting request for pagination handling - session #{session_id}" }
             type, prompt = handle_intercepted_request
             [type, prompt, []]
           else
+            # Clear pagination state for new flows
+            if pagination_state.present?
+              FlowChat.logger.debug { "Ussd::Pagination: Clearing pagination state for new flow - session #{session_id}" }
+            end
             @session.delete "ussd.pagination"
+
             type, prompt, choices, media = @app.call(context)
 
             prompt = FlowChat::Ussd::Renderer.new(prompt, choices: choices, media: media).render
-            type, prompt = maybe_paginate(type, prompt) if prompt.present?
+
+            if prompt.present?
+              original_length = prompt.length
+              type, prompt = maybe_paginate(type, prompt)
+              if prompt.length != original_length
+                FlowChat.logger.info { "Ussd::Pagination: Content paginated - original: #{original_length} chars, paginated: #{prompt.length} chars" }
+              end
+            end
 
             [type, prompt, []]
           end
@@ -27,53 +48,91 @@ module FlowChat
         private
 
         def intercept?
-          pagination_state.present? &&
+          should_intercept = pagination_state.present? &&
             (pagination_state["type"].to_sym == :terminal ||
              ([FlowChat::Config.ussd.pagination_next_option, FlowChat::Config.ussd.pagination_back_option].include? @context.input))
+
+          if should_intercept
+            FlowChat.logger.debug { "Ussd::Pagination: Intercepting - input: #{@context.input}, pagination type: #{pagination_state["type"]}" }
+          end
+
+          should_intercept
         end
 
         def handle_intercepted_request
-          FlowChat::Config.logger&.info "FlowChat::Middleware::Pagination :: Intercepted to handle pagination"
+          FlowChat.logger.info { "Ussd::Pagination: Handling paginated request" }
           start, finish, has_more = calculate_offsets
           type = (pagination_state["type"].to_sym == :terminal && !has_more) ? :terminal : :prompt
           prompt = pagination_state["prompt"][start..finish] + build_pagination_options(type, has_more)
           set_pagination_state(current_page, start, finish)
 
+          # Instrument pagination navigation
+          instrument(Events::PAGINATION_TRIGGERED, {
+            session_id: @context["session.id"],
+            current_page: current_page,
+            total_pages: calculate_total_pages,
+            content_length: pagination_state["prompt"].length,
+            page_limit: FlowChat::Config.ussd.pagination_page_size,
+            navigation_action: (@context.input == FlowChat::Config.ussd.pagination_next_option) ? "next" : "back"
+          })
+
+          FlowChat.logger.debug { "Ussd::Pagination: Serving page content - start: #{start}, finish: #{finish}, has_more: #{has_more}, type: #{type}" }
           [type, prompt]
         end
 
         def maybe_paginate(type, prompt)
           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."
+            FlowChat.logger.info { "Ussd::Pagination: Content exceeds page size (#{prompt.length} > #{FlowChat::Config.ussd.pagination_page_size}), initiating pagination" }
+
             slice_end = single_option_slice_size
             # Ensure we do not cut words and options off in the middle.
             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
+
+            FlowChat.logger.debug { "Ussd::Pagination: First page break at position #{current_pagebreak}" }
+
             set_pagination_state(1, 0, current_pagebreak, original_prompt, type)
             prompt = original_prompt[0..current_pagebreak] + "\n\n" + next_option
             type = :prompt
+
+            # Instrument initial pagination setup
+            total_pages = calculate_total_pages(original_prompt)
+            instrument(Events::PAGINATION_TRIGGERED, {
+              session_id: @context["session.id"],
+              current_page: 1,
+              total_pages: total_pages,
+              content_length: original_prompt.length,
+              page_limit: FlowChat::Config.ussd.pagination_page_size,
+              navigation_action: "initial"
+            })
+
+            FlowChat.logger.debug { "Ussd::Pagination: First page prepared with #{prompt.length} characters" }
           end
           [type, prompt]
         end
 
         def calculate_offsets
           page = current_page
+
+          FlowChat.logger.debug { "Ussd::Pagination: Calculating offsets for page #{page}" }
+
           offset = pagination_state["offsets"][page.to_s]
           if offset.present?
-            FlowChat::Config.logger&.debug "FlowChat::Middleware::Pagination :: Reusing cached offset for page: #{page}"
+            FlowChat.logger.debug { "Ussd::Pagination: Using cached offset for page #{page}" }
             start = offset["start"]
             finish = offset["finish"]
             has_more = pagination_state["prompt"].length > finish
           else
-            FlowChat::Config.logger&.debug "FlowChat::Middleware::Pagination :: Calculating offset for page: #{page}"
+            FlowChat.logger.debug { "Ussd::Pagination: Computing new offset for page #{page}" }
             # We are guaranteed a previous offset because it was set in maybe_paginate
             previous_page = page - 1
             previous_offset = pagination_state["offsets"][previous_page.to_s]
             start = previous_offset["finish"] + 1
             has_more, len = (pagination_state["prompt"].length > start + single_option_slice_size) ? [true, dual_options_slice_size] : [false, single_option_slice_size]
             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}"
+              FlowChat.logger.warn { "Ussd::Pagination: No content for page #{page}, reverting to page #{page - 1}" }
               page -= 1
               has_more = false
               start = previous_offset["start"]
@@ -90,19 +149,26 @@ module FlowChat
                   # 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
+                    old_finish = finish
                     finish = start + boundary_pos
+                    FlowChat.logger.debug { "Ussd::Pagination: Adjusted finish for word boundary - #{old_finish} -> #{finish}" }
                   end
                   # If no boundary found, we'll have to break mid-word (fallback)
                 end
               end
             end
           end
+
+          FlowChat.logger.debug { "Ussd::Pagination: Page #{page} offsets - start: #{start}, finish: #{finish}, has_more: #{has_more}" }
           [start, finish, has_more]
         end
 
         def build_pagination_options(type, has_more)
           options_str = ""
           has_less = current_page > 1
+
+          FlowChat.logger.debug { "Ussd::Pagination: Building pagination options - type: #{type}, has_more: #{has_more}, has_less: #{has_less}" }
+
           if type.to_sym == :prompt
             options_str += "\n\n"
             next_opt = has_more ? next_option : ""
@@ -126,6 +192,7 @@ module FlowChat
             # We accomodate the 2 newlines and the longest of the options
             # We subtract an additional 1 to normalize it for slicing
             @single_option_slice_size = FlowChat::Config.ussd.pagination_page_size - 2 - [next_option.length, back_option.length].max - 1
+            FlowChat.logger.debug { "Ussd::Pagination: Calculated single option slice size: #{@single_option_slice_size}" }
           end
           @single_option_slice_size
         end
@@ -135,6 +202,7 @@ module FlowChat
             # To display both back and next options
             # We accomodate the 3 newlines and both of the options
             @dual_options_slice_size = FlowChat::Config.ussd.pagination_page_size - 3 - [next_option.length, back_option.length].sum - 1
+            FlowChat.logger.debug { "Ussd::Pagination: Calculated dual options slice size: #{@dual_options_slice_size}" }
           end
           @dual_options_slice_size
         end
@@ -143,8 +211,10 @@ module FlowChat
           page = pagination_state["page"]
           if @context.input == FlowChat::Config.ussd.pagination_back_option
             page -= 1
+            FlowChat.logger.debug { "Ussd::Pagination: Moving to previous page: #{page}" }
           elsif @context.input == FlowChat::Config.ussd.pagination_next_option
             page += 1
+            FlowChat.logger.debug { "Ussd::Pagination: Moving to next page: #{page}" }
           end
           [page, 1].max
         end
@@ -165,8 +235,18 @@ module FlowChat
             "prompt" => prompt,
             "type" => type.to_s
           }
+
+          FlowChat.logger.debug { "Ussd::Pagination: Saving pagination state - page: #{page}, total_content: #{prompt&.length || 0} chars" }
           @session.set "ussd.pagination", new_state
         end
+
+        def calculate_total_pages(content = nil)
+          content ||= pagination_state["prompt"]
+          return 1 unless content&.length&.> FlowChat::Config.ussd.pagination_page_size
+
+          # Rough estimation - actual pages may vary due to word boundaries
+          (content.length.to_f / single_option_slice_size).ceil
+        end
       end
     end
   end

data/lib/flow_chat/ussd/processor.rb

@@ -1,9 +1,11 @@
 module FlowChat
   module Ussd
     class Processor < FlowChat::BaseProcessor
-      def use_resumable_sessions
-        middleware.insert_before 0, FlowChat::Ussd::Middleware::ResumableSession
-        self
+      def use_durable_sessions(cross_gateway: false)
+        FlowChat.logger.debug { "Ussd::Processor: Enabling durable sessions via session configuration" }
+        use_session_config(
+          identifier: :msisdn  # Use MSISDN for durable sessions
+        )
       end
 
       protected
@@ -13,14 +15,24 @@ module FlowChat
       end
 
       def build_middleware_stack
+        FlowChat.logger.debug { "Ussd::Processor: Building USSD middleware stack" }
         create_middleware_stack("ussd")
       end
 
       def configure_middleware_stack(builder)
-        builder.use FlowChat::Session::Middleware
+        FlowChat.logger.debug { "Ussd::Processor: Configuring USSD middleware stack" }
+
         builder.use FlowChat::Ussd::Middleware::Pagination
+        FlowChat.logger.debug { "Ussd::Processor: Added Ussd::Middleware::Pagination" }
+
         builder.use middleware
+        FlowChat.logger.debug { "Ussd::Processor: Added custom middleware" }
+
+        builder.use FlowChat::Ussd::Middleware::ChoiceMapper
+        FlowChat.logger.debug { "Ussd::Processor: Added Ussd::Middleware::ChoiceMapper" }
+
         builder.use FlowChat::Ussd::Middleware::Executor
+        FlowChat.logger.debug { "Ussd::Processor: Added Ussd::Middleware::Executor" }
       end
     end
   end

data/lib/flow_chat/ussd/renderer.rb

@@ -14,7 +14,7 @@ module FlowChat
       private
 
       def build_prompt
-        parts = [prompt, build_media, build_choices].compact
+        parts = [build_media, prompt, build_choices].compact
         parts.join "\n\n"
       end
 

data/lib/flow_chat/version.rb

@@ -1,3 +1,3 @@
 module FlowChat
-  VERSION = "0.6.1"
+  VERSION = "0.8.0"
 end