flow_chat 0.2.1 → 0.3.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 6c1e5cd739c50f112b6a5637e712756e0b96bdb18c2276c7d30db2b2a071cc23
-  data.tar.gz: f701ad5050599c06b87eba80841823b04eef156e7ea3e77527a0be91519b0d48
+  metadata.gz: 31c7630d410bbcff17307ade16634f5d5c9662f91eeeab8365b98681886de6b3
+  data.tar.gz: 4a7d4059a7a60dee5af2b189fa33c4638a439af903a72f38ffa5a67f9325115d
 SHA512:
-  metadata.gz: ef7e1721b7c5453130999b2ef899af4f20ba6db81ac4b3956ce7ade5956bf2b61e248b2be66ace885c633d4d612025208b31d1ff081ef1a0d671f579e0d3db38
-  data.tar.gz: 2581189b102229a0e8843691f38eaf91a9c7bf1d2db7c7a71e685124a849621cf55bdd33c6cdd1c928e2bfac051bca597601875dc9cff921063a98ff954a7b82
+  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,85 +1,473 @@
 # FlowChat
 
-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.
+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.
 
-The framework's architecture leverages a middleware processing pipeline, offering flexibility in customizing the conversation handling process.
+**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
 
-## Getting Started
+## Architecture Overview
 
-### Installation
+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.
 
-Incorporate FlowChat into your Rails project by adding the following line to your Gemfile:
+```
+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 FlowChat to your Rails application's Gemfile:
 
 ```ruby
-gem 'flow_chat', '~> 0.2.0'
+gem 'flow_chat'
 ```
 
-Then, execute:
+Then execute:
 
 ```bash
 bundle install
 ```
 
-Alternatively, you can install it directly using:
+## Quick Start
 
-```bash
-gem install flow_chat
+### 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
 ```
 
-### Basic Usage
+### 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
 
-#### Building Your First Flow
+    processor.run WelcomeFlow, :main_page
+  end
+end
+```
 
-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`.
+### 3. Configure Routes
 
-For a simple "Hello World" flow:
+Add the route to `config/routes.rb`:
 
 ```ruby
-class HelloWorldFlow < FlowChat::Flow
+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
-    app.say "Hello World!"
+    # 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
 ```
 
-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.
+### Input Validation and Transformation
 
-#### Integration with USSD
+FlowChat provides powerful input processing capabilities:
 
-Given that most USSD gateways interact via HTTP, set up a controller to handle the conversation flow:
+```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
-class UssdDemoController < ApplicationController
-  skip_forgery_protection
+# 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
 
-  def hello_world
-    ussd_processor.run HelloWorldFlow, :main_page
+### 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
+```
 
-  private
+### 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
 
-  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
+**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
 ```
 
-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.
+### Integration Testing
 
-Bind the controller action to a route:
+Test complete user journeys:
 
 ```ruby
-Rails.application.routes.draw do
-  post 'ussd_hello_world' => 'ussd_demo#hello_world'
+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
 ```
 
-#### Testing with the USSD Simulator
+### USSD Simulator
 
-FlowChat comes with a USSD simulator for local testing:
+Use the built-in simulator for interactive testing:
 
 ```ruby
 class UssdSimulatorController < ApplicationController
@@ -88,7 +476,7 @@ class UssdSimulatorController < ApplicationController
   protected
 
   def default_endpoint
-    '/ussd_hello_world'
+    '/ussd'
   end
 
   def default_provider
@@ -97,62 +485,145 @@ class UssdSimulatorController < ApplicationController
 end
 ```
 
-And set up the corresponding route:
+Add to routes and visit `http://localhost:3000/ussd_simulator`.
+
+## Best Practices
+
+### 1. Keep Flows Focused
+
+Create separate flows for different user journeys:
 
 ```ruby
-Rails.application.routes.draw do
-  get 'ussd_simulator' => 'ussd_simulator#ussd_simulator'
+# 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
 ```
 
-Visit [http://localhost:3000/ussd_simulator](http://localhost:3000/ussd_simulator) to initiate and test your flow.
+### 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?" }
+```
 
-### Advanced Usage: Implementing Multiple Screens
+### 3. Validate Early and Often
 
-To engage users with a multi-step interaction, define a flow with multiple screens:
+Always validate user input to provide clear feedback:
 
 ```ruby
-class MultipleScreensFlow < FlowChat::Flow
-  def main_page
-    name = app.screen(:name) { |prompt|
-      prompt.ask "What is your name?", transform: ->(input) { input.squish }
+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
+```
 
-    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"] }
+### 4. Handle Edge Cases
 
-    confirm = app.screen(:confirm) do |prompt|
-      prompt.yes?("Is this correct?\n\nName: #{name}\nAge: #{age}\nGender: #{gender}")
-    end
+Consider error scenarios and provide helpful messages:
 
-    app.say confirm ? "Thank you for confirming" : "Please try again"
+```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
 ```
 
-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.
+## Configuration
+
+### Session Storage Options
 
-TODO:
+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
+
+  def get(key)
+    # Your storage logic
+  end
 
-### Sub Flows
+  def set(key, value)
+    # Your storage logic
+  end
+end
 
-TODO:
+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
+
+FlowChat uses Minitest for testing:
+
+```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"
+```
+
+### Contributing
 
-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).
+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
 
-## Contributing
+## Roadmap
 
-Bug reports and pull requests are welcome on GitHub at https://github.com/[USERNAME]/flow_chat.
+- 📱 **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/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/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/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/version.rb

@@ -1,3 +1,3 @@
 module FlowChat
-  VERSION = "0.2.1"
+  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.1
+  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
@@ -89,7 +89,7 @@ extra_rdoc_files: []
 files:
 - ".DS_Store"
 - ".gitignore"
-- ".rspec"
+- ".ruby-version"
 - ".travis.yml"
 - Gemfile
 - LICENSE.txt
@@ -141,7 +141,7 @@ 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 building Menu based conversations (e.g. USSD) in Rails.

data/.rspec

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