flow_chat 0.1.0 → 0.2.1

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 77864972a34ad8761c6ce77a4f3574b9f45b4f8ef3210c34ca376812d0b54a41
-  data.tar.gz: 47b860cf8170d1cda13fa280ba92ba731c3060ca7d955b727b22ce8367ee8e97
+  metadata.gz: 6c1e5cd739c50f112b6a5637e712756e0b96bdb18c2276c7d30db2b2a071cc23
+  data.tar.gz: f701ad5050599c06b87eba80841823b04eef156e7ea3e77527a0be91519b0d48
 SHA512:
-  metadata.gz: fd997d03b94ce1051ab2ad6483b5864fb2b223b510d96d45833c7908a6928b419fdc4c5512730c80bf86e5f1b9741f2fc3d7c377a1f4ba8ea2b7baa0ed2244bf
-  data.tar.gz: c39477b7915c3abe9f2b1ff5c31b99eb3a618ecd2ab53e5405fb34e8564822510ad16dd94a2ceb664e33ada5549910c096b38e1a925e8609a3f73c855b392d3d
+  metadata.gz: ef7e1721b7c5453130999b2ef899af4f20ba6db81ac4b3956ce7ade5956bf2b61e248b2be66ace885c633d4d612025208b31d1ff081ef1a0d671f579e0d3db38
+  data.tar.gz: 2581189b102229a0e8843691f38eaf91a9c7bf1d2db7c7a71e685124a849621cf55bdd33c6cdd1c928e2bfac051bca597601875dc9cff921063a98ff954a7b82

data/README.md

@@ -1,28 +1,147 @@
 # 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.
+FlowChat is a Rails framework designed for crafting Menu-based conversation workflows, such as those used in USSD systems. It introduces an intuitive approach to defining conversation flows in Ruby, facilitating clear and logical flow development. Currently supporting USSD with plans to extend functionality to WhatsApp and Telegram, FlowChat makes multi-channel user interaction seamless and efficient.
 
-TODO: Delete this and the text above, and describe your gem
+The framework's architecture leverages a middleware processing pipeline, offering flexibility in customizing the conversation handling process.
 
-## Installation
+## Getting Started
 
-Add this line to your application's Gemfile:
+### Installation
+
+Incorporate FlowChat into your Rails project by adding the following line to your Gemfile:
 
 ```ruby
-gem 'flow_chat'
+gem 'flow_chat', '~> 0.2.0'
+```
+
+Then, execute:
+
+```bash
+bundle install
 ```
 
-And then execute:
+Alternatively, you can install it directly using:
+
+```bash
+gem install flow_chat
+```
+
+### Basic Usage
+
+#### Building Your First Flow
+
+Create a new class derived from `FlowChat::Flow` to define your conversation flow. It's recommended to place your flow definitions under `app/flow_chat`.
+
+For a simple "Hello World" flow:
+
+```ruby
+class HelloWorldFlow < FlowChat::Flow
+  def main_page
+    app.say "Hello World!"
+  end
+end
+```
+
+The `app` instance within `FlowChat::Flow` provides methods to interact with and respond to the user, such as `app.say`, which sends a message to the user.
+
+#### Integration with USSD
+
+Given that most USSD gateways interact via HTTP, set up a controller to handle the conversation flow:
+
+```ruby
+class UssdDemoController < ApplicationController
+  skip_forgery_protection
+
+  def hello_world
+    ussd_processor.run HelloWorldFlow, :main_page
+  end
+
+  private
+
+  def ussd_processor
+    @ussd_processor ||= FlowChat::Ussd::Processor.new(self) do |processor|
+      processor.use_gateway FlowChat::Ussd::Gateway::Nalo
+      processor.use_session_store FlowChat::Session::RailsSessionStore
+    end
+  end
+end
+```
+
+This controller initializes a `FlowChat::Ussd::Processor` specifying the use of Nalo Solutions' gateway and a session storage mechanism. Here, `RailsSessionStore` is chosen for simplicity and demonstration purposes.
+
+Bind the controller action to a route:
 
-    $ bundle install
+```ruby
+Rails.application.routes.draw do
+  post 'ussd_hello_world' => 'ussd_demo#hello_world'
+end
+```
+
+#### Testing with the USSD Simulator
+
+FlowChat comes with a USSD simulator for local testing:
+
+```ruby
+class UssdSimulatorController < ApplicationController
+  include FlowChat::Ussd::Simulator::Controller
+
+  protected
+
+  def default_endpoint
+    '/ussd_hello_world'
+  end
+
+  def default_provider
+    :nalo
+  end
+end
+```
+
+And set up the corresponding route:
+
+```ruby
+Rails.application.routes.draw do
+  get 'ussd_simulator' => 'ussd_simulator#ussd_simulator'
+end
+```
+
+Visit [http://localhost:3000/ussd_simulator](http://localhost:3000/ussd_simulator) to initiate and test your flow.
+
+### Advanced Usage: Implementing Multiple Screens
+
+To engage users with a multi-step interaction, define a flow with multiple screens:
+
+```ruby
+class MultipleScreensFlow < FlowChat::Flow
+  def main_page
+    name = app.screen(:name) { |prompt|
+      prompt.ask "What is your name?", transform: ->(input) { input.squish }
+    }
+
+    age = app.screen(:age) do |prompt|
+      prompt.ask "How old are you?",
+        convert: ->(input) { input.to_i },
+        validate: ->(input) { "You must be at least 13 years old" unless input >= 13 }
+    end
+
+    gender = app.screen(:gender) { |prompt| prompt.select "What is your gender", ["Male", "Female"] }
+
+    confirm = app.screen(:confirm) do |prompt|
+      prompt.yes?("Is this correct?\n\nName: #{name}\nAge: #{age}\nGender: #{gender}")
+    end
+
+    app.say confirm ? "Thank you for confirming" : "Please try again"
+  end
+end
+```
 
-Or install it yourself as:
+This example illustrates a flow that collects and confirms user information across multiple interaction steps, showcasing FlowChat's capability to handle complex conversation logic effortlessly.
 
-    $ gem install flow_chat
+TODO:
 
-## Usage
+### Sub Flows
 
-TODO: Write usage instructions here
+TODO:
 
 ## Development
 

data/flow_chat.gemspec

@@ -6,9 +6,9 @@ Gem::Specification.new do |spec|
   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.summary = "Framework for building Menu based conversations (e.g. USSD) in Rails."
+  spec.description = "Framework for building Menu based conversations (e.g. USSD) in Rails."
+  spec.homepage = "https://github.com/radioactive-labs/flow_chat"
   spec.license = "MIT"
   spec.required_ruby_version = Gem::Requirement.new(">= 2.3.0")
 

data/lib/flow_chat/context.rb

@@ -12,6 +12,8 @@ module FlowChat
       @data[key] = value
     end
 
+    def input = @data["request.input"]
+
     def session = @data["session"]
 
     def controller = @data["controller"]

data/lib/flow_chat/flow.rb

@@ -0,0 +1,9 @@
+module FlowChat
+  class Flow
+    attr_reader :app
+
+    def initialize(app)
+      @app = app
+    end
+  end
+end

data/lib/flow_chat/session/rails_session_store.rb

@@ -7,8 +7,8 @@ module FlowChat
         @session_data = (session_store[session_id] || {}).with_indifferent_access
       end
 
-      def get(key, default = nil)
-        session_data[key] || default
+      def get(key)
+        session_data[key]
       end
 
       def set(key, value)

data/lib/flow_chat/ussd/app.rb

@@ -5,8 +5,8 @@ module FlowChat
 
       def initialize(context)
         @context = context
-        @session = context["session"]
-        @input = context["request.input"]
+        @session = context.session
+        @input = context.input
         @navigation_stack = []
       end
 
@@ -25,7 +25,7 @@ module FlowChat
         value
       end
 
-      def terminate!(msg)
+      def say(msg)
         raise FlowChat::Interrupt::Terminate.new(msg)
       end
     end

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

@@ -18,26 +18,20 @@ module FlowChat
           # context["request.type"] = params["MSGTYPE"] ? :initial : :response
           context["request.input"] = params["USERDATA"].presence
 
-          type, msg, choices = @app.call(context)
+          type, prompt, choices = @app.call(context)
 
           context.controller.render json: {
             USERID: params["USERID"],
             MSISDN: params["MSISDN"],
-            MSG: build_message(msg, choices),
+            MSG: render_prompt(prompt, 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"
+        def render_prompt(prompt, choices)
+          FlowChat::Ussd::Renderer.new(prompt, choices).render
         end
       end
     end

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

@@ -11,17 +11,16 @@ module FlowChat
           @session = context.session
 
           if intercept?
-            @context["ussd.response"] = handle_intercepted_request
-            [200, {}, [""]]
+            type, prompt = handle_intercepted_request
+            [type, prompt, []]
           else
             @session.delete "ussd.pagination"
-            res = @app.call(context)
+            type, prompt, choices = @app.call(context)
 
-            if @context["ussd.response"].present?
-              @context["ussd.response"] = maybe_paginate @context["ussd.response"]
-            end
+            prompt = FlowChat::Ussd::Renderer.new(prompt, choices).render
+            type, prompt = maybe_paginate(type, prompt) if prompt.present?
 
-            res
+            [type, prompt, []]
           end
         end
 
@@ -29,57 +28,59 @@ module FlowChat
 
         def intercept?
           pagination_state.present? &&
-            (pagination_state[:type].to_sym == :terminal ||
-             ([Config.pagination_next_option, Config.pagination_back_option].include? @context["ussd.request"][:input]))
+            (pagination_state["type"].to_sym == :terminal ||
+             ([Config.pagination_next_option, Config.pagination_back_option].include? @context.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)
+          type = (pagination_state["type"].to_sym == :terminal && !has_more) ? :terminal : :prompt
+          prompt = pagination_state["prompt"][start..finish].strip + build_pagination_options(type, has_more)
           set_pagination_state(current_page, start, finish)
 
-          {body: body, type: type}
+          [type, prompt]
         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]
+        def maybe_paginate(type, prompt)
+          if prompt.length > Config.pagination_page_size
+            original_prompt = prompt
+            Config.logger&.info "FlowChat::Middleware::Pagination :: Response length (#{prompt.length}) exceeds page size (#{Config.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 = 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
+            current_pagebreak = prompt[single_option_slice_size + 1].blank? ? single_option_slice_size : prompt.rindex("\n") || prompt.rindex(" ") || single_option_slice_size
+            set_pagination_state(1, 0, current_pagebreak, original_prompt, type)
+            prompt = prompt[0..current_pagebreak].strip + "\n\n" + next_option
+            type = :prompt
           end
-          response
+          [type, prompt]
         end
 
         def calculate_offsets
           page = current_page
-          offset = pagination_state[:offsets][page]
+          offset = pagination_state["offsets"][page.to_s]
           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
+            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}"
             # 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]
+            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[:body].length
+            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
               has_more = false
-              start = previous_offset[:start]
-              finish = previous_offset[:finish]
+              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
+              prompt = pagination_state["prompt"][start..finish]
+              current_pagebreak = pagination_state["prompt"][finish + 1].blank? ? len : prompt.rindex("\n") || prompt.rindex(" ") || len
               finish = start + current_pagebreak
             end
           end
@@ -126,28 +127,31 @@ module FlowChat
         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
+          page = pagination_state["page"]
+          if @context.input == Config.pagination_back_option
+            page -= 1
+          elsif @context.input == Config.pagination_next_option
+            page += 1
           end
-          [current_page, 1].max
+          [page, 1].max
         end
 
         def pagination_state
-          @context.session.get("pagination", {})
+          @pagination_state ||= @context.session.get("ussd.pagination") || {}
         end
 
-        def set_pagination_state(page, offset_start, offset_finish, body = nil, type = nil)
-          offsets = pagination_state[:offsets] || {}
+        def set_pagination_state(page, offset_start, offset_finish, prompt = nil, type = nil)
+          offsets = pagination_state["offsets"] || {}
           offsets[page] = {start: offset_start, finish: offset_finish}
-          @session["ussd.pagination"] = {
-            page: page,
-            offsets: offsets,
-            body: body || pagination_state[:body],
-            type: type || pagination_state[:type]
+          prompt ||= pagination_state["prompt"]
+          type ||= pagination_state["type"]
+          @pagination_state = {
+            "page" => page,
+            "offsets" => offsets,
+            "prompt" => prompt,
+            "type" => type
           }
+          @session.set "ussd.pagination", @pagination_state
         end
       end
     end

data/lib/flow_chat/ussd/processor.rb

@@ -33,21 +33,22 @@ module FlowChat
         self
       end
 
-      def use_pagination
-        middleware.use FlowChat::Ussd::Middleware::Pagination
-      end
-
-      def run(flow, action)
-        @context["flow.class"] = flow
+      def run(flow_class, action)
+        @context["flow.name"] = flow_class.name.underscore
+        @context["flow.class"] = flow_class
         @context["flow.action"] = action
 
-        ::Middleware::Builder.new name: "ussd" do |b|
+        stack = ::Middleware::Builder.new name: "ussd" do |b|
           b.use gateway
           b.use FlowChat::Session::Middleware
-          # b.use FlowChat::Middleware::Pagination
+          b.use FlowChat::Ussd::Middleware::Pagination
           b.use middleware
           b.use FlowChat::Ussd::Middleware::Executor
-        end.inject_logger(Rails.logger).call(@context)
+        end.inject_logger(Rails.logger)
+
+        yield stack if block_given?
+
+        stack.call(@context)
       end
     end
   end

data/lib/flow_chat/ussd/renderer.rb

@@ -0,0 +1,26 @@
+module FlowChat
+  module Ussd
+    class Renderer
+      attr_reader :prompt, :choices
+
+      def initialize(prompt, choices)
+        @prompt = prompt
+        @choices = choices
+      end
+
+      def render = build_prompt
+
+      private
+
+      def build_prompt
+        [prompt, build_choices].compact.join "\n\n"
+      end
+
+      def build_choices
+        return unless choices.present?
+
+        choices.map { |i, c| "#{i}. #{c}" }.join "\n"
+      end
+    end
+  end
+end

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

@@ -40,22 +40,22 @@
   </head>
   <body>
     <div class="content">
-      <div class="field hidden<%=  show_options ? '' : 'hidden' %>">
+      <div class="field <%= 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>
+            <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="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="field <%= show_options ? '' : 'hidden' %>">
         <div class="label">MSISDN </div>
         <div class="value">
           <input id="msisdn" value="<%= default_msisdn %>" />

data/lib/flow_chat/version.rb

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

metadata

@@ -1,14 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: flow_chat
 version: !ruby/object:Gem::Version
-  version: 0.1.0
+  version: 0.2.1
 platform: ruby
 authors:
 - Stefan Froelich
 autorequire:
 bindir: exe
 cert_chain: []
-date: 2024-04-04 00:00:00.000000000 Z
+date: 2024-04-05 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: zeitwerk
@@ -80,13 +80,14 @@ dependencies:
     - - "~>"
       - !ruby/object:Gem::Version
         version: 0.4.2
-description: Enable USSD processing support in Rails.
+description: Framework for building Menu based conversations (e.g. USSD) in Rails.
 email:
 - sfroelich01@gmail.com
 executables: []
 extensions: []
 extra_rdoc_files: []
 files:
+- ".DS_Store"
 - ".gitignore"
 - ".rspec"
 - ".travis.yml"
@@ -97,9 +98,11 @@ files:
 - bin/console
 - bin/setup
 - flow_chat.gemspec
+- images/ussd_simulator.png
 - lib/flow_chat.rb
 - lib/flow_chat/config.rb
 - lib/flow_chat/context.rb
+- lib/flow_chat/flow.rb
 - lib/flow_chat/interrupt.rb
 - lib/flow_chat/session/middleware.rb
 - lib/flow_chat/session/rails_session_store.rb
@@ -111,17 +114,18 @@ files:
 - lib/flow_chat/ussd/middleware/resumable_session.rb
 - lib/flow_chat/ussd/processor.rb
 - lib/flow_chat/ussd/prompt.rb
+- lib/flow_chat/ussd/renderer.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
+homepage: https://github.com/radioactive-labs/flow_chat
 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
+  homepage_uri: https://github.com/radioactive-labs/flow_chat
+  source_code_uri: https://github.com/radioactive-labs/flow_chat
+  changelog_uri: https://github.com/radioactive-labs/flow_chat
 post_install_message:
 rdoc_options: []
 require_paths:
@@ -140,5 +144,5 @@ requirements: []
 rubygems_version: 3.5.6
 signing_key:
 specification_version: 4
-summary: Enable USSD processing support in Rails.
+summary: Framework for building Menu based conversations (e.g. USSD) in Rails.
 test_files: []