conduit-ussd 0.1.0

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA256:
+  metadata.gz: 557f1741896d47caed701bf3bb0c73f19dc128dd0cdf5cd076699baebaf8435b
+  data.tar.gz: dd048e06d6d0cac802f7ad3be66ad62ad0fa20730838bbc2c317281da7a5eb91
+SHA512:
+  metadata.gz: fa64e78847e2ec50787f91d8bcc27a3cca8c81d2cac82b8dcd361b9bfebc556092a20d67898676f4b2bc35cc78bc4aa4f4c1927f329df8af20ac0a8622669867
+  data.tar.gz: 2c1ea4bffd6af908fbf71581a0f5100c56ecc372a48cb5516e783af31b0f195eb8d585072184b8488abd1132abe69eea8e7ed69fe61be79998c467fd9595f086

data/MIT-LICENSE

@@ -0,0 +1,20 @@
+Copyright charles chuck
+
+Permission is hereby granted, free of charge, to any person obtaining
+a copy of this software and associated documentation files (the
+"Software"), to deal in the Software without restriction, including
+without limitation the rights to use, copy, modify, merge, publish,
+distribute, sublicense, and/or sell copies of the Software, and to
+permit persons to whom the Software is furnished to do so, subject to
+the following conditions:
+
+The above copyright notice and this permission notice shall be
+included in all copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND,
+EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF
+MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND
+NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE
+LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION
+OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION
+WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.

data/README.md

@@ -0,0 +1,426 @@
+# Conduit
+
+Lightning-fast USSD flow engine for Rails applications. Build interactive USSD services with an expressive DSL, Redis-backed session management, and built-in support for AfricasTalking.
+
+## Design Philosophy
+
+Conduit is built on four core principles that make USSD development in Africa a joy:
+
+### 1. **Speed is Everything**
+USSD sessions have a strict 60-120 second timeout. Every millisecond counts. Conduit uses Redis connection pooling, minimal middleware overhead, and optimized session serialization to deliver sub-50ms response times.
+
+### 2. **Developer Experience First**
+Your flow code should read like a specification. Conduit's DSL is designed to be self-documenting, making it easy for teams to understand, maintain, and extend USSD applications.
+
+```ruby
+state :welcome do
+  display "Welcome! What would you like to do?"
+  on "1", to: :check_balance
+  on "2", to: :send_money
+end
+```
+
+### 3. **African Mobile Networks are Unique**
+Built specifically for African telecom infrastructure. Handles network delays, session drops, and the quirks of different USSD gateways. First-class support for AfricasTalking with extensible provider architecture.
+
+### 4. **Production-Grade from Day One**
+Includes middleware for logging, throttling, and session tracking. Built-in error handling, session persistence, and monitoring hooks. Deploy with confidence.
+
+## Features
+
+- **Blazing Fast** - Redis-backed sessions with sub-50ms response times
+- **Expressive DSL** - Write flows that read like specifications  
+- **AfricasTalking Ready** - Built-in provider support with extensible architecture
+- **Smart Navigation** - Automatic back (0) and home (00) handling with navigation stack
+- **Production Ready** - Middleware, throttling, error handling, and session persistence
+- **Multi-language** - Easy internationalization support
+- **60-120s Sessions** - Optimized for USSD's time constraints
+- **Rails Integration** - Seamless Rails engine with generators and conventions
+
+## Quick Start
+
+### Installation
+
+Add to your Gemfile:
+
+```ruby
+gem "conduit-ussd"
+```
+
+Then run:
+
+```bash
+bundle install
+rails generate conduit:install
+rails generate conduit:migration
+rails db:migrate
+```
+
+### Your First Flow
+
+```ruby
+# app/flows/banking_flow.rb
+class BankingFlow < Conduit::Flow
+  initial_state :welcome
+
+  state :welcome do
+    display <<~TEXT
+      Welcome to MobileBank
+      
+      1. Check Balance
+      2. Send Money
+      3. Buy Airtime
+    TEXT
+
+    on "1", to: :check_balance
+    on "2", to: :send_money
+    on "3", to: :buy_airtime
+  end
+
+  state :check_balance do
+    display do |session|
+      balance = User.find_by(phone: session.msisdn)&.balance || 0
+      "Your balance is KES #{balance}"
+    end
+  end
+
+  state :send_money do
+    display "Enter phone number:"
+    
+    on_any do |input, session|
+      if valid_phone?(input)
+        session.data[:recipient] = input
+        session.navigate_to(:enter_amount)
+      else
+        Conduit::Response.new(text: "Invalid phone number. Try again:")
+      end
+    end
+  end
+
+  state :enter_amount do
+    display do |session|
+      "Send money to #{session.data[:recipient]}\nEnter amount:"
+    end
+
+    on_any do |input, session|
+      amount = input.to_i
+      if amount > 0 && amount <= user_balance(session)
+        process_transfer(session, amount)
+        Conduit::Response.new(text: "Money sent successfully!", action: :end)
+      else
+        Conduit::Response.new(text: "Invalid amount. Try again:")
+      end
+    end
+  end
+
+  private
+
+  def valid_phone?(phone)
+    phone.match?(/^254\d{9}$/)
+  end
+
+  def user_balance(session)
+    User.find_by(phone: session.msisdn)&.balance || 0
+  end
+
+  def process_transfer(session, amount)
+    # Your transfer logic here
+    TransferService.new(
+      from: session.msisdn,
+      to: session.data[:recipient],
+      amount: amount
+    ).call
+  end
+end
+```
+
+### Configuration
+
+```ruby
+# config/initializers/conduit.rb
+Conduit.configure do |config|
+  config.redis_url = ENV.fetch("REDIS_URL", "redis://localhost:6379/1")
+  config.session_ttl = 90.seconds
+  config.max_navigation_depth = 10
+
+  # Middleware (order matters)
+  config.middleware.use Conduit::Middleware::Logging
+  config.middleware.use Conduit::Middleware::Throttling, max_requests: 20, window: 60
+  config.middleware.use Conduit::Middleware::SessionTracking
+end
+
+# Route service codes to flows
+Conduit::Router.draw do
+  route "*123#", to: BankingFlow
+  route "*456#", to: AirtimeFlow
+  route "*789#", to: UtilitiesFlow
+end
+```
+
+### Controller
+
+```ruby
+# app/controllers/ussd_controller.rb
+class UssdController < ApplicationController
+  def handle
+    handler = Conduit::RequestHandler.new(
+      Conduit::Providers::AfricasTalking.new(params)
+    )
+    
+    response = handler.process
+    render plain: response
+  end
+end
+```
+
+## Advanced Features
+
+### Session Management
+
+```ruby
+state :collect_info do
+  display "Enter your name:"
+  
+  on_any do |input, session|
+    session.data[:user_name] = input
+    session.data[:collected_at] = Time.current
+    session.navigate_to(:confirm)
+  end
+end
+
+state :confirm do
+  display do |session|
+    "Hello #{session.data[:user_name]}!
+    Session started: #{session.started_at}
+    Duration: #{session.duration.to_i}s"
+  end
+end
+```
+
+### Navigation Stack
+
+```ruby
+# Automatic back/home handling
+state :menu do
+  display <<~TEXT
+    Main Menu
+    1. Services
+    2. Account
+    
+    0. Back
+    00. Home
+  TEXT
+  
+  # 0 and 00 are handled automatically
+  on "1", to: :services
+  on "2", to: :account
+end
+```
+
+### Conditional Flows
+
+```ruby
+state :check_eligibility do
+  display "Checking your eligibility..."
+  
+  transition do |session|
+    user = User.find_by(phone: session.msisdn)
+    
+    if user&.kyc_verified?
+      :premium_services
+    elsif user&.basic_verified?
+      :basic_services  
+    else
+      :verification_required
+    end
+  end
+end
+```
+
+### Error Handling
+
+```ruby
+state :risky_operation do
+  display "Processing..."
+  
+  on_any do |input, session|
+    begin
+      result = ExternalService.call(input)
+      session.navigate_to(:success)
+    rescue ExternalService::Error => e
+      Conduit.logger.error("Service failed: #{e.message}")
+      Conduit::Response.new(text: "Service temporarily unavailable. Try again later.", action: :end)
+    end
+  end
+end
+```
+
+### Custom Middleware
+
+```ruby
+class AuthenticationMiddleware < Conduit::Middleware::Base
+  def call(env)
+    session = env[:session]
+    
+    unless authenticated?(session.msisdn)
+      return Conduit::Response.end("Please register first by dialing *100#")
+    end
+    
+    @app.call(env)
+  end
+  
+  private
+  
+  def authenticated?(phone)
+    User.exists?(phone: phone, status: 'active')
+  end
+end
+
+# Add to config
+config.middleware.use AuthenticationMiddleware
+```
+
+## Testing
+
+```ruby
+# spec/flows/banking_flow_spec.rb
+RSpec.describe BankingFlow do
+  let(:session) { build_session(msisdn: "254712345678") }
+  let(:flow) { described_class.new }
+
+  describe "welcome state" do
+    it "displays menu options" do
+      response = flow.process(session)
+      
+      expect(response.text).to include("Welcome to MobileBank")
+      expect(response.text).to include("1. Check Balance")
+      expect(response).to be_continue
+    end
+  end
+
+  describe "balance inquiry" do
+    before { session.current_state = :welcome }
+    
+    it "shows balance when option 1 is selected" do
+      create(:user, phone: "254712345678", balance: 1500)
+      
+      response = flow.process(session, "1")
+      
+      expect(response.text).to include("Your balance is KES 1500")
+      expect(response).to be_end
+    end
+  end
+end
+```
+
+## Deployment
+
+### Production Configuration
+
+```ruby
+# config/environments/production.rb
+config.cache_store = :redis_cache_store, {
+  url: ENV['REDIS_URL'],
+  pool_size: 20,
+  pool_timeout: 0.1
+}
+
+# Use separate Redis instance for Conduit sessions
+Conduit.configure do |config|
+  config.redis_url = ENV.fetch("CONDUIT_REDIS_URL", ENV["REDIS_URL"])
+  config.redis_pool_size = 20
+  config.session_ttl = 120.seconds
+end
+```
+
+### Monitoring
+
+```ruby
+# config/initializers/conduit.rb
+class MetricsMiddleware < Conduit::Middleware::Base
+  def call(env)
+    start_time = Time.current
+    
+    result = @app.call(env)
+    
+    duration = (Time.current - start_time) * 1000
+    Rails.logger.info("USSD Response time: #{duration.round(2)}ms")
+    
+    # Send to your monitoring service
+    StatsD.histogram('ussd.response_time', duration)
+    
+    result
+  end
+end
+
+config.middleware.use MetricsMiddleware
+```
+
+## Provider Support
+
+Currently supports AfricasTalking with extensible provider architecture:
+
+```ruby
+# Custom provider
+class CustomProvider
+  def initialize(params)
+    @params = params
+  end
+  
+  def parse_request
+    {
+      session_id: @params[:session_id],
+      msisdn: @params[:phone_number],
+      service_code: @params[:service_code], 
+      input: @params[:user_input]
+    }
+  end
+  
+  def format_response(response)
+    {
+      message: response.text,
+      action: response.end? ? 'terminate' : 'continue'
+    }.to_json
+  end
+end
+```
+
+## Architecture
+
+Conduit follows a middleware-based architecture:
+
+```
+Request → Provider → Middleware Chain → Router → Flow → Response → Provider → Response
+```
+
+- **Provider**: Parses telecom-specific requests
+- **Middleware**: Cross-cutting concerns (logging, throttling, auth)
+- **Router**: Maps service codes to flows
+- **Flow**: Your business logic
+- **Session**: Redis-backed state management
+
+## Contributing
+
+1. Fork the repository
+2. Create your feature branch (`git checkout -b feature/amazing-feature`)
+3. Write tests for your changes
+4. Ensure all tests pass (`bundle exec rspec`)
+5. Run the linter (`bundle exec rubocop`)
+6. Commit your changes (`git commit -m 'Add amazing feature'`)
+7. Push to the branch (`git push origin feature/amazing-feature`)
+8. Open a Pull Request
+
+## License
+
+The gem is available as open source under the terms of the [MIT License](https://opensource.org/licenses/MIT).
+
+## Support
+
+- 📧 Email: support@conduit-ussd.com
+- 🐛 Issues: [GitHub Issues](https://github.com/chalchuck/conduit/issues)
+- 📖 Docs: [Full Documentation](https://docs.conduit-ussd.com)
+- 💬 Community: [Discord](https://discord.gg/conduit-ussd)
+
+---
+
+Built with ❤️ for African developers by African developers.

data/Rakefile

@@ -0,0 +1,2 @@
+require "bundler/setup"
+require "bundler/gem_tasks"

data/app/assets/stylesheets/conduit/application.css

@@ -0,0 +1,15 @@
+/*
+ * This is a manifest file that'll be compiled into application.css, which will include all the files
+ * listed below.
+ *
+ * Any CSS and SCSS file within this directory, lib/assets/stylesheets, vendor/assets/stylesheets,
+ * or any plugin's vendor/assets/stylesheets directory can be referenced here using a relative path.
+ *
+ * You're free to add application-wide styles to this file and they'll appear at the bottom of the
+ * compiled file so the styles you add here take precedence over styles defined in any other CSS/SCSS
+ * files in this directory. Styles in this file should be added after the last require_* statement.
+ * It is generally better to create a new file per style scope.
+ *
+ *= require_tree .
+ *= require_self
+ */

data/app/controllers/conduit/application_controller.rb

@@ -0,0 +1,4 @@
+module Conduit
+  class ApplicationController < ActionController::Base
+  end
+end

data/app/helpers/conduit/application_helper.rb

@@ -0,0 +1,4 @@
+module Conduit
+  module ApplicationHelper
+  end
+end

data/app/jobs/conduit/application_job.rb

@@ -0,0 +1,4 @@
+module Conduit
+  class ApplicationJob < ActiveJob::Base
+  end
+end

data/app/jobs/conduit/save_session_job.rb

@@ -0,0 +1,11 @@
+module Conduit
+  class SaveSessionJob < ApplicationJob
+    queue_as :default
+
+    def perform(session_data)
+      session = Session.from_hash(session_data)
+      record = SessionRecord.from_session(session, completed: true)
+      record.save!
+    end
+  end
+end

data/app/models/conduit/application_record.rb

@@ -0,0 +1,5 @@
+module Conduit
+  class ApplicationRecord < ActiveRecord::Base
+    self.abstract_class = true
+  end
+end

data/app/models/conduit/session_record.rb

@@ -0,0 +1,28 @@
+module Conduit
+  class SessionRecord < ApplicationRecord
+    self.table_name = "conduit_sessions"
+
+    validates :session_id, presence: true, uniqueness: true
+    validates :msisdn, presence: true
+    validates :started_at, presence: true
+
+    scope :completed, -> { where(completed: true) }
+    scope :incomplete, -> { where(completed: false) }
+    scope :recent, -> { order(created_at: :desc) }
+    scope :for_phone, ->(msisdn) { where(msisdn:) }
+
+    def self.from_session(session, completed: false)
+      new(
+        session_id: session.session_id,
+        msisdn: session.msisdn,
+        service_code: session.service_code,
+        final_state: session.current_state,
+        data: session.data,
+        duration_seconds: session.duration.to_i,
+        completed:,
+        started_at: session.started_at,
+        completed_at: completed ? Time.current : nil
+      )
+    end
+  end
+end

data/config/routes.rb

@@ -0,0 +1,2 @@
+Conduit::Engine.routes.draw do
+end

data/lib/conduit/configuration.rb

@@ -0,0 +1,25 @@
+# lib/conduit/configuration.rb
+module Conduit
+  class Configuration
+    attr_accessor :session_ttl, :redis_url, :max_navigation_depth,
+      :redis_pool_size, :logger, :save_sessions
+
+    def initialize
+      @session_ttl = 90.seconds
+      @redis_url = "redis://localhost:6379/1"
+      @max_navigation_depth = 10
+      @redis_pool_size = 10 # this number is experimental+configurable
+      @logger = Rails.logger
+      @save_sessions = true
+      @middleware = ::Conduit::Middleware::Chain.new
+    end
+
+    attr_reader :middleware
+
+    def redis_pool
+      @redis_pool ||= ConnectionPool.new(size: redis_pool_size, timeout: 0.1) do
+        Redis.new(url: redis_url, driver: :hiredis)
+      end
+    end
+  end
+end

data/lib/conduit/display_builder.rb

@@ -0,0 +1,58 @@
+module Conduit
+  class DisplayBuilder
+    attr_reader :parts
+
+    def initialize
+      @parts = []
+    end
+
+    def header(*lines)
+      @parts << lines.join("\n")
+      @parts << "" # Add blank line after header
+    end
+
+    def text(content)
+      @parts << content
+    end
+
+    def menu(&block)
+      menu_builder = MenuBuilder.new
+      menu_builder.instance_eval(&block)
+      @parts << menu_builder.to_s
+    end
+
+    def blank_line
+      @parts << ""
+    end
+
+    def to_s
+      @parts.join("\n")
+    end
+  end
+
+  class MenuBuilder
+    def initialize
+      @options = []
+    end
+
+    def option(number, text)
+      @options << "#{number}. #{text}"
+    end
+
+    def back_option(text = "Back")
+      @options << "0. #{text}"
+    end
+
+    def home_option(text = "Main Menu")
+      @options << "00. #{text}"
+    end
+
+    def exit_option(text = "Exit")
+      @options << "000. #{text}"
+    end
+
+    def to_s
+      @options.join("\n")
+    end
+  end
+end

data/lib/conduit/engine.rb

@@ -0,0 +1,21 @@
+require "redis"
+require "connection_pool"
+
+module Conduit
+  class Engine < ::Rails::Engine
+    isolate_namespace Conduit
+
+    config.generators do |generator|
+      generator.test_framework :rspec
+    end
+
+    config.autoload_paths << File.expand_path("../", __dir__)
+
+    initializer "conduit.setup" do
+      Conduit.configure do |config|
+        config.session_ttl ||= 90.seconds
+        config.redis_url ||= ENV.fetch("REDIS_URL", "redis://localhost:6379/1")
+      end
+    end
+  end
+end

data/lib/conduit/flow.rb

@@ -0,0 +1,54 @@
+module Conduit
+  class Flow
+    class InvalidTransition < StandardError; end
+
+    class << self
+      attr_reader :initial_state_name
+
+      def states
+        @states ||= {}
+      end
+
+      def initial_state(name)
+        @initial_state_name = name
+      end
+
+      def state(name, options = {}, &)
+        states[name.to_sym] = State.new(name, options, &)
+      end
+    end
+
+    def initialize
+      @states = self.class.states
+      @initial_state = self.class.initial_state_name
+    end
+
+    def process(session, input = nil)
+      # Initialize state if needed
+      if session.current_state.nil? || session.current_state == "initial"
+        session.current_state = @initial_state
+      end
+
+      # Get current state object
+      current_state = @states[session.current_state.to_sym]
+
+      unless current_state
+        raise InvalidTransition, "State '#{session.current_state}' not found"
+      end
+
+      # Process input if provided
+      if input.present?
+        result = current_state.handle_input(input, session, self)
+        return result if result.is_a?(Response)
+
+        # If state changed, render new state
+        if session.current_state != current_state.name
+          current_state = @states[session.current_state.to_sym]
+        end
+      end
+
+      # Render current state
+      current_state.render(session)
+    end
+  end
+end