flow_chat 0.2.1 → 0.4.0

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/config.rb

@@ -1,16 +1,29 @@
 module FlowChat
   module Config
+    # General framework configuration
     mattr_accessor :logger, default: Logger.new($stdout)
     mattr_accessor :cache, default: nil
 
-    mattr_accessor :pagination_page_size, default: 140
-    mattr_accessor :pagination_back_option, default: "0"
-    mattr_accessor :pagination_back_text, default: "Back"
-    mattr_accessor :pagination_next_option, default: "#"
-    mattr_accessor :pagination_next_text, default: "More"
+    # USSD-specific configuration object
+    def self.ussd
+      @ussd ||= UssdConfig.new
+    end
 
-    mattr_accessor :resumable_sessions_enabled, default: false
-    mattr_accessor :resumable_sessions_global, default: true
-    mattr_accessor :resumable_sessions_timeout_seconds, default: 300
+    class UssdConfig
+      attr_accessor :pagination_page_size, :pagination_back_option, :pagination_back_text,
+        :pagination_next_option, :pagination_next_text,
+        :resumable_sessions_enabled, :resumable_sessions_global, :resumable_sessions_timeout_seconds
+
+      def initialize
+        @pagination_page_size = 140
+        @pagination_back_option = "0"
+        @pagination_back_text = "Back"
+        @pagination_next_option = "#"
+        @pagination_next_text = "More"
+        @resumable_sessions_enabled = false
+        @resumable_sessions_global = true
+        @resumable_sessions_timeout_seconds = 300
+      end
+    end
   end
 end

data/lib/flow_chat/context.rb

@@ -14,8 +14,16 @@ module FlowChat
 
     def input = @data["request.input"]
 
+    def input=(value)
+      @data["request.input"] = value
+    end
+
     def session = @data["session"]
 
+    def session=(value)
+      @data["session"] = value
+    end
+
     def controller = @data["controller"]
 
     # def request = controller.request

data/lib/flow_chat/interrupt.rb

@@ -1,5 +1,6 @@
 module FlowChat
   module Interrupt
+    # standard:disable Lint/InheritException
     class Base < Exception
       attr_reader :prompt
 
@@ -8,6 +9,7 @@ module FlowChat
         super
       end
     end
+    # standard:enable Lint/InheritException
 
     class Prompt < Base
       attr_reader :choices

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

@@ -7,19 +7,27 @@ module FlowChat
 
       def call(context)
         context["session.id"] = session_id context
-        context["session"] = context["session.store"].new context
+        context.session = context["session.store"].new(context)
         @app.call(context)
       end
 
       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,11 +12,13 @@ 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
           # context["request.type"] = params["MSGTYPE"] ? :initial : :response
-          context["request.input"] = params["USERDATA"].presence
+          context.input = params["USERDATA"].presence
 
           type, prompt, choices = @app.call(context)
 

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

@@ -10,7 +10,13 @@ module FlowChat
 
         def call(context)
           controller = context["controller"]
-          request = controller.request
+          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

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

@@ -12,16 +12,14 @@ module FlowChat
 
           if intercept?
             type, prompt = handle_intercepted_request
-            [type, prompt, []]
           else
             @session.delete "ussd.pagination"
             type, prompt, choices = @app.call(context)
 
             prompt = FlowChat::Ussd::Renderer.new(prompt, choices).render
             type, prompt = maybe_paginate(type, prompt) if prompt.present?
-
-            [type, prompt, []]
           end
+          [type, prompt, []]
         end
 
         private
@@ -29,11 +27,11 @@ module FlowChat
         def intercept?
           pagination_state.present? &&
             (pagination_state["type"].to_sym == :terminal ||
-             ([Config.pagination_next_option, Config.pagination_back_option].include? @context.input))
+             ([FlowChat::Config.ussd.pagination_next_option, FlowChat::Config.ussd.pagination_back_option].include? @context.input))
         end
 
         def handle_intercepted_request
-          Config.logger&.info "FlowChat::Middleware::Pagination :: Intercepted to handle pagination"
+          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)
@@ -43,9 +41,9 @@ module FlowChat
         end
 
         def maybe_paginate(type, prompt)
-          if prompt.length > Config.pagination_page_size
+          if prompt.length > FlowChat::Config.ussd.pagination_page_size
             original_prompt = prompt
-            Config.logger&.info "FlowChat::Middleware::Pagination :: Response length (#{prompt.length}) exceeds page size (#{Config.pagination_page_size}). Paginating."
+            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]
             # 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
@@ -60,12 +58,12 @@ module FlowChat
           page = current_page
           offset = pagination_state["offsets"][page.to_s]
           if offset.present?
-            Config.logger&.debug "FlowChat::Middleware::Pagination :: Reusing cached offset for page: #{page}"
+            FlowChat::Config.logger&.debug "FlowChat::Middleware::Pagination :: Reusing cached offset for page: #{page}"
             start = offset["start"]
             finish = offset["finish"]
             has_more = pagination_state["prompt"].length > finish
           else
-            Config.logger&.debug "FlowChat::Middleware::Pagination :: Calculating offset for page: #{page}"
+            FlowChat::Config.logger&.debug "FlowChat::Middleware::Pagination :: Calculating 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]
@@ -73,8 +71,7 @@ module FlowChat
             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
-              Config.logger&.debug "FlowChat::Middleware::Pagination :: No content exists for page: #{page}. Reverting to page: #{page - 1}"
-              page -= 1
+              FlowChat::Config.logger&.debug "FlowChat::Middleware::Pagination :: No content exists for page: #{page}. Reverting to page: #{page - 1}"
               has_more = false
               start = previous_offset["start"]
               finish = previous_offset["finish"]
@@ -100,11 +97,11 @@ module FlowChat
         end
 
         def next_option
-          "#{Config.pagination_next_option} #{Config.pagination_next_text}"
+          "#{FlowChat::Config.ussd.pagination_next_option} #{FlowChat::Config.ussd.pagination_next_text}"
         end
 
         def back_option
-          "#{Config.pagination_back_option} #{Config.pagination_back_text}"
+          "#{FlowChat::Config.ussd.pagination_back_option} #{FlowChat::Config.ussd.pagination_back_text}"
         end
 
         def single_option_slice_size
@@ -112,7 +109,7 @@ module FlowChat
             # To display a single back or next option
             # 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 = Config.pagination_page_size - 2 - [next_option.length, back_option.length].max - 1
+            @single_option_slice_size = FlowChat::Config.ussd.pagination_page_size - 2 - [next_option.length, back_option.length].max - 1
           end
           @single_option_slice_size
         end
@@ -121,16 +118,16 @@ module FlowChat
           unless @dual_options_slice_size.present?
             # To display both back and next options
             # We accomodate the 3 newlines and both of the options
-            @dual_options_slice_size = Config.pagination_page_size - 3 - [next_option.length, back_option.length].sum - 1
+            @dual_options_slice_size = FlowChat::Config.ussd.pagination_page_size - 3 - [next_option.length, back_option.length].sum - 1
           end
           @dual_options_slice_size
         end
 
         def current_page
           page = pagination_state["page"]
-          if @context.input == Config.pagination_back_option
+          if @context.input == FlowChat::Config.ussd.pagination_back_option
             page -= 1
-          elsif @context.input == Config.pagination_next_option
+          elsif @context.input == FlowChat::Config.ussd.pagination_next_option
             page += 1
           end
           [page, 1].max

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

@@ -7,44 +7,31 @@ module FlowChat
         end
 
         def call(context)
-          if Config.resumable_sessions_enabled && context["ussd.request"].present?
-            request = Rack::Request.new(context)
-            session = request.session
-
-            context["ussd.resumable_sessions"] = {}
-
-            # If this is a new session but we have the flag set, this means the call terminated before
-            # the session closed. Force it to resume.
-            # This is safe since a new session is started if the old session does not indeed exist.
-            if context["ussd.request"][:type] == :initial && can_resume_session?(session)
-              context["ussd.request"][:type] = :response
-              context["ussd.resumable_sessions"][:resumed] = true
+          if FlowChat::Config.ussd.resumable_sessions_enabled && context["ussd.request"].present?
+            # First, try to find any interruption session.
+            # The session key can be:
+            #  - a global session (key: "global")
+            #  - a provider-specific session (key: <provider>)
+            session_key = self.class.session_key(context)
+            resumable_session = context["session.store"].get(session_key)
+
+            if resumable_session.present? && valid?(resumable_session)
+              context.merge! resumable_session
             end
-
-            res = @app.call(context)
-
-            if context["ussd.response"].present?
-              if context["ussd.response"][:type] == :terminal || context["ussd.resumable_sessions"][:disable]
-                session.delete "ussd.resumable_sessions"
-              else
-                session["ussd.resumable_sessions"] = Time.now.to_i
-              end
-            end
-
-            res
-          else
-            @app.call(context)
           end
+
+          @app.call(context)
         end
 
         private
 
-        def can_resume_session?(session)
-          return unless session["ussd.resumable_sessions"].present?
-          return true unless Config.resumable_sessions_timeout_seconds
+        def valid?(session)
+          return true unless FlowChat::Config.ussd.resumable_sessions_timeout_seconds
 
-          last_active_at = Time.at(session["ussd.resumable_sessions"])
-          (Time.now - Config.resumable_sessions_timeout_seconds) < last_active_at
+          last_active_at = Time.parse session.dig("context", "last_active_at")
+          (Time.current - FlowChat::Config.ussd.resumable_sessions_timeout_seconds) < last_active_at
+        rescue
+          false
         end
       end
     end

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/ussd/prompt.rb

@@ -32,7 +32,7 @@ module FlowChat
           msg,
           choices: choices_prompt,
           convert: lambda { |choice| choice.to_i },
-          validate: lambda { |choice| "Invalid selection:" unless (1..choices.size).include?(choice) },
+          validate: lambda { |choice| "Invalid selection:" unless (1..choices.size).cover?(choice) },
           transform: lambda { |choice| choices[choice - 1] }
         )
       end

data/lib/flow_chat/ussd/simulator/controller.rb

@@ -38,7 +38,7 @@ module FlowChat
 
         def simulator_locals
           {
-            pagesize: Config.pagination_page_size,
+            pagesize: FlowChat::Config.ussd.pagination_page_size,
             show_options: show_options,
             default_msisdn: default_msisdn,
             default_endpoint: default_endpoint,

data/lib/flow_chat/version.rb

@@ -1,3 +1,3 @@
 module FlowChat
-  VERSION = "0.2.1"
+  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