flow_chat 0.2.0 → 0.3.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 6eba909e6ae38dfeb26be6f854b185ca2c8097397aa4eea8a094d47e1d3fcd56
-  data.tar.gz: c47e6bf434684b87c7f0c8b2ebb9b6536c5bc17efe46fa3bec3876b976401f96
+  metadata.gz: 31c7630d410bbcff17307ade16634f5d5c9662f91eeeab8365b98681886de6b3
+  data.tar.gz: 4a7d4059a7a60dee5af2b189fa33c4638a439af903a72f38ffa5a67f9325115d
 SHA512:
-  metadata.gz: f52ba0115aa8000f9de120d436c9800318c8635efa86979b17f2dc01104d6ae65f66dcc193ada68a0a36ff238e9b6a87ef9ee66e00581ca4b5faa72a31fb25a0
-  data.tar.gz: 508138465e83f318e8e889f4e11ea19a709fc06c310b76c44388f56b84c94521fa44b45cc734fcfc07acf3b1cf38bbc764614e1d7252ee7b40ab4e0a20c55877
+  metadata.gz: 6040ccd725fa1a24b7ff46b5d288e11a1f1a4a2d58b4e773a843153a7d2cf3fb7c1fd7971dd27ed2bc938bf12da17a42b9bdbee9db06152507051eca57592fdb
+  data.tar.gz: 002d2fc1f5b6ea0b20e4229220801bc94311b5237ce24891a571f6f544abaf072a6fdf71de15632069a40d1b29b58e349f937b80ff3975f97bd3a607053b2c39

data/.ruby-version

@@ -0,0 +1 @@
+3.2.2

data/Gemfile

@@ -4,4 +4,6 @@ source "https://rubygems.org"
 gemspec
 
 gem "rake", "~> 12.0"
-gem "rspec", "~> 3.0"
+gem "minitest", "~> 5.0"
+gem "minitest-reporters", "~> 1.4"
+gem "ostruct"

data/README.md

@@ -1,39 +1,629 @@
 # 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 building sophisticated conversational workflows, particularly for USSD (Unstructured Supplementary Service Data) systems. It provides an intuitive Ruby DSL for creating multi-step, menu-driven conversations with automatic session management, input validation, and flow control.
 
-TODO: Delete this and the text above, and describe your gem
+**Key Features:**
+- 🎯 **Declarative Flow Definition** - Define conversation flows as Ruby classes
+- 🔄 **Automatic Session Management** - Persistent state across requests  
+- ✅ **Input Validation & Transformation** - Built-in validation and data conversion
+- 🌊 **Middleware Architecture** - Flexible request processing pipeline
+- 📱 **USSD Gateway Support** - Currently supports Nalo and Nsano gateways
+- 🧪 **Built-in Testing Tools** - USSD simulator for local development
+
+## Architecture Overview
+
+FlowChat uses a **request-per-interaction** model where each user input creates a new request. The framework maintains conversation state through session storage while processing each interaction through a middleware pipeline.
+
+```
+User Input → Gateway → Session → Pagination → Custom → Executor → Flow → Response
+                ↓
+         Session Storage
+```
+
+**Middleware Pipeline:**
+- **Gateway**: USSD provider communication (Nalo/Nsano)
+- **Session**: Load/save conversation state  
+- **Pagination**: Split long responses into pages
+- **Custom**: Your application middleware (logging, auth, etc.)
+- **Executor**: Execute flow methods and handle interrupts
 
 ## Installation
 
-Add this line to your application's Gemfile:
+Add FlowChat to your Rails application's Gemfile:
 
 ```ruby
 gem 'flow_chat'
 ```
 
-And then execute:
+Then execute:
+
+```bash
+bundle install
+```
+
+## Quick Start
+
+### 1. Create Your First Flow
+
+Create a flow class in `app/flow_chat/welcome_flow.rb`:
+
+```ruby
+class WelcomeFlow < FlowChat::Flow
+  def main_page
+    name = app.screen(:name) do |prompt|
+      prompt.ask "Welcome! What's your name?",
+        transform: ->(input) { input.strip.titleize }
+    end
+
+    app.say "Hello, #{name}! Welcome to FlowChat."
+  end
+end
+```
+
+### 2. Set Up the Controller
+
+Create a controller to handle USSD requests:
+
+```ruby
+class UssdController < ApplicationController
+  skip_forgery_protection
+
+  def process_request
+    processor = FlowChat::Ussd::Processor.new(self) do |config|
+      config.use_gateway FlowChat::Ussd::Gateway::Nalo
+      config.use_session_store FlowChat::Session::RailsSessionStore
+    end
+
+    processor.run WelcomeFlow, :main_page
+  end
+end
+```
+
+### 3. Configure Routes
+
+Add the route to `config/routes.rb`:
+
+```ruby
+Rails.application.routes.draw do
+  post 'ussd' => 'ussd#process_request'
+end
+```
+
+## Core Concepts
+
+### Flows and Screens
+
+**Flows** are Ruby classes that define conversation logic. **Screens** represent individual interaction points where you collect user input.
+
+```ruby
+class RegistrationFlow < FlowChat::Flow
+  def main_page
+    # Each screen captures one piece of user input
+    phone = app.screen(:phone) do |prompt|
+      prompt.ask "Enter your phone number:",
+        validate: ->(input) { "Invalid phone number" unless valid_phone?(input) }
+    end
+
+    age = app.screen(:age) do |prompt|
+      prompt.ask "Enter your age:",
+        convert: ->(input) { input.to_i },
+        validate: ->(input) { "Must be 18 or older" unless input >= 18 }
+    end
+
+    # Process the collected data
+    create_user(phone: phone, age: age)
+    app.say "Registration complete!"
+  end
+
+  private
+
+  def valid_phone?(phone)
+    phone.match?(/\A\+?[\d\s\-\(\)]+\z/)
+  end
+
+  def create_user(phone:, age:)
+    # Your user creation logic here
+  end
+end
+```
+
+### Input Validation and Transformation
+
+FlowChat provides powerful input processing capabilities:
+
+```ruby
+app.screen(:email) do |prompt|
+  prompt.ask "Enter your email:",
+    # Transform input before validation
+    transform: ->(input) { input.strip.downcase },
+    
+    # Validate the input
+    validate: ->(input) { 
+      "Invalid email format" unless input.match?(/\A[\w+\-.]+@[a-z\d\-]+(\.[a-z\d\-]+)*\.[a-z]+\z/i)
+    },
+    
+    # Convert to final format
+    convert: ->(input) { input }
+end
+```
+
+### Menu Selection
+
+Create selection menus with automatic validation:
+
+```ruby
+# Array-based choices
+language = app.screen(:language) do |prompt|
+  prompt.select "Choose your language:", ["English", "French", "Spanish"]
+end
+
+# Hash-based choices (keys are returned values)
+plan = app.screen(:plan) do |prompt|
+  prompt.select "Choose a plan:", {
+    "basic" => "Basic Plan ($10/month)",
+    "premium" => "Premium Plan ($25/month)",
+    "enterprise" => "Enterprise Plan ($100/month)"
+  }
+end
+```
+
+### Yes/No Prompts
+
+Simplified boolean input collection:
+
+```ruby
+confirmed = app.screen(:confirmation) do |prompt|
+  prompt.yes? "Do you want to proceed with the payment?"
+end
+
+if confirmed
+  process_payment
+  app.say "Payment processed successfully!"
+else
+  app.say "Payment cancelled."
+end
+```
+
+## Advanced Features
+
+### Session Management and Flow State
+
+FlowChat automatically manages session state across requests. Each screen's result is cached, so users can navigate back and forth without losing data:
+
+```ruby
+class OrderFlow < FlowChat::Flow
+  def main_page
+    # These values persist across requests
+    product = app.screen(:product) { |p| p.select "Choose product:", products }
+    quantity = app.screen(:quantity) { |p| p.ask "Quantity:", convert: :to_i }
+    
+    # Show summary
+    total = calculate_total(product, quantity)
+    confirmed = app.screen(:confirm) do |prompt|
+      prompt.yes? "Order #{quantity}x #{product} for $#{total}. Confirm?"
+    end
+
+    if confirmed
+      process_order(product, quantity)
+      app.say "Order placed successfully!"
+    else
+      app.say "Order cancelled."
+    end
+  end
+end
+```
+
+### Error Handling
+
+Handle validation errors gracefully:
+
+```ruby
+app.screen(:credit_card) do |prompt|
+  prompt.ask "Enter credit card number:",
+    validate: ->(input) {
+      return "Card number must be 16 digits" unless input.length == 16
+      return "Invalid card number" unless luhn_valid?(input)
+      nil # Return nil for valid input
+    }
+end
+```
+
+### Middleware Configuration
+
+FlowChat uses a **middleware architecture** to process USSD requests through a configurable pipeline. Each request flows through multiple middleware layers in a specific order.
+
+#### Default Middleware Stack
+
+When you run a flow, FlowChat automatically builds this middleware stack:
+
+```
+User Input → Gateway → Session → Pagination → Custom Middleware → Executor → Flow
+```
+
+1. **Gateway Middleware** - Handles USSD provider communication (Nalo/Nsano)
+2. **Session Middleware** - Manages session storage and retrieval
+3. **Pagination Middleware** - Automatically splits long responses across pages
+4. **Custom Middleware** - Your application-specific middleware (optional)
+5. **Executor Middleware** - Executes the actual flow logic
+
+#### Basic Configuration
+
+```ruby
+processor = FlowChat::Ussd::Processor.new(self) do |config|
+  # Gateway configuration (required)
+  config.use_gateway FlowChat::Ussd::Gateway::Nalo
+  
+  # Session storage (required)
+  config.use_session_store FlowChat::Session::RailsSessionStore
+  
+  # Add custom middleware (optional)
+  config.use_middleware MyLoggingMiddleware
+  
+  # Enable resumable sessions (optional)
+  config.use_resumable_sessions
+end
+```
+
+#### Runtime Middleware Modification
+
+You can modify the middleware stack at runtime for advanced use cases:
+
+```ruby
+processor.run(MyFlow, :main_page) do |stack|
+  # Add authentication middleware
+  stack.use AuthenticationMiddleware
+  
+  # Insert rate limiting before execution
+  stack.insert_before FlowChat::Ussd::Middleware::Executor, RateLimitMiddleware
+  
+  # Add logging after gateway
+  stack.insert_after gateway, RequestLoggingMiddleware
+end
+```
+
+#### Built-in Middleware
+
+**Pagination Middleware** automatically handles responses longer than 182 characters (configurable):
+
+```ruby
+# Configure pagination behavior
+FlowChat::Config.ussd.pagination_page_size = 140        # Default: 140 characters
+FlowChat::Config.ussd.pagination_next_option = "#"      # Default: "#"
+FlowChat::Config.ussd.pagination_next_text = "More"     # Default: "More"
+FlowChat::Config.ussd.pagination_back_option = "0"      # Default: "0"
+FlowChat::Config.ussd.pagination_back_text = "Back"     # Default: "Back"
+```
+
+**Resumable Sessions** allow users to continue interrupted conversations:
+
+```ruby
+processor = FlowChat::Ussd::Processor.new(self) do |config|
+  config.use_gateway FlowChat::Ussd::Gateway::Nalo
+  config.use_session_store FlowChat::Session::RailsSessionStore
+  config.use_resumable_sessions  # Enable resumable sessions
+end
+```
+
+#### Creating Custom Middleware
+
+```ruby
+class LoggingMiddleware
+  def initialize(app)
+    @app = app
+  end
+
+  def call(context)
+    Rails.logger.info "Processing USSD request: #{context.input}"
+    
+    # Call the next middleware in the stack
+    result = @app.call(context)
+    
+    Rails.logger.info "Response: #{result[1]}"
+    result
+  end
+end
+
+# Use your custom middleware
+processor = FlowChat::Ussd::Processor.new(self) do |config|
+  config.use_gateway FlowChat::Ussd::Gateway::Nalo
+  config.use_session_store FlowChat::Session::RailsSessionStore
+  config.use_middleware LoggingMiddleware
+end
+```
+
+### Multiple Gateways
+
+FlowChat supports multiple USSD gateways:
+
+```ruby
+# Nalo Solutions Gateway
+config.use_gateway FlowChat::Ussd::Gateway::Nalo
+
+# Nsano Gateway  
+config.use_gateway FlowChat::Ussd::Gateway::Nsano
+```
+
+## Testing
+
+### Unit Testing Flows
+
+Test your flows in isolation using the provided test helpers:
+
+```ruby
+require 'test_helper'
+
+class WelcomeFlowTest < Minitest::Test
+  def setup
+    @context = FlowChat::Context.new
+    @context.session = create_test_session_store
+  end
+
+  def test_welcome_flow_with_name
+    @context.input = "John Doe"
+    app = FlowChat::Ussd::App.new(@context)
+    
+    error = assert_raises(FlowChat::Interrupt::Terminate) do
+      flow = WelcomeFlow.new(app)
+      flow.main_page
+    end
+    
+    assert_equal "Hello, John Doe! Welcome to FlowChat.", error.prompt
+  end
+
+  def test_welcome_flow_without_input
+    @context.input = nil
+    app = FlowChat::Ussd::App.new(@context)
+    
+    error = assert_raises(FlowChat::Interrupt::Prompt) do
+      flow = WelcomeFlow.new(app)
+      flow.main_page
+    end
+    
+    assert_equal "Welcome! What's your name?", error.prompt
+  end
+end
+```
+
+### Integration Testing
+
+Test complete user journeys:
+
+```ruby
+class RegistrationFlowIntegrationTest < Minitest::Test
+  def test_complete_registration_flow
+    controller = mock_controller
+    processor = FlowChat::Ussd::Processor.new(controller) do |config|
+      config.use_gateway MockGateway
+      config.use_session_store FlowChat::Session::RailsSessionStore
+    end
+
+    # Simulate the complete flow
+    # First request - ask for phone
+    # Second request - provide phone, ask for age  
+    # Third request - provide age, complete registration
+  end
+end
+```
+
+### Testing Middleware
+
+Test your custom middleware in isolation:
+
+```ruby
+class LoggingMiddlewareTest < Minitest::Test
+  def test_logs_request_and_response
+    # Mock the next app in the chain
+    app = lambda { |context| [:prompt, "Test response", []] }
+    middleware = LoggingMiddleware.new(app)
+    
+    context = FlowChat::Context.new
+    context.input = "test input"
+    
+    # Capture log output
+    log_output = StringIO.new
+    Rails.stub(:logger, Logger.new(log_output)) do
+      type, prompt, choices = middleware.call(context)
+      
+      assert_equal :prompt, type
+      assert_equal "Test response", prompt
+      assert_includes log_output.string, "Processing USSD request: test input"
+      assert_includes log_output.string, "Response: Test response"
+    end
+  end
+end
+```
+
+### Testing Middleware Stack Modification
+
+Test runtime middleware modifications:
+
+```ruby
+class ProcessorMiddlewareTest < Minitest::Test
+  def test_custom_middleware_insertion
+    controller = mock_controller
+    processor = FlowChat::Ussd::Processor.new(controller) do |config|
+      config.use_gateway MockGateway
+      config.use_session_store FlowChat::Session::RailsSessionStore
+    end
+    
+    custom_middleware_called = false
+    custom_middleware = Class.new do
+      define_method(:initialize) { |app| @app = app }
+      define_method(:call) do |context|
+        custom_middleware_called = true
+        @app.call(context)
+      end
+    end
+    
+    processor.run(TestFlow, :main_page) do |stack|
+      stack.use custom_middleware
+      stack.insert_before FlowChat::Ussd::Middleware::Executor, custom_middleware
+    end
+    
+    assert custom_middleware_called, "Custom middleware should have been executed"
+  end
+end
+```
+
+### USSD Simulator
+
+Use the built-in simulator for interactive testing:
+
+```ruby
+class UssdSimulatorController < ApplicationController
+  include FlowChat::Ussd::Simulator::Controller
+
+  protected
+
+  def default_endpoint
+    '/ussd'
+  end
+
+  def default_provider
+    :nalo
+  end
+end
+```
+
+Add to routes and visit `http://localhost:3000/ussd_simulator`.
+
+## Best Practices
+
+### 1. Keep Flows Focused
+
+Create separate flows for different user journeys:
+
+```ruby
+# Good: Focused flows
+class LoginFlow < FlowChat::Flow
+  # Handle user authentication
+end
+
+class RegistrationFlow < FlowChat::Flow
+  # Handle user registration  
+end
+
+class AccountFlow < FlowChat::Flow
+  # Handle account management
+end
+```
+
+### 2. Use Descriptive Screen Names
+
+Screen names should clearly indicate their purpose:
+
+```ruby
+# Good
+app.screen(:customer_phone_number) { |p| p.ask "Phone:" }
+app.screen(:payment_confirmation) { |p| p.yes? "Confirm payment?" }
+
+# Avoid
+app.screen(:input1) { |p| p.ask "Phone:" }
+app.screen(:confirm) { |p| p.yes? "Confirm payment?" }
+```
+
+### 3. Validate Early and Often
 
-    $ bundle install
+Always validate user input to provide clear feedback:
 
-Or install it yourself as:
+```ruby
+app.screen(:amount) do |prompt|
+  prompt.ask "Enter amount:",
+    convert: ->(input) { input.to_f },
+    validate: ->(amount) {
+      return "Amount must be positive" if amount <= 0
+      return "Maximum amount is $1000" if amount > 1000
+      nil
+    }
+end
+```
+
+### 4. Handle Edge Cases
+
+Consider error scenarios and provide helpful messages:
+
+```ruby
+def main_page
+  begin
+    process_user_request
+  rescue PaymentError => e
+    app.say "Payment failed: #{e.message}. Please try again."
+  rescue SystemError
+    app.say "System temporarily unavailable. Please try again later."
+  end
+end
+```
+
+## Configuration
+
+### Session Storage Options
+
+Configure different session storage backends:
+
+```ruby
+# Rails session (default)
+config.use_session_store FlowChat::Session::RailsSessionStore
+
+# Custom session store
+class MySessionStore
+  def initialize(context)
+    @context = context
+  end
 
-    $ gem install flow_chat
+  def get(key)
+    # Your storage logic
+  end
 
-## Usage
+  def set(key, value)
+    # Your storage logic
+  end
+end
 
-TODO: Write usage instructions here
+config.use_session_store MySessionStore
+```
 
 ## 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.
+### Running Tests
 
-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).
+FlowChat uses Minitest for testing:
 
-## Contributing
+```bash
+# Run all tests
+bundle exec rake test
+
+# Run specific test file
+bundle exec rake test TEST=test/unit/flow_test.rb
+
+# Run specific test
+bundle exec rake test TESTOPTS="--name=test_flow_initialization"
+```
 
-Bug reports and pull requests are welcome on GitHub at https://github.com/[USERNAME]/flow_chat.
+### Contributing
+
+1. Fork the repository
+2. Create your feature branch (`git checkout -b feature/amazing-feature`)
+3. Add tests for your changes
+4. Ensure all tests pass (`bundle exec rake test`)
+5. Commit your changes (`git commit -am 'Add amazing feature'`)
+6. Push to the branch (`git push origin feature/amazing-feature`)
+7. Open a Pull Request
+
+## Roadmap
+
+- 📱 **WhatsApp Integration** - Support for WhatsApp Business API
+- 💬 **Telegram Bot Support** - Native Telegram bot integration  
+- 🔄 **Sub-flows** - Reusable conversation components
+- 📊 **Analytics Integration** - Built-in conversation analytics
+- 🌐 **Multi-language Support** - Internationalization features
+- ⚡ **Performance Optimizations** - Improved middleware performance
 
 ## License
 
-The gem is available as open source under the terms of the [MIT License](https://opensource.org/licenses/MIT).
+FlowChat is available as open source under the terms of the [MIT License](https://opensource.org/licenses/MIT).
+
+## Support
+
+- 📖 **Documentation**: [GitHub Repository](https://github.com/radioactive-labs/flow_chat)
+- 🐛 **Bug Reports**: [GitHub Issues](https://github.com/radioactive-labs/flow_chat/issues)
+- 💬 **Community**: Join our discussions for help and feature requests

data/Rakefile

@@ -1,6 +1,10 @@
 require "bundler/gem_tasks"
-require "rspec/core/rake_task"
+require "rake/testtask"
 
-RSpec::Core::RakeTask.new(:spec)
+Rake::TestTask.new(:test) do |t|
+  t.libs << "test"
+  t.libs << "lib"
+  t.test_files = FileList["test/**/*_test.rb"]
+end
 
-task default: :spec
+task default: :test

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/config.rb

@@ -1,16 +1,29 @@
 module FlowChat
   module Config
+    # General framework configuration
     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"
+    # USSD-specific configuration object
+    def self.ussd
+      @ussd ||= UssdConfig.new
+    end
 
-    mattr_accessor :resumable_sessions_enabled, default: false
-    mattr_accessor :resumable_sessions_global, default: true
-    mattr_accessor :resumable_sessions_timeout_seconds, default: 300
+    class UssdConfig
+      attr_accessor :pagination_page_size, :pagination_back_option, :pagination_back_text,
+        :pagination_next_option, :pagination_next_text,
+        :resumable_sessions_enabled, :resumable_sessions_global, :resumable_sessions_timeout_seconds
+
+      def initialize
+        @pagination_page_size = 140
+        @pagination_back_option = "0"
+        @pagination_back_text = "Back"
+        @pagination_next_option = "#"
+        @pagination_next_text = "More"
+        @resumable_sessions_enabled = false
+        @resumable_sessions_global = true
+        @resumable_sessions_timeout_seconds = 300
+      end
+    end
   end
 end

data/lib/flow_chat/context.rb

@@ -14,8 +14,16 @@ module FlowChat
 
     def input = @data["request.input"]
 
+    def input=(value)
+      @data["request.input"] = value
+    end
+
     def session = @data["session"]
 
+    def session=(value)
+      @data["session"] = value
+    end
+
     def controller = @data["controller"]
 
     # def request = controller.request

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/interrupt.rb

@@ -1,5 +1,6 @@
 module FlowChat
   module Interrupt
+    # standard:disable Lint/InheritException
     class Base < Exception
       attr_reader :prompt
 
@@ -8,6 +9,7 @@ module FlowChat
         super
       end
     end
+    # standard:enable Lint/InheritException
 
     class Prompt < Base
       attr_reader :choices

data/lib/flow_chat/session/middleware.rb

@@ -7,7 +7,7 @@ module FlowChat
 
       def call(context)
         context["session.id"] = session_id context
-        context["session"] = context["session.store"].new context
+        context.session = context["session.store"].new(context)
         @app.call(context)
       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/gateway/nalo.rb

@@ -16,7 +16,7 @@ module FlowChat
           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
+          context.input = params["USERDATA"].presence
 
           type, prompt, choices = @app.call(context)
 

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

@@ -10,7 +10,7 @@ module FlowChat
 
         def call(context)
           controller = context["controller"]
-          request = controller.request
+          controller.request
 
           # input = context["rack.input"].read
           # context["rack.input"].rewind

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

@@ -12,16 +12,14 @@ module FlowChat
 
           if intercept?
             type, prompt = handle_intercepted_request
-            [type, prompt, []]
           else
             @session.delete "ussd.pagination"
             type, prompt, choices = @app.call(context)
 
             prompt = FlowChat::Ussd::Renderer.new(prompt, choices).render
             type, prompt = maybe_paginate(type, prompt) if prompt.present?
-
-            [type, prompt, []]
           end
+          [type, prompt, []]
         end
 
         private
@@ -29,11 +27,11 @@ module FlowChat
         def intercept?
           pagination_state.present? &&
             (pagination_state["type"].to_sym == :terminal ||
-             ([Config.pagination_next_option, Config.pagination_back_option].include? @context.input))
+             ([FlowChat::Config.ussd.pagination_next_option, FlowChat::Config.ussd.pagination_back_option].include? @context.input))
         end
 
         def handle_intercepted_request
-          Config.logger&.info "FlowChat::Middleware::Pagination :: Intercepted to handle pagination"
+          FlowChat::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
           prompt = pagination_state["prompt"][start..finish].strip + build_pagination_options(type, has_more)
@@ -43,9 +41,9 @@ module FlowChat
         end
 
         def maybe_paginate(type, prompt)
-          if prompt.length > Config.pagination_page_size
+          if prompt.length > FlowChat::Config.ussd.pagination_page_size
             original_prompt = prompt
-            Config.logger&.info "FlowChat::Middleware::Pagination :: Response length (#{prompt.length}) exceeds page size (#{Config.pagination_page_size}). Paginating."
+            FlowChat::Config.logger&.info "FlowChat::Middleware::Pagination :: Response length (#{prompt.length}) exceeds page size (#{FlowChat::Config.ussd.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 = prompt[single_option_slice_size + 1].blank? ? single_option_slice_size : prompt.rindex("\n") || prompt.rindex(" ") || single_option_slice_size
@@ -60,12 +58,12 @@ module FlowChat
           page = current_page
           offset = pagination_state["offsets"][page.to_s]
           if offset.present?
-            Config.logger&.debug "FlowChat::Middleware::Pagination :: Reusing cached offset for page: #{page}"
+            FlowChat::Config.logger&.debug "FlowChat::Middleware::Pagination :: Reusing cached offset for page: #{page}"
             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}"
+            FlowChat::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_page = page - 1
             previous_offset = pagination_state["offsets"][previous_page.to_s]
@@ -73,8 +71,7 @@ module FlowChat
             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["prompt"].length
-              Config.logger&.debug "FlowChat::Middleware::Pagination :: No content exists for page: #{page}. Reverting to page: #{page - 1}"
-              page -= 1
+              FlowChat::Config.logger&.debug "FlowChat::Middleware::Pagination :: No content exists for page: #{page}. Reverting to page: #{page - 1}"
               has_more = false
               start = previous_offset["start"]
               finish = previous_offset["finish"]
@@ -100,11 +97,11 @@ module FlowChat
         end
 
         def next_option
-          "#{Config.pagination_next_option} #{Config.pagination_next_text}"
+          "#{FlowChat::Config.ussd.pagination_next_option} #{FlowChat::Config.ussd.pagination_next_text}"
         end
 
         def back_option
-          "#{Config.pagination_back_option} #{Config.pagination_back_text}"
+          "#{FlowChat::Config.ussd.pagination_back_option} #{FlowChat::Config.ussd.pagination_back_text}"
         end
 
         def single_option_slice_size
@@ -112,7 +109,7 @@ module FlowChat
             # 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
+            @single_option_slice_size = FlowChat::Config.ussd.pagination_page_size - 2 - [next_option.length, back_option.length].max - 1
           end
           @single_option_slice_size
         end
@@ -121,16 +118,16 @@ module FlowChat
           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
+            @dual_options_slice_size = FlowChat::Config.ussd.pagination_page_size - 3 - [next_option.length, back_option.length].sum - 1
           end
           @dual_options_slice_size
         end
 
         def current_page
           page = pagination_state["page"]
-          if @context.input == Config.pagination_back_option
+          if @context.input == FlowChat::Config.ussd.pagination_back_option
             page -= 1
-          elsif @context.input == Config.pagination_next_option
+          elsif @context.input == FlowChat::Config.ussd.pagination_next_option
             page += 1
           end
           [page, 1].max

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

@@ -7,44 +7,31 @@ module FlowChat
         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
+          if FlowChat::Config.ussd.resumable_sessions_enabled && context["ussd.request"].present?
+            # First, try to find any interruption session.
+            # The session key can be:
+            #  - a global session (key: "global")
+            #  - a provider-specific session (key: <provider>)
+            session_key = self.class.session_key(context)
+            resumable_session = context["session.store"].get(session_key)
+
+            if resumable_session.present? && valid?(resumable_session)
+              context.merge! resumable_session
             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
+
+          @app.call(context)
         end
 
         private
 
-        def can_resume_session?(session)
-          return unless session["ussd.resumable_sessions"].present?
-          return true unless Config.resumable_sessions_timeout_seconds
+        def valid?(session)
+          return true unless FlowChat::Config.ussd.resumable_sessions_timeout_seconds
 
-          last_active_at = Time.at(session["ussd.resumable_sessions"])
-          (Time.now - Config.resumable_sessions_timeout_seconds) < last_active_at
+          last_active_at = Time.parse session.dig("context", "last_active_at")
+          (Time.now - FlowChat::Config.ussd.resumable_sessions_timeout_seconds) < last_active_at
+        rescue
+          false
         end
       end
     end

data/lib/flow_chat/ussd/prompt.rb

@@ -32,7 +32,7 @@ module FlowChat
           msg,
           choices: choices_prompt,
           convert: lambda { |choice| choice.to_i },
-          validate: lambda { |choice| "Invalid selection:" unless (1..choices.size).include?(choice) },
+          validate: lambda { |choice| "Invalid selection:" unless (1..choices.size).cover?(choice) },
           transform: lambda { |choice| choices[choice - 1] }
         )
       end

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

@@ -38,7 +38,7 @@ module FlowChat
 
         def simulator_locals
           {
-            pagesize: Config.pagination_page_size,
+            pagesize: FlowChat::Config.ussd.pagination_page_size,
             show_options: show_options,
             default_msisdn: default_msisdn,
             default_endpoint: default_endpoint,

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.3.0"
 end

metadata

@@ -1,14 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: flow_chat
 version: !ruby/object:Gem::Version
-  version: 0.2.0
+  version: 0.3.0
 platform: ruby
 authors:
 - Stefan Froelich
 autorequire:
 bindir: exe
 cert_chain: []
-date: 2024-04-05 00:00:00.000000000 Z
+date: 2025-06-04 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: zeitwerk
@@ -80,15 +80,16 @@ 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"
+- ".ruby-version"
 - ".travis.yml"
 - Gemfile
 - LICENSE.txt
@@ -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
@@ -138,8 +141,8 @@ required_rubygems_version: !ruby/object:Gem::Requirement
     - !ruby/object:Gem::Version
       version: '0'
 requirements: []
-rubygems_version: 3.5.6
+rubygems_version: 3.4.10
 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: []

data/.rspec

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