bianchi 0.1.0 → 0.1.1

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 6fe9c6aabbf8e704a9ea9403896cc71c9aedf9a5f8bf5a5433469dba9e80d40b
-  data.tar.gz: 4caa2699c795f348136640d2300e636c8ce2848daf7605a0596749507034286a
+  metadata.gz: 57689540f35b1837b227a23ec9b9badd237e5e1bda6b7f0b5c3d64443b404fd9
+  data.tar.gz: b963e56598337607ef36f0d4ebb514c9a83e354c3dc65d55d3ad299c856668b3
 SHA512:
-  metadata.gz: 3f56b2bf18384a755a4e6022b457e450c54efeb088926e112fca3b0ba6a7732a3762d83243a30572fd704c0131c816154e7cf4bbb3548fb489af5c0f11bdbec9
-  data.tar.gz: f763c36ef9616506fc87223383bb73487f0fc37901e8e14e99078970ad86c618b97f6b4602ef8140f95d182d23f62c23878fe72c68db9b84f3075ed3e5db8419
+  metadata.gz: 9272b56f5a057de49f9695cc615afcf05fbdcb14db6f31f582bf8d6b421b4dc8787ba5fbbcab87a120aaf4fd0519fad88c66f842423984915dbf271de3076207
+  data.tar.gz: ce5f129f37e80ff25fa642af17ae8d5f31b467f580419a7b053afe941979f6e09cf9183668a9443aea262c2d933f41a1656401098e6ef6d8d8ac26ed890b2d22

data/README.md

@@ -1,43 +1,197 @@
-# bianchi
+# Bianchi
+A DSL (Domain-Specific Language) and a minimalist framework in Ruby, tailored for USSD development. Structured around a menu page approach, Bianchi offers a comprehensive suite of methods and generators, streamlining the process of building USSD applications efficiently and easily.
 
-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/bianchi`. To experiment with that code, run `bin/console` for an interactive prompt.
+## Installation
+Add `gem 'bianchi', '~> 0.1.0'` to your gem file and run `bundle install`
 
-TODO: Delete this and the text above, and describe your gem
+Bianchi relies on Redis and requires the `REDIS_URL` environment variable to be set, pointing to your Redis instance. Ensure Redis is installed, running, and that REDIS_URL is correctly configured before using Bianchi.
 
-## Installation
+## Getting Started
+
+To initialize a new USSD project, generate a project directory using Bianchi's command-line interface. Use the following Ruby command:
+
+```ruby
+bundle exec bianchi setup -p provider_name
+```
+
+Replace `provider_name` with your desired provider. Currently supported providers include: africa_is_talking.
+
+This command creates a `ussd/engine.rb` file in the project root directory. Here's a sample content of `ussd/engine.rb`:
+
+```ruby
+module USSD
+  class Engine
+    def self.start(params)
+      Bianchi::USSD::Engine.start(params, provider: :africa_is_talking) do
+        # e.g menu :main, options
+      end
+    end
+  end
+end
+```
+
+To define menus for your USSD applications' engine instance, use the following command:
+
+```ruby
+menu :menu_name, options
+```
+
+For example, let's define our first menu, which serves as the initial menu of the application, and let's call this the main menu:
+
+```ruby
+menu :main, initial: true
+```
+now that we have the initial menu up let's generate our pages for that menu using Bianchi's command-line interface. Use the following Ruby command:
+```ruby
+command: bundle exec bianchi g menu menu_name page page_number
+example: bianchi g menu main page 1
+```
+This creates a `ussd/main_menu/page_1` file in the project root directory. Here's a sample content of the file:
+
+```ruby
+module USSD
+  module MainMenu
+    class Page1 < Bianchi::USSD::Page
+      def request
+      end
+
+      def response
+      end
+    end
+  end
+end
+```
 
-Add this line to your application's Gemfile:
+In the `ussd/main_menu/page_1` file, the main application code goes into the `request` and `response` methods. Here's a sample code to illustrate the usage:
 
 ```ruby
-gem 'bianchi'
+module USSD
+  module MainMenu
+    class Page1 < Bianchi::USSD::Page
+      def request
+        render_and_await(request_body)
+      end
+
+      def response
+        case session_input_body
+        when "1"
+          redirect_to_greetings_menu_page_1
+        when "2"
+          redirect_to_repeat_menu_page_1
+        else
+          render_and_await("invalid input \n" + request_body)
+        end
+      end
+
+      private
+
+      def request_body
+        <<~MSG
+          Welcome
+          1. Greetings
+          2. Repeat my name
+        MSG
+      end
+    end
+  end
+end
 ```
 
-And then execute:
+In this example, when a page is requested, you send some information, and the end user submits data for that request. The `response` method processes the response data and can move to a new page request, end the session, or send a response from there.
+### Page Renders
 
-    $ bundle install
+In Bianchi USSD applications, any method that starts with `render` sends data back to the user. Typically, we either send data and expect a response or send data and terminate the session. Here are the two main methods for rendering pages:
 
-Or install it yourself as:
+- `render_and_await(string)`: Responds to the user and expects the user to respond.
 
-    $ gem install bianchi
+- `render_and_end(string)`: Responds to the user and terminates the session.
 
-## Usage
+Here's how you can use these methods in Ruby:
+```ruby
+render_and_await("Please select an option:")
+```
+This method sends the message "Please select an option:" to the user and awaits their response.
+```ruby
+render_and_end("Thank you for using our service. Goodbye!")
+```
+This method sends the message "Thank you for using our service. Goodbye!" to the user and terminates the session.
+
+### Page Session
+
+In Bianchi USSD applications, the `session` serves as an information tracker between all the pages and records all interactions between the user and the application. It contains valuable information necessary for the USSD application to function properly.
+
+Here are the methods available within the page session:
+
+- `session_params`: Returns a hash containing all the data the provider sent.
+- `session_input_body`: Retrieves the user's current input.
+- `session_mobile_number`: Returns the current user's phone number dialing the code.
+- `session_session_id`: Provides the session's ID.
+- `session.store`: Accesses the current session's cache. Further details about this will be discussed later.
+
+### Page Store
+
+In Bianchi USSD applications, the `session.store` serves as the main application cache, where data can be stored and accessed across all pages.
+
+Here are the methods available within the page store:
+
+- `session.store.set(key, value)`: Stores a key-value pair in the cache.
+- `session.store.get(key)`: Retrieves the value associated with a given key from the cache.
+- `session.store.all`: Returns the entire cache as a hash.
 
-TODO: Write usage instructions here
+Here's how you can use these methods to manage your application's cache:
 
-## Development
+```ruby
+# Storing data in the cache
+session.store.set('user_id', 123)
+
+# Retrieving data from the cache
+user_id = session.store.get('user_id')
+
+# Retrieving the entire cache
+all_data = session.store.all
+```
+
+### Page Redirects
+
+In Bianchi USSD applications, any method that starts with `redirect_to` initiates another page request to be sent to the user. An example use case is when you want to transition to another menu page after processing the user's response.
 
-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.
+For instance, in the snippet of the main menu page provided earlier, we use `redirect_to_greetings_menu_page_1` when the user selects "1". This directs the application to the greetings menu page 1's request.
 
-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 the created tag, and push the `.gem` file to [rubygems.org](https://rubygems.org).
+Here are the methods available within the page redirects:
 
-## Contributing
+- `redirect_to_menu_[menu_name]_page_[page_number]`: Redirects to a specified menu using the `menu_name` and loads the page specified by `page_number`.
+- `redirect_to_[next|previous]_page`: Redirects to the next or previous page within the same menu.
 
-Bug reports and pull requests are welcome on GitHub at https://github.com/[USERNAME]/bianchi. This project is intended to be a safe, welcoming space for collaboration, and contributors are expected to adhere to the [code of conduct](https://github.com/[USERNAME]/bianchi/blob/master/CODE_OF_CONDUCT.md).
+Here's how you can use these methods within your Bianchi USSD application:
 
-## License
+```ruby
+# Redirecting to a specific menu page
+redirect_to_menu_greetings_page_1
+
+# Redirecting to the next or previous page in the same menu
+redirect_to_next_page
+redirect_to_previous_page
+```
 
-The gem is available as open source under the terms of the [MIT License](https://opensource.org/licenses/MIT).
+## Responding to the Provider
 
-## Code of Conduct
+Once all processes are completed, the next step is to prepare the response to send to the provider. The provider prompt data is accessible via the engine instance's `prompt_data` attribute.
 
-Everyone interacting in the bianchi project's codebases, issue trackers, chat rooms and mailing lists is expected to follow the [code of conduct](https://github.com/[USERNAME]/bianchi/blob/master/CODE_OF_CONDUCT.md).
+Here's an example of how you can retrieve the provider prompt data in your USSD application:
+
+```ruby
+module USSD
+  class Engine
+    def self.start(params)
+      Bianchi::USSD::Engine.start(params, provider: :africa_is_talking) do
+          menu :main, options
+          menu :greetings
+          menu :repeat
+      end
+    end
+  end
+end
+
+# Retrieving provider prompt data
+provider_data = USSD::Engine.new(provider_params).prompt_data
+```

data/bianchi.gemspec

@@ -6,7 +6,7 @@ Gem::Specification.new do |spec|
   spec.name          = "bianchi"
   spec.version       = Bianchi::VERSION
   spec.authors       = ["Dapilah Sydney"]
-  spec.email         = ['dapilah.sydney@gmail.com']
+  spec.email         = ["dapilah.sydney@gmail.com"]
 
   spec.summary       = "Write a short summary, because RubyGems requires one."
   spec.homepage      = "https://github.com/SydDaps/Bianchi"

data/lib/bianchi/cli/main.rb

@@ -1,6 +1,5 @@
 # frozen_string_literal: true
 
-# rubocop:disable Metrics/ParameterLists
 module Bianchi
   module Cli
     class Main < Thor
@@ -25,10 +24,10 @@ module Bianchi
         \x5 Example: `bianchi setup -p :africa_is_talking`
 
       LONG_DESC
-      method_option :provider, :aliases => "-p", type: :string, :desc => "Set up ussd project for provider"
+      method_option :provider, aliases: "-p", type: :string, desc: "Set up ussd project for provider"
       def setup
         @provider = options[:provider]
-        unless ["africa_is_talking", "none"].include? @provider
+        unless %w[africastalking none].include? @provider
           say("Error: provider #{@provider} is not yet configured.", :yellow)
           exit(1)
         end
@@ -63,4 +62,3 @@ module Bianchi
     end
   end
 end
-# rubocop:enable Metrics/ParameterLists

data/lib/bianchi/cli/templates/page.erb

@@ -1,11 +1,9 @@
 module USSD
   module <%= @menu_name.camelize %>Menu
     class Page<%= @page_number  %> < Bianchi::USSD::Page
-      def request
-      end
+      def request; end
 
-      def response
-      end
+      def response; end
     end
   end
 end

data/lib/bianchi/ussd/page.rb

@@ -29,8 +29,11 @@ module Bianchi
         page = constant_name.safe_constantize
 
         unless page
-          raise PageLoadError,
-                "#{constant_name} is supposed to be defined to process #{menu_name} menu #{page_number}"
+          raise PageLoadError, <<~MSG
+            \n
+            #{constant_name} is supposed to be defined to process #{menu_name} menu #{page_number}.
+            generate menu page with `bianchi g menu #{menu_name} page #{page_number[4..]}`
+          MSG
         end
 
         session.menu = Menu.new(menu_name)

data/lib/bianchi/ussd/provider_configurations.rb

@@ -3,10 +3,12 @@
 module Bianchi
   module USSD
     module ProviderConfigurations
+      include ProviderParsers::Africastalking
+
       def parse_params(params)
         provider_parsers = {
           none: proc { params },
-          africa_is_talking: proc { africa_is_talking_params_parser(params) }
+          africastalking: proc { africastalking_params_parser(params) }
         }.with_indifferent_access
 
         parser = provider_parsers[@provider]
@@ -16,27 +18,10 @@ module Bianchi
         parser.call
       end
 
-      def africa_is_talking_params_parser(params)
-        required_params = %w[sessionId phoneNumber text serviceCode]
-        left_required_params = required_params - params.keys.map(&:to_s)
-
-        unless left_required_params.empty?
-          raise ArgumentError, "#{left_required_params} required in params to start engine for provider #{@provider}"
-        end
-
-        {
-          session_id: params["sessionId"],
-          mobile_number: params["phoneNumber"],
-          activity_state: params["text"] && params["text"].empty? ? "initial" : "subsequent",
-          input_body: params["text"],
-          service_code: params["serviceCode"]
-        }
-      end
-
       def parser_prompt_data(prompt_data)
         provider_parsers = {
           none: proc { prompt_data },
-          africa_is_talking: proc { africa_is_talking_prompt_data_parser(prompt_data) }
+          africastalking: proc { africastalking_prompt_data_parser(prompt_data) }
         }.with_indifferent_access
 
         parser = provider_parsers[@provider]
@@ -45,10 +30,6 @@ module Bianchi
 
         parser.call
       end
-
-      def africa_is_talking_prompt_data_parser(prompt_data)
-        prompt_data["activity_state"] == :await ? "CON #{prompt_data['body']}" : "END #{prompt_data['body']}"
-      end
     end
   end
 end

data/lib/bianchi/ussd/provider_parsers/africastalking.rb

@@ -0,0 +1,28 @@
+module Bianchi
+  module USSD
+    module ProviderParsers
+      module Africastalking
+        def africastalking_params_parser(params)
+          required_params = %w[sessionId phoneNumber text serviceCode]
+          left_required_params = required_params - params.keys.map(&:to_s)
+
+          unless left_required_params.empty?
+            raise ArgumentError, "#{left_required_params} required in params to start engine for provider #{@provider}"
+          end
+
+          {
+            session_id: params["sessionId"],
+            mobile_number: params["phoneNumber"],
+            activity_state: params["text"] && params["text"].empty? ? "initial" : "subsequent",
+            input_body: params["text"].split("*").last,
+            service_code: params["serviceCode"]
+          }
+        end
+
+        def africastalking_prompt_data_parser(prompt_data)
+          prompt_data["activity_state"] == :await ? "CON #{prompt_data['body']}" : "END #{prompt_data['body']}"
+        end
+      end
+    end
+  end
+end

data/lib/bianchi/version.rb

@@ -1,5 +1,5 @@
 # frozen_string_literal: true
 
 module Bianchi
-  VERSION = "0.1.0"
+  VERSION = "0.1.1"
 end

data/lib/bianchi.rb

@@ -6,6 +6,7 @@ require "json"
 require "thor"
 
 require_relative "bianchi/version"
+require_relative "bianchi/ussd/provider_parsers/africastalking"
 require_relative "bianchi/ussd/provider_configurations"
 require_relative "bianchi/ussd/engine"
 require_relative "bianchi/ussd/menu"

data/ussd/engine.rb

@@ -1,7 +1,8 @@
+# frozen_string_literal: true
+
 module USSD
   class Engine
     def self.start(params)
-
       Bianchi::USSD::Engine.start(params, provider: :africa_is_talking) do
         # e.g menu :main, options
       end

data/ussd/main_menu/page_1.rb

@@ -1,11 +1,11 @@
+# frozen_string_literal: true
+
 module USSD
   module MainMenu
     class Page1 < Bianchi::USSD::Page
-      def request
-      end
+      def request; end
 
-      def response
-      end
+      def response; end
     end
   end
-end
+end

metadata

@@ -1,14 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: bianchi
 version: !ruby/object:Gem::Version
-  version: 0.1.0
+  version: 0.1.1
 platform: ruby
 authors:
 - Dapilah Sydney
 autorequire:
 bindir: exe
 cert_chain: []
-date: 2024-01-25 00:00:00.000000000 Z
+date: 2024-01-28 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: activesupport
@@ -98,6 +98,7 @@ files:
 - lib/bianchi/ussd/page.rb
 - lib/bianchi/ussd/page_delegators.rb
 - lib/bianchi/ussd/provider_configurations.rb
+- lib/bianchi/ussd/provider_parsers/africastalking.rb
 - lib/bianchi/ussd/session.rb
 - lib/bianchi/ussd/store.rb
 - lib/bianchi/version.rb