ExUssd

Goals:

• An idiomatic, readable, and comfortable API for Elixir developers
• Extensibility based on small parts that do one thing well.
• Detailed error messages and documentation.
• A focus on robustness and production-level performance.

Table of contents

• Why Use ExUssd
• Documentation
• Installation
• Configuration
• Usage
• Contribution
• Contributors
• Licence

Why Use ExUssd?

ExUssd lets you create simple, flexible, and customizable USSD interface. Under the hood ExUssd uses Elixir Registry to create and route individual USSD session.

https://user-images.githubusercontent.com/23293150/124460086-95ebf080-dd97-11eb-87ab-605f06291563.mp4

Documentation

The docs can be found at https://hexdocs.pm/ex_ussd.

Installation

If available in Hex, the package can be installed by adding ex_ussd to your list of dependencies in mix.exs:

defp deps do
  [
    {:ex_ussd, "~> 1.0.0-rc-1"}
  ]
end

Configuration

Add to your config.exs

# config/config.exs
# TODO: This are example values, replace them with your own
config :ex_ussd,
 nav: [
   ExUssd.Nav.new(type: :home, name: "HOME", match: "00", reverse: true, orientation: :vertical),
   ExUssd.Nav.new(type: :back, name: "BACK", match: "0", right: 1),
   ExUssd.Nav.new(type: :next, name: "MORE", match: "98")
     ],
 delimiter: ").",
 default_error: "invalid input,try again\n"

Usage

Settable Fields

• :data Set data to pass through to next menu. N/B - ExUssd menu are stateful unless using ExUssd.new/2 with :name and :resolve as arguments;

  data = %{name: "John Doe"}
  # stateful
  menu
  |> ExUssd.set(data: data)
  |> ExUssd.add(ExUssd.new("Check Balance", &check_balance/2))
  
  # stateless
  menu
  |> ExUssd.add(ExUssd.new(data: data, name: "Check Balance", resolve: &check_balance/2))
  

• :delimiter Set's menu style delimiter. Default- :

• :default_error Default error shown on invalid input

• :error Set custom error message

• :name Sets the name of the menu

• :nav Its used to create a new ExUssd Nav menu

• :orientation Sets the menu orientation. Available option;

  • :horizontal - Left to right. Blog/articles style menu
  • vertical - Top to bottom(default)

• :resolve Navigates(invokes the next ussd_init/2) to the next menu

• :should_close Indicate whether to USSD session should end or continue

• :show_navigation Set show navigation menu. Default - true

• :split Set menu batch size. Default - 7

• :title Set menu title

ExUssd Callbacks

ExUssd provides you with 3 callbacks

• ussd_init/2 It's invoked once when the user navigates to that particular menu

• ussd_callback/3 It's an optional callback that is invoked after ussd_init/2 to validate the user input.

• ussd_after_callback/3 It's an optional callback that is invoked after ussd_callback/3 is invoked.

Example

Create a new module:

defmodule ApiWeb.HomeResolver do
  use ExUssd
  def ussd_init(menu, _) do
    ExUssd.set(menu, title: "Enter your PIN")
  end

  def ussd_callback(menu, payload, %{attempt: attempt}) do
    if payload.text == "5555" do
      ExUssd.set(menu, resolve: &success_menu/2)
    else
      ExUssd.set(menu, error: "Wrong PIN, attempt #{attempt}/3\n")
    end
  end

  def ussd_after_callback(%{error: true} = menu, _payload, %{attempt: 3}) do
    menu
    |> ExUssd.set(title: "Account is locked, you have entered the wrong PIN 3 times")
    |> ExUssd.set(should_close: true)
  end

  def success_menu(menu, _) do
    menu
    |> ExUssd.set(title: "You have Entered the Secret Number, 5555")
    |> ExUssd.set(should_close: true)
  end
end

Let's test the different ExUssd callbacks with ExUssd.to_string/3

create menu

menu = ExUssd.new(name: "PIN", resolve: ApiWeb.HomeResolver)

ussd_init/2

iex> ExUssd.to_string(menu, :ussd_init, [])
{:ok, %{menu_string: "Enter your PIN", should_close: false}}

ussd_callback/3

iex> ExUssd.to_string(menu, :ussd_callback, [payload: %{text: "5555"}, init_text: "1"])
{:ok, %{menu_string: "You have Entered the Secret Number, 5555", should_close: true}}

iex> ExUssd.to_string(menu, :ussd_callback, [payload: %{text: "42", attempt: 3}, init_text: "1"])
{:ok, %{menu_string: "Wrong PIN, attempt 3/3\nEnter your PIN", should_close: false}}

ussd_after_callback/3

iex> ExUssd.to_string(menu, :ussd_after_callback, [payload: %{text: "42", attempt: 3}, init_text: "1"])
{:ok,
 %{
   menu_string: "Account is locked, you have entered the wrong PIN 3 times",
   should_close: true
 }}

ExUssd Menu List

  defmodule HomeResolver do
    use ExUssd
    
    def product_a(menu, _payload), do: menu |> ExUssd.set(title: "selected product a")
    def product_b(menu, _payload), do: menu |> ExUssd.set(title: "selected product b")
    def product_c(menu, _payload), do: menu |> ExUssd.set(title: "selected product c")

    def account(%{data: %{account_type: :personal}} = menu, _payload) do
       menu 
       |> ExUssd.set(name: "personal Account")
       |> ExUssd.set(resolve: &personal_account/2)
    end

    def account(%{data: %{account_type: :business}} = menu, _payload) do
      menu 
      |> ExUssd.set(name: "business Account")
      |> ExUssd.set(resolve: &business_account/2)
    end

    def check_balance(%{data: %{account_type: account_type}} = menu, _payload) do
      if (account_type == :personal) do
        menu
        |> ExUssd.set(resolve: &personal_account_balance/2)
      else
        menu
        |> ExUssd.set(resolve: &business_account_balance/2)
      end
    end

    def home(menu, _payload) do
      data = %{user_name: "john_doe", account_type: :personal}
      menu 
      |> ExUssd.set(title: "Welcome")
      |> ExUssd.set(data: data)
      |> ExUssd.add(ExUssd.new(name: "Product A", resolve: &product_a/2))
      |> ExUssd.add(ExUssd.new(name: "Product B", resolve: &product_b/2))
      |> ExUssd.add(ExUssd.new(name: "Product C", resolve: &product_c/2))
      |> ExUssd.add(ExUssd.new(&account/2))
      |> ExUssd.add(ExUssd.new("Check Balance", &check_balance/2))
      |> ExUssd.add(ExUssd.new(name: "Enter Pin", resolve: __MODULE__))
    end
  end

Contribution

If you'd like to contribute, start by searching through the issues and pull requests to see whether someone else has raised a similar idea or question. If you don't see your idea listed, Open an issue.

Check the Contribution guide on how to contribute.

Contributors

Auto-populated from: contributors-img

Licence

ExUssd is released under MIT License