flow_chat 0.1.0

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA256:
+  metadata.gz: 77864972a34ad8761c6ce77a4f3574b9f45b4f8ef3210c34ca376812d0b54a41
+  data.tar.gz: 47b860cf8170d1cda13fa280ba92ba731c3060ca7d955b727b22ce8367ee8e97
+SHA512:
+  metadata.gz: fd997d03b94ce1051ab2ad6483b5864fb2b223b510d96d45833c7908a6928b419fdc4c5512730c80bf86e5f1b9741f2fc3d7c377a1f4ba8ea2b7baa0ed2244bf
+  data.tar.gz: c39477b7915c3abe9f2b1ff5c31b99eb3a618ecd2ab53e5405fb34e8564822510ad16dd94a2ceb664e33ada5549910c096b38e1a925e8609a3f73c855b392d3d

data/.gitignore

@@ -0,0 +1,14 @@
+/.bundle/
+/.yardoc
+/_yardoc/
+/coverage/
+/doc/
+/pkg/
+/spec/reports/
+/tmp/
+
+# rspec failure tracking
+.rspec_status
+
+# Ignore Gemfile.lock for our gem
+/Gemfile.lock

data/.rspec

@@ -0,0 +1,3 @@
+--format documentation
+--color
+--require spec_helper

data/.travis.yml

@@ -0,0 +1,6 @@
+---
+language: ruby
+cache: bundler
+rvm:
+  - 2.7.1
+before_install: gem install bundler -v 2.1.4

data/Gemfile

@@ -0,0 +1,7 @@
+source "https://rubygems.org"
+
+# Specify your gem's dependencies in flow_chat.gemspec
+gemspec
+
+gem "rake", "~> 12.0"
+gem "rspec", "~> 3.0"

data/LICENSE.txt

@@ -0,0 +1,21 @@
+The MIT License (MIT)
+
+Copyright (c) 2022 Stefan Froelich
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in
+all copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN
+THE SOFTWARE.

data/README.md

@@ -0,0 +1,39 @@
+# FlowChat
+
+Welcome to your new gem! In this directory, you'll find the files you need to be able to package up your Ruby library into a gem. Put your Ruby code in the file `lib/flow_chat`. To experiment with that code, run `bin/console` for an interactive prompt.
+
+TODO: Delete this and the text above, and describe your gem
+
+## Installation
+
+Add this line to your application's Gemfile:
+
+```ruby
+gem 'flow_chat'
+```
+
+And then execute:
+
+    $ bundle install
+
+Or install it yourself as:
+
+    $ gem install flow_chat
+
+## Usage
+
+TODO: Write usage instructions here
+
+## Development
+
+After checking out the repo, run `bin/setup` to install dependencies. Then, run `rake spec` to run the tests. You can also run `bin/console` for an interactive prompt that will allow you to experiment.
+
+To install this gem onto your local machine, run `bundle exec rake install`. To release a new version, update the version number in `version.rb`, and then run `bundle exec rake release`, which will create a git tag for the version, push git commits and tags, and push the `.gem` file to [rubygems.org](https://rubygems.org).
+
+## Contributing
+
+Bug reports and pull requests are welcome on GitHub at https://github.com/[USERNAME]/flow_chat.
+
+## License
+
+The gem is available as open source under the terms of the [MIT License](https://opensource.org/licenses/MIT).

data/Rakefile

@@ -0,0 +1,6 @@
+require "bundler/gem_tasks"
+require "rspec/core/rake_task"
+
+RSpec::Core::RakeTask.new(:spec)
+
+task default: :spec

data/bin/console

@@ -0,0 +1,14 @@
+#!/usr/bin/env ruby
+
+require "bundler/setup"
+require "flow_chat"
+
+# You can add fixtures and/or initialization code here to make experimenting
+# with your gem easier. You can also use a different console, if you like.
+
+# (If you use this, don't forget to add pry to your Gemfile!)
+# require "pry"
+# Pry.start
+
+require "irb"
+IRB.start(__FILE__)

data/bin/setup

@@ -0,0 +1,8 @@
+#!/usr/bin/env bash
+set -euo pipefail
+IFS=$'\n\t'
+set -vx
+
+bundle install
+
+# Do any other automated setup that you need to do here

data/flow_chat.gemspec

@@ -0,0 +1,35 @@
+require_relative "lib/flow_chat/version"
+
+Gem::Specification.new do |spec|
+  spec.name = "flow_chat"
+  spec.version = FlowChat::VERSION
+  spec.authors = ["Stefan Froelich"]
+  spec.email = ["sfroelich01@gmail.com"]
+
+  spec.summary = "Enable USSD processing support in Rails."
+  spec.description = "Enable USSD processing support in Rails."
+  spec.homepage = "https://github.com/ussd-engine/api-base"
+  spec.license = "MIT"
+  spec.required_ruby_version = Gem::Requirement.new(">= 2.3.0")
+
+  spec.metadata["allowed_push_host"] = "https://rubygems.org"
+
+  spec.metadata["homepage_uri"] = spec.homepage
+  spec.metadata["source_code_uri"] = spec.homepage
+  spec.metadata["changelog_uri"] = spec.homepage
+
+  # Specify which files should be added to the gem when it is released.
+  # The `git ls-files -z` loads the files in the RubyGem that have been added into git.
+  spec.files = Dir.chdir(File.expand_path("..", __FILE__)) do
+    `git ls-files -z`.split("\x0").reject { |f| f.match(%r{^(test|spec|features)/}) }
+  end
+  spec.bindir = "exe"
+  spec.executables = spec.files.grep(%r{^exe/}) { |f| File.basename(f) }
+  spec.require_paths = ["lib"]
+
+  spec.add_dependency "zeitwerk"
+  spec.add_dependency "activesupport", ">= 6"
+  spec.add_dependency "actionpack", ">= 6"
+  spec.add_dependency "phonelib"
+  spec.add_dependency "ibsciss-middleware", "~> 0.4.2"
+end

data/lib/flow_chat/config.rb

@@ -0,0 +1,16 @@
+module FlowChat
+  module Config
+    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"
+
+    mattr_accessor :resumable_sessions_enabled, default: false
+    mattr_accessor :resumable_sessions_global, default: true
+    mattr_accessor :resumable_sessions_timeout_seconds, default: 300
+  end
+end

data/lib/flow_chat/context.rb

@@ -0,0 +1,23 @@
+module FlowChat
+  class Context
+    def initialize
+      @data = {}.with_indifferent_access
+    end
+
+    def [](key)
+      @data[key]
+    end
+
+    def []=(key, value)
+      @data[key] = value
+    end
+
+    def session = @data["session"]
+
+    def controller = @data["controller"]
+
+    # def request = controller.request
+
+    def flow = @data["flow.class"]
+  end
+end

data/lib/flow_chat/interrupt.rb

@@ -0,0 +1,23 @@
+module FlowChat
+  module Interrupt
+    class Base < Exception
+      attr_reader :prompt
+
+      def initialize(prompt)
+        @prompt = prompt
+        super
+      end
+    end
+
+    class Prompt < Base
+      attr_reader :choices
+
+      def initialize(*args, choices: nil)
+        @choices = choices
+        super(*args)
+      end
+    end
+
+    class Terminate < Base; end
+  end
+end

data/lib/flow_chat/session/middleware.rb

@@ -0,0 +1,26 @@
+module FlowChat
+  module Session
+    class Middleware
+      def initialize(app)
+        @app = app
+      end
+
+      def call(context)
+        context["session.id"] = session_id 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]
+        # )
+      end
+    end
+  end
+end

data/lib/flow_chat/session/rails_session_store.rb

@@ -0,0 +1,33 @@
+module FlowChat
+  module Session
+    class RailsSessionStore
+      def initialize(context)
+        @session_id = context["session.id"]
+        @session_store = context.controller.session
+        @session_data = (session_store[session_id] || {}).with_indifferent_access
+      end
+
+      def get(key, default = nil)
+        session_data[key] || default
+      end
+
+      def set(key, value)
+        session_data[key] = value
+        session_store[session_id] = session_data
+        value
+      end
+
+      def delete(key)
+        set key, nil
+      end
+
+      def destroy
+        session_store[session_id] = nil
+      end
+
+      private
+
+      attr_reader :session_id, :session_store, :session_data
+    end
+  end
+end

data/lib/flow_chat/ussd/app.rb

@@ -0,0 +1,33 @@
+module FlowChat
+  module Ussd
+    class App
+      attr_reader :session, :input, :context, :navigation_stack
+
+      def initialize(context)
+        @context = context
+        @session = context["session"]
+        @input = context["request.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::Ussd::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 terminate!(msg)
+        raise FlowChat::Interrupt::Terminate.new(msg)
+      end
+    end
+  end
+end

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

@@ -0,0 +1,45 @@
+require "phonelib"
+
+module FlowChat
+  module Ussd
+    module Gateway
+      class Nalo
+        def initialize(app)
+          @app = app
+        end
+
+        def call(context)
+          params = context.controller.request.params
+
+          context["request.id"] = params["USERID"]
+          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
+
+          type, msg, choices = @app.call(context)
+
+          context.controller.render json: {
+            USERID: params["USERID"],
+            MSISDN: params["MSISDN"],
+            MSG: build_message(msg, choices),
+            MSGTYPE: type == :prompt
+          }
+        end
+
+        private
+
+        def build_message(msg, choices)
+          [msg, build_choices(choices)].compact.join "\n\n"
+        end
+
+        def build_choices(choices)
+          return unless choices.present?
+
+          choices.map { |i, c| "#{i}. #{c}" }.join "\n"
+        end
+      end
+    end
+  end
+end

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

@@ -0,0 +1,58 @@
+require "phonelib"
+
+module FlowChat
+  module Ussd
+    module Gateway
+      class Nsano
+        def initialize(app)
+          @app = app
+        end
+
+        def call(context)
+          controller = context["controller"]
+          request = controller.request
+
+          # input = context["rack.input"].read
+          # context["rack.input"].rewind
+          # if input.present?
+          #   params = JSON.parse input
+          #   if params["network"].present? && params["UserSessionID"].present?
+          #     request_id = "nsano::request_id::#{params["UserSessionID"]}"
+          #     context["ussd.request"] = {
+          #       provider: :nsano,
+          #       network: params["network"].to_sym,
+          #       msisdn: Phonelib.parse(params["msisdn"]).e164,
+          #       type: Config.cache&.read(request_id).present? ? :response : :initial,
+          #       input: params["msg"].presence,
+          #       network: params["network"]
+          #     }
+          #   end
+          # end
+
+          # status, headers, response = @app.call(context)
+
+          # if context["ussd.response"].present? && context["ussd.request"][:provider] == :nsano
+          #   if context["ussd.response"][:type] == :terminal
+          #     Config.cache&.write(request_id, nil)
+          #   else
+          #     Config.cache&.write(request_id, 1)
+          #   end
+
+          #   status = 200
+          #   response =
+          #     {
+          #       USSDResp: {
+          #         action: (context["ussd.response"][:type] == :terminal) ? :prompt : :input,
+          #         menus: "",
+          #         title: context["ussd.response"][:body]
+          #       }
+          #     }.to_json
+          #   headers = headers.merge({"Content-Type" => "application/json", "Content-Length" => response.bytesize.to_s})
+          #   response = [response]
+          # end
+          # [status, headers, response]
+        end
+      end
+    end
+  end
+end

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

@@ -0,0 +1,28 @@
+module FlowChat
+  module Ussd
+    module Middleware
+      class Executor
+        def initialize(app)
+          @app = app
+        end
+
+        def call(context)
+          ussd_app = build_ussd_app context
+          flow = context.flow.new ussd_app
+          flow.send context["flow.action"]
+        rescue FlowChat::Interrupt::Prompt => e
+          [:prompt, e.prompt, e.choices]
+        rescue FlowChat::Interrupt::Terminate => e
+          context.session.destroy
+          [:terminate, e.prompt, nil]
+        end
+
+        private
+
+        def build_ussd_app(context)
+          FlowChat::Ussd::App.new(context)
+        end
+      end
+    end
+  end
+end

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

@@ -0,0 +1,155 @@
+module FlowChat
+  module Ussd
+    module Middleware
+      class Pagination
+        def initialize(app)
+          @app = app
+        end
+
+        def call(context)
+          @context = context
+          @session = context.session
+
+          if intercept?
+            @context["ussd.response"] = handle_intercepted_request
+            [200, {}, [""]]
+          else
+            @session.delete "ussd.pagination"
+            res = @app.call(context)
+
+            if @context["ussd.response"].present?
+              @context["ussd.response"] = maybe_paginate @context["ussd.response"]
+            end
+
+            res
+          end
+        end
+
+        private
+
+        def intercept?
+          pagination_state.present? &&
+            (pagination_state[:type].to_sym == :terminal ||
+             ([Config.pagination_next_option, Config.pagination_back_option].include? @context["ussd.request"][:input]))
+        end
+
+        def handle_intercepted_request
+          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
+          body = pagination_state[:body][start..finish].strip + build_pagination_options(type, has_more)
+          set_pagination_state(current_page, start, finish)
+
+          {body: body, type: type}
+        end
+
+        def maybe_paginate(response)
+          if response[:body].length > Config.pagination_page_size
+            Config.logger&.info "FlowChat::Middleware::Pagination :: Response length (#{response[:body].length}) exceeds page size (#{Config.pagination_page_size}). Paginating."
+            body = response[:body][0..single_option_slice_size]
+            # Ensure we do not cut words and options off in the middle.
+            current_pagebreak = response[:body][single_option_slice_size + 1].blank? ? single_option_slice_size : body.rindex("\n") || body.rindex(" ") || single_option_slice_size
+            set_pagination_state(1, 0, current_pagebreak, response[:body], response[:type])
+            response[:body] = body[0..current_pagebreak].strip + "\n\n" + next_option
+            response[:type] = :prompt
+          end
+          response
+        end
+
+        def calculate_offsets
+          page = current_page
+          offset = pagination_state[:offsets][page]
+          if offset.present?
+            Config.logger&.debug "FlowChat::Middleware::Pagination :: Reusing cached offset for page: #{page}"
+            start = offset[:start]
+            finish = offset[:finish]
+            has_more = pagination_state[:body].length > finish
+          else
+            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_offset = pagination_state[:offsets][page - 1]
+            start = previous_offset[:finish] + 1
+            has_more, len = (pagination_state[:body].length > start + single_option_slice_size) ? [true, dual_options_slice_size] : [false, single_option_slice_size]
+            finish = start + len
+            if start > pagination_state[:body].length
+              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
+              body = pagination_state[:body][start..finish]
+              current_pagebreak = pagination_state[:body][finish + 1].blank? ? len : body.rindex("\n") || body.rindex(" ") || len
+              finish = start + current_pagebreak
+            end
+          end
+          [start, finish, has_more]
+        end
+
+        def build_pagination_options(type, has_more)
+          options_str = ""
+          has_less = current_page > 1
+          if type.to_sym == :prompt
+            options_str += "\n\n"
+            next_opt = has_more ? next_option : ""
+            back_opt = has_less ? back_option : ""
+            options_str += [next_opt, back_opt].join("\n").strip
+          end
+          options_str
+        end
+
+        def next_option
+          "#{Config.pagination_next_option} #{Config.pagination_next_text}"
+        end
+
+        def back_option
+          "#{Config.pagination_back_option} #{Config.pagination_back_text}"
+        end
+
+        def single_option_slice_size
+          unless @single_option_slice_size.present?
+            # 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
+          end
+          @single_option_slice_size
+        end
+
+        def dual_options_slice_size
+          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
+          end
+          @dual_options_slice_size
+        end
+
+        def current_page
+          current_page = pagination_state[:page]
+          if @context["ussd.request"][:input] == Config.pagination_back_option
+            current_page -= 1
+          elsif @context["ussd.request"][:input] == Config.pagination_next_option
+            current_page += 1
+          end
+          [current_page, 1].max
+        end
+
+        def pagination_state
+          @context.session.get("pagination", {})
+        end
+
+        def set_pagination_state(page, offset_start, offset_finish, body = nil, type = nil)
+          offsets = pagination_state[:offsets] || {}
+          offsets[page] = {start: offset_start, finish: offset_finish}
+          @session["ussd.pagination"] = {
+            page: page,
+            offsets: offsets,
+            body: body || pagination_state[:body],
+            type: type || pagination_state[:type]
+          }
+        end
+      end
+    end
+  end
+end

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

@@ -0,0 +1,52 @@
+module FlowChat
+  module Ussd
+    module Middleware
+      class ResumableSession
+        def initialize(app)
+          @app = app
+        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
+            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
+        end
+
+        private
+
+        def can_resume_session?(session)
+          return unless session["ussd.resumable_sessions"].present?
+          return true unless Config.resumable_sessions_timeout_seconds
+
+          last_active_at = Time.at(session["ussd.resumable_sessions"])
+          (Time.now - Config.resumable_sessions_timeout_seconds) < last_active_at
+        end
+      end
+    end
+  end
+end

data/lib/flow_chat/ussd/processor.rb

@@ -0,0 +1,54 @@
+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
+
+      def use_resumable_sessions
+        middleware.insert_before 0, FlowChat::Ussd::Middleware::ResumableSession
+        self
+      end
+
+      def use_pagination
+        middleware.use FlowChat::Ussd::Middleware::Pagination
+      end
+
+      def run(flow, action)
+        @context["flow.class"] = flow
+        @context["flow.action"] = action
+
+        ::Middleware::Builder.new name: "ussd" do |b|
+          b.use gateway
+          b.use FlowChat::Session::Middleware
+          # b.use FlowChat::Middleware::Pagination
+          b.use middleware
+          b.use FlowChat::Ussd::Middleware::Executor
+        end.inject_logger(Rails.logger).call(@context)
+      end
+    end
+  end
+end

data/lib/flow_chat/ussd/prompt.rb

@@ -0,0 +1,68 @@
+module FlowChat
+  module Ussd
+    class Prompt
+      attr_reader :user_input
+
+      def initialize(input)
+        @user_input = input
+      end
+
+      def ask(msg, choices: nil, convert: nil, validate: nil, transform: nil)
+        if user_input.present?
+          input = user_input
+          input = convert.call(input) if convert.present?
+          validation_error = validate.call(input) if validate.present?
+
+          prompt!([validation_error, msg].join("\n\n"), choices:) if validation_error.present?
+
+          input = transform.call(input) if transform.present?
+          return input
+        end
+
+        prompt! msg, choices:
+      end
+
+      def say(message)
+        terminate! message
+      end
+
+      def select(msg, 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).include?(choice) },
+          transform: lambda { |choice| choices[choice - 1] }
+        )
+      end
+
+      def yes?(msg)
+        select(msg, ["Yes", "No"]) == "Yes"
+      end
+
+      private
+
+      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:)
+        raise FlowChat::Interrupt::Prompt.new(msg, choices:)
+      end
+
+      def terminate!(msg)
+        raise FlowChat::Interrupt::Terminate.new(msg)
+      end
+    end
+  end
+end

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

@@ -0,0 +1,51 @@
+module FlowChat
+  module Ussd
+    module Simulator
+      module Controller
+        def ussd_simulator
+          respond_to do |format|
+            format.html do
+              render inline: simulator_view_template, layout: false, locals: simulator_locals
+            end
+          end
+        end
+
+        protected
+
+        def show_options
+          true
+        end
+
+        def default_msisdn
+          "233200123456"
+        end
+
+        def default_endpoint
+          "/ussd"
+        end
+
+        def default_provider
+          :nalo
+        end
+
+        def simulator_view_template
+          File.read simulator_view_path
+        end
+
+        def simulator_view_path
+          File.join FlowChat.root.join("flow_chat", "ussd", "simulator", "views", "simulator.html.erb")
+        end
+
+        def simulator_locals
+          {
+            pagesize: Config.pagination_page_size,
+            show_options: show_options,
+            default_msisdn: default_msisdn,
+            default_endpoint: default_endpoint,
+            default_provider: default_provider
+          }
+        end
+      end
+    end
+  end
+end

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

@@ -0,0 +1,239 @@
+<!DOCTYPE html>
+<html>
+  <head>
+    <title>FlowChat Ussd Simulator</title>
+    <style>
+      .content {
+        width: 320px;
+        margin: 100px auto;
+      }
+      .label {
+        display: inline-block;
+        width: 80px;
+        font-weight: bold;
+      }
+      .value {
+        display: inline;
+      }
+      .value select, input {
+        width: 200px;
+      }
+      .field {
+        margin: 5px;
+      }
+      #screen {
+        border: 1px black solid;
+        height:400px;
+        width:300px;
+        margin-top: 10px;
+        margin-bottom: 10px;
+        padding: 10px 5px;
+      }
+      #char-count {
+        text-align: center;
+        font-size: 10px;
+      }
+      .hidden {
+        display: none;
+      }
+    </style>
+  </head>
+  <body>
+    <div class="content">
+      <div class="field hidden<%=  show_options ? '' : 'hidden' %>">
+        <div class="label">Provider </div>
+        <div class="value">
+          <select id="provider">
+            <option <%=  default_provider == :nalo ? 'selected' : '' %> value="nalo">Nalo</option>
+            <option <%=  default_provider == :nsano ? 'selected' : '' %> value="nsano">Nsano</option>
+          </select>
+        </div>
+      </div>
+      <div class="field <%=  show_options ? '' : 'hidden' %>">
+        <div class="label">Endpoint </div>
+        <div class="value">
+          <input id="endpoint" value="<%= default_endpoint %>" />
+        </div>
+      </div>
+      <div class="field <%=  show_options ? '' : 'hidden' %>">
+        <div class="label">MSISDN </div>
+        <div class="value">
+          <input id="msisdn" value="<%= default_msisdn %>" />
+        </div>
+      </div>
+      <div id="screen"></div>
+      <div id="char-count"></div>
+      <div class="field">
+        <input id="data" disabled> <button id="respond" disabled>Respond</button>
+      </div>
+      <div class="field">
+        <button id="initiate" disabled>Initiate</button>
+        <button id="reset" disabled>Reset</button>
+      </div>
+    </div>
+    <script>
+      // Config
+      const pagesize = <%= pagesize %>
+
+      // View
+      const $screen = document.getElementById('screen')
+      const $charCount = document.getElementById('char-count')
+
+      const $provider = document.getElementById('provider')
+      const $endpoint = document.getElementById('endpoint')
+      const $msisdn = document.getElementById('msisdn')
+
+      const $data = document.getElementById('data')
+      const $respondBtn = document.getElementById('respond')
+      const $initiateBtn = document.getElementById('initiate')
+      const $resetBtn = document.getElementById('reset')
+
+      $provider.addEventListener('change', function (e) {
+        state.provider = $provider.value
+        render()
+      }, false)
+
+      $endpoint.addEventListener('keyup', function (e) {
+        state.endpoint = $endpoint.value
+        render()
+      }, false)
+
+      $msisdn.addEventListener('keyup', function (e) {
+        state.msisdn = $msisdn.value
+        render()
+      }, false)
+
+      $initiateBtn.addEventListener('click', function (e) {
+        makeRequest()
+      }, false)
+
+      $resetBtn.addEventListener('click',function(e){
+        reset()
+      }, false)
+
+      $respondBtn.addEventListener('click', function (e) {
+        makeRequest()
+      }, false)
+
+      function disableInputs() {
+        $data.disabled = 'disabled'
+        $respondBtn.disabled = 'disabled'
+        $initiateBtn.disabled = 'disabled'
+        $resetBtn.disabled = 'disabled'
+        $data.disabled = 'disabled'
+      }
+
+      function enableResponse() {
+        $data.disabled = false
+        $respondBtn.disabled = false
+        $resetBtn.disabled = false
+      }
+
+      function display(text) {
+        $screen.innerText = text.substr(0, pagesize)
+        if(text.length > 0)
+          $charCount.innerText = `${text.length} chars`
+        else
+          $charCount.innerText = ''
+      }
+
+      function render() {
+        disableInputs()
+
+        if(!state.isRunning){
+          if(state.provider && state.endpoint && state.msisdn)
+            $initiateBtn.disabled = false
+          else
+            $initiateBtn.disabled = 'disabled'
+        }
+        else {
+          enableResponse()
+        }
+      }
+
+      // State
+      const state = {}
+
+      function reset(shouldRender) {
+        state.isRunning = false
+        state.request_id = btoa(Math.random().toString()).substr(10, 10)
+        state.provider = $provider.value
+        state.endpoint = $endpoint.value
+        state.msisdn = $msisdn.value
+
+        $data.value = null
+
+        display("")
+        if(shouldRender !== false) render()
+      }
+
+
+      // API
+
+      function makeRequest() {
+        var data = {}
+
+        switch (state.provider) {
+          case "nalo":
+            data = {
+              USERID: state.request_id,
+              MSISDN: state.msisdn,
+              USERDATA: $data.value,
+              MSGTYPE: !state.isRunning,
+            }
+            break;
+          case "nsano":
+            data = {
+              network: 'MTN',
+              msisdn: state.msisdn,
+              msg: $data.value,
+              UserSessionID: state.request_id,
+            }
+            break;
+
+          default:
+            alert(`Unhandled provider request: ${state.provider}`)
+            return
+        }
+
+        disableInputs()
+        fetch(state.endpoint, {
+          method: 'POST',
+          headers: {
+            'Content-Type': 'application/json'
+          },
+          redirect: 'error',
+          body: JSON.stringify(data)
+        })
+          .then(response => {
+            if (!response.ok) {
+                throw Error(`${response.status}: ${response.statusText}`);
+            }
+            return response.json()
+          })
+          .then(data => {
+            switch (state.provider) {
+              case "nalo":
+                display(data.MSG)
+                state.isRunning = data.MSGTYPE
+                break;
+              case "nsano":
+                display(data.USSDResp.title)
+                state.isRunning = data.USSDResp.action == "input"
+                break;
+
+              default:
+                alert(`Unhandled provider response: ${state.provider}`)
+                return
+            }
+            $data.value = null
+          })
+          .catch(error => alert(error.message))
+          .finally(render);
+      }
+
+      // run the app
+      reset()
+    </script>
+  </body>
+</html>

data/lib/flow_chat/version.rb

@@ -0,0 +1,3 @@
+module FlowChat
+  VERSION = "0.1.0"
+end

data/lib/flow_chat.rb

@@ -0,0 +1,14 @@
+require "zeitwerk"
+require "active_support"
+
+loader = Zeitwerk::Loader.for_gem
+loader.enable_reloading if defined?(Rails.env) && Rails.env.development?
+loader.setup
+
+module FlowChat
+  def self.root
+    Pathname.new __dir__
+  end
+end
+
+loader.eager_load

metadata

@@ -0,0 +1,144 @@
+--- !ruby/object:Gem::Specification
+name: flow_chat
+version: !ruby/object:Gem::Version
+  version: 0.1.0
+platform: ruby
+authors:
+- Stefan Froelich
+autorequire:
+bindir: exe
+cert_chain: []
+date: 2024-04-04 00:00:00.000000000 Z
+dependencies:
+- !ruby/object:Gem::Dependency
+  name: zeitwerk
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '0'
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '0'
+- !ruby/object:Gem::Dependency
+  name: activesupport
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '6'
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '6'
+- !ruby/object:Gem::Dependency
+  name: actionpack
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '6'
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '6'
+- !ruby/object:Gem::Dependency
+  name: phonelib
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '0'
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '0'
+- !ruby/object:Gem::Dependency
+  name: ibsciss-middleware
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: 0.4.2
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: 0.4.2
+description: Enable USSD processing support in Rails.
+email:
+- sfroelich01@gmail.com
+executables: []
+extensions: []
+extra_rdoc_files: []
+files:
+- ".gitignore"
+- ".rspec"
+- ".travis.yml"
+- Gemfile
+- LICENSE.txt
+- README.md
+- Rakefile
+- bin/console
+- bin/setup
+- flow_chat.gemspec
+- lib/flow_chat.rb
+- lib/flow_chat/config.rb
+- lib/flow_chat/context.rb
+- lib/flow_chat/interrupt.rb
+- lib/flow_chat/session/middleware.rb
+- lib/flow_chat/session/rails_session_store.rb
+- lib/flow_chat/ussd/app.rb
+- lib/flow_chat/ussd/gateway/nalo.rb
+- lib/flow_chat/ussd/gateway/nsano.rb
+- lib/flow_chat/ussd/middleware/executor.rb
+- lib/flow_chat/ussd/middleware/pagination.rb
+- lib/flow_chat/ussd/middleware/resumable_session.rb
+- lib/flow_chat/ussd/processor.rb
+- lib/flow_chat/ussd/prompt.rb
+- lib/flow_chat/ussd/simulator/controller.rb
+- lib/flow_chat/ussd/simulator/views/simulator.html.erb
+- lib/flow_chat/version.rb
+homepage: https://github.com/ussd-engine/api-base
+licenses:
+- MIT
+metadata:
+  allowed_push_host: https://rubygems.org
+  homepage_uri: https://github.com/ussd-engine/api-base
+  source_code_uri: https://github.com/ussd-engine/api-base
+  changelog_uri: https://github.com/ussd-engine/api-base
+post_install_message:
+rdoc_options: []
+require_paths:
+- lib
+required_ruby_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: 2.3.0
+required_rubygems_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: '0'
+requirements: []
+rubygems_version: 3.5.6
+signing_key:
+specification_version: 4
+summary: Enable USSD processing support in Rails.
+test_files: []