flow_chat 0.2.0 → 0.2.1

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 6eba909e6ae38dfeb26be6f854b185ca2c8097397aa4eea8a094d47e1d3fcd56
-  data.tar.gz: c47e6bf434684b87c7f0c8b2ebb9b6536c5bc17efe46fa3bec3876b976401f96
+  metadata.gz: 6c1e5cd739c50f112b6a5637e712756e0b96bdb18c2276c7d30db2b2a071cc23
+  data.tar.gz: f701ad5050599c06b87eba80841823b04eef156e7ea3e77527a0be91519b0d48
 SHA512:
-  metadata.gz: f52ba0115aa8000f9de120d436c9800318c8635efa86979b17f2dc01104d6ae65f66dcc193ada68a0a36ff238e9b6a87ef9ee66e00581ca4b5faa72a31fb25a0
-  data.tar.gz: 508138465e83f318e8e889f4e11ea19a709fc06c310b76c44388f56b84c94521fa44b45cc734fcfc07acf3b1cf38bbc764614e1d7252ee7b40ab4e0a20c55877
+  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,8 +6,8 @@ Gem::Specification.new do |spec|
   spec.authors = ["Stefan Froelich"]
   spec.email = ["sfroelich01@gmail.com"]
 
-  spec.summary = "Framework for processing Menu based conversations e.g. USSD in Rails."
-  spec.description = "Framework for processing Menu based conversations e.g. USSD in Rails."
+  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/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/ussd/app.rb

@@ -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/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.2.0"
+  VERSION = "0.2.1"
 end

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: flow_chat
 version: !ruby/object:Gem::Version
-  version: 0.2.0
+  version: 0.2.1
 platform: ruby
 authors:
 - Stefan Froelich
@@ -80,13 +80,14 @@ dependencies:
     - - "~>"
       - !ruby/object:Gem::Version
         version: 0.4.2
-description: Framework for processing Menu based conversations e.g. USSD 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
@@ -141,5 +144,5 @@ requirements: []
 rubygems_version: 3.5.6
 signing_key:
 specification_version: 4
-summary: Framework for processing Menu based conversations e.g. USSD in Rails.
+summary: Framework for building Menu based conversations (e.g. USSD) in Rails.
 test_files: []