conduit-ussd 0.1.0

data/lib/conduit/validator.rb

@@ -0,0 +1,55 @@
+module Conduit
+  class Validator
+    def self.numeric
+      lambda do |input, _session|
+        return true if input.match?(/^\d+(\.\d+)?$/)
+        "Please enter a valid number"
+      end
+    end
+
+    def self.greater_than(value)
+      lambda do |input, _session|
+        num = input.to_f
+        return true if num > value
+        "Must be greater than #{value}"
+      end
+    end
+
+    def self.less_than(value)
+      lambda do |input, _session|
+        num = input.to_f
+        return true if num < value
+        "Must be less than #{value}"
+      end
+    end
+
+    def self.min_length(length)
+      lambda do |input, _session|
+        return true if input.length >= length
+        "Must be at least #{length} characters"
+      end
+    end
+
+    def self.max_length(length)
+      lambda do |input, _session|
+        return true if input.length <= length
+        "Must be at most #{length} characters"
+      end
+    end
+
+    def self.matches(pattern, message = "Invalid format")
+      lambda do |input, _session|
+        return true if input.match?(pattern)
+        message
+      end
+    end
+
+    def self.in_range(min, max)
+      lambda do |input, _session|
+        num = input.to_f
+        return true if num.between?(min, max)
+        "Must be between #{min} and #{max}"
+      end
+    end
+  end
+end

data/lib/conduit/version.rb

@@ -0,0 +1,3 @@
+module Conduit
+  VERSION = "0.1.0"
+end

data/lib/conduit.rb

@@ -0,0 +1,31 @@
+require "conduit/version"
+require "conduit/engine"
+require "conduit/configuration"
+require "conduit/router"
+require "conduit/middleware"
+require "conduit/middleware/logging"
+require "conduit/middleware/throttling"
+require "conduit/middleware/session_tracking"
+require "conduit/display_builder"
+require "conduit/validator"
+
+module Conduit
+  class Error < StandardError; end
+
+  class SessionTimeout < Error; end
+
+  class InvalidTransition < Error; end
+
+  mattr_accessor :configuration
+
+  class << self
+    def configure
+      self.configuration ||= Configuration.new
+      yield(configuration) if block_given?
+    end
+
+    def process(params)
+      RequestHandler.new.process(params)
+    end
+  end
+end

data/lib/generators/conduit/install/install_generator.rb

@@ -0,0 +1,41 @@
+require "rails/generators"
+
+module Conduit
+  module Generators
+    class InstallGenerator < Rails::Generators::Base
+      source_root File.expand_path("templates", __dir__)
+
+      def create_initializer
+        template "conduit.rb", "config/initializers/conduit.rb"
+      end
+
+      def create_controller
+        template "ussd_controller.rb", "app/controllers/ussd_controller.rb"
+      end
+
+      def add_routes
+        route 'post "/ussd", to: "ussd#handle"'
+      end
+
+      def create_flow_directory
+        empty_directory "app/flows"
+        template "example_flow.rb", "app/flows/example_flow.rb"
+      end
+
+      def display_post_install
+        say "\n✅ Conduit installed successfully!", :green
+        say "\nNext steps:"
+        say "  1. Configure Redis in config/initializers/conduit.rb"
+        say "  2. Run 'rails generate conduit:migration' to create database table"
+        say "  3. Run 'rails db:migrate'"
+        say "  4. Create your flows in app/flows/"
+        say "  5. Map service codes to flows in the initializer"
+        say "  6. Test your USSD endpoint: POST /ussd"
+        say "\nExample AfricasTalking request:"
+        say "  curl -X POST http://localhost:3000/ussd \\"
+        say '    -H "Content-Type: application/x-www-form-urlencoded" \\'
+        say '    -d "sessionId=test123&phoneNumber=254712345678&serviceCode=*123%23&text="'
+      end
+    end
+  end
+end

data/lib/generators/conduit/install/templates/conduit.rb

@@ -0,0 +1,26 @@
+Conduit.configure do |config|
+  # Redis configuration
+  config.redis_url = ENV.fetch("REDIS_URL", "redis://localhost:6379/1")
+  config.session_ttl = 90.seconds
+
+  # Logging
+  config.logger = Rails.logger
+
+  # Session settings
+  config.max_navigation_depth = 10
+  config.save_sessions = true
+
+  # Middleware (order matters - first added is outermost)
+  config.middleware.use Conduit::Middleware::Logging
+  config.middleware.use Conduit::Middleware::Throttling, max_requests: 20, window: 60
+  config.middleware.use Conduit::Middleware::SessionTracking
+
+  # Add custom middleware
+  # config.middleware.use MyCustomMiddleware
+end
+
+# Route service codes to flows
+Conduit::Router.draw do
+  route "*123#", to: ExampleFlow
+  # route "*456#", to: AnotherFlow
+end

data/lib/generators/conduit/install/templates/example_flow.rb

@@ -0,0 +1,72 @@
+class ExampleFlow < Conduit::Flow
+  initial_state :welcome
+
+  state :welcome do
+    display <<~TEXT
+      Welcome to Conduit USSD Demo!
+
+      1. Get Started
+      2. About
+      3. Exit
+    TEXT
+
+    on "1", to: :get_name
+    on "2", to: :about
+    on "3" do
+      Conduit::Response.new(text: "Thank you for using Conduit! Goodbye.", action: :end)
+    end
+  end
+
+  state :get_name do
+    display "What's your name?"
+
+    on_any do |input, session|
+      session.data[:name] = input
+      session.navigate_to(:greet)
+    end
+  end
+
+  state :greet do
+    display do |session|
+      <<~TEXT
+        Hello #{session.data[:name]}!
+
+        You have successfully set up Conduit.
+
+        1. Try something else
+        0. Back
+        00. Home
+      TEXT
+    end
+
+    on "1", to: :demo_feature
+  end
+
+  state :about do
+    display <<~TEXT
+      Conduit v#{Conduit::VERSION}
+
+      Lightning-fast USSD framework for Rails
+      Built with ❤️ for Africa
+
+      0. Back
+      00. Home
+    TEXT
+  end
+
+  state :demo_feature do
+    display do |session|
+      <<~TEXT
+        #{session.data[:name]}, this is where you'd add your features!
+
+        Current session info:
+        - ID: #{session.session_id}
+        - Phone: #{session.msisdn}
+        - Duration: #{session.duration.to_i}s
+
+        0. Back
+        00. Home
+      TEXT
+    end
+  end
+end

data/lib/generators/conduit/install/templates/ussd_controller.rb

@@ -0,0 +1,11 @@
+class UssdController < ApplicationController
+  skip_before_action :verify_authenticity_token
+
+  def handle
+    # Process AfricasTalking USSD request
+    response = Conduit.process(params)
+
+    # Return plain text response for AfricasTalking
+    render plain: response, content_type: "text/plain"
+  end
+end

data/lib/generators/conduit/migration/migration_generator.rb

@@ -0,0 +1,21 @@
+require "rails/generators"
+require "rails/generators/active_record"
+
+module Conduit
+  module Generators
+    class MigrationGenerator < Rails::Generators::Base
+      include ActiveRecord::Generators::Migration
+
+      source_root File.expand_path("templates", __dir__)
+
+      def create_migration_file
+        migration_template "create_conduit_sessions.rb", "db/migrate/create_conduit_sessions.rb"
+      end
+
+      def display_post_install
+        say "\n✅ Migration created!", :green
+        say "\nRun 'rails db:migrate' to create the conduit_sessions table"
+      end
+    end
+  end
+end

data/lib/generators/conduit/migration/templates/create_conduit_sessions.rb

@@ -0,0 +1,19 @@
+class CreateConduitSessions < ActiveRecord::Migration[8.0] # this needs fixing to make it dynamic?
+  def change
+    create_table :conduit_sessions do |t|
+      t.string :session_id, null: false, index: {unique: true}
+      t.string :msisdn, null: false, index: true
+      t.string :service_code
+      t.string :final_state
+      t.jsonb :data, default: {}
+      t.integer :duration_seconds
+      t.boolean :completed, default: false
+      t.datetime :started_at, null: false
+      t.datetime :completed_at
+      t.timestamps null: false
+
+      t.index [:msisdn, :created_at]
+      t.index :created_at
+    end
+  end
+end

data/lib/tasks/conduit_tasks.rake

@@ -0,0 +1,4 @@
+# desc "Explaining what the task does"
+# task :conduit do
+#   # Task goes here
+# end

metadata

@@ -0,0 +1,191 @@
+--- !ruby/object:Gem::Specification
+name: conduit-ussd
+version: !ruby/object:Gem::Version
+  version: 0.1.0
+platform: ruby
+authors:
+- Charles Chuck
+bindir: bin
+cert_chain: []
+date: 1980-01-02 00:00:00.000000000 Z
+dependencies:
+- !ruby/object:Gem::Dependency
+  name: rails
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: 8.0.2
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: 8.0.2
+- !ruby/object:Gem::Dependency
+  name: redis
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '5.0'
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '5.0'
+- !ruby/object:Gem::Dependency
+  name: connection_pool
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '2.4'
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '2.4'
+- !ruby/object:Gem::Dependency
+  name: standard
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '0'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '0'
+- !ruby/object:Gem::Dependency
+  name: rubocop-rails-omakase
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '0'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '0'
+- !ruby/object:Gem::Dependency
+  name: rspec-rails
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '8.0'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '8.0'
+- !ruby/object:Gem::Dependency
+  name: fakeredis
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '0'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '0'
+- !ruby/object:Gem::Dependency
+  name: pry-rails
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '0'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '0'
+description: Build USSD applications with an expressive DSL. Redis-backed sessions,
+  AfricasTalking integration, built for the 60-120 second constraint.
+email:
+- chalcchuck@email.com
+executables: []
+extensions: []
+extra_rdoc_files: []
+files:
+- MIT-LICENSE
+- README.md
+- Rakefile
+- app/assets/stylesheets/conduit/application.css
+- app/controllers/conduit/application_controller.rb
+- app/helpers/conduit/application_helper.rb
+- app/jobs/conduit/application_job.rb
+- app/jobs/conduit/save_session_job.rb
+- app/models/conduit/application_record.rb
+- app/models/conduit/session_record.rb
+- config/routes.rb
+- lib/conduit.rb
+- lib/conduit/configuration.rb
+- lib/conduit/display_builder.rb
+- lib/conduit/engine.rb
+- lib/conduit/flow.rb
+- lib/conduit/middleware.rb
+- lib/conduit/middleware/logging.rb
+- lib/conduit/middleware/session_tracking.rb
+- lib/conduit/middleware/throttling.rb
+- lib/conduit/providers/africas_talking.rb
+- lib/conduit/request_handler.rb
+- lib/conduit/response.rb
+- lib/conduit/router.rb
+- lib/conduit/session.rb
+- lib/conduit/session_store.rb
+- lib/conduit/state.rb
+- lib/conduit/validator.rb
+- lib/conduit/version.rb
+- lib/generators/conduit/install/install_generator.rb
+- lib/generators/conduit/install/templates/conduit.rb
+- lib/generators/conduit/install/templates/example_flow.rb
+- lib/generators/conduit/install/templates/ussd_controller.rb
+- lib/generators/conduit/migration/migration_generator.rb
+- lib/generators/conduit/migration/templates/create_conduit_sessions.rb
+- lib/tasks/conduit_tasks.rake
+homepage: https://github.com/chalchuck/conduit
+licenses:
+- MIT
+metadata:
+  homepage_uri: https://github.com/chalchuck/conduit
+  source_code_uri: https://github.com/chalchuck/conduit
+rdoc_options: []
+require_paths:
+- lib
+required_ruby_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: 3.4.1
+required_rubygems_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: '0'
+requirements: []
+rubygems_version: 3.6.9
+specification_version: 4
+summary: Lightning-fast USSD flow engine for Rails
+test_files: []