joy_ussd_engine 0.1.0

data/lib/generators/joy_data_transformer/joy_data_transformer_generator.rb

@@ -0,0 +1,13 @@
+class JoyDataTransformerGenerator < Rails::Generators::Base
+  source_root File.expand_path('templates', __dir__)
+  argument :transformer_name, type: :string
+
+  def generate_transformer
+    create_transformer
+  end
+
+  private
+  def create_transformer
+    template 'joy_transformer_template.template', "app/services/ussd/transformers/#{transformer_name.underscore}_transformer.rb"
+  end
+end

data/lib/generators/joy_data_transformer/templates/joy_transformer_template.template

@@ -0,0 +1,33 @@
+class Ussd::Transformers::<%= transformer_name.camelcase %>Transformer  < JoyUssdEngine::DataTransformer
+            
+    # Responsible for transforming ussd requests and responses from different providers into 
+    # what our application can understand
+
+    def request_params(params)
+        # transform request body of ussd provider currently in use to match the ussd engine request type
+        # {
+        #     session_id: '',
+        #     message: '',
+        # }
+    end
+    
+    def app_terminator(params)
+        # Checks to see if ussd app can be terminated by a particular provider depending on the response
+        # default is to return false
+        return false
+    end
+
+    def response(message, next_state = '')
+        # Returns a tranformed ussd response for a particular provider and waits for user feedback
+    end
+
+    def release(message)
+        # Returns a tranformed ussd response for a particular provider and ends the ussd session
+    end
+
+    def expiration
+        # set expiration for different providers
+        # default is 60 seconds
+        60.seconds
+    end
+end

data/lib/generators/joy_menu/USAGE

@@ -0,0 +1,8 @@
+Description:
+    This will generate a new ussd menu.
+
+Example:
+    bin/rails generate joy_menu Transactions
+
+    This will create:
+        app/services/ussd/menus/transactions_menu.rb

data/lib/generators/joy_menu/joy_menu_generator.rb

@@ -0,0 +1,13 @@
+class JoyMenuGenerator < Rails::Generators::Base
+  source_root File.expand_path('templates', __dir__)
+  argument :menu_name, type: :string
+
+  def generate_menu
+    create_menu
+  end
+
+  private
+  def create_menu
+    template 'joy_menu_template.template', "app/services/ussd/menus/#{menu_name.underscore}_menu.rb"
+  end
+end

data/lib/generators/joy_menu/templates/joy_menu_template.template

@@ -0,0 +1,28 @@
+class Ussd::Menus::<%= menu_name.camelcase %>Menu < JoyUssdEngine::Menu
+    def on_validate
+        # User input validation
+    end
+
+    def before_render
+        # Implement before call backs
+        @field_name="<%= menu_name.underscore %>"
+        @menu_text = "Welcome to the <%= menu_name.camelcase %> menu"
+    end
+
+    def on_error
+        # Render error 
+        # @menu_text = "#{@error_text}\n#{@menu_text }"
+    end
+
+    def after_render
+        # Implement after call backs
+    end
+
+    def render
+        # Render ussd menu and pass the next menu as an argument
+        # joy_response(Ussd::Menus::<%= menu_name.camelcase %>Menu)
+
+        # Render ussd menu and terminate the user session
+        # joy_release
+    end
+end

data/lib/generators/joy_paginate_menu/USAGE

@@ -0,0 +1,8 @@
+Description:
+    This will create a new paginating ussd menu
+
+Example:
+    bin/rails generate joy_paginate_menu Paginate
+
+    This will create:
+         app/services/ussd/menus/paginate_menu.rb

data/lib/generators/joy_paginate_menu/joy_paginate_menu_generator.rb

@@ -0,0 +1,13 @@
+class JoyPaginateMenuGenerator < Rails::Generators::Base
+  source_root File.expand_path('templates', __dir__)
+  argument :paginating_menu_name, type: :string
+
+  def generate_menu
+    create_menu
+  end
+
+  private
+  def create_menu
+    template 'joy_paginate_menu_template.template', "app/services/ussd/menus/#{paginating_menu_name.underscore}_menu.rb"
+  end
+end

data/lib/generators/joy_paginate_menu/templates/joy_paginate_menu_template.template

@@ -0,0 +1,48 @@
+class Ussd::Menus::<%= paginating_menu_name.camelcase %>Menu < JoyUssdEngine::PaginateMenu
+    def on_validate
+        # User input validation
+    end
+
+    def before_render
+        # Implement before call backs
+        @field_name="<%= paginating_menu_name.underscore %>"
+
+    # Store paginating items in @paginating_items array variable 
+    # @paginating_items = [
+    #   {title: "Data Structures", item: {id: 1}},
+    #   {title: "Excel Programming", item: {id: 2}},
+    #   {title: "Economics", item: {id: 3}},
+    #   {title: "Big Bang", item: {id: 4}},
+    #   {title: "Democracy Building", item: {id: 5}},
+    #   {title: "Python for Data Scientist", item: {id: 6}},
+    #   {title: "Money Mind", item: {id: 7}},
+    #   {title: "Design Patterns In C#", item: {id: 8}}
+    # ]
+
+    # Call the paginate method and store the return value in paginated_list 
+    # paginated_list = paginate
+
+    # Use the show menu method to get the paginated list items and return them as text and store in @menu_text
+    # @menu_text = show_menu(paginated_list, title: "Welcome to the <%= paginating_menu_name.camelcase %> menu", key: 'title')
+
+    # Get the selected item from the user with the `get_selected_item` method and save in state with @context.set_state
+    # if has_selected?
+    #   selected_book = get_selected_item
+    #   @context.set_state(selected_book: selected_book)
+    # end
+    end
+
+    def on_error
+        # Render error 
+        # @menu_text = "#{@error_text}\n#{@menu_text }"
+    end
+
+    def after_render
+        # Implement after call backs
+    end
+
+    def render
+        # Render paginating menu here or load the next menu after user has made a selection
+        # load_menu(Ussd::Menus::ShowBook)
+    end
+end

data/lib/generators/joy_route_menu/USAGE

@@ -0,0 +1,8 @@
+Description:
+    Explain the generator
+
+Example:
+    bin/rails generate joy_route_menu Thing
+
+    This will create:
+        what/will/it/create

data/lib/generators/joy_route_menu/joy_route_menu_generator.rb

@@ -0,0 +1,13 @@
+class JoyRouteMenuGenerator < Rails::Generators::Base
+  source_root File.expand_path('templates', __dir__)
+  argument :menu_name, type: :string
+
+  def generate_menu
+    create_menu
+  end
+
+  private
+  def create_menu
+    template 'joy_route_menu_template.template', "app/services/ussd/menus/#{menu_name.underscore}_menu.rb"
+  end
+end

data/lib/generators/joy_route_menu/templates/joy_route_menu_template.template

@@ -0,0 +1,36 @@
+class Ussd::Menus::<%= menu_name.camelcase %>Menu < JoyUssdEngine::Menu
+    def on_validate
+        # User input validation
+    end
+
+    def before_render
+        # Implement before call backs
+        # @field_name="<%= menu_name.underscore %>"
+
+        # title = "Welcome to the <%= menu_name.camelcase %> menu"
+
+        # Put menu routes in the @menu_items array
+        # @menu_items = [
+        #     {title: 'Make Payments', route: Ussd::Menus::SendMenu},
+        #     {title: 'View Transactions', route: Ussd::Menus::RequestMenu},
+        #     {title: 'Books', route: Ussd::Menus::Books}
+        # ]
+
+        # Render the menu out with show_menu and pass the title as a parameter to the `show_menu` method
+        # @menu_text = show_menu(title)
+    end
+
+    def on_error
+        # Render error 
+        # @menu_text = "#{@error_text}\n#{@menu_text }"
+    end
+
+    def after_render
+        # Implement after call backs
+    end
+
+    def render
+        # Render ussd menu and process to the selected menu when the user selects a menu.
+        # load_menu(get_selected_item)
+    end
+end

data/lib/joy_ussd_engine/data_transformer.rb

@@ -0,0 +1,35 @@
+module JoyUssdEngine
+        class DataTransformer   
+            # NOTE THIS CLASS SHOULD NEVER BE USED DIRECTLY BUT RATHER BE TREATED AS AN ABSTRACT CLASS
+            # THIS CLASS IS USED TO TRANSFORM REQUEST AND RESPONSE OBJECT FROM OUR USSD ENGINE 
+            # TO ONE A PROVIDER (Hubtel, Twilio, etc.) CAN UNDERSTAND
+            
+            # Responsible for transforming ussd requests and responses from different providers into 
+            # what our application can understand
+            attr_reader :context
+            def initialize(context)
+                @context = context
+            end
+
+            def request_params(params)
+                # transform request body of ussd provider currently in use to match the ussd engine request type
+            end
+            
+            def app_terminator(params)
+                #Checks to see if ussd app can be terminated by a particular provider depending on the response
+                return false
+            end
+
+            def response(message, next_menu = nil)
+                # Returns a tranformed ussd response for a particular provider and wait for user feedback
+            end
+
+            def release(message)
+                # Returns a tranformed ussd response for a particular provider and ends the ussd session
+            end
+
+            def expiration
+                # set expiration for different providers
+            end
+        end
+end

data/lib/joy_ussd_engine/menu.rb

@@ -0,0 +1,218 @@
+require 'will_paginate/array'
+module JoyUssdEngine
+    class Menu
+        # THIS CLASS IS THE BASE CLASS FOR ALL MENUS IN THE USSD ENGINE. EVERY MENU INHERITS FROM THIS CLASS AND IMPLEMENT THEIR CUSTOM BEHAVIOURS.
+
+        # NOTE THIS CLASS SHOULD NEVER BE USED DIRECTLY BUT RATHER BE TREATED AS AN ABSTRACT CLASS
+        # FROM WHICH OTHER CLASSES CAN INHERIT FROM AND IMPLEMENT CERTAIN CUSTOM BEHAVIOURS PERTAINING TO THEIR OPERATION
+
+        attr_reader :context
+        attr_accessor :field_name, :field_error, :errors, :skip_save, :previous_client_state, :current_client_state, :menu_text, :error_text, :menu_items, :menu_error, :previous_menu
+
+        def initialize(context)
+            @context = context
+            @current_client_state = @context.current_menu
+        end
+
+        def joy_response(client_state)
+            new_state = client_state.to_s
+            if @menu_text.blank?
+                set_previous_state
+                @context.current_menu = @current_client_state = new_state
+                return @context.load_menu(new_state)
+            end
+
+            { 
+                ClientState: new_state,
+                data: @context.selected_provider.send("response", @menu_text, new_state) 
+            }            
+        end
+
+        def joy_release(error_message = "")
+            @context.reset_state
+            { 
+                ClientState: "EndJoyUssdEngineiuewhjsdj",
+                data: @context.selected_provider.send("release", error_message.blank? ? @menu_text : error_message)
+            }
+        end
+
+        def load_menu(menu_to_load)
+            return render_menu_error[:data] if @menu_error
+            next_menu = menu_to_load.to_s
+            if has_selected?
+                @context.set_state({"#{@current_client_state}_show_menu_initiation".to_sym =>  nil})
+                set_previous_state 
+                @context.current_menu = @current_client_state = next_menu
+                @context.load_menu(next_menu) 
+            end
+        end
+
+        def show_menu(title = '')
+            raise_error("Sorry something went wrong!") if @menu_items.blank?
+            tmp_menu = []
+            
+            first_option = 0
+            @menu_items.each do |m|
+              tmp_menu << "#{first_option+=1}. #{m[:title]}"
+            end
+            text = tmp_menu.join("\n")
+            title.blank? ? text : "#{title}\n#{text}" 
+        end
+
+        def before_show_menu
+            is_first_render = @context.get_state[:"#{@current_client_state}_show_menu_initiation"].blank?
+            @context.set_state({"#{@current_client_state}_show_menu_initiation".to_sym => is_first_render ? "is_new" : "exists"})
+        end
+
+        def has_selected?
+            @context.get_state[:"#{@current_client_state}_show_menu_initiation"] == "exists"
+        end
+
+        def get_selected_item(error_message = "Sorry wrong option selected")
+
+            return unless has_selected?
+
+            selected_item = nil
+            check_input = is_numeric(@context.params[:message]) && @context.params[:message].to_i != 0  && !(@context.params[:message].to_i > @menu_items.length)
+
+            if check_input 
+                selected_item = @menu_items[@context.params[:message].to_i - 1][:route]
+            end
+
+            # 17332447
+            
+            @menu_error = selected_item.blank?
+            @error_text = error_message if @menu_error
+
+            selected_item
+        end
+
+        def is_numeric(numeric_string)
+            "#{numeric_string}" !~ /\D/
+        end
+
+        def before_render
+            # Implement before call backs
+            puts "before render passed"
+        end
+
+        def after_render
+            # Implement after call backs
+            puts "after render passed"
+        end
+
+        def save_state(state)
+            return if @skip_save
+            data = @context.get_state
+            @previous_client_state = @current_client_state
+            # @context.set_state({"#{data[:field]}".to_sym => @context.params[:message]}) unless data[:field].blank?
+            @context.set_state({ClientState: state, PrevClientState: @previous_client_state , field: @field_name, field_error: @field_error, error_text: @error_text})
+        end
+
+        def save_field_value
+            data = get_previous_state
+            return if @skip_save
+            @context.set_state({"#{data[:field]}".to_sym => @context.params[:message]}) unless data[:field].blank?
+        end
+
+        def get_previous_state
+            data = @context.get_state
+            @previous_client_state = data[:PrevClientState]
+            data
+        end
+
+        def set_previous_state
+            @context.set_state({PrevClientState: @current_client_state})
+        end
+
+        def render
+            # Render ussd menu here
+            puts "render passed"
+        end
+
+        def on_validate
+            
+        end
+
+        def on_error
+            
+        end
+
+        def raise_error(message)
+            @error_text = message
+            @menu_error = true
+        end
+
+        def render_menu_error
+            @context.reset_state
+            joy_release(@error_text)
+        end
+
+        def render_field_error
+            before_show_menu
+            before_render
+            on_error
+            return render_menu_error[:data] if menu_error
+            response = render
+            response = response.blank? ? joy_response(current_client_state) : response
+            after_render
+            save_state(response[:ClientState]) if response[:ClientState] != "EndJoyUssdEngineiuewhjsdj"
+            @context.reset_state if response[:ClientState] == "EndJoyUssdEngineiuewhjsdj" 
+            response[:data].blank? ? response : response[:data]
+        end
+
+        def render_previous
+           @context.current_menu = @previous_menu.current_client_state = @previous_client_state
+           @context.set_state({"#{@previous_client_state}_show_menu_initiation".to_sym =>  nil})
+           @previous_menu.render_field_error
+        end
+
+        def is_last_menu
+            @context.last_menu == @current_client_state
+        end
+
+        def allow_validation
+            !is_last_menu && !@previous_client_state.blank?
+        end
+
+        def do_validation
+            return unless allow_validation
+           @previous_menu = @previous_client_state.constantize.new(@context)
+           @previous_menu.on_validate
+        end
+
+        def run
+            save_field_value
+            do_validation
+            before_show_menu
+            before_render
+            return render_menu_error[:data] if @menu_error
+            if allow_validation
+                return render_previous if @previous_menu.field_error
+            end
+            response = render
+            response = response.blank? ? joy_response(@current_client_state) : response
+            after_render
+            save_state(response[:ClientState]) if response[:ClientState] != "EndJoyUssdEngineiuewhjsdj"
+            @context.reset_state if response[:ClientState] == "EndJoyUssdEngineiuewhjsdj" 
+            response
+        end
+
+        def execute
+            save_field_value
+            do_validation
+            before_show_menu
+            before_render
+            return render_menu_error[:data] if @menu_error
+            if allow_validation
+                return render_previous if @previous_menu.field_error
+            end
+            response = render
+            response = response.blank? ? joy_response(@current_client_state) : response
+            after_render
+            save_state(response[:ClientState]) if response[:ClientState] != "EndJoyUssdEngineiuewhjsdj"
+            @context.reset_state if response[:ClientState] == "EndJoyUssdEngineiuewhjsdj" 
+            response[:data].blank? ? response : response[:data]
+        end
+    end
+end

data/lib/joy_ussd_engine/paginate_menu.rb

@@ -0,0 +1,193 @@
+require 'will_paginate/array'
+module JoyUssdEngine
+    class PaginateMenu < JoyUssdEngine::Menu
+        # NOTE THIS CLASS SHOULD NEVER BE USED DIRECTLY BUT RATHER BE TREATED AS AN ABSTRACT CLASS
+        # FROM WHICH OTHER CLASSES CAN INHERIT FROM AND IMPLEMENT CERTAIN CUSTOM BEHAVIOURS PERTAINING TO THEIR OPERATION
+
+        # Paginating Menus will need to set entire collection in paginating_items, 
+        # The current_page is automatically determined from the user input and 
+        # the default values items_per_page, back_key, and next_key can be overiding in any class that inherits from the PaginatingMenu 
+        # Every paginating menu must set the current_client_state property to be their client_state this keeps track of pagination and menu location
+
+        # To paginate a menu you just call the `paginate` method and to display a paginated menu you call the `show_menu` method and pass the values returned from the `paginate` method. 
+        # To get a item the user selects from the menu just use the `get_selected_item` method
+        # EXAMPLE: 
+        # my_items = paginate
+        # show_menu(my_items)
+        # selected_item = get_selected_item
+        
+        attr_reader :paginating_items, :paginating_items_selector, :paginating_error, :current_page, :items_per_page, :back_key, :next_key 
+
+        def initialize(context)
+            super(context)
+            @items_per_page = 5
+            @back_key = '0'
+            @next_key = '#'
+        end
+
+        def paginate 
+
+            before_paginate
+            return [] if @paginating_error
+            
+            @current_page = get_current_page
+            
+            paginated_items = @paginating_items.to_a.paginate(page: @current_page, per_page: @items_per_page)
+
+            is_first_render = @context.get_state[:"#{@field_name}_paginate_initiation"].blank?
+
+            @context.set_state({"#{@field_name}_paginate".to_sym => @current_page, "#{@field_name}_paginated_list_size".to_sym => paginated_items.length, "#{@field_name}_list_size".to_sym => paginated_items.length, "#{@field_name}_paginate_initiation".to_sym => is_first_render ? "is_new" : "exists"})
+
+            paginated_items
+        end
+
+        def show_menu(items=[], title: '', key: '')
+
+            return if has_selected?
+            
+            @errors = true if @paginating_error || items.blank?
+            return @error_text if @paginating_error
+            return raise_error("Sorry something went wrong!") if items.blank?
+
+            more_menu = !is_last_page(@current_page, items.length)
+            back_menu = !is_first_page(@current_page) 
+
+            item_number = (@current_page - 1) * @items_per_page
+
+            tmp_menu = []
+            
+            first_option = item_number
+            items.each do |m|
+              tmp_menu << "#{first_option+=1}. #{key.blank? ? m : m[:"#{key}"]}"
+            end
+
+            tmp_menu << "#{back_key}. Back" if back_menu
+            tmp_menu << "#{next_key}. Next" if more_menu
+            text = tmp_menu.join("\n")
+            text = "#{title}\n#{text}" unless title.blank?
+            text
+        end
+
+        def load_menu(menu_to_load)
+            return render_menu_error[:data] if @menu_error
+            next_menu = menu_to_load.to_s
+            if has_selected?
+                @context.set_state({"#{@field_name}_paginate_initiation".to_sym =>  nil})
+                set_previous_state 
+                @context.current_menu = @current_client_state = next_menu
+                @context.load_from_paginate_menu(next_menu) 
+            end
+        end
+
+        def has_selected?
+            can_paginate? &&  ((@context.params[:message] != @next_key) && (@context.params[:message] != @back_key))
+        end
+
+        def can_paginate?
+            @context.get_state[:"#{@field_name}_paginate_initiation"] == 'exists'
+        end
+
+        def can_load_more?
+            !@context.get_state[:"#{@field_name}_paginate"].blank? &&
+            (@context.params[:message] == @next_key) && !is_last_page(get_previous_page, @context.get_state[:"#{@field_name}_paginated_list_size"])
+        end
+
+        def can_go_back?
+            !@context.get_state[:"#{@field_name}_paginate"].blank? &&
+            (@context.params[:message] == @back_key) && !is_first_page(get_previous_page)
+        end
+
+        def get_selected_item(error_message = "Sorry wrong option selected")
+
+            selected_item = nil
+            check_input = is_numeric(@context.params[:message]) && @context.params[:message].to_i != 0
+            if check_input 
+                selected_item = @paginating_items[@context.params[:message].to_i - 1]
+            end
+            
+
+            @paginating_error = selected_item.blank?
+            @error_text = error_message if @paginating_error
+            selected_item
+        end
+
+        def load_next_page
+            (@context.get_state[:"#{@field_name}_paginate"].to_i + 1)
+        end
+
+        def load_prev_page
+            (@context.get_state[:"#{@field_name}_paginate"].to_i - 1)
+        end
+
+        def get_previous_page
+            can_paginate? ? @context.get_state[:"#{@field_name}_paginate"] : 1
+        end
+
+        def get_current_page
+            return 1 unless !@context.get_state[:"#{@field_name}_paginate"].blank?
+            return load_prev_page if can_go_back?
+            return load_next_page if can_load_more?
+            @current_page
+        end
+
+        def check_input_errors?
+           @errors = (!can_load_more? && @context.params[:message] == @next_key) || (!can_go_back? && @context.params[:message] == @back_key)
+
+           @error_text = "Sorry invalid input" if @errors
+           @errors
+        end
+
+        def is_last_page(page_number, page_items_size)
+            (((page_number - 1) * 5) + page_items_size) >= @paginating_items.count
+        end
+
+        def is_first_page(page_number)
+            page_number.present? ? page_number == 1 : true
+        end
+
+        def before_paginate
+           @paginating_error = check_input_errors?
+        end
+
+        def before_render
+            # To use pagination in a particular menu we need to follow the other of execution in the before_render method
+            # 
+            # 1. {my_items = paginate} - first you have to execute the `paginate` method and cache the value
+            # 2. {show_menu(my_items)} - then you pass the cached value returned from the `paginate` method 
+            # and save in some data in some variable you will use in the `render` method to render the page.
+            # 3. {get_selected_item if has_selected?} - we use this to `get_selected_item` to return the item
+            # the user selected and we do so by checking if the user has selected an item with the `has_selected?` method
+        end
+
+        def render
+            # Paginating menu's render method calls the `load_menu` method to load a particular menu
+            # This can come from a selected paginating item
+            # load_menu(menu_name)
+
+            # Paginating menus also terminates the session with a `joy_release` method to end the ussd_application
+            # joy_release(@error_message - optional)
+        end
+
+        def render_previous
+            @context.current_menu = @previous_menu.current_client_state = @previous_client_state
+            @context.set_state({"#{@field_name}_paginate_initiation".to_sym =>  nil})
+            @previous_menu.render_field_error
+        end
+        
+        def execute
+            save_field_value
+            do_validation
+            before_render
+            return render_menu_error[:data] if @paginating_error || @menu_error
+            if allow_validation
+                return render_previous if @previous_menu.field_error
+            end
+            response = render
+            response = response.blank? ? joy_response(@current_client_state) : response
+            after_render
+            save_state(response[:ClientState]) if response[:ClientState] != "EndJoyUssdEngineiuewhjsdj"
+            @context.reset_state if response[:ClientState] == "EndJoyUssdEngineiuewhjsdj" 
+            response[:data].blank? ? response : response[:data]
+        end
+    end
+end